# API of `@koobiq/components/app-switcher`

Documented on [App Switcher](https://koobiq.io/en/components/app-switcher.md). NgModule: `KbqAppSwitcherModule`.

## 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;
```
