# API of `@koobiq/components/accordion`

Documented on [Accordion](https://koobiq.io/en/components/accordion.md). NgModule: `KbqAccordionModule`.

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