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