# API of `@koobiq/components/autocomplete`

Documented on [Autocomplete](https://koobiq.io/en/components/autocomplete.md). NgModule: `KbqAutocompleteModule`.

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