# @mk-kit/ui 0.60.2 — full API reference

Generated from the library sources. Browsable version: https://mk-kit.dev/api · JSON: https://mk-kit.dev/api.json · Guides: https://mk-kit.dev/llms.txt

## Usage

```bash
ng add @mk-kit/ui
```

Every component and directive below is standalone — import the class from its entry point and list it in `imports`. Attribute selectors like `button[mkButton]` enhance native elements; element selectors render their own template. Inputs marked two-way are `model()` signals and accept `[(name)]`. Inputs are signal inputs: read them as `comp.name()` in TypeScript.

## @mk-kit/ui/core

87 exports. `import { … } from '@mk-kit/ui/core';`

### MkAnchoredPanel (directive)

Selector: `[mkAnchoredPanel]` · exportAs: `mkAnchoredPanel`

Docs: https://mk-kit.dev/core-services

Import: `import { MkAnchoredPanel } from '@mk-kit/ui/core';`

Anchored-overlay directive. Apply it to a floating panel element (a dropdown
list, calendar, menu, …) that is rendered inside its component's own template
— typically inside an `@if (open()) { … }` block. On init the directive
**teleports the panel to `document.body` and into the browser top layer** via
the native Popover API (`popover="manual"` + `showPopover()`), then positions
it against the anchor with `position: fixed`. Because the element stays part
of the component's Angular view, all bindings, `@for` content, events and
projected content keep working after the move.

The top layer is immune to ancestor `overflow`, `transform` and `z-index`
stacking contexts, so the panel can never be clipped by a container or hidden
behind sibling content. Where the Popover API is unavailable the panel still
renders in a `document.body` portal with a `z-index` fallback.

```html
<ul #panel mkAnchoredPanel [mkAnchoredPanelFor]="trigger" [matchWidth]="true"
    (dismiss)="close()"> … </ul>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkAnchoredPanelFor` | `HTMLElement \| ElementRef<HTMLElement> \| undefined` | `undefined` | The trigger element to position against. |
| `anchorRect` | `{ x: number; y: number; } \| undefined` | `undefined` | Viewport-point anchor (e.g. a right-click position) — takes precedence. |
| `placement` | `MkPlacement` | `'bottom-start'` | Preferred placement relative to the anchor. |
| `gap` | `number` | `4` | Distance in px between the anchor and the panel. |
| `matchWidth` | `boolean` | `false` | Set the panel's `min-width` to the anchor's width (dropdowns). |
| `flip` | `boolean` | `true` | Flip to the opposite side when the preferred side would overflow. |
| `clamp` | `boolean` | `true` | Clamp the panel inside the viewport. |
| `keepOpenWhen` | `((target: Node) => boolean) \| null` | `null` | Predicate consulted before an outside pointerdown dismisses the panel. Return `true` for targets that must keep it open — e.g. a nested panel (a submenu) that lives in the top layer outside this element. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `dismiss` | `void` | Emitted on an outside pointerdown or when the window loses focus. |

Methods:

| Signature | Description |
| --- | --- |
| `position(track?: boolean): void` | Recompute and apply the panel position. Safe to call at any time. With `track` (scroll-driven), the panel follows the anchor unclamped and dismisses once the anchor leaves the viewport (matching the CDK's reposition-with-auto-close scroll behaviour). |

### MkAccentService (service)

Import: `import { MkAccentService } from '@mk-kit/ui/core';`

Runtime accent — the user picks one of `MK_ACCENTS` and every kit
control recolours: the service writes the `--mk-primary` family
(`primary`, `-hover`, `-active`, `-subtle`, `-subtle-hover`,
`-subtle-text`), `--mk-focus-ring`, `--mk-selected-bg` / `-text` and three
accent tokens of its own — `--mk-accent`, `--mk-accent-ink`,
`--mk-accent-glow` — onto `<html>`, and mirrors the key as
`data-mk-accent`. Hover / active are a touch darker in light and a touch
lighter in dark (it follows `MkThemeService`). The choice persists
in `localStorage` (`mk-kit-accent`); nothing is written until `set()` is
called, so an app that never picks keeps the preset's own primary.

```ts
readonly accent = inject(MkAccentService);
accent.set('coral');           // every button, ring and chip turns coral
accent.key();                  // 'coral'
mkAccentSwatch(accent.key());  // for the picker
```

Methods:

| Signature | Description |
| --- | --- |
| `set(key: MkAccentKey): void` | Pick an accent; persisted. |
| `reset(): void` | Back to the preset's own primary; the stored choice is cleared. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `Signal<MkAccentKey \| null>` | The chosen accent, or `null` while the preset's own primary is in use. |
| `accent` | `Signal<MkAccent>` | The chosen accent's definition (indigo when none is chosen). |

### MkBreakpointService (service)

Docs: https://mk-kit.dev/core-services

Import: `import { MkBreakpointService } from '@mk-kit/ui/core';`

Reactive viewport breakpoints, one `matchMedia` listener per step.

```ts
private readonly bp = inject(MkBreakpointService);
readonly compact = this.bp.down('md');          // Signal<boolean>
readonly columns = computed(() => this.bp.resolve({ xs: 1, md: 2, xl: 4 }));
```

On the server (no `window`) everything reports `xs`.

Methods:

| Signature | Description |
| --- | --- |
| `up(bp: MkBreakpoint): Signal<boolean>` | True while the viewport is at least `bp` wide (`up('md')` = md, lg, xl, 2xl). |
| `down(bp: MkBreakpoint): Signal<boolean>` | True while the viewport is narrower than `bp` (`down('md')` = xs, sm). |
| `between(from: MkBreakpoint, to: MkBreakpoint): Signal<boolean>` | True while the viewport is at least `from` and narrower than `to`. |
| `observe(query: string): Signal<boolean>` | Any media query as a signal, e.g. `observe('(orientation: portrait)')`. |
| `resolve<T>(value: MkResponsive<T>): T \| undefined` | Pick the entry of a responsive value for the current viewport — mobile-first, so `{ xs: 1, md: 2 }` gives 1 on `sm` and 2 on `xl`. A plain value is returned as is. Read inside a `computed` to track it. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `breakpoints` | `MkBreakpoints` | The breakpoint scale in effect (see `MK_BREAKPOINTS`). |
| `current` | `Signal<MkBreakpoint>` | The widest breakpoint the viewport currently satisfies. |

### MkLiveAnnouncer (service)

Docs: https://mk-kit.dev/core-services

Import: `import { MkLiveAnnouncer } from '@mk-kit/ui/core';`

Announces messages to assistive technology via a visually-hidden
`aria-live` region. Used by toasts, form validation, sort changes, etc.
so state changes are perceivable without sight. WCAG 4.1.3 (Status Messages).

Methods:

| Signature | Description |
| --- | --- |
| `announce(message: string, politeness?: MkAriaLivePoliteness): void` | Announce `message`. `politeness` controls interruption behavior. |

### MkOverlayService (service)

Docs: https://mk-kit.dev/core-services

Import: `import { MkOverlayService } from '@mk-kit/ui/core';`

Lightweight, dependency-free overlay renderer. Instantiates a standalone
component into a body-level host, manages the backdrop, focus trapping,
Escape handling, and scroll locking. Powers Dialog, Menu, and others.

Methods:

| Signature | Description |
| --- | --- |
| `closeAll(): void` | Close every open overlay, newest first. Each is closed with no result, so `afterClosed` resolves undefined exactly as a backdrop click or Escape would. Safe to call when nothing is open. |
| `open<TComponent, TResult = unknown, TData = unknown>(component: Type<TComponent>, config?: MkOverlayConfig<TData>): MkOverlayRef<TResult, TComponent>` |  |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `openCount` | `number` | How many overlays are currently open. |

### MkThemeService (service)

Docs: https://mk-kit.dev/core-services

Import: `import { MkThemeService } from '@mk-kit/ui/core';`

Reactive theme controller for mk-kit.

- `preference()` is the user's choice: `light`, `dark`, or `system`.
- `resolvedTheme()` is the concrete theme currently applied.
- Writes `data-mk-theme` on `<html>` and persists the choice to
  `localStorage`. When set to `system`, it live-tracks the OS setting and
  removes the attribute so pure-CSS `prefers-color-scheme` takes over.

Provided in root — inject it anywhere and bind to the signals.

Methods:

| Signature | Description |
| --- | --- |
| `setDensity(density: MkDensity): void` | Set the global density mode. |
| `toggleDensity(): void` | Toggle between comfortable and compact — the two modes a density switch in a UI offers. `touch` is a deliberate choice for a specific screen, not something to land on by toggling, so from `touch` this returns to comfortable rather than cycling. |
| `setContrast(contrast: MkContrastPreference): void` | Set the contrast preference explicitly. |
| `toggleContrast(): void` | Toggle between normal and high contrast (resolving `system` first). |
| `setTheme(preference: MkThemePreference): void` | Set the theme preference explicitly. |
| `toggle(): void` | Toggle between light and dark (resolving `system` first). |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `preference` | `Signal<MkThemePreference>` | The user's theme preference. |
| `resolvedTheme` | `Signal<MkResolvedTheme>` | The concrete theme in effect (`light` or `dark`). |
| `isDark` | `Signal<boolean>` | Convenience boolean for template bindings. |
| `density` | `Signal<MkDensity>` | The global density mode. `compact` tightens control heights and the core spacing steps via the `data-mk-density` attribute, `touch` enlarges them — every component follows automatically because they read the same tokens.  This signal is the GLOBAL mode only. To make one screen or dialog touch- sized inside an otherwise comfortable app, put `data-mk-density="touch"` on that element instead; the tokens inherit and this service stays out of it. |
| `contrast` | `Signal<MkContrastPreference>` | The user's contrast preference: `normal`, `high` or `system` (follow the OS `prefers-contrast` setting — the default). Written as `data-mk-contrast` on `<html>` and persisted; `system` removes the attribute so the pure-CSS `prefers-contrast: more` mapping takes over.  Like density, the attribute also works per subtree: put `data-mk-contrast="high"` on any element to raise contrast there only. |
| `resolvedContrast` | `Signal<MkResolvedContrast>` | The concrete contrast in effect (`normal` or `high`). |
| `isHighContrast` | `Signal<boolean>` | Convenience boolean for template bindings. |

### MkFieldContext (class)

Import: `import { MkFieldContext } from '@mk-kit/ui/core';`

Field context — the contract a field wrapper (`mk-form-field`) exposes to
the control nested inside it. Controls inject it optionally
(`inject(MkFieldContext, { optional: true })`) to adopt the wrapper's
control id and to reflect its required/error state and `aria-describedby`
wiring — without depending on the `@mk-kit/ui/forms` entry point.

`MkFormField` provides itself under this token; standalone usage (no
wrapper) simply yields `null`.

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `controlId` | `string` | Id for the nested interactive control — adopt on your control element. |
| `labelId` | `string` | Id of the field's label element, for `aria-labelledby`. |
| `size` | `Signal<MkSize>` | The field's visual size, mirrored onto the nested control. |
| `isRequired` | `Signal<boolean>` | Whether the field is required (explicitly or via the bound control). |
| `hasError` | `Signal<boolean>` | Whether the field currently shows an error. |
| `describedBy` | `Signal<string \| null>` | Space-separated id list for the nested control's `aria-describedby`, or `null` when there is nothing to describe. |

### MkFocusTrap (class)

Docs: https://mk-kit.dev/core-services

Import: `import { MkFocusTrap } from '@mk-kit/ui/core';`

Traps keyboard focus within `root` (wrapping Tab / Shift+Tab), moves focus
inside on activation, and restores focus to the previously-focused element
on release. Essential for accessible modals/menus (WCAG 2.4.3, 2.1.2).

Methods:

| Signature | Description |
| --- | --- |
| `activate(initialFocus?: HTMLElement): void` | Activate the trap and move focus to the first focusable element (or root). |
| `release(): void` | Deactivate and restore focus to the trigger element. |

### MkOverlayRef (class)

Import: `import { MkOverlayRef } from '@mk-kit/ui/core';`

Handle to an open overlay. Injected into the rendered component and returned
from `MkOverlayService.open`. Resolve the overlay by calling `close`.

The close result is exposed three ways so the handle fits whatever style the
calling code already uses — they all settle together:

- `result` — a signal, for template binding and signal-based components.
- `closed$` — an Observable that emits once and completes, for RxJS
  pipelines. A service that hands a dialog result back to its callers can
  return this directly instead of wrapping the promise in `from(...)`.
- `afterClosed` — a Promise, for `await` / `.then()`.

Methods:

| Signature | Description |
| --- | --- |
| `close(result?: TResult): void` | Close the overlay, optionally returning a result. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `componentRef` | `ComponentRef<TComponent> \| undefined` | The rendered component instance (set by the service after creation). |
| `closed` | `Signal<boolean>` | Becomes `true` once the overlay has been dismissed. |
| `result` | `Signal<TResult \| undefined>` | The value passed to `close`, or `undefined` while open and for a dismissal (Escape / backdrop). Read `closed()` to tell "closed with no result" apart from "still open". |
| `afterClosed` | `Promise<TResult \| undefined>` | Resolves with the close result when the overlay is dismissed. |
| `closed$` | `Observable<TResult \| undefined>` | Emits the close result once, then completes. Subscribing after the overlay has already closed replays the result immediately, so a late subscriber never hangs. |

### mkAccentSwatch (function)

Import: `import { mkAccentSwatch } from '@mk-kit/ui/core';`

The swatch a picker shows for an accent (bumblebee is the black / yellow split).

```ts
function mkAccentSwatch(key: MkAccentKey): string
```

### mkBodyLevelAncestor (function)

Import: `import { mkBodyLevelAncestor } from '@mk-kit/ui/core';`

The direct child of `document.body` an overlay-root descendant lives under,
crossing shadow boundaries on the way up — `null` when the node is not under
`body` at all. The overlay service uses it to keep the overlay's own host
out of the elements it makes `inert` behind a modal.

```ts
function mkBodyLevelAncestor(node: Node, body: HTMLElement): Element | null
```

### mkComputeAnchoredPosition (function)

Import: `import { mkComputeAnchoredPosition } from '@mk-kit/ui/core';`

Pure viewport-positioning maths shared by every anchored overlay
(`MkAnchoredPanel` and the tooltip). Given the anchor rect, the panel
size and the viewport size, returns the top/left for a `position: fixed`
panel — flipping to the opposite side when it would overflow and clamping
back inside the viewport.

```ts
function mkComputeAnchoredPosition(anchor: MkRectLike, panel: MkDimensions, viewport: MkDimensions, opts: MkAnchoredPositionOptions): MkAnchoredPosition
```

### mkCreateQueryGroup (function)

Import: `import { mkCreateQueryGroup } from '@mk-kit/ui/core';`

A fresh empty group.

```ts
function mkCreateQueryGroup(init?: Partial<Omit<MkQueryGroup, "id">>): MkQueryGroup
```

### mkCreateQueryRule (function)

Import: `import { mkCreateQueryRule } from '@mk-kit/ui/core';`

A fresh rule on `field`, using its first operator.

```ts
function mkCreateQueryRule(field: MkQueryField): MkQueryRule
```

### mkFirstErrorMessage (function)

Import: `import { mkFirstErrorMessage } from '@mk-kit/ui/core';`

Resolves the message for the first error on a control, mirroring how
`mat-error` shows one message at a time.

Lookup order per key: the field's `overrides`, then the i18n `validation`
table, then the error payload's own `message` string (so a custom validator
can carry its text), then the generic fallback. Keys are visited in the
order the validators put them on the control, so composing
`[Validators.required, Validators.email]` surfaces "required" while empty.

```ts
function mkFirstErrorMessage(errors: ValidationErrors | null | undefined, strings: MkValidationStrings, overrides?: MkErrorMessages): string | null
```

### mkGetFocusable (function)

Import: `import { mkGetFocusable } from '@mk-kit/ui/core';`

Returns the tabbable elements inside `root`, in DOM order.

```ts
function mkGetFocusable(root: HTMLElement): HTMLElement[]
```

### mkHexAlpha (function)

Import: `import { mkHexAlpha } from '@mk-kit/ui/core';`

`#rrggbb` → `rgba(r,g,b,a)`.

```ts
function mkHexAlpha(hex: string, alpha: number): string
```

### mkHighlight (function)

Import: `import { mkHighlight } from '@mk-kit/ui/core';`

Highlight `src` for `language`, falling back to escaped plain text.

```ts
function mkHighlight(src: string, language: string): string
```

### mkHighlightJson (function)

Import: `import { mkHighlightJson } from '@mk-kit/ui/core';`

Highlight a JSON document. Recognises object keys, strings, numbers, the
`true`/`false`/`null` literals and structural punctuation. Invalid JSON is
still highlighted token-by-token (the editor validates separately).

```ts
function mkHighlightJson(src: string): string
```

### mkIsQueryGroup (function)

Import: `import { mkIsQueryGroup } from '@mk-kit/ui/core';`

True for a group node (as opposed to a rule).

```ts
function mkIsQueryGroup(node: MkQueryNode): node is MkQueryGroup
```

### mkIsResponsive (function)

Import: `import { mkIsResponsive } from '@mk-kit/ui/core';`

True when `value` is a per-breakpoint map rather than a plain value.

```ts
function mkIsResponsive<T>(value: MkResponsive<T>): value is Partial<Record<MkBreakpoint, T>>
```

### mkMergeI18n (function)

Import: `import { mkMergeI18n } from '@mk-kit/ui/core';`

Merges `overrides` over a complete string map — shallow for the top level,
deep for the `dateNames`, `blockEditor` and `validation` groups. Exported
so locale packs and tests can build a map without providing it.

```ts
function mkMergeI18n(base: MkI18nStrings, overrides: MkI18nOverrides): MkI18nStrings
```

### mkQueryCompact (function)

Import: `import { mkQueryCompact } from '@mk-kit/ui/core';`

Drop empty groups and rules that still need a value, so the API gets only complete conditions.

```ts
function mkQueryCompact(group: MkQueryGroup): MkQueryGroup
```

### mkQueryIsEmpty (function)

Import: `import { mkQueryIsEmpty } from '@mk-kit/ui/core';`

True when the tree holds no rule at all (empty groups only).

```ts
function mkQueryIsEmpty(group: MkQueryGroup): boolean
```

### mkQueryOperatorLabel (function)

Import: `import { mkQueryOperatorLabel } from '@mk-kit/ui/core';`

Localised label of an operator.

```ts
function mkQueryOperatorLabel(op: MkQueryOperator, i18n?: MkQueryTextStrings): string
```

### mkQueryOperatorsFor (function)

Import: `import { mkQueryOperatorsFor } from '@mk-kit/ui/core';`

Operators a field offers (its own list, else the defaults for its type).

```ts
function mkQueryOperatorsFor(field: MkQueryField | undefined): readonly MkQueryOperator[]
```

### mkQueryRuleCount (function)

Import: `import { mkQueryRuleCount } from '@mk-kit/ui/core';`

Number of rules in the tree.

```ts
function mkQueryRuleCount(group: MkQueryGroup): number
```

### mkQueryRuleIsComplete (function)

Import: `import { mkQueryRuleIsComplete } from '@mk-kit/ui/core';`

A rule is complete when its operator needs no value or has one.

```ts
function mkQueryRuleIsComplete(rule: MkQueryRule): boolean
```

### mkQueryRuleMatches (function)

Import: `import { mkQueryRuleMatches } from '@mk-kit/ui/core';`

Evaluate one rule against a row.

```ts
function mkQueryRuleMatches(rule: MkQueryRule, row: Record<string, unknown>, field?: MkQueryField): boolean
```

### mkQueryToPredicate (function)

Import: `import { mkQueryToPredicate } from '@mk-kit/ui/core';`

Compile a query into a row predicate for client-side filtering
(`rows.filter(mkQueryToPredicate(query, fields))`). Unfinished rules are
ignored, so a half-edited query never blanks the table.

```ts
function mkQueryToPredicate<T extends object = Record<string, unknown>>(group: MkQueryGroup, fields?: readonly MkQueryField[]): (row: T) => boolean
```

### mkQueryToText (function)

Import: `import { mkQueryToText } from '@mk-kit/ui/core';`

Human-readable sentence for a query, e.g.
`(Name contains "ada" and Orders at least 10) or Status is any of Active, Invited`.

```ts
function mkQueryToText(group: MkQueryGroup, fields?: readonly MkQueryField[], i18n?: MkQueryTextStrings): string
```

### mkSignalErrorMessage (function)

Import: `import { mkSignalErrorMessage } from '@mk-kit/ui/core';`

Resolves the message for the first Signal Forms error on a field, the way
`mkFirstErrorMessage` does for reactive forms.

Lookup order: the field's `overrides` for that kind, then the `message` the
schema attached to the error (`required(p.email, { message: '…' })`), then
the i18n `validation` table, then the generic fallback.

```ts
function mkSignalErrorMessage(errors: readonly MkSignalValidationError[] | null | undefined, strings: MkValidationStrings, overrides?: MkErrorMessages): string | null
```

### mkSignalErrorsToValidationErrors (function)

Import: `import { mkSignalErrorsToValidationErrors } from '@mk-kit/ui/core';`

Converts Signal Forms errors to the reactive-forms `ValidationErrors` shape
the `validation` i18n table is keyed by, so both form systems render the
same messages. The built-in kinds map to Angular's classic keys and payloads
(`minLength` → `minlength: { requiredLength }`, `minDate` → `mkMinDate`,
…); any other kind is kept as-is with its payload spread into the value.

```ts
function mkSignalErrorsToValidationErrors(errors: readonly MkSignalValidationError[] | null | undefined): ValidationErrors | null
```

### mkUniqueId (function)

Import: `import { mkUniqueId } from '@mk-kit/ui/core';`

Generates a stable, unique DOM id for wiring `aria-*` relationships
(labels, descriptions, controls). Prefer this over `Math.random()` so
ids are deterministic within a render and SSR-safe.

```ts
function mkUniqueId(prefix?: string): string
```

### mkValidatorChange (function)

Import: `import { mkValidatorChange } from '@mk-kit/ui/core';`

Re-validates the bound form control whenever a validator's inputs change.

A `Validator` whose constraints come from component inputs (`[min]`,
`[max]`, `[required]`, …) must tell Angular when those inputs change,
otherwise the control keeps the verdict computed under the old constraints.
`NgModel`/`FormControlName` pass a callback to `registerOnValidatorChange`
for exactly this; call it from an effect over the constraint signals.

Must be called from an injection context (i.e. as a field initialiser).

```ts
private readonly validatorChange = mkValidatorChange(() => {
  this.min();
  this.max();
});

registerOnValidatorChange(fn: () => void): void {
  this.validatorChange.register(fn);
}
```

```ts
function mkValidatorChange(deps: () => void): MkValidatorChangeRef
```

### provideMkI18n (function)

Docs: https://mk-kit.dev/core-services

Import: `import { provideMkI18n } from '@mk-kit/ui/core';`

Provide localised strings — pass any subset, merged over `base` (the
English defaults unless given). The nested `dateNames`, `blockEditor` and
`validation` groups are merged deeply, so partial overrides of those work
too.

```ts
bootstrapApplication(App, {
  providers: [provideMkI18n({ noResults: 'Brak wyników', close: 'Zamknij' })],
});
```

A locale pack is a complete map that serves as the base — either through
its own helper (`provideMkI18nPl(overrides)` from `@mk-kit/ui/locales/pl`)
or explicitly: `provideMkI18n(overrides, MK_PL_I18N)`.

```ts
function provideMkI18n(overrides: MkI18nOverrides, base?: MkI18nStrings): Provider
```

### MK_BREAKPOINTS (token)

Import: `import { MK_BREAKPOINTS } from '@mk-kit/ui/core';`

Override the breakpoint scale app-wide: `{ provide: MK_BREAKPOINTS, useValue: { …, lg: 1100 } }`.

```ts
const MK_BREAKPOINTS: InjectionToken<MkBreakpoints>;
```

### MK_I18N (token)

Import: `import { MK_I18N } from '@mk-kit/ui/core';`

The active string map. Defaults to `MK_DEFAULT_I18N`; override with
`provideMkI18n`. Inject it (`inject(MK_I18N)`) wherever a built-in
string is rendered.

```ts
const MK_I18N: InjectionToken<MkI18nStrings>;
```

### MK_OVERLAY_DATA (token)

Import: `import { MK_OVERLAY_DATA } from '@mk-kit/ui/core';`

Injection token exposing the data passed to an overlay component.

```ts
const MK_OVERLAY_DATA: InjectionToken<unknown>;
```

### MK_OVERLAY_ROOT (token)

Import: `import { MK_OVERLAY_ROOT } from '@mk-kit/ui/core';`

Where mk-kit mounts everything that leaves the component tree: overlay
containers (dialogs), anchored panels (selects, menus, tooltips), toast /
snackbar containers and the tour surfaces. Defaults to `document.body`.

Override it to confine those surfaces to another element — `@mk-kit/ui/embed`
points it at a themed shadow-DOM host so overlays opened by embedded custom
elements stay isolated from the host page's stylesheet:

```ts
{ provide: MK_OVERLAY_ROOT, useValue: () => myOverlayHost }
```

```ts
const MK_OVERLAY_ROOT: InjectionToken<MkOverlayRootFn>;
```

### MK_ACCENT_ORDER (const)

Import: `import { MK_ACCENT_ORDER } from '@mk-kit/ui/core';`

Picker order.

```ts
const MK_ACCENT_ORDER: readonly MkAccentKey[];
```

### MK_ACCENTS (const)

Import: `import { MK_ACCENTS } from '@mk-kit/ui/core';`

High-saturation, distinct, energising accents — the set the `momentum` preset was designed around.

```ts
const MK_ACCENTS: Record<MkAccentKey, MkAccent>;
```

### MK_DEFAULT_BREAKPOINTS (const)

Import: `import { MK_DEFAULT_BREAKPOINTS } from '@mk-kit/ui/core';`

The default scale (same numbers as Tailwind, so mental models transfer).

```ts
const MK_DEFAULT_BREAKPOINTS: MkBreakpoints;
```

### MK_DEFAULT_DATE_NAMES (const)

Import: `import { MK_DEFAULT_DATE_NAMES } from '@mk-kit/ui/core';`

The built-in English date names.

```ts
const MK_DEFAULT_DATE_NAMES: MkDateNames;
```

### MK_DEFAULT_I18N (const)

Import: `import { MK_DEFAULT_I18N } from '@mk-kit/ui/core';`

The built-in English strings.

```ts
const MK_DEFAULT_I18N: MkI18nStrings;
```

### MK_DEFAULT_VALIDATION (const)

Import: `import { MK_DEFAULT_VALIDATION } from '@mk-kit/ui/core';`

The built-in English validation messages.

```ts
const MK_DEFAULT_VALIDATION: MkValidationStrings;
```

### MK_QUERY_OPERATORS (const)

Import: `import { MK_QUERY_OPERATORS } from '@mk-kit/ui/core';`

Operators offered per field type, in menu order.

```ts
const MK_QUERY_OPERATORS: Readonly<Record<MkQueryValueType, readonly MkQueryOperator[]>>;
```

### MK_QUERY_TEXT_EN (const)

Import: `import { MK_QUERY_TEXT_EN } from '@mk-kit/ui/core';`

English defaults for `MkQueryTextStrings`.

```ts
const MK_QUERY_TEXT_EN: MkQueryTextStrings;
```

### MK_QUERY_UNARY (const)

Import: `import { MK_QUERY_UNARY } from '@mk-kit/ui/core';`

Operators that take no value.

```ts
const MK_QUERY_UNARY: ReadonlySet<MkQueryOperator>;
```

### MkAccent (interface)

Import: `import { MkAccent } from '@mk-kit/ui/core';`

`fill` = bars, rings and buttons · `ink` = small accent text on a light ground.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `fill` | `string` |  |
| `ink` | `string` |  |
| `name` | `string` |  |

### MkAnchoredPosition (interface)

Import: `import { MkAnchoredPosition } from '@mk-kit/ui/core';`

Resolved coordinates (viewport-relative, for `position: fixed`).

Members:

| Name | Type | Description |
| --- | --- | --- |
| `top` | `number` |  |
| `left` | `number` |  |
| `placement` | `MkPlacement` | The placement actually used after any flip. |

### MkAnchoredPositionOptions (interface)

Import: `import { MkAnchoredPositionOptions } from '@mk-kit/ui/core';`

Options controlling `mkComputeAnchoredPosition`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `placement` | `MkPlacement` |  |
| `gap` | `number` |  |
| `flip` | `boolean` |  |
| `clamp` | `boolean` |  |
| `rtl`? | `boolean \| undefined` | Resolve `-start`/`-end` alignment against a right-to-left anchor. |

### MkBlockEditorStrings (interface)

Import: `import { MkBlockEditorStrings } from '@mk-kit/ui/core';`

Strings used by the block editor's chrome.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `addBlock` | `string` |  |
| `addFirstBlock` | `string` |  |
| `insertBlockHere` | `string` |  |
| `blockInserter` | `string` |  |
| `searchBlocks` | `string` |  |
| `blocks` | `string` |  |
| `moveBlockUp` | `string` |  |
| `moveBlockDown` | `string` |  |
| `blockOptions` | `string` |  |
| `duplicate` | `string` |  |
| `remove` | `string` |  |
| `textFormatting` | `string` |  |
| `altText` | `string` |  |
| `caption` | `string` |  |
| `alignment` | `string` |  |
| `replaceImage` | `string` |  |
| `imageUrl` | `string` |  |
| `externalContent` | `string` |  |
| `embedUrl` | `string` |  |
| `columnSettings` | `string` |  |
| `columns` | `string` |  |
| `ratio` | `string` |  |
| `gap` | `string` |  |
| `align` | `string` |  |
| `justify` | `string` |  |
| `headingLevel` | `(level: number) => string` |  |
| `editorLabel` | `string` | Editor region label + empty-block placeholder defaults. |
| `emptyBlockPlaceholder` | `string` |  |
| `dragHandle` | `string` | Drag handle tooltip. |
| `turnInto` | `(label: string) => string` | "Turn into …" transform menu item; receives the target block's label. |
| `unknownBlock` | `(type: string) => string` | Shown for a block whose type has no registered definition. |
| `blockAdded` | `(label: string) => string` | Structural-change screen-reader announcements. |
| `blockDuplicated` | `string` |  |
| `blockDeleted` | `(label: string) => string` |  |
| `blockMovedUp` | `string` |  |
| `blockMovedDown` | `string` |  |
| `turnedInto` | `(label: string) => string` |  |
| `noBlocksMatch` | `(query: string) => string` | Inserter empty state; receives the search query. |
| `groupText` | `string` | Built-in palette group headings. |
| `groupMedia` | `string` |  |
| `groupLayout` | `string` |  |
| `blockParagraph` | `string` | Built-in block labels + inserter descriptions. |
| `blockParagraphDesc` | `string` |  |
| `blockHeading` | `string` |  |
| `blockHeadingDesc` | `string` |  |
| `blockList` | `string` |  |
| `blockListDesc` | `string` |  |
| `blockQuote` | `string` |  |
| `blockQuoteDesc` | `string` |  |
| `blockCode` | `string` |  |
| `blockCodeDesc` | `string` |  |
| `blockImage` | `string` |  |
| `blockImageDesc` | `string` |  |
| `blockEmbed` | `string` |  |
| `blockEmbedDesc` | `string` |  |
| `blockButton` | `string` |  |
| `blockButtonDesc` | `string` |  |
| `blockDivider` | `string` |  |
| `blockDividerDesc` | `string` |  |
| `blockColumns` | `string` |  |
| `blockColumnsDesc` | `string` |  |
| `bold` | `string` | Rich-text inline toolbar. |
| `italic` | `string` |  |
| `underline` | `string` |  |
| `strikethrough` | `string` |  |
| `inlineCode` | `string` |  |
| `link` | `string` |  |
| `clearFormatting` | `string` |  |
| `linkUrlPrompt` | `string` | Prompt asking for a link URL. |
| `editableText` | `string` | Default label of the editable rich-text region. |
| `headingPlaceholder` | `(level: number) => string` | Heading block. |
| `headingLevelGroup` | `string` |  |
| `listStyle` | `string` | List block. |
| `bulleted` | `string` |  |
| `numbered` | `string` |  |
| `listItem` | `string` |  |
| `quoteText` | `string` | Quote block. |
| `citation` | `string` |  |
| `addCitation` | `string` |  |
| `codeLanguage` | `string` | Code block. |
| `codeLanguagePlaceholder` | `string` |  |
| `enterCode` | `string` |  |
| `imageWidth` | `(percent: number) => string` | Image block. |
| `uploading` | `string` |  |
| `dropImagePrompt` | `string` |  |
| `chooseFile` | `string` |  |
| `pasteImageUrl` | `string` |  |
| `notAnImage` | `string` |  |
| `uploadFailed` | `string` |  |
| `imageAdded` | `string` |  |
| `pasteEmbedUrl` | `string` | Embed block. |
| `embedFallbackNote` | `string` |  |
| `embedTitle` | `(provider: string) => string` |  |
| `embedAdded` | `(provider: string) => string` |  |
| `embeddedContent` | `string` |  |
| `buttonLabel` | `string` | Button block settings. |
| `buttonLink` | `string` |  |
| `buttonTone` | `string` |  |
| `buttonVariant` | `string` |  |
| `buttonDefaultLabel` | `string` | Label a freshly inserted Button block starts with. |
| `alignLeft` | `string` | Alignment option captions (image + button blocks). |
| `alignCenter` | `string` |  |
| `alignRight` | `string` |  |
| `tonePrimary` | `string` | Tone option captions (button block swatches). |
| `toneNeutral` | `string` |  |
| `toneSuccess` | `string` |  |
| `toneWarning` | `string` |  |
| `toneDanger` | `string` |  |
| `toneInfo` | `string` |  |
| `variantSolid` | `string` | Variant option captions (button block). |
| `variantSoft` | `string` |  |
| `variantOutline` | `string` |  |
| `ratioEqual` | `string` | Columns settings option captions. |
| `alignStretch` | `string` |  |
| `alignTop` | `string` |  |
| `alignMiddle` | `string` |  |
| `alignBottom` | `string` |  |
| `justifyStart` | `string` |  |
| `justifyCenter` | `string` |  |
| `justifyEnd` | `string` |  |
| `justifyBetween` | `string` |  |

### MkDateNames (interface)

Import: `import { MkDateNames } from '@mk-kit/ui/core';`

Localised month and weekday name tables (the shape `MK_I18N` carries).

Members:

| Name | Type | Description |
| --- | --- | --- |
| `months` | `readonly string[]` | Full month names, January-first (12). |
| `monthsShort` | `readonly string[]` | Abbreviated month names (12). |
| `weekdays` | `readonly string[]` | Full weekday names, Sunday-first (7). |
| `weekdaysShort` | `readonly string[]` | Abbreviated weekday names (7). |
| `weekdaysNarrow` | `readonly string[]` | One/two-letter weekday names for calendar headers (7). |

### MkI18nStrings (interface)

Import: `import { MkI18nStrings } from '@mk-kit/ui/core';`

All user-facing strings the library renders itself (aria-labels, empty-state
text, control captions and screen-reader announcements). Consumers localise
the library by overriding any subset via `provideMkI18n`. Interpolated
strings are functions so translators control word order.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `locale`? | `string \| undefined` | BCP 47 locale tag (`'pl-PL'`, `'de'`) used by the formatting pipes (`mkCurrency`, `mkRelativeTime`, `mkFileSize`, `mkPluralize`) and any other `Intl`-based formatting that has no explicit locale of its own. Unset → the runtime (browser / Node) default locale. |
| `currency`? | `string \| undefined` | ISO 4217 currency code the `mkCurrency` pipe falls back to when the template passes none. Unset → `'USD'`. |
| `validation` | `MkValidationStrings` | Validation messages (deep-merged by provideMkI18n). |
| `close` | `string` | Generic "Close" control (dialog, drawer, bottom-sheet). |
| `dismiss` | `string` | Generic "Dismiss" control (alert, banner, toast, snackbar). |
| `clear` | `string` | Clear-input control (autocomplete, pickers, tag inputs). |
| `confirm` | `string` | Generic confirm action (confirm dialog, popconfirm). |
| `cancel` | `string` | Generic cancel action (dialogs, inline edit). |
| `ok` | `string` | Generic acknowledge action (alert/prompt dialogs). |
| `save` | `string` | Generic save action (inline edit). |
| `submit` | `string` | Default action-button caption (submit input). |
| `edit` | `string` | Generic edit affordance (inline edit trigger). |
| `remove` | `string` | Generic remove control (chip). |
| `removeItem` | `(name: string) => string` | Remove a named item (tag input chips, file upload rows). |
| `empty` | `string` | Placeholder shown for an empty editable value (inline edit, mini date). |
| `optional` | `string` | "Optional" marker (stepper). |
| `filter` | `string` | Filter/search field placeholder (transfer list). |
| `confirmMessage` | `string` | Default confirmation question (popconfirm). |
| `decrease` | `string` | Decrease control (number input). |
| `increase` | `string` | Increase control (number input). |
| `loading` | `string` | Async loading row (autocomplete, multi-select). |
| `noOptions` | `string` | Empty listbox with no options (select, time picker). |
| `noResults` | `string` | Empty async/filtered results (autocomplete, multi-select, command palette). |
| `noData` | `string` | Empty data table / list. |
| `translationEditorSearch` | `string` | Translation editor (`@mk-kit/ui/translate/editor`). |
| `translationEditorAll` | `string` |  |
| `translationEditorOverridden` | `string` |  |
| `translationEditorMissing` | `string` |  |
| `translationEditorKey` | `string` |  |
| `translationEditorReset` | `string` |  |
| `translationEditorExport` | `string` |  |
| `translationEditorKeys` | `string` |  |
| `sessionExpiryTitle` | `string` | Session-expiry dialog (`@mk-kit/ui/attention`). |
| `sessionExpiryExtend` | `string` |  |
| `sessionExpiryExtending` | `string` |  |
| `sessionExpiryLogout` | `string` |  |
| `sessionExpiryBody` | `(countdown: string) => string` |  |
| `scannerTitle` | `string` | Barcode scanner (`@mk-kit/ui/media/scanner`). |
| `scannerHint` | `string` |  |
| `scannerCameraError` | `string` |  |
| `resultsCount` | `(count: number) => string` | Announced when a filterable list updates (autocomplete, multi-select, command palette). |
| `previousPage` | `string` | Pagination: previous page control. |
| `nextPage` | `string` | Pagination: next page control. |
| `goToPage` | `(page: number) => string` | Pagination: jump to a page. |
| `paginationLabel` | `string` | Pagination landmark label. |
| `previousSlide` | `string` | Carousel: previous slide control. |
| `nextSlide` | `string` | Carousel: next slide control. |
| `goToSlide` | `(slide: number) => string` | Carousel: jump to a slide. |
| `carouselLabel` | `string` | Carousel region label. |
| `pauseSlideshow` | `string` | Carousel: pause / resume automatic rotation. |
| `playSlideshow` | `string` |  |
| `slideOf` | `(slide: number, total: number) => string` | Carousel: slide position (slide labels + live announcements). |
| `dateNames` | `MkDateNames` | Localised month/weekday name tables (deep-merged by provideMkI18n). |
| `previousMonth` | `string` | Calendar: previous month control. |
| `nextMonth` | `string` | Calendar: next month control. |
| `previousYear` | `string` | Month picker: previous/next year (month mode). |
| `nextYear` | `string` |  |
| `previousYears` | `string` | Month picker: previous/next decade page (year mode). |
| `nextYears` | `string` |  |
| `selectDate` | `string` | Field placeholders. |
| `selectRange` | `string` |  |
| `selectTime` | `string` |  |
| `selectMonth` | `string` |  |
| `selectYear` | `string` |  |
| `selectWeek` | `string` |  |
| `selectPlaceholder` | `string` |  |
| `chooseDate` | `string` | Popover dialog labels. |
| `chooseDateRange` | `string` |  |
| `chooseMonth` | `string` |  |
| `chooseYear` | `string` |  |
| `chooseWeek` | `string` |  |
| `openCalendar` | `string` |  |
| `openTimeList` | `string` |  |
| `moreActions` | `string` | Accessible name of the chevron segment of `mk-split-button`. |
| `selectDateTime` | `string` | Placeholder of `mk-datetime-picker`. |
| `chooseDateTime` | `string` | Dialog label of the `mk-datetime-picker` panel. |
| `chooseTime` | `string` | Listbox label of the time list inside `mk-datetime-picker`. |
| `openDateTimePicker` | `string` | Toggle-button label of `mk-datetime-picker`. |
| `daySegment` | `string` | Mini-date segment names. |
| `monthSegment` | `string` |  |
| `yearSegment` | `string` |  |
| `countdownDays` | `string` | Countdown unit captions. |
| `countdownHours` | `string` |  |
| `countdownMinutes` | `string` |  |
| `countdownSeconds` | `string` |  |
| `countdownFinished` | `string` | Announced when a countdown reaches zero. |
| `dayEvents` | `(count: number, titles: string) => string` | Event-calendar day label suffix, e.g. `2 events: Standup, Demo`. |
| `moreEvents` | `(count: number) => string` | Event-calendar overflow pill for events beyond `maxPerDay`, e.g. `+2 more`. |
| `selectAllRows` | `string` | Select-all header checkbox. |
| `selectRow` | `(row: string) => string` | Per-row checkbox; receives the row's leading cell text. |
| `expandHeader` | `string` | Hidden expander column header. |
| `expandRow` | `string` | Row expander toggle labels. |
| `collapseRow` | `string` |  |
| `expandTreeRow` | `string` | Tree-row toggle labels (`childrenKey`). |
| `collapseTreeRow` | `string` |  |
| `expandGroup` | `string` | aria-label of a group header's toggle when the group is collapsed. |
| `collapseGroup` | `string` | aria-label of a group header's toggle when the group is expanded. |
| `groupCount` | `(count: number) => string` | Row count shown on a group header, e.g. "4 items". |
| `resizeColumn` | `string` | Column resize separator label. |
| `columnWidth` | `(column: string, width: number) => string` | Announced while a column is resized by keyboard. |
| `columnMoved` | `(column: string, position: number, total: number) => string` | Announced when a column is reordered. |
| `editCell` | `string` | Hint suffix + announcement for editable cells. |
| `cellSaved` | `(value: string) => string` |  |
| `sortedBy` | `(column: string, direction: MkSortAnnounceDirection) => string` | Announced when a column is sorted. |
| `sortingCleared` | `(column: string) => string` | Announced when sorting is removed from a column. |
| `showPassword` | `string` | Password reveal toggle. |
| `hidePassword` | `string` |  |
| `passwordRuleMinLength` | `(length: number) => string` | Password rule captions. |
| `passwordRuleUppercase` | `string` |  |
| `passwordRuleNumber` | `string` |  |
| `passwordRuleSymbol` | `string` |  |
| `passwordStrength` | `(score: number) => string` | Password strength label for a 0–4 score. |
| `passwordStrengthLabel` | `string` | Visible prefix before the strength label. |
| `ruleMet` | `string` | Rule-state prefixes announced to screen readers. |
| `ruleNotMet` | `string` |  |
| `oneTimeCode` | `string` | OTP field labels. |
| `otpDigit` | `(position: number) => string` |  |
| `numericKeypadLabel` | `string` | Numeric keypad labels + masked-PIN progress announcement. |
| `keypadClear` | `string` |  |
| `keypadBackspace` | `string` |  |
| `keypadDigitsEntered` | `(count: number, length: number) => string` |  |
| `onScreenKeyboardLabel` | `string` | On-screen keyboard label + action-key labels. |
| `keyboardShift` | `string` |  |
| `keyboardSpace` | `string` |  |
| `keyboardEnter` | `string` |  |
| `keyboardAltLayer` | `string` |  |
| `keyboardBaseLayer` | `string` |  |
| `ratingLabel` | `string` | Rating slider label + value text. |
| `ratingValueText` | `(value: number, max: number) => string` |  |
| `minimum` | `string` | Range slider thumb labels. |
| `maximum` | `string` |  |
| `chooseColor` | `string` | Color picker labels. |
| `hexValue` | `string` |  |
| `presetColors` | `string` |  |
| `chooseCountry` | `string` | Phone input: country-prefix trigger label. |
| `searchCountries` | `string` | Phone input: search field placeholder inside the country list. |
| `phoneNumber` | `string` | Phone input: default accessible label of the national-number field. |
| `postalCode` | `string` | Postal-code input: default accessible label. |
| `amount` | `string` | Currency input: default accessible label. |
| `cardNumber` | `string` | Card-number input: default accessible label. |
| `cardBrand` | `(brand: string) => string` | Card-number input: announced/badge text for a detected brand. |
| `iban` | `string` | IBAN input: default accessible label. |
| `taxId` | `string` | Tax-ID input: default accessible label. |
| `signature` | `string` | Signature pad: default accessible label of the drawing surface. |
| `jsonLabel` | `string` | JSON viewer: default accessible label of the tree. |
| `logViewerLabel` | `string` | Log viewer: default accessible label of the log region. |
| `logFollow` | `string` | Log viewer: re-attach-to-tail button. |
| `logCopyAll` | `string` | Log viewer: copy-the-whole-buffer toolbar button. |
| `logWrapLines` | `string` | Log viewer: soft-wrap toolbar toggle. |
| `orgChartLabel` | `string` | Org chart: default accessible label of the tree. |
| `orgChartExpand` | `string` | Org chart: aria-label of a collapsed node's toggle (`{label}` = node label). |
| `orgChartCollapse` | `string` | Org chart: aria-label of an expanded node's toggle (`{label}` = node label). |
| `chatLabel` | `string` | Chat: accessible name of the message log. |
| `chatComposerLabel` | `string` | Chat: accessible name of the composer textarea. |
| `chatPlaceholder` | `string` | Chat: composer placeholder. |
| `chatSend` | `string` | Chat: send button. |
| `chatStop` | `string` | Chat: stop-generating button (replaces send while busy). |
| `chatAttach` | `string` | Chat: attach-files button. |
| `chatRemoveAttachment` | `string` | Chat: remove one pending attachment. |
| `chatAttachments` | `string` | Chat: group label of pending / shown attachments. |
| `chatSuggestions` | `string` | Chat: group label of quick-reply suggestions. |
| `chatCopy` | `string` | Chat: copy-message button. |
| `chatRetry` | `string` | Chat: retry a failed message. |
| `chatTyping` | `string` | Chat: typing indicator. |
| `chatStreaming` | `string` | Chat: screen-reader text while a reply streams in. |
| `chatJumpToLatest` | `string` | Chat: scroll-to-newest button. |
| `chatEmpty` | `string` | Chat: empty-state text. |
| `chatYou` | `string` | Chat: author fallback for the user's own messages. |
| `chatAssistant` | `string` | Chat: author fallback for assistant messages. |
| `chatToolRunning` | `string` | Chat: tool call in progress. |
| `chatToolDone` | `string` | Chat: tool call finished. |
| `chatToolError` | `string` | Chat: tool call failed. |
| `dynamicFormAdd` | `string` | Dynamic form: add an item to an array field. |
| `dynamicFormRemove` | `(index: number) => string` | Dynamic form: remove one item of an array field (index is 1-based). |
| `queryBuilderLabel` | `string` | Query builder: accessible name of the whole builder. |
| `queryAddRule` | `string` |  |
| `queryAddGroup` | `string` |  |
| `queryRemoveRule` | `string` |  |
| `queryRemoveGroup` | `string` |  |
| `queryAnd` | `string` | Combinator labels — also used by `mkQueryToText`. |
| `queryOr` | `string` |  |
| `queryNot` | `string` |  |
| `queryField` | `string` |  |
| `queryOperator` | `string` |  |
| `queryValue` | `string` |  |
| `queryValueFrom` | `string` |  |
| `queryValueTo` | `string` |  |
| `queryEmptyGroup` | `string` |  |
| `queryTrue` | `string` |  |
| `queryFalse` | `string` |  |
| `queryOpEq` | `string` |  |
| `queryOpNeq` | `string` |  |
| `queryOpContains` | `string` |  |
| `queryOpNotContains` | `string` |  |
| `queryOpStartsWith` | `string` |  |
| `queryOpEndsWith` | `string` |  |
| `queryOpGt` | `string` |  |
| `queryOpGte` | `string` |  |
| `queryOpLt` | `string` |  |
| `queryOpLte` | `string` |  |
| `queryOpBetween` | `string` |  |
| `queryOpIn` | `string` |  |
| `queryOpNotIn` | `string` |  |
| `queryOpBefore` | `string` |  |
| `queryOpAfter` | `string` |  |
| `queryOpEmpty` | `string` |  |
| `queryOpNotEmpty` | `string` |  |
| `dialogMove` | `string` | Dialog: label of the move grip (arrow keys move, Home resets). |
| `dialogResize` | `string` | Dialog: label of the resize grip (arrow keys resize, Home resets). |
| `listboxFilter` | `string` | Listbox: filter box placeholder / label. |
| `listboxEmpty` | `string` | Listbox: shown when the filter matches nothing. |
| `eventCalendarGrabbed` | `(title: string, from: string, to: string) => string` | Announced when an event is picked up in keyboard move mode. |
| `eventCalendarPosition` | `(title: string, day: string, from: string, to: string) => string` | Announced after each keyboard step: current day + time range. |
| `eventCalendarMoved` | `(title: string, day: string, from: string, to: string) => string` | Announced when a move commits. |
| `eventCalendarResized` | `(title: string, to: string) => string` | Announced when a resize commits. |
| `eventCalendarEditCancelled` | `string` | Announced when an edit is aborted. |
| `eventCalendarMovableEvent` | `string` | `aria-roledescription` of an editable event pill. |
| `previousImage` | `string` | Lightbox / gallery: previous-image control. |
| `nextImage` | `string` | Lightbox / gallery: next-image control. |
| `imageOf` | `(index: number, total: number) => string` | Lightbox counter + per-image aria label, e.g. `Image 2 of 8`. |
| `viewImage` | `(alt: string) => string` | Gallery tile label; receives the image's alt text. |
| `imageFailed` | `string` | Shown in an image block whose source failed to load. |
| `zoom` | `string` | Cropper zoom controls. |
| `zoomIn` | `string` |  |
| `zoomOut` | `string` |  |
| `mediaLibrary` | `string` | Media gallery region label. |
| `dropzoneLabel` | `string` | File upload dropzone + states. |
| `uploadFailed` | `string` |  |
| `retryUpload` | `string` |  |
| `errorSummaryTitle` | `string` | Form error summary heading. |
| `available` | `string` | Default column titles. |
| `selected` | `string` |  |
| `transferSelected` | `(target: string) => string` | Move-button labels; receive the target list's title. |
| `transferAll` | `(target: string) => string` |  |
| `itemsMoved` | `(count: number, target: string) => string` | Announced after a move. |
| `notificationsTitle` | `string` |  |
| `allCaughtUp` | `string` |  |
| `markAllRead` | `string` |  |
| `notificationsUnread` | `(count: number) => string` |  |
| `unread` | `string` | Unread state announced per row. |
| `tourStepOf` | `(step: number, total: number) => string` |  |
| `tourSkip` | `string` |  |
| `tourPrevious` | `string` |  |
| `tourNext` | `string` |  |
| `tourDone` | `string` |  |
| `commandPalettePlaceholder` | `string` | Command palette input placeholder. |
| `commandPaletteLabel` | `string` | Command palette dialog label. |
| `stepCompleted` | `string` | Stepper: step state, appended to the step's accessible name. |
| `stepError` | `string` |  |
| `diffAddedLine` | `string` | Diff: screen-reader prefix for changed lines. |
| `diffRemovedLine` | `string` |  |
| `itemAdded` | `(name: string) => string` | Chip collections (tag input, multi-select): announced on add/remove. |
| `itemRemoved` | `(name: string) => string` |  |
| `resizePanes` | `string` | Splitter separator label. |
| `backToTop` | `string` | Back-to-top button label. |
| `breadcrumbLabel` | `string` | Breadcrumb nav landmark label. |
| `fabLabel` | `string` | FAB default label. |
| `appSwitcherLabel` | `string` | App switcher: trigger / panel label, and the note when the registry cannot be fetched. |
| `appSwitcherError` | `string` |  |
| `diffBefore` | `string` | Diff view labels. |
| `diffAfter` | `string` |  |
| `diffChanges` | `string` |  |
| `skipToContent` | `string` | App shell. |
| `primaryNav` | `string` |  |
| `dndPickedUp` | `(position: number, total: number) => string` | Announced when an item is lifted for keyboard dragging. |
| `dndMoved` | `(position: number, total: number) => string` | Announced as the item moves within its list. |
| `dndMovedToList` | `(list: string, position: number, total: number) => string` | Announced as the item moves into another list. |
| `dndDropped` | `(position: number) => string` | Announced when the item is dropped. |
| `dndMovedToZone` | `(zone: string) => string` | Announced as a lifted item reaches a drop zone (a target that is not a list). |
| `dndDroppedInZone` | `(zone: string) => string` | Announced when the item is dropped on a zone. |
| `dndCancelled` | `string` | Announced when the drag is cancelled. |
| `repeaterAddRow` | `string` | Repeater add-row button caption (default when no `addLabel` is given). |
| `repeaterRemoveRow` | `(index: number) => string` | Repeater per-row remove button label (1-based row number). |
| `repeaterReorderRow` | `(index: number) => string` | Repeater per-row drag-handle label (1-based row number). |
| `repeaterRowMoved` | `(from: number, to: number) => string` | Announced after a repeater row is reordered (1-based positions). |
| `fileRejectedType` | `(name: string) => string` |  |
| `fileRejectedSize` | `(name: string, limit: string) => string` |  |
| `fileRejectedCount` | `(name: string, max: number) => string` |  |
| `chartCategory` | `string` |  |
| `chartValue` | `string` |  |
| `chartSeries` | `string` |  |
| `chartSlice` | `string` |  |
| `chartStage` | `string` |  |
| `chartConversion` | `string` |  |
| `chartAxis` | `string` |  |
| `chartShare` | `string` |  |
| `chartLabel` | `string` |  |
| `qrCodeLabel` | `(text: string) => string` | Default accessible label of a QR code, carrying its encoded content. |
| `sortableListLabel` | `string` | Default accessible name of `mk-sortable-list` when no `label` is given. |
| `filterColumn` | `(column: string) => string` | Table filter row: accessible name of a column's filter control. |
| `clearFilter` | `(column: string) => string` | Table filter row: the per-control clear (×) button. |
| `filterAny` | `string` | Table filter row: the "no filter" option of a select filter. |
| `filterMin` | `string` | Table filter row: placeholder of a number / date filter (matches values ≥ the entry). |
| `blockEditor` | `MkBlockEditorStrings` | Block editor chrome (deep-merged by provideMkI18n). |

### MkOverlayConfig (interface)

Import: `import { MkOverlayConfig } from '@mk-kit/ui/core';`

Members:

| Name | Type | Description |
| --- | --- | --- |
| `data`? | `TData \| undefined` | Arbitrary data injected via `MK_OVERLAY_DATA`. |
| `hasBackdrop`? | `boolean \| undefined` | Render a dimmed scrim behind the panel. Default `true`. |
| `closeOnBackdropClick`? | `boolean \| undefined` | Close when the backdrop is clicked. Default `true`. |
| `closeOnEscape`? | `boolean \| undefined` | Close when Escape is pressed. Default `true`. |
| `trapFocus`? | `boolean \| undefined` | Trap focus within the panel and restore it on close. Default `true`. |
| `autoFocus`? | `boolean \| undefined` | Move focus to the panel's first focusable element on open. Default `true`. Set `false` to focus the panel itself instead — for content-led surfaces (a product sheet, a preview) where focusing the close button first reads as "dismiss me". Tab containment and focus restore are unaffected; turn `trapFocus` off only if you want neither. |
| `panelClass`? | `string \| string[] \| undefined` | Extra class(es) applied to the panel host element. |
| `role`? | `"dialog" \| "alertdialog" \| "menu" \| "listbox" \| undefined` | Accessible role for the panel. Default `dialog`. |
| `ariaLabel`? | `string \| undefined` | `aria-label` for the panel when no visible title is wired up. |
| `injector`? | `Injector \| undefined` | A custom injector to use as the parent for the rendered component. |

### MkQueryField (interface)

Import: `import { MkQueryField } from '@mk-kit/ui/core';`

A field the user can filter on.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `string` | Property key on the row objects / the API's filter name. |
| `label` | `string` | Label shown in the field picker. |
| `type`? | `MkQueryValueType \| undefined` | Default `string`. |
| `options`? | `readonly MkQueryFieldOption[] \| undefined` | Choices for `select` fields. |
| `operators`? | `readonly MkQueryOperator[] \| undefined` | Restrict / reorder the operators offered (default: all for the type). |
| `placeholder`? | `string \| undefined` | Placeholder of the value editor. |

### MkQueryFieldOption (interface)

Import: `import { MkQueryFieldOption } from '@mk-kit/ui/core';`

A choice for `select` fields.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` |  |
| `value` | `unknown` |  |

### MkQueryGroup (interface)

Import: `import { MkQueryGroup } from '@mk-kit/ui/core';`

A group of rules and nested groups joined by one combinator, optionally negated.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `combinator` | `MkQueryCombinator` |  |
| `not`? | `boolean \| undefined` | Negate the whole group. |
| `rules` | `MkQueryNode[]` |  |

### MkQueryRule (interface)

Import: `import { MkQueryRule } from '@mk-kit/ui/core';`

A leaf condition. `value` is `[from, to]` for `between`, an array for `in` / `notIn`, absent for `empty` / `notEmpty`. Dates are ISO strings.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `field` | `string` |  |
| `operator` | `MkQueryOperator` |  |
| `value`? | `unknown` |  |

### MkQueryTextStrings (interface)

Import: `import { MkQueryTextStrings } from '@mk-kit/ui/core';`

The strings `mkQueryToText` and `mkQueryOperatorLabel` render
with. A structural subset of mk-kit's `MkI18nStrings`, so the UI's full
i18n map can be passed directly; defaults to `MK_QUERY_TEXT_EN`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `queryTrue` | `string` |  |
| `queryFalse` | `string` |  |
| `queryAnd` | `string` |  |
| `queryOr` | `string` |  |
| `queryNot` | `string` |  |
| `queryOpEq` | `string` |  |
| `queryOpNeq` | `string` |  |
| `queryOpContains` | `string` |  |
| `queryOpNotContains` | `string` |  |
| `queryOpStartsWith` | `string` |  |
| `queryOpEndsWith` | `string` |  |
| `queryOpGt` | `string` |  |
| `queryOpGte` | `string` |  |
| `queryOpLt` | `string` |  |
| `queryOpLte` | `string` |  |
| `queryOpBetween` | `string` |  |
| `queryOpIn` | `string` |  |
| `queryOpNotIn` | `string` |  |
| `queryOpBefore` | `string` |  |
| `queryOpAfter` | `string` |  |
| `queryOpEmpty` | `string` |  |
| `queryOpNotEmpty` | `string` |  |

### MkSignalValidationError (interface)

Import: `import { MkSignalValidationError } from '@mk-kit/ui/core';`

The shape of a Signal Forms validation error as `mk-kit` reads it — the
`{ kind, message? }` contract of `ValidationError` from
`@angular/forms/signals`, plus whatever payload the error class carries
(`min`, `maxLength`, `pattern`, …). Declared structurally so `@mk-kit/ui/core`
stays free of a runtime dependency on the signals entry point.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `string` | Identifies the kind of error (`'required'`, `'minLength'`, …). |
| `message`? | `string \| undefined` | Human-readable message, when the schema supplied one. |

### MkValidationStrings (interface)

Import: `import { MkValidationStrings } from '@mk-kit/ui/core';`

Messages rendered by `mk-form-field` for the validation errors the library's
own controls produce, plus the standard Angular `Validators` keys, so a
field wrapping any control shows something sensible without per-form wiring.

Keys match the `ValidationErrors` keys exactly and each entry receives that
key's error payload. Override any subset through
`provideMkI18n({ validation: … })`, or a whole map per field via
`mk-form-field`'s `errorMessages` input.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `required` | `string` | `Validators.required` — also emitted by checkbox and radio-group. |
| `email` | `string` | `Validators.email`. |
| `min` | `(err: { min: number; actual: number; }) => string` | `Validators.min`, and the numeric controls' `[min]`. |
| `max` | `(err: { max: number; actual: number; }) => string` | `Validators.max`, and the numeric controls' `[max]`. |
| `minlength` | `(err: { requiredLength: number; actualLength: number; }) => string` | `Validators.minLength` — also emitted by password-input and OTP. |
| `maxlength` | `(err: { requiredLength: number; actualLength: number; }) => string` | `Validators.maxLength`. |
| `pattern` | `string` | `Validators.pattern`. |
| `mkMinDate` | `(err: { min: Date; actual: Date; }) => string` | A date/month/week picker's `[min]`. |
| `mkMaxDate` | `(err: { max: Date; actual: Date; }) => string` | A date/month/week picker's `[max]`. |
| `mkDateFilter` | `string` | A date rejected by a calendar's `[disabledDate]` predicate. |
| `mkDateRangeIncomplete` | `string` | A range picker with only one end filled in. |
| `mkMinTime` | `(err: { min: string; actual: string; }) => string` | The time-picker's `[min]`. |
| `mkMaxTime` | `(err: { max: string; actual: string; }) => string` | The time-picker's `[max]`. |
| `mkMaxItems` | `(err: { max: number; actual: number; }) => string` | More items than a multi-select's, tag-input's or upload's `[max*]` allows. |
| `mkFileSize` | `(err: { max: number; maxLabel: string; name: string; }) => string` | A file larger than a file-upload's `[maxSize]`. |
| `mkFileType` | `(err: { accept: string; name: string; }) => string` | A file not matching a file-upload's `[accept]` filter. |
| `cardNumber` | `string` | A card number failing the Luhn checksum. |
| `iban` | `(err: { country: string; expectedLength: number \| null; }) => string` | An IBAN failing the mod-97 checksum. |
| `postalCode` | `(err: { country: string; example: string; }) => string` | A postal code not matching the country's format. |
| `taxId` | `(err: { country: string; label: string; example: string; }) => string` | A tax identifier not matching the country's format or checksum. |
| `unknown` | `string` | Fallback for an error key with no message of its own. |

### MkValidatorChangeRef (interface)

Import: `import { MkValidatorChangeRef } from '@mk-kit/ui/core';`

Handle returned by `mkValidatorChange`, wiring a component's
`registerOnValidatorChange` callback to a set of reactive dependencies.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `register` | `(fn: () => void): void` | Store the callback Angular hands to `registerOnValidatorChange`. |
| `notify` | `(): void` | Ask the bound control to re-run `validate()` now. |

### MkAccentKey (type)

Import: `import { MkAccentKey } from '@mk-kit/ui/core';`

One of the eight kit accents (the Momentum palette).

```ts
type MkAccentKey = 'indigo' | 'blue' | 'teal' | 'violet' | 'coral' | 'lime' | 'pink' | 'bumblebee';
```

### MkAriaLivePoliteness (type)

Import: `import { MkAriaLivePoliteness } from '@mk-kit/ui/core';`

```ts
type MkAriaLivePoliteness = 'polite' | 'assertive';
```

### MkBreakpoint (type)

Import: `import { MkBreakpoint } from '@mk-kit/ui/core';`

Named viewport ranges, mobile-first: each starts at its min-width.

```ts
type MkBreakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
```

### MkBreakpoints (type)

Import: `import { MkBreakpoints } from '@mk-kit/ui/core';`

Min-widths (px) at which each named breakpoint begins; `xs` is everything below `sm`.

```ts
type MkBreakpoints = Record<Exclude<MkBreakpoint, 'xs'>, number>;
```

### MkCodeLanguage (type)

Import: `import { MkCodeLanguage } from '@mk-kit/ui/core';`

Languages with built-in highlighting. Unknown values render plain text.

```ts
type MkCodeLanguage = 'json' | 'plaintext';
```

### MkContrastPreference (type)

Import: `import { MkContrastPreference } from '@mk-kit/ui/core';`

Contrast preference.

`high` applies the high-contrast token preset (`data-mk-contrast="high"`):
pure text colours, line-like borders, opaque interaction washes, a thicker
focus ring. `system` (the default) writes no attribute and lets the
stylesheet follow the OS `prefers-contrast: more` setting; `normal` opts
out of that even when the OS asks for more contrast.

```ts
type MkContrastPreference = 'normal' | 'high' | 'system';
```

### MkDensity (type)

Import: `import { MkDensity } from '@mk-kit/ui/core';`

Global control-density mode.

`touch` sizes controls for fingers (48px default) rather than a cursor —
tablets, kiosks, order screens. It is usually applied per-subtree with the
`data-mk-density` attribute rather than globally, since one app often has
both a mouse-driven admin and a touch-driven screen.

```ts
type MkDensity = 'comfortable' | 'compact' | 'touch';
```

### MkErrorMessages (type)

Import: `import { MkErrorMessages } from '@mk-kit/ui/core';`

A per-field override map: an error key mapped either to a fixed message or
to a function receiving that key's error payload.

```html
<mk-form-field label="Age" [errorMessages]="{ min: 'You must be 18 or over' }">
```

```ts
type MkErrorMessages = Readonly<Record<string, string | ((err: any) => string)>>;
```

### MkI18nOverrides (type)

Import: `import { MkI18nOverrides } from '@mk-kit/ui/core';`

Any subset of `MkI18nStrings`; the nested `dateNames`, `blockEditor`
and `validation` groups may be partial too (they are merged deeply).

```ts
type MkI18nOverrides = Partial< Omit<MkI18nStrings, 'dateNames' | 'blockEditor' | 'validation'> > & { dateNames?: Partial<MkDateNames>; blockEditor?: Partial<MkBlockEditorStrings>; validation?: Partial<MkValidationStrings>; };
```

### MkOverlayRootFn (type)

Import: `import { MkOverlayRootFn } from '@mk-kit/ui/core';`

Resolves the element overlay surfaces are appended to. A function (not an
element) because the root may be created lazily, after DI is set up.

```ts
type MkOverlayRootFn = () => HTMLElement;
```

### MkPlacement (type)

Import: `import { MkPlacement } from '@mk-kit/ui/core';`

Common placement values for anchored overlays (menus, tooltips, popovers).

```ts
type MkPlacement = | 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end';
```

### MkQueryCombinator (type)

Import: `import { MkQueryCombinator } from '@mk-kit/ui/core';`

```ts
type MkQueryCombinator = 'and' | 'or';
```

### MkQueryNode (type)

Import: `import { MkQueryNode } from '@mk-kit/ui/core';`

```ts
type MkQueryNode = MkQueryRule | MkQueryGroup;
```

### MkQueryOperator (type)

Import: `import { MkQueryOperator } from '@mk-kit/ui/core';`

Comparison operators. Which apply depends on the field type.

```ts
type MkQueryOperator = | 'eq' | 'neq' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'in' | 'notIn' | 'before' | 'after' | 'empty' | 'notEmpty';
```

### MkQueryValueType (type)

Import: `import { MkQueryValueType } from '@mk-kit/ui/core';`

Value kind of a filterable field; decides the editor and the operators offered.

```ts
type MkQueryValueType = 'string' | 'number' | 'boolean' | 'date' | 'select';
```

### MkResolvedContrast (type)

Import: `import { MkResolvedContrast } from '@mk-kit/ui/core';`

Concrete resolved contrast (never `system`).

```ts
type MkResolvedContrast = 'normal' | 'high';
```

### MkResolvedTheme (type)

Import: `import { MkResolvedTheme } from '@mk-kit/ui/core';`

Concrete resolved theme (never `system`).

```ts
type MkResolvedTheme = 'light' | 'dark';
```

### MkResponsive (type)

Import: `import { MkResponsive } from '@mk-kit/ui/core';`

A value that may differ per breakpoint: either the plain value or a
mobile-first map, `{ xs: 1, md: 2, xl: 4 }`, where each key applies from
that breakpoint up until the next key given.

```ts
type MkResponsive<T> = T | Partial<Record<MkBreakpoint, T>>;
```

### MkSize (type)

Import: `import { MkSize } from '@mk-kit/ui/core';`

Control size scale. Maps to `--mk-control-height-*` tokens.

```ts
type MkSize = 'sm' | 'md' | 'lg';
```

### MkSortAnnounceDirection (type)

Import: `import { MkSortAnnounceDirection } from '@mk-kit/ui/core';`

Direction passed to the sort announcer.

```ts
type MkSortAnnounceDirection = 'asc' | 'desc';
```

### MkThemePreference (type)

Import: `import { MkThemePreference } from '@mk-kit/ui/core';`

Theme selection. `system` follows the OS `prefers-color-scheme`.

```ts
type MkThemePreference = 'light' | 'dark' | 'system';
```

### MkTone (type)

Import: `import { MkTone } from '@mk-kit/ui/core';`

Semantic color tone. Each maps to a `--mk-<tone>*` token family.

```ts
type MkTone = | 'primary' | 'neutral' | 'success' | 'warning' | 'danger' | 'info';
```

### MkVariant (type)

Import: `import { MkVariant } from '@mk-kit/ui/core';`

Visual treatment for tinted/interactive surfaces.

```ts
type MkVariant = 'solid' | 'soft' | 'outline' | 'ghost' | 'link';
```

## @mk-kit/ui/core/signal-forms

1 exports. `import { … } from '@mk-kit/ui/core/signal-forms';`

### mkInjectFieldTouched (function)

Import: `import { mkInjectFieldTouched } from '@mk-kit/ui/core/signal-forms';`

Touched-gate for a control's `invalid` input under Signal Forms.

When a control is bound with the `[formField]` directive, Angular writes the
field's `invalid()` state straight into the control's `invalid` input — from
the first render, before the user has reached the field. mk-kit controls
pass that input through this gate so the invalid visual (and `aria-invalid`)
only shows once the field is touched or dirty, matching how `mk-form-field`
reveals its message and how `submit()` (which marks every field touched)
surfaces the remaining problems.

Returns a signal that is always `true` for a control that is not bound with
`[formField]`, so a standalone `[invalid]="true"` keeps working as before.
Call it in a field initializer (an injection context):

```ts
private readonly fieldTouched = mkInjectFieldTouched();
protected readonly isInvalid = computed(
  () => (this.invalid() && this.fieldTouched()) || (this.field?.hasError() ?? false),
);
```

The binding is looked up lazily, on first read: the `FormField` directive
itself injects the element's `NG_VALUE_ACCESSOR` (the control) while it is
created, so resolving it from the control's constructor would be circular.

```ts
function mkInjectFieldTouched(): Signal<boolean>
```

## @mk-kit/ui/icon

8 exports. `import { … } from '@mk-kit/ui/icon';`

### MkIcon (component)

Selector: `mk-icon`

Docs: https://mk-kit.dev/components/icon

Import: `import { MkIcon } from '@mk-kit/ui/icon';`

Icon — renders a registered SVG by `name`, or your own projected `<svg>`.
The glyph inherits the current text colour (`currentColor`) and scales to the
`size` box, so it composes cleanly inside buttons, inputs and menus.

Decorative by default (`aria-hidden`); pass `label` to expose it as an image
to assistive tech.

```html
<mk-icon name="search" />
<mk-icon name="trash" size="lg" label="Delete" />
<button mkButton iconOnly aria-label="Menu"><mk-icon name="menu" /></button>
<mk-icon><svg viewBox="0 0 24 24">…custom…</svg></mk-icon>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | `''` | Name of a registered icon (see `MkIconRegistry`). |
| `size` | `number \| MkSize` | `'md'` | Size: `sm`/`md`/`lg`, or a pixel number for a custom dimension. |
| `label` | `string` | `''` | Accessible name. When set the icon becomes `role="img"`; otherwise hidden. |

### MkIconRegistry (service)

Docs: https://mk-kit.dev/components/icon

Import: `import { MkIconRegistry } from '@mk-kit/ui/icon';`

IconRegistry — the name → SVG store behind `<mk-icon name="…">`. The
hand-made `MK_DEFAULT_ICONS` are registered on construction and ship
with every app. Everything else is opt-in and tree-shakeable: the
Lucide-derived extended set via `provideMkExtendedIcons()` (from
`@mk-kit/ui/icon/extended`), a themed subset or your own SVGs (from a
sprite, a design export, anything) via `provideMkIcons()`, or at runtime
with `register` / `registerIcons` / `load`.

SVG markup is trusted verbatim (bypassed through `DomSanitizer`), so only
register icons from sources you control — never user input.

```ts
const reg = inject(MkIconRegistry);
reg.register('logo', '<svg viewBox="0 0 24 24">…</svg>');
reg.registerIcons({ save: '<svg…>', share: '<svg…>' });
reg.load(() => import('@mk-kit/ui/icon/extended').then((m) => m.MK_EXTENDED_ICONS_FILES));
```

Methods:

| Signature | Description |
| --- | --- |
| `register(name: string, svg: string): this` | Register (or overwrite) a single named icon from raw SVG markup. |
| `registerIcons(icons: MkIconMap): this` | Register many icons at once from a `{ name: svg }` map — a whole set, a themed subset (`MK_EXTENDED_ICONS_FILES`) or a hand-picked few. Later registrations overwrite earlier ones on a shared name. |
| `registerAliases(aliases: Readonly<Record<string, string>>): this` | Register alternative names that resolve to existing icons — e.g. map Material Symbols ligature names onto the built-in set (`{ delete: 'trash', expand_more: 'chevron-down' }`). A real icon registered under an alias name always wins over the alias; an alias whose target is not registered resolves to nothing (and, in dev mode, warns once naming the missing target). |
| `load(loader: MkIconLoader): Promise<void>` | Load an icon map asynchronously and register it once it arrives. Icons already on screen fill in when the map lands (see `changes`); the missing-icon warning stays quiet while a load is pending. Server-side rendering waits for it (Angular's `PendingTasks`), so the HTML ships with the icons in place.  ```ts registry.load(() => import('@mk-kit/ui/icon/extended').then((m) => m.MK_EXTENDED_ICONS)); ``` |
| `get(name: string): SafeHtml \| null` | Sanitized SVG for a name (aliases resolved), or `null` when unknown. |
| `has(name: string): boolean` | Whether an icon with this name (or alias) is registered. |
| `names(): string[]` | All registered icon names (useful for a picker / catalogue). |
| `warnMissing(name: string): void` | Dev-mode only: warn once per unknown name with a hint about the opt-in extended set. Silent in production builds and while a `load` is pending (the name may be on its way). Called by `<mk-icon>`. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `changes` | `Signal<number>` | Bumps on every registration. `<mk-icon>` reads it, so an icon that arrives late (a lazy `load`, a runtime `register`) renders in place without any re-binding. |
| `pending` | `Signal<boolean>` | Whether a lazy `load` is still in flight. |

### provideMkIcons (function)

Import: `import { provideMkIcons } from '@mk-kit/ui/icon';`

Registers extra icons at bootstrap — a themed subset of the extended set,
a hand-picked few, your own SVGs, or a lazily loaded map. Call it as many
times as you like; each call adds to the `MkIconRegistry`. The
hand-made defaults are always there; this is for everything else.

```ts
import { provideMkIcons } from '@mk-kit/ui/icon';
import { MK_EXTENDED_ICONS_FILES, MK_EXTENDED_ICONS_DATA } from '@mk-kit/ui/icon/extended';

bootstrapApplication(App, {
  providers: [
    // themed subsets — only these glyphs end up in the bundle
    provideMkIcons(MK_EXTENDED_ICONS_FILES),
    provideMkIcons(MK_EXTENDED_ICONS_DATA),
    // your own
    provideMkIcons({ logo: '<svg viewBox="0 0 24 24">…</svg>' }),
    // or the whole extended set in its own lazy chunk, off the critical path
    provideMkIcons(() => import('@mk-kit/ui/icon/extended').then((m) => m.MK_EXTENDED_ICONS)),
  ],
});
```

A loader runs once at bootstrap without blocking it: icons already on
screen fill in when the chunk lands, and server-side rendering waits for
it. Picking single names out of the full map
(`{ receipt: MK_EXTENDED_ICONS['receipt'] }`) works but still bundles the
whole map — use a subset or copy the SVG when size matters.

```ts
function provideMkIcons(icons: MkIconMap | MkIconLoader): EnvironmentProviders
```

### provideMkMaterialIcons (function)

Import: `import { provideMkMaterialIcons } from '@mk-kit/ui/icon';`

Installs the Material Symbols name aliases into the `MkIconRegistry`,
so `<mk-icon name="delete" />`, `name="expand_more"`, `name="visibility"`
etc. resolve to the built-in set. Add it to your bootstrap providers when
migrating an app off `<mat-icon>` ligatures:

```ts
bootstrapApplication(App, {
  providers: [provideMkMaterialIcons()],
});
```

```ts
function provideMkMaterialIcons(): EnvironmentProviders
```

### MK_DEFAULT_ICONS (const)

Import: `import { MK_DEFAULT_ICONS } from '@mk-kit/ui/icon';`

Name → SVG markup map of the default icons (registered by `MkIconRegistry` on construction).

```ts
const MK_DEFAULT_ICONS: Readonly<Record<string, string>>;
```

### MK_MATERIAL_ICON_ALIASES (const)

Import: `import { MK_MATERIAL_ICON_ALIASES } from '@mk-kit/ui/icon';`

Material Symbols ligature names → built-in mk icon names. Lets templates
written against `<mat-icon>delete</mat-icon>` conventions keep their icon
names when migrating: `<mk-icon name="delete" />` renders the `trash`
glyph once `provideMkMaterialIcons` is installed.

Several Material names intentionally collapse onto one mk glyph (all the
calendar variants → `calendar`, the delete variants → `trash`, …). Every
target is a default icon, so the aliases work without the opt-in extended
set. Names not listed here have no sensible built-in equivalent — register
your own SVG under the Material name via `MkIconRegistry.register`, or
alias it onto an extended glyph with `registerAliases` once
`provideMkExtendedIcons()` is installed (an alias whose target is missing
renders nothing and warns once in dev mode).

```ts
const MK_MATERIAL_ICON_ALIASES: Readonly<Record<string, string>>;
```

### MkIconLoader (type)

Import: `import { MkIconLoader } from '@mk-kit/ui/icon';`

Loads an icon map on demand — typically a dynamic import of the extended
set: `() => import('@mk-kit/ui/icon/extended').then((m) => m.MK_EXTENDED_ICONS)`.

```ts
type MkIconLoader = () => Promise<MkIconMap>;
```

### MkIconMap (type)

Import: `import { MkIconMap } from '@mk-kit/ui/icon';`

A `{ name: '<svg …>…</svg>' }` map — what every registration API accepts.

```ts
type MkIconMap = Readonly<Record<string, string>>;
```

## @mk-kit/ui/icon/extended

19 exports. `import { … } from '@mk-kit/ui/icon/extended';`

### provideMkExtendedIcons (function)

Import: `import { provideMkExtendedIcons } from '@mk-kit/ui/icon/extended';`

Registers the whole Lucide-derived extended set (`MK_EXTENDED_ICONS`)
so every `<mk-icon name="…">` in the catalogue resolves. Opt-in: without
it only the hand-made defaults are available and an unknown name warns
once in dev mode.

```ts
import { provideMkExtendedIcons } from '@mk-kit/ui/icon/extended';

bootstrapApplication(App, {
  providers: [provideMkExtendedIcons()],
});
```

Size-conscious alternatives (see `provideMkIcons`): register only the
themed subsets you use (`provideMkIcons(MK_EXTENDED_ICONS_FILES)`), or load
the full set lazily in its own chunk:
`provideMkIcons(() => import('@mk-kit/ui/icon/extended').then((m) => m.MK_EXTENDED_ICONS))`.
The hand-made defaults keep their names — the generated set never
overlaps them.

```ts
function provideMkExtendedIcons(): EnvironmentProviders
```

### MK_EXTENDED_ICON_GROUPS (const)

Import: `import { MK_EXTENDED_ICON_GROUPS } from '@mk-kit/ui/icon/extended';`

The themed subsets by group name — handy for a picker or for registering
several groups at once: `provideMkIcons(MK_EXTENDED_ICON_GROUPS['files'])`.

```ts
const MK_EXTENDED_ICON_GROUPS: Readonly<Record<string, Readonly<Record<string, string>>>>;
```

### MK_EXTENDED_ICONS (const)

Import: `import { MK_EXTENDED_ICONS } from '@mk-kit/ui/icon/extended';`

Every Lucide-derived icon (305 glyphs). Not registered by
default — install it with `provideMkExtendedIcons()`, pass a themed subset
to `provideMkIcons()`, or load it lazily:
`provideMkIcons(() => import('@mk-kit/ui/icon/extended').then((m) => m.MK_EXTENDED_ICONS))`.

```ts
const MK_EXTENDED_ICONS: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_COMMERCE (const)

Import: `import { MK_EXTENDED_ICONS_COMMERCE } from '@mk-kit/ui/icon/extended';`

`commerce` subset of `MK_EXTENDED_ICONS` (23 icons).

```ts
const MK_EXTENDED_ICONS_COMMERCE: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_COMMUNICATION (const)

Import: `import { MK_EXTENDED_ICONS_COMMUNICATION } from '@mk-kit/ui/icon/extended';`

`communication` subset of `MK_EXTENDED_ICONS` (15 icons).

```ts
const MK_EXTENDED_ICONS_COMMUNICATION: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_DATA (const)

Import: `import { MK_EXTENDED_ICONS_DATA } from '@mk-kit/ui/icon/extended';`

`data` subset of `MK_EXTENDED_ICONS` (15 icons).

```ts
const MK_EXTENDED_ICONS_DATA: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_DEVELOPER (const)

Import: `import { MK_EXTENDED_ICONS_DEVELOPER } from '@mk-kit/ui/icon/extended';`

`developer` subset of `MK_EXTENDED_ICONS` (23 icons).

```ts
const MK_EXTENDED_ICONS_DEVELOPER: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_DEVICES (const)

Import: `import { MK_EXTENDED_ICONS_DEVICES } from '@mk-kit/ui/icon/extended';`

`devices` subset of `MK_EXTENDED_ICONS` (15 icons).

```ts
const MK_EXTENDED_ICONS_DEVICES: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_EDITING (const)

Import: `import { MK_EXTENDED_ICONS_EDITING } from '@mk-kit/ui/icon/extended';`

`editing` subset of `MK_EXTENDED_ICONS` (34 icons).

```ts
const MK_EXTENDED_ICONS_EDITING: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_FILES (const)

Import: `import { MK_EXTENDED_ICONS_FILES } from '@mk-kit/ui/icon/extended';`

`files` subset of `MK_EXTENDED_ICONS` (22 icons).

```ts
const MK_EXTENDED_ICONS_FILES: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_LAYOUT (const)

Import: `import { MK_EXTENDED_ICONS_LAYOUT } from '@mk-kit/ui/icon/extended';`

`layout` subset of `MK_EXTENDED_ICONS` (17 icons).

```ts
const MK_EXTENDED_ICONS_LAYOUT: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_LIFESTYLE (const)

Import: `import { MK_EXTENDED_ICONS_LIFESTYLE } from '@mk-kit/ui/icon/extended';`

`lifestyle` subset of `MK_EXTENDED_ICONS` (40 icons).

```ts
const MK_EXTENDED_ICONS_LIFESTYLE: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_MEDIA (const)

Import: `import { MK_EXTENDED_ICONS_MEDIA } from '@mk-kit/ui/icon/extended';`

`media` subset of `MK_EXTENDED_ICONS` (14 icons).

```ts
const MK_EXTENDED_ICONS_MEDIA: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_NAVIGATION (const)

Import: `import { MK_EXTENDED_ICONS_NAVIGATION } from '@mk-kit/ui/icon/extended';`

`navigation` subset of `MK_EXTENDED_ICONS` (34 icons).

```ts
const MK_EXTENDED_ICONS_NAVIGATION: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_PEOPLE (const)

Import: `import { MK_EXTENDED_ICONS_PEOPLE } from '@mk-kit/ui/icon/extended';`

`people` subset of `MK_EXTENDED_ICONS` (11 icons).

```ts
const MK_EXTENDED_ICONS_PEOPLE: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_SECURITY (const)

Import: `import { MK_EXTENDED_ICONS_SECURITY } from '@mk-kit/ui/icon/extended';`

`security` subset of `MK_EXTENDED_ICONS` (5 icons).

```ts
const MK_EXTENDED_ICONS_SECURITY: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_STATUS (const)

Import: `import { MK_EXTENDED_ICONS_STATUS } from '@mk-kit/ui/icon/extended';`

`status` subset of `MK_EXTENDED_ICONS` (20 icons).

```ts
const MK_EXTENDED_ICONS_STATUS: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_TIME (const)

Import: `import { MK_EXTENDED_ICONS_TIME } from '@mk-kit/ui/icon/extended';`

`time` subset of `MK_EXTENDED_ICONS` (8 icons).

```ts
const MK_EXTENDED_ICONS_TIME: Readonly<Record<string, string>>;
```

### MK_EXTENDED_ICONS_TRAVEL (const)

Import: `import { MK_EXTENDED_ICONS_TRAVEL } from '@mk-kit/ui/icon/extended';`

`travel` subset of `MK_EXTENDED_ICONS` (9 icons).

```ts
const MK_EXTENDED_ICONS_TRAVEL: Readonly<Record<string, string>>;
```

## @mk-kit/ui/chip

2 exports. `import { … } from '@mk-kit/ui/chip';`

### MkChip (component)

Selector: `mk-chip`

Docs: https://mk-kit.dev/components/badges-avatars

Import: `import { MkChip } from '@mk-kit/ui/chip';`

Chip — an interactive, optionally removable/selectable token. Use it for
filters, active selections or editable input tokens. For a purely decorative
label use `MkTag` instead.

```html
<mk-chip removable (removed)="drop(item)">{{ item.name }}</mk-chip>
<mk-chip selectable [(selected)]="active" tone="primary">Filter</mk-chip>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `MkTone` | `'neutral'` | Semantic color tone. |
| `variant` | `MkChipVariant` | `'soft'` | Visual treatment. |
| `size` | `MkSize` | `'md'` | Size scale. |
| `selectable` | `boolean` | `false` | Make the chip toggle a selected state on click / Enter / Space. |
| `removable` | `boolean` | `false` | Show a trailing remove button and enable Delete/Backspace removal. |
| `disabled` | `boolean` | `false` | Disable all interaction. |
| `removeLabel` | `string` | `this.i18n.remove` | Accessible label for the remove button. |
| `selected` (two-way) | `boolean` | `false` | Two-way selected state (only meaningful when `selectable`). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `selectedChange` | `boolean` | Emits when `selected` changes (two-way binding). |
| `removed` | `void` | Emitted when the chip is removed via the button or Delete/Backspace. |

### MkChipVariant (type)

Import: `import { MkChipVariant } from '@mk-kit/ui/chip';`

Visual treatment for a `MkChip`.

```ts
type MkChipVariant = 'solid' | 'soft' | 'outline';
```

## @mk-kit/ui/checkbox

1 exports. `import { … } from '@mk-kit/ui/checkbox';`

### MkCheckbox (component)

Selector: `mk-checkbox` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/toggles

Import: `import { MkCheckbox } from '@mk-kit/ui/checkbox';`

Checkbox — a themed checkbox built on a visually-hidden native
`input[type=checkbox]` (so keyboard + form semantics are native) with a
custom box. Supports an `indeterminate` state and projects its label.

Implements `ControlValueAccessor` with a two-way `checked` model, so it works
with `[(ngModel)]`, reactive forms and `[(checked)]`.

```html
<mk-checkbox [(ngModel)]="accepted">Accept terms</mk-checkbox>
<mk-checkbox [(checked)]="all" [indeterminate]="some()" tone="success">
  Select all
</mk-checkbox>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` (two-way) | `boolean` | `false` | Two-way checked state. |
| `indeterminate` (two-way) | `boolean` | `false` | Two-way indeterminate ("mixed") state; cleared when the user toggles. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). |
| `size` | `MkSize` | `'md'` | Control size. |
| `tone` | `MkTone` | `'primary'` | Semantic color tone for the checked box. |
| `aria-label` | `string` | `''` | Accessible label when no text content is projected. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `checkedChange` | `boolean` | Emits when `checked` changes (two-way binding). |
| `indeterminateChange` | `boolean` | Emits when `indeterminate` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `required` for an unchecked box when `[required]` is set, so `required` on the element behaves like `Validators.requiredTrue`. |

## @mk-kit/ui/button

1 exports. `import { … } from '@mk-kit/ui/button';`

### MkButton (component)

Selector: `button[mkButton], a[mkButton]`

Docs: https://mk-kit.dev/components/buttons

Import: `import { MkButton } from '@mk-kit/ui/button';`

Button — enhances a native `<button>` or `<a>` so semantics and keyboard
behaviour come for free. Fully themed via `--mk-*` tokens.

```html
<button mkButton tone="primary">Save</button>
<button mkButton variant="outline" tone="danger" [loading]="saving()">Delete</button>
<a mkButton variant="ghost" href="/docs">Docs</a>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `MkVariant` | `'solid'` | Visual treatment. |
| `tone` | `MkTone` | `'primary'` | Semantic color tone. |
| `size` | `MkSize` | `'md'` | Control size. |
| `loading` | `boolean` | `false` | Shows a spinner and blocks interaction without collapsing layout. |
| `fullWidth` | `boolean` | `false` | Stretch to fill the container width. |
| `iconOnly` | `boolean` | `false` | Square, icon-only button (ensure an `aria-label` is provided). |
| `disabled` | `boolean` | `false` | Disable the button (native `disabled` for `<button>`, aria for `<a>`). |

## @mk-kit/ui/directives

43 exports. `import { … } from '@mk-kit/ui/directives';`

### MkAutofocus (directive)

Selector: `[mkAutofocus]`

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkAutofocus } from '@mk-kit/ui/directives';`

Focuses the host element once it renders. Handy for dialogs, drawers and
newly-revealed forms. Disable conditionally with `[mkAutofocus]="cond"`.

```html
<input mkInput mkAutofocus />
<input mkInput [mkAutofocus]="isEditing()" [mkAutofocusDelay]="100" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkAutofocus` | `boolean` | `true` | Whether to focus. Bare `mkAutofocus` = true. |
| `mkAutofocusDelay` | `number` | `0` | Delay before focusing, in ms (e.g. to wait out an entrance animation). |

### MkAutosize (directive)

Selector: `textarea[mkAutosize]`

Docs: https://mk-kit.dev/components/text-inputs

Import: `import { MkAutosize } from '@mk-kit/ui/directives';`

Grows a `<textarea>` to fit its content, between `minRows` and `maxRows`
(0 = unbounded). Resizes on input and when the bound value changes.

```html
<textarea mkInput mkAutosize [mkAutosizeMaxRows]="8" [(ngModel)]="note"></textarea>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkAutosizeMinRows` | `number` | `1` | Minimum height in rows. |
| `mkAutosizeMaxRows` | `number` | `0` | Maximum height in rows before scrolling (0 = unbounded). |
| `mkAutosizeValue` | `unknown` | `undefined` | Bind the textarea's value so programmatic changes trigger a resize. |

Methods:

| Signature | Description |
| --- | --- |
| `resize(): void` | Recompute the textarea height from its content. |

### MkCan (directive)

Selector: `[mkCan]`

Import: `import { MkCan } from '@mk-kit/ui/directives';`

Structural directive that renders its template only while the app's
`MkPermissionPolicy` grants the given permission. With a
signal-based policy the check is live — the view is created and destroyed
as permissions change. When no policy is provided, everything is granted.

```html
<button *mkCan="'posts.delete'" (click)="remove()">Delete</button>

<!-- With a fallback template, like *ngIf's else: -->
<section *mkCan="'billing.view'; else locked">…</section>
<ng-template #locked><mk-empty-state title="No access" /></ng-template>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkCan` (required) | `string` |  | The permission key to check, e.g. `'posts.delete'`. |
| `mkCanElse` | `TemplateRef<unknown> \| null` | `null` | Template rendered while the permission is denied (`; else ref`). |

### MkCanDisable (directive)

Selector: `[mkCanDisable]`

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkCanDisable } from '@mk-kit/ui/directives';`

Disables the host while the app's `MkPermissionPolicy` denies the
given permission — the "keep it visible but inert" alternative to `*mkCan`
for buttons, inputs and menu items.

While denied, the host gets `aria-disabled="true"`, and — when the element
supports it (button, input, select, textarea, fieldset…) — its native
`disabled` property is set too. Non-disableable elements (links, custom
menu items) get `aria-disabled` only; pair it with CSS / a click guard as
needed. The directive owns the disabled state: it also re-enables the host
when the permission is granted. With a signal-based policy the state flips
live; with no policy provided, everything is granted.

```html
<button [mkCanDisable]="'posts.delete'" (click)="remove()">Delete</button>
<a [mkCanDisable]="'billing.view'" routerLink="/billing">Billing</a>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkCanDisable` (required) | `string` |  | The permission key to check, e.g. `'posts.delete'`. |

### MkCannot (directive)

Selector: `[mkCannot]`

Import: `import { MkCannot } from '@mk-kit/ui/directives';`

The negation of `MkCan`: renders its template only while the
permission is **denied** — for upsell hints, "ask an admin" notes and the
like. With no policy provided everything is granted, so `*mkCannot`
renders nothing.

```html
<p *mkCannot="'reports.export'">Exporting requires an admin role.</p>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkCannot` (required) | `string` |  | The permission key to check. |
| `mkCannotElse` | `TemplateRef<unknown> \| null` | `null` | Template rendered while the permission is granted (`; else ref`). |

### MkClickOutside (directive)

Selector: `[mkClickOutside]` · exportAs: `mkClickOutside`

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkClickOutside } from '@mk-kit/ui/directives';`

Emits when a pointer press lands outside the host element — the building block
for dismissing menus, popovers and custom dropdowns. Listens on the document
in the capture phase so it fires before the target handles the event.

```html
<div class="panel" (mkClickOutside)="close()">…</div>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkClickOutsideEnabled` | `boolean` | `true` | Disable the listener without removing the directive. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `mkClickOutside` | `PointerEvent` | Emits the originating event when a pointerdown occurs outside the host. |

### MkCopyToClipboard (directive)

Selector: `[mkCopyToClipboard]` · exportAs: `mkCopyToClipboard`

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkCopyToClipboard } from '@mk-kit/ui/directives';`

Copies text to the clipboard when the host is clicked. Emits `(copied)` on
success and `(copyFailed)` on error, and exposes a transient `copied` signal
(via `exportAs`) so a template can show a "Copied!" state without extra code.

```html
<button mkButton [mkCopyToClipboard]="token" #c="mkCopyToClipboard">
  {{ c.justCopied() ? 'Copied!' : 'Copy' }}
</button>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkCopyToClipboard` (required) | `string` |  | The text to copy. |
| `mkCopyFeedbackDuration` | `number` | `1500` | How long (ms) the `copied` signal stays true after a successful copy. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `copied` | `string` | Emits the copied text on success. |
| `copyFailed` | `unknown` | Emits the error on failure. |

Methods:

| Signature | Description |
| --- | --- |
| `copy(): Promise<void>` | Copy the text now. Bound to the host click, but callable directly too. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `justCopied` | `Signal<boolean>` | True for `feedbackDuration` ms after a successful copy. |

### MkField (directive)

Selector: `[mkField]`

Docs: https://mk-kit.dev/components/text-inputs

Import: `import { MkField } from '@mk-kit/ui/directives';`

Field — applies the semantic mobile-keyboard and autofill attribute bundle
for a kind of field, so you never again ship an email input that iOS
capitalises or an address input the browser can't autofill.

It sets `type`, `inputmode`, `autocomplete`, `autocapitalize`, `autocorrect`,
`spellcheck` and `enterkeyhint` (see `MK_FIELD_PRESETS`) and nothing
else — no styling, no value handling — so it composes with `mkInput`,
`mk-form-field`, `[(ngModel)]` and reactive forms untouched.

```html
<input mkInput mkField="email" formControlName="email" />
<input mkInput mkField="street" formControlName="street" />
<input mkInput [mkField]="isCompany() ? 'organization' : 'name'" />
```

## Precedence

A **static** attribute you write on the element wins: the directive reads the
seven attributes once at construction (before any host binding has run) and
keeps whatever was already there, filling in only what you left out. So
`<input mkField="username" type="password" />` stays a password field but
still gets `autocomplete="username"`, `autocapitalize="off"`, …

A **template binding** for the same attribute (`[attr.autocomplete]="…"`)
does *not* win — Angular applies directive host bindings after template
bindings, so the preset overwrites it. Use a static attribute to override, or
drop `mkField` and set the bundle yourself.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkField` (required) | `MkFieldKind` |  | Which kind of field this is. |

### MkHotkey (directive)

Selector: `[mkHotkey]` · exportAs: `mkHotkey`

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkHotkey } from '@mk-kit/ui/directives';`

`[mkHotkey]` — declaratively bind a keyboard shortcut to a host element.

When the combo fires, a `<button>` or `<a>` host is `click()`ed; any other
host emits `(mkHotkeyPressed)`. Registration is scoped to the element's
lifetime (auto-unregistered on destroy) via `MkHotkeysService`.

```html
<button mkHotkey="mod+s" (click)="save()">Save</button>
<div mkHotkey="?" (mkHotkeyPressed)="showHelp()">…</div>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkHotkey` (required) | `string` |  | The combo (or space-separated chord) to bind, e.g. `mod+k`, `g i`, `?`. |
| `mkHotkeyAllowInInput` | `boolean` | `false` | Fire even while an editable field is focused. |
| `mkHotkeyPreventDefault` | `boolean` | `true` | Call `preventDefault()` when the hotkey fires. Defaults to `true`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `mkHotkeyPressed` | `KeyboardEvent` | Emitted when the hotkey fires and the host is not a button/link. |

### MkInfiniteScroll (directive)

Selector: `[mkInfiniteScroll]` · exportAs: `mkInfiniteScroll`

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkInfiniteScroll } from '@mk-kit/ui/directives';`

InfiniteScroll — emits `(mkInfiniteScroll)` when the host scroll container is
scrolled within `distance` px of its bottom, so a list can load its next
page. Apply it to the scrollable element (`overflow: auto`). It fires once per
approach and re-arms after you scroll back up past the threshold, so a single
gesture never triggers repeated loads. Set `disabled` while a page is loading
or once everything is loaded.

```html
<div class="feed" mkInfiniteScroll [disabled]="loading() || done()"
     (mkInfiniteScroll)="loadMore()">

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `distance` | `number` | `200` | Distance (px) from the bottom at which the output fires. |
| `disabled` | `boolean` | `false` | Pause firing (e.g. while a page is loading or all items are loaded). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `mkInfiniteScroll` | `void` | Emitted when the host is scrolled near its bottom. |

### MkIntersect (directive)

Selector: `[mkIntersect]` · exportAs: `mkIntersect`

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkIntersect } from '@mk-kit/ui/directives';`

Intersect — a thin `IntersectionObserver` wrapper. Emits `(mkIntersect)` with
the host's visibility whenever it enters or leaves the viewport (or `root`),
and exposes an `intersecting` signal via `exportAs`. Set `once` to fire a
single time and disconnect — the primitive for reveal-on-scroll animations
and lazy loading.

```html
<img [attr.src]="loaded() ? src : null" mkIntersect once
     (mkIntersect)="loaded.set(true)" />

<div mkIntersect #io="mkIntersect" [class.in-view]="io.intersecting()">…</div>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `HTMLElement \| null` | `null` | Element used as the viewport for the check (defaults to the browser one). |
| `rootMargin` | `string` | `'0px'` | Margin grown/shrunk around the root before computing intersection. |
| `threshold` | `number \| number[]` | `0` | Visibility ratio(s) at which the observer fires. |
| `once` | `boolean` | `false` | Emit the first time the host becomes visible, then disconnect. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `mkIntersect` | `boolean` | Emits the host's `isIntersecting` state on every change. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `intersecting` | `WritableSignal<boolean>` | The current visibility, also readable via `exportAs`. |

### MkMask (directive)

Selector: `[mkMask]` · exportAs: `mkMask`

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkMask } from '@mk-kit/ui/directives';`

Mask — formats an `<input>` as the user types against a token pattern
(phone, card, date, custom). Apply it to any text input; read the raw value
via `(unmaskedChange)` (or the exported `unmasked` getter) and the formatted
value via `(maskedChange)`.

```html
<input mkInput mkMask="(000) 000-0000" (unmaskedChange)="phone.set($event)" />
<input mkInput mkMask="0000 0000 0000 0000" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkMask` (required) | `string` |  | The mask pattern (token string). |
| `mkMaskInputmode` | `string \| null` | `null` | Override the derived `inputmode` (`numeric` for digit-only masks). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `maskedChange` | `string` | The formatted value, on every change. |
| `unmaskedChange` | `string` | The raw value (token characters only), on every change. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | The current formatted value. |
| `unmasked` | `string` | The current raw value (token characters only). |

### MkRipple (directive)

Selector: `[mkRipple]`

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkRipple } from '@mk-kit/ui/directives';`

Ripple — a Material-style touch ripple that expands from the pointer on press.
Apply it to any pressable surface (button, list item, card). The directive
makes the host a positioned, clipping container and paints a short-lived wave;
it respects `prefers-reduced-motion`.

```html
<button mkRipple>Save</button>
<li mkRipple mkRippleColor="var(--mk-primary)">Item</li>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkRippleColor` | `string` | `''` | Wave colour (any CSS colour). Defaults to the host's `currentColor`. |
| `mkRippleCentered` | `boolean` | `false` | Start every ripple from the centre instead of the pointer. |
| `mkRippleDisabled` | `boolean` | `false` | Turn the effect off. |

### MkScrollspy (directive)

Selector: `[mkScrollspy]` · exportAs: `mkScrollspy`

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkScrollspy } from '@mk-kit/ui/directives';`

Scrollspy — tracks which section is currently in view and exposes its `id`,
so a table of contents / "on this page" nav can highlight the active link.

Apply it to any element (typically the nav) and point `mkScrollspy` at a CSS
selector matching the section elements to watch (each needs an `id`). Read the
active id via the exported instance, or bind `(activeChange)`:

```html
<nav mkScrollspy="main :is(h2, h3)[id]" #spy="mkScrollspy">
  <a href="#intro" [class.is-active]="spy.activeId() === 'intro'">Intro</a>
  …
</nav>
```

A section activates once its top passes `offset` px below the top of the
scroll root (default the viewport). When scrolling through a gap between
sections the previous one stays active until the next crosses the line.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkScrollspy` (required) | `string` |  | CSS selector for the section elements to track (queried within `root`). |
| `root` | `HTMLElement \| null` | `null` | Scroll container. Sections are queried inside it and its top edge is the activation reference. Defaults to the whole document / viewport. |
| `offset` | `number` | `96` | Distance (px) below the scroll root's top at which a section becomes active. Raise it to account for a sticky header. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `activeChange` | `string \| null` | Emitted whenever the active section changes. |

Methods:

| Signature | Description |
| --- | --- |
| `refresh(): void` | Re-evaluate the active section (call after sections change). |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `activeId` | `WritableSignal<string \| null>` | The id of the currently active section (`null` before the first one). |

### MkCurrencyPipe (pipe)

Pipe name: `mkCurrency` · `transform(value: number | string | null | undefined, currency?: string | null, options?: MkCurrencyOptions): string`

Import: `import { MkCurrencyPipe } from '@mk-kit/ui/directives';`

`mkCurrency` — format a number as money with `Intl.NumberFormat`, honouring
the locale and default currency from `provideMkI18n({ locale, currency })`.
No Angular locale data is needed. Pure: `null`, `undefined`, `''` and
non-numeric input render as `''`.

```html
{{ 1234.5 | mkCurrency }}                                <!-- $1,234.50 (i18n currency, default USD) -->
{{ 1234.5 | mkCurrency:'EUR' }}                          <!-- €1,234.50 -->
{{ 1234.5 | mkCurrency:'PLN':{ locale: 'pl-PL' } }}      <!-- 1234,50 zł -->
{{ 1234567 | mkCurrency:'USD':{ notation: 'compact' } }} <!-- $1.2M -->
{{ total() | mkCurrency:'GBP':{ signDisplay: 'always' } }} <!-- signals work as-is -->
```

### MkFileSizePipe (pipe)

Pipe name: `mkFileSize` · `transform(value: number | string | null | undefined, options?: MkFileSizeOptions): string`

Import: `import { MkFileSizePipe } from '@mk-kit/ui/directives';`

`mkFileSize` — bytes → a human-readable size such as `1.2 MB`, with the
number formatted by `Intl.NumberFormat` in the `provideMkI18n` locale.
Pure: `null`, `undefined`, `''` and non-numeric input render as `''`.

```html
{{ 1_234_567 | mkFileSize }}                        <!-- 1.2 MB -->
{{ 1_234_567 | mkFileSize:{ base: 'binary' } }}     <!-- 1.2 MiB -->
{{ 1_234_567 | mkFileSize:{ digits: 2, locale: 'de' } }} <!-- 1,23 MB -->
{{ 512 | mkFileSize }}                              <!-- 512 B -->
```

### MkInitialsPipe (pipe)

Pipe name: `mkInitials` · `transform(value: string | null | undefined, max?: number): string`

Import: `import { MkInitialsPipe } from '@mk-kit/ui/directives';`

`mkInitials` — "Ada Lovelace" → "AL", the same rule `mk-avatar` uses for
its fallback: first letter of the first and last word, upper-cased. A
single word yields its first `max` letters ("Ada" → "AD"); more than two
words with `max` > 2 take one letter per word from the start ("Jean
Luc Picard" with `max: 3` → "JLP"). Leading/trailing/duplicate whitespace
is ignored, and grapheme-aware slicing keeps emoji and accents intact.
Pure: `null`, `undefined` and blank input render as `''`.

```html
{{ user.name | mkInitials }}      <!-- Grace Hopper → GH -->
{{ user.name | mkInitials:1 }}    <!-- Grace Hopper → G -->
{{ 'Jean Luc Picard' | mkInitials:3 }} <!-- JLP -->
```

### MkPluralizePipe (pipe)

Pipe name: `mkPluralize` · `transform(value: number | string | null | undefined, singular: string | MkPluralForms, plural?: string | null, options?: MkPluralizeOptions): string`

Import: `import { MkPluralizePipe } from '@mk-kit/ui/directives';`

`mkPluralize` — pick the right word for a count using the locale's plural
rules (`Intl.PluralRules`), optionally prefixed with the formatted count.
The English shorthand takes a singular and an optional plural (default
`singular + 's'`); other languages pass a `MkPluralForms` map.
Pure: `null`, `undefined`, `''` and non-numeric counts render as `''`.

```html
{{ count | mkPluralize:'item' }}                 <!-- 1 item / 3 items -->
{{ count | mkPluralize:'entry':'entries' }}      <!-- 1 entry / 2 entries -->
{{ count | mkPluralize:'file':null:{ withCount: false } }} <!-- files -->
{{ n | mkPluralize:{ one: 'plik', few: 'pliki', many: 'plików', other: 'pliku' }:null:{ locale: 'pl' } }}
```

### MkRelativeTimePipe (pipe)

Pipe name: `mkRelativeTime` · `transform(value: Date | number | string | null | undefined, nowOrOptions?: Date | number | string | MkRelativeTimeOptions | null, options?: MkRelativeTimeOptions): string`

Import: `import { MkRelativeTimePipe } from '@mk-kit/ui/directives';`

`mkRelativeTime` — "3 minutes ago" / "in 2 days" / "yesterday" from a
`Date`, timestamp or ISO string, via `Intl.RelativeTimeFormat` in the
`provideMkI18n` locale (no Angular locale data). Pure: `null`, `undefined`
and unparsable input render as `''`.

The pipe picks the largest unit whose magnitude is at least 1 (seconds →
minutes → hours → days → weeks → months → years) and rounds. Pass `now`
for deterministic output in tests, or bind a ticking signal to keep a
list live — a pure pipe only re-runs when an argument changes. The second
argument is either that `now` or the options object, so options alone
need no `null` placeholder; the three-argument form (`now`, then options)
works too:

```html
{{ comment.createdAt | mkRelativeTime }}                    <!-- 3 minutes ago -->
{{ due | mkRelativeTime:now() }}                            <!-- in 2 days (now() ticks) -->
{{ due | mkRelativeTime:{ style: 'short' } }}               <!-- in 2 days -->
{{ ts | mkRelativeTime:{ locale: 'pl', numeric: 'always' } }} <!-- 3 minuty temu -->
{{ due | mkRelativeTime:now():{ style: 'short' } }}         <!-- in 2 days (ticking) -->
```

### MkTruncatePipe (pipe)

Pipe name: `mkTruncate` · `transform(value: string | null | undefined, length?: number, options?: MkTruncateOptions): string`

Import: `import { MkTruncatePipe } from '@mk-kit/ui/directives';`

`mkTruncate` — shorten text to `length` characters and append an ellipsis.
The ellipsis counts toward the limit, so the output never exceeds
`length` characters; counting is grapheme-aware (emoji and accented
letters are one character). Text that already fits is returned as-is.
Pure: `null` and `undefined` render as `''`.

```html
{{ post.body | mkTruncate:80 }}                          <!-- hard cut at 80 -->
{{ post.body | mkTruncate:80:{ wordBoundary: true } }}   <!-- cut at the last space -->
{{ hash | mkTruncate:12:{ ellipsis: '...' } }}
```

### MkHistoryService (service)

Docs: https://mk-kit.dev/core-services

Import: `import { MkHistoryService } from '@mk-kit/ui/directives';`

MkHistoryService — the app-wide `MkHistoryStack` singleton. Inject it
anywhere; call `MkHistoryStack.createScope` for an isolated local
stack, or wire `mod+z` / `mod+shift+z` / `mod+y` with
`registerHistoryHotkeys`.

### Recipe — undoable `mk-table` cell edits
Wire the table's `(cellEdit)` output so each saved cell becomes one
undoable step. Apply the edit yourself first (`push()` records an action
that already happened), and match rows by a stable id — the row object is
replaced by the immutable update:

```ts
// <mk-table [rows]="rows()" [columns]="columns" (cellEdit)="onCellEdit($event)" />
private readonly history = inject(MkHistoryService);
readonly rows = signal<Order[]>([...]);

onCellEdit(edit: MkCellEdit<Order>): void {
  const previous = edit.row[edit.key as keyof Order];
  const apply = (value: unknown) =>
    this.rows.update((rows) =>
      rows.map((r) => (r.id === edit.row.id ? { ...r, [edit.key]: value } : r)),
    );
  apply(edit.value); // first execution is the caller's job
  this.history.push({
    label: `Edit ${edit.key}`,
    undo: () => apply(previous),
    redo: () => apply(edit.value),
  });
}
```

Undoing replays the old value through the same `apply` function; if your
change pipeline re-emits into `onCellEdit` during that replay, the
re-entrancy guard drops the spurious `push()` (see `MkHistoryStack`).

### MkHotkeysService (service)

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkHotkeysService } from '@mk-kit/ui/directives';`

MkHotkeysService — app-wide keyboard shortcuts. Register a combo string and a
handler; a single `keydown` listener (attached lazily on the first
registration, browser only) dispatches to every match.

Supports single combos (`'mod+k'`, `'ctrl+shift+p'`, `'?'`) and simple
two-step chords (`'g i'`). By default hotkeys are ignored while an editable
field is focused — pass `allowInInput` to opt in per registration.

```ts
const off = hotkeys.register('mod+k', (e) => openPalette(), { preventDefault: true });
// …later
off();
```

Methods:

| Signature | Description |
| --- | --- |
| `register(combo: string, handler: (e: KeyboardEvent) => void, options?: MkHotkeyOptions): () => void` | Register `combo` → `handler`. Returns a disposer that unregisters it. `combo` may be a single combo or a space-separated two-step chord. |
| `unregisterAll(): void` | Remove every registration and detach the listener. |

### MkHistoryStack (class)

Import: `import { MkHistoryStack } from '@mk-kit/ui/directives';`

MkHistoryStack — a pure, signal-based, linear undo/redo command stack with
no Angular DI involved. Instantiate it directly for a local editing session
(a dialog, a canvas, a form wizard), or use the app-wide singleton
`MkHistoryService`.

```ts
const stack = new MkHistoryStack();
deleteRow(row);                                  // 1. do the work yourself
stack.push({                                     // 2. record how to revert/redo it
  label: 'Delete row',
  undo: () => insertRow(row),
  redo: () => deleteRow(row),
});
stack.undo();                                    // row is back
```

### Linear history
`push()` clears the redo branch — after undoing twice and pushing a new
entry, the two undone entries are gone (the standard editor model).

### ⚠️ Re-entrancy guard — the classic footgun
Pushes made **while** `undo()` or `redo()` is executing are **silently
ignored**. Naive consumers often record history from a generic change
handler (`(cellEdit)`, `valueChanges`, …); when an undo replays the old
value, that same handler fires again and would push a mirror entry,
corrupting the stack into an undo/redo ping-pong. The guard makes that
pattern safe by construction. If you need to record something new in
response to an undo, do it after `undo()` returns.

Methods:

| Signature | Description |
| --- | --- |
| `push(entry: MkHistoryEntry): void` | Record an already-performed action. Clears the redo branch and evicts the oldest entry beyond `limit`. Ignored while `undo()`/`redo()` is executing (see the re-entrancy note on the class) — inside a `batch()` the entry is collected into the composite instead. |
| `undo(): boolean` | Undo the most recent entry. Returns `false` when there is nothing to undo. |
| `redo(): boolean` | Redo the most recently undone entry. Returns `false` when there is nothing to redo. |
| `clear(): void` | Drop all entries (both branches) and any in-flight batch collection. |
| `batch<T>(label: string, work: () => T): T` | Group every `push()` made during `work()` into **one** undoable step. Undo runs the children in reverse order; redo runs them forward. Nested `batch()` calls flatten into the outermost batch (its label wins). An empty batch records nothing. Returns `work()`'s result; if `work()` throws, entries pushed before the throw are still committed. |
| `createScope(): MkHistoryStack` | Create an **independent** stack with the same API — e.g. for a dialog's local editing session that should not pollute the app-wide history. Discard it (or `clear()` it) when the session ends. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `canUndo` | `Signal<boolean>` | True when at least one entry can be undone. |
| `canRedo` | `Signal<boolean>` | True when at least one undone entry can be redone. |
| `undoLabel` | `Signal<string \| null>` | Label of the entry `undo()` would revert, or `null` ("Undo *Delete row*"). |
| `redoLabel` | `Signal<string \| null>` | Label of the entry `redo()` would re-apply, or `null`. |
| `size` | `Signal<number>` | Number of undoable entries currently on the stack. |
| `limit` | `number` | Maximum number of undoable entries kept (default `100`). When exceeded the **oldest** entries are dropped. Settable at any time; lowering it trims the stack immediately. Values below 1 are clamped to 1. |

### MkPermissionPolicy (class)

Docs: https://mk-kit.dev/components/utilities

Import: `import { MkPermissionPolicy } from '@mk-kit/ui/directives';`

Permission policy — the contract the permission directives (`*mkCan`,
`*mkCannot`, `[mkCanDisable]`) check against. Provide an implementation
once at bootstrap; the directives inject it optionally and, when no policy
is provided at all, treat every permission as **granted** — an app that
never wires permissions must not have its whole UI hidden.

`can` may return a plain `boolean` (static role checks) or a
`Signal<boolean>` (live permissions). The directives normalise both, and a
signal-returning policy re-evaluates reactively: views appear/disappear and
controls enable/disable the moment the underlying permissions change.

```ts
// A signal-based policy fed from an auth service:

Methods:

| Signature | Description |
| --- | --- |
| `can(permission: string): boolean \| Signal<boolean>` | Whether the current user holds `permission`. Return a `Signal<boolean>` to make the verdict live; a plain boolean is treated as static. |

### mkApplyMask (function)

Import: `import { mkApplyMask } from '@mk-kit/ui/directives';`

Format `value` against a mask `pattern`. Pattern tokens: `0` = digit,
`A` = letter, `*` = alphanumeric; any other character is a literal that is
inserted automatically. Characters that don't fit the current token are
skipped, so pasted / mistyped input is coerced into shape.

Returns the `masked` (display) string and the `unmasked` string (only the
token characters — the value you usually store).

```ts
function mkApplyMask(value: string, pattern: string): MkMaskResult
```

### mkMaskCaret (function)

Import: `import { mkMaskCaret } from '@mk-kit/ui/directives';`

Compute where the caret belongs after re-masking: after the same number of
value (alphanumeric) characters the caret used to sit behind, absorbing any
literal(s) that immediately follow — so typing "1" in "(0)" lands the caret
after the "(". Shared by `MkMask` and the masked form controls.

```ts
function mkMaskCaret(oldValue: string, oldCaret: number, masked: string): number
```

### mkMatchesHotkey (function)

Import: `import { mkMatchesHotkey } from '@mk-kit/ui/directives';`

Does a `keydown` event satisfy a hotkey? `combo` may be a raw string (parsed
on the fly) or an already-parsed `MkParsedHotkey`.

The key is compared case-insensitively; modifier flags must match exactly.
`mod` resolves to Meta on macOS and Ctrl elsewhere. Shift is not enforced for
symbol keys (e.g. `'?'`), whose shifted state varies by keyboard layout.

```ts
function mkMatchesHotkey(event: KeyboardEvent, combo: string | MkParsedHotkey): boolean
```

### mkParseHotkey (function)

Import: `import { mkParseHotkey } from '@mk-kit/ui/directives';`

Parse a single hotkey combo (e.g. `'mod+k'`, `'ctrl+shift+p'`, `'?'`) into a
structured `MkParsedHotkey`. Tokens are joined by `+`; the last
non-modifier token is the trigger key. Pure and SSR-safe.

For a chord (space-separated sequence like `'g i'`), split on whitespace and
parse each step — `MkHotkeysService` does this for you.

```ts
function mkParseHotkey(combo: string): MkParsedHotkey
```

### mkPermissionGranted (function)

Import: `import { mkPermissionGranted } from '@mk-kit/ui/directives';`

Resolve a policy verdict to a boolean, unwrapping signal-based results.
Call it inside a reactive context (`computed` / `effect`) so a
signal-returning policy stays live. A missing policy grants everything.

```ts
function mkPermissionGranted(policy: MkPermissionPolicy | null, permission: string): boolean
```

### registerHistoryHotkeys (function)

Import: `import { registerHistoryHotkeys } from '@mk-kit/ui/directives';`

Opt-in helper wiring the standard editor shortcuts to a history stack
through `MkHotkeysService`:

- `mod+z` → `undo()`
- `mod+shift+z` **and** `mod+y` → `redo()`

Must be called in an **injection context** (constructor, field initializer,
or `runInInjectionContext`). Nothing is registered automatically — apps own
their shortcuts and call this where (and if) they want them:

```ts
export class AppShell {
  private readonly disposeHistoryKeys = registerHistoryHotkeys();
}
```

Pass a specific stack (e.g. a `createScope()` stack for a dialog) to bind
the shortcuts to it instead of the app-wide `MkHistoryService`.

Returns a dispose function that unregisters all three shortcuts; it is also
called automatically when the current injection context is destroyed.

Notes:
- `MkHotkeysService` ignores keydowns while an editable element
  (input/textarea/select/contentEditable) is focused, so native text-field
  undo keeps working — no extra handling needed here.
- The shortcuts register with `preventDefault` so the browser's own
  history/document undo does not fire alongside yours.

```ts
function registerHistoryHotkeys(history?: MkHistoryStack): () => void
```

### MK_FIELD_PRESETS (const)

Import: `import { MK_FIELD_PRESETS } from '@mk-kit/ui/directives';`

The attribute bundle per field kind. Exported so hosts can inspect what a
kind resolves to, or spread an entry into their own preset table.

`autocorrect` (non-standard, honoured by iOS Safari) is set to `off`
wherever `spellcheck` is `false`.

```ts
const MK_FIELD_PRESETS: Readonly<Record<MkFieldKind, Partial<Record<"type" | "inputmode" | "autocomplete" | "autocapitalize" | "autocorrect" | "spellcheck" | "enterkeyhint", string>>>>;
```

### MkCurrencyOptions (interface)

Import: `import { MkCurrencyOptions } from '@mk-kit/ui/directives';`

Options accepted by `MkCurrencyPipe`. They map onto
`Intl.NumberFormat` currency options; `locale` overrides the i18n /
runtime locale for this call only.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `locale`? | `string \| undefined` | BCP 47 locale for this call; defaults to `provideMkI18n({ locale })`, then the runtime locale. |
| `display`? | `"symbol" \| "name" \| "narrowSymbol" \| "code" \| undefined` | How the currency is shown. Default `'symbol'` (`€`, `$`, `zł`). |
| `minimumFractionDigits`? | `number \| undefined` | Fraction digits; both default to the currency's own (2 for EUR, 0 for JPY). |
| `maximumFractionDigits`? | `number \| undefined` |  |
| `signDisplay`? | `"auto" \| "never" \| "always" \| "exceptZero" \| undefined` | Sign display, e.g. `'always'` for `+€10.00` or `'exceptZero'`. |
| `notation`? | `"compact" \| "standard" \| undefined` | Compact notation for dashboards (`$1.2M`). Default `'standard'`. |
| `useGrouping`? | `boolean \| undefined` | Thousands grouping; default `true`. |

### MkFileSizeOptions (interface)

Import: `import { MkFileSizeOptions } from '@mk-kit/ui/directives';`

Options accepted by `MkFileSizePipe`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `locale`? | `string \| undefined` | BCP 47 locale for the number part (decimal separator); defaults to the i18n / runtime locale. |
| `base`? | `"decimal" \| "binary" \| undefined` | `'decimal'` (default) divides by 1000 and labels `kB MB GB …` (what operating systems and file dialogs show); `'binary'` divides by 1024 and labels `KiB MiB GiB …`. |
| `digits`? | `number \| undefined` | Maximum fraction digits. Default `1`; bytes never get fractions. |

### MkHistoryEntry (interface)

Import: `import { MkHistoryEntry } from '@mk-kit/ui/directives';`

A single undoable step recorded in an `MkHistoryStack`.

The **first** execution of an action is the caller's job — `push()` records
an action that has *already happened*. `undo()` reverts it; `redo()` applies
it again after an undo.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Human label for menus/tooltips ("Delete row", "Move card"). |
| `undo` | `(): void` | Revert the action. |
| `redo` | `(): void` | Re-apply the action after an undo. |

### MkHotkeyOptions (interface)

Import: `import { MkHotkeyOptions } from '@mk-kit/ui/directives';`

Options accepted by `MkHotkeysService.register`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `preventDefault`? | `boolean \| undefined` | Call `preventDefault()` on the event when the hotkey fires. Default `false`. |
| `allowInInput`? | `boolean \| undefined` | Also fire while a text field (text-like input/textarea/select/contentEditable) is focused. Default `false`. |

### MkMaskResult (interface)

Import: `import { MkMaskResult } from '@mk-kit/ui/directives';`

Result of applying a mask: the formatted string and its raw token chars.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `masked` | `string` |  |
| `unmasked` | `string` |  |

### MkParsedHotkey (interface)

Import: `import { MkParsedHotkey } from '@mk-kit/ui/directives';`

A single hotkey combo parsed into a normalized key + modifier flags.
Produced by `mkParseHotkey`; consumed by `mkMatchesHotkey`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `string` | The non-modifier key, lowercased and alias-normalized (e.g. `k`, `escape`, `?`). |
| `mod` | `boolean` | `mod` — Cmd on macOS, Ctrl elsewhere. |
| `ctrl` | `boolean` | The Control key. |
| `meta` | `boolean` | The Meta / Command / Windows key. |
| `alt` | `boolean` | The Alt / Option key. |
| `shift` | `boolean` | The Shift key. |

### MkPluralizeOptions (interface)

Import: `import { MkPluralizeOptions } from '@mk-kit/ui/directives';`

Options accepted by `MkPluralizePipe`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `locale`? | `string \| undefined` | BCP 47 locale for the plural rules and number; defaults to the i18n / runtime locale. |
| `withCount`? | `boolean \| undefined` | Prefix the formatted count (`"3 items"`); `false` gives just the word. Default `true`. |

### MkRelativeTimeOptions (interface)

Import: `import { MkRelativeTimeOptions } from '@mk-kit/ui/directives';`

Options accepted by `MkRelativeTimePipe`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `locale`? | `string \| undefined` | BCP 47 locale for this call; defaults to `provideMkI18n({ locale })`, then the runtime locale. |
| `numeric`? | `"auto" \| "always" \| undefined` | `'auto'` (default) uses phrases like "yesterday" / "now" where the locale has them; `'always'` sticks to "1 day ago" / "in 0 seconds". |
| `style`? | `"long" \| "short" \| "narrow" \| undefined` | Length of the unit word: `'long'` (default, "minutes"), `'short'` ("min."), `'narrow'` ("m"). |
| `maxUnit`? | `Intl.RelativeTimeFormatUnit \| undefined` | Largest unit to use. Default `'year'`; e.g. `'day'` keeps "45 days ago" instead of "1 month ago". |

### MkTruncateOptions (interface)

Import: `import { MkTruncateOptions } from '@mk-kit/ui/directives';`

Options accepted by `MkTruncatePipe`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `ellipsis`? | `string \| undefined` | Suffix appended when text is cut. Default `'…'` (a single ellipsis character). |
| `wordBoundary`? | `boolean \| undefined` | Cut at the last whitespace before the limit instead of mid-word (falls back to a hard cut when the first word alone is longer). Default `false`. |

### MkFieldKind (type)

Import: `import { MkFieldKind } from '@mk-kit/ui/directives';`

Semantic field kinds understood by `MkField`.

```ts
type MkFieldKind = | 'email' | 'tel' | 'url' | 'search' | 'numeric' | 'given-name' | 'family-name' | 'name' | 'organization' | 'street' | 'address-line1' | 'address-line2' | 'city' | 'region' | 'country' | 'postal-code' | 'username' | 'one-time-code';
```

### MkFieldPreset (type)

Import: `import { MkFieldPreset } from '@mk-kit/ui/directives';`

The attribute bundle applied for one `MkFieldKind`. Omitted = not set.

```ts
type MkFieldPreset = Partial<Record<MkFieldAttr, string>>;
```

### MkPluralForms (type)

Import: `import { MkPluralForms } from '@mk-kit/ui/directives';`

Per-category word forms for `MkPluralizePipe`, keyed by the CLDR
plural categories `Intl.PluralRules` returns. `other` is required; the
pipe falls back to it for any category you leave out.

```ts
const files: MkPluralForms = { one: 'plik', few: 'pliki', many: 'plików', other: 'pliku' };
```

```ts
type MkPluralForms = { other: string } & Partial<Record<Intl.LDMLPluralRule, string>>;
```

## @mk-kit/ui/dnd

13 exports. `import { … } from '@mk-kit/ui/dnd';`

### MkDrag (component)

Selector: `[mkDrag]` · exportAs: `mkDrag`

Docs: https://mk-kit.dev/components/drag-drop

Import: `import { MkDrag } from '@mk-kit/ui/dnd';`

Makes an item inside a `[mkDropList]` draggable — by pointer (mouse / touch /
pen) **and** by keyboard (WCAG 2.1.1). Every move is announced via
`MkLiveAnnouncer`. Which element carries the keyboard interaction
depends on the handle:

- **No handle, or a decorative one** (`<span mkDragHandle aria-hidden>`):
  the item itself is focusable and exposes `aria-roledescription="Draggable
  item"` with `role="button"` — or `role="option"` when it is an `<li>` of a
  `<ul mkDropList>`, which then becomes a labelled `listbox` (an `<li>` may
  not take the `button` role).
- **A focusable handle** (`<button mkDragHandle aria-label="…">`, or any
  handle with `tabindex`): the handle is the keyboard target and receives
  the `aria-roledescription` / `aria-pressed` / `aria-grabbed` state; the
  item stays a plain container with no role and no `tabindex`, so it can hold
  inputs, links and buttons of its own (no nested interactive controls) and
  `<li>` items keep their list semantics.

Keyboard: focus the item (or its handle) and press **Space/Enter** to pick
it up, **Arrow** keys to move it (crossing into connected lists at the ends /
across the perpendicular axis), **Space/Enter** to drop, **Escape** to cancel.

Besides lists, an item can be released on a connected `[mkDropZone]` — a
target that reports *where* it was dropped instead of an index (a timeline,
a priority band, a "focus on this" pane). Zones sit in the same keyboard
travel group as lists, in document order; while an item hovers a zone no
placeholder is shown and the zone streams `mkDropZoneMoved` events.

Touch: a swipe scrolls the page as usual — the drag only arms after a
long-press (`mkDragTouchDelay`, default 300 ms). While armed the item
gets the `mk-drag--armed` class so consumers can style the lift moment.
Mouse and pen drags start immediately, as before.

Performance: pointer moves are rAF-coalesced (one hit-test + one set of
style/DOM writes per frame) against list/item rects snapshotted when the
drag lifts, so a move never forces layout. The pending frame is flushed
synchronously on release so drops land exactly where the pointer ended.

```html
<div mkDrag [mkDragData]="row" [mkDragDisabled]="row.locked">
  <span mkDragHandle aria-hidden="true">⠿</span> {{ row.title }}
</div>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkDragData` | `T \| undefined` |  | Arbitrary payload associated with this item. |
| `mkDragDisabled` | `boolean` | `false` | Disable dragging this specific item. |
| `mkDragTouchDelay` | `number` | `300` | Long-press delay (ms) before a *touch* pointer arms the drag. Until it elapses a swipe scrolls natively; moving more than `TOUCH_SLOP` pixels abandons the pending drag. `0` arms immediately (legacy behavior). Mouse and pen are never delayed. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `element` | `HTMLElement` | The item's host element. |
| `keyboardHandle` | `Signal<MkDragHandle \| null>` | The handle that carries the keyboard drag — the first of this item's handles that is focusable on its own (a `<button mkDragHandle>`, say). `null` when the item itself is the keyboard target. |
| `disabled` | `Signal<boolean>` | Effective disabled state (item- or list-level). |

### MkDropList (component)

Selector: `[mkDropList]` · exportAs: `mkDropList`

Docs: https://mk-kit.dev/components/drag-drop

Import: `import { MkDropList } from '@mk-kit/ui/dnd';`

A drop container for reorderable `[mkDrag]` items.

- **Sort list:** a single `[mkDropList]` over an array — items reorder within it.
- **Buckets / kanban:** several `[mkDropList]`s wired together with
  `mkDropListConnectedTo` so items transfer between them (both by pointer and
  by keyboard at the ends of a list).

The array bound to `mkDropListData` is **not** mutated for you — handle
`mkDropListDropped` and call `mkMoveItemInArray` / `mkTransferArrayItem`.

Semantics follow the host element and its items, so the tree is always
valid ARIA:

- any host other than `<ul>`/`<ol>` is a `role="group"` (named by
  `mkDropListLabel`) of `role="button"` items;
- a `<ul>`/`<ol>` whose `<li mkDrag>` items all carry a *focusable*
  `[mkDragHandle]` stays a plain list — the handles are the controls;
- a `<ul>`/`<ol>` whose items are themselves the keyboard targets becomes a
  `listbox` of `option`s (an `<li>` may not be a `button`); give it a
  `mkDropListLabel`, listboxes need a name.

A `role` you set in the template is kept, and `aria-orientation` is only
exposed on roles that allow it (`listbox`, `toolbar`, `tree`, …) — the
keyboard model handles both axes regardless.

```html
<div mkDropList [mkDropListData]="todo()" mkDropListLabel="To do"
     mkDropListId="todo" [mkDropListConnectedTo]="['done']"
     (mkDropListDropped)="drop($event)">

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkDropListData` | `readonly T[]` | `[]` | The array backing the list. Bound, never mutated by the directive. |
| `mkDropListId` | `string \| undefined` |  | Stable id used to connect lists. Auto-generated when omitted. |
| `mkDropListConnectedTo` | `readonly string[]` | `[]` | Ids of other lists items may be transferred into. |
| `mkDropListLabel` | `string` | `''` | Human-readable name used in screen-reader announcements when an item is moved into this list (e.g. `"In progress"`). Falls back to the list `id` — which may be auto-generated gibberish — so set it wherever users can move items across lists by keyboard. |
| `mkDropListLabelledBy` | `string` | `''` | Id of the element that names the list (`aria-labelledby`), e.g. a visible heading. Takes precedence over `mkDropListLabel` as the accessible name; the label is still used in announcements. |
| `mkDropListOrientation` | `MkDropListOrientation` | `'vertical'` | Layout axis; controls pointer hit-testing and arrow-key direction. |
| `mkDropListDisabled` | `boolean` | `false` | Disable dropping into (and dragging out of) this list. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `mkDropListDropped` | `MkDropEvent<T>` | Fires when an item is dropped into this list (pointer or keyboard). |

Methods:

| Signature | Description |
| --- | --- |
| `size(): number` | Number of drag items currently in the list. |
| `indexOf(drag: MkDrag<any>): number` | Index of `drag` among this list's items, or -1. |
| `itemElementsExcept(exclude: MkDrag<any>): HTMLElement[]` | Host elements of this list's items, excluding `exclude`, in DOM order. |
| `setReceiving(value: boolean): void` | Toggle the "receiving" highlight (called by the active drag). |
| `emitDrop(event: MkDropEvent<any>): void` | Emit a drop into this list. Called by the active `MkDrag`. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `element` | `HTMLElement` | The list's host element (drop target bounds). |
| `id` | `Signal<string>` | Resolved id (input or generated). |
| `label` | `Signal<string>` | Announceable name: the label when set, otherwise the resolved id. |
| `role` | `Signal<string \| null>` | The role the host exposes. One set in the template wins. A `<ul>`/`<ol>` keeps its implicit `list` role (`null` — nothing is written) while every item hands the keyboard drag to a focusable handle, and becomes a `listbox` (its items `option`s) otherwise. Any other element is a `group`. |
| `connectedTo` | `Signal<readonly string[]>` | Connected-list ids, normalised to a plain array. |

### MkDropZone (component)

Selector: `[mkDropZone]` · exportAs: `mkDropZone`

Import: `import { MkDropZone } from '@mk-kit/ui/dnd';`

A drop **target** that is not a list: an item dragged out of a connected
`[mkDropList]` can be released anywhere on it, and the zone reports *where*
— client coordinates, the offset inside the zone and the 0–1 fraction along
each axis — so the consumer can turn a position into meaning: a time on a
timeline, a priority band, a "focus on this" pane, a trash can.

Nothing reorders and no placeholder is shown while an item hovers a zone;
the zone gets the `mk-drop-zone--receiving` class and a stream of
`mkDropZoneMoved` events instead. Zones and lists can overlap — the
innermost target under the pointer wins, so a column can hold three
priority bands and still accept plain drops between the bands.

Wire a zone exactly like another list: give it an id and name that id in
the source list's `mkDropListConnectedTo`.

Keyboard: a lifted item reaches zones with the arrow keys that cross lists
(Left/Right in a vertical list, Up/Down in a horizontal one) — zones sit in
the same DOM-ordered travel group as connected lists; Space/Enter drops at
the zone's centre. Every step is announced.

```html
<ul mkDropList mkDropListId="backlog" [mkDropListConnectedTo]="['now', 'rail']" …>
<section mkDropZone mkDropZoneId="now" mkDropZoneLabel="Focus now"
         (mkDropZoneDropped)="focus($event.item.mkDragData())">
<div mkDropZone mkDropZoneId="rail" mkDropZoneLabel="Today"
     (mkDropZoneMoved)="preview($event.fractionY)"
     (mkDropZoneDropped)="schedule($event.item.mkDragData(), $event.fractionY)">
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkDropZoneId` | `string \| undefined` |  | Stable id source lists name in `mkDropListConnectedTo`. Auto-generated when omitted. |
| `mkDropZoneLabel` | `string` | `''` | Human-readable name, used in screen-reader announcements when a lifted item reaches the zone ("Moved to Focus now") and as the zone's accessible name. Set it: the fallback is the id, which may be generated gibberish. |
| `mkDropZoneLabelledBy` | `string` | `''` | Id of a visible element that names the zone (`aria-labelledby`); wins over the label as the accessible name. |
| `mkDropZoneData` | `Z \| undefined` |  | Arbitrary payload handed back on every hover and drop event. |
| `mkDropZoneDisabled` | `boolean` | `false` | Disable dropping onto this zone (it leaves the travel group too). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `mkDropZoneEntered` | `MkDropZoneHover<T, Z>` | An item entered the zone (pointer or keyboard). |
| `mkDropZoneMoved` | `MkDropZoneHover<T, Z>` | The pointer moved while over the zone (one per frame, pointer only). |
| `mkDropZoneLeft` | `MkDrag<T>` | The item left the zone without dropping (moved on, or the drag was cancelled). |
| `mkDropZoneDropped` | `MkDropZoneEvent<T, Z>` | The item was released on the zone. |

Methods:

| Signature | Description |
| --- | --- |
| `setReceiving(value: boolean): void` | Toggle the "receiving" highlight (called by the active drag). |
| `emitEntered(event: MkDropZoneHover<T, Z>): void` | Called by the active `MkDrag` — not part of the consumer API. |
| `emitMoved(event: MkDropZoneHover<T, Z>): void` |  |
| `emitLeft(item: MkDrag<T>): void` |  |
| `emitDrop(event: MkDropZoneEvent<T, Z>): void` |  |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `element` | `HTMLElement` | The zone's host element (drop target bounds). |
| `id` | `Signal<string>` | Resolved id (input or generated). |
| `label` | `Signal<string>` | Announceable name: the label when set, otherwise the resolved id. |

### MkSortableList (component)

Selector: `mk-sortable-list`

Docs: https://mk-kit.dev/components/drag-drop

Import: `import { MkSortableList } from '@mk-kit/ui/dnd';`

Thin convenience wrapper over a single `[mkDropList]` for the common
"reorderable list" case. Bind `items` two-way and provide an `<ng-template>`
to render each row; drops are applied to the model for you (via
`mkMoveItemInArray`).

For connected buckets / kanban, use `[mkDropList]` + `[mkDrag]` directly.

The list renders as a named `group` of `button` items: pass `label` (or
`labelledBy` pointing at a visible heading) so screen readers say what is
being reordered — the i18n `sortableListLabel` ("Sortable list") is the
fallback.

```html
<mk-sortable-list [(items)]="rows" label="Steps">
  <ng-template let-row let-i="index">
    <span mkDragHandle aria-hidden="true">⠿</span> {{ i + 1 }}. {{ row.name }}
  </ng-template>
</mk-sortable-list>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (two-way) | `T[]` | `[]` | The ordered items (two-way). Reordered in place on drop. |
| `label` | `string \| undefined` |  | Accessible name of the list (`aria-label`), also used in the "moved into …" announcements. Defaults to the i18n `sortableListLabel`. |
| `labelledBy` | `string \| undefined` |  | Id of an element that names the list (`aria-labelledby`), e.g. a visible heading. Wins over `label` as the accessible name. |
| `orientation` | `MkDropListOrientation` | `'vertical'` | Layout axis of the list. |
| `disabled` | `boolean` | `false` | Disable reordering. |
| `trackBy` | `(index: number, item: T) => unknown` | `(_, item) => item` | `@for` tracking function. Defaults to identity (track by item). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `itemsChange` | `T[]` | Emits when `items` changes (two-way binding). |
| `sorted` | `MkDropEvent<T>` | Emitted after the model has been reordered. |

### MkDragHandle (directive)

Selector: `[mkDragHandle]` · exportAs: `mkDragHandle`

Docs: https://mk-kit.dev/components/drag-drop

Import: `import { MkDragHandle } from '@mk-kit/ui/dnd';`

Optional grip that restricts where a pointer drag of the enclosing
`[mkDrag]` may begin. Place it on the element the user should press to drag;
without any handle the whole item is draggable.

A directive (not a component), so it composes onto anything — a `<span>`,
a `<button>`, or another component's host such as `<mk-icon mkDragHandle />`.
Its look (grab cursor, muted colour, `touch-action: none`) ships as the
global `.mk-drag-handle` class in the theme stylesheet.

**Decorative grip** — a non-focusable element (`<span>`, `<mk-icon>`): the
item itself stays the keyboard target (`role="button"`, focusable), so the
grip should be `aria-hidden`:

```html
<div mkDrag [mkDragData]="row">
  <span mkDragHandle aria-hidden="true">⠿</span>
  {{ row.name }}
</div>
```

**Focusable grip** — a `<button>` (or any element with `tabindex`): the
handle becomes the keyboard target instead. The item is then a plain
container (no role, not focusable), so rows may hold inputs, links and
other buttons without nesting interactive controls, and `<li>` items keep
valid list semantics. Give it an accessible name:

```html
<li mkDrag [mkDragData]="row">
  <button type="button" mkDragHandle [attr.aria-label]="'Reorder ' + row.name">⠿</button>
  <input mkInput [(ngModel)]="row.name" />
</li>
```

Methods:

| Signature | Description |
| --- | --- |
| `isFocusable(): boolean` | Whether the handle can take keyboard focus itself — a native control (`<button>`, …), a link with `href`, or any element with a `tabindex`. A focusable handle carries the keyboard drag for its `[mkDrag]`. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `element` | `HTMLElement` | The handle's host element. |

### MkDragDropRegistry (service)

Import: `import { MkDragDropRegistry } from '@mk-kit/ui/dnd';`

Central registry of every live `[mkDropList]` on the page, keyed by id.

Connected lists (kanban "buckets") use it to resolve the sibling lists named
in `mkDropListConnectedTo`, and both pointer and keyboard dragging use it to
find the group of lists an item may travel between.

Registration is automatic — you never call this service directly; it is
documented so tooling/tests can inspect the wiring.

Methods:

| Signature | Description |
| --- | --- |
| `register(id: string, list: MkDropList<any>): void` | Register (or replace) the list published under `id`. |
| `unregister(id: string, list: MkDropList<any>): void` | Remove `list` from the registry if it is still the holder of `id`. |
| `get(id: string): MkDropList<any> \| undefined` | Look up a list by its `mkDropListId`. |
| `all(): MkDropList<any>[]` | All registered lists, in registration order. |
| `connectedGroup(list: MkDropList<any>): MkDropList<any>[]` | The ordered travel group for `list`: `list` itself plus every enabled list it is `mkDropListConnectedTo`, in registration (roughly DOM) order. Used to resolve "adjacent" lists for keyboard column-to-column movement and to hit-test the pointer against candidate targets. |
| `registerZone(id: string, zone: MkDropZone<any>): void` | Register (or replace) the zone published under `id`. |
| `unregisterZone(id: string, zone: MkDropZone<any>): void` | Remove `zone` from the registry if it is still the holder of `id`. |
| `getZone(id: string): MkDropZone<any> \| undefined` | Look up a zone by its `mkDropZoneId`. |
| `connectedZones(list: MkDropList<any>): MkDropZone<any>[]` | Every enabled zone named in `list`'s `mkDropListConnectedTo`, in registration order. |
| `travelGroup(list: MkDropList<any>): MkDropTarget[]` | The keyboard travel group for `list`: its connected lists **and** zones, in document order, so arrow keys walk targets the way they appear on screen regardless of when each registered. |

### mkMoveItemInArray (function)

Import: `import { mkMoveItemInArray } from '@mk-kit/ui/dnd';`

Move an item within a single array from `fromIndex` to `toIndex`.
Mutates and returns `array`.

```ts
mkMoveItemInArray(rows, e.previousIndex, e.currentIndex);
```

```ts
function mkMoveItemInArray<T>(array: T[], fromIndex: number, toIndex: number): T[]
```

### mkTransferArrayItem (function)

Import: `import { mkTransferArrayItem } from '@mk-kit/ui/dnd';`

Move an item from one array (`from`) to another (`to`), removing it from
`from[fromIndex]` and inserting it at `to[toIndex]`. Mutates both arrays and
returns the target (`to`) array.

```ts
mkTransferArrayItem(todo, done, e.previousIndex, e.currentIndex);
```

```ts
function mkTransferArrayItem<T>(from: T[], to: T[], fromIndex: number, toIndex: number): T[]
```

### MkDropEvent (interface)

Import: `import { MkDropEvent } from '@mk-kit/ui/dnd';`

Emitted by `[mkDropList]` (`mkDropListDropped`) when an item is dropped.

Mirrors the shape of Angular CDK's `CdkDragDrop` so the exported
`mkMoveItemInArray` / `mkTransferArrayItem` helpers can be used
exactly as their CDK counterparts:

```ts
onDrop(e: MkDropEvent) {
  if (e.previousContainer === e.container) {
    mkMoveItemInArray(e.container.mkDropListData(), e.previousIndex, e.currentIndex);
  } else {
    mkTransferArrayItem(
      e.previousContainer.mkDropListData(),
      e.container.mkDropListData(),
      e.previousIndex, e.currentIndex,
    );
  }
}
```

Members:

| Name | Type | Description |
| --- | --- | --- |
| `previousIndex` | `number` | Index of the item within `previousContainer`'s data before the drop. |
| `currentIndex` | `number` | Index the item should occupy within `container`'s data after the drop. |
| `item` | `MkDrag<T>` | The `MkDrag` directive instance that was moved. |
| `previousContainer` | `MkDropList<T>` | The list the item came from. |
| `container` | `MkDropList<T>` | The list the item was dropped into (same as `previousContainer` for a re-sort). |
| `isPointerEvent` | `boolean` | `true` for pointer (mouse/touch/pen) drops, `false` for keyboard drops. |

### MkDropZoneEvent (interface)

Import: `import { MkDropZoneEvent } from '@mk-kit/ui/dnd';`

Emitted by `[mkDropZone]` (`mkDropZoneDropped`) when an item is released on
it. Carries the same position fields as `MkDropZoneHover` plus where
the item came from — the consumer removes it from that list (or not: a
"focus on this" zone may leave the card where it is).

Members (extends `MkDropZoneHover<T, Z>`):

| Name | Type | Description |
| --- | --- | --- |
| `previousContainer` | `MkDropList<T>` | The list the item came from. |
| `previousIndex` | `number` | Index of the item within `previousContainer`'s data. |

### MkDropZoneHover (interface)

Import: `import { MkDropZoneHover } from '@mk-kit/ui/dnd';`

Where an item is over a `[mkDropZone]`, emitted on enter and on every
pointer frame (`mkDropZoneEntered` / `mkDropZoneMoved`). Keyboard entries
report the zone's centre.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `item` | `MkDrag<T>` | The `MkDrag` directive instance being dragged. |
| `zone` | `MkDropZone<Z, any>` | The zone under the pointer. |
| `x` | `number` | Pointer position in client (viewport) coordinates. |
| `y` | `number` |  |
| `offsetX` | `number` | Pointer position relative to the zone's top-left corner, in CSS pixels. |
| `offsetY` | `number` |  |
| `fractionX` | `number` | Pointer position as a 0–1 fraction of the zone's width / height (clamped). |
| `fractionY` | `number` |  |
| `isPointerEvent` | `boolean` | `true` for pointer (mouse/touch/pen) hovers, `false` for keyboard steps. |

### MkDropListOrientation (type)

Import: `import { MkDropListOrientation } from '@mk-kit/ui/dnd';`

Layout axis a drop list lays its items along.

```ts
type MkDropListOrientation = 'vertical' | 'horizontal';
```

### MkDropTarget (type)

Import: `import { MkDropTarget } from '@mk-kit/ui/dnd';`

A keyboard-reachable drop target: a connected list or a connected zone.

```ts
type MkDropTarget = MkDropList<any> | MkDropZone<any>;
```

## @mk-kit/ui/navigation

39 exports. `import { … } from '@mk-kit/ui/navigation';`

### MkAccordion (component)

Selector: `mk-accordion`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkAccordion } from '@mk-kit/ui/navigation';`

Groups `<mk-accordion-item>`s. By default only one item can be open at a
time (single-open); set `multi` to allow several. Coordinates its children
through their two-way `open` models.

```html
<mk-accordion [multi]="false">
  <mk-accordion-item header="One">…</mk-accordion-item>
  <mk-accordion-item header="Two">…</mk-accordion-item>
</mk-accordion>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `multi` | `boolean` | `false` | Allow multiple items open simultaneously. |

Methods:

| Signature | Description |
| --- | --- |
| `onItemToggle(source: MkAccordionItem, opening: boolean): void` | Called by an item just before its open state changes. |

### MkAccordionItem (component)

Selector: `mk-accordion-item`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkAccordionItem } from '@mk-kit/ui/navigation';`

A collapsible section within an `<mk-accordion>`. The header is a button that
toggles a smoothly animated body region wired with `aria-expanded` /
`aria-controls`. Open state is two-way bindable via `open`.

```html
<mk-accordion-item header="Shipping" [(open)]="shippingOpen">
  …body…
</mk-accordion-item>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `header` | `string` | `''` | Plain-text header (ignored when `[mkAccordionHeader]` is projected). |
| `disabled` | `boolean` | `false` | Disable toggling of this item. |
| `open` (two-way) | `boolean` | `false` | Whether the item is expanded (two-way). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `openChange` | `boolean` | Emits when `open` changes (two-way binding). |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `triggerId` | `string` | Stable id for the trigger button. |
| `panelId` | `string` | Stable id for the panel region. |

### MkAppShell (component)

Selector: `mk-app-shell`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkAppShell } from '@mk-kit/ui/navigation';`

Admin dashboard layout with a fixed header, a collapsible/responsive sidebar
and a main content area. On small screens the sidebar becomes a focus-trapped
off-canvas drawer with a scrim (Escape to close). Includes a skip-to-content
link for keyboard users.

```html
<mk-app-shell [(sidebarOpen)]="open" [(sidebarCollapsed)]="collapsed">
  <div mkAppHeader>
    <button mkButton iconOnly (click)="shell.toggleSidebar()">☰</button>
  </div>
  <mk-nav-list mkAppSidebar [collapsed]="collapsed()">…</mk-nav-list>
  <router-outlet />
</mk-app-shell>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `sidebarOpen` (two-way) | `boolean` | `false` | Whether the mobile drawer is open (two-way). |
| `sidebarCollapsed` (two-way) | `boolean` | `false` | Whether the desktop sidebar is collapsed to icons (two-way). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `sidebarOpenChange` | `boolean` | Emits when `sidebarOpen` changes (two-way binding). |
| `sidebarCollapsedChange` | `boolean` | Emits when `sidebarCollapsed` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `toggleSidebar(): void` | Toggle the mobile drawer open/closed. Handy for a hamburger button. |
| `openSidebar(): void` | Open the mobile drawer. |
| `closeSidebar(): void` | Close the mobile drawer. |
| `toggleCollapsed(): void` | Toggle the desktop collapsed (icon-only) state. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `isMobile` | `WritableSignal<boolean>` | True when the viewport is at/below the mobile breakpoint. |

### MkAppSwitcher (component)

Selector: `mk-app-switcher` · exportAs: `mkAppSwitcher`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkAppSwitcher } from '@mk-kit/ui/navigation';`

The "apps grid" of a family of applications: a header button that opens a
grid of links to the other apps, the current one marked. Give it the list
(`apps`) or a registry to fetch it from (`src` — JSON, either an array or
`{ apps: [...] }`), so every app of a suite shows the same switcher from one
shared file.

```html
<mk-app-shell>
  <ng-container mkAppHeader>
    <mk-app-switcher src="https://home.example.com/apps.json" current="sales" />
  </ng-container>
</mk-app-shell>
```

The registry is fetched lazily, the first time the panel opens, and once
per page. The panel is a disclosure (a labelled group of links, not a menu):
Tab moves through the tiles, arrows too, Escape closes and returns focus.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `apps` | `MkAppLink[]` | `[]` | The apps, when the host has the list. |
| `src` | `string` | `''` | A registry URL to fetch the apps from (JSON: an array or `{ apps }`). Used when `apps` is empty. |
| `current` | `string` | `''` | The app this switcher is shown in — its `id` or `url`; marked as current and listed first. |
| `label` | `string` | `''` | Accessible name of the trigger. Defaults to the i18n `appSwitcherLabel`. |
| `columns` | `number` | `3` | Tiles per row. |
| `newTab` | `boolean` | `false` | Open links in a new tab. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `openChange` | `boolean` | Emits when the panel opens or closes. |

Methods:

| Signature | Description |
| --- | --- |
| `toggle(): void` |  |
| `show(): void` |  |
| `close(restoreFocus?: boolean): void` |  |

### MkBackToTop (component)

Selector: `mk-back-to-top`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkBackToTop } from '@mk-kit/ui/navigation';`

BackToTop — a floating button that appears once the page (or a scroll target)
has scrolled past `threshold`, and smooth-scrolls back to the top on click.

```html
<mk-back-to-top [threshold]="600" />
```
Pass `[target]` to watch/scroll a specific scroll container instead of the
window.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `threshold` | `number` | `400` | Scroll distance (px) before the button appears. |
| `target` | `HTMLElement \| null` | `null` | Optional scroll container; defaults to the window. |
| `ariaLabel` | `string` | `this.i18n.backToTop` | Accessible label. |
| `smooth` | `boolean` | `true` | Smooth-scroll on click. Ignored under `prefers-reduced-motion: reduce` (programmatic `scrollTo` is not toned down by browsers, so the component falls back to an instant jump itself). |

### MkBreadcrumb (component)

Selector: `mk-breadcrumb`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkBreadcrumb } from '@mk-kit/ui/navigation';`

Breadcrumb trail. Renders `nav[aria-label="Breadcrumb"] > ol` and marks the
final `<mk-breadcrumb-item>` as the current page. The separator is drawn in
CSS and can be customised via `separator`.

```html
<mk-breadcrumb separator="›">
  <mk-breadcrumb-item href="/">Home</mk-breadcrumb-item>
  <mk-breadcrumb-item href="/users">Users</mk-breadcrumb-item>
  <mk-breadcrumb-item>Jane</mk-breadcrumb-item>
</mk-breadcrumb>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `this.i18n.breadcrumbLabel` | Accessible label for the navigation landmark. |
| `separator` | `string` | `'/'` | Separator character rendered between crumbs. |

### MkBreadcrumbItem (component)

Selector: `mk-breadcrumb-item`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkBreadcrumbItem } from '@mk-kit/ui/navigation';`

A single crumb inside `<mk-breadcrumb>`. Renders a link when `href` is set,
otherwise plain text. The last item is automatically marked
`aria-current="page"` by the parent.

```html
<mk-breadcrumb-item href="/">Home</mk-breadcrumb-item>
<mk-breadcrumb-item>Current page</mk-breadcrumb-item>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `href` | `string \| undefined` |  | Optional link target. Rendered as text when omitted or when it is last. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `last` | `WritableSignal<boolean>` | Whether this is the final crumb. Set by the parent `MkBreadcrumb`. |

### MkCommandPalette (component)

Selector: `mk-command-palette`

Docs: https://mk-kit.dev/components/command-nav

Import: `import { MkCommandPalette } from '@mk-kit/ui/navigation';`

CommandPalette — a modal ⌘K/Ctrl+K menu for fast, keyboard-first actions and
navigation. Supply a flat `commands` list (optionally grouped); the palette
filters as you type, groups results, and runs the chosen command. Implements
the ARIA combobox + listbox pattern with full keyboard support and focus
trapping.

Mount it once near your app root and bind `open` (the built-in hotkey toggles
it, or open it yourself).

```html
<mk-command-palette [(open)]="paletteOpen" [commands]="commands"
  (commandSelected)="run($event)" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (two-way) | `boolean` | `false` | Whether the palette is open (two-way). |
| `commands` | `readonly MkCommand[]` | `[]` | The commands to search and run. |
| `placeholder` | `string` | `this.i18n.commandPalettePlaceholder` | Search field placeholder. |
| `emptyMessage` | `string` | `this.i18n.noResults` | Message shown when nothing matches. |
| `hotkey` | `boolean` | `true` | Toggle open with ⌘K / Ctrl+K anywhere. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `openChange` | `boolean` | Emits when `open` changes (two-way binding). |
| `commandSelected` | `MkCommand` | Emits the chosen command (its own `run` callback also fires). |

### MkDrawer (component)

Selector: `mk-drawer`

Docs: https://mk-kit.dev/components/drawer

Import: `import { MkDrawer } from '@mk-kit/ui/navigation';`

Drawer — a declarative slide-out panel anchored to a viewport edge, driven by
a two-way `open`. Ideal for admin/CMS side panels: filters, entity details,
settings, quick-create forms. Traps focus while open, closes on backdrop
click or Escape, restores focus on close, and locks body scroll when modal.

Slots: `[mkDrawerHeader]` (extra header content), default content (body),
`[mkDrawerFooter]` (sticky footer).

```html
<button mkButton (click)="filters.set(true)">Filters</button>
<mk-drawer [(open)]="filters" side="end" heading="Filters">
  …filter form…
  <div mkDrawerFooter>
    <button mkButton variant="ghost" (click)="filters.set(false)">Close</button>
    <button mkButton (click)="apply()">Apply</button>
  </div>
</mk-drawer>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (two-way) | `boolean` | `false` | Whether the drawer is open (two-way). |
| `side` | `MkDrawerSide` | `'end'` | Viewport edge to anchor to. |
| `size` | `string` | `'20rem'` | Panel width (start/end) or height (top/bottom) — any CSS length. |
| `hasBackdrop` | `boolean` | `true` | Render a dimmed backdrop and lock body scroll (modal). |
| `closeOnBackdrop` | `boolean` | `true` | Close when the backdrop is clicked. |
| `closeOnEscape` | `boolean` | `true` | Close on the Escape key. |
| `trapFocus` | `boolean` | `true` | Trap Tab focus inside the panel while open. |
| `heading` | `string` | `''` | Optional heading rendered in the header. |
| `hideClose` | `boolean` | `false` | Hide the header close button. |
| `aria-label` | `string` | `''` | Accessible name when no `heading` is provided. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `openChange` | `boolean` | Emits when `open` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `close(): void` | Close the drawer. |

### MkFab (component)

Selector: `mk-fab`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkFab } from '@mk-kit/ui/navigation';`

FAB — a floating action button, fixed to a corner (or `static` for inline
use). Project the icon as content and set `label` for the accessible name
(shown too when `extended`). Add `mkFabAction` buttons to turn it into a
speed-dial that reveals them on toggle.

```html
<mk-fab label="Create" position="bottom-end">
  <svg>…</svg>
  <button mkFabAction (click)="newDoc()">Doc</button>
  <button mkFabAction (click)="newFolder()">Folder</button>
</mk-fab>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `MkFabPosition` | `'bottom-end'` | Corner placement (or `static` to render inline). |
| `tone` | `MkTone` | `'primary'` | Semantic tone. |
| `size` | `MkSize` | `'md'` | Size scale. |
| `label` | `string` | `this.i18n.fabLabel` | Accessible label (and visible text when `extended`). |
| `extended` | `boolean` | `false` | Render as a pill with the label beside the icon. |
| `disabled` | `boolean` | `false` | Disable the button. |
| `open` (two-way) | `boolean` | `false` | Two-way open state of the speed-dial. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `openChange` | `boolean` | Emits when `open` changes (two-way binding). |
| `action` | `void` | Emitted when the FAB is activated (only when it has no actions). |

### MkMenu (component)

Selector: `mk-menu` · exportAs: `mkMenu`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkMenu } from '@mk-kit/ui/navigation';`

Dropdown menu implementing the ARIA menu pattern (roving focus, Arrow / Home
/ End / typeahead, Enter/Space to activate). Attach it to a trigger with the
`mkMenuTriggerFor` directive; the trigger controls opening and positioning.

The panel is rendered in the browser top layer via `MkAnchoredPanel`, so
it is never clipped by an ancestor's `overflow`/`transform` and always flips
back on-screen near a viewport edge.

```html
<button mkButton [mkMenuTriggerFor]="menu">Actions</button>
<mk-menu #menu>
  <mk-menu-item (action)="edit()">Edit</mk-menu-item>
  <mk-menu-item danger (action)="del()">Delete</mk-menu-item>
</mk-menu>
```

**Submenus.** Point an item at a nested menu with `[mkSubmenuFor]`; declare
the nested `<mk-menu>` anywhere inside the parent menu. The submenu opens
beside its item on hover (after a short delay), on ArrowRight / Enter /
Space / click, and closes with ArrowLeft or Escape (returning focus to the
item) — only that level, per the APG menu pattern. Activating any leaf item
closes the whole chain. In RTL the submenu opens on the left and the arrow
keys swap.

```html
<mk-menu #menu>
  <mk-menu-item [mkSubmenuFor]="exportMenu">Export</mk-menu-item>
  <mk-menu #exportMenu>
    <mk-menu-item (action)="csv()">CSV</mk-menu-item>
    <mk-menu-item (action)="pdf()">PDF</mk-menu-item>
  </mk-menu>
</mk-menu>
```

Methods:

| Signature | Description |
| --- | --- |
| `open(trigger: HTMLElement, focus?: boolean \| "first" \| "last", placement?: MkPlacement): void` | Open the menu anchored to `trigger`. `focus` picks the item that receives focus once the panel is painted: `true`/`'first'` for the first enabled item, `'last'` for the last (ArrowUp on a menu button, per the APG menu-button pattern), `false` to leave focus where it is (mouse open). `placement` overrides the default `bottom-start` (submenus pass `right-start` / `left-start`). |
| `openAt(x: number, y: number, restoreFocusEl?: HTMLElement): void` | Open the menu at viewport coordinates — e.g. a right-click point from a `contextmenu` event. Positioning (and flip/shift back on-screen) is handled by `MkAnchoredPanel` via the point anchor. Focus moves to the first item; `restoreFocusEl` (when provided) regains focus on close. |
| `close(restoreFocus?: boolean): void` | Close this menu (and any submenu open under it); optionally restore focus to the trigger — for a submenu that is the item it hangs off. |
| `closeAll(restoreFocus?: boolean): void` | Close the whole menu chain from the root down — what activating a leaf item does, wherever in the tree it sits. Focus returns to the root trigger when `restoreFocus` is set. |
| `closeChildren(keep?: MkMenu): void` | Close every submenu open under this menu, except `keep`. |
| `toggle(trigger: HTMLElement, focusFirst?: boolean): void` | Toggle open/closed from a trigger. |
| `focusFirstItem(): void` | Move focus to the first enabled item. Used by the trigger when the menu is already open (e.g. ArrowDown after a mouse open), so arrow keys always reach the items even though focus never left the trigger. |
| `focusLastItem(): void` | Move focus to the last enabled item (ArrowUp from the trigger). |
| `containsTarget(node: Node \| null): boolean` | Whether `node` lives inside this menu's panel or any submenu open under it. Submenu panels are separate top-layer elements, so a plain `contains` on the parent panel would treat clicks in them as outside. |
| `itemHovered(item: MkMenuItem): void` | An item was hovered: close sibling submenus so only the hovered branch stays open (the item opens its own submenu after a delay). |
| `submenuPlacement(): MkPlacement` | Placement for a submenu hanging off `item`, honouring text direction. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `panelId` | `string` | Stable id for `aria-controls` on the trigger. |
| `opened` | `Signal<boolean>` | Whether the menu is currently open. |
| `ariaLabel` | `WritableSignal<string \| undefined>` | Accessible label for the menu (defaults via the trigger if unset). |
| `isSubmenu` | `boolean` | Whether this menu is a submenu of another `mk-menu`. Submenus open sideways, close a single level on Escape, and swap ArrowLeft/ArrowRight. |

### MkMenuItem (component)

Selector: `mk-menu-item`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkMenuItem } from '@mk-kit/ui/navigation';`

An item within an `<mk-menu>`. Renders as an ARIA `menuitem` with an optional
icon slot (`[mkMenuItemIcon]`), disabled and danger states, and either emits
`action` or navigates when `href` is set. Activating closes the menu.

With `[mkSubmenuFor]` pointing at a nested `<mk-menu>` the item becomes a
submenu trigger instead: it shows a chevron, exposes `aria-haspopup` /
`aria-expanded`, opens the submenu beside itself on hover, ArrowRight,
Enter, Space or click, and never emits `action`.

```html
<mk-menu-item (action)="rename()">
  <svg mkMenuItemIcon>…</svg> Rename
</mk-menu-item>
<mk-menu-item danger (action)="remove()">Delete</mk-menu-item>
<mk-menu-item href="/help">Help</mk-menu-item>
<mk-menu-item [mkSubmenuFor]="more">More</mk-menu-item>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Prevent selection and focus. |
| `danger` | `boolean` | `false` | Destructive styling (e.g. Delete). |
| `href` | `string \| undefined` |  | When set, activating the item navigates here. |
| `mkSubmenuFor` | `MkMenu \| undefined` | `undefined` | A nested `mk-menu` this item opens as a submenu. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `action` | `void` | Emitted when the item is activated (not for disabled or submenu items). |

Methods:

| Signature | Description |
| --- | --- |
| `activate(event?: Event): void` |  |
| `openSubmenu(focus: boolean): void` | Open the submenu beside this item; `focus` moves focus to its first item. |
| `focusEl(): void` | Move DOM focus to this item (roving focus). |
| `contains(node: Node \| null): boolean` | Whether `node` lives inside this item. |
| `text(): string` | Lowercased text content, used for typeahead matching. |

### MkNavGroup (component)

Selector: `mk-nav-group`

Docs: https://mk-kit.dev/components/command-nav

Import: `import { MkNavGroup } from '@mk-kit/ui/navigation';`

A titled section within an `<mk-nav-list>` — the "MAIN" / "SETTINGS" groupings
common in admin/CMS sidebars. Static by default; set `collapsible` to make
the label a toggle that expands/collapses its items (`aria-expanded` +
region). In a collapsed icon rail the label becomes a divider.

```html
<mk-nav-list>
  <mk-nav-group label="Main">
    <mk-nav-item label="Dashboard" href="/" />
  </mk-nav-group>
  <mk-nav-group label="Settings" collapsible>
    <mk-nav-item label="Team" href="/team" />
  </mk-nav-group>
</mk-nav-list>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `''` | Section title. |
| `collapsible` | `boolean` | `false` | Make the label a toggle that shows/hides the items. |
| `expanded` (two-way) | `boolean` | `true` | Whether the section is expanded (two-way; only meaningful when collapsible). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `expandedChange` | `boolean` | Emits when `expanded` changes (two-way binding). |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `regionId` | `string` | Id of the items region (for `aria-controls`). |
| `headerId` | `string` | Id of the header, used to name the nested item list. |

### MkNavItem (component)

Selector: `mk-nav-item`

Docs: https://mk-kit.dev/components/command-nav

Import: `import { MkNavItem } from '@mk-kit/ui/navigation';`

A single sidebar entry: icon slot (`[mkNavIcon]`), label, optional badge and
active state. Renders a link when `href` is set, otherwise a button that
emits `action`. If it contains nested `<mk-nav-item>`s it becomes an
expandable disclosure (`aria-expanded`). Collapses to an icon in a collapsed
list, exposing the label as a tooltip — and because a sub-list can't be shown
at rail width, a parent item there emits `action` (navigate) instead of
toggling, so it never becomes a dead button.

```html
<mk-nav-item label="Reports" active href="/reports" badge="3">
  <svg mkNavIcon>…</svg>
</mk-nav-item>
<mk-nav-item label="Settings">
  <svg mkNavIcon>…</svg>
  <mk-nav-item label="Team" href="/team" />
</mk-nav-item>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `''` | Visible label. Also used as the tooltip when collapsed. |
| `href` | `string \| undefined` |  | Link target. Renders an anchor instead of a button. |
| `active` | `boolean` | `false` | Marks the current page (`aria-current="page"`). |
| `disabled` | `boolean` | `false` | Disable interaction. |
| `badge` | `string \| number \| undefined` |  | Optional badge (count or short text). |
| `expanded` (two-way) | `boolean` | `false` | Whether nested children are expanded (two-way). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `expandedChange` | `boolean` | Emits when `expanded` changes (two-way binding). |
| `action` | `void` | Emitted when a button-style item is activated. |

### MkNavList (component)

Selector: `mk-nav-list`

Docs: https://mk-kit.dev/components/command-nav

Import: `import { MkNavList } from '@mk-kit/ui/navigation';`

Sidebar navigation list. Hosts `<mk-nav-item>`s and, when `collapsed`, drives
them into an icon-only rail (labels hidden, exposed via `title` tooltips).
Designed to sit inside the `mkAppSidebar` slot of `<mk-app-shell>`.

```html
<mk-nav-list [collapsed]="collapsed()">
  <mk-nav-item label="Dashboard" href="/" active>
    <svg mkNavIcon>…</svg>
  </mk-nav-item>
</mk-nav-list>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `collapsed` | `boolean` | `false` | Collapse items to icon-only. Read by descendant `MkNavItem`s. |

### MkPageHeader (component)

Selector: `mk-page-header`

Docs: https://mk-kit.dev/components/structure

Import: `import { MkPageHeader } from '@mk-kit/ui/navigation';`

PageHeader — the standard heading block at the top of an admin/CMS page: an
optional breadcrumb, a page title with optional description and inline meta
(badges/status), a right-aligned actions cluster, and an optional tab row
beneath. Everything but the title/description is projected, so it composes
with `mk-breadcrumb`, `mk-tabs`, buttons, badges, etc.

Slots: `[mkPageHeaderBreadcrumb]`, `[mkPageHeaderMeta]` (beside the title),
`[mkPageHeaderActions]` (right), `[mkPageHeaderTabs]` (below).

```html
<mk-page-header heading="Articles" description="Manage your published posts.">
  <mk-breadcrumb mkPageHeaderBreadcrumb …></mk-breadcrumb>
  <mk-badge mkPageHeaderMeta tone="success">Live</mk-badge>
  <div mkPageHeaderActions>
    <button mkButton variant="outline">Import</button>
    <button mkButton>New article</button>
  </div>
</mk-page-header>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `heading` | `string` | `''` | The page title (rendered as an `<h1>`). |
| `description` | `string` | `''` | Supporting description under the title. |

### MkPagination (component)

Selector: `mk-pagination`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkPagination } from '@mk-kit/ui/navigation';`

Page navigation with previous/next controls and numbered pages that collapse
to ellipses for large ranges. Provide either `total` (+ `pageSize`) or a
direct `pageCount`. `page` is 1-based and two-way bindable.

```html
<mk-pagination
  [total]="240"
  [pageSize]="20"
  [(page)]="page"
  (pageChange)="load($event)"
/>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `total` | `number` | `0` | Total number of items (used with `pageSize` when `pageCount` is unset). |
| `pageSize` | `number` | `10` | Items per page. |
| `pageCount` | `number` | `0` | Explicit page count; overrides `total`/`pageSize` when > 0. |
| `page` (two-way) | `number` | `1` | Current 1-based page (two-way). |
| `siblingCount` | `number` | `1` | Number of page buttons to keep on each side of the current page. |
| `boundaryCount` | `number` | `1` | Number of page buttons pinned at each end. |
| `label` | `string` | `this.i18n.paginationLabel` | Accessible label for the navigation landmark. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `pageChange` | `number` | Emits when `page` changes (two-way binding). |

### MkScrollArea (component)

Selector: `mk-scroll-area`

Docs: https://mk-kit.dev/components/structure

Import: `import { MkScrollArea } from '@mk-kit/ui/navigation';`

ScrollArea — a scroll container that hides the native scrollbar and renders
its own themed overlay bars (à la Radix ScrollArea). The projected content
scrolls inside a real, keyboard-focusable viewport, so native wheel / arrow
scrolling keeps working; the custom bars are decorative (`aria-hidden`) and
draggable.

```html
<mk-scroll-area maxHeight="20rem">
  <p>…lots of content…</p>
</mk-scroll-area>
```

Set `orientation` to `horizontal` / `both` for a horizontal bar, and
`hideDelay` to auto-hide the bars after inactivity (`0` = always visible).

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `maxHeight` | `string` | `''` | Optional CSS max-height for the viewport, e.g. `'20rem'`. |
| `ariaLabel` | `string` | `''` | Accessible name for the scrollable viewport. When set, the viewport is exposed as a labelled `region` landmark — recommended, since the viewport is keyboard-focusable (`tabindex="0"`) and a focusable scroll container should have an accessible name. When empty, no role / label is added. |
| `orientation` | `MkScrollAreaOrientation` | `'vertical'` | Which axes render a custom bar. |
| `hideDelay` | `number` | `1000` | Auto-hide the bars after this many ms of inactivity (`0` = always on). |

### MkSplitButton (component)

Selector: `mk-split-button`

Docs: https://mk-kit.dev/components/buttons

Import: `import { MkSplitButton } from '@mk-kit/ui/navigation';`

SplitButton — a primary action with an attached menu of alternatives.
The main segment emits `action`; the chevron segment is a menu button
(`mkMenuTriggerFor`) for the `mk-menu` passed in `[menu]`, with the full
keyboard model of the menu trigger (ArrowDown / Enter / Space open and focus
the first item, ArrowUp the last, Escape closes).

Both segments share `variant`, `tone` and `size`; `disabled` disables both,
`loading` shows the main segment's spinner and disables the chevron.

```html
<mk-split-button [menu]="saveMenu" tone="primary" (action)="save()">
  Save
</mk-split-button>
<mk-menu #saveMenu>
  <mk-menu-item (action)="saveAs()">Save as…</mk-menu-item>
  <mk-menu-item (action)="saveTemplate()">Save as template</mk-menu-item>
</mk-menu>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `menu` (required) | `MkMenu` |  | The menu the chevron segment opens. |
| `variant` | `MkVariant` | `'solid'` | Visual treatment shared by both segments. |
| `tone` | `MkTone` | `'primary'` | Semantic color tone shared by both segments. |
| `size` | `MkSize` | `'md'` | Control size shared by both segments. |
| `disabled` | `boolean` | `false` | Disable both segments. |
| `loading` | `boolean` | `false` | Spinner on the main segment; the menu segment is disabled meanwhile. |
| `fullWidth` | `boolean` | `false` | Stretch to the container width (the main segment grows). |
| `type` | `"submit" \| "button"` | `'button'` | `type` of the main segment — `submit` to submit the enclosing form. |
| `menuLabel` | `string` | `this.i18n.moreActions` | Accessible name of the chevron segment. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `action` | `void` | Emitted when the main segment is activated (not while disabled/loading). |

### MkSplitter (component)

Selector: `mk-splitter`

Docs: https://mk-kit.dev/components/structure

Import: `import { MkSplitter } from '@mk-kit/ui/navigation';`

Splitter — two resizable panes with a draggable, keyboard-operable separator
(ARIA `separator` with `aria-valuenow`). `horizontal` places the panes
side-by-side (a vertical handle); `vertical` stacks them (a horizontal
handle). The start pane's size is a two-way `position` model (percent).

Project the panes with `mkSplitterStart` / `mkSplitterEnd`:
```html
<mk-splitter [(position)]="split" [min]="20">
  <nav mkSplitterStart>…</nav>
  <main mkSplitterEnd>…</main>
</mk-splitter>
```
Drag the handle, or focus it and use Arrow keys (Home/End jump to min/max).

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `MkSplitterOrientation` | `'horizontal'` | `horizontal` = side-by-side; `vertical` = stacked. |
| `position` (two-way) | `number` | `50` | Two-way position of the separator = start-pane size, in percent (0–100). |
| `min` | `number` | `10` | Minimum start-pane size (percent). |
| `max` | `number` | `90` | Maximum start-pane size (percent). |
| `step` | `number` | `5` | Keyboard resize increment (percent). |
| `disabled` | `boolean` | `false` | Disable resizing. |
| `ariaLabel` | `string` | `this.i18n.resizePanes` | Accessible label for the separator. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `positionChange` | `number` | Emits when `position` changes (two-way binding). |

### MkStep (component)

Selector: `mk-step`

Docs: https://mk-kit.dev/components/stepper

Import: `import { MkStep } from '@mk-kit/ui/navigation';`

A single step + its content panel. Declared inside `<mk-stepper>`; the
projected content becomes the step body while `label` (and optional
`description`) render in the step header.

`completed` is a two-way model so a parent can gate a `linear` stepper:
`<mk-step label="Details" [(completed)]="detailsValid()">`.

```html
<mk-stepper linear>
  <mk-step label="Account" [completed]="form.valid">…</mk-step>
  <mk-step label="Payment" optional>…</mk-step>
</mk-stepper>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `''` | Title shown in the step header. |
| `description` | `string` | `''` | Optional secondary line under the label. |
| `optional` | `boolean` | `false` | Marks the step optional (skippable in a `linear` stepper). |
| `completed` (two-way) | `boolean` | `false` | Whether the step is complete (two-way; drives `linear` gating + the ✓). |
| `hasError` | `boolean` | `false` | Show the error state in the header (e.g. failed validation). |
| `editable` | `boolean` | `true` | Allow returning to this step after it is completed. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `completedChange` | `boolean` | Emits when `completed` changes (two-way binding). |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `headerId` | `string` | Stable id for the header button (wires `aria-labelledby`). |
| `panelId` | `string` | Stable id for the panel (wires `aria-controls`). |
| `active` | `WritableSignal<boolean>` | Whether this step is currently selected. Set by the parent `MkStepper`. |

### MkStepper (component)

Selector: `mk-stepper`

Docs: https://mk-kit.dev/components/stepper

Import: `import { MkStepper } from '@mk-kit/ui/navigation';`

Stepper — walks a user through an ordered sequence of `<mk-step>`s with an
accessible header rail (ARIA `tablist` + roving tabindex, Arrow/Home/End
navigation) and a single visible panel.

In `linear` mode a step is only reachable once every preceding required
(non-`optional`) step reports `completed`. Drive completion from your form
state and move with the `next()` / `previous()` / `reset()` API or by
clicking a reachable header.

```html
<mk-stepper #s linear [(selectedIndex)]="index">
  <mk-step label="Account" [completed]="accountValid()">…</mk-step>
  <mk-step label="Address" [completed]="addressValid()">…</mk-step>
  <mk-step label="Review">…</mk-step>
</mk-stepper>
<button mkButton (click)="s.previous()">Back</button>
<button mkButton (click)="s.next()">Next</button>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `selectedIndex` (two-way) | `number` | `0` | Zero-based index of the active step (two-way). |
| `orientation` | `MkStepperOrientation` | `'horizontal'` | Header rail orientation. |
| `linear` | `boolean` | `false` | Enforce sequential completion before a step becomes reachable. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `selectedIndexChange` | `number` | Emits when `selectedIndex` changes (two-way binding). |
| `selectionChange` | `number` | Emits the newly selected index whenever the active step changes. |

Methods:

| Signature | Description |
| --- | --- |
| `isReachable(index: number): boolean` | Whether a step can be selected. In linear mode every earlier required step must be completed; a completed step is reachable only when `editable`. |
| `next(): void` | Advance to the next reachable step, if any. |
| `previous(): void` | Return to the previous step, if any. |
| `reset(): void` | Reset to the first step and clear every step's completed flag. |

### MkTab (component)

Selector: `mk-tab`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkTab } from '@mk-kit/ui/navigation';`

A single tab + its panel. Declared inside `<mk-tabs>`; the projected content
becomes the tab panel body while `label` is rendered in the tablist.

```html
<mk-tabs>
  <mk-tab label="Overview">…panel content…</mk-tab>
  <mk-tab label="Settings" [disabled]="locked()">…</mk-tab>
</mk-tabs>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `''` | Text shown on the tab button in the tablist. |
| `disabled` | `boolean` | `false` | Disable selection of this tab. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `tabId` | `string` | Stable id for the tab button (wires `aria-labelledby`). |
| `panelId` | `string` | Stable id for the panel (wires `aria-controls`). |
| `active` | `WritableSignal<boolean>` | Whether this tab is currently selected. Set by the parent `MkTabs`. |

### MkTabs (component)

Selector: `mk-tabs`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkTabs } from '@mk-kit/ui/navigation';`

Accessible tabs implementing the ARIA tabs pattern: a `role="tablist"` with
roving tabindex, Arrow/Home/End keyboard navigation and an animated active
indicator. Selection is two-way bindable via `selectedIndex`.

```html
<mk-tabs [(selectedIndex)]="tab" variant="line">
  <mk-tab label="Profile">…</mk-tab>
  <mk-tab label="Billing">…</mk-tab>
</mk-tabs>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `selectedIndex` (two-way) | `number` | `0` | Zero-based index of the active tab (two-way). |
| `variant` | `MkTabsVariant` | `'line'` | `line` shows an underline indicator; `pill` uses filled pills. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `selectedIndexChange` | `number` | Emits when `selectedIndex` changes (two-way binding). |

### MkToolbar (component)

Selector: `mk-toolbar`

Docs: https://mk-kit.dev/components/structure

Import: `import { MkToolbar } from '@mk-kit/ui/navigation';`

Toolbar — a horizontal action bar: content flows on the start side, anything
marked `mkToolbarEnd` is pushed to the end. Handy above tables and lists for
a title/search on the left and actions on the right.

The projected controls are ordinary tab stops (no roving focus), so this is a
layout container, not an ARIA `toolbar` widget.

```html
<mk-toolbar bordered aria-label="Users actions">
  <strong>Users</strong>
  <span mkToolbarEnd>
    <button mkButton variant="outline">Export</button>
    <button mkButton>New user</button>
  </span>
</mk-toolbar>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `bordered` | `boolean` | `false` | Wrap the bar in a themed, bordered surface. |
| `aria-label` | `string` | `''` | Accessible name (also promotes the bar to an ARIA `group`). |

### MkTree (component)

Selector: `mk-tree`

Docs: https://mk-kit.dev/components/tree

Import: `import { MkTree } from '@mk-kit/ui/navigation';`

Tree — renders hierarchical data following the ARIA tree pattern
(`role="tree"` / `treeitem` with `aria-level`, `aria-expanded`,
`aria-selected`). Supply `nodes`; expansion is managed internally.

Keyboard: Up/Down move between visible rows, Right expands (or steps into the
first child), Left collapses (or steps out to the parent), Home/End jump, and
Enter/Space toggles expansion and selects (when `selectable`). A single
roving tabindex keeps the whole tree one tab stop.

```html
<mk-tree selectable [nodes]="tree" [(selected)]="picked"
  (selectionChange)="onPick($event)" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `readonly MkTreeNode[]` | `[]` | The hierarchical data to render. |
| `selectable` | `boolean` | `false` | Allow choosing a node (adds selection styling + `aria-selected`). |
| `aria-label` | `string` | `''` | Accessible name for the tree. |
| `selected` (two-way) | `unknown` | `null` | Two-way selected value (a node's `value`, or the node itself if unset). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `selectedChange` | `unknown` | Emits when `selected` changes (two-way binding). |
| `selectionChange` | `unknown` | Emits the selected value whenever the selection changes. |
| `nodeToggle` | `MkTreeNode` | Emits a node whenever it is expanded or collapsed. |

### MkAccordionHeader (directive)

Selector: `[mkAccordionHeader]`

Import: `import { MkAccordionHeader } from '@mk-kit/ui/navigation';`

Marks projected content as the header of an `<mk-accordion-item>`. Use when
the header needs rich markup instead of the plain-text `header` input.

```html
<mk-accordion-item>
  <span mkAccordionHeader><mk-icon name="user" /> Account</span>
  …body…
</mk-accordion-item>
```

### MkFabAction (directive)

Selector: `[mkFabAction]`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkFabAction } from '@mk-kit/ui/navigation';`

A speed-dial action button projected into `MkFab`.

### MkMenuTrigger (directive)

Selector: `[mkMenuTriggerFor]` · exportAs: `mkMenuTrigger`

Docs: https://mk-kit.dev/components/navigation

Import: `import { MkMenuTrigger } from '@mk-kit/ui/navigation';`

Turns its host button into a trigger for an `<mk-menu>`. Wires
`aria-haspopup="menu"` / `aria-expanded` / `aria-controls`, toggles on click,
opens on ArrowDown / Enter / Space (focusing the first item) and on ArrowUp
(focusing the last item, per the APG menu-button pattern), and closes on
Escape. When the menu is already open — e.g. after a mouse click, which
deliberately leaves focus on the trigger — ArrowDown moves focus to the
first item and ArrowUp to the last, so the keyboard is never dead.

```html
<button mkButton [mkMenuTriggerFor]="menu">Actions</button>
<mk-menu #menu>…</mk-menu>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkMenuTriggerFor` (required) | `MkMenu` |  | The menu instance to control. |

### MkAppLink (interface)

Import: `import { MkAppLink } from '@mk-kit/ui/navigation';`

One app in the switcher.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable id; `current` matches on it (or on `url`). |
| `name` | `string` |  |
| `url` | `string` |  |
| `description`? | `string \| undefined` | One line under the name. |
| `icon`? | `string \| undefined` | A short glyph for the tile — an emoji or one or two letters. Defaults to the name's initial. |
| `color`? | `string \| undefined` | Tile colour; any CSS colour. Defaults to the primary tone. |

### MkCommand (interface)

Import: `import { MkCommand } from '@mk-kit/ui/navigation';`

A single actionable entry in the `MkCommandPalette`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable unique id. |
| `label` | `string` | Text shown (and the primary search target). |
| `group`? | `string \| undefined` | Optional section heading this command is grouped under. |
| `hint`? | `string \| undefined` | Secondary text shown after the label. |
| `icon`? | `string \| undefined` | Name of a registered icon (see `MkIconRegistry`). |
| `keywords`? | `string \| undefined` | Extra search terms (not shown). |
| `shortcut`? | `string \| undefined` | Display-only shortcut hint, e.g. `⌘S`. |
| `disabled`? | `boolean \| undefined` | Disable the command (skipped by keyboard, not runnable). |
| `run`? | `(() => void) \| undefined` | Invoked when the command is chosen. |

### MkTreeNode (interface)

Import: `import { MkTreeNode } from '@mk-kit/ui/navigation';`

A node in an `MkTree`. `children` makes it expandable.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Text shown for the node. |
| `value`? | `unknown` | Value bound to the selection when the node is chosen (defaults to the node). |
| `children`? | `MkTreeNode[] \| undefined` | Child nodes; a non-empty array makes the node a parent (expandable). |
| `disabled`? | `boolean \| undefined` | Disable selection/toggling of this node (still focusable). |
| `expanded`? | `boolean \| undefined` | Expand this node initially. |
| `icon`? | `string \| undefined` | Optional leading glyph (any short string / emoji). |
| `iconName`? | `string \| undefined` | Name of a registered icon (see `MkIconRegistry`), rendered with `mk-icon`; wins over `icon`. |

### MkDrawerSide (type)

Import: `import { MkDrawerSide } from '@mk-kit/ui/navigation';`

Edge the drawer slides in from.

```ts
type MkDrawerSide = 'start' | 'end' | 'top' | 'bottom';
```

### MkFabPosition (type)

Import: `import { MkFabPosition } from '@mk-kit/ui/navigation';`

Corner placement for a fixed `MkFab`. `static` renders it inline.

```ts
type MkFabPosition = | 'bottom-end' | 'bottom-start' | 'top-end' | 'top-start' | 'static';
```

### MkPageItem (type)

Import: `import { MkPageItem } from '@mk-kit/ui/navigation';`

A rendered pagination cell: a real page number or a gap marker.

```ts
type MkPageItem = number | 'ellipsis';
```

### MkScrollAreaOrientation (type)

Import: `import { MkScrollAreaOrientation } from '@mk-kit/ui/navigation';`

Which axes get a custom scrollbar for `MkScrollArea`.

```ts
type MkScrollAreaOrientation = 'vertical' | 'horizontal' | 'both';
```

### MkSplitterOrientation (type)

Import: `import { MkSplitterOrientation } from '@mk-kit/ui/navigation';`

Split direction for `MkSplitter`.

```ts
type MkSplitterOrientation = 'horizontal' | 'vertical';
```

### MkStepperOrientation (type)

Import: `import { MkStepperOrientation } from '@mk-kit/ui/navigation';`

Orientation of the step header rail.

```ts
type MkStepperOrientation = 'horizontal' | 'vertical';
```

### MkTabsVariant (type)

Import: `import { MkTabsVariant } from '@mk-kit/ui/navigation';`

Visual style for the tablist.

```ts
type MkTabsVariant = 'line' | 'pill';
```

## @mk-kit/ui/forms

99 exports. `import { … } from '@mk-kit/ui/forms';`

### MkAutocomplete (component)

Selector: `mk-autocomplete` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/selection

Import: `import { MkAutocomplete } from '@mk-kit/ui/forms';`

Autocomplete — an accessible text input that suggests options as the user
types, implementing the ARIA combobox (`aria-autocomplete="list"`) pattern
with a popup listbox.

Filtering is built in (`contains` / `startsWith`); set `filterMode="none"`
and drive `options` yourself from the `search` output for async/server-side
suggestions. Typing arbitrary text is allowed unless `requireSelection` is
set, in which case the field clears on blur if it doesn't match an option.

Implements `ControlValueAccessor` and exposes a two-way `value` model, so it
works with `[(ngModel)]`, reactive forms and `[(value)]`. When nested in an
`mk-form-field` it inherits size, label, hint/error and required wiring.

```html
<mk-autocomplete placeholder="Search users"
  [options]="filtered()"
  filterMode="none"
  (search)="query.set($event)"
  [(value)]="userId" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `''` | Accessible name when the control is used without an `mk-form-field` label. |
| `options` | `readonly MkAutocompleteOption[]` | `[]` |  |
| `placeholder` | `string` | `''` | Placeholder shown when the input is empty. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). Set by Signal Forms' `[formField]` from the schema. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `filterMode` | `MkAutocompleteFilterMode` | `'contains'` | How the option list is filtered against the typed text. |
| `minChars` | `number` | `0` | Only open the list once this many characters have been typed. |
| `loading` | `boolean` | `false` | Show a loading row instead of "no results" (for async fetches). |
| `requireSelection` | `boolean` | `false` | Clear the input on blur unless the text matches a selectable option. |
| `emptyMessage` | `string` | `this.i18n.noResults` | Message shown when there are no matching options. |
| `value` (two-way) | `unknown` | `null` | Two-way selected value (the `value` of the chosen option, or `null`). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `unknown` | Emits when `value` changes (two-way binding). |
| `search` | `string` | Emits the current input text on every keystroke — drive async loading. |
| `optionSelected` | `MkAutocompleteOption` | Emits the option whenever one is committed by click or Enter. |

### MkButtonToggle (component)

Selector: `mk-button-toggle`

Import: `import { MkButtonToggle } from '@mk-kit/ui/forms';`

A single segment inside an `mk-button-toggle-group`. Projected content is the
label (text, an icon, or both). Its selected state and keyboard behaviour are
driven by the parent group.

```html
<mk-button-toggle value="bold" aria-label="Bold"><b>B</b></mk-button-toggle>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `unknown` | `undefined` | The value contributed to the group's selection when this item is on. |
| `disabled` | `boolean` | `false` | Disable just this item. |

Methods:

| Signature | Description |
| --- | --- |
| `focus(): void` | Move focus to this item's button. Called by the parent group. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `selected` | `Signal<boolean>` | Whether this item is currently selected (owned by the parent group). |
| `isDisabled` | `Signal<boolean>` | Disabled if the item or the whole group is disabled. |

### MkButtonToggleGroup (component)

Selector: `mk-button-toggle-group` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/selection

Import: `import { MkButtonToggleGroup } from '@mk-kit/ui/forms';`

ButtonToggleGroup — a segmented control grouping one or more
`mk-button-toggle` items into a single, keyboard-operable selection.

In single-select mode (default) the group is an ARIA `radiogroup`: exactly
one item is selected, Arrow keys move and select, and the selected item is
the tab stop. Set `multiple` to allow any number of items — the group
becomes a toolbar of independent `aria-pressed` buttons.

Implements `ControlValueAccessor` and exposes a two-way `value` model. In
single mode `value` is the chosen item's `value`; in multiple mode it is an
array of the selected values.

```html
<mk-button-toggle-group [(value)]="view" aria-label="View">
  <mk-button-toggle value="grid">Grid</mk-button-toggle>
  <mk-button-toggle value="list">List</mk-button-toggle>
</mk-button-toggle-group>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `multiple` | `boolean` | `false` | Allow selecting any number of items (toolbar of `aria-pressed` buttons). |
| `size` | `MkSize` | `'md'` | Control size, applied to every item. Ignored inside an `mk-form-field`. |
| `tone` | `MkTone` | `'primary'` | Semantic color tone used for the selected fill. |
| `disabled` | `boolean` | `false` | Disable the whole group. |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `aria-label` | `string` | `''` | Accessible name for the group (recommended). |
| `value` (two-way) | `unknown` | `null` | Two-way selected value. Single mode: the chosen item's `value` (or `null`). Multiple mode: an array of selected values. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `unknown` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `isSelected(toggle: MkButtonToggle): boolean` | Whether a given item is part of the current selection. |
| `tabIndexFor(toggle: MkButtonToggle): number` | `0` for the item that owns the tab stop, `-1` for the rest. |
| `select(toggle: MkButtonToggle): void` | Toggle (multiple) or set (single) the selection for an item. |
| `onKeydown(event: KeyboardEvent, toggle: MkButtonToggle): void` |  |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `effectiveSize` | `Signal<MkSize>` | The size actually applied (the form field's when nested). |

### MkCardNumberInput (component)

Selector: `mk-card-number-input` · exportAs: `mkCardNumberInput` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/payment

Import: `import { MkCardNumberInput } from '@mk-kit/ui/forms';`

CardNumberInput — a payment-card number field that groups digits with the
detected network's layout (16-digit `0000 0000 0000 0000`, Amex
`0000 000000 00000`, Diners `0000 000000 0000`), shows the brand as a
badge, and validates the complete number with the Luhn checksum.

The form value is the raw digit string (no spaces). `brand()` exposes the
detected network (also via `(brandChange)`), and `valid()` reports
`true`/`false` for a complete number passing/failing Luhn and `null` while
empty or incomplete; invalid styling engages after the field was touched.

Implements `ControlValueAccessor` and exposes a two-way `value` model, so
`[(ngModel)]`, reactive forms and `[(value)]` all work.

```html
<mk-card-number-input [(ngModel)]="cardNumber" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `showBrand` | `boolean` | `true` | Show the detected brand as a badge inside the field. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `placeholder` | `string` | `'0000 0000 0000 0000'` | Placeholder shown when empty. |
| `value` (two-way) | `string` | `''` | Two-way card number, digits only (no spaces). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |
| `brandChange` | `MkCardBrand \| null` | Emits whenever the detected brand changes. |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `cardNumber` for a number failing the Luhn checksum (which includes a half-typed one). An empty value passes; compose with `Validators.required` to reject it. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `brand` | `Signal<MkCardBrand \| null>` | The detected card network, `null` while unrecognised. |
| `valid` | `Signal<boolean \| null>` | `true` for a complete number passing Luhn, `false` for a complete number failing it, `null` while empty or incomplete. |

### MkCascader (component)

Selector: `mk-cascader` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/selection

Import: `import { MkCascader } from '@mk-kit/ui/forms';`

Cascader — a select whose choices are a hierarchy shown as side-by-side
columns (region → country → city, category → subcategory, org unit → team).
Each pick opens the next column; picking a leaf commits the whole path.

The value is the **path** of option values (`['eu', 'pl', 'krk']`) by
default, or just the leaf's value with `valueMode="leaf"`. Parents are only
selectable with `selectParents` (a click on one then commits, and its
children stay reachable).

Keyboard: Up / Down move within a column, Right opens the children, Left
goes back, Enter / Space selects, typing jumps to a label, Escape closes.
`expandTrigger="hover"` opens columns on pointer hover as well as click.

Implements `ControlValueAccessor` and a two-way `value` model.

```html
<mk-cascader [options]="regions" [(value)]="location" placeholder="Where?" clearable />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `readonly MkCascaderOption[]` | `[]` | The hierarchy to choose from. |
| `value` (two-way) | `unknown` | `null` | Two-way value: the path of values (default) or the leaf value (`valueMode="leaf"`). |
| `valueMode` | `"path" \| "leaf"` | `'path'` | Bind the full path of values (default) or only the chosen option's value. |
| `selectParents` | `boolean` | `false` | Allow committing a parent option (click / Enter on it) instead of leaves only. |
| `expandTrigger` | `"click" \| "hover"` | `'click'` | Open the next column on click (default) or also on pointer hover. |
| `placeholder` | `string` | `this.i18n.selectPlaceholder` |  |
| `separator` | `string` | `' / '` | Text between the labels of the chosen path. |
| `clearable` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `invalid` | `boolean` | `false` |  |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `unknown` | Emits when `value` changes (two-way binding). |
| `change` | `unknown` | Emitted after the user commits or clears a value. |

### MkCheckbox (component)

Selector: `mk-checkbox` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/toggles

Import: `import { MkCheckbox } from '@mk-kit/ui/forms';`

Checkbox — a themed checkbox built on a visually-hidden native
`input[type=checkbox]` (so keyboard + form semantics are native) with a
custom box. Supports an `indeterminate` state and projects its label.

Implements `ControlValueAccessor` with a two-way `checked` model, so it works
with `[(ngModel)]`, reactive forms and `[(checked)]`.

```html
<mk-checkbox [(ngModel)]="accepted">Accept terms</mk-checkbox>
<mk-checkbox [(checked)]="all" [indeterminate]="some()" tone="success">
  Select all
</mk-checkbox>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` (two-way) | `boolean` | `false` | Two-way checked state. |
| `indeterminate` (two-way) | `boolean` | `false` | Two-way indeterminate ("mixed") state; cleared when the user toggles. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). |
| `size` | `MkSize` | `'md'` | Control size. |
| `tone` | `MkTone` | `'primary'` | Semantic color tone for the checked box. |
| `aria-label` | `string` | `''` | Accessible label when no text content is projected. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `checkedChange` | `boolean` | Emits when `checked` changes (two-way binding). |
| `indeterminateChange` | `boolean` | Emits when `indeterminate` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `required` for an unchecked box when `[required]` is set, so `required` on the element behaves like `Validators.requiredTrue`. |

### MkCodeEditor (component)

Selector: `mk-code-editor` · exportAs: `mkCodeEditor` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/forms

Import: `import { MkCodeEditor } from '@mk-kit/ui/forms';`

CodeEditor — a lightweight, dependency-free code field with syntax
highlighting, JSON validation and pretty-printing. A `<textarea>` provides
editing and a synced highlight layer sits behind it, so it stays fully
accessible (real textarea semantics, `aria-invalid`, form-field wiring)
without pulling in a heavyweight editor.

With `language="json"` it validates on every change (exposing an inline error
+ `(validate)` output) and offers `format()` to pretty-print. Ideal for a CMS
`json` field or plugin/settings JSONB editing.

Keyboard: Tab inserts `tabSize` spaces; press Escape then Tab to move focus
out (so it is never a keyboard trap). Implements `ControlValueAccessor` over a
string value with a two-way `value` model.

```html
<mk-code-editor #editor language="json" [(value)]="config" [rows]="10" />
<button mkButton (click)="editor.format()">Format</button>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `language` | `MkCodeLanguage` | `'plaintext'` | Language for highlighting + validation. |
| `placeholder` | `string` | `''` | Placeholder shown when empty. |
| `readOnly` | `boolean` | `false` | Render read-only (still focusable/selectable). |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force invalid styling when used standalone. |
| `rows` | `number` | `8` | Visible rows (minimum height). |
| `lineNumbers` | `boolean` | `true` | Show a line-number gutter. |
| `tabSize` | `number` | `2` | Number of spaces inserted by Tab. |
| `wrap` | `boolean` | `false` | Soft-wrap long lines instead of scrolling horizontally. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `ariaLabel` | `string` | `''` | Accessible label when used standalone (no form field). |
| `value` (two-way) | `string` | `''` | Two-way editor content. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |
| `validate` | `MkCodeValidity` | Emits the content validity whenever it changes (JSON only). |

Methods:

| Signature | Description |
| --- | --- |
| `parsed(): unknown` | The parsed JSON value, or `undefined` when empty / invalid / plaintext. |
| `format(): void` | Pretty-print valid JSON with `tabSize` indentation. No-op otherwise. |

### MkColorPicker (component)

Selector: `mk-color-picker` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/sliders

Import: `import { MkColorPicker } from '@mk-kit/ui/forms';`

ColorPicker — a compact color control: a live swatch that opens the native OS
picker, an editable hex field and an optional row of preset swatches.
`ControlValueAccessor` + two-way `value` model over a hex string.

```html
<mk-color-picker [(value)]="brand" [swatches]="palette" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `string` | `'#000000'` | Two-way hex color value. |
| `swatches` | `readonly string[]` | `[]` | Preset swatches (hex strings). |
| `hexInput` | `boolean` | `true` | Show the editable hex text field. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force invalid styling when standalone. |
| `size` | `MkSize` | `'md'` | Control size. Ignored inside an `mk-form-field`. |
| `ariaLabel` | `string` | `this.i18n.chooseColor` | Accessible label for the swatch trigger. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |

### MkCurrencyInput (component)

Selector: `mk-currency-input` · exportAs: `mkCurrencyInput` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/payment

Import: `import { MkCurrencyInput } from '@mk-kit/ui/forms';`

CurrencyInput — a money/amount field that formats itself with
`Intl.NumberFormat`: thousands grouping live as the user types, the
currency symbol as a fixed prefix/suffix (per locale), fraction digits
padded to the currency's convention on blur (`1234,5` → `1 234,50 zł`).
The form value is always a plain `number` (or `null` when empty) — the
locale formatting never leaks into the data.

`currency` takes an ISO 4217 code; omit it for a plain grouped decimal.
`locale` defaults to the runtime locale. `decimals` overrides the
currency's fraction digits; `min`/`max` clamp on blur.

Implements `ControlValueAccessor` and exposes a two-way `value` model, so
`[(ngModel)]`, reactive forms and `[(value)]` all work.

```html
<mk-currency-input currency="PLN" [(ngModel)]="price" />
<mk-currency-input currency="USD" [min]="0" [(value)]="budget" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `''` | Accessible name when the control is used without an `mk-form-field` label. |
| `currency` | `string` | `''` |  |
| `locale` | `string \| undefined` | `undefined` | BCP 47 locale for separators/symbol; defaults to the runtime locale. |
| `decimals` | `number \| null` | `null` | Max fraction digits; defaults to the currency's convention (else 2). |
| `min` | `number \| null` | `null` | Clamp the value to at least this on blur. |
| `max` | `number \| null` | `null` | Clamp the value to at most this on blur. |
| `allowNegative` | `boolean` | `true` | Allow a leading minus sign. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `placeholder` | `string` | `''` | Placeholder shown when empty. |
| `value` (two-way) | `number \| null` | `null` | Two-way numeric value (`null` when empty). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `number \| null` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `min` / `max` against the `[min]` and `[max]` inputs, using the same error shapes as `Validators.min` / `Validators.max`. |

### MkFileUpload (component)

Selector: `mk-file-upload` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/forms

Import: `import { MkFileUpload } from '@mk-kit/ui/forms';`

FileUpload — an accessible click-or-drag dropzone with multi-file support,
type/size/count validation, image thumbnails and per-file progress.

Provide an `uploadFn` to stream each accepted file to your backend (it
reports progress and resolves/rejects); with `autoUpload` (on by default when
an `uploadFn` is set) files upload as soon as they are accepted. Without one,
the component just validates + tracks files and emits `filesSelected` for you
to handle. The tracked list is a two-way `files` model so you can reset it.

Keyboard: the dropzone is a button — Enter/Space opens the native picker.
Rejections are announced through a polite live region.

Implements `ControlValueAccessor` and `Validator`, so it drops into a
reactive form like any other control. The form value is `File[]` by default
(`[valueFormat]="'item'"` publishes the tracked `MkUploadFile[]` instead),
and `accept` / `maxSize` / `maxFiles` are enforced as validation errors as
well as at pick time — a list written in from the model side is checked too.

```html
<mk-file-upload accept="image/*" multiple [maxSize]="5_000_000"
  [uploadFn]="upload" (filesSelected)="onFiles($event)" [(files)]="files" />

<mk-file-upload formControlName="attachments" accept=".pdf" [maxFiles]="3" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `accept` | `string` | `''` | Native `accept` filter, e.g. `image/*` or `.pdf,.doc`. |
| `multiple` | `boolean` | `false` | Allow selecting more than one file. |
| `maxSize` | `number` | `0` | Maximum size per file in bytes (0 = unlimited). |
| `maxFiles` | `number` | `0` | Maximum number of files kept (0 = unlimited). |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force invalid styling when used standalone. |
| `label` | `string` | `this.i18n.dropzoneLabel` | Primary dropzone prompt. |
| `hint` | `string` | `''` | Secondary hint under the prompt (e.g. accepted types / size). |
| `hideList` | `boolean` | `false` | Hide the built-in file list (render your own from `files`). |
| `uploadFn` | `MkUploadFn \| null` | `null` | Async upload handler. When set, files upload automatically. |
| `autoUpload` | `boolean \| undefined` | `undefined` | Upload accepted files immediately. Defaults to true when `uploadFn` set. |
| `valueFormat` | `MkUploadValueFormat` | `'file'` | Shape of the value published to a bound form control. |
| `files` (two-way) | `MkUploadFile[]` | `[]` | The tracked files (two-way, so consumers can reset the list). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `filesChange` | `MkUploadFile[]` | Emits when `files` changes (two-way binding). |
| `filesSelected` | `File[]` | Emits the accepted `File`s each time files are added. |
| `rejected` | `MkUploadRejection[]` | Emits rejected files with a reason. |
| `uploaded` | `MkUploadFile` | Emits a file once its upload succeeds. |
| `removed` | `MkUploadFile` | Emits a file when it is removed from the list. |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Applies the same `accept` / `maxSize` / `maxFiles` rules the dropzone enforces at pick time, so a list written in from the model side — which never goes through that path — is checked too. An empty list passes; compose with `Validators.required` to reject it. |

### MkFormErrorSummary (component)

Selector: `mk-form-error-summary` · exportAs: `mkFormErrorSummary`

Docs: https://mk-kit.dev/components/forms

Import: `import { MkFormErrorSummary } from '@mk-kit/ui/forms';`

FormErrorSummary — an accessible summary of a form's validation errors,
shown at the top of the form on a failed submit. Each entry links to its
field and focuses it on click. Following the WAI/GOV.UK pattern it is an
`alert` region and, when the surrounding form is submitted with errors,
focus moves here automatically (opt out with `[autoFocus]="false"`) so
screen-reader and keyboard users are taken straight to the problems. The
public `focus()` remains for manual flows (e.g. server-side errors).

## Automatic collection

Point `form` at a `FormGroup` and the summary walks it itself: one entry per
invalid control, worded from the `validation` i18n table (override per key
with `errorMessages`). Pass `labels` to name the fields — without an entry
the control's path is used. Entries appear once the form is submitted;
`showOn="always"` lists them as soon as they exist.

Each entry is linked to its field by locating the control in the DOM, so
`formControlName` must be a static attribute (`formControlName="email"`,
the usual form) rather than a binding.

## Signal Forms

Point `field` at a Signal Forms root (`[field]="f"`) instead of `form` and
the summary reads `errorSummary()` from the `FieldTree`: one entry per
invalid field, keyed by dotted path in `labels` / `errorMessages` like the
reactive path. With the default `showOn="submit"` an entry appears once its
field is touched — `submit()` marks every field touched, so a failed submit
lists them all. Clicking an entry focuses the control bound with
`[formField]`. When the summary sits inside the `<form>`, focus also moves
to it after the form's `submit` event, as with `ngSubmit`.

```html
<form (submit)="save($event)">
  <mk-form-error-summary [field]="f" [labels]="{ email: 'Email address' }" />
  …
</form>
```

```html
<!-- automatic -->
<form [formGroup]="form" (ngSubmit)="submit()">
  <mk-form-error-summary #summary [form]="form"
    [labels]="{ email: 'Email address', age: 'Age' }" />
  …
</form>

<!-- manual -->
<mk-form-error-summary #summary [errors]="errors()" />
…
onSubmit() { if (invalid) { this.errors.set(collect()); this.summary.focus(); } }
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `errors` | `readonly MkFormError[]` | `[]` | Errors to list explicitly. When non-empty this wins over `form`, so a form can mix automatic collection with server-side errors by not setting it. |
| `form` | `AbstractControl<any, any, any> \| null` | `null` | Collect errors from this control tree instead of passing them in. |
| `field` | `Field<unknown> \| null` | `null` | Collect errors from this Signal Forms field (usually the root returned by `form()`) instead of `form`. Entries are keyed by dotted path for `labels`. |
| `labels` | `Readonly<Record<string, string>>` | `{}` | Field names for automatic entries, keyed by control path. |
| `errorMessages` | `Readonly<Record<string, string \| ((err: any) => string)>> \| null` | `null` | Per-key wording for automatic entries, as on `mk-form-field`. |
| `showOn` | `"submit" \| "always"` | `'submit'` | When automatic entries appear. Defaults to after the form is submitted. |
| `summaryTitle` | `string` | `this.i18n.errorSummaryTitle` | Heading shown above the list. |
| `autoFocus` | `boolean` | `true` | Move focus to the summary automatically when the surrounding form is submitted with errors (the WAI/GOV.UK pattern). Disable to drive focus yourself via the public `focus()`. |

Methods:

| Signature | Description |
| --- | --- |
| `focus(): void` | Move keyboard focus to the summary (call after a failed submit). |

### MkFormField (component)

Selector: `mk-form-field`

Docs: https://mk-kit.dev/components/forms

Import: `import { MkFormField } from '@mk-kit/ui/forms';`

FormField — an accessible wrapper that provides a real `<label>`, optional
hint text, error text and a required indicator for any nested control
(`input[mkInput]`, `mk-select`, `mk-checkbox`, …).

It generates stable ids (via `mkUniqueId`) and exposes them so nested
controls can wire `aria-labelledby` / `aria-describedby` / `aria-invalid`
automatically by injecting this component. While an error shows, the hint is
hidden and the error is announced through a `role="alert"` region.

## Automatic errors

When the projected control is bound to a form (`formControlName`,
`[formControl]` or `[(ngModel)]`) the field adopts its `NgControl` and shows
the first validation error by itself — no `[error]` binding needed. Messages
come from the `validation` i18n table and can be reworded per field with
`errorMessages`. As with `mat-error`, an error only appears once the control
is touched or dirty, or its form has been submitted; `errorOn` changes that.
`required` and the disabled styling are derived from the control too.

## Signal Forms

The same applies to a control bound with Signal Forms' `[formField]`
directive (`@angular/forms/signals`): the field adopts the projected
`FormField` binding and reads `touched()` / `dirty()` / `invalid()` /
`errors()` / `required()` / `disabled()` from its `FieldState`. Errors
written by the schema (`required(p.email)`, `minLength(p.name, 2)`, …) are
rendered through the same `validation` i18n table, a `message` supplied to
the schema rule wins over the table, and `errorMessages` / `errorOn` work
unchanged. Calling `submit()` marks every field touched, so errors surface
on a failed submit exactly as with `formControlName`. When the control is
not projected (or lives deeper), point the field at it with `[field]`.

```html
<mk-form-field label="Email">
  <input mkInput type="email" [formField]="f.email" />
</mk-form-field>

<mk-form-field label="Country" [field]="f.country">
  <mk-select [formField]="f.country" [options]="countries" />
</mk-form-field>
```

```html
<!-- automatic: message + required marker come from the validators -->
<mk-form-field label="Email">
  <input mkInput type="email" formControlName="email" />
</mk-form-field>

<!-- per-field wording -->
<mk-form-field label="Age" [errorMessages]="{ min: 'You must be 18 or over' }">
  <mk-number-input formControlName="age" [min]="18" />
</mk-form-field>

<!-- fully manual: an explicit [error] always wins -->
<mk-form-field label="Email" hint="We never share it." required
  [error]="emailError()">
  <input mkInput type="email" [(ngModel)]="email" />
</mk-form-field>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `''` | Visible field label. Rendered as a real `<label for>`. |
| `hint` | `string` | `''` | Optional helper text shown below the control (hidden while an error shows). |
| `error` | `string \| null` | `null` | Explicit error message. When non-null it overrides the automatic message derived from the projected control; `''` suppresses errors entirely. |
| `errorMessages` | `Readonly<Record<string, string \| ((err: any) => string)>> \| null` | `null` | Per-field wording for automatic errors, keyed by `ValidationErrors` key. Each value is either a fixed string or a function of the error payload. |
| `errorOn` | `"always" \| "touched" \| "dirty"` | `'touched'` | When automatic errors become visible. `touched` (the default) matches Material: after the control is touched or dirty, or the form is submitted. `dirty` waits for an actual edit; `always` shows as soon as it is invalid. |
| `required` | `boolean` | `false` | Marks the field required (adds an indicator + `aria-required`). Derived from the projected control's validators when it is bound to a form. |
| `disabled` | `boolean` | `false` | Visually reflect a disabled control. Derived from the projected control when it is bound to a form. |
| `size` | `MkSize` | `'md'` | Control size; nested controls inherit it. |
| `labelPosition` | `"top" \| "float"` | `'top'` | Where the label sits: above the control (default), or `float` — inside the control, sliding up once it is focused or has a value. Floating works with `mkInput` / textarea and any control bound with `ngModel` or a `formControl`; the placeholder stays hidden until the label has moved. |
| `field` | `Field<unknown> \| null` | `null` | Signal Forms field to read state from explicitly (`[field]="f.email"`). Not needed when the projected control carries the `[formField]` binding — the wrapper finds that itself; set it when the control is nested deeper or when the wrapper should follow a field it does not contain. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `controlId` | `string` | Id for the nested interactive control — adopt on your control element. |
| `labelId` | `string` | Id of the `<label>` element (for `aria-labelledby`). |
| `hintId` | `string` | Id of the hint element. |
| `errorId` | `string` | Id of the error element. |
| `errorText` | `Signal<string \| null>` | The message actually rendered — an explicit `error` always wins. |
| `hasError` | `Signal<boolean>` | Whether the field currently has an error. |
| `isRequired` | `Signal<boolean>` | Required either explicitly or through the bound control's validators. |
| `isDisabled` | `Signal<boolean>` | Disabled either explicitly or through the bound control. |
| `hintVisible` | `Signal<boolean>` | Whether the hint should be shown (hidden while an error is present). |
| `describedBy` | `Signal<string \| null>` | Space-separated id list for a nested control's `aria-describedby`, or `null` when there is nothing to describe. |

### MkI18nInput (component)

Selector: `mk-i18n-input` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/text-inputs

Import: `import { MkI18nInput } from '@mk-kit/ui/forms';`

I18nInput — one field that edits the same text in several languages.

The common alternative is stacking one input per language, which grows the
form linearly with locale count and buries the field the author actually
cares about. This shows a single input and a compact switcher, and marks
which locales already have content so nothing is silently left untranslated.

Binds a `Record<code, string>`, so it drops into reactive forms as one
control instead of a nested group:

```html
<mk-form-field label="Name">
  <mk-i18n-input formControlName="name" [locales]="locales" />
</mk-form-field>
```

```ts
locales = [
  { code: 'en', label: 'EN', name: 'English' },
  { code: 'pl', label: 'PL', name: 'Polish' },
];
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `locales` | `readonly MkI18nLocale[]` | `[]` | Locales offered, in switcher order. The first is the initial tab. |
| `multiline` | `boolean` | `false` | Render a textarea instead of a single-line input. |
| `rows` | `number` | `3` | Textarea rows (ignored unless `multiline`). |
| `placeholder` | `string` | `''` | Placeholder for the active locale's input. |
| `size` | `MkSize` | `'md'` | Control size, forwarded to the input and the switcher. |
| `requiredLocales` | `readonly string[]` | `[]` | Locale codes that must be filled. They get a marker in the switcher while empty, so a missing translation is visible without switching to it. |
| `disabled` | `boolean` | `false` | Disable the whole control. |

### MkIbanInput (component)

Selector: `mk-iban-input` · exportAs: `mkIbanInput` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/payment

Import: `import { MkIbanInput } from '@mk-kit/ui/forms';`

IbanInput — an international bank account number field: uppercases and
groups the number in blocks of four as the user types (`PL61 1090 1014 …`),
caps input at the country's exact length (65 countries built in) and
validates with the ISO 13616 mod-97 checksum.

The form value is the compact electronic format (uppercase, no spaces).
`valid()` (via `exportAs`) reports `true`/`false` for a complete number
passing/failing validation and `null` while empty or incomplete; invalid
styling engages after the field was touched.
`mkIbanValidator()` covers reactive forms.

Implements `ControlValueAccessor` and exposes a two-way `value` model, so
`[(ngModel)]`, reactive forms and `[(value)]` all work.

```html
<mk-iban-input [(ngModel)]="account" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `placeholder` | `string` | `'PL61 1090 1014 0000 0712 1981 2874'` | Placeholder shown when empty. |
| `value` (two-way) | `string` | `''` | Two-way IBAN in compact electronic format (uppercase, no spaces). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `iban` for a number failing the mod-97 checksum — the same error `mkIbanValidator()` produces, so the two are interchangeable. An empty value passes; compose with `Validators.required` to reject it. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `valid` | `Signal<boolean \| null>` | `true` for a complete IBAN passing the mod-97 check, `false` for a complete-but-wrong one (or an unknown country once 2+ chars are typed and the field was left), `null` while empty or still incomplete. |

### MkInput (component)

Selector: `input[mkInput], textarea[mkInput]` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/text-inputs

Import: `import { MkInput } from '@mk-kit/ui/forms';`

Input — enhances a native `<input>` or `<textarea>` with mk-kit theming and
a11y wiring. It is an attribute-selector component so all native semantics
and keyboard behaviour come for free; this layers on tokenised styling, aria
state and form integration.

It provides its own `ControlValueAccessor` (over the native `value`) so
`[(ngModel)]` and reactive forms write back to the DOM reliably — including
when the bound model is reset programmatically. IME composition is buffered
so `onChange` fires once per completed character, matching Angular's built-in
`DefaultValueAccessor`.

When placed inside an `mk-form-field` it automatically adopts the field's
control id (so the `<label for>` associates), `aria-describedby`,
`aria-invalid` and `aria-required`.

```html
<input mkInput type="email" placeholder="you@example.com" />
<textarea mkInput rows="4" [invalid]="true"></textarea>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field` (inherits it). |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |

### MkInputGroup (component)

Selector: `mk-input-group`

Docs: https://mk-kit.dev/components/text-inputs

Import: `import { MkInputGroup } from '@mk-kit/ui/forms';`

InputGroup — wraps a native `input[mkInput]` with leading / trailing affixes
(icons, static text, compact buttons) inside one shared control frame. The
group carries the border, background and focus ring; the nested input
detects the group and drops its own chrome, so the whole assembly reads as
a single field.

Project affixes with the `mkInputPrefix` / `mkInputSuffix` attributes. Both
are optional; interactive suffixes (a clear or scan button) keep their own
focus behaviour.

Inside an `mk-form-field` the group inherits the field's size and invalid
state, and the field's label association still targets the inner input.

```html
<mk-input-group>
  <mk-icon mkInputPrefix name="search" />
  <input mkInput type="search" placeholder="Search…" />
</mk-input-group>

<mk-form-field label="Price">
  <mk-input-group>
    <input mkInput type="number" formControlName="price" />
    <span mkInputSuffix>zł</span>
  </mk-input-group>
</mk-form-field>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field` (inherits it). |
| `invalid` | `boolean` | `false` | Force the invalid visual when used standalone. |
| `disabled` | `boolean` | `false` | Visually reflect a disabled inner control. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `effectiveSize` | `Signal<MkSize>` | The size the group (and its nested input) renders at. |
| `isInvalid` | `Signal<boolean>` | Whether the group renders the invalid frame. |

### MkListbox (component)

Selector: `mk-listbox` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/selection

Import: `import { MkListbox } from '@mk-kit/ui/forms';`

Listbox — a standalone, always-visible selection list (the ARIA `listbox`
pattern) for one or many values: settings panes, "choose a template"
pickers, side-by-side assignments, any place a dropdown would hide choices
the user should see at once.

Keyboard: Up / Down move, Home / End jump, PageUp / PageDown skip ten,
type to jump to a label, Enter / Space select (toggle when `multiple`),
Shift+Arrow / Shift+click extend a range, Ctrl/Cmd+A selects all. Focus
stays on the list (`aria-activedescendant`). With `filterable`, a search
box above the list narrows it by label or description.

Implements `ControlValueAccessor` and a two-way `value` model — a single
value, or an array when `multiple`.

```html
<mk-listbox [options]="plans" [(value)]="plan" ariaLabel="Plan" />
<mk-listbox multiple filterable [options]="people" [(ngModel)]="reviewers" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `options` | `readonly MkListboxOption[]` | `[]` | The rows to choose from. |
| `multiple` | `boolean` | `false` | Allow several values; the model becomes an array. |
| `filterable` | `boolean` | `false` | Show a search box that narrows the list by label / description. |
| `filterPlaceholder` | `string \| undefined` | `undefined` |  |
| `selectionFollowsFocus` | `boolean` | `true` | Single-select only: moving with the arrow keys selects immediately (default `true`); `false` requires Enter / Space to commit. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `invalid` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `ariaLabel` | `string \| undefined` | `undefined` | Accessible name when there is no visible label / form field. |
| `ariaLabelledby` | `string \| undefined` | `undefined` |  |
| `emptyText` | `string \| undefined` | `undefined` | Text shown when no option matches the filter. |
| `value` (two-way) | `unknown` | `null` | Two-way value: one value, or an array when `multiple`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `unknown` | Emits when `value` changes (two-way binding). |
| `change` | `unknown` | Emitted after the user changes the selection (not on programmatic writes). |

Methods:

| Signature | Description |
| --- | --- |
| `focus(): void` | Focus the list. |

### MkMentionPanel (component)

Selector: `mk-mention-panel`

Import: `import { MkMentionPanel } from '@mk-kit/ui/forms';`

Suggestion listbox for `MkMention`. Created dynamically by the
directive and wired imperatively right after creation: the directive hands
it read-only signals (options, active index, caret anchor point) plus plain
callbacks, so the panel re-renders reactively without `setInput` churn.

The `<ul>` is promoted to the top layer by `mkAnchoredPanel` and positioned
at the caret point; this host element stays empty in place.

Not intended for direct use — the public API is the `[mkMention]` directive.

Methods:

| Signature | Description |
| --- | --- |
| `optionId(index: number): string` |  |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `anchorPoint` | `Signal<{ x: number; y: number; }>` | Caret point (viewport px) the panel is anchored to. |
| `anchorEl` | `HTMLElement \| undefined` | The mention control itself — passed as the anchored panel's element anchor so pointerdowns inside the control don't count as "outside" dismissals (the point anchor still wins for positioning). |

### MkMultiSelect (component)

Selector: `mk-multi-select` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/selection

Import: `import { MkMultiSelect } from '@mk-kit/ui/forms';`

MultiSelect — an accessible combobox that commits **multiple** values,
rendering each selection as a removable chip inside the control. Implements
the ARIA combobox + multiselectable listbox pattern.

Filtering is built in (`contains` / `startsWith`); set `filterMode="none"`
and drive `options` from the `search` output for async / server-side sources.
Selected options are remembered even after they leave the `options` list, so
chips keep their labels across async pages.

Implements `ControlValueAccessor` over an **array** value and exposes a
two-way `value` model, so it works with `[(ngModel)]`, reactive forms and
`[(value)]`. When nested in an `mk-form-field` it inherits size, label,
hint/error and required wiring.

Keyboard: type to filter, Up/Down to move, Home/End to jump, Enter/Space to
toggle the active option, Backspace on an empty query removes the last chip,
Escape closes. The dropdown renders in the top layer via
`MkAnchoredPanel` so it is never clipped by a container.

```html
<mk-multi-select placeholder="Add tags"
  [options]="tagOptions()"
  [(value)]="tags" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `''` | Accessible name when the control is used without an `mk-form-field` label. |
| `options` | `readonly MkMultiSelectOption[]` | `[]` |  |
| `placeholder` | `string` | `''` | Placeholder shown when no value is selected. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). Set by Signal Forms' `[formField]` from the schema. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `filterMode` | `MkMultiSelectFilterMode` | `'contains'` | How the option list is filtered against the typed text. |
| `minChars` | `number` | `0` | Only open the list once this many characters have been typed. |
| `loading` | `boolean` | `false` | Show a loading row instead of "no results" (for async fetches). |
| `max` | `number` | `0` | Maximum number of selections (0 = unlimited). |
| `closeOnSelect` | `boolean` | `false` | Close the dropdown after each selection. Default keeps it open. |
| `emptyMessage` | `string` | `this.i18n.noResults` | Message shown when there are no matching options. |
| `value` (two-way) | `unknown[]` | `[]` | Two-way selected values. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `unknown[]` | Emits when `value` changes (two-way binding). |
| `search` | `string` | Emits the current query text on every keystroke — drive async loading. |
| `optionAdded` | `MkMultiSelectOption` | Emits the option whenever one is added. |
| `optionRemoved` | `unknown` | Emits the value whenever a selection is removed. |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `mkMaxItems` when more options are selected than `[max]` allows. |

### MkNumberInput (component)

Selector: `mk-number-input` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/text-inputs

Import: `import { MkNumberInput } from '@mk-kit/ui/forms';`

NumberInput — a numeric field with −/+ stepper buttons, clamping and keyboard
stepping (Arrow keys / Page keys). Implements the ARIA `spinbutton` pattern
and `ControlValueAccessor` over `number | null`, with a two-way `value` model.

```html
<mk-number-input [(value)]="qty" [min]="0" [max]="99" [step]="1" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `''` | Accessible name when the control is used without an `mk-form-field` label. |
| `min` | `number \| null` | `null` |  |
| `max` | `number \| null` | `null` | Maximum value. |
| `step` | `number` | `1` | Step increment for buttons + Arrow keys. |
| `value` (two-way) | `number \| null` | `null` | Two-way value. |
| `placeholder` | `string` | `''` | Placeholder when empty. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force invalid styling when standalone. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). Set by Signal Forms' `[formField]` from the schema. |
| `size` | `MkSize` | `'md'` | Control size. Ignored inside an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `number \| null` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `min` / `max` against the `[min]` and `[max]` inputs, using the same error shapes as `Validators.min` / `Validators.max`. |

### MkNumericKeypad (component)

Selector: `mk-numeric-keypad` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/touch-keys

Import: `import { MkNumericKeypad } from '@mk-kit/ui/forms';`

Numeric keypad — a touch-first 3×4 digit pad for PIN entry, quantity entry
and money amounts (POS-style). `ControlValueAccessor` + two-way `value`
model; the value is a **string** in `pin` mode (leading zeros preserved)
and a **number | null** in `quantity`/`amount` mode.

- `pin`: masked echo row by default; `(submit)` fires automatically when
  `length` digits are entered.
- `quantity`: integer entry; the bottom-left key clears.
- `amount`: decimal entry (value uses `.`; the echo shows
  `decimalSeparator`); capped at `fractionDigits` fraction digits.

A physical keyboard works anywhere inside the pad: digits, Backspace,
Delete (clear), Enter (submit) and the decimal separator. Arrow keys move
between the on-screen keys (roving tabindex).

```html
<mk-numeric-keypad mode="pin" [length]="4" (submit)="unlock($event)" />
<mk-numeric-keypad mode="quantity" [min]="1" [(value)]="qty" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `MkNumericKeypadMode` | `'quantity'` | Entry mode. Decides the value type and the bottom-left key. |
| `length` | `number` | `4` | PIN length (`pin` mode only). Reaching it emits `submit`. |
| `min` | `number \| null` | `null` | Lower bound reported through the validator (`quantity`/`amount`). |
| `max` | `number \| null` | `null` | Upper bound reported through the validator (`quantity`/`amount`). |
| `mask` | `boolean` | `true` | Mask the echo row in `pin` mode. Default `true`. |
| `showValue` | `boolean` | `true` | Show the echo row above the keys. Default `true`. |
| `decimalSeparator` | `string` | `','` | Echo-row separator for `amount` mode. The VALUE always uses `.`. |
| `fractionDigits` | `number` | `2` | Max fraction digits accepted in `amount` mode. |
| `disabled` | `boolean` | `false` | Disable the pad. |
| `invalid` | `boolean` | `false` | Force invalid styling. |
| `ariaLabel` | `string` | `this.i18n.numericKeypadLabel` | Accessible label for the pad. |
| `value` (two-way) | `string \| number \| null` | `null` | Two-way value: `string` in `pin` mode, `number \| null` otherwise. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string \| number \| null` | Emits when `value` changes (two-way binding). |
| `submit` | `string \| number \| null` | Enter key / full PIN. Emits the current value. |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | `pin`: reports `minlength` while the code is incomplete (empty passes — compose with `Validators.required`). `quantity`/`amount`: reports `min`/`max` against the bounds. |

### MkOnScreenKeyboard (component)

Selector: `mk-on-screen-keyboard` · exportAs: `mkOnScreenKeyboard`

Docs: https://mk-kit.dev/components/touch-keys

Import: `import { MkOnScreenKeyboard } from '@mk-kit/ui/forms';`

On-screen keyboard — a touch QWERTY panel for kiosk/till screens where no
physical keyboard exists. Anchored below its input in the browser top layer
(via `MkAnchoredPanel`), it writes caret-aware into the target's
native value and dispatches `input` events, so `ngModel`/reactive forms
stay in sync with no extra wiring.

Pair it with the `mkOnScreenKeyboardFor` directive, which opens the panel
on focus and suppresses the OS keyboard (`inputmode="none"`):

```html
<input mkInput [mkOnScreenKeyboardFor]="kbd" />
<mk-on-screen-keyboard #kbd />
```

Layers: base (letters + digit row), shift (auto-resets after one
character) and an alternate layer (Polish diacritics + symbols in the
default `MK_KEYBOARD_LAYOUT_QWERTY_PL`); pass `layout` for other
languages. Enter inserts a newline in a `<textarea>` and emits `enter`
for single-line inputs. Keys are excluded from the tab order — physical
keyboards type into the input directly, the panel is a pointer surface.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `layout` | `MkKeyboardLayout` | `MK_KEYBOARD_LAYOUT_QWERTY_PL` | Key layout. Defaults to QWERTY with a Polish alternate layer. |
| `placement` | `MkPlacement` | `'bottom-start'` | Preferred placement relative to the input. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `enter` | `void` | Enter pressed on a single-line input (textareas insert a newline instead). |
| `closed` | `void` | Emitted whenever the keyboard closes (any reason). |

Methods:

| Signature | Description |
| --- | --- |
| `open(anchor: HTMLElement, target: MkOnScreenKeyboardTarget): void` | Open anchored to `anchor`, typing into `target`. |
| `close(): void` | Close the panel. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `panelId` | `string` | Stable id for `aria-controls` on the trigger. |
| `opened` | `Signal<boolean>` | Whether the panel is open. |

### MkOtp (component)

Selector: `mk-otp` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/text-inputs

Import: `import { MkOtp } from '@mk-kit/ui/forms';`

OTP — a segmented one-time-code input: N single-character boxes with automatic
focus advance, Backspace-to-previous, Arrow navigation and full-code paste.
`ControlValueAccessor` + two-way `value` model over the concatenated string.

```html
<mk-otp [(value)]="code" [length]="6" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `length` | `number` | `6` | Number of character boxes. |
| `type` | `"number" \| "text"` | `'number'` | Restrict input to digits (`number`) or allow any char (`text`). |
| `mask` | `boolean` | `false` | Mask entered characters (password style). |
| `value` (two-way) | `string` | `''` | Two-way concatenated value. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force invalid styling when standalone. |
| `size` | `MkSize` | `'md'` | Control size. Ignored inside an `mk-form-field`. |
| `ariaLabel` | `string` | `this.i18n.oneTimeCode` | Accessible label for the group. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `minlength` for a partially entered code. An empty value passes; compose with `Validators.required` to reject it. |

### MkPasswordInput (component)

Selector: `mk-password-input` · exportAs: `mkPasswordInput` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/text-inputs

Import: `import { MkPasswordInput } from '@mk-kit/ui/forms';`

PasswordInput — a password field with a reveal toggle, an optional strength
meter and an optional rules checklist. Implements `ControlValueAccessor` over
`string` with a two-way `value` model, and wires label / description /
validity a11y automatically when nested in an `mk-form-field`.

```html
<mk-password-input [(value)]="pw" showStrength showRules [minLength]="10" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `string` | `''` | Two-way value. |
| `placeholder` | `string` | `''` | Placeholder when empty. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `size` | `MkSize` | `'md'` | Control size. Ignored inside an `mk-form-field`. |
| `invalid` | `boolean` | `false` | Force invalid styling when standalone. |
| `showStrength` | `boolean` | `false` | Show the 0–4 strength meter below the field. |
| `showRules` | `boolean` | `false` | Show the rules checklist below the field. |
| `minLength` | `number` | `8` | Minimum length used by the strength score and rules. |
| `autocomplete` | `(string & {}) \| "current-password" \| "new-password"` | `'current-password'` | `autocomplete` for the native input. Use `'new-password'` on signup / change-password forms (where the strength meter and rules belong) so the browser offers a generated password instead of the saved one. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `minlength` for a password shorter than `[minLength]` — the same requirement the rules list shows. An empty value passes; compose with `Validators.required` to reject it. |

### MkPhoneInput (component)

Selector: `mk-phone-input` · exportAs: `mkPhoneInput` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/phone-postal

Import: `import { MkPhoneInput } from '@mk-kit/ui/forms';`

PhoneInput — an international telephone field: a searchable country-prefix
dropdown (flag + dial code) next to a national-number input that formats
itself with the selected country's mask as the user types.

The form value is either a single E.164 string (`"+48601234567"`, default)
or a structured object (`valueFormat="parts"`) carrying the country, dial
code and national number separately; both modes read back either shape and
`null` when empty. Pasting a full international number (`+44…`) into the
number field switches the country automatically.

Implements `ControlValueAccessor` and exposes two-way `value` and `country`
models, so `[(ngModel)]`, reactive forms, `[(value)]` and `[(country)]` all
work.

```html
<mk-phone-input [(ngModel)]="phone" country="PL" />
<mk-phone-input valueFormat="parts" [preferredCountries]="['PL','DE','CZ']"
  [(value)]="phoneParts" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `countries` | `readonly MkPhoneCountry[]` | `MK_PHONE_COUNTRIES` | The selectable country set (defaults to the built-in list). |
| `preferredCountries` | `readonly string[]` | `[]` | ISO codes pinned, in order, to the top of the dropdown. |
| `valueFormat` | `"e164" \| "parts"` | `'e164'` | Shape of the form value: an E.164 string or a structured object. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `placeholder` | `string` | `''` | Placeholder for the national-number field. |
| `country` (two-way) | `string` | `'US'` | Two-way selected ISO country code. |
| `value` (two-way) | `string \| MkPhoneValue \| null` | `null` | Two-way form value (`string` in `e164` mode, `MkPhoneValue` in `parts`). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `countryChange` | `string` | Emits when `country` changes (two-way binding). |
| `valueChange` | `string \| MkPhoneValue \| null` | Emits when `value` changes (two-way binding). |

### MkPostalCodeInput (component)

Selector: `mk-postal-code-input` · exportAs: `mkPostalCodeInput` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/phone-postal

Import: `import { MkPostalCodeInput } from '@mk-kit/ui/forms';`

PostalCodeInput — a postal/ZIP code field that masks, uppercases and
validates itself for the given `country` (35+ built-in formats: `PL`
`00-000`, `US` `00000[-0000]`, `CA` `A0A 0A0`, `NL` `0000 AA`, …).
Free-format countries (e.g. `GB`) skip the mask and validate against the
national pattern instead, normalising the inward-code space on blur.

The placeholder defaults to a valid example for the country. `valid()`
(via `exportAs`) reports `true`/`false` for a complete/incomplete code and
`null` when empty or the country is unknown; invalid styling engages after
the field is touched.

Implements `ControlValueAccessor` and exposes a two-way `value` model, so
`[(ngModel)]`, reactive forms and `[(value)]` all work.

```html
<mk-postal-code-input country="PL" [(ngModel)]="zip" />
<mk-postal-code-input [country]="form.value.country" [(value)]="zip" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `country` | `string` | `'US'` | ISO 3166-1 alpha-2 country whose format applies. |
| `formats` | `readonly MkPostalFormat[]` | `MK_POSTAL_FORMATS` | The format table (defaults to the built-in set) — extend to add countries. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `placeholder` | `string` | `''` | Placeholder; defaults to a valid example for the country. |
| `value` (two-way) | `string` | `''` | Two-way formatted value (e.g. `00-950`, `K1A 0B1`). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `postalCode` for a code not matching `[country]`'s format — the same error `mkPostalCodeValidator()` produces. Empty values and countries without a built-in format pass. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `valid` | `Signal<boolean \| null>` | `true`/`false` for a complete/incomplete code, `null` when empty or the country has no known format. |

### MkRadio (component)

Selector: `mk-radio`

Docs: https://mk-kit.dev/components/toggles

Import: `import { MkRadio } from '@mk-kit/ui/forms';`

Radio — a single option within an `mk-radio-group`. Rendered as
`role="radio"` with a roving tabindex managed by the parent group, so the
whole group is a single Tab stop and Arrow keys move between options.

Must be used as a child of `mk-radio-group`.

```html
<mk-radio [value]="'pro'">Pro plan</mk-radio>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `unknown` | `null` | The value contributed to the group when this radio is selected. |
| `disabled` | `boolean` | `false` | Disable just this radio. |

Methods:

| Signature | Description |
| --- | --- |
| `focus(): void` | Focus this radio's host element (used by the group's keyboard nav). |

### MkRadioGroup (component)

Selector: `mk-radio-group` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/toggles

Import: `import { MkRadioGroup } from '@mk-kit/ui/forms';`

RadioGroup — an ARIA `radiogroup` that coordinates projected `mk-radio`
children. It manages a single selected value with roving tabindex and
Arrow-key navigation (Up/Left = previous, Down/Right = next, wrapping and
skipping disabled radios).

Implements `ControlValueAccessor` with a two-way `value` model.

```html
<mk-radio-group [(ngModel)]="plan" aria-label="Plan">
  <mk-radio [value]="'free'">Free</mk-radio>
  <mk-radio [value]="'pro'">Pro</mk-radio>
</mk-radio-group>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `unknown` | `null` | Two-way selected value. |
| `disabled` | `boolean` | `false` | Disable the whole group. |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). |
| `size` | `MkSize` | `'md'` | Size applied to all child radios. |
| `tone` | `MkTone` | `'primary'` | Semantic color tone applied to all child radios. |
| `name` | `string` | `mkUniqueId('mk-radio')` | Shared `name` grouping (defaults to a generated unique name). |
| `orientation` | `"vertical" \| "horizontal"` | `'vertical'` | Layout direction; also sets arrow-key mapping expectations. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `unknown` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `register(radio: MkRadio): void` | Register a child radio (called from `mk-radio` on init). |
| `unregister(radio: MkRadio): void` | Unregister a child radio (called on destroy). |
| `isChecked(radio: MkRadio): boolean` | True when `radio` matches the group's current value. |
| `select(radio: MkRadio): void` | Select a radio's value (guarded by disabled state). |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `required` when `[required]` is set and no radio is selected. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `hasChecked` | `Signal<boolean>` | Whether a radio currently matches the selected value. |
| `firstEnabled` | `Signal<MkRadio \| null>` | The radio that should be tabbable when nothing is selected. |

### MkRangeSlider (component)

Selector: `mk-range-slider` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/sliders

Import: `import { MkRangeSlider } from '@mk-kit/ui/forms';`

RangeSlider — a two-thumb slider selecting a `[low, high]` range. Each thumb is
a `role="slider"` (Arrow / Page / Home / End keys); the thumbs can't cross.
Implements `ControlValueAccessor` over a `[number, number]` tuple with a
two-way `value` model.

```html
<mk-range-slider [min]="0" [max]="1000" [step]="10" [(value)]="priceRange" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `min` | `number` | `0` | Minimum value. |
| `max` | `number` | `100` | Maximum value. |
| `step` | `number` | `1` | Step increment (must be > 0). |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `size` | `MkSize` | `'md'` | Control size. |
| `tone` | `MkTone` | `'primary'` | Semantic tone for the filled range + thumbs. |
| `minLabel` | `string` | `this.i18n.minimum` | Accessible label for the low thumb. |
| `maxLabel` | `string` | `this.i18n.maximum` | Accessible label for the high thumb. |
| `value` (two-way) | `MkRange` | `[0, 100]` | Two-way `[low, high]` value. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `MkRange` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `min` / `max` for either endpoint falling outside the track. The slider clamps what the user can produce, so this only fires for a range written in from the model side. |

### MkRating (component)

Selector: `mk-rating` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/sliders

Import: `import { MkRating } from '@mk-kit/ui/forms';`

Rating — a star rating input (and read-only display). Implements the ARIA
slider pattern: one focusable control, Arrow keys adjust, Home/End jump.
Click or hover a star to set the value. `ControlValueAccessor` + two-way
`value` model over a number.

```html
<mk-rating [(value)]="score" [max]="5" />
<mk-rating [value]="4" readonly />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `max` | `number` | `5` | Number of stars. |
| `value` (two-way) | `number` | `0` | Two-way rating value (0–max). |
| `readonly` | `boolean` | `false` | Read-only display (no interaction). |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `size` | `MkSize` | `'md'` | Size scale. |
| `ariaLabel` | `string` | `this.i18n.ratingLabel` | Accessible label. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `number` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `max` for a rating above `[max]`. Zero means "unrated" and is left to `Validators.required` to reject. |

### MkRepeater (component)

Selector: `mk-repeater` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/forms#repeater

Import: `import { MkRepeater } from '@mk-kit/ui/forms';`

Repeater — the schema-friendly editable list: renders one instance of a
consumer-projected row template per item, with add / remove / (optional)
drag-and-drop + keyboard reorder built in.

`items` is a two-way model and the component also implements
`ControlValueAccessor` over `T[]`, so it drops into template-driven and
reactive forms alike. **Every mutation produces a new array** — the
consumer's array is never mutated in place.

Rows are tracked by **item object identity** (stable across the repeater's
immutable array copies), so removing a middle row keeps the following rows'
DOM — and any in-progress input state — intact. Consequently, arrays of
primitives with duplicate values (e.g. `['a', 'a']`) are not supported
directly: wrap each value in an object (`{ value: 'a' }`) so every row has
a distinct identity.

With `reorderable`, each row gets a drag handle wired through the dnd
module's touch-safe handle-based configuration (a swipe on the row body
still scrolls the page). The handle button is the only control the dnd
layer adds — rows stay plain list items, so the inputs and buttons inside
them are never nested in an interactive role. Reordering also works by
keyboard: focus the handle and press Space/Enter to pick up, arrows to
move, Space/Enter to drop, Escape to cancel. Each completed reorder is
announced via `MkLiveAnnouncer`.

```html
<mk-repeater [(items)]="rows" [min]="1" [max]="10" reorderable
             [factory]="newRow" addLabel="Add row">
  <ng-template mkRepeaterRow let-item let-i="index">
    <input mkInput [(ngModel)]="item.name" />
  </ng-template>
  <ng-template mkRepeaterEmpty>No rows yet.</ng-template>
</mk-repeater>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (two-way) | `T[]` | `[]` | The rows (two-way). Every mutation sets a **new** array. |
| `factory` | `() => T` | `() => ({}) as T` | Creates the item appended by the add button. Default: `{}` cast to `T`. |
| `min` | `number` | `0` | Minimum number of rows — remove buttons disable at (or below) it. |
| `max` | `number` | `0` | Maximum number of rows (0 = unlimited) — the add button disables at it. |
| `reorderable` | `boolean` | `false` | Enable per-row drag handles (pointer + keyboard reorder). |
| `disabled` | `boolean` | `false` | Disable the whole control (add, remove and reorder). |
| `addLabel` | `string` | `''` | Add-button caption. Defaults to the i18n `repeaterAddRow` string. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `itemsChange` | `T[]` | Emits when `items` changes (two-way binding). |
| `added` | `{ item: T; index: number; }` | Emitted after the add button appended a factory-made item. |
| `removed` | `{ item: T; index: number; }` | Emitted after a row was removed. |
| `moved` | `{ from: number; to: number; }` | Emitted after a row was reordered (drag or keyboard). |

### MkSelect (component)

Selector: `mk-select` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/forms

Import: `import { MkSelect } from '@mk-kit/ui/forms';`

Select — a fully custom, accessible single-select implementing the ARIA
listbox/combobox pattern. Options are supplied via the `options` input.

Keyboard: Up/Down to move, Home/End to jump, Enter/Space to select, Esc to
close, and typeahead by typing option text. Focus stays on the trigger
(`aria-activedescendant` pattern) for robust screen-reader behaviour.

Implements `ControlValueAccessor` and exposes a two-way `value` model, so it
works with `[(ngModel)]`, reactive forms and `[(value)]`.

```html
<mk-select placeholder="Pick a role"
  [options]="[{label:'Admin', value:'admin'}, {label:'Editor', value:'editor'}]"
  [(ngModel)]="role" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | `''` | Accessible name when the control is used without an `mk-form-field` label. |
| `options` | `readonly MkSelectOption[]` | `[]` |  |
| `placeholder` | `string` | `this.i18n.selectPlaceholder` | Placeholder shown when nothing is selected. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). Set by Signal Forms' `[formField]` from the schema. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `value` (two-way) | `unknown` | `null` | Two-way selected value. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `unknown` | Emits when `value` changes (two-way binding). |

### MkSignaturePad (component)

Selector: `mk-signature-pad` · exportAs: `mkSignaturePad` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/signature

Import: `import { MkSignaturePad } from '@mk-kit/ui/forms';`

SignaturePad — a canvas the user draws a signature on (pointer, touch or
pen). Strokes are captured as smoothed polylines, rendered crisp on hi-DPI
screens and re-drawn losslessly when the pad resizes. The form value is a
PNG data-URL of the drawing (`null` while empty), so it drops straight into
an `<img>`, a form post or an upload.

A Clear control resets the pad (also available as `clear()`); `isEmpty()`
reports whether anything is drawn. Programmatic values (`writeValue`,
`[value]`) are painted onto the canvas as an image.

Drawing is inherently pointer-based; pair the pad with an alternative flow
(e.g. a typed-name checkbox) where WCAG requires a keyboard equivalent.

Implements `ControlValueAccessor` and exposes a two-way `value` model, so
`[(ngModel)]`, reactive forms and `[(value)]` all work.

```html
<mk-signature-pad [(ngModel)]="signature" />
<img [src]="signature" alt="Captured signature" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `strokeWidth` | `number` | `2` | Stroke width in CSS pixels. |
| `height` | `number` | `160` | Pad height in CSS pixels (width follows the container). |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `value` (two-way) | `string \| null` | `null` | Two-way PNG data-URL of the signature (`null` while empty). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string \| null` | Emits when `value` changes (two-way binding). |
| `cleared` | `void` | Emits when the pad is cleared (via the button or `clear()`). |

Methods:

| Signature | Description |
| --- | --- |
| `clear(): void` | Clear the drawing (and the form value). |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `isEmpty` | `Signal<boolean>` | Whether nothing is drawn yet. |

### MkSlider (component)

Selector: `mk-slider` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/sliders

Import: `import { MkSlider } from '@mk-kit/ui/forms';`

Slider — a single-value range slider with `role="slider"`, a filled track and
a draggable thumb (pointer events). Fully keyboard operable: Arrow keys step,
Page Up/Down take larger steps, Home/End jump to the bounds.

Implements `ControlValueAccessor` with a two-way `value` model, so it works
with `[(ngModel)]`, reactive forms and `[(value)]`.

```html
<mk-slider [min]="0" [max]="100" [step]="5" [(ngModel)]="volume" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `min` | `number` | `0` | Minimum value. |
| `max` | `number` | `100` | Maximum value. |
| `step` | `number` | `1` | Step increment (must be > 0). |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). Set by Signal Forms' `[formField]` from the schema. |
| `size` | `MkSize` | `'md'` | Control size (track/thumb thickness). |
| `tone` | `MkTone` | `'primary'` | Semantic color tone for the filled track + thumb. |
| `aria-label` | `string` | `''` | Accessible label for the thumb. |
| `value` (two-way) | `number` | `0` | Two-way current value. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `number` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `min` / `max` for a value outside the track. The slider clamps what the user can produce, so this only fires for a value written in from the model side. |

### MkSubmitInput (component)

Selector: `mk-submit-input` · exportAs: `mkSubmitInput` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/forms

Import: `import { MkSubmitInput } from '@mk-kit/ui/forms';`

SubmitInput — a short text entry and its action button rendered as one
connected control: the "type a code and apply it" pattern (discount codes,
gift cards, invite codes, newsletter sign-up, quick search).

The button is disabled while the value is empty or blank, shows a spinner
while `loading` and emits `submitted` with the **trimmed** value on
click or on Enter.

## Enter never submits the surrounding form

This control is normally dropped inside a bigger form (a checkout, a
settings page), where triggering that form's submit would be a bug. So the
action button is a `type="button"` and, while `submitOnEnter` is on, the
Enter keydown is `preventDefault()`-ed — implicit form submission never
fires. Set `submitOnEnter="false"` to restore the native behaviour and let
Enter reach the enclosing form.

## Button content

The button is configured, not projected: `buttonLabel` sets its text.
Passing `buttonIcon` (a registered `MkIcon` name) switches it to the
square icon-only variant, where `buttonLabel` becomes its `aria-label` — so
the action always has an accessible name.

Implements `ControlValueAccessor` and exposes a two-way `value` model, so
`[(ngModel)]`, reactive forms and `[(value)]` all work.

```html
<mk-submit-input
  [(value)]="code"
  buttonLabel="Apply"
  [loading]="applying()"
  placeholder="SUMMER10"
  clearable
  (submitted)="apply($event)"
/>

<!-- icon-only, inside a field -->
<mk-form-field label="Search">
  <mk-submit-input buttonIcon="search" buttonLabel="Search" [(ngModel)]="q" />
</mk-form-field>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `disabled` | `boolean` | `false` | Disable the whole control (input + button). |
| `placeholder` | `string` | `''` | Placeholder shown when empty. |
| `label` | `string` | `''` | Accessible name for the inner input when the control is used outside an `mk-form-field` (inside one, the field's `<label>` wins). Defaults to the button's caption. |
| `type` | `string` | `'text'` | Native `type` of the inner input (`text`, `search`, `email`, …). |
| `autocomplete` | `string` | `'off'` | Native `autocomplete` hint for the inner input. |
| `value` (two-way) | `string` | `''` | Two-way value. `submitted` emits it trimmed; the model keeps what was typed. |
| `buttonLabel` | `string` | `''` | Button text — or, with `buttonIcon`, the icon button's `aria-label`. |
| `buttonIcon` | `string` | `''` | Registered icon name; switches the button to the icon-only variant. |
| `buttonVariant` | `MkVariant` | `'solid'` | Button visual treatment. |
| `buttonTone` | `MkTone` | `'primary'` | Button colour tone. |
| `loading` | `boolean` | `false` | Shows a spinner in the button and blocks submitting while an action runs. |
| `clearable` | `boolean` | `false` | Show a clear affix while the value is non-empty. |
| `submitOnEnter` | `boolean` | `true` | Submit on Enter, without submitting an enclosing `<form>`. Turn it off to let Enter bubble to the form as the browser normally would. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |
| `submitted` | `string` | Emits the current value, trimmed, when the action is triggered. |

Methods:

| Signature | Description |
| --- | --- |
| `submit(): void` | Emit `submitted` with the trimmed value, when the control allows it. |
| `clear(): void` | Clear the value and return focus to the input. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `inputId` | `string` | Id of the inner input — the `<label for>` target inside an `mk-form-field`. |

### MkSwitch (component)

Selector: `mk-switch` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/toggles

Import: `import { MkSwitch } from '@mk-kit/ui/forms';`

Switch — a toggle with `role="switch"` and an animated knob. Operable with
Space/Enter, projects its label, and supports size + tone.

Implements `ControlValueAccessor` with a two-way `checked` model, so it works
with `[(ngModel)]`, reactive forms and `[(checked)]`.

```html
<mk-switch [(ngModel)]="notify">Email notifications</mk-switch>
<mk-switch [(checked)]="dark" tone="success" size="lg">Dark mode</mk-switch>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` (two-way) | `boolean` | `false` | Two-way checked (on/off) state. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). Set by Signal Forms' `[formField]` from the schema. |
| `size` | `MkSize` | `'md'` | Control size. |
| `tone` | `MkTone` | `'primary'` | Semantic color tone for the "on" track. |
| `aria-label` | `string` | `''` | Accessible label when no text content is projected. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `checkedChange` | `boolean` | Emits when `checked` changes (two-way binding). |

### MkTagInput (component)

Selector: `mk-tag-input` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/selection

Import: `import { MkTagInput } from '@mk-kit/ui/forms';`

TagInput — a freeform token input: type a value and press Enter (or a
separator) to add it as a removable chip. Backspace on an empty field removes
the last tag, and pasting a delimited string adds several at once. Unlike
`mk-multi-select` the tags are not drawn from a fixed option list. Implements
`ControlValueAccessor` + a two-way `value` model of `string[]`.

```html
<mk-tag-input placeholder="Add tags…" [(value)]="tags" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `string[]` | `[]` | Two-way list of tags. |
| `placeholder` | `string` | `''` | Placeholder shown in the text field. |
| `max` | `number` | `0` | Maximum number of tags (0 = unlimited). |
| `allowDuplicates` | `boolean` | `false` | Allow the same tag more than once. |
| `addOnBlur` | `boolean` | `false` | Commit the pending text as a tag when the field loses focus. |
| `separators` | `readonly string[]` | `[',']` | Extra characters that commit the pending text (Enter always does). A pasted string is split on these too. Default: comma. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). Set by Signal Forms' `[formField]` from the schema. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string[]` | Emits when `value` changes (two-way binding). |
| `added` | `string` | Emitted when a tag is added. |
| `removed` | `string` | Emitted when a tag is removed. |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `mkMaxItems` when more tags are present than `[max]` allows. |

### MkTaxIdInput (component)

Selector: `mk-tax-id-input` · exportAs: `mkTaxIdInput` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/payment

Import: `import { MkTaxIdInput } from '@mk-kit/ui/forms';`

TaxIdInput — a business tax-identifier field that masks and validates itself
for the given `country` (`PL` NIP `000-000-00-00`, `DE` USt-IdNr., `CZ` DIČ,
`IT` Partita IVA, `SK` IČ DPH). Poland's NIP is checksum-verified; the other
built-ins are shape-verified.

Like `MkIbanInput`, the form value is the **compact** identifier (digits
only, e.g. `1234563218`) while the field *displays* it masked
(`123-456-32-18`) — so what is stored is what an API or invoice expects, and
`writeValue()` accepts either form. The placeholder defaults to a valid
example for the country. `valid()` (via `exportAs`) reports `true`/`false`
for a complete identifier passing/failing validation and `null` while empty,
still incomplete or the country is unknown; invalid styling engages after
the field was touched. `mkTaxIdValidator()` covers reactive forms.

Implements `ControlValueAccessor` and exposes a two-way `value` model, so
`[(ngModel)]`, reactive forms and `[(value)]` all work.

```html
<mk-tax-id-input [(ngModel)]="nip" />
<mk-tax-id-input [country]="form.value.country" [(value)]="taxId" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `country` | `string` | `'PL'` | ISO 3166-1 alpha-2 country whose format applies. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `placeholder` | `string` | `''` | Placeholder; defaults to a valid example for the country. |
| `value` (two-way) | `string` | `''` | Two-way identifier in compact form (digits only, e.g. `1234563218`). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `taxId` for an identifier not matching `[country]`'s format or failing its checksum — the same error `mkTaxIdValidator()` produces, so the two are interchangeable. Empty values and unknown countries pass; compose with `Validators.required` to reject an empty one. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `valid` | `Signal<boolean \| null>` | `true` for a complete identifier passing its format (and checksum), `false` for a complete-but-wrong one, `null` while empty, still shorter than the mask allows, or the country has no known format. |

### MkTransferList (component)

Selector: `mk-transfer-list` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/selection

Import: `import { MkTransferList } from '@mk-kit/ui/forms';`

TransferList — a dual list box (a.k.a. pick list) for moving items between an
**available** list and a **selected** list, e.g. assigning roles or
permissions. The user checks rows in one list then clicks the middle move
buttons (or presses Enter on a row) to shuttle them across.

Implements `ControlValueAccessor` over an **array** value (the values in the
selected list) and exposes a two-way `value` model, so it works with
`[(ngModel)]`, reactive forms and `[(value)]`. When nested in an
`mk-form-field` it inherits size and label wiring.

Keyboard: each listbox is a single tab stop (roving tabindex). Arrow Up/Down
and Home/End move between rows, Space toggles a row's check and Enter moves
it to the opposite list.

```html
<mk-transfer-list filterable
  [items]="allRoles()"
  [(value)]="assignedRoles"
  availableLabel="All roles"
  selectedLabel="Assigned" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `readonly MkTransferItem[]` | `[]` | The full set of items to shuttle between the two lists. |
| `availableLabel` | `string` | `this.i18n.available` | Heading for the left (available) list. |
| `selectedLabel` | `string` | `this.i18n.selected` | Heading for the right (selected) list. |
| `filterable` | `boolean` | `false` | Show a search box over each list. |
| `disabled` | `boolean` | `false` | Disable the whole control. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid` when used standalone. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |
| `value` (two-way) | `unknown[]` | `[]` | Two-way values currently in the selected (right) list. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `unknown[]` | Emits when `value` changes (two-way binding). |
| `change` | `unknown[]` | Emits the new selected values whenever items are moved. |

### MkTreeSelect (component)

Selector: `mk-tree-select` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/selection

Import: `import { MkTreeSelect } from '@mk-kit/ui/forms';`

TreeSelect — a form field whose popover contains a hierarchical
`MkTree`. The trigger shows the selected node's label (or a
placeholder); opening it reveals a selectable tree rendered in the top layer
via `MkAnchoredPanel`, so it is never clipped. Choosing a node sets the
value to that node's `value` (or the node itself when `value` is unset),
closes the panel and restores focus to the trigger. Implements
`ControlValueAccessor` and a two-way `value` model.

```html
<mk-tree-select [nodes]="tree" [(value)]="picked" clearable />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `readonly MkTreeNode[]` | `[]` | The hierarchical data to render in the panel. |
| `value` (two-way) | `unknown` | `null` | Two-way selected value (a node's `value`, or the node itself if unset). |
| `placeholder` | `string` | `this.i18n.selectPlaceholder` | Placeholder shown when nothing is selected. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `clearable` | `boolean` | `false` | Show a clear button when a value is selected. |
| `invalid` | `boolean` | `false` | Force invalid styling. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `unknown` | Emits when `value` changes (two-way binding). |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `valueId` | `string` | Id of the rendered value/placeholder span, appended to `aria-labelledby`. |

### MkMention (directive)

Selector: `textarea[mkMention], input[mkMention]` · exportAs: `mkMention`

Docs: https://mk-kit.dev/components/selection#mention

Import: `import { MkMention } from '@mk-kit/ui/forms';`

Mention / hashtag autocomplete for a **native** `<textarea>` or text
`<input>`. Typing a trigger character (`@`, `#`, …) at the start of a word
opens a top-layer suggestion panel anchored at the caret; picking an option
replaces the trigger-plus-query with the completed mention and dispatches an
`input` event so `ngModel`/reactive-forms bindings stay in sync.

The element keeps its native textbox semantics — no `role="combobox"` — and
follows the ARIA activedescendant pattern while the panel is open
(`aria-autocomplete="list"`, `aria-controls`, `aria-expanded`,
`aria-activedescendant`).

Filtering is built in (`contains` / `startsWith` over label + value); set
`mentionFilter="none"` and drive `mentionOptions` from the `mentionSearch`
output for async/server-side suggestions (`mentionLoading` keeps the panel
open with a spinner while results are in flight).

```html
<textarea mkMention
  [mentionTriggers]="['@', '#']"
  [mentionOptions]="users"
  (mentionSelect)="onPick($event)"
></textarea>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mentionTriggers` | `readonly string[]` | `['@']` | Single characters that start a mention session. |
| `mentionOptions` | `readonly MkMentionOption[]` | `[]` | The suggestion pool. Update it from `mentionSearch` for async sources. |
| `mentionFilter` | `MkMentionFilterMode` | `'contains'` | How suggestions are filtered against the typed query. |
| `mentionLoading` | `boolean` | `false` | Keep the panel open with a loading row while async results are pending. |
| `mentionInsert` | `((option: MkMentionOption, trigger: string) => string) \| null` | `null` | Builds the text inserted for a picked option. Defaults to `` `${trigger}${option.label} ` `` (note the trailing space). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `mentionSearch` | `MkMentionSearchEvent` | Emits `{trigger, query}` whenever the active query changes — drive async loading. |
| `mentionSelect` | `MkMentionSelectEvent` | Emits after an option has been inserted into the control. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `listId` | `string` | Id of the listbox panel, wired to `aria-controls` while open. |

### MkOnScreenKeyboardTrigger (directive)

Selector: `input[mkOnScreenKeyboardFor], textarea[mkOnScreenKeyboardFor]` · exportAs: `mkOnScreenKeyboardTrigger`

Docs: https://mk-kit.dev/components/touch-keys

Import: `import { MkOnScreenKeyboardTrigger } from '@mk-kit/ui/forms';`

Binds an `<input>`/`<textarea>` to an `MkOnScreenKeyboard`: opens the
panel on focus/click, closes it when focus leaves, and sets
`inputmode="none"` so touch devices don't raise the OS keyboard on top of
it. Disabled/readonly fields never open the panel.

```html
<input mkInput [mkOnScreenKeyboardFor]="kbd" />
<mk-on-screen-keyboard #kbd />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkOnScreenKeyboardFor` (required) | `MkOnScreenKeyboard` |  | The keyboard instance to open for this field. |

### MkRepeaterEmpty (directive)

Selector: `[mkRepeaterEmpty]`

Docs: https://mk-kit.dev/components/forms#repeater

Import: `import { MkRepeaterEmpty } from '@mk-kit/ui/forms';`

Marks an `<ng-template>` as `MkRepeater`'s custom empty state, shown
instead of the row list while there are no items.

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `template` | `TemplateRef<any>` | The projected empty-state template. |

### MkRepeaterRow (directive)

Selector: `[mkRepeaterRow]`

Docs: https://mk-kit.dev/components/forms#repeater

Import: `import { MkRepeaterRow } from '@mk-kit/ui/forms';`

Marks an `<ng-template>` as the row template for `MkRepeater`. The
template receives the item as its implicit context plus its `index`:

```html
<ng-template mkRepeaterRow let-item let-i="index">
  <input mkInput [(ngModel)]="item.name" />
</ng-template>
```

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `template` | `TemplateRef<MkRepeaterRowContext<T>>` | The projected row template, rendered once per item. |

### mkCountryFlag (function)

Import: `import { mkCountryFlag } from '@mk-kit/ui/forms';`

Regional-indicator flag emoji for an ISO 3166-1 alpha-2 code.

```ts
function mkCountryFlag(code: string): string
```

### mkDetectCardBrand (function)

Import: `import { mkDetectCardBrand } from '@mk-kit/ui/forms';`

Detect the card network from the leading digits — `detectCardBrand` from `@mk-kit/validators`.

```ts
function mkDetectCardBrand(digits: string): MkCardBrand | null
```

### mkHighlight (function)

Import: `import { mkHighlight } from '@mk-kit/ui/forms';`

Highlight `src` for `language`, falling back to escaped plain text.

```ts
function mkHighlight(src: string, language: string): string
```

### mkIbanChecksum (function)

Import: `import { mkIbanChecksum } from '@mk-kit/ui/forms';`

ISO 7064 MOD 97-10 over a compact (uppercase, no separators) IBAN.

```ts
function mkIbanChecksum(compact: string): boolean
```

### mkIbanIsValid (function)

Import: `import { mkIbanIsValid } from '@mk-kit/ui/forms';`

Shape, the registry length for the country and the checksum — delegates
to `isIban` from `@mk-kit/validators`. Unlike that function this one keeps
the input kit's stricter rule that the country must be in the table.

```ts
function mkIbanIsValid(compact: string): boolean
```

### mkIbanValidator (function)

Import: `import { mkIbanValidator } from '@mk-kit/ui/forms';`

Reactive-forms validator for an IBAN (any supported country). Empty values
pass (compose with `Validators.required`); the error carries the country
and its expected length when known.

```ts
account: ['', [Validators.required, mkIbanValidator()]]
```

```ts
function mkIbanValidator(): ValidatorFn
```

### mkLuhnCheck (function)

Import: `import { mkLuhnCheck } from '@mk-kit/ui/forms';`

Luhn (mod 10) checksum over a digit string — `isLuhn` from `@mk-kit/validators`.

```ts
function mkLuhnCheck(digits: string): boolean
```

### mkNipChecksum (function)

Import: `import { mkNipChecksum } from '@mk-kit/ui/forms';`

Polish NIP checksum — delegates to `isNip` from `@mk-kit/validators`
(weights 6-5-7-2-3-4-5-6-7 mod 11; a remainder of 10 is invalid).

```ts
function mkNipChecksum(compact: string): boolean
```

### mkPostalCodeValidator (function)

Import: `import { mkPostalCodeValidator } from '@mk-kit/ui/forms';`

Reactive-forms validator for a postal code in a given country. Empty values
pass (compose with `Validators.required`); countries without a built-in
format pass everything.

```ts
zip: ['', [Validators.required, mkPostalCodeValidator('PL')]]
```

```ts
function mkPostalCodeValidator(country: string, formats?: readonly MkPostalFormat[]): ValidatorFn
```

### mkPostalFormat (function)

Import: `import { mkPostalFormat } from '@mk-kit/ui/forms';`

Look up the built-in format for an ISO country code (case-insensitive).

```ts
function mkPostalFormat(code: string): MkPostalFormat | undefined
```

### mkTaxIdFormat (function)

Import: `import { mkTaxIdFormat } from '@mk-kit/ui/forms';`

Look up the built-in format for an ISO country code (case-insensitive).

```ts
function mkTaxIdFormat(country: string): MkTaxIdFormat | undefined
```

### mkTaxIdIsValid (function)

Import: `import { mkTaxIdIsValid } from '@mk-kit/ui/forms';`

Full validity for a country: shape plus the national checksum when the
format defines one. Masked and compact input are both accepted; unknown
countries have no rule to fail, so they pass.

```ts
function mkTaxIdIsValid(value: string, country: string): boolean
```

### mkTaxIdValidator (function)

Import: `import { mkTaxIdValidator } from '@mk-kit/ui/forms';`

Reactive-forms validator for a business tax identifier in a given country.
Empty values pass (compose with `Validators.required`); countries without a
built-in format pass everything.

```ts
nip: ['', [Validators.required, mkTaxIdValidator('PL')]]
```

```ts
function mkTaxIdValidator(country: string): ValidatorFn
```

### MK_CARD_BRAND_NAMES (const)

Import: `import { MK_CARD_BRAND_NAMES } from '@mk-kit/ui/forms';`

Human-readable names for the recognised brands.

```ts
const MK_CARD_BRAND_NAMES: Record<MkCardBrand, string>;
```

### MK_IBAN_LENGTHS (const)

Import: `import { MK_IBAN_LENGTHS } from '@mk-kit/ui/forms';`

IBAN lengths per country — re-exported from `@mk-kit/validators`
(`IBAN_LENGTHS`, the SWIFT registry).

```ts
const MK_IBAN_LENGTHS: Readonly<Record<string, number>>;
```

### MK_KEYBOARD_LAYOUT_QWERTY_PL (const)

Import: `import { MK_KEYBOARD_LAYOUT_QWERTY_PL } from '@mk-kit/ui/forms';`

QWERTY with a Polish alternate layer (programmer-Polish convention: base
letters are plain QWERTY, diacritics sit on the `?ąę` layer along with the
common symbols).

```ts
const MK_KEYBOARD_LAYOUT_QWERTY_PL: MkKeyboardLayout;
```

### MK_PHONE_COUNTRIES (const)

Import: `import { MK_PHONE_COUNTRIES } from '@mk-kit/ui/forms';`

The built-in country set (alphabetical by ISO code).

```ts
const MK_PHONE_COUNTRIES: readonly MkPhoneCountry[];
```

### MK_POSTAL_FORMATS (const)

Import: `import { MK_POSTAL_FORMATS } from '@mk-kit/ui/forms';`

The built-in postal formats (alphabetical by ISO code).

```ts
const MK_POSTAL_FORMATS: readonly MkPostalFormat[];
```

### MK_TAX_ID_FORMATS (const)

Import: `import { MK_TAX_ID_FORMATS } from '@mk-kit/ui/forms';`

The built-in tax-identifier formats (alphabetical by ISO code). Only Poland
carries a checksum; the rest are length/shape checks, which is what the
national registries publish without ambiguity.

```ts
const MK_TAX_ID_FORMATS: readonly MkTaxIdFormat[];
```

### MkAutocompleteOption (interface)

Import: `import { MkAutocompleteOption } from '@mk-kit/ui/forms';`

A single suggestion for `MkAutocomplete`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Text shown to the user and used as the input display value when chosen. |
| `value` | `unknown` | The value bound to the form control when this option is selected. |
| `disabled`? | `boolean \| undefined` | Disable the option (skipped by keyboard + not selectable). |
| `description`? | `string \| undefined` | Muted second line under the label — the disambiguator when labels can collide (two customers named Jan Kowalski, telling accounts apart by email, an id under a product name). |

### MkCascaderOption (interface)

Import: `import { MkCascaderOption } from '@mk-kit/ui/forms';`

One node of a cascader: a leaf, or a parent with `children`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` |  |
| `value` | `unknown` |  |
| `children`? | `readonly MkCascaderOption[] \| undefined` |  |
| `disabled`? | `boolean \| undefined` |  |

### MkCodeValidity (interface)

Import: `import { MkCodeValidity } from '@mk-kit/ui/forms';`

The validity of the editor's current content.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `valid` | `boolean` |  |
| `error` | `string \| null` | Parser error message, or `null` when valid / not validated. |

### MkFormError (interface)

Import: `import { MkFormError } from '@mk-kit/ui/forms';`

One field-level error to surface in `MkFormErrorSummary`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `fieldId` | `string` | The `id` of the control (or `mk-form-field`'s `controlId`) the message refers to. Clicking the summary entry focuses this element. |
| `message` | `string` | The human-readable error message. |

### MkI18nLocale (interface)

Import: `import { MkI18nLocale } from '@mk-kit/ui/forms';`

One translatable locale offered by `MkI18nInput`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `code` | `string` | Value key in the bound record, e.g. `pl`. |
| `label` | `string` | Short switcher label, e.g. `PL`. |
| `name`? | `string \| undefined` | Longer name for the accessible label, e.g. `Polish`. |

### MkKeyboardActionKey (interface)

Import: `import { MkKeyboardActionKey } from '@mk-kit/ui/forms';`

Non-character keys. `span` stretches the key across extra grid columns.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `action` | `"shift" \| "backspace" \| "space" \| "enter" \| "layer"` |  |
| `span`? | `number \| undefined` |  |

### MkKeyboardLayout (interface)

Import: `import { MkKeyboardLayout } from '@mk-kit/ui/forms';`

Members:

| Name | Type | Description |
| --- | --- | --- |
| `base` | `readonly (readonly MkKeyboardKey[])[]` | Letter layer. |
| `alt` | `readonly (readonly MkKeyboardKey[])[]` | Alternate layer (digits live in the base top row; this holds diacritics + symbols). |
| `shiftMap`? | `Readonly<Record<string, string>> \| undefined` | Overrides for shifted characters; missing keys fall back to `toUpperCase()`. |

### MkListboxOption (interface)

Import: `import { MkListboxOption } from '@mk-kit/ui/forms';`

One row of an `mk-listbox`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Text shown (and matched by typeahead / the filter). |
| `value` | `unknown` | Value committed to the model when selected. |
| `description`? | `string \| undefined` | Secondary line under the label. |
| `disabled`? | `boolean \| undefined` | Skipped by keyboard, not selectable. |
| `group`? | `string \| undefined` | Options sharing a `group` render under one heading (keep them adjacent). |

### MkMentionOption (interface)

Import: `import { MkMentionOption } from '@mk-kit/ui/forms';`

A single suggestion offered by `MkMention`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | Machine identifier (username, tag slug) — also matched when filtering. |
| `label` | `string` | Text shown in the panel; the default insertion writes `trigger + label`. |
| `hint`? | `string \| undefined` | Muted, single-line disambiguator shown after the label (e-mail, count…). |
| `trigger`? | `string \| undefined` | Offer this option for one trigger character only (e.g. `'#'` for tags). Options without a `trigger` are offered for every trigger. |

### MkMentionSearchEvent (interface)

Import: `import { MkMentionSearchEvent } from '@mk-kit/ui/forms';`

Payload of `MkMention.mentionSearch`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `trigger` | `string` | The trigger character that opened the session (`'@'`, `'#'`, …). |
| `query` | `string` | Text typed between the trigger and the caret. |

### MkMentionSelectEvent (interface)

Import: `import { MkMentionSelectEvent } from '@mk-kit/ui/forms';`

Payload of `MkMention.mentionSelect`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `option` | `MkMentionOption` |  |
| `trigger` | `string` |  |

### MkMultiSelectOption (interface)

Import: `import { MkMultiSelectOption } from '@mk-kit/ui/forms';`

A single selectable option for `MkMultiSelect`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Text shown to the user (and used for the chip + typeahead). |
| `value` | `unknown` | The value committed to the form control when chosen. |
| `disabled`? | `boolean \| undefined` | Disable the option (skipped by keyboard + not selectable). |

### MkPasswordRule (interface)

Import: `import { MkPasswordRule } from '@mk-kit/ui/forms';`

A single password rule with its current pass/fail state.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `"number" \| "symbol" \| "length" \| "uppercase"` |  |
| `label` | `string` |  |
| `met` | `boolean` |  |

### MkPhoneCountry (interface)

Import: `import { MkPhoneCountry } from '@mk-kit/ui/forms';`

Per-country dialing metadata for `MkPhoneInput`.

`mask` is an `mkApplyMask`-style pattern for the **national** number
(`0` = digit, everything else is a literal). Masks follow the most common
national formatting; countries with several plan lengths use their longest
common mobile format. The set covers the countries an admin product is
likely to meet — extend or replace it via the `countries` input.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `code` | `string` | ISO 3166-1 alpha-2 code, uppercase (drives the flag + display name). |
| `dialCode` | `string` | International dialing code, digits only (no `+`). |
| `mask` | `string` | Mask for the national number, `0` = digit. |

### MkPhoneValue (interface)

Import: `import { MkPhoneValue } from '@mk-kit/ui/forms';`

Structured value emitted by `MkPhoneInput` in `parts` mode.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `country` | `string` | ISO 3166-1 alpha-2 country code, e.g. `PL`. |
| `dialCode` | `string` | Dialing prefix with the leading `+`, e.g. `+48`. |
| `national` | `string` | National number, digits only. |
| `e164` | `string` | The full E.164 number, e.g. `+48601234567`. |

### MkPostalFormat (interface)

Import: `import { MkPostalFormat } from '@mk-kit/ui/forms';`

Per-country postal-code formats for `MkPostalCodeInput`.

`mask` is an `mkApplyMask`-style pattern (`0` = digit, `A` = letter,
`*` = alphanumeric, everything else a literal). `pattern` validates the
complete formatted value. Countries whose codes vary too much for a fixed
mask (e.g. GB) omit `mask` and rely on `pattern` + uppercasing alone.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `code` | `string` | ISO 3166-1 alpha-2 code, uppercase. |
| `mask`? | `string \| undefined` | Input mask; omitted for free-form (variable-length) codes. |
| `pattern` | `RegExp` | Regex the complete formatted value must match to be valid. |
| `example` | `string` | Example of a valid code, used as the default placeholder. |

### MkRepeaterRowContext (interface)

Import: `import { MkRepeaterRowContext } from '@mk-kit/ui/forms';`

Template context for a `MkRepeaterRow` row template.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `$implicit` | `T` | The row's item — destructure with `let-item`. |
| `index` | `number` | The row's current index — destructure with `let-i="index"`. |

### MkSelectOption (interface)

Import: `import { MkSelectOption } from '@mk-kit/ui/forms';`

A single selectable option for `MkSelect`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Text shown to the user (and used for typeahead). |
| `value` | `unknown` | The value bound to the form control when chosen. |
| `disabled`? | `boolean \| undefined` | Disable the option (skipped by keyboard + not selectable). |

### MkTaxIdFormat (interface)

Import: `import { MkTaxIdFormat } from '@mk-kit/ui/forms';`

Per-country business tax-identifier format for `MkTaxIdInput`.

`mask` is an `mkApplyMask` pattern (`0` = digit; every built-in format is
digits only). `compact` validates the unmasked value — the form value —
and `validate` adds the national checksum where one exists and is
unambiguous. Formats without a `validate` are pattern-checked only.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `country` | `string` | ISO 3166-1 alpha-2 code, uppercase. |
| `label` | `string` | Local name of the identifier, e.g. `NIP`. |
| `mask` | `string` | Input mask; `0` = digit. |
| `compact` | `RegExp` | Regex the complete unmasked (compact) value must match. |
| `example` | `string` | Example of a valid identifier, used as the default placeholder. |
| `validate`? | `((compact: string) => boolean) \| undefined` | National checksum over the compact value; omitted when there is none. |

### MkTransferItem (interface)

Import: `import { MkTransferItem } from '@mk-kit/ui/forms';`

A single transferable item for `MkTransferList`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `value` | `unknown` | The value committed to the form control when the item is in the selected list. |
| `label` | `string` | Text shown to the user. |
| `disabled`? | `boolean \| undefined` | Disable the item (cannot be checked or moved). |

### MkTreeNode (interface)

Import: `import { MkTreeNode } from '@mk-kit/ui/forms';`

A node in an `MkTree`. `children` makes it expandable.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Text shown for the node. |
| `value`? | `unknown` | Value bound to the selection when the node is chosen (defaults to the node). |
| `children`? | `MkTreeNode[] \| undefined` | Child nodes; a non-empty array makes the node a parent (expandable). |
| `disabled`? | `boolean \| undefined` | Disable selection/toggling of this node (still focusable). |
| `expanded`? | `boolean \| undefined` | Expand this node initially. |
| `icon`? | `string \| undefined` | Optional leading glyph (any short string / emoji). |
| `iconName`? | `string \| undefined` | Name of a registered icon (see `MkIconRegistry`), rendered with `mk-icon`; wins over `icon`. |

### MkUploadFile (interface)

Import: `import { MkUploadFile } from '@mk-kit/ui/forms';`

A file tracked by `MkFileUpload`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable id for tracking + removal. |
| `file` | `File` | The underlying browser `File`. |
| `name` | `string` | File name. |
| `size` | `number` | Size in bytes. |
| `status` | `MkUploadStatus` | Upload lifecycle state. |
| `progress` | `number` | Upload progress, 0–100. |
| `error`? | `string \| undefined` | Failure reason (validation or upload error). |
| `previewUrl`? | `string \| undefined` | Object URL for an image preview, when the file is an image. |

### MkUploadRejection (interface)

Import: `import { MkUploadRejection } from '@mk-kit/ui/forms';`

Why a dropped/selected file was rejected.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `file` | `File` |  |
| `reason` | `"type" \| "size" \| "maxFiles"` |  |
| `message` | `string` |  |

### MkAutocompleteFilterMode (type)

Import: `import { MkAutocompleteFilterMode } from '@mk-kit/ui/forms';`

How the option list is narrowed against the typed text.

```ts
type MkAutocompleteFilterMode = 'contains' | 'startsWith' | 'none';
```

### MkCardBrand (type)

Import: `import { MkCardBrand } from '@mk-kit/ui/forms';`

Card networks `MkCardNumberInput` recognises.

```ts
type MkCardBrand = | 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners' | 'jcb';
```

### MkCodeLanguage (type)

Import: `import { MkCodeLanguage } from '@mk-kit/ui/forms';`

Languages with built-in highlighting. Unknown values render plain text.

```ts
type MkCodeLanguage = 'json' | 'plaintext';
```

### MkI18nValue (type)

Import: `import { MkI18nValue } from '@mk-kit/ui/forms';`

The bound value: one string per locale code.

```ts
type MkI18nValue = Record<string, string>;
```

### MkKeyboardKey (type)

Import: `import { MkKeyboardKey } from '@mk-kit/ui/forms';`

```ts
type MkKeyboardKey = string | MkKeyboardActionKey;
```

### MkMentionFilterMode (type)

Import: `import { MkMentionFilterMode } from '@mk-kit/ui/forms';`

How mention suggestions are narrowed against the typed query.

```ts
type MkMentionFilterMode = 'contains' | 'startsWith' | 'none';
```

### MkMultiSelectFilterMode (type)

Import: `import { MkMultiSelectFilterMode } from '@mk-kit/ui/forms';`

How the option list is narrowed against the typed text.

```ts
type MkMultiSelectFilterMode = 'contains' | 'startsWith' | 'none';
```

### MkNumericKeypadMode (type)

Import: `import { MkNumericKeypadMode } from '@mk-kit/ui/forms';`

```ts
type MkNumericKeypadMode = 'pin' | 'quantity' | 'amount';
```

### MkOnScreenKeyboardTarget (type)

Import: `import { MkOnScreenKeyboardTarget } from '@mk-kit/ui/forms';`

```ts
type MkOnScreenKeyboardTarget = HTMLInputElement | HTMLTextAreaElement;
```

### MkRange (type)

Import: `import { MkRange } from '@mk-kit/ui/forms';`

A `[low, high]` value pair.

```ts
type MkRange = [number, number];
```

### MkUploadFn (type)

Import: `import { MkUploadFn } from '@mk-kit/ui/forms';`

Uploads the given file, reporting progress via `onProgress` (0–100) and
resolving on success / rejecting (optionally with an `Error`) on failure.

```ts
type MkUploadFn = ( file: File, onProgress: (percent: number) => void, ) => Promise<void>;
```

### MkUploadStatus (type)

Import: `import { MkUploadStatus } from '@mk-kit/ui/forms';`

Upload lifecycle state for a single file.

```ts
type MkUploadStatus = 'pending' | 'uploading' | 'success' | 'error';
```

### MkUploadValueFormat (type)

Import: `import { MkUploadValueFormat } from '@mk-kit/ui/forms';`

What `MkFileUpload` publishes as its form value: the raw browser
`File`s (the default, and what you would send in a `FormData`), or the full
tracked items including upload status and progress.

```ts
type MkUploadValueFormat = 'file' | 'item';
```

## @mk-kit/ui/datetime

39 exports. `import { … } from '@mk-kit/ui/datetime';`

### MkCalendar (component)

Selector: `mk-calendar` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/date-time

Import: `import { MkCalendar } from '@mk-kit/ui/datetime';`

Calendar — an accessible month-grid date picker following the WAI-ARIA
grid / date-picker pattern. It is the reusable core behind
`mk-date-picker` and `mk-date-range-picker`.

Keyboard (when a day has focus): Arrow keys move by day/week (crossing month
boundaries updates the view), Home/End jump to the start/end of the week,
PageUp/PageDown change month, Shift+PageUp/PageDown change year, and
Enter/Space selects the focused day. A roving tabindex keeps a single tab
stop. Month changes are announced via `MkLiveAnnouncer`.

Exposes a two-way `value` model and implements `ControlValueAccessor`, so it
also works directly with `ngModel` / `formControl` (single-date mode).
Additive range inputs (`rangeMode`,
`rangeStart`, `rangeEnd`) let it highlight an in-progress selection without
affecting single-date use; range hosts listen to `dateSelected`.

```html
<mk-calendar [(value)]="date" [min]="minDate" [firstDayOfWeek]="1" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `Date \| null` | `null` | Two-way selected date (single-date mode). |
| `min` | `Date \| null` | `null` | Earliest selectable date (inclusive, day granularity). |
| `max` | `Date \| null` | `null` | Latest selectable date (inclusive, day granularity). |
| `firstDayOfWeek` | `number` | `0` | First column of the week: 0 = Sunday … 6 = Saturday. |
| `disabled` | `boolean` | `false` | Disable the whole calendar. |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `disabledDate` | `((d: Date) => boolean) \| null` | `null` | Predicate marking individual days as disabled. |
| `size` | `MkSize` | `'md'` | Control size. |
| `fullWidth` | `boolean` | `false` | Stretch to fill the container instead of sizing to content.  Off by default, because the common host is a date-picker popover that must stay a compact widget. Turn it on when the calendar is laid out as part of a page — a sidebar or a column — where sizing to content leaves the space beside it empty. Cells share the width evenly and `--_cell-size` becomes their minimum rather than their fixed size. |
| `rangeMode` | `boolean` | `false` | Enable range highlighting. Hosts drive selection via `dateSelected`. |
| `rangeStart` | `Date \| null` | `null` | Range start endpoint to highlight (range mode). |
| `rangeEnd` | `Date \| null` | `null` | Range end endpoint to highlight (range mode). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `Date \| null` | Emits when `value` changes (two-way binding). |
| `dateSelected` | `Date` | Emitted whenever a (non-disabled) day is activated. |
| `dateHovered` | `Date \| null` | Emitted (in range mode) as the pointer hovers days — the hovered day, or `null` on leave. Lets hosts preview a selection (e.g. a whole-week highlight in `mk-week-picker`). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `mkMinDate` / `mkMaxDate` for a date outside `[min]`/`[max]`, and `mkDateFilter` for one rejected by `[disabledDate]`. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `labelId` | `string` | id of the visible month/year label — wire as the grid's label. |

### MkDatePicker (component)

Selector: `mk-date-picker` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/date-time

Import: `import { MkDatePicker } from '@mk-kit/ui/datetime';`

DatePicker — a text field paired with a calendar popover. Type a date (parsed
on blur/Enter) or pick one from the `mk-calendar`. Implements
`ControlValueAccessor` and a two-way `value` model, so it works with
`[(ngModel)]`, reactive forms and `[(value)]`.

The calendar opens below the field, closes on Escape / outside click / after
a selection, and wires `aria-expanded` / `aria-haspopup` / `aria-invalid`.
When nested in an `mk-form-field` it adopts the field's id and aria wiring.

```html
<mk-date-picker [(value)]="date" [min]="minDate" clearable />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `Date \| null` | `null` | Two-way selected date. |
| `aria-label` | `string` | `''` | Accessible name when the picker is used without an `mk-form-field` label. |
| `min` | `Date \| null` | `null` |  |
| `max` | `Date \| null` | `null` | Latest selectable date (inclusive). |
| `disabledDate` | `((d: Date) => boolean) \| null` | `null` | Predicate marking individual days as disabled (threaded to the calendar). |
| `placeholder` | `string` | `this.i18n.selectDate` | Placeholder shown when empty. |
| `displayFormat` | `string` | `'MMM d, yyyy'` | Pattern used to render the selected date in the field. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `clearable` | `boolean` | `false` | Show a clear button when a date is selected. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid`. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). Set by Signal Forms' `[formField]` from the schema. |
| `firstDayOfWeek` | `number` | `0` | First column of the calendar week (0 = Sunday). |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `Date \| null` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `mkMinDate` / `mkMaxDate` against the `[min]` and `[max]` inputs. |

### MkDateRangePicker (component)

Selector: `mk-date-range-picker` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/date-time

Import: `import { MkDateRangePicker } from '@mk-kit/ui/datetime';`

DateRangePicker — select a start + end date from a single calendar popover.
The first click sets the start, the second sets the end (endpoints are
swapped if picked in reverse), and the hovered range is previewed live.
Implements `ControlValueAccessor` and a two-way `value` model of
`MkDateRange`.

```html
<mk-date-range-picker [(value)]="range" [min]="minDate" clearable />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `MkDateRange` | `{ start: null, end: null }` | Two-way selected range. |
| `min` | `Date \| null` | `null` | Earliest selectable date (inclusive). |
| `max` | `Date \| null` | `null` | Latest selectable date (inclusive). |
| `disabledDate` | `((d: Date) => boolean) \| null` | `null` | Predicate marking individual days as disabled. |
| `placeholder` | `string` | `this.i18n.selectRange` | Placeholder shown when no range is selected. |
| `displayFormat` | `string` | `'MMM d, yyyy'` | Pattern used to render each endpoint. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `clearable` | `boolean` | `false` | Show a clear button when a range is selected. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid`. |
| `firstDayOfWeek` | `number` | `0` | First column of the calendar week (0 = Sunday). |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `MkDateRange` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `mkDateRangeIncomplete` for a half-picked range, `mkMinDate` / `mkMaxDate` for ends outside `[min]`/`[max]`, and `mkDateFilter` for an end rejected by `[disabledDate]`. A fully empty range passes; compose with `Validators.required` to reject it. |

### MkDateTimePicker (component)

Selector: `mk-datetime-picker` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/date-time

Import: `import { MkDateTimePicker } from '@mk-kit/ui/datetime';`

DateTimePicker — one field for a date **and** a time of day. The panel pairs
an `mk-calendar` with a time list generated from `step`; the value is a
single `Date` carrying both parts in local time (seconds and milliseconds
zeroed). Implements `ControlValueAccessor` and a two-way `value` model, so it
works with `[(ngModel)]`, reactive forms and `[(value)]`.

Interaction: picking a day keeps the panel open and — when a value already
exists — moves that value to the new day, preserving its time; picking a
time commits and closes. With no value yet, the day is held until a time is
chosen (so a half-picked datetime is never emitted). Typing also works:
`2026-08-26 14:30`, `2026-08-26T09:05`, `Aug 26, 2026 2:30 pm` and a bare
ISO date (→ midnight) are parsed on Enter/blur.

`min` / `max` bound the whole instant at minute precision: the calendar
greys out days outside the range and the time list hides times outside it
on the boundary days. Validation reports `mkMinDate` / `mkMaxDate`.

When nested in an `mk-form-field` it adopts the field's id and aria wiring.

```html
<mk-datetime-picker [(value)]="startsAt" [step]="15" [min]="now" clearable />
<mk-datetime-picker [(value)]="startsAt" hour12 />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `Date \| null` | `null` | Two-way selected date-time (local; seconds and ms are zero). |
| `min` | `Date \| null` | `null` | Earliest selectable instant (inclusive, minute precision). |
| `max` | `Date \| null` | `null` | Latest selectable instant (inclusive, minute precision). |
| `disabledDate` | `((d: Date) => boolean) \| null` | `null` | Predicate marking individual days as disabled (threaded to the calendar). |
| `placeholder` | `string` | `this.i18n.selectDateTime` | Placeholder shown when empty. |
| `displayFormat` | `string \| null` | `null` | Pattern used to render the value in the field. Defaults to `'MMM d, yyyy HH:mm'`, or `'MMM d, yyyy h:mm a'` when `hour12` is set. |
| `step` | `number` | `30` | Interval between generated time options, in minutes. |
| `hour12` | `boolean` | `false` | Display 12-hour times with AM/PM (the model is a `Date` either way). |
| `disabled` | `boolean` | `false` | Disable the control. |
| `clearable` | `boolean` | `false` | Show a clear button when a value is selected. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid`. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). Set by Signal Forms' `[formField]` from the schema. |
| `firstDayOfWeek` | `number` | `0` | First column of the calendar week (0 = Sunday). |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `Date \| null` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `mkMinDate` / `mkMaxDate` against the `[min]` and `[max]` inputs, comparing whole instants at minute precision. |

### MkEventCalendar (component)

Selector: `mk-event-calendar`

Docs: https://mk-kit.dev/components/date-time

Import: `import { MkEventCalendar } from '@mk-kit/ui/datetime';`

Event calendar — a month-grid scheduler view. Renders a 6×7 grid of day
cells built from `buildMonthMatrix`; each cell lists the events whose
`date` falls on that day as coloured pills, capped at `maxPerDay` with a
"+N more" line for the remainder.

Shares the month-grid rendering, header navigation, and weekday header of
`mk-calendar` but is display-only (no date selection). Exposes the viewed
month as a two-way `viewDate` model plus `dayClick` / `eventClick` outputs.

With `editable`, the week/day time grids additionally support drag-to-move
and drag-to-resize (pointer *and* keyboard — WCAG 2.5.7): times snap to
`snapMinutes` and the would-be range is emitted via `eventMove` /
`eventResize` — the calendar never mutates `events` itself.

```html
<mk-event-calendar [events]="events" [(viewDate)]="month"
  (eventClick)="open($event)" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `events` | `readonly MkCalendarEvent[]` | `[]` | Events to plot onto the grid. |
| `viewDate` (two-way) | `Date` | `new Date()` | Two-way month being viewed (any day within it). Defaults to today. |
| `firstDayOfWeek` | `number` | `0` | First column of the week: 0 = Sunday … 6 = Saturday. |
| `maxPerDay` | `number` | `3` | Max event pills per day before collapsing the rest into "+N more". |
| `view` (two-way) | `MkCalendarView` | `'month'` | Presentation: the classic month grid, or a timed `week`/`day` grid. |
| `dayStartHour` | `number` | `8` | First hour shown on the week/day time grid. |
| `dayEndHour` | `number` | `22` | Hour the time grid ends at (exclusive). |
| `editable` | `boolean` | `false` | Week/day views: allow rescheduling events by dragging a pill (move) or its bottom edge (resize end time), by pointer or keyboard. Off by default — without it the grid renders exactly as before (no handles, no ARIA additions, no drag behavior). |
| `snapMinutes` | `number` | `15` | Snap grid (minutes) for drag/keyboard edits; also the minimum duration. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `viewDateChange` | `Date` | Emits when `viewDate` changes (two-way binding). |
| `viewChange` | `MkCalendarView` | Emits when `view` changes (two-way binding). |
| `dayClick` | `Date` | Emitted when a day cell is activated (click / Enter). |
| `eventClick` | `MkCalendarEvent` | Emitted when an event pill is clicked (does not also fire `dayClick`). Mouse-only convenience: the pills are presentational (`aria-hidden`), so keyboard / screen-reader users reach events via the day button — its label announces the day's events and activating it fires `dayClick`. |
| `monthChange` | `Date` | Emitted when the viewed range changes via the prev/next buttons. |
| `slotClick` | `Date` | Week/day view: an empty hour slot was clicked — the slot's start instant. |
| `eventMove` | `MkCalendarEventEdit` | Editable week/day grid: an event pill was dragged (or keyboard-moved) to a new start time and/or day. Carries the would-be `start`/`end` — the calendar does **not** mutate `events`; the consumer owns the data and applies the change, typically:  ```ts onMove = ({ event, start, end }: MkCalendarEventEdit) =>   (this.events = this.events.map((e) =>     e === event ? { ...e, date: start, start, end } : e,   )); ``` |
| `eventResize` | `MkCalendarEventEdit` | Editable week/day grid: the pill's bottom edge was dragged (or Shift+Arrow-resized) — only `end` differs, never below `snapMinutes` of duration. Same consumer-owns-the-data contract as `eventMove`. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `labelId` | `string` | id of the visible month/year label — wired as the grid's label. |

### MkMiniDate (component)

Selector: `mk-mini-date` · exportAs: `mkMiniDate` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/date-time

Import: `import { MkMiniDate } from '@mk-kit/ui/datetime';`

MiniDate — a compact, popover-free inline date editor with segmented
day / month / year spin fields (like a native `<input type="date">` but
themed and signal-driven). Each segment is an ARIA `spinbutton`: Arrow
Up/Down step the value (day wraps within the month), Home/End jump to the
segment's minimum/maximum, Arrow Left/Right move between segments, and
typing digits fills the focused segment and auto-advances (OTP-style). Implements `ControlValueAccessor` and a two-way
`value` model over a real `Date | null`.

A non-null `Date` is emitted only when all three segments are set and valid;
the day is clamped to the month's length (e.g. Feb 31 → 28/29) and the
result is clamped to `[min, max]`.

```html
<mk-mini-date [(value)]="date" order="dmy" [min]="minDate" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `min` | `Date \| null` | `null` | Minimum selectable date (inclusive). |
| `max` | `Date \| null` | `null` | Maximum selectable date (inclusive). |
| `value` (two-way) | `Date \| null` | `null` | Two-way value — a real `Date`, or `null` while incomplete. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force invalid styling when standalone. |
| `size` | `MkSize` | `'md'` | Control size. Ignored inside an `mk-form-field`. |
| `order` | `MkMiniDateOrder` | `'dmy'` | Segment order. |
| `yearMin` | `number` | `1900` | Lowest selectable year (for the year spinbutton range). |
| `yearMax` | `number` | `2100` | Highest selectable year (for the year spinbutton range). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `Date \| null` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `mkMinDate` / `mkMaxDate` against the `[min]` and `[max]` inputs. |

### MkMonthPicker (component)

Selector: `mk-month-picker` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/date-time

Import: `import { MkMonthPicker } from '@mk-kit/ui/datetime';`

MonthPicker — a compact field + popover for picking a **month** (`MMM yyyy`)
or a **year**. The panel shows a 12-month grid (with year nav) or a 12-year
grid (with decade nav). Value is a `Date` at the first day of the selection.
Implements `ControlValueAccessor` + a two-way `value` model; the panel renders
in the top layer so it is never clipped.

```html
<mk-month-picker [(value)]="month" />
<mk-month-picker mode="year" [(value)]="year" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `Date \| null` | `null` | Two-way selected date (first of the month / year). |
| `mode` | `MkMonthPickerMode` | `'month'` | Pick a month or a whole year. |
| `min` | `Date \| null` | `null` | Earliest selectable date. |
| `max` | `Date \| null` | `null` | Latest selectable date. |
| `placeholder` | `string` | `''` | Placeholder shown when empty. |
| `displayFormat` | `string` | `''` | Display pattern (defaults to `MMM yyyy` / `yyyy`). |
| `disabled` | `boolean` | `false` | Disable the control. |
| `clearable` | `boolean` | `false` | Show a clear button when a value is selected. |
| `invalid` | `boolean` | `false` | Force invalid styling. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `Date \| null` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `mkMinDate` / `mkMaxDate` against the `[min]` and `[max]` inputs, compared at month granularity. |

### MkTimePicker (component)

Selector: `mk-time-picker` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/date-time

Import: `import { MkTimePicker } from '@mk-kit/ui/datetime';`

TimePicker — a 24-hour-canonical time field with an editable input plus a
scrollable list of times generated from `step`. The time itself is always
24h canonical regardless of the `hour12` display. Implements
`ControlValueAccessor` and a two-way `value` model.

The form value is either a `HH:mm` string (`"14:30"`, default) or a `Date`
carrying the time in its **local** hours/minutes (`valueFormat="date"`, for
hosts whose model is a datetime — e.g. migrating off Material's
`mat-timepicker`); both modes read back either shape and `null` when empty.
Only the *emitted* value depends on `valueFormat` — internally the time is
always normalised to `HH:mm`, which is also what `min` / `max` compare.

In `date` mode seconds and milliseconds are zeroed, and the **date part** is
taken from the current model value when that is already a `Date` (so editing
the time repeatedly never drifts the day); otherwise today's local date is
used. Assign a `Date` first if the day matters.

Type a time (`14:30`, `2:30 pm`) or pick from the ARIA listbox
(Up/Down/Home/End/Enter/Esc; the active option scrolls into view). When
nested in an `mk-form-field` it adopts the field's id and aria wiring.

```html
<mk-time-picker [(value)]="time" [step]="15" hour12 clearable />
<mk-time-picker valueFormat="date" [(value)]="pickupAt" [step]="15" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `string \| Date \| null` | `null` | Two-way selected time: a canonical `HH:mm` (24h) string, a `Date` when `valueFormat="date"`, or `null`. Either shape may be assigned in either mode; it is normalised to the configured format. |
| `aria-label` | `string` | `''` | Accessible name when the picker is used without an `mk-form-field` label. |
| `valueFormat` | `"string" \| "date"` | `'string'` |  |
| `min` | `string \| null` | `null` | Earliest selectable time `HH:mm` (inclusive). |
| `max` | `string \| null` | `null` | Latest selectable time `HH:mm` (inclusive). |
| `step` | `number` | `30` | Interval between generated options, in minutes. |
| `hour12` | `boolean` | `false` | Display 12-hour time with AM/PM (the model stays 24h). |
| `disabled` | `boolean` | `false` | Disable the control. |
| `placeholder` | `string` | `this.i18n.selectTime` | Placeholder shown when empty. |
| `clearable` | `boolean` | `false` | Show a clear button when a time is selected. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid`. |
| `required` | `boolean` | `false` | Mark required (adds `aria-required`). Set by Signal Forms' `[formField]` from the schema. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string \| Date \| null` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `mkMinTime` / `mkMaxTime` against the `[min]` and `[max]` inputs. The control value is normalised to `HH:mm` first (so a `Date` model validates too); both sides are then zero-padded `HH:mm`, so a lexicographic compare is a chronological one. |

### MkWeekPicker (component)

Selector: `mk-week-picker` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/date-time

Import: `import { MkWeekPicker } from '@mk-kit/ui/datetime';`

WeekPicker — pick a whole calendar week from a popover calendar. Hovering a
day previews its entire week; clicking selects it. The value is an
`MkWeek` (`{ start, end }`, aligned to `firstDayOfWeek`). Implements
`ControlValueAccessor` and a two-way `value` model; the panel renders in the
top layer so it is never clipped.

```html
<mk-week-picker [(value)]="week" [firstDayOfWeek]="1" clearable />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `MkWeek \| null` | `null` | Two-way selected week. |
| `min` | `Date \| null` | `null` | Earliest selectable date (inclusive). |
| `max` | `Date \| null` | `null` | Latest selectable date (inclusive). |
| `firstDayOfWeek` | `number` | `0` | First column of the calendar week (0 = Sunday). Also anchors the week. |
| `placeholder` | `string` | `this.i18n.selectWeek` | Placeholder shown when empty. |
| `displayFormat` | `string` | `'MMM d'` | Pattern used to render each endpoint of the week range. |
| `showWeekNumber` | `boolean` | `false` | Prefix the label with the ISO week number, e.g. `W28 · …`. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `clearable` | `boolean` | `false` | Show a clear button when a week is selected. |
| `invalid` | `boolean` | `false` | Force invalid styling + `aria-invalid`. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `MkWeek \| null` | Emits when `value` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `validate(control: AbstractControl): ValidationErrors \| null` | Reports `mkMinDate` / `mkMaxDate` when the selected week starts before `[min]` or ends after `[max]`. |

### addDays (function)

Import: `import { addDays } from '@mk-kit/ui/datetime';`

A new date `count` days after `date` (negative to subtract).

```ts
function addDays(date: Date, count: number): Date
```

### addMonths (function)

Import: `import { addMonths } from '@mk-kit/ui/datetime';`

A new date `count` months after `date` (negative to subtract). Clamps the
day of month so e.g. Jan 31 + 1 month = Feb 28/29, not Mar 3.

```ts
function addMonths(date: Date, count: number): Date
```

### buildMonthMatrix (function)

Import: `import { buildMonthMatrix } from '@mk-kit/ui/datetime';`

Build a fixed 6×7 matrix of `Date` cells for `viewDate`'s month, including
the leading days from the previous month and trailing days from the next so
every row is full. `firstDayOfWeek` is 0 (Sunday) … 6 (Saturday).

```ts
function buildMonthMatrix(viewDate: Date, firstDayOfWeek?: number): Date[][]
```

### clampDate (function)

Import: `import { clampDate } from '@mk-kit/ui/datetime';`

Clamp `date` into the inclusive `[min, max]` range (either bound optional).

```ts
function clampDate(date: Date, min?: Date | null, max?: Date | null): Date
```

### endOfMonth (function)

Import: `import { endOfMonth } from '@mk-kit/ui/datetime';`

Midnight on the last day of `date`'s month.

```ts
function endOfMonth(date: Date): Date
```

### endOfWeek (function)

Import: `import { endOfWeek } from '@mk-kit/ui/datetime';`

The last day of the week containing `date`, at midnight.

```ts
function endOfWeek(date: Date, firstDayOfWeek?: number): Date
```

### formatDate (function)

Import: `import { formatDate } from '@mk-kit/ui/datetime';`

Format `date` using a small pattern set. Supported tokens:
`yyyy` (4-digit year), `MMMM` (full month), `MMM` (short month),
`MM` (2-digit month), `dd` (2-digit day), `d` (day), `ddd` (short weekday),
`HH` / `H` (24-hour, padded / bare), `hh` / `h` (12-hour, padded / bare),
`mm` (2-digit minutes) and `a` (`AM` / `PM`). Longer tokens are matched
first so `MMMM` wins over `MM`. Month/weekday names come from `names` when
given, else English.

```ts
function formatDate(date: Date, pattern: string, names?: MkDateNames): string
```

### formatISODate (function)

Import: `import { formatISODate } from '@mk-kit/ui/datetime';`

Format `date` as an ISO calendar date `YYYY-MM-DD` (local time).

```ts
function formatISODate(date: Date): string
```

### getISOWeek (function)

Import: `import { getISOWeek } from '@mk-kit/ui/datetime';`

ISO-8601 week number (1–53) of `date`. Weeks start on Monday and week 1 is
the week containing the first Thursday of the year.

```ts
function getISOWeek(date: Date): number
```

### getMonthNames (function)

Import: `import { getMonthNames } from '@mk-kit/ui/datetime';`

Full month names, index 0 = January (from `names`, else English).

```ts
function getMonthNames(names?: MkDateNames): readonly string[]
```

### getWeekdayFullName (function)

Import: `import { getWeekdayFullName } from '@mk-kit/ui/datetime';`

Full weekday name for `date` (for screen-reader labels).

```ts
function getWeekdayFullName(date: Date, names?: MkDateNames): string
```

### getWeekdayNames (function)

Import: `import { getWeekdayNames } from '@mk-kit/ui/datetime';`

Weekday header labels ordered to start at `firstDayOfWeek`.
`format` selects `'short'` (e.g. `Mon`) or `'narrow'` (e.g. `M`).
Labels come from `names` when given, else English.

```ts
function getWeekdayNames(firstDayOfWeek?: number, format?: "short" | "narrow", names?: MkDateNames): string[]
```

### isAfter (function)

Import: `import { isAfter } from '@mk-kit/ui/datetime';`

True when `a` is strictly after `b` (full timestamp comparison).

```ts
function isAfter(a: Date, b: Date): boolean
```

### isBefore (function)

Import: `import { isBefore } from '@mk-kit/ui/datetime';`

True when `a` is strictly before `b` (full timestamp comparison).

```ts
function isBefore(a: Date, b: Date): boolean
```

### isNumericDatePattern (function)

Import: `import { isNumericDatePattern } from '@mk-kit/ui/datetime';`

True when `pattern` writes day, month and year as numbers ('dd.MM.yyyy',
'MM/dd/yy HH:mm') — then it, not `Date.parse`, decides how numeric text
reads.

```ts
function isNumericDatePattern(pattern: string): boolean
```

### isSameDay (function)

Import: `import { isSameDay } from '@mk-kit/ui/datetime';`

True when both dates fall on the same calendar day (local time).

```ts
function isSameDay(a: Date, b: Date): boolean
```

### isSameMonth (function)

Import: `import { isSameMonth } from '@mk-kit/ui/datetime';`

True when both dates fall in the same calendar month of the same year.

```ts
function isSameMonth(a: Date, b: Date): boolean
```

### parseDateByPattern (function)

Import: `import { parseDateByPattern } from '@mk-kit/ui/datetime';`

Parse `text` by the numeric day/month/year order of a display `pattern` —
`dd.MM.yyyy` reads day first, `MM/dd/yyyy` month first. `Date.parse` must
never see such text: it reads '09.10.2026' as September 10 in every engine.

Returns `null` when the pattern has no numeric `d`/`M`/`y` triple (e.g.
'MMM d, yyyy'), when `text` is not three numbers, or when they do not form
a real date ('31.02.2026' is rejected, not rolled over). Two-digit years
are 20xx. The result is local midnight.

```ts
function parseDateByPattern(text: string, pattern: string): Date | null
```

### parseISODate (function)

Import: `import { parseISODate } from '@mk-kit/ui/datetime';`

Parse a `YYYY-MM-DD` string into a local-time `Date`, or `null` if invalid.

```ts
function parseISODate(value: string | null | undefined): Date | null
```

### startOfDay (function)

Import: `import { startOfDay } from '@mk-kit/ui/datetime';`

Midnight (00:00:00.000) on `date`'s calendar day.

```ts
function startOfDay(date: Date): Date
```

### startOfMonth (function)

Import: `import { startOfMonth } from '@mk-kit/ui/datetime';`

Midnight (00:00:00.000) on the first day of `date`'s month.

```ts
function startOfMonth(date: Date): Date
```

### startOfWeek (function)

Import: `import { startOfWeek } from '@mk-kit/ui/datetime';`

The first day of the week containing `date`, at midnight. `firstDayOfWeek`
is the week's starting weekday (0 = Sunday … 6 = Saturday).

```ts
function startOfWeek(date: Date, firstDayOfWeek?: number): Date
```

### MkCalendarEvent (interface)

Import: `import { MkCalendarEvent } from '@mk-kit/ui/datetime';`

A single event plotted onto the `MkEventCalendar`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `date` | `Date` | The day the event falls on. Month view places by this alone; in week/day view an event with no `start` renders in the all-day strip. |
| `start`? | `Date \| undefined` | Start instant — positions the event on the week/day time grid. |
| `end`? | `Date \| undefined` | End instant; defaults to 30 minutes after `start`. |
| `title` | `string` | Short label shown inside the event pill. |
| `color`? | `string \| undefined` | Optional pill background colour; falls back to `--mk-primary`. |
| `id`? | `unknown` | Optional caller-supplied identifier, echoed back on `eventClick`. |

### MkCalendarEventEdit (interface)

Import: `import { MkCalendarEventEdit } from '@mk-kit/ui/datetime';`

Payload of `eventMove` / `eventResize`: the untouched source event plus the
would-be new time range. The calendar itself never mutates `events` — the
consumer owns the data and applies (or rejects) the change.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `event` | `MkCalendarEvent` | The event that was dragged — the exact object from the `events` input. |
| `start` | `Date` | New start instant (snapped to `snapMinutes`). |
| `end` | `Date` | New end instant (snapped; never closer than `snapMinutes` to `start`). |

### MkDateRange (interface)

Import: `import { MkDateRange } from '@mk-kit/ui/datetime';`

A selected date range. Either endpoint may be `null` while incomplete.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `start` | `Date \| null` |  |
| `end` | `Date \| null` |  |

### MkWeek (interface)

Import: `import { MkWeek } from '@mk-kit/ui/datetime';`

A selected calendar week (its first and last day, at midnight).

Members:

| Name | Type | Description |
| --- | --- | --- |
| `start` | `Date` |  |
| `end` | `Date` |  |

### MkCalendarView (type)

Import: `import { MkCalendarView } from '@mk-kit/ui/datetime';`

The calendar's presentation: month grid, or a timed week/day grid.

```ts
type MkCalendarView = 'month' | 'week' | 'day';
```

### MkMiniDateOrder (type)

Import: `import { MkMiniDateOrder } from '@mk-kit/ui/datetime';`

Segment display order.

```ts
type MkMiniDateOrder = 'dmy' | 'mdy' | 'ymd';
```

### MkMonthPickerMode (type)

Import: `import { MkMonthPickerMode } from '@mk-kit/ui/datetime';`

Selection granularity for `MkMonthPicker`.

```ts
type MkMonthPickerMode = 'month' | 'year';
```

### MkWeekday (type)

Import: `import { MkWeekday } from '@mk-kit/ui/datetime';`

Day-of-week index 0 (Sunday) … 6 (Saturday).

```ts
type MkWeekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
```

## @mk-kit/ui/table

39 exports. `import { … } from '@mk-kit/ui/table';`

### MkSortHeader (component)

Selector: `[mkSortHeader]`

Docs: https://mk-kit.dev/components/sort

Import: `import { MkSortHeader } from '@mk-kit/ui/table';`

Sort header — attach `mkSortHeader` to a header cell (`<th>`) inside an
element carrying `mkSort`. It wraps the projected header text in a real
`<button>` (so assistive tech hears an operable control), adds a directional
arrow (faint on hover, solid when active), reflects `aria-sort` on the cell,
and toggles the sort on click or Enter/Space.

```html
<th mkSortHeader="email" mkSortHeaderLabel="Email address">Email</th>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkSortHeader` | `string` | `''` | Column id this header sorts by (the `mkSortHeader` value). |
| `mkSortHeaderStart` | `"asc" \| "desc" \| undefined` | `undefined` | Per-header override for the initial sort direction. |
| `mkSortHeaderDisabled` | `boolean` | `false` | Disable sorting for just this header. |
| `mkSortHeaderLabel` | `string` | `''` | Accessible label used in sort announcements (defaults to the id). |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `isDisabled` | `Signal<boolean>` | Disabled if this header or the whole `mkSort` is disabled. |
| `isActive` | `Signal<boolean>` | Whether this header is the active, non-cleared sort. |
| `direction` | `Signal<MkSortDirection>` | Active direction, or `none` when this header is not the active sort. |

### MkTable (component)

Selector: `mk-table`

Docs: https://mk-kit.dev/components/table

Import: `import { MkTable } from '@mk-kit/ui/table';`

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` (required) | `MkTableColumn<T>[]` |  | Column definitions (order = display order). |
| `data` | `T[]` | `[]` | Row objects to render. |
| `stickyHeader` | `boolean` | `false` | Pin the header to the top of the scroll container. |
| `zebra` | `boolean` | `false` | Alternate row background for readability. |
| `hover` | `boolean` | `true` | Highlight rows on hover. |
| `density` | `MkTableDensity` | `'comfortable'` | Row density. |
| `stackAt` | `number` | `0` | Width in px below which each row renders as a CARD instead of a table row. `0` (default) never stacks.  Measured on the table's own container, not the viewport — a table in a narrow sidebar should stack on a desktop, and a table on a tablet in landscape should not. Per-column behaviour is set with `MkTableColumn.stack`.  A grid cannot survive a phone: eight columns become eight unreadable slivers, and horizontal scrolling loses the row you were reading. Cards keep one record together and put its header beside each value. |
| `clickableRows` | `boolean` | `false` | Style rows as clickable and emit `rowClick`. |
| `emptyMessage` | `string` | `this.i18n.noData` | Message shown when there are no rows. |
| `selectable` | `boolean` | `false` | Render a leading checkbox column for row selection. |
| `selected` (two-way) | `T[]` | `[]` | Two-way bound array of selected rows. Use `[(selected)]` to bind, or read `selectionChange`. Rows are compared by `trackKey` when set, else by referential identity. |
| `trackKey` | `string \| undefined` |  | Property name identifying a row for selection equality. When omitted rows are matched by reference. |
| `rowClass` | `((row: T) => string \| null \| undefined) \| null` | `null` | Optional per-row CSS class: called with each row, the returned string is appended to the row's class list (falsy → none). For state the consumer owns — an "active in the side panel" highlight, an unread accent — that `selectable`'s own selected style doesn't cover. |
| `expandable` | `boolean` | `false` | Render a leading expander column. Each row can reveal a detail panel supplied via an `<ng-template mkTableRowDetail let-row>`. |
| `singleExpand` | `boolean` | `false` | Allow only one row expanded at a time (accordion). |
| `resizableColumns` | `boolean` | `false` | Enable drag-to-resize on columns marked `resizable` (data-grid pro). |
| `reorderableColumns` | `boolean` | `false` | Enable drag-to-reorder of column headers (data-grid pro). |
| `groupBy` | `string \| ((row: T) => unknown) \| null` | `null` | Group rows by a column key or an accessor. Renders a collapsible group header row (sticky, with a row count) above each group. Sorting still applies within groups; groups follow their first row's sorted position. |
| `groupLabel` | `((value: unknown, rows: T[]) => string) \| null` | `null` | Formats a group header label; defaults to `String(value)`. |
| `virtual` | `boolean` | `false` | Render only the rows in view (plus `overscan`) — for tables of thousands of rows. The `<table>` scrolls inside its own box sized by `height` / `maxHeight` (`max-height: 60vh` when neither is set) with the header pinned; spacer rows keep the scrollbar honest.  Works with sorting, selection (select-all still covers every row), tree rows, grouping (group headers are rows too), expandable detail rows (their height is measured once rendered; an unmeasured detail counts as one row) and the header filter row. Falls back to the full render while stacked into cards. Export and select-all always see every row, not the window. |
| `rowHeight` | `number \| null` | `null` | Height (px) of one row in virtual mode. Leave unset to have it measured from the first rendered row — which follows `density` and `data-mk-density` automatically — starting from 44 (comfortable). |
| `overscan` | `number` | `6` | Rows rendered beyond each edge of the viewport in virtual mode. |
| `height` | `string \| number \| null` | `null` | Fixed height of the scroll box (CSS length, or px as a number). |
| `maxHeight` | `string \| number \| null` | `null` | Maximum height of the scroll box (CSS length, or px as a number). |
| `filterable` | `boolean` | `false` | Render a second header row with a filter control per column — a text box, a select, a number or a date field as the column's `MkTableColumn.filter` says. Values live in `filters`. |
| `filters` (two-way) | `MkTableFilters` | `{}` | The active filters, keyed by column key (`[(filters)]`; `filtersChange` emits the whole map on every edit). Text filters hold the typed string, select filters the chosen option value, number / date filters the lower bound or a `{ min, max }` range. Set programmatically to pre-filter. |
| `clientFilter` | `boolean` | `true` | Filter rows in the browser (default). Turn off when the server applies the filters — `MkTableDataSource.setFilters($event)` on `filtersChange` — so the page it returns is shown as-is. |
| `childrenKey` | `string \| null` | `null` | Tree rows: the property on each row holding its child rows (`T[]`). When set, the table renders a tree grid — child rows are indented under their parent behind an expand toggle in the first column, sorting applies per sibling group, and ArrowRight / ArrowLeft on a row open / close it. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `selectedChange` | `T[]` | Emits when `selected` changes (two-way binding). |
| `filtersChange` | `MkTableFilters` | Emits when `filters` changes (two-way binding). |
| `sortChange` | `MkSortChange` | Emitted when the sort column/direction changes. |
| `rowClick` | `T` | Emitted when a row is clicked (enable via `clickableRows`). |
| `selectionChange` | `T[]` | Emitted with the new selection whenever it changes (enable via `selectable`). |
| `expandedChange` | `T[]` | Emitted with the currently expanded rows whenever they change. |
| `columnResize` | `MkColumnResize` | Emitted when a column is resized (px). |
| `columnReorder` | `string[]` | Emitted with the new column key order after a reorder. |
| `cellEdit` | `MkCellEdit<T>` | Emitted when an inline-editable cell is saved. |
| `groupToggle` | `MkGroupToggle` | Emitted when a group header is expanded or collapsed. |
| `treeToggle` | `MkTreeToggle<T>` | Emitted when a parent row is expanded or collapsed (tree mode). |

Methods:

| Signature | Description |
| --- | --- |
| `setFilter(key: string, value: unknown): void` | Set one column's filter (`null` / `''` clears it). Updates `filters` and emits `filtersChange`; a no-op when unchanged. |
| `clearFilter(key: string): void` | Clear one column's filter. |
| `clearFilters(): void` | Clear every filter. |
| `scrollToRow(target: unknown, by?: "index" \| "key"): boolean` | Scroll a row into view. A number is the row's **display index** — its position among the rendered rows, group headers included, after sorting, filtering and tree expansion; anything else is a row key (the `trackKey` value, or the row object when there is none). Pass `'key'` to look a numeric key up. Returns `false` when the row is not currently displayed (filtered out, under a collapsed parent or group).  In virtual mode the row lands at the top of the viewport, just under the header; otherwise it is scrolled to the nearest edge. |
| `isTreeExpanded(row: T): boolean` | Whether a parent row's children are currently shown (tree mode). |
| `toggleTreeRow(row: T, event?: Event): void` | Show or hide a parent row's children (tree mode). |
| `expandAllRows(): void` | Expand every parent row (tree mode). |
| `collapseAllRows(): void` | Collapse every parent row (tree mode). |
| `getExportRows(options?: MkTableExportRowsOptions): MkTableExportRows<T>` | The rows and columns an export writes — exactly what `exportCsv` serialises, for other formats (XLSX, PDF, the clipboard, …): rows in display order with the current sort and header `filters` applied (every matching row, never just the virtual window) and tree children (`childrenKey`) flattened under their parent whether or not they are expanded, optionally only the selected ones; columns in the table's current order, restricted to `options.columns` when given, each carrying its header and `format` so what the user saw is what gets written.  ```ts const { rows, columns } = table.getExportRows({ selectedOnly: true }); const sheet = rows.map((row) =>   Object.fromEntries(columns.map((c) => [c.header ?? c.key, c.format ? c.format(row[c.key], row) : row[c.key]])), ); ``` |
| `exportCsv(options?: MkTableExportOptions): string` | The table's rows as CSV: current column order, column formatters applied, sorted and filtered the way they are shown, tree children flattened under their parent whether or not they are expanded. Downloads the file (default name `table.csv`) and returns the text. Built on `getExportRows`. |
| `collapseAllGroups(): void` | Collapse every group. |
| `expandAllGroups(): void` | Expand every group. |

### MkSort (directive)

Selector: `[mkSort]` · exportAs: `mkSort`

Docs: https://mk-kit.dev/components/sort

Import: `import { MkSort } from '@mk-kit/ui/table';`

Sort coordinator — apply `mkSort` to a table (or any container) to track
which column is sorted and in which direction. It holds no data: register
headers with `mkSortHeader`, then re-sort your rows in the
`(mkSortChange)` handler. Mirrors the Angular Material `matSort` model but
signal-based.

Clicking a header cycles asc → desc → unsorted (set `mkSortDisableClear` to
cycle asc ↔ desc only). `mkSortStart` flips the initial direction.

```html
<table mkSort mkSortActive="name" mkSortDirection="asc"
       (mkSortChange)="sortData($event)">
  <thead><tr>
    <th mkSortHeader="name">Name</th>
    <th mkSortHeader="size" mkSortHeaderStart="desc">Size</th>
  </tr></thead>
  …
</table>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `active` (two-way) | `string` | `''` | Id of the currently sorted column (two-way; empty when unsorted). |
| `direction` (two-way) | `MkSortDirection` | `'none'` | Current sort direction (two-way). |
| `mkSortStart` | `"asc" \| "desc"` | `'asc'` | Direction the first click on a header applies. Default `asc`. |
| `mkSortDisabled` | `boolean` | `false` | Disable sorting for every header. |
| `mkSortDisableClear` | `boolean` | `false` | Remove the "unsorted" step so headers cycle asc ↔ desc only. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `activeChange` | `string` | Emits when `active` changes (two-way binding). |
| `directionChange` | `MkSortDirection` | Emits when `direction` changes (two-way binding). |
| `sortChange` | `MkSortState` | Emits the new sort state whenever a header is activated. |

Methods:

| Signature | Description |
| --- | --- |
| `sort(header: MkSortable): void` | Advance the sort state for the given header (called on click/keyboard). |
| `isActive(id: string): boolean` | Whether the given column id is the active, non-cleared sort. |

### MkTableCell (directive)

Selector: `[mkTableCell]`

Docs: https://mk-kit.dev/components/table

Import: `import { MkTableCell } from '@mk-kit/ui/table';`

Marks an `<ng-template>` as the renderer for one column's cells, named by the
column `key`. Without it a cell can only be text — `MkTableColumn.format`
returns a string — so anything richer (a status tag, an avatar, a progress
bar, an action button) meant abandoning `mk-table` for a hand-rolled
`<table>`.

The value is the template's implicit context and the row is available as
`let-row`:

```html
<mk-table [columns]="cols" [data]="rows()">
  <ng-template mkTableCell="status" let-value let-row="row">
    <mk-tag [tone]="toneFor(value)">{{ label(value) }}</mk-tag>
  </ng-template>
</mk-table>
```

A column with both a template and a `format` uses the template; `format`
still applies to sorting/export paths that need a string.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkTableCell` (required) | `string` |  | Column key whose cells this template renders. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `template` | `TemplateRef<MkTableCellContext<T>>` | The projected template, rendered once per cell in that column. |

### MkTableRowDetail (directive)

Selector: `[mkTableRowDetail]`

Docs: https://mk-kit.dev/components/table

Import: `import { MkTableRowDetail } from '@mk-kit/ui/table';`

Marks an `<ng-template>` as the expandable detail content for `MkTable`
rows. The template's implicit context is the row object, so consumers can
destructure it with `let-row`:

```html
<mk-table [columns]="cols" [data]="rows()" expandable>
  <ng-template mkTableRowDetail let-row>
    <dl>… {{ row.notes }} …</dl>
  </ng-template>
</mk-table>
```

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `template` | `TemplateRef<{ $implicit: T; }>` | The projected detail template, rendered once per expanded row. |

### MkTableDataSource (class)

Docs: https://mk-kit.dev/components/table#data-source

Import: `import { MkTableDataSource } from '@mk-kit/ui/table';`

Server-side data adapter for `mk-table` — the page/sort/filter plumbing every
admin screen otherwise hand-rolls. A plain class (no component, no injection
required): give it a fetcher and bind its signals; every setter re-queries
the server and **stale responses never overwrite newer state** (latest-wins).

- `setFilter` is debounced (default 300 ms); page, sort and page size load
  immediately. Sort, filter and page-size changes reset to page 1.
- `rows` keeps its previous value while loading and on error, so the table
  never blanks mid-transition; `error` is cleared by the next successful
  load.
- Created in an injection context (a component field initialiser) it hooks
  `DestroyRef` and cleans up automatically; anywhere else, call
  `destroy` yourself.

```ts
interface User { id: number; name: string; email: string; }

Methods:

| Signature | Description |
| --- | --- |
| `setPage(page: number): void` | Jump to a 1-based page and load it immediately. |
| `setPageSize(size: number): void` | Change the page size; resets to page 1 and loads immediately. |
| `setSort(sort: MkSortState \| MkSortChange \| null): void` | Change the sort; resets to page 1 and loads immediately. Accepts either the `mkSort` directive's `MkSortState` or `mk-table`'s `MkSortChange` payload; a cleared sort (`direction: 'none'` or an empty column id) normalises to `null`. A no-op when the sort is unchanged. |
| `setFilter(query: string): void` | Change the free-text filter. The `filter` signal updates (and the page resets to 1) immediately, but the request is debounced — `refresh()` flushes it early. A no-op when the query is unchanged. |
| `setQuery(query: MkQueryGroup \| null): void` | Set (or clear with `null`) the structured query from `mk-query-builder`. Empty groups and unfinished rules are dropped before the request; a query with nothing left is sent as `null`. Resets to page 1 and loads at once. |
| `setFilters(filters: MkTableFilters \| null): void` | Set (or clear with `null` / `{}`) the per-column filters from `mk-table`'s header filter row — bind `(filtersChange)="ds.setFilters($event)"` and turn the table's `clientFilter` off. Empty entries are dropped before the request; nothing left is sent as `null`. Resets to page 1 and loads at once (the table already debounces nothing, so debounce the fetcher if your API needs it). A no-op when unchanged. |
| `refresh(): void` | Re-run the current request immediately (e.g. after a mutation). Flushes a pending debounced filter, since the request reads the live filter value. |
| `reload(): void` | Back to page 1 and load — the "filters changed outside the search box" case. Unlike `setPage`, this loads even when already on page 1, so callers no longer need `page() === 1 ? refresh() : setPage(1)`. |
| `connectSort(sort: MkSort): void` | Pipe an `mkSort` directive's changes into `setSort`. Idempotent per directive instance; all subscriptions are released by `destroy`. |
| `destroy(): void` | Cancel pending work: the debounce timer, any in-flight Observable fetch, and `connectSort` subscriptions. In-flight Promise settles are discarded. Called automatically on host destroy when created in an injection context. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `rows` | `Signal<T[]>` | Rows of the current page (`[]` until the first load lands). |
| `total` | `Signal<number>` | Total row count across all pages (feed to `mk-pagination`'s `total`). |
| `loading` | `Signal<boolean>` | True while the LATEST request is in flight. |
| `error` | `Signal<unknown>` | The last load's error, or `null`; cleared by the next successful load. |
| `page` | `Signal<number>` | Current 1-based page. |
| `pageSize` | `Signal<number>` | Current page size. |
| `sort` | `Signal<MkSortState \| null>` | Current sort, or `null` when unsorted. |
| `filter` | `Signal<string>` | Current filter query (updates immediately, even while debouncing). |
| `query` | `Signal<MkQueryGroup \| null>` | Current structured query, or `null`. |
| `filters` | `Signal<MkTableFilters \| null>` | Current per-column filters, or `null`. |
| `empty` | `Signal<boolean>` | True when a settled load reported no rows at all. |

### mkClientFetcher (function)

Import: `import { mkClientFetcher } from '@mk-kit/ui/table';`

In-memory `MkDataFetcher`: filter, sort and slice a full row set that
the app already holds (an API that returns everything). Lets a client-side
list use `MkTableDataSource` — same pager, footer and API as a
server-paged one — without hand-rolling `filtered/sorted/paged` computeds.

```ts
ds = new MkTableDataSource(mkClientFetcher(() => this.rows()));
```

```ts
function mkClientFetcher<T>(rows: () => readonly T[], opts?: MkClientFetcherOptions<T>): (req: MkDataRequest) => Promise<MkDataPage<T>>
```

### mkCompactFilters (function)

Import: `import { mkCompactFilters } from '@mk-kit/ui/table';`

Drop the empty entries of a filter map (`null` when nothing is left).

```ts
function mkCompactFilters(filters: MkTableFilters | null | undefined): MkTableFilters | null
```

### mkDownloadText (function)

Import: `import { mkDownloadText } from '@mk-kit/ui/table';`

Trigger a browser download of `text` as a file. No-op outside a DOM
(server-side rendering); returns whether a download was started.

```ts
function mkDownloadText(text: string, filename: string, type?: string): boolean
```

### mkExportCsv (function)

Import: `import { mkExportCsv } from '@mk-kit/ui/table';`

Serialise `rows` as CSV and download it. Returns the CSV text so callers
can also keep it (tests, previews, uploads).

```ts
function mkExportCsv<T>(rows: readonly T[], columns?: readonly MkCsvColumn<T>[], options?: MkCsvExportOptions): string
```

### mkToCsv (function)

Import: `import { mkToCsv } from '@mk-kit/ui/table';`

Serialise `rows` as CSV text.

Without `columns` every key of the first row is exported in its own order.
Column formatters are applied, so what the user saw in the table is what
lands in the file.

```ts
function mkToCsv<T>(rows: readonly T[], columns?: readonly MkCsvColumn<T>[], options?: MkCsvOptions): string
```

### MkCellEdit (interface)

Import: `import { MkCellEdit } from '@mk-kit/ui/table';`

Payload emitted by `MkTable.cellEdit` when an editable cell is saved.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `row` | `T` | The edited row. |
| `key` | `string` | The column key that was edited. |
| `value` | `string` | The new (string) value the user entered. |

### MkClientFetcherOptions (interface)

Import: `import { MkClientFetcherOptions } from '@mk-kit/ui/table';`

Options for `mkClientFetcher`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `match`? | `((row: T, query: string) => boolean) \| undefined` | Row matcher for `setFilter` text; default: case-insensitive substring over every string/number field. |
| `compare`? | `((a: T, b: T, sort: MkSortState) => number) \| undefined` | Comparator for an active sort; default: locale compare on `row[sort.active]`. |

### MkColumnResize (interface)

Import: `import { MkColumnResize } from '@mk-kit/ui/table';`

Payload emitted by `MkTable.columnResize` after a column resize.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `string` | The resized column's key. |
| `width` | `number` | The new width in pixels. |

### MkCsvColumn (interface)

Import: `import { MkCsvColumn } from '@mk-kit/ui/table';`

A column to export: the row property, its header, and an optional formatter.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `string` | Property key on each row object supplying the cell value. |
| `header`? | `string \| undefined` | Header text; defaults to `key`. |
| `format`? | `((value: unknown, row: T) => string) \| undefined` | Formatter turning the raw value into cell text (same shape as `MkTableColumn.format`). |

### MkCsvExportOptions (interface)

Import: `import { MkCsvExportOptions } from '@mk-kit/ui/table';`

Options for `mkExportCsv`.

Members (extends `MkCsvOptions`):

| Name | Type | Description |
| --- | --- | --- |
| `filename`? | `string \| undefined` | File name for the download (default `export.csv`; `.csv` is appended if missing). |

### MkCsvOptions (interface)

Import: `import { MkCsvOptions } from '@mk-kit/ui/table';`

Members:

| Name | Type | Description |
| --- | --- | --- |
| `delimiter`? | `string \| undefined` | Field separator (default `,`; use `;` for locales whose Excel expects it). |
| `header`? | `boolean \| undefined` | Emit the header row first (default `true`). |
| `newline`? | `string \| undefined` | Line terminator (default `\r\n`, per RFC 4180). |
| `bom`? | `boolean \| undefined` | Prefix a UTF-8 byte-order mark (default `true`) so Excel reads accented characters correctly. Only affects the downloaded file / returned text. |
| `sanitize`? | `boolean \| undefined` | Neutralise spreadsheet formula injection (default `true`): a text cell starting with `=`, `+`, `-`, `@`, tab or CR is prefixed with `'` so a malicious value cannot execute when opened in Excel / Sheets. Numbers are never touched, so `-5` stays `-5`. |
| `childrenKey`? | `string \| undefined` | Property holding child rows; when set, trees are flattened depth-first. |

### MkDataPage (interface)

Import: `import { MkDataPage } from '@mk-kit/ui/table';`

One page of server data returned by a `MkDataFetcher`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `rows` | `T[]` | The rows for the requested page. |
| `total` | `number` | Total number of rows across ALL pages (drives the pager). |

### MkDataRequest (interface)

Import: `import { MkDataRequest } from '@mk-kit/ui/table';`

The request handed to a `MkDataFetcher` on every load.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `page` | `number` | 1-based page index, matching `mk-pagination`. |
| `pageSize` | `number` | Number of rows per page. |
| `sort` | `MkSortState \| null` | Active sort, or `null` when unsorted (cleared sorts normalise to `null`). |
| `filter` | `string` | Free-text filter query (`''` = none). |
| `query` | `MkQueryGroup \| null` | Structured filter from `mk-query-builder` (`null` = none). Compacted: no empty groups or unfinished rules. |
| `filters` | `MkTableFilters \| null` | Per-column filters from `mk-table`'s header filter row (`null` = none), keyed by column key with empty entries dropped — see `MkTableDataSource.setFilters`. |

### MkGroupToggle (interface)

Import: `import { MkGroupToggle } from '@mk-kit/ui/table';`

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `unknown` | The toggled group's value. |
| `collapsed` | `boolean` | Whether the group is now collapsed. |

### MkSortable (interface)

Import: `import { MkSortable } from '@mk-kit/ui/table';`

The minimal shape `MkSort` needs from a header. Implemented by
`MkSortHeader`; declared separately so the coordinator does not depend
on the header's concrete type (avoids a circular import).

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `(): string` |  |
| `start` | `(): "asc" \| "desc" \| undefined` |  |
| `disabled` | `(): boolean` |  |
| `sortLabel` | `(): string` |  |

### MkSortChange (interface)

Import: `import { MkSortChange } from '@mk-kit/ui/table';`

Payload emitted by `MkTable.sortChange`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `string` | Column key sorted by. |
| `direction` | `MkSortDirection` | Resulting direction (`none` when sorting was cleared). |

### MkSortState (interface)

Import: `import { MkSortState } from '@mk-kit/ui/table';`

Current sort state emitted by `MkSort.mkSortChange`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `active` | `string` | Id of the column being sorted by (empty when cleared). |
| `direction` | `MkSortDirection` | Sort direction (`none` when cleared). |

### MkTableCellContext (interface)

Import: `import { MkTableCellContext } from '@mk-kit/ui/table';`

Context handed to an `[mkTableCell]` template.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `$implicit` | `unknown` | The cell's raw value (the row's property named by the column key). |
| `row` | `T` | The whole row, for cells that need more than one field. |

### MkTableColumn (interface)

Import: `import { MkTableColumn } from '@mk-kit/ui/table';`

Column definition for `MkTable`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `string` | Property key on each row object supplying the cell value. |
| `header` | `string` | Visible column header text. |
| `sortable`? | `boolean \| undefined` | Allow sorting by this column. |
| `align`? | `MkTableAlign \| undefined` | Cell/header alignment (default `start`). |
| `width`? | `string \| undefined` | Fixed column width (any CSS length). |
| `format`? | `((value: unknown, row: T) => string) \| undefined` | Optional formatter turning the raw value into display text. |
| `resizable`? | `boolean \| undefined` | Allow the user to drag-resize this column (needs `resizableColumns`). |
| `editable`? | `boolean \| undefined` | Make this column's cells inline-editable (double-click / Enter). |
| `pinned`? | `"left" \| "right" \| undefined` | Pin (freeze) this column to a side while the body scrolls horizontally. |
| `minWidth`? | `number \| undefined` | Minimum width in px when resizing (default 60). |
| `stack`? | `"footer" \| "title" \| "hide" \| undefined` | What becomes of this column when the table stacks into cards (see `MkTable.stackAt`). Omitted, the column renders as a labelled field: its `header` on one side, its value on the other.  - `'title'` — the card's heading. No label; the value identifies the   record at a glance (an order number, a product name). Mark one, or two   if something short belongs beside it such as a status or a total. - `'footer'` — pinned to the bottom of the card, full width and unlabelled.   Where an actions cell belongs: buttons read as buttons, rather than as   the answer to a label. - `'hide'` — not rendered at all. Not merely invisible: the cell is never   created, so a screen reader does not read it either. For columns that   only earn their place while scanning a grid, and especially for anything   an expandable row detail already repeats. |
| `filter`? | `false \| MkTableFilterKind \| undefined` | The header-row filter control for this column (rendered when the table is `MkTable.filterable`). Omitted, a filterable table gives the column a text filter; `false` leaves its filter cell empty.  - `'text'` — case-insensitive *contains* on the displayed (formatted) text. - `'select'` — equality against one of `filterOptions`; without   options, the distinct values found in `data`. - `'number'` / `'date'` — the control keeps rows whose value is **≥** the   entry. Set `{ min, max }` through `MkTable.filters` for an   inclusive range. Dates compare by local calendar day. |
| `filterOptions`? | `readonly (string \| number \| MkTableFilterOption)[] \| undefined` | Options of a `select` filter — strings / numbers, or `{ value, label }`. Omitted: every distinct value of the column in `data`, sorted. |
| `filterPlaceholder`? | `string \| undefined` | Placeholder of the filter control (text: `i18n.filter`; number / date: `i18n.filterMin`). |
| `compare`? | `((a: T, b: T) => number) \| undefined` | Custom ordering for this column, used instead of the built-in value comparison whenever it sorts. Return a negative number when `a` comes first. The table negates it for descending order, so keep the function pure. Lets a file list keep folders first, or a status column sort by rank rather than alphabet. |

### MkTableDataSourceOptions (interface)

Import: `import { MkTableDataSourceOptions } from '@mk-kit/ui/table';`

Construction options for `MkTableDataSource`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `pageSize`? | `number \| undefined` | Initial rows per page (default 10, matching `mk-pagination`). |
| `filterDebounce`? | `number \| undefined` | Debounce for `MkTableDataSource.setFilter` in ms (default 300). |

### MkTableExportOptions (interface)

Import: `import { MkTableExportOptions } from '@mk-kit/ui/table';`

Options for `MkTable.exportCsv`.

Members (extends `MkCsvExportOptions`, `MkTableExportRowsOptions`):

| Name | Type | Description |
| --- | --- | --- |
| `download`? | `boolean \| undefined` | Start the browser download (default `true`); `false` just returns the text. |

### MkTableExportRows (interface)

Import: `import { MkTableExportRows } from '@mk-kit/ui/table';`

What `MkTable.getExportRows` returns: the rows and the columns to write them with.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `rows` | `T[]` | The rows in display order — sorted the way they are shown, tree children flattened under their parent (expanded or not), selection applied when `selectedOnly` was set. |
| `columns` | `MkCsvColumn<T>[]` | The columns in the table's current (user-reordered) order, restricted to the requested keys, each with its header and formatter. |

### MkTableExportRowsOptions (interface)

Import: `import { MkTableExportRowsOptions } from '@mk-kit/ui/table';`

Options for `MkTable.getExportRows` — which rows and columns to export.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `selectedOnly`? | `boolean \| undefined` | Export only the selected rows (default: every row). |
| `columns`? | `readonly string[] \| undefined` | Restrict to these column keys, in table order (default: every column). |

### MkTableFilterOption (interface)

Import: `import { MkTableFilterOption } from '@mk-kit/ui/table';`

One option of a `select` header filter.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `value` | `unknown` | The value compared against the cell (by `String()` equality). |
| `label` | `string` | Visible option text. |

### MkTableFilterRange (interface)

Import: `import { MkTableFilterRange } from '@mk-kit/ui/table';`

An inclusive range accepted as the value of a `number` or `date` filter
(dates as `YYYY-MM-DD`, `Date` or a timestamp). Either bound may be omitted.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `min`? | `V \| null \| undefined` |  |
| `max`? | `V \| null \| undefined` |  |

### MkTableGroup (interface)

Import: `import { MkTableGroup } from '@mk-kit/ui/table';`

A group of rows produced by `MkTable.groupBy`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `unknown` | The shared group value. |
| `label` | `string` | Display label for the group header. |
| `rows` | `T[]` | The rows in this group, in display (sorted) order. |

### MkTreeToggle (interface)

Import: `import { MkTreeToggle } from '@mk-kit/ui/table';`

Payload of `(treeToggle)`: a parent row was expanded or collapsed.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `row` | `T` | The parent row. |
| `expanded` | `boolean` | Whether its child rows are now shown. |

### MkDataFetcher (type)

Import: `import { MkDataFetcher } from '@mk-kit/ui/table';`

Loads one page of data for a `MkDataRequest`. May return a `Promise`
(e.g. `fetch`) or an `Observable` (e.g. `HttpClient`); an Observable is
treated as single-shot — the first emission wins and the subscription is
released.

```ts
type MkDataFetcher<T> = ( req: MkDataRequest, ) => Promise<MkDataPage<T>> | Observable<MkDataPage<T>>;
```

### MkSortDirection (type)

Import: `import { MkSortDirection } from '@mk-kit/ui/table';`

Sort direction; `none` means unsorted.

```ts
type MkSortDirection = 'asc' | 'desc' | 'none';
```

### MkTableAlign (type)

Import: `import { MkTableAlign } from '@mk-kit/ui/table';`

Horizontal text alignment for a table column.

```ts
type MkTableAlign = 'start' | 'center' | 'end';
```

### MkTableDensity (type)

Import: `import { MkTableDensity } from '@mk-kit/ui/table';`

Row vertical density.

```ts
type MkTableDensity = 'comfortable' | 'compact';
```

### MkTableFilterKind (type)

Import: `import { MkTableFilterKind } from '@mk-kit/ui/table';`

Which control a column's header filter renders (see `MkTableColumn.filter`).

```ts
type MkTableFilterKind = 'text' | 'select' | 'number' | 'date';
```

### MkTableFilters (type)

Import: `import { MkTableFilters } from '@mk-kit/ui/table';`

Active header filters keyed by column key: a string for `text`, an option
value for `select`, a number / date (`>=`) or a `MkTableFilterRange`
for `number` and `date`. Empty strings and `null` mean "no filter".

```ts
type MkTableFilters = Record<string, unknown>;
```

## @mk-kit/ui/status

6 exports. `import { … } from '@mk-kit/ui/status';`

### MkBadge (component)

Selector: `mk-badge`

Docs: https://mk-kit.dev/components/badges-avatars

Import: `import { MkBadge } from '@mk-kit/ui/status';`

Badge — a compact status pill, typically for counts or short state labels.
Set `dot` for a minimal notification indicator with no text.

```html
<mk-badge tone="success">Active</mk-badge>
<mk-badge tone="danger" variant="solid">3</mk-badge>
<mk-badge tone="danger" dot aria-label="Unread messages" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `MkTone` | `'primary'` | Semantic color tone. |
| `variant` | `MkBadgeVariant` | `'soft'` | Visual treatment. |
| `size` | `MkSize` | `'md'` | Size scale. |
| `dot` | `boolean` | `false` | Render as a tiny dot (no text) for notification indicators. |

### MkEmptyState (component)

Selector: `mk-empty-state`

Docs: https://mk-kit.dev/components/empty-timeline

Import: `import { MkEmptyState } from '@mk-kit/ui/status';`

EmptyState — a centered placeholder for "nothing here yet" situations: empty
tables, no search results, a fresh dashboard, a cleared inbox. Provide a
`title` (and usually a `description`), an `icon` or projected media, and
call-to-action buttons via the actions slot.

Slots: `[mkEmptyStateMedia]` (custom illustration, overrides `icon`), default
content (extra body), `[mkEmptyStateActions]` (buttons).

```html
<mk-empty-state icon="search" title="No results"
  description="Try adjusting your filters.">
  <button mkButton mkEmptyStateActions variant="outline">Clear filters</button>
</mk-empty-state>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `string` | `''` | Name of a registered icon shown above the title (ignored if media is projected). |
| `title` | `string` | `''` | Main heading, e.g. "No invoices yet". |
| `description` | `string` | `''` | Supporting sentence under the title. |
| `size` | `MkSize` | `'md'` | Overall scale of the block. |

### MkSpinner (component)

Selector: `mk-spinner`

Docs: https://mk-kit.dev/components/loading

Import: `import { MkSpinner } from '@mk-kit/ui/status';`

Spinner — a circular indeterminate loading indicator. Exposes `role="status"`
with a visually-hidden label so assistive tech announces the loading state.
The animation slows under `prefers-reduced-motion`.

```html
<mk-spinner />
<mk-spinner size="lg" tone="neutral" label="Fetching results" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `MkSize` | `'md'` | Size scale. |
| `tone` | `MkTone` | `'primary'` | Semantic color tone. |
| `label` | `string` | `this.i18n.loading` | Visually-hidden status label announced to screen readers. |

### MkBadgeOverlay (directive)

Selector: `[mkBadgeOverlay]`

Docs: https://mk-kit.dev/components/badges-avatars

Import: `import { MkBadgeOverlay } from '@mk-kit/ui/status';`

Badge overlay — anchors a small badge (count, dot or short text) to a corner
of ANY element: an icon button, an avatar, a tab label. The host stays a
single tab stop; the badge is a decorative, non-focusable child.

- Numbers above `mkBadgeOverlayMax` (default 99) collapse to `99+`.
- `mkBadgeOverlayDot` renders a textless dot ("something is new").
- `mkBadgeOverlayAriaLabel` is the screen-reader text ("3 unread"). It is
  rendered in a visually hidden span and wired to the host with
  `aria-describedby`, so it is announced after the host's own name even
  when the host has an `aria-label`. When it is given, the visible badge is
  `aria-hidden` so the count is not read twice.
- Positions use logical insets, so `top-end` sits at the top-right in LTR
  and the top-left in RTL.

The badge is painted with the global `.mk-badge-overlay` styles from
`@mk-kit/ui/styles.css` and follows the `--mk-*` tone tokens.

```html
<button mkButton iconOnly aria-label="Notifications"
        [mkBadgeOverlay]="unread()" mkBadgeOverlayTone="danger"
        [mkBadgeOverlayAriaLabel]="unread() + ' unread'">
  <mk-icon name="bell" />
</button>

<mk-avatar name="Ada Lovelace" mkBadgeOverlay mkBadgeOverlayDot
           mkBadgeOverlayTone="success" mkBadgeOverlayPosition="bottom-end" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkBadgeOverlay` | `string \| number \| null \| undefined` | `null` | Badge content — a count or a short label. `null` / empty hides the badge unless `mkBadgeOverlayDot` is set. Numeric strings are treated as numbers so `mkBadgeOverlay="120"` also collapses to `99+`. |
| `mkBadgeOverlayPosition` | `MkBadgeOverlayPosition` | `'top-end'` | Corner the badge is anchored to (logical: `end` flips in RTL). |
| `mkBadgeOverlayTone` | `MkTone` | `'primary'` | Semantic color tone (same scale as `mk-badge`). |
| `mkBadgeOverlayDot` | `boolean` | `false` | Render a textless dot instead of the content. |
| `mkBadgeOverlayMax` | `number` | `99` | Numbers above this render as `<max>+`. `0` disables the cap. |
| `mkBadgeOverlayHidden` | `boolean` | `false` | Hide the badge while keeping the directive (and its aria wiring) in place. |
| `mkBadgeOverlayAriaLabel` | `string` | `''` | Screen-reader text for the badge, e.g. `"3 unread"`. Announced as the host's description; the visible badge becomes `aria-hidden`. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `Signal<string>` | The text painted in the badge (`''` in dot mode). |
| `visible` | `Signal<boolean>` | Whether the badge is currently rendered. |

### MkBadgeOverlayPosition (type)

Import: `import { MkBadgeOverlayPosition } from '@mk-kit/ui/status';`

Corner of the host an `MkBadgeOverlay` is anchored to.

```ts
type MkBadgeOverlayPosition = | 'top-end' | 'top-start' | 'bottom-end' | 'bottom-start';
```

### MkBadgeVariant (type)

Import: `import { MkBadgeVariant } from '@mk-kit/ui/status';`

Visual treatment for a `MkBadge`.

```ts
type MkBadgeVariant = 'solid' | 'soft' | 'outline';
```

## @mk-kit/ui/data

127 exports. `import { … } from '@mk-kit/ui/data';`

### MkAvatar (component)

Selector: `mk-avatar`

Docs: https://mk-kit.dev/components/badges-avatars

Import: `import { MkAvatar } from '@mk-kit/ui/data';`

Avatar — a user/entity image that gracefully falls back to initials derived
from `name`, or to a projected icon. The whole avatar is exposed as a single
labelled image to assistive tech.

```html
<mk-avatar name="Ada Lovelace" src="/ada.jpg" status="online" />
<mk-avatar name="Grace Hopper" />          <!-- initials fallback -->
<mk-avatar><svg>…</svg></mk-avatar>        <!-- icon fallback -->
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string \| undefined` |  | Image URL. When it fails to load the avatar falls back automatically. |
| `name` | `string \| undefined` |  | Display name; drives the initials fallback and the default alt text. |
| `alt` | `string \| undefined` |  | Explicit accessible label. Defaults to `name`, else "Avatar". |
| `size` | `MkSize` | `'md'` | Size scale. |
| `shape` | `MkAvatarShape` | `'circle'` | Outline shape. |
| `status` | `MkAvatarStatus \| undefined` |  | Presence indicator dot; omit for none. |

### MkAvatarGroup (component)

Selector: `mk-avatar-group`

Docs: https://mk-kit.dev/components/badges-avatars

Import: `import { MkAvatarGroup } from '@mk-kit/ui/data';`

Avatar group — overlaps a set of `MkAvatar` children and, when `max`
is set, collapses the overflow into a trailing "+N" bubble.

```html
<mk-avatar-group [max]="3">
  <mk-avatar name="Ada Lovelace" />
  <mk-avatar name="Grace Hopper" />
  <mk-avatar name="Alan Turing" />
  <mk-avatar name="Katherine Johnson" />
</mk-avatar-group>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `max` | `number` | `undefined` | Maximum avatars to show before collapsing the rest into "+N". |
| `size` | `MkSize` | `'md'` | Size of the overflow bubble (match your avatars' size). |

### MkBadge (component)

Selector: `mk-badge`

Docs: https://mk-kit.dev/components/badges-avatars

Import: `import { MkBadge } from '@mk-kit/ui/data';`

Badge — a compact status pill, typically for counts or short state labels.
Set `dot` for a minimal notification indicator with no text.

```html
<mk-badge tone="success">Active</mk-badge>
<mk-badge tone="danger" variant="solid">3</mk-badge>
<mk-badge tone="danger" dot aria-label="Unread messages" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `MkTone` | `'primary'` | Semantic color tone. |
| `variant` | `MkBadgeVariant` | `'soft'` | Visual treatment. |
| `size` | `MkSize` | `'md'` | Size scale. |
| `dot` | `boolean` | `false` | Render as a tiny dot (no text) for notification indicators. |

### MkBarChart (component)

Selector: `mk-bar-chart`

Docs: https://mk-kit.dev/components/charts

Import: `import { MkBarChart } from '@mk-kit/ui/data';`

BarChart — compares a measure across categories with one or more series
(grouped or `stacked`), `vertical` (default) or `horizontal`. Dependency-free
SVG on the validated `--mk-chart-*` palette; ships a legend for ≥ 2 series, a
value axis with gridlines, per-bar hover tooltips and a screen-reader table.

```html
<mk-bar-chart orientation="horizontal"
  [categories]="['Q1','Q2','Q3','Q4']"
  [series]="[{ name: 'Revenue', data: [12,19,15,22] }]" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `categories` | `readonly string[]` | `[]` | Category labels along the category axis. |
| `series` | `readonly MkChartSeries[]` | `[]` | One or more data series (values align to `categories`). |
| `orientation` | `MkBarOrientation` | `'vertical'` | Bar direction. |
| `width` | `number` | `480` | Intrinsic width in viewBox units — the fallback before the host is measured, and the fixed drawing width when `responsive` is off. |
| `responsive` | `boolean` | `true` | Match the viewBox width to the host's actual width so `height` means pixels and a wide container no longer stretches the chart vertically. Set false to pin the drawing to `width` (the pre-0.8 behaviour). |
| `height` | `number` | `260` | Intrinsic height. |
| `stacked` | `boolean` | `false` | Stack series into one bar per category instead of grouping. |
| `showGrid` | `boolean` | `true` | Show gridlines behind the bars. |
| `showLegend` | `boolean \| undefined` | `undefined` | Force the legend on/off (defaults to on when there are ≥ 2 series). |
| `labelAngle` | `number \| "auto"` | `'auto'` | Category-label tilt in degrees. `'auto'` (the default) leaves labels flat while they fit and tilts them 45° when they would collide — the axis of a narrow chart is otherwise an unreadable smear. A number pins the angle (0 = always flat, 30/45 = always tilted); values are clamped to 0…90.  Tilting reserves the extra vertical room it needs, so `height` still means the height you asked for. When even tilted labels cannot fit, the chart thins them — every Nth label is dropped rather than overlapped. |
| `label` | `string` | `''` | Accessible summary; generated from the data when omitted. |
| `interactive` | `boolean` | `false` | Make bars clickable + keyboard-focusable (`role="button"`, accessible name) and emit `barClick`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `barClick` | `{ series: MkChartSeries; seriesIndex: number; category: string; categoryIndex: number; value: number; }` | A bar was clicked or activated with Enter / Space (needs `interactive`). |

### MkCalendarHeatmap (component)

Selector: `mk-calendar-heatmap`

Docs: https://mk-kit.dev/components/charts

Import: `import { MkCalendarHeatmap } from '@mk-kit/ui/data';`

Calendar heatmap — a GitHub-style year of daily squares: weeks as columns,
weekdays as rows, each day shaded by its value. Rendered as a semantic
`<table>` (month headers span their week columns, weekday names are row
headers, every cell carries its formatted value for screen readers) with
intensities mixed from `color` over the surface via `color-mix`, so it
tracks the theme. Values are bucketed linearly against the range maximum
into `levels` steps; days with value 0 (or no entry) render transparent.

Shows the last 12 months ending today by default; set `year` for a fixed
calendar year.

```html
<mk-calendar-heatmap
  [data]="contributions"
  [year]="2026"
  (cellClick)="openDay($event.date)"
/>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `readonly MkCalendarHeatmapEntry[]` | `[]` | The daily values. Days without an entry count as 0. |
| `year` | `number \| null` | `null` | Show a fixed calendar year; unset shows the last 12 months ending today. |
| `firstDayOfWeek` | `number` | `1` | First weekday of the columns: 0 = Sunday … 6 = Saturday. |
| `color` | `string` | `'var(--mk-primary)'` | Base colour mixed over the surface for intensity. |
| `levels` | `number` | `5` | Number of intensity buckets in the ramp. |
| `format` | `((date: Date, value: number) => string) \| null` | `null` | Formatter for each cell's title / screen-reader text (and legend max). |
| `showScale` | `boolean` | `true` | Show the less→more colour ramp legend. |
| `label` | `string` | `''` | Accessible summary; generated from the data when omitted. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `cellClick` | `MkCalendarHeatmapCell` | Emits the clicked day and its value. |

### MkCard (component)

Selector: `mk-card`

Docs: https://mk-kit.dev/components/cards-lists

Import: `import { MkCard } from '@mk-kit/ui/data';`

Card — a themed surface container that groups related content. Compose it
with the projected `mk-card-header`, `mk-card-title` and `mk-card-footer`
parts, or drop plain content straight into the body.

```html
<mk-card variant="elevated">
  <mk-card-header>
    <mk-card-title>Monthly revenue</mk-card-title>
  </mk-card-header>
  Body content goes here.
  <mk-card-footer>
    <button mkButton variant="ghost">Details</button>
  </mk-card-footer>
</mk-card>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `MkCardVariant` | `'elevated'` | Surface treatment: raised shadow, hairline border, or tinted fill. |
| `padding` | `MkCardPadding` | `'md'` | Internal spacing applied to the body, header and footer. |

### MkCardFooter (component)

Selector: `mk-card-footer, [mkCardFooter]`

Import: `import { MkCardFooter } from '@mk-kit/ui/data';`

Card footer region — a padded band separated from the body by a hairline
border, usually holding actions aligned to the end.

### MkCardHeader (component)

Selector: `mk-card-header, [mkCardHeader]`

Docs: https://mk-kit.dev/components/cards-lists

Import: `import { MkCardHeader } from '@mk-kit/ui/data';`

Card header region — a padded band separated from the body by a hairline
border. Typically wraps a `MkCardTitle` and optional actions.

### MkCardTitle (component)

Selector: `mk-card-title`

Import: `import { MkCardTitle } from '@mk-kit/ui/data';`

Card title — semantic heading text for a card header. Renders as bold,
emphasised text; wrap the projected content in your own heading element if a
specific heading level is required for the document outline.

### MkCarousel (component)

Selector: `mk-carousel`

Docs: https://mk-kit.dev/components/data

Import: `import { MkCarousel } from '@mk-kit/ui/data';`

Carousel — an accessible slides/gallery. Project slides marked with
`mkCarouselSlide`; get prev/next arrows, dot indicators, Arrow-key
navigation, pointer swipe (touch or mouse drag; vertical page scroll stays
native) and optional autoplay that pauses on hover/focus. The current slide
is a two-way `index` model.

```html
<mk-carousel ariaLabel="Featured" autoplay>
  <div mkCarouselSlide>…</div>
  <div mkCarouselSlide>…</div>
</mk-carousel>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `index` (two-way) | `number` | `0` | Two-way current slide index. |
| `ariaLabel` | `string` | `this.i18n.carouselLabel` | Accessible label for the carousel region. |
| `loop` | `boolean` | `true` | Wrap around at the ends. |
| `showDots` | `boolean` | `true` | Show the dot indicators. |
| `showArrows` | `boolean` | `true` | Show the prev/next arrows. |
| `autoplay` | `boolean` | `false` | Advance automatically. Pauses transiently on hover/focus/pointer-down and shows a persistent pause/play toggle (`userPaused`). Never runs when the user prefers reduced motion. |
| `interval` | `number` | `5000` | Autoplay interval in ms. |
| `userPaused` (two-way) | `boolean` | `false` | Persistent, user-controlled pause (WCAG 2.2.2). Latched by the pause/play toggle; the transient hover/focus pause never overrides it. Two-way so consumers can bind or preset it. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `indexChange` | `number` | Emits when `index` changes (two-way binding). |
| `userPausedChange` | `boolean` | Emits when `userPaused` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `goTo(i: number): void` | Go to slide `i` (clamped, or wrapped when `loop`). |
| `next(): void` |  |
| `prev(): void` |  |

### MkCode (component)

Selector: `mk-code`

Docs: https://mk-kit.dev/components/data

Import: `import { MkCode } from '@mk-kit/ui/data';`

Code — a read-only, themed code block with syntax highlighting, an optional
filename header, line numbers and a copy button. Highlighting reuses the same
dependency-free tokenizer as `MkCodeEditor`. For an editable field use
`mk-code-editor` instead.

```html
<mk-code language="json" filename="config.json" [code]="json" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `code` | `string` | `''` | The source to display. |
| `language` | `MkCodeLanguage` | `'plaintext'` | Language for highlighting. |
| `filename` | `string` | `''` | Optional filename shown in a header bar. |
| `lineNumbers` | `boolean` | `false` | Show a line-number gutter. |
| `copyable` | `boolean` | `true` | Show the copy button. |
| `wrap` | `boolean` | `false` | Soft-wrap long lines instead of scrolling horizontally. |

### MkCountdown (component)

Selector: `mk-countdown`

Docs: https://mk-kit.dev/components/data

Import: `import { MkCountdown } from '@mk-kit/ui/data';`

Countdown — ticks every second and shows the time remaining until a target
instant as days / hours / minutes / seconds. Emits `finished` once when
the target passes and then keeps showing zeros (or `finishedText`).

```html
<mk-countdown [to]="launchDate" (finished)="onLaunch()" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `to` | `Date \| null` | `null` | The target instant to count down to. |
| `showDays` | `boolean` | `true` | Show the days segment; when false, days roll into the hours value. |
| `showLabels` | `boolean` | `true` | Show the textual label beneath each value. |
| `pad` | `boolean` | `true` | Zero-pad values to two digits. |
| `finishedText` | `string` | `''` | Text to show instead of zeros once the countdown finishes. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `finished` | `void` | Fires exactly once when the target instant is reached. |

### MkDescItem (component)

Selector: `mk-desc-item`

Import: `import { MkDescItem } from '@mk-kit/ui/data';`

A single term/detail row of `MkDescriptionList`: `term` becomes the
`<dt>`, the projected content the `<dd>`. The row itself renders nothing —
the list reads its rows and writes `<dt>`/`<dd>` as direct children of the
`<dl>`, which is what HTML and assistive tech require (a wrapper element
between `<dl>` and `<dt>` fails axe `definition-list` / `dlitem`).

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `term` | `string` | `''` | The term (label) shown in the `<dt>`. |

### MkDescriptionList (component)

Selector: `mk-description-list`

Docs: https://mk-kit.dev/components/cards-lists

Import: `import { MkDescriptionList } from '@mk-kit/ui/data';`

DescriptionList — a semantic `<dl>` of term/detail pairs for entity-detail and
metadata panels. Project `MkDescItem` rows; values may be rich content
(badges, links, …). In `grid` layout terms align in a shared column; in
`stacked` each term sits above its value.

```html
<mk-description-list>
  <mk-desc-item term="Status"><mk-badge tone="success">Active</mk-badge></mk-desc-item>
  <mk-desc-item term="Owner">Ada Lovelace</mk-desc-item>
</mk-description-list>
```

Only `mk-desc-item` children are rendered; the `<dl>` always contains plain
`<dt>`/`<dd>` pairs.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `layout` | `MkDescriptionLayout` | `'grid'` | `grid` aligns terms in a column; `stacked` puts each term above its value. |
| `divided` | `boolean` | `false` | Draw a divider between rows. |

### MkDiff (component)

Selector: `mk-diff`

Docs: https://mk-kit.dev/components/data

Import: `import { MkDiff } from '@mk-kit/ui/data';`

Diff — a text comparison view for revisions (before ⇄ after). Computes an LCS
line diff with optional intra-line word highlighting and renders a `unified`
(single-column, +/-) or `split` (side-by-side) view with line numbers and an
add/remove summary.

```html
<mk-diff [before]="v1" [after]="v2" mode="split" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `before` | `string` | `''` | The original ("before") text. |
| `after` | `string` | `''` | The new ("after") text. |
| `mode` | `MkDiffMode` | `'unified'` | Layout: single-column `unified` or side-by-side `split`. |
| `wordHighlight` | `boolean` | `true` | Highlight the specific words that changed within a line. |
| `lineNumbers` | `boolean` | `true` | Show line-number gutters. |
| `ignoreTrailingWhitespace` | `boolean` | `false` | Ignore trailing whitespace when comparing lines. |
| `showStats` | `boolean` | `true` | Show the +added / −removed summary header. |
| `beforeLabel` | `string` | `this.i18n.diffBefore` | Column labels (split view header / a11y). |
| `afterLabel` | `string` | `this.i18n.diffAfter` |  |

### MkDivider (component)

Selector: `mk-divider`

Docs: https://mk-kit.dev/components/cards-lists

Import: `import { MkDivider } from '@mk-kit/ui/data';`

Divider — a themed separator rule. Renders horizontally by default; set
`orientation="vertical"` for an inline vertical rule. Project content to
label a horizontal divider (the label sits centred between two rules).

```html
<mk-divider />
<mk-divider>OR</mk-divider>
<mk-divider orientation="vertical" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `MkDividerOrientation` | `'horizontal'` | Axis the rule is drawn along. |

### MkDonutChart (component)

Selector: `mk-donut-chart`

Docs: https://mk-kit.dev/components/proportion-charts

Import: `import { MkDonutChart } from '@mk-kit/ui/data';`

DonutChart — proportions of a whole as a ring (or a full pie when
`thickness` covers the radius). Dependency-free SVG on the validated
`--mk-chart-*` palette; ships a value/percent legend, per-slice hover
tooltips, an optional centre label, and a screen-reader data table.

```html
<mk-donut-chart centerLabel="1,240" centerSublabel="Total"
  [slices]="[{ name: 'Direct', value: 540 }, { name: 'Search', value: 700 }]" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `slices` | `readonly MkChartSlice[]` | `[]` | The slices; each `value` contributes to the whole. |
| `size` | `number` | `220` | Diameter in viewBox units (the SVG scales to its container). |
| `thickness` | `number` | `34` | Ring thickness. Set `0` (or ≥ radius) for a full pie. |
| `showLegend` | `boolean` | `true` | Show the legend with values + percentages. |
| `centerLabel` | `string` | `''` | Big centre label (e.g. a total). Donut only. |
| `centerSublabel` | `string` | `''` | Small centre caption under the label. |
| `label` | `string` | `''` | Accessible summary; generated from the data when omitted. |
| `interactive` | `boolean` | `false` | Make slices (and legend rows) clickable and keyboard-focusable: they get `role="button"` + an accessible name and emit `sliceClick`. Off by default — the chart stays a static picture with its screen-reader table. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `sliceClick` | `{ slice: MkChartSlice; index: number; }` | A slice was clicked or activated with Enter / Space (needs `interactive`). |

### MkEmptyState (component)

Selector: `mk-empty-state`

Docs: https://mk-kit.dev/components/empty-timeline

Import: `import { MkEmptyState } from '@mk-kit/ui/data';`

EmptyState — a centered placeholder for "nothing here yet" situations: empty
tables, no search results, a fresh dashboard, a cleared inbox. Provide a
`title` (and usually a `description`), an `icon` or projected media, and
call-to-action buttons via the actions slot.

Slots: `[mkEmptyStateMedia]` (custom illustration, overrides `icon`), default
content (extra body), `[mkEmptyStateActions]` (buttons).

```html
<mk-empty-state icon="search" title="No results"
  description="Try adjusting your filters.">
  <button mkButton mkEmptyStateActions variant="outline">Clear filters</button>
</mk-empty-state>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `string` | `''` | Name of a registered icon shown above the title (ignored if media is projected). |
| `title` | `string` | `''` | Main heading, e.g. "No invoices yet". |
| `description` | `string` | `''` | Supporting sentence under the title. |
| `size` | `MkSize` | `'md'` | Overall scale of the block. |

### MkFunnelChart (component)

Selector: `mk-funnel-chart`

Docs: https://mk-kit.dev/components/proportion-charts

Import: `import { MkFunnelChart } from '@mk-kit/ui/data';`

FunnelChart — decreasing stacked trapezoids visualising conversion through a
sequence of stages. Each band's top width tracks its own value and its bottom
width tracks the next stage's value, so consecutive bands connect into a
funnel. Dependency-free SVG on the validated `--mk-chart-*` palette; each band
is labelled with its value and its conversion relative to the top stage, and a
screen-reader table mirrors the data.

```html
<mk-funnel-chart
  [segments]="[
    { label: 'Visits', value: 1000 },
    { label: 'Signups', value: 400 },
    { label: 'Paid', value: 120 },
  ]" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `segments` | `readonly MkFunnelSegment[]` | `[]` | The funnel stages, ordered largest → smallest conceptually. |
| `width` | `number` | `420` | Intrinsic width (viewBox units; the SVG scales to its container). |
| `height` | `number` | `300` | Intrinsic height. |
| `showLegend` | `boolean \| undefined` | `undefined` | Force the legend on/off (funnels label each band, so off by default). |
| `showValues` | `boolean` | `true` | Render the value + conversion text on each band. |
| `label` | `string` | `''` | Accessible summary; generated from the data when omitted. |

### MkGauge (component)

Selector: `mk-gauge`

Docs: https://mk-kit.dev/components/proportion-charts

Import: `import { MkGauge } from '@mk-kit/ui/data';`

Gauge — a single-metric radial dial (a KPI: "68% of quota"). Dependency-free
SVG: a track arc with a value arc filled proportionally to `value` on the
`[min, max]` scale, and a centred value + label. The sweep is configurable
(`arc`, default 270°). Exposes `role="meter"` for assistive tech.

```html
<mk-gauge [value]="68" label="of quota" unit="%" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | `0` | The current value. |
| `min` | `number` | `0` | Scale minimum. |
| `max` | `number` | `100` | Scale maximum. |
| `arc` | `number` | `270` | Sweep of the arc in degrees (30–360). |
| `size` | `number` | `180` | Intrinsic size (viewBox units; the SVG scales to its container). |
| `thickness` | `number` | `14` | Arc thickness. |
| `color` | `string` | `'var(--mk-primary)'` | Value-arc colour. |
| `trackColor` | `string` | `'var(--mk-border-subtle)'` | Track (background arc) colour. |
| `label` | `string` | `''` | Label under the value. |
| `unit` | `string` | `''` | Unit appended to the value (e.g. `%`). |
| `valueText` | `string` | `''` | Override the centred value text. |

### MkHeatmap (component)

Selector: `mk-heatmap`

Docs: https://mk-kit.dev/components/charts

Import: `import { MkHeatmap } from '@mk-kit/ui/data';`

Heatmap — a matrix of cells shaded by value intensity, for correlation
grids, activity-by-time tables and the like. Rendered as a semantic
`<table>` (so it is inherently screen-reader friendly) with cell colours
mixed from `accent` over the surface via `color-mix`, so it tracks the theme.

Printed values (`showValues`) pick `--mk-text` or `--mk-text-inverse` per
cell by contrast against that cell's actual colour, in both themes — see
`mkHeatmapCellColors`.

```html
<mk-heatmap
  [xLabels]="hours" [yLabels]="days" [data]="matrix()" showValues />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `xLabels` | `readonly string[]` | `[]` | Column labels (x axis). |
| `yLabels` | `readonly string[]` | `[]` | Row labels (y axis). |
| `data` | `readonly (readonly (number \| null)[])[]` | `[]` | Row-major matrix: `data[row][col]`. Use `null` for a blank cell. |
| `min` | `number \| null` | `null` | Override the low end of the colour domain (defaults to the data min). |
| `max` | `number \| null` | `null` | Override the high end of the colour domain (defaults to the data max). |
| `accent` | `string` | `'var(--mk-primary)'` | Base colour mixed over the surface for intensity. |
| `showValues` | `boolean` | `false` | Print each cell's value inside it. |
| `showScale` | `boolean` | `true` | Show the min→max colour scale legend. |
| `format` | `(value: number) => string` | `mkFormatCompact` | Formatter for cell + legend values. |
| `label` | `string` | `''` | Accessible summary; generated from the data when omitted. |

### MkInlineEdit (component)

Selector: `mk-inline-edit` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/table

Import: `import { MkInlineEdit } from '@mk-kit/ui/data';`

InlineEdit — click a piece of text to edit it in place. The display is a
button that swaps to an input on click (or Enter/Space); Enter or blur saves,
Escape reverts. Ideal for editable labels in tables and detail panels.
Implements `ControlValueAccessor` + a two-way `value` model of `string`.

```html
<mk-inline-edit [(value)]="title" placeholder="Untitled" />
<mk-inline-edit multiline [(value)]="notes" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `string` | `''` | Two-way edited value. |
| `placeholder` | `string` | `this.i18n.empty` | Shown (muted) when the value is empty. |
| `multiline` | `boolean` | `false` | Use a multi-line textarea; Enter inserts a newline, blur/✓ saves. |
| `saveOnBlur` | `boolean` | `true` | Save when the field loses focus (otherwise blur cancels). |
| `ariaLabel` | `string` | `this.i18n.edit` | Accessible label for the edit trigger + field. |
| `disabled` | `boolean` | `false` | Disable editing. |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `size` | `MkSize` | `'md'` | Control size. Ignored when nested in an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |
| `saved` | `string` | Emitted with the new value when an edit is saved. |
| `cancelled` | `void` | Emitted when an edit is cancelled. |

### MkJsonViewer (component)

Selector: `mk-json-viewer` · exportAs: `mkJsonViewer`

Docs: https://mk-kit.dev/components/data

Import: `import { MkJsonViewer } from '@mk-kit/ui/data';`

JsonViewer — a read-only, collapsible tree for JSON-ish data: objects and
arrays fold behind disclosure buttons (with a `{…} n items` preview),
primitives are colour-coded by type, and circular references render as
`[Circular]` instead of recursing. `expandDepth` controls how much is open
initially; `expandAll()` / `collapseAll()` are available on the component.

The complement of `mk-code-editor`: the editor edits JSON text, this
explores JSON *data* (API responses, entity payloads, config dumps).

```html
<mk-json-viewer [data]="response" [expandDepth]="2" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `unknown` |  | The value to display (any JSON-serialisable data). |
| `expandDepth` | `number` | `1` | How many levels start expanded (root = level 1). |
| `aria-label` | `string` | `this.i18n.jsonLabel` | Accessible label of the tree region. |

Methods:

| Signature | Description |
| --- | --- |
| `expandAll(): void` | Expand every object/array node. |
| `collapseAll(): void` | Collapse everything (the root stays visible). |

### MkLineChart (component)

Selector: `mk-line-chart`

Docs: https://mk-kit.dev/components/charts

Import: `import { MkLineChart } from '@mk-kit/ui/data';`

LineChart — a line (or `area`) chart for change over time / ordered
categories, with one or more series. Dependency-free SVG on the validated
`--mk-chart-*` palette; ships a legend for ≥ 2 series, a value axis, a
hover crosshair with a shared tooltip, and a screen-reader data table.

```html
<mk-line-chart area
  [categories]="months"
  [series]="[{ name: 'Sessions', data: sessions() }]" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `categories` | `readonly string[]` | `[]` | Ordered category labels along the x axis. |
| `series` | `readonly MkChartSeries[]` | `[]` | One or more data series (values align to `categories`). |
| `width` | `number` | `480` | Intrinsic width in viewBox units — the fallback before the host is measured, and the fixed drawing width when `responsive` is off. |
| `responsive` | `boolean` | `true` | Match the viewBox width to the host's actual width so `height` means pixels and a wide container no longer stretches the chart vertically. Set false to pin the drawing to `width` (the pre-0.8 behaviour). |
| `height` | `number` | `260` | Intrinsic height. |
| `area` | `boolean` | `false` | Fill the area under each line. |
| `stacked` | `boolean` | `false` | Stack the series (cumulative bands) — implies filled areas. |
| `showDots` | `boolean` | `false` | Draw a dot at every data point. |
| `showGrid` | `boolean` | `true` | Show gridlines. |
| `showLegend` | `boolean \| undefined` | `undefined` | Force the legend on/off (defaults to on when there are ≥ 2 series). |
| `label` | `string` | `''` | Accessible summary; generated from the data when omitted. |
| `interactive` | `boolean` | `false` | Make x positions keyboard-focusable (`role="button"`, accessible name) and emit `pointClick`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `pointClick` | `{ index: number; category: string; values: Array<{ series: MkChartSeries; value: number; }>; }` | A category (x position) was clicked or activated with Enter / Space (needs `interactive`). |

### MkList (component)

Selector: `mk-list`

Docs: https://mk-kit.dev/components/cards-lists

Import: `import { MkList } from '@mk-kit/ui/data';`

List — a vertical stack of `MkListItem`s with `role="list"` semantics.

```html
<mk-list>
  <mk-list-item>Dashboard</mk-list-item>
  <mk-list-item interactive (activated)="open()">Settings</mk-list-item>
</mk-list>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `bordered` | `boolean` | `false` | Draw hairline separators between items. |

### MkListItem (component)

Selector: `mk-list-item`

Docs: https://mk-kit.dev/components/cards-lists

Import: `import { MkListItem } from '@mk-kit/ui/data';`

List item — a row inside `MkList`. Project leading/trailing adornments
with the `mkListLeading` / `mkListTrailing` attributes. Set `interactive`
to make the row focusable and clickable (Enter/Space activate it).

```html
<mk-list-item interactive [selected]="active()" (activated)="pick()">
  <mk-avatar mkListLeading name="Ada" />
  Ada Lovelace
  <mk-badge mkListTrailing tone="success">New</mk-badge>
</mk-list-item>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `interactive` | `boolean` | `false` | Make the row focusable/clickable with hover + keyboard activation. |
| `selected` | `boolean` | `false` | Highlight the row as the current selection. |
| `disabled` | `boolean` | `false` | Disable interaction and dim the row. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `activated` | `void` | Emitted on click / Enter / Space when `interactive`. |

### MkLogViewer (component)

Selector: `mk-log-viewer` · exportAs: `mkLogViewer`

Docs: https://mk-kit.dev/components/markdown

Import: `import { MkLogViewer } from '@mk-kit/ui/data';`

LogViewer — a virtualized, tail-following log / terminal pane. Renders only
the visible window of a (ring-buffered) line array, parses ANSI SGR colour
codes into theme-aware spans, follows new output at the bottom until the
user scrolls away, and highlights plain-string search matches.

```html
<mk-log-viewer
  [lines]="lines()"
  [(follow)]="follow"
  [query]="search()"
  (matches)="count.set($event)"
/>
```

Wrap mode (`[wrap]="true"` or the toolbar toggle) soft-wraps long lines;
because wrapped rows have no fixed height, wrap mode renders **without**
virtualization — fine up to a few thousand lines, so keep `maxLines`
modest when wrapping is expected.

`query` is matched as a case-insensitive plain string — no regex.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `lines` | `readonly string[]` | `[]` | The log lines (may contain ANSI SGR escape sequences). |
| `follow` (two-way) | `boolean` | `true` | Stick to the bottom as new lines arrive (two-way; detaches on scroll-up). |
| `wrap` (two-way) | `boolean` | `false` | Soft-wrap long lines (two-way; disables virtualization — see class docs). |
| `ansi` | `boolean` | `true` | Parse ANSI SGR colour codes; `false` renders lines verbatim. |
| `query` | `string` | `''` | Case-insensitive plain-string search; matches are highlighted. |
| `maxLines` | `number` | `10_000` | Ring buffer size: oldest lines are dropped beyond this. |
| `itemHeight` | `number` | `20` | Fixed row height in px (drives virtualization; also sets line-height). |
| `hideToolbar` | `boolean` | `false` | Hide the built-in toolbar row. |
| `aria-label` | `string` | `this.i18n.logViewerLabel` | Accessible label of the log region. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `followChange` | `boolean` | Emits when `follow` changes (two-way binding). |
| `wrapChange` | `boolean` | Emits when `wrap` changes (two-way binding). |
| `matches` | `number` | Emits the total number of `query` matches whenever it changes. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `matchCount` | `Signal<number>` | Total number of case-insensitive plain-string matches of `query`. |

### MkMarkdown (component)

Selector: `mk-markdown`

Docs: https://mk-kit.dev/components/markdown

Import: `import { MkMarkdown } from '@mk-kit/ui/data';`

Markdown — renders a CommonMark subset (see `mkParseMarkdown` for the
exact syntax list) with zero runtime dependencies. Built for admin-app
content: changelogs, AI output, user notes.

SECURITY MODEL: raw HTML in the source is never passed through — it is
always escaped and shown as text, and link/image URLs are restricted to
http/https/mailto/relative, so the rendered string contains only markup the
renderer itself generates. It is bound via `[innerHTML]` and additionally
passes through Angular's `DomSanitizer` (no `bypassSecurityTrustHtml`),
which keeps every element and attribute the renderer emits.

```html
<mk-markdown [source]="changelog" linkTarget="_blank" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `source` | `string` | `''` | Markdown source text. |
| `autolink` | `boolean` | `false` | Turn bare `http(s)://…` URLs into links. Off by default. |
| `linkTarget` | `"" \| "_blank"` | `''` | Link target; `'_blank'` also adds `rel="noopener noreferrer"`. |

### MkOrgChart (component)

Selector: `mk-org-chart` · exportAs: `mkOrgChart`

Docs: https://mk-kit.dev/components/org-chart

Import: `import { MkOrgChart } from '@mk-kit/ui/data';`

Organisation chart — a reporting-line hierarchy drawn with plain nested
lists and CSS connectors (no canvas, prints and themes like everything
else). Feed it a tree (`nodes`) or convert a flat `parentId` list with
`mkOrgChartFromFlat`. Nodes render as a default card (avatar /
initials, label, `data.title`) or through an `mkOrgChartNodeDef` template.

Follows the ARIA tree pattern (`role="tree"` / `treeitem` / `group`, one
roving tab stop). Keyboard (top-down; the axes swap for `orientation="left"`
and in RTL): Down = first child (expands a collapsed node first), Up =
parent, Left/Right = previous/next sibling, Home/End = first/last visible
node, Enter/Space = select (or toggle when not selectable), `*` = expand
all siblings, `+`/`-` = expand/collapse.

```html
<mk-org-chart
  [nodes]="company"
  selectable
  [(selected)]="personId"
  collapsible
  (nodeClick)="open($event)"
/>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodes` | `readonly MkOrgChartNode<T>[]` | `[]` | The hierarchy to render (roots first). |
| `orientation` | `MkOrgChartOrientation` | `'top'` | Root at the top (children below) or at the inline start (children to the side). |
| `selectable` | `boolean` | `false` | Allow choosing a node (adds selection styling + `aria-selected`). |
| `collapsible` | `boolean` | `false` | Show a toggle on every parent so branches can be hidden. |
| `zoom` | `number` | `1` | Scale factor applied to the whole chart (clamped to 0.5–2). |
| `aria-label` | `string` | `this.i18n.orgChartLabel` | Accessible name for the tree. |
| `selected` (two-way) | `string \| null` | `null` | Two-way selected node id (`null` = nothing selected). |
| `expanded` (two-way) | `readonly string[] \| undefined` | `undefined` | Two-way ids of the expanded parents. Leave unbound to let the chart manage expansion itself (seeded from each node's `expanded` flag). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `selectedChange` | `string \| null` | Emits when `selected` changes (two-way binding). |
| `expandedChange` | `readonly string[] \| undefined` | Emits when `expanded` changes (two-way binding). |
| `nodeClick` | `MkOrgChartNode<T>` | Emits the node whose card was clicked or activated with Enter/Space. |
| `nodeToggle` | `MkOrgChartToggleEvent<T>` | Emits whenever a node is expanded or collapsed. |

Methods:

| Signature | Description |
| --- | --- |
| `toggle(node: MkOrgChartNode<T>): void` | Expand or collapse a parent (no-op for leaves / non-collapsible charts). |
| `setExpanded(node: MkOrgChartNode<T>, expanded: boolean): void` | Expand or collapse a parent explicitly. |
| `select(node: MkOrgChartNode<T>): void` | Select a node by reference (no-op unless `selectable`). |

### MkProfileActions (component)

Selector: `[mkProfileActions]`

Import: `import { MkProfileActions } from '@mk-kit/ui/data';`

Profile actions row — buttons projected into the footer area of a
`MkProfileCard`. Centred in vertical orientation; pinned to the end
in horizontal orientation.

```html
<div mkProfileActions>
  <button mkButton>Follow</button>
  <button mkButton variant="outline">Message</button>
</div>
```

### MkProfileCard (component)

Selector: `mk-profile-card` · exportAs: `mkProfileCard`

Docs: https://mk-kit.dev/components/cards-lists

Import: `import { MkProfileCard } from '@mk-kit/ui/data';`

Profile card — a person/entity summary on a bordered surface: an optional
cover banner, an `MkAvatar` (with automatic initials fallback derived
from `name`), the display name, a muted subtitle, free-form body content and
two optional slots for a meta/stats row and an actions row.

Orientations:
- `vertical` (default) — centred column; when `coverSrc` is set a 3:1 banner
  spans the card top and the avatar overlaps its bottom edge with a
  surface-coloured ring.
- `horizontal` — avatar on the left, text in the middle, actions pinned to
  the end. The cover banner is intentionally NOT rendered in this
  orientation (a side-by-side row has no top edge for it to crown).

The name renders as emphasised generic text (like `mk-card-title`, no
hard-coded heading level) so the card never disrupts the document outline.

```html
<mk-profile-card
  name="Ada Lovelace"
  subtitle="Analytical Engine Programmer"
  avatarSrc="/ada.jpg"
  coverSrc="/cover.jpg">
  First programmer. Wrote notes G through... well, all of them.
  <div mkProfileMeta>
    <div><strong>128</strong> posts</div>
    <div><strong>2.4k</strong> followers</div>
    <div><strong>310</strong> following</div>
  </div>
  <div mkProfileActions>
    <button mkButton>Follow</button>
    <button mkButton variant="outline">Message</button>
  </div>
</mk-profile-card>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `name` (required) | `string` |  | Display name. Also drives the avatar's initials fallback and alt text. |
| `subtitle` | `string` | `''` | Muted supporting line under the name (role, handle, email…). |
| `avatarSrc` | `string` | `''` | Avatar image URL; when empty the avatar falls back to initials. |
| `coverSrc` | `string` | `''` | Cover banner image URL rendered as a ~3:1 band across the card top (vertical orientation only). When set, the avatar overlaps the banner's bottom edge with a surface-coloured ring. |
| `orientation` | `MkProfileCardOrientation` | `'vertical'` | Layout: centred column (`vertical`) or avatar-left row (`horizontal`). |
| `avatarSize` | `MkSize` | `'lg'` | Avatar size scale, forwarded to `MkAvatar`. |

### MkProfileMeta (component)

Selector: `[mkProfileMeta]`

Import: `import { MkProfileMeta } from '@mk-kit/ui/data';`

Profile meta row — a stats strip projected into a `MkProfileCard`
between the body and the actions. Direct children are laid out as
evenly-spaced, centre-aligned cells with subtle separators between them.

```html
<div mkProfileMeta>
  <div><strong>128</strong> posts</div>
  <div><strong>2.4k</strong> followers</div>
</div>
```

### MkProgressBar (component)

Selector: `mk-progress-bar`

Docs: https://mk-kit.dev/components/loading

Import: `import { MkProgressBar } from '@mk-kit/ui/data';`

Progress bar — a determinate (0–100) or indeterminate progress indicator
with `role="progressbar"`. `aria-valuenow` is omitted while indeterminate.
The indeterminate animation respects `prefers-reduced-motion`.

```html
<mk-progress-bar [value]="uploaded()" label="Uploading" showValue />
<mk-progress-bar indeterminate label="Loading" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | `0` | Completion percentage 0–100 (ignored while indeterminate). |
| `indeterminate` | `boolean` | `false` | Show an animated indeterminate bar with no known completion. |
| `tone` | `MkTone` | `'primary'` | Semantic color tone of the fill. |
| `size` | `MkSize` | `'md'` | Track thickness. |
| `label` | `string \| undefined` |  | Optional visible caption; also labels the bar for assistive tech. |
| `showValue` | `boolean` | `false` | Show the numeric percentage next to the label (determinate only). |

### MkProgressRing (component)

Selector: `mk-progress-ring`

Docs: https://mk-kit.dev/components/proportion-charts

Import: `import { MkProgressRing } from '@mk-kit/ui/data';`

ProgressRing — a circular progress indicator. Determinate by default (an arc
proportional to `value`); set `indeterminate` for a spinner-style preloader
when progress is unknown. Themed by `tone`, sized by `size`.

```html
<mk-progress-ring [value]="uploaded()" showLabel />
<mk-progress-ring indeterminate tone="neutral" [size]="24" />
<mk-progress-ring [value]="72" tone="success"><mk-icon name="check" /></mk-progress-ring>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | `0` | Current progress value (clamped to `[0, max]`). Ignored when indeterminate. |
| `max` | `number` | `100` | Maximum value. Default `100`. |
| `size` | `number` | `48` | Diameter in px. Default `48`. |
| `thickness` | `number` | `4` | Ring thickness in px. Default `4`. |
| `tone` | `MkTone` | `'primary'` | Semantic colour of the progress arc. |
| `indeterminate` | `boolean` | `false` | Show a rotating arc for unknown-duration work (a circular preloader). |
| `showLabel` | `boolean` | `false` | Show the percentage in the centre. |
| `label` | `string` | `''` | Accessible label (recommended, especially when indeterminate). |

### MkQrCode (component)

Selector: `mk-qr-code`

Docs: https://mk-kit.dev/components/data

Import: `import { MkQrCode } from '@mk-kit/ui/data';`

QR Code — a dependency-free QR generator rendered as an SVG. The entire
encoding (byte mode, Reed–Solomon ECC, masking, format info) is implemented
from scratch in `mkEncodeQr`; no npm library is used. Dark modules are
drawn as `<rect>`s over a background rectangle that also fills the quiet zone,
so the code is theme-aware (`var(--mk-text)` on `var(--mk-surface)`) and
fully overridable. Exposes `role="img"` with an `aria-label` for assistive
tech.

Supports versions 1–10 and ECC levels L/M/Q/H (byte mode / UTF-8).

```html
<mk-qr-code value="https://example.com" ecc="M" [size]="200" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  | The text to encode (UTF-8, byte mode). |
| `ecc` | `MkQrEcc` | `'M'` | Error-correction level: `L` (~7%), `M` (~15%), `Q` (~25%), `H` (~30%). |
| `size` | `number` | `160` | Rendered pixel size of the (square) SVG. |
| `quietZone` | `number` | `4` | Width of the light margin around the code, in modules (spec recommends 4). |
| `color` | `string` | `'var(--mk-text)'` | Dark-module colour. |
| `background` | `string` | `'var(--mk-surface)'` | Background / quiet-zone colour. |
| `label` | `string` | `''` | Accessible label for the image. When omitted, the label carries the encoded content (`QR code: <value>`) so AT users learn what the code says. |

### MkRadarChart (component)

Selector: `mk-radar-chart`

Docs: https://mk-kit.dev/components/proportion-charts

Import: `import { MkRadarChart } from '@mk-kit/ui/data';`

RadarChart — a radar / spider chart comparing several series across the same
set of axes (skills, product profiles, survey dimensions). Dependency-free
SVG on the validated `--mk-chart-*` palette; ships concentric grid rings, a
legend for ≥ 2 series and a screen-reader data table.

```html
<mk-radar-chart
  [axes]="['Speed','Power','Range','Cost','Ease']"
  [series]="[{ name: 'Model A', data: [8,6,7,5,9] }]" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `axes` | `readonly string[]` | `[]` | Axis labels (one spoke each). Series data align to this order. |
| `series` | `readonly MkChartSeries[]` | `[]` | One or more series (values align to `axes`). |
| `max` | `number \| null` | `null` | Domain maximum (defaults to a nice value above the data max). |
| `levels` | `number` | `4` | Number of concentric grid rings. |
| `width` | `number` | `360` | Intrinsic width (viewBox units; the SVG scales to its container). |
| `height` | `number` | `360` | Intrinsic height. |
| `showDots` | `boolean` | `true` | Draw a dot at each vertex. |
| `showLegend` | `boolean \| undefined` | `undefined` | Force the legend on/off (defaults to on when there are ≥ 2 series). |
| `label` | `string` | `''` | Accessible summary; generated from the data when omitted. |

### MkScatterChart (component)

Selector: `mk-scatter-chart`

Docs: https://mk-kit.dev/components/charts

Import: `import { MkScatterChart } from '@mk-kit/ui/data';`

ScatterChart — plot (x, y) points across two numeric axes to reveal
correlation and clusters. Give each point a `size` to render a bubble chart.
Dependency-free SVG on the validated `--mk-chart-*` palette; ships nice-tick
axes, a legend for ≥ 2 series, a per-point hover tooltip and a screen-reader
data table.

```html
<mk-scatter-chart
  xLabel="Spend" yLabel="Revenue"
  [series]="[{ name: 'Q3', points: pts() }]" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `series` | `readonly MkScatterSeries[]` | `[]` | One or more point series. |
| `width` | `number` | `480` | Intrinsic width (viewBox units; the SVG scales to its container). |
| `height` | `number` | `300` | Intrinsic height. |
| `pointRadius` | `number` | `4` | Radius of each point when not sizing by `size`. |
| `bubble` | `boolean` | `false` | Size points by their `size` value (bubble chart). |
| `maxRadius` | `number` | `20` | Largest bubble radius when `bubble` is on. |
| `showGrid` | `boolean` | `true` | Show gridlines. |
| `showLegend` | `boolean \| undefined` | `undefined` | Force the legend on/off (defaults to on when there are ≥ 2 series). |
| `xLabel` | `string` | `''` | x-axis title. |
| `yLabel` | `string` | `''` | y-axis title. |
| `label` | `string` | `''` | Accessible summary; generated from the data when omitted. |

### MkSkeleton (component)

Selector: `mk-skeleton`

Docs: https://mk-kit.dev/components/loading

Import: `import { MkSkeleton } from '@mk-kit/ui/data';`

Skeleton — a shimmering placeholder shown while content loads. It is
`aria-hidden`; mark the surrounding region `aria-busy="true"` so assistive
tech knows content is pending. The shimmer stops under
`prefers-reduced-motion`.

```html
<mk-skeleton shape="circle" [width]="40" [height]="40" />
<mk-skeleton shape="text" [lines]="3" />
<mk-skeleton shape="rect" width="100%" [height]="180" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `shape` | `MkSkeletonShape` | `'text'` | Placeholder geometry. |
| `width` | `string \| number \| undefined` |  | Width — a number (px) or any CSS length/percentage string. |
| `height` | `string \| number \| undefined` |  | Height — a number (px) or any CSS length/percentage string. |
| `lines` | `number` | `1` | Number of lines to render for `shape="text"`. |

### MkSkeletonPreset (component)

Selector: `mk-skeleton-preset`

Docs: https://mk-kit.dev/components/loading

Import: `import { MkSkeletonPreset } from '@mk-kit/ui/data';`

SkeletonPreset — composite loading placeholders assembled from
`MkSkeleton`: a `paragraph`, a media `card`, an avatar `list` or a
`table`. Announces "Loading" to assistive tech; swap it for real content once
loaded.

```html
<mk-skeleton-preset preset="card" />
<mk-skeleton-preset preset="list" [rows]="5" />
<mk-skeleton-preset preset="table" [rows]="4" [columns]="5" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `preset` | `MkSkeletonPresetKind` | `'paragraph'` | Which layout to render. |
| `rows` | `number` | `3` | Number of rows (paragraph lines / list items / table body rows). |
| `columns` | `number` | `4` | Number of columns (table only). |
| `loadingLabel` | `string` | `this.i18n.loading` | Accessible loading label. |

### MkSparkline (component)

Selector: `mk-sparkline`

Docs: https://mk-kit.dev/components/charts

Import: `import { MkSparkline } from '@mk-kit/ui/data';`

Sparkline — a tiny, axis-less trend chart sized to sit inline in a table
cell, stat card or list row. Single series only; it's a *mark*, so it carries
no legend or tooltip (give context with the surrounding label + `label`).

```html
<mk-sparkline [data]="[3,5,4,7,6,9,8]" type="area" />
<mk-sparkline [data]="visits()" [width]="80" showDot
  color="var(--mk-success)" label="Weekly visits" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `readonly number[]` | `[]` | The values to plot (left → right). |
| `type` | `MkSparklineType` | `'line'` | Visual form. |
| `color` | `string` | `'var(--mk-chart-1)'` | Any CSS colour; defaults to the first chart hue. |
| `width` | `number` | `120` | Intrinsic width in px (the SVG scales with its box). |
| `height` | `number` | `32` | Intrinsic height in px. |
| `strokeWidth` | `number` | `2` | Line/area stroke width. |
| `showDot` | `boolean` | `false` | Draw a dot on the last point (line/area only). |
| `min` | `number \| undefined` | `undefined` | Fixed domain minimum (defaults to the data min). |
| `max` | `number \| undefined` | `undefined` | Fixed domain maximum (defaults to the data max). |
| `label` | `string` | `''` | Accessible label; a data summary is generated when omitted. |

### MkSpinner (component)

Selector: `mk-spinner`

Docs: https://mk-kit.dev/components/loading

Import: `import { MkSpinner } from '@mk-kit/ui/data';`

Spinner — a circular indeterminate loading indicator. Exposes `role="status"`
with a visually-hidden label so assistive tech announces the loading state.
The animation slows under `prefers-reduced-motion`.

```html
<mk-spinner />
<mk-spinner size="lg" tone="neutral" label="Fetching results" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `MkSize` | `'md'` | Size scale. |
| `tone` | `MkTone` | `'primary'` | Semantic color tone. |
| `label` | `string` | `this.i18n.loading` | Visually-hidden status label announced to screen readers. |

### MkStatCard (component)

Selector: `mk-stat-card`

Docs: https://mk-kit.dev/components/cards-lists

Import: `import { MkStatCard } from '@mk-kit/ui/data';`

Stat card — a compact KPI tile for dashboards. Shows a label, a primary
value and an optional trend delta. The trend is conveyed by an arrow glyph
and a screen-reader phrase in addition to colour, so it never relies on
colour alone.

```html
<mk-stat-card
  label="Revenue"
  value="$48.2k"
  [delta]="'+12%'"
  deltaTrend="up"
  hint="vs. last month">
  <svg mkStatIcon>…</svg>
</mk-stat-card>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | `''` | Metric name shown above the value. |
| `value` | `string \| number` | `''` | The primary metric value. |
| `delta` | `string \| number \| undefined` |  | Change indicator (e.g. `'+12%'` or `-4`). Omit to hide the delta row. |
| `deltaTrend` | `MkStatTrend` | `'neutral'` | Trend direction; colourises the delta and picks the arrow glyph. |
| `hint` | `string \| undefined` |  | Small supporting note under the delta (e.g. "vs. last month"). |

### MkTag (component)

Selector: `mk-tag`

Docs: https://mk-kit.dev/components/badges-avatars

Import: `import { MkTag } from '@mk-kit/ui/data';`

Tag — a non-interactive label for categories, keywords or metadata. Unlike
`MkChip` it carries no interaction; use it purely for display.

```html
<mk-tag>Design</mk-tag>
<mk-tag tone="info" variant="outline">Beta</mk-tag>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `MkTone` | `'neutral'` | Semantic color tone. |
| `variant` | `MkTagVariant` | `'soft'` | Visual treatment. |
| `size` | `MkSize` | `'md'` | Size scale. |

### MkTimeline (component)

Selector: `mk-timeline`

Docs: https://mk-kit.dev/components/empty-timeline

Import: `import { MkTimeline } from '@mk-kit/ui/data';`

Timeline — a vertical sequence of chronological events (activity feeds, order
status, audit logs). A container for `<mk-timeline-item>`s that draws the
connecting rail; exposed to assistive tech as a list.

```html
<mk-timeline>
  <mk-timeline-item tone="success" time="09:30" heading="Order placed">
    Payment confirmed.
  </mk-timeline-item>
  <mk-timeline-item time="10:15" heading="Packed">In the warehouse.</mk-timeline-item>
</mk-timeline>
```

### MkTimelineItem (component)

Selector: `mk-timeline-item`

Docs: https://mk-kit.dev/components/empty-timeline

Import: `import { MkTimelineItem } from '@mk-kit/ui/data';`

A single event in an `<mk-timeline>`: a tone-coloured marker (optionally an
icon), an optional time/label and heading, and projected body content.

```html
<mk-timeline-item tone="danger" icon="error" time="2m ago" heading="Build failed">
  3 tests failed on <code>main</code>.
</mk-timeline-item>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `MkTone` | `'primary'` | Semantic colour of the marker dot. |
| `icon` | `string` | `''` | Name of a registered icon rendered inside the marker. |
| `time` | `string` | `''` | Time or label shown above the heading (e.g. "09:30", "2m ago"). |
| `heading` | `string` | `''` | Event title. |

### MkTreemap (component)

Selector: `mk-treemap`

Docs: https://mk-kit.dev/components/proportion-charts

Import: `import { MkTreemap } from '@mk-kit/ui/data';`

Treemap — nested rectangles sized by value, using a squarified layout that
keeps tiles close to square. Dependency-free SVG on the validated
`--mk-chart-*` palette; ships in-tile labels (hidden when a tile is too
small), a hover tooltip with the share of total, and a screen-reader table.

```html
<mk-treemap [items]="[{ label: 'Ads', value: 40 }, { label: 'SEO', value: 25 }]" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `readonly MkTreemapItem[]` | `[]` | The tiles to pack, largest first (order-independent — sorted internally). |
| `width` | `number` | `480` | Intrinsic width (viewBox units; the SVG scales to its container). |
| `height` | `number` | `320` | Intrinsic height. |
| `showValues` | `boolean` | `true` | Draw each tile's value beneath its label when the tile is tall enough. |
| `label` | `string` | `''` | Accessible summary; generated from the data when omitted. |

### MkVirtualScroll (component)

Selector: `mk-virtual-scroll`

Docs: https://mk-kit.dev/components/data

Import: `import { MkVirtualScroll } from '@mk-kit/ui/data';`

VirtualScroll — renders only the rows visible in the viewport (plus a small
overscan), so a list of thousands of fixed-height items stays smooth. Give
the host a height and provide a row template:

```html
<mk-virtual-scroll [items]="rows" [itemHeight]="40" style="height: 20rem;">
  <ng-template let-row let-i="index">{{ i }} — {{ row.name }}</ng-template>
</mk-virtual-scroll>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `readonly unknown[]` | `[]` | The full list of items. |
| `itemHeight` | `number` | `40` | Fixed height of each row in px. |
| `overscan` | `number` | `4` | Extra rows rendered above/below the viewport to smooth fast scrolls. |

### MkBadgeOverlay (directive)

Selector: `[mkBadgeOverlay]`

Docs: https://mk-kit.dev/components/badges-avatars

Import: `import { MkBadgeOverlay } from '@mk-kit/ui/data';`

Badge overlay — anchors a small badge (count, dot or short text) to a corner
of ANY element: an icon button, an avatar, a tab label. The host stays a
single tab stop; the badge is a decorative, non-focusable child.

- Numbers above `mkBadgeOverlayMax` (default 99) collapse to `99+`.
- `mkBadgeOverlayDot` renders a textless dot ("something is new").
- `mkBadgeOverlayAriaLabel` is the screen-reader text ("3 unread"). It is
  rendered in a visually hidden span and wired to the host with
  `aria-describedby`, so it is announced after the host's own name even
  when the host has an `aria-label`. When it is given, the visible badge is
  `aria-hidden` so the count is not read twice.
- Positions use logical insets, so `top-end` sits at the top-right in LTR
  and the top-left in RTL.

The badge is painted with the global `.mk-badge-overlay` styles from
`@mk-kit/ui/styles.css` and follows the `--mk-*` tone tokens.

```html
<button mkButton iconOnly aria-label="Notifications"
        [mkBadgeOverlay]="unread()" mkBadgeOverlayTone="danger"
        [mkBadgeOverlayAriaLabel]="unread() + ' unread'">
  <mk-icon name="bell" />
</button>

<mk-avatar name="Ada Lovelace" mkBadgeOverlay mkBadgeOverlayDot
           mkBadgeOverlayTone="success" mkBadgeOverlayPosition="bottom-end" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkBadgeOverlay` | `string \| number \| null \| undefined` | `null` | Badge content — a count or a short label. `null` / empty hides the badge unless `mkBadgeOverlayDot` is set. Numeric strings are treated as numbers so `mkBadgeOverlay="120"` also collapses to `99+`. |
| `mkBadgeOverlayPosition` | `MkBadgeOverlayPosition` | `'top-end'` | Corner the badge is anchored to (logical: `end` flips in RTL). |
| `mkBadgeOverlayTone` | `MkTone` | `'primary'` | Semantic color tone (same scale as `mk-badge`). |
| `mkBadgeOverlayDot` | `boolean` | `false` | Render a textless dot instead of the content. |
| `mkBadgeOverlayMax` | `number` | `99` | Numbers above this render as `<max>+`. `0` disables the cap. |
| `mkBadgeOverlayHidden` | `boolean` | `false` | Hide the badge while keeping the directive (and its aria wiring) in place. |
| `mkBadgeOverlayAriaLabel` | `string` | `''` | Screen-reader text for the badge, e.g. `"3 unread"`. Announced as the host's description; the visible badge becomes `aria-hidden`. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `Signal<string>` | The text painted in the badge (`''` in dot mode). |
| `visible` | `Signal<boolean>` | Whether the badge is currently rendered. |

### MkCarouselSlide (directive)

Selector: `[mkCarouselSlide]`

Import: `import { MkCarouselSlide } from '@mk-kit/ui/data';`

A single slide inside `MkCarousel`. Mark each slide element with
`mkCarouselSlide`; the carousel wires ARIA + visibility.

### MkOrgChartNodeDef (directive)

Selector: `ng-template[mkOrgChartNodeDef]`

Import: `import { MkOrgChartNodeDef } from '@mk-kit/ui/data';`

Custom node card for `mk-org-chart`:

```html
<mk-org-chart [nodes]="nodes">
  <ng-template mkOrgChartNodeDef let-node let-selected="selected">
    <strong>{{ node.label }}</strong> — {{ node.data?.title }}
  </ng-template>
</mk-org-chart>
```

Bind the same array you pass to `nodes` to get a typed `node.data` in the
template: `<ng-template [mkOrgChartNodeDef]="nodes" let-node>`.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkOrgChartNodeDef` | `"" \| readonly MkOrgChartNode<T>[] \| undefined` | `undefined` | Type-inference hook only (the value is not used at runtime): bind the `nodes` array so `let-node` is typed as `MkOrgChartNode<T>`. |

### mkArcPath (function)

Import: `import { mkArcPath } from '@mk-kit/ui/data';`

SVG arc path for a donut/pie slice between two angles (radians, clockwise
from 12 o'clock). `inner` of 0 yields a pie wedge; > 0 yields a ring segment.

```ts
function mkArcPath(cx: number, cy: number, outer: number, inner: number, startAngle: number, endAngle: number): string
```

### mkAreaPath (function)

Import: `import { mkAreaPath } from '@mk-kit/ui/data';`

Closed area path under a line: the line, dropped to `baselineY` at each end.

```ts
function mkAreaPath(points: readonly MkPoint[], baselineY: number): string
```

### mkBuildJsonTree (function)

Import: `import { mkBuildJsonTree } from '@mk-kit/ui/data';`

Build the node tree for a JSON-ish value (circular refs marked).

```ts
function mkBuildJsonTree(value: unknown): MkJsonNode
```

### mkChartColor (function)

Import: `import { mkChartColor } from '@mk-kit/ui/data';`

Categorical colour for a series index — a CSS reference to the validated
`--mk-chart-N` token. Assigned in fixed order and wrapped past 8 (prefer
folding a 9th series into "Other" over relying on the wrap).

```ts
function mkChartColor(index: number): string
```

### mkComputeDiff (function)

Import: `import { mkComputeDiff } from '@mk-kit/ui/data';`

Compute a line diff between `before` and `after`. Returns one `MkDiffRow`
per line in document order, with `equal` / `insert` / `delete` ops and 1-based
before/after line numbers. With `wordHighlight` (default true) changed lines
also carry word-level `segments`.

```ts
function mkComputeDiff(before: string, after: string, options?: MkDiffOptions): MkDiffRow[]
```

### mkContrastRatio (function)

Import: `import { mkContrastRatio } from '@mk-kit/ui/data';`

WCAG 2.x contrast ratio (1–21) between two colours.

```ts
function mkContrastRatio(a: MkRgb, b: MkRgb): number
```

### mkDiffStats (function)

Import: `import { mkDiffStats } from '@mk-kit/ui/data';`

Summary counts (added / removed / unchanged lines) for a diff.

```ts
function mkDiffStats(rows: MkDiffRow[]): MkDiffStats
```

### mkEncodeQr (function)

Import: `import { mkEncodeQr } from '@mk-kit/ui/data';`

Encode `text` (UTF-8, byte mode) as a QR code module matrix.

```ts
function mkEncodeQr(text: string, ecc: MkQrEcc): boolean[][]
```

### mkFormatCompact (function)

Import: `import { mkFormatCompact } from '@mk-kit/ui/data';`

Compact number formatting for axes/tooltips (1.2k, 3.4M).

```ts
function mkFormatCompact(value: number): string
```

### mkHeatmapCellColors (function)

Import: `import { mkHeatmapCellColors } from '@mk-kit/ui/data';`

Choose the text token for a cell at intensity `t` (0–1) — light text on
dark cells, dark text on light cells, decided by contrast against the
actual blend rather than a fixed threshold.

Every accent ramp has a crossover band where neither `--mk-text` nor
`--mk-text-inverse` reaches 4.5:1 (the cell is mid-luminance). When values
are printed in the cells, a cell in that band is painted at the nearest
intensity just outside it, so its value stays readable; the shift is a few
percent of the ramp and the cell keeps its order relative to its
neighbours. Without a resolved palette (server rendering, tests) a plain
threshold is used.

```ts
function mkHeatmapCellColors(t: number, palette: MkHeatmapPalette | null, showValues: boolean): MkHeatmapCellColors
```

### mkLinearScale (function)

Import: `import { mkLinearScale } from '@mk-kit/ui/data';`

Build a linear scale mapping `[d0,d1]` (domain) onto `[r0,r1]` (range).

```ts
function mkLinearScale(d0: number, d1: number, r0: number, r1: number): (value: number) => number
```

### mkLinePath (function)

Import: `import { mkLinePath } from '@mk-kit/ui/data';`

Straight-segment SVG path (`M … L …`) through the given points.

```ts
function mkLinePath(points: readonly MkPoint[]): string
```

### mkMixRgb (function)

Import: `import { mkMixRgb } from '@mk-kit/ui/data';`

What `color-mix(in srgb, a t%, b)` yields: a linear blend in gamma-encoded sRGB.

```ts
function mkMixRgb(a: MkRgb, b: MkRgb, t: number): MkRgb
```

### mkNiceTicks (function)

Import: `import { mkNiceTicks } from '@mk-kit/ui/data';`

"Nice" rounded tick values covering `[min,max]` with roughly `count` steps —
used for value axes so gridlines land on human numbers.

```ts
function mkNiceTicks(min: number, max: number, count?: number): number[]
```

### mkOrgChartFromFlat (function)

Import: `import { mkOrgChartFromFlat } from '@mk-kit/ui/data';`

Build the nested `nodes` input from a flat `parentId` list (the shape most
HR / directory APIs return). Row order is preserved among siblings; rows
whose `parentId` does not match any row become roots.

```ts
const nodes = mkOrgChartFromFlat([
  { id: 'ceo', label: 'Ada' },
  { id: 'cto', label: 'Grace', parentId: 'ceo' },
]);
```

```ts
function mkOrgChartFromFlat<T = unknown>(list: readonly MkOrgChartFlatNode<T>[]): MkOrgChartNode<T>[]
```

### mkParseAnsi (function)

Import: `import { mkParseAnsi } from '@mk-kit/ui/data';`

Parse one log line into styled spans. Pure — same input, same output.
Adjacent runs with identical styling are merged, so a plain line yields a
single span (or none when empty).

```ts
function mkParseAnsi(line: string): MkAnsiSpan[]
```

### mkParseMarkdown (function)

Import: `import { mkParseMarkdown } from '@mk-kit/ui/data';`

Parse markdown source into a typed AST. Pure and dependency-free — safe to
run on a server. Unsafe link/image URLs are already dropped at this stage,
so the AST never carries a `javascript:` (or other non-allow-listed) URL.

```ts
function mkParseMarkdown(src: string, options?: MkMarkdownParseOptions): MkMarkdownBlock[]
```

### mkParseRgb (function)

Import: `import { mkParseRgb } from '@mk-kit/ui/data';`

Parse a CSS colour as the CSSOM serialises it — `rgb(r, g, b)` /
`rgba(r, g, b, a)` — or a `#rgb` / `#rrggbb` literal. `null` for anything
else (an unresolved `var()`, `color(...)`, …).

```ts
function mkParseRgb(text: string | null | undefined): MkRgb | null
```

### mkRelativeLuminance (function)

Import: `import { mkRelativeLuminance } from '@mk-kit/ui/data';`

WCAG 2.x relative luminance of an sRGB colour.

```ts
function mkRelativeLuminance([r, g, b]: MkRgb): number
```

### mkRenderMarkdown (function)

Import: `import { mkRenderMarkdown } from '@mk-kit/ui/data';`

Render a parsed AST to an HTML string. The output contains only tags this
renderer generates (all source text is escaped), so it is safe to bind to
`[innerHTML]` — Angular's sanitizer keeps every element/attribute used here.
Fenced code is highlighted via `mkHighlight` for its known languages.

```ts
function mkRenderMarkdown(blocks: MkMarkdownBlock[], options?: MkMarkdownRenderOptions): string
```

### mkSplitDuration (function)

Import: `import { mkSplitDuration } from '@mk-kit/ui/data';`

Split a positive millisecond duration into whole days, hours, minutes and
seconds. Negative inputs clamp to zero.

```ts
mkSplitDuration(90_061_000); // { days: 1, hours: 1, minutes: 1, seconds: 1 }
```

```ts
function mkSplitDuration(ms: number): MkDurationParts
```

### mkSquarify (function)

Import: `import { mkSquarify } from '@mk-kit/ui/data';`

Squarified treemap layout — pack `items` into the rectangle `(x, y, w, h)` as
nested tiles whose areas are proportional to `value`, greedily building rows
along the shorter side so tiles stay close to square. Returns exactly one
rect per input item, tagged with its original `index` (so callers can render
in input order). Framework-agnostic and pure.

```ts
function mkSquarify(items: readonly { value: number; }[], x: number, y: number, w: number, h: number): MkTreemapRect[]
```

### mkStripAnsi (function)

Import: `import { mkStripAnsi } from '@mk-kit/ui/data';`

Remove every ANSI escape sequence from a line (for copy / search).

```ts
function mkStripAnsi(line: string): string
```

### MK_CHART_PALETTE_SIZE (const)

Import: `import { MK_CHART_PALETTE_SIZE } from '@mk-kit/ui/data';`

Number of hues in the validated categorical palette (`--mk-chart-1..8`).

```ts
const MK_CHART_PALETTE_SIZE: 8;
```

### MK_HEATMAP_MIN_CONTRAST (const)

Import: `import { MK_HEATMAP_MIN_CONTRAST } from '@mk-kit/ui/data';`

WCAG AA minimum contrast for normal text — what cell values are held to.

```ts
const MK_HEATMAP_MIN_CONTRAST: 4.5;
```

### MkAnsiSpan (interface)

Import: `import { MkAnsiSpan } from '@mk-kit/ui/data';`

One styled run of text within a parsed line.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `text` | `string` | The plain text of the run (escape sequences removed). |
| `classes` | `readonly string[]` | `mk-ansi--*` class names styling the run; empty for plain text. |

### MkCalendarHeatmapCell (interface)

Import: `import { MkCalendarHeatmapCell } from '@mk-kit/ui/data';`

Payload of `mk-calendar-heatmap`'s `cellClick`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `date` | `Date` | The clicked day (local midnight). |
| `value` | `number` | The day's aggregated value (0 when no entry exists). |

### MkCalendarHeatmapEntry (interface)

Import: `import { MkCalendarHeatmapEntry } from '@mk-kit/ui/data';`

One day's datum for `mk-calendar-heatmap`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `date` | `string \| Date` | The day — a `Date`, or a string. `YYYY-MM-DD` strings are parsed as **local** dates (never UTC-shifted); other strings go through `new Date()`. |
| `value` | `number` | The day's value (e.g. an activity count). Multiple entries for the same day are summed. |

### MkChartSeries (interface)

Import: `import { MkChartSeries } from '@mk-kit/ui/data';`

A named data series for multi-series charts.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | Legend/tooltip label (identity — always shown, never colour-alone). |
| `data` | `number[]` | The values, one per category/x position. |
| `color`? | `string \| undefined` | Optional explicit colour; defaults to the validated palette by index. |

### MkChartSlice (interface)

Import: `import { MkChartSlice } from '@mk-kit/ui/data';`

A single slice for the donut/pie chart.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | Slice label. |
| `value` | `number` | Slice value (summed to compute proportions). |
| `color`? | `string \| undefined` | Optional explicit colour; defaults to the palette by index. |

### MkDiffOptions (interface)

Import: `import { MkDiffOptions } from '@mk-kit/ui/data';`

Options for `mkComputeDiff`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `wordHighlight`? | `boolean \| undefined` | Highlight the specific words that changed within paired lines. |
| `ignoreTrailingWhitespace`? | `boolean \| undefined` | Treat trailing whitespace as insignificant when comparing lines. |

### MkDiffRow (interface)

Import: `import { MkDiffRow } from '@mk-kit/ui/data';`

One line of a computed diff.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `op` | `MkDiffOp` |  |
| `text` | `string` |  |
| `beforeNo` | `number \| null` | 1-based line number in the "before" text (null for inserts). |
| `afterNo` | `number \| null` | 1-based line number in the "after" text (null for deletes). |
| `segments`? | `MkDiffSegment[] \| undefined` | Word segments for changed lines (present when word highlighting runs). |

### MkDiffSegment (interface)

Import: `import { MkDiffSegment } from '@mk-kit/ui/data';`

A word-level segment within a changed line.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `text` | `string` |  |
| `changed` | `boolean` | True when this word differs from the paired line. |

### MkDiffStats (interface)

Import: `import { MkDiffStats } from '@mk-kit/ui/data';`

Summary counts for a diff.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `added` | `number` |  |
| `removed` | `number` |  |
| `unchanged` | `number` |  |

### MkDurationParts (interface)

Import: `import { MkDurationParts } from '@mk-kit/ui/data';`

A duration split into whole day/hour/minute/second parts.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `days` | `number` |  |
| `hours` | `number` |  |
| `minutes` | `number` |  |
| `seconds` | `number` |  |

### MkFunnelSegment (interface)

Import: `import { MkFunnelSegment } from '@mk-kit/ui/data';`

A single stage of the funnel (ordered largest → smallest conceptually).

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Stage label (e.g. "Visits"). |
| `value` | `number` | Stage value; drives the band width. |
| `color`? | `string \| undefined` | Optional explicit colour; defaults to the palette by index. |

### MkHeatmapCellColors (interface)

Import: `import { MkHeatmapCellColors } from '@mk-kit/ui/data';`

Which text token a cell value is drawn with, and the intensity to paint the cell at.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `intensity` | `number` | Accent share of the cell background, 0–1. |
| `inverse` | `boolean` | `true` → `--mk-text-inverse`, `false` → `--mk-text`. |
| `contrast` | `number` | Contrast ratio of the chosen text against the cell background (1–21). |

### MkHeatmapPalette (interface)

Import: `import { MkHeatmapPalette } from '@mk-kit/ui/data';`

The resolved colours a heatmap picks its cell text against.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `accent` | `MkRgb` | The `accent` input, resolved to sRGB. |
| `surface` | `MkRgb` | `--mk-surface-2` — the zero-intensity cell colour. |
| `text` | `MkRgb` | `--mk-text`. |
| `textInverse` | `MkRgb` | `--mk-text-inverse`. |

### MkJsonNode (interface)

Import: `import { MkJsonNode } from '@mk-kit/ui/data';`

One rendered node of the JSON tree.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `string \| null` | Property name / array index; `null` for the root. |
| `type` | `"string" \| "number" \| "boolean" \| "object" \| "array" \| "null" \| "circular"` | Node kind (drives colouring + expandability). |
| `display` | `string` | Display text for primitives. |
| `children` | `MkJsonNode[]` | Children for objects/arrays. |
| `path` | `string` | Unique path (e.g. `$.users[0].name`) used for expansion tracking. |
| `depth` | `number` | Nesting depth (root = 0). |

### MkLogToken (interface)

Import: `import { MkLogToken } from '@mk-kit/ui/data';`

One render token of a log line: a styled run, optionally a search match.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `text` | `string` |  |
| `cls` | `string` | Space-joined `mk-ansi--*` classes ('' for plain text). |
| `mark` | `boolean` | True when the token is part of a search-query match. |

### MkMarkdownList (interface)

Import: `import { MkMarkdownList } from '@mk-kit/ui/data';`

An ordered or unordered (tight) list block.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `"list"` |  |
| `ordered` | `boolean` |  |
| `start` | `number` | First ordinal of an ordered list (`3.` starts at 3). Always 1 for bullets. |
| `items` | `MkMarkdownListItem[]` |  |

### MkMarkdownListItem (interface)

Import: `import { MkMarkdownListItem } from '@mk-kit/ui/data';`

One `<li>`: tight inline content plus an optional nested list.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `children` | `MkMarkdownInline[]` |  |
| `sublist` | `MkMarkdownList \| null` |  |

### MkMarkdownParseOptions (interface)

Import: `import { MkMarkdownParseOptions } from '@mk-kit/ui/data';`

Members:

| Name | Type | Description |
| --- | --- | --- |
| `autolink`? | `boolean \| undefined` | Turn bare `http(s)://…` URLs into links. Off by default. |

### MkMarkdownRenderOptions (interface)

Import: `import { MkMarkdownRenderOptions } from '@mk-kit/ui/data';`

Members:

| Name | Type | Description |
| --- | --- | --- |
| `linkTarget`? | `"" \| "_blank" \| undefined` | `'_blank'` renders `target="_blank" rel="noopener noreferrer"` on links. |

### MkOrgChartFlatNode (interface)

Import: `import { MkOrgChartFlatNode } from '@mk-kit/ui/data';`

One row of a flat list accepted by `mkOrgChartFromFlat`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `label`? | `string \| undefined` |  |
| `data`? | `T \| undefined` |  |
| `parentId`? | `string \| null \| undefined` | Id of the parent row; `null` / `undefined` / unknown id = root. |
| `expanded`? | `boolean \| undefined` |  |

### MkOrgChartNode (interface)

Import: `import { MkOrgChartNode } from '@mk-kit/ui/data';`

A node in an `MkOrgChart` tree. `children` makes it a parent.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Unique id — drives selection (`[(selected)]`) and expansion (`[(expanded)]`). |
| `label`? | `string \| undefined` | Primary text of the default card (and the initials fallback). |
| `data`? | `T \| undefined` | Arbitrary payload handed to the node template. The default card reads `data.title` (sub-label) and `data.avatar` (image URL) when present. |
| `children`? | `MkOrgChartNode<T>[] \| undefined` | Direct reports; a non-empty array makes the node collapsible. |
| `expanded`? | `boolean \| undefined` | Initial expansion (default `true`). Only consulted when `[(expanded)]` is not bound. |

### MkOrgChartNodeContext (interface)

Import: `import { MkOrgChartNodeContext } from '@mk-kit/ui/data';`

Template context of `ng-template[mkOrgChartNodeDef]`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `$implicit` | `MkOrgChartNode<MkOrgChartTemplateData<T>>` | The node (also available as `let-node`). |
| `node` | `MkOrgChartNode<MkOrgChartTemplateData<T>>` |  |
| `depth` | `number` | 1-based depth (roots are 1). |
| `expanded` | `boolean` | Whether the node's children are currently shown. |
| `selected` | `boolean` | Whether the node is the selected one. |

### MkOrgChartToggleEvent (interface)

Import: `import { MkOrgChartToggleEvent } from '@mk-kit/ui/data';`

Payload of `(nodeToggle)`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `node` | `MkOrgChartNode<T>` |  |
| `expanded` | `boolean` |  |

### MkPoint (interface)

Import: `import { MkPoint } from '@mk-kit/ui/data';`

A resolved 2-D point in SVG user space.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `x` | `number` |  |
| `y` | `number` |  |

### MkScatterPoint (interface)

Import: `import { MkScatterPoint } from '@mk-kit/ui/data';`

A single plotted point. `size` (optional) turns it into a bubble.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `x` | `number` |  |
| `y` | `number` |  |
| `size`? | `number \| undefined` | Value driving the bubble radius when `bubble` sizing is used. |
| `label`? | `string \| undefined` | Optional label shown in the tooltip. |

### MkScatterSeries (interface)

Import: `import { MkScatterSeries } from '@mk-kit/ui/data';`

A named group of scatter points sharing a colour.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` |  |
| `color`? | `string \| undefined` |  |
| `points` | `readonly MkScatterPoint[]` |  |

### MkTreemapItem (interface)

Import: `import { MkTreemapItem } from '@mk-kit/ui/data';`

A single treemap tile: a labelled rectangle sized by `value`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Tile label (identity — shown on the tile when it fits, and in the tooltip). |
| `value` | `number` | Positive magnitude driving the tile's area. |
| `color`? | `string \| undefined` | Optional explicit colour; defaults to the validated palette by index. |

### MkTreemapRect (interface)

Import: `import { MkTreemapRect } from '@mk-kit/ui/data';`

A positioned tile in SVG user space, tagged with its source `index`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `x` | `number` |  |
| `y` | `number` |  |
| `w` | `number` |  |
| `h` | `number` |  |
| `index` | `number` |  |

### MkAvatarShape (type)

Import: `import { MkAvatarShape } from '@mk-kit/ui/data';`

Outline shape of an `MkAvatar`.

```ts
type MkAvatarShape = 'circle' | 'rounded';
```

### MkAvatarStatus (type)

Import: `import { MkAvatarStatus } from '@mk-kit/ui/data';`

Presence status shown as a corner dot on an `MkAvatar`.

```ts
type MkAvatarStatus = 'online' | 'offline' | 'away' | 'busy';
```

### MkBadgeOverlayPosition (type)

Import: `import { MkBadgeOverlayPosition } from '@mk-kit/ui/data';`

Corner of the host an `MkBadgeOverlay` is anchored to.

```ts
type MkBadgeOverlayPosition = | 'top-end' | 'top-start' | 'bottom-end' | 'bottom-start';
```

### MkBadgeVariant (type)

Import: `import { MkBadgeVariant } from '@mk-kit/ui/data';`

Visual treatment for a `MkBadge`.

```ts
type MkBadgeVariant = 'solid' | 'soft' | 'outline';
```

### MkBarOrientation (type)

Import: `import { MkBarOrientation } from '@mk-kit/ui/data';`

Bar orientation.

```ts
type MkBarOrientation = 'vertical' | 'horizontal';
```

### MkCardPadding (type)

Import: `import { MkCardPadding } from '@mk-kit/ui/data';`

Internal padding scale for a `MkCard`.

```ts
type MkCardPadding = 'none' | 'sm' | 'md' | 'lg';
```

### MkCardVariant (type)

Import: `import { MkCardVariant } from '@mk-kit/ui/data';`

Surface treatment for a `MkCard`.

```ts
type MkCardVariant = 'elevated' | 'outlined' | 'filled';
```

### MkDescriptionLayout (type)

Import: `import { MkDescriptionLayout } from '@mk-kit/ui/data';`

Layout for `MkDescriptionList`.

```ts
type MkDescriptionLayout = 'grid' | 'stacked';
```

### MkDiffMode (type)

Import: `import { MkDiffMode } from '@mk-kit/ui/data';`

How `MkDiff` lays out the comparison.

```ts
type MkDiffMode = 'unified' | 'split';
```

### MkDiffOp (type)

Import: `import { MkDiffOp } from '@mk-kit/ui/data';`

The kind of change for a diff row/segment.

```ts
type MkDiffOp = 'equal' | 'insert' | 'delete';
```

### MkDividerOrientation (type)

Import: `import { MkDividerOrientation } from '@mk-kit/ui/data';`

Axis a `MkDivider` is drawn along.

```ts
type MkDividerOrientation = 'horizontal' | 'vertical';
```

### MkMarkdownAlign (type)

Import: `import { MkMarkdownAlign } from '@mk-kit/ui/data';`

Column alignment of a table, from the delimiter row's colons.

```ts
type MkMarkdownAlign = 'left' | 'center' | 'right' | null;
```

### MkMarkdownBlock (type)

Import: `import { MkMarkdownBlock } from '@mk-kit/ui/data';`

Block-level node of the markdown AST.

```ts
type MkMarkdownBlock = | { kind: 'heading'; level: 1 | 2 | 3 | 4 | 5 | 6; children: MkMarkdownInline[] } | { kind: 'paragraph'; children: MkMarkdownInline[] } | { kind: 'code'; language: string; code: string } | { kind: 'blockquote'; children: MkMarkdownBlock[] } | { kind: 'hr' } | MkMarkdownList | { kind: 'table'; align: MkMarkdownAlign[]; header: MkMarkdownInline[][]; rows: MkMarkdownInline[][][]; };
```

### MkMarkdownInline (type)

Import: `import { MkMarkdownInline } from '@mk-kit/ui/data';`

Inline (phrasing) node of the markdown AST.

```ts
type MkMarkdownInline = | { kind: 'text'; text: string } | { kind: 'softbreak' } | { kind: 'break' } | { kind: 'code'; code: string } | { kind: 'strong'; children: MkMarkdownInline[] } | { kind: 'em'; children: MkMarkdownInline[] } | { kind: 'del'; children: MkMarkdownInline[] } | { kind: 'link'; href: string; children: MkMarkdownInline[] } | { kind: 'image'; src: string; alt: string };
```

### MkOrgChartOrientation (type)

Import: `import { MkOrgChartOrientation } from '@mk-kit/ui/data';`

Chart direction: `top` = root at the top, `left` = root at the inline start.

```ts
type MkOrgChartOrientation = 'top' | 'left';
```

### MkOrgChartTemplateData (type)

Import: `import { MkOrgChartTemplateData } from '@mk-kit/ui/data';`

`data` type seen by a node template: `T` when it could be inferred (the
template binds `[mkOrgChartNodeDef]="nodes"`), otherwise `any` so an
untyped `<ng-template mkOrgChartNodeDef>` can still read `node.data?.title`.

```ts
type MkOrgChartTemplateData<T> = keyof T extends never ? any : T;
```

### MkProfileCardOrientation (type)

Import: `import { MkProfileCardOrientation } from '@mk-kit/ui/data';`

Layout direction of a `MkProfileCard`.

```ts
type MkProfileCardOrientation = 'vertical' | 'horizontal';
```

### MkQrEcc (type)

Import: `import { MkQrEcc } from '@mk-kit/ui/data';`

Dependency-free QR Code encoder.

A from-scratch implementation of the QR encoding algorithm (ISO/IEC 18004):
byte-mode (UTF-8) data encoding, Reed–Solomon error correction over GF(256),
matrix construction with function patterns, all eight data masks scored by
the four penalty rules, and BCH format/version information.

Scope: byte mode only, versions 1–10 (module counts 21…57), ECC levels
L/M/Q/H. That covers roughly 7–271 UTF-8 bytes depending on the ECC level.
Numeric/alphanumeric/kanji modes and versions ≥ 11 are intentionally out of
scope — everything is encoded as UTF-8 bytes, which is always valid.

The single public entry point is `mkEncodeQr`, a pure function.

```ts
type MkQrEcc = 'L' | 'M' | 'Q' | 'H';
```

### MkRgb (type)

Import: `import { MkRgb } from '@mk-kit/ui/data';`

An sRGB colour as 0–255 channels.

```ts
type MkRgb = readonly [number, number, number];
```

### MkSkeletonPresetKind (type)

Import: `import { MkSkeletonPresetKind } from '@mk-kit/ui/data';`

Ready-made loading layouts for `MkSkeletonPreset`.

```ts
type MkSkeletonPresetKind = 'paragraph' | 'card' | 'list' | 'table';
```

### MkSkeletonShape (type)

Import: `import { MkSkeletonShape } from '@mk-kit/ui/data';`

Placeholder geometry for a `MkSkeleton`.

```ts
type MkSkeletonShape = 'text' | 'rect' | 'circle';
```

### MkSparklineType (type)

Import: `import { MkSparklineType } from '@mk-kit/ui/data';`

Visual form of a `MkSparkline`.

```ts
type MkSparklineType = 'line' | 'area' | 'bar';
```

### MkStatTrend (type)

Import: `import { MkStatTrend } from '@mk-kit/ui/data';`

Direction of a `MkStatCard` delta.

```ts
type MkStatTrend = 'up' | 'down' | 'neutral';
```

### MkTagVariant (type)

Import: `import { MkTagVariant } from '@mk-kit/ui/data';`

Visual treatment for a `MkTag`.

```ts
type MkTagVariant = 'solid' | 'soft' | 'outline';
```

## @mk-kit/ui/kanban

8 exports. `import { … } from '@mk-kit/ui/kanban';`

### MkKanban (component)

Selector: `mk-kanban`

Docs: https://mk-kit.dev/components/data

Import: `import { MkKanban } from '@mk-kit/ui/kanban';`

Kanban board — a horizontal row of columns whose cards can be dragged and
reordered within a column or transferred between columns. Built on the dnd
group's connected `[mkDropList]` / `[mkDrag]` directives, so it inherits both
pointer and keyboard dragging (WCAG 2.1.1) for free.

Bind `columns` two-way; the model is updated immutably on each drop. Project
an `<ng-template>` to render custom card content — it receives the card as
`$implicit` and the owning column as `column`. Column headers and footers
take their own templates (`mkKanbanColumnHeader` / `mkKanbanColumnFooter`,
context `{ $implicit: column, index, count }`):

```html
<mk-kanban [(columns)]="board" (cardMoved)="onMoved($event)">
  <ng-template mkKanbanColumnHeader let-column let-count="count">
    <strong>{{ column.title }}</strong> {{ count }}
    <button (click)="rename(column)">Rename</button>
  </ng-template>
  <ng-template mkKanbanCard let-card let-column="column">
    <strong>{{ card.title }}</strong>
  </ng-template>
  <ng-template mkKanbanColumnFooter let-column>
    <button (click)="add(column)">+ Card</button>
  </ng-template>
</mk-kanban>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` (two-way) | `MkKanbanColumn[]` | `[]` | The board's columns and their cards (two-way). Updated on every drop. |
| `disabled` | `boolean` | `false` | Disable all dragging on the board. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `columnsChange` | `MkKanbanColumn[]` | Emits when `columns` changes (two-way binding). |
| `cardMoved` | `MkKanbanCardMovedEvent` | Emitted after the model is updated when a card is moved. |

### MkKanbanCardDef (directive)

Selector: `ng-template[mkKanbanCard]`

Import: `import { MkKanbanCardDef } from '@mk-kit/ui/kanban';`

Marks the projected card renderer explicitly:
`<ng-template mkKanbanCard let-card let-column="column">`. Without it the
first plain `<ng-template>` inside `<mk-kanban>` is used, as before 0.54.

### MkKanbanColumnFooterDef (directive)

Selector: `ng-template[mkKanbanColumnFooter]`

Import: `import { MkKanbanColumnFooterDef } from '@mk-kit/ui/kanban';`

Rendered under each column's card list — a "quick add" input, say:
`<ng-template mkKanbanColumnFooter let-column>`.

### MkKanbanColumnHeaderDef (directive)

Selector: `ng-template[mkKanbanColumnHeader]`

Import: `import { MkKanbanColumnHeaderDef } from '@mk-kit/ui/kanban';`

Replaces the default column header (title + count):
`<ng-template mkKanbanColumnHeader let-column let-count="count">`.

### MkKanbanCard (interface)

Import: `import { MkKanbanCard } from '@mk-kit/ui/kanban';`

A single draggable card on a `MkKanban` board.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `unknown` | Stable identity used for tracking and move events. |
| `title` | `string` | Text shown by the default card renderer. |

### MkKanbanCardMovedEvent (interface)

Import: `import { MkKanbanCardMovedEvent } from '@mk-kit/ui/kanban';`

Emitted by `MkKanban` after a card has been moved (between or within
columns) and the two-way `columns` model has been updated.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `card` | `MkKanbanCard` | The card that was moved. |
| `from` | `unknown` | `id` of the column the card came from. |
| `to` | `unknown` | `id` of the column the card was dropped into. |
| `fromIndex` | `number` | The card's index within the source column before the move. |
| `toIndex` | `number` | The card's index within the destination column after the move. |

### MkKanbanColumn (interface)

Import: `import { MkKanbanColumn } from '@mk-kit/ui/kanban';`

A column (bucket) of `MkKanbanCard`s on a `MkKanban` board.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `unknown` | Stable identity used for tracking and move events. |
| `title` | `string` | Heading shown in the column header and used as its aria-label. |
| `cards` | `MkKanbanCard[]` | The ordered cards contained in this column. |

### MkKanbanColumnContext (interface)

Import: `import { MkKanbanColumnContext } from '@mk-kit/ui/kanban';`

Context handed to the column header / footer templates.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `$implicit` | `MkKanbanColumn` | The column being rendered. |
| `index` | `number` | Its position in `columns`. |
| `count` | `number` | `column.cards.length`, for a count badge. |

## @mk-kit/ui/translate

18 exports. `import { … } from '@mk-kit/ui/translate';`

### MkTranslatePipe (pipe)

Pipe name: `translate` · `transform(key: string | null | undefined, params?: MkTranslateParams): string`

Import: `import { MkTranslatePipe } from '@mk-kit/ui/translate';`

`translate` — the key's string in the active language, with `{{name}}`
placeholders filled from `params`. Impure so a language switch (or a
`patch()`) re-renders every use; the signal reads inside `instant()` mark
the host view dirty, so this stays cheap under OnPush and zoneless.

```html
{{ 'menu.title' | translate }}
{{ 'cart.items' | translate: { count: 3 } }}
```

### MkTranslatePluralPipe (pipe)

Pipe name: `translatePlural` · `transform(count: number | string | null | undefined, keyBase: string, params?: MkTranslateParams): string`

Import: `import { MkTranslatePluralPipe } from '@mk-kit/ui/translate';`

`translatePlural` — the CLDR plural form under `keyBase` for a count
(see `MkTranslate.plural`), interpolated with `{ count, ...params }`.

```html
{{ guests | translatePlural: 'reservation.guests' }}   <!-- 2 osoby / 5 osób -->
```

### MkTranslate (service)

Docs: https://mk-kit.dev/components/translate

Import: `import { MkTranslate } from '@mk-kit/ui/translate';`

App translations as signals: a `lang` you switch with `use()`, `instant()`
for code, the `translate` pipe for templates, and `plural()` for CLDR
count forms. Dictionaries are the plain nested JSON you already have; an
optional overrides loader (a database of edits, say) is merged on top per
language. On the server the loaded strings ride to the browser through
`TransferState`, so hydration never refetches or flashes raw keys.

```ts
provideMkTranslate({
  lang: 'pl',
  fallbackLang: 'pl',
  loader: mkHttpTranslateLoader({ prefix: '/assets/i18n/' }),
});
```
```html
{{ 'checkout.cart.total' | translate }}
{{ 'checkout.cart.freeDeliveryMissing' | translate: { amount: 12 } }}
```

Methods:

| Signature | Description |
| --- | --- |
| `getCurrentLang(): string` | The active language as a plain string (for non-reactive call sites). |
| `getLangs(): string[]` | Languages known to the service: loaded ones plus any added with `addLangs`. |
| `addLangs(langs: string[]): void` | Declare languages up front (a switcher's list); loading still happens on `use()`. |
| `setTranslation(lang: string, strings: MkTranslationTree \| MkFlatTranslations, shouldMerge?: boolean): void` | ngx-translate-compatible alias: `setTranslation(lang, strings, true)` merges like `patch`, `false` (the default there) replaces like `set`. |
| `use(lang: string): Promise<void>` | Load `lang` (once — later calls are cached) and make it active. Resolves when the strings are in memory; a failed load rejects and leaves the previous language active. |
| `load(lang: string): Promise<void>` | Load a language into memory without switching to it. |
| `instant(key: string, params?: MkTranslateParams): string` | Translate `key` in the active language, then the fallback; `{{name}}` placeholders come from `params`. A missing key renders as the key itself (or whatever `onMissing` returns) and is recorded in `missingKeys`. Reactive: reading it inside a template or a `computed()` re-runs on language switch and after `patch()`. |
| `has(key: string, lang?: string): boolean` | Whether `key` exists in `lang` (default: the active language) or its fallback. |
| `plural(keyBase: string, count: number, params?: MkTranslateParams): string` | CLDR plural form: `keyBase.{zero\|one\|two\|few\|many\|other}` picked with `Intl.PluralRules` for the active language, `other` as the fallback, interpolated with `{ count, ...params }`.  ```json { "guests": { "one": "{{count}} osoba", "few": "{{count}} osoby", "many": "{{count}} osób", "other": "{{count}} osoby" } } ``` |
| `translations(lang?: string): MkFlatTranslations` | The flat dictionary of `lang` (default: active), `{}` before it loads. |
| `loadedLangs(): string[]` | Languages currently in memory. |
| `patch(lang: string, strings: MkTranslationTree \| MkFlatTranslations): void` | Merge strings into `lang` at runtime — a translation editor previewing an edit, or a late-arriving overrides payload. Nested or flat. |
| `set(lang: string, strings: MkTranslationTree \| MkFlatTranslations): void` | Replace `lang` entirely (tests, editors reloading from source). |
| `isPartial(lang?: string): boolean` | `true` while `lang` holds only a server render's keys and the rest is still loading. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `lang` | `WritableSignal<string>` | The active language. Read it in a `computed()` to follow switches. |
| `ready` | `Signal<boolean>` | `true` once the active language's strings are in memory. |
| `langChange` | `Observable<string>` | `lang` as an observable, for code still written around streams. |
| `missingKeys` | `Signal<string[]>` | Keys asked for that neither the active nor the fallback language has. |
| `currentLang` | `string` | ngx-translate-compatible alias of `getCurrentLang`. |

### mkFlattenTranslations (function)

Import: `import { mkFlattenTranslations } from '@mk-kit/ui/translate';`

`{ a: { b: 'x' } }` → `{ 'a.b': 'x' }`; already-dotted keys pass through.

```ts
function mkFlattenTranslations(tree: MkTranslationTree | null | undefined, prefix?: string, out?: MkFlatTranslations): MkFlatTranslations
```

### mkHttpTranslateLoader (function)

Import: `import { mkHttpTranslateLoader } from '@mk-kit/ui/translate';`

Fetch `<prefix><lang><suffix>` with `HttpClient` — the bundled JSON files
in `assets/i18n/`. Needs `provideHttpClient()`; SSR apps that read the
files from disk can supply their own `MkTranslateLoader` instead.

```ts
function mkHttpTranslateLoader(options?: MkHttpTranslateLoaderOptions): MkTranslateLoaderFactory
```

### mkInterpolate (function)

Import: `import { mkInterpolate } from '@mk-kit/ui/translate';`

Replace `{{name}}` placeholders; unknown names are left in place.

```ts
function mkInterpolate(template: string, params?: MkTranslateParams): string
```

### mkStaticTranslateLoader (function)

Import: `import { mkStaticTranslateLoader } from '@mk-kit/ui/translate';`

Strings given up front, keyed by language — tests, storybooks, tiny apps.
A language not in the map resolves to `{}`.

```ts
function mkStaticTranslateLoader(byLang: Record<string, MkTranslationTree>): MkTranslateLoaderFactory
```

### mkUnflattenTranslations (function)

Import: `import { mkUnflattenTranslations } from '@mk-kit/ui/translate';`

`{ 'a.b': 'x' }` → `{ a: { b: 'x' } }` — for editors that write files back.

```ts
function mkUnflattenTranslations(flat: MkFlatTranslations): MkTranslationTree
```

### provideMkTranslate (function)

Import: `import { provideMkTranslate } from '@mk-kit/ui/translate';`

Register app translations. By default the initial language is loaded
before the first render (`preload`), so no view ever shows raw keys and
nothing caches them.

```ts
providers: [
  provideHttpClient(withFetch()),
  provideMkTranslate({
    lang: 'pl',
    fallbackLang: 'pl',
    loader: mkHttpTranslateLoader(),
    overrides: () => inject(TranslationOverridesApi), // optional
  }),
]
```

```ts
function provideMkTranslate(config: MkTranslateConfig): EnvironmentProviders
```

### MK_TRANSLATE_CONFIG (token)

Import: `import { MK_TRANSLATE_CONFIG } from '@mk-kit/ui/translate';`

Configuration token; set by `provideMkTranslate`.

```ts
const MK_TRANSLATE_CONFIG: InjectionToken<MkTranslateConfig>;
```

### MkTranslateImports (const)

Import: `import { MkTranslateImports } from '@mk-kit/ui/translate';`

Everything a template needs, for `imports: [...MkTranslateImports]` — the
one-line replacement for an ngx-translate `TranslateModule` import.

```ts
const MkTranslateImports: readonly [typeof MkTranslatePipe, typeof MkTranslatePluralPipe];
```

### MkHttpTranslateLoaderOptions (interface)

Import: `import { MkHttpTranslateLoaderOptions } from '@mk-kit/ui/translate';`

Options for `mkHttpTranslateLoader`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `prefix`? | `string \| undefined` | URL prefix; the language code is appended. Default `/assets/i18n/`. |
| `suffix`? | `string \| undefined` | URL suffix after the language code. Default `.json`. |

### MkTranslateConfig (interface)

Import: `import { MkTranslateConfig } from '@mk-kit/ui/translate';`

Options for `provideMkTranslate`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `lang` | `string` | Language loaded first and used until `use()` switches it. |
| `fallbackLang`? | `string \| undefined` | Looked up when the active language lacks a key. Default: none. |
| `loader` | `MkTranslateLoaderFactory` | Base strings — the bundled JSON, typically (`mkHttpTranslateLoader`). |
| `overrides`? | `MkTranslateLoaderFactory \| undefined` | Optional second source merged OVER the base per language: edits kept in a database, a tenant's wording, a translator's work in progress. A loader that throws or resolves `{}` leaves the base untouched. |
| `preload`? | `boolean \| undefined` | Block application bootstrap until the initial language is loaded, so the first render never shows raw keys and `instant()` calls inside `computed()` never cache them. Default `true`. |
| `transfer`? | `"none" \| "used" \| "all" \| undefined` | What a server render hands to the browser through `TransferState`: - `'used'` (default): only the keys read while rendering this page —   a few KB — so hydration never flashes raw keys, while the full   dictionary loads in the background right after; - `'all'`: the whole dictionary (no second request, but every page   carries it); - `'none'`: nothing; the browser loads the file itself before bootstrap. |
| `documentLang`? | `boolean \| undefined` | Mirror the active language onto `<html lang>` (server and browser), so screen readers, hyphenation and search engines follow `use()`. Default `true`. |
| `onMissing`? | `((key: string, lang: string) => string \| undefined \| void) \| undefined` | Called for a key missing in both the active and the fallback language. Return a string to render instead of the key. Missing keys are also collected in `MkTranslate.missingKeys`. |

### MkTranslateLoader (interface)

Import: `import { MkTranslateLoader } from '@mk-kit/ui/translate';`

Where a language's strings come from. Return the tree (or a promise of
it); the service flattens, caches per language and merges overrides.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `load` | `(lang: string): Promise<MkTranslationTree> \| MkTranslationTree` |  |

### MkTranslationTree (interface)

Import: `import { MkTranslationTree } from '@mk-kit/ui/translate';`

A translation file: nested objects of strings. Keys are addressed with
dots (`checkout.cart.total`), so `{ checkout: { cart: { total: '…' } } }`
and `{ 'checkout.cart.total': '…' }` are the same dictionary. This is the
plain JSON most apps already ship (ngx-translate's format included).

### MkFlatTranslations (type)

Import: `import { MkFlatTranslations } from '@mk-kit/ui/translate';`

Flattened dictionary: dotted key → string.

```ts
type MkFlatTranslations = Record<string, string>;
```

### MkTranslateLoaderFactory (type)

Import: `import { MkTranslateLoaderFactory } from '@mk-kit/ui/translate';`

A loader factory; runs inside an injection context, so `inject()` works.

```ts
type MkTranslateLoaderFactory = () => MkTranslateLoader;
```

### MkTranslateParams (type)

Import: `import { MkTranslateParams } from '@mk-kit/ui/translate';`

Values interpolated into `{{name}}` placeholders.

```ts
type MkTranslateParams = Record<string, unknown>;
```

## @mk-kit/ui/attention

16 exports. `import { … } from '@mk-kit/ui/attention';`

### MkSessionExpiryDialog (component)

Selector: `mk-session-expiry-dialog`

Docs: https://mk-kit.dev/components/attention

Import: `import { MkSessionExpiryDialog } from '@mk-kit/ui/attention';`

Last call before a session ends: counts down and offers to extend.
Reaching zero ends the session, so doing nothing still produces a definite,
visible outcome. Opened by `MkSessionExpiry`; usable on its own.

### MkNotificationSound (service)

Docs: https://mk-kit.dev/components/attention

Import: `import { MkNotificationSound } from '@mk-kit/ui/attention';`

Alert sounds for incoming work (orders, messages, tickets) with the
browser's autoplay rules handled: an `AudioContext` stays suspended until a
user gesture, so a sound fired by a WebSocket message would be silent. The
context is unlocked when the user enables sound (a click) and lazily on the
first interaction anywhere in the app. The default sound is synthesised
(a short C–E–G chime) — nothing to ship, no CORS, lowest latency; file
presets are fetched and decoded once and fall back to the chime when they
fail. The on/off preference lives in localStorage under a configurable key.

```ts
provideMkNotificationSound({ presets: [MK_CHIME_PRESET, { id: 'ding', label: 'Ding', url: '/assets/ding.wav' }] })
sound.primeOnFirstInteraction();          // at app start
sound.play(settings.newOrderSound);       // on an event, honours the device mute
sound.preview('ding');                    // settings page test button
```

Methods:

| Signature | Description |
| --- | --- |
| `isEnabled(): boolean` | Whether the device has sound on. |
| `hasBeenAsked(): boolean` | Whether the user ever answered the "enable sound?" question on this device. |
| `setEnabled(enabled: boolean): void` | Persist the preference; call from a click so audio unlocks at once. |
| `primeOnFirstInteraction(): void` | Arm a one-time listener so the first pointer/key interaction unlocks audio. |
| `chime(): void` | The default chime, if the device has sound on. |
| `play(soundId: string, customUrl?: string \| null): void` | Play the sound configured for an event: a preset id, `custom` (with `customUrl`) or `none` (silent). Unknown ids and failed loads fall back to the chime. Honours the device mute. |
| `preview(soundId: string, customUrl?: string \| null): void` | Same as `play()` but ignores the device mute — for settings test buttons. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `presets` | `MkSoundPreset[]` | The selectable presets (always includes the chime). |

### MkSessionExpiry (service)

Docs: https://mk-kit.dev/components/attention

Import: `import { MkSessionExpiry } from '@mk-kit/ui/attention';`

Watches `expiresAt()` and warns BEFORE the session lapses, so a session
never ends silently: the dialog offers to extend, or signs out at zero.
Re-arms itself whenever `expiresAt()` changes (every token rotation),
runs the timer outside the Angular zone and only in the browser. Started
automatically by `provideMkSessionExpiry`.

Methods:

| Signature | Description |
| --- | --- |
| `start(): void` | Begin watching. Idempotent; called by the provider's initializer. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `open` | `WritableSignal<boolean>` | Whether the dialog is currently open. |

### MkTabAttention (service)

Docs: https://mk-kit.dev/components/attention

Import: `import { MkTabAttention } from '@mk-kit/ui/attention';`

Messenger-style tab attention: while unhandled work exists the favicon
carries a red counter badge, and — only while the tab is hidden — the
title alternates with "(N) label" so a pinned tab flashes in the tab strip.
Focusing the tab stops the blinking (someone is looking) but keeps the
badge until the count reaches zero. SSR-safe: every entry point bails
without a `document`; the blink timer runs outside the Angular zone.

```ts
private attention = inject(MkTabAttention);
effect(() => this.attention.set(this.pending().length, 'new orders'));
```

Methods:

| Signature | Description |
| --- | --- |
| `set(count: number, label?: string): void` | Update the pending count and the label used in the blinking title. |
| `clear(): void` | Drop the badge and the blinking entirely and stop listening. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `count` | `WritableSignal<number>` | The count currently shown (0 = nothing pending). |

### provideMkNotificationSound (function)

Import: `import { provideMkNotificationSound } from '@mk-kit/ui/attention';`

Register presets / storage key for `MkNotificationSound`. Optional.

```ts
function provideMkNotificationSound(config: MkNotificationSoundConfig): { provide: InjectionToken<MkNotificationSoundConfig>; useValue: MkNotificationSoundConfig; }
```

### provideMkSessionExpiry (function)

Import: `import { provideMkSessionExpiry } from '@mk-kit/ui/attention';`

Register the session-expiry watcher; it starts with the application.

```ts
provideMkSessionExpiry({
  expiresAt: () => auth.tokenExpiresAt(),
  extend: () => firstValueFrom(auth.refresh()),
  onExpire: () => auth.logout(),
  warnBeforeMs: 2 * 60_000,
})
```

```ts
function provideMkSessionExpiry(config: MkSessionExpiryConfig): EnvironmentProviders
```

### provideMkTabAttention (function)

Import: `import { provideMkTabAttention } from '@mk-kit/ui/attention';`

Register options for `MkTabAttention`. Optional — the defaults work.

```ts
function provideMkTabAttention(config: MkTabAttentionConfig): { provide: InjectionToken<MkTabAttentionConfig>; useValue: MkTabAttentionConfig; }
```

### MK_NOTIFICATION_SOUND_CONFIG (token)

Import: `import { MK_NOTIFICATION_SOUND_CONFIG } from '@mk-kit/ui/attention';`

```ts
const MK_NOTIFICATION_SOUND_CONFIG: InjectionToken<MkNotificationSoundConfig>;
```

### MK_SESSION_EXPIRY_CONFIG (token)

Import: `import { MK_SESSION_EXPIRY_CONFIG } from '@mk-kit/ui/attention';`

```ts
const MK_SESSION_EXPIRY_CONFIG: InjectionToken<MkSessionExpiryConfig>;
```

### MK_TAB_ATTENTION_CONFIG (token)

Import: `import { MK_TAB_ATTENTION_CONFIG } from '@mk-kit/ui/attention';`

```ts
const MK_TAB_ATTENTION_CONFIG: InjectionToken<MkTabAttentionConfig>;
```

### MK_CHIME_PRESET (const)

Import: `import { MK_CHIME_PRESET } from '@mk-kit/ui/attention';`

The always-available synthesised sound.

```ts
const MK_CHIME_PRESET: MkSoundPreset;
```

### MkNotificationSoundConfig (interface)

Import: `import { MkNotificationSoundConfig } from '@mk-kit/ui/attention';`

Options for `MkNotificationSound`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `presets`? | `MkSoundPreset[] \| undefined` | Selectable sounds; the ids `custom` and `none` are reserved. Default: the chime only. |
| `storageKey`? | `(() => string) \| undefined` | localStorage key for the on/off preference — a function so it can vary per tenant / user. |
| `volume`? | `number \| undefined` | Output gain for file presets (0–1). Default `0.8`. |

### MkSessionExpiryConfig (interface)

Import: `import { MkSessionExpiryConfig } from '@mk-kit/ui/attention';`

Options for `provideMkSessionExpiry`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `expiresAt` | `() => number \| null` | Epoch ms when the session lapses, or `null` when there is none. Read reactively. |
| `warnBeforeMs`? | `number \| undefined` | How long before the lapse the dialog appears. Default 2 minutes. |
| `extend` | `() => Promise<unknown>` | Extend the session (refresh the token). Resolve = extended, reject = nothing to extend. |
| `onExpire` | `() => void` | End the session (sign out, navigate). |
| `enabled`? | `(() => boolean) \| undefined` | Read reactively; `false` suspends the watcher (a kiosk / PIN mode, say). |

### MkSessionExpiryDialogData (interface)

Import: `import { MkSessionExpiryDialogData } from '@mk-kit/ui/attention';`

Data handed to `MkSessionExpiryDialog`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `expiresAt` | `number` |  |
| `extend` | `() => Promise<unknown>` |  |
| `onExpire` | `() => void` |  |

### MkSoundPreset (interface)

Import: `import { MkSoundPreset } from '@mk-kit/ui/attention';`

One selectable alert sound. `url: null` = the synthesised chime.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `label` | `string` |  |
| `url` | `string \| null` |  |

### MkTabAttentionConfig (interface)

Import: `import { MkTabAttentionConfig } from '@mk-kit/ui/attention';`

Options for `MkTabAttention`, set with `provideMkTabAttention`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `badgeColor`? | `string \| undefined` | Badge fill colour (any CSS colour). Default `#e53935`. |
| `blinkMs`? | `number \| undefined` | Title blink period in ms while the tab is hidden. Default `1200`. |

## @mk-kit/ui/feedback

55 exports. `import { … } from '@mk-kit/ui/feedback';`

### MkAlert (component)

Selector: `mk-alert`

Docs: https://mk-kit.dev/components/feedback

Import: `import { MkAlert } from '@mk-kit/ui/feedback';`

Alert — an inline banner that communicates a contextual status message.
Fully themed via `--mk-*` tokens using the same tone/local-var pattern as
the Button. Danger/warning alerts use `role="alert"` (assertive), all other
tones use `role="status"` (polite).

```html
<mk-alert tone="success" title="Saved">Your changes were saved.</mk-alert>

<mk-alert tone="danger" variant="outline" dismissible (dismissed)="hide()">
  <svg mkAlertIcon>…</svg>
  Could not reach the server.
</mk-alert>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `MkAlertTone` | `'info'` | Semantic color tone. |
| `variant` | `MkAlertVariant` | `'soft'` | Visual treatment. |
| `title` | `string \| undefined` |  | Optional bold heading rendered above the message. |
| `dismissible` | `boolean` | `false` | When set, renders a keyboard-accessible close button that emits `dismissed`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `dismissed` | `void` | Emitted when the user activates the close button. |

### MkBanner (component)

Selector: `mk-banner`

Docs: https://mk-kit.dev/components/feedback

Import: `import { MkBanner } from '@mk-kit/ui/feedback';`

Banner — a persistent, full-width page/section message with a tone, optional
title, an actions slot and optional dismiss. Heavier than an inline
`MkAlert` toast; use it for standing notices ("Trial ends in 3 days").

Project an icon with `[mkBannerIcon]` and buttons with `[mkBannerActions]`.
Danger/warning banners announce assertively (`role="alert"`).

```html
<mk-banner tone="warning" title="Storage almost full" dismissible>
  You've used 90% of your quota.
  <button mkButton size="sm" mkBannerActions>Upgrade</button>
</mk-banner>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `MkTone` | `'info'` | Semantic color tone. |
| `title` | `string` | `''` | Optional bold title above the message. |
| `dismissible` | `boolean` | `false` | Show a dismiss (×) button. |
| `open` (two-way) | `boolean` | `true` | Two-way open state; set false to hide. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `openChange` | `boolean` | Emits when `open` changes (two-way binding). |
| `dismissed` | `void` | Emitted when the banner is dismissed. |

### MkBlockUiOverlay (component)

Selector: `mk-block-ui-overlay`

Import: `import { MkBlockUiOverlay } from '@mk-kit/ui/feedback';`

The translucent panel with a spinner that `mkBlockUi` and
`MkBlockUiService` drop over a region or the page.

### MkBottomSheet (component)

Selector: `mk-bottom-sheet`

Docs: https://mk-kit.dev/components/bottom-sheet

Import: `import { MkBottomSheet } from '@mk-kit/ui/feedback';`

BottomSheet layout — the surface rendered inside an `MkOverlayService`
panel by `MkBottomSheetService`. Provides a drag handle (swipe down to
dismiss), an optional titled header with a close button, and a scrollable
body for projected content.

Slots: `[mkBottomSheetHeader]` (extra header content), default content
(body), `[mkBottomSheetFooter]` (sticky footer).

```html
<mk-bottom-sheet sheetTitle="Share">
  <button mkButton fullWidth variant="ghost">Copy link</button>
  <button mkButton fullWidth variant="ghost">Email</button>
</mk-bottom-sheet>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `sheetTitle` | `string \| undefined` |  | Optional plain-text title rendered in the header. |
| `titleId` | `string` | `mkUniqueId('mk-bottom-sheet-title')` | Stable id for the built-in title element. |
| `hideHandle` | `boolean` | `false` | Hide the drag handle (also disables swipe-to-dismiss). |
| `hideClose` | `boolean` | `false` | Hide the header close button. |

### MkConfirmDialog (component)

Selector: `mk-confirm-dialog`

Docs: https://mk-kit.dev/components/dialogs

Import: `import { MkConfirmDialog } from '@mk-kit/ui/feedback';`

Internal component backing `MkDialogService.confirm`. Renders a title,
message, and cancel/confirm buttons. Resolves the overlay ref with `true`
on confirm and `false` on cancel. Uses `alertdialog` semantics for the
`danger` tone (set on the panel by the service).

### MkDialog (component)

Selector: `mk-dialog`

Docs: https://mk-kit.dev/components/dialogs

Import: `import { MkDialog } from '@mk-kit/ui/feedback';`

Dialog layout — a surface with a sticky header, scrollable body, and sticky
footer, designed to be rendered inside an `MkOverlayService` panel. The
header exposes a close button wired to the injected `MkOverlayRef` and
the dialog's title is linked to the panel via `aria-labelledby`.

Slots: `[mkDialogHeader]` / `<mk-dialog-title>` (header), default content
(body), `[mkDialogFooter]` (footer).

```html
<mk-dialog>
  <mk-dialog-title>Rename</mk-dialog-title>
  <p>Choose a new name.</p>
  <div mkDialogFooter>
    <button mkButton variant="ghost">Cancel</button>
    <button mkButton>Save</button>
  </div>
</mk-dialog>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `dialogTitle` | `string \| undefined` |  | Optional plain-text title. Ignored when a `<mk-dialog-title>` is projected. |
| `titleId` | `string` | `mkUniqueId('mk-dialog-title')` | Stable id for the built-in title element. |
| `hideClose` | `boolean` | `false` | Hide the header close button. |
| `draggable` | `boolean` | `false` | Let the user move the dialog by dragging its header (pointer / touch) or with the arrow keys on the grip that appears in the header. Double-click the header or press Home on the grip to snap back to the centre. |
| `resizable` | `boolean` | `false` | Let the user resize the dialog from the corner grip (pointer / touch, or arrow keys on the grip; Home resets). The panel never grows past the viewport or shrinks below a usable minimum. |

Methods:

| Signature | Description |
| --- | --- |
| `reset(): void` | Snap back to the centred, preset-sized panel. |

### MkDialogTitle (component)

Selector: `mk-dialog-title`

Docs: https://mk-kit.dev/components/dialogs

Import: `import { MkDialogTitle } from '@mk-kit/ui/feedback';`

Accessible heading for a dialog. Renders as a level-2 heading and exposes a
stable id that `MkDialog` wires to the panel's `aria-labelledby`.

```html
<mk-dialog>
  <mk-dialog-title>Delete workspace</mk-dialog-title>
  …
</mk-dialog>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | `mkUniqueId('mk-dialog-title')` | Stable id used for `aria-labelledby` wiring. |

### MkHovercard (component)

Selector: `mk-hovercard` · exportAs: `mkHovercard`

Docs: https://mk-kit.dev/components/popovers

Import: `import { MkHovercard } from '@mk-kit/ui/feedback';`

Hovercard — a rich hover-preview panel anchored to a trigger, in the spirit of
GitHub's user hovercards. Unlike `MkTooltip` (short text) it projects
arbitrary content, and unlike `MkPopover` (click) it opens on hover/focus
after a short delay and closes when the pointer leaves both the trigger and the
card. It is driven by the `mkHovercardFor` directive (or the `open`/`close` API).

The panel renders in the browser top layer through `MkAnchoredPanel`, so
it is never clipped by an ancestor's `overflow`/`transform`. It is non-modal —
no focus trap. Moving the pointer from the trigger onto the card keeps it open;
Escape closes it.

```html
<a href="/u/ada" [mkHovercardFor]="ada">@ada</a>
<mk-hovercard #ada ariaLabel="Ada Lovelace">
  <img src="/ada.png" alt="" /><strong>Ada Lovelace</strong>
</mk-hovercard>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `MkPlacement` | `'bottom-start'` | Preferred placement relative to the trigger. |
| `ariaLabel` | `string \| undefined` |  | Accessible label for the panel. |
| `openDelay` | `number` | `300` | Delay in ms before the card opens on hover/focus. Default `300`. |
| `closeDelay` | `number` | `200` | Delay in ms before the card closes after the pointer leaves. Default `200`. |
| `closeOnEscape` | `boolean` | `true` | Close the card when Escape is pressed while it is open. Default `true`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `closed` | `void` | Emitted whenever the hovercard closes (any reason). |

Methods:

| Signature | Description |
| --- | --- |
| `scheduleOpen(trigger: HTMLElement): void` | Open the card anchored to `trigger` after `openDelay` (cancels a pending close). |
| `scheduleClose(): void` | Close the card after `closeDelay` (cancels a pending open). |
| `keepOpen(): void` | Keep the card open: cancel any pending open/close. Called when the pointer enters the card itself, so moving from the trigger to the card is seamless. |
| `open(trigger: HTMLElement): void` | Open the card immediately, anchored to `trigger`. |
| `close(): void` | Close the card immediately. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `panelId` | `string` | Stable id for `aria-controls` on the trigger. |
| `opened` | `Signal<boolean>` | Whether the hovercard is open. |

### MkLoadingBar (component)

Selector: `mk-loading-bar`

Docs: https://mk-kit.dev/components/feedback

Import: `import { MkLoadingBar } from '@mk-kit/ui/feedback';`

LoadingBar — a thin progress bar fixed to the top of the viewport, driven by
`MkLoadingBarService`. Place it once (e.g. in the app shell) and call
`start()` / `complete()` on navigation or async work.

```html
<mk-loading-bar />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `color` | `string` | `'var(--mk-primary)'` | Bar colour. |
| `height` | `number` | `3` | Bar thickness in px. |

### MkNotificationCenter (component)

Selector: `mk-notification-center`

Docs: https://mk-kit.dev/components/status

Import: `import { MkNotificationCenter } from '@mk-kit/ui/feedback';`

NotificationCenter — a bell trigger with an unread-count badge that opens a
dropdown panel listing notifications, each markable as read.

The panel renders in the browser top layer through `MkAnchoredPanel`,
so it is never clipped by an ancestor's `overflow`/`transform`. Clicking the
bell toggles it; an outside click, Tabbing out or Escape closes it and
restores focus to the bell. Clicking a row marks that one read (updating the
two-way `notifications` immutably); "Mark all read" clears every unread item.

```html
<mk-notification-center
  [(notifications)]="items"
  (itemClick)="open($event)"
  (markedAllRead)="sync()" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `notifications` (two-way) | `MkNotification[]` | `[]` | Two-way list of notifications rendered in the panel. |
| `panelTitle` | `string` | `this.i18n.notificationsTitle` | Heading shown at the top of the panel. |
| `emptyText` | `string` | `this.i18n.allCaughtUp` | Message shown by the empty state when there are no notifications. |
| `maxHeight` | `string` | `'24rem'` | Max height of the scrollable list (any CSS length). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `notificationsChange` | `MkNotification[]` | Emits when `notifications` changes (two-way binding). |
| `itemClick` | `MkNotification` | Emitted with a notification when its row is clicked. |
| `read` | `MkNotification` | Emitted with a notification when it transitions to read. |
| `markedAllRead` | `void` | Emitted when every notification is marked read at once. |

Methods:

| Signature | Description |
| --- | --- |
| `toggle(): void` | Toggle the panel open/closed. |
| `openPanel(): void` | Open the panel, moving focus into it on the next render. |
| `close(restoreFocus?: boolean): void` | Close the panel; optionally restore focus to the bell trigger. |
| `markAllRead(): void` | Mark every notification read and emit `markedAllRead`. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `panelId` | `string` | Stable id linking the trigger to the panel via `aria-controls`. |
| `titleId` | `string` | Stable id for the panel's labelling heading. |
| `open` | `Signal<boolean>` | Whether the panel is open. |
| `unreadCount` | `Signal<number>` | Count of notifications that are not yet read. |

### MkPopconfirm (component)

Selector: `mk-popconfirm` · exportAs: `mkPopconfirm`

Docs: https://mk-kit.dev/components/popovers

Import: `import { MkPopconfirm } from '@mk-kit/ui/feedback';`

Popconfirm — an inline confirmation popover (e.g. a row-level "Delete?").
Composes `MkPopover` with a message and cancel/confirm buttons, so it
inherits the top-layer positioning + focus behaviour. Attach it with the
`mkPopconfirmFor` directive.

```html
<button mkButton tone="danger" [mkPopconfirmFor]="del">Delete</button>
<mk-popconfirm #del message="Delete this item?" (confirm)="remove()" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `message` | `string` | `this.i18n.confirmMessage` | Confirmation message. |
| `title` | `string \| undefined` |  | Optional bold heading above the message. |
| `confirmText` | `string` | `this.i18n.confirm` | Confirm button label. |
| `cancelText` | `string` | `this.i18n.cancel` | Cancel button label. |
| `tone` | `MkTone` | `'danger'` | Tone of the confirm button (destructive actions use `danger`). |
| `placement` | `MkPlacement` | `'top'` | Preferred placement relative to the trigger. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `confirm` | `void` | Emitted when the user confirms. |
| `cancel` | `void` | Emitted when the user cancels (button, Escape or outside click). |

Methods:

| Signature | Description |
| --- | --- |
| `opened(): boolean` | Whether the popconfirm is open. |
| `open(trigger: HTMLElement): void` | Open anchored to `trigger`. |
| `toggle(trigger: HTMLElement): void` | Toggle from a trigger. |
| `close(): void` | Close the popconfirm. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `panelId` | `string \| null` | Id of the underlying dialog panel (for the trigger's `aria-controls`). |

### MkPopover (component)

Selector: `mk-popover` · exportAs: `mkPopover`

Docs: https://mk-kit.dev/components/popovers

Import: `import { MkPopover } from '@mk-kit/ui/feedback';`

Popover — a non-modal floating panel for rich (non-text) content, anchored to
a trigger. Unlike `MkTooltip` (text, hover) it holds arbitrary projected
content and is opened by click via the `mkPopoverTriggerFor` directive (or the
`open`/`toggle` API).

The panel renders in the browser top layer through `MkAnchoredPanel`, so
it is never clipped by an ancestor's `overflow`/`transform`. On open, focus
moves into the panel; Escape closes and restores focus to the trigger, an
outside click or Tabbing out closes it (non-modal — no keyboard trap).

```html
<button mkButton [mkPopoverTriggerFor]="info">Details</button>
<mk-popover #info ariaLabel="Details">
  <h4>Shipping</h4><p>Ships in 2–3 business days.</p>
</mk-popover>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `placement` | `MkPlacement` | `'bottom'` | Preferred placement relative to the trigger. |
| `ariaLabel` | `string \| undefined` |  | Accessible label for the dialog panel. |
| `autoFocus` | `boolean` | `true` | Move focus into the panel on open. Default `true`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `closed` | `void` | Emitted whenever the popover closes (any reason). |

Methods:

| Signature | Description |
| --- | --- |
| `open(trigger: HTMLElement): void` | Open the popover anchored to `trigger`. |
| `close(restoreFocus?: boolean): void` | Close the popover; optionally restore focus to the trigger. |
| `toggle(trigger: HTMLElement): void` | Toggle open/closed from a trigger. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `panelId` | `string` | Stable id for `aria-controls` on the trigger. |
| `opened` | `Signal<boolean>` | Whether the popover is open. |

### MkResult (component)

Selector: `mk-result`

Docs: https://mk-kit.dev/components/status

Import: `import { MkResult } from '@mk-kit/ui/feedback';`

Result — a centred, full-page status state: a success confirmation, an error,
an empty 404/403/500 page. Renders a large status icon (chosen from
`status`), a title, a muted subtitle, projected body content, and a row of
action buttons at the bottom.

Slots: `[mkResultIcon]` (custom icon, overrides the built-in glyph),
`[mkResultTitle]` (custom heading, used when `resultTitle` is unset), default
content (extra body), `[mkResultActions]` (buttons).

```html
<mk-result status="success" resultTitle="Payment complete"
  subtitle="Your order is on its way.">
  <button mkButton mkResultActions>Back home</button>
</mk-result>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `MkResultStatus` | `'info'` | Status preset that selects the built-in icon glyph and its tone colour. |
| `resultTitle` | `string` | `''` | Main heading rendered as an `<h2>` (falls back to the `[mkResultTitle]` slot). |
| `subtitle` | `string` | `''` | Supporting muted sentence under the title. |

### MkSnackbar (component)

Selector: `mk-snackbar`

Import: `import { MkSnackbar } from '@mk-kit/ui/feedback';`

The visual snackbar bar. Internal to the snackbar system — rendered by
`MkSnackbarContainer`. Shows a message, an optional action button and
(when `dismissible`) a close button. Auto-dismiss pauses on hover/focus.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `item` (required) | `MkSnackbarItem` |  | The snackbar model to render. |

### MkSnackbarContainer (component)

Selector: `mk-snackbar-container`

Import: `import { MkSnackbarContainer } from '@mk-kit/ui/feedback';`

Fixed, bottom-centre host that renders the single active snackbar from
`MkSnackbarService`. Mounted once, lazily, into `document.body` by the
service — not intended for direct template use.

### MkToast (component)

Selector: `mk-toast`

Import: `import { MkToast } from '@mk-kit/ui/feedback';`

A single toast card. Internal to the toast system — rendered by
`MkToastContainer`. Displays a tone accent, optional title, message,
optional action button, and (when dismissible) a close button. Auto-dismiss
pauses while the toast is hovered or focused.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `item` (required) | `MkToastItem` |  | The toast model to render. |

### MkToastContainer (component)

Selector: `mk-toast-container`

Import: `import { MkToastContainer } from '@mk-kit/ui/feedback';`

Fixed, bottom-right stack that renders the active toasts from
`MkToastService`. Mounted once, lazily, into `document.body` by the
service — not intended for direct template use.

### MkTooltipPanel (component)

Selector: `mk-tooltip`

Import: `import { MkTooltipPanel } from '@mk-kit/ui/feedback';`

Body-level presentation surface for `MkTooltip`. Rendered imperatively
by the directive; not intended for direct template use.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | `''` | Text content shown inside the tooltip. |
| `id` | `string \| undefined` |  | DOM id used to wire `aria-describedby` on the trigger. |
| `placement` | `MkPlacement` | `'top'` | Resolved placement relative to the trigger. |
| `visible` | `boolean` | `false` | Drives the entrance/exit transition. |

### MkTourPopup (component)

Selector: `mk-tour-popup`

Import: `import { MkTourPopup } from '@mk-kit/ui/feedback';`

The floating coach-mark popover for one tour step. Rendered dynamically by
`MkTourService` (one instance per step) and anchored to the step's
target through `MkAnchoredPanel`, so it lives in the browser top layer
and is never clipped by an ancestor's `overflow`/`transform`.

### MkBlockUi (directive)

Selector: `[mkBlockUi]`

Docs: https://mk-kit.dev/components/loading

Import: `import { MkBlockUi } from '@mk-kit/ui/feedback';`

Block UI — cover the host element with a translucent panel and spinner
while something loads, so its contents can neither be read nor operated:
a card refreshing, a form submitting, a table re-fetching.

Children get `inert` (no clicks, no Tab stops) and the host `aria-busy`.
`mkBlockUiDelay` (ms) holds the overlay back for quick operations so the
screen does not flash.

```html
<mk-card [mkBlockUi]="saving()" mkBlockUiMessage="Saving…">…</mk-card>
<form [mkBlockUi]="submitting()" [mkBlockUiDelay]="300">…</form>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkBlockUi` | `boolean` | `false` | Block while `true`. |
| `mkBlockUiMessage` | `string` | `''` | Text under the spinner (also its accessible label). |
| `mkBlockUiDelay` | `number` | `0` | Wait this many ms before showing, to avoid a flash on fast operations. |

### MkHovercardTrigger (directive)

Selector: `[mkHovercardFor]` · exportAs: `mkHovercardTrigger`

Docs: https://mk-kit.dev/components/popovers

Import: `import { MkHovercardTrigger } from '@mk-kit/ui/feedback';`

Turns its host element into a hover/focus trigger for an `<mk-hovercard>`.
On `mouseenter`/`focus` it opens the card (after the card's `openDelay`),
anchored to the host; on `mouseleave`/`blur` it schedules a close (after the
card's `closeDelay`). Moving the pointer — or keyboard focus — from the host
onto the card cancels that close, so the card stays open and its content is
reachable with Tab. Escape closes it.

On touch there is no hover, so a tap toggles instead: tap opens the card
immediately, tapping the trigger again closes it, and a tap anywhere else
closes it through the panel's outside-pointerdown dismissal.

```html
<a href="/u/ada" [mkHovercardFor]="ada">@ada</a>
<mk-hovercard #ada>…</mk-hovercard>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkHovercardFor` (required) | `MkHovercard` |  | The hovercard instance to control. |

### MkPopconfirmTrigger (directive)

Selector: `[mkPopconfirmFor]` · exportAs: `mkPopconfirmTrigger`

Docs: https://mk-kit.dev/components/popovers

Import: `import { MkPopconfirmTrigger } from '@mk-kit/ui/feedback';`

Turns its host element into a click trigger for an `<mk-popconfirm>`. Wires
`aria-haspopup="dialog"` / `aria-expanded` / `aria-controls`, toggles on click
and closes on Escape.

```html
<button mkButton tone="danger" [mkPopconfirmFor]="del">Delete</button>
<mk-popconfirm #del message="Delete this item?" (confirm)="remove()" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkPopconfirmFor` (required) | `MkPopconfirm` |  | The popconfirm instance to control. |

### MkPopoverTrigger (directive)

Selector: `[mkPopoverTriggerFor]` · exportAs: `mkPopoverTrigger`

Docs: https://mk-kit.dev/components/popovers

Import: `import { MkPopoverTrigger } from '@mk-kit/ui/feedback';`

Turns its host element into a click trigger for an `<mk-popover>`. Wires
`aria-haspopup="dialog"` / `aria-expanded` / `aria-controls`, toggles on click
and closes on Escape.

```html
<button mkButton [mkPopoverTriggerFor]="info">Details</button>
<mk-popover #info>…</mk-popover>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkPopoverTriggerFor` (required) | `MkPopover` |  | The popover instance to control. |

### MkTooltip (directive)

Selector: `[mkTooltip]`

Docs: https://mk-kit.dev/components/popovers

Import: `import { MkTooltip } from '@mk-kit/ui/feedback';`

Tooltip directive — shows a themed tooltip on hover AND keyboard focus, and
hides on blur, mouse-leave (after a short grace period — the pointer may
move onto the tooltip itself, which keeps it open, per WCAG 1.4.13), or
Escape pressed anywhere while it is visible. The tooltip is appended to
`document.body`, positioned relative to the host, and wired to the host via
`aria-describedby` for screen-reader users. Respects `prefers-reduced-motion`.

```html
<button mkButton [mkTooltip]="'Delete row'" mkTooltipPlacement="bottom">
  <svg>…</svg>
</button>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkTooltip` | `string` | `''` | Tooltip text. When empty the tooltip is suppressed. |
| `mkTooltipPlacement` | `MkPlacement` | `'top'` | Preferred placement relative to the host. |

### MkBlockUiService (service)

Docs: https://mk-kit.dev/components/loading

Import: `import { MkBlockUiService } from '@mk-kit/ui/feedback';`

Block the whole page. Reference-counted: every `block()` returns a release
function, and the overlay disappears once all of them have been called.

```ts
const release = this.blockUi.block('Exporting…');
try { await this.api.export(); } finally { release(); }
```

Methods:

| Signature | Description |
| --- | --- |
| `block(message?: string): () => void` | Show the page overlay (or update its message); call the returned function to release. |
| `isBlocked(): boolean` | True while the page is blocked. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `count` | `Signal<number>` | Number of active blocks. |

### MkBottomSheetService (service)

Docs: https://mk-kit.dev/components/bottom-sheet

Import: `import { MkBottomSheetService } from '@mk-kit/ui/feedback';`

BottomSheet service — a thin layer over `MkOverlayService` that renders
a component in a panel anchored to the bottom edge of the viewport: full
width on small screens, a centred card capped at ~42rem on large ones. It
slides up on open and can be swiped down to dismiss (via `MkBottomSheet`).

Use it for contextual actions, pickers and mobile-style menus. For a centred
modal use `MkDialogService` instead.

```ts
const ref = bottomSheet.open(ShareSheet, { data: { url } });
const choice = await ref.afterClosed;
```

Methods:

| Signature | Description |
| --- | --- |
| `open<TComponent, TResult = unknown, TData = unknown>(component: Type<TComponent>, config?: MkBottomSheetConfig<TData>): MkOverlayRef<TResult, TComponent>` | Open `component` inside a bottom-anchored sheet panel. |

### MkDialogService (service)

Docs: https://mk-kit.dev/components/dialogs

Import: `import { MkDialogService } from '@mk-kit/ui/feedback';`

Dialog service — a thin, opinionated layer over `MkOverlayService` that
renders content on a themed `--mk-surface` panel (shadow, radius, entrance
animation) and adds a `confirm()` convenience.

```ts
const ref = dialog.open(EditUserDialog, { data: user });
const saved = await ref.afterClosed;

if (await dialog.confirm({ title: 'Delete?', message: 'This cannot be undone.', tone: 'danger' })) {
  remove();
}
```

Methods:

| Signature | Description |
| --- | --- |
| `open<TComponent, TResult = unknown, TData = unknown>(component: Type<TComponent>, config?: MkDialogConfig<TData>): MkOverlayRef<TResult, TComponent>` | Open `component` inside a themed dialog panel. |
| `confirm(data: MkConfirmDialogData): Promise<boolean>` | Open a confirmation dialog. Resolves `true` if confirmed, `false` if the user cancels, presses Escape, or clicks the backdrop. |
| `alert(data: Omit<MkConfirmDialogData, "hideCancel" \| "cancelText">): Promise<void>` | Open a single-button acknowledgement dialog. Resolves when the user dismisses it (button, Escape, or backdrop). |
| `prompt(data: MkPromptDialogData): Promise<string \| null>` | Open a single-field prompt dialog. Resolves with the entered string, or `null` if the user cancels, presses Escape, or clicks the backdrop. |

### MkLoadingBarService (service)

Docs: https://mk-kit.dev/components/feedback

Import: `import { MkLoadingBarService } from '@mk-kit/ui/feedback';`

Drives a global `MkLoadingBar` — the thin top-of-page progress bar for
route changes and background work. `start()` shows it and trickles toward 90%;
`complete()` finishes and hides it. Also supports a determinate `set(value)`.

```ts
const bar = inject(MkLoadingBarService);
router.events.subscribe(e => {
  if (e instanceof NavigationStart) bar.start();
  if (e instanceof NavigationEnd) bar.complete();
});
```

Methods:

| Signature | Description |
| --- | --- |
| `start(): void` | Show the bar and start trickling toward 90%. |
| `set(value: number): void` | Set an explicit determinate value (0–100). |
| `inc(amount?: number): void` | Nudge progress up by `amount` (default 5), capped at 90%. |
| `complete(): void` | Finish (jump to 100%) then fade out. |
| `stop(): void` | Hide immediately without finishing. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `progress` | `Signal<number>` | Current progress, 0–100. |
| `active` | `Signal<boolean>` | Whether the bar is visible. |
| `finishing` | `Signal<boolean>` | True while finishing (progress full but not yet hidden). |

### MkSnackbarService (service)

Docs: https://mk-kit.dev/components/snackbar

Import: `import { MkSnackbarService } from '@mk-kit/ui/feedback';`

Snackbar service — shows a single, brief message at the bottom-centre of the
viewport with an optional action button, following the Material snackbar
model: only one is visible at a time, and opening a new one replaces the
current. For stacked, persistent notifications use `MkToastService` instead.

```ts
const ref = snackbar.open('Message archived', 'Undo');
ref.onAction().then(() => restore());

snackbar.open('Changes saved', undefined, { tone: 'success' });
```

Methods:

| Signature | Description |
| --- | --- |
| `open(message: string, action?: string, config?: MkSnackbarConfig): MkSnackbarRef` | Open a snackbar. `action` is the (optional) button label — react to it via the returned ref's `MkSnackbarRef.onAction`. |
| `dismiss(id: number): void` | Dismiss the snackbar with the given id (if it is the active one). |
| `runAction(id: number): void` | Run the action for the active snackbar, then close it. |
| `pause(): void` | Pause the auto-dismiss countdown (e.g. on hover/focus). |
| `resume(): void` | Resume a paused countdown. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `active` | `Signal<MkSnackbarItem \| null>` | The currently visible snackbar, or `null`. |

### MkToastService (service)

Docs: https://mk-kit.dev/components/snackbar

Import: `import { MkToastService } from '@mk-kit/ui/feedback';`

Toast service — enqueues transient notifications rendered by a single,
lazily-mounted `MkToastContainer` at the bottom-right of the viewport.
Each rendered toast is itself a live region (`role="alert"` for `danger`,
else `role="status"`), so assistive tech announces it exactly once. Toasts
auto-dismiss after `duration` ms unless it is `0`.

```ts
toasts.success('Saved');
toasts.show({ title: 'Upload failed', message: 'Retry?', tone: 'danger',
  duration: 0, action: { label: 'Retry', handler: () => retry() } });
```

Methods:

| Signature | Description |
| --- | --- |
| `show(config: MkToastConfig): number` | Show a toast, returning its id (usable with `dismiss`). |
| `info(message: string, config?: Partial<MkToastConfig>): number` | Show an `info` toast. |
| `success(message: string, config?: Partial<MkToastConfig>): number` | Show a `success` toast. |
| `warning(message: string, config?: Partial<MkToastConfig>): number` | Show a `warning` toast. |
| `danger(message: string, config?: Partial<MkToastConfig>): number` | Show a `danger` toast. |
| `neutral(message: string, config?: Partial<MkToastConfig>): number` | Show a `neutral` toast. |
| `dismiss(id: number): void` | Dismiss a toast by id. |
| `clear(): void` | Dismiss every visible toast. |
| `runAction(item: MkToastItem): void` | Run a toast action, then dismiss it. |
| `pause(id: number): void` | Pause a toast's auto-dismiss countdown (e.g. on hover/focus). |
| `resume(id: number): void` | Resume a paused countdown. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `toasts` | `Signal<readonly MkToastItem[]>` | Reactive list of currently visible toasts. |

### MkTourService (service)

Docs: https://mk-kit.dev/components/status

Import: `import { MkTourService } from '@mk-kit/ui/feedback';`

Product-onboarding tour service — walks the user through a sequence of
`MkTourStep`s. For each step it scrolls the target into view, dims the
page behind a scrim, highlights the target with a bright ring, and anchors a
coach-mark popover (`MkTourPopup`) to it in the browser top layer via
`MkAnchoredPanel`.

```ts
const tour = inject(MkTourService);
await tour.start([
  { target: '#new-btn', title: 'Create', body: 'Start a project here.' },
  { target: '#inbox', body: 'Your notifications land here.', placement: 'left' },
]);
```

Methods:

| Signature | Description |
| --- | --- |
| `start(steps: MkTourStep[]): Promise<void>` | Begin a tour at step 0. Returns a promise that resolves when the tour ends (finished, skipped, or Escaped). |
| `afterEnd(): Promise<void>` | Resolves when the active (or next) tour ends. |
| `next(): void` | Advance to the next step, or finish on the last step. |
| `prev(): void` | Return to the previous step (no-op at the first step). |
| `end(): void` | End the tour and clean up all DOM, highlight, and listeners. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `index` | `Signal<number>` | Zero-based index of the current step, or `-1` when no tour is running. |
| `running` | `Signal<boolean>` | Whether a tour is currently active. |
| `total` | `Signal<number>` | Total number of steps in the active tour. |
| `currentStep` | `Signal<MkTourStep \| null>` | The current step, or `null`. |

### MkSnackbarRef (class)

Import: `import { MkSnackbarRef } from '@mk-kit/ui/feedback';`

Handle to an opened snackbar. Await `onAction` to react to the action
button, or `afterDismissed` to run code once it closes.

Methods:

| Signature | Description |
| --- | --- |
| `dismiss(): void` | Dismiss the snackbar programmatically. |
| `onAction(): Promise<void>` | Resolves when the action button is activated. |
| `afterDismissed(): Promise<MkSnackbarDismissReason>` | Resolves when the snackbar has closed, with the reason it closed. |

### MK_TOUR_DATA (token)

Import: `import { MK_TOUR_DATA } from '@mk-kit/ui/feedback';`

DI token carrying the current `MkTourData` to the popup.

```ts
const MK_TOUR_DATA: InjectionToken<MkTourData>;
```

### MkBottomSheetConfig (interface)

Import: `import { MkBottomSheetConfig } from '@mk-kit/ui/feedback';`

Configuration for `MkBottomSheetService.open`. Extends the overlay config.

### MkConfirmDialogData (interface)

Import: `import { MkConfirmDialogData } from '@mk-kit/ui/feedback';`

Data contract for `MkConfirmDialog` / `MkDialogService.confirm`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `title` | `string` | Heading text. |
| `message` | `string` | Body message. |
| `confirmText`? | `string \| undefined` | Confirm button label. Default `Confirm`. |
| `cancelText`? | `string \| undefined` | Cancel button label. Default `Cancel`. |
| `tone`? | `"primary" \| "success" \| "warning" \| "danger" \| undefined` | Tone of the confirm button (and `alertdialog` semantics when `danger`). |
| `icon`? | `string \| undefined` | Optional registered icon name shown beside the message. Useful when the action is destructive and the wording alone carries no visual weight (`trash`, `alert-triangle`, `user-x`). |
| `hideCancel`? | `boolean \| undefined` | Hide the cancel button — a single-button acknowledgement (`alert`). |

### MkDialogConfig (interface)

Import: `import { MkDialogConfig } from '@mk-kit/ui/feedback';`

Configuration for `MkDialogService.open`. Extends the raw overlay config.

Members (extends `MkOverlayConfig<TData>`):

| Name | Type | Description |
| --- | --- | --- |
| `size`? | `MkDialogSize \| undefined` | Panel width preset. Defaults to `sm`, matching pre-0.9 behaviour. |

### MkNotification (interface)

Import: `import { MkNotification } from '@mk-kit/ui/feedback';`

A single notification shown in the `MkNotificationCenter` panel.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `unknown` | Stable identity, used for `track` and immutable updates. |
| `title` | `string` | Headline line, always shown. |
| `body`? | `string \| undefined` | Optional supporting text under the title. |
| `time`? | `string \| undefined` | Optional relative/absolute timestamp label (e.g. "2m ago"). |
| `read`? | `boolean \| undefined` | Whether the user has already read this item. |

### MkPromptDialogData (interface)

Import: `import { MkPromptDialogData } from '@mk-kit/ui/feedback';`

Data contract for `MkPromptDialog` / `MkDialogService.prompt`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `title` | `string` | Heading text. |
| `message`? | `string \| undefined` | Optional body message shown above the input. |
| `label`? | `string \| undefined` | Field label. |
| `value`? | `string \| undefined` | Pre-filled value. |
| `placeholder`? | `string \| undefined` | Input placeholder. |
| `confirmText`? | `string \| undefined` | Confirm button label. Default `OK`. |
| `cancelText`? | `string \| undefined` | Cancel button label. Default `Cancel`. |
| `required`? | `boolean \| undefined` | Require a non-empty value before the confirm button enables. |
| `inputType`? | `string \| undefined` | Native input type (e.g. `text`, `email`, `number`, `password`). |

### MkSnackbarConfig (interface)

Import: `import { MkSnackbarConfig } from '@mk-kit/ui/feedback';`

Options for `MkSnackbarService.open`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `tone`? | `MkSnackbarTone \| undefined` | Semantic tone. Default `neutral`. |
| `duration`? | `number \| undefined` | Auto-dismiss delay in ms. `0` keeps it open until dismissed. Default `5000`. |
| `dismissible`? | `boolean \| undefined` | Show a close (×) button. Default `false` (dismiss via action/timeout). |
| `politeness`? | `"polite" \| "assertive" \| undefined` |  |

### MkSnackbarItem (interface)

Import: `import { MkSnackbarItem } from '@mk-kit/ui/feedback';`

The live snackbar model rendered by the container.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `number` |  |
| `message` | `string` |  |
| `actionLabel`? | `string \| undefined` |  |
| `tone` | `MkSnackbarTone` |  |
| `dismissible` | `boolean` |  |

### MkToastAction (interface)

Import: `import { MkToastAction } from '@mk-kit/ui/feedback';`

An optional action button rendered inside a toast.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Button label. |
| `handler`? | `(() => void) \| undefined` | Invoked when the action is activated. The toast is dismissed afterwards. |

### MkToastConfig (interface)

Import: `import { MkToastConfig } from '@mk-kit/ui/feedback';`

Options accepted by `MkToastService.show`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `title`? | `string \| undefined` | Optional bold heading. |
| `message` | `string` | Body message (required). |
| `tone`? | `MkToastTone \| undefined` | Semantic tone. Default `info`. |
| `duration`? | `number \| undefined` | Auto-dismiss delay in ms. `0` keeps the toast until dismissed. Default `5000`. |
| `dismissible`? | `boolean \| undefined` | Show a close button. Default `true`. |
| `action`? | `MkToastAction \| undefined` | Optional action button. |

### MkToastItem (interface)

Import: `import { MkToastItem } from '@mk-kit/ui/feedback';`

A live toast rendered by the container.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `number` |  |
| `title`? | `string \| undefined` |  |
| `message` | `string` |  |
| `tone` | `MkToastTone` |  |
| `duration` | `number` |  |
| `dismissible` | `boolean` |  |
| `action`? | `MkToastAction \| undefined` |  |

### MkTourController (interface)

Import: `import { MkTourController } from '@mk-kit/ui/feedback';`

Navigation callbacks the popup invokes on the owning `MkTourService`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `next` | `(): void` |  |
| `prev` | `(): void` |  |
| `end` | `(): void` |  |

### MkTourData (interface)

Import: `import { MkTourData } from '@mk-kit/ui/feedback';`

Per-step data injected into `MkTourPopup` via `MK_TOUR_DATA`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `step` | `MkTourStep` | The step being shown. |
| `index` | `number` | Zero-based index of this step. |
| `total` | `number` | Total number of steps in the tour. |
| `anchor` | `HTMLElement` | The resolved target element to anchor against. |
| `controller` | `MkTourController` | Navigation handle back to the service. |

### MkTourStep (interface)

Import: `import { MkTourStep } from '@mk-kit/ui/feedback';`

A single coach-mark step in a product tour. The `target` is the element the
step points at — either a live `HTMLElement` or a CSS selector resolved
against the document when the step is shown.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `target` | `string \| HTMLElement` | Element (or selector) the popover anchors to and highlights. |
| `title`? | `string \| undefined` | Optional heading shown above the body. |
| `body` | `string` | The explanatory copy for this step. |
| `placement`? | `MkPlacement \| undefined` | Preferred placement of the popover relative to the target. |

### MkAlertTone (type)

Import: `import { MkAlertTone } from '@mk-kit/ui/feedback';`

Semantic tones supported by `MkAlert`.

```ts
type MkAlertTone = 'info' | 'success' | 'warning' | 'danger' | 'neutral';
```

### MkAlertVariant (type)

Import: `import { MkAlertVariant } from '@mk-kit/ui/feedback';`

Visual treatments supported by `MkAlert`.

```ts
type MkAlertVariant = 'soft' | 'solid' | 'outline';
```

### MkDialogSize (type)

Import: `import { MkDialogSize } from '@mk-kit/ui/feedback';`

Panel width preset. The panel is always `min(target, 92vw)`, so it shrinks to
fit a phone and grows to its target on a desktop.

- `sm` (32rem) — the default; confirmations, single-field prompts
- `md` (45rem) — two-column forms
- `lg` (56rem) — forms with nested sections
- `xl` (75rem) — tables or side-by-side content inside a modal

```ts
type MkDialogSize = 'sm' | 'md' | 'lg' | 'xl';
```

### MkResultIconVariant (type)

Import: `import { MkResultIconVariant } from '@mk-kit/ui/feedback';`

Built-in icon glyph chosen for a status.

```ts
type MkResultIconVariant = 'check' | 'x' | 'alert' | 'info' | 'search';
```

### MkResultStatus (type)

Import: `import { MkResultStatus } from '@mk-kit/ui/feedback';`

Status presets supported by `MkResult`.

```ts
type MkResultStatus = | 'success' | 'error' | 'info' | 'warning' | '404' | '403' | '500';
```

### MkResultTone (type)

Import: `import { MkResultTone } from '@mk-kit/ui/feedback';`

Tone colour applied to the status icon.

```ts
type MkResultTone = 'success' | 'danger' | 'warning' | 'info' | 'muted';
```

### MkSnackbarDismissReason (type)

Import: `import { MkSnackbarDismissReason } from '@mk-kit/ui/feedback';`

Why a snackbar closed.

```ts
type MkSnackbarDismissReason = 'action' | 'timeout' | 'dismiss';
```

### MkSnackbarTone (type)

Import: `import { MkSnackbarTone } from '@mk-kit/ui/feedback';`

Semantic tone of a snackbar. `neutral` is the default dark bar.

```ts
type MkSnackbarTone = | 'neutral' | 'info' | 'success' | 'warning' | 'danger';
```

### MkToastTone (type)

Import: `import { MkToastTone } from '@mk-kit/ui/feedback';`

Semantic tones supported by toasts.

```ts
type MkToastTone = 'info' | 'success' | 'warning' | 'danger' | 'neutral';
```

## @mk-kit/ui/rich-text

4 exports. `import { … } from '@mk-kit/ui/rich-text';`

### MkRichText (component)

Selector: `mk-rich-text` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/rich-text

Import: `import { MkRichText } from '@mk-kit/ui/rich-text';`

Rich text — a small WYSIWYG form control over a sanitised HTML string, for
single "description"-style fields where the full block editor is overkill.
Renders a textarea-like surface with the floating inline formatting toolbar
(Bold, Italic, Underline, Strikethrough, Inline code, Link, Clear) on text
selection; Enter inserts a line break.

Implements `ControlValueAccessor` with a two-way `value` model, so it works
with `[(ngModel)]`, reactive forms and `[(value)]`. Every value — written or
emitted — passes through `sanitizeInlineHtml`, and a visually empty
surface (whitespace / lone `<br>`s) normalises to `''` so `required`
validation behaves.

```html
<mk-rich-text [(ngModel)]="description" placeholder="Describe it…" />
<mk-rich-text [(value)]="html" minHeight="8rem" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `string` | `''` | Two-way HTML string value (sanitised; `''` when visually empty). |
| `placeholder` | `string` | `''` | Placeholder shown when empty. |
| `disabled` | `boolean` | `false` | Disable the control. |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `minHeight` | `string` | `'4.5em'` | Minimum height of the editable area (any CSS length). |
| `aria-label` | `string` | `''` | Accessible label when not labelled by an `mk-form-field`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |

### MkRichTextEngine (component)

Selector: `mk-rich-text-engine`

Docs: https://mk-kit.dev/components/rich-text

Import: `import { MkRichTextEngine } from '@mk-kit/ui/rich-text';`

Rich-text engine — an accessible contenteditable surface with a floating
inline formatting toolbar (Bold, Italic, Underline, Strikethrough, Inline
code, Link, Clear). Built on the native Selection API +
`document.execCommand` (deprecated but universally supported and
dependency-free — the only practical way to do inline formatting without a
heavyweight editor engine).

This is the low-level building block: it emits HTML via `contentChange`, and
structural intents (`splitAt`, `removeEmpty`, `arrowOut`) so a block-editor
host can create, merge or navigate blocks. For a standalone form control use
`MkRichText` (`<mk-rich-text>`), which wraps this engine in a CVA over
a sanitised HTML string.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `html` | `string` | `''` | Current HTML content. |
| `placeholder` | `string` | `''` | Placeholder shown when empty. |
| `disabled` | `boolean` | `false` | Disable editing. |
| `multiline` | `boolean` | `true` | Allow soft line breaks (Shift+Enter). Plain Enter always splits. |
| `splitOnEnter` | `boolean` | `true` | Emit `splitAt` on Enter (block-editor hosts). When `false` — standalone field usage — Enter inserts a line break inside this surface instead. |
| `minHeight` | `string \| null` | `null` | Minimum height of the editable surface (any CSS length). |
| `ariaLabel` | `string` | `this.i18n.blockEditor.editableText` | Accessible label for the editable region. |
| `labelledBy` | `string \| null` | `null` | Id of an external label element, for `aria-labelledby`. |
| `describedBy` | `string \| null` | `null` | Space-separated id list for `aria-describedby`. |
| `invalid` | `boolean` | `false` | Reflect an invalid state via `aria-invalid`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `contentChange` | `string` | Fired on every edit with the sanitised-by-construction HTML. |
| `splitAt` | `MkRichTextSplit` | Enter pressed: `before` stays in this block, `after` starts a new one. |
| `removeEmpty` | `void` | Backspace at the very start of an empty block. |
| `arrowOut` | `"up" \| "down"` | Caret tried to leave the top/bottom edge with an arrow key. |
| `focusChange` | `boolean` | Focus/blur bubbled so the wrapper can show selection chrome. |

Methods:

| Signature | Description |
| --- | --- |
| `focus(position?: "start" \| "end"): void` | Places the caret and focuses (called by the host for navigation). |

### sanitizeInlineHtml (function)

Import: `import { sanitizeInlineHtml } from '@mk-kit/ui/rich-text';`

Allow-list cleaner for inline rich text. Keeps a small set of formatting
tags, strips everything else's tags (preserving their text), removes event
handler attributes and unsafe `href`s. Not a substitute for `DomSanitizer`,
but makes the serialised string safe by construction.

```ts
function sanitizeInlineHtml(html: string): string
```

### MkRichTextSplit (interface)

Import: `import { MkRichTextSplit } from '@mk-kit/ui/rich-text';`

Payload for a split (Enter) event: text before/after the caret.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `before` | `string` |  |
| `after` | `string` |  |

## @mk-kit/ui/block-editor

25 exports. `import { … } from '@mk-kit/ui/block-editor';`

### MkBlockEditor (component)

Selector: `mk-block-editor` · form control (ControlValueAccessor)

Docs: https://mk-kit.dev/components/content-editor

Import: `import { MkBlockEditor } from '@mk-kit/ui/block-editor';`

Block editor — a configurable, Gutenberg-style block content editor. Renders
an ordered document of blocks (paragraph, heading, image, columns, embed,
list, quote, button, divider, code) with a filterable inserter, per-block
chrome (move/duplicate/transform/delete) and inline rich-text formatting.

The palette is fully customisable: pass definitions via the `blocks` input or
the `MK_BLOCK_DEFINITIONS` token (mirrors `registerBlockType`). Both are
merged over `MK_DEFAULT_BLOCKS`.

Implements `ControlValueAccessor` AND a two-way `value` model, so it works
with `[(ngModel)]`, reactive forms and `[(value)]`.

```html
<mk-block-editor [(value)]="doc" [uploadHandler]="upload" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `MkBlockDocument` | `mkEmptyDocument()` | Two-way document value (always an `MkBlockDocument`, regardless of format). |
| `valueFormat` | `MkBlockValueFormat` | `'document'` | Form/CVA exchange format. `document` (default) reads/writes an `MkBlockDocument`; `html` reads/writes an **HTML string** — so the editor can back a string-typed richtext field (`[(ngModel)]="htmlString"`). The two-way `value` model stays an `MkBlockDocument` either way. |
| `blocks` | `MkBlockDefinition[] \| null` | `null` | Custom / extended block definitions (merged over the defaults + token). |
| `placeholder` | `string` | `this.i18n.blockEditor.emptyBlockPlaceholder` | Placeholder for empty text blocks. |
| `ariaLabel` | `string` | `this.i18n.blockEditor.editorLabel` | Accessible label for the editor region. |
| `readonly` | `boolean` | `false` | Read-only: renders content without editing chrome. |
| `disabled` | `boolean` | `false` | Disabled (form-level). |
| `invalid` | `boolean` | `false` | Force the invalid visual + `aria-invalid` when used standalone. |
| `uploadHandler` | `MkBlockUploadHandler \| null` | `null` | Async upload handler (overrides the `MK_BLOCK_UPLOAD_HANDLER` token). |
| `embedProviders` | `MkEmbedProvider[] \| null` | `null` | Extra embed providers (merged with defaults + token). |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `MkBlockDocument` | Emits when `value` changes (two-way binding). |
| `change` | `MkBlockDocument` | Fires on any document change (in addition to the `value` model). |
| `htmlChange` | `string` | Fires the serialised HTML on any change — convenient in `html` mode. |

### MkBlockRenderer (component)

Selector: `mk-block-renderer`

Docs: https://mk-kit.dev/components/content-editor

Import: `import { MkBlockRenderer } from '@mk-kit/ui/block-editor';`

Block renderer — read-only, themed display of a `MkBlockDocument` for
published content pages and blog posts. Reuses the same layout CSS as the
editor so authored columns look identical when published.

SECURITY MODEL: rich-text HTML is passed through `sanitizeInlineHtml`
and then bound with `[innerHTML]`, so Angular's `DomSanitizer` sanitises it
again at render time (never bypassed for author HTML). The ONLY bypass is for
a stored embed's `embedUrl`, which came from an allow-listed provider.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `MkBlockDocument \| null` | `null` | The document to render. |
| `blocks` | `MkBlock[] \| null` | `null` | Internal: a block subtree (used when recursing into columns). |

### mkBlockId (function)

Import: `import { mkBlockId } from '@mk-kit/ui/block-editor';`

Generates a reasonably unique, JSON-safe block id. Combines a monotonic
counter with a short random suffix so ids are unique even across documents
merged at runtime.

```ts
function mkBlockId(prefix?: string): string
```

### mkBlocksToHtml (function)

Docs: https://mk-kit.dev/components/content-editor

Import: `import { mkBlocksToHtml } from '@mk-kit/ui/block-editor';`

Serialises a document to clean, semantic, self-contained HTML — the "rich
HTML content" you persist and publish for a blog post or content page.
Layout blocks become responsive grid wrappers with inline styles.

```ts
function mkBlocksToHtml(doc: MkBlockDocument | null | undefined): string
```

### mkBlocksToText (function)

Import: `import { mkBlocksToText } from '@mk-kit/ui/block-editor';`

Serialises a document to plain text — handy for previews, excerpts, search
indexes and meta descriptions.

```ts
function mkBlocksToText(doc: MkBlockDocument | null | undefined): string
```

### mkCloneBlock (function)

Import: `import { mkCloneBlock } from '@mk-kit/ui/block-editor';`

Deep-clones a block (and its subtree), assigning fresh ids.

```ts
function mkCloneBlock(block: MkBlock): MkBlock
```

### mkEmptyDocument (function)

Import: `import { mkEmptyDocument } from '@mk-kit/ui/block-editor';`

An empty, valid document.

```ts
function mkEmptyDocument(): MkBlockDocument
```

### mkEscapeAttr (function)

Import: `import { mkEscapeAttr } from '@mk-kit/ui/block-editor';`

Escapes a value for safe placement in a double-quoted attribute.

```ts
function mkEscapeAttr(value: string): string
```

### mkEscapeHtml (function)

Import: `import { mkEscapeHtml } from '@mk-kit/ui/block-editor';`

Escapes text for safe placement in element content.

```ts
function mkEscapeHtml(value: string): string
```

### mkHtmlToBlocks (function)

Docs: https://mk-kit.dev/components/content-editor

Import: `import { mkHtmlToBlocks } from '@mk-kit/ui/block-editor';`

Parse an HTML string into a `MkBlockDocument`. Empty / whitespace input
yields an empty document.

```ts
function mkHtmlToBlocks(html: string): MkBlockDocument
```

### mkIsSafeUrl (function)

Import: `import { mkIsSafeUrl } from '@mk-kit/ui/block-editor';`

True for URL schemes safe to place in `href`/`src`.

```ts
function mkIsSafeUrl(url: string): boolean
```

### mkMergeBlockDefinitions (function)

Import: `import { mkMergeBlockDefinitions } from '@mk-kit/ui/block-editor';`

Merges default definitions with app-token definitions and per-editor input,
de-duplicating by `type` (later sources win).

```ts
function mkMergeBlockDefinitions(defaults: MkBlockDefinition[], ...sources: (MkBlockDefinition[] | null | undefined)[]): MkBlockDefinition[]
```

### sanitizeInlineHtml (function)

Import: `import { sanitizeInlineHtml } from '@mk-kit/ui/block-editor';`

Allow-list cleaner for inline rich text. Keeps a small set of formatting
tags, strips everything else's tags (preserving their text), removes event
handler attributes and unsafe `href`s. Not a substitute for `DomSanitizer`,
but makes the serialised string safe by construction.

```ts
function sanitizeInlineHtml(html: string): string
```

### MK_BLOCK_DEFINITIONS (token)

Docs: https://mk-kit.dev/components/content-editor

Import: `import { MK_BLOCK_DEFINITIONS } from '@mk-kit/ui/block-editor';`

Multi-provider injection token for adding block definitions app-wide. Each
provided array is merged over `MK_DEFAULT_BLOCKS` (by `type`). The
editor's `blocks` input takes final precedence.

```ts
providers: [
  { provide: MK_BLOCK_DEFINITIONS, multi: true, useValue: [myCalloutBlock] },
]
```

```ts
const MK_BLOCK_DEFINITIONS: InjectionToken<MkBlockDefinition[][]>;
```

### MK_BLOCK_EMBED_PROVIDERS (token)

Import: `import { MK_BLOCK_EMBED_PROVIDERS } from '@mk-kit/ui/block-editor';`

App-wide embed providers token (merged with the editor's input).

```ts
const MK_BLOCK_EMBED_PROVIDERS: InjectionToken<MkEmbedProvider[][]>;
```

### MK_BLOCK_UPLOAD_HANDLER (token)

Import: `import { MK_BLOCK_UPLOAD_HANDLER } from '@mk-kit/ui/block-editor';`

App-wide upload handler token (overridable by the editor's input).

```ts
const MK_BLOCK_UPLOAD_HANDLER: InjectionToken<MkBlockUploadHandler>;
```

### MK_BLOCK_DOCUMENT_VERSION (const)

Import: `import { MK_BLOCK_DOCUMENT_VERSION } from '@mk-kit/ui/block-editor';`

Current document schema version.

```ts
const MK_BLOCK_DOCUMENT_VERSION: 1;
```

### MK_DEFAULT_BLOCKS (const)

Import: `import { MK_DEFAULT_BLOCKS } from '@mk-kit/ui/block-editor';`

The default palette of built-in block definitions. Grouped for the inserter.
Consumers can spread this and append custom definitions, or replace it.

The English `label`/`group`/`description` text here is only a base: the
editor resolves the built-in types' display text from the `blockEditor`
i18n strings (see `provideMkI18n`) before merging custom definitions.

```ts
const MK_DEFAULT_BLOCKS: MkBlockDefinition[];
```

### MK_DEFAULT_EMBED_PROVIDERS (const)

Import: `import { MK_DEFAULT_EMBED_PROVIDERS } from '@mk-kit/ui/block-editor';`

Default embed providers: YouTube + Vimeo.

```ts
const MK_DEFAULT_EMBED_PROVIDERS: MkEmbedProvider[];
```

### MkBlock (interface)

Import: `import { MkBlock } from '@mk-kit/ui/block-editor';`

A single content block.

`type` keys into the `MkBlockDefinition` registry that knows how to
edit, serialise and render it. `data` is a free-form, JSON-safe bag of the
block's own state (e.g. `{ html }` for a paragraph, `{ src, alt }` for an
image). `children` enables nested layout blocks (a Columns block stores its
columns' contents here).

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable unique id (used for keying, focus and drag/move). |
| `type` | `string` | Registry type key, e.g. `paragraph`, `heading`, `columns`. |
| `data` | `Record<string, any>` | JSON-serialisable per-block state. |
| `children`? | `MkBlock[] \| undefined` | Nested blocks for layout/container blocks (e.g. columns). |

### MkBlockDefinition (interface)

Import: `import { MkBlockDefinition } from '@mk-kit/ui/block-editor';`

Describes one registerable block type — the extensibility layer of the
editor. Mirrors Gutenberg's `registerBlockType`: consumers supply an array of
these (via the `blocks` input or the `MK_BLOCK_DEFINITIONS` token) to
add, remove or reconfigure the palette. The built-in set is
`MK_DEFAULT_BLOCKS`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `type` | `string` | Unique type key that `MkBlock.type` references. |
| `label` | `string` | Human label shown in the inserter and block toolbar. |
| `icon`? | `string \| undefined` | Optional icon (emoji or short text glyph) shown in the inserter. |
| `group`? | `string \| undefined` | Inserter grouping heading, e.g. `Text`, `Media`, `Layout`. |
| `description`? | `string \| undefined` | Short description shown in the inserter. |
| `create` | `(): MkBlock` | Factory returning a fresh, ready-to-edit block of this type. |
| `allowedInColumns`? | `boolean \| undefined` | May this block be placed inside a Columns column? Default `true`. |
| `keywords`? | `string[] \| undefined` | Keywords to match against when filtering the inserter. |
| `transforms`? | `string[] \| undefined` | Block types this one can transform into (by type key). |

### MkBlockDocument (interface)

Import: `import { MkBlockDocument } from '@mk-kit/ui/block-editor';`

A full editor document: a version stamp plus an ordered list of blocks.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `version` | `number` | Schema version, bumped when the persisted shape changes. |
| `blocks` | `MkBlock[]` | Top-level blocks, in document order. |

### MkEmbedProvider (interface)

Import: `import { MkEmbedProvider } from '@mk-kit/ui/block-editor';`

An allow-listed embed provider. `test` matches a pasted URL; `toEmbedUrl`
returns the safe iframe `src` (which is the ONLY value ever passed to
`DomSanitizer.bypassSecurityTrustResourceUrl`). Non-matching URLs fall back
to a plain link card — raw HTML is never injected.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | Display name, e.g. `YouTube`. |
| `test` | `RegExp` | Matches URLs this provider handles. |
| `toEmbedUrl` | `(url: string): string \| null` | Transforms a matched page URL into an embeddable iframe `src`. |
| `aspectRatio`? | `number \| undefined` | Aspect ratio `width / height` for the responsive frame. Default 16/9. |
| `sandbox`? | `string \| undefined` | Allow list for the iframe `sandbox` attribute. |

### MkBlockUploadHandler (type)

Import: `import { MkBlockUploadHandler } from '@mk-kit/ui/block-editor';`

Async handler that persists an uploaded `File` and resolves to its URL.
Provide app-wide via this token, or per-editor via the `uploadHandler` input.
When absent, the Image block falls back to an inline `data:` URL.

```ts
type MkBlockUploadHandler = (file: File) => Promise<string>;
```

### MkBlockValueFormat (type)

Import: `import { MkBlockValueFormat } from '@mk-kit/ui/block-editor';`

How the form/CVA value is exchanged: a document object or an HTML string.

```ts
type MkBlockValueFormat = 'document' | 'html';
```

## @mk-kit/ui/context-menu

1 exports. `import { … } from '@mk-kit/ui/context-menu';`

### MkContextMenuTrigger (directive)

Selector: `[mkContextMenuTriggerFor]` · exportAs: `mkContextMenuTrigger`

Docs: https://mk-kit.dev/components/context-menu

Import: `import { MkContextMenuTrigger } from '@mk-kit/ui/context-menu';`

Turns its host element into a right-click trigger for an `<mk-menu>`, reusing
the same `MkMenu` instance as `mkMenuTriggerFor`. On `contextmenu` it
prevents the native menu and opens the menu at the pointer coordinates via
`MkMenu.openAt`, restoring focus to the host on close.

On touch devices a long-press (~500ms hold with a touch pointer) opens the
menu at the touch point — iOS Safari never fires `contextmenu`, so this is
the only way to reach a context menu on iPhones. Moving the finger beyond a
small slop, or lifting it early, cancels the press. On platforms that do
synthesize a `contextmenu` after a long-press (Android), that follow-up
event is suppressed so the menu doesn't open twice. While the directive is
attached it disables the iOS press callout and text selection on the host
(inline host styles — the directive has no stylesheet).

For keyboard users (WCAG) the dedicated <kbd>ContextMenu</kbd> key and
<kbd>Shift</kbd>+<kbd>F10</kbd> open the menu anchored to the host element;
<kbd>Escape</kbd> closes it. The host advertises `aria-haspopup="menu"`.
The menu closes on selection, Escape or an outside click (handled by
`MkMenu`).

```html
<tr [mkContextMenuTriggerFor]="rowMenu" tabindex="0">…</tr>
<mk-menu #rowMenu>
  <mk-menu-item (action)="edit()">Edit</mk-menu-item>
  <mk-menu-item danger (action)="del()">Delete</mk-menu-item>
</mk-menu>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkContextMenuTriggerFor` (required) | `MkMenu` |  | The menu instance to open on right-click / context-menu key. |

## @mk-kit/ui/layout

16 exports. `import { … } from '@mk-kit/ui/layout';`

### MkFlex (component)

Selector: `mk-flex`

Docs: https://mk-kit.dev/components/layout

Import: `import { MkFlex } from '@mk-kit/ui/layout';`

Flex — a flexbox container with its options as inputs, horizontal by default
and no gap unless asked. Reach for it when a stack's "one after another"
isn't the point: space-between toolbars, centring, wrapping tag clouds.
Children can fine-tune themselves with `mkFlexItem`.

```html
<mk-flex align="center" justify="between" gap="3">
  <h2>Orders</h2>
  <button mkButton>New order</button>
</mk-flex>
<mk-flex wrap gap="2">@for (tag of tags; track tag) { <mk-chip>{{ tag }}</mk-chip> }</mk-flex>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `gap` | `MkResponsiveSpace` | `0` | Space between children (default none). |
| `direction` | `MkResponsive<MkFlexDirection>` | `'row'` | Direction (default `row`). |

### MkGrid (component)

Selector: `mk-grid`

Docs: https://mk-kit.dev/components/layout

Import: `import { MkGrid } from '@mk-kit/ui/layout';`

Grid — a CSS grid with the common cases as inputs.

- `columns` — a count (`3` → three equal tracks) or a raw
  `grid-template-columns` string (`'240px 1fr'`); responsive maps work for
  both: `[columns]="{ xs: 1, md: 2, xl: 4 }"`.
- `minColumnWidth` — auto-responsive without breakpoints: as many
  `≥ 16rem` columns as fit (`auto-fill`; add `autoFit` to stretch the last
  row's items instead of leaving empty tracks). Wins over `columns`.
- `gap`, `rowGap`, `columnGap` — `--mk-space-*` steps or CSS lengths.

Children can span tracks with `mkGridItem`.

```html
<mk-grid [columns]="{ xs: 1, md: 2, xl: 4 }" gap="4">

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` | `MkResponsive<string \| number>` | `1` | Column count or `grid-template-columns` value; responsive allowed (default `1`). |
| `rows` | `MkResponsive<string \| number> \| null` | `null` | Row count or `grid-template-rows` value; responsive allowed. |
| `minColumnWidth` | `MkResponsive<string> \| null` | `null` | Minimum column width for an auto-filling grid, e.g. `16rem`. Overrides `columns`. |
| `autoFit` | `boolean` | `false` | With `minColumnWidth`: use `auto-fit` so items stretch when a row is short. |
| `gap` | `MkResponsiveSpace` | `4` | Gap between both rows and columns (default `4` = 16px). |
| `rowGap` | `MkResponsiveSpace \| null` | `null` | Row gap override. |
| `columnGap` | `MkResponsiveSpace \| null` | `null` | Column gap override. |
| `align` | `MkResponsive<MkAlign> \| null` | `null` | `align-items` for every cell. |
| `justify` | `MkResponsive<MkGridJustify> \| null` | `null` | `justify-items` for every cell. |
| `flow` | `"row" \| "column" \| "dense" \| "row dense" \| "column dense" \| null` | `null` | `grid-auto-flow` (e.g. `dense` to backfill holes left by spanning items). |
| `inline` | `boolean` | `false` | Render as `inline-grid`. |

### MkStack (component)

Selector: `mk-stack`

Docs: https://mk-kit.dev/components/layout

Import: `import { MkStack } from '@mk-kit/ui/layout';`

Stack — children laid out one after another with a consistent gap, vertical
by default. The everyday layout primitive: form sections, card bodies,
sidebars, a row of buttons (`direction="row"`).

```html
<mk-stack gap="4">
  <mk-input … />
  <mk-input … />
  <mk-stack direction="row" gap="2" justify="end">
    <button mkButton variant="ghost">Cancel</button>
    <button mkButton>Save</button>
  </mk-stack>
</mk-stack>

<!-- Stack on phones, side by side from md up -->
<mk-stack [direction]="{ xs: 'column', md: 'row' }" [gap]="{ xs: 3, md: 6 }">…</mk-stack>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `gap` | `MkResponsiveSpace` | `4` | Space between children (default `4` = 16px). |
| `direction` | `MkResponsive<MkFlexDirection>` | `'column'` | Direction (default `column`). |

### MkFlexBase (directive)

Import: `import { MkFlexBase } from '@mk-kit/ui/layout';`

Shared inputs and host style bindings of `mk-stack` and `mk-flex`.
Responsive inputs re-resolve when the viewport crosses a breakpoint.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `MkResponsive<MkAlign> \| null` | `null` | Cross-axis alignment of children. |
| `justify` | `MkResponsive<MkJustify> \| null` | `null` | Main-axis distribution of children. |
| `wrap` | `boolean` | `false` | Let children wrap onto new lines. |
| `inline` | `boolean` | `false` | Render as `inline-flex` (sits in a line of text) instead of a block. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `gap` | `InputSignal<MkResponsiveSpace>` | Space between children — a `--mk-space-*` step, a CSS length, or a per-breakpoint map. |
| `direction` | `InputSignal<MkResponsive<MkFlexDirection>>` | Main-axis direction; may be responsive, e.g. `{ xs: 'column', md: 'row' }`. |

### MkFlexItem (directive)

Selector: `[mkFlexItem]`

Import: `import { MkFlexItem } from '@mk-kit/ui/layout';`

Per-child flex options inside `mk-flex` / `mk-stack` (or any flex parent).

```html
<mk-flex gap="3">
  <mk-input mkFlexItem grow />      <!-- takes the remaining width -->
  <button mkButton>Search</button>
</mk-flex>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `grow` | `number \| null` | `null` | `flex-grow`; a bare `grow` attribute means `1`. |
| `shrink` | `number \| null` | `null` | `flex-shrink`; a bare `shrink` attribute means `1`, `[shrink]="0"` pins the size. |
| `basis` | `MkResponsive<string> \| null` | `null` | `flex-basis` — any CSS length or `auto`; may be responsive. |
| `alignSelf` | `MkResponsive<MkAlign> \| null` | `null` | Override the parent's `align` for this child. |
| `order` | `MkResponsive<string \| number> \| null` | `null` | Visual order; may be responsive (e.g. move a sidebar first on phones). |

### MkGridItem (directive)

Selector: `[mkGridItem]`

Import: `import { MkGridItem } from '@mk-kit/ui/layout';`

Per-cell placement inside `mk-grid`: span several tracks, or pin a start
line. All inputs accept responsive maps, so a hero card can span the full
row on phones and two of four columns on desktop.

```html
<mk-grid [columns]="{ xs: 1, lg: 4 }" gap="4">
  <mk-card mkGridItem [colSpan]="{ xs: 1, lg: 2 }">Revenue</mk-card>
  …
</mk-grid>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `colSpan` | `MkResponsive<string \| number> \| null` | `null` | Number of columns to span (`'all'` = the full row). |
| `rowSpan` | `MkResponsive<string \| number> \| null` | `null` | Number of rows to span. |
| `colStart` | `MkResponsive<string \| number> \| null` | `null` | Column line to start at (1-based). |
| `rowStart` | `MkResponsive<string \| number> \| null` | `null` | Row line to start at (1-based). |
| `alignSelf` | `MkResponsive<"start" \| "end" \| "center" \| "stretch"> \| null` | `null` | `align-self` for this cell. |
| `justifySelf` | `MkResponsive<"start" \| "end" \| "center" \| "stretch"> \| null` | `null` | `justify-self` for this cell. |

### mkAlignToCss (function)

Import: `import { mkAlignToCss } from '@mk-kit/ui/layout';`

`align-items` / `align-self` value for a `MkAlign` keyword (`null` when unset).

```ts
function mkAlignToCss(value: MkAlign | null | undefined): string | null
```

### mkJustifyToCss (function)

Import: `import { mkJustifyToCss } from '@mk-kit/ui/layout';`

`justify-content` value for a `MkJustify` keyword (`null` when unset).

```ts
function mkJustifyToCss(value: MkJustify | null | undefined): string | null
```

### mkNumeric (function)

Import: `import { mkNumeric } from '@mk-kit/ui/layout';`

A number, or a numeric string as it arrives from a plain attribute
(`gap="4"`, `colSpan="2"`), as a number; anything else unchanged.

```ts
function mkNumeric<T>(value: T): T | number
```

### mkSpaceToCss (function)

Import: `import { mkSpaceToCss } from '@mk-kit/ui/layout';`

Translate a `MkSpace` into CSS (`null` when unset).

```ts
function mkSpaceToCss(value: MkSpace | null | undefined): string | null
```

### MkAlign (type)

Import: `import { MkAlign } from '@mk-kit/ui/layout';`

Cross-axis alignment keywords.

```ts
type MkAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
```

### MkFlexDirection (type)

Import: `import { MkFlexDirection } from '@mk-kit/ui/layout';`

Flex direction keywords.

```ts
type MkFlexDirection = 'row' | 'column' | 'row-reverse' | 'column-reverse';
```

### MkGridJustify (type)

Import: `import { MkGridJustify } from '@mk-kit/ui/layout';`

`justify-items` keywords.

```ts
type MkGridJustify = 'start' | 'center' | 'end' | 'stretch';
```

### MkJustify (type)

Import: `import { MkJustify } from '@mk-kit/ui/layout';`

Flex / grid main-axis distribution keywords, in plain words.

```ts
type MkJustify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | 'stretch';
```

### MkResponsiveSpace (type)

Import: `import { MkResponsiveSpace } from '@mk-kit/ui/layout';`

Per-breakpoint spacing, e.g. `{ xs: 2, md: 4 }`.

```ts
type MkResponsiveSpace = MkResponsive<MkSpace>;
```

### MkSpace (type)

Import: `import { MkSpace } from '@mk-kit/ui/layout';`

A spacing value: a step on the `--mk-space-*` scale (`0 1 2 3 4 5 6 8 10 12
16`, so `4` = `var(--mk-space-4)` = 16px and follows the density modes) or
any CSS length such as `'1.5rem'` / `'clamp(1rem, 2vw, 2rem)'`.

```ts
type MkSpace = number | string;
```

## @mk-kit/ui/chat

12 exports. `import { … } from '@mk-kit/ui/chat';`

### MkChat (component)

Selector: `mk-chat`

Docs: https://mk-kit.dev/components/chat

Import: `import { MkChat } from '@mk-kit/ui/chat';`

Chat — a conversation: a scrolling, screen-reader-announced log of
`mk-chat-message` bubbles that stays pinned to the newest message while
text streams in (with a *jump to latest* button once the reader scrolls
up), a typing indicator, and an `mk-prompt-box` composer.

The component is presentational: hand it `messages` (replace the array or
a message object to update — signals compare by reference) and react to
`(send)` / `(stop)` / `(retry)` with your own transport.

```html
<mk-chat
  [messages]="messages()"
  [busy]="generating()"
  [typing]="peerTyping()"
  attachments
  [suggestions]="starters"
  (send)="ask($event)"
  (stop)="abort()"
  (retry)="resend($event)"
  style="height: 32rem"
>
  <div mkChatHeader>…title, model picker…</div>
  <div mkChatEmpty>…first-run hint…</div>
</mk-chat>
```

Slots: `[mkChatHeader]`, `[mkChatEmpty]`, `[mkChatFooter]` (under the composer).

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `messages` | `readonly MkChatMessage[]` | `[]` | The conversation, oldest first. |
| `ownRole` | `MkChatRole` | `'user'` | Which role renders on the "own" side (default `user`). |
| `markdown` | `boolean` | `true` | Render assistant text as Markdown. |
| `showAvatars` | `boolean` | `true` |  |
| `showTimestamps` | `boolean` | `true` |  |
| `typing` | `boolean` | `false` | Someone else is typing (shows the dots indicator). |
| `busy` | `boolean` | `false` | A reply is being generated: composer shows *stop*. |
| `disabled` | `boolean` | `false` | Disable the composer. |
| `readonly` | `boolean` | `false` | Hide the composer entirely (read-only transcript). |
| `placeholder` | `string \| undefined` | `undefined` |  |
| `attachments` | `boolean` | `false` | Allow attachments in the composer. |
| `accept` | `string` | `''` |  |
| `maxFiles` | `number` | `0` |  |
| `maxLength` | `number` | `0` |  |
| `suggestions` | `readonly string[]` | `[]` | Quick replies above the composer; each click sends its text. |
| `emptyMessage` | `string \| undefined` | `undefined` | Text shown when there are no messages (or project `[mkChatEmpty]`). |
| `autoScroll` | `boolean` | `true` | Keep the log pinned to the newest message while the reader is at the bottom. |
| `ariaLabel` | `string \| undefined` | `undefined` | Accessible name of the log region. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `send` | `MkChatSend` |  |
| `stop` | `void` |  |
| `retry` | `MkChatMessage` |  |

Methods:

| Signature | Description |
| --- | --- |
| `scrollToBottom(): void` | Scroll the log to the newest message. |
| `focus(): void` | Focus the composer. |

### MkChatMessageComponent (component)

Selector: `mk-chat-message`

Docs: https://mk-kit.dev/components/chat

Import: `import { MkChatMessageComponent } from '@mk-kit/ui/chat';`

ChatMessage — one bubble: avatar, author and time, attachment previews,
tool-call cards, the text (Markdown for assistants) with a streaming
cursor, and copy / retry actions. `mk-chat` renders these for you; use it
directly to build your own list.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `message` (required) | `MkChatMessage` |  | The message to render. |
| `own` | `boolean` | `false` | Render on the "own" (end) side — `mk-chat` sets this from `ownRole`. |
| `markdown` | `boolean` | `true` | Render `text` as Markdown (assistants only; user text is always plain). |
| `showAvatar` | `boolean` | `true` |  |
| `showTimestamp` | `boolean` | `true` |  |
| `copyable` | `boolean` | `true` | Offer a copy button on hover / focus. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `retry` | `MkChatMessage` | The retry button of a failed message was pressed. |

### MkPromptBox (component)

Selector: `mk-prompt-box`

Docs: https://mk-kit.dev/components/chat

Import: `import { MkPromptBox } from '@mk-kit/ui/chat';`

PromptBox — the composer of a chat: an auto-growing textarea, attachments
(button, drop, paste), quick-reply suggestions and a send button that turns
into *stop* while a reply is being generated.

Enter sends, Shift+Enter breaks the line (`sendOnEnter="false"` to swap).

```html
<mk-prompt-box
  [(value)]="draft"
  [busy]="generating()"
  attachments
  [suggestions]="['Summarise this page', 'Draft a reply']"
  (send)="ask($event)"
  (stop)="abort()"
/>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (two-way) | `string` | `''` | The draft text (two-way). |
| `placeholder` | `string` | `this.i18n.chatPlaceholder` | Placeholder of the textarea. |
| `disabled` | `boolean` | `false` | Disable everything (e.g. while offline). |
| `busy` | `boolean` | `false` | A reply is being generated: the send button becomes *stop*, sending is paused. |
| `attachments` | `boolean` | `false` | Allow attaching files (button, drag & drop, paste). |
| `accept` | `string` | `''` | Accepted file types for the picker (`accept` attribute syntax). |
| `maxFiles` | `number` | `0` | Maximum number of attached files (0 = unlimited). |
| `maxLength` | `number` | `0` | Maximum draft length; shows a counter when set. |
| `rows` | `number` | `1` | Minimum visible rows. |
| `maxRows` | `number` | `8` | Rows the textarea grows to before scrolling. |
| `sendOnEnter` | `boolean` | `true` | Enter sends and Shift+Enter breaks the line (default); `false` swaps them. |
| `suggestions` | `readonly string[]` | `[]` | Quick replies shown above the box; clicking one sends it. |
| `autofocus` | `boolean` | `false` | Focus the textarea on render. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `string` | Emits when `value` changes (two-way binding). |
| `send` | `MkChatSend` | The user submitted the draft (and any files). |
| `stop` | `void` | The user pressed *stop* while `busy`. |

Methods:

| Signature | Description |
| --- | --- |
| `focus(): void` | Focus the textarea. |
| `clear(): void` | Empty the draft and the attachment list. |
| `submit(): void` | Submit the current draft (no-op when there is nothing to send or while busy). |
| `addFiles(list: ArrayLike<File> \| null \| undefined): void` | Add files, honouring `maxFiles` and `accept`. |
| `removeFile(index: number): void` |  |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `files` | `WritableSignal<File[]>` | Files waiting to be sent. |

### MkChatMessageDef (directive)

Selector: `ng-template[mkChatMessageDef]`

Import: `import { MkChatMessageDef } from '@mk-kit/ui/chat';`

Custom message rendering for `mk-chat`:

```html
<mk-chat [messages]="messages()">
  <ng-template mkChatMessageDef let-message let-own="own">
    <my-bubble [message]="message" [mine]="own" />
  </ng-template>
</mk-chat>
```

### MkChatAttachment (interface)

Import: `import { MkChatAttachment } from '@mk-kit/ui/chat';`

A file shown with a message (an image when `type` is `image/*` and `url` is set).

Members:

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` |  |
| `type`? | `string \| undefined` | MIME type, e.g. `image/png`. |
| `size`? | `number \| undefined` | Size in bytes, shown formatted. |
| `url`? | `string \| undefined` | Link / image source. |

### MkChatAuthor (interface)

Import: `import { MkChatAuthor } from '@mk-kit/ui/chat';`

Display identity of a message author.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | Shown beside the message and used for avatar initials. |
| `avatar`? | `string \| undefined` | Avatar image URL; initials from `name` when omitted. |

### MkChatMessage (interface)

Import: `import { MkChatMessage } from '@mk-kit/ui/chat';`

One message in the conversation. Replace the object (new reference) to update it.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `role` | `MkChatRole` |  |
| `text` | `string` | Message body — Markdown for assistants (when `markdown` is on), plain text otherwise. |
| `author`? | `MkChatAuthor \| undefined` |  |
| `timestamp`? | `string \| number \| Date \| undefined` | When it was sent; a `Date`, ISO string or epoch ms. |
| `streaming`? | `boolean \| undefined` | Still receiving text: shows a cursor and keeps the log pinned to the bottom. |
| `error`? | `string \| undefined` | Delivery / generation failed; shown under the bubble with a retry button. |
| `attachments`? | `MkChatAttachment[] \| undefined` |  |
| `tools`? | `MkChatToolCall[] \| undefined` |  |

### MkChatMessageContext (interface)

Import: `import { MkChatMessageContext } from '@mk-kit/ui/chat';`

Context handed to an `*mkChatMessageDef` template.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `$implicit` | `MkChatMessage` |  |
| `own` | `boolean` |  |
| `index` | `number` |  |

### MkChatSend (interface)

Import: `import { MkChatSend } from '@mk-kit/ui/chat';`

Payload of the `send` output.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `text` | `string` |  |
| `files` | `File[]` |  |

### MkChatToolCall (interface)

Import: `import { MkChatToolCall } from '@mk-kit/ui/chat';`

A tool call card rendered above the message text.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id`? | `string \| undefined` |  |
| `name` | `string` | Tool name, e.g. `search_orders`. |
| `status` | `MkChatToolStatus` |  |
| `summary`? | `string \| undefined` | One-line human summary, e.g. `3 orders found`. |
| `input`? | `string \| undefined` | Raw input, shown under the disclosure. |
| `output`? | `string \| undefined` | Raw output, shown under the disclosure. |

### MkChatRole (type)

Import: `import { MkChatRole } from '@mk-kit/ui/chat';`

Who a message comes from. `system` renders as a centred note.

```ts
type MkChatRole = 'user' | 'assistant' | 'system';
```

### MkChatToolStatus (type)

Import: `import { MkChatToolStatus } from '@mk-kit/ui/chat';`

Lifecycle of a tool / function call an assistant made while answering.

```ts
type MkChatToolStatus = 'running' | 'done' | 'error';
```

## @mk-kit/ui/query-builder

2 exports. `import { … } from '@mk-kit/ui/query-builder';`

### MkQueryBuilder (component)

Selector: `mk-query-builder`

Docs: https://mk-kit.dev/components/query-builder

Import: `import { MkQueryBuilder } from '@mk-kit/ui/query-builder';`

QueryBuilder — a rule / group tree the user assembles from your `fields`,
held as plain JSON (`MkQueryGroup`) in the two-way `query` model. Pair it
with `mkQueryToPredicate()` to filter rows in the browser, with
`MkTableDataSource.setQuery()` to send it to the server, or with
`mkQueryToText()` for a readable summary.

```html
<mk-query-builder [fields]="fields" [(query)]="query" allowNot />

fields: MkQueryField[] = [
  { key: 'name', label: 'Name' },
  { key: 'orders', label: 'Orders', type: 'number' },
  { key: 'status', label: 'Status', type: 'select', options: [{ label: 'Active', value: 'active' }, …] },
  { key: 'since', label: 'Customer since', type: 'date' },
  { key: 'vip', label: 'VIP', type: 'boolean' },
];
rows = computed(() => this.all.filter(mkQueryToPredicate(this.query(), this.fields)));
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fields` (required) | `readonly MkQueryField[]` |  | The filterable fields, in picker order. |
| `query` (two-way) | `MkQueryGroup` | `mkCreateQueryGroup()` | The query tree (two-way). Starts as an empty `and` group. |
| `maxDepth` | `number` | `3` | How deep groups may nest (0 = rules only). |
| `allowNot` | `boolean` | `false` | Offer a *Not* toggle on every group. |
| `disabled` | `boolean` | `false` |  |
| `size` | `MkSize` | `'sm'` | Control size (default `sm`). |
| `ariaLabel` | `string \| undefined` | `undefined` |  |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `queryChange` | `MkQueryGroup` | Emits when `query` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `clear(): void` | Reset to an empty group. |

### MkQueryGroupComponent (component)

Selector: `mk-query-group`

Import: `import { MkQueryGroupComponent } from '@mk-kit/ui/query-builder';`

One group of the builder — its combinator toggle, rules, nested groups and
the add / remove actions. Used by `mk-query-builder`; every edit emits a
new immutable group upward.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `group` (required) | `MkQueryGroup` |  |  |
| `fields` (required) | `readonly MkQueryField[]` |  |  |
| `depth` | `number` | `0` |  |
| `maxDepth` | `number` | `3` |  |
| `allowNot` | `boolean` | `false` |  |
| `disabled` | `boolean` | `false` |  |
| `root` | `boolean` | `false` |  |
| `size` | `MkSize` | `'sm'` |  |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `groupChange` | `MkQueryGroup` | A new version of this group after an edit. |
| `remove` | `void` | The user removed this (non-root) group. |

## @mk-kit/ui/dynamic-form

29 exports. `import { … } from '@mk-kit/ui/dynamic-form';`

### MkDynamicFields (component)

Selector: `mk-dynamic-fields`

Import: `import { MkDynamicFields } from '@mk-kit/ui/dynamic-form';`

Renders one field list (the root, a group, or one array item) as a grid.
Internal — projected by `MkDynamicForm`; recursive for groups/arrays.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fields` (required) | `readonly MkDynamicField[]` |  |  |
| `group` (required) | `FormGroup<any>` |  |  |
| `columns` | `number` | `1` |  |
| `scope` (required) | `Record<string, unknown>` |  | Value the conditions of this level are evaluated against. |

### MkDynamicForm (component)

Selector: `mk-dynamic-form`

Docs: https://mk-kit.dev/components/dynamic-form

Import: `import { MkDynamicForm } from '@mk-kit/ui/dynamic-form';`

Dynamic form — renders a form from a JSON schema and manages one reactive
`FormGroup` for it. Every value field renders inside `mk-form-field`, so
labels, hints, required marks and localised validation messages come from
the schema alone.

```html
<mk-dynamic-form [schema]="schema" [(value)]="user" (formSubmit)="save($event)">
  <button mkButton type="submit">Save</button>
</mk-dynamic-form>
```

```ts
schema: MkDynamicSchema = {
  columns: 2,
  fields: [
    { key: 'name', type: 'text', label: 'Name', required: true },
    { key: 'role', type: 'select', label: 'Role', options: roles },
    { key: 'company', type: 'text', label: 'Company', showWhen: { field: 'role', eq: 'b2b' } },
  ],
};
```

- Hidden fields (`showWhen` false) are disabled, so `value` only carries
  what the user can see; `form.getRawValue()` has everything.
- `form` is the live `FormGroup` for anything the schema does not cover.
- Custom field types: project an `ng-template[mkDynamicField]`.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `schema` (required) | `MkDynamicSchema` |  | The schema. Changing it rebuilds the form (values of surviving keys are kept). |
| `value` (two-way) | `Record<string, unknown>` | `{}` | Two-way form value (visible, enabled fields only). |
| `disabled` | `boolean` | `false` | Disable every control. |
| `labelPosition` | `"top" \| "float"` | `'top'` | Label placement forwarded to every `mk-form-field`. |
| `size` | `"sm" \| "md" \| "lg"` | `'md'` | Control size forwarded to the fields. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `valueChange` | `Record<string, unknown>` | Emits when `value` changes (two-way binding). |
| `formSubmit` | `Record<string, unknown>` | Emits the value when the form is submitted and valid. |
| `invalidSubmit` | `FormGroup<any>` | Emits when a submit is attempted while invalid (every control is marked touched). |

Methods:

| Signature | Description |
| --- | --- |
| `patch(value: Record<string, unknown>): void` | Patch part of the value. |
| `reset(value?: Record<string, unknown>): void` | Reset to the schema defaults (or the given value). |
| `touchAll(): void` | Mark every control touched so validation messages show. |

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `form` | `FormGroup<any>` | The live reactive form. |
| `valid` | `Signal<boolean>` | `true` while every control passes validation. |

### MkDynamicFieldDef (directive)

Selector: `ng-template[mkDynamicField]`

Import: `import { MkDynamicFieldDef } from '@mk-kit/ui/dynamic-form';`

Registers a renderer for a custom field type:

```html
<mk-dynamic-form [schema]="schema">
  <ng-template mkDynamicField="signature" let-field let-control="control">
    <mk-signature-pad [formControl]="control" />
  </ng-template>
</mk-dynamic-form>
```

A field `{ type: 'custom', key: 'sig', props: { renderer: 'signature' } }`
(or any built-in `type` you want to override) then renders this template
inside the usual `mk-form-field`.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `mkDynamicField` (required) | `string` |  | The type (or `props.renderer` name) this template renders. |

### mkDynamicCondition (function)

Import: `import { mkDynamicCondition } from '@mk-kit/ui/dynamic-form';`

Evaluate a condition against a form value. `value` is normally the whole
form value; inside an array item the item's own value is used, with the
root available under `$root`.

```ts
function mkDynamicCondition(cond: MkDynamicCondition | undefined, value: Record<string, unknown>): boolean
```

### mkDynamicControl (function)

Import: `import { mkDynamicControl } from '@mk-kit/ui/dynamic-form';`

Build the `FormControl` / `FormGroup` / `FormArray` for one field.

```ts
function mkDynamicControl(field: MkDynamicField, value?: unknown): AbstractControl
```

### mkDynamicDefaults (function)

Import: `import { mkDynamicDefaults } from '@mk-kit/ui/dynamic-form';`

Default value object of a field list (groups nested, arrays as item lists).

```ts
function mkDynamicDefaults(fields: readonly MkDynamicField[]): Record<string, unknown>
```

### mkDynamicEmptyValue (function)

Import: `import { mkDynamicEmptyValue } from '@mk-kit/ui/dynamic-form';`

The empty value a field type starts with when no `default` is given.

```ts
function mkDynamicEmptyValue(field: MkDynamicFieldBase): unknown
```

### mkDynamicFlatten (function)

Import: `import { mkDynamicFlatten } from '@mk-kit/ui/dynamic-form';`

Depth-first list of every value field with its dotted path.

```ts
function mkDynamicFlatten(fields: readonly MkDynamicField[], prefix?: string): Array<{ path: string; field: MkDynamicFieldBase | MkDynamicGroup | MkDynamicArray; }>
```

### mkDynamicForm (function)

Import: `import { mkDynamicForm } from '@mk-kit/ui/dynamic-form';`

Build the reactive form of a whole schema.

```ts
function mkDynamicForm(schema: MkDynamicSchema, value?: Record<string, unknown>): FormGroup
```

### mkDynamicFormToSignalSchema (function)

Docs: https://mk-kit.dev/components/signal-forms

Import: `import { mkDynamicFormToSignalSchema } from '@mk-kit/ui/dynamic-form';`

Converts an `mk-dynamic-form` schema into a Signal Forms `Schema`, so the
same JSON definition can drive `form()` from `@angular/forms/signals`:

```ts
const definition: MkDynamicSchema = { fields: [ … ] };
const model = signal(mkDynamicDefaults(definition.fields));
const f = form(model, mkDynamicFormToSignalSchema(definition));
```

What maps:
- `required` → `required()` (for `checkbox` / `switch` this means "must be
  on", as Signal Forms treats `false` as empty — the `requiredTrue`
  behaviour of the renderer);
- `validators.min` / `max` / `minLength` / `maxLength` / `pattern` / `email`
  (and `type: 'email'`) → the matching built-in rules, so the field's
  `min()` / `maxLength()` / `pattern()` state is set as well;
- `validators.custom` → `validate()` running each `ValidatorFn` against a
  throw-away `FormControl` holding the field's value; the reactive error
  keys become error `kind`s with their payload attached, so
  `mk-form-field` renders them through the same i18n table;
- `disabled: true` and `disabledWhen` → `disabled()`, `showWhen` →
  `hidden()` — the condition is evaluated against the form value exactly as
  the renderer does it (dotted paths, `and` / `or` / `not`, and inside an
  array item the item's own value with the root under `$root` and the
  position under `$index`);
- `group` → the nested fields under the group's key, `array` → `applyEach`
  over the items plus `minItems` / `maxItems` errors from `min` / `max`.

What differs from the renderer: a hidden Signal Forms field is skipped for
validation and touched / dirty state but **keeps its value in the model**
(the model is your data — nothing is stripped), so remove hidden controls
from the template with `@if (!f.company().hidden())` and drop the value
yourself before saving if it must not be sent. Layout properties (`span`,
`columns`), `options`, `props` and `section` entries have no schema
equivalent and are ignored.

```ts
function mkDynamicFormToSignalSchema<TModel extends object = Record<string, unknown>>(definition: MkDynamicSchema | readonly MkDynamicField[]): Schema<TModel>
```

### mkDynamicGroup (function)

Import: `import { mkDynamicGroup } from '@mk-kit/ui/dynamic-form';`

A `FormGroup` for a field list; `value` (partial) overrides the defaults.

```ts
function mkDynamicGroup(fields: readonly MkDynamicField[], value?: Record<string, unknown>): FormGroup
```

### mkDynamicSpan (function)

Import: `import { mkDynamicSpan } from '@mk-kit/ui/dynamic-form';`

Column span a field takes in a grid of `columns`.

```ts
function mkDynamicSpan(field: MkDynamicField, columns: number): number
```

### mkDynamicValidators (function)

Import: `import { mkDynamicValidators } from '@mk-kit/ui/dynamic-form';`

Angular validators for one value field, from its declarative `validators` + `required`.

```ts
function mkDynamicValidators(field: MkDynamicFieldBase): ValidatorFn[]
```

### mkIsArray (function)

Import: `import { mkIsArray } from '@mk-kit/ui/dynamic-form';`

```ts
function mkIsArray(f: MkDynamicField): f is MkDynamicArray
```

### mkIsGroup (function)

Import: `import { mkIsGroup } from '@mk-kit/ui/dynamic-form';`

```ts
function mkIsGroup(f: MkDynamicField): f is MkDynamicGroup
```

### mkIsSection (function)

Import: `import { mkIsSection } from '@mk-kit/ui/dynamic-form';`

```ts
function mkIsSection(f: MkDynamicField): f is MkDynamicSection
```

### mkIsValueField (function)

Import: `import { mkIsValueField } from '@mk-kit/ui/dynamic-form';`

```ts
function mkIsValueField(f: MkDynamicField): f is MkDynamicFieldBase
```

### MkDynamicArray (interface)

Import: `import { MkDynamicArray } from '@mk-kit/ui/dynamic-form';`

A list of objects: a `FormArray` of groups with add / remove controls.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `type` | `"array"` |  |
| `key` | `string` |  |
| `label`? | `string \| undefined` |  |
| `hint`? | `string \| undefined` |  |
| `fields` | `MkDynamicField[]` | Fields of one item. |
| `min`? | `number \| undefined` |  |
| `max`? | `number \| undefined` |  |
| `addLabel`? | `string \| undefined` |  |
| `default`? | `Record<string, unknown>[] \| undefined` | Initial items (each is patched over the item defaults). |
| `span`? | `number \| undefined` |  |
| `columns`? | `number \| undefined` |  |
| `showWhen`? | `MkDynamicCondition \| undefined` |  |
| `disabledWhen`? | `MkDynamicCondition \| undefined` |  |

### MkDynamicFieldBase (interface)

Import: `import { MkDynamicFieldBase } from '@mk-kit/ui/dynamic-form';`

Properties shared by every field that holds a value.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `string` | Key in the form value. |
| `type` | `MkDynamicFieldType` |  |
| `label`? | `string \| undefined` |  |
| `hint`? | `string \| undefined` |  |
| `placeholder`? | `string \| undefined` |  |
| `required`? | `boolean \| undefined` |  |
| `disabled`? | `boolean \| undefined` |  |
| `default`? | `unknown` | Initial value when the form (or a new array item) is created. |
| `validators`? | `MkDynamicValidators \| undefined` |  |
| `options`? | `readonly MkDynamicOption[] \| undefined` | Options for select / multi-select / radio / toggle / autocomplete. |
| `props`? | `Record<string, unknown> \| undefined` | Extra inputs forwarded to the underlying control — the subset each type understands (`rows`, `min`, `max`, `step`, `currency`, `accept`, `multiple`, `swatches`, `language`, …). See the docs table. |
| `span`? | `number \| undefined` | Grid columns (1–12) the field spans. Default: the form's `columns` split. |
| `showWhen`? | `MkDynamicCondition \| undefined` | Render (and enable) only when the condition holds. Hidden fields are excluded from the value. |
| `disabledWhen`? | `MkDynamicCondition \| undefined` | Disable while the condition holds. |

### MkDynamicFieldContext (interface)

Import: `import { MkDynamicFieldContext } from '@mk-kit/ui/dynamic-form';`

Context handed to a custom field template.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `$implicit` | `MkDynamicFieldBase` |  |
| `field` | `MkDynamicFieldBase` |  |
| `control` | `FormControl<any>` | The field's `FormControl` — bind it with `[formControl]`. |
| `value` | `Record<string, unknown>` | The current value of the whole form (or array item). |

### MkDynamicGroup (interface)

Import: `import { MkDynamicGroup } from '@mk-kit/ui/dynamic-form';`

A nested object: its fields become a child `FormGroup` under `key`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `type` | `"group"` |  |
| `key` | `string` |  |
| `label`? | `string \| undefined` |  |
| `hint`? | `string \| undefined` |  |
| `fields` | `MkDynamicField[]` |  |
| `span`? | `number \| undefined` |  |
| `columns`? | `number \| undefined` | Columns for the group's own grid (default: inherits the form's). |
| `showWhen`? | `MkDynamicCondition \| undefined` |  |
| `disabledWhen`? | `MkDynamicCondition \| undefined` |  |

### MkDynamicGroupField (interface)

Import: `import { MkDynamicGroupField } from '@mk-kit/ui/dynamic-form';`

A nested object: its fields become a child `FormGroup` under `key`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `type` | `"group"` |  |
| `key` | `string` |  |
| `label`? | `string \| undefined` |  |
| `hint`? | `string \| undefined` |  |
| `fields` | `MkDynamicField[]` |  |
| `span`? | `number \| undefined` |  |
| `columns`? | `number \| undefined` | Columns for the group's own grid (default: inherits the form's). |
| `showWhen`? | `MkDynamicCondition \| undefined` |  |
| `disabledWhen`? | `MkDynamicCondition \| undefined` |  |

### MkDynamicOption (interface)

Import: `import { MkDynamicOption } from '@mk-kit/ui/dynamic-form';`

One option of a select / radio / toggle / autocomplete field.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` |  |
| `value` | `unknown` |  |
| `disabled`? | `boolean \| undefined` |  |

### MkDynamicSchema (interface)

Import: `import { MkDynamicSchema } from '@mk-kit/ui/dynamic-form';`

The whole form.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `fields` | `MkDynamicField[]` |  |
| `columns`? | `number \| undefined` | Default number of columns fields are laid out in (1–12). Default 1. |

### MkDynamicSection (interface)

Import: `import { MkDynamicSection } from '@mk-kit/ui/dynamic-form';`

A heading + description with no value of its own.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `type` | `"section"` |  |
| `label` | `string` |  |
| `hint`? | `string \| undefined` |  |
| `span`? | `number \| undefined` |  |
| `showWhen`? | `MkDynamicCondition \| undefined` |  |

### MkDynamicValidators (interface)

Import: `import { MkDynamicValidators } from '@mk-kit/ui/dynamic-form';`

Declarative validators — plain data so a schema can be stored as JSON.
`custom` takes Angular validator functions for anything else.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `min`? | `number \| undefined` |  |
| `max`? | `number \| undefined` |  |
| `minLength`? | `number \| undefined` |  |
| `maxLength`? | `number \| undefined` |  |
| `pattern`? | `string \| RegExp \| undefined` | A RegExp or its source string. |
| `email`? | `boolean \| undefined` |  |
| `custom`? | `ValidatorFn[] \| undefined` | Angular validator functions appended after the declarative ones. |

### MkDynamicCondition (type)

Import: `import { MkDynamicCondition } from '@mk-kit/ui/dynamic-form';`

A serialisable condition over the form value (dotted paths reach into
groups: `address.country`). Combine with `and` / `or`; a function is the
escape hatch for TypeScript-only schemas.

```ts
type MkDynamicCondition = | { field: string; eq?: unknown; neq?: unknown; in?: unknown[]; notIn?: unknown[]; truthy?: boolean; empty?: boolean } | { and: MkDynamicCondition[] } | { or: MkDynamicCondition[] } | { not: MkDynamicCondition } | ((value: Record<string, unknown>) => boolean);
```

### MkDynamicField (type)

Import: `import { MkDynamicField } from '@mk-kit/ui/dynamic-form';`

```ts
type MkDynamicField = MkDynamicFieldBase | MkDynamicGroup | MkDynamicArray | MkDynamicSection;
```

### MkDynamicFieldType (type)

Import: `import { MkDynamicFieldType } from '@mk-kit/ui/dynamic-form';`

Field kinds `mk-dynamic-form` renders out of the box. Each maps to one
mk-kit control; `custom` renders a projected `mkDynamicField` template.

```ts
type MkDynamicFieldType = | 'text' | 'email' | 'password' | 'url' | 'tel' | 'search' | 'textarea' | 'number' | 'currency' | 'date' | 'time' | 'datetime' | 'select' | 'multi-select' | 'autocomplete' | 'radio' | 'toggle' | 'checkbox' | 'switch' | 'slider' | 'rating' | 'color' | 'tags' | 'phone' | 'file' | 'code' | 'custom';
```

## @mk-kit/ui/media

20 exports. `import { … } from '@mk-kit/ui/media';`

### MkImage (component)

Selector: `mk-image` · exportAs: `mkImage`

Docs: https://mk-kit.dev/components/images

Import: `import { MkImage } from '@mk-kit/ui/media';`

Image — an enhanced image block. While the picture loads it shows a skeleton
shimmer, and when loading fails it swaps to a localised fallback panel
(icon + text, never colour alone). The picture is wrapped in a `<figure>`
with an optional `<figcaption>`, and changing `src` restarts the whole load
cycle.

```html
<mk-image
  src="/photos/harbour.jpg"
  alt="Harbour at dawn"
  aspectRatio="16 / 9"
  caption="The old harbour, photographed at dawn"
  (loaded)="onLoaded()"
  (errored)="onErrored()"
/>

<!-- The hero: eager, high priority, and sized per breakpoint so a phone
     does not download the desktop file. -->
<mk-image
  src="/photos/hero-1600.jpg"
  srcset="/photos/hero-800.jpg 800w, /photos/hero-1600.jpg 1600w"
  sizes="100vw"
  alt=""
  aspectRatio="16 / 9"
  priority
/>
```

`aspectRatio` is what keeps this from shifting layout: the frame reserves
its box before the picture arrives, so nothing below it moves.

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `src` (required) | `string` |  | Image URL. Changing it resets the block to its loading state. |
| `alt` | `string` | `''` | Alt text, always reflected onto the `<img>`. Keep `''` for decorative images. |
| `aspectRatio` | `string` | `'auto'` | Any CSS `aspect-ratio` value for the frame, e.g. `'1 / 1'` or `'16 / 9'`. |
| `fit` | `MkImageFit` | `'cover'` | How the picture fills the frame. |
| `rounded` | `MkImageRounded` | `'md'` | Corner rounding of the frame. |
| `caption` | `string` | `''` | Caption rendered in a `<figcaption>` below the picture. |
| `lazy` | `boolean` | `true` | Defer fetching until near the viewport (`loading="lazy"` vs `"eager"`). |
| `priority` | `boolean` | `false` | Mark this as the page's LCP image: fetched eagerly at high priority and decoded synchronously, and `lazy` is ignored. Use it on exactly ONE image per page — the hero. Marking several is worse than marking none, because they then compete for the same bandwidth the real LCP image needs.  This does NOT emit a `<link rel=preload>`; the tag has to be in the HTML the server sends to beat the preload scanner, which a component rendered later cannot guarantee. Pair it with a preload hint for a background or late-rendered hero. |
| `srcset` | `string` | `''` | Responsive candidates, passed through verbatim to the `<img>`. Serving a 2048px file into a 600px slot is one of the most common LCP mistakes, and this is the fix; pair with `sizes`. |
| `sizes` | `string` | `''` | `sizes` attribute — how wide the image renders at each breakpoint. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `loaded` | `void` | Emits once the picture has finished loading. |
| `errored` | `void` | Emits when the picture fails to load and the fallback panel is shown. |

### MkImageCropper (component)

Selector: `mk-image-cropper` · exportAs: `mkImageCropper`

Docs: https://mk-kit.dev/components/media-manager

Import: `import { MkImageCropper } from '@mk-kit/ui/media';`

ImageCropper — pan-and-zoom crop control for avatars, covers and media uploads.
The image covers a fixed-aspect viewport (object-fit-cover style); the user
drags to pan, scrolls / pinch-zooms via the slider or `+`/`−` controls, and
`crop()` renders the visible region to a data-URL on an offscreen canvas.

Pan is always clamped so the image keeps covering the viewport, a
rule-of-thirds grid appears while dragging, and `round` overlays a circular
scrim for avatar crops (the exported bitmap stays rectangular). The crop
area is keyboard operable: Arrow keys pan by 10px (1px with Shift), `+`/`-`
zoom.

```html
<mk-image-cropper #cropper src="/assets/photo.jpg" [aspect]="1" round />
<button mkButton (click)="avatar = cropper.crop({ size: 512 })">Save</button>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `src` (required) | `string` |  | Image URL or data-URL to crop. |
| `aspect` | `number \| null` | `1` | Aspect ratio (width / height) of the crop viewport, e.g. `1` for a square or `16 / 9`. `null` makes the viewport fill its container. |
| `round` | `boolean` | `false` | Circular mask overlay for avatar crops. Purely visual — the exported bitmap from `crop()` stays rectangular. |
| `minZoom` | `number` | `1` | Lowest allowed zoom factor. |
| `maxZoom` | `number` | `4` | Highest allowed zoom factor. |
| `disabled` | `boolean` | `false` | Disable panning and zooming. |
| `crossOrigin` | `"anonymous" \| "use-credentials" \| null` | `null` | `crossorigin` for the internal `<img>`. Set to `'anonymous'` when cropping CORS-enabled remote images — without it the canvas is tainted and `crop()` returns `null`. Same-origin and data-URL sources don't need it. |
| `ariaLabel` | `string \| null` | `null` | Accessible name for the crop area (defaults to the i18n `zoom` label). |
| `zoom` (two-way) | `number` | `1` | Two-way zoom factor, clamped to `[minZoom, maxZoom]`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `changed` | `void` | Emits on any pan or zoom change. |
| `imageError` | `void` | Emits when the image fails to load. |
| `zoomChange` | `number` | Emits when `zoom` changes (two-way binding). |

Methods:

| Signature | Description |
| --- | --- |
| `reset(): void` | Centre the image and reset zoom to 1 (clamped to `minZoom`). |
| `cropRect(): { sx: number; sy: number; sw: number; sh: number; } \| null` | The visible crop region in natural image pixels — what `crop()` would rasterise, without touching a canvas. Use it when the backend performs the actual crop from the master image (no client-side quality loss). Returns `null` until the image has loaded and the viewport is measured. |
| `crop(options?: { type?: string; quality?: number; size?: number; }): string \| null` |  |

### MkImageGallery (component)

Selector: `mk-image-gallery` · exportAs: `mkImageGallery`

Docs: https://mk-kit.dev/components/images

Import: `import { MkImageGallery } from '@mk-kit/ui/media';`

Image gallery — a wall of clickable picture tiles built on `MkImage`.
Choose a uniform `grid`, a natural-ratio `masonry` flow, or a snap-scrolling
horizontal `strip`. Clicking a tile opens the shared `MkLightboxService`
at that picture (full-size `src`, not the thumb) and always emits
`itemClick`. With `max` set, only the first `max` tiles render and the last
one carries a "+N" overflow scrim that opens the rest in the lightbox.

```html
<mk-image-gallery
  [items]="[
    { src: '/photos/1.jpg', thumb: '/thumbs/1.jpg', alt: 'Harbour at dawn' },
    { src: '/photos/2.jpg', alt: 'Old town square', caption: 'Kraków' },
  ]"
  [columns]="4"
  [max]="8"
  aspectRatio="4 / 3"
  (itemClick)="onItemClick($event)"
/>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `readonly MkGalleryItem[]` |  | Pictures to show. |
| `layout` | `MkImageGalleryLayout` | `'grid'` | Tile arrangement. |
| `columns` | `number` | `3` | Grid/masonry column count; also sets the visible tile count of a strip. |
| `max` | `number \| null` | `null` | When set, show only the first `max` tiles plus a "+N" overflow tile. |
| `lightbox` | `boolean` | `true` | Open the shared lightbox on tile click. |
| `aspectRatio` | `string` | `'1 / 1'` | CSS aspect-ratio of grid/strip tiles (masonry keeps natural ratios). |
| `rounded` | `MkImageRounded` | `'md'` | Corner rounding of the tiles. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `itemClick` | `MkGalleryItemClick` | Emits on every tile click (also when the lightbox opens). |

### MkLightbox (component)

Selector: `mk-lightbox`

Docs: https://mk-kit.dev/components/images

Import: `import { MkLightbox } from '@mk-kit/ui/media';`

Internal overlay component backing `MkLightboxService`. Renders the
current image near-fullscreen over the overlay scrim with a caption bar,
an `imageOf` counter, a close button and looping previous/next navigation.

Keyboard: `ArrowLeft`/`ArrowRight` navigate, `Home`/`End` jump to the first
or last image. `Escape` and backdrop clicks are handled by the overlay
itself (`closeOnEscape` / `closeOnBackdropClick`), so they are deliberately
not re-handled here.

Open it via the service — not by placing `<mk-lightbox>` in a template:

```ts
inject(MkLightboxService).open(items, 2);
```

### MkMediaGallery (component)

Selector: `mk-media-gallery` · exportAs: `mkMediaGallery`

Docs: https://mk-kit.dev/components/media-manager

Import: `import { MkMediaGallery } from '@mk-kit/ui/media';`

Media gallery — a management grid of image tiles for admin media libraries.
Each tile shows a square thumbnail (a labelled preview button emitting
`itemClick`), the item's name and optional meta line, an optional
selection checkbox (two-way `selection` model of selected ids) and an
optional consumer-projected action bar (`MkMediaActions`).

With `reorderable`, tiles become draggable via the dnd group's
`[mkDropList]` / `[mkDrag]` directives — pointer and keyboard dragging
(WCAG 2.1.1) both included. Each drop immutably updates the two-way `items`
model and emits `reordered`.

Clicking a tile always means "open/preview" — selection only toggles through
the checkbox, never on tile click.

```html
<mk-media-gallery
  [(items)]="assets"
  [(selection)]="selectedIds"
  selectable
  reorderable
  [columns]="5"
  (itemClick)="openPreview($event)"
  (reordered)="persistOrder($event)"
>
  <ng-template mkMediaActions let-item>
    <button mkButton size="sm" variant="ghost" (click)="edit(item)">Edit</button>
    <button mkButton size="sm" variant="ghost" tone="danger" (click)="remove(item)">
      Delete
    </button>
  </ng-template>
</mk-media-gallery>
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (two-way) | `MkMediaItem[]` | `[]` | The gallery's items (two-way). Replaced immutably on every reorder drop. |
| `selection` (two-way) | `string[]` | `[]` | Ids of the currently selected items (two-way). |
| `selectable` | `boolean` | `false` | Show a selection checkbox on every tile. |
| `reorderable` | `boolean` | `false` | Allow drag-and-drop (pointer + keyboard) reordering of the tiles. |
| `columns` | `number` | `4` | Number of grid columns. |
| `ariaLabel` | `string` | `this.i18n.mediaLibrary` | Accessible name of the gallery region. Defaults to `i18n.mediaLibrary`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `itemsChange` | `MkMediaItem[]` | Emits when `items` changes (two-way binding). |
| `selectionChange` | `string[]` | Emits when `selection` changes (two-way binding). |
| `itemClick` | `MkMediaItem` | Emitted when a tile's preview button is activated (click/Enter/Space). |
| `reordered` | `MkMediaReorderEvent` | Emitted after a drop has updated the `items` model. |

### MkMediaActions (directive)

Selector: `[mkMediaActions]`

Docs: https://mk-kit.dev/components/media-manager

Import: `import { MkMediaActions } from '@mk-kit/ui/media';`

Marks an `<ng-template>` as the per-tile action bar for `MkMediaGallery`.
The template's implicit context is the `MkMediaItem`, so consumers can
destructure it with `let-item`. The gallery renders it into each tile's
top-right action bar (revealed on hover / focus-within, always visible on
touch devices); the consumer supplies the buttons and their handlers.

```html
<mk-media-gallery [items]="assets()">
  <ng-template mkMediaActions let-item>
    <button mkButton size="sm" variant="ghost" (click)="edit(item)">Edit</button>
  </ng-template>
</mk-media-gallery>
```

Properties:

| Name | Type | Description |
| --- | --- | --- |
| `template` | `TemplateRef<{ $implicit: MkMediaItem; }>` | The projected action-bar template, rendered once per tile. |

### MkLightboxService (service)

Docs: https://mk-kit.dev/components/images

Import: `import { MkLightboxService } from '@mk-kit/ui/media';`

Fullscreen image lightbox — opens a set of images in a modal overlay with
looping previous/next navigation, captions, a counter, keyboard support
(Arrow keys, Home/End, Escape) and focus trapping, all powered by
`MkOverlayService`.

```ts
private readonly lightbox = inject(MkLightboxService);

viewPhoto(index: number): void {
  this.lightbox.open(
    [
      { src: '/photos/1.jpg', alt: 'Harbour at dawn', caption: 'Dawn' },
      { src: '/photos/2.jpg', alt: 'Old town square' },
    ],
    index,
  );
}
```

Methods:

| Signature | Description |
| --- | --- |
| `open(items: readonly MkLightboxItem[], startIndex?: number): void` | Open the lightbox over the page. Does nothing when `items` is empty. `startIndex` is clamped into `[0, items.length - 1]`. |

### mkClampPan (function)

Import: `import { mkClampPan } from '@mk-kit/ui/media';`

Clamp a pan offset (CSS px, measured from the viewport centre to the image
centre) so the image scaled by `scale` still covers the viewport — no empty
edges. When the scaled image is not larger than the viewport on an axis the
offset collapses to `0` (centred).

```ts
function mkClampPan(x: number, y: number, imgW: number, imgH: number, vpW: number, vpH: number, scale: number): { x: number; y: number; }
```

### mkCoverScale (function)

Import: `import { mkCoverScale } from '@mk-kit/ui/media';`

Base cover scale for an image in a viewport — the smallest scale at which
`imgW × imgH` fully covers `vpW × vpH` (object-fit: cover). Returns `1`
for degenerate (non-positive) dimensions.

```ts
function mkCoverScale(imgW: number, imgH: number, vpW: number, vpH: number): number
```

### mkCropRect (function)

Import: `import { mkCropRect } from '@mk-kit/ui/media';`

Source rect (in natural image pixels) of the crop region visible through
the viewport. `scale` maps natural pixels to CSS pixels (cover scale ×
zoom); `panX`/`panY` are the CSS-px offsets of the image centre from the
viewport centre. The rect is clamped inside the image bounds.

```ts
function mkCropRect(imgNaturalW: number, imgNaturalH: number, vpW: number, vpH: number, scale: number, panX: number, panY: number): { sx: number; sy: number; sw: number; sh: number; }
```

### MkGalleryItem (interface)

Import: `import { MkGalleryItem } from '@mk-kit/ui/media';`

A single picture inside an `MkImageGallery`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `src` | `string` | Full-size image URL (what the lightbox opens). |
| `thumb`? | `string \| undefined` | Optional smaller thumbnail URL for the tile; falls back to `src`. |
| `alt`? | `string \| undefined` | Alt text; also drives the tile's accessible label. |
| `caption`? | `string \| undefined` | Optional caption forwarded to the lightbox. |

### MkGalleryItemClick (interface)

Import: `import { MkGalleryItemClick } from '@mk-kit/ui/media';`

Payload of the `MkImageGallery.itemClick` output.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `item` | `MkGalleryItem` | The clicked picture. |
| `index` | `number` | Its index within `items`. |

### MkLightboxData (interface)

Import: `import { MkLightboxData } from '@mk-kit/ui/media';`

Data injected into `MkLightbox` via `MK_OVERLAY_DATA`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `items` | `readonly MkLightboxItem[]` | The images to page through. |
| `startIndex` | `number` | Index of the image shown first (already clamped into range). |

### MkLightboxItem (interface)

Import: `import { MkLightboxItem } from '@mk-kit/ui/media';`

A single image shown by `MkLightboxService`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `src` | `string` | Image URL. |
| `alt`? | `string \| undefined` | Alternative text for the image. |
| `caption`? | `string \| undefined` | Optional caption rendered below the image. |

### MkMediaItem (interface)

Import: `import { MkMediaItem } from '@mk-kit/ui/media';`

A single asset displayed as a tile in `MkMediaGallery`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Stable identity used for tracking, selection and reorder events. |
| `src` | `string` | Full-size image URL (used for the thumbnail when `thumb` is omitted). |
| `thumb`? | `string \| undefined` | Optional dedicated thumbnail URL shown in the grid. |
| `name` | `string` | Display name shown under the thumbnail; also names the selection checkbox. |
| `alt`? | `string \| undefined` | Alternative text describing the image; falls back to `name` for labels. |
| `meta`? | `string \| undefined` | Optional caption/meta line shown under the name (e.g. "1.2 MB · JPG"). |

### MkMediaReorderEvent (interface)

Import: `import { MkMediaReorderEvent } from '@mk-kit/ui/media';`

Emitted by `MkMediaGallery` after a tile has been reordered.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `from` | `number` | Index the item was dragged from. |
| `to` | `number` | Index the item was dropped at. |
| `items` | `MkMediaItem[]` | The full item array after the move (same reference as the updated model). |

### MkImageFit (type)

Import: `import { MkImageFit } from '@mk-kit/ui/media';`

How the picture is scaled inside its frame (`object-fit`).

```ts
type MkImageFit = 'cover' | 'contain';
```

### MkImageGalleryLayout (type)

Import: `import { MkImageGalleryLayout } from '@mk-kit/ui/media';`

Tile arrangement of an `MkImageGallery`.

```ts
type MkImageGalleryLayout = 'grid' | 'masonry' | 'strip';
```

### MkImageRounded (type)

Import: `import { MkImageRounded } from '@mk-kit/ui/media';`

Corner rounding applied to the frame of an `MkImage`.

```ts
type MkImageRounded = 'none' | 'md' | 'lg' | 'circle';
```

### MkImageState (type)

Import: `import { MkImageState } from '@mk-kit/ui/media';`

Load lifecycle of an `MkImage`.

```ts
type MkImageState = 'loading' | 'loaded' | 'error';
```

## @mk-kit/ui/embed

4 exports. `import { … } from '@mk-kit/ui/embed';`

### MkEmbedApp (class)

Import: `import { MkEmbedApp } from '@mk-kit/ui/embed';`

One shared embed application. Create it with `mkEmbed`.

Methods:

| Signature | Description |
| --- | --- |
| `element(tag: string, component: Type<unknown>): this` | Defines `tag` as a custom element rendering `component`. Chainable; a no-op when the tag is already defined (hot reload, duplicate script) or outside a browser. |
| `ready(): Promise<void>` | Resolves when the shared application is running (created on demand). |
| `whenStable(): Promise<void>` | Resolves when the application has no pending change detection. |
| `destroy(): void` | Destroys the shared application, every mounted component and the overlay host. Defined tags remain registered (the platform cannot undefine them) but render nothing afterwards. |

### mkEmbed (function)

Import: `import { mkEmbed } from '@mk-kit/ui/embed';`

Creates an embed application: a factory for custom elements that render
mk-kit-based Angular components behind shadow DOM.

- **Lazy**: `element()` only defines the tag; the Angular application is
  created on the first element actually connected to a document.
- **Shared**: every element of one `mkEmbed()` call runs in one zoneless
  `ApplicationRef` with one provider set.
- **Isolated but themable**: the host page's CSS cannot reach the widget
  internals, while `--mk-*` custom properties still inherit through the
  shadow boundary — set them on the element (or any ancestor) to theme it.
- **Styled**: Angular routes each component's own styles into the shadow
  root it renders in; the `styles` option supplies the token/theme layer.

```ts
import { mkEmbed, mkShadowCss } from '@mk-kit/ui/embed';
import themeCss from '@mk-kit/ui/styles.css' with { type: 'text' };

mkEmbed({ styles: mkShadowCss(themeCss) })
  .element('acme-reviews', ReviewsWidget)
  .element('acme-signup', SignupWidget);
```

```html
<acme-reviews product-id="42" style="--mk-primary: #7c3aed"></acme-reviews>
```

Inputs are exposed as dash-cased attributes (string values go through the
input's `transform`, so `booleanAttribute` / `numberAttribute` inputs coerce
as usual) and as camel-cased element properties (any value); outputs become
bubbling, composed `CustomEvent`s named after the output, with the emitted
value as `detail`.

```ts
function mkEmbed(init?: MkEmbedInit): MkEmbedApp
```

### mkShadowCss (function)

Import: `import { mkShadowCss } from '@mk-kit/ui/embed';`

Rewrites a document-level stylesheet for adoption into a shadow root:
`:root` never matches inside one, so token blocks like mk-kit's
`:root { --mk-primary: … }` are retargeted to `:host`. Theme opt-ins keep
working — `:root:not([data-mk-theme='light'])` becomes
`:host:not([data-mk-theme='light'])`, so `<my-widget data-mk-theme="dark">`
switches one embedded element to the dark palette.

```ts
import themeCss from '@mk-kit/ui/styles.css' with { type: 'text' };
mkEmbed({ styles: mkShadowCss(themeCss) });
```

```ts
function mkShadowCss(css: string): string
```

### MkEmbedInit (interface)

Import: `import { MkEmbedInit } from '@mk-kit/ui/embed';`

Options for `mkEmbed`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `styles`? | `string \| readonly string[] \| undefined` | CSS text adopted into every element's shadow root (and the overlay host). Pass the mk-kit theme through `mkShadowCss` so its `:root` token blocks target `:host`; append your own widget CSS after it. Shared as constructable stylesheets when the browser supports them (one parse for any number of instances), `<style>` elements otherwise. |
| `styleUrls`? | `readonly string[] \| undefined` | Stylesheet URLs loaded as `<link rel="stylesheet">` into every shadow root (and the overlay host) — an alternative to inlining `styles` when the theme lives on a CDN. Loaded per shadow root by the browser's cache, so the network cost is paid once. |
| `nonce`? | `string \| undefined` | CSP nonce applied to every style and link element this app creates — including Angular's own component styles (provided as `CSP_NONCE`) and the `<style>` fallback when constructable stylesheets are unavailable. For host pages with a `style-src` policy that forbids `'unsafe-inline'`. |
| `providers`? | `(Provider \| EnvironmentProviders)[] \| undefined` | Extra providers for the shared application — `provideMkI18n(…)`, `provideMkExtendedIcons()`, `provideHttpClient()`, your services. |
| `overlays`? | `boolean \| undefined` | Mount mk-kit overlays (dialogs, anchored panels, toasts, tours) inside a page-level shadow host that carries the same `styles`, instead of bare `document.body`. Default `true`; set `false` to keep the application default (overlays styled by the page's own stylesheets). |

## @mk-kit/ui/locales/de

6 exports. `import { … } from '@mk-kit/ui/locales/de';`

### mkPluralDe (function)

Import: `import { mkPluralDe } from '@mk-kit/ui/locales/de';`

Picks the German plural form for a count — CLDR's `de` rules for integers:
`one` for 1, `other` for everything else.

```ts
mkPluralDe(1, 'Ergebnis', 'Ergebnisse'); // 'Ergebnis'
mkPluralDe(3, 'Ergebnis', 'Ergebnisse'); // 'Ergebnisse'
```

```ts
function mkPluralDe(count: number, one: string, other: string): string
```

### provideMkI18nDe (function)

Import: `import { provideMkI18nDe } from '@mk-kit/ui/locales/de';`

Provides the German strings — `MK_DE_I18N` with any `overrides`
merged on top (deep for `dateNames`, `blockEditor` and `validation`, like
`provideMkI18n`).

```ts
bootstrapApplication(App, {
  providers: [provideMkI18nDe({ noData: 'Nichts zu sehen' })],
});
```

```ts
function provideMkI18nDe(overrides?: MkI18nOverrides): Provider
```

### MK_DE_BLOCK_EDITOR (const)

Import: `import { MK_DE_BLOCK_EDITOR } from '@mk-kit/ui/locales/de';`

German strings of the block editor's chrome.

```ts
const MK_DE_BLOCK_EDITOR: MkBlockEditorStrings;
```

### MK_DE_DATE_NAMES (const)

Import: `import { MK_DE_DATE_NAMES } from '@mk-kit/ui/locales/de';`

German month and weekday names (Sunday-first, as in `Intl`).

```ts
const MK_DE_DATE_NAMES: MkDateNames;
```

### MK_DE_I18N (const)

Import: `import { MK_DE_I18N } from '@mk-kit/ui/locales/de';`

The complete German string map — every key of `MkI18nStrings`,
`locale: 'de-DE'` and `currency: 'EUR'` for the formatting pipes.
Provide it whole with `provideMkI18nDe`, or pass it as the base of
`provideMkI18n(overrides, MK_DE_I18N)`.

```ts
const MK_DE_I18N: MkI18nStrings;
```

### MK_DE_VALIDATION (const)

Import: `import { MK_DE_VALIDATION } from '@mk-kit/ui/locales/de';`

German validation messages rendered by `mk-form-field`.

```ts
const MK_DE_VALIDATION: MkValidationStrings;
```

## @mk-kit/ui/locales/es

6 exports. `import { … } from '@mk-kit/ui/locales/es';`

### mkPluralEs (function)

Import: `import { mkPluralEs } from '@mk-kit/ui/locales/es';`

Picks the Spanish plural form for a count — CLDR's `es` rules for integers:
`one` for 1, `other` for everything else.

```ts
mkPluralEs(1, 'resultado', 'resultados'); // 'resultado'
mkPluralEs(3, 'resultado', 'resultados'); // 'resultados'
```

```ts
function mkPluralEs(count: number, one: string, other: string): string
```

### provideMkI18nEs (function)

Import: `import { provideMkI18nEs } from '@mk-kit/ui/locales/es';`

Provides the Spanish strings — `MK_ES_I18N` with any `overrides`
merged on top (deep for `dateNames`, `blockEditor` and `validation`, like
`provideMkI18n`).

```ts
bootstrapApplication(App, {
  providers: [provideMkI18nEs({ noData: 'No hay nada aquí' })],
});
```

```ts
function provideMkI18nEs(overrides?: MkI18nOverrides): Provider
```

### MK_ES_BLOCK_EDITOR (const)

Import: `import { MK_ES_BLOCK_EDITOR } from '@mk-kit/ui/locales/es';`

Spanish strings of the block editor's chrome.

```ts
const MK_ES_BLOCK_EDITOR: MkBlockEditorStrings;
```

### MK_ES_DATE_NAMES (const)

Import: `import { MK_ES_DATE_NAMES } from '@mk-kit/ui/locales/es';`

Spanish month and weekday names (Sunday-first, lowercase as in `Intl`).

```ts
const MK_ES_DATE_NAMES: MkDateNames;
```

### MK_ES_I18N (const)

Import: `import { MK_ES_I18N } from '@mk-kit/ui/locales/es';`

The complete Spanish string map — every key of `MkI18nStrings`,
`locale: 'es-ES'` and `currency: 'EUR'` for the formatting pipes.
Provide it whole with `provideMkI18nEs`, or pass it as the base of
`provideMkI18n(overrides, MK_ES_I18N)`.

```ts
const MK_ES_I18N: MkI18nStrings;
```

### MK_ES_VALIDATION (const)

Import: `import { MK_ES_VALIDATION } from '@mk-kit/ui/locales/es';`

Spanish validation messages rendered by `mk-form-field`.

```ts
const MK_ES_VALIDATION: MkValidationStrings;
```

## @mk-kit/ui/locales/fr

6 exports. `import { … } from '@mk-kit/ui/locales/fr';`

### mkPluralFr (function)

Import: `import { mkPluralFr } from '@mk-kit/ui/locales/fr';`

Picks the French plural form for a count — CLDR's `fr` rules for integers:
`one` for 0 and 1, `other` for everything else.

```ts
mkPluralFr(1, 'résultat', 'résultats'); // 'résultat'
mkPluralFr(0, 'résultat', 'résultats'); // 'résultat'
mkPluralFr(3, 'résultat', 'résultats'); // 'résultats'
```

```ts
function mkPluralFr(count: number, one: string, other: string): string
```

### provideMkI18nFr (function)

Import: `import { provideMkI18nFr } from '@mk-kit/ui/locales/fr';`

Provides the French strings — `MK_FR_I18N` with any `overrides`
merged on top (deep for `dateNames`, `blockEditor` and `validation`, like
`provideMkI18n`).

```ts
bootstrapApplication(App, {
  providers: [provideMkI18nFr({ noData: 'Rien à afficher ici' })],
});
```

```ts
function provideMkI18nFr(overrides?: MkI18nOverrides): Provider
```

### MK_FR_BLOCK_EDITOR (const)

Import: `import { MK_FR_BLOCK_EDITOR } from '@mk-kit/ui/locales/fr';`

French strings of the block editor's chrome.

```ts
const MK_FR_BLOCK_EDITOR: MkBlockEditorStrings;
```

### MK_FR_DATE_NAMES (const)

Import: `import { MK_FR_DATE_NAMES } from '@mk-kit/ui/locales/fr';`

French month and weekday names (Sunday-first, lowercase as in `Intl`).

```ts
const MK_FR_DATE_NAMES: MkDateNames;
```

### MK_FR_I18N (const)

Import: `import { MK_FR_I18N } from '@mk-kit/ui/locales/fr';`

The complete French string map — every key of `MkI18nStrings`,
`locale: 'fr-FR'` and `currency: 'EUR'` for the formatting pipes.
Provide it whole with `provideMkI18nFr`, or pass it as the base of
`provideMkI18n(overrides, MK_FR_I18N)`.

```ts
const MK_FR_I18N: MkI18nStrings;
```

### MK_FR_VALIDATION (const)

Import: `import { MK_FR_VALIDATION } from '@mk-kit/ui/locales/fr';`

French validation messages rendered by `mk-form-field`.

```ts
const MK_FR_VALIDATION: MkValidationStrings;
```

## @mk-kit/ui/locales/pl

6 exports. `import { … } from '@mk-kit/ui/locales/pl';`

### mkPluralPl (function)

Import: `import { mkPluralPl } from '@mk-kit/ui/locales/pl';`

Picks the Polish plural form for a count: `one` for 1, `few` for 2–4
(except 12–14), `many` otherwise — CLDR's `pl` rules for integers, which is
all the library's counts ever are.

```ts
mkPluralPl(1, 'wynik', 'wyniki', 'wyników');  // 'wynik'
mkPluralPl(3, 'wynik', 'wyniki', 'wyników');  // 'wyniki'
mkPluralPl(12, 'wynik', 'wyniki', 'wyników'); // 'wyników'
```

```ts
function mkPluralPl(count: number, one: string, few: string, many: string): string
```

### provideMkI18nPl (function)

Import: `import { provideMkI18nPl } from '@mk-kit/ui/locales/pl';`

Provides the Polish strings — `MK_PL_I18N` with any `overrides`
merged on top (deep for `dateNames`, `blockEditor` and `validation`, like
`provideMkI18n`).

```ts
bootstrapApplication(App, {
  providers: [provideMkI18nPl({ noData: 'Nic tu nie ma' })],
});
```

```ts
function provideMkI18nPl(overrides?: MkI18nOverrides): Provider
```

### MK_PL_BLOCK_EDITOR (const)

Import: `import { MK_PL_BLOCK_EDITOR } from '@mk-kit/ui/locales/pl';`

Polish strings of the block editor's chrome.

```ts
const MK_PL_BLOCK_EDITOR: MkBlockEditorStrings;
```

### MK_PL_DATE_NAMES (const)

Import: `import { MK_PL_DATE_NAMES } from '@mk-kit/ui/locales/pl';`

Polish month and weekday names (Sunday-first, lowercase as in `Intl`).

```ts
const MK_PL_DATE_NAMES: MkDateNames;
```

### MK_PL_I18N (const)

Import: `import { MK_PL_I18N } from '@mk-kit/ui/locales/pl';`

The complete Polish string map — every key of `MkI18nStrings`,
`locale: 'pl-PL'` and `currency: 'PLN'` for the formatting pipes.
Provide it whole with `provideMkI18nPl`, or pass it as the base of
`provideMkI18n(overrides, MK_PL_I18N)`.

```ts
const MK_PL_I18N: MkI18nStrings;
```

### MK_PL_VALIDATION (const)

Import: `import { MK_PL_VALIDATION } from '@mk-kit/ui/locales/pl';`

Polish validation messages rendered by `mk-form-field`.

```ts
const MK_PL_VALIDATION: MkValidationStrings;
```

## @mk-kit/ui/locales/uk

6 exports. `import { … } from '@mk-kit/ui/locales/uk';`

### mkPluralUk (function)

Import: `import { mkPluralUk } from '@mk-kit/ui/locales/uk';`

Picks the Ukrainian plural form for a count — CLDR's `uk` rules for
integers: `one` when the number ends in 1 (but not 11), `few` when it ends
in 2–4 (but not 12–14), `many` otherwise.

```ts
mkPluralUk(1, 'результат', 'результати', 'результатів');  // 'результат'
mkPluralUk(3, 'результат', 'результати', 'результатів');  // 'результати'
mkPluralUk(11, 'результат', 'результати', 'результатів'); // 'результатів'
```

```ts
function mkPluralUk(count: number, one: string, few: string, many: string): string
```

### provideMkI18nUk (function)

Import: `import { provideMkI18nUk } from '@mk-kit/ui/locales/uk';`

Provides the Ukrainian strings — `MK_UK_I18N` with any `overrides`
merged on top (deep for `dateNames`, `blockEditor` and `validation`, like
`provideMkI18n`).

```ts
bootstrapApplication(App, {
  providers: [provideMkI18nUk({ noData: 'Тут нічого немає' })],
});
```

```ts
function provideMkI18nUk(overrides?: MkI18nOverrides): Provider
```

### MK_UK_BLOCK_EDITOR (const)

Import: `import { MK_UK_BLOCK_EDITOR } from '@mk-kit/ui/locales/uk';`

Ukrainian strings of the block editor's chrome.

```ts
const MK_UK_BLOCK_EDITOR: MkBlockEditorStrings;
```

### MK_UK_DATE_NAMES (const)

Import: `import { MK_UK_DATE_NAMES } from '@mk-kit/ui/locales/uk';`

Ukrainian month and weekday names (Sunday-first, lowercase as in `Intl`).

```ts
const MK_UK_DATE_NAMES: MkDateNames;
```

### MK_UK_I18N (const)

Import: `import { MK_UK_I18N } from '@mk-kit/ui/locales/uk';`

The complete Ukrainian string map — every key of `MkI18nStrings`,
`locale: 'uk-UA'` and `currency: 'UAH'` for the formatting pipes.
Provide it whole with `provideMkI18nUk`, or pass it as the base of
`provideMkI18n(overrides, MK_UK_I18N)`.

```ts
const MK_UK_I18N: MkI18nStrings;
```

### MK_UK_VALIDATION (const)

Import: `import { MK_UK_VALIDATION } from '@mk-kit/ui/locales/uk';`

Ukrainian validation messages rendered by `mk-form-field`.

```ts
const MK_UK_VALIDATION: MkValidationStrings;
```

## @mk-kit/ui/media/scanner

5 exports. `import { … } from '@mk-kit/ui/media/scanner';`

### MkBarcodeScanner (component)

Selector: `mk-barcode-scanner`

Docs: https://mk-kit.dev/components/images

Import: `import { MkBarcodeScanner } from '@mk-kit/ui/media/scanner';`

Camera barcode / QR reader. Starts the rear camera when it appears, emits
`scanned` once with the first decoded text and stops. The decoder
(`html5-qrcode`, an optional peer dependency) is loaded on demand, so pages
that only *offer* scanning ship nothing extra until a scan starts. Use
inline, or through `MkBarcodeScannerDialog`.

```html
<mk-barcode-scanner (scanned)="onCode($event)" (failed)="show($event)" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `formats` | `MkBarcodeFormat[]` | `MK_BARCODE_DEFAULT_FORMATS` | Symbologies to decode. Default: QR + the retail 1-D codes. |
| `fps` | `number` | `10` | Frames per second offered to the decoder. Default 10. |
| `hint` | `boolean` | `true` | Show the built-in hint line above the viewfinder. Default `true`. |
| `continuous` | `boolean` | `false` | Keep scanning after a hit instead of stopping. Default `false`. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `scanned` | `string` | Decoded text. |
| `failed` | `string` | The camera could not start (permission, no device, insecure context). |

Methods:

| Signature | Description |
| --- | --- |
| `stop(): Promise<void>` | Stop the camera and release it. Safe to call twice. |

### MkBarcodeScannerDialog (component)

Selector: `mk-barcode-scanner-dialog`

Docs: https://mk-kit.dev/components/images

Import: `import { MkBarcodeScannerDialog } from '@mk-kit/ui/media/scanner';`

The scanner in a dialog: resolves with the decoded text, or `null` when
cancelled. Open it with `MkDialogService`:

```ts
const code = await dialog.open<MkBarcodeScannerDialog, string | null>(MkBarcodeScannerDialog, { size: 'sm' }).afterClosed;
if (code) this.search.setValue(code);
```

### MK_BARCODE_DEFAULT_FORMATS (const)

Import: `import { MK_BARCODE_DEFAULT_FORMATS } from '@mk-kit/ui/media/scanner';`

```ts
const MK_BARCODE_DEFAULT_FORMATS: MkBarcodeFormat[];
```

### MkBarcodeScannerDialogData (interface)

Import: `import { MkBarcodeScannerDialogData } from '@mk-kit/ui/media/scanner';`

Optional data for `MkBarcodeScannerDialog`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `title`? | `string \| undefined` |  |
| `formats`? | `MkBarcodeFormat[] \| undefined` |  |

### MkBarcodeFormat (type)

Import: `import { MkBarcodeFormat } from '@mk-kit/ui/media/scanner';`

Symbologies the scanner reads; names follow `Html5QrcodeSupportedFormats`.

```ts
type MkBarcodeFormat = | 'QR_CODE' | 'EAN_13' | 'EAN_8' | 'CODE_128' | 'CODE_39' | 'UPC_A' | 'UPC_E' | 'DATA_MATRIX' | 'ITF' | 'CODABAR';
```

## @mk-kit/ui/testing

23 exports. `import { … } from '@mk-kit/ui/testing';`

### MkButtonHarness (class)

Import: `import { MkButtonHarness } from '@mk-kit/ui/testing';`

`button[mkButton]` / `a[mkButton]`.

Methods:

| Signature | Description |
| --- | --- |
| `text(): string` |  |
| `click(): Promise<void>` |  |
| `focus(): Promise<void>` |  |
| `isDisabled(): boolean` |  |
| `isLoading(): boolean` |  |
| `tone(): string \| null` |  |
| `variant(): string \| null` | `solid` \| `soft` \| `outline` \| `ghost` \| `link`. |
| `size(): string \| null` |  |

### MkCheckboxHarness (class)

Import: `import { MkCheckboxHarness } from '@mk-kit/ui/testing';`

`mk-checkbox`.

Methods:

| Signature | Description |
| --- | --- |
| `label(): string` |  |
| `isChecked(): boolean` |  |
| `isIndeterminate(): boolean` |  |
| `isDisabled(): boolean` |  |
| `isRequired(): boolean` |  |
| `toggle(): Promise<void>` |  |
| `check(): Promise<void>` |  |
| `uncheck(): Promise<void>` |  |
| `focus(): Promise<void>` |  |
| `blur(): Promise<void>` |  |

### MkDialogHarness (class)

Import: `import { MkDialogHarness } from '@mk-kit/ui/testing';`

A dialog opened by `MkDialogService` (`open()`, `confirm()`, `alert()`,
`prompt()`). Dialogs live in `document.body`, so look them up through
`loader.document()`.

Methods:

| Signature | Description |
| --- | --- |
| `title(): string` |  |
| `bodyText(): string` |  |
| `buttons(): string[]` | Texts of every button in the dialog (header close excluded). |
| `clickButton(which: number \| string \| RegExp): Promise<void>` | Click a button by index, exact text or RegExp. |
| `close(): Promise<void>` | The header × button. |
| `pressEscape(): Promise<void>` |  |
| `input(): MkTestElement \| null` | The prompt dialog's text field, if any. |

### MkFormFieldHarness (class)

Import: `import { MkFormFieldHarness } from '@mk-kit/ui/testing';`

`mk-form-field` — label / hint / error around any control.

Methods:

| Signature | Description |
| --- | --- |
| `label(): string` |  |
| `hint(): string \| null` |  |
| `error(): string \| null` | The visible validation message, or `null` when the field is valid/untouched. |
| `hasError(): boolean` |  |
| `isRequired(): boolean` |  |
| `control<T extends MkHarness>(type: Parameters<typeof this.loader.get<T>>[0]): Promise<T>` | The control inside the field, as a harness of the given type. |

### MkHarness (class)

Import: `import { MkHarness } from '@mk-kit/ui/testing';`

Base class of every mk-kit harness. Subclasses declare `hostSelector`
and expose user-level actions (`click()`, `selectOption()`, …) and reads
(`isChecked()`, `text()`), so specs never depend on the component's DOM.

### MkHarnessLoader (class)

Docs: https://mk-kit.dev/testing

Import: `import { MkHarnessLoader } from '@mk-kit/ui/testing';`

Finds harnesses under a root element. Create one with
`MkHarnessLoader.fromFixture(fixture)`; use `.document()` for content that
mk-kit teleports into `document.body` (dialogs, toasts, menus, select
panels) and `.within(el)` to scope lookups.

Methods:

| Signature | Description |
| --- | --- |
| `document(): MkHarnessLoader` | Same settle function, rooted at `document.body` — for overlays. |
| `within(root: Element \| MkTestElement): MkHarnessLoader` |  |
| `rootElement(): MkTestElement` | Wrap the root element itself. |
| `element(selector: string): MkTestElement` |  |
| `elements(selector: string): MkTestElement[]` |  |
| `get<T extends MkHarness>(type: MkHarnessType<T>, filters?: MkHarnessFilters): Promise<T>` | First matching harness; throws when there is none. Retries for a short while first: overlays such as `MkDialogService.prompt()` render after a lazy chunk resolves, so the host may appear a few ticks after the call. `has()` / `getOrNull()` stay immediate so absence can be asserted. |
| `getOrNull<T extends MkHarness>(type: MkHarnessType<T>, filters?: MkHarnessFilters): Promise<T \| null>` |  |
| `has<T extends MkHarness>(type: MkHarnessType<T>, filters?: MkHarnessFilters): Promise<boolean>` |  |
| `getAll<T extends MkHarness>(type: MkHarnessType<T>, filters?: MkHarnessFilters): Promise<T[]>` |  |

### MkInputHarness (class)

Import: `import { MkInputHarness } from '@mk-kit/ui/testing';`

Native `input[mkInput]` / `textarea[mkInput]`.

Methods:

| Signature | Description |
| --- | --- |
| `value(): string` |  |
| `setValue(value: string): Promise<void>` | Replace the value (fires `input` + `change`). |
| `type(text: string): Promise<void>` | Append text one character at a time (keydown / input / keyup). |
| `clear(): Promise<void>` |  |
| `focus(): Promise<void>` |  |
| `blur(): Promise<void>` |  |
| `placeholder(): string` |  |
| `type_(): string` |  |
| `isDisabled(): boolean` |  |
| `isInvalid(): boolean` |  |
| `isRequired(): boolean` |  |
| `isFocused(): boolean` |  |

### MkMenuHarness (class)

Import: `import { MkMenuHarness } from '@mk-kit/ui/testing';`

A `[mkMenuTriggerFor]` trigger and the `mk-menu` panel it opens. The host
is matched by the trigger's `aria-haspopup="menu"` (the directive's
attribute is an input binding, so it is not in the DOM).

Methods:

| Signature | Description |
| --- | --- |
| `isOpen(): boolean` |  |
| `open(): Promise<void>` |  |
| `close(): Promise<void>` |  |
| `panel(): MkTestElement \| null` | The teleported panel (`[role="menu"]`), or `null` while closed. |
| `items(): Promise<string[]>` | Item texts of the open menu (opens it if needed). Submenu panels excluded. |
| `clickItem(which: number \| string \| RegExp): Promise<void>` | Click an item by index, exact text or RegExp (opens the menu first). |
| `isItemDisabled(which: number \| string \| RegExp): Promise<boolean>` |  |

### MkRadioGroupHarness (class)

Import: `import { MkRadioGroupHarness } from '@mk-kit/ui/testing';`

`mk-radio-group`.

Methods:

| Signature | Description |
| --- | --- |
| `radios(): Promise<MkRadioHarness[]>` |  |
| `labels(): Promise<string[]>` |  |
| `checkedLabel(): Promise<string \| null>` | Label of the checked radio, or `null`. |
| `checkedIndex(): Promise<number>` |  |
| `select(which: number \| string \| RegExp): Promise<void>` | Select by index, exact label or RegExp. |
| `isDisabled(): boolean` |  |

### MkRadioHarness (class)

Import: `import { MkRadioHarness } from '@mk-kit/ui/testing';`

One `mk-radio` inside a group.

Methods:

| Signature | Description |
| --- | --- |
| `label(): string` |  |
| `isChecked(): boolean` |  |
| `isDisabled(): boolean` |  |
| `select(): Promise<void>` |  |
| `focus(): Promise<void>` |  |

### MkSelectHarness (class)

Import: `import { MkSelectHarness } from '@mk-kit/ui/testing';`

`mk-select` — opens the teleported listbox and picks options like a user.

Methods:

| Signature | Description |
| --- | --- |
| `valueText(): string` | Label of the selected option, or `''` when only the placeholder shows. |
| `placeholder(): string` |  |
| `isOpen(): boolean` |  |
| `isDisabled(): boolean` |  |
| `isInvalid(): boolean` |  |
| `open(): Promise<void>` |  |
| `close(): Promise<void>` |  |
| `focus(): Promise<void>` |  |
| `options(): Promise<MkSelectOptionState[]>` | Options of the (opened) listbox. Opens it if needed. |
| `selectOption(which: number \| string \| RegExp): Promise<void>` | Pick an option by index, exact label or RegExp (opens the list first). |

### MkSwitchHarness (class)

Import: `import { MkSwitchHarness } from '@mk-kit/ui/testing';`

`mk-switch`.

Methods:

| Signature | Description |
| --- | --- |
| `label(): string` |  |
| `isChecked(): boolean` |  |
| `isDisabled(): boolean` |  |
| `toggle(): Promise<void>` |  |
| `check(): Promise<void>` |  |
| `uncheck(): Promise<void>` |  |
| `focus(): Promise<void>` |  |

### MkTableHarness (class)

Import: `import { MkTableHarness } from '@mk-kit/ui/testing';`

`mk-table`.

Methods:

| Signature | Description |
| --- | --- |
| `headers(): string[]` | Header labels of the data columns, in display order. |
| `rows(): Promise<MkTableRowHarness[]>` |  |
| `rowCount(): Promise<number>` |  |
| `cellTexts(): Promise<string[][]>` | Every data cell as text: `rows()[r].cells()`. |
| `sortBy(which: number \| string \| RegExp): Promise<void>` | Click a sortable header (by index, exact label or RegExp). |
| `sortDirection(which: number \| string \| RegExp): string \| null` | `'ascending' \| 'descending' \| 'none' \| null` (null = not sortable). |
| `selectedRowCount(): Promise<number>` |  |
| `toggleAll(): Promise<void>` | Toggle the header "select all" checkbox. |
| `isEmpty(): boolean` | True when the table shows no data rows (an `emptyMessage` row does not count). |
| `emptyMessage(): string \| null` | The rendered `emptyMessage`, or `null` while the table has rows. |
| `setFilter(key: string, value: string): Promise<void>` | Set a header-row filter (table is `filterable`). `value` is typed into a text / number / date box, or picked from a select by option label or value; `''` clears that filter. |
| `filterValue(key: string): string` | The current value of a header-row filter control (`''` when unset). |
| `clearFilters(): Promise<void>` | Clear every header-row filter. |
| `scrollToRow(index: number): Promise<void>` | Scroll a `virtual` table so the row at display `index` is at the top of the viewport (drives the scroll box, so only the rows around it render). |

### MkTableRowHarness (class)

Import: `import { MkTableRowHarness } from '@mk-kit/ui/testing';`

One data row of `mk-table` (the `emptyMessage` placeholder row is not one).

Methods:

| Signature | Description |
| --- | --- |
| `cells(): string[]` | Cell texts of the data columns (expand / select cells excluded). |
| `cell(index: number): string` |  |
| `isSelected(): boolean` |  |
| `isExpanded(): boolean` |  |
| `click(): Promise<void>` |  |
| `toggleSelected(): Promise<void>` | Toggle the selection checkbox (throws when the table is not `selectable`). |
| `toggleExpanded(): Promise<void>` | Toggle the expand / tree control of the row. |

### MkTabsHarness (class)

Import: `import { MkTabsHarness } from '@mk-kit/ui/testing';`

`mk-tabs`.

Methods:

| Signature | Description |
| --- | --- |
| `labels(): string[]` |  |
| `selectedIndex(): number` |  |
| `selectedLabel(): string \| null` |  |
| `select(which: number \| string \| RegExp): Promise<void>` | Select by index, exact label or RegExp. |
| `isDisabled(which: number \| string \| RegExp): boolean` |  |
| `selectedPanel(): MkTestElement \| null` | The visible tab panel (`mk-tab` host). |
| `selectedPanelText(): string` | Text of the visible panel. |

### MkTestElement (class)

Import: `import { MkTestElement } from '@mk-kit/ui/testing';`

A DOM element wrapped for tests: reads are synchronous, every interaction
dispatches the same events a user would and then settles change detection
(`fixture.detectChanges()` + `whenStable()`), so the next read sees the
updated view.

Methods:

| Signature | Description |
| --- | --- |
| `text(): string` | Trimmed text content with whitespace collapsed. |
| `attr(name: string): string \| null` |  |
| `hasClass(name: string): boolean` |  |
| `prop<T = unknown>(name: string): T` | Read a DOM property (`value`, `checked`, `open`, …). |
| `matches(selector: string): boolean` |  |
| `isFocused(): boolean` |  |
| `isDisabled(): boolean` | Native `disabled`, `aria-disabled="true"` or a `--disabled` host class. |
| `query(selector: string): MkTestElement \| null` |  |
| `queryAll(selector: string): MkTestElement[]` |  |
| `child(selector: string): MkTestElement` | Like `query`, but throws a readable error when nothing matches. |
| `click(): Promise<void>` | pointerdown → mousedown → focus → pointerup → mouseup → click, like a user. |
| `hover(): Promise<void>` |  |
| `leave(): Promise<void>` |  |
| `focus(): Promise<void>` |  |
| `blur(): Promise<void>` |  |
| `type(text: string): Promise<void>` | Type into an input/textarea/contenteditable character by character — keydown, `value` append, `input`, keyup — then settle. Use `setValue` to replace the value in one go. |
| `setValue(value: string): Promise<void>` | Set the value of an input/textarea/select and fire `input` + `change`. |
| `clear(): Promise<void>` |  |
| `sendKeys(...keys: Array<MkTestKey \| (string & {})>): Promise<void>` | Dispatch keydown/keyup for each key. Printable single characters are also typed. |
| `dispatch(event: Event): Promise<void>` | Dispatch any event on the element and settle. |

### MkToastHarness (class)

Import: `import { MkToastHarness } from '@mk-kit/ui/testing';`

One toast shown by `MkToastService` (lives in `document.body` — use `loader.document()`).

Methods:

| Signature | Description |
| --- | --- |
| `title(): string \| null` |  |
| `message(): string` |  |
| `tone(): string \| null` |  |
| `actionLabel(): string \| null` |  |
| `clickAction(): Promise<void>` |  |
| `dismiss(): Promise<void>` |  |

### matchText (function)

Import: `import { matchText } from '@mk-kit/ui/testing';`

```ts
function matchText(actual: string, expected: string | RegExp): boolean
```

### pickBy (function)

Import: `import { pickBy } from '@mk-kit/ui/testing';`

Resolve "by index or by label" arguments shared by option-style harnesses.

```ts
function pickBy<T>(items: T[], which: number | string | RegExp, label: (item: T) => string, what: string): T
```

### MkHarnessFilters (interface)

Import: `import { MkHarnessFilters } from '@mk-kit/ui/testing';`

Filters every harness lookup accepts. `selector` narrows the host elements
considered (e.g. a class or attribute your template sets); `text` matches
the host's trimmed text content — a string must match exactly, a RegExp
is tested.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `selector`? | `string \| undefined` |  |
| `text`? | `string \| RegExp \| undefined` |  |

### MkHarnessType (interface)

Import: `import { MkHarnessType } from '@mk-kit/ui/testing';`

Constructor shape of every harness class: a static `hostSelector`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `hostSelector` | `string` |  |

### MkSelectOptionState (interface)

Import: `import { MkSelectOptionState } from '@mk-kit/ui/testing';`

Members:

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` |  |
| `selected` | `boolean` |  |
| `disabled` | `boolean` |  |

### MkTestKey (type)

Import: `import { MkTestKey } from '@mk-kit/ui/testing';`

Keys accepted by `MkTestElement.sendKeys` besides printable characters.

```ts
type MkTestKey = | 'Enter' | 'Escape' | 'Tab' | 'Backspace' | 'Delete' | ' ' | 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight' | 'Home' | 'End' | 'PageUp' | 'PageDown';
```

## @mk-kit/ui/translate/editor

3 exports. `import { … } from '@mk-kit/ui/translate/editor';`

### MkTranslationEditor (component)

Selector: `mk-translation-editor`

Docs: https://mk-kit.dev/components/translate

Import: `import { MkTranslationEditor } from '@mk-kit/ui/translate/editor';`

Translation editor — keys as rows, locales as columns, click a cell to
edit. The base strings are your bundled files; edits are **overrides**
kept apart from them, so a rebuild never loses them and a cell can be
restored to the file text. Search by key or text, filter to the keys a
locale is missing or the ones already edited, export the grid as CSV.
Persistence is yours: every edit is emitted as `changed`, feed the result
back through `overrides`.

```html
<mk-translation-editor
  [locales]="['pl', 'en', 'ru']"
  [base]="base()"
  [overrides]="overrides()"
  (changed)="save($event)" />
```

Inputs:

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `locales` (required) | `string[]` |  | Locale codes, in column order. The first one is the reference language. |
| `base` (required) | `Record<string, MkFlatTranslations>` |  | Bundled strings per locale, flat (`'a.b.c': 'text'`) or nested. |
| `overrides` | `Record<string, MkFlatTranslations>` | `{}` | Edits per locale, flat. Missing locales are fine. |
| `readonly` | `boolean` | `false` | Show but do not edit. |
| `exportFilename` | `string` | `'translations.csv'` | File name of the CSV export. |

Outputs:

| Name | Type | Description |
| --- | --- | --- |
| `changed` | `MkTranslationChange` | An edit or a restore; persist it and update `overrides`. |

### MkTranslationChange (interface)

Import: `import { MkTranslationChange } from '@mk-kit/ui/translate/editor';`

One edit made in the editor. `value: null` clears the override.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `locale` | `string` |  |
| `key` | `string` |  |
| `value` | `string \| null` |  |
| `previous` | `string \| null` | The text shown before the edit (override, or the base string). |

### MkTranslationRow (interface)

Import: `import { MkTranslationRow } from '@mk-kit/ui/translate/editor';`

A row of the editor: the key plus the effective text per locale.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `key` | `string` |  |

## @mk-kit/ui/translate/server

2 exports. `import { … } from '@mk-kit/ui/translate/server';`

### mkFsTranslateLoader (function)

Import: `import { mkFsTranslateLoader } from '@mk-kit/ui/translate/server';`

Server-side loader that reads the translation JSON from disk instead of
fetching the app's own HTTP endpoint during SSR — no self-request, no
proxy hop, no interceptor ordering to get right. Register it in the
server config only (`app.config.server.ts`); the browser keeps
`mkHttpTranslateLoader`. Files are parsed once per process.

```ts
// app.config.server.ts
provideMkTranslate({
  ...browserTranslateConfig,
  loader: mkFsTranslateLoader({
    dirs: [join(import.meta.dirname, '../browser/assets/i18n'), join(process.cwd(), 'src/assets/i18n')],
  }),
})
```

```ts
function mkFsTranslateLoader(options: MkFsTranslateLoaderOptions): MkTranslateLoaderFactory
```

### MkFsTranslateLoaderOptions (interface)

Import: `import { MkFsTranslateLoaderOptions } from '@mk-kit/ui/translate/server';`

Options for `mkFsTranslateLoader`.

Members:

| Name | Type | Description |
| --- | --- | --- |
| `dirs` | `string[]` | Directories searched in order for `<lang><suffix>`; the first readable file wins. Typical: the built browser assets next to the server bundle, then the source tree for `ng serve`. |
| `suffix`? | `string \| undefined` | File suffix after the language code. Default `.json`. |
| `onNotFound`? | `"empty" \| "throw" \| undefined` | When no directory has the file: return `{}` (default) so the app boots with keys as text, or throw so the failure surfaces at once. |