# API of `@koobiq/components/top-bar`

Documented on [Topbar](https://koobiq.io/en/components/top-bar.md). NgModule: `KbqTopBarModule`.

## 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 {}
```
