# Kikita UI -- Full Context

Every public docs page for the installed @kikita-labs/ui package, concatenated for large-context
agent ingestion. Prefer llms.txt for a curated index; use this file when you need everything.

---

<!-- route: / -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/index.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Kikita UI

> Angular component library documentation and external consumer verification.

- Status: available
- Route: /
- Package: @kikita-labs/ui@2.0.0

## Foundations

- [Accessibility](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/accessibility.md): Keyboard, semantics, focus, and WCAG expectations.
- [Auto Focus](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/auto-focus.md): kuiAutoFocus moves focus to its host, or to the first focusable element inside it, after the browser has rendered.
- [Defaults](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/defaults.md): Set shared preferences such as size, shape, clearable or toast placement once for the application or for a subtree, instead of repeating them in every template.
- [Density](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/density.md): Spacing and control density expectations for product UIs.
- [Forms](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/forms.md): Kikita UI is Signal Forms first: put the control directive and [formField] on the same element and wrap it in kui-field for the label, hint, error and required marker.
- [Installation](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/installation.md): Package installation and global stylesheet setup.
- [Internationalization](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/internationalization.md): Locale and messages are two independent settings: the locale formats dates, numbers and plurals, the messages translate the text the library owns.
- [Migrating to 2.0](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/migration.md): Every breaking change of @kikita-labs/ui 2.0: renamed exports, provider defaults, locale and messages, icons, tokens, component behaviour and the charts.
- [Structural icons](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/structural-icons.md): The small glyphs a component draws for itself, such as the cross on a dialog or the chevron on a select, as replaceable icon data.
- [Theming](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/theming.md): Theme provider setup and theme customization basics.
- [Tokens](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/tokens.md): Design token categories exposed through Kikita CSS variables.
- [Typography](https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/typography.md): Semantic type-role classes, text tones, and the kuiText directive.

## Components

- [Accordion](https://kikita-labs.github.io/kikita-ui-docs/llms/components/accordion.md): Disclosure component for grouped expandable content.
- [Alert](https://kikita-labs.github.io/kikita-ui-docs/llms/components/alert.md): Inline notification embedded in the page content flow.
- [Avatar](https://kikita-labs.github.io/kikita-ui-docs/llms/components/avatar.md): User or entity identity with image, initials, and status.
- [Badge](https://kikita-labs.github.io/kikita-ui-docs/llms/components/badge.md): Compact status or metadata marker.
- [Bar Chart](https://kikita-labs.github.io/kikita-ui-docs/llms/components/bar-chart.md): Vertical or horizontal, grouped or stacked bar chart.
- [Breadcrumbs](https://kikita-labs.github.io/kikita-ui-docs/llms/components/breadcrumbs.md): Hierarchy trail.
- [Button](https://kikita-labs.github.io/kikita-ui-docs/llms/components/button.md): Primary command primitive for buttons and links.
- [Calendar](https://kikita-labs.github.io/kikita-ui-docs/llms/components/calendar.md): Date grid.
- [Calendar Range](https://kikita-labs.github.io/kikita-ui-docs/llms/components/calendar-range.md): Inline month grid for selecting a start and end date.
- [Card](https://kikita-labs.github.io/kikita-ui-docs/llms/components/card.md): Surface, elevated, and sunken content container.
- [Carousel](https://kikita-labs.github.io/kikita-ui-docs/llms/components/carousel.md): Horizontal strip of slides with arrows, a dot picker and optional autoplay.
- [Checkbox](https://kikita-labs.github.io/kikita-ui-docs/llms/components/checkbox.md): Native checkbox styling with field state integration.
- [Chip](https://kikita-labs.github.io/kikita-ui-docs/llms/components/chip.md): Compact token for selected values, filters, and entity references.
- [Color Input](https://kikita-labs.github.io/kikita-ui-docs/llms/components/color-input.md): Color value input.
- [Combobox](https://kikita-labs.github.io/kikita-ui-docs/llms/components/combobox.md): Searchable input with projected options and async mode.
- [Command Palette](https://kikita-labs.github.io/kikita-ui-docs/llms/components/command-palette.md): Searchable command overlay for application actions.
- [Date Picker](https://kikita-labs.github.io/kikita-ui-docs/llms/components/date-picker.md): Calendar date input.
- [Dialog](https://kikita-labs.github.io/kikita-ui-docs/llms/components/dialog.md): Typed modal overlay service and host contract.
- [Donut Chart](https://kikita-labs.github.io/kikita-ui-docs/llms/components/donut-chart.md): Donut chart for shares of a whole.
- [Drawer](https://kikita-labs.github.io/kikita-ui-docs/llms/components/drawer.md): Side and edge overlay surface for focused workflows.
- [Dropdown](https://kikita-labs.github.io/kikita-ui-docs/llms/components/dropdown.md): Projected option overlay used by select-like controls.
- [Empty State](https://kikita-labs.github.io/kikita-ui-docs/llms/components/empty-state.md): Known empty, error, no-access, and success content states.
- [Field](https://kikita-labs.github.io/kikita-ui-docs/llms/components/field.md): Label, hint, error, and form-control composition.
- [File Upload](https://kikita-labs.github.io/kikita-ui-docs/llms/components/file-upload.md): Controlled file picker.
- [Group](https://kikita-labs.github.io/kikita-ui-docs/llms/components/group.md): Grouped control chrome for adjacent actions and fields.
- [Icon](https://kikita-labs.github.io/kikita-ui-docs/llms/components/icon.md): SVG icon renderer.
- [Icon Button](https://kikita-labs.github.io/kikita-ui-docs/llms/components/icon-button.md): Compact icon-only action control.
- [Input](https://kikita-labs.github.io/kikita-ui-docs/llms/components/input.md): Native text input styling with field integration.
- [Line Chart](https://kikita-labs.github.io/kikita-ui-docs/llms/components/line-chart.md): Line and area chart for trends over categories.
- [Link](https://kikita-labs.github.io/kikita-ui-docs/llms/components/link.md): Inline interactive text for navigation or a JS-driven action.
- [Loader](https://kikita-labs.github.io/kikita-ui-docs/llms/components/loader.md): Inline loading indicator for buttons and status areas.
- [Media Viewer](https://kikita-labs.github.io/kikita-ui-docs/llms/components/media-viewer.md): Fullscreen photo lightbox with navigation, thumbnails and zoom.
- [Menu](https://kikita-labs.github.io/kikita-ui-docs/llms/components/menu.md): Anchored command menu with keyboard focus behavior.
- [Number Input](https://kikita-labs.github.io/kikita-ui-docs/llms/components/number-input.md): Number input states with compact variant options.
- [OTP Input](https://kikita-labs.github.io/kikita-ui-docs/llms/components/otp-input.md): Row of single-character cells for a one-time code or PIN.
- [Pagination](https://kikita-labs.github.io/kikita-ui-docs/llms/components/pagination.md): Page navigation with numbers, steps, a summary and a rows-per-page picker.
- [Popover](https://kikita-labs.github.io/kikita-ui-docs/llms/components/popover.md): Anchored content surface for contextual UI.
- [Progress](https://kikita-labs.github.io/kikita-ui-docs/llms/components/progress.md): Progress status primitive for determinate and indeterminate work.
- [Radio](https://kikita-labs.github.io/kikita-ui-docs/llms/components/radio.md): Native radio control styling for exclusive choices.
- [Scatter Chart](https://kikita-labs.github.io/kikita-ui-docs/llms/components/scatter-chart.md): Scatter and bubble chart for two numeric measures.
- [Scrollbar](https://kikita-labs.github.io/kikita-ui-docs/llms/components/scrollbar.md): Tokenized native scroll container utility.
- [Segmented](https://kikita-labs.github.io/kikita-ui-docs/llms/components/segmented.md): Compact single-choice control rendered as adjacent segment buttons.
- [Select](https://kikita-labs.github.io/kikita-ui-docs/llms/components/select.md): Dropdown-backed selection control for single and multiple values.
- [Separator](https://kikita-labs.github.io/kikita-ui-docs/llms/components/separator.md): Tokenized horizontal or vertical separator primitive.
- [Skeleton](https://kikita-labs.github.io/kikita-ui-docs/llms/components/skeleton.md): Loading placeholder with reduced-motion behavior.
- [Slider](https://kikita-labs.github.io/kikita-ui-docs/llms/components/slider.md): Native range input styling with field and Signal Forms support.
- [Splitter](https://kikita-labs.github.io/kikita-ui-docs/llms/components/splitter.md): Draggable multi-pane layout with resizable gutters.
- [Stepper](https://kikita-labs.github.io/kikita-ui-docs/llms/components/stepper.md): Multi-step progress and navigation indicator.
- [Switch](https://kikita-labs.github.io/kikita-ui-docs/llms/components/switch.md): Native switch control styling for binary settings.
- [Table](https://kikita-labs.github.io/kikita-ui-docs/llms/components/table.md): Native table styling, sorting context, and selection cells.
- [Tabs](https://kikita-labs.github.io/kikita-ui-docs/llms/components/tabs.md): Line and pill tab navigation with optional panel wiring.
- [Textarea](https://kikita-labs.github.io/kikita-ui-docs/llms/components/textarea.md): Native multiline input styling with field integration.
- [Time Picker](https://kikita-labs.github.io/kikita-ui-docs/llms/components/time-picker.md): Time-of-day input with a scrollable hour, minute and second panel.
- [Toast](https://kikita-labs.github.io/kikita-ui-docs/llms/components/toast.md): Global notifications with actions and live-region semantics.
- [Tooltip](https://kikita-labs.github.io/kikita-ui-docs/llms/components/tooltip.md): Hover and focus hint.
- [Tree](https://kikita-labs.github.io/kikita-ui-docs/llms/components/tree.md): Hierarchical list.

## Resources

- [AI Support](https://kikita-labs.github.io/kikita-ui-docs/llms/resources/ai-support.md): Agent-readable docs, llms.txt, and local MCP setup for Kikita UI.
- [Package Smoke](https://kikita-labs.github.io/kikita-ui-docs/llms/resources/smoke.md): External consumer verification for package imports, styles, and providers.

---

<!-- route: /foundations/accessibility -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/accessibility.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Accessibility

> Keyboard, semantics, focus, and WCAG expectations.

- Status: available
- Route: /foundations/accessibility
- Package: @kikita-labs/ui@2.0.0

## Content

### Baseline rules
These requirements apply to primitives, docs examples, and consumer verification pages.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| Semantics first | HTML | - | Prefer native elements and browser behavior before adding ARIA. |
| Keyboard | WCAG AA | - | Every interactive state must be reachable, operable, and escapable by keyboard. |
| Focus | Visible state | - | Focus indicators must remain visible and must not cause layout shift. |
| Contrast | WCAG AA | - | Text, icons, focus, disabled, invalid, selected, and loading states must remain distinguishable. |

### Review levels
A clean automated scan is only a smoke test. Do not mark a primitive fully audited without keyboard and assistive-technology review.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| DOM smoke | Automated | - | Catches broken ARIA references, duplicate ids, invalid roles, and unnamed controls. |
| Keyboard review | Manual | - | Verifies tab order, activation keys, escape behavior, and focus restoration. |
| Assistive technology | Manual | - | Uses a real screen reader or platform accessibility tool for names, roles, and states. |
| Visual review | Manual | - | Checks responsive layout, 200% zoom, reduced motion, forced colors, and contrast. |

### Focus, forms and keyboard
Focus handling and required or invalid state follow one shared behaviour across the library.

### Motion, contrast and forced colors
Nonessential motion, contrast and Windows High Contrast are part of every state-bearing component.

### Docs examples
Examples should use Kikita field wiring and native state attributes instead of compensating for broken markup with custom ARIA.
#### field-example.html

```html
<kui-field label="Email" hint="Use your work address.">
  <input kuiInput type="email" autocomplete="email" />
</kui-field>
```

#### navigation.html

```html
<a routerLink="/foundations/tokens" aria-current="page">
  Tokens
</a>
```

### Coverage notes
Record the actual level of review. Be explicit when only DOM smoke has run.
#### state-coverage.md

```md
- DOM accessibility smoke has run for <primitive>, but real assistive-technology review is still pending.
```

#### state-coverage.md

```md
- Assistive-technology review for <primitive> was run with <AT/browser/OS>.
  Covered keyboard navigation, names/roles/states, focus return, and primitive-specific behavior.
  Remaining gap: none known.
```

---

<!-- route: /foundations/auto-focus -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/auto-focus.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Auto Focus

> kuiAutoFocus moves focus to its host, or to the first focusable element inside it, after the browser has rendered.

- Status: available
- Route: /foundations/auto-focus
- Package: @kikita-labs/ui@2.0.0

## Content

### Import and usage
Use it where the next step is obvious, such as the first field of a dialog or a code field that has just appeared. The directive has no styles.
#### auto-focus.ts

```ts
import { KuiAutoFocus } from '@kikita-labs/ui';
```

#### form.html

```html
<input kuiInput kuiAutoFocus />
```

#### form.html

```html
<input kuiInput [kuiAutoFocus]="editing()" />
```

#### form.html

```html
<div kuiAutoFocus>
  <input kuiInput aria-label="Search" />
</div>
```

### Rules
The directive is conservative about when it moves focus.

### API
There are no outputs, providers or CSS custom properties.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| kuiAutoFocus | boolean | - | Enables focus (default false). The attribute without a value is true, and false to true focuses again. |
| kuiAutoFocusPreventScroll | boolean | - | Focuses without scrolling the element into view (default false). |

### Accessibility
Automatic focus can disorient screen-reader users, so keep it off by default.

---

<!-- route: /foundations/defaults -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/defaults.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Defaults

> Set shared preferences such as size, shape, clearable or toast placement once for the application or for a subtree, instead of repeating them in every template.

- Status: available
- Route: /foundations/defaults
- Package: @kikita-labs/ui@2.0.0

## Content

### When to use defaults
Defaults cover preferences shared by many instances. Data, instance state and form state are never defaults.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| Colour, radius, spacing, type | Theme seeds and CSS variables | - | Visual identity of the whole application. |
| Variant or behaviour shared across the app | Defaults | - | Size, shape, clearable, toast placement and similar preferences (this page). |
| Density | Theme seeds | - | Set seeds.density in the theme. |
| Texts and accessible names | Messages | - | See the Internationalization page. |

### Setting defaults
defaults is a flat map with one key per primitive plus the global control size. Every key points to a named options interface such as KuiButtonOptions or KuiSelectOptions.
#### app.config.ts

```ts
provideKikitaUi({
  defaults: {
    size: 'sm',
    button: { shape: 'ghost', size: 'md' },
    select: { clearable: true, maxVisibleChips: 2 },
    toast: { position: 'top-end', duration: 4000 },
  },
});
```

#### section.providers.ts

```ts
// A component, route or environment injector: applies to that subtree only
providers: [provideKuiDefaults({ button: { size: 'lg' } })];
```

### Layers and merging
The nearest value wins, and each level is merged over the defaults it inherits per component key and per property.

### Reactive values
Every property accepts a plain value or a Signal, and the whole defaults value may be a function that runs in an injection context.
#### app.config.ts

```ts
@Service()
class ThemeState {
  readonly shape = signal<KuiButtonShape>('solid');
}

provideKikitaUi({
  defaults: () => ({ button: { shape: inject(ThemeState).shape } }),
});
```

#### defaults.ts

```ts
const defaults = inject(KuiDefaults);

defaults.set('button', { shape: 'outline' }); // merges into this level's own layer
defaults.update('select', (current) => ({ clearable: !current?.clearable }));
defaults.get('button'); // Signal of the effective button options
```

### Global control size
defaults.size applies to every primitive with a size input when neither the local input nor the component key sets one.

### Clearable controls and tooltips
A few keys resolve through a chain with a shared field key.

### Overlays
Anchored overlays share the placement and offset options and add their own.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| popover | placement, offset, align, arrow, triggerType, hoverDelay | - | Built-in: bottom, 8, center, false, click, 100. |
| menu | placement, offset, menuAlign, minWidth | - | Built-in: bottom, 4, start, none. |
| dropdown | maxHeight, offset, closeOnSelect, panelWidth | - | Built-in: 240px, 4, true, anchor. |
| tooltip | triggerType, placement | - | Built-in: auto, top. |
| dialog | size, appearance, dismissable, closable | - | Per kuiDialog call. Built-in: md, default, true, true. |
| drawer | side, size, closeOnBackdropClick, closeOnEscape, closable | - | Built-in: right, md, true, true, true. |

### Calendars, time, carousel and pagination
These keys follow local input, then defaults, then the built-in default.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| calendar, calendarRange | size, flat, showWeekend, showFooter, showPrevNav, showNextNav | - | Built-in: global size, false, true, false, true, true. The two keys are separate and share KuiCalendarViewOptions. |
| timePicker | clearable, format, hourStep, minuteStep, secondStep, showSeconds | - | Built-in: true, the hour cycle of the locale, 1, 1, 1, false. The directive pushes them into its panel. |
| carousel | itemsPerView, loop, autoplay, autoplayInterval, showArrows, showDots, draggable | - | Built-in: 1, false, false, 4000, true, true, true. |
| pagination | variant, siblingCount, boundaryCount, pageSizeOptions | - | Built-in: compact, 1, 1, [10, 25, 50, 100]. |

### Other primitives
Every remaining primitive has a key. Each option resolves as local input, then defaults, then the built-in default; size follows the size chain above.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| badge, breadcrumbs, chip, emptyState, loader, segmented, table | size | - |  |
| input, textarea, checkbox, radio, switch, colorInput | size | - |  |
| numberInput | size, variant | - |  |
| slider, progress | size, color | - |  |
| accordion | size, mode, appearance | - |  |
| alert | size, shape, showIcon, closable | - |  |
| card | size, appearance | - |  |
| tabs | size, variant, orientation | - |  |
| stepper | size, orientation, linear, compact | - |  |
| tree | size, mode | - |  |
| group | size, orientation, collapsed, rounded | - |  |
| avatar, avatarGroup | size, shape (avatarGroup also max) | - |  |
| link | tone, underline | - |  |
| separator | appearance, orientation, spacing | - |  |
| skeleton | shape, animation | - |  |
| fileUpload | size, variant, mode | - |  |
| otpInput | size, mask, integerOnly | - |  |
| barChart, lineChart, donutChart, scatterChart | size, legend | - |  |

### Structural icons
The icons key replaces the glyphs components draw for themselves, one glyph per role or per component slot.
#### app.config.ts

```ts
provideKikitaUi({ defaults: { icons: { close: MY_CLOSE }, select: { chevronIcon: MY_CHEVRON } } });
```

### Migrating from the token API
The injection tokens are removed and the provider functions remain as deprecated wrappers until 3.0.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| kuiProvideButtonOptions({ button, iconButton }) | provideKuiDefaults({ button, iconButton }) | - | Deprecated wrapper, removed in 3.0. |
| kuiProvideFieldOptions(options) | provideKuiDefaults({ field: options }) | - | Deprecated wrapper, removed in 3.0. |
| kuiProvideSelectOptions(options) | provideKuiDefaults({ select: options }) | - | Deprecated wrapper, removed in 3.0. |
| kuiProvideComboboxOptions(options) | provideKuiDefaults({ combobox: options }) | - | Deprecated wrapper, removed in 3.0. |
| kuiProvideTooltipOptions(options) | provideKuiDefaults({ tooltip: options }) | - | Deprecated wrapper, removed in 3.0. |
| provideKuiToastOptions(options) | provideKuiDefaults({ toast: options }) | - | Deprecated wrapper, removed in 3.0. |
| provideKikitaUi({ tooltip }) | provideKikitaUi({ defaults: { tooltip } }) | - | Deprecated. |
| KuiButtonOptions { button, iconButton } | KuiButtonProviderOptions | - | Deprecated; KuiButtonOptions now describes one button (shape, appearance, size). |
| KuiButtonPrimitiveOptions | KuiButtonBaseOptions | - | Renamed. |
| KikitaUiDefaults | KuiComponentDefaults | - | Deprecated alias. |

---

<!-- route: /foundations/density -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/density.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Density

> Spacing and control density expectations for product UIs.

- Status: available
- Route: /foundations/density
- Package: @kikita-labs/ui@2.0.0

## Content

### Density values
The published package exposes a typed KuiDensity union for compact, regular, and comfortable experiences.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| compact | KuiDensity | - | Dense operational surfaces such as toolbars, tables, and high-frequency controls. |
| regular | KuiDensity | - | Default application density and the safest choice for documentation examples. |
| comfortable | KuiDensity | - | Touch-heavy or spacious contexts where larger hit areas matter more than density. |

### Global defaults
Set density through theme seeds. Use provideKikitaUi defaults.size for app-wide control size, not for density.
#### app.config.ts

```ts
import { DEFAULT_KUI_THEME, provideKikitaUi } from '@kikita-labs/ui';

provideKikitaUi({
  theme: {
    seeds: {
      ...DEFAULT_KUI_THEME.seeds,
      density: 'regular',
    },
  },
});
```

#### app.config.ts

```ts
import { provideKikitaUi } from '@kikita-labs/ui';

provideKikitaUi({
  defaults: {
    size: 'sm',
  },
});
```

### Control recommendations
Height follows the size cascade. Density rebinds horizontal padding and spacing rhythm only.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| Control height (xs / sm / md / lg) | 28px / 32px / 40px / 44px | - | Set by local size inputs, component providers, or provideKikitaUi defaults.size. Density does not affect height. |
| Button x padding | 8px / 12px / 16px | - | Horizontal control padding across compact, regular, and comfortable density. |

### Component tokens
Density rebinds the padding tokens below; height tokens resolve from data-kui-size instead.
#### density.css

```css
--kui-btn-px-compact
--kui-btn-px-regular
--kui-btn-px-comfortable
```

#### resolved.css

```css
--kui-control-height-xs
--kui-control-height-sm
--kui-control-height-md
--kui-control-height-lg
--kui-btn-height
--kui-btn-px
--kui-input-px
--kui-default-size
```

---

<!-- route: /foundations/forms -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/forms.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Forms

> Kikita UI is Signal Forms first: put the control directive and [formField] on the same element and wrap it in kui-field for the label, hint, error and required marker.

- Status: available
- Route: /foundations/forms
- Package: @kikita-labs/ui@2.0.0

## Content

### Signal Forms first
Place the Kikita control directive and the Angular Signal Forms formField binding on the same native element, then wrap it with kui-field when the UI needs a visible label, hint, error or required marker.
#### profile-form.ts

```ts
import { signal } from '@angular/core';
import { email, form, minLength, required } from '@angular/forms/signals';

const model = signal({
  email: '',
  project: '',
});

const profileForm = form(model, (path) => {
  required(path.email, { message: 'Email is required' });
  email(path.email, { message: 'Enter a valid email' });
  required(path.project, { message: 'Project is required' });
  minLength(path.project, 3, { message: 'Use at least 3 characters' });
});
```

#### profile-form.html

```html
<form [formRoot]="profileForm">
  <kui-field label="Email" hint="Use your work email">
    <input kuiInput type="email" [formField]="profileForm.email" />
  </kui-field>
</form>
```

### Field-first pattern
kui-field owns the label, hint, error, required marker and aria-describedby wiring, so do not write them by hand for normal field usage.
#### form.html

```html
<kui-field label="Label" hint="Optional helper text">
  <input kuiInput [formField]="form.field" />
</kui-field>
```

#### form.html

```html
<kui-field label="Notes" hint="Internal project notes">
  <textarea kuiTextarea [formField]="form.notes"></textarea>
</kui-field>

<kui-field label="Count" hint="Enter a value from 1 to 100">
  <input type="number" kuiNumberInput [formField]="form.count" />
</kui-field>

<kui-field label="Volume" hint="Use arrow keys, Home, and End">
  <input type="range" kuiSlider [formField]="form.volume" />
</kui-field>
```

### Custom field templates
Use projected marker directives only when the field needs custom template logic.
#### form.html

```html
<kui-field>
  <label kuiLabel>Email</label>
  <input kuiInput type="email" [formField]="profileForm.email" />
  <p kuiHint>Use your work email</p>

  @if (showEmailError()) {
    <p kuiError>Email is required</p>
  }
</kui-field>
```

### Controls that are not native elements
kui-segmented and kui-otp-input implement the Signal Forms control contract themselves, so formField goes on the component.
#### form.html

```html
<kui-field label="View">
  <kui-segmented [formField]="myForm.view">
    <button kuiSegment value="list">List</button>
    <button kuiSegment value="grid">Grid</button>
  </kui-segmented>
</kui-field>

<kui-field label="Verification code">
  <kui-otp-input [formField]="signInForm.code" />
</kui-field>
```

### Required and invalid state
How the field and its controls expose validation to assistive technology.

---

<!-- route: /foundations/installation -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/installation.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Installation

> Package installation and global stylesheet setup.

- Status: available
- Route: /foundations/installation
- Package: @kikita-labs/ui@2.0.0

## Content

### Package registry
Kikita UI is published under the @kikita-labs scope on the public npm registry. No registry configuration or auth token is required.
#### terminal

```bash
pnpm add @kikita-labs/ui
```

### Angular CLI setup
Use the package schematic when possible. It preserves existing style entries and configures the selected Angular project.
#### terminal

```bash
ng add @kikita-labs/ui
```

#### terminal

```bash
ng add @kikita-labs/ui --project my-app
```

### Manual setup
This docs app keeps the stylesheet in angular.json because that path is verified in a fresh Angular consumer build.
#### angular.json

```json
"styles": [
  "node_modules/@kikita-labs/ui/styles/kikita-ui.css",
  "src/styles.scss"
]
```

#### app.config.ts

```ts
import { type ApplicationConfig } from '@angular/core';
import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      scrollbars: 'styled',
    }),
  ],
};
```

### Schematic options
Use these options when a consumer app needs to control which parts of setup are written.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| --project | string | - | Targets a specific Angular project when the workspace contains multiple projects. |
| --skip-provider | boolean | - | Skips writing provideKikitaUi() when the app manages providers manually. |
| --skip-styles | boolean | - | Skips adding the package stylesheet to angular.json. |
| --theme | boolean | - | Writes the default theme seed configuration into provideKikitaUi(). Without it Kikita UI uses the same default theme internally and adds no theme code to the app. |

### Styles outside the CLI
When styles are managed outside Angular CLI, import the public style entrypoint once and register the provider by hand.
#### styles.css

```css
@import '@kikita-labs/ui/styles';
```

#### app.config.ts

```ts
import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig = {
  providers: [provideKikitaUi()],
};
```

### Icons and Content Security Policy
The default Lucide set is read at a pinned lucide-static version (1.51.0) and converted to glyph data, not inserted as trusted HTML.
#### app.config.ts

```ts
import {
  createKuiLucideResolver,
  provideKikitaUi,
  provideKuiIcons,
} from '@kikita-labs/ui';

// Serve the pinned lucide-static files yourself instead of reading them from the CDN.
export const appConfig = {
  providers: [
    provideKikitaUi({ icons: false }),
    provideKuiIcons(createKuiLucideResolver({ baseUrl: '/assets/lucide' })),
  ],
};
```

#### Content-Security-Policy

```text
connect-src 'self' https://cdn.jsdelivr.net
```
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| KUI_LUCIDE_STATIC_VERSION | '1.51.0' | - | Exact lucide-static version the default resolver reads. It changes only with a Kikita UI release. |
| createKuiLucideResolver | (options?: KuiLucideResolverOptions) => KuiIconResolver | - | Reads another lucide-static version or origin, for self-hosted icon files. |
| provideKuiIcons | (icons: KuiIconRegistry) => EnvironmentProviders | - | Registers named icons and resolvers for the injector it is provided in. |

### Upgrading from 1.x
Update the package and run the migration that ships with it. See the Migrating to 2.0 page for every breaking change.
#### terminal

```bash
ng update @kikita-labs/ui
```

#### terminal

```bash
ng update @kikita-labs/ui --migrate-only --from=1.8.0 --to=2.0.0
```

---

<!-- route: /foundations/internationalization -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/internationalization.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Internationalization

> Locale and messages are two independent settings: the locale formats dates, numbers and plurals, the messages translate the text the library owns.

- Status: available
- Route: /foundations/internationalization
- Package: @kikita-labs/ui@2.0.0

## Content

### Locale and messages
An application can change either one without the other: German dates with English labels, or French messages with the locale of the request. The library ships English only.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| Locale | locale | - | Month and weekday names, week start and weekend, date and time layout, numbers and plural rules. |
| Messages | messages | - | The text of the library: accessible names, visible words, placeholders, hints and announcements. |

### Quick start
Set the locale and a partial messages layer in the root provider. Only the keys you write change; every other key keeps its English default.
#### app.config.ts

```ts
import { provideKikitaUi, type KuiMessagesLayer } from '@kikita-labs/ui';

const german: KuiMessagesLayer = {
  pagination: { next: 'Weiter', previous: 'Zurueck' },
  calendar: { today: 'Heute' },
};

provideKikitaUi({ locale: 'de-DE', messages: german });
```

#### messages.ts

```ts
import { type KuiMessagesLayer } from '@kikita-labs/ui';

const german: KuiMessagesLayer = {
  pagination: {
    summary: ({ start, end, total }) => `${start}-${end} von ${total}`,
  },
};
```

### Follow the language at runtime
Pass a Signal or a function. The library re-renders its labels when the signal changes and nothing is recreated.
#### app.config.ts

```ts
provideKikitaUi({
  locale: () => inject(LanguageService).locale, // Signal<string>
  messages: () => inject(LanguageService).messages, // Signal<KuiMessagesLayer>
});
```

#### language.service.ts

```ts
inject(KuiI18n).setLocale('fr-FR');
inject(KuiI18n).setMessages(frenchMessages);
```

#### app.config.ts

```ts
provideKikitaUi({ locale: () => inject(LOCALE_ID) });
```

### Override a subtree or one instance
Levels and per-instance inputs let one part of the page differ without affecting another.
#### booking.component.ts

```ts
@Component({
  providers: [
    provideKuiI18n({ locale: 'fr-FR', messages: { calendar: { today: "Aujourd'hui" } } }),
  ],
})
export class BookingComponent {}
```

### Writing a translation
Copy KUI_ENGLISH_MESSAGES, translate the values and let the compiler check every key.
#### messages.ts

```ts
fileUpload: {
  tooMany: ({ max }, { formatNumber, plural }) =>
    `Maksymalnie ${formatNumber(max)} ${plural(max, { one: 'plik', few: 'pliki', many: 'plikow', other: 'pliku' })}`,
},
```

#### app.config.ts

```ts
provideKikitaUi({
  messages: () => {
    const transloco = inject(TranslocoService);
    const catalogue = toSignal(transloco.selectTranslateObject('kui'));
    return computed(() => toKuiMessages(catalogue()));
  },
});
```
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| ctx.locale | string | - | The resolved locale tag. |
| ctx.formatNumber(n) | string | - | A number with the grouping and decimal separators of the locale, in Latin digits. |
| ctx.plural(n, { one, ... }) | string | - | The form Intl.PluralRules selects: zero, one, two, few, many or other. |

### Where the locale comes from
The locale is resolved from the nearest source and checked against the runtime Intl.

### What the locale controls
Each area below follows the resolved locale.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| Calendar | locale | - | Month and weekday names; heading order; first day and weekend from Intl.Locale getWeekInfo (static fallback for older engines); every day button named with its full date. |
| Date Picker | locale | - | Field order and separator of the numeric date (10/03/2026, 03.10.2026). Parsing reads digit groups and needs a four digit year; format pins a layout. |
| Time Picker | locale | - | Default 12 or 24 hour cycle, the separator, the day period text and its position; typing accepts the locale AM/PM text and ASCII am/pm. |
| Pagination, Carousel, Media Viewer, OTP | locale | - | Counts and positions are formatted with the locale. |
| Charts | locale | - | The default value format is the compact notation of the locale (1.2K in English, 1,5 Mio. in German). |
| File Upload | locale | - | Sizes use Intl units (2.5 MB, 340 kB) and progress uses a percent format. |

### Accessibility and testing
Accessible names come from the same messages as the visible text.

### Reference
The public API of the locale and messages layer.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| provideKikitaUi({ locale, messages }) | Provider | - | Root locale and messages. |
| provideKuiI18n({ locale, messages }) | Provider[] | - | A level for a subtree. |
| provideKuiLocale(locale) | Provider[] | - | Locale only. Accepts a tag, a Signal or a function. |
| provideKuiMessages(messages) | Provider[] | - | Messages only. |
| KuiI18n | service | - | locale, messages, context, get(group), setLocale and setMessages. |
| KuiMessages, KuiMessagesLayer | types | - | The full message map and its partial override. |
| KuiMessageContext, KuiPluralForms | types | - | Helpers passed to function messages. |
| KUI_ENGLISH_MESSAGES | KuiMessages | - | The complete English pack. |
| KUI_LOCALE | InjectionToken | - | Root locale source: request, transfer state, navigator. |
| getKuiCalendarLocaleText(locale) | function | - | Month and weekday names, first day and weekend for a locale (pure, no cache). |

---

<!-- route: /foundations/migration -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/migration.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Migrating to 2.0

> Every breaking change of @kikita-labs/ui 2.0: renamed exports, provider defaults, locale and messages, icons, tokens, component behaviour and the charts.

- Status: available
- Route: /foundations/migration
- Package: @kikita-labs/ui@2.0.0

## Content

### Automatic migration
Update the package and run the migration that ships with it. It renames identifiers only and never touches strings, comments or templates.
#### terminal

```bash
ng update @kikita-labs/ui
```

#### terminal

```bash
ng update @kikita-labs/ui --migrate-only --from=1.8.0 --to=2.0.0
```

#### terminal

```bash
git grep -nE "Kui[A-Za-z]+(Component|Directive)\b|KuiToastService|kuiProvideLocale"
```

### Naming rule and renamed exports
An Angular class is named for what it is, not for the construct that declares it. There are no compatibility aliases: the old names no longer exist in 2.0.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| KuiButtonDirective | KuiButton | - | A directive loses its suffix. |
| KuiTabsComponent | KuiTabs | - | A component loses its suffix. |
| KuiToastService | KuiToast | - | A service loses its suffix; kuiToast() still returns it. |
| KuiSelectCellComponent | KuiSelectCell | - | Table selection parts are renamed the same way. |
| kuiProvideLocale | provideKuiLocale | - | Returns Provider[] and accepts a Signal. |

### Provider defaults
Component defaults moved from six injection tokens to one mechanism, KuiDefaults. A nested provider now merges with its parent per property.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| KUI_BUTTON_OPTIONS, KUI_FIELD_OPTIONS, KUI_SELECT_OPTIONS | provideKuiDefaults({ button, field, select }) | - | The injection tokens are removed. |
| KUI_COMBOBOX_OPTIONS, KUI_TOOLTIP_OPTIONS, KUI_TOAST_OPTIONS | provideKuiDefaults({ combobox, tooltip, toast }) | - | The injection tokens are removed. |
| kuiProvideButtonOptions, kuiProvideFieldOptions, kuiProvideSelectOptions | provideKuiDefaults | - | Deprecated, forward to provideKuiDefaults, removed in 3.0. |
| kuiProvideComboboxOptions, kuiProvideTooltipOptions, provideKuiToastOptions | provideKuiDefaults | - | Deprecated, forward to provideKuiDefaults, removed in 3.0. |
| provideKikitaUi({ tooltip }) | provideKikitaUi({ defaults: { tooltip } }) | - | Deprecated. |
| KikitaUiDefaults | KuiComponentDefaults | - | Deprecated alias, removed in 3.0. |
| KuiButtonOptions as { button, iconButton } | KuiButtonProviderOptions | - | KuiButtonOptions now describes one button. |

### Locale and messages
All text the library owns is a typed message with an English default.

### Icons
Structural icons are replaceable data, and the Lucide set is read at a pinned version.

### Component behaviour
Behaviour that differs from 1.x. Each item names the component, so search this list for the ones you use.

### Packaging and styles
Style delivery changed, and field and icon now need the shared stylesheet like every other component.

### Token and style changes
Token names are kept with the exceptions below. Colour tokens have their own table on the Theming page.

### Chart behaviour
The four charts changed their keyboard model, tooltip data and sizing.

### Verify the upgrade
Work through these checks in order after the automatic migration.

---

<!-- route: /foundations/structural-icons -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/structural-icons.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Structural icons

> The small glyphs a component draws for itself, such as the cross on a dialog or the chevron on a select, as replaceable icon data.

- Status: available
- Route: /foundations/structural-icons
- Package: @kikita-labs/ui@2.0.0

## Content

### Replace a glyph
Structural icons are not the icons you pass to kui-icon by name. They never touch the icon registry or the network, they render on the server, and you can replace them for the whole app or for one subtree without changing a template.
#### close-icon.ts

```ts
import type { KuiIconGlyph } from '@kikita-labs/ui';

export const CIRCLE_X: KuiIconGlyph = {
  node: [
    ['circle', { cx: 12, cy: 12, r: 10 }],
    ['path', { d: 'm15 9-6 6' }],
    ['path', { d: 'm9 9 6 6' }],
  ],
};
```

#### app.config.ts

```ts
provideKikitaUi({ defaults: { icons: { close: CIRCLE_X, remove: CIRCLE_X } } });
```

#### section.providers.ts

```ts
providers: [provideKuiDefaults({ icons: { close: CIRCLE_X } })];
```

### Precedence
A role changes every component without a more specific override; a component slot changes only that component.

### Roles
defaults.icons takes one glyph per role. Roles are named for what the icon does, not for its shape: one cross is close on a dialog, remove on a chip and clear in a field.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| close | role | - | Dialog, Drawer, Media Viewer, Toast and Alert close buttons. |
| remove | role | - | Chip remove button (also the chips of a multiple Select) and File Upload remove button. |
| clear | role | - | Clear button of Select, Combobox, Date Picker and Time Picker, and the Command Palette search clear. |
| pickerChevron | role | - | Options toggle of Select, Combobox, Date Picker, Time Picker and Color Input. |
| previous, next | role | - | Previous and next page, month, slide or tab group (Pagination, Calendar, Calendar Range, Carousel, Tabs, Media Viewer). |
| first, last | role | - | First and last page buttons of Pagination. |
| disclosure | role | - | Expand control of Accordion items and Tree nodes; the rotation stays CSS. |
| separator | role | - | Breadcrumb separator. |
| check | role | - | Completed Stepper step and finished File Upload item. |
| statusInfo, statusSuccess, statusWarning, statusDanger | role | - | Status mark of Alert and Toast, and the warning mark of a non-default Confirm dialog. |
| externalLink | role | - | Mark after an external kuiLink. |

### Component slots
A component slot beats the role. Slots live in the options interface of the component, so a typo is a type error.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| dialog, drawer | closeIcon | - | Close button. |
| alert, toast | closeIcon | - | Close button. |
| chip, fileUpload | removeIcon | - | Remove button. |
| select, combobox, datePicker, timePicker | chevronIcon, clearIcon | - | Options toggle and clear button. |
| colorInput | chevronIcon | - | Options toggle. |
| calendar, calendarRange, carousel, tabs | previousIcon, nextIcon | - | Step controls. |
| pagination | firstIcon, previousIcon, nextIcon, lastIcon | - | Step controls. |
| accordion, tree | disclosureIcon | - | Expand control. |
| breadcrumbs | separatorIcon | - | Separator. |
| link | externalIcon | - | Mark after an external link. |

### Glyph data
An icon is plain data in the icon-node layout of Lucide, so an icon from the Lucide packages can be used as is.
#### glyph.ts

```ts
interface KuiIconGlyph {
  readonly node: readonly (readonly [
    tag: string,
    attributes: Record<string, string | number | undefined>,
  ])[];
  readonly viewBox?: string; // default '0 0 24 24'
}
```
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| Elements | path, line, polyline, polygon, circle, ellipse, rect | - | Any other element invalidates the glyph. |
| Attributes | geometry and paint | - | Geometry (d, cx, cy, r, rx, ry, x, y, x1, y1, x2, y2, width, height, points) and paint (fill, fill-opacity, fill-rule, clip-rule, stroke, stroke-opacity, stroke-linecap, stroke-linejoin, stroke-miterlimit, stroke-dasharray, stroke-dashoffset, opacity, transform). Everything else is ignored. |
| Values | strings and numbers | - | Values containing url(, <, > or javascript: are ignored. |
| Line weight | stroke-width, vector-effect | - | Not accepted; the stroke tokens own them. |
| Filled shapes | fill and stroke none | - | Set fill and stroke: none on the element, as the built-in play glyph does. |
| Invalid override | ignored | - | The next level of the precedence chain is used. In development mode the first use of an invalid glyph logs a warning. |

### Stroke width
Two public CSS custom properties control the line of structural icons and of stroke-based kui-icon content. Set them on the root or on any subtree.
#### styles.css

```css
:root {
  --kui-icon-stroke-width: 1.5; /* thinner icons everywhere */
}
```

#### icon.html

```html
<kui-icon name="settings" size="96" [strokeWidth]="1.5" absoluteStrokeWidth />
```
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| --kui-icon-stroke-width | a number in glyph-grid units | - | Built-in glyphs default to the weight of their call site (between 1.5 and 2.5); content icons keep the weight of their own markup until the token is set. |
| --kui-icon-vector-effect | none \| non-scaling-stroke | - | non-scaling-stroke keeps the stroke the same number of pixels at any icon size. The default is none. |

### Accessibility, security and server rendering
Structural icons are decorative plain template output.

### Not supported
Use a subtree and provideKuiDefaults for per-instance needs.

---

<!-- route: /foundations/theming -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/theming.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Theming

> Theme provider setup and theme customization basics.

- Status: available
- Route: /foundations/theming
- Package: @kikita-labs/ui@2.0.0

## Content

### Runtime contract
The public theming contract is CSS variables. The theme pipeline starts with seed tokens and ends in component-level tokens.
#### theme-pipeline.txt

```text
seed tokens -> OKLCH palettes -> semantic tokens -> component tokens
```

#### index.html

```html
<html data-kui-theme="dark"></html>
```

### Angular provider
Use provideKikitaUi() for the default theme and optional root configuration.
#### app.config.ts

```ts
import { type ApplicationConfig } from '@angular/core';
import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [provideKikitaUi()],
};
```

#### app.config.ts

```ts
provideKikitaUi({
  scrollbars: 'styled',
});
```

### Overriding tokens
Where you set a token decides how far it reaches. Components read semantic or component tokens, never palette or seed variables.
#### billing.css

```css
.billing-panel {
  --kui-btn-danger-bg: oklch(0.5 0.2 25);
  --kui-btn-danger-bg-hov: oklch(0.44 0.2 25);
}
```
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| A seed in provideKikitaUi({ theme }) | whole theme | - | Palette, semantic roles and literal component tokens are regenerated for every element. |
| A semantic token on any element | element and below | - | --kui-color-danger-fill on an element restyles that element and everything below it; on the root it changes the whole page. |
| A component token on any element | element and below | - | --kui-btn-danger-bg restyles that one component part for the element and everything below it. |
| A palette step or a type role alias | set globally | - | Not reliable on an element: semantic tokens and --kui-type-* are resolved from them on the root, so set them there. |

### Defaults, layers and density
The default theme works from CSS alone, and your own variables always win over the generated ones.

### Contrast profiles
WCAG 1.4.11 asks for 3:1 on the boundary of a control only where that boundary identifies it. A contrast profile re-points the neutral roles that draw it.
#### app.config.ts

```ts
import { DEFAULT_KUI_THEME, provideKuiTheme } from '@kikita-labs/ui';

provideKuiTheme({ ...DEFAULT_KUI_THEME, contrast: 'soft' });
```

#### contrast.ts

```ts
document.documentElement.setAttribute('data-kui-contrast', 'strict');
```
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| KuiThemeContrast | 'strict' \| 'soft' | - | Contrast profile name and the value of the data-kui-contrast attribute. |
| DEFAULT_KUI_THEME_CONTRAST | KuiThemeContrast | - | Profile a theme uses when the contrast option is not set. |
| KuiGeneratedContrast | { name; media?; light; dark } | - | Variables one profile changes relative to the default, emitted as [data-kui-contrast] rules and an optional media query. |

### Shared behaviour tokens
A few tokens change one behaviour for the whole library. Set them on the root or on any subtree.
#### styles.css

```css
:root {
  --kui-opacity-disabled: 0.4; /* every disabled control, option and cell */
  --kui-focus-ring-width: 2px; /* standalone controls; parts use --kui-focus-ring-width-sm */
  --kui-duration-base: 120ms; /* enter animations and control state changes */
  --kui-color-scrim: oklch(0 0 0 / 0.65); /* behind Dialog, Drawer and Command Palette */
}
```

### Migrating to the colour roles
The 2.x colour system keeps every public token name, so an existing theme keeps working. Move to the new roles when you next touch a custom component.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| --kui-color-on-fill on a solid fill | --kui-color-<role>-on-fill | - | White or near-black, whichever reaches 4.5:1 on that fill. |
| --kui-color-<role>-fill as text or an icon colour | --kui-color-<role>-text | - | 4.5:1 on every surface. |
| --kui-color-<role>-fill as a border, outline, bar or mark | --kui-color-<role>-indicator | - | 3:1 on every light surface. |
| --kui-color-border on an interactive control | --kui-color-border-control | - | A 3:1 boundary at rest; the hover value is --kui-color-border-control-hover. |
| --kui-color-primary-focus-ring or a box-shadow ring | a 2px outline in --kui-color-focus | - | Visible in forced-colors mode and 3:1. |
| --kui-color-text-disabled on placeholders | --kui-color-text-placeholder | - | 4.5:1; disabled text stays for disabled controls. |

### Custom seeds
Seed values are the stable way to customize generated palettes and shared scales.
#### app.config.ts

```ts
provideKikitaUi({
  theme: {
    seeds: {
      color: {
        primary: 'oklch(0.52 0.25 285)',
        neutral: 'oklch(0.5 0.01 80)',
        success: 'oklch(0.54 0.16 145)',
        warning: 'oklch(0.74 0.16 75)',
        danger: 'oklch(0.54 0.22 25)',
        info: 'oklch(0.58 0.16 215)',
      },
      radius: 8,
      density: 'regular',
    },
  },
});
```

### Theme utilities
These public functions can generate CSS variables for docs, visual tests, or non-Angular tooling.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| createKuiTheme | (options?: KuiThemeOptions) => KuiGeneratedTheme | - | Generates a theme object from seed options. |
| createKuiThemeVariableMap | (theme, mode?) => KuiCssVariableMap | - | Flattens a generated theme into CSS variable names and values. |
| createKuiThemeCssText | (theme, selector, mode?) => string | - | Serializes variables for a selector. |
| createKuiThemeStyleSheet | (theme) => string | - | Serializes light and dark theme CSS for tooling or docs output. |

---

<!-- route: /foundations/tokens -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/tokens.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Tokens

> Design token categories exposed through Kikita CSS variables.

- Status: available
- Route: /foundations/tokens
- Package: @kikita-labs/ui@2.0.0

## Content

### Token layers
Public CSS variables use the --kui-* prefix and flow through predictable layers.
#### token-layers.txt

```text
seed -> palette -> semantic -> component
```

#### palette.css

```css
--kui-primary-1 ... --kui-primary-12
--kui-neutral-1 ... --kui-neutral-12
--kui-success-1 ... --kui-success-12
--kui-warning-1 ... --kui-warning-12
--kui-danger-1 ... --kui-danger-12
--kui-info-1 ... --kui-info-12
```

#### semantic.css

```css
--kui-color-bg
--kui-color-surface
--kui-color-border
--kui-color-text
--kui-color-primary-fill
--kui-color-focus
```

### Color seeds
Required color seeds generate the palette and semantic token layers.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| --kui-seed-primary | oklch(0.52 0.25 285) | - | Brand and action color. |
| --kui-seed-neutral | oklch(0.5 0.01 80) | - | Surface, border, and text base. |
| --kui-seed-success | oklch(0.54 0.16 145) | - | Positive state. |
| --kui-seed-warning | oklch(0.56 0.15 65) | - | Caution state. |
| --kui-seed-danger | oklch(0.54 0.22 25) | - | Error or destructive state. |
| --kui-seed-info | oklch(0.53 0.14 215) | - | Informational state. |

### Fill, indicator and text roles
Every accent (primary, success, warning, danger, info) has these roles. A fill is a background only: text and icons read -text, and borders and marks read -indicator.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| --kui-color-<role>-fill | solid background | - | The seed in both modes, slightly corrected when no text colour reaches 4.5:1 on it. |
| --kui-color-<role>-on-fill | text and icons on the fill | - | White or near-black, whichever reads better (at least 4.5:1). Generated. |
| --kui-color-<role>-fill-away | away colour | - | Black when the on-fill is light, white when it is dark. Generated. |
| --kui-color-<role>-fill-hover, -fill-active | hover and pressed fill | - | The fill mixed with the away colour (light 18% and 36%, dark 28% and 8% toward black), so contrast never drops. |
| --kui-color-<role>-indicator | border, outline, mark | - | The fill when it reaches 3:1 on every surface of the mode, otherwise step 7 (light) or step 5 (dark). Generated. |
| --kui-color-<role>-text | text and icon on a surface | - | At least 4.5:1: step 8 in light mode and step 4 in dark mode. |
| --kui-color-<role>-soft-bg, -soft-text, -soft-border | tinted surface | - | Tinted background with its text and border. |
| --kui-color-border-control, -hover | control boundary | - | The boundary of a control that the border alone identifies, such as an input or a checkbox: at least 3:1 in the strict profile, quieter in soft. --kui-color-border and --kui-color-border-strong stay for dividers and cards. |
| --kui-color-text-placeholder | placeholder text | - | 4.5:1 on every surface. --kui-color-text-disabled is only for disabled controls. |
| --kui-color-state-hover, -state-active | translucent text layers | - | 8% and 14% of the text colour for the hover and pressed fill of list items, menu items, calendar days, tabs and ghost buttons, so a hover never disappears on any surface. |
| --kui-color-focus | 2px focus outline colour | - | Defaults to the primary indicator. |
| --kui-color-scrim, -scrim-strong, -on-scrim | overlay layers | - | Black at 50% behind Dialog, Drawer and Command Palette, black at 92% behind the fullscreen Media Viewer, and white text over a scrim. |

### Common scales
Radius and spacing scales are shared by component tokens and docs layout primitives.
#### radius.css

```css
--kui-radius-none: 0;
--kui-radius-xs: 4px;
--kui-radius-sm: 6px;
--kui-radius-md: 8px;
--kui-radius-lg: 10px;
--kui-radius-xl: 14px;
--kui-radius-full: 9999px;
```

#### spacing.css

```css
--kui-space-1: 4px;
--kui-space-2: 8px;
--kui-space-3: 12px;
--kui-space-4: 16px;
--kui-space-5: 20px;
--kui-space-6: 24px;
--kui-space-8: 32px;
--kui-space-12: 48px;
--kui-space-16: 64px;
```

### Shared tokens
A few global tokens are the single knob for a behaviour the whole library shares. A component hook is read first and defaults to the global token in the CSS of the component, so a value set on any ancestor wins.
#### styles.css

```css
:root {
  --kui-opacity-disabled: 0.4;
  --kui-focus-ring-width: 2px;
  --kui-duration-base: 120ms;
}
```
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| --kui-duration-fast | 100ms | - | Hover and colour changes. |
| --kui-duration-quick | 120ms | - | Exit animations. |
| --kui-duration-base | 160ms | - | Enter animations and control state changes. |
| --kui-duration-normal | 200ms | - | Moving indicators, backdrops and progress. |
| --kui-ease, --kui-ease-exit | cubic-bezier(0.16, 1, 0.3, 1) and cubic-bezier(0.4, 0, 1, 1) | - | Entering and moving, and leaving (shorter and accelerating, never lingering). |
| --kui-focus-ring-width | 3px | - | Standalone controls: Button, Icon Button, Checkbox, Radio, Switch, Tab, Segmented, Card, Chip, Avatar, Table sort and selection. |
| --kui-focus-ring-width-sm | 2px | - | Parts inside a composite: links, calendar and picker cells, rows, options, field actions, chip remove. |
| --kui-focus-ring-offset, --kui-focus-ring-offset-inset | 2px and -2px | - | Gap between the element and an outer ring, and the ring drawn inside rows, cells and options in a scroll container. |
| --kui-opacity-disabled | 0.5 | - | Dims every disabled control, row, cell and option. The hooks --kui-btn-disabled-opacity, --kui-chip-disabled-opacity and --kui-field-action-disabled-opacity override it for one component. |
| --kui-border-width-hairline, -thick, -heavy | 1px, 1.5px, 2px | - | Borders and dividers, the today marker and thick separators, and indicator bars, step circles, dashed dropzone borders and spinner strokes. |

### Icon tokens
Two public tokens control the line of structural icons and of stroke-based kui-icon content. Set them on the root or on any subtree.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| --kui-icon-stroke-width | a number in glyph-grid units | - | Structural icons default to the weight of their call site (1.5 to 2.5); kui-icon keeps the weight of the icon itself. |
| --kui-icon-vector-effect | none \| non-scaling-stroke | - | none lets the stroke scale with the icon; non-scaling-stroke keeps it the same number of pixels. |

### Defaults that moved into CSS
These tokens are still valid hooks: set one on an element or an ancestor to override a single component. They are no longer defined on the root, because a literal copy of a global value there would shadow a change to the global token.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| --kui-btn-focus-ring-w, --kui-checkbox-focus-ring-w, --kui-radio-focus-ring-w, --kui-switch-focus-ring-w, --kui-avatar-focus-ring-w, --kui-chip-focus-ring-width | --kui-focus-ring-width | - | Focus ring width hooks. |
| --kui-chip-remove-focus-ring-width, --kui-field-action-focus-ring-width | --kui-focus-ring-width-sm | - | Focus ring width hooks of parts inside a composite. |
| --kui-btn-focus-ring-off, --kui-checkbox-focus-ring-off, --kui-radio-focus-ring-off, --kui-switch-focus-ring-off, --kui-avatar-focus-ring-off | --kui-focus-ring-offset | - | Focus ring offset hooks. |
| --kui-btn-disabled-opacity, --kui-chip-disabled-opacity, --kui-field-action-disabled-opacity | --kui-opacity-disabled | - | Disabled opacity hooks; the chip one was 0.4. |
| --kui-dialog-backdrop, --kui-drawer-backdrop-bg, --kui-command-backdrop-bg | --kui-color-scrim | - | Backdrop colour hooks. |
| --kui-btn-font-weight, --kui-tab-font-weight, --kui-seg-font-weight, --kui-menu-item-font-weight | --kui-font-weight-medium | - | Medium weight hooks. |
| --kui-tab-font-weight-active, --kui-seg-font-weight-active, --kui-badge-font-weight, --kui-avatar-font-weight, --kui-chip-font-weight, --kui-field-label-weight, --kui-menu-group-header-font-weight, --kui-drawer-title-weight, --kui-breadcrumb-font-weight-current, --kui-empty-title-weight | --kui-font-weight-semibold | - | Semibold weight hooks; the empty state title was 650. |
| --kui-chip-avatar-font-weight | --kui-font-weight-bold | - | Bold weight hook. |

### Removed in 2.0
These generated tokens are gone and nothing in Kikita UI reads them any more. Set the replacement. 322 component tokens that only mapped a role onto another token are no longer generated either; each component states its default in its own CSS.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| --kui-btn-bg | --kui-btn-solid-bg | - | Button background. |
| --kui-btn-bg-hover | --kui-btn-solid-bg-hov | - | Button hover background. |
| --kui-btn-bg-active | --kui-btn-solid-bg-act | - | Button pressed background. |
| --kui-btn-color | --kui-btn-solid-fg | - | Button text colour. |
| --kui-btn-secondary-bg | --kui-btn-soft-bg | - | Soft button background. |
| --kui-btn-secondary-bg-hover | --kui-btn-soft-bg-hov | - | Soft button hover background. |
| --kui-btn-secondary-color | --kui-btn-soft-fg | - | Soft button text colour. |
| --kui-btn-outline-bg-hover | --kui-btn-outline-bg-hov | - | Outline button hover background. |
| --kui-btn-ghost-bg-hover | --kui-btn-ghost-bg-hov | - | Ghost button hover background. |
| --kui-btn-focus-ring-width | --kui-btn-focus-ring-w | - | Button focus ring width. |
| --kui-btn-focus-ring-offset | --kui-btn-focus-ring-off | - | Button focus ring offset. |
| --kui-btn-focus-ring | outline from --kui-btn-focus-ring-w and -color | - | Button focus ring shadow. |
| --kui-select-bg | --kui-input-bg | - | Select background. |
| --kui-select-border | --kui-input-border | - | Select border. |
| --kui-select-border-hover | --kui-input-border-hover | - | Select hover border. |
| --kui-select-border-focus | --kui-input-border-focus | - | Select focus border. |
| --kui-select-border-error | --kui-input-border-error | - | Select error border. |
| --kui-select-radius | --kui-input-radius | - | Select corner radius. |

---

<!-- route: /foundations/typography -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/foundations/typography.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Typography

> Semantic type-role classes, text tones, and the kuiText directive.

- Status: available
- Route: /foundations/typography
- Package: @kikita-labs/ui@2.0.0

## Content

### Import
The CSS classes ship through the main stylesheet. Import the directive only when templates should bind variant or tone.
#### angular.json

```json
"styles": [
  "node_modules/@kikita-labs/ui/styles/kikita-ui.css",
  "src/styles.scss"
]
```

#### typography-example.ts

```ts
import { KuiText } from '@kikita-labs/ui';
```

### Usage
Decorate native text elements. Typography classes and kuiText change presentation without replacing semantic HTML.
#### typography-example.html

```html
<section aria-labelledby="project-title">
  <p class="kui-overline kui-text-primary">Project profile</p>
  <h2 id="project-title" class="kui-heading-lg kui-text-default">Workspace settings</h2>
  <p class="kui-body kui-text-muted">Manage members, billing, and integrations.</p>
  <small class="kui-caption kui-text-muted">Last updated 2 minutes ago</small>
  <p class="kui-body-sm kui-text-danger">Slug is already used by another workspace.</p>
  <p class="kui-body-sm">
    Current slug: <code class="kui-code">workspace.slug</code>
  </p>
</section>
```

#### typography-directive-example.html

```html
<section aria-labelledby="project-title">
  <p kuiText variant="overline" tone="primary">Project profile</p>
  <h2 id="project-title" kuiText variant="heading-lg">Workspace settings</h2>
  <p kuiText variant="body" tone="muted">Manage members, billing, and integrations.</p>
  <small kuiText variant="caption" tone="muted">Last updated 2 minutes ago</small>
  <p kuiText variant="body-sm" tone="danger">Slug is already used by another workspace.</p>
  <p kuiText variant="body-sm">
    Current slug: <code class="kui-code">workspace.slug</code>
  </p>
</section>
```

### Type roles
Choose the role that matches the text's purpose, then keep the native element semantic. Each role resets margin to 0; control vertical spacing explicitly with gap or layout primitives instead of relying on the host tag's default margin.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| .kui-display | h1 | - | Rare docs or specification page title. |
| .kui-heading-lg | h1 \| h2 | - | Main page or top-level section title. |
| .kui-heading-md | h2 \| h3 | - | Panel, dialog, or drawer title. |
| .kui-heading-sm | h3 \| h4 | - | Compact section, card, or table group title. |
| .kui-title | h4 \| h5 \| span | - | Small emphasized UI title. |
| .kui-body-lg | p | - | Relaxed paragraph text where space allows. |
| .kui-body | p | - | Default product UI body text. |
| .kui-body-sm | p \| span | - | Dense descriptions and table adjunct text. |
| .kui-caption | small \| span | - | Hints, metadata, helper text, and timestamps. |
| .kui-overline | span | - | Optional uppercase group label. Use sparingly. |
| .kui-code | code \| span | - | Inline monospace code and token text. |

### Tone utilities
Tone utilities only set color. Pair status color with clear visible text when the state matters.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| .kui-text-default | default | - | Normal foreground text color. |
| .kui-text-muted | muted | - | Secondary copy, descriptions, and metadata. |
| .kui-text-disabled | disabled | - | Unavailable copy paired with a disabled control or state. |
| .kui-text-primary | primary | - | Brand or primary action emphasis. |
| .kui-text-success | success | - | Positive status text paired with visible status copy. |
| .kui-text-warning | warning | - | Caution status text paired with visible status copy. |
| .kui-text-danger | danger | - | Error or destructive status text paired with visible status copy. |

### Directive API
The kuiText directive is convenience sugar over the same public class contract.
| Name | Type | Default | Description |
| --- | --- | --- | --- |
| kuiText | attribute directive | - | Applies a semantic type role and text tone to a native text element. |
| variant | KuiTextVariant \| undefined | undefined | Semantic typography role applied by the directive. Falls back to defaults.typography.variant, then body. |
| tone | KuiTextTone \| undefined | undefined | Semantic text color tone applied by the directive. Falls back to defaults.typography.tone, then default. |
| KuiTextVariant | 'display' \| 'heading-lg' \| 'heading-md' \| 'heading-sm' \| 'title' \| 'body-lg' \| 'body' \| 'body-sm' \| 'caption' \| 'overline' \| 'code' | - | Public type for the directive variant input. |
| KuiTextTone | 'default' \| 'muted' \| 'disabled' \| 'primary' \| 'success' \| 'warning' \| 'danger' | - | Public type for the directive tone input. |

### Tokens
Each role exposes generated size, line-height, and weight tokens for theme-aware text scales.
#### typography-tokens.css

```css
--kui-type-heading-md-size
--kui-type-heading-md-line-height
--kui-type-heading-md-weight
```

#### font-weight-tokens.css

```css
--kui-font-weight-regular
--kui-font-weight-medium
--kui-font-weight-semibold
--kui-font-weight-bold
```

### Accessibility
Typography should strengthen native semantics rather than replace them.

---

<!-- route: /components/accordion -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/accordion.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/accordion.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Accordion

> Disclosure component for grouped expandable content.

- Status: available
- Route: /components/accordion
- Package: @kikita-labs/ui@2.0.0
- Import: KuiAccordion from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/accordion.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-accordion mode="exclusive" appearance="default" size="md">
  <kui-accordion-item id="general" header="General settings">
    Configure display and behavior options.
  </kui-accordion-item>

  <kui-accordion-item id="security" header="Security">
    Account security parameters.
  </kui-accordion-item>
</kui-accordion>
```

## Examples

Rendered at /components/accordion:

### appearance-accordion-example

#### appearance-accordion-example.html

```html
<div class="appearance-accordion-example">
  <div class="appearance-accordion-example__col">
    <p class="appearance-accordion-example__label">bordered</p>
    <kui-accordion appearance="bordered">
      <kui-accordion-item id="bordered-general" header="General settings">
        Configure display and behavior options.
      </kui-accordion-item>
      <kui-accordion-item id="bordered-security" header="Security">
        Account security parameters.
      </kui-accordion-item>
    </kui-accordion>
  </div>

  <div class="appearance-accordion-example__col">
    <p class="appearance-accordion-example__label">ghost</p>
    <kui-accordion appearance="ghost">
      <kui-accordion-item id="ghost-general" header="General settings">
        Configure display and behavior options.
      </kui-accordion-item>
      <kui-accordion-item id="ghost-security" header="Security">
        Account security parameters.
      </kui-accordion-item>
    </kui-accordion>
  </div>
</div>
```

#### appearance-accordion-example.ts

```ts
import { Component } from '@angular/core';

import { KuiAccordion, KuiAccordionItem } from '@kikita-labs/ui';

@Component({
  selector: 'app-appearance-accordion-example',
  imports: [KuiAccordion, KuiAccordionItem],
  templateUrl: './appearance-accordion-example.html',
  styleUrl: './appearance-accordion-example.scss',
})
export class AppearanceAccordionExample {}
```

#### appearance-accordion-example.scss

```scss
.appearance-accordion-example {
  display: flex;
  gap: var(--kui-space-6, 24px);
  flex-wrap: wrap;
}

.appearance-accordion-example__col {
  flex: 1;
  min-width: 220px;
}

.appearance-accordion-example__label {
  margin: 0 0 var(--kui-space-2, 8px);
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-xs-size, 11px);
  text-transform: uppercase;
  letter-spacing: 0.5px;
}
```

### basic-accordion-example

#### basic-accordion-example.html

```html
<kui-accordion mode="exclusive" appearance="default" size="md">
  <kui-accordion-item id="general" header="General settings">
    Configure display and behavior options.
  </kui-accordion-item>

  <kui-accordion-item id="notifications" header="Notifications">
    Manage push notifications and email digests.
  </kui-accordion-item>

  <kui-accordion-item id="security" header="Security">
    Account security parameters.
  </kui-accordion-item>
</kui-accordion>
```

#### basic-accordion-example.ts

```ts
import { Component } from '@angular/core';

import { KuiAccordion, KuiAccordionItem } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-accordion-example',
  imports: [KuiAccordion, KuiAccordionItem],
  templateUrl: './basic-accordion-example.html',
  styleUrl: './basic-accordion-example.scss',
})
export class BasicAccordionExample {}
```

#### basic-accordion-example.scss

```scss
:host {
  display: block;
}
```

### icon-accordion-example

#### icon-accordion-example.html

```html
<kui-accordion appearance="bordered">
  <kui-accordion-item id="settings" header="Settings">
    <ng-template kuiAccordionIcon>
      <kui-icon name="settings" />
    </ng-template>
    Settings content with a leading icon slot.
  </kui-accordion-item>

  <kui-accordion-item id="disabled" header="Archived project" [disabled]="true">
    This section is disabled and cannot be toggled.
  </kui-accordion-item>
</kui-accordion>
```

#### icon-accordion-example.ts

```ts
import { Component } from '@angular/core';

import { KuiAccordion, KuiAccordionIcon, KuiAccordionItem, KuiIcon } from '@kikita-labs/ui';

@Component({
  selector: 'app-icon-accordion-example',
  imports: [KuiAccordion, KuiAccordionIcon, KuiAccordionItem, KuiIcon],
  templateUrl: './icon-accordion-example.html',
  styleUrl: './icon-accordion-example.scss',
})
export class IconAccordionExample {}
```

#### icon-accordion-example.scss

```scss
:host {
  display: block;
}
```

### multi-accordion-example

#### multi-accordion-example.html

```html
<kui-accordion mode="multi" [(expandedItems)]="expanded">
  <kui-accordion-item id="profile" header="Profile">Profile content.</kui-accordion-item>
  <kui-accordion-item id="billing" header="Billing">Billing content.</kui-accordion-item>
  <kui-accordion-item id="team" header="Team members">Team content.</kui-accordion-item>
</kui-accordion>
```

#### multi-accordion-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiAccordion, KuiAccordionItem } from '@kikita-labs/ui';

@Component({
  selector: 'app-multi-accordion-example',
  imports: [KuiAccordion, KuiAccordionItem],
  templateUrl: './multi-accordion-example.html',
  styleUrl: './multi-accordion-example.scss',
})
export class MultiAccordionExample {
  protected readonly expanded = signal(['profile']);
}
```

#### multi-accordion-example.scss

```scss
:host {
  display: block;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| mode | 'exclusive' \| 'multi' | 'exclusive' | Toggle mode. exclusive keeps a single section open at a time; multi allows any number of sections open simultaneously. A plain input, not two-way bindable. Falls back to defaults.accordion.mode. |
| appearance | 'default' \| 'bordered' \| 'ghost' | 'default' | Container and divider treatment: default uses bottom borders between items, bordered wraps each item in its own bordered block, ghost has no borders. A plain input; falls back to defaults.accordion.appearance. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' | 'md' | Trigger height and text size. A plain input; falls back to defaults.accordion.size, then the global defaults.size. |
| expandedItems | string[] | [] | IDs of currently expanded items. The only mutable state of the accordion and the only two-way bindable one: use [(expandedItems)] or listen to (expandedItemsChange). |
| header | string | '' | kui-accordion-item: trigger label text. |
| id | string | auto-generated | kui-accordion-item: stable ID used for state tracking and ARIA wiring. The generated default is numbered per Angular application, so server-rendered ids match the browser. |
| disabled | boolean | false | kui-accordion-item: removes the trigger from tab order and prevents toggling the section. |
| kuiAccordionIcon | - | - | Marker directive for an ng-template projected into a kui-accordion-item trigger, before the label text. |
| provideKuiDefaults({ accordion }) | (defaults: KuiComponentDefaults) => Provider | - | Sets size, mode, appearance and disclosureIcon for a subtree; provideKikitaUi({ defaults }) does it for the whole application. |
| KuiAccordionOptions | interface | - | Shape of defaults.accordion. disclosureIcon takes precedence over defaults.icons.disclosure. |
| KuiAccordionMode / KuiAccordionAppearance | type aliases | - | Public unions of the mode and appearance values. |

## Accessibility

Each item renders a native button trigger with `aria-expanded`, `aria-controls`,
and a region body linked through `aria-labelledby`.

## Playground

Available at /components/accordion/playground.

---

<!-- route: /components/alert -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/alert.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/alert.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Alert

> Inline notification embedded in the page content flow.

- Status: available
- Route: /components/alert
- Package: @kikita-labs/ui@2.0.0
- Import: KuiAlert from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/alert.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-alert
  appearance="warning"
  title="Session expiring"
  message="Your access token expires in 3 days -- renew it in advance."
  actionLabel="Renew"
  (action)="renewSession()"
  (closed)="dismissed.set(true)"
/>
```

`kui-alert` is a controlled component: it never removes itself from the DOM. `(closed)` only
notifies the consumer when the close button is clicked, the same pattern `[kuiChip]`'s `(removed)`
uses -- conditionally render the alert (e.g. `@if (!dismissed())`) to actually hide it.

```ts
protected readonly dismissed = signal(false);
```

```html
@if (!dismissed()) {
<kui-alert message="Draft saved." (closed)="dismissed.set(true)" />
}
```

At least one of `title`/`message`/a projected `[kuiAlertMessage]` should be set.

## Examples

Rendered at /components/alert:

### basic-alert-example

#### basic-alert-example.html

```html
<div class="alert-example">
  <kui-alert appearance="neutral" title="Neutral" message="A plain notice without severity." />
  <kui-alert appearance="info" title="Info" message="We updated the terms of service." />
  <kui-alert appearance="success" title="Success" message="Your changes were saved." />
  <kui-alert appearance="warning" title="Warning" message="Your access token expires in 3 days." />
  <kui-alert
    appearance="danger"
    title="Danger"
    message="The upload failed. Check your connection."
  />
</div>
```

#### basic-alert-example.ts

```ts
import { Component } from '@angular/core';

import { KuiAlert } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-alert-example',
  imports: [KuiAlert],
  templateUrl: './basic-alert-example.html',
  styleUrl: './basic-alert-example.scss',
})
export class BasicAlertExample {}
```

#### basic-alert-example.scss

```scss
.alert-example {
  display: grid;
  gap: var(--kui-space-3);
}
```

### alert-shape-example

#### alert-shape-example.html

```html
<div class="alert-example">
  <kui-alert appearance="info" shape="soft" title="Soft" message="Tinted background and border." />
  <kui-alert appearance="info" shape="outline" title="Outline" message="Transparent background." />
  <kui-alert
    appearance="info"
    shape="solid"
    title="Solid"
    message="Saturated fill with on-fill text."
  />
  <kui-alert appearance="info" size="sm" title="Small" message="Tighter padding and gap." />
</div>
```

#### alert-shape-example.ts

```ts
import { Component } from '@angular/core';

import { KuiAlert } from '@kikita-labs/ui';

@Component({
  selector: 'app-alert-shape-example',
  imports: [KuiAlert],
  templateUrl: './alert-shape-example.html',
  styleUrl: './alert-shape-example.scss',
})
export class AlertShapeExample {}
```

#### alert-shape-example.scss

```scss
.alert-example {
  display: grid;
  gap: var(--kui-space-3);
}
```

### alert-action-example

#### alert-action-example.html

```html
<div class="alert-example">
  @if (!dismissed()) {
    <kui-alert
      appearance="warning"
      title="Session expiring"
      message="Your access token expires in 3 days. Renewed {{ renewals() }} times."
      actionLabel="Renew"
      (action)="renew()"
      (closed)="dismissed.set(true)"
    />
  } @else {
    <button kuiButton shape="outline" type="button" (click)="restore()">
      Show the alert again
    </button>
  }
</div>
```

#### alert-action-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiAlert, KuiButton } from '@kikita-labs/ui';

@Component({
  selector: 'app-alert-action-example',
  imports: [KuiAlert, KuiButton],
  templateUrl: './alert-action-example.html',
  styleUrl: './alert-action-example.scss',
})
export class AlertActionExample {
  protected readonly dismissed = signal(false);
  protected readonly renewals = signal(0);

  protected renew(): void {
    this.renewals.update((count) => count + 1);
  }

  protected restore(): void {
    this.dismissed.set(false);
  }
}
```

#### alert-action-example.scss

```scss
.alert-example {
  display: grid;
  gap: var(--kui-space-3);
  justify-items: start;
}

.alert-example kui-alert {
  inline-size: 100%;
}
```

### alert-custom-content-example

#### alert-custom-content-example.html

```html
<kui-alert appearance="danger" [closable]="false">
  <kui-icon kuiAlertIcon name="cloud-off" />
  <span kuiAlertTitle>Upload failed <span kuiBadge appearance="danger">retrying</span></span>
  <p kuiAlertMessage>Check your connection and <a href="#retry">try again</a>.</p>
  <div kuiAlertActions>
    <button kuiButton shape="ghost" size="xs" type="button">Retry</button>
    <button kuiButton shape="ghost" size="xs" type="button">Dismiss</button>
  </div>
</kui-alert>
```

#### alert-custom-content-example.ts

```ts
import { Component } from '@angular/core';

import {
  KuiAlert,
  KuiAlertActions,
  KuiAlertIcon,
  KuiAlertMessage,
  KuiAlertTitle,
  KuiBadge,
  KuiButton,
  KuiIcon,
} from '@kikita-labs/ui';

@Component({
  selector: 'app-alert-custom-content-example',
  imports: [
    KuiAlert,
    KuiAlertActions,
    KuiAlertIcon,
    KuiAlertMessage,
    KuiAlertTitle,
    KuiBadge,
    KuiButton,
    KuiIcon,
  ],
  templateUrl: './alert-custom-content-example.html',
  styleUrl: './alert-custom-content-example.scss',
})
export class AlertCustomContentExample {}
```

#### alert-custom-content-example.scss

```scss
:host {
  display: block;
}
```

### alert-banner-example

#### alert-banner-example.html

```html
<kui-alert appearance="info" banner message="We updated the terms of service." />
```

#### alert-banner-example.ts

```ts
import { Component } from '@angular/core';

import { KuiAlert } from '@kikita-labs/ui';

@Component({
  selector: 'app-alert-banner-example',
  imports: [KuiAlert],
  templateUrl: './alert-banner-example.html',
  styleUrl: './alert-banner-example.scss',
})
export class AlertBannerExample {}
```

#### alert-banner-example.scss

```scss
:host {
  display: block;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| appearance | 'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger' | 'neutral' | Semantic type. Same five values as the toast. neutral never shows the built-in icon; danger is announced assertively, every other value politely. |
| shape | 'soft' \| 'outline' \| 'solid' \| undefined | undefined | Visual weight, using the button shape vocabulary. Falls back to defaults.alert.shape, then soft. |
| size | 'sm' \| 'md' \| undefined | undefined | Padding and gap density. Falls back to defaults.alert.size, then the root defaults.size (sm or md only), then md. |
| banner | boolean | false | Stretches the alert to the full width of its container and removes the corner radius. |
| title | string \| undefined | undefined | Optional single-line heading. Ignored when [kuiAlertTitle] is projected. Set at least one of title, message or [kuiAlertMessage]. |
| message | string \| undefined | undefined | Optional supporting text below the title. Ignored when [kuiAlertMessage] is projected. |
| showIcon | boolean \| undefined | undefined | Shows the built-in appearance icon (defaults.alert.showIcon, then true). neutral never shows one. Ignored when [kuiAlertIcon] is projected, which always renders. |
| closable | boolean \| undefined | undefined | Shows the close button and enables (closed). Falls back to defaults.alert.closable, then true. |
| closeLabel | string \| undefined | undefined | Accessible label for the close button. Falls back to the alert.close message (Close notification). |
| actionLabel | string \| undefined | undefined | Label for the inline ghost action button. Ignored when [kuiAlertActions] is projected. |
| (action) | void | - | Emits when the action button is clicked. Not emitted for a projected [kuiAlertActions]. |
| (closed) | void | - | Emits when the close button is clicked. The alert never removes itself; hide it with @if. |
| [kuiAlertTitle] | content slot | - | Replaces the plain title string with arbitrary markup. |
| [kuiAlertIcon] | content slot | - | Replaces the built-in severity icon. A projected icon always renders, even for neutral, and inherits --kui-alert-icon-color. |
| [kuiAlertMessage] | content slot | - | Replaces the plain message string with arbitrary markup (links, lists). The title still renders alongside it. |
| [kuiAlertActions] | content slot | - | Replaces the single ghost action button with custom controls. kuiButton inside it picks up the appearance-tinted ghost colour. |
| KuiAlertOptions | interface | - | Shape of defaults.alert: size, shape, showIcon, closable and closeIcon. |

## Accessibility

- `role="alert"` + `aria-live="assertive"` + `aria-atomic="true"` only for `appearance="danger"`
  (genuinely urgent). Every other appearance uses `role="status"` + `aria-live="polite"` +
  `aria-atomic="true"` -- the same split `kuiToast()` uses, so a screen reader is not interrupted
  by routine info/success/warning alerts.
- `kui-alert` itself is not in the tab order; only its real controls (action, close) are
  focusable.
- The close button is a `kuiIconButton` with a required accessible name (`closeLabel`, default
  `"Close notification"`), never an unlabeled icon.
- Severity is never color-only: `info`/`success`/`warning`/`danger` always pair an icon with text;
  `neutral` has no icon because it carries no severity meaning.
- `Escape` does not close `kui-alert` -- it is a static region, not an overlay.

## Playground

Available at /components/alert/playground.

---

<!-- route: /components/avatar -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/avatar.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/avatar.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Avatar

> User or entity identity with image, initials, and status.

- Status: available
- Route: /components/avatar
- Package: @kikita-labs/ui@2.0.0
- Import: KuiAvatar from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/avatar.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-avatar src="/users/nikita.png" name="Nikita Repin" status="online" />
<kui-avatar name="Anya Murashova" />
<kui-avatar />
```

Image avatars render a native `<img>`. If the image fails to load, the component falls back to
initials generated from `name`, then to the icon fallback when no initials are available.

## Examples

Rendered at /components/avatar:

### avatar-button-example

#### avatar-button-example.html

```html
<div class="avatar-button-example">
  <button class="kui-avatar-action" type="button" aria-label="Open Nikita Repin profile">
    <kui-avatar src="https://i.pravatar.cc/64?img=12" name="Nikita Repin" />
  </button>
</div>
```

#### avatar-button-example.ts

```ts
import { Component } from '@angular/core';

import { KuiAvatar } from '@kikita-labs/ui';

@Component({
  selector: 'app-avatar-button-example',
  imports: [KuiAvatar],
  templateUrl: './avatar-button-example.html',
  styleUrl: './avatar-button-example.scss',
})
export class AvatarButtonExample {}
```

#### avatar-button-example.scss

```scss
.avatar-button-example {
  display: flex;
  align-items: center;
  justify-content: center;
}
```

### avatar-group-example

#### avatar-group-example.html

```html
<div class="avatar-group-example">
  <kui-avatar-group [avatars]="members" [max]="4" size="sm" label="Project participants" />
</div>
```

#### avatar-group-example.ts

```ts
import { Component } from '@angular/core';

import { KuiAvatarGroup, type KuiAvatarItem } from '@kikita-labs/ui';

const MEMBERS: readonly KuiAvatarItem[] = [
  { src: 'https://i.pravatar.cc/64?img=12', name: 'Nikita Repin', status: 'online' },
  { name: 'Anya Murashova', status: 'away' },
  { name: 'Timur Ognev' },
  { name: 'Vera Saltykova' },
  { name: 'Ilya Denisov' },
];

@Component({
  selector: 'app-avatar-group-example',
  imports: [KuiAvatarGroup],
  templateUrl: './avatar-group-example.html',
  styleUrl: './avatar-group-example.scss',
})
export class AvatarGroupExample {
  protected readonly members = MEMBERS;
}
```

#### avatar-group-example.scss

```scss
.avatar-group-example {
  display: flex;
  align-items: center;
  justify-content: center;
}
```

### avatar-sizes-shapes-example

#### avatar-sizes-shapes-example.html

```html
<div class="avatar-sizes-shapes-example">
  <div class="avatar-sizes-shapes-example__row">
    <kui-avatar name="Nikita Repin" size="xs" />
    <kui-avatar name="Nikita Repin" size="sm" />
    <kui-avatar name="Nikita Repin" size="md" />
    <kui-avatar name="Nikita Repin" size="lg" />
    <kui-avatar name="Nikita Repin" size="xl" />
    <kui-avatar name="Nikita Repin" size="2xl" />
  </div>
  <div class="avatar-sizes-shapes-example__row">
    <kui-avatar name="Design Bot" shape="square" />
    <kui-avatar name="Release Team" shape="square" size="lg" />
  </div>
</div>
```

#### avatar-sizes-shapes-example.ts

```ts
import { Component } from '@angular/core';

import { KuiAvatar } from '@kikita-labs/ui';

@Component({
  selector: 'app-avatar-sizes-shapes-example',
  imports: [KuiAvatar],
  templateUrl: './avatar-sizes-shapes-example.html',
  styleUrl: './avatar-sizes-shapes-example.scss',
})
export class AvatarSizesShapesExample {}
```

#### avatar-sizes-shapes-example.scss

```scss
.avatar-sizes-shapes-example {
  display: flex;
  flex-direction: column;
  gap: var(--kui-space-4, 16px);
  align-items: center;
}

.avatar-sizes-shapes-example__row {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### avatar-status-example

#### avatar-status-example.html

```html
<div class="avatar-status-example">
  <kui-avatar name="Nikita Repin" status="online" />
  <kui-avatar name="Anya Murashova" status="away" />
  <kui-avatar name="Timur Ognev" status="busy" />
  <kui-avatar name="Vera Saltykova" status="offline" />
</div>
```

#### avatar-status-example.ts

```ts
import { Component } from '@angular/core';

import { KuiAvatar } from '@kikita-labs/ui';

@Component({
  selector: 'app-avatar-status-example',
  imports: [KuiAvatar],
  templateUrl: './avatar-status-example.html',
  styleUrl: './avatar-status-example.scss',
})
export class AvatarStatusExample {}
```

#### avatar-status-example.scss

```scss
.avatar-status-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### basic-avatar-example

#### basic-avatar-example.html

```html
<div class="basic-avatar-example">
  <kui-avatar src="https://i.pravatar.cc/64?img=12" name="Nikita Repin" status="online" />
  <kui-avatar name="Anya Murashova" />
  <kui-avatar />
</div>
```

#### basic-avatar-example.ts

```ts
import { Component } from '@angular/core';

import { KuiAvatar } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-avatar-example',
  imports: [KuiAvatar],
  templateUrl: './basic-avatar-example.html',
  styleUrl: './basic-avatar-example.scss',
})
export class BasicAvatarExample {}
```

#### basic-avatar-example.scss

```scss
.basic-avatar-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| src | string \| undefined | undefined | Image URL. Falls back to initials, then the icon fallback, on load error. |
| name | string \| undefined | undefined | Used to derive initials, the palette hash, and the accessible label. |
| initials | string \| undefined | auto | Explicit one or two character initials, overriding the value derived from name. |
| alt | string \| undefined | name | Image alt text and accessible label override. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' | 'md' | Fixed avatar size. Falls back to defaults.avatar.size, then the global defaults.size. |
| shape | 'circle' \| 'square' | 'circle' | circle is intended for people; square is intended for entities such as bots, teams, or projects. Falls back to defaults.avatar.shape. |
| status | 'online' \| 'away' \| 'busy' \| 'offline' \| undefined | undefined | Optional presence indicator. Appended to the accessible label; the dot itself is decorative. |
| paletteIndex | number \| undefined | auto | Palette slot from 1 to 7 used for the fallback background and text color. A static numeric attribute is coerced and finite values clamp to 1-7. |
| loading | boolean | false | Renders the avatar using the internal [kuiSkeleton] loading treatment and hides avatar content. |
| kui-avatar-group avatars | readonly KuiAvatarItem[] | [] | Items rendered by the group. Each item accepts the same fields as kui-avatar. |
| kui-avatar-group max | number | 4 | Maximum visible avatars before the group collapses the rest into a +N overflow avatar. Falls back to defaults.avatarGroup.max; a static numeric attribute is coerced, and an invalid or less-than-one value resolves to 1. |
| kui-avatar-group size | KuiAvatarSize | 'md' | Size applied to every avatar in the group, including the overflow avatar. Falls back to defaults.avatarGroup.size, then the global defaults.size. |
| kui-avatar-group shape | KuiAvatarShape | 'circle' | Shape applied to every avatar in the group, including the overflow avatar. Falls back to defaults.avatarGroup.shape. |
| kui-avatar-group label | string \| undefined | 'Avatar group' | Accessible label for the group container. Undefined when omitted: the rendered text comes from the avatarGroup.label message. |
| .kui-avatar-action | CSS class | - | Applied to an external native button wrapping a kui-avatar to make it interactive. kui-avatar itself must not be made clickable. |
| KuiAvatarItem | interface | - | Item of kui-avatar-group avatars: the same fields as kui-avatar (src, name, initials, alt, status, paletteIndex). |
| KuiAvatarOptions / KuiAvatarGroupOptions | interfaces | - | Shapes of defaults.avatar (size, shape) and defaults.avatarGroup (size, shape, max). |
| KuiAvatarMessages / KuiAvatarGroupMessages | interfaces | - | Typed messages of the avatar (fallback name, status words, name with status) and of the group (label, overflow text). |

## Accessibility

- Image avatars render a native `<img>` with `alt` derived from `alt`, then `name`.
- Initials and icon fallback avatars expose `role="img"` and `aria-label`.
- Status is appended to the accessible label, for example `Nikita Repin, online`.
- The status dot is decorative.
- Interactive avatars must use a native `<button>` wrapper with `aria-label`.

## Playground

Available at /components/avatar/playground.

---

<!-- route: /components/badge -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/badge.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/badge.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Badge

> Compact status or metadata marker.

- Status: available
- Route: /components/badge
- Package: @kikita-labs/ui@2.0.0
- Import: KuiBadge from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/badge.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<span kuiBadge>Neutral</span>
<span kuiBadge appearance="success">Ready</span>
<span kuiBadge appearance="danger">Error</span>
```

`kuiBadge` is an attribute directive so it can be used on inline semantic elements such as `span`,
`strong`, `code`, or `a`.

## Examples

Rendered at /components/badge:

### badge-appearance-example

#### badge-appearance-example.html

```html
<div class="badge-appearance-example">
  <span kuiBadge appearance="neutral">Neutral</span>
  <span kuiBadge appearance="primary">Primary</span>
  <span kuiBadge appearance="success">Success</span>
  <span kuiBadge appearance="warning">Warning</span>
  <span kuiBadge appearance="danger">Danger</span>
  <span kuiBadge appearance="info">Info</span>
</div>
```

#### badge-appearance-example.ts

```ts
import { Component } from '@angular/core';

import { KuiBadge } from '@kikita-labs/ui';

@Component({
  selector: 'app-badge-appearance-example',
  imports: [KuiBadge],
  templateUrl: './badge-appearance-example.html',
  styleUrl: './badge-appearance-example.scss',
})
export class BadgeAppearanceExample {}
```

#### badge-appearance-example.scss

```scss
.badge-appearance-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### badge-size-example

#### badge-size-example.html

```html
<div class="badge-size-example">
  <span kuiBadge size="xs" appearance="primary">Extra small</span>
  <span kuiBadge size="sm" appearance="primary">Small</span>
  <span kuiBadge size="md" appearance="primary">Medium</span>
  <span kuiBadge size="lg" appearance="primary">Large</span>
</div>
```

#### badge-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiBadge } from '@kikita-labs/ui';

@Component({
  selector: 'app-badge-size-example',
  imports: [KuiBadge],
  templateUrl: './badge-size-example.html',
  styleUrl: './badge-size-example.scss',
})
export class BadgeSizeExample {}
```

#### badge-size-example.scss

```scss
.badge-size-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### basic-badge-example

#### basic-badge-example.html

```html
<div class="badge-example">
  <span kuiBadge>Neutral</span>
  <strong kuiBadge appearance="success">Ready</strong>
  <code kuiBadge appearance="warning">Review</code>
  <a kuiBadge appearance="info" href="#api">API reference</a>
</div>
```

#### basic-badge-example.ts

```ts
import { Component } from '@angular/core';

import { KuiBadge } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-badge-example',
  imports: [KuiBadge],
  templateUrl: './basic-badge-example.html',
  styleUrl: './basic-badge-example.scss',
})
export class BasicBadgeExample {}
```

#### basic-badge-example.scss

```scss
.badge-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| appearance | 'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info' | 'neutral' | Visual badge treatment mapped to Kikita UI status tokens. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' | 'md' | Badge size mapped to Kikita UI text and spacing tokens. |
| --kui-badge-height | CSS length | 22px | Badge block size. Overridden per size by the size input. |
| --kui-badge-px | CSS length | 8px | Inline padding. Overridden per size by the size input. |
| --kui-badge-radius | CSS length | var(--kui-radius-full) | Corner radius of the badge surface. |
| --kui-badge-font-size | CSS length | 11px | Badge label font size. Overridden per size by the size input. |
| --kui-badge-neutral-bg | CSS color | - | Background color for the neutral appearance (default). |
| --kui-badge-primary-bg | CSS color | - | Background color for the primary appearance. |
| --kui-badge-success-bg | CSS color | - | Background color for the success appearance. |
| --kui-badge-warning-bg | CSS color | - | Background color for the warning appearance. |
| --kui-badge-danger-bg | CSS color | - | Background color for the danger appearance. |
| --kui-badge-info-bg | CSS color | - | Background color for the info appearance. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/badge/playground.

---

<!-- route: /components/bar-chart -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/bar-chart.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/chart.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Bar Chart

> Vertical or horizontal, grouped or stacked bar chart.

- Status: available
- Route: /components/bar-chart
- Package: @kikita-labs/ui@2.0.0
- Import: KuiBarChart from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/chart.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-line-chart ariaLabel="Sessions per day" [series]="series" [categories]="categories" />
```

```ts
protected readonly series: readonly KuiChartCartesianSeries[] = [
  { id: 'sessions', name: 'Sessions', data: [120, 180, 150, 220, 260, 210, 300] },
];
protected readonly categories = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
```

`ariaLabel` has a chart-type fallback name and should describe what the chart shows. It is distinct
from each point's own `aria-label` (its value).

## Examples

Rendered at /components/bar-chart:

### basic-bar-chart-example

#### basic-bar-chart-example.html

```html
<div class="chart-example">
  <kui-bar-chart ariaLabel="MRR by plan" [series]="series" [categories]="categories" />
</div>
```

#### basic-bar-chart-example.ts

```ts
import { Component } from '@angular/core';

import { KuiBarChart, type KuiChartCartesianSeries } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-bar-chart-example',
  imports: [KuiBarChart],
  templateUrl: './basic-bar-chart-example.html',
  styleUrl: './basic-bar-chart-example.scss',
})
export class BasicBarChartExample {
  protected readonly series: readonly KuiChartCartesianSeries[] = [
    { id: 'mrr', name: 'MRR', data: [0, 4200, 9800, 15600] },
  ];
  protected readonly categories = ['Free', 'Pro', 'Business', 'Enterprise'];
}
```

#### basic-bar-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### bar-stacked-chart-example

#### bar-stacked-chart-example.html

```html
<div class="chart-example chart-example--stack">
  <kui-bar-chart ariaLabel="Grouped by day" [series]="series" [categories]="categories" size="sm" />
  <kui-bar-chart
    ariaLabel="Stacked by day"
    [series]="series"
    [categories]="categories"
    [stacked]="true"
    size="sm"
  />
</div>
```

#### bar-stacked-chart-example.ts

```ts
import { Component } from '@angular/core';

import { KuiBarChart, type KuiChartCartesianSeries } from '@kikita-labs/ui';

@Component({
  selector: 'app-bar-stacked-chart-example',
  imports: [KuiBarChart],
  templateUrl: './bar-stacked-chart-example.html',
  styleUrl: './bar-stacked-chart-example.scss',
})
export class BarStackedChartExample {
  protected readonly series: readonly KuiChartCartesianSeries[] = [
    { id: 'sessions', name: 'Sessions', data: [120, 180, 150, 220, 260, 210, 300] },
    { id: 'signups', name: 'Sign-ups', data: [40, 65, 52, 90, 110, 80, 140] },
  ];
  protected readonly categories = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
}
```

#### bar-stacked-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### bar-horizontal-chart-example

#### bar-horizontal-chart-example.html

```html
<div class="chart-example">
  <kui-bar-chart
    ariaLabel="MRR by plan"
    orientation="horizontal"
    [series]="series"
    [categories]="categories"
    [axes]="axes"
  />
</div>
```

#### bar-horizontal-chart-example.ts

```ts
import { Component } from '@angular/core';

import {
  KuiBarChart,
  type KuiChartAxesOptions,
  type KuiChartCartesianSeries,
} from '@kikita-labs/ui';

@Component({
  selector: 'app-bar-horizontal-chart-example',
  imports: [KuiBarChart],
  templateUrl: './bar-horizontal-chart-example.html',
  styleUrl: './bar-horizontal-chart-example.scss',
})
export class BarHorizontalChartExample {
  protected readonly series: readonly KuiChartCartesianSeries[] = [
    { id: 'mrr', name: 'MRR', data: [0, 4200, 9800, 15600] },
  ];
  protected readonly categories = ['Free', 'Pro', 'Business', 'Enterprise'];
  protected readonly axes: KuiChartAxesOptions = { xTitle: 'Plan', yTitle: 'MRR (USD)' };
}
```

#### bar-horizontal-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### bar-patterns-chart-example

#### bar-patterns-chart-example.html

```html
<div class="chart-example">
  <kui-bar-chart
    ariaLabel="Sessions and sign-ups"
    [series]="series"
    [categories]="categories"
    [patterns]="true"
  />
</div>
```

#### bar-patterns-chart-example.ts

```ts
import { Component } from '@angular/core';

import { KuiBarChart, type KuiChartCartesianSeries } from '@kikita-labs/ui';

@Component({
  selector: 'app-bar-patterns-chart-example',
  imports: [KuiBarChart],
  templateUrl: './bar-patterns-chart-example.html',
  styleUrl: './bar-patterns-chart-example.scss',
})
export class BarPatternsChartExample {
  protected readonly series: readonly KuiChartCartesianSeries[] = [
    { id: 'sessions', name: 'Sessions', data: [120, 180, 150, 220, 260, 210, 300] },
    { id: 'signups', name: 'Sign-ups', data: [40, 65, 52, 90, 110, 80, 140] },
  ];
  protected readonly categories = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
}
```

#### bar-patterns-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### bar-states-chart-example

#### bar-states-chart-example.html

```html
<div class="chart-example chart-example--stack">
  <kui-bar-chart
    ariaLabel="Loading MRR"
    [series]="series"
    [categories]="categories"
    [loading]="true"
    size="sm"
  />
  <kui-bar-chart ariaLabel="Empty MRR" [series]="[]" size="sm" />
</div>
```

#### bar-states-chart-example.ts

```ts
import { Component } from '@angular/core';

import { KuiBarChart, type KuiChartCartesianSeries } from '@kikita-labs/ui';

@Component({
  selector: 'app-bar-states-chart-example',
  imports: [KuiBarChart],
  templateUrl: './bar-states-chart-example.html',
  styleUrl: './bar-states-chart-example.scss',
})
export class BarStatesChartExample {
  protected readonly series: readonly KuiChartCartesianSeries[] = [
    { id: 'mrr', name: 'MRR', data: [0, 4200, 9800, 15600] },
  ];
  protected readonly categories = ['Free', 'Pro', 'Business', 'Enterprise'];
}
```

#### bar-states-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| series | readonly KuiChartCartesianSeries[] | - | Required. { id?, name, color?, data }, with data aligned index for index with categories. Without a non-gap value the empty composition renders. |
| categories | readonly string[] | [] | Category labels aligned with each series data. The shorter side wins. |
| orientation | 'vertical' \| 'horizontal' | 'vertical' | Flips the on-screen bar direction only; axes.x and axes.y stay semantic. |
| stacked | boolean | false | Stacks the series within each category. Only meaningful with more than one series; positive and negative values stack separately. Hiding a series recomputes the domain. |
| patterns | boolean | false | Fills each series with one of eight hatch patterns (colour independence). |

## Accessibility

- The `<svg>` is the graphic: `role="graphics-document"` with the name and the role description
  (`aria-roledescription`). The wrapper has no role, and axis text, gridlines and decorative shapes
  are `aria-hidden`.
- Each point/bar/slice is `role="graphics-symbol img"` with its own `aria-label` (the same text as
  the tooltip) -- an indivisible graphical unit, per the WAI-ARIA Graphics Module.
- Roving tabindex across points/bars/slices (see Keyboard). The inline legend is a named group of
  native `<button aria-pressed>` items at least 24px high.
- The tooltip shown on hover is the same one shown on keyboard focus (one shared overlay, retargeted
  between marks). It is dismissible and persistent. On pointer hover it appears at the pointer and follows
  it; keyboard focus anchors it to the focused mark. On touch, a tap pins the tooltip open until an
  outside tap, `Escape`, or a tap on a different mark; it also always renders below 768px, since it is
  the primary way to read a chart's exact value.
- Pointer hit targets: a line chart shows the tooltip while the pointer is on the point (its marker plus a
  3px margin), a scatter chart on the point's hit circle (at least 12px in radius), a bar chart on the bar
  itself and a donut on the slice.
- Text is at least 12px on screen: axis text defaults to 13px and keeps its pixel size at any width.
- `prefers-reduced-motion: reduce` disables the hover/dim transition and the donut sweep.
- The alt-table is a real accessible alternative to the graphic, not a decorative duplicate.

Automated checks (keyboard, accessibility tree, axe, forced-colours media emulation, reduced motion)
are in `chart-contract.spec.ts` and `accessibility.spec.ts`. A session with a real screen reader has
not been run and stays pending.

## Playground

Available at /components/bar-chart/playground.

---

<!-- route: /components/breadcrumbs -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/breadcrumbs.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/breadcrumbs.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Breadcrumbs

> Hierarchy trail.

- Status: available
- Route: /components/breadcrumbs
- Package: @kikita-labs/ui@2.0.0
- Import: KuiBreadcrumbs from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/breadcrumbs.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<nav aria-label="Breadcrumb">
  <ol kuiBreadcrumbs>
    <li><a kuiBreadcrumbItem href="/components">Components</a></li>
    <li kuiBreadcrumbSeparator></li>
    <li><a kuiBreadcrumbItem href="/components/actions">Actions</a></li>
    <li kuiBreadcrumbSeparator></li>
    <li><span kuiBreadcrumbItem current>Icon Button</span></li>
  </ol>
</nav>
```

### Plain-text (non-link) crumb

Use a `<span kuiBreadcrumbItem>` without `current` for a grouping crumb that has no page of its own:

```html
<li><a kuiBreadcrumbItem href="/catalog">Catalog</a></li>
<li kuiBreadcrumbSeparator></li>
<li><span kuiBreadcrumbItem>Electronics</span></li>
<li kuiBreadcrumbSeparator></li>
<li><span kuiBreadcrumbItem current>Headphones</span></li>
```

### Leading icon

At most one optional leading icon, on the first crumb only:

```html
<li>
  <a kuiBreadcrumbItem href="/">
    <span class="kui-breadcrumb-icon"><svg>...</svg></span>
  </a>
</li>
```

### Sizes

```html
<ol kuiBreadcrumbs size="sm">
  ...
</ol>
<ol kuiBreadcrumbs size="lg">
  ...
</ol>
```

### Responsive / narrow screens

The library does not enforce a single collapse strategy; pick the one that fits the consumer app and hierarchy depth:

- **Truncate a middle crumb** — add `.kui-breadcrumb-truncate` to the `<a>`/`<span>` that should shrink with an ellipsis; keep the trail's `<ol>` non-wrapping (`style="flex-wrap: nowrap"`).
- **Collapse behind an ellipsis menu** — render a `<button class="kui-breadcrumb-ellipsis">` in place of the hidden crumbs and wire it to an existing `kui-menu`/`kui-dropdown` listing the hidden levels. Breadcrumbs does not manage this menu itself.
- **First + last only** — drop the middle crumbs and separators entirely at the narrowest breakpoint.

## Examples

Rendered at /components/breadcrumbs:

### basic-breadcrumbs-example

#### basic-breadcrumbs-example.html

```html
<nav class="basic-breadcrumbs-example" aria-label="Breadcrumb">
  <ol kuiBreadcrumbs>
    <li><a kuiBreadcrumbItem href="/components">Components</a></li>
    <li kuiBreadcrumbSeparator></li>
    <li><span kuiBreadcrumbItem>Surfaces</span></li>
    <li kuiBreadcrumbSeparator></li>
    <li><span kuiBreadcrumbItem current>Breadcrumbs</span></li>
  </ol>
</nav>
```

#### basic-breadcrumbs-example.ts

```ts
import { Component } from '@angular/core';

import { KuiBreadcrumbItem, KuiBreadcrumbs, KuiBreadcrumbSeparator } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-breadcrumbs-example',
  imports: [KuiBreadcrumbItem, KuiBreadcrumbSeparator, KuiBreadcrumbs],
  templateUrl: './basic-breadcrumbs-example.html',
  styleUrl: './basic-breadcrumbs-example.scss',
})
export class BasicBreadcrumbsExample {}
```

#### basic-breadcrumbs-example.scss

```scss
.basic-breadcrumbs-example {
  min-width: 0;
}
```

### breadcrumbs-size-example

#### breadcrumbs-size-example.html

```html
<div class="breadcrumbs-size-example">
  <nav aria-label="Small breadcrumb">
    <ol kuiBreadcrumbs size="sm">
      <li><a kuiBreadcrumbItem href="/components">Components</a></li>
      <li kuiBreadcrumbSeparator></li>
      <li><span kuiBreadcrumbItem current>Small</span></li>
    </ol>
  </nav>

  <nav aria-label="Medium breadcrumb">
    <ol kuiBreadcrumbs>
      <li><a kuiBreadcrumbItem href="/components">Components</a></li>
      <li kuiBreadcrumbSeparator></li>
      <li><span kuiBreadcrumbItem current>Medium</span></li>
    </ol>
  </nav>

  <nav aria-label="Large breadcrumb">
    <ol kuiBreadcrumbs size="lg">
      <li><a kuiBreadcrumbItem href="/components">Components</a></li>
      <li kuiBreadcrumbSeparator></li>
      <li><span kuiBreadcrumbItem current>Large</span></li>
    </ol>
  </nav>
</div>
```

#### breadcrumbs-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiBreadcrumbItem, KuiBreadcrumbs, KuiBreadcrumbSeparator } from '@kikita-labs/ui';

@Component({
  selector: 'app-breadcrumbs-size-example',
  imports: [KuiBreadcrumbItem, KuiBreadcrumbSeparator, KuiBreadcrumbs],
  templateUrl: './breadcrumbs-size-example.html',
  styleUrl: './breadcrumbs-size-example.scss',
})
export class BreadcrumbsSizeExample {}
```

#### breadcrumbs-size-example.scss

```scss
.breadcrumbs-size-example {
  display: grid;
  gap: var(--kui-space-3, 12px);
  min-inline-size: 0;
}
```

### breadcrumbs-collapse-example

#### breadcrumbs-collapse-example.html

```html
<div class="breadcrumbs-collapse-example">
  <nav aria-label="Truncated breadcrumb">
    <ol kuiBreadcrumbs class="breadcrumbs-collapse-example__trail">
      <li><a kuiBreadcrumbItem href="#catalog">Catalog</a></li>
      <li kuiBreadcrumbSeparator></li>
      <li>
        <a kuiBreadcrumbItem class="kui-breadcrumb-truncate" href="#audio">
          Audio equipment and accessories
        </a>
      </li>
      <li kuiBreadcrumbSeparator></li>
      <li><span kuiBreadcrumbItem current>Headphones</span></li>
    </ol>
  </nav>

  <nav aria-label="Collapsed breadcrumb">
    <ol kuiBreadcrumbs>
      <li><a kuiBreadcrumbItem href="#catalog">Catalog</a></li>
      <li kuiBreadcrumbSeparator></li>
      <li>
        <button
          class="kui-breadcrumb-ellipsis"
          type="button"
          aria-label="Show hidden levels"
          [kuiMenuFor]="hiddenLevels"
        >
          &hellip;
        </button>
      </li>
      <li kuiBreadcrumbSeparator></li>
      <li><span kuiBreadcrumbItem current>Headphones</span></li>
    </ol>
  </nav>

  <kui-menu #hiddenLevels ariaLabel="Hidden levels">
    <a kuiMenuItem href="#electronics">Electronics</a>
    <a kuiMenuItem href="#audio">Audio</a>
  </kui-menu>
</div>
```

#### breadcrumbs-collapse-example.ts

```ts
import { Component } from '@angular/core';

import {
  KuiBreadcrumbItem,
  KuiBreadcrumbs,
  KuiBreadcrumbSeparator,
  KuiMenu,
  KuiMenuFor,
  KuiMenuItem,
} from '@kikita-labs/ui';

@Component({
  selector: 'app-breadcrumbs-collapse-example',
  imports: [
    KuiBreadcrumbItem,
    KuiBreadcrumbSeparator,
    KuiBreadcrumbs,
    KuiMenu,
    KuiMenuFor,
    KuiMenuItem,
  ],
  templateUrl: './breadcrumbs-collapse-example.html',
  styleUrl: './breadcrumbs-collapse-example.scss',
})
export class BreadcrumbsCollapseExample {}
```

#### breadcrumbs-collapse-example.scss

```scss
.breadcrumbs-collapse-example {
  display: grid;
  gap: var(--kui-space-4, 16px);
  min-inline-size: 0;
}

.breadcrumbs-collapse-example__trail {
  flex-wrap: nowrap;
  max-inline-size: 20rem;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| ol[kuiBreadcrumbs].size | 'sm' \| 'md' \| 'lg' | 'md' | Font size, separator scale, and spacing for the full trail. Falls back to defaults.breadcrumbs.size, then the global defaults.size. |
| a[kuiBreadcrumbItem] | directive | - | Native link crumb for navigable hierarchy levels. |
| span[kuiBreadcrumbItem] | directive | - | Plain-text crumb for grouping labels or the current page. |
| span[kuiBreadcrumbItem].current | boolean | false | Marks the final crumb as the current page and sets aria-current. |
| li[kuiBreadcrumbSeparator] | component | - | Decorative separator list item hidden from assistive technology. |
| .kui-breadcrumb-truncate | CSS class | - | Added to the crumb that should shrink with an ellipsis; keep the trail non-wrapping. The maximum width is --kui-breadcrumb-truncate-max-width. |
| button.kui-breadcrumb-ellipsis | CSS class | - | Styles a button that stands in for hidden crumbs. Breadcrumbs does not manage the menu; wire it to kui-menu or kui-dropdown yourself. |
| span.kui-breadcrumb-icon | CSS class | - | Optional leading icon wrapper, on the first crumb only. |
| KuiBreadcrumbsOptions | interface | - | Shape of defaults.breadcrumbs: size and separatorIcon (takes precedence over defaults.icons.separator). |

## Accessibility

- Wrap the trail in `<nav aria-label="Breadcrumb">` (or a localized label).
- `[kuiBreadcrumbs]` sets `role="list"` on the `<ol>` to restore list semantics after `list-style: none`.
- Link crumbs are native `<a>`, focusable with a visible `:focus-visible` ring.
- The current crumb is a `<span aria-current="page">`, not a link, and is not in tab order.
- `[kuiBreadcrumbSeparator]` renders a decorative chevron `<li aria-hidden="true">`, never read by assistive technology.

Breadcrumb links intentionally do not compose `[kuiLink]`. Breadcrumbs owns its
navigation-specific spacing, responsive size scale, color tokens, separator
relationship, and current-page treatment; applying generic Link styling would
create competing visual contracts. Keep navigable crumbs as native anchors with
`[kuiBreadcrumbItem]`.

## Playground

Available at /components/breadcrumbs/playground.

---

<!-- route: /components/button -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/button.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/button.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Button

> Primary command primitive for buttons and links.

- Status: available
- Route: /components/button
- Package: @kikita-labs/ui@2.0.0
- Import: KuiButton from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/button.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<button kuiButton>Save</button>
<button kuiButton shape="soft">Cancel</button>
<button kuiButton shape="outline" appearance="danger">Delete</button>
<button kuiButton shape="ghost" appearance="success">Approve</button>
<button kuiButton appearance="warning">Review</button>
<button kuiButton wrap>Long responsive label</button>
<button kuiButton [loading]="isSaving()">Save changes</button>

<a kuiButton shape="outline" href="/settings">Settings</a>
```

`shape` controls the surface treatment and `appearance` controls its semantic color intent. The
axes can be combined freely.

Without an explicit `appearance`, `solid` and `soft` use primary colors while `outline` and
`ghost` use their neutral defaults.

Use `iconStart`/`iconEnd` for a registered icon by name, instead of hand-projecting `kui-icon`:

```html
<button kuiButton appearance="success" iconStart="check">Save</button>
<button kuiButton shape="outline" iconEnd="arrow-right">Continue</button>
```

Project `kui-icon` directly when the icon needs `source` or `src` instead of a registered `name`:

```html
<button kuiButton appearance="success">
  <kui-icon [source]="checkIcon" />
  Save
</button>
```

## Examples

Rendered at /components/button:

### basic-button-example

#### basic-button-example.html

```html
<div class="button-example">
  <button kuiButton type="button">Save changes</button>
  <button kuiButton type="button" shape="soft">Cancel</button>
  <a kuiButton routerLink="/components/button">Button docs</a>
</div>
```

#### basic-button-example.ts

```ts
import { Component } from '@angular/core';
import { RouterLink } from '@angular/router';

import { KuiButton } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-button-example',
  imports: [KuiButton, RouterLink],
  templateUrl: './basic-button-example.html',
  styleUrl: './basic-button-example.scss',
})
export class BasicButtonExample {}
```

#### basic-button-example.scss

```scss
.button-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### button-appearance-example

#### button-appearance-example.html

```html
<div class="button-appearance-example">
  <button kuiButton type="button">Solid</button>
  <button kuiButton type="button" shape="soft">Soft</button>
  <button kuiButton type="button" shape="outline">Outline</button>
  <button kuiButton type="button" shape="ghost">Ghost</button>
  <button kuiButton type="button" appearance="danger">Danger</button>
  <button kuiButton type="button" shape="outline" appearance="danger">Outline danger</button>
</div>
```

#### button-appearance-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton } from '@kikita-labs/ui';

@Component({
  selector: 'app-button-appearance-example',
  imports: [KuiButton],
  templateUrl: './button-appearance-example.html',
  styleUrl: './button-appearance-example.scss',
})
export class ButtonAppearanceExample {}
```

#### button-appearance-example.scss

```scss
.button-appearance-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### button-size-example

#### button-size-example.html

```html
<div class="button-size-example">
  <button kuiButton type="button" size="xs">Extra small</button>
  <button kuiButton type="button" size="sm">Small</button>
  <button kuiButton type="button" size="md">Medium</button>
  <button kuiButton type="button" size="lg">Large</button>
  <button kuiButton type="button" disabled>Disabled</button>
  <button kuiButton type="button" loading>Loading</button>
</div>
```

#### button-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton } from '@kikita-labs/ui';

@Component({
  selector: 'app-button-size-example',
  imports: [KuiButton],
  templateUrl: './button-size-example.html',
  styleUrl: './button-size-example.scss',
})
export class ButtonSizeExample {}
```

#### button-size-example.scss

```scss
.button-size-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### button-icon-example

#### button-icon-example.html

```html
<div class="button-icon-example">
  <button kuiButton shape="soft" appearance="success" iconStart="check" type="button">Save</button>
  <button kuiButton shape="outline" iconEnd="arrow-right" type="button">Continue</button>
  <button
    kuiIconButton
    shape="soft"
    appearance="danger"
    icon="trash-2"
    aria-label="Delete"
    type="button"
  ></button>
</div>
```

#### button-icon-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiIconButton } from '@kikita-labs/ui';

@Component({
  selector: 'app-button-icon-example',
  imports: [KuiButton, KuiIconButton],
  templateUrl: './button-icon-example.html',
  styleUrl: './button-icon-example.scss',
})
export class ButtonIconExample {}
```

#### button-icon-example.scss

```scss
.button-icon-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### button-wrap-example

#### button-wrap-example.html

```html
<div class="button-wrap-example">
  <button kuiButton type="button">Save changes and continue to the review step</button>
  <button kuiButton type="button" wrap>Save changes and continue to the review step</button>
</div>
```

#### button-wrap-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton } from '@kikita-labs/ui';

@Component({
  selector: 'app-button-wrap-example',
  imports: [KuiButton],
  templateUrl: './button-wrap-example.html',
  styleUrl: './button-wrap-example.scss',
})
export class ButtonWrapExample {}
```

#### button-wrap-example.scss

```scss
.button-wrap-example {
  display: grid;
  gap: var(--kui-space-3, 12px);
  inline-size: min(100%, 16rem);
  margin-inline: auto;
}
```

### button-link-example

#### button-link-example.html

```html
<div class="button-link-example">
  <a kuiButton shape="outline" routerLink="/components/button">Open the Button page</a>
  <a kuiButton shape="outline" routerLink="/components/button" disabled>Disabled link</a>
</div>
```

#### button-link-example.ts

```ts
import { Component } from '@angular/core';
import { RouterLink } from '@angular/router';

import { KuiButton } from '@kikita-labs/ui';

@Component({
  selector: 'app-button-link-example',
  imports: [KuiButton, RouterLink],
  templateUrl: './button-link-example.html',
  styleUrl: './button-link-example.scss',
})
export class ButtonLinkExample {}
```

#### button-link-example.scss

```scss
.button-link-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| shape | 'solid' \| 'soft' \| 'outline' \| 'ghost' | 'solid' | Surface treatment. Combines freely with appearance. |
| appearance | 'primary' \| 'danger' \| 'success' \| 'warning' \| null | null | Semantic color intent. Without an explicit value, solid and soft use primary colors and outline and ghost use their neutral defaults. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' | 'md' | Control height and spacing size. Falls back to defaults.button.size, then the global defaults.size. |
| wrap | boolean | false | Allows long button text to wrap instead of truncating in narrow containers. |
| disabled | boolean | false | Disables button behavior. A button host gets the native disabled attribute; an anchor host gets aria-disabled="true", leaves the tab order and suppresses navigation. |
| loading | boolean | false | Centers a kuiLoader spinner over the button content, fades the content out while keeping its layout size, sets aria-busy="true" and behaves like disabled. The button keeps full opacity instead of dimming like a disabled one. |
| iconStart | KuiIconName \| undefined | undefined | Renders a kui-icon resolved by registered name before the projected content, without hand-projecting kui-icon. |
| iconEnd | KuiIconName \| undefined | undefined | Renders a kui-icon resolved by registered name after the projected content, without hand-projecting kui-icon. |
| provideKuiDefaults({ button }) | (defaults: KuiComponentDefaults) => Provider | - | Scopes repeated defaults for kuiButton in a component, route or feature subtree. A nested level merges with its parent per property. Use the defaults option of provideKikitaUi for the whole application. |
| KuiButtonOptions | interface | - | Shape of defaults.button: shape, appearance (null selects each shape neutral appearance) and size. It is the same shape as KuiButtonBaseOptions, shared with defaults.iconButton. |
| KuiDefaults | service | - | Injectable that reads and writes defaults at runtime: get(key) returns a Signal of the effective options, set and update write to the nearest level. |
| KuiButtonShape / KuiButtonAppearance | type aliases | - | Public unions of the shape and appearance values, exported for typed wrappers. |
| kuiProvideButtonOptions | deprecated function | - | Forwards { button, iconButton } (KuiButtonProviderOptions) to provideKuiDefaults. Deprecated, removed in 3.0; use provideKuiDefaults. |

## Accessibility

Use native `button` whenever the action does not navigate. Use an `a` host only for navigation.
Every button needs an accessible name. Disabled native buttons use `disabled`; disabled anchors
use `aria-disabled="true"`, leave the tab order, and suppress navigation.

Native button keyboard behavior is preserved: `Enter` and `Space` activate a `button`; links use
native anchor keyboard behavior. The directive does not introduce a custom keyboard model.

## Playground

Available at /components/button/playground.

---

<!-- route: /components/calendar -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/calendar.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/calendar.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Calendar

> Date grid.

- Status: available
- Route: /components/calendar
- Package: @kikita-labs/ui@2.0.0
- Import: KuiCalendar from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/calendar.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-calendar [(value)]="selectedDate" />
```

`value` is a two-way model holding a `Date | null`.

Placed as a sibling of `input[kuiDatePicker]` inside the same `kui-field`, the directive
auto-wires this calendar's `value`/`viewDate` for you — see [Date Picker](./date-picker.md),
which is the recommended way to pair the two.

### Disabled Dates

```html
<kui-calendar [minDate]="today" [(value)]="selectedDate" />
<kui-calendar [disabledDates]="[holiday1, holiday2]" [(value)]="selectedDate" />
<kui-calendar [disabledDates]="isWeekend" [(value)]="selectedDate" />
```

### Footer

```html
<kui-calendar showFooter [(value)]="selectedDate" />
```

Off by default. When enabled, adds a footer with the current value and a "Today" shortcut button — useful when the calendar is the whole surface (e.g. inside a popover), but usually skipped for bare inline placements (sidebars, filter panels).

### Custom Header / Footer

The header (month/year title + nav arrows) and footer are both replaceable through content projection. Project an element with `kuiCalendarHeader` or `kuiCalendarFooter` to fully replace the corresponding default block; the built-in one (including the `showFooter` toggle) only renders when nothing is projected.

```html
<kui-calendar [(value)]="selectedDate">
  <div kuiCalendarFooter class="my-footer">
    <button type="button" (click)="clearSelection()">Clear</button>
  </div>
</kui-calendar>
```

Projected content is compiled against the host template, not `kui-calendar`'s internal state — it replaces the block rather than augmenting it.

### Compact Size

```html
<kui-calendar size="sm" [(value)]="selectedDate" />
```

`sm` drops the border and padding, for embedding directly inside a sidebar or panel.

### Width

The calendar has a fixed width (`296px`) so its day grid always has enough room, regardless of
how wide whatever's anchoring it (a field, a dropdown trigger) happens to be. Override it with
the `--kui-calendar-width` custom property:

```html
<kui-calendar style="--kui-calendar-width: 340px" [(value)]="selectedDate" />
```

### Flat (No Own Chrome)

```html
<kui-calendar flat [(value)]="selectedDate" />
```

Strips the calendar's own background/border/padding. Use this when nesting it inside chrome
that already draws those — a `kui-dropdown`/`kui-popover` panel in a date picker — so the two
don't stack into a double frame. See [Date Picker](./date-picker.md).

### Controlling The Displayed Month

```html
<kui-calendar [(value)]="selectedDate" [(viewDate)]="viewDate" />
```

`viewDate` (a first-of-month `Date`, two-way) drives which month the grid shows. Bind it when
an external control needs to move the calendar to a specific month manually. Left unbound, it
defaults to today's month, or the bound `value`'s month at construction time. When paired with
`input[kuiDatePicker]` inside the same `kui-field`, this is wired automatically — see
[Date Picker](./date-picker.md).

`showPrevNav`/`showNextNav` (`boolean`, default `true`) hide the previous/next nav button. This
is for pairing two linked calendars a month apart (one showing month N with only a "previous"
button, the other month N+1 with only "next") — not yet wired up as a built-in range popover,
but available for custom layouts.

### Locale

`kui-calendar` resolves month names, weekday names, the heading, the first day of the week and the weekend purely from `Intl` — there is no bundled locale data to keep in sync. The heading is one `Intl` month-and-year format, so its order follows the locale (`October 2026`, `2026年10月`). The first day and the weekend come from `Intl.Locale#getWeekInfo()` (`he-IL` has a Friday and Saturday weekend), with a static table for engines that lack it. Names use the Gregorian calendar and Latin digits whatever the locale's default is.

By default it uses the locale of the nearest `KuiI18n` level, which starts from the app-wide `KUI_LOCALE` (in the browser `navigator.language`, on the server the request's `Accept-Language`, both falling back to `en-US`; see `KUI_LOCALE` for the server-to-browser hand-off). See [Internationalization](./i18n.md).

Set the locale for the whole app or a subtree:

```ts
// app.config.ts
import { provideKikitaUi } from '@kikita-labs/ui';

provideKikitaUi({ locale: 'ru-RU' });

// a subtree: provideKuiLocale('ru-RU') in the component's providers
```

Or override it for a single instance with the `locale` input, which takes precedence over the level:

```html
<kui-calendar locale="ru-RU" [(value)]="selectedDate" />
```

## Examples

Rendered at /components/calendar:

### basic-calendar-example

#### basic-calendar-example.html

```html
<div class="basic-calendar-example">
  <kui-calendar [(value)]="selectedDate" [minDate]="minDate" showFooter />

  <kui-calendar size="sm" flat [(value)]="selectedDate" />
</div>
```

#### basic-calendar-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCalendar } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-calendar-example',
  imports: [KuiCalendar],
  templateUrl: './basic-calendar-example.html',
  styleUrl: './basic-calendar-example.scss',
})
export class BasicCalendarExample {
  protected readonly selectedDate = signal<Date | null>(new Date(2026, 6, 14));
  protected readonly minDate = new Date(2026, 6, 1);
}
```

#### basic-calendar-example.scss

```scss
.basic-calendar-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-5, 20px);
  align-items: flex-start;
}
```

### calendar-states-example

#### calendar-states-example.html

```html
<div class="calendar-states-example">
  <kui-calendar
    [(value)]="selectedDate"
    [minDate]="minDate"
    [maxDate]="maxDate"
    [disabledDates]="holidays"
  />

  <kui-calendar [(value)]="selectedDate" [disabledDates]="isWeekend" [showWeekend]="false" />
</div>
```

#### calendar-states-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCalendar } from '@kikita-labs/ui';

@Component({
  selector: 'app-calendar-states-example',
  imports: [KuiCalendar],
  templateUrl: './calendar-states-example.html',
  styleUrl: './calendar-states-example.scss',
})
export class CalendarStatesExample {
  protected readonly selectedDate = signal<Date | null>(new Date(2026, 6, 14));
  protected readonly minDate = new Date(2026, 6, 6);
  protected readonly maxDate = new Date(2026, 6, 24);
  protected readonly holidays = [new Date(2026, 6, 15), new Date(2026, 6, 20)];

  protected readonly isWeekend = (date: Date): boolean =>
    date.getDay() === 0 || date.getDay() === 6;
}
```

#### calendar-states-example.scss

```scss
.calendar-states-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-5, 20px);
  align-items: flex-start;
}
```

### calendar-locale-example

#### calendar-locale-example.html

```html
<div class="calendar-locale-example">
  <kui-calendar locale="ja-JP" size="sm" [(value)]="selectedDate" />

  <kui-calendar
    locale="de-DE"
    size="sm"
    showFooter
    [messages]="messages"
    [(value)]="selectedDate"
  />
</div>
```

#### calendar-locale-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCalendar, type KuiCalendarMessages } from '@kikita-labs/ui';

@Component({
  selector: 'app-calendar-locale-example',
  imports: [KuiCalendar],
  templateUrl: './calendar-locale-example.html',
  styleUrl: './calendar-locale-example.scss',
})
export class CalendarLocaleExample {
  protected readonly selectedDate = signal<Date | null>(new Date(2026, 9, 3));
  protected readonly messages: Partial<KuiCalendarMessages> = {
    label: 'Booking calendar',
    today: 'Jump to today',
  };
}
```

#### calendar-locale-example.scss

```scss
.calendar-locale-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-5, 20px);
  align-items: flex-start;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| [(value)] | Date \| null | null | Selected date. For a start and end pair use kui-calendar-range, whose value is a KuiDateRange \| null. Next to input[kuiDatePicker] in the same field the directive wires it for you. |
| messages | Partial<KuiCalendarMessages> \| undefined | undefined | Per-instance text overrides (label, today, previousMonth, nextMonth, previousYear, nextYear, previousDecade, nextDecade). They win over scoped and root messages. |
| [(viewDate)] | Date | current month | First-of-month date that controls the visible month. |
| size | 'md' \| 'sm' | 'md' | Calendar density. Use sm when embedding in tighter sidebars or panels. |
| flat | boolean | false | Removes the calendar frame for dropdown or popover panel composition. |
| showWeekend | boolean | true | Mutes the weekend days of the locale (Saturday and Sunday in en-US) when enabled. |
| showFooter | boolean | false | Shows the built-in value summary and Today shortcut. |
| [(minDate)] / [(maxDate)] | Date \| undefined | undefined | Inclusive lower and upper bounds for selectable days. Models, so a paired input[kuiDatePicker] can wire them from its own bounds. |
| disabledDates | Date[] \| ((date: Date) => boolean) \| undefined | undefined | Individual disabled dates or a predicate evaluated for each rendered date. |
| locale | string \| undefined | KUI_LOCALE | BCP 47 locale override for month names, weekday names, the heading, week start and weekend. It wins over the locale of the nearest KuiI18n level. |
| showPrevNav / showNextNav | boolean | true | Hide one header navigation control for linked multi-calendar layouts. |
| [kuiCalendarHeader] / [kuiCalendarFooter] | projected content | - | Replace the default header or footer with consumer-owned content. |
| provideKuiLocale(locale) | Provider[] | - | Sets the locale of a subtree (a tag, a Signal or a function). Use provideKikitaUi({ locale }) for the whole application. |
| --kui-calendar-width | CSS custom property | 296px | Overrides the fixed calendar width while keeping the day grid predictable. |
| KuiCalendarOptions / KuiCalendarViewOptions | interfaces | - | Shape of defaults.calendar (size, flat, showWeekend, showFooter, showPrevNav, showNextNav, previousIcon, nextIcon), shared with kui-calendar-range. |
| KuiCalendarMessages | interface | - | Typed messages of the calendar and the calendar range, with English defaults. |
| kui-picked | DOM event | - | Bubbling event the calendar dispatches after a date pick, so an enclosing kui-dropdown can close. |

## Accessibility

- The day grid is a complete ARIA grid: `role="grid"` containing the weekday header `role="row"` (with `role="columnheader"` cells that carry the full weekday name as `abbr`) and a `role="rowgroup"` of six `role="row"` week rows, each holding seven `role="gridcell"` elements. Each gridcell wraps one day `<button>`.
- `aria-selected` on the selected gridcell (not on the button), `aria-current="date"` on today, `aria-disabled` on disabled dates.
- Roving tabindex: one day cell is in the tab order at a time (the focused date). On initial render, the selected date receives focus when it is in the displayed month; otherwise today is used when visible, then the first day of the displayed month. Arrow keys, `Home`/`End`, and `PageUp`/`PageDown` move DOM focus to the new roving cell without leaving the grid.
- Month/year changes are announced through an `aria-live="polite"` region.

### Keyboard

- `ArrowLeft` / `ArrowRight`: previous/next day
- `ArrowUp` / `ArrowDown`: previous/next week
- `Home` / `End`: start/end of the focused week
- `PageUp` / `PageDown`: previous/next month
- `Shift+PageUp` / `Shift+PageDown`: previous/next year
- `Enter` / `Space`: select the focused date

## Playground

Available at /components/calendar/playground.

---

<!-- route: /components/calendar-range -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/calendar-range.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/calendar-range.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Calendar Range

> Inline month grid for selecting a start and end date.

- Status: available
- Route: /components/calendar-range
- Package: @kikita-labs/ui@2.0.0
- Import: KuiCalendarRange from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/calendar-range.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-calendar-range [(value)]="selectedRange" />
```

`value` is a two-way model holding a `KuiDateRange | null`:

```ts
interface KuiDateRange {
  start: Date;
  end: Date | null;
}
```

`end` is `null` while the range is still open (only the start date has been picked).

### Disabled Dates

```html
<kui-calendar-range [minDate]="today" [(value)]="selectedRange" />
<kui-calendar-range [disabledDates]="[holiday1, holiday2]" [(value)]="selectedRange" />
<kui-calendar-range [disabledDates]="isWeekend" [(value)]="selectedRange" />
```

### Footer

```html
<kui-calendar-range showFooter [(value)]="selectedRange" />
```

Off by default. When enabled, adds a footer with the current value and a "Today" shortcut button.

### Custom Header / Footer

Project an element with `kuiCalendarHeader` or `kuiCalendarFooter` to fully replace the corresponding default block; the built-in one (including the `showFooter` toggle) only renders when nothing is projected.

```html
<kui-calendar-range [(value)]="selectedRange">
  <div kuiCalendarFooter class="my-footer">
    <button type="button" (click)="clearSelection()">Clear</button>
  </div>
</kui-calendar-range>
```

### Compact Size

```html
<kui-calendar-range size="sm" [(value)]="selectedRange" />
```

`sm` drops the border and padding, for embedding directly inside a sidebar or panel.

### Width

Fixed width (`296px` by default), overridable with `--kui-calendar-width`, same as `kui-calendar`. See [Calendar > Width](./calendar.md#width).

### Flat (No Own Chrome)

```html
<kui-calendar-range flat [(value)]="selectedRange" />
```

Strips the calendar's own background/border/padding. Use this when nesting it inside chrome that already draws those (a `kui-dropdown`/`kui-popover` panel) so the two don't stack into a double frame.

### Controlling The Displayed Month

```html
<kui-calendar-range [(value)]="selectedRange" [(viewDate)]="viewDate" />
```

`viewDate` (a first-of-month `Date`, two-way) drives which month the grid shows. Left unbound, it defaults to today's month, or the bound `value.start`'s month at construction time.

`showPrevNav`/`showNextNav` (`boolean`, default `true`) hide the previous/next nav button — for pairing two linked calendars a month apart (one showing month N with only "previous", the other month N+1 with only "next"); not yet wired up as a built-in range popover, but available for custom layouts.

### Locale

Same `Intl`-driven locale resolution as `kui-calendar` — see [Calendar > Locale](./calendar.md#locale).

## Examples

Rendered at /components/calendar-range:

### basic-calendar-range-example

#### basic-calendar-range-example.html

```html
<div class="calendar-range-example">
  <kui-calendar-range [(value)]="range" [(viewDate)]="viewDate" showFooter />

  <kui-calendar-range size="sm" flat [(value)]="range" [(viewDate)]="viewDate" />
</div>
```

#### basic-calendar-range-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCalendarRange, type KuiDateRange } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-calendar-range-example',
  imports: [KuiCalendarRange],
  templateUrl: './basic-calendar-range-example.html',
  styleUrl: './basic-calendar-range-example.scss',
})
export class BasicCalendarRangeExample {
  protected readonly viewDate = signal(new Date(2026, 6, 1));
  protected readonly range = signal<KuiDateRange | null>({
    start: new Date(2026, 6, 6),
    end: new Date(2026, 6, 14),
  });
}
```

#### basic-calendar-range-example.scss

```scss
.calendar-range-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4);
  align-items: flex-start;
}
```

### calendar-range-states-example

#### calendar-range-states-example.html

```html
<div class="calendar-range-example">
  <kui-calendar-range
    [(value)]="range"
    [(viewDate)]="viewDate"
    [minDate]="minDate"
    [maxDate]="maxDate"
    [disabledDates]="holidays"
  />

  <kui-calendar-range
    [(value)]="range"
    [(viewDate)]="viewDate"
    [disabledDates]="isWeekend"
    [showWeekend]="false"
  />
</div>
```

#### calendar-range-states-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCalendarRange, type KuiDateRange } from '@kikita-labs/ui';

@Component({
  selector: 'app-calendar-range-states-example',
  imports: [KuiCalendarRange],
  templateUrl: './calendar-range-states-example.html',
  styleUrl: './calendar-range-states-example.scss',
})
export class CalendarRangeStatesExample {
  protected readonly viewDate = signal(new Date(2026, 6, 1));
  protected readonly range = signal<KuiDateRange | null>(null);
  protected readonly minDate = new Date(2026, 6, 6);
  protected readonly maxDate = new Date(2026, 6, 24);
  protected readonly holidays = [new Date(2026, 6, 15), new Date(2026, 6, 20)];

  protected readonly isWeekend = (date: Date): boolean =>
    date.getDay() === 0 || date.getDay() === 6;
}
```

#### calendar-range-states-example.scss

```scss
.calendar-range-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4);
  align-items: flex-start;
}
```

### calendar-range-linked-example

#### calendar-range-linked-example.html

```html
<div class="calendar-range-example">
  <kui-calendar-range [(value)]="range" [(viewDate)]="leftView" [showNextNav]="false" />

  <kui-calendar-range
    [(value)]="range"
    [viewDate]="rightView()"
    (viewDateChange)="showFromRight($event)"
    [showPrevNav]="false"
  />
</div>
```

#### calendar-range-linked-example.ts

```ts
import { Component, computed, signal } from '@angular/core';

import { KuiCalendarRange, type KuiDateRange } from '@kikita-labs/ui';

@Component({
  selector: 'app-calendar-range-linked-example',
  imports: [KuiCalendarRange],
  templateUrl: './calendar-range-linked-example.html',
  styleUrl: './calendar-range-linked-example.scss',
})
export class CalendarRangeLinkedExample {
  protected readonly range = signal<KuiDateRange | null>(null);
  protected readonly leftView = signal(new Date(2026, 6, 1));
  protected readonly rightView = computed(
    () => new Date(this.leftView().getFullYear(), this.leftView().getMonth() + 1, 1),
  );

  protected showFromRight(view: Date): void {
    this.leftView.set(new Date(view.getFullYear(), view.getMonth() - 1, 1));
  }
}
```

#### calendar-range-linked-example.scss

```scss
.calendar-range-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4);
  align-items: flex-start;
}
```

### calendar-range-locale-example

#### calendar-range-locale-example.html

```html
<div class="calendar-range-example">
  <kui-calendar-range locale="ja-JP" size="sm" [(value)]="range" [(viewDate)]="viewDate" />

  <kui-calendar-range
    locale="de-DE"
    size="sm"
    showFooter
    [messages]="messages"
    [(value)]="range"
    [(viewDate)]="viewDate"
  />
</div>
```

#### calendar-range-locale-example.ts

```ts
import { Component, signal } from '@angular/core';

import { type KuiCalendarMessages, KuiCalendarRange, type KuiDateRange } from '@kikita-labs/ui';

@Component({
  selector: 'app-calendar-range-locale-example',
  imports: [KuiCalendarRange],
  templateUrl: './calendar-range-locale-example.html',
  styleUrl: './calendar-range-locale-example.scss',
})
export class CalendarRangeLocaleExample {
  protected readonly viewDate = signal(new Date(2026, 9, 1));
  protected readonly range = signal<KuiDateRange | null>({
    start: new Date(2026, 9, 5),
    end: new Date(2026, 9, 9),
  });
  protected readonly messages: Partial<KuiCalendarMessages> = {
    label: 'Booking range',
    today: 'Jump to today',
  };
}
```

#### calendar-range-locale-example.scss

```scss
.calendar-range-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4);
  align-items: flex-start;
}
```

### calendar-range-footer-example

#### calendar-range-footer-example.html

```html
<kui-calendar-range [(value)]="range" [(viewDate)]="viewDate">
  <div kuiCalendarFooter class="calendar-range-footer">
    <button kuiButton shape="ghost" size="sm" type="button" (click)="clear()">Clear</button>
  </div>
</kui-calendar-range>
```

#### calendar-range-footer-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiButton, KuiCalendarRange, type KuiDateRange } from '@kikita-labs/ui';

@Component({
  selector: 'app-calendar-range-footer-example',
  imports: [KuiButton, KuiCalendarRange],
  templateUrl: './calendar-range-footer-example.html',
  styleUrl: './calendar-range-footer-example.scss',
})
export class CalendarRangeFooterExample {
  protected readonly viewDate = signal(new Date(2026, 6, 1));
  protected readonly range = signal<KuiDateRange | null>({
    start: new Date(2026, 6, 6),
    end: new Date(2026, 6, 10),
  });

  protected clear(): void {
    this.range.set(null);
  }
}
```

#### calendar-range-footer-example.scss

```scss
.calendar-range-footer {
  display: flex;
  justify-content: flex-end;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| [(value)] | KuiDateRange \| null | null | Selected range, { start: Date; end: Date \| null }. end is null while only the start has been picked; the first click after a committed range starts a new one. |
| [(viewDate)] | Date | current month | First-of-month date that controls the visible month. Left unbound it defaults to today, or to the month of the bound value.start at construction. |
| size | 'md' \| 'sm' \| undefined | undefined | Calendar density. sm drops the border and padding for sidebars. Falls back to defaults.calendarRange.size, then the global defaults.size, then md. |
| flat | boolean \| undefined | undefined | Strips the calendar background, border and padding, for dropdown or popover panels. Falls back to defaults.calendarRange.flat, then false. |
| showWeekend | boolean \| undefined | undefined | Mutes the weekend days of the locale. Falls back to defaults.calendarRange.showWeekend, then true. |
| showFooter | boolean \| undefined | undefined | Shows the built-in footer with the current value and the Today shortcut. Falls back to defaults.calendarRange.showFooter, then false. |
| showPrevNav / showNextNav | boolean \| undefined | undefined | Hide the previous or next header navigation control, for two linked calendars a month apart. Fall back to defaults.calendarRange, then true. |
| minDate / maxDate | Date \| undefined | undefined | Inclusive lower and upper bounds. Dates outside them are disabled. |
| disabledDates | Date[] \| ((date: Date) => boolean) \| undefined | undefined | Individual disabled dates or a predicate evaluated for each rendered date. |
| locale | string \| undefined | undefined | BCP 47 locale for month and weekday names, heading order, week start and weekend. It overrides the locale of the nearest KuiI18n level for this instance. |
| messages | Partial<KuiCalendarMessages> \| undefined | undefined | Per-instance text overrides, the same group as the calendar. They win over scoped and root messages. |
| [kuiCalendarHeader] / [kuiCalendarFooter] | projected content | - | Replace the default header or footer entirely; the built-in block (and the showFooter toggle) renders only when nothing is projected. |
| --kui-calendar-width | CSS custom property | 296px | Overrides the fixed calendar width, as for kui-calendar. |
| KuiDateRange | interface | - | The value shape: { start: Date; end: Date \| null }. |
| KuiCalendarOptions / KuiCalendarViewOptions | interfaces | - | Shape of defaults.calendarRange (size, flat, showWeekend, showFooter, showPrevNav, showNextNav, previousIcon, nextIcon), shared with kui-calendar. |

## Accessibility

- The day grid is a complete ARIA grid, structured as in `kui-calendar`: `role="grid"`, a weekday header row of `role="columnheader"` cells, and a `role="rowgroup"` of six week `role="row"`s holding seven `role="gridcell"`s, each wrapping one day `<button>`.
- `aria-selected` on the gridcells of the range endpoints (and any single committed day), `aria-current="date"` on today, `aria-disabled` on disabled dates.
- Roving tabindex: one day cell is in the tab order at a time (the focused date); arrow keys, `Home`/`End`, `PageUp`/`PageDown` move focus without leaving the grid.
- Month/year changes are announced through an `aria-live="polite"` region.

### Keyboard

- `ArrowLeft` / `ArrowRight`: previous/next day
- `ArrowUp` / `ArrowDown`: previous/next week
- `Home` / `End`: start/end of the focused week
- `PageUp` / `PageDown`: previous/next month
- `Shift+PageUp` / `Shift+PageDown`: previous/next year
- `Enter` / `Space`: select the focused date

## Playground

Available at /components/calendar-range/playground.

---

<!-- route: /components/card -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/card.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/card.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Card

> Surface, elevated, and sunken content container.

- Status: available
- Route: /components/card
- Package: @kikita-labs/ui@2.0.0
- Import: KuiCard from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/card.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```ts
import { KuiCard } from '@kikita-labs/ui';
```

Import `@kikita-labs/ui/styles` once in the application stylesheet to load Card's runtime styles.

```html
<article kuiCard>
  <h3>Default surface</h3>
  <p>Grouped content with Kikita border, radius, and surface tokens.</p>
</article>

<button kuiCard interactive type="button">Interactive card</button>
```

Choose a native host that matches the content and behavior: `article`, `section`, or `aside` for
content; `button` for an action; and `a` with an `href` for navigation.

## Examples

Rendered at /components/card:

### basic-card-example

#### basic-card-example.html

```html
<article kuiCard>
  <h3>Default surface</h3>
  <p>Grouped content with Kikita border, radius, and surface tokens.</p>
</article>
```

#### basic-card-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCard } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-card-example',
  imports: [KuiCard],
  templateUrl: './basic-card-example.html',
  styleUrl: './basic-card-example.scss',
})
export class BasicCardExample {}
```

#### basic-card-example.scss

```scss
:host {
  display: block;
  max-inline-size: 320px;
}
```

### card-appearance-example

#### card-appearance-example.html

```html
<article kuiCard appearance="surface">
  <h3>Surface</h3>
  <p>Default flat card surface.</p>
</article>
<article kuiCard appearance="elevated">
  <h3>Elevated</h3>
  <p>Raised shadow for content that floats above the page.</p>
</article>
<article kuiCard appearance="sunken">
  <h3>Sunken</h3>
  <p>Inset surface for nested or secondary content.</p>
</article>
```

#### card-appearance-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCard } from '@kikita-labs/ui';

@Component({
  selector: 'app-card-appearance-example',
  imports: [KuiCard],
  templateUrl: './card-appearance-example.html',
  styleUrl: './card-appearance-example.scss',
})
export class CardAppearanceExample {}
```

#### card-appearance-example.scss

```scss
:host {
  display: grid;
  gap: var(--kui-space-4, 16px);
  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
  inline-size: 100%;
}
```

### card-interactive-example

#### card-interactive-example.html

```html
<button kuiCard interactive type="button" class="card-interactive-example__button">
  <h3>Interactive card</h3>
  <p>Hover and focus-visible affordances for a clickable card surface.</p>
</button>
<a kuiCard interactive href="https://kikita.dev" class="card-interactive-example__button">
  <h3>Linked card</h3>
  <p>Anchor host keeps native link semantics and keyboard behavior.</p>
</a>
```

#### card-interactive-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCard } from '@kikita-labs/ui';

@Component({
  selector: 'app-card-interactive-example',
  imports: [KuiCard],
  templateUrl: './card-interactive-example.html',
  styleUrl: './card-interactive-example.scss',
})
export class CardInteractiveExample {}
```

#### card-interactive-example.scss

```scss
:host {
  display: grid;
  gap: var(--kui-space-4, 16px);
  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
  inline-size: 100%;
}

.card-interactive-example__button {
  display: block;
  border: none;
  background: none;
  font: inherit;
  text-align: start;
  text-decoration: none;
  cursor: pointer;
}
```

### card-size-example

#### card-size-example.html

```html
<article kuiCard size="xs">
  <h3>Extra small</h3>
</article>
<article kuiCard size="sm">
  <h3>Small</h3>
</article>
<article kuiCard size="md">
  <h3>Medium</h3>
</article>
<article kuiCard size="lg">
  <h3>Large</h3>
</article>
```

#### card-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCard } from '@kikita-labs/ui';

@Component({
  selector: 'app-card-size-example',
  imports: [KuiCard],
  templateUrl: './card-size-example.html',
  styleUrl: './card-size-example.scss',
})
export class CardSizeExample {}
```

#### card-size-example.scss

```scss
:host {
  display: grid;
  gap: var(--kui-space-4, 16px);
  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
  inline-size: 100%;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| appearance | 'surface' \| 'elevated' \| 'sunken' | 'surface' | Visual surface treatment: flat surface, elevated shadow, or sunken inset. Falls back to defaults.card.appearance. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' | 'md' | Card padding size, mapped to the shared Kikita size scale. An explicit local size wins, then defaults.card.size, then the global defaults.size. |
| interactive | boolean | false | Enables hover and focus-visible affordances for clickable cards. Does not add semantics or keyboard behavior; choose an interactive host element (button, a) for that. |

## Accessibility

`kuiCard` styles its host; it does not add a role, `tabindex`, activation behavior, or keyboard
handlers. `interactive` only supplies visual affordances. Use a native `button` for an action or an
`a` element with an `href` for navigation so the browser provides focus and keyboard activation.
Card has no disabled, selected, pressed, or form state of its own; native host behavior remains
owned by the host element.

## Playground

Available at /components/card/playground.

---

<!-- route: /components/carousel -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/carousel.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/carousel.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Carousel

> Horizontal strip of slides with arrows, a dot picker and optional autoplay.

- Status: available
- Route: /components/carousel
- Package: @kikita-labs/ui@2.0.0
- Import: KuiCarousel from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/carousel.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-carousel ariaLabel="Product photos" [(index)]="slide">
  <div kuiCarouselSlide><img src="photo-1.jpg" alt="" /></div>
  <div kuiCarouselSlide><img src="photo-2.jpg" alt="" /></div>
  <div kuiCarouselSlide><img src="photo-3.jpg" alt="" /></div>
</kui-carousel>
```

```ts
protected readonly slide = signal(0);
```

`ariaLabel` defaults to the `carousel.label` message (`Slides`) and should use a content-specific name when one is available. It
must not contain the word "carousel" -- the region's own `aria-roledescription="carousel"`
already announces that to screen readers.

## Examples

Rendered at /components/carousel:

### basic-carousel-example

#### basic-carousel-example.html

```html
<div class="carousel-example">
  <kui-carousel ariaLabel="Product photos" [(index)]="slide">
    <div kuiCarouselSlide class="carousel-slide">Slide 1</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 2</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 3</div>
  </kui-carousel>
</div>
```

#### basic-carousel-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCarousel, KuiCarouselSlide } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-carousel-example',
  imports: [KuiCarousel, KuiCarouselSlide],
  templateUrl: './basic-carousel-example.html',
  styleUrl: './basic-carousel-example.scss',
})
export class BasicCarouselExample {
  protected readonly slide = signal(0);
}
```

#### basic-carousel-example.scss

```scss
.carousel-example {
  inline-size: min(100%, 520px);
}

.carousel-slide {
  display: grid;
  place-items: center;
  min-block-size: 120px;
  font-weight: var(--kui-font-weight-semibold, 600);
  color: var(--kui-color-text);
}
```

### carousel-items-example

#### carousel-items-example.html

```html
<div class="carousel-example">
  <kui-carousel ariaLabel="Two at a time" [itemsPerView]="2" loop>
    <div kuiCarouselSlide class="carousel-slide">Slide 1</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 2</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 3</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 4</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 5</div>
  </kui-carousel>
</div>
```

#### carousel-items-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCarousel, KuiCarouselSlide } from '@kikita-labs/ui';

@Component({
  selector: 'app-carousel-items-example',
  imports: [KuiCarousel, KuiCarouselSlide],
  templateUrl: './carousel-items-example.html',
  styleUrl: './carousel-items-example.scss',
})
export class CarouselItemsExample {}
```

#### carousel-items-example.scss

```scss
.carousel-example {
  inline-size: min(100%, 520px);
}

.carousel-slide {
  display: grid;
  place-items: center;
  min-block-size: 120px;
  font-weight: var(--kui-font-weight-semibold, 600);
  color: var(--kui-color-text);
}
```

### carousel-autoplay-example

#### carousel-autoplay-example.html

```html
<div class="carousel-example">
  <kui-carousel ariaLabel="Autoplay slides" autoplay [autoplayInterval]="4000">
    <div kuiCarouselSlide class="carousel-slide">Slide 1</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 2</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 3</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 4</div>
  </kui-carousel>
</div>
```

#### carousel-autoplay-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCarousel, KuiCarouselSlide } from '@kikita-labs/ui';

@Component({
  selector: 'app-carousel-autoplay-example',
  imports: [KuiCarousel, KuiCarouselSlide],
  templateUrl: './carousel-autoplay-example.html',
  styleUrl: './carousel-autoplay-example.scss',
})
export class CarouselAutoplayExample {}
```

#### carousel-autoplay-example.scss

```scss
.carousel-example {
  inline-size: min(100%, 520px);
}

.carousel-slide {
  display: grid;
  place-items: center;
  min-block-size: 120px;
  font-weight: var(--kui-font-weight-semibold, 600);
  color: var(--kui-color-text);
}
```

### carousel-controls-example

#### carousel-controls-example.html

```html
<div class="carousel-example">
  <kui-carousel ariaLabel="Dots only" [showArrows]="false" [draggable]="false">
    <div kuiCarouselSlide class="carousel-slide">Slide 1</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 2</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 3</div>
  </kui-carousel>
</div>
```

#### carousel-controls-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCarousel, KuiCarouselSlide } from '@kikita-labs/ui';

@Component({
  selector: 'app-carousel-controls-example',
  imports: [KuiCarousel, KuiCarouselSlide],
  templateUrl: './carousel-controls-example.html',
  styleUrl: './carousel-controls-example.scss',
})
export class CarouselControlsExample {}
```

#### carousel-controls-example.scss

```scss
.carousel-example {
  inline-size: min(100%, 520px);
}

.carousel-slide {
  display: grid;
  place-items: center;
  min-block-size: 120px;
  font-weight: var(--kui-font-weight-semibold, 600);
  color: var(--kui-color-text);
}
```

### carousel-messages-example

#### carousel-messages-example.html

```html
<div class="carousel-example">
  <kui-carousel [messages]="messages">
    <div kuiCarouselSlide class="carousel-slide">Slide 1</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 2</div>
    <div kuiCarouselSlide class="carousel-slide">Slide 3</div>
  </kui-carousel>
</div>
```

#### carousel-messages-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCarousel, type KuiCarouselMessages, KuiCarouselSlide } from '@kikita-labs/ui';

@Component({
  selector: 'app-carousel-messages-example',
  imports: [KuiCarousel, KuiCarouselSlide],
  templateUrl: './carousel-messages-example.html',
  styleUrl: './carousel-messages-example.scss',
})
export class CarouselMessagesExample {
  protected readonly messages: Partial<KuiCarouselMessages> = {
    label: 'Galerie',
    previous: 'Vorherige Folie',
    next: 'Naechste Folie',
    dots: 'Folie waehlen',
  };
}
```

#### carousel-messages-example.scss

```scss
.carousel-example {
  inline-size: min(100%, 520px);
}

.carousel-slide {
  display: grid;
  place-items: center;
  min-block-size: 120px;
  font-weight: var(--kui-font-weight-semibold, 600);
  color: var(--kui-color-text);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| itemsPerView | number \| undefined | undefined | How many slides are visible at once (defaults.carousel.itemsPerView, then 1). Invalid or non-positive static values use 1. The highest reachable index is slideCount - itemsPerView, and the dot picker renders exactly that many dots. |
| loop | boolean \| undefined | undefined | Wraps navigation at the edges instead of disabling Prev and Next there. Falls back to defaults.carousel.loop, then false. |
| autoplay | boolean \| undefined | undefined | Advances automatically on a timer and always shows Play/Pause; pauses while the pointer, focus or a touch is inside. Falls back to defaults.carousel.autoplay, then false. |
| autoplayInterval | number \| undefined | undefined | Autoplay delay between slides in ms (defaults.carousel.autoplayInterval, then 4000). Invalid or non-positive static values use 4000. |
| showArrows | boolean \| undefined | undefined | Shows the Prev and Next arrows (defaults.carousel.showArrows, then true). Swipe and scroll work regardless. |
| showDots | boolean \| undefined | undefined | Shows the dot picker below the track (defaults.carousel.showDots, then true). Swipe and scroll work regardless. |
| draggable | boolean \| undefined | undefined | Adds mouse drag-to-scroll on top of the always-native touch swipe (defaults.carousel.draggable, then true). false also locks wheel and trackpad scroll and removes the track from the tab order. |
| ariaLabel | string \| undefined | undefined | Accessible name of the region. Falls back to the carousel.label message (Slides); use a content-specific name that does not contain "carousel". |
| messages | Partial<KuiCarouselMessages> \| undefined | undefined | Per-instance text overrides for the label, role descriptions, controls and slide names. They win over scoped and root messages. |
| [(index)] | number | 0 | Index of the first visible slide. A debounced scroll listener snaps it to the nearest slide after a swipe or drag. |
| (indexChange) | number | - | Emitted whenever index changes (model output). |
| [kuiCarouselSlide] | content slot | - | Marks projected slide content: role="group" with aria-roledescription="slide" and an "N of total" name. It has no inputs. |
| --kui-carousel-gap / -radius / -slide-radius | CSS custom properties | - | Gap between slides and the region and slide corner radii. |
| --kui-carousel-bg / -border / -slide-bg | CSS custom properties | - | Region background and border and the slide backdrop. |
| --kui-carousel-control-bg / -control-shadow | CSS custom properties | - | Backdrop circle and shadow of the Prev, Next and Play controls. |
| --kui-carousel-dot-bg / -dot-bg-active / -dot-size | CSS custom properties | - | Colour of the dots, the active dot and the dot size. |
| KuiCarouselOptions | interface | - | Shape of defaults.carousel: itemsPerView, loop, autoplay, autoplayInterval, showArrows, showDots, draggable, previousIcon and nextIcon. |

## Accessibility

- The outer element is `role="region"` with `aria-roledescription="carousel"` and `ariaLabel`,
  which defaults to `Slides`; provide a content-specific label where possible.
- Each slide is `role="group"` with `aria-roledescription="slide"` and an `aria-label` of
  `"N of total"`.
- The dot picker follows the "tabbed carousel" variant: `role="tablist"`/`role="tab"`,
  `aria-selected`, `aria-controls` pointing at the corresponding slide's `id`, and roving
  `tabindex` (only the selected dot is in the natural tab order; arrow keys/`Home`/`End` move
  both focus and selection between dots).
- The region itself also responds to `ArrowLeft`/`ArrowRight`/`Home`/`End` to move the current
  slide, independent of dot focus.
- While `draggable` is `true` the slide track is a scrollable region, so it is a keyboard tab stop
  (`tabindex="0"`) with a visible focus ring; the arrow keys above then move slides even when the
  arrows and dots are hidden. With `draggable=false` the track does not scroll and is not a tab stop.
- Prev/Next/Play/Pause are `button[kuiIconButton]` with a required `aria-label`, no visible text.
- Range boundaries (when `loop` is `false`) use the native `disabled` attribute on Prev/Next,
  removing them from tab order, not just dimming them.
- Play/Pause order and pausing autoplay on hover/focus follow the W3C APG "Auto-Rotating Image
  Carousel Example".
- Mouse drag-to-scroll (`draggable`, default `true`) is an added affordance on top of the required
  non-drag alternatives (Prev/Next buttons, dots, keyboard) -- never the only way to navigate,
  except in the same intentionally-noncompliant `showArrows=false, showDots=false` combination
  already called out above.
- Combining `autoplay` with `showArrows=false`, `showDots=false`, and `draggable=false` leaves no
  way to pause a self-updating carousel by hand, which conflicts with WCAG 2.2.2 (Pause, Stop,
  Hide) for content that auto-updates for longer than 5 seconds. Every one of those props is
  reachable individually for other reasons; this specific combination is a deliberate, documented
  spec trade-off (see the design spec's own open questions), not a recommended production pattern
  -- only use it for purely decorative rotation that carries no information a user would need to
  pause and read.

| Key                      | Where       | Action                                      |
| ------------------------ | ----------- | ------------------------------------------- |
| `ArrowLeft`/`ArrowRight` | Region      | Previous/next slide.                        |
| `Home`/`End`             | Region      | Jump to the first/last reachable slide.     |
| `ArrowLeft`/`ArrowRight` | Dot picker  | Move focus and selection between dots.      |
| `Home`/`End`             | Dot picker  | Move focus and selection to first/last dot. |
| `Enter`/`Space`          | Any control | Activates the focused button.               |

## Playground

Available at /components/carousel/playground.

---

<!-- route: /components/checkbox -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/checkbox.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/checkbox.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Checkbox

> Native checkbox styling with field state integration.

- Status: available
- Route: /components/checkbox
- Package: @kikita-labs/ui@2.0.0
- Import: KuiCheckbox from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/checkbox.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-field label="Notifications" hint="Control product and release emails">
  <label>
    <input kuiCheckbox type="checkbox" />
    Receive updates
  </label>
</kui-field>
```

Inside `kui-field`, `kuiCheckbox` receives the field id, `aria-describedby`, and invalid state
automatically. Keep the native label around the checkbox for the option text itself.

## Examples

Rendered at /components/checkbox:

### basic-checkbox-example

#### basic-checkbox-example.html

```html
<kui-field label="Notifications" hint="Control product and release emails">
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" [checked]="receiveUpdates()" />
    <span>Receive updates</span>
  </label>
</kui-field>
```

#### basic-checkbox-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCheckbox, KuiField } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-checkbox-example',
  imports: [KuiCheckbox, KuiField],
  templateUrl: './basic-checkbox-example.html',
  styleUrl: './basic-checkbox-example.scss',
})
export class BasicCheckboxExample {
  protected readonly receiveUpdates = signal(true);
}
```

#### basic-checkbox-example.scss

```scss
:host {
  display: block;
  inline-size: min(100%, 360px);
}

.checkbox-option {
  display: inline-flex;
  align-items: center;
  gap: var(--kui-space-2, 8px);
  color: var(--kui-color-text);
}
```

### checkbox-size-example

#### checkbox-size-example.html

```html
<div class="checkbox-size-example">
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" size="xs" />
    <span>Extra small</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" size="sm" checked />
    <span>Small</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" size="md" checked />
    <span>Medium</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" size="lg" />
    <span>Large</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" disabled />
    <span>Disabled</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" disabled checked />
    <span>Disabled and checked</span>
  </label>
  <label class="checkbox-option">
    <input kuiCheckbox type="checkbox" invalid />
    <span>Invalid</span>
  </label>
</div>
```

#### checkbox-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCheckbox } from '@kikita-labs/ui';

@Component({
  selector: 'app-checkbox-size-example',
  imports: [KuiCheckbox],
  templateUrl: './checkbox-size-example.html',
  styleUrl: './checkbox-size-example.scss',
})
export class CheckboxSizeExample {}
```

#### checkbox-size-example.scss

```scss
.checkbox-size-example {
  display: grid;
  gap: var(--kui-space-3, 12px);
  justify-content: center;
}

.checkbox-option {
  display: inline-flex;
  align-items: center;
  gap: var(--kui-space-2, 8px);
  color: var(--kui-color-text);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' | 'md' | Checkbox size mapped to Kikita checkbox tokens. |
| invalid | boolean | false | Marks the checkbox invalid outside a field error state. |
| id | string \| undefined | - | Explicit id override. Inside kui-field, the field id is used when omitted. |
| checked | boolean | false | Native checked state. Not a directive input; bind it directly on the input element. |
| disabled | boolean | false | Native disabled state. Not a directive input; bind it directly on the input element. |
| indeterminate | boolean | false | Native DOM property, not an HTML attribute or directive input. Set it imperatively on the element to show the dash-mark state; .kui-checkbox styles :indeterminate. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/checkbox/playground.

---

<!-- route: /components/chip -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/chip.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/chip.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Chip

> Compact token for selected values, filters, and entity references.

- Status: available
- Route: /components/chip
- Package: @kikita-labs/ui@2.0.0
- Import: KuiChip from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/chip.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<span kuiChip>Design</span>

<!-- Primary way to make a chip removable: the `removable` input renders a default
     crossmark button and wires up `removed` for you. -->
<span
  kuiChip
  size="sm"
  appearance="primary"
  removable
  removeLabel="Remove Design"
  (removed)="removeTag('design')"
>
  <span class="kui-chip-label">Design</span>
</span>

<button kuiChip type="button">Filter</button>
```

Only reach for `button[kuiChipRemove]` when the default button in `removable` isn't
enough — a custom icon, extra markup, or a design that needs a fully custom remove
control. It's a behavior-only directive (click handling, ARIA wiring) with no visual
of its own: project whatever content you want as the button's children, for example a
`kuiIconButton`:

```html
<span kuiChip size="sm" appearance="primary" (removed)="removeTag('design')">
  <span class="kui-chip-label">Design</span>
  <button kuiChipRemove kuiIconButton icon="x" size="xs" aria-label="Remove Design"></button>
</span>
```

`kuiIconButton` is its own directive; import `KuiIconButton` alongside
`KuiChip`/`KuiChipRemove` to use this pattern. See [Icon
Button](icon-button.md).

Do not combine `removable` and a projected `button[kuiChipRemove]` on the same chip —
pick one.

## Examples

Rendered at /components/chip:

### basic-chip-example

#### basic-chip-example.html

```html
<div class="basic-chip-example">
  <span kuiChip>Design</span>
  <span kuiChip appearance="primary">Engineering</span>
  <span kuiChip appearance="success">Shipped</span>
</div>
```

#### basic-chip-example.ts

```ts
import { Component } from '@angular/core';

import { KuiChip } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-chip-example',
  imports: [KuiChip],
  templateUrl: './basic-chip-example.html',
  styleUrl: './basic-chip-example.scss',
})
export class BasicChipExample {}
```

#### basic-chip-example.scss

```scss
.basic-chip-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### chip-states-example

#### chip-states-example.html

```html
<div class="chip-states-example">
  <span kuiChip disabled>
    <span class="kui-chip-label">Design</span>
    <button kuiChipRemove type="button" aria-label="Remove Design"></button>
  </span>
  <span kuiChip invalid appearance="danger">Missing owner</span>
</div>
```

#### chip-states-example.ts

```ts
import { Component } from '@angular/core';

import { KuiChip, KuiChipRemove } from '@kikita-labs/ui';

@Component({
  selector: 'app-chip-states-example',
  imports: [KuiChip, KuiChipRemove],
  templateUrl: './chip-states-example.html',
  styleUrl: './chip-states-example.scss',
})
export class ChipStatesExample {}
```

#### chip-states-example.scss

```scss
.chip-states-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### interactive-chip-example

#### interactive-chip-example.html

```html
<div class="interactive-chip-example">
  <button
    kuiChip
    type="button"
    [appearance]="selected() === 'all' ? 'primary' : 'neutral'"
    (click)="select('all')"
  >
    All
  </button>
  <button
    kuiChip
    type="button"
    [appearance]="selected() === 'open' ? 'primary' : 'neutral'"
    (click)="select('open')"
  >
    Open
  </button>
  <button
    kuiChip
    type="button"
    [appearance]="selected() === 'closed' ? 'primary' : 'neutral'"
    (click)="select('closed')"
  >
    Closed
  </button>
</div>
```

#### interactive-chip-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiChip } from '@kikita-labs/ui';

@Component({
  selector: 'app-interactive-chip-example',
  imports: [KuiChip],
  templateUrl: './interactive-chip-example.html',
  styleUrl: './interactive-chip-example.scss',
})
export class InteractiveChipExample {
  protected readonly selected = signal<'all' | 'open' | 'closed'>('all');

  protected select(filter: 'all' | 'open' | 'closed'): void {
    this.selected.set(filter);
  }
}
```

#### interactive-chip-example.scss

```scss
.interactive-chip-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### removable-chip-example

#### removable-chip-example.html

```html
<div class="removable-chip-example">
  @for (tag of tags(); track tag) {
    <span
      kuiChip
      appearance="primary"
      removable
      [removeLabel]="'Remove ' + tag"
      (removed)="removeTag(tag)"
    >
      <span class="kui-chip-label">{{ tag }}</span>
    </span>
  }
</div>
```

#### removable-chip-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiChip } from '@kikita-labs/ui';

@Component({
  selector: 'app-removable-chip-example',
  imports: [KuiChip],
  templateUrl: './removable-chip-example.html',
  styleUrl: './removable-chip-example.scss',
})
export class RemovableChipExample {
  protected readonly tags = signal(['Design', 'Engineering', 'Product']);

  protected removeTag(tag: string): void {
    this.tags.update((current) => current.filter((existing) => existing !== tag));
  }
}
```

#### removable-chip-example.scss

```scss
.removable-chip-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| appearance | 'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info' | 'neutral' | Semantic visual treatment mapped to Kikita UI status tokens. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' | 'md' | Chip size. sm is the size used inside Select and Combobox controls. Falls back to defaults.chip.size, then the global defaults.size. |
| disabled | boolean | false | Reduces opacity and makes the nested remove action inert. |
| invalid | boolean | false | Shows the invalid border treatment. |
| removable | boolean | false | Renders a default remove button (crossmark icon) as the last child. Primary way to make a chip removable; use kuiChipRemove instead only for a custom icon or extra content. |
| removeLabel | string \| undefined | 'Remove' | Accessible name for the default remove button rendered by removable. Provide a value-specific label, for example "Remove Design". |
| removed | output: void | - | Emitted when the default remove button or a nested button[kuiChipRemove] is activated. |
| kuiChipRemove | directive on button | - | Marks a native button as the chip remove action. Use only when the default removable button is not enough (custom icon, extra content); do not combine both on the same chip. Needs its own aria-label, for example "Remove Design". |
| --kui-chip-bg | CSS color | - | Chip background color. |
| --kui-chip-bg-hover | CSS color | - | Chip background color on hover for interactive chips. |
| --kui-chip-border | CSS color | - | Chip border color. |
| --kui-chip-text | CSS color | - | Chip label text color. |
| --kui-chip-radius | CSS length | - | Chip corner radius. |
| --kui-chip-height-xs | CSS length | - | Chip block size for size="xs". |
| --kui-chip-height-sm | CSS length | - | Chip block size for size="sm". |
| --kui-chip-height-md | CSS length | - | Chip block size for size="md" (default). |
| --kui-chip-height-lg | CSS length | - | Chip block size for size="lg". |
| --kui-chip-remove-color | CSS color | - | Remove icon color. |
| --kui-chip-remove-color-hover | CSS color | - | Remove icon color on hover. |
| --kui-chip-disabled-opacity | CSS number | - | Opacity applied to the whole chip when disabled. |
| KuiChipOptions | interface | - | Shape of defaults.chip: size and removeIcon (takes precedence over defaults.icons.remove). |

## Accessibility

- Static chip: use a non-interactive host such as `span`.
- Interactive chip: use a native `button` or `a`.
- Remove action is a native `<button>`, either the `removable` default or a projected
  `button[kuiChipRemove]`.
- Give the remove button an accessible name: `removeLabel` for `removable`, or an
  explicit `aria-label` such as `aria-label="Remove Design"` on a custom
  `button[kuiChipRemove]`.
- Disabled chips mark remove buttons as `aria-disabled="true"` and `tabindex="-1"`.
- Select and Combobox own keyboard behavior for Delete/Backspace selected-value removal.

## Playground

Available at /components/chip/playground.

---

<!-- route: /components/color-input -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/color-input.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/color-input.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Color Input

> Color value input.

- Status: available
- Route: /components/color-input
- Package: @kikita-labs/ui@2.0.0
- Import: KuiColorInput from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/color-input.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-field label="Primary seed" hint="Hex or oklch().">
  <input kuiColorInput value="#5b4fe0" />
</kui-field>
```

OKLCH values are accepted as text seed values:

```html
<kui-field label="Primary seed">
  <input kuiColorInput value="oklch(0.52 0.25 285)" />
</kui-field>
```

Hex values also enable the browser-native color picker from the swatch button:

```html
<kui-field label="Danger seed">
  <input kuiColorInput value="#e0002a" />
</kui-field>
```

## Examples

Rendered at /components/color-input:

### basic-color-input-example

#### basic-color-input-example.html

```html
<div class="basic-color-input-example">
  <kui-field label="Primary seed" hint="Hex and OKLCH values are supported.">
    <input
      kuiColorInput
      value="#5b4fe0"
      autocomplete="off"
      swatchLabel="Open primary seed color picker"
    />
  </kui-field>
</div>
```

#### basic-color-input-example.ts

```ts
import { Component } from '@angular/core';

import { KuiColorInput, KuiField } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-color-input-example',
  imports: [KuiColorInput, KuiField],
  templateUrl: './basic-color-input-example.html',
  styleUrl: './basic-color-input-example.scss',
})
export class BasicColorInputExample {}
```

#### basic-color-input-example.scss

```scss
.basic-color-input-example {
  display: grid;
  max-width: 28rem;
  min-width: 0;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| kuiColorInput | directive | - | Applies Kikita color-input styling and picker affordances to a native input. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' | 'md' | Control height matched to Kikita UI size tokens. Falls back to defaults.colorInput.size, then the parent field, then the global defaults.size. |
| invalid | boolean | false | Applies an error border and inherits invalid state from parent kui-field. |
| id | string \| undefined | field id | Native input id override. |
| swatchLabel | string \| undefined | colorInput.openPicker message | Accessible label for the swatch button. Undefined when omitted: the rendered text comes from the colorInput.openPicker message (Open color picker). |
| messages | Partial<KuiColorInputMessages> \| undefined | undefined | Per-instance text overrides (openPicker, pickerLabel, and the other picker labels). They win over scoped and root messages. |
| KuiColorInputOptions | interface | - | Shape of defaults.colorInput: size and chevronIcon (takes precedence over defaults.icons.pickerChevron). |

## Accessibility

- The control uses a native text input for editable value semantics.
- The swatch is a native button with an accessible name containing the current
  value.
- The chevron is a native button and rotates while the picker is open.
- The 2D surface exposes slider semantics and supports arrow-key changes.
- The hue control is a native range input.
- The swatch focus ring is visible and does not shift layout.
- Invalid state is exposed through `aria-invalid`.
- Place the input inside `kui-field` for label and description wiring.

## Playground

Available at /components/color-input/playground.

---

<!-- route: /components/combobox -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/combobox.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/combobox.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Combobox

> Searchable input with projected options and async mode.

- Status: available
- Route: /components/combobox
- Package: @kikita-labs/ui@2.0.0
- Import: KuiCombobox from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/combobox.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-field label="Assignee">
  <input
    kuiCombobox
    [(value)]="assignee"
    [(query)]="query"
    [kuiLabelFn]="personLabel"
    placeholder="Search people..."
    (search)="query.set($event)"
  />

  <kui-dropdown>
    @for (person of filteredPeople(); track person.id) {
    <button kuiOption [value]="person">
      <span class="kui-combobox-match-label">
        @for (segment of person.name | kuiComboboxHighlight: query(); track $index) { @if
        (segment.match) {
        <mark class="kui-combobox-highlight">{{ segment.text }}</mark>
        } @else {
        <span>{{ segment.text }}</span>
        } }
      </span>
    </button>
    } @empty {
    <div class="kui-combobox-empty">No people found</div>
    }
  </kui-dropdown>
</kui-field>
```

```ts
assignee = signal<Person | null>(null);
query = signal('');
personLabel = (person: Person) => person.name;
filteredPeople = computed(() => {
  const q = this.query().toLocaleLowerCase();
  return q
    ? this.people.filter((person) => person.name.toLocaleLowerCase().includes(q))
    : this.people;
});
```

Inside `kui-field`, Combobox inherits field id, label association, `aria-describedby`,
invalid state, and field size. With Angular Signal Forms, the field gates the required error and
`aria-invalid` state until the control is touched; selecting a valid option clears that state.

## Examples

Rendered at /components/combobox:

### async-combobox-example

#### async-combobox-example.html

```html
<kui-field label="Reviewer" hint="Simulates a remote lookup with a loading row">
  <input
    kuiCombobox
    mode="async"
    [(value)]="reviewer"
    [(query)]="reviewerQuery"
    [loading]="loading()"
    [kuiLabelFn]="personLabel"
    placeholder="Type to search..."
    (search)="loadReviewers($event)"
  />

  <kui-dropdown>
    @if (loading()) {
      <div class="kui-combobox-loading-row">
        <span class="kui-combobox-loader" aria-hidden="true"></span>
        Loading people
      </div>
    } @else if (errorMessage(); as lookupError) {
      <div class="kui-combobox-empty" role="alert">{{ lookupError }}</div>
    } @else {
      @for (person of reviewers(); track person.id) {
        <button kuiOption [value]="person">{{ person.name }}</button>
      } @empty {
        <div class="kui-combobox-empty">No matches</div>
      }
    }
  </kui-dropdown>
</kui-field>
```

#### async-combobox-example.ts

```ts
import { Component, effect, inject, signal } from '@angular/core';

import { KuiCombobox, KuiDropdown, KuiField, KuiOption } from '@kikita-labs/ui';

import { ALL_REVIEWERS, type AsyncReviewer, AsyncReviewerService } from './async-reviewer.service';

@Component({
  selector: 'app-async-combobox-example',
  imports: [KuiCombobox, KuiDropdown, KuiField, KuiOption],
  providers: [AsyncReviewerService],
  templateUrl: './async-combobox-example.html',
  styleUrl: './async-combobox-example.scss',
})
export class AsyncComboboxExample {
  private readonly reviewerLookup = inject(AsyncReviewerService);
  private readonly requestedQuery = signal<string | null>(null);

  protected readonly reviewer = signal<AsyncReviewer | null>(null);
  protected readonly reviewerQuery = signal('');
  protected readonly reviewers = signal<readonly AsyncReviewer[]>(ALL_REVIEWERS);
  protected readonly loading = signal(false);
  protected readonly errorMessage = signal<string | null>(null);

  protected readonly personLabel = (person: AsyncReviewer) => person.name;

  private readonly reviewerLookupEffect = effect((onCleanup) => {
    const query = this.requestedQuery();

    if (query === null) {
      return;
    }

    this.loading.set(true);
    this.errorMessage.set(null);

    const subscription = this.reviewerLookup.search(query).subscribe({
      next: (reviewers) => {
        this.reviewers.set(reviewers);
        this.loading.set(false);
      },
      error: () => {
        this.reviewers.set([]);
        this.loading.set(false);
        this.errorMessage.set('Reviewers could not be loaded. Try again.');
      },
    });

    onCleanup(() => subscription.unsubscribe());
  });

  protected loadReviewers(query: string): void {
    this.requestedQuery.set(query);
  }
}
```

#### async-reviewer.service.ts

```ts
import { Injectable } from '@angular/core';

import { map, type Observable, timer } from 'rxjs';

export interface AsyncReviewer {
  readonly id: string;
  readonly name: string;
}

const ALL_REVIEWERS: readonly AsyncReviewer[] = [
  { id: 'amelia', name: 'Amelia Novak' },
  { id: 'daniel', name: 'Daniel Kowalski' },
  { id: 'harper', name: 'Harper Singh' },
  { id: 'ines', name: 'Ines Delacroix' },
  { id: 'ravi', name: 'Ravi Patel' },
];

@Injectable()
export class AsyncReviewerService {
  public search(query: string): Observable<readonly AsyncReviewer[]> {
    return timer(400).pipe(
      map(() => {
        const normalizedQuery = query.toLocaleLowerCase();

        return normalizedQuery
          ? ALL_REVIEWERS.filter((reviewer) =>
              reviewer.name.toLocaleLowerCase().includes(normalizedQuery),
            )
          : ALL_REVIEWERS;
      }),
    );
  }
}

export { ALL_REVIEWERS };
```

#### async-combobox-example.scss

```scss
:host {
  display: block;
  max-inline-size: 320px;
}
```

### basic-combobox-example

#### basic-combobox-example.html

```html
<kui-field label="Assignee" hint="Type to filter projected options">
  <input
    kuiCombobox
    [(value)]="assignee"
    [(query)]="query"
    [kuiLabelFn]="personLabel"
    placeholder="Search people..."
    (search)="query.set($event)"
  />

  <kui-dropdown>
    @for (person of filteredPeople(); track person.id) {
      <button kuiOption [value]="person">
        <span class="kui-combobox-match-label">
          @for (segment of person.name | kuiComboboxHighlight: query(); track $index) {
            @if (segment.match) {
              <mark class="kui-combobox-highlight">{{ segment.text }}</mark>
            } @else {
              <span>{{ segment.text }}</span>
            }
          }
        </span>
      </button>
    } @empty {
      <div class="kui-combobox-empty">No people found</div>
    }
  </kui-dropdown>
</kui-field>
```

#### basic-combobox-example.ts

```ts
import { Component, computed, signal } from '@angular/core';

import {
  KuiCombobox,
  KuiComboboxHighlightPipe,
  KuiDropdown,
  KuiField,
  KuiOption,
} from '@kikita-labs/ui';

interface Person {
  readonly id: string;
  readonly name: string;
}

const PEOPLE: readonly Person[] = [
  { id: 'amelia', name: 'Amelia Novak' },
  { id: 'daniel', name: 'Daniel Kowalski' },
  { id: 'harper', name: 'Harper Singh' },
  { id: 'ines', name: 'Ines Delacroix' },
  { id: 'ravi', name: 'Ravi Patel' },
];

@Component({
  selector: 'app-basic-combobox-example',
  imports: [KuiCombobox, KuiComboboxHighlightPipe, KuiDropdown, KuiField, KuiOption],
  templateUrl: './basic-combobox-example.html',
  styleUrl: './basic-combobox-example.scss',
})
export class BasicComboboxExample {
  protected readonly assignee = signal<Person | null>(null);
  protected readonly query = signal('');

  protected readonly personLabel = (person: Person) => person.name;

  protected readonly filteredPeople = computed(() => {
    const q = this.query().toLocaleLowerCase();

    return q ? PEOPLE.filter((person) => person.name.toLocaleLowerCase().includes(q)) : PEOPLE;
  });
}
```

#### basic-combobox-example.scss

```scss
:host {
  display: block;
  max-inline-size: 320px;
}
```

### combobox-field-states-example

#### combobox-field-states-example.html

```html
<div class="combobox-field-states-example">
  <kui-field label="Owner" hint="Disabled prevents editing and opening the dropdown">
    <input kuiCombobox disabled [(value)]="disabledOwner" placeholder="Search people..." />
    <kui-dropdown>
      <button kuiOption value="engineer">Software Engineer</button>
      <button kuiOption value="designer">Designer</button>
    </kui-dropdown>
  </kui-field>

  <kui-field label="Owner" error="Choose an owner before continuing">
    <input kuiCombobox invalid [(value)]="invalidOwner" placeholder="Search people..." />
    <kui-dropdown>
      <button kuiOption value="engineer">Software Engineer</button>
      <button kuiOption value="designer">Designer</button>
    </kui-dropdown>
  </kui-field>
</div>
```

#### combobox-field-states-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCombobox, KuiDropdown, KuiField, KuiOption } from '@kikita-labs/ui';

@Component({
  selector: 'app-combobox-field-states-example',
  imports: [KuiCombobox, KuiDropdown, KuiField, KuiOption],
  templateUrl: './combobox-field-states-example.html',
  styleUrl: './combobox-field-states-example.scss',
})
export class ComboboxFieldStatesExample {
  protected readonly disabledOwner = signal<string | null>('engineer');
  protected readonly invalidOwner = signal<string | null>(null);
}
```

#### combobox-field-states-example.scss

```scss
.combobox-field-states-example {
  display: grid;
  gap: var(--kui-space-4, 16px);
  max-inline-size: 320px;
}
```

### free-combobox-example

#### free-combobox-example.html

```html
<kui-field label="Tag" hint="Type a custom tag or choose a suggestion">
  <input kuiCombobox mode="free" [(value)]="tag" placeholder="Type or choose..." />
  <kui-dropdown>
    <button kuiOption value="Bug">Bug</button>
    <button kuiOption value="Feature">Feature</button>
    <button kuiOption value="Regression">Regression</button>
  </kui-dropdown>
</kui-field>
```

#### free-combobox-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCombobox, KuiDropdown, KuiField, KuiOption } from '@kikita-labs/ui';

@Component({
  selector: 'app-free-combobox-example',
  imports: [KuiCombobox, KuiDropdown, KuiField, KuiOption],
  templateUrl: './free-combobox-example.html',
  styleUrl: './free-combobox-example.scss',
})
export class FreeComboboxExample {
  protected readonly tag = signal<string | null>(null);
}
```

#### free-combobox-example.scss

```scss
:host {
  display: block;
  max-inline-size: 320px;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| value | T \| string \| null | null | Selected value. Bound by [formField] or [(value)]. |
| query | string | '' | Current search text shown in the native input. |
| search | output: string | - | Emitted on every native input edit. Use for local filtering or remote requests. |
| kuiLabelFn | (item: T) => string | String() | Maps a selected object value to display text. Required when T is not a primitive. |
| placeholder | string | '' | Native input placeholder shown when no value is selected. |
| mode | 'filter' \| 'free' \| 'async' | 'filter' | filter clears the value while editing until a kuiOption is selected. free stores typed text as the value. async documents that filtering happens outside the directive. |
| clearable | boolean \| undefined | true | Shows a clear affordance. Falls back to defaults.combobox, then defaults.field, then true. |
| loading | boolean | false | Shows a suffix loader. Loading row content inside kui-dropdown is projected by the consumer. |
| disabled | boolean | false | Disables the native input. Set by [formField] or directly. |
| readonly | boolean | false | Keeps the value readable but prevents editing and opening the dropdown. |
| invalid | boolean | false | Applies ARIA invalid state. kui-field also contributes invalid state from validation. |
| errors | readonly ValidationError[] | [] | Validation errors set by [formField], consumed by kui-field for automatic error text. |
| touched | boolean | false | Touched state set by [formField] or Signal Forms. |
| touch | output: void | - | Emitted when an opened dropdown closes; marks the control touched for Signal Forms. |
| id | string \| undefined | undefined | Explicit id override. Inside kui-field, the field id is used when omitted. |
| kuiOption | directive | - | Marks a projected option inside kui-dropdown. Provides role="option", aria-selected, disabled state, and keyboard navigation. |
| kuiComboboxHighlight | pipe: (label: string, query: string \| null \| undefined) => readonly { text: string; match: boolean }[] | - | Splits an option label into plain and matched segments for highlighting the current query. |
| provideKuiDefaults({ combobox }) | (defaults: KuiComponentDefaults) => Provider | - | Registers combobox defaults, such as clearable, for a subtree. Use provideKikitaUi({ defaults }) for the whole application. |
| KuiComboboxOptions | interface | - | Shape of the defaults.combobox key, read by the directive for the clearable fallback. |
| --kui-combobox-affordance-size | CSS custom property | - | Size of the suffix clear/chevron affordance controls. |
| --kui-combobox-suffix-gap | CSS custom property | - | Gap between suffix affordances (clear button, chevron, loader). |
| --kui-combobox-loader-size | CSS custom property | - | Diameter of the suffix loading spinner. |
| --kui-combobox-loader-border-width | CSS custom property | - | Border width of the suffix loading spinner. |
| --kui-combobox-loader-duration | CSS custom property | - | Animation duration of the suffix loading spinner. |
| --kui-combobox-highlight-bg | CSS custom property | - | Background color of matched text inside kui-combobox-highlight. |
| --kui-combobox-highlight-text | CSS custom property | - | Text color of matched text inside kui-combobox-highlight. |
| --kui-combobox-highlight-radius | CSS custom property | - | Corner radius of the matched-text highlight mark. |

## Accessibility

- The host remains a native `<input>`.
- The input uses `role="combobox"`, `aria-haspopup="listbox"`, `aria-expanded`, and `aria-controls`.
- `kui-field` provides label, hint, error, required marker, `aria-describedby`, and inherited invalid state.
- `kui-dropdown` renders the popup listbox through Angular CDK overlay.
- `kuiOption` provides `role="option"`, `aria-selected`, disabled state, click selection, and keyboard navigation.
- Arrow keys open the dropdown and move focus to the first or last enabled option.
- Escape closes the dropdown.

## Playground

Available at /components/combobox/playground.

---

<!-- route: /components/command-palette -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/command-palette.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/command-palette.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Command Palette

> Searchable command overlay for application actions.

- Status: available
- Route: /components/command-palette
- Package: @kikita-labs/ui@2.0.0
- Import: KuiCommandPalette from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/command-palette.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<button kuiButton type="button" (click)="open.set(true)">Open command palette</button>

<kui-command-palette
  [(open)]="open"
  [groups]="groups"
  [(query)]="query"
  (selected)="runCommand($event)"
/>
```

```ts
readonly open = signal(false);
readonly query = signal('');

readonly groups: readonly KuiCommandGroup[] = [
  {
    heading: 'Navigation',
    items: [
      {
        id: 'projects',
        label: 'Open projects',
        shortcut: ['G', 'P'],
        keywords: ['workspace'],
      },
    ],
  },
];
```

## Examples

Rendered at /components/command-palette:

### basic-command-palette-example

#### basic-command-palette-example.html

```html
<div class="basic-command-palette-example">
  <button kuiButton type="button" (click)="open.set(true)">Open command palette</button>

  @if (selectedCommand(); as command) {
    <p class="basic-command-palette-example__selection">Selected: {{ command }}</p>
  }

  <kui-command-palette
    [(open)]="open"
    [(query)]="query"
    [groups]="groups"
    (selected)="runCommand($event)"
  />
</div>
```

#### basic-command-palette-example.ts

```ts
import { Component, signal } from '@angular/core';

import {
  KuiButton,
  type KuiCommandGroup,
  type KuiCommandItem,
  KuiCommandPalette,
} from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-command-palette-example',
  imports: [KuiButton, KuiCommandPalette],
  templateUrl: './basic-command-palette-example.html',
  styleUrl: './basic-command-palette-example.scss',
})
export class BasicCommandPaletteExample {
  protected readonly open = signal(false);
  protected readonly query = signal('');
  protected readonly selectedCommand = signal<string | null>(null);

  protected readonly groups: readonly KuiCommandGroup[] = [
    {
      heading: 'Navigation',
      items: [
        {
          id: 'projects',
          label: 'Open projects',
          description: 'Go to the project overview.',
          shortcut: ['G', 'P'],
          keywords: ['workspace'],
        },
        {
          id: 'components',
          label: 'Browse components',
          description: 'Open the component index.',
          shortcut: ['G', 'C'],
          keywords: ['docs', 'ui'],
        },
      ],
    },
    {
      heading: 'Project',
      items: [
        {
          id: 'rename',
          label: 'Rename project',
          description: 'Update the display name.',
          meta: 'Project',
          badge: 'New',
          shortcut: ['F2'],
          icon: 'R',
          keywords: ['edit', 'title'],
        },
        {
          id: 'delete',
          label: 'Delete project',
          danger: true,
          disabled: true,
        },
      ],
    },
  ];

  protected runCommand(item: KuiCommandItem): void {
    this.selectedCommand.set(item.label);
  }
}
```

#### basic-command-palette-example.scss

```scss
.basic-command-palette-example {
  display: grid;
  gap: var(--kui-space-3, 12px);
  justify-items: center;
}

.basic-command-palette-example__selection {
  margin: 0;
  color: var(--kui-color-text-muted);
  font-size: var(--kui-text-sm-size, 13px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| open | ModelSignal<boolean> | - | Two-way model controlling overlay visibility. |
| groups | readonly KuiCommandGroup[] | - | Command groups rendered in the list. |
| loading | boolean | - | Renders skeleton rows and sets aria-busy. |
| placeholder | string \| undefined | - | Search input placeholder. Undefined when omitted: the text comes from the commandPalette.placeholder message. |
| label | string \| undefined | - | Accessible label for the modal dialog and search input. Defaults to the commandPalette.label message. |
| emptyText | string \| undefined | - | Empty-state title when no command matches. Defaults to the commandPalette.empty message. |
| query | ModelSignal<string> | - | Two-way model for the current search value. |
| selected | OutputEmitterRef<KuiCommandItem> | - | Emits the selected command item. |
| messages | Partial<KuiCommandPaletteMessages> \| undefined | undefined | Per-instance text overrides (placeholder, label, empty, emptyDescription, clearSearch, key hints and the rest). They win over scoped and root messages. |
| KuiCommandItem.id | string | - | Required stable key, unique across every group of one palette. Development builds report empty, whitespace-containing and duplicate ids. |

## Accessibility

- Uses a CDK overlay with scroll blocking.
- Uses a modal dialog container with CDK focus trap.
- Focus moves to the search input after the overlay has rendered, on every open, including when another control had focus.
- The search input exposes combobox/listbox relationships through `aria-controls` and
  `aria-activedescendant`.
- Arrow keys move the active option, Enter selects it, Escape closes the palette.
- Disabled commands are skipped by keyboard navigation and cannot be selected.

## Playground

Available at /components/command-palette/playground.

---

<!-- route: /components/date-picker -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/date-picker.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/date-picker.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Date Picker

> Calendar date input.

- Status: available
- Route: /components/date-picker
- Package: @kikita-labs/ui@2.0.0
- Import: KuiDatePicker from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/date-picker.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-field label="Meeting date">
  <input kuiDatePicker [(value)]="date" />
  <kui-dropdown panelRole="dialog" panelWidth="auto" maxHeight="420px">
    <kui-calendar flat showFooter />
  </kui-dropdown>
</kui-field>
```

The calendar needs no `[value]`/`(valueChange)` or `[(viewDate)]` binding: when `kui-calendar`
is found as a sibling of `input[kuiDatePicker]` inside the same `kui-field`, the directive
auto-discovers it and wires `value`/`viewDate` both ways automatically — a day clicked in the
calendar updates the input, and a valid date typed in the input updates (and scrolls) the
calendar. This is the recommended usage.

Manually binding `[value]`/`(valueChange)`/`[(viewDate)]` on the calendar still works — it's no
longer required, not deprecated. If you keep the old pattern (e.g. bound to the same signal as
the input), the auto-wire effects and your binding stay in sync without fighting each other:

```html
<!-- Still supported: manual binding, same as before this feature shipped. -->
<kui-field label="Meeting date">
  <input kuiDatePicker [(value)]="date" [(viewDate)]="viewDate" />
  <kui-dropdown panelRole="dialog" panelWidth="auto" maxHeight="420px">
    <kui-calendar flat [(value)]="date" [(viewDate)]="viewDate" [showFooter]="true" />
  </kui-dropdown>
</kui-field>
```

Three things on `kui-dropdown` matter here, all different from its default (listbox) usage:

- `panelRole="dialog"` — the panel holds a calendar grid, not a list of options.
- `panelWidth="auto"` — sizes the panel to the calendar's own width (296px by default)
  instead of clipping it to the (usually narrower) field. This is why the popover is often
  wider than the input — that's intentional, not a bug: `kui-calendar` has a fixed width
  (`--kui-calendar-width`, 296px by default) because its day grid needs a minimum amount of
  room regardless of the trigger. Override `--kui-calendar-width` on `kui-calendar` if you want
  it narrower or wider — `panelWidth` only controls how the _dropdown panel_ relates to the
  trigger's width, not the calendar's own size, so switching it to `"anchor"` alone would just
  clip a still-296px-wide calendar into a narrower panel rather than shrink it.
- `maxHeight="420px"` — the calendar's natural height comfortably fits under this; it's a
  safety cap so the popover never renders unbounded when there isn't enough room in either
  direction, falling back to an internal scroll instead of visually overflowing.

And on `kui-calendar`:

- `flat` — the popover panel already draws its own background/border, so the calendar drops
  its own to avoid a double frame. See [Calendar](./calendar.md#flat-no-own-chrome).

## Examples

Rendered at /components/date-picker:

### basic-date-picker-example

#### basic-date-picker-example.html

```html
<div class="basic-date-picker-example">
  <kui-field
    label="Meeting date"
    hint="Type the date in your locale's layout or choose from the calendar."
  >
    <input kuiDatePicker [(value)]="meetingDate" [minDate]="minDate" [maxDate]="maxDate" />
    <kui-dropdown panelRole="dialog" panelWidth="auto" maxHeight="420px">
      <kui-calendar flat showFooter />
    </kui-dropdown>
  </kui-field>
</div>
```

#### basic-date-picker-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCalendar, KuiDatePicker, KuiDropdown, KuiField } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-date-picker-example',
  imports: [KuiCalendar, KuiDatePicker, KuiDropdown, KuiField],
  templateUrl: './basic-date-picker-example.html',
  styleUrl: './basic-date-picker-example.scss',
})
export class BasicDatePickerExample {
  protected readonly meetingDate = signal<Date | null>(new Date(2026, 6, 14));
  protected readonly minDate = new Date(2026, 6, 1);
  protected readonly maxDate = new Date(2026, 6, 31);
}
```

#### basic-date-picker-example.scss

```scss
.basic-date-picker-example {
  max-width: 22rem;
}
```

### date-picker-format-example

#### date-picker-format-example.html

```html
<div class="date-picker-format-example">
  <kui-field label="Locale layout" hint="Follows the locale of the nearest i18n level.">
    <input kuiDatePicker [(value)]="localeDate" />
    <kui-dropdown panelRole="dialog" panelWidth="auto" maxHeight="420px">
      <kui-calendar flat />
    </kui-dropdown>
  </kui-field>

  <kui-field label="Pinned layout" hint="format pins dd.MM.yyyy whatever the locale is.">
    <input kuiDatePicker format="dd.MM.yyyy" [(value)]="pinnedDate" />
    <kui-dropdown panelRole="dialog" panelWidth="auto" maxHeight="420px">
      <kui-calendar flat />
    </kui-dropdown>
  </kui-field>
</div>
```

#### date-picker-format-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCalendar, KuiDatePicker, KuiDropdown, KuiField } from '@kikita-labs/ui';

@Component({
  selector: 'app-date-picker-format-example',
  imports: [KuiCalendar, KuiDatePicker, KuiDropdown, KuiField],
  templateUrl: './date-picker-format-example.html',
  styleUrl: './date-picker-format-example.scss',
})
export class DatePickerFormatExample {
  protected readonly localeDate = signal<Date | null>(new Date(2026, 9, 3));
  protected readonly pinnedDate = signal<Date | null>(new Date(2026, 9, 3));
}
```

#### date-picker-format-example.scss

```scss
.date-picker-format-example {
  display: grid;
  gap: var(--kui-space-5, 20px);
  inline-size: min(100%, 22rem);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| input[kuiDatePicker] | Directive | - | Turns a native text input into a masked date picker trigger. |
| [(value)] | Date \| null | null | Selected date. Bind the same signal to the paired calendar. |
| [(viewDate)] | Date | current month | Visible calendar month. Bind on both input and calendar for live month sync. |
| minDate / maxDate | Date \| undefined | undefined | Inclusive bounds for typed values and linked calendar cells. |
| clearable | boolean \| undefined | field option | Shows a clear action when the input has a value. |
| disabled | boolean | false | Disables the input and prevents opening the dropdown. |
| readonly | boolean | false | Keeps the value readable while preventing popover opening. |
| invalid | boolean | false | Reflects validation state from Signal Forms or direct binding. |
| errors / touched / touch | Signal Forms control contract | - | Integrates with Angular Signal Forms validation and touched state. |
| placeholder | string \| undefined | locale layout | Native input placeholder. Defaults to the day, month and year placeholder messages in the order and separators of the locale (mm/dd/yyyy, dd.mm.yyyy). |
| id | string \| undefined | field control id | Input id. Falls back to the parent kui-field control id when present. |
| kui-dropdown panelRole | 'dialog' \| 'listbox' \| 'grid' \| null | 'listbox' | Use dialog for the calendar popover because the panel is not a listbox. |
| kui-calendar flat | boolean | false | Use flat inside the dropdown so the calendar does not draw a second frame. |
| format | string \| undefined | 'locale' | Display and parse layout: d/dd, M/MM and yyyy tokens such as dd.MM.yyyy pin it. Resolves as the input, then defaults.datePicker.format, then the locale layout. |
| messages | Partial<KuiDatePickerMessages> \| undefined | undefined | Per-instance text overrides (openCalendar, closeCalendar and the day, month and year placeholder tokens). They win over scoped and root messages. |
| KuiDatePickerOptions | interface | - | Shape of defaults.datePicker: clearable, format, chevronIcon and clearIcon (they take precedence over defaults.icons.pickerChevron and defaults.icons.clear). |

## Accessibility

- `role="combobox"` on the input, `aria-haspopup="dialog"`, `aria-expanded` + `aria-controls`
  pointing at the popover panel id.
- `aria-invalid`/`data-kui-invalid` reflect parse failures and out-of-range dates.
- The linked `kui-calendar` carries its own grid accessibility (`role="grid"`, roving tabindex,
  `aria-current="date"`, `aria-selected`) — see [Calendar](./calendar.md#accessibility).

### Keyboard

- `ArrowDown`: opens the popover
- `Enter`: opens the popover if closed, closes it if open
- `Escape`: closes the popover; focus stays in the field, or returns to it when it was inside the calendar
- `Tab`: closes the popover, focus moves to the next tabbable element
- Inside the popover: calendar keyboard navigation applies (see Calendar docs)

## Playground

Available at /components/date-picker/playground.

---

<!-- route: /components/dialog -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/dialog.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/dialog.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Dialog

> Typed modal overlay service and host contract.

- Status: available
- Route: /components/dialog
- Package: @kikita-labs/ui@2.0.0
- Import: kuiDialog from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/dialog.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```ts
// 1. Define the dialog component
@Component({ ... })
export class EditUserDialog implements KuiDialogHost<'saved' | null, UserData> {
  public readonly dialogContext =
    inject<KuiDialogContext<'saved' | null, UserData>>(KUI_DIALOG_CONTEXT);
}

// 2. Create a typed opener in an injection context
export function injectEditUserDialog() {
  return kuiDialog(EditUserDialog, { size: 'md' });
}

// 3. Use in a component
class MyPage {
  private readonly openEditUser = injectEditUserDialog();

  edit(user: User) {
    this.openEditUser({ userId: user.id })
      .pipe(takeUntilDestroyed())
      .subscribe((result) => {
        if (result === 'saved') this.reload();
      });
  }
}
```

## Examples

Rendered at /components/dialog:

### basic-dialog-example

#### basic-dialog-example.html

```html
<div class="basic-dialog-example">
  <button kuiButton type="button" (click)="invite()">Invite teammate</button>
  @if (lastResult()) {
    <p class="basic-dialog-example__result">Last result: {{ lastResult() }}</p>
  }
</div>
```

#### invite-teammate-dialog.html

```html
<div class="kui-dialog-header">
  <h2 class="kui-dialog-title">Invite to {{ dialogContext.data.teamName }}</h2>
</div>
<div class="kui-dialog-body">
  <label for="invite-teammate-email">Email address</label>
  <input
    id="invite-teammate-email"
    kuiInput
    type="email"
    placeholder="teammate@company.com"
    [value]="email()"
    (input)="email.set($any($event.target).value)"
  />
</div>
<div class="kui-dialog-footer">
  <button kuiButton type="button" shape="outline" (click)="cancel()">Cancel</button>
  <button kuiButton type="button" [disabled]="!email()" (click)="send()">Send invite</button>
</div>
```

#### basic-dialog-example.ts

```ts
import { Component, DestroyRef, inject, signal } from '@angular/core';

import { takeUntilDestroyed } from '@angular/core/rxjs-interop';

import { KuiButton, kuiDialog } from '@kikita-labs/ui';

import { InviteTeammateDialog } from './invite-teammate-dialog';

@Component({
  selector: 'app-basic-dialog-example',
  imports: [KuiButton],
  templateUrl: './basic-dialog-example.html',
  styleUrl: './basic-dialog-example.scss',
})
export class BasicDialogExample {
  private readonly destroyRef = inject(DestroyRef);
  private readonly openInvite = kuiDialog(InviteTeammateDialog, { size: 'sm' });

  protected readonly lastResult = signal<string | null>(null);

  protected invite(): void {
    this.openInvite({ teamName: 'Docs' })
      .pipe(takeUntilDestroyed(this.destroyRef))
      .subscribe((result) => this.lastResult.set(result ?? 'dismissed'));
  }
}
```

#### invite-teammate-dialog.ts

```ts
import { Component, inject, signal } from '@angular/core';

import {
  KUI_DIALOG_CONTEXT,
  KuiButton,
  type KuiDialogContext,
  type KuiDialogHost,
  KuiInput,
} from '@kikita-labs/ui';

export interface InviteTeammateData {
  readonly teamName: string;
}

export type InviteTeammateResult = 'sent' | null;

@Component({
  selector: 'app-invite-teammate-dialog',
  imports: [KuiButton, KuiInput],
  templateUrl: './invite-teammate-dialog.html',
})
export class InviteTeammateDialog implements KuiDialogHost<
  InviteTeammateResult,
  InviteTeammateData
> {
  public readonly dialogContext =
    inject<KuiDialogContext<InviteTeammateResult, InviteTeammateData>>(KUI_DIALOG_CONTEXT);

  protected readonly email = signal('');

  protected send(): void {
    this.dialogContext.close('sent');
  }

  protected cancel(): void {
    this.dialogContext.close(null);
  }
}
```

#### basic-dialog-example.scss

```scss
.basic-dialog-example {
  display: grid;
  gap: var(--kui-space-3, 12px);
  justify-items: center;
}

.basic-dialog-example__result {
  margin: 0;
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

### dialog-confirm-example

#### dialog-confirm-example.html

```html
<div class="dialog-confirm-example">
  <button kuiButton type="button" appearance="danger" (click)="deleteRecord()">
    Delete record
  </button>
  @if (lastResult()) {
    <p class="dialog-confirm-example__result">Last result: {{ lastResult() }}</p>
  }
</div>
```

#### dialog-confirm-example.ts

```ts
import { Component, DestroyRef, inject, signal } from '@angular/core';

import { takeUntilDestroyed } from '@angular/core/rxjs-interop';

import { KuiButton, kuiConfirm } from '@kikita-labs/ui';

@Component({
  selector: 'app-dialog-confirm-example',
  imports: [KuiButton],
  templateUrl: './dialog-confirm-example.html',
  styleUrl: './dialog-confirm-example.scss',
})
export class DialogConfirmExample {
  private readonly destroyRef = inject(DestroyRef);
  private readonly confirm = kuiConfirm();

  protected readonly lastResult = signal<string | null>(null);

  protected deleteRecord(): void {
    this.confirm({
      title: 'Delete record?',
      message: 'This action cannot be undone.',
      appearance: 'danger',
      confirmLabel: 'Delete',
    })
      .pipe(takeUntilDestroyed(this.destroyRef))
      .subscribe((ok) => this.lastResult.set(ok ? 'confirmed' : 'cancelled'));
  }
}
```

#### dialog-confirm-example.scss

```scss
.dialog-confirm-example {
  display: grid;
  gap: var(--kui-space-3, 12px);
  justify-items: center;
}

.dialog-confirm-example__result {
  margin: 0;
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

### dialog-sizes-example

#### dialog-sizes-example.html

```html
<div class="dialog-sizes-example">
  @for (size of sizes; track size) {
    <button kuiButton type="button" shape="outline" (click)="open(size)">{{ size }}</button>
  }
</div>
```

#### size-preview-dialog.html

```html
<div class="kui-dialog-header">
  <h2 class="kui-dialog-title">size="{{ dialogContext.data.size }}"</h2>
</div>
<div class="kui-dialog-body">
  <p>
    This panel was opened with <code>size: '{{ dialogContext.data.size }}'</code>.
  </p>
</div>
<div class="kui-dialog-footer">
  <button kuiButton type="button" (click)="dialogContext.close()">Close</button>
</div>
```

#### dialog-sizes-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, kuiDialog, type KuiDialogSize } from '@kikita-labs/ui';

import { SizePreviewDialog } from './size-preview-dialog';

@Component({
  selector: 'app-dialog-sizes-example',
  imports: [KuiButton],
  templateUrl: './dialog-sizes-example.html',
  styleUrl: './dialog-sizes-example.scss',
})
export class DialogSizesExample {
  protected readonly sizes: readonly KuiDialogSize[] = ['auto', 'sm', 'md', 'lg', 'fullscreen'];

  private readonly openers = new Map(
    this.sizes.map((size) => [size, kuiDialog(SizePreviewDialog, { size })]),
  );

  protected open(size: KuiDialogSize): void {
    this.openers.get(size)?.({ size });
  }
}
```

#### size-preview-dialog.ts

```ts
import { Component, inject } from '@angular/core';

import {
  KUI_DIALOG_CONTEXT,
  KuiButton,
  type KuiDialogContext,
  type KuiDialogHost,
} from '@kikita-labs/ui';

export interface SizePreviewData {
  readonly size: string;
}

@Component({
  selector: 'app-size-preview-dialog',
  imports: [KuiButton],
  templateUrl: './size-preview-dialog.html',
})
export class SizePreviewDialog implements KuiDialogHost<void, SizePreviewData> {
  public readonly dialogContext =
    inject<KuiDialogContext<void, SizePreviewData>>(KUI_DIALOG_CONTEXT);
}
```

#### dialog-sizes-example.scss

```scss
.dialog-sizes-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  justify-content: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| kuiDialog(component, config?) | (component: Type<TComponent>, config?: Omit<KuiDialogConfig, "data">) => (data: TData) => Observable<TResult \| undefined> | - | Inject-function factory. Call once per injection context to get a typed opener bound to that component. |
| KuiDialogHost<TResult, TData> | interface | - | Contract your dialog component implements. Requires a dialogContext property injected from KUI_DIALOG_CONTEXT. |
| KUI_DIALOG_CONTEXT | InjectionToken<KuiDialogContext<TResult, TData>> | - | Injected inside the dialog component to read data and close the dialog. |
| dialogContext.data | TData | - | Data passed via the opener call, e.g. openDialog(data). |
| dialogContext.closable | boolean | - | Mirrors KuiDialogConfig.closable. Informational only -- the container renders .kui-dialog-close itself when true. |
| dialogContext.appearance | KuiDialogAppearance | - | Mirrors KuiDialogConfig.appearance, for coloring a custom icon if needed. |
| dialogContext.close(result?) | (result?: TResult) => void | - | Closes the dialog, optionally emitting a typed result to the opener subscription. |
| KuiDialogConfig.data | TData | undefined | Available on the low-level config type; kuiDialog() passes feature data through the returned opener function instead. |
| KuiDialogConfig.size | 'auto' \| 'sm' \| 'md' \| 'lg' \| 'fullscreen' | 'md' | Panel width preset: auto (min 320px), sm (400px), md (560px), lg (720px), fullscreen (fills the viewport, no border, radius or shadow). Falls back to defaults.dialog.size. |
| KuiDialogConfig.appearance | 'default' \| 'danger' \| 'warning' | 'default' | Colors .kui-dialog-icon via a CSS variable. Has no other visual effect. Falls back to defaults.dialog.appearance. |
| KuiDialogConfig.dismissable | boolean | true | Allows Escape and backdrop click to close the dialog. Falls back to defaults.dialog.dismissable. |
| KuiDialogConfig.closable | boolean | true | Shows the .kui-dialog-close button the container renders automatically, absolutely positioned top-right of the panel. |
| KuiDialogRef<TResult> | class | - | Return type of kuiDialog(component, config). Calling it with data opens the dialog and returns Observable<TResult \| undefined>. |
| kuiConfirm() | () => (config: KuiConfirmConfig) => Observable<boolean> | - | Inject-function for a pre-built confirmation dialog. No custom component required. |
| KuiConfirmConfig.title | string | required | Header text. |
| KuiConfirmConfig.message | string \| undefined | - | Body text. |
| KuiConfirmConfig.appearance | KuiDialogAppearance | 'default' | Icon color and button tone. |
| KuiConfirmConfig.confirmLabel | string \| undefined | dialog.confirm message | Confirm button label. Defaults to the dialog.confirm message (OK). |
| KuiConfirmConfig.cancelLabel | string \| undefined | dialog.cancel message | Cancel button label. Defaults to the dialog.cancel message (Cancel). |
| .kui-dialog-icon | CSS class | - | Add to an SVG placed before .kui-dialog-title inside .kui-dialog-header. Fixed 20x20px, colored via appearance. |
| --kui-dialog-bg | CSS custom property | var(--kui-color-surface-elevated) | Panel background color. |
| --kui-dialog-border | CSS custom property | var(--kui-color-border) | Panel border color. |
| --kui-dialog-radius | CSS custom property | var(--kui-radius-lg) | Panel corner radius. |
| --kui-dialog-shadow | CSS custom property | var(--kui-shadow-lg) | Panel elevation shadow. |
| --kui-dialog-backdrop | CSS custom property | oklch(0 0 0 / 0.5) | Backdrop fill color. |
| KuiDialogOptions / KuiModalSurfaceOptions | interfaces | - | Shape of defaults.dialog (closable, size, appearance, dismissable, closeIcon), built on the base interface shared with the drawer. Options are read each time a dialog opens, so an open dialog keeps what it opened with. |

## Accessibility

- `role="dialog"` and `aria-modal="true"` are set on the panel.
- The panel uses `aria-labelledby` when `.kui-dialog-title` exists.
- The panel falls back to `aria-label="Dialog"` when no title is present.
- Focus is trapped inside the dialog via CDK `cdkTrapFocus`.
- Focus returns to the opener after the dialog closes.
- Escape closes when `dismissable: true`.
- Backdrop dismissal only applies when the pointer interaction starts on the backdrop;
  selecting text or dragging from inside the panel cannot dismiss the dialog.
- Page scroll is blocked via CDK block scroll strategy while open.

## Playground

Available at /components/dialog/playground.

---

<!-- route: /components/donut-chart -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/donut-chart.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/chart.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Donut Chart

> Donut chart for shares of a whole.

- Status: available
- Route: /components/donut-chart
- Package: @kikita-labs/ui@2.0.0
- Import: KuiDonutChart from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/chart.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-line-chart ariaLabel="Sessions per day" [series]="series" [categories]="categories" />
```

```ts
protected readonly series: readonly KuiChartCartesianSeries[] = [
  { id: 'sessions', name: 'Sessions', data: [120, 180, 150, 220, 260, 210, 300] },
];
protected readonly categories = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
```

`ariaLabel` has a chart-type fallback name and should describe what the chart shows. It is distinct
from each point's own `aria-label` (its value).

## Examples

Rendered at /components/donut-chart:

### basic-donut-chart-example

#### basic-donut-chart-example.html

```html
<div class="chart-example">
  <kui-donut-chart ariaLabel="Plan mix" [slices]="slices" />
</div>
```

#### basic-donut-chart-example.ts

```ts
import { Component } from '@angular/core';

import { type KuiChartSlice, KuiDonutChart } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-donut-chart-example',
  imports: [KuiDonutChart],
  templateUrl: './basic-donut-chart-example.html',
  styleUrl: './basic-donut-chart-example.scss',
})
export class BasicDonutChartExample {
  protected readonly slices: readonly KuiChartSlice[] = [
    { id: 'free', label: 'Free', value: 40 },
    { id: 'pro', label: 'Pro', value: 35 },
    { id: 'business', label: 'Business', value: 25 },
  ];
}
```

#### basic-donut-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### donut-patterns-chart-example

#### donut-patterns-chart-example.html

```html
<div class="chart-example">
  <kui-donut-chart ariaLabel="Plan mix with patterns" [slices]="slices" [patterns]="true" />
</div>
```

#### donut-patterns-chart-example.ts

```ts
import { Component } from '@angular/core';

import { type KuiChartSlice, KuiDonutChart } from '@kikita-labs/ui';

@Component({
  selector: 'app-donut-patterns-chart-example',
  imports: [KuiDonutChart],
  templateUrl: './donut-patterns-chart-example.html',
  styleUrl: './donut-patterns-chart-example.scss',
})
export class DonutPatternsChartExample {
  protected readonly slices: readonly KuiChartSlice[] = [
    { id: 'free', label: 'Free', value: 40 },
    { id: 'pro', label: 'Pro', value: 35 },
    { id: 'business', label: 'Business', value: 25 },
  ];
}
```

#### donut-patterns-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### donut-sizes-chart-example

#### donut-sizes-chart-example.html

```html
<div class="chart-example chart-example--stack">
  <kui-donut-chart ariaLabel="Small plan mix" [slices]="slices" size="sm" [legend]="false" />
  <kui-donut-chart ariaLabel="Large plan mix" [slices]="slices" size="lg" />
</div>
```

#### donut-sizes-chart-example.ts

```ts
import { Component } from '@angular/core';

import { type KuiChartSlice, KuiDonutChart } from '@kikita-labs/ui';

@Component({
  selector: 'app-donut-sizes-chart-example',
  imports: [KuiDonutChart],
  templateUrl: './donut-sizes-chart-example.html',
  styleUrl: './donut-sizes-chart-example.scss',
})
export class DonutSizesChartExample {
  protected readonly slices: readonly KuiChartSlice[] = [
    { id: 'free', label: 'Free', value: 40 },
    { id: 'pro', label: 'Pro', value: 35 },
    { id: 'business', label: 'Business', value: 25 },
  ];
}
```

#### donut-sizes-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### donut-states-chart-example

#### donut-states-chart-example.html

```html
<div class="chart-example chart-example--stack">
  <kui-donut-chart ariaLabel="Loading plan mix" [slices]="slices" [loading]="true" size="sm" />
  <kui-donut-chart ariaLabel="Empty plan mix" [slices]="[]" size="sm" />
</div>
```

#### donut-states-chart-example.ts

```ts
import { Component } from '@angular/core';

import { type KuiChartSlice, KuiDonutChart } from '@kikita-labs/ui';

@Component({
  selector: 'app-donut-states-chart-example',
  imports: [KuiDonutChart],
  templateUrl: './donut-states-chart-example.html',
  styleUrl: './donut-states-chart-example.scss',
})
export class DonutStatesChartExample {
  protected readonly slices: readonly KuiChartSlice[] = [
    { id: 'free', label: 'Free', value: 40 },
    { id: 'pro', label: 'Pro', value: 35 },
  ];
}
```

#### donut-states-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| slices | readonly KuiChartSlice[] | - | Required. { id?, label, value, color? }. Negative and non-finite values are dropped; a visible total of zero draws no arc. |
| patterns | boolean | false | Fills each slice with one of eight hatch patterns (colour independence). |

## Accessibility

- The `<svg>` is the graphic: `role="graphics-document"` with the name and the role description
  (`aria-roledescription`). The wrapper has no role, and axis text, gridlines and decorative shapes
  are `aria-hidden`.
- Each point/bar/slice is `role="graphics-symbol img"` with its own `aria-label` (the same text as
  the tooltip) -- an indivisible graphical unit, per the WAI-ARIA Graphics Module.
- Roving tabindex across points/bars/slices (see Keyboard). The inline legend is a named group of
  native `<button aria-pressed>` items at least 24px high.
- The tooltip shown on hover is the same one shown on keyboard focus (one shared overlay, retargeted
  between marks). It is dismissible and persistent. On pointer hover it appears at the pointer and follows
  it; keyboard focus anchors it to the focused mark. On touch, a tap pins the tooltip open until an
  outside tap, `Escape`, or a tap on a different mark; it also always renders below 768px, since it is
  the primary way to read a chart's exact value.
- Pointer hit targets: a line chart shows the tooltip while the pointer is on the point (its marker plus a
  3px margin), a scatter chart on the point's hit circle (at least 12px in radius), a bar chart on the bar
  itself and a donut on the slice.
- Text is at least 12px on screen: axis text defaults to 13px and keeps its pixel size at any width.
- `prefers-reduced-motion: reduce` disables the hover/dim transition and the donut sweep.
- The alt-table is a real accessible alternative to the graphic, not a decorative duplicate.

Automated checks (keyboard, accessibility tree, axe, forced-colours media emulation, reduced motion)
are in `chart-contract.spec.ts` and `accessibility.spec.ts`. A session with a real screen reader has
not been run and stays pending.

## Playground

Available at /components/donut-chart/playground.

---

<!-- route: /components/drawer -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/drawer.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/drawer.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Drawer

> Side and edge overlay surface for focused workflows.

- Status: available
- Route: /components/drawer
- Package: @kikita-labs/ui@2.0.0
- Import: kuiDrawer from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/drawer.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```ts
interface EditData {
  id: string;
}

type EditResult = 'saved' | 'cancelled';

@Component({
  selector: 'app-edit-drawer',
  template: `
    <div class="kui-drawer-header">
      <div class="kui-drawer-header-text">
        <h2 class="kui-drawer-title">Edit item</h2>
        <div class="kui-drawer-subtitle">{{ drawerContext.data.id }}</div>
      </div>
    </div>
    <div class="kui-drawer-body">...</div>
    <div class="kui-drawer-footer">
      <button
        kuiButton
        appearance="outline"
        type="button"
        (click)="drawerContext.close('cancelled')"
      >
        Cancel
      </button>
      <button kuiButton type="button" (click)="drawerContext.close('saved')">Save</button>
    </div>
  `,
  imports: [KuiButton],
})
export class EditDrawer implements KuiDrawerHost<EditResult, EditData> {
  public readonly drawerContext =
    inject<KuiDrawerContext<EditResult, EditData>>(KUI_DRAWER_CONTEXT);
}

function injectEditDrawer() {
  return kuiDrawer(EditDrawer, { side: 'right', size: 'md' });
}
```

## Examples

Rendered at /components/drawer:

### basic-drawer-example

#### basic-drawer-example.html

```html
<div class="basic-drawer-example">
  <button kuiButton type="button" (click)="edit()">Edit item</button>
  @if (lastResult()) {
    <p class="basic-drawer-example__result">Last result: {{ lastResult() }}</p>
  }
</div>
```

#### edit-item-drawer.html

```html
<div class="kui-drawer-header">
  <div class="kui-drawer-header-text">
    <h2 class="kui-drawer-title">Edit item</h2>
    <div class="kui-drawer-subtitle">{{ drawerContext.data.id }}</div>
  </div>
</div>
<div class="kui-drawer-body">
  <p>Edit fields for item {{ drawerContext.data.id }} here.</p>
</div>
<div class="kui-drawer-footer">
  <button kuiButton type="button" shape="outline" (click)="drawerContext.close('cancelled')">
    Cancel
  </button>
  <button kuiButton type="button" (click)="drawerContext.close('saved')">Save</button>
</div>
```

#### basic-drawer-example.ts

```ts
import { Component, DestroyRef, inject, signal } from '@angular/core';

import { takeUntilDestroyed } from '@angular/core/rxjs-interop';

import { KuiButton, kuiDrawer } from '@kikita-labs/ui';

import { EditItemDrawer } from './edit-item-drawer';

@Component({
  selector: 'app-basic-drawer-example',
  imports: [KuiButton],
  templateUrl: './basic-drawer-example.html',
  styleUrl: './basic-drawer-example.scss',
})
export class BasicDrawerExample {
  private readonly destroyRef = inject(DestroyRef);
  private readonly openEditItem = kuiDrawer(EditItemDrawer, { side: 'right', size: 'md' });

  protected readonly lastResult = signal<string | null>(null);

  protected edit(): void {
    this.openEditItem({ id: 'item-42' })
      .pipe(takeUntilDestroyed(this.destroyRef))
      .subscribe((result) => this.lastResult.set(result ?? 'dismissed'));
  }
}
```

#### edit-item-drawer.ts

```ts
import { Component, inject } from '@angular/core';

import {
  KUI_DRAWER_CONTEXT,
  KuiButton,
  type KuiDrawerContext,
  type KuiDrawerHost,
} from '@kikita-labs/ui';

export interface EditItemData {
  readonly id: string;
}

export type EditItemResult = 'saved' | 'cancelled';

@Component({
  selector: 'app-edit-item-drawer',
  imports: [KuiButton],
  templateUrl: './edit-item-drawer.html',
})
export class EditItemDrawer implements KuiDrawerHost<EditItemResult, EditItemData> {
  public readonly drawerContext =
    inject<KuiDrawerContext<EditItemResult, EditItemData>>(KUI_DRAWER_CONTEXT);
}
```

#### basic-drawer-example.scss

```scss
.basic-drawer-example {
  display: grid;
  gap: var(--kui-space-3, 12px);
  justify-items: center;
}

.basic-drawer-example__result {
  margin: 0;
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

### drawer-sides-example

#### drawer-sides-example.html

```html
<div class="drawer-sides-example">
  @for (side of sides; track side) {
    <button kuiButton type="button" shape="outline" (click)="open(side)">{{ side }}</button>
  }
</div>
```

#### side-preview-drawer.html

```html
<div class="kui-drawer-header">
  <div class="kui-drawer-header-text">
    <h2 class="kui-drawer-title">side="{{ drawerContext.side }}"</h2>
  </div>
</div>
<div class="kui-drawer-body">
  <p>
    This panel was opened with <code>side: '{{ drawerContext.side }}'</code>.
  </p>
</div>
<div class="kui-drawer-footer">
  <button kuiButton type="button" (click)="drawerContext.close()">Close</button>
</div>
```

#### drawer-sides-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, kuiDrawer, type KuiDrawerSide } from '@kikita-labs/ui';

import { SidePreviewDrawer } from './side-preview-drawer';

@Component({
  selector: 'app-drawer-sides-example',
  imports: [KuiButton],
  templateUrl: './drawer-sides-example.html',
  styleUrl: './drawer-sides-example.scss',
})
export class DrawerSidesExample {
  protected readonly sides: readonly KuiDrawerSide[] = ['top', 'right', 'bottom', 'left'];

  private readonly openers = new Map(
    this.sides.map((side) => [side, kuiDrawer(SidePreviewDrawer, { side, size: 'sm' })]),
  );

  protected open(side: KuiDrawerSide): void {
    this.openers.get(side)?.(undefined);
  }
}
```

#### side-preview-drawer.ts

```ts
import { Component, inject } from '@angular/core';

import {
  KUI_DRAWER_CONTEXT,
  KuiButton,
  type KuiDrawerContext,
  type KuiDrawerHost,
} from '@kikita-labs/ui';

@Component({
  selector: 'app-side-preview-drawer',
  imports: [KuiButton],
  templateUrl: './side-preview-drawer.html',
})
export class SidePreviewDrawer implements KuiDrawerHost<void, void> {
  public readonly drawerContext = inject<KuiDrawerContext<void, void>>(KUI_DRAWER_CONTEXT);
}
```

#### drawer-sides-example.scss

```scss
.drawer-sides-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  justify-content: center;
}
```

### drawer-sizes-example

#### drawer-sizes-example.html

```html
<div class="drawer-sizes-example">
  @for (size of sizes; track size) {
    <button kuiButton type="button" shape="outline" (click)="open(size)">{{ size }}</button>
  }
</div>
```

#### size-preview-drawer.html

```html
<div class="kui-drawer-header">
  <div class="kui-drawer-header-text">
    <h2 class="kui-drawer-title">size="{{ drawerContext.size }}"</h2>
  </div>
</div>
<div class="kui-drawer-body">
  <p>
    This panel was opened with <code>size: '{{ drawerContext.size }}'</code>.
  </p>
</div>
<div class="kui-drawer-footer">
  <button kuiButton type="button" (click)="drawerContext.close()">Close</button>
</div>
```

#### drawer-sizes-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, kuiDrawer, type KuiDrawerSize } from '@kikita-labs/ui';

import { SizePreviewDrawer } from './size-preview-drawer';

@Component({
  selector: 'app-drawer-sizes-example',
  imports: [KuiButton],
  templateUrl: './drawer-sizes-example.html',
  styleUrl: './drawer-sizes-example.scss',
})
export class DrawerSizesExample {
  protected readonly sizes: readonly KuiDrawerSize[] = ['sm', 'md', 'lg', 'full', 'auto'];

  private readonly openers = new Map(
    this.sizes.map((size) => [size, kuiDrawer(SizePreviewDrawer, { side: 'right', size })]),
  );

  protected open(size: KuiDrawerSize): void {
    this.openers.get(size)?.(undefined);
  }
}
```

#### size-preview-drawer.ts

```ts
import { Component, inject } from '@angular/core';

import {
  KUI_DRAWER_CONTEXT,
  KuiButton,
  type KuiDrawerContext,
  type KuiDrawerHost,
} from '@kikita-labs/ui';

@Component({
  selector: 'app-size-preview-drawer',
  imports: [KuiButton],
  templateUrl: './size-preview-drawer.html',
})
export class SizePreviewDrawer implements KuiDrawerHost<void, void> {
  public readonly drawerContext = inject<KuiDrawerContext<void, void>>(KUI_DRAWER_CONTEXT);
}
```

#### drawer-sizes-example.scss

```scss
.drawer-sizes-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  justify-content: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| kuiDrawer(component, config?) | (component: Type<TComponent>, config?: Omit<KuiDrawerConfig, "data">) => (data: TData) => Observable<TResult \| undefined> | - | Inject-function factory. Call once per injection context to get a typed opener bound to that component. |
| KuiDrawerHost<TResult, TData> | interface | - | Contract your drawer component implements. Requires a drawerContext property injected from KUI_DRAWER_CONTEXT. |
| KUI_DRAWER_CONTEXT | InjectionToken<KuiDrawerContext<TResult, TData>> | - | Injected inside the drawer component to read data and close the drawer. |
| drawerContext.data | TData | - | Data passed via the opener call, e.g. openDrawer(data). |
| drawerContext.side | KuiDrawerSide | - | Drawer side resolved from KuiDrawerConfig.side, read-only. |
| drawerContext.size | KuiDrawerSize | - | Drawer size preset resolved from KuiDrawerConfig.size, read-only. |
| drawerContext.closable | boolean | - | Mirrors KuiDrawerConfig.closable. Informational only -- the container renders .kui-drawer-close itself when true. |
| drawerContext.close(result?) | (result?: TResult) => void | - | Closes the drawer, optionally emitting a typed result to the opener subscription. |
| KuiDrawerConfig.data | TData | undefined | Available on the low-level config type; kuiDrawer() passes feature data through the returned opener function instead. |
| KuiDrawerConfig.side | 'right' \| 'left' \| 'bottom' \| 'top' | 'right' | Edge from which the drawer enters and docks. |
| KuiDrawerConfig.size | 'sm' \| 'md' \| 'lg' \| 'full' \| 'auto' | 'md' | Width for left/right drawers, height for top/bottom drawers. 'auto' sizes to content (min 320px width for left/right, min 200px height for top/bottom). |
| KuiDrawerConfig.closeOnBackdropClick | boolean | true | Closes the drawer on backdrop click. Disable for required actions. |
| KuiDrawerConfig.closeOnEscape | boolean | true | Closes the drawer on Escape. Disable for required actions. |
| KuiDrawerConfig.closable | boolean | true | Shows the .kui-drawer-close button the container renders automatically, absolutely positioned top-right of the panel. |
| KuiDrawerRef<TResult> | class | - | Return type of kuiDrawer(component, config). Calling it with data opens the drawer and returns Observable<TResult \| undefined>. |
| .kui-drawer-header / .kui-drawer-title / .kui-drawer-subtitle | CSS classes | - | Header structure classes. .kui-drawer-title is wired as aria-labelledby automatically when present. |
| .kui-drawer-body / .kui-drawer-footer | CSS classes | - | Scrollable content region and action row classes. |
| --kui-drawer-bg | CSS custom property | - | Panel background color. |
| --kui-drawer-border | CSS custom property | - | Panel border color. |
| --kui-drawer-radius | CSS custom property | - | Panel corner radius. |
| --kui-drawer-backdrop-bg | CSS custom property | - | Backdrop fill color. |
| --kui-drawer-width-sm / -md / -lg | CSS custom properties | - | Width presets used by left/right drawers. |
| --kui-drawer-height-sm / -md / -lg | CSS custom properties | - | Height presets used by top/bottom drawers. |
| --kui-drawer-duration-open / -close | CSS custom properties | - | Enter/exit animation durations. |
| KuiDrawerOptions / KuiModalSurfaceOptions | interfaces | - | Shape of defaults.drawer (closable, side, size, closeOnBackdropClick, closeOnEscape, closeIcon), built on the base interface shared with the dialog. Options are read each time a drawer opens. |

## Accessibility

- Drawer renders `role="dialog"` and `aria-modal="true"`.
- Focus is trapped inside the drawer while open.
- Focus returns to the previously focused element after close.
- If `.kui-drawer-title` exists, it is wired as `aria-labelledby`.
- Escape closes by default unless `closeOnEscape` is `false`.
- Backdrop click closes by default unless `closeOnBackdropClick` is `false`, and only when
  the pointer interaction starts on the backdrop. Selecting text or dragging from inside the
  drawer cannot dismiss it.

## Playground

Available at /components/drawer/playground.

---

<!-- route: /components/dropdown -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/dropdown.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/dropdown.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Dropdown

> Projected option overlay used by select-like controls.

- Status: available
- Route: /components/dropdown
- Package: @kikita-labs/ui@2.0.0
- Import: KuiDropdown from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/dropdown.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

### Inside `kui-field`

`kui-field` detects a nested dropdown, sets itself as the anchor, and toggles the
panel when the field is clicked. This is the normal pattern for `input[kuiSelect]`.

```html
<kui-field label="Fruit">
  <input kuiSelect [(value)]="fruit" placeholder="Pick..." />
  <kui-dropdown>
    @for (option of options; track option) {
    <div [kuiOption]="option">{{ option }}</div>
    }
  </kui-dropdown>
</kui-field>
```

### Trigger directive

Use `[kuiDropdownFor]` when the dropdown is anchored to a standalone trigger.
Prefer a native `<button>` so keyboard behavior and button semantics are already
correct.

```html
<button type="button" [kuiDropdownFor]="menu">Actions</button>

<kui-dropdown #menu [maxHeight]="null">
  <div kuiOption="edit">Edit</div>
  <div kuiOption="delete" [disabled]="true">Delete</div>
</kui-dropdown>
```

For non-button triggers, the host element must already be focusable and handle
keyboard activation. The directive only wires click toggling, `aria-expanded`,
and `aria-haspopup`.

### Controlled open state

Use the `open` model when the parent owns when the panel should be visible. The
dropdown updates the bound signal when it closes itself because of Escape, an
outside click, or an off-screen anchor.

```ts
readonly resultsOpen = signal(false);
```

```html
<kui-dropdown [(open)]="resultsOpen" panelWidth="anchor" [panelRole]="null">
  <!-- Projected search results. -->
</kui-dropdown>
```

The existing `open()`, `close()`, and `toggle()` methods remain available for
imperative integrations.

## Examples

Rendered at /components/dropdown:

### field-dropdown-example

#### field-dropdown-example.html

```html
<kui-field label="Fruit">
  <input kuiSelect [(value)]="fruit" placeholder="Pick..." />
  <kui-dropdown>
    <div kuiOption value="apple">Apple</div>
    <div kuiOption value="banana">Banana</div>
    <div kuiOption value="cherry">Cherry</div>
  </kui-dropdown>
</kui-field>
```

#### field-dropdown-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiDropdown, KuiField, KuiOption, KuiSelect } from '@kikita-labs/ui';

@Component({
  selector: 'app-field-dropdown-example',
  imports: [KuiDropdown, KuiField, KuiOption, KuiSelect],
  templateUrl: './field-dropdown-example.html',
})
export class FieldDropdownExample {
  protected readonly fruit = signal<string | null>(null);
}
```

### panel-width-dropdown-example

#### panel-width-dropdown-example.html

```html
<div class="panel-width-dropdown-example">
  <button kuiButton type="button" [kuiDropdownFor]="anchorPanel">panelWidth="anchor"</button>
  <kui-dropdown #anchorPanel panelWidth="anchor">
    <div kuiOption value="a">Matches trigger width</div>
  </kui-dropdown>

  <button kuiButton type="button" [kuiDropdownFor]="contentPanel">panelWidth="content"</button>
  <kui-dropdown #contentPanel panelWidth="content">
    <div kuiOption value="b">Grows with a longer content line if needed</div>
  </kui-dropdown>

  <button kuiButton type="button" [kuiDropdownFor]="explicitPanel">width="320px"</button>
  <kui-dropdown #explicitPanel width="320px">
    <div kuiOption value="c">Always exactly 320px wide</div>
  </kui-dropdown>
</div>
```

#### panel-width-dropdown-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiDropdown, KuiDropdownFor, KuiOption } from '@kikita-labs/ui';

@Component({
  selector: 'app-panel-width-dropdown-example',
  imports: [KuiButton, KuiDropdown, KuiDropdownFor, KuiOption],
  templateUrl: './panel-width-dropdown-example.html',
  styleUrl: './panel-width-dropdown-example.scss',
})
export class PanelWidthDropdownExample {}
```

#### panel-width-dropdown-example.scss

```scss
.panel-width-dropdown-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
}
```

### standalone-dropdown-example

#### standalone-dropdown-example.html

```html
<div class="standalone-dropdown-example">
  <button kuiButton type="button" [kuiDropdownFor]="menu">Actions</button>

  <kui-dropdown #menu [maxHeight]="null">
    <div kuiOption value="edit">Edit</div>
    <div kuiOption value="delete" [disabled]="true">Delete</div>
  </kui-dropdown>
</div>
```

#### standalone-dropdown-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiDropdown, KuiDropdownFor, KuiOption } from '@kikita-labs/ui';

@Component({
  selector: 'app-standalone-dropdown-example',
  imports: [KuiButton, KuiDropdown, KuiDropdownFor, KuiOption],
  templateUrl: './standalone-dropdown-example.html',
})
export class StandaloneDropdownExample {}
```

### controlled-open-dropdown-example

#### controlled-open-dropdown-example.html

```html
<div class="controlled-open-dropdown-example">
  <div class="controlled-open-dropdown-example__actions">
    <button kuiButton type="button" [kuiDropdownFor]="results">Show results</button>
    <button kuiButton type="button" shape="soft" (click)="resultsOpen.set(true)">
      Open from parent
    </button>
  </div>

  <kui-dropdown #results [(open)]="resultsOpen" panelWidth="anchor" [panelRole]="null">
    <div kuiOption value="alpha">Alpha result</div>
    <div kuiOption value="beta">Beta result</div>
  </kui-dropdown>
</div>
```

#### controlled-open-dropdown-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiButton, KuiDropdown, KuiDropdownFor, KuiOption } from '@kikita-labs/ui';

@Component({
  selector: 'app-controlled-open-dropdown-example',
  imports: [KuiButton, KuiDropdown, KuiDropdownFor, KuiOption],
  templateUrl: './controlled-open-dropdown-example.html',
  styleUrl: './controlled-open-dropdown-example.scss',
})
export class ControlledOpenDropdownExample {
  protected readonly resultsOpen = signal(false);
}
```

#### controlled-open-dropdown-example.scss

```scss
.controlled-open-dropdown-example {
  &__actions {
    display: flex;
    flex-wrap: wrap;
    gap: 0.5rem;
  }
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| maxHeight | string \| null \| undefined | '240px' (--kui-dropdown-max-height) | Preferred max height of the panel before it scrolls. Falls back to defaults.dropdown.maxHeight, then the --kui-dropdown-max-height token (240px). Always additionally clamped to the viewport so the panel can never render taller than the screen. null removes only the preferred cap, not the viewport clamp. |
| offset | number \| undefined | 4 | Gap in px between the anchor and the panel edge. A static numeric attribute is coerced. Falls back to defaults.dropdown.offset. |
| closeOnSelect | boolean \| undefined | true | Closes the panel after an enabled option is selected with a pointer or Enter/Space. A plain input (it is no longer a two-way model). Falls back to defaults.dropdown.closeOnSelect. |
| open | ModelSignal<boolean> | false | Controlled open state. Bind with [(open)] to keep parent state synchronized with Escape, outside-click, and off-screen-anchor dismissal. Imperative open(), close(), and toggle() remain available. |
| panelRole | 'listbox' \| 'dialog' \| 'grid' \| null | 'listbox' | ARIA role rendered on the panel. Set to dialog (or null to omit the role) for non-listbox projected content, e.g. kui-calendar. |
| panelWidth | 'anchor' \| 'content' \| 'auto' \| undefined | 'anchor' | Falls back to defaults.dropdown.panelWidth. anchor matches the trigger's width exactly (listboxes). content grows with the panel's own content but never below the trigger's width. auto ignores the trigger's width and sizes purely to content. |
| width | string \| null | null | Explicit panel width (any CSS width, e.g. 320px). Overrides panelWidth entirely when set. |
| isOpen | Signal<boolean> | - | Current open state. |
| open() | method | - | Shows the panel and attaches scroll/outside-click/Escape listeners. |
| close() | method | - | Starts the close animation and detaches listeners. |
| toggle() | method | - | Opens when closed, closes when open. |
| setAnchor(el, focusReturn?) | method | - | Sets the anchor imperatively. The optional third argument names the element that receives focus when the panel closes after a selection or Escape. Called by kui-field and [kuiDropdownFor]. |
| getPanel() | method | - | Returns the rendered panel element, if attached. |
| getPanelId() | method | - | Returns the stable panel id for ARIA wiring. |
| [kuiDropdownFor] | KuiDropdown | - | Wires a standalone trigger to a dropdown instance and manages click toggling, aria-expanded, and aria-haspopup. Prefer a native button so keyboard behavior is already correct. |
| [kuiOption] value | unknown | - | Required. The value an option renders and emits. Set via the `value` input on `KuiOption`, e.g. `<div kuiOption value="edit">`. |
| [kuiOption] disabled | boolean | false | Disables click and keyboard selection for this option. |
| kuiOptionSelect | EventEmitter<unknown> | - | Emits the option value on selection. |
| --kui-dropdown-bg | CSS custom property | var(--kui-color-surface-elevated) | Panel background. |
| --kui-dropdown-border | CSS custom property | var(--kui-color-border) | Panel border color. |
| --kui-dropdown-radius | CSS custom property | var(--kui-radius-md) | Panel corner radius. |
| --kui-dropdown-shadow | CSS custom property | var(--kui-shadow-lg) | Panel drop shadow. |
| --kui-dropdown-viewport-margin | CSS custom property | var(--kui-space-6, 32px) | Margin subtracted from the viewport height when clamping the panel max-height. |
| Known non-feature | - | - | Dropdown does not own selection or value state itself. Select, Combobox, Menu, or another host component provides that context; a bare kui-dropdown only positions the panel and manages open/close. |
| KuiDropdownOptions | interface | - | Shape of defaults.dropdown: maxHeight, offset, closeOnSelect and panelWidth. |

## Accessibility

- Keep dropdown triggers native where possible, especially `<button>`.
- Select-style hosts should expose `role="combobox"`, `aria-expanded`,
  `aria-controls`, and `aria-describedby` through their own directive.
- Options use `role="option"` inside the dropdown `role="listbox"` panel.
- Escape closes the panel. Enter/Space selects an option and, by default, closes
  it. Tab closes without stealing focus back from the next tabbable element.

## Playground

Available at /components/dropdown/playground.

---

<!-- route: /components/empty-state -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/empty-state.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/empty-state.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Empty State

> Known empty, error, no-access, and success content states.

- Status: available
- Route: /components/empty-state
- Package: @kikita-labs/ui@2.0.0
- Import: KuiEmptyState from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/empty-state.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-empty-state
  heading="No projects yet"
  description="Create the first project to start working with your team."
>
  <svg kuiEmptyStateIcon viewBox="0 0 24 24" fill="none" stroke="currentColor">
    <path d="M21 8v13H3V8" />
    <path d="M1 3h22v5H1z" />
    <path d="M10 12h4" />
  </svg>

  <div kuiEmptyStateActions>
    <button kuiButton type="button">Create project</button>
    <button kuiButton appearance="ghost" type="button">Import</button>
  </div>
</kui-empty-state>
```

## Examples

Rendered at /components/empty-state:

### basic-empty-state-example

#### basic-empty-state-example.html

```html
<div class="basic-empty-state-example">
  <kui-empty-state
    heading="No projects yet"
    description="Create the first project to start working with your team."
  >
    <kui-icon kuiEmptyStateIcon name="package" />

    <div kuiEmptyStateActions>
      <button kuiButton type="button">Create project</button>
      <button kuiButton shape="ghost" type="button">Import</button>
    </div>
  </kui-empty-state>
</div>
```

#### basic-empty-state-example.ts

```ts
import { Component } from '@angular/core';

import {
  KuiButton,
  KuiEmptyState,
  KuiEmptyStateActions,
  KuiEmptyStateIcon,
  KuiIcon,
} from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-empty-state-example',
  imports: [KuiButton, KuiEmptyStateActions, KuiEmptyState, KuiEmptyStateIcon, KuiIcon],
  templateUrl: './basic-empty-state-example.html',
  styleUrl: './basic-empty-state-example.scss',
})
export class BasicEmptyStateExample {}
```

#### basic-empty-state-example.scss

```scss
.basic-empty-state-example {
  display: flex;
  justify-content: center;
  inline-size: 100%;
}
```

### empty-state-context-example

#### empty-state-context-example.html

```html
<div class="empty-state-context-example">
  <kui-empty-state
    size="sm"
    context="no-results"
    heading="No results"
    description="Try a different search term or clear your filters."
  >
    <kui-icon kuiEmptyStateIcon name="search" />
  </kui-empty-state>

  <kui-empty-state
    size="sm"
    context="error"
    heading="Couldn't load projects"
    description="Something went wrong while loading this list."
  >
    <kui-icon kuiEmptyStateIcon name="circle-alert" />

    <div kuiEmptyStateActions>
      <button kuiButton shape="soft" type="button">Retry</button>
    </div>
  </kui-empty-state>

  <kui-empty-state
    size="sm"
    context="no-access"
    heading="No access"
    description="Ask a workspace admin for access to this project."
  >
    <kui-icon kuiEmptyStateIcon name="lock" />
  </kui-empty-state>

  <kui-empty-state
    size="sm"
    context="success"
    heading="All caught up"
    description="No pending reviews are waiting on you right now."
  >
    <kui-icon kuiEmptyStateIcon name="circle-check" />
  </kui-empty-state>
</div>
```

#### empty-state-context-example.ts

```ts
import { Component } from '@angular/core';

import {
  KuiButton,
  KuiEmptyState,
  KuiEmptyStateActions,
  KuiEmptyStateIcon,
  KuiIcon,
} from '@kikita-labs/ui';

@Component({
  selector: 'app-empty-state-context-example',
  imports: [KuiButton, KuiEmptyStateActions, KuiEmptyState, KuiEmptyStateIcon, KuiIcon],
  templateUrl: './empty-state-context-example.html',
  styleUrl: './empty-state-context-example.scss',
})
export class EmptyStateContextExample {}
```

#### empty-state-context-example.scss

```scss
.empty-state-context-example {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
  gap: var(--kui-space-4, 16px);
  inline-size: 100%;
}
```

### empty-state-size-example

#### empty-state-size-example.html

```html
<div class="empty-state-size-example">
  <kui-empty-state size="sm" heading="No comments" description="Be the first to leave a comment.">
    <kui-icon kuiEmptyStateIcon name="message-circle" />
  </kui-empty-state>

  <kui-empty-state size="md" heading="No comments" description="Be the first to leave a comment.">
    <kui-icon kuiEmptyStateIcon name="message-circle" />
  </kui-empty-state>

  <kui-empty-state size="lg" heading="No comments" description="Be the first to leave a comment.">
    <kui-icon kuiEmptyStateIcon name="message-circle" />
  </kui-empty-state>
</div>
```

#### empty-state-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiEmptyState, KuiEmptyStateIcon, KuiIcon } from '@kikita-labs/ui';

@Component({
  selector: 'app-empty-state-size-example',
  imports: [KuiEmptyState, KuiEmptyStateIcon, KuiIcon],
  templateUrl: './empty-state-size-example.html',
  styleUrl: './empty-state-size-example.scss',
})
export class EmptyStateSizeExample {}
```

#### empty-state-size-example.scss

```scss
.empty-state-size-example {
  display: flex;
  flex-direction: column;
  gap: var(--kui-space-6, 24px);
  inline-size: 100%;
}
```

### empty-state-description-example

#### empty-state-description-example.html

```html
<kui-empty-state size="sm" description="No results match the current filters." />
```

#### empty-state-description-example.ts

```ts
import { Component } from '@angular/core';

import { KuiEmptyState } from '@kikita-labs/ui';

@Component({
  selector: 'app-empty-state-description-example',
  imports: [KuiEmptyState],
  templateUrl: './empty-state-description-example.html',
  styleUrl: './empty-state-description-example.scss',
})
export class EmptyStateDescriptionExample {}
```

#### empty-state-description-example.scss

```scss
:host {
  display: block;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| heading | string \| undefined | - | Optional empty-state heading text; omit it for a description-only state. Visual text only, not a forced heading level. |
| description | string \| null | null | Optional supporting text rendered below the title. |
| context | 'no-data' \| 'no-results' \| 'error' \| 'no-access' \| 'success' | 'no-data' | Semantic context. Only changes the icon accent, not layout. |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Empty-state layout size. Small uses a compact horizontal layout. Falls back to defaults.emptyState.size, then the global defaults.size. |
| [kuiEmptyStateIcon] | KuiEmptyStateIcon | - | Marks projected visual content as the decorative icon slot. Kikita marks it aria-hidden. |
| [kuiEmptyStateActions] | KuiEmptyStateActions | - | Marks projected content as the action slot for native buttons, links, or Kikita button directives. |
| KuiEmptyStateOptions | interface | - | Shape of defaults.emptyState: size. |

## Accessibility

- Use surrounding page structure for heading hierarchy. The built-in heading is visual text, not a
  forced heading level.
- Decorative icons should use `[kuiEmptyStateIcon]`.
- Use `role="status"` on the `kui-empty-state` host when a no-results state appears dynamically
  after filtering.
- Actions remain normal interactive elements and should use native buttons or links.

## Playground

Available at /components/empty-state/playground.

---

<!-- route: /components/field -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/field.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/field.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Field

> Label, hint, error, and form-control composition.

- Status: available
- Route: /components/field
- Package: @kikita-labs/ui@2.0.0
- Import: KuiField from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/field.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-field label="Email" hint="Use your work email" required>
  <input kuiInput type="email" />
</kui-field>

<kui-field label="Email" error="Email is required">
  <input kuiInput type="email" />
</kui-field>
```

When `kuiInput` is projected inside `kui-field`, it receives the field id, `aria-describedby`, and invalid state automatically.

Use `kui-field` as the default wrapper for input-like controls whenever a visible label, hint,
error, or required marker is needed. Do not hand-wire those pieces around Kikita inputs in docs,
playground pages, or examples.

## Examples

Rendered at /components/field:

### basic-field-example

#### basic-field-example.html

```html
<div class="basic-field-example">
  <kui-field label="Email" hint="Use your work email">
    <input kuiInput type="email" placeholder="mira@company.dev" />
  </kui-field>

  <kui-field label="Project" error="Project name is required" required>
    <input kuiInput value="" />
  </kui-field>
</div>
```

#### basic-field-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-field-example',
  imports: [KuiField, KuiInput],
  templateUrl: './basic-field-example.html',
  styleUrl: './basic-field-example.scss',
})
export class BasicFieldExample {}
```

#### basic-field-example.scss

```scss
.basic-field-example {
  display: grid;
  inline-size: min(100%, 360px);
  gap: var(--kui-space-4, 16px);
}
```

### field-projected-example

#### field-projected-example.html

```html
<div class="field-projected-example">
  <kui-field label="Email">
    <input kuiInput type="email" placeholder="mira@company.dev" />
    <p kuiHint>Use your work email</p>
    <p kuiError>Email is required</p>
  </kui-field>

  <kui-field label="API key">
    <input kuiInput />
    <p kuiHint class="kui-field-message">
      <span>Stored encrypted. <a href="#encryption">Learn more</a>.</span>
    </p>
  </kui-field>
</div>
```

#### field-projected-example.ts

```ts
import { Component } from '@angular/core';

import { KuiError, KuiField, KuiHint, KuiInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-field-projected-example',
  imports: [KuiError, KuiField, KuiHint, KuiInput],
  templateUrl: './field-projected-example.html',
  styleUrl: './field-projected-example.scss',
})
export class FieldProjectedExample {}
```

#### field-projected-example.scss

```scss
.field-projected-example {
  display: grid;
  gap: var(--kui-space-5, 20px);
  inline-size: min(100%, 24rem);
}
```

### field-affix-example

#### field-affix-example.html

```html
<div class="field-affix-example">
  <kui-field label="Project URL" hint="The prefix and suffix are visual field chrome.">
    <span kuiFieldAffix>https://</span>
    <input kuiInput aria-label="Project slug" />
    <span kuiFieldAffix>.dev</span>
  </kui-field>

  <kui-field label="Search">
    <kui-icon kuiFieldAffix name="search" />
    <input kuiInput aria-label="Search query" />
    <button kuiFieldAffix type="button" aria-label="Clear search">
      <kui-icon name="x" />
    </button>
  </kui-field>
</div>
```

#### field-affix-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiFieldAffix, KuiIcon, KuiInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-field-affix-example',
  imports: [KuiFieldAffix, KuiField, KuiIcon, KuiInput],
  templateUrl: './field-affix-example.html',
  styleUrl: './field-affix-example.scss',
})
export class FieldAffixExample {}
```

#### field-affix-example.scss

```scss
.field-affix-example {
  display: grid;
  gap: var(--kui-space-5, 20px);
  inline-size: min(100%, 24rem);
}
```

### field-input-group-example

#### field-input-group-example.html

```html
<div class="field-input-group-example">
  <kui-field label="API key">
    <div class="kui-input-group">
      <input kuiInput />
      <span class="kui-affix-spinner" role="status" aria-label="Checking key"></span>
    </div>
  </kui-field>
</div>
```

#### field-input-group-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiInput, KuiInputGroup } from '@kikita-labs/ui';

@Component({
  selector: 'app-field-input-group-example',
  imports: [KuiField, KuiInput, KuiInputGroup],
  templateUrl: './field-input-group-example.html',
  styleUrl: './field-input-group-example.scss',
})
export class FieldInputGroupExample {}
```

#### field-input-group-example.scss

```scss
.field-input-group-example {
  display: grid;
  gap: var(--kui-space-5, 20px);
  inline-size: min(100%, 24rem);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | - | Visible label shorthand. Prefer this for simple field labels. |
| hint | string | - | Optional help text rendered below the control and wired through aria-describedby. |
| error | string | - | Explicit error text rendered below the control and wired through aria-describedby. |
| hideErrors | boolean | - | Hides automatic, explicit, and projected error messages while keeping invalid state. |
| required | boolean | - | Explicit required marker override. Omit when Signal Forms can infer it. Also drives aria-required on the projected control. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' | - | Field spacing and projected control size. Falls back to defaults.field.size, then the global defaults.size. |
| [kuiLabel] / [kuiHint] / [kuiError] | marker directives | - | Projected label, hint and error with the same field wiring. kuiError is manual content: render it with @if. |
| [kuiFieldAffix] | directive | - | Prefix, suffix, icon or action chrome inside the field: button hosts get action styling, kui-icon an icon slot, anything else muted text (emphasis input for full color). kuiFieldAffixIcon and kuiFieldAction are explicit overrides. |
| .kui-input-group / KuiInputGroup | class and directive | - | Hand-built input group chrome; the directive delegates clicks on non-interactive chrome to the first enabled control. |
| KuiFieldOptions | interface | - | Shape of defaults.field: clearable, size and hideErrors. Controls inside the field take an explicit field size first, then their own defaults key, then defaults.field.size. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/field/playground.

---

<!-- route: /components/file-upload -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/file-upload.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/file-upload.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# File Upload

> Controlled file picker.

- Status: available
- Route: /components/file-upload
- Package: @kikita-labs/ui@2.0.0
- Import: KuiFileUpload from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/file-upload.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-file-upload
  acceptLabel="PNG, JPG up to 10 MB"
  [accept]="['image/png', 'image/jpeg']"
  [maxSize]="10 * 1024 * 1024"
  [maxCount]="5"
  [(files)]="files"
  (retry)="onRetry($event)"
/>
```

```ts
protected readonly files = signal<KuiUploadFile[]>([]);

protected onRetry(entry: KuiUploadFile): void {
  this.startUpload(entry);
}

private startUpload(entry: KuiUploadFile): void {
  this.files.update((list) =>
    list.map((f) => (f.id === entry.id ? { ...f, status: 'uploading', progress: 0 } : f)),
  );

  // Drive `entry.file` through your own transport, updating `progress` as it
  // advances and setting `status` to 'success' or 'error' (with `errorMsg`)
  // when it settles.
}
```

A newly picked or dropped file lands in the model as `pending`; wire a
`files` effect (or watch `filesChange` via two-way binding) to notice new
`pending` entries and call `startUpload` on them the same way `onRetry` does.

## Examples

Rendered at /components/file-upload:

### basic-file-upload-example

#### basic-file-upload-example.html

```html
<div class="basic-file-upload-example">
  <kui-file-upload
    acceptLabel="PNG, JPG, or PDF up to 10 MB"
    [accept]="['image/png', 'image/jpeg', 'application/pdf']"
    [maxSize]="10 * 1024 * 1024"
    [maxCount]="3"
    [(files)]="files"
    (retry)="handleRetry($event)"
  />
</div>
```

#### basic-file-upload-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiFileUpload, type KuiUploadFile } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-file-upload-example',
  imports: [KuiFileUpload],
  templateUrl: './basic-file-upload-example.html',
  styleUrl: './basic-file-upload-example.scss',
})
export class BasicFileUploadExample {
  protected readonly files = signal<readonly KuiUploadFile[]>([]);

  protected handleRetry(file: KuiUploadFile): void {
    this.files.update((files) =>
      files.map((entry) =>
        entry.id === file.id ? { ...entry, status: 'pending', progress: 0 } : entry,
      ),
    );
  }
}
```

#### basic-file-upload-example.scss

```scss
.basic-file-upload-example {
  display: grid;
  min-width: 0;
  max-width: 32rem;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| variant | 'dropzone' \| 'compact' | 'dropzone' | Renders the full drag-and-drop zone or a compact attach button. |
| mode | 'single' \| 'multiple' | 'multiple' | Controls whether a new selection replaces or appends to the file list. |
| accept | readonly string[] | undefined | Allowed MIME types. Omit it to accept any file type. |
| acceptLabel | string | undefined | Human-readable format and limit hint shown near the picker. |
| maxSize | number | undefined | Maximum file size in bytes. |
| maxCount | number | undefined | Maximum number of files in multiple mode. |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Controls row height, thumbnail scale, and trigger density. |
| disabled | boolean | false | Stops drag, click, and keyboard file-picking interactions. |
| [(files)] | readonly KuiUploadFile[] | [] | Controlled file list. Consumers own upload status and progress after picking. |
| (retry) | KuiUploadFile | - | Emits when an errored item retry action is activated. |
| KuiUploadFile.status | 'pending' \| 'uploading' \| 'success' \| 'error' | - | Per-file state written by the component initially and then by the consumer. |
| messages | Partial<KuiFileUploadMessages> \| undefined | undefined | Per-instance text overrides: prompt, buttons, statuses and errors. Sizes and percentages are formatted with the locale (2.5 MB, 340 kB). They win over scoped and root messages. |
| KuiUploadFile.errorKind | 'type' \| 'size' | - | Set by the component when client-side validation rejects a file; the displayed text then follows the active messages. Omit it for errors you set yourself. |
| KuiFileUploadOptions | interface | - | Shape of defaults.fileUpload: size, variant, mode and removeIcon (takes precedence over defaults.icons.remove). |

## Accessibility

The visible dropzone/button controls a visually hidden native
`<input type="file">` — drag-and-drop is never the only way to select a
file. The native input is `aria-hidden` and out of the tab order; the dropzone
(or the compact "Attach file" button) is the control. The dropzone is
`role="button"` with an `aria-label` that includes `acceptLabel` when set. The
small "Choose file" label inside it is presentational (`aria-hidden`), not a
second button, so a click on it reaches the dropzone and no interactive control
is nested inside another. Upload progress reuses `kui-progress`
(`role="progressbar"`, `aria-valuenow`) with an
`aria-label="Uploading {name}"`. The file list is wrapped in
`aria-live="polite"` so additions/removals are announced, and the
`maxCount` form error is its own `aria-live="polite"` region. The remove
button has `aria-label="Remove {name}"`.

The errored-item Retry control is a native `button[kuiLink]` with caption
typography and an always-visible underline. It remains an action: it has
`type="button"`, does not navigate or submit a surrounding form, and emits the
same `retry` payload for the consumer-owned upload restart.

## Playground

Available at /components/file-upload/playground.

---

<!-- route: /components/group -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/group.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/group.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Group

> Grouped control chrome for adjacent actions and fields.

- Status: available
- Route: /components/group
- Package: @kikita-labs/ui@2.0.0
- Import: KuiGroup from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/group.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<div kuiGroup collapsed>
  <button kuiButton appearance="outline">One</button>
  <button kuiButton appearance="outline">Two</button>
  <button kuiIconButton appearance="outline" aria-label="More">
    <kui-icon name="more" />
  </button>
</div>
```

## Examples

Rendered at /components/group:

### basic-group-example

#### basic-group-example.html

```html
<div class="basic-group-example">
  <div kuiGroup collapsed>
    <button kuiButton type="button" shape="outline">One</button>
    <button kuiButton type="button" shape="outline">Two</button>
    <button kuiIconButton type="button" shape="outline" aria-label="More options">
      <kui-icon [source]="moreIcon" />
    </button>
  </div>
</div>
```

#### basic-group-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiGroup, KuiIcon, KuiIconButton } from '@kikita-labs/ui';

const MORE_ICON =
  '<svg viewBox="0 0 24 24" fill="none"><circle cx="5" cy="12" r="1.6" fill="currentColor"/><circle cx="12" cy="12" r="1.6" fill="currentColor"/><circle cx="19" cy="12" r="1.6" fill="currentColor"/></svg>';

@Component({
  selector: 'app-basic-group-example',
  imports: [KuiButton, KuiGroup, KuiIconButton, KuiIcon],
  templateUrl: './basic-group-example.html',
  styleUrl: './basic-group-example.scss',
})
export class BasicGroupExample {
  protected readonly moreIcon = MORE_ICON;
}
```

#### basic-group-example.scss

```scss
.basic-group-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### group-field-example

#### group-field-example.html

```html
<div class="group-field-example">
  <div kuiGroup collapsed>
    <input kuiInput placeholder="Search projects" />
    <button kuiIconButton type="button" shape="outline" aria-label="Search">
      <kui-icon [source]="searchIcon" />
    </button>
  </div>

  <div kuiGroup collapsed size="sm">
    <input kuiInput placeholder="Search" />
    <button kuiButton type="button" shape="outline">Go</button>
  </div>
</div>
```

#### group-field-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiGroup, KuiIcon, KuiIconButton, KuiInput } from '@kikita-labs/ui';

const SEARCH_ICON =
  '<svg viewBox="0 0 24 24" fill="none"><circle cx="11" cy="11" r="6" stroke="currentColor" stroke-width="2"/><path d="M20 20l-3.5-3.5" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>';

@Component({
  selector: 'app-group-field-example',
  imports: [KuiButton, KuiGroup, KuiIconButton, KuiIcon, KuiInput],
  templateUrl: './group-field-example.html',
  styleUrl: './group-field-example.scss',
})
export class GroupFieldExample {
  protected readonly searchIcon = SEARCH_ICON;
}
```

#### group-field-example.scss

```scss
.group-field-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
  align-items: center;
  justify-content: center;
}
```

### group-orientation-example

#### group-orientation-example.html

```html
<div class="group-orientation-example">
  <div kuiGroup collapsed orientation="horizontal">
    <button kuiButton type="button" shape="outline">Left</button>
    <button kuiButton type="button" shape="outline">Center</button>
    <button kuiButton type="button" shape="outline">Right</button>
  </div>

  <div kuiGroup collapsed orientation="vertical" class="group-orientation-example__vertical">
    <button kuiButton type="button" shape="outline">Top</button>
    <button kuiButton type="button" shape="outline">Middle</button>
    <button kuiButton type="button" shape="outline">Bottom</button>
  </div>
</div>
```

#### group-orientation-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiGroup } from '@kikita-labs/ui';

@Component({
  selector: 'app-group-orientation-example',
  imports: [KuiButton, KuiGroup],
  templateUrl: './group-orientation-example.html',
  styleUrl: './group-orientation-example.scss',
})
export class GroupOrientationExample {}
```

#### group-orientation-example.scss

```scss
.group-orientation-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-6, 24px);
  align-items: center;
  justify-content: center;
}

.group-orientation-example__vertical {
  inline-size: fit-content;
}
```

### group-size-example

#### group-size-example.html

```html
<div class="group-size-example">
  <div kuiGroup collapsed size="xs">
    <button kuiButton type="button" shape="outline">One</button>
    <button kuiButton type="button" shape="outline">Two</button>
  </div>

  <div kuiGroup collapsed size="sm">
    <button kuiButton type="button" shape="outline">One</button>
    <button kuiButton type="button" shape="outline">Two</button>
  </div>

  <div kuiGroup collapsed size="md">
    <button kuiButton type="button" shape="outline">One</button>
    <button kuiButton type="button" shape="outline">Two</button>
  </div>

  <div kuiGroup collapsed size="lg">
    <button kuiButton type="button" shape="outline">One</button>
    <button kuiButton type="button" shape="outline">Two</button>
  </div>
</div>
```

#### group-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiGroup } from '@kikita-labs/ui';

@Component({
  selector: 'app-group-size-example',
  imports: [KuiButton, KuiGroup],
  templateUrl: './group-size-example.html',
  styleUrl: './group-size-example.scss',
})
export class GroupSizeExample {}
```

#### group-size-example.scss

```scss
.group-size-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
  align-items: center;
  justify-content: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| orientation | 'horizontal' \| 'vertical' | 'horizontal' | Layout direction for the grouped controls. Falls back to defaults.group.orientation. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' | 'md' | Size inherited by grouped controls through CSS variables. Set on the group instead of each child. |
| collapsed | boolean | false | Collapses adjacent control borders into a single visual group, removing the double border between children. |
| rounded | boolean | true | Keeps the outer group corners rounded when collapsed. Set to false for square outer corners. |
| KuiGroupOptions | interface | - | Shape of defaults.group: size, orientation, collapsed and rounded. Each input is undefined when omitted and falls back to it. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/group/playground.

---

<!-- route: /components/icon -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/icon.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/icon.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Icon

> SVG icon renderer.

- Status: available
- Route: /components/icon
- Package: @kikita-labs/ui@2.0.0
- Import: KuiIcon from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/icon.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-icon name="check" label="Success" />
<kui-icon [source]="glyph" label="Gauge" />
<kui-icon src="/assets/logo.svg" label="Logo" />
<kui-icon name="check" />
```

Omit `label` for decorative icons. Decorative icons render with `aria-hidden="true"`.

`source` (direct glyph data or inline SVG markup) always takes precedence over `name`; its content
renders synchronously. A `name` that is found in a static registry also renders synchronously, on
the first pass, with no promise and no network request. Only names that need an async resolver
render when it settles.

## Examples

Rendered at /components/icon:

### basic-icon-example

#### basic-icon-example.html

```html
<div class="basic-icon-example">
  <span class="basic-icon-example__status">
    <kui-icon [source]="checkIcon" label="Success" size="18px" />
    Package verified
  </span>

  <button kuiIconButton type="button" shape="soft" aria-label="Run magic action">
    <kui-icon [source]="sparkIcon" />
  </button>
</div>
```

#### basic-icon-example.ts

```ts
import { Component } from '@angular/core';

import { KuiIcon, KuiIconButton } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-icon-example',
  imports: [KuiIconButton, KuiIcon],
  templateUrl: './basic-icon-example.html',
  styleUrl: './basic-icon-example.scss',
})
export class BasicIconExample {
  protected readonly checkIcon =
    '<svg viewBox="0 0 16 16" fill="none"><path d="M3 8l3 3 7-7" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/></svg>';
  protected readonly sparkIcon =
    '<svg viewBox="0 0 16 16" fill="none"><path d="M8 1.5l1.4 4 4.1 1.5-4.1 1.5-1.4 4-1.4-4L2.5 7l4.1-1.5L8 1.5z" stroke="currentColor" stroke-linejoin="round"/></svg>';
}
```

#### basic-icon-example.scss

```scss
.basic-icon-example {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: var(--kui-space-3, 12px);
  flex-wrap: wrap;
}

.basic-icon-example__status {
  display: inline-flex;
  align-items: center;
  gap: var(--kui-space-2, 8px);
  color: var(--kui-color-text);
}
```

### icon-glyph-example

#### icon-glyph-example.html

```html
<div class="icon-glyph-example">
  <kui-icon [source]="gauge" label="Gauge" size="32px" />
  <kui-icon [source]="gauge" label="Gauge, thin stroke" size="32px" [strokeWidth]="1" />
  <kui-icon [source]="gauge" label="Gauge, heavy stroke" size="32px" [strokeWidth]="3" />
  <kui-icon [source]="gauge" label="Large gauge, constant stroke" size="64px" absoluteStrokeWidth />
</div>
```

#### icon-glyph-example.ts

```ts
import { Component } from '@angular/core';

import { KuiIcon, type KuiIconGlyph } from '@kikita-labs/ui';

@Component({
  selector: 'app-icon-glyph-example',
  imports: [KuiIcon],
  templateUrl: './icon-glyph-example.html',
  styleUrl: './icon-glyph-example.scss',
})
export class IconGlyphExample {
  /** Glyph data is plain data drawn through an allowlist, so it is safe from any source. */
  protected readonly gauge: KuiIconGlyph = {
    node: [
      ['path', { d: 'M12 14l4-4' }],
      ['path', { d: 'M3.34 19a10 10 0 1 1 17.32 0' }],
    ],
  };
}
```

#### icon-glyph-example.scss

```scss
.icon-glyph-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-5, 20px);
  align-items: center;
  justify-content: center;
}
```

### swap-icon-set-example

#### swap-icon-set-example.html

```html
<div class="swap-icon-set-example">
  <div class="swap-icon-set-example__item">
    <kui-icon name="star" label="Lucide star" size="28px" />
    <span>Lucide (default)</span>
  </div>

  <div class="swap-icon-set-example__item">
    <app-material-icon-scope />
    <span>Material Symbols</span>
  </div>

  <div class="swap-icon-set-example__item">
    <app-custom-icon-scope />
    <span>Custom set</span>
  </div>
</div>
```

#### swap-icon-set-example.ts

```ts
import { Component } from '@angular/core';

import { KUI_ICONS, KuiIcon, type KuiIconRegistry } from '@kikita-labs/ui';

const MATERIAL_SYMBOLS_ICON_SET: KuiIconRegistry = {
  star: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960" fill="currentColor"><path d="m323-245 157-94 157 95-42-178 138-120-182-16-71-168-71 167-182 16 138 120-42 178Zm-90 125 65-281L80-590l288-25 112-265 112 265 288 25-218 189 65 281-247-149-247 149Zm247-355Z"/></svg>',
};

const CUSTOM_ICON_SET: KuiIconRegistry = {
  'brand-mark':
    '<svg viewBox="0 0 16 16" fill="none"><path d="M3 2v12M3 8l7-6M3 8l7 6" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>',
};

@Component({
  selector: 'app-material-icon-scope',
  imports: [KuiIcon],
  template: `<kui-icon name="star" label="Material Symbols star" size="28px" />`,
  providers: [{ provide: KUI_ICONS, multi: true, useValue: MATERIAL_SYMBOLS_ICON_SET }],
})
export class MaterialIconScope {}

@Component({
  selector: 'app-custom-icon-scope',
  imports: [KuiIcon],
  template: `<kui-icon name="brand-mark" label="Custom brand mark" size="28px" />`,
  providers: [{ provide: KUI_ICONS, multi: true, useValue: CUSTOM_ICON_SET }],
})
export class CustomIconScope {}

@Component({
  selector: 'app-swap-icon-set-example',
  imports: [KuiIcon, MaterialIconScope, CustomIconScope],
  templateUrl: './swap-icon-set-example.html',
  styleUrl: './swap-icon-set-example.scss',
})
export class SwapIconSetExample {}
```

#### swap-icon-set-example.scss

```scss
.swap-icon-set-example {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: var(--kui-space-6, 24px);
  flex-wrap: wrap;
}

.swap-icon-set-example__item {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: var(--kui-space-2, 8px);
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| kui-icon | Component | - | Renders an icon from a registered name, trusted inline SVG source, or image URL. |
| name | KuiIconName \| undefined | undefined | Icon name resolved from icons registered with provideKuiIcons(), falling back to the default pinned Lucide resolver unless disabled. A name in a static registry renders on the first pass; others render when the async resolver settles. |
| source | KuiIconContent \| undefined | undefined | Direct icon content: KuiIconGlyph data (safe from any source) or trusted static inline SVG markup. It takes precedence over name and renders synchronously. |
| src | string \| undefined | undefined | External image URL used when no source or registered name is provided. |
| label | string \| undefined | undefined | Accessible name for meaningful icons. Omit it for decorative icons. |
| size | '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| string \| number | '1em' | Named presets map to Kikita icon-size tokens. Numeric values become pixels, and arbitrary CSS size strings pass through. |
| provideKuiIcons(icons) | EnvironmentProviders | - | Registers a static map of trusted SVG strings, or an async KuiIconResolver function, for name-based icon lookup. Later registrations take precedence for names both define. Route-level only; component providers cannot accept EnvironmentProviders. |
| KUI_ICONS | InjectionToken<readonly KuiIconRegistry[]> | - | The multi-provider token behind provideKuiIcons(). Provide it directly in a component's own providers ({ provide: KUI_ICONS, multi: true, useValue }) to scope an icon-set override to that subtree. |
| provideKikitaUi({ icons }) | 'lucide' \| false | 'lucide' | Registers kui-icon's default resolvers: Lucide (lazily fetched SVG markup from the jsDelivr CDN) and the built-in KUI_BRAND_ICONS set (currently just the 'kikita-brand' wordmark, resolved locally). Set to false to opt out of both. |
| strokeWidth | number \| string \| undefined | undefined | Stroke width in glyph-grid units (24 by 24 for Lucide). Sets --kui-icon-stroke-width on the host; unset keeps the icon weight or the token of an ancestor. |
| absoluteStrokeWidth | boolean | false | Keeps the stroke the same number of pixels at any icon size. Sets --kui-icon-vector-effect: non-scaling-stroke on the host. |
| KuiIconGlyph / KuiIconContent | types | - | Glyph data { node, viewBox? } drawn through an allowlist, and the union of glyph data and trusted SVG markup accepted by source and by registries. |
| createKuiLucideResolver(options?) | (options?: KuiLucideResolverOptions) => KuiIconResolver | - | The safe Lucide resolver for another lucide-static version or for files you host (baseUrl, no trailing slash). Fetched text is converted to glyph data, never inserted as markup. |
| KUI_LUCIDE_STATIC_VERSION | string | '1.51.0' | The exact lucide-static version of the default resolver. It changes only with a library release. |
| --kui-icon-stroke-width / --kui-icon-vector-effect | CSS custom properties | - | Set by strokeWidth and absoluteStrokeWidth; set them on :root or a subtree to restyle every stroke-based icon, structural icons included. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/icon/playground.

---

<!-- route: /components/icon-button -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/icon-button.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/icon-button.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Icon Button

> Compact icon-only action control.

- Status: available
- Route: /components/icon-button
- Package: @kikita-labs/ui@2.0.0
- Import: KuiIconButton from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/icon-button.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

Use `icon` for a registered icon by name, instead of hand-projecting `kui-icon`:

```html
<button kuiIconButton icon="x" aria-label="Close"></button>

<button kuiIconButton shape="soft" appearance="success" icon="check" aria-label="Approve"></button>

<a
  kuiIconButton
  shape="outline"
  appearance="primary"
  href="/settings"
  icon="settings"
  aria-label="Settings"
></a>
```

Project `kui-icon` directly when the icon needs `source` or `src` instead of a registered `name`:

```html
<button kuiIconButton aria-label="Close">
  <kui-icon [source]="closeIcon" />
</button>
```

Use `loading` to show a spinner in place of the icon while an action is pending:

```html
<button kuiIconButton icon="check" loading aria-label="Save"></button>
```

## Examples

Rendered at /components/icon-button:

### icon-button-appearance-example

#### icon-button-appearance-example.html

```html
<div class="icon-button-appearance-example">
  <button kuiIconButton type="button" aria-label="Add item">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" shape="soft" aria-label="Add item softly">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" shape="outline" aria-label="Add item with outline">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" shape="ghost" aria-label="Add item quietly">
    <kui-icon [source]="plusIcon" />
  </button>
  <button kuiIconButton type="button" appearance="danger" aria-label="Delete item">
    <kui-icon [source]="trashIcon" />
  </button>
  <button
    kuiIconButton
    type="button"
    shape="outline"
    appearance="danger"
    aria-label="Delete item with outline"
  >
    <kui-icon [source]="trashIcon" />
  </button>
</div>
```

#### icon-button-appearance-example.ts

```ts
import { Component } from '@angular/core';

import { KuiIcon, KuiIconButton } from '@kikita-labs/ui';

const PLUS_ICON =
  '<svg viewBox="0 0 24 24" fill="none"><path d="M12 5v14M5 12h14" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>';
const TRASH_ICON =
  '<svg viewBox="0 0 24 24" fill="none"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 14h10l1-14M9 7V4h6v3" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>';

@Component({
  selector: 'app-icon-button-appearance-example',
  imports: [KuiIconButton, KuiIcon],
  templateUrl: './icon-button-appearance-example.html',
  styleUrl: './icon-button-appearance-example.scss',
})
export class IconButtonAppearanceExample {
  protected readonly plusIcon = PLUS_ICON;
  protected readonly trashIcon = TRASH_ICON;
}
```

#### icon-button-appearance-example.scss

```scss
.icon-button-appearance-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### icon-button-size-example

#### icon-button-size-example.html

```html
<div class="icon-button-size-example">
  <button kuiIconButton type="button" size="xs" aria-label="Extra small settings">
    <kui-icon [source]="settingsIcon" />
  </button>
  <button kuiIconButton type="button" size="sm" aria-label="Small settings">
    <kui-icon [source]="settingsIcon" />
  </button>
  <button kuiIconButton type="button" size="md" aria-label="Medium settings">
    <kui-icon [source]="settingsIcon" />
  </button>
  <button kuiIconButton type="button" size="lg" aria-label="Large settings">
    <kui-icon [source]="settingsIcon" />
  </button>
  <button kuiIconButton type="button" disabled aria-label="Disabled settings">
    <kui-icon [source]="settingsIcon" />
  </button>
  <button kuiIconButton type="button" loading aria-label="Loading settings">
    <kui-icon [source]="settingsIcon" />
  </button>
</div>
```

#### icon-button-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiIcon, KuiIconButton } from '@kikita-labs/ui';

const SETTINGS_ICON =
  '<svg viewBox="0 0 24 24" fill="none"><path d="M12 15.5a3.5 3.5 0 1 0 0-7 3.5 3.5 0 0 0 0 7Z" stroke="currentColor" stroke-width="2"/><path d="M19.4 15a1.7 1.7 0 0 0 .34 1.88l.04.04a2 2 0 0 1-2.83 2.83l-.04-.04a1.7 1.7 0 0 0-1.88-.34 1.7 1.7 0 0 0-1.03 1.56V21a2 2 0 0 1-4 0v-.06A1.7 1.7 0 0 0 8.96 19.4a1.7 1.7 0 0 0-1.88.34l-.04.04a2 2 0 0 1-2.83-2.83l.04-.04A1.7 1.7 0 0 0 4.6 15a1.7 1.7 0 0 0-1.56-1.03H3a2 2 0 0 1 0-4h.06A1.7 1.7 0 0 0 4.6 8.96a1.7 1.7 0 0 0-.34-1.88l-.04-.04a2 2 0 1 1 2.83-2.83l.04.04A1.7 1.7 0 0 0 8.96 4.6 1.7 1.7 0 0 0 10 3.06V3a2 2 0 0 1 4 0v.06A1.7 1.7 0 0 0 15.04 4.6a1.7 1.7 0 0 0 1.88-.34l.04-.04a2 2 0 0 1 2.83 2.83l-.04.04a1.7 1.7 0 0 0-.34 1.88A1.7 1.7 0 0 0 20.94 10H21a2 2 0 0 1 0 4h-.06A1.7 1.7 0 0 0 19.4 15Z" stroke="currentColor" stroke-width="2" stroke-linejoin="round"/></svg>';

@Component({
  selector: 'app-icon-button-size-example',
  imports: [KuiIconButton, KuiIcon],
  templateUrl: './icon-button-size-example.html',
  styleUrl: './icon-button-size-example.scss',
})
export class IconButtonSizeExample {
  protected readonly settingsIcon = SETTINGS_ICON;
}
```

#### icon-button-size-example.scss

```scss
.icon-button-size-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### icon-button-icon-example

#### icon-button-icon-example.html

```html
<div class="icon-button-icon-example">
  <button kuiIconButton icon="plus" aria-label="Add item" type="button"></button>
  <button
    kuiIconButton
    shape="outline"
    appearance="danger"
    icon="trash-2"
    aria-label="Delete item"
    type="button"
  ></button>
  <button kuiIconButton shape="soft" icon="settings" aria-label="Settings" type="button"></button>
</div>
```

#### icon-button-icon-example.ts

```ts
import { Component } from '@angular/core';

import { KuiIconButton } from '@kikita-labs/ui';

@Component({
  selector: 'app-icon-button-icon-example',
  imports: [KuiIconButton],
  templateUrl: './icon-button-icon-example.html',
  styleUrl: './icon-button-icon-example.scss',
})
export class IconButtonIconExample {}
```

#### icon-button-icon-example.scss

```scss
.icon-button-icon-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| shape | 'solid' \| 'soft' \| 'outline' \| 'ghost' | 'ghost' | Surface treatment. Defaults to ghost. Combines freely with appearance. |
| appearance | 'primary' \| 'danger' \| 'success' \| 'warning' \| null | null | Semantic color intent. Without an explicit value, solid/soft use primary colors and outline/ghost use neutral defaults. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' | 'md' | Square control size mapped to Kikita control height tokens (matches kui-input height at md). |
| disabled | boolean | false | Disables native button behavior. Anchor icon buttons receive aria-disabled and leave tab order. |
| loading | boolean | false | Replaces the icon (and any projected content) with a centered kui-loader spinner, sets aria-busy, and behaves like disabled. |
| icon | KuiIconName \| undefined | undefined | Renders a kui-icon resolved by name as the button content, prepended before any other projected content, without hand-projecting kui-icon. |
| KuiButtonOptions | interface | - | Shape of defaults.iconButton: shape, appearance and size. The old { button, iconButton } pair is KuiButtonProviderOptions and is deprecated. |

## Accessibility

Icon-only controls must have an accessible label, normally through `aria-label`. Use native
`button` for actions and `a` for navigation.

Native button and anchor keyboard behavior is preserved. The directive adds no custom key
bindings.

## Playground

Available at /components/icon-button/playground.

---

<!-- route: /components/input -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/input.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/input.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Input

> Native text input styling with field integration.

- Status: available
- Route: /components/input
- Package: @kikita-labs/ui@2.0.0
- Import: KuiInput from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/input.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

Import the directive where it is used:

```ts
import { KuiInput } from '@kikita-labs/ui';
```

Import the Kikita UI runtime styles once in the application entry point:

```ts
import '@kikita-labs/ui/styles';
```

Use the directive on a native input. Add a native label or `aria-label` when the input is not
inside a labelled Field:

```html
<label for="email">Email</label> <input id="email" kuiInput type="email" autocomplete="email" />
```

Inside `kui-field`, the Field supplies the visible label and wires its generated control id,
hint, error, and invalid state:

```html
<kui-field label="Email" hint="Use your work email">
  <input kuiInput type="email" autocomplete="email" />
</kui-field>
```

Use `textarea[kuiTextarea]` for multiline controls. Use the dedicated Kikita UI controls for
specialized number, color, date, selection, and other input behaviors.

## Examples

Rendered at /components/input:

### basic-input-example

#### basic-input-example.html

```html
<div class="basic-input-example">
  <input kuiInput type="email" aria-label="Work email" placeholder="mira@company.dev" />
  <input kuiInput aria-label="Project slug" value="kikita-ui" />
  <input kuiInput invalid aria-label="Invalid project slug" value="Invalid value" />
</div>
```

#### basic-input-example.ts

```ts
import { Component } from '@angular/core';

import { KuiInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-input-example',
  imports: [KuiInput],
  templateUrl: './basic-input-example.html',
  styleUrl: './basic-input-example.scss',
})
export class BasicInputExample {}
```

#### basic-input-example.scss

```scss
.basic-input-example {
  display: grid;
  inline-size: min(100%, 360px);
  gap: var(--kui-space-4, 16px);
}
```

### input-group-example

#### input-group-example.html

```html
<kui-field label="Project URL" hint="Affixes are visual field chrome." class="input-group-example">
  <span kuiFieldAffix>https://</span>
  <input kuiInput aria-label="Project slug" value="kikita-ui" />
  <span kuiFieldAffix>.dev</span>
</kui-field>
```

#### input-group-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiFieldAffix, KuiInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-input-group-example',
  imports: [KuiFieldAffix, KuiField, KuiInput],
  templateUrl: './input-group-example.html',
  styleUrl: './input-group-example.scss',
})
export class InputGroupExample {}
```

#### input-group-example.scss

```scss
.input-group-example {
  inline-size: min(100%, 380px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Resolved in order: local size, parent Field effective size, defaults.input.size, root defaults.size, then md. The resolved value is written to data-kui-size. |
| invalid | boolean | false | Marks a standalone input (or one outside a Field error state) invalid: sets data-kui-invalid and aria-invalid="true". With [formField] the Field state wins and this binding is not a manual override. |
| id | string \| undefined | undefined | Inside a Field, omitted uses the Field generated control id; outside, no id is added. An explicit id can leave the Field label for attribute pointing elsewhere. |
| KuiInputOptions | interface | - | Shape of defaults.input: size. |

## Accessibility

- Keep the native `<input>` semantics; do not add an ARIA role to it.
- Give every input an accessible name through a `kui-field` label, an associated native `<label>`,
  or `aria-label`. Placeholder text alone is not a label.
- The directive uses the containing Field's control id and references only its currently rendered
  hint and error with `aria-describedby`. The Field exposes a visible error as `role="alert"`.
- `aria-invalid` is omitted when the input is valid. When invalid, the directive sets
  `aria-invalid="true"` and the `data-kui-invalid` styling hook.
- Keep native `disabled` and `readonly` distinct. A disabled input is not available for normal
  interaction; a read-only input remains a native focusable control whose value cannot be edited.
  Required semantics come from native HTML or Signal Forms, not from the Field's visual required
  marker.

## Playground

Available at /components/input/playground.

---

<!-- route: /components/line-chart -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/line-chart.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/chart.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Line Chart

> Line and area chart for trends over categories.

- Status: available
- Route: /components/line-chart
- Package: @kikita-labs/ui@2.0.0
- Import: KuiLineChart from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/chart.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-line-chart ariaLabel="Sessions per day" [series]="series" [categories]="categories" />
```

```ts
protected readonly series: readonly KuiChartCartesianSeries[] = [
  { id: 'sessions', name: 'Sessions', data: [120, 180, 150, 220, 260, 210, 300] },
];
protected readonly categories = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
```

`ariaLabel` has a chart-type fallback name and should describe what the chart shows. It is distinct
from each point's own `aria-label` (its value).

## Examples

Rendered at /components/line-chart:

### basic-line-chart-example

#### basic-line-chart-example.html

```html
<div class="chart-example">
  <kui-line-chart ariaLabel="Sessions per day" [series]="series" [categories]="categories" />
</div>
```

#### basic-line-chart-example.ts

```ts
import { Component } from '@angular/core';

import { type KuiChartCartesianSeries, KuiLineChart } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-line-chart-example',
  imports: [KuiLineChart],
  templateUrl: './basic-line-chart-example.html',
  styleUrl: './basic-line-chart-example.scss',
})
export class BasicLineChartExample {
  protected readonly series: readonly KuiChartCartesianSeries[] = [
    { id: 'sessions', name: 'Sessions', data: [120, 180, 150, 220, 260, 210, 300] },
  ];
  protected readonly categories = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
}
```

#### basic-line-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### line-area-chart-example

#### line-area-chart-example.html

```html
<div class="chart-example">
  <kui-line-chart
    ariaLabel="Traffic by source"
    [series]="series"
    [categories]="categories"
    [area]="true"
    [patterns]="true"
    [axes]="axes"
  />
</div>
```

#### line-area-chart-example.ts

```ts
import { Component } from '@angular/core';

import {
  type KuiChartAxesOptions,
  type KuiChartCartesianSeries,
  KuiLineChart,
} from '@kikita-labs/ui';

@Component({
  selector: 'app-line-area-chart-example',
  imports: [KuiLineChart],
  templateUrl: './line-area-chart-example.html',
  styleUrl: './line-area-chart-example.scss',
})
export class LineAreaChartExample {
  protected readonly series: readonly KuiChartCartesianSeries[] = [
    { id: 'sessions', name: 'Sessions', data: [120, 180, 150, 220, 260, 210, 300] },
    { id: 'signups', name: 'Sign-ups', data: [40, 65, 52, 90, 110, 80, 140] },
  ];
  protected readonly categories = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
  protected readonly axes: KuiChartAxesOptions = { xTitle: 'Day', yTitle: 'Count' };
}
```

#### line-area-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### line-gaps-chart-example

#### line-gaps-chart-example.html

```html
<div class="chart-example">
  <kui-line-chart
    ariaLabel="Sessions with a missing day"
    [series]="series"
    [categories]="categories"
    [tooltip]="formatTooltip"
    [valueFormat]="formatValue"
    size="sm"
  />
</div>
```

#### line-gaps-chart-example.ts

```ts
import { Component } from '@angular/core';

import { type KuiChartCartesianSeries, type KuiChartPoint, KuiLineChart } from '@kikita-labs/ui';

@Component({
  selector: 'app-line-gaps-chart-example',
  imports: [KuiLineChart],
  templateUrl: './line-gaps-chart-example.html',
  styleUrl: './line-gaps-chart-example.scss',
})
export class LineGapsChartExample {
  protected readonly series: readonly KuiChartCartesianSeries[] = [
    { id: 'sessions', name: 'Sessions', data: [120, 180, null, 220, 260, 210, 300] },
  ];
  protected readonly categories = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];

  protected readonly formatValue = (value: number): string => value.toLocaleString('en-US');

  protected readonly formatTooltip = (point: KuiChartPoint): string =>
    `${point.categoryLabel}: ${point.value.toLocaleString('en-US')} sessions`;
}
```

#### line-gaps-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### line-external-legend-example

#### line-external-legend-example.html

```html
<div class="chart-example">
  <kui-line-chart
    #chartRef
    ariaLabel="Sessions and sign-ups"
    [series]="series"
    [categories]="categories"
    [legend]="false"
  />
  <kui-chart-legend [chart]="chartRef" />
</div>
```

#### line-external-legend-example.ts

```ts
import { Component } from '@angular/core';

import { type KuiChartCartesianSeries, KuiChartLegend, KuiLineChart } from '@kikita-labs/ui';

@Component({
  selector: 'app-line-external-legend-example',
  imports: [KuiChartLegend, KuiLineChart],
  templateUrl: './line-external-legend-example.html',
  styleUrl: './line-external-legend-example.scss',
})
export class LineExternalLegendExample {
  protected readonly series: readonly KuiChartCartesianSeries[] = [
    { id: 'sessions', name: 'Sessions', data: [120, 180, 150, 220, 260, 210, 300] },
    { id: 'signups', name: 'Sign-ups', data: [40, 65, 52, 90, 110, 80, 140] },
  ];
  protected readonly categories = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
}
```

#### line-external-legend-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### line-states-chart-example

#### line-states-chart-example.html

```html
<div class="chart-example chart-example--stack">
  <kui-line-chart
    ariaLabel="Loading sessions"
    [series]="series"
    [categories]="categories"
    [loading]="true"
    size="sm"
  />
  <kui-line-chart ariaLabel="Empty sessions" [series]="[]" size="sm" />
</div>
```

#### line-states-chart-example.ts

```ts
import { Component } from '@angular/core';

import { type KuiChartCartesianSeries, KuiLineChart } from '@kikita-labs/ui';

@Component({
  selector: 'app-line-states-chart-example',
  imports: [KuiLineChart],
  templateUrl: './line-states-chart-example.html',
  styleUrl: './line-states-chart-example.scss',
})
export class LineStatesChartExample {
  protected readonly series: readonly KuiChartCartesianSeries[] = [
    { id: 'sessions', name: 'Sessions', data: [120, 180, 150, 220, 260, 210, 300] },
  ];
  protected readonly categories = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
}
```

#### line-states-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| series | readonly KuiChartCartesianSeries[] | - | Required. { id?, name, color?, data }, with data aligned index for index with categories. null, NaN and Infinity are gaps. Without a non-gap value the empty composition renders. |
| categories | readonly string[] | [] | Category labels aligned with each series data. The shorter side wins. |
| area | boolean | false | Fills the area under each line. It is not a separate chart type. |
| patterns | boolean | false | With area, fills each area with one of eight hatch patterns (colour independence). |

## Accessibility

- The `<svg>` is the graphic: `role="graphics-document"` with the name and the role description
  (`aria-roledescription`). The wrapper has no role, and axis text, gridlines and decorative shapes
  are `aria-hidden`.
- Each point/bar/slice is `role="graphics-symbol img"` with its own `aria-label` (the same text as
  the tooltip) -- an indivisible graphical unit, per the WAI-ARIA Graphics Module.
- Roving tabindex across points/bars/slices (see Keyboard). The inline legend is a named group of
  native `<button aria-pressed>` items at least 24px high.
- The tooltip shown on hover is the same one shown on keyboard focus (one shared overlay, retargeted
  between marks). It is dismissible and persistent. On pointer hover it appears at the pointer and follows
  it; keyboard focus anchors it to the focused mark. On touch, a tap pins the tooltip open until an
  outside tap, `Escape`, or a tap on a different mark; it also always renders below 768px, since it is
  the primary way to read a chart's exact value.
- Pointer hit targets: a line chart shows the tooltip while the pointer is on the point (its marker plus a
  3px margin), a scatter chart on the point's hit circle (at least 12px in radius), a bar chart on the bar
  itself and a donut on the slice.
- Text is at least 12px on screen: axis text defaults to 13px and keeps its pixel size at any width.
- `prefers-reduced-motion: reduce` disables the hover/dim transition and the donut sweep.
- The alt-table is a real accessible alternative to the graphic, not a decorative duplicate.

Automated checks (keyboard, accessibility tree, axe, forced-colours media emulation, reduced motion)
are in `chart-contract.spec.ts` and `accessibility.spec.ts`. A session with a real screen reader has
not been run and stays pending.

## Playground

Available at /components/line-chart/playground.

---

<!-- route: /components/link -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/link.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/link.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Link

> Inline interactive text for navigation or a JS-driven action.

- Status: available
- Route: /components/link
- Package: @kikita-labs/ui@2.0.0
- Import: KuiLink from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/link.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<a kuiLink href="/docs">Read the docs</a>
```

### Tone

```html
<a kuiLink tone="default" href="/settings">Settings</a>
<a kuiLink tone="muted" href="/archive">Archive</a>
<a kuiLink tone="primary" href="/docs">Docs (default)</a>
<a kuiLink tone="success" href="/billing">Upgrade</a>
<a kuiLink tone="warning" href="/billing/past-due">Resolve billing issue</a>
<a kuiLink tone="danger" href="/account/delete">Delete account</a>
```

Tone sets the rest color only. Hover, focus, and active never change color -- only underline
thickness and a focus ring do (see Accessibility).

### Underline

```html
<a kuiLink underline="always" href="/docs">Inline link inside a paragraph of body text</a>
<a kuiLink underline="hover" href="/docs">Standalone link (default)</a>
<a kuiLink underline="none" href="/docs">No underline</a>
```

Use `always` for a link inside a paragraph of running text -- color alone is not a sufficient
signal there. `hover` (the default) is meant for a link that already stands apart from body text
(a card title, a nav item); it still underlines on `:focus-visible`/`:active`, not only mouse
hover, so keyboard and touch users get the same cue.

### Sizes (via composed `[kuiText]`)

```html
<a kuiLink variant="body-lg" href="/docs">body-lg</a>
<a kuiLink variant="body" href="/docs">body (default)</a>
<a kuiLink variant="body-sm" href="/docs">body-sm</a>
<a kuiLink variant="caption" href="/docs">caption</a>
```

`variant` is forwarded straight into the internally-composed `[kuiText]` directive -- `[kuiLink]`
carries no typography scale of its own. Only inline text roles make sense for a link. A link
acting as a heading wraps `[kuiLink]` inside an `<h1>`-`<h6>`, not the reverse -- so heading
semantics never depend on whether the text happens to be a link.

Font size, weight, and line height use the selected `--kui-type-<variant>-*`
tokens. The component layer must not replace the role's line height with the
parent's value. This requirement is preserved from the original Link design's
Typography anatomy; the correction is included in Unreleased.

### Icons

```html
<a kuiLink iconStart="download" href="/report.csv">Download report</a>
<a kuiLink iconEnd="arrow-right" href="/updates">All updates</a>
```

`iconStart`/`iconEnd` take a Lucide icon name, rendered through `kui-icon` and decorative (the
link text already carries the meaning).

### External links

```html
<a kuiLink href="https://example.com" target="_blank">External docs</a>
```

`external` defaults to `target() === '_blank'`; set it explicitly to override. When true:

- `rel="noopener noreferrer"` is merged with any `rel` you already set.
- The library's own static external-link chrome glyph fills the `iconEnd` slot, unless you pass
  an explicit `iconEnd` (it is library chrome, not a consumer-chosen icon, so it is a structural icon: synchronous
  icon data drawn as inline SVG rather than the async, name-resolved `kui-icon`, the same treatment
  `kuiDatePicker`'s calendar affix and `kuiTimePicker`'s clock affix get). Replace it with
  `defaults.link.externalIcon` or the `externalLink` role; see [Structural Icons](structural-icons.md).
- A visually-hidden suffix is appended to the accessible name: the `link.opensInNewTab` message, `(opens in a new tab)` by default.

### Disabled

```html
<a kuiLink href="/report.csv" disabled>Download (unavailable)</a>
<button kuiLink type="button" disabled>Copy link</button>
```

`<a>` has no native `disabled` attribute, so a disabled anchor gets `aria-disabled="true"` +
`tabIndex="-1"` + a click handler that cancels navigation -- the same convention `[kuiButton]`
already applies for `as="a"`. Pointer input never reaches a disabled link (`pointer-events: none`),
so the handler only guards keyboard and programmatic activation. A host `<button>` also gets the
native `disabled` attribute.

### JS-driven action, no navigation

```html
<button kuiLink type="button" (click)="copyToClipboard()">Copy link</button>
```

Per MUI's accessibility guidance: a link with no real `href` should render as a `<button>`, not an
`<a>`.

## Examples

Rendered at /components/link:

### basic-link-example

#### basic-link-example.html

```html
<div class="link-example">
  <a kuiLink tone="default" href="#settings">Settings</a>
  <a kuiLink tone="muted" href="#archive">Archive</a>
  <a kuiLink tone="primary" href="#docs">Docs (default)</a>
  <a kuiLink tone="success" href="#billing">Upgrade</a>
  <a kuiLink tone="warning" href="#past-due">Resolve billing issue</a>
  <a kuiLink tone="danger" href="#delete">Delete account</a>
</div>
```

#### basic-link-example.ts

```ts
import { Component } from '@angular/core';

import { KuiLink } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-link-example',
  imports: [KuiLink],
  templateUrl: './basic-link-example.html',
  styleUrl: './basic-link-example.scss',
})
export class BasicLinkExample {}
```

#### basic-link-example.scss

```scss
.link-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
  align-items: center;
}
```

### link-underline-example

#### link-underline-example.html

```html
<div class="link-example">
  <a kuiLink underline="always" href="#inline">Inline link</a>
  <a kuiLink underline="hover" href="#standalone">Standalone link (default)</a>
  <a kuiLink underline="none" href="#plain">No underline</a>
  <a kuiLink variant="body-lg" href="#lg">body-lg</a>
  <a kuiLink variant="body-sm" href="#sm">body-sm</a>
  <a kuiLink variant="caption" href="#caption">caption</a>
</div>
```

#### link-underline-example.ts

```ts
import { Component } from '@angular/core';

import { KuiLink } from '@kikita-labs/ui';

@Component({
  selector: 'app-link-underline-example',
  imports: [KuiLink],
  templateUrl: './link-underline-example.html',
  styleUrl: './link-underline-example.scss',
})
export class LinkUnderlineExample {}
```

#### link-underline-example.scss

```scss
.link-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
  align-items: center;
}
```

### link-icons-example

#### link-icons-example.html

```html
<div class="link-example">
  <a kuiLink iconStart="download" href="#report">Download report</a>
  <a kuiLink iconEnd="arrow-right" href="#updates">All updates</a>
  <a kuiLink href="https://example.com" target="_blank">External docs</a>
</div>
```

#### link-icons-example.ts

```ts
import { Component } from '@angular/core';

import { KuiLink } from '@kikita-labs/ui';

@Component({
  selector: 'app-link-icons-example',
  imports: [KuiLink],
  templateUrl: './link-icons-example.html',
  styleUrl: './link-icons-example.scss',
})
export class LinkIconsExample {}
```

#### link-icons-example.scss

```scss
.link-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
  align-items: center;
}
```

### link-actions-example

#### link-actions-example.html

```html
<div class="link-example">
  <button kuiLink type="button" (click)="copy()">Copy link ({{ copied() }})</button>
  <a kuiLink href="#report" disabled>Download (unavailable)</a>
  <button kuiLink type="button" disabled>Copy link</button>
</div>
```

#### link-actions-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiLink } from '@kikita-labs/ui';

@Component({
  selector: 'app-link-actions-example',
  imports: [KuiLink],
  templateUrl: './link-actions-example.html',
  styleUrl: './link-actions-example.scss',
})
export class LinkActionsExample {
  protected readonly copied = signal(0);

  protected copy(): void {
    this.copied.update((count) => count + 1);
  }
}
```

#### link-actions-example.scss

```scss
.link-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
  align-items: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| tone | 'default' \| 'muted' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| undefined | undefined | Rest colour only; hover, focus and active never change it. Falls back to defaults.link.tone, then primary. |
| underline | 'always' \| 'hover' \| 'none' \| undefined | undefined | When the link is underlined (defaults.link.underline, then hover). Use always inside running text; hover also underlines on focus-visible and active. |
| variant | 'body-lg' \| 'body' \| 'body-sm' \| 'caption' | 'body' | Forwarded to the composed kuiText directive. The link has no typography scale of its own and ignores defaults.typography. |
| iconStart / iconEnd | string \| undefined | undefined | Decorative icon name rendered through kui-icon before or after the content. An explicit iconEnd replaces the external-link glyph. |
| target / rel | string \| undefined | undefined | Reflected onto the host as native attributes. rel is merged with noopener noreferrer for external links. |
| external | boolean \| undefined | target() === "_blank" | Marks the link as leaving the app: adds rel="noopener noreferrer", the external-link glyph (unless iconEnd is set) and a hidden "(opens in a new tab)" suffix to the name. |
| disabled | boolean | false | A disabled anchor gets aria-disabled, tabindex -1 and a blocked click; a button also gets the native disabled attribute. |
| href, type, (click) | native attributes | - | Plain bindings on the host a or button. There is no as input: use a button without a real href for a JS-driven action. |
| --kui-link-color-default / -muted / -primary / -success / -warning / -danger / -disabled | CSS custom properties | - | Rest colour per tone and the disabled colour. |
| --kui-link-focus-ring / -radius-focus | CSS custom properties | - | Focus ring shadow and its corner radius. |
| --kui-link-decoration-thickness-rest / -active | CSS custom properties | - | Underline thickness at rest and on hover, focus and active. |
| --kui-link-gap | CSS custom property | - | Gap between the icons and the text. |
| KuiLinkOptions | interface | - | Shape of defaults.link: tone, underline and externalIcon. |

## Accessibility

- Host is a native `<a href>` or `<button type="button">` -- no custom ARIA role.
- The visible link text is the accessible name; icons are decorative (`aria-hidden` via `kui-icon`
  without a `label`), never the only carrier of meaning.
- `:focus-visible` shows an explicit ring (`box-shadow` on `--kui-link-focus-ring`).
- Disabled: `aria-disabled="true"` + `tabIndex="-1"` + a blocked click handler (`<a>` has no native
  `disabled`; a host `<button>` also gets the native attribute).
- External links get `rel="noopener noreferrer"` and a visually-hidden "(opens in a new tab)" text
  appended to the accessible name, not only a visual icon.
- Color is never the only signal: default/hover/focus/active differ by underline thickness (and
  focus by the ring), not color alone. Avoid `underline="none"` for a link inside a paragraph of
  running text -- there, tone-color-only is not enough.
- No `visited` tone/state -- not found in Taiga `tuiLink`, MUI `Link`, or the kit's own `Text`; not
  a typical pattern in product SaaS/dashboard UI (see Explicitly Not Included).

| Key             | Action                                                                                 |
| --------------- | -------------------------------------------------------------------------------------- |
| Tab / Shift+Tab | Moves focus to/from the link in the page's normal order (disabled links are excluded). |
| Enter           | Activates the link/button (native `<a>`/`<button>` behavior).                          |
| Space           | Activates only when the host is a `<button>` (native `<a>` does not respond to Space). |

## Playground

Available at /components/link/playground.

---

<!-- route: /components/loader -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/loader.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/loader.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Loader

> Inline loading indicator for buttons and status areas.

- Status: available
- Route: /components/loader
- Package: @kikita-labs/ui@2.0.0
- Import: KuiLoader from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/loader.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<span kuiLoader label="Loading"></span>

<button kuiButton disabled>
  <span kuiLoader size="sm" label="Saving"></span>
  Saving
</button>
```

The directive sets `role="status"` and `aria-live="polite"`.

## Examples

Rendered at /components/loader:

### basic-loader-example

#### basic-loader-example.html

```html
<div class="loader-example">
  <span kuiLoader label="Loading"></span>
</div>
```

#### basic-loader-example.ts

```ts
import { Component } from '@angular/core';

import { KuiLoader } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-loader-example',
  imports: [KuiLoader],
  templateUrl: './basic-loader-example.html',
  styleUrl: './basic-loader-example.scss',
})
export class BasicLoaderExample {}
```

#### basic-loader-example.scss

```scss
.loader-example {
  display: flex;
  align-items: center;
  justify-content: center;
}
```

### loader-button-example

#### loader-button-example.html

```html
<div class="loader-button-example">
  <button kuiButton type="button" disabled>
    <span kuiLoader size="sm" label="Saving"></span>
    Saving
  </button>

  <button kuiButton type="button" loading>Saving</button>
</div>
```

#### loader-button-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiLoader } from '@kikita-labs/ui';

@Component({
  selector: 'app-loader-button-example',
  imports: [KuiButton, KuiLoader],
  templateUrl: './loader-button-example.html',
  styleUrl: './loader-button-example.scss',
})
export class LoaderButtonExample {}
```

#### loader-button-example.scss

```scss
.loader-button-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
  justify-content: center;
}
```

### loader-size-example

#### loader-size-example.html

```html
<div class="loader-size-example">
  <span kuiLoader size="xs" label="Loading extra small"></span>
  <span kuiLoader size="sm" label="Loading small"></span>
  <span kuiLoader size="md" label="Loading medium"></span>
  <span kuiLoader size="lg" label="Loading large"></span>
</div>
```

#### loader-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiLoader } from '@kikita-labs/ui';

@Component({
  selector: 'app-loader-size-example',
  imports: [KuiLoader],
  templateUrl: './loader-size-example.html',
  styleUrl: './loader-size-example.scss',
})
export class LoaderSizeExample {}
```

#### loader-size-example.scss

```scss
.loader-size-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
  align-items: center;
  justify-content: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Loader size. Falls back to defaults.loader.size, then the global defaults.size, then md. |
| label | string \| undefined | undefined | Accessible label rendered as aria-label and announced through the host role="status" and aria-live="polite". Falls back to the common.loading message (Loading). |
| --kui-loader-size | CSS custom property | - | Overrides the rendered loader diameter for the current size step. |
| --kui-loader-track | CSS custom property | - | Overrides the loader track (background ring) color. |
| --kui-loader-fill | CSS custom property | - | Overrides the loader spinning fill color. |
| --kui-loader-border-width | CSS custom property | - | Overrides the loader ring stroke width. |
| --kui-loader-duration | CSS custom property | - | Overrides the spin animation duration. |
| --kui-loader-duration-reduced | CSS custom property | - | Spin animation duration used when the user prefers reduced motion. |
| KuiLoaderOptions | interface | - | Shape of defaults.loader: size. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/loader/playground.

---

<!-- route: /components/media-viewer -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/media-viewer.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/media-viewer.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Media Viewer

> Fullscreen photo lightbox with navigation, thumbnails and zoom.

- Status: available
- Route: /components/media-viewer
- Package: @kikita-labs/ui@2.0.0
- Import: kuiMediaViewer from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/media-viewer.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```ts
class PhotoGrid {
  private readonly openViewer = kuiMediaViewer();

  protected readonly photos: KuiMediaViewerItem[] = [
    { id: 'p1', src: '/photos/1.jpg', alt: 'Sunset over the bay' },
    { id: 'p2', src: '/photos/2.jpg', alt: 'City skyline at night' },
  ];

  protected openPhotoAt(index: number): void {
    this.openViewer({ items: this.photos, index });
  }
}
```

```html
@for (photo of photos; track photo.id) {
<button type="button" (click)="openPhotoAt($index)">
  <img [src]="photo.src" [alt]="photo.alt" />
</button>
}
```

`kuiMediaViewer()` must be called during an injection context (a component/directive constructor
or field initializer), exactly like `kuiDialog()`/`kuiConfirm()`/`kuiDrawer()`.

### Multi-select composition

A per-tile `input[type=checkbox][kuiCheckbox]` next to (not inside) the cover button is the
consumer's own composition, not a `kuiMediaViewer()` option:

```html
@for (photo of photos; track photo.id) {
<div style="position: relative">
  <button
    type="button"
    (click)="openPhotoAt($index)"
    [attr.aria-label]="'Open photo ' + ($index + 1)"
  >
    <img [src]="photo.src" [alt]="photo.alt" />
  </button>
  <input
    type="checkbox"
    kuiCheckbox
    [checked]="isSelected(photo.id)"
    (change)="toggleSelected(photo.id)"
    aria-label="Select photo"
  />
</div>
}
```

### Single photo, no gallery chrome

```ts
this.openViewer({ items: [{ src: '/photos/1.jpg', alt: 'Sunset over the bay' }] });
```

Just zoom and Close -- no counter, no Prev/Next, no thumbnail strip. `id` is optional here too
(defaults to `src`).

### Live index

```ts
this.openViewer({
  items: this.photos,
  index: 0,
  onIndexChange: (index) => this.lastViewedIndex.set(index),
});
```

`onIndexChange` fires once on open (with the clamped initial index) and again on every
prev/next/thumbnail/keyboard navigation while the lightbox stays open.

## Examples

Rendered at /components/media-viewer:

### basic-media-viewer-example

#### basic-media-viewer-example.html

```html
<div class="media-viewer-example">
  @for (photo of photos; track photo.id) {
    <button type="button" class="media-viewer-example__tile" (click)="openPhotoAt($index)">
      <img [src]="photo.src" [alt]="photo.alt" />
    </button>
  }
  <span>Last viewed index: {{ lastViewed() }}</span>
</div>
```

#### basic-media-viewer-example.ts

```ts
import { Component, signal } from '@angular/core';

import { kuiMediaViewer, type KuiMediaViewerItem } from '@kikita-labs/ui';

function photoSource(label: string, color: string): string {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="800"><rect width="1200" height="800" fill="${color}"/><text x="600" y="420" font-size="96" text-anchor="middle" fill="white" font-family="sans-serif">${label}</text></svg>`;

  return `data:image/svg+xml,${encodeURIComponent(svg)}`;
}

@Component({
  selector: 'app-basic-media-viewer-example',
  imports: [],
  templateUrl: './basic-media-viewer-example.html',
  styleUrl: './basic-media-viewer-example.scss',
})
export class BasicMediaViewerExample {
  protected readonly photos: readonly KuiMediaViewerItem[] = [
    { id: 'p1', src: photoSource('Sunset', '#f59e0b'), alt: 'Sunset over the bay' },
    { id: 'p2', src: photoSource('Skyline', '#6366f1'), alt: 'City skyline at night' },
    { id: 'p3', src: photoSource('Forest', '#10b981'), alt: 'Forest in the morning' },
    { id: 'p4', src: photoSource('Desert', '#ef4444'), alt: 'Dunes at noon' },
  ];
  protected readonly lastViewed = signal(0);
  private readonly openViewer = kuiMediaViewer();

  protected openPhotoAt(index: number): void {
    this.openViewer({
      items: this.photos,
      index,
      onIndexChange: (viewed) => this.lastViewed.set(viewed),
    });
  }
}
```

#### basic-media-viewer-example.scss

```scss
.media-viewer-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
}

.media-viewer-example__tile {
  display: block;
  padding: 0;
  border: 1px solid var(--kui-color-border);
  border-radius: var(--kui-radius-md, 8px);
  background: none;
  cursor: pointer;
  overflow: hidden;
}

.media-viewer-example__tile img {
  display: block;
  inline-size: 96px;
  block-size: 64px;
  object-fit: cover;
}
```

### media-viewer-single-example

#### media-viewer-single-example.html

```html
<div class="media-viewer-example">
  <button kuiButton type="button" (click)="open()">Open a single photo</button>
</div>
```

#### media-viewer-single-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, kuiMediaViewer } from '@kikita-labs/ui';

function photoSource(label: string, color: string): string {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="800"><rect width="1200" height="800" fill="${color}"/><text x="600" y="420" font-size="96" text-anchor="middle" fill="white" font-family="sans-serif">${label}</text></svg>`;

  return `data:image/svg+xml,${encodeURIComponent(svg)}`;
}

@Component({
  selector: 'app-media-viewer-single-example',
  imports: [KuiButton],
  templateUrl: './media-viewer-single-example.html',
  styleUrl: './media-viewer-single-example.scss',
})
export class MediaViewerSingleExample {
  private readonly openViewer = kuiMediaViewer();

  protected open(): void {
    this.openViewer({
      items: [{ src: photoSource('Single', '#0ea5e9'), alt: 'A single photo' }],
      maxZoom: 4,
      zoomStep: 1,
    });
  }
}
```

#### media-viewer-single-example.scss

```scss
.media-viewer-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
}

.media-viewer-example__tile {
  display: block;
  padding: 0;
  border: 1px solid var(--kui-color-border);
  border-radius: var(--kui-radius-md, 8px);
  background: none;
  cursor: pointer;
  overflow: hidden;
}

.media-viewer-example__tile img {
  display: block;
  inline-size: 96px;
  block-size: 64px;
  object-fit: cover;
}
```

### media-viewer-select-example

#### media-viewer-select-example.html

```html
<div class="media-viewer-example">
  @for (photo of photos; track photo.id) {
    <div class="media-viewer-example__cell">
      <button
        type="button"
        class="media-viewer-example__tile"
        [attr.aria-label]="'Open photo ' + ($index + 1)"
        (click)="openPhotoAt($index)"
      >
        <img [src]="photo.src" [alt]="photo.alt" />
      </button>
      <input
        type="checkbox"
        kuiCheckbox
        aria-label="Select photo"
        [checked]="isSelected(photo.id ?? photo.src)"
        (change)="toggle(photo.id ?? photo.src)"
      />
    </div>
  }
  <span>{{ selected().size }} selected</span>
</div>
```

#### media-viewer-select-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiCheckbox, kuiMediaViewer, type KuiMediaViewerItem } from '@kikita-labs/ui';

function photoSource(label: string, color: string): string {
  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="800"><rect width="1200" height="800" fill="${color}"/><text x="600" y="420" font-size="96" text-anchor="middle" fill="white" font-family="sans-serif">${label}</text></svg>`;

  return `data:image/svg+xml,${encodeURIComponent(svg)}`;
}

@Component({
  selector: 'app-media-viewer-select-example',
  imports: [KuiCheckbox],
  templateUrl: './media-viewer-select-example.html',
  styleUrl: './media-viewer-select-example.scss',
})
export class MediaViewerSelectExample {
  protected readonly photos: readonly KuiMediaViewerItem[] = [
    { id: 'p1', src: photoSource('Sunset', '#f59e0b'), alt: 'Sunset over the bay' },
    { id: 'p2', src: photoSource('Skyline', '#6366f1'), alt: 'City skyline at night' },
    { id: 'p3', src: photoSource('Forest', '#10b981'), alt: 'Forest in the morning' },
    { id: 'p4', src: photoSource('Desert', '#ef4444'), alt: 'Dunes at noon' },
  ];
  protected readonly selected = signal<ReadonlySet<string>>(new Set());
  private readonly openViewer = kuiMediaViewer();

  protected isSelected(id: string): boolean {
    return this.selected().has(id);
  }

  protected toggle(id: string): void {
    this.selected.update((current) => {
      const next = new Set(current);

      if (!next.delete(id)) {
        next.add(id);
      }

      return next;
    });
  }

  protected openPhotoAt(index: number): void {
    this.openViewer({ items: this.photos, index });
  }
}
```

#### media-viewer-select-example.scss

```scss
.media-viewer-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
  align-items: center;
}

.media-viewer-example__tile {
  display: block;
  padding: 0;
  border: 1px solid var(--kui-color-border);
  border-radius: var(--kui-radius-md, 8px);
  background: none;
  cursor: pointer;
  overflow: hidden;
}

.media-viewer-example__tile img {
  display: block;
  inline-size: 96px;
  block-size: 64px;
  object-fit: cover;
}

.media-viewer-example__cell {
  position: relative;
}

.media-viewer-example__cell input {
  position: absolute;
  inset-block-start: var(--kui-space-1, 4px);
  inset-inline-start: var(--kui-space-1, 4px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| kuiMediaViewer() | () => (data: KuiMediaViewerData) => Observable<void \| undefined> | - | Returns the opener. Call it in an injection context (a constructor or field initializer), like kuiDialog(). The Observable completes when the lightbox closes (Close, Escape or backdrop) and carries no value. |
| items | readonly KuiMediaViewerItem[] | - | Required. Photos to browse, at least one. A single item hides the counter, Prev, Next and the thumbnail strip, leaving zoom and Close. |
| index | number \| undefined | 0 | Index to open on, clamped to the valid range. |
| maxZoom | number \| undefined | 3 | Upper zoom bound. |
| zoomStep | number \| undefined | 0.5 | Zoom increment per Zoom in or Zoom out click and per wheel event. |
| ariaLabel | string \| undefined | mediaViewer.label message | Base accessible name of the lightbox (Photo viewer). The position, photo N of total, is appended automatically. |
| messages | Partial<KuiMediaViewerMessages> \| undefined | undefined | Text overrides for this viewer: name, zoom, close, previous, next, thumbnail, position and load error texts. They win over scoped and root messages. |
| onIndexChange | (index: number) => void | - | Called once on open with the clamped initial index and on every Prev, Next, thumbnail or keyboard navigation. |
| KuiMediaViewerItem.id | string \| undefined | src | Stable identifier for tracking and thumbnail keys. Pass it only when two items can share a src. |
| KuiMediaViewerItem.src | string | - | Image URL. The viewer never fetches or transforms it. |
| KuiMediaViewerItem.alt | string | - | Alt text. Required; pass an empty string explicitly for a decorative photo. |
| KuiDialogSize "fullscreen" | dialog size | - | The panel is a KuiDialog with the fullscreen size, which any dialog content may also request. |

## Accessibility

- The panel is `role="dialog"` + `aria-modal="true"` (from `KuiDialog`), `aria-labelledby`
  pointing at a visually-hidden `<h2>` reading "Photo viewer, photo N of total" for a gallery, or
  just "Photo viewer" (the `ariaLabel` alone) for a single photo.
- Focus trap, focus restore to the trigger element on close, and page scroll lock come from
  `KuiDialog`, not reimplemented here.
- The counter is `aria-live="polite"`, announced on navigation without reopening the dialog. Not
  rendered at all for a single photo -- "1 / 1" carries no information.
- Close/Prev/Next/Zoom in/Zoom out are `button[kuiIconButton]`; Prev/Next/Zoom in/Zoom out get
  native `disabled` at their bounds instead of only a dimmed appearance. Prev/Next are not rendered
  at all for a single photo, rather than shown permanently disabled.
- Every thumbnail is a real `<button>` with an `aria-label` ("Go to photo N of total") and
  `aria-current="true"` on the currently viewed one.

| Key             | Action                                                             |
| --------------- | ------------------------------------------------------------------ |
| Tab / Shift+Tab | Cycles focus inside the lightbox (trap from `KuiDialog`).          |
| Escape          | Closes the lightbox.                                               |
| Left / Right    | Previous / next photo. Does not wrap -- bounds disable the button. |
| Home / End      | First / last photo.                                                |
| Enter / Space   | Activates the focused button (native).                             |

## Playground

Available at /components/media-viewer/playground.

---

<!-- route: /components/menu -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/menu.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/menu.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Menu

> Anchored command menu with keyboard focus behavior.

- Status: available
- Route: /components/menu
- Package: @kikita-labs/ui@2.0.0
- Import: KuiMenu from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/menu.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<button kuiButton type="button" [kuiMenuFor]="actionsMenu">Actions</button>

<kui-menu #actionsMenu ariaLabel="Project actions">
  <button type="button" kuiMenuItem>
    <span class="kui-menu-item__label">Edit</span>
  </button>
  <button type="button" kuiMenuItem>
    <span class="kui-menu-item__label">Copy</span>
  </button>
  <hr kuiSeparator spacing="xs" />
  <button type="button" kuiMenuItem appearance="destructive">
    <span class="kui-menu-item__label">Delete</span>
  </button>
</kui-menu>
```

## Examples

Rendered at /components/menu:

### basic-menu-example

#### basic-menu-example.html

```html
<div class="basic-menu-example">
  <button kuiButton type="button" [kuiMenuFor]="actionsMenu">Actions</button>

  <kui-menu #actionsMenu ariaLabel="Project actions">
    <button type="button" kuiMenuItem>
      <span class="kui-menu-item__label">Edit</span>
    </button>
    <button type="button" kuiMenuItem>
      <span class="kui-menu-item__label">Copy</span>
    </button>
    <hr kuiSeparator spacing="xs" />
    <button type="button" kuiMenuItem appearance="destructive">
      <span class="kui-menu-item__label">Delete</span>
    </button>
  </kui-menu>
</div>
```

#### basic-menu-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiMenu, KuiMenuFor, KuiMenuItem, KuiSeparator } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-menu-example',
  imports: [KuiButton, KuiMenu, KuiMenuFor, KuiMenuItem, KuiSeparator],
  templateUrl: './basic-menu-example.html',
  styleUrl: './basic-menu-example.scss',
})
export class BasicMenuExample {}
```

#### basic-menu-example.scss

```scss
.basic-menu-example {
  display: flex;
  justify-content: center;
}
```

### menu-content-example

#### menu-content-example.html

```html
<div class="menu-content-example">
  <button kuiButton type="button" shape="outline" [kuiMenuFor]="rowMenu">Row actions</button>

  <kui-menu #rowMenu ariaLabel="Row actions" menuAlign="end" minWidth="220px">
    <div kuiMenuHeader>Project</div>
    <button type="button" kuiMenuItem>
      <span class="kui-menu-item__icon" aria-hidden="true">E</span>
      <span class="kui-menu-item__label">Rename</span>
      <span class="kui-menu-item__shortcut">F2</span>
    </button>
    <button type="button" kuiMenuItem>
      <span class="kui-menu-item__icon" aria-hidden="true">C</span>
      <span class="kui-menu-item__label">Copy link</span>
      <span class="kui-menu-item__shortcut">Ctrl C</span>
    </button>
    <hr kuiSeparator spacing="xs" />
    <button type="button" kuiMenuItem disabled>
      <span class="kui-menu-item__label">Archive</span>
    </button>
  </kui-menu>
</div>
```

#### menu-content-example.ts

```ts
import { Component } from '@angular/core';

import {
  KuiButton,
  KuiMenu,
  KuiMenuFor,
  KuiMenuHeader,
  KuiMenuItem,
  KuiSeparator,
} from '@kikita-labs/ui';

@Component({
  selector: 'app-menu-content-example',
  imports: [KuiButton, KuiMenu, KuiMenuFor, KuiMenuHeader, KuiMenuItem, KuiSeparator],
  templateUrl: './menu-content-example.html',
  styleUrl: './menu-content-example.scss',
})
export class MenuContentExample {}
```

#### menu-content-example.scss

```scss
.menu-content-example {
  display: flex;
  justify-content: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| ariaLabel | string \| undefined | undefined | Accessible name for the menu panel. Falls back to the menu.label message (Actions). |
| placement | 'top' \| 'bottom' \| 'left' \| 'right' \| undefined | undefined | Preferred side of the trigger the menu opens on. Falls back to defaults.menu.placement, then bottom. Auto-flips to the opposite side to fit the viewport. |
| menuAlign | 'start' \| 'end' \| undefined | undefined | Alignment along the trigger edge (defaults.menu.menuAlign, then start). For top/bottom placement, start is left-aligned and end is right-aligned. For left/right placement, start is top-aligned and end is bottom-aligned. |
| offset | number \| undefined | undefined | Pixel gap between the trigger and the menu panel. Falls back to defaults.menu.offset, then 4. A static numeric string is coerced. |
| minWidth | string \| null \| undefined | undefined | Optional minimum inline size, applied to the visible panel as well as its overlay pane. Falls back to defaults.menu.minWidth, then none. |
| [kuiMenuFor] | KuiMenu \| undefined | - | Wires a native trigger to a menu instance and manages trigger ARIA state. |
| kuiMenuHeader | - | - | Marks a non-interactive group heading inside the menu panel. Renders with role="presentation". |
| kuiSeparator | - | - | Native hr[kuiSeparator] divider between menu item groups. See the Separator page for spacing and appearance inputs. |
| kuiMenuItem.appearance | 'neutral' \| 'destructive' | 'neutral' | Visual treatment for an action item. Use destructive for dangerous actions. |
| kuiMenuItem.disabled | boolean | false | Prevents activation and applies disabled/aria-disabled semantics. Disabled items are skipped by keyboard navigation. |
| isOpen | WritableSignal<boolean> | false | Whether the menu is currently open. Read it from a template reference. |
| KuiMenuOptions | interface | - | Shape of defaults.menu: placement, offset, menuAlign and minWidth. |

## Accessibility

- The panel uses `role="menu"`.
- Items use `role="menuitem"`.
- Separators use native `hr[kuiSeparator]`.
- Group headers use `role="presentation"`.
- Disabled items expose `aria-disabled="true"`.
- `ArrowDown` / `ArrowUp` opens from the trigger and focuses first/last item.
- Inside the menu, `ArrowDown`, `ArrowUp`, `Home`, and `End` move focus.
- `Escape` closes the menu and returns focus to the trigger.
- `Tab` closes the menu and lets focus continue normally.
- When `prefers-reduced-motion: reduce` is active, closing completes without waiting for an exit
  animation.

## Playground

Available at /components/menu/playground.

---

<!-- route: /components/number-input -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/number-input.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/number-input.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Number Input

> Number input states with compact variant options.

- Status: available
- Route: /components/number-input
- Package: @kikita-labs/ui@2.0.0
- Import: KuiNumberInput from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/number-input.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<!-- Standalone -->
<input type="number" kuiNumberInput min="0" max="100" aria-label="Quantity" />

<!-- With ngModel -->
<input type="number" kuiNumberInput min="1" max="99" [(ngModel)]="qty" aria-label="Quantity" />

<!-- In a kui-field -->
<kui-field label="Count" hint="Enter a value from 1 to 100">
  <input type="number" kuiNumberInput min="1" max="100" [(ngModel)]="qty" />
</kui-field>
```

`split`, with minus/plus controls on the sides, is the default and recommended
for most use cases. `stacked` uses stacked arrows on the right and is more compact.

```html
<input type="number" kuiNumberInput variant="stacked" min="0" max="99" [(ngModel)]="qty" />
```

## Examples

Rendered at /components/number-input:

### basic-number-input-example

#### basic-number-input-example.html

```html
<input type="number" kuiNumberInput min="0" max="100" aria-label="Quantity" value="4" />
<input
  type="number"
  kuiNumberInput
  size="sm"
  min="0"
  max="10"
  aria-label="Small quantity"
  value="2"
/>
<input
  type="number"
  kuiNumberInput
  disabled
  min="0"
  max="10"
  aria-label="Disabled quantity"
  value="3"
/>
```

#### basic-number-input-example.ts

```ts
import { Component } from '@angular/core';

import { KuiNumberInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-number-input-example',
  imports: [KuiNumberInput],
  templateUrl: './basic-number-input-example.html',
  styleUrl: './basic-number-input-example.scss',
})
export class BasicNumberInputExample {}
```

#### basic-number-input-example.scss

```scss
:host {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
  align-items: center;
}
```

### compact-number-input-example

#### compact-number-input-example.html

```html
<input
  type="number"
  kuiNumberInput
  variant="stacked"
  min="0"
  max="99"
  aria-label="Compact quantity"
  value="12"
/>
<input
  type="number"
  kuiNumberInput
  variant="split"
  min="0"
  max="99"
  aria-label="Default quantity"
  value="12"
/>
```

#### compact-number-input-example.ts

```ts
import { Component } from '@angular/core';

import { KuiNumberInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-compact-number-input-example',
  imports: [KuiNumberInput],
  templateUrl: './compact-number-input-example.html',
  styleUrl: './compact-number-input-example.scss',
})
export class CompactNumberInputExample {}
```

#### compact-number-input-example.scss

```scss
:host {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
  align-items: center;
}
```

### field-number-input-example

#### field-number-input-example.html

```html
<kui-field label="Seats" hint="Choose between 1 and 10 seats">
  <input type="number" kuiNumberInput min="1" max="10" value="4" />
</kui-field>

<kui-field label="Discount" error="Discount must be at least 0%" required>
  <input type="number" kuiNumberInput invalid min="0" max="100" value="-5" />
</kui-field>
```

#### field-number-input-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiNumberInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-field-number-input-example',
  imports: [KuiField, KuiNumberInput],
  templateUrl: './field-number-input-example.html',
  styleUrl: './field-number-input-example.scss',
})
export class FieldNumberInputExample {}
```

#### field-number-input-example.scss

```scss
:host {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
  align-items: flex-start;
}
```

### range-number-input-example

#### range-number-input-example.html

```html
<input
  type="number"
  kuiNumberInput
  min="0"
  max="20"
  step="5"
  aria-label="Step of five"
  value="10"
/>
<input
  type="number"
  kuiNumberInput
  invalid
  min="1"
  max="10"
  aria-label="Invalid quantity"
  value="0"
/>
```

#### range-number-input-example.ts

```ts
import { Component } from '@angular/core';

import { KuiNumberInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-range-number-input-example',
  imports: [KuiNumberInput],
  templateUrl: './range-number-input-example.html',
  styleUrl: './range-number-input-example.scss',
})
export class RangeNumberInputExample {}
```

#### range-number-input-example.scss

```scss
:host {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-4, 16px);
  align-items: center;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Control height from --kui-control-height-*; generated buttons scale to match. Resolved from defaults.numberInput.size, then the parent field, then the global defaults.size, then md. |
| variant | 'stacked' \| 'split' \| undefined | undefined | Button layout. split places minus/plus controls on the sides (recommended); stacked stacks compact arrows on the right. Falls back to defaults.numberInput.variant, then split. |
| invalid | boolean | false | Applies an error border. Also inherited automatically from a parent kui-field with an error. |
| id | string \| undefined | - | Id override for the native input. Falls back to the parent kui-field control id. |
| min | string \| number | - | Native HTML attribute placed directly on the input. Decrement stops and disables at this value. |
| max | string \| number | - | Native HTML attribute placed directly on the input. Increment stops and disables at this value. |
| step | string \| number | 1 | Native HTML attribute. Amount the generated buttons and arrow keys step by. |
| disabled | boolean | false | Native HTML attribute. Sets data-kui-disabled on the container and disables both generated buttons. |
| readonly | boolean | false | Native HTML attribute. Sets data-kui-readonly on the container and disables both generated buttons. |
| --kui-input-bg | CSS custom property | Field | Shared control background color. |
| --kui-input-bg-disabled | CSS custom property | var(--kui-input-bg) | Shared background color used for disabled and readonly states. |
| --kui-number-input-border | CSS custom property | --kui-input-border | Optional number-input border override; falls back to the shared input border. |
| --kui-number-input-divider | CSS custom property | --kui-color-border | Divider color between the buttons and the native input. |
| --kui-number-input-btn-bg | CSS custom property | transparent | Generated button background in the default state. |
| --kui-number-input-btn-bg-hover | CSS custom property | --kui-color-surface-elevated | Generated button background on hover. |
| --kui-number-input-btn-text | CSS custom property | --kui-color-text-secondary | Generated button icon color. |
| KuiNumberInputOptions | interface | - | Shape of defaults.numberInput: size and variant. |

## Accessibility

- The native `input[type=number]` keeps its built-in keyboard and screen-reader semantics.
- Generated buttons use `aria-label="Decrease value"` and `aria-label="Increase value"`.
- Generated buttons use native `disabled` plus `aria-disabled="true"` when stepping is not available.
- Place the input inside `kui-field` to inherit label, hint, error, and id wiring.

## Playground

Available at /components/number-input/playground.

---

<!-- route: /components/otp-input -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/otp-input.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/otp-input.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# OTP Input

> Row of single-character cells for a one-time code or PIN.

- Status: available
- Route: /components/otp-input
- Package: @kikita-labs/ui@2.0.0
- Import: KuiOtpInput from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/otp-input.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-otp-input [(value)]="code" (complete)="verify($event)" autoFocus />
```

```ts
protected readonly code = signal('');

protected verify(code: string): void {
  // ...
}
```

`value` is the joined string of every cell's character, in cell order. `(complete)` fires exactly
once, with the completed value, the moment every cell becomes filled -- it does not re-fire while
the code stays complete, and fires again only after the code becomes incomplete and is refilled.

## Examples

Rendered at /components/otp-input:

### basic-otp-input-example

#### basic-otp-input-example.html

```html
<div class="otp-example">
  <kui-otp-input [(value)]="code" (complete)="verify($event)" />
  <span>Entered: {{ code() || 'nothing' }}. Completed: {{ verified() || 'not yet' }}</span>
</div>
```

#### basic-otp-input-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiOtpInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-otp-input-example',
  imports: [KuiOtpInput],
  templateUrl: './basic-otp-input-example.html',
  styleUrl: './basic-otp-input-example.scss',
})
export class BasicOtpInputExample {
  protected readonly code = signal('');
  protected readonly verified = signal('');

  protected verify(code: string): void {
    this.verified.set(code);
  }
}
```

#### basic-otp-input-example.scss

```scss
.otp-example {
  display: grid;
  gap: var(--kui-space-4, 16px);
  justify-items: start;
}
```

### otp-input-variants-example

#### otp-input-variants-example.html

```html
<div class="otp-example">
  <kui-otp-input mask [length]="4" [(value)]="pin" ariaLabel="PIN code" />
  <kui-otp-input
    [integerOnly]="false"
    [length]="8"
    size="sm"
    [(value)]="backupCode"
    ariaLabel="Backup code"
  />
</div>
```

#### otp-input-variants-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiOtpInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-otp-input-variants-example',
  imports: [KuiOtpInput],
  templateUrl: './otp-input-variants-example.html',
  styleUrl: './otp-input-variants-example.scss',
})
export class OtpInputVariantsExample {
  protected readonly pin = signal('');
  protected readonly backupCode = signal('');
}
```

#### otp-input-variants-example.scss

```scss
.otp-example {
  display: grid;
  gap: var(--kui-space-4, 16px);
  justify-items: start;
}
```

### otp-input-field-example

#### otp-input-field-example.html

```html
<div class="otp-example">
  <kui-field
    label="Code from email"
    hint="We sent a 6-digit code to your email. Try 123456."
    [error]="wrong() ? 'Code is wrong or expired' : ''"
  >
    <kui-otp-input [(value)]="code" [loading]="verifying()" [invalid]="wrong()" />
  </kui-field>
  <button kuiButton shape="outline" size="sm" type="button" (click)="toggleVerifying()">
    Toggle loading
  </button>
</div>
```

#### otp-input-field-example.ts

```ts
import { Component, computed, signal } from '@angular/core';

import { KuiButton, KuiField, KuiOtpInput } from '@kikita-labs/ui';

@Component({
  selector: 'app-otp-input-field-example',
  imports: [KuiButton, KuiField, KuiOtpInput],
  templateUrl: './otp-input-field-example.html',
  styleUrl: './otp-input-field-example.scss',
})
export class OtpInputFieldExample {
  protected readonly code = signal('');
  protected readonly verifying = signal(false);
  protected readonly wrong = computed(() => this.code().length === 6 && this.code() !== '123456');

  protected toggleVerifying(): void {
    this.verifying.update((value) => !value);
  }
}
```

#### otp-input-field-example.scss

```scss
.otp-example {
  display: grid;
  gap: var(--kui-space-4, 16px);
  justify-items: start;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| length | number | 6 | Number of cells. Static numeric values are coerced; an invalid or non-positive value uses 1. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Cell size, the same scale as Input. Falls back to defaults.otpInput.size, then the root size, then md. |
| mask | boolean \| undefined | undefined | Renders every cell as type="password" (defaults.otpInput.mask, then false). |
| integerOnly | boolean \| undefined | undefined | Restricts input to digits with a numeric mobile keyboard (defaults.otpInput.integerOnly, then true). false accepts letters and digits, uppercased. |
| autoFocus | boolean | false | Focuses the first cell that can take focus after the first render, and again on every false to true change. |
| ariaLabel | string \| undefined | undefined | Accessible name of the role="group" cell group. Falls back to the otpInput.label message (Verification code). |
| [(value)] | string | '' | Joined characters of every cell, in order. Set by [formField] or [(value)]. |
| disabled | boolean | false | Disables every cell with the native attribute. Set by [formField] or directly. |
| readonly | boolean | false | Makes every cell read-only and also blocks pasting a new code and the cross-cell Backspace clear. |
| required | boolean | false | Marks the code required: the first cell, which the field label points at, gets the native required state. Also follows a required ancestor kui-field. |
| loading | boolean | false | Disables every cell, blurs the code in place and shows a centered Loader without changing the group size. |
| invalid | boolean | false | Marks every cell invalid. Through [formField] the raw state is gated by touched before it shows. |
| errors | readonly ValidationError[] | [] | Current validation errors. Set by [formField]. |
| touched | boolean | false | Whether the control has been touched. Set by [formField]. |
| (touch) | void | - | Emitted after any cell edit; marks the control touched in the form system. |
| (complete) | string | - | Emitted once with the completed value when every cell becomes filled. It fires again only after the code became incomplete and was refilled. |
| focus(options?) | (options?: FocusOptions) => void | - | Moves focus to the first cell that can take focus, so focusBoundControl() works. Does nothing while every cell is disabled. |
| --kui-otp-gap / -cell-size / -cell-font-size / -loading-blur | CSS custom properties | - | Gap between cells, the square cell size, the digit font size and the loading blur (2px). |
| KuiOtpInputOptions | interface | - | Shape of defaults.otpInput: size, mask and integerOnly. |

## Accessibility

- The group is `role="group"` with an `aria-label` (default `"Verification code"`).
- Each cell is a plain `<input>` with its own `aria-label="Digit N of M"`.
- Keyboard:
  - Typing a valid character fills the cell and advances focus to the next empty cell.
  - `Backspace` on an already-empty cell clears and refocuses the previous cell (a non-empty cell
    just clears itself, native browser behavior).
  - `ArrowLeft`/`ArrowRight` move focus between cells without changing any value.
  - `Home`/`End` jump to the first/last cell.
  - `Tab`/`Shift+Tab` leave the whole group (arrow keys, not Tab, move between cells).
  - `Ctrl`/`Cmd+V` distributes a pasted code across cells starting at the first cell, regardless of
    which cell had focus.
- The first cell carries `autocomplete="one-time-code"` for WebOTP-based SMS autofill on iOS/
  Android.
- `invalid` is a plain manual input for standalone use; whether a code is wrong is normally a
  server response, which no client-side validator can know ahead of time. When bound through
  `[formField]`, Signal Forms writes its raw, untouched-gated validity into `invalid` (the same
  interop `input[kuiInput]` documents); `kui-otp-input` gates that specific case by `touched()`
  itself before showing it on the cells, so a required-but-empty code does not paint every cell red
  before the user has interacted with the group -- matching `kui-field`'s own gated error text.
- `readonly` blocks pasting a new code and blocks the cross-cell Backspace clear (the native
  `readonly` attribute alone only blocks a cell's own direct keystroke, not those two component-
  level behaviors, so both are guarded explicitly).
- Disabled/loading use the native `disabled` attribute on every cell, so they are excluded from the
  tab order, not merely dimmed.

## Playground

Available at /components/otp-input/playground.

---

<!-- route: /components/pagination -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/pagination.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/pagination.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Pagination

> Page navigation with numbers, steps, a summary and a rows-per-page picker.

- Status: available
- Route: /components/pagination
- Package: @kikita-labs/ui@2.0.0
- Import: KuiPagination from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/pagination.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-pagination [totalPages]="10" [(currentPage)]="page" />
```

```ts
protected readonly page = signal(1);
```

`currentPage` and `pageSize` are plain two-way bindings (`[(currentPage)]`, `[(pageSize)]`), not
`FormValueControl` -- pagination is page-level navigation state, not a form field value, so it is
never placed inside `kui-field`.

## Examples

Rendered at /components/pagination:

### basic-pagination-example

#### basic-pagination-example.html

```html
<div class="pagination-example">
  <kui-pagination ariaLabel="Project pages" [totalPages]="10" [(currentPage)]="page" />
  <span>Current page: {{ page() }}</span>
</div>
```

#### basic-pagination-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiPagination } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-pagination-example',
  imports: [KuiPagination],
  templateUrl: './basic-pagination-example.html',
  styleUrl: './basic-pagination-example.scss',
})
export class BasicPaginationExample {
  protected readonly page = signal(3);
}
```

#### basic-pagination-example.scss

```scss
.pagination-example {
  display: grid;
  gap: var(--kui-space-5, 20px);
  justify-items: start;
}
```

### pagination-variants-example

#### pagination-variants-example.html

```html
<div class="pagination-example">
  <kui-pagination
    ariaLabel="Simple pages"
    variant="simple"
    [totalPages]="12"
    [(currentPage)]="page"
  />
  <kui-pagination
    ariaLabel="Full pages"
    variant="full"
    [totalPages]="12"
    [totalItems]="289"
    [(currentPage)]="page"
    [(pageSize)]="pageSize"
  />
  <kui-pagination
    ariaLabel="Disabled pages"
    size="sm"
    [totalPages]="12"
    [(currentPage)]="page"
    disabled
  />
</div>
```

#### pagination-variants-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiPagination } from '@kikita-labs/ui';

@Component({
  selector: 'app-pagination-variants-example',
  imports: [KuiPagination],
  templateUrl: './pagination-variants-example.html',
  styleUrl: './pagination-variants-example.scss',
})
export class PaginationVariantsExample {
  protected readonly page = signal(2);
  protected readonly pageSize = signal(25);
}
```

#### pagination-variants-example.scss

```scss
.pagination-example {
  display: grid;
  gap: var(--kui-space-5, 20px);
  justify-items: start;
}
```

### pagination-window-example

#### pagination-window-example.html

```html
<div class="pagination-example">
  <kui-pagination
    ariaLabel="Wide window pages"
    [totalPages]="42"
    [siblingCount]="2"
    [boundaryCount]="1"
    [(currentPage)]="page"
  />
  <kui-pagination
    ariaLabel="Edge window pages"
    [totalPages]="42"
    [siblingCount]="0"
    [boundaryCount]="2"
    [(currentPage)]="page"
  />
</div>
```

#### pagination-window-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiPagination } from '@kikita-labs/ui';

@Component({
  selector: 'app-pagination-window-example',
  imports: [KuiPagination],
  templateUrl: './pagination-window-example.html',
  styleUrl: './pagination-window-example.scss',
})
export class PaginationWindowExample {
  protected readonly page = signal(20);
}
```

#### pagination-window-example.scss

```scss
.pagination-example {
  display: grid;
  gap: var(--kui-space-5, 20px);
  justify-items: start;
}
```

### pagination-table-example

#### pagination-table-example.html

```html
<div class="pagination-example">
  <table kuiTable [data]="pageRows()">
    <thead>
      <tr>
        <th kuiTh>Id</th>
        <th kuiTh>Name</th>
      </tr>
    </thead>
    <tbody>
      @for (row of pageRows(); track row.id) {
        <tr kuiRow [value]="row">
          <td kuiCell>{{ row.id }}</td>
          <td kuiCell>{{ row.name }}</td>
        </tr>
      }
    </tbody>
  </table>

  <kui-pagination
    ariaLabel="Table pages"
    variant="full"
    [totalPages]="totalPages()"
    [totalItems]="allRows.length"
    [pageSizeOptions]="[10, 20, 30]"
    [(currentPage)]="page"
    [(pageSize)]="pageSize"
  />
</div>
```

#### pagination-table-example.ts

```ts
import { Component, computed, signal } from '@angular/core';

import { KuiCell, KuiPagination, KuiRow, KuiTable, KuiTh } from '@kikita-labs/ui';

@Component({
  selector: 'app-pagination-table-example',
  imports: [KuiCell, KuiPagination, KuiRow, KuiTable, KuiTh],
  templateUrl: './pagination-table-example.html',
  styleUrl: './pagination-table-example.scss',
})
export class PaginationTableExample {
  protected readonly allRows = Array.from({ length: 60 }, (_, index) => ({
    id: index + 1,
    name: `Project ${index + 1}`,
  }));
  protected readonly page = signal(1);
  protected readonly pageSize = signal(10);
  protected readonly totalPages = computed(() =>
    Math.max(1, Math.ceil(this.allRows.length / this.pageSize())),
  );
  protected readonly pageRows = computed(() => {
    const start = (this.page() - 1) * this.pageSize();

    return this.allRows.slice(start, start + this.pageSize());
  });
}
```

#### pagination-table-example.scss

```scss
.pagination-example {
  display: grid;
  gap: var(--kui-space-5, 20px);
  justify-items: start;
}

table {
  inline-size: 100%;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| variant | 'full' \| 'compact' \| 'simple' \| undefined | undefined | Layout preset (defaults.pagination.variant, then compact). compact is First, Prev, numbers with ellipsis, Next and Last; simple is Prev, "Page X of Y" and Next; full adds the summary and the rows-per-page picker. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Control size on the Button scale. Falls back to the root defaults.size, then md. |
| totalPages | number | - | Required total page count. Static numeric values are coerced; an invalid or non-positive value uses 1. |
| [(currentPage)] | number | 1 | Current page, 1-based. A plain two-way model, not a form value, so pagination is never placed in kui-field. An out-of-range binding is clamped. |
| siblingCount | number \| undefined | undefined | Page numbers shown beside the current page before an ellipsis (defaults.pagination.siblingCount, then 1). |
| boundaryCount | number \| undefined | undefined | Page numbers always shown at each edge (defaults.pagination.boundaryCount, then 1). |
| [(pageSize)] | number | 25 | Rows per page, used by the full variant. Changing the picker sets pageSize and resets currentPage to 1 in the same update. |
| pageSizeOptions | readonly number[] \| undefined | undefined | Choices of the rows-per-page picker, full variant only (defaults.pagination.pageSizeOptions, then [10, 25, 50, 100]). |
| totalItems | number \| undefined | totalPages * pageSize | Total item count for the "Showing X-Y of Z" summary, full variant only. |
| disabled | boolean | false | Disables every control with the native attribute, removing them from the tab order. |
| ariaLabel | string \| undefined | undefined | Accessible name of the nav landmark. Falls back to the pagination.label message (Pagination). |
| messages | Partial<KuiPaginationMessages> \| undefined | undefined | Per-instance text overrides: button names, rowsPerPage, summary and page. They win over scoped and root messages. |
| (currentPageChange) | number | - | Emitted whenever currentPage changes (model output). |
| (pageSizeChange) | number | - | Emitted whenever pageSize changes (model output). |
| --kui-pagination-gap / -summary-gap / -ellipsis-color | CSS custom properties | - | Gap between the controls, gap between the summary row and the controls, and the ellipsis and secondary text colour. |
| --kui-pagination-page-min-size-{xs,sm,md,lg} / -page-size-width | CSS custom properties | - | Square size of the page-number buttons per size and the fixed width (76px) of the rows-per-page picker. |
| KuiPaginationOptions | interface | - | Shape of defaults.pagination: variant, siblingCount, boundaryCount, pageSizeOptions and the four step icons. |

## Accessibility

- The controls sit inside a `<nav>` landmark with `aria-label` (default: the `pagination.label` message, `"Pagination"`), a
  separate landmark from the page's own primary navigation.
- The current page gets both `aria-current="page"` and its own `aria-label`
  (`"Page N, current"`) -- state is not carried by `shape="solid"`/`appearance="primary"` color
  alone.
- First/Prev/Next/Last are `button[kuiIconButton]` with a required `aria-label`, no visible text.
- The ellipsis is `<span aria-hidden="true">`, excluded from both the accessibility tree and the
  tab order -- it is never a button.
- Range boundaries use the native `disabled` attribute on First/Prev (`currentPage === 1`) and
  Next/Last (`currentPage === totalPages`), which removes them from tab order, not just dims them.
- The `variant="full"` summary is `aria-live="polite"`, announcing the changed range without
  interrupting the user.
- Focus-visible is `Button`/`IconButton`'s own native focus ring -- nothing custom.
- There is no roving-tabindex/arrow-key navigation between controls -- every researched kit
  (PrimeNG, MUI, HeroUI) treats pagination as a set of independent buttons in normal tab order, not
  a single composite widget like a listbox, so arrow keys are never intercepted here either.

| Key               | Action                                                                                                           |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| `Tab`/`Shift+Tab` | Moves between every non-disabled control in visual order (First → Prev → numbers → Next → Last → rows-per-page). |
| `Enter`/`Space`   | Activates the focused page/step button.                                                                          |

## Playground

Available at /components/pagination/playground.

---

<!-- route: /components/popover -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/popover.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/popover.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Popover

> Anchored content surface for contextual UI.

- Status: available
- Route: /components/popover
- Package: @kikita-labs/ui@2.0.0
- Import: KuiPopover from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/popover.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<button [kuiPopoverFor]="myPop" kuiButton>Open</button>

<kui-popover #myPop placement="bottom" [arrow]="true" ariaLabel="Details">
  <div class="kui-popover-title">Title</div>
  <div class="kui-popover-desc">Supporting text.</div>
</kui-popover>
```

## Examples

Rendered at /components/popover:

### action-popover-example

#### action-popover-example.html

```html
<div class="action-popover-example">
  <button [kuiPopoverFor]="confirmPop" kuiButton type="button" appearance="danger">Delete</button>

  <kui-popover
    #confirmPop
    placement="bottom"
    align="start"
    [arrow]="true"
    ariaLabel="Delete record"
  >
    <div class="kui-popover-title">Delete record?</div>
    <div class="kui-popover-desc" style="margin-bottom: 12px">This cannot be undone.</div>
    <div style="display: flex; gap: 8px; justify-content: flex-end">
      <button kuiButton type="button" shape="outline" size="sm" (click)="confirmPop.close()">
        Cancel
      </button>
      <button
        kuiButton
        type="button"
        appearance="danger"
        size="sm"
        (click)="delete(); confirmPop.close()"
      >
        Delete
      </button>
    </div>
  </kui-popover>

  @if (deleted()) {
    <span class="action-popover-example__status">Record deleted.</span>
  }
</div>
```

#### action-popover-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiButton, KuiPopover, KuiPopoverFor } from '@kikita-labs/ui';

@Component({
  selector: 'app-action-popover-example',
  imports: [KuiButton, KuiPopover, KuiPopoverFor],
  templateUrl: './action-popover-example.html',
})
export class ActionPopoverExample {
  protected readonly deleted = signal(false);

  protected delete(): void {
    this.deleted.set(true);
  }
}
```

### basic-popover-example

#### basic-popover-example.html

```html
<div class="basic-popover-example">
  <button [kuiPopoverFor]="myPop" kuiButton type="button">Open</button>

  <kui-popover #myPop placement="bottom" [arrow]="true" ariaLabel="Details">
    <div class="kui-popover-title">Title</div>
    <div class="kui-popover-desc">Supporting text.</div>
  </kui-popover>
</div>
```

#### basic-popover-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiPopover, KuiPopoverFor } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-popover-example',
  imports: [KuiButton, KuiPopover, KuiPopoverFor],
  templateUrl: './basic-popover-example.html',
})
export class BasicPopoverExample {}
```

### hover-popover-example

#### hover-popover-example.html

```html
<div class="hover-popover-example">
  <button [kuiPopoverFor]="hoverPop" kuiButton type="button">Hover me</button>

  <kui-popover
    #hoverPop
    placement="top"
    triggerType="hover"
    [arrow]="true"
    ariaLabel="Hover details"
  >
    <div class="kui-popover-desc">Opens on hover. Mouse can travel to the panel.</div>
  </kui-popover>
</div>
```

#### hover-popover-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiPopover, KuiPopoverFor } from '@kikita-labs/ui';

@Component({
  selector: 'app-hover-popover-example',
  imports: [KuiButton, KuiPopover, KuiPopoverFor],
  templateUrl: './hover-popover-example.html',
})
export class HoverPopoverExample {}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| placement | 'top' \| 'bottom' \| 'left' \| 'right' \| undefined | undefined | Preferred side of the anchor (defaults.popover.placement, then bottom). Auto-flips to the opposite side to fit the viewport. |
| align | 'start' \| 'center' \| 'end' \| undefined | undefined | Alignment of the panel along the anchor edge (defaults.popover.align, then center). Preserved after a placement flip. |
| arrow | boolean \| undefined | undefined | Shows the arrow caret pointing to the anchor. Falls back to defaults.popover.arrow, then false. |
| triggerType | 'click' \| 'hover' \| undefined | undefined | Falls back to defaults.popover.triggerType, then click. click toggles the panel on click and closes on outside click or ESC. hover opens on mouseenter and closes on mouseleave. |
| ariaLabel | string \| undefined | undefined | Accessible name for the role="dialog" panel. Falls back to the popover.label message (Popover); prefer content-specific text. |
| hoverDelay | number \| undefined | undefined | Delay in ms before closing on mouseleave in hover mode (defaults.popover.hoverDelay, then 100). Lets the mouse travel from trigger to panel. |
| offset | number \| undefined | undefined | Gap in px between the anchor and the panel (defaults.popover.offset, then 8). The arrow adds 6px automatically. A static numeric string is coerced. |
| trapFocus | boolean | false | Traps focus inside the panel and auto-focuses the first focusable element on open. |
| open | boolean (model) | false | Current open state exposed for trigger integrations via openChange. Not intended as a standalone controlled API. |
| [kuiPopoverFor] | KuiPopover \| undefined | - | Wires any element as a trigger for a kui-popover. Sets aria-expanded and aria-haspopup="dialog" automatically. |
| .kui-popover-title | - | - | Optional CSS class for a semi-bold sm title inside the projected content. |
| .kui-popover-desc | - | - | Optional CSS class for secondary sm supporting text inside the projected content. |
| --kui-popover-bg | CSS custom property | var(--kui-color-surface-elevated) | Panel background. |
| --kui-popover-border | CSS custom property | var(--kui-color-border) | Panel border color. |
| --kui-popover-radius | CSS custom property | var(--kui-radius-lg) | Panel corner radius. |
| --kui-popover-shadow | CSS custom property | var(--kui-shadow-lg) | Panel drop shadow. |
| --kui-popover-padding-x | CSS custom property | var(--kui-space-4) | Panel horizontal padding. |
| --kui-popover-padding-y | CSS custom property | var(--kui-space-4) | Panel vertical padding. |
| --kui-popover-min-width | CSS custom property | 160px | Minimum panel width. |
| --kui-popover-max-width | CSS custom property | 320px | Maximum panel width. |
| --kui-popover-arrow-size | CSS custom property | 10px | Arrow caret size. |
| --kui-z-popover | CSS custom property | 400 | Panel z-index in browsers without the Popover API. |
| openFor(anchor) | (anchor: Element) => void | - | Opens the popover anchored to the given element. |
| toggleFor(anchor) | (anchor: Element) => void | - | Toggles the popover for a trigger and reopens immediately when an exit animation is running. |
| close() | () => void | - | Closes the popover with the exit animation. |
| scheduleClose(delay) | (delay: number) => void | - | Schedules a close after delay ms (hover mode). |
| cancelClose() | () => void | - | Cancels a pending scheduled close. |
| KuiPopoverOptions | interface | - | Shape of defaults.popover: placement, offset, align, arrow, triggerType and hoverDelay. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/popover/playground.

---

<!-- route: /components/progress -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/progress.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/progress.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Progress

> Progress status primitive for determinate and indeterminate work.

- Status: available
- Route: /components/progress
- Package: @kikita-labs/ui@2.0.0
- Import: KuiProgress from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/progress.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Examples

Rendered at /components/progress:

### basic-progress-example

#### basic-progress-example.html

```html
<div class="progress-example">
  <div class="progress-example__item">
    <span class="progress-example__label">Determinate (60%)</span>
    <kui-progress [value]="60" aria-label="Upload progress" />
  </div>
  <div class="progress-example__item">
    <span class="progress-example__label">Indeterminate</span>
    <kui-progress aria-label="Loading" />
  </div>
</div>
```

#### basic-progress-example.ts

```ts
import { Component } from '@angular/core';

import { KuiProgress } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-progress-example',
  imports: [KuiProgress],
  templateUrl: './basic-progress-example.html',
  styleUrl: './basic-progress-example.scss',
})
export class BasicProgressExample {}
```

#### basic-progress-example.scss

```scss
.progress-example {
  display: flex;
  flex-direction: column;
  gap: var(--kui-space-4, 16px);
  inline-size: 100%;
  max-inline-size: 360px;
}

.progress-example__item {
  display: flex;
  flex-direction: column;
  gap: var(--kui-space-2, 8px);
}

.progress-example__label {
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

### progress-circular-example

#### progress-circular-example.html

```html
<div class="progress-circular-example">
  <kui-progress type="circular" size="lg" color="success" [value]="72" aria-label="72% complete">
    72%
  </kui-progress>
  <kui-progress type="circular" aria-label="Loading" />
</div>
```

#### progress-circular-example.ts

```ts
import { Component } from '@angular/core';

import { KuiProgress } from '@kikita-labs/ui';

@Component({
  selector: 'app-progress-circular-example',
  imports: [KuiProgress],
  templateUrl: './progress-circular-example.html',
  styleUrl: './progress-circular-example.scss',
})
export class ProgressCircularExample {}
```

#### progress-circular-example.scss

```scss
.progress-circular-example {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  justify-content: center;
  gap: var(--kui-space-6, 24px);
}
```

### progress-color-size-example

#### progress-color-size-example.html

```html
<div class="progress-color-size-example">
  <div class="progress-color-size-example__group">
    <kui-progress size="xs" [value]="40" aria-label="Extra small progress" />
    <kui-progress size="sm" [value]="40" aria-label="Small progress" />
    <kui-progress size="md" [value]="40" aria-label="Medium progress" />
    <kui-progress size="lg" [value]="40" aria-label="Large progress" />
    <kui-progress size="xl" [value]="40" aria-label="Extra large progress" />
  </div>
  <div class="progress-color-size-example__group">
    <kui-progress color="primary" [value]="55" aria-label="Primary progress" />
    <kui-progress color="success" [value]="55" aria-label="Success progress" />
    <kui-progress color="warning" [value]="55" aria-label="Warning progress" />
    <kui-progress color="danger" [value]="55" aria-label="Danger progress" />
    <kui-progress color="neutral" [value]="55" aria-label="Neutral progress" />
  </div>
</div>
```

#### progress-color-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiProgress } from '@kikita-labs/ui';

@Component({
  selector: 'app-progress-color-size-example',
  imports: [KuiProgress],
  templateUrl: './progress-color-size-example.html',
  styleUrl: './progress-color-size-example.scss',
})
export class ProgressColorSizeExample {}
```

#### progress-color-size-example.scss

```scss
.progress-color-size-example {
  display: flex;
  flex-direction: column;
  gap: var(--kui-space-5, 20px);
  inline-size: 100%;
  max-inline-size: 360px;
}

.progress-color-size-example__group {
  display: flex;
  flex-direction: column;
  gap: var(--kui-space-3, 12px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| type | 'linear' \| 'circular' | 'linear' | Progress shape. |
| value | number \| null | null | Progress value from 0 to 100. Values are clamped visually. A static numeric attribute is coerced; null or an invalid value renders the indeterminate animation. |
| color | 'primary' \| 'success' \| 'warning' \| 'danger' \| 'neutral' \| undefined | undefined | Semantic color of the filled part. Falls back to defaults.progress.color, then primary. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| undefined | undefined | Linear thickness or circular diameter. Falls back to defaults.progress.size, then the root size default, then md. |
| content projection | text \| template | - | Projected content is rendered centered inside circular progress. |
| KuiProgressOptions | interface | - | Shape of defaults.progress: size and color. |

## Accessibility

The host uses `role="progressbar"`, `aria-valuemin="0"`, and
`aria-valuemax="100"`. Determinate progress also sets `aria-valuenow`.

Always provide an accessible name with `aria-label` or `aria-labelledby`.

## Playground

Available at /components/progress/playground.

---

<!-- route: /components/radio -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/radio.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/radio.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Radio

> Native radio control styling for exclusive choices.

- Status: available
- Route: /components/radio
- Package: @kikita-labs/ui@2.0.0
- Import: KuiRadio from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/radio.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-field label="Plan" hint="Choose a billing plan">
  <div role="radiogroup">
    <label>
      <input kuiRadio type="radio" name="plan" value="starter" />
      Starter
    </label>
    <label>
      <input kuiRadio type="radio" name="plan" value="pro" />
      Pro
    </label>
  </div>
</kui-field>
```

Use a shared native `name` for mutually exclusive radio choices. Use `kui-field` for the
field-level label, hint, error, and description wiring; keep native labels for each option.

## Examples

Rendered at /components/radio:

### basic-radio-example

#### basic-radio-example.html

```html
<kui-field label="Plan" hint="Choose a billing plan">
  <div role="radiogroup" class="radio-group" aria-label="Plan">
    <label class="radio-option">
      <input
        kuiRadio
        type="radio"
        name="plan"
        value="starter"
        [checked]="plan() === 'starter'"
        (change)="plan.set('starter')"
      />
      <span>Starter</span>
    </label>
    <label class="radio-option">
      <input
        kuiRadio
        type="radio"
        name="plan"
        value="pro"
        [checked]="plan() === 'pro'"
        (change)="plan.set('pro')"
      />
      <span>Pro</span>
    </label>
  </div>
</kui-field>
```

#### basic-radio-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiField, KuiRadio } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-radio-example',
  imports: [KuiField, KuiRadio],
  templateUrl: './basic-radio-example.html',
  styleUrl: './basic-radio-example.scss',
})
export class BasicRadioExample {
  protected readonly plan = signal('starter');
}
```

#### basic-radio-example.scss

```scss
:host {
  display: block;
  inline-size: min(100%, 360px);
}

.radio-group {
  display: grid;
  gap: var(--kui-space-2, 8px);
}

.radio-option {
  display: inline-flex;
  align-items: center;
  gap: var(--kui-space-2, 8px);
  color: var(--kui-color-text);
}
```

### radio-disabled-example

#### radio-disabled-example.html

```html
<div role="radiogroup" class="radio-group" aria-label="Delivery speed">
  <label class="radio-option">
    <input kuiRadio type="radio" name="delivery" value="standard" checked />
    <span>Standard</span>
  </label>
  <label class="radio-option">
    <input kuiRadio type="radio" name="delivery" value="express" />
    <span>Express</span>
  </label>
  <label class="radio-option radio-option--disabled">
    <input kuiRadio type="radio" name="delivery" value="same-day" disabled />
    <span>Same day (unavailable in this region)</span>
  </label>
</div>
```

#### radio-disabled-example.ts

```ts
import { Component } from '@angular/core';

import { KuiRadio } from '@kikita-labs/ui';

@Component({
  selector: 'app-radio-disabled-example',
  imports: [KuiRadio],
  templateUrl: './radio-disabled-example.html',
  styleUrl: './radio-disabled-example.scss',
})
export class RadioDisabledExample {}
```

#### radio-disabled-example.scss

```scss
.radio-group {
  display: grid;
  gap: var(--kui-space-2, 8px);
}

.radio-option {
  display: inline-flex;
  align-items: center;
  gap: var(--kui-space-2, 8px);
  color: var(--kui-color-text);
}

.radio-option--disabled {
  color: var(--kui-color-text-secondary);
}
```

### radio-invalid-example

#### radio-invalid-example.html

```html
<kui-field label="Payment method" error="Select a payment method to continue" required>
  <div role="radiogroup" class="radio-group" aria-label="Payment method">
    <label class="radio-option">
      <input kuiRadio type="radio" name="payment" value="card" />
      <span>Card</span>
    </label>
    <label class="radio-option">
      <input kuiRadio type="radio" name="payment" value="bank-transfer" />
      <span>Bank transfer</span>
    </label>
  </div>
</kui-field>
```

#### radio-invalid-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiRadio } from '@kikita-labs/ui';

@Component({
  selector: 'app-radio-invalid-example',
  imports: [KuiField, KuiRadio],
  templateUrl: './radio-invalid-example.html',
  styleUrl: './radio-invalid-example.scss',
})
export class RadioInvalidExample {}
```

#### radio-invalid-example.scss

```scss
:host {
  display: block;
  inline-size: min(100%, 360px);
}

.radio-group {
  display: grid;
  gap: var(--kui-space-2, 8px);
}

.radio-option {
  display: inline-flex;
  align-items: center;
  gap: var(--kui-space-2, 8px);
  color: var(--kui-color-text);
}
```

### radio-size-example

#### radio-size-example.html

```html
<div class="radio-size-example">
  <label class="radio-option">
    <input kuiRadio type="radio" name="radio-size-xs" size="xs" checked />
    <span>Extra small</span>
  </label>
  <label class="radio-option">
    <input kuiRadio type="radio" name="radio-size-sm" size="sm" checked />
    <span>Small</span>
  </label>
  <label class="radio-option">
    <input kuiRadio type="radio" name="radio-size-md" size="md" checked />
    <span>Medium</span>
  </label>
  <label class="radio-option">
    <input kuiRadio type="radio" name="radio-size-lg" size="lg" checked />
    <span>Large</span>
  </label>
</div>
```

#### radio-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiRadio } from '@kikita-labs/ui';

@Component({
  selector: 'app-radio-size-example',
  imports: [KuiRadio],
  templateUrl: './radio-size-example.html',
  styleUrl: './radio-size-example.scss',
})
export class RadioSizeExample {}
```

#### radio-size-example.scss

```scss
.radio-size-example {
  display: grid;
  gap: var(--kui-space-3, 12px);
  justify-content: center;
}

.radio-option {
  display: inline-flex;
  align-items: center;
  gap: var(--kui-space-2, 8px);
  color: var(--kui-color-text);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Radio size mapped to Kikita radio tokens. Resolved from defaults.radio.size, then the parent field, then the global defaults.size, then md. |
| invalid | boolean | false | Marks the radio invalid outside a kui-field error state. With [formField] the Field state wins. |
| id | string \| undefined | undefined | Explicit id override. Inside kui-field, the field id is used when omitted. |
| KuiRadioOptions | interface | - | Shape of defaults.radio: size. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/radio/playground.

---

<!-- route: /components/scatter-chart -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/scatter-chart.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/chart.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Scatter Chart

> Scatter and bubble chart for two numeric measures.

- Status: available
- Route: /components/scatter-chart
- Package: @kikita-labs/ui@2.0.0
- Import: KuiScatterChart from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/chart.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-line-chart ariaLabel="Sessions per day" [series]="series" [categories]="categories" />
```

```ts
protected readonly series: readonly KuiChartCartesianSeries[] = [
  { id: 'sessions', name: 'Sessions', data: [120, 180, 150, 220, 260, 210, 300] },
];
protected readonly categories = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
```

`ariaLabel` has a chart-type fallback name and should describe what the chart shows. It is distinct
from each point's own `aria-label` (its value).

## Examples

Rendered at /components/scatter-chart:

### basic-scatter-chart-example

#### basic-scatter-chart-example.html

```html
<div class="chart-example">
  <kui-scatter-chart ariaLabel="Age vs. income" [series]="series" [axes]="axes" />
</div>
```

#### basic-scatter-chart-example.ts

```ts
import { Component } from '@angular/core';

import {
  type KuiChartAxesOptions,
  type KuiChartScatterSeries,
  KuiScatterChart,
} from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-scatter-chart-example',
  imports: [KuiScatterChart],
  templateUrl: './basic-scatter-chart-example.html',
  styleUrl: './basic-scatter-chart-example.scss',
})
export class BasicScatterChartExample {
  protected readonly series: readonly KuiChartScatterSeries[] = [
    {
      id: 'free',
      name: 'Free plan',
      points: [
        { x: 22, y: 32000 },
        { x: 29, y: 41000 },
        { x: 35, y: 52000 },
        { x: 41, y: 61000 },
      ],
    },
    {
      id: 'pro',
      name: 'Pro plan',
      points: [
        { x: 26, y: 48000 },
        { x: 33, y: 67000 },
        { x: 44, y: 82000 },
        { x: 52, y: 95000 },
      ],
    },
  ];
  protected readonly axes: KuiChartAxesOptions = { xTitle: 'Age', yTitle: 'Income (USD)' };
}
```

#### basic-scatter-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### scatter-bubble-chart-example

#### scatter-bubble-chart-example.html

```html
<div class="chart-example">
  <kui-scatter-chart
    ariaLabel="Accounts by age, income and seats"
    [series]="series"
    [bubble]="true"
  />
</div>
```

#### scatter-bubble-chart-example.ts

```ts
import { Component } from '@angular/core';

import { type KuiChartScatterSeries, KuiScatterChart } from '@kikita-labs/ui';

@Component({
  selector: 'app-scatter-bubble-chart-example',
  imports: [KuiScatterChart],
  templateUrl: './scatter-bubble-chart-example.html',
  styleUrl: './scatter-bubble-chart-example.scss',
})
export class ScatterBubbleChartExample {
  protected readonly series: readonly KuiChartScatterSeries[] = [
    {
      id: 'accounts',
      name: 'Accounts',
      points: [
        { x: 22, y: 32000, r: 6 },
        { x: 29, y: 41000, r: 9 },
        { x: 35, y: 52000, r: 7 },
        { x: 41, y: 61000, r: 14 },
      ],
    },
  ];
}
```

#### scatter-bubble-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

### scatter-states-chart-example

#### scatter-states-chart-example.html

```html
<div class="chart-example chart-example--stack">
  <kui-scatter-chart ariaLabel="Loading accounts" [series]="series" [loading]="true" size="sm" />
  <kui-scatter-chart ariaLabel="Empty accounts" [series]="[]" size="sm" />
</div>
```

#### scatter-states-chart-example.ts

```ts
import { Component } from '@angular/core';

import { type KuiChartScatterSeries, KuiScatterChart } from '@kikita-labs/ui';

@Component({
  selector: 'app-scatter-states-chart-example',
  imports: [KuiScatterChart],
  templateUrl: './scatter-states-chart-example.html',
  styleUrl: './scatter-states-chart-example.scss',
})
export class ScatterStatesChartExample {
  protected readonly series: readonly KuiChartScatterSeries[] = [
    {
      id: 'accounts',
      name: 'Accounts',
      points: [
        { x: 22, y: 32000 },
        { x: 41, y: 61000 },
      ],
    },
  ];
}
```

#### scatter-states-chart-example.scss

```scss
.chart-example {
  inline-size: 100%;
  min-inline-size: 0;
}

.chart-example--stack {
  display: grid;
  gap: var(--kui-space-6, 24px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| series | readonly KuiChartScatterSeries[] | - | Required. { id?, name, color?, points: { x, y, r? }[] }. A point with a non-finite x, y or r is dropped. Without a point the empty composition renders. |
| bubble | boolean | false | Reads r from each point as the radius in CSS pixels. It is not clamped; the consumer owns a radius that fits the plot. |

## Accessibility

- The `<svg>` is the graphic: `role="graphics-document"` with the name and the role description
  (`aria-roledescription`). The wrapper has no role, and axis text, gridlines and decorative shapes
  are `aria-hidden`.
- Each point/bar/slice is `role="graphics-symbol img"` with its own `aria-label` (the same text as
  the tooltip) -- an indivisible graphical unit, per the WAI-ARIA Graphics Module.
- Roving tabindex across points/bars/slices (see Keyboard). The inline legend is a named group of
  native `<button aria-pressed>` items at least 24px high.
- The tooltip shown on hover is the same one shown on keyboard focus (one shared overlay, retargeted
  between marks). It is dismissible and persistent. On pointer hover it appears at the pointer and follows
  it; keyboard focus anchors it to the focused mark. On touch, a tap pins the tooltip open until an
  outside tap, `Escape`, or a tap on a different mark; it also always renders below 768px, since it is
  the primary way to read a chart's exact value.
- Pointer hit targets: a line chart shows the tooltip while the pointer is on the point (its marker plus a
  3px margin), a scatter chart on the point's hit circle (at least 12px in radius), a bar chart on the bar
  itself and a donut on the slice.
- Text is at least 12px on screen: axis text defaults to 13px and keeps its pixel size at any width.
- `prefers-reduced-motion: reduce` disables the hover/dim transition and the donut sweep.
- The alt-table is a real accessible alternative to the graphic, not a decorative duplicate.

Automated checks (keyboard, accessibility tree, axe, forced-colours media emulation, reduced motion)
are in `chart-contract.spec.ts` and `accessibility.spec.ts`. A session with a real screen reader has
not been run and stays pending.

## Playground

Available at /components/scatter-chart/playground.

---

<!-- route: /components/scrollbar -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/scrollbar.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/scrollbar.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Scrollbar

> Tokenized native scroll container utility.

- Status: available
- Route: /components/scrollbar
- Package: @kikita-labs/ui@2.0.0
- Import: .kui-scroll from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/scrollbar.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

For application-wide scrollbar styling, enable the provider option once:

```ts
import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig = {
  providers: [provideKikitaUi({ scrollbars: 'styled' })],
};
```

This sets `data-kui-scrollbars="styled"` on the document root and styles native scrollbars for application-owned scroll containers.

The default is `scrollbars: 'native'` for application-owned scroll containers. Kikita-owned internal scroll areas, such as dropdown, dialog body, drawer body, and command palette list, still use Kikita scrollbar tokens automatically.

Use `kui-scroll` only for local opt-in when you do not want global application scrollbar styling:

```html
<div class="kui-scroll" tabindex="0" style="max-block-size: 240px; overflow: auto">
  <p>Scrollable content...</p>
  <p>Scrollable content...</p>
  <p>Scrollable content...</p>
</div>
```

Apply the class to the element that actually scrolls. Do not apply it to a child wrapper that has no overflow.

## Examples

Rendered at /components/scrollbar:

### local-scroll-container-example

#### local-scroll-container-example.html

```html
<div class="kui-scroll local-scroll-container-example__region" tabindex="0">
  <p>First paragraph of scrollable content.</p>
  <p>Second paragraph of scrollable content.</p>
  <p>Third paragraph of scrollable content.</p>
  <p>Fourth paragraph of scrollable content.</p>
  <p>Fifth paragraph of scrollable content.</p>
</div>
```

#### local-scroll-container-example.ts

```ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-local-scroll-container-example',
  templateUrl: './local-scroll-container-example.html',
  styleUrl: './local-scroll-container-example.scss',
})
export class LocalScrollContainerExample {}
```

#### local-scroll-container-example.scss

```scss
.local-scroll-container-example__region {
  max-block-size: 160px;
  overflow: auto;
  padding-inline-end: var(--kui-space-2, 8px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| .kui-scroll | CSS class | - | Local opt-in for Kikita scrollbar token styling. Apply to the element that actually scrolls (the one with overflow: auto/scroll set), not a non-scrolling wrapper. |
| provideKikitaUi({ scrollbars }) | KuiScrollbarMode = 'native' \| 'styled' | 'native' | App-wide scrollbar mode for application-owned scroll containers. Sets data-kui-scrollbars on the document root. Kikita-owned internal scroll areas (dropdown, dialog body, drawer body, command palette list) use Kikita scrollbar tokens automatically regardless of this option. |
| --kui-scrollbar-size | CSS custom property | - | Scrollbar thickness. |
| --kui-scrollbar-radius | CSS custom property | - | Corner radius of the scrollbar thumb. |
| --kui-scrollbar-track | CSS custom property | - | Scrollbar track background color. |
| --kui-scrollbar-thumb-min | CSS custom property | - | Minimum thumb length so short thumbs stay grabbable. |
| --kui-scrollbar-thumb-inset | CSS custom property | - | Inset spacing between the thumb and the track edge. |
| --kui-color-scrollbar-thumb | CSS custom property | - | Thumb color in the resting state. |
| --kui-color-scrollbar-thumb-hover | CSS custom property | - | Thumb color on hover. |
| --kui-color-scrollbar-thumb-active | CSS custom property | - | Thumb color while being dragged. |

## Accessibility

- The utility keeps native browser scrolling behavior.
- Add `tabindex="0"` on the scrollable element itself so keyboard users can focus and scroll it (WCAG 2.1.1 / axe `scrollable-region-focusable`). CSS alone cannot make an overflow container focusable.
- Do not add ARIA roles only to style a scrollbar.
- Keyboard scrolling, touch scrolling, and assistive-technology behavior remain owned by the native scroll container.
- In forced-colors mode, scrollbar colors fall back to the system implementation.
- Browser and OS scrollbar rendering can differ, especially with overlay scrollbars.

## Playground

No playground for this component.

---

<!-- route: /components/segmented -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/segmented.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/segmented.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Segmented

> Compact single-choice control rendered as adjacent segment buttons.

- Status: available
- Route: /components/segmented
- Package: @kikita-labs/ui@2.0.0
- Import: KuiSegmented from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/segmented.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-segmented [(value)]="view">
  <button kuiSegment value="list">List</button>
  <button kuiSegment value="grid">Grid</button>
  <button kuiSegment value="calendar">Calendar</button>
</kui-segmented>
```

### Sizes

```html
<kui-segmented size="sm" [(value)]="view">...</kui-segmented>
```

### Signal Forms

`kui-segmented` implements `FormValueControl<string>`, so it takes `[formField]` directly
(it is not a native element, so `[formField]` goes on `kui-segmented` itself, not on `kui-field`):

```html
<kui-field label="View">
  <kui-segmented [formField]="myForm.view">
    <button kuiSegment value="list">List</button>
    <button kuiSegment value="grid">Grid</button>
  </kui-segmented>
</kui-field>
```

## Examples

Rendered at /components/segmented:

### basic-segmented-example

#### basic-segmented-example.html

```html
<div class="basic-segmented-example">
  <kui-segmented [(value)]="view" aria-label="Project view">
    <button kuiSegment value="list">List</button>
    <button kuiSegment value="board">Board</button>
    <button kuiSegment value="timeline">Timeline</button>
  </kui-segmented>

  <p>Selected view: {{ view() }}</p>
</div>
```

#### basic-segmented-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiSegment, KuiSegmented } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-segmented-example',
  imports: [KuiSegment, KuiSegmented],
  templateUrl: './basic-segmented-example.html',
  styleUrl: './basic-segmented-example.scss',
})
export class BasicSegmentedExample {
  protected readonly view = signal('list');
}
```

#### basic-segmented-example.scss

```scss
.basic-segmented-example {
  display: grid;
  gap: var(--kui-space-3, 12px);
  justify-items: center;
}

.basic-segmented-example p {
  margin: 0;
  color: var(--kui-color-text-muted);
  font-size: var(--kui-font-size-sm);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| [(value)] | string | '' | Selected segment value. Implements FormValueControl for [formField] integration, or bind directly for standalone use. |
| [(selected)] | string | '' | Deprecated alias for value, kept in sync with it. Use value instead; planned for removal in the next major version. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Control height and spacing for the whole segmented group. Falls back to defaults.segmented.size, then the global defaults.size, then md. |
| disabled | boolean | false | Disables every segment. Set by [formField] or directly. |
| invalid | boolean | false | Marks the control as having validation errors. Set by [formField]. |
| errors | readonly WithOptionalFieldTree<ValidationError>[] | [] | Current validation errors. Set by [formField]. |
| touched | boolean | false | Whether the control has been touched. Set by [formField]. |
| (touch) | void | - | Emitted whenever an enabled segment is selected, including one that was already selected; marks the control as touched in the form system. Focus and blur alone do not emit it. |
| button[kuiSegment].value | string | '' | Value emitted when the segment is selected. |
| button[kuiSegment].disabled | boolean | false | Disables one segment and removes it from keyboard selection. |
| focus(options?) | (options?: FocusOptions) => void | - | Focuses the selected segment, or the first enabled one when nothing is selected, so Signal Forms focusBoundControl() reaches the control. Does nothing while every segment is disabled. |
| required | - | - | Not available: a segmented control always shows one active segment, so it exposes no required state. |
| KuiSegmentedOptions | interface | - | Shape of defaults.segmented: size. |

## Accessibility

- `role="radiogroup"` on `kui-segmented`
- `role="radio"` and `aria-checked` on each segment
- Roving `tabindex`

## Playground

Available at /components/segmented/playground.

---

<!-- route: /components/select -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/select.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/select.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Select

> Dropdown-backed selection control for single and multiple values.

- Status: available
- Route: /components/select
- Package: @kikita-labs/ui@2.0.0
- Import: KuiSelect from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/select.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-field label="Role">
  <input kuiSelect [(value)]="role" placeholder="Select a role..." />
  <kui-dropdown>
    <div kuiOption value="engineer">Software Engineer</div>
    <div kuiOption value="designer">Designer</div>
  </kui-dropdown>
</kui-field>
```

```ts
role = signal<string | null>(null);
```

## Examples

Rendered at /components/select:

### basic-select-example

#### basic-select-example.html

```html
<kui-field label="Role" hint="Pick one role for the user">
  <input kuiSelect [(value)]="role" placeholder="Select a role..." [clearable]="true" />
  <kui-dropdown>
    <div kuiOption value="engineer">Software Engineer</div>
    <div kuiOption value="designer">Designer</div>
    <div kuiOption value="manager">Product Manager</div>
  </kui-dropdown>
</kui-field>
```

#### basic-select-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiDropdown, KuiField, KuiOption, KuiSelect } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-select-example',
  imports: [KuiDropdown, KuiField, KuiOption, KuiSelect],
  templateUrl: './basic-select-example.html',
  styleUrl: './basic-select-example.scss',
})
export class BasicSelectExample {
  protected readonly role = signal<string | null>(null);
}
```

#### basic-select-example.scss

```scss
:host {
  display: block;
  inline-size: min(100%, 360px);
}
```

### multiple-select-example

#### multiple-select-example.html

```html
<kui-field label="Roles" hint="Multiple mode renders selected values as chips">
  <input
    kuiSelect
    multiple
    [(value)]="roles"
    [kuiLabelFn]="roleLabel"
    [maxVisibleChips]="3"
    placeholder="Select roles..."
    [clearable]="true"
  />
  <kui-dropdown>
    @for (role of roleOptions; track role.value) {
      <div kuiOption [value]="role.value">{{ role.label }}</div>
    }
  </kui-dropdown>
</kui-field>
```

#### multiple-select-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiDropdown, KuiField, KuiOption, KuiSelect } from '@kikita-labs/ui';

interface RoleOption {
  readonly label: string;
  readonly value: string;
}

@Component({
  selector: 'app-multiple-select-example',
  imports: [KuiDropdown, KuiField, KuiOption, KuiSelect],
  templateUrl: './multiple-select-example.html',
  styleUrl: './multiple-select-example.scss',
})
export class MultipleSelectExample {
  protected readonly roles = signal<readonly string[]>(['engineer']);

  protected readonly roleOptions: readonly RoleOption[] = [
    { label: 'Software Engineer', value: 'engineer' },
    { label: 'Designer', value: 'designer' },
    { label: 'Product Manager', value: 'manager' },
    { label: 'Support Lead', value: 'support' },
  ];

  protected readonly roleLabel = (value: string): string =>
    this.roleOptions.find((role) => role.value === value)?.label ?? value;
}
```

#### multiple-select-example.scss

```scss
:host {
  display: block;
  inline-size: min(100%, 420px);
}
```

### object-value-select-example

#### object-value-select-example.html

```html
<kui-field label="Role" hint="Object values are shown through kuiLabelFn">
  <input kuiSelect [(value)]="role" [kuiLabelFn]="roleLabel" placeholder="Select a role..." />
  <kui-dropdown>
    @for (role of roles; track role.id) {
      <div kuiOption [value]="role">{{ role.label }}</div>
    }
  </kui-dropdown>
</kui-field>
```

#### object-value-select-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiDropdown, KuiField, KuiOption, KuiSelect } from '@kikita-labs/ui';

interface Role {
  readonly id: number;
  readonly label: string;
}

@Component({
  selector: 'app-object-value-select-example',
  imports: [KuiDropdown, KuiField, KuiOption, KuiSelect],
  templateUrl: './object-value-select-example.html',
  styleUrl: './object-value-select-example.scss',
})
export class ObjectValueSelectExample {
  protected readonly roles: readonly Role[] = [
    { id: 1, label: 'Software Engineer' },
    { id: 2, label: 'Designer' },
    { id: 3, label: 'Product Manager' },
  ];

  protected readonly role = signal<Role | null>(this.roles[0] ?? null);

  protected readonly roleLabel = (role: Role): string => role.label;
}
```

#### object-value-select-example.scss

```scss

```

### custom-value-select-example

#### custom-value-select-example.html

```html
<kui-field label="Roles" hint="A kuiSelectValue template replaces the default chip">
  <input kuiSelect multiple [(value)]="roles" [kuiLabelFn]="roleLabel" />

  <ng-template kuiSelectValue let-label="label" let-remove="remove">
    <span kuiChip appearance="primary" size="sm">
      <span class="kui-chip-label">{{ label }}</span>
      <button kuiChipRemove type="button" [attr.aria-label]="'Remove ' + label" (click)="remove()">
        x
      </button>
    </span>
  </ng-template>

  <kui-dropdown>
    @for (role of roleOptions; track role.value) {
      <div kuiOption [value]="role.value">{{ role.label }}</div>
    }
  </kui-dropdown>
</kui-field>
```

#### custom-value-select-example.ts

```ts
import { Component, signal } from '@angular/core';

import {
  KuiChip,
  KuiChipRemove,
  KuiDropdown,
  KuiField,
  KuiOption,
  KuiSelect,
  KuiSelectValue,
} from '@kikita-labs/ui';

interface RoleOption {
  readonly label: string;
  readonly value: string;
}

@Component({
  selector: 'app-custom-value-select-example',
  imports: [KuiChip, KuiChipRemove, KuiDropdown, KuiField, KuiOption, KuiSelect, KuiSelectValue],
  templateUrl: './custom-value-select-example.html',
  styleUrl: './custom-value-select-example.scss',
})
export class CustomValueSelectExample {
  protected readonly roles = signal<readonly string[]>(['engineer', 'designer']);

  protected readonly roleOptions: readonly RoleOption[] = [
    { label: 'Software Engineer', value: 'engineer' },
    { label: 'Designer', value: 'designer' },
    { label: 'Product Manager', value: 'manager' },
  ];

  protected readonly roleLabel = (value: string): string =>
    this.roleOptions.find((role) => role.value === value)?.label ?? value;
}
```

#### custom-value-select-example.scss

```scss

```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| value | T \| readonly T[] \| null | - | Selected value. In multiple mode this is an array. |
| disabled | boolean | - | Disables the native input and prevents opening the dropdown. |
| readonly | boolean | - | Prevents opening the dropdown while keeping the field visually enabled. |
| invalid | boolean | - | Validation state set by Signal Forms or direct input binding. |
| errors | ValidationError[] | - | Validation errors consumed by kui-field for automatic error text. |
| touched | boolean | - | Touched state set by Signal Forms. |
| id | string | - | Explicit id override. Inside kui-field, the field id is used when omitted. |
| multiple | boolean | - | Enables array values and keeps the dropdown open on option selection. |
| maxVisibleChips | number \| undefined | - | Maximum selected chips shown before collapsed +N overflow. Falls back to defaults.select.maxVisibleChips, then 3. |
| multipleDisplay | 'chips' \| 'text' | - | Renders multiple selections as field chips or plain joined text. |
| multipleTextFn | (items: readonly T[]) => string | - | Formats native input text when multipleDisplay is text. |
| kuiLabelFn | (item: T) => string | - | Maps selected object values to display text. |
| placeholder | string | - | Placeholder on the readonly input. |
| clearable | boolean \| undefined | - | Shows a clear button when a value is selected. Resolved as local input, defaults.select.clearable, defaults.field.clearable, then false. |
| touch | output | - | Emitted after an opened dropdown closes for Signal Forms support. |
| ng-template[kuiSelectValue] | context: { $implicit: T; label: string; remove: () => void } | - | Replaces the default chip for each visible selected item in multiple mode. Call remove from a native button to make the item removable. |
| KuiSelectOptions | interface | - | Shape of defaults.select: clearable, multipleDisplay, maxVisibleChips, chevronIcon and clearIcon. |

## Accessibility

- The input uses `role="combobox"`, `aria-haspopup="listbox"`, and `aria-expanded`.
- The dropdown panel uses `role="listbox"`.
- Each `kuiOption` uses `role="option"`, `aria-selected`, and `aria-disabled`.
- The clear button is a native button with `aria-label="Clear"`.
- Multiple selected values render removable chip buttons inside the field.
- Custom selected value templates receive `item`, `label`, and `remove` context values.
- `maxVisibleChips` is count-based. It does not currently auto-measure field width.
- Use `kui-field` for label, hint, error, `aria-describedby`, and `aria-invalid` wiring.

## Playground

Available at /components/select/playground.

---

<!-- route: /components/separator -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/separator.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/separator.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Separator

> Tokenized horizontal or vertical separator primitive.

- Status: available
- Route: /components/separator
- Package: @kikita-labs/ui@2.0.0
- Import: KuiSeparator from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/separator.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<section>
  <p>Account details</p>
  <hr kuiSeparator />
  <p>Billing details</p>
</section>
```

Use the native `<hr>` host. Do not use a `div` for purely visual separators
unless a future primitive explicitly supports it.

## Examples

Rendered at /components/separator:

### basic-separator-example

#### basic-separator-example.html

```html
<section>
  <p>Account details</p>
  <hr kuiSeparator />
  <p>Billing details</p>
</section>
```

#### basic-separator-example.ts

```ts
import { Component } from '@angular/core';

import { KuiSeparator } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-separator-example',
  imports: [KuiSeparator],
  templateUrl: './basic-separator-example.html',
  styleUrl: './basic-separator-example.scss',
})
export class BasicSeparatorExample {}
```

#### basic-separator-example.scss

```scss
:host {
  display: block;
  max-inline-size: 320px;
}
```

### separator-appearance-example

#### separator-appearance-example.html

```html
<p>Subtle</p>
<hr kuiSeparator appearance="subtle" />
<p>Default</p>
<hr kuiSeparator appearance="default" />
<p>Strong</p>
<hr kuiSeparator appearance="strong" />
```

#### separator-appearance-example.ts

```ts
import { Component } from '@angular/core';

import { KuiSeparator } from '@kikita-labs/ui';

@Component({
  selector: 'app-separator-appearance-example',
  imports: [KuiSeparator],
  templateUrl: './separator-appearance-example.html',
  styleUrl: './separator-appearance-example.scss',
})
export class SeparatorAppearanceExample {}
```

#### separator-appearance-example.scss

```scss
:host {
  display: block;
  max-inline-size: 320px;
}

p {
  margin: 0;
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

### separator-spacing-example

#### separator-spacing-example.html

```html
<p>none</p>
<hr kuiSeparator spacing="none" />
<p>xs</p>
<hr kuiSeparator spacing="xs" />
<p>sm</p>
<hr kuiSeparator spacing="sm" />
<p>md</p>
<hr kuiSeparator spacing="md" />
<p>lg</p>
<hr kuiSeparator spacing="lg" />
```

#### separator-spacing-example.ts

```ts
import { Component } from '@angular/core';

import { KuiSeparator } from '@kikita-labs/ui';

@Component({
  selector: 'app-separator-spacing-example',
  imports: [KuiSeparator],
  templateUrl: './separator-spacing-example.html',
  styleUrl: './separator-spacing-example.scss',
})
export class SeparatorSpacingExample {}
```

#### separator-spacing-example.scss

```scss
:host {
  display: block;
  max-inline-size: 320px;
}

p {
  margin: 0;
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

### separator-vertical-example

#### separator-vertical-example.html

```html
<div class="separator-vertical-example__toolbar">
  <button kuiButton type="button" shape="ghost">Bold</button>
  <button kuiButton type="button" shape="ghost">Italic</button>
  <hr kuiSeparator orientation="vertical" spacing="xs" />
  <button kuiButton type="button" shape="ghost">Link</button>
</div>
```

#### separator-vertical-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiSeparator } from '@kikita-labs/ui';

@Component({
  selector: 'app-separator-vertical-example',
  imports: [KuiButton, KuiSeparator],
  templateUrl: './separator-vertical-example.html',
  styleUrl: './separator-vertical-example.scss',
})
export class SeparatorVerticalExample {}
```

#### separator-vertical-example.scss

```scss
.separator-vertical-example__toolbar {
  display: flex;
  align-items: center;
  gap: var(--kui-space-2, 8px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| appearance | 'subtle' \| 'default' \| 'strong' \| undefined | undefined | Visual divider emphasis. Falls back to defaults.separator.appearance, then default. |
| orientation | 'horizontal' \| 'vertical' \| undefined | undefined | Divider direction (defaults.separator.orientation, then horizontal). Vertical separators set aria-orientation="vertical" and stretch to the parent block size. |
| spacing | 'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Outer spacing around the divider line. Falls back to defaults.separator.spacing, then sm. |
| KuiSeparatorOptions | interface | - | Shape of defaults.separator: appearance, orientation and spacing. |

## Accessibility

- Prefer native `<hr kuiSeparator>`.
- The separator is not focusable and has no hover, focus, active, or disabled
  states.
- Vertical separators expose `aria-orientation="vertical"`.
- Do not add labels by default; named separators should be rare structural
  boundaries.

## Playground

Available at /components/separator/playground.

---

<!-- route: /components/skeleton -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/skeleton.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/skeleton.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Skeleton

> Loading placeholder with reduced-motion behavior.

- Status: available
- Route: /components/skeleton
- Package: @kikita-labs/ui@2.0.0
- Import: KuiSkeleton from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/skeleton.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<section aria-busy="true">
  <span kuiSkeleton shape="heading" style="inline-size: 180px"></span>
  <span kuiSkeleton shape="text" style="inline-size: 80%"></span>
  <span kuiSkeleton shape="button" style="inline-size: 96px"></span>
</section>
```

Skeleton hosts are automatically `aria-hidden="true"`. Put `aria-busy="true"` on the loading
region, not on every skeleton block.

## Examples

Rendered at /components/skeleton:

### skeleton-animation-example

#### skeleton-animation-example.html

```html
<div class="skeleton-animation-example">
  <div class="skeleton-animation-example__stack">
    <span kuiSkeleton shape="heading" style="inline-size: 60%"></span>
    <span kuiSkeleton shape="text" style="inline-size: 100%"></span>
    <span kuiSkeleton shape="text" style="inline-size: 80%"></span>
    <code>shimmer (default)</code>
  </div>
  <div class="skeleton-animation-example__stack">
    <span kuiSkeleton shape="heading" animation="pulse" style="inline-size: 60%"></span>
    <span kuiSkeleton shape="text" animation="pulse" style="inline-size: 100%"></span>
    <span kuiSkeleton shape="text" animation="pulse" style="inline-size: 80%"></span>
    <code>pulse</code>
  </div>
  <div class="skeleton-animation-example__stack">
    <span kuiSkeleton shape="heading" animation="none" style="inline-size: 60%"></span>
    <span kuiSkeleton shape="text" animation="none" style="inline-size: 100%"></span>
    <span kuiSkeleton shape="text" animation="none" style="inline-size: 80%"></span>
    <code>none</code>
  </div>
</div>
```

#### skeleton-animation-example.ts

```ts
import { Component } from '@angular/core';

import { KuiSkeleton } from '@kikita-labs/ui';

@Component({
  selector: 'app-skeleton-animation-example',
  imports: [KuiSkeleton],
  templateUrl: './skeleton-animation-example.html',
  styleUrl: './skeleton-animation-example.scss',
})
export class SkeletonAnimationExample {}
```

#### skeleton-animation-example.scss

```scss
.skeleton-animation-example {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
  gap: var(--kui-space-6, 24px);
}

.skeleton-animation-example__stack {
  display: grid;
  gap: var(--kui-space-2, 8px);
  align-content: start;
}

.skeleton-animation-example__stack code {
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

### skeleton-composition-example

#### skeleton-composition-example.html

```html
<article kuiCard class="skeleton-composition-example" aria-busy="true">
  <div class="skeleton-composition-example__row">
    <span kuiSkeleton shape="circle" style="inline-size: 40px"></span>
    <div class="skeleton-composition-example__stack">
      <span kuiSkeleton shape="heading" style="inline-size: 45%"></span>
      <span kuiSkeleton shape="text" style="inline-size: 70%"></span>
    </div>
  </div>

  <div class="skeleton-composition-example__stack">
    <span kuiSkeleton shape="text" style="inline-size: 100%"></span>
    <span kuiSkeleton shape="text" style="inline-size: 88%"></span>
    <span kuiSkeleton shape="text" style="inline-size: 64%"></span>
  </div>

  <span kuiSkeleton shape="button" style="inline-size: 100%"></span>
</article>
```

#### skeleton-composition-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCard, KuiSkeleton } from '@kikita-labs/ui';

@Component({
  selector: 'app-skeleton-composition-example',
  imports: [KuiCard, KuiSkeleton],
  templateUrl: './skeleton-composition-example.html',
  styleUrl: './skeleton-composition-example.scss',
})
export class SkeletonCompositionExample {}
```

#### skeleton-composition-example.scss

```scss
.skeleton-composition-example {
  display: grid;
  gap: var(--kui-space-4, 16px);
  max-inline-size: 320px;
}

.skeleton-composition-example__row {
  display: flex;
  align-items: center;
  gap: var(--kui-space-3, 12px);
}

.skeleton-composition-example__stack {
  display: grid;
  gap: var(--kui-space-2, 8px);
  inline-size: 100%;
}
```

### skeleton-shapes-example

#### skeleton-shapes-example.html

```html
<div class="skeleton-shapes-example">
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="text" style="inline-size: 140px"></span>
    <code>text</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="heading" style="inline-size: 180px"></span>
    <code>heading</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="rect" style="inline-size: 140px; block-size: 64px"></span>
    <code>rect</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="circle" style="inline-size: 40px"></span>
    <code>circle</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="square" style="inline-size: 40px"></span>
    <code>square</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="button" style="inline-size: 96px"></span>
    <code>button</code>
  </div>
  <div class="skeleton-shapes-example__item">
    <span kuiSkeleton shape="badge" style="inline-size: 64px"></span>
    <code>badge</code>
  </div>
</div>
```

#### skeleton-shapes-example.ts

```ts
import { Component } from '@angular/core';

import { KuiSkeleton } from '@kikita-labs/ui';

@Component({
  selector: 'app-skeleton-shapes-example',
  imports: [KuiSkeleton],
  templateUrl: './skeleton-shapes-example.html',
  styleUrl: './skeleton-shapes-example.scss',
})
export class SkeletonShapesExample {}
```

#### skeleton-shapes-example.scss

```scss
.skeleton-shapes-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-6, 24px);
}

.skeleton-shapes-example__item {
  display: grid;
  gap: var(--kui-space-2, 8px);
  justify-items: start;
}

.skeleton-shapes-example__item code {
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| shape | 'text' \| 'heading' \| 'rect' \| 'circle' \| 'square' \| 'button' \| 'badge' \| undefined | undefined | Placeholder shape mapped to Kikita UI skeleton geometry tokens. Falls back to defaults.skeleton.shape, then rect. |
| animation | 'shimmer' \| 'pulse' \| 'none' \| undefined | undefined | Placeholder animation mode (defaults.skeleton.animation, then shimmer). Automatically disabled when the user prefers reduced motion, regardless of this value. |
| KuiSkeletonOptions | interface | - | Shape of defaults.skeleton: shape and animation. |

## Accessibility

- Skeleton is decorative placeholder chrome and must not expose text to assistive technology.
- Do not make skeleton hosts focusable or interactive.
- Use Loader instead when the UI needs an announced loading status.
- Respect `prefers-reduced-motion`; Kikita disables skeleton animation under reduced motion.

## Playground

Available at /components/skeleton/playground.

---

<!-- route: /components/slider -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/slider.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/slider.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Slider

> Native range input styling with field and Signal Forms support.

- Status: available
- Route: /components/slider
- Package: @kikita-labs/ui@2.0.0
- Import: KuiSlider from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/slider.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-field label="Volume" hint="Use arrow keys, Home, and End.">
  <input type="range" kuiSlider min="0" max="100" value="60" />
</kui-field>
```

Use native range input semantics first. For visible labels and helper text, prefer a wrapping
`kui-field` instead of hand-written labels or description ids.
When projected inside `kui-field`, `kuiSlider` inherits the field id, `aria-describedby`,
`aria-invalid`, and visual invalid state.

```html
<input
  type="range"
  kuiSlider
  color="success"
  size="lg"
  minLabel="0"
  maxLabel="100"
  aria-label="Progress"
/>
```

## Examples

Rendered at /components/slider:

### basic-slider-example

#### basic-slider-example.html

```html
<div class="basic-slider-example">
  <kui-field label="Volume" hint="Use arrow keys, Home, and End.">
    <input type="range" kuiSlider min="0" max="100" value="60" />
  </kui-field>

  <input
    type="range"
    kuiSlider
    color="success"
    size="lg"
    min="0"
    max="100"
    value="40"
    minLabel="0"
    maxLabel="100"
    aria-label="Progress"
  />
</div>
```

#### basic-slider-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiSlider } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-slider-example',
  imports: [KuiField, KuiSlider],
  templateUrl: './basic-slider-example.html',
  styleUrl: './basic-slider-example.scss',
})
export class BasicSliderExample {}
```

#### basic-slider-example.scss

```scss
.basic-slider-example {
  display: grid;
  gap: var(--kui-space-6, 24px);
  inline-size: 100%;
  max-inline-size: 360px;
}
```

### slider-disabled-example

#### slider-disabled-example.html

```html
<div class="slider-disabled-example">
  <kui-field label="Storage limit" hint="Disabled until a plan is selected.">
    <input type="range" kuiSlider min="0" max="100" value="25" disabled />
  </kui-field>

  <input type="range" kuiSlider min="0" max="100" value="70" invalid aria-label="Invalid slider" />
</div>
```

#### slider-disabled-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiSlider } from '@kikita-labs/ui';

@Component({
  selector: 'app-slider-disabled-example',
  imports: [KuiField, KuiSlider],
  templateUrl: './slider-disabled-example.html',
  styleUrl: './slider-disabled-example.scss',
})
export class SliderDisabledExample {}
```

#### slider-disabled-example.scss

```scss
.slider-disabled-example {
  display: grid;
  gap: var(--kui-space-6, 24px);
  inline-size: 100%;
  max-inline-size: 360px;
}
```

### slider-field-example

#### slider-field-example.html

```html
<div class="slider-field-example">
  <kui-field label="Volume" hint="Signal Forms native range binding">
    <input type="range" kuiSlider [formField]="settingsForm.volume" />
  </kui-field>
</div>
```

#### slider-field-example.ts

```ts
import { Component, signal } from '@angular/core';
import { form, FormField, max, min } from '@angular/forms/signals';

import { KuiField, KuiSlider } from '@kikita-labs/ui';

interface SettingsModel {
  readonly volume: number;
}

@Component({
  selector: 'app-slider-field-example',
  imports: [FormField, KuiField, KuiSlider],
  templateUrl: './slider-field-example.html',
  styleUrl: './slider-field-example.scss',
})
export class SliderFieldExample {
  private readonly settingsModel = signal<SettingsModel>({ volume: 60 });

  protected readonly settingsForm = form(this.settingsModel, (path) => {
    min(path.volume, 0);
    max(path.volume, 100);
  });
}
```

#### slider-field-example.scss

```scss
.slider-field-example {
  display: grid;
  gap: var(--kui-space-6, 24px);
  inline-size: 100%;
  max-inline-size: 360px;
}
```

### slider-range-example

#### slider-range-example.html

```html
<div class="slider-range-example">
  <kui-field label="Playback speed" hint="min 0.5, max 2, step 0.25">
    <input
      type="range"
      kuiSlider
      min="0.5"
      max="2"
      step="0.25"
      value="1"
      minLabel="0.5x"
      maxLabel="2x"
    />
  </kui-field>

  <kui-field label="Rating" hint="min 1, max 5, step 1">
    <input type="range" kuiSlider min="1" max="5" step="1" value="3" minLabel="1" maxLabel="5" />
  </kui-field>
</div>
```

#### slider-range-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiSlider } from '@kikita-labs/ui';

@Component({
  selector: 'app-slider-range-example',
  imports: [KuiField, KuiSlider],
  templateUrl: './slider-range-example.html',
  styleUrl: './slider-range-example.scss',
})
export class SliderRangeExample {}
```

#### slider-range-example.scss

```scss
.slider-range-example {
  display: grid;
  gap: var(--kui-space-6, 24px);
  inline-size: 100%;
  max-inline-size: 360px;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| kuiSlider | directive | - | Selector input[type=range][kuiSlider]. Applies Kikita UI slider styling and behavior to a native range input. |
| color | 'primary' \| 'success' \| 'danger' \| 'neutral' \| undefined | undefined | Semantic color applied to the generated slider fill and thumb. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | undefined | Visual size of the generated slider control. |
| minLabel | string | '' | Optional label rendered below the minimum side of the track. |
| maxLabel | string | '' | Optional label rendered below the maximum side of the track. |
| disabled | boolean | false | Mirrors disabled styling on the generated slider wrapper. |
| invalid | boolean | false | Applies invalid styling outside a kui-field error state. |
| id | string \| undefined | - | Explicit native input id. Falls back to the parent kui-field control id. |
| min / max / step / value | native attributes | - | Native range input attributes. kuiSlider reads them directly; use them (or Signal Forms min/max validators) instead of a directive input. |
| kuiTooltip | string | - | When set to a non-empty string on the same host, the static tooltip text wins over the default value tooltip. Otherwise kuiSlider shows the current numeric value in a tooltip on hover. |
| [formField] | FieldTree<number> (from @angular/forms/signals) | - | Angular Signal Forms binding. Owns native value, disabled, and validation state; kuiSlider keeps the generated track and thumb visuals in sync. Do not add native min/max alongside formField; use the min(...) and max(...) schema validators instead. |
| KuiSliderOptions | interface | - | Shape of defaults.slider: size and color. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/slider/playground.

---

<!-- route: /components/splitter -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/splitter.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/splitter.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Splitter

> Draggable multi-pane layout with resizable gutters.

- Status: available
- Route: /components/splitter
- Package: @kikita-labs/ui@2.0.0
- Import: KuiSplitter from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/splitter.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-splitter orientation="horizontal" (sizesChange)="onResize($event)">
  <kui-splitter-pane size="30" [minSize]="15" [collapsible]="true">
    <app-file-tree />
  </kui-splitter-pane>
  <kui-splitter-pane size="70" [minSize]="30">
    <app-editor />
  </kui-splitter-pane>
</kui-splitter>
```

```ts
protected onResize(sizes: readonly number[]): void {
  // sizes[i] is the percentage width/height of pane i
}
```

`size` on `kui-splitter-pane` is only the initial/requested share -- `kui-splitter` owns the live
size from then on (drag and keyboard both write back into it). Panes without an explicit `size`
split the remaining space evenly among themselves, the same way flex items without an explicit
basis share leftover space.

## Examples

Rendered at /components/splitter:

### basic-splitter-example

#### basic-splitter-example.html

```html
<div class="splitter-example">
  <kui-splitter (sizesChange)="onResize($event)">
    <kui-splitter-pane [size]="30" [minSize]="15" [collapsible]="true">
      <div class="splitter-example__pane">Files</div>
    </kui-splitter-pane>
    <kui-splitter-pane [size]="70" [minSize]="30">
      <div class="splitter-example__pane">Editor</div>
    </kui-splitter-pane>
  </kui-splitter>
</div>
<p>Sizes: {{ sizes().join(' / ') }}</p>
```

#### basic-splitter-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiSplitter, KuiSplitterPane } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-splitter-example',
  imports: [KuiSplitter, KuiSplitterPane],
  templateUrl: './basic-splitter-example.html',
  styleUrl: './basic-splitter-example.scss',
})
export class BasicSplitterExample {
  protected readonly sizes = signal<readonly number[]>([30, 70]);

  protected onResize(sizes: readonly number[]): void {
    this.sizes.set(sizes);
  }
}
```

#### basic-splitter-example.scss

```scss
.splitter-example {
  block-size: 220px;
  inline-size: 100%;
}

.splitter-example__pane {
  display: grid;
  place-items: center;
  block-size: 100%;
  padding: var(--kui-space-3, 12px);
  color: var(--kui-color-text);
}
```

### splitter-nested-example

#### splitter-nested-example.html

```html
<div class="splitter-example">
  <kui-splitter orientation="vertical">
    <kui-splitter-pane>
      <kui-splitter orientation="horizontal">
        <kui-splitter-pane [size]="25">
          <div class="splitter-example__pane">Tree</div>
        </kui-splitter-pane>
        <kui-splitter-pane [size]="75">
          <div class="splitter-example__pane">Editor</div>
        </kui-splitter-pane>
      </kui-splitter>
    </kui-splitter-pane>
    <kui-splitter-pane [size]="30" [minSize]="10" [collapsible]="true">
      <div class="splitter-example__pane">Terminal</div>
    </kui-splitter-pane>
  </kui-splitter>
</div>
```

#### splitter-nested-example.ts

```ts
import { Component } from '@angular/core';

import { KuiSplitter, KuiSplitterPane } from '@kikita-labs/ui';

@Component({
  selector: 'app-splitter-nested-example',
  imports: [KuiSplitter, KuiSplitterPane],
  templateUrl: './splitter-nested-example.html',
  styleUrl: './splitter-nested-example.scss',
})
export class SplitterNestedExample {}
```

#### splitter-nested-example.scss

```scss
.splitter-example {
  block-size: 300px;
  inline-size: 100%;
}

.splitter-example__pane {
  display: grid;
  place-items: center;
  block-size: 100%;
  padding: var(--kui-space-3, 12px);
  color: var(--kui-color-text);
}
```

### splitter-multiple-example

#### splitter-multiple-example.html

```html
<div class="splitter-example">
  <kui-splitter>
    <kui-splitter-pane [size]="20">
      <div class="splitter-example__pane">One</div>
    </kui-splitter-pane>
    <kui-splitter-pane>
      <div class="splitter-example__pane">Two</div>
    </kui-splitter-pane>
    <kui-splitter-pane>
      <div class="splitter-example__pane">Three</div>
    </kui-splitter-pane>
  </kui-splitter>
</div>
<div class="splitter-example">
  <kui-splitter [disabled]="true">
    <kui-splitter-pane>
      <div class="splitter-example__pane">Locked one</div>
    </kui-splitter-pane>
    <kui-splitter-pane>
      <div class="splitter-example__pane">Locked two</div>
    </kui-splitter-pane>
  </kui-splitter>
</div>
```

#### splitter-multiple-example.ts

```ts
import { Component } from '@angular/core';

import { KuiSplitter, KuiSplitterPane } from '@kikita-labs/ui';

@Component({
  selector: 'app-splitter-multiple-example',
  imports: [KuiSplitter, KuiSplitterPane],
  templateUrl: './splitter-multiple-example.html',
  styleUrl: './splitter-multiple-example.scss',
})
export class SplitterMultipleExample {}
```

#### splitter-multiple-example.scss

```scss
.splitter-example {
  block-size: 220px;
  inline-size: 100%;
}

.splitter-example__pane {
  display: grid;
  place-items: center;
  block-size: 100%;
  padding: var(--kui-space-3, 12px);
  color: var(--kui-color-text);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| kui-splitter orientation | 'horizontal' \| 'vertical' \| undefined | undefined | Pane layout direction (defaults.splitter.orientation, then horizontal). Horizontal puts the panes side by side with a vertical gutter line. |
| kui-splitter disabled | boolean | false | Disables every gutter: aria-disabled, tabindex -1, and no drag or keyboard resize. Pane content stays interactive. |
| (sizesChange) | readonly number[] | - | Emitted with the full sizes array, in percent, on every drag or keyboard resize. |
| kui-splitter-pane size | number \| undefined | undefined | Initial or requested share in percent. The splitter owns the live size afterwards. Panes without a size split the remaining space evenly. |
| kui-splitter-pane minSize | number \| undefined | undefined | Minimum share in percent, clamped to 0-100 (defaults.splitter.minSize, then 10). Drag and keyboard resizing clamp to it; invalid static values use 10. |
| kui-splitter-pane collapsible | boolean | false | Adds a one-touch collapse button to the adjacent gutter. Only meaningful on the first or last pane; the flag of a middle pane is ignored. |
| currentSize | Signal<number> | - | Live share of a pane in percent, reflecting drag and keyboard changes. |
| collapsed | Signal<boolean> | - | True while the pane is collapsed to its minSize. |
| toggleCollapse() | () => void | - | Toggles the collapse state. A no-op when collapsible is false or the pane is in the middle. |
| --kui-splitter-pane-bg / -pane-border / -radius | CSS custom properties | - | Container background, border and corner radius. |
| --kui-splitter-gutter-size | CSS custom property | --kui-space-2 | Width or height of the interactive gutter strip. |
| --kui-splitter-gutter-line / -line-hover / -line-active / -line-disabled | CSS custom properties | - | Gutter line colour by state. |
| --kui-splitter-thumb-bg / -thumb-bg-hover / -thumb-bg-active | CSS custom properties | - | Default grip colour by state. |
| --kui-splitter-collapse-btn-bg / -collapse-btn-fg / -focus-ring | CSS custom properties | - | One-touch collapse button colours and the focus-visible ring of a gutter. |
| KuiSplitterOptions | interface | - | Shape of defaults.splitter: orientation and minSize. |

## Accessibility

- Each gutter renders an inner `role="separator"` element, focusable (`tabIndex="0"` unless
  `disabled`), following the W3C ARIA APG Window Splitter Pattern. The `kui-splitter-gutter` host
  carries no role; it only positions the separator and the optional collapse button.
- `aria-orientation` describes the gutter's own line, not the panes' layout: panes laid out
  horizontally have a _vertical_ line, so `aria-orientation="vertical"`, and vice versa.
- `aria-valuenow`/`aria-valuemin`/`aria-valuemax` track the size of the pane _before_ the gutter in
  DOM order, recalculated on every resize from the same value that drives the visual `flex-basis` --
  they can never drift out of sync with what's on screen.
- `aria-controls` points at the id of that same before-pane. Each `kui-splitter-pane` renders a
  generated `id` on its element for this, replacing any `id` set on the pane in a template.
- The one-touch collapse button has its own `aria-label` ("Collapse pane" / "Expand pane"), not
  relying on the chevron icon alone. It is a sibling of the separator, not a child, because a
  focusable separator must not contain an interactive control. It stays out of the tab order; the
  keyboard equivalent is `Enter` on the separator.
- `disabled` sets `aria-disabled="true"` and `tabIndex="-1"`, removing the gutter from the tab
  order, not just dimming it.

| Key                                      | Action                                                                                                    |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `Tab` / `Shift+Tab`                      | Focus each gutter in turn.                                                                                |
| `←`/`→` (horizontal), `↑`/`↓` (vertical) | Resize the before-pane by 2%. `Shift` for a 10% step.                                                     |
| `Home` / `End`                           | Collapse the before-pane to its `minSize` / expand it to the max (bounded by the after-pane's `minSize`). |
| `Enter`                                  | Toggle collapse on the adjacent pane -- only when it is `collapsible`.                                    |
| `Escape`                                 | Cancel an active drag, reverting to the sizes from before it started.                                     |

## Playground

Available at /components/splitter/playground.

---

<!-- route: /components/stepper -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/stepper.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/stepper.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Stepper

> Multi-step progress and navigation indicator.

- Status: available
- Route: /components/stepper
- Package: @kikita-labs/ui@2.0.0
- Import: KuiStepper from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/stepper.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-stepper [(currentIndex)]="step" aria-label="Progress">
  <kui-step label="Account" />
  <kui-step label="Workspace" />
  <kui-step label="Invite team" />
</kui-stepper>
```

### Vertical Orientation

```html
<kui-stepper orientation="vertical" [(currentIndex)]="step" aria-label="Progress">
  <kui-step label="Account details" description="Name, email, password" />
  <kui-step label="Workspace setup" description="Team name and logo" />
</kui-stepper>
```

### Error State

```html
<kui-stepper [currentIndex]="1" aria-label="Progress">
  <kui-step label="Account" />
  <kui-step label="Payment" description="Card declined" [hasError]="true" />
  <kui-step label="Confirm" />
</kui-stepper>
```

Steps after an errored step automatically render as `disabled`.

### Compact

```html
<kui-stepper compact [(currentIndex)]="step" aria-label="Progress">
  <kui-step label="Account" />
  <kui-step label="Workspace" />
  <kui-step label="Invite team" />
</kui-stepper>
```

## Examples

Rendered at /components/stepper:

### basic-stepper-example

#### basic-stepper-example.html

```html
<div class="basic-stepper-example">
  <kui-stepper [(currentIndex)]="currentIndex">
    <kui-step label="Details" description="Project basics" />
    <kui-step label="Team" description="Invite collaborators" />
    <kui-step label="Review" description="Confirm settings" />
  </kui-stepper>
</div>
```

#### basic-stepper-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiStep, KuiStepper } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-stepper-example',
  imports: [KuiStep, KuiStepper],
  templateUrl: './basic-stepper-example.html',
  styleUrl: './basic-stepper-example.scss',
})
export class BasicStepperExample {
  protected readonly currentIndex = signal(1);
}
```

#### basic-stepper-example.scss

```scss
.basic-stepper-example {
  display: grid;
  min-width: 0;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| [(currentIndex)] | number | 0 | Zero-based active step index. |
| orientation | 'horizontal' \| 'vertical' \| undefined | undefined | Step list layout direction. Falls back to defaults.stepper.orientation, then horizontal. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | undefined | Circle size and label scale. Falls back to defaults.stepper.size, then the root size, then md. |
| linear | boolean \| undefined | undefined | When true, only completed steps can be clicked to go back; when false, upcoming steps can be clicked to jump forward. Falls back to defaults.stepper.linear, then true. |
| compact | boolean \| undefined | undefined | Shows step circles (dots) without labels or descriptions. Falls back to defaults.stepper.compact, then false. |
| kui-step.label | string | '' | Primary step label. |
| kui-step.description | string | '' | Optional secondary line below the label. |
| kui-step.hasError | boolean | false | Marks the step as errored and disables later steps. |
| kui-step.disabled | boolean | false | Forces a step to render disabled. |
| --kui-stepper-connector-color | CSS custom property | - | Connector line colour. |
| --kui-stepper-connector-color-done | CSS custom property | - | Connector line colour after a completed step. |
| --kui-stepper-circle-size | CSS custom property | - | Step circle diameter. |
| --kui-stepper-fg-upcoming | CSS custom property | - | Foreground of an upcoming step. |
| --kui-stepper-fg-current | CSS custom property | - | Foreground of the current step. |
| --kui-stepper-fg-done | CSS custom property | - | Foreground of a completed step. |
| --kui-stepper-fg-error | CSS custom property | - | Foreground of an errored step. |
| KuiStepperOptions | interface | - | Shape of defaults.stepper: size, orientation, linear and compact. |

## Accessibility

- `kui-stepper` renders `role="list"`; each `kui-step` renders `role="listitem"`.
- The current step has `aria-current="step"`.
- Completed steps (and, when `linear` is `false`, upcoming steps) render their circle as a native `<button>` with an accessible name (`Back to step X` / `Go to step X`).
- Disabled and non-interactive steps render a plain `<span>`, out of tab order.
- Connector lines are decorative (`aria-hidden="true"`).
- Pass `aria-label` on the host, for example `aria-label="Progress"`.

## Playground

Available at /components/stepper/playground.

---

<!-- route: /components/switch -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/switch.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/switch.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Switch

> Native switch control styling for binary settings.

- Status: available
- Route: /components/switch
- Package: @kikita-labs/ui@2.0.0
- Import: KuiSwitch from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/switch.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-field label="Notifications" hint="Control product and release notifications">
  <label>
    <input kuiSwitch type="checkbox" />
    Enable notifications
  </label>
</kui-field>
```

The directive adds `role="switch"` while keeping the native checkbox input, keyboard behavior, and
form behavior. Use `kui-field` for field-level label, hint, error, and description wiring; keep a
native label for the switch text itself.

## Examples

Rendered at /components/switch:

### basic-switch-example

#### basic-switch-example.html

```html
<kui-field label="Notifications" hint="Control product and release notifications">
  <label class="switch-option">
    <input kuiSwitch type="checkbox" checked />
    <span>Enable notifications</span>
  </label>
</kui-field>
```

#### basic-switch-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiSwitch } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-switch-example',
  imports: [KuiField, KuiSwitch],
  templateUrl: './basic-switch-example.html',
  styleUrl: './basic-switch-example.scss',
})
export class BasicSwitchExample {}
```

#### basic-switch-example.scss

```scss
:host {
  display: block;
  inline-size: min(100%, 360px);
}

.switch-option {
  display: inline-flex;
  align-items: center;
  gap: var(--kui-space-2, 8px);
  color: var(--kui-color-text);
}
```

### switch-size-example

#### switch-size-example.html

```html
<div class="switch-size-example">
  <label class="switch-option">
    <input kuiSwitch type="checkbox" size="xs" />
    <span>Extra small</span>
  </label>
  <label class="switch-option">
    <input kuiSwitch type="checkbox" size="sm" checked />
    <span>Small</span>
  </label>
  <label class="switch-option">
    <input kuiSwitch type="checkbox" size="md" checked />
    <span>Medium</span>
  </label>
  <label class="switch-option">
    <input kuiSwitch type="checkbox" size="lg" />
    <span>Large</span>
  </label>
</div>
```

#### switch-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiSwitch } from '@kikita-labs/ui';

@Component({
  selector: 'app-switch-size-example',
  imports: [KuiSwitch],
  templateUrl: './switch-size-example.html',
  styleUrl: './switch-size-example.scss',
})
export class SwitchSizeExample {}
```

#### switch-size-example.scss

```scss
.switch-size-example {
  display: grid;
  gap: var(--kui-space-3, 12px);
  justify-content: center;
}

.switch-option {
  display: inline-flex;
  align-items: center;
  gap: var(--kui-space-2, 8px);
  color: var(--kui-color-text);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Switch size mapped to Kikita switch tokens. Resolved from defaults.switch.size, then the parent field, then the global defaults.size, then md. |
| invalid | boolean | false | Marks the switch invalid outside a kui-field error state. With [formField] the Field state wins. |
| id | string \| undefined | undefined | Explicit id override. Inside kui-field, the field id is used when omitted. |
| KuiSwitchOptions | interface | - | Shape of defaults.switch: size. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/switch/playground.

---

<!-- route: /components/table -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/table.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/table.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Table

> Native table styling, sorting context, and selection cells.

- Status: available
- Route: /components/table
- Package: @kikita-labs/ui@2.0.0
- Import: KuiTable from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/table.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<table kuiTable [data]="rows" #table="kuiTable">
  <thead>
    <tr kuiThGroup>
      <th kuiSelectTh ariaLabel="Select all rows"></th>
      <th kuiTh sortKey="name">Name</th>
      <th kuiTh sortKey="status">Status</th>
      <th kuiTh>Actions</th>
    </tr>
  </thead>
  <tbody>
    @for (row of table.sortedData(); track row.id) {
    <tr kuiRow [value]="row">
      <td kuiSelectCell [ariaLabel]="'Select ' + row.name"></td>
      <td kuiCell>{{ row.name }}</td>
      <td kuiCell>{{ row.status }}</td>
      <td kuiCell>...</td>
    </tr>
    }
  </tbody>
</table>
```

## Examples

Rendered at /components/table:

### basic-sortable-table-example

#### basic-sortable-table-example.html

```html
<table kuiTable [data]="rows" #table="kuiTable">
  <thead>
    <tr kuiThGroup>
      <th kuiTh sortKey="name">Name</th>
      <th kuiTh sortKey="role">Role</th>
      <th kuiTh sortKey="status">Status</th>
    </tr>
  </thead>
  <tbody>
    @for (row of table.sortedData(); track row.id) {
      <tr kuiRow [value]="row">
        <td kuiCell>{{ row.name }}</td>
        <td kuiCell>{{ row.role }}</td>
        <td kuiCell>{{ row.status }}</td>
      </tr>
    }
  </tbody>
</table>
```

#### basic-sortable-table-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCell, KuiRow, KuiTable, KuiTh, KuiThGroup } from '@kikita-labs/ui';

interface TeamMember {
  readonly id: string;
  readonly name: string;
  readonly role: string;
  readonly status: 'Active' | 'Invited' | 'Suspended';
}

const TEAM_MEMBERS: TeamMember[] = [
  { id: '1', name: 'Ava Chen', role: 'Engineer', status: 'Active' },
  { id: '2', name: 'Liam Osei', role: 'Designer', status: 'Invited' },
  { id: '3', name: 'Noor Malik', role: 'Product Manager', status: 'Active' },
  { id: '4', name: 'Priya Rao', role: 'Support', status: 'Suspended' },
  { id: '5', name: 'Tomas Silva', role: 'Engineer', status: 'Active' },
];

@Component({
  selector: 'app-basic-sortable-table-example',
  imports: [KuiCell, KuiRow, KuiTable, KuiTh, KuiThGroup],
  templateUrl: './basic-sortable-table-example.html',
  styleUrl: './basic-sortable-table-example.scss',
})
export class BasicSortableTableExample {
  protected readonly rows = TEAM_MEMBERS;
}
```

#### basic-sortable-table-example.scss

```scss
:host {
  display: block;
  overflow-x: auto;
}
```

### combined-table-example

#### combined-table-example.html

```html
<div class="combined-table-example__scroll">
  <table kuiTable [data]="rows" #table="kuiTable" (selectionChange)="onSelectionChange($event)">
    <thead>
      <tr kuiThGroup sticky>
        <th kuiSelectTh ariaLabel="Select all team members"></th>
        <th kuiTh sortKey="name" sticky>Name</th>
        <th kuiTh sortKey="role">Role</th>
        <th kuiTh sortKey="department">Department</th>
        <th kuiTh sortKey="status">Status</th>
      </tr>
    </thead>
    <tbody>
      @for (row of table.sortedData(); track row.id) {
        <tr kuiRow [value]="row">
          <td kuiSelectCell [ariaLabel]="'Select ' + row.name"></td>
          <td kuiCell>{{ row.name }}</td>
          <td kuiCell>{{ row.role }}</td>
          <td kuiCell>{{ row.department }}</td>
          <td kuiCell>{{ row.status }}</td>
        </tr>
      }
    </tbody>
  </table>
</div>
<p class="combined-table-example__note">{{ selected().length }} of {{ rows.length }} selected</p>
```

#### combined-table-example.ts

```ts
import { Component, signal } from '@angular/core';

import {
  KuiCell,
  KuiRow,
  KuiSelectCell,
  KuiSelectTh,
  KuiTable,
  KuiTh,
  KuiThGroup,
} from '@kikita-labs/ui';

interface TeamMember {
  readonly id: string;
  readonly name: string;
  readonly role: string;
  readonly department: string;
  readonly status: 'Active' | 'Invited' | 'Suspended';
}

const TEAM_MEMBERS: TeamMember[] = [
  { id: '1', name: 'Ava Chen', role: 'Engineer', department: 'Platform', status: 'Active' },
  { id: '2', name: 'Liam Osei', role: 'Designer', department: 'Product', status: 'Invited' },
  { id: '3', name: 'Noor Malik', role: 'Product Manager', department: 'Product', status: 'Active' },
  { id: '4', name: 'Priya Rao', role: 'Support', department: 'Operations', status: 'Suspended' },
  { id: '5', name: 'Tomas Silva', role: 'Engineer', department: 'Platform', status: 'Active' },
];

@Component({
  selector: 'app-combined-table-example',
  imports: [KuiCell, KuiRow, KuiSelectCell, KuiSelectTh, KuiTable, KuiTh, KuiThGroup],
  templateUrl: './combined-table-example.html',
  styleUrl: './combined-table-example.scss',
})
export class CombinedTableExample {
  protected readonly rows = TEAM_MEMBERS;
  protected readonly selected = signal<readonly TeamMember[]>([]);

  protected onSelectionChange(rows: readonly TeamMember[]): void {
    this.selected.set(rows);
  }
}
```

#### combined-table-example.scss

```scss
.combined-table-example__scroll {
  max-block-size: 220px;
  overflow: auto;
}

.combined-table-example__note {
  margin: var(--kui-space-2, 8px) 0 0;
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

### row-selection-table-example

#### row-selection-table-example.html

```html
<table kuiTable [data]="rows" (selectionChange)="onSelectionChange($event)">
  <thead>
    <tr kuiThGroup>
      <th kuiSelectTh ariaLabel="Select all team members"></th>
      <th kuiTh sortKey="name">Name</th>
      <th kuiTh sortKey="role">Role</th>
      <th kuiTh sortKey="status">Status</th>
    </tr>
  </thead>
  <tbody>
    @for (row of rows; track row.id) {
      <tr kuiRow [value]="row">
        <td kuiSelectCell [ariaLabel]="'Select ' + row.name"></td>
        <td kuiCell>{{ row.name }}</td>
        <td kuiCell>{{ row.role }}</td>
        <td kuiCell>{{ row.status }}</td>
      </tr>
    }
  </tbody>
</table>
<p class="row-selection-table-example__note">
  {{ selected().length }} of {{ rows.length }} selected
</p>
```

#### row-selection-table-example.ts

```ts
import { Component, signal } from '@angular/core';

import {
  KuiCell,
  KuiRow,
  KuiSelectCell,
  KuiSelectTh,
  KuiTable,
  KuiTh,
  KuiThGroup,
} from '@kikita-labs/ui';

interface TeamMember {
  readonly id: string;
  readonly name: string;
  readonly role: string;
  readonly status: 'Active' | 'Invited' | 'Suspended';
}

const TEAM_MEMBERS: TeamMember[] = [
  { id: '1', name: 'Ava Chen', role: 'Engineer', status: 'Active' },
  { id: '2', name: 'Liam Osei', role: 'Designer', status: 'Invited' },
  { id: '3', name: 'Noor Malik', role: 'Product Manager', status: 'Active' },
  { id: '4', name: 'Priya Rao', role: 'Support', status: 'Suspended' },
  { id: '5', name: 'Tomas Silva', role: 'Engineer', status: 'Active' },
];

@Component({
  selector: 'app-row-selection-table-example',
  imports: [KuiCell, KuiRow, KuiSelectCell, KuiSelectTh, KuiTable, KuiTh, KuiThGroup],
  templateUrl: './row-selection-table-example.html',
  styleUrl: './row-selection-table-example.scss',
})
export class RowSelectionTableExample {
  protected readonly rows = TEAM_MEMBERS;
  protected readonly selected = signal<readonly TeamMember[]>([]);

  protected onSelectionChange(rows: readonly TeamMember[]): void {
    this.selected.set(rows);
  }
}
```

#### row-selection-table-example.scss

```scss
:host {
  display: block;
  overflow-x: auto;
}

.row-selection-table-example__note {
  margin: var(--kui-space-2, 8px) 0 0;
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

### sticky-header-table-example

#### sticky-header-table-example.html

```html
<div class="sticky-header-table-example__scroll">
  <table kuiTable [data]="rows" #table="kuiTable">
    <thead>
      <tr kuiThGroup sticky>
        <th kuiTh sortKey="name" sticky>Name</th>
        <th kuiTh sortKey="role">Role</th>
        <th kuiTh sortKey="department">Department</th>
        <th kuiTh sortKey="location">Location</th>
        <th kuiTh sortKey="status">Status</th>
      </tr>
    </thead>
    <tbody>
      @for (row of table.sortedData(); track row.id) {
        <tr kuiRow [value]="row">
          <td kuiCell>{{ row.name }}</td>
          <td kuiCell>{{ row.role }}</td>
          <td kuiCell>{{ row.department }}</td>
          <td kuiCell>{{ row.location }}</td>
          <td kuiCell>{{ row.status }}</td>
        </tr>
      }
    </tbody>
  </table>
</div>
```

#### sticky-header-table-example.ts

```ts
import { Component } from '@angular/core';

import { KuiCell, KuiRow, KuiTable, KuiTh, KuiThGroup } from '@kikita-labs/ui';

interface TeamMember {
  readonly id: string;
  readonly name: string;
  readonly role: string;
  readonly department: string;
  readonly location: string;
  readonly status: 'Active' | 'Invited' | 'Suspended';
}

const TEAM_MEMBERS: TeamMember[] = [
  {
    id: '1',
    name: 'Ava Chen',
    role: 'Engineer',
    department: 'Platform',
    location: 'Remote',
    status: 'Active',
  },
  {
    id: '2',
    name: 'Liam Osei',
    role: 'Designer',
    department: 'Product',
    location: 'Berlin',
    status: 'Invited',
  },
  {
    id: '3',
    name: 'Noor Malik',
    role: 'Product Manager',
    department: 'Product',
    location: 'Remote',
    status: 'Active',
  },
  {
    id: '4',
    name: 'Priya Rao',
    role: 'Support',
    department: 'Operations',
    location: 'Singapore',
    status: 'Suspended',
  },
  {
    id: '5',
    name: 'Tomas Silva',
    role: 'Engineer',
    department: 'Platform',
    location: 'Lisbon',
    status: 'Active',
  },
];

@Component({
  selector: 'app-sticky-header-table-example',
  imports: [KuiCell, KuiRow, KuiTable, KuiTh, KuiThGroup],
  templateUrl: './sticky-header-table-example.html',
  styleUrl: './sticky-header-table-example.scss',
})
export class StickyHeaderTableExample {
  protected readonly rows = TEAM_MEMBERS;
}
```

#### sticky-header-table-example.scss

```scss
.sticky-header-table-example__scroll {
  max-block-size: 220px;
  overflow: auto;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| data | T[] | [] | Source rows for sorting and selection. Selector: table[kuiTable]. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Table density and typography scale. Falls back to defaults.table.size, then the global defaults.size, then md. Selector: table[kuiTable]. |
| selectionChange | output<T[]> | - | Emits current selection whenever it changes. Observing this output is what makes the selection column appear. Selector: table[kuiTable]. |
| sortChange | output<KuiActiveSortState \| null> | - | Emits the active sort key/direction, or null when sort is cleared. When observed, kuiTable hands row ordering to the parent instead of sorting locally. Selector: table[kuiTable]. |
| sortState | Signal<KuiSortState> | - | Current sort state (null when no column is sorted). Selector: table[kuiTable]. |
| sortedData | Signal<T[]> | - | Rows in current sort order. Use this in the template instead of data when sort is uncontrolled. Selector: table[kuiTable]. |
| isSelected(item) | (item: T) => boolean | - | Returns whether a given row value is currently selected. Selector: table[kuiTable]. |
| #table="kuiTable" | exportAs | - | Template reference for reading sortedData(), sortState(), and selection state. |
| sortKey | string \| undefined | - | Enables sort for this header cell; usually matches a row property name. Selector: th[kuiTh]. |
| comparator | (a: T, b: T) => number | - | Custom sort function for the column, used instead of default comparison. Selector: th[kuiTh]. |
| sticky | boolean | false | Pins this header cell horizontally with position: sticky. Selector: th[kuiTh]. Also available on tr[kuiThGroup] to pin the whole header row vertically. |
| value | T \| undefined | undefined | Data object used for selected state. Omit it for a presentational row without selection. Selector: tr[kuiRow]. |
| ariaLabel | string \| undefined | undefined | Accessible label for the select-all checkbox; falls back to the table.selectAllRows message (Select all rows). Selector: th[kuiSelectTh]. |
| ariaLabel | string \| undefined | undefined | Accessible label for a row selection checkbox, falling back to the table.selectRow message (Select row), e.g. "Select " + row.name. Selector: td[kuiSelectCell]. |
| td[kuiCell] | marker directive | - | Applies Kikita table cell styling to a native td. No inputs in the installed version. |
| --kui-table-font-size | CSS custom property | - | Base font size for table text. |
| --kui-table-th-py | CSS custom property | - | Vertical padding for header cells. |
| --kui-table-cell-px | CSS custom property | - | Horizontal padding for cells. |
| --kui-table-row-py | CSS custom property | - | Vertical padding for body row cells. |
| --kui-table-th-fg | CSS custom property | - | Header cell text color. |
| --kui-table-th-bg | CSS custom property | - | Header cell background color. |
| --kui-table-border | CSS custom property | - | Outer table border color. |
| --kui-table-row-border | CSS custom property | - | Row divider border color. |
| --kui-table-row-hover-bg | CSS custom property | - | Row background on hover. |
| --kui-table-row-selected-bg | CSS custom property | - | Row background when selected. |
| --kui-table-row-selected-accent | CSS custom property | - | Accent color for selected rows. |
| --kui-table-sort-active-color | CSS custom property | - | Color used for the active sort indicator. |
| --kui-table-bg | CSS custom property | - | Table background color. |
| KuiTableOptions | interface | - | Shape of defaults.table: size. |

## Accessibility

- Keep real `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, and `<td>` markup.
- Sortable headers keep `aria-sort` on `<th>` and expose the action through a
  native button.
- Selection uses native checkboxes with accessible labels.
- Add a native `<caption>` in product tables when the surrounding page does not
  already provide a clear table title.
- Avoid putting complex interactive widgets inside cells unless their focus
  order and labels are explicitly tested.

## Playground

Available at /components/table/playground.

---

<!-- route: /components/tabs -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/tabs.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/tabs.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Tabs

> Line and pill tab navigation with optional panel wiring.

- Status: available
- Route: /components/tabs
- Package: @kikita-labs/ui@2.0.0
- Import: KuiTabs from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/tabs.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-tabs [(value)]="activeTab">
  <button kuiTab value="overview">Overview</button>
  <button kuiTab value="settings">Settings</button>
  <button kuiTab value="logs">Logs</button>

  <div kuiTabPanel value="overview">Overview content</div>
  <div kuiTabPanel value="settings">Settings content</div>
  <div kuiTabPanel value="logs">Log content</div>
</kui-tabs>
```

### Pill Variant

```html
<kui-tabs variant="pill" [(value)]="activeTab"> ... </kui-tabs>
```

### Inverted Edge

Use `inverted` when the tab list should sit on the opposite edge of the panels.
Horizontal tabs render panels above the tab list and place the line indicator on
the top edge. Vertical tabs render panels before the tab list and place the line
indicator on the start edge.

```html
<kui-tabs inverted [(value)]="activeTab">
  <button kuiTab value="details">Details</button>
  <button kuiTab value="history">History</button>

  <div kuiTabPanel value="details">Details content</div>
  <div kuiTabPanel value="history">History content</div>
</kui-tabs>

<kui-tabs orientation="vertical" inverted [(value)]="activeTab">
  <button kuiTab value="details">Details</button>
  <button kuiTab value="history">History</button>

  <div kuiTabPanel value="details">Details content</div>
  <div kuiTabPanel value="history">History content</div>
</kui-tabs>
```

### Router Navigation

Use `controlsPanels="false"` when `kui-tabs` is used as navigation and the routed page content is rendered by `router-outlet` instead of local `kuiTabPanel` elements.

```html
<kui-tabs [(value)]="currentRoute" [controlsPanels]="false" aria-label="Sections">
  <button kuiTab value="/overview">Overview</button>
  <button kuiTab value="/settings">Settings</button>
</kui-tabs>
```

## Examples

Rendered at /components/tabs:

### basic-tabs-example

#### basic-tabs-example.html

```html
<kui-tabs [(value)]="activeTab">
  <button kuiTab value="overview">Overview</button>
  <button kuiTab value="settings">Settings</button>
  <button kuiTab value="logs">Logs</button>

  <div kuiTabPanel value="overview">Overview content.</div>
  <div kuiTabPanel value="settings">Settings content.</div>
  <div kuiTabPanel value="logs">Log content.</div>
</kui-tabs>
```

#### basic-tabs-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiTab, KuiTabPanel, KuiTabs } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-tabs-example',
  imports: [KuiTab, KuiTabPanel, KuiTabs],
  templateUrl: './basic-tabs-example.html',
  styleUrl: './basic-tabs-example.scss',
})
export class BasicTabsExample {
  protected readonly activeTab = signal('overview');
}
```

#### basic-tabs-example.scss

```scss
:host {
  display: block;
}
```

### navigation-tabs-example

#### navigation-tabs-example.html

```html
<kui-tabs [(value)]="currentSection" [controlsPanels]="false" aria-label="Sections">
  <button kuiTab value="/overview">Overview</button>
  <button kuiTab value="/settings">Settings</button>
  <button kuiTab value="/team">Team</button>
</kui-tabs>

<p class="navigation-tabs-example__note">
  Selected value: <code>{{ currentSection() }}</code>
</p>
```

#### navigation-tabs-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiTab, KuiTabs } from '@kikita-labs/ui';

@Component({
  selector: 'app-navigation-tabs-example',
  imports: [KuiTab, KuiTabs],
  templateUrl: './navigation-tabs-example.html',
  styleUrl: './navigation-tabs-example.scss',
})
export class NavigationTabsExample {
  protected readonly currentSection = signal('/overview');
}
```

#### navigation-tabs-example.scss

```scss
:host {
  display: block;
}

.navigation-tabs-example__note {
  margin: var(--kui-space-3, 12px) 0 0;
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

### pill-tabs-example

#### pill-tabs-example.html

```html
<kui-tabs variant="pill" [(value)]="activeTab">
  <button kuiTab value="daily">Daily</button>
  <button kuiTab value="weekly" hasError errorLabel="Contains validation errors">Weekly</button>
  <button kuiTab value="monthly">Monthly</button>

  <div kuiTabPanel value="daily">Daily report content.</div>
  <div kuiTabPanel value="weekly">Weekly report content.</div>
  <div kuiTabPanel value="monthly">Monthly report content.</div>
</kui-tabs>
```

#### pill-tabs-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiTab, KuiTabPanel, KuiTabs } from '@kikita-labs/ui';

@Component({
  selector: 'app-pill-tabs-example',
  imports: [KuiTab, KuiTabPanel, KuiTabs],
  templateUrl: './pill-tabs-example.html',
  styleUrl: './pill-tabs-example.scss',
})
export class PillTabsExample {
  protected readonly activeTab = signal('daily');
}
```

#### pill-tabs-example.scss

```scss
:host {
  display: block;
}
```

### vertical-tabs-example

#### vertical-tabs-example.html

```html
<kui-tabs orientation="vertical" [(value)]="activeTab">
  <button kuiTab value="profile">Profile</button>
  <button kuiTab value="billing">Billing</button>
  <button kuiTab value="security">Security</button>

  <div kuiTabPanel value="profile">Profile content.</div>
  <div kuiTabPanel value="billing">Billing content.</div>
  <div kuiTabPanel value="security">Security content.</div>
</kui-tabs>
```

#### vertical-tabs-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiTab, KuiTabPanel, KuiTabs } from '@kikita-labs/ui';

@Component({
  selector: 'app-vertical-tabs-example',
  imports: [KuiTab, KuiTabPanel, KuiTabs],
  templateUrl: './vertical-tabs-example.html',
  styleUrl: './vertical-tabs-example.scss',
})
export class VerticalTabsExample {
  protected readonly activeTab = signal('profile');
}
```

#### vertical-tabs-example.scss

```scss
:host {
  display: block;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| variant | 'line' \| 'pill' \| undefined | undefined | Tab visual style: underline indicator (line) or pill background (pill). Falls back to defaults.tabs.variant, then line. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Tab trigger height and font size. Falls back to defaults.tabs.size, then the root size, then md. |
| orientation | 'horizontal' \| 'vertical' \| undefined | undefined | Layout direction of the tab list (defaults.tabs.orientation, then horizontal). Vertical stacks triggers in a column with the indicator on the side edge. |
| inverted | boolean | false | Flips the tab edge. Horizontal tabs render panels above and the indicator on top; vertical tabs render panels before the list and the indicator on the start edge. |
| controlsPanels | boolean | true | Whether tabs expose aria-controls links to projected kuiTabPanel elements. Set to false when tabs are used as navigation and content is rendered elsewhere, such as a router-outlet. |
| [(value)] | string | - | Value of the active tab. |
| [(selected)] | string | - | Deprecated alias for value, kept in sync with it. Use value instead; planned for removal in the next major version. |
| [kuiTab] value | string | - | Identifier for this tab trigger. Must match a kuiTabPanel value when controlsPanels is true. |
| [kuiTab] hasError | boolean | false | Shows a small danger dot next to the tab label without changing the selected state or tab color. |
| [kuiTab] errorLabel | string \| undefined | undefined | Screen-reader-only text announced alongside the error dot. Falls back to the tabs.errorIndicator message (has error). |
| [kuiTabPanel] value | string | - | Identifier matching a [kuiTab] value. Panel is shown when its value matches the tabs value. |
| --kui-tabs-gap | CSS length | 2px | Gap between tab triggers in the list. |
| --kui-tabs-border | CSS color | var(--kui-color-border) | Border color of the tab list edge (bottom for horizontal, side for vertical). |
| --kui-tabs-panel-gap | CSS length | var(--kui-space-4) | Gap between the tab list and the active panel. |
| --kui-tab-height | CSS length | var(--kui-btn-height) | Tab trigger block size. Overridden per size. |
| --kui-tab-px | CSS length | var(--kui-btn-px) | Tab trigger inline padding. Overridden per size. |
| --kui-tab-indicator | CSS color | var(--kui-color-primary-fill) | Color of the selected-tab indicator (underline for line, background for pill). |
| --kui-tab-fg-active | CSS color | var(--kui-color-text) | Text color of the selected tab. |
| --kui-tab-gap | CSS custom property | - | Gap inside a tab trigger. |
| --kui-tab-radius | CSS custom property | - | Tab trigger corner radius. |
| --kui-tab-fg | CSS custom property | - | Tab foreground. |
| --kui-tab-fg-hover | CSS custom property | - | Tab foreground on hover. |
| --kui-tab-bg-hover | CSS custom property | - | Tab background on hover. |
| --kui-tab-indicator-size | CSS custom property | - | Thickness of the active indicator. |
| --kui-tab-font-size | CSS custom property | - | Tab font size. |
| --kui-tab-font-weight | CSS custom property | - | Tab font weight. |
| --kui-tab-font-weight-active | CSS custom property | - | Active tab font weight. |
| --kui-tab-pill-gap | CSS custom property | - | Gap between pill tabs. |
| --kui-tab-pill-radius | CSS custom property | - | Pill tab corner radius. |
| --kui-tab-pill-bg-hover | CSS custom property | - | Pill tab background on hover. |
| --kui-tab-pill-bg-active | CSS custom property | - | Active pill tab background. |
| --kui-tab-pill-fg-active | CSS custom property | - | Active pill tab foreground. |
| KuiTabsOptions | interface | - | Shape of defaults.tabs: size, variant, orientation, previousIcon and nextIcon. |

## Accessibility

- `role="tablist"` on the list container
- `role="tab"` on each trigger, with `aria-selected` and roving `tabindex`
- `role="tabpanel"` on each panel
- `aria-controls` is emitted by default and should point to a matching `[kuiTabPanel]`
- Use `[controlsPanels]="false"` only for navigation-style tabs without local panels

## Playground

Available at /components/tabs/playground.

---

<!-- route: /components/textarea -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/textarea.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/textarea.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Textarea

> Native multiline input styling with field integration.

- Status: available
- Route: /components/textarea
- Package: @kikita-labs/ui@2.0.0
- Import: KuiTextarea from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/textarea.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-field label="Notes" hint="Internal project note">
  <textarea kuiTextarea rows="4" placeholder="Write a note"></textarea>
</kui-field>
```

## Examples

Rendered at /components/textarea:

### basic-textarea-example

#### basic-textarea-example.html

```html
<div class="basic-textarea-example">
  <kui-field label="Notes" hint="Internal project note">
    <textarea kuiTextarea rows="4" placeholder="Write a note"></textarea>
  </kui-field>
</div>
```

#### basic-textarea-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiTextarea } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-textarea-example',
  imports: [KuiField, KuiTextarea],
  templateUrl: './basic-textarea-example.html',
  styleUrl: './basic-textarea-example.scss',
})
export class BasicTextareaExample {}
```

#### basic-textarea-example.scss

```scss
.basic-textarea-example {
  display: grid;
  inline-size: min(100%, 360px);
  gap: var(--kui-space-4, 16px);
}
```

### textarea-invalid-example

#### textarea-invalid-example.html

```html
<div class="textarea-invalid-example">
  <kui-field label="Summary" error="Summary must be at least 20 characters" required>
    <textarea kuiTextarea rows="3" placeholder="Describe the change"></textarea>
  </kui-field>

  <kui-field label="Notes" hint="Standalone invalid state outside field error wiring">
    <textarea kuiTextarea invalid rows="3" placeholder="Write a note"></textarea>
  </kui-field>
</div>
```

#### textarea-invalid-example.ts

```ts
import { Component } from '@angular/core';

import { KuiField, KuiTextarea } from '@kikita-labs/ui';

@Component({
  selector: 'app-textarea-invalid-example',
  imports: [KuiField, KuiTextarea],
  templateUrl: './textarea-invalid-example.html',
  styleUrl: './textarea-invalid-example.scss',
})
export class TextareaInvalidExample {}
```

#### textarea-invalid-example.scss

```scss
.textarea-invalid-example {
  display: grid;
  inline-size: min(100%, 360px);
  gap: var(--kui-space-4, 16px);
}
```

### textarea-size-example

#### textarea-size-example.html

```html
<div class="textarea-size-example">
  <label class="textarea-size-example__option">
    <span>Extra small</span>
    <textarea kuiTextarea size="xs" rows="2" placeholder="Extra small"></textarea>
  </label>
  <label class="textarea-size-example__option">
    <span>Small</span>
    <textarea kuiTextarea size="sm" rows="2" placeholder="Small"></textarea>
  </label>
  <label class="textarea-size-example__option">
    <span>Medium</span>
    <textarea kuiTextarea size="md" rows="2" placeholder="Medium (default)"></textarea>
  </label>
  <label class="textarea-size-example__option">
    <span>Large</span>
    <textarea kuiTextarea size="lg" rows="2" placeholder="Large"></textarea>
  </label>
</div>
```

#### textarea-size-example.ts

```ts
import { Component } from '@angular/core';

import { KuiTextarea } from '@kikita-labs/ui';

@Component({
  selector: 'app-textarea-size-example',
  imports: [KuiTextarea],
  templateUrl: './textarea-size-example.html',
  styleUrl: './textarea-size-example.scss',
})
export class TextareaSizeExample {}
```

#### textarea-size-example.scss

```scss
.textarea-size-example {
  display: grid;
  inline-size: min(100%, 360px);
  gap: var(--kui-space-4, 16px);
}

.textarea-size-example__option {
  display: grid;
  gap: var(--kui-space-2, 8px);
  color: var(--kui-color-text-secondary);
  font-size: var(--kui-text-sm-size, 13px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Textarea height and spacing size, mapped to Kikita UI control tokens. Resolved from defaults.textarea.size, then the parent field, then the global defaults.size, then md. |
| invalid | boolean | false | Marks the textarea invalid outside a kui-field error state. With [formField] the Field state wins. |
| id | string \| undefined | undefined | Explicit id override. Inside kui-field, the field id is used when omitted. |
| KuiTextareaOptions | interface | - | Shape of defaults.textarea: size. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/textarea/playground.

---

<!-- route: /components/time-picker -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/time-picker.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/time-picker.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Time Picker

> Time-of-day input with a scrollable hour, minute and second panel.

- Status: available
- Route: /components/time-picker
- Package: @kikita-labs/ui@2.0.0
- Import: KuiTimePicker from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/time-picker.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-field label="Meeting time">
  <input kuiTimePicker [(value)]="time" />
  <kui-dropdown panelRole="dialog" panelWidth="auto" maxHeight="280px">
    <kui-time-picker-panel />
  </kui-dropdown>
</kui-field>
```

The panel needs no `[value]`/`(valueChange)` or `[format]`/`[minuteStep]`/`[secondStep]`/
`[showSeconds]` binding: when `kui-time-picker-panel` is found as a sibling of
`input[kuiTimePicker]` inside the same `kui-field`, the directive auto-discovers it and wires
`value` both ways (a column pick, an arrow-key move, or "Now" updates the input; a valid time
typed in the input updates the panel), and pushes `format`/`hourStep`/`minuteStep`/`secondStep`/
`showSeconds`/`minTime`/`maxTime`/`disabledHours`/`disabledMinutes`/`disabledSeconds` into it
one-way. Every column auto-centers on its selected cell -- both the moment the panel opens and on
every later selection (click, keyboard, "Now") -- reacting to the ancestor `kui-dropdown`'s own
`isOpen` signal rather than this component's construction, so it holds regardless of whether a
given `kui-dropdown` recreates a fresh panel per open or reuses one across opens.

### Inline (standalone)

`kui-time-picker-panel` also works on its own, the same way `kui-calendar` does — its ancestor
`kui-dropdown` is optional, and it auto-detects whether one is present:

```html
<kui-time-picker-panel [(value)]="time" [showSeconds]="true" />
```

With no `kui-dropdown` ancestor, the panel draws its own background/border (`data-kui-flat` is
only set when one is present, matching `kui-calendar`'s `flat` input — just auto-detected here
instead of an explicit prop). "Now"/"Done" still work standalone; "Done" simply has nothing to
close.

## Examples

Rendered at /components/time-picker:

### basic-time-picker-example

#### basic-time-picker-example.html

```html
<div class="time-picker-example">
  <kui-field label="Meeting time" hint="Type a time or choose from the columns.">
    <input kuiTimePicker [(value)]="time" />
    <kui-dropdown panelRole="dialog" panelWidth="auto" maxHeight="280px">
      <kui-time-picker-panel />
    </kui-dropdown>
  </kui-field>
</div>
```

#### basic-time-picker-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiDropdown, KuiField, KuiTimePicker, KuiTimePickerPanel } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-time-picker-example',
  imports: [KuiDropdown, KuiField, KuiTimePicker, KuiTimePickerPanel],
  templateUrl: './basic-time-picker-example.html',
  styleUrl: './basic-time-picker-example.scss',
})
export class BasicTimePickerExample {
  protected readonly time = signal<Date | null>(new Date(2026, 6, 14, 9, 30));
}
```

#### basic-time-picker-example.scss

```scss
.time-picker-example {
  display: grid;
  gap: var(--kui-space-4, 16px);
  inline-size: min(100%, 320px);
}
```

### time-picker-format-example

#### time-picker-format-example.html

```html
<div class="time-picker-example">
  <kui-field label="Slot" hint="12-hour clock with seconds in 15-minute and 15-second steps.">
    <input
      kuiTimePicker
      [(value)]="time"
      format="12h"
      [showSeconds]="true"
      [minuteStep]="15"
      [secondStep]="15"
    />
    <kui-dropdown panelRole="dialog" panelWidth="auto" maxHeight="300px">
      <kui-time-picker-panel />
    </kui-dropdown>
  </kui-field>
</div>
```

#### time-picker-format-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiDropdown, KuiField, KuiTimePicker, KuiTimePickerPanel } from '@kikita-labs/ui';

@Component({
  selector: 'app-time-picker-format-example',
  imports: [KuiDropdown, KuiField, KuiTimePicker, KuiTimePickerPanel],
  templateUrl: './time-picker-format-example.html',
  styleUrl: './time-picker-format-example.scss',
})
export class TimePickerFormatExample {
  protected readonly time = signal<Date | null>(new Date(2026, 6, 14, 14, 45, 15));
}
```

#### time-picker-format-example.scss

```scss
.time-picker-example {
  display: grid;
  gap: var(--kui-space-4, 16px);
  inline-size: min(100%, 320px);
}
```

### time-picker-limits-example

#### time-picker-limits-example.html

```html
<div class="time-picker-example">
  <kui-field
    label="Office hours"
    hint="09:00 to 18:00, lunch hours and 17:30 to 17:59 are not available."
  >
    <input
      kuiTimePicker
      [(value)]="time"
      [minTime]="minTime"
      [maxTime]="maxTime"
      [disabledHours]="disabledHours"
      [disabledMinutes]="disabledMinutes"
    />
    <kui-dropdown panelRole="dialog" panelWidth="auto" maxHeight="280px">
      <kui-time-picker-panel />
    </kui-dropdown>
  </kui-field>
</div>
```

#### time-picker-limits-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiDropdown, KuiField, KuiTimePicker, KuiTimePickerPanel } from '@kikita-labs/ui';

@Component({
  selector: 'app-time-picker-limits-example',
  imports: [KuiDropdown, KuiField, KuiTimePicker, KuiTimePickerPanel],
  templateUrl: './time-picker-limits-example.html',
  styleUrl: './time-picker-limits-example.scss',
})
export class TimePickerLimitsExample {
  protected readonly time = signal<Date | null>(null);
  protected readonly minTime = new Date(2026, 0, 1, 9, 0);
  protected readonly maxTime = new Date(2026, 0, 1, 18, 0);
  protected readonly disabledHours = (): readonly number[] => [12, 13];
  protected readonly disabledMinutes = (hour: number): readonly number[] =>
    hour === 17 ? [30, 45] : [];
}
```

#### time-picker-limits-example.scss

```scss
.time-picker-example {
  display: grid;
  gap: var(--kui-space-4, 16px);
  inline-size: min(100%, 320px);
}
```

### time-picker-inline-example

#### time-picker-inline-example.html

```html
<div class="time-picker-example">
  <kui-time-picker-panel [(value)]="time" [showSeconds]="true" />
</div>
```

#### time-picker-inline-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiTimePickerPanel } from '@kikita-labs/ui';

@Component({
  selector: 'app-time-picker-inline-example',
  imports: [KuiTimePickerPanel],
  templateUrl: './time-picker-inline-example.html',
  styleUrl: './time-picker-inline-example.scss',
})
export class TimePickerInlineExample {
  protected readonly time = signal<Date | null>(new Date(2026, 6, 14, 8, 5, 0));
}
```

#### time-picker-inline-example.scss

```scss
.time-picker-example {
  display: grid;
  gap: var(--kui-space-4, 16px);
  inline-size: min(100%, 320px);
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| [(value)] | Date \| null | null | Selected time. Only the hours, minutes and seconds are meaningful. Auto-wired both ways into a sibling kui-time-picker-panel inside the same kui-field. |
| format | '24h' \| '12h' \| undefined | undefined | Display and parse format. Resolves as format, then defaults.timePicker.format, then the hour cycle of the locale (12h in en-US, 24h in ru-RU). Pushed into the panel. |
| hourStep / minuteStep / secondStep | number | 1 | Thins the hour, minute and second columns to every Nth value; typed values snap to the step. Static numeric values are coerced and invalid or non-positive values use 1. Fall back to defaults.timePicker. Pushed into the panel. |
| showSeconds | boolean | false | Adds a seconds column and group. Falls back to defaults.timePicker.showSeconds. |
| minTime / maxTime | Date \| undefined | undefined | Earliest and latest selectable time of day, inclusive; only hours, minutes and seconds are read. Out-of-range cells are disabled and a typed out-of-range time is only marked aria-invalid. |
| disabledHours | (() => readonly number[]) \| undefined | undefined | Returns the hours to disable. A typed value on one is marked aria-invalid, not rejected. |
| disabledMinutes | ((hour: number) => readonly number[]) \| undefined | undefined | Returns the minutes to disable for a given hour. |
| disabledSeconds | ((hour: number, minute: number) => readonly number[]) \| undefined | undefined | Returns the seconds to disable for a given hour and minute; used only with showSeconds. |
| clearable | boolean \| undefined | undefined | Shows the clear button once there is a value. Resolved as local input, defaults.timePicker.clearable, defaults.field.clearable, then true. |
| disabled / readonly | boolean | false | disabled uses the native attribute on the input and the chevron. readonly shows the value but never opens the popover. |
| placeholder | string \| undefined | locale layout | Defaults to the hour, minute and second placeholder messages joined with the locale separator, plus the day period for 12h. |
| messages | Partial<KuiTimePickerMessages> \| undefined | undefined | Per-instance text overrides: button and column names, Now, Done and the placeholder tokens. |
| id | string \| undefined | undefined | Falls back to the control id of the parent kui-field. |
| invalid, errors, touched, (touch) | FormValueControl<Date \| null> | - | The Signal Forms contract, with the same shape as the date picker. invalid is also set by an incomplete group or a value in an excluded range. |
| kui-time-picker-panel | component | - | The scrollable hour, minute and second columns with Now and Done. It works inside a kui-dropdown (auto-wired to the input) or standalone with [(value)]; standalone it draws its own background and border. |
| --kui-timepicker-col-gap / -icon-color / -cell-bg-selected / -cell-text-selected / -cell-bg-hover | CSS custom properties | - | Column gap, clock icon colour and the selected and hover cell colours. |
| --kui-timepicker-affordance-size / -suffix-gap | CSS custom properties | 20px / 2px | Chevron and clear target size and the gap between the trailing buttons. |
| KuiTimePickerOptions | interface | - | Shape of defaults.timePicker: clearable, format, hourStep, minuteStep, secondStep, showSeconds, chevronIcon and clearIcon. |

## Accessibility

- `role="combobox"` on the input, `aria-haspopup="dialog"`, `aria-expanded` + `aria-controls`
  pointing at the popover panel id — the same pattern `kuiDatePicker` uses (a combobox that
  opens a non-modal dialog, not a listbox).
- Each unit column is `role="listbox"` with its own `aria-label` ("Hours"/"Minutes"/"Seconds"),
  focusable (`tabindex="0"`); arrow keys/Home/End work inside it without moving focus to another
  column. Cells are `role="option"` + `aria-selected`; the selected cell is also visually distinct
  (fill + bold), not color alone.
- `:focus-visible` is explicitly styled on the column (a `--kui-color-primary-fill` ring), not
  left to the browser default.
- AM/PM uses `kui-segmented` (`role="radiogroup"`) — already keyboard-accessible as part of the
  kit, not reimplemented here.
- Disabled uses native `disabled` on the input and the chevron button (excluded from tab order).
- Invalid sets `aria-invalid` on the input; pair with `kui-field`'s `error` for an announced
  `role="alert"` message.

### Keyboard

- `ArrowDown` (in the input, panel closed): opens the popover and moves focus into the first
  column.
- `Enter` (in the input): opens the popover if closed, closes it if open.
- `Enter` (in a column): closes the popover, keeping the current selection.
- `Escape` (anywhere in the field or panel): closes the popover; focus stays in the field, or returns to it when it was inside the panel.
- `Tab` (in the input): closes the popover, focus moves to the next tabbable element.
- `ArrowUp` / `ArrowDown` (in a column): cyclic move to the previous/next value, applied
  immediately.
- `Home` / `End` (in a column): jump to the first/last value in that column.

Selecting a cell (by click or arrow key) does **not** close the panel — picking hours would
otherwise close the panel before minutes/seconds could be picked. Close explicitly with
`Enter`/`Escape`/an outside click, or the panel's own "Done" button. The panel's "Now" button
sets `value` to the current time without closing.

## Playground

Available at /components/time-picker/playground.

---

<!-- route: /components/toast -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/toast.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/toast.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Toast

> Global notifications with actions and live-region semantics.

- Status: available
- Route: /components/toast
- Package: @kikita-labs/ui@2.0.0
- Import: KuiToast from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/toast.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```ts
@Component({ ... })
export class MyComponent {
  private toast = kuiToast();

  save() {
    this.api.save().subscribe({
      next: () =>
        this.toast.open({ title: 'Saved', appearance: 'success' }),
      error: () =>
        this.toast.open({ title: 'Failed', appearance: 'danger', persistent: true }),
    });
  }
}
```

## Examples

Rendered at /components/toast:

### basic-toast-example

#### basic-toast-example.html

```html
<div class="basic-toast-example">
  @for (trigger of triggers; track trigger.appearance) {
    <button kuiButton type="button" shape="soft" (click)="show(trigger.appearance)">
      {{ trigger.label }}
    </button>
  }
</div>
```

#### basic-toast-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, kuiToast, type KuiToastAppearance } from '@kikita-labs/ui';

interface ToastTrigger {
  readonly label: string;
  readonly appearance: KuiToastAppearance;
}

@Component({
  selector: 'app-basic-toast-example',
  imports: [KuiButton],
  templateUrl: './basic-toast-example.html',
  styleUrl: './basic-toast-example.scss',
})
export class BasicToastExample {
  private readonly toast = kuiToast();

  protected readonly triggers: readonly ToastTrigger[] = [
    { label: 'Neutral', appearance: 'neutral' },
    { label: 'Success', appearance: 'success' },
    { label: 'Warning', appearance: 'warning' },
    { label: 'Danger', appearance: 'danger' },
    { label: 'Info', appearance: 'info' },
  ];

  protected show(appearance: KuiToastAppearance): void {
    this.toast.open({
      title: this.titleFor(appearance),
      message: this.messageFor(appearance),
      appearance,
      persistent: appearance === 'danger',
    });
  }

  private titleFor(appearance: KuiToastAppearance): string {
    switch (appearance) {
      case 'success':
        return 'Saved';
      case 'danger':
        return 'Failed to save';
      case 'warning':
        return 'Check your input';
      case 'info':
        return 'Heads up';
      default:
        return 'Notification';
    }
  }

  private messageFor(appearance: KuiToastAppearance): string {
    switch (appearance) {
      case 'success':
        return 'Your changes have been saved.';
      case 'danger':
        return 'Check your connection and try again.';
      case 'warning':
        return 'Some fields still need your attention.';
      case 'info':
        return 'A new version is available.';
      default:
        return 'Something happened.';
    }
  }
}
```

#### basic-toast-example.scss

```scss
.basic-toast-example {
  display: flex;
  flex-wrap: wrap;
  gap: var(--kui-space-3, 12px);
}
```

### toast-action-example

#### toast-action-example.html

```html
<button kuiButton type="button" shape="outline" appearance="danger" (click)="deleteMessage()">
  Delete message
</button>
```

#### toast-action-example.ts

```ts
import { Component, DestroyRef, inject } from '@angular/core';

import { takeUntilDestroyed } from '@angular/core/rxjs-interop';

import { KuiButton, kuiToast } from '@kikita-labs/ui';

@Component({
  selector: 'app-toast-action-example',
  imports: [KuiButton],
  templateUrl: './toast-action-example.html',
  styleUrl: './toast-action-example.scss',
})
export class ToastActionExample {
  private readonly toast = kuiToast();
  private readonly destroyRef = inject(DestroyRef);

  protected deleteMessage(): void {
    const ref = this.toast.open({
      title: 'Message deleted',
      actionLabel: 'Undo',
      duration: 6000,
    });

    ref.action$.pipe(takeUntilDestroyed(this.destroyRef)).subscribe(() => this.undoDelete());
  }

  private undoDelete(): void {
    this.toast.open({ title: 'Delete undone', appearance: 'success' });
  }
}
```

#### toast-action-example.scss

```scss
:host {
  display: block;
}
```

### toast-position-example

#### toast-position-example.html

```html
<div class="toast-position-example">
  @for (position of positions; track position) {
    <button kuiButton type="button" shape="soft" size="sm" (click)="show(position)">
      {{ position }}
    </button>
  }
</div>
```

#### toast-position-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, kuiToast, type KuiToastPosition } from '@kikita-labs/ui';

@Component({
  selector: 'app-toast-position-example',
  imports: [KuiButton],
  templateUrl: './toast-position-example.html',
  styleUrl: './toast-position-example.scss',
})
export class ToastPositionExample {
  private readonly toast = kuiToast();

  protected readonly positions: readonly KuiToastPosition[] = [
    'top-start',
    'top-center',
    'top-end',
    'bottom-start',
    'bottom-center',
    'bottom-end',
  ];

  protected show(position: KuiToastPosition): void {
    this.toast.setPosition(position);
    this.toast.open({
      title: position,
      message: 'This toast opened at the selected position.',
    });
  }
}
```

#### toast-position-example.scss

```scss
.toast-position-example {
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: var(--kui-space-2, 8px);
  max-inline-size: 420px;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| title | string | - | Required headline text passed to open(). |
| message | string \| undefined | - | Optional supporting text below the title. |
| appearance | 'neutral' \| 'success' \| 'warning' \| 'danger' \| 'info' | 'neutral' | Visual intent. Controls the accent bar and icon color; neutral renders no icon. |
| actionLabel | string \| undefined | - | Label for the inline action button. Clicking it emits once on KuiToastRef.action$. |
| duration | number | 5000 | Auto-dismiss delay in ms. Ignored when persistent is true. App-wide default overridable via defaults.toast. |
| persistent | boolean \| Signal<boolean> | false | Keeps the toast open until it is closed explicitly. A signal can start or pause the auto-dismiss timer reactively. |
| closable | boolean | true | Shows the close button. App-wide default overridable via defaults.toast. |
| showIcon | boolean | true | Shows the appearance icon. App-wide default overridable via defaults.toast. |
| showProgress | boolean | false | Shows a progress bar tracking time until auto-dismiss. App-wide default overridable via defaults.toast. |
| kuiToast() | () => KuiToast | - | Inject-function returning a reusable opener bound to the current injector scope. Call once per component; prefer over injecting KuiToast directly. |
| KuiToast.open(config) | (config: KuiToastConfig) => KuiToastRef | - | Shows a toast notification and returns a ref for programmatic control. |
| KuiToast.setPosition(position) | (position: KuiToastPosition) => void | - | Changes the shared toast region position at runtime. Intended for interactive demos; prefer defaults.toast for app-level configuration. |
| KuiToastRef.close() | () => void | - | Closes this toast programmatically and plays the exit animation. |
| KuiToastRef.id | number | - | Stable identifier for this toast within its owning toast service. |
| KuiToastRef.update(config) | (config: Partial<KuiToastConfig>) => void | - | Updates this toast in place and re-evaluates its auto-dismiss timer. |
| KuiToastRef.closed$ | Observable<void> | - | Emits once after the close animation finishes, then completes. |
| KuiToastRef.action$ | Observable<void> | - | Emits once when the action button is clicked, then completes. |
| KuiToast.dismiss(id) | (id: number) => void | - | Dismisses one toast created by this service using its stable reference id. |
| KuiToast.dismissAll() | () => void | - | Dismisses all active toasts created by this service. |
| provideKuiDefaults({ toast }) | (defaults: KuiComponentDefaults) => Provider | - | App or route-level provider for toast defaults: position, duration, maxVisible, showProgress, closable, showIcon and closeIcon. |
| position | 'top-start' \| 'top-center' \| 'top-end' \| 'bottom-start' \| 'bottom-center' \| 'bottom-end' | 'bottom-center' | Global region position. Set app-wide via defaults.toast, or at runtime via KuiToast.setPosition for demos. |
| maxVisible | number | 3 | Max simultaneous toasts, set via defaults.toast. The oldest visible toast is evicted when exceeded. It follows runtime changes of the default. |
| KuiToastOptions | interface | - | Shape of defaults.toast: position, duration, maxVisible, showProgress, closable, showIcon and closeIcon. |

## Accessibility

Rendered documentation, interactive examples, and the playground live at the HTML route above.

## Playground

Available at /components/toast/playground.

---

<!-- route: /components/tooltip -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/tooltip.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/tooltip.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Tooltip

> Hover and focus hint.

- Status: available
- Route: /components/tooltip
- Package: @kikita-labs/ui@2.0.0
- Import: KuiTooltip from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/tooltip.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<button kuiButton [kuiTooltip]="'Save changes'">Save</button>

<button kuiButton [kuiTooltip]="'Delete item'" placement="bottom">Delete</button>
```

The tooltip text is passed as the directive binding value. Empty or whitespace-only strings are ignored, and no tooltip is rendered. `auto` is the default trigger: it uses hover/focus for mouse input and tap for touch input while keeping the tooltip surface and `role="tooltip"`.

For short, non-interactive information triggers, keep the tooltip surface and opt into adaptive tap behavior:

```html
<button
  kuiIconButton
  type="button"
  aria-label="Billing information"
  triggerType="auto"
  [kuiTooltip]="'Your plan renews automatically on the date shown here.'"
>
  <kui-icon name="info" />
</button>
```

Configure the default at application or component scope. The local `triggerType` input takes precedence over the provider:

```ts
// app.config.ts
providers: [
  provideKikitaUi({ defaults: { tooltip: { triggerType: KuiTooltipTriggerType.Auto } } }),
];

// A component or route subtree
providers: [provideKuiDefaults({ tooltip: { triggerType: KuiTooltipTriggerType.Hover } })];
```

Use `providers` when the default should apply to the component's subtree and projected content.
Use `viewProviders` when it should apply only to the component's own view. A nested level merges with
the parent per property, so it can change `triggerType` without resetting other tooltip defaults.

## Examples

Rendered at /components/tooltip:

### basic-tooltip-example

#### basic-tooltip-example.html

```html
<div class="basic-tooltip-example">
  <button kuiButton type="button" [kuiTooltip]="'Save the current draft'">Save</button>
  <button
    kuiButton
    type="button"
    shape="soft"
    [kuiTooltip]="'Open advanced settings'"
    placement="bottom"
  >
    Settings
  </button>
</div>
```

#### basic-tooltip-example.ts

```ts
import { Component } from '@angular/core';

import { KuiButton, KuiTooltip } from '@kikita-labs/ui';

@Component({
  selector: 'app-basic-tooltip-example',
  imports: [KuiButton, KuiTooltip],
  templateUrl: './basic-tooltip-example.html',
  styleUrl: './basic-tooltip-example.scss',
})
export class BasicTooltipExample {}
```

#### basic-tooltip-example.scss

```scss
.basic-tooltip-example {
  display: flex;
  justify-content: center;
  gap: var(--kui-space-3, 12px);
  flex-wrap: wrap;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| [kuiTooltip] | string | '' | Tooltip text content. Empty or whitespace-only text does not render a tooltip. |
| placement | 'top' \| 'bottom' \| 'left' \| 'right' \| undefined | undefined | Preferred placement relative to the trigger (defaults.tooltip.placement, then top). The CDK overlay can still adjust. |
| offset | number \| undefined | undefined | Gap in px between the trigger and the tooltip. Falls back to defaults.tooltip.offset, then 6. A static numeric string is coerced. |
| triggerType | 'auto' \| 'hover' \| 'click' \| 'none' \| undefined | undefined | Local interaction override. auto uses hover/focus for mouse input and tap for touch input. |
| KuiTooltipTriggerType | enum: Auto \| Hover \| Click \| None | Auto | Enum values accepted by triggerType and tooltip provider options. |
| KuiTooltipOptions | interface | - | Shape of defaults.tooltip: triggerType, placement and offset, for app-wide and scoped tooltip defaults. |
| provideKuiDefaults({ tooltip }) | (defaults: KuiComponentDefaults) => Provider | - | Provides merged tooltip defaults for a component or route subtree; a local input wins and each level merges with its parent per property. |
| provideKikitaUi({ defaults: { tooltip } }) | KikitaUiOptions.defaults?: KuiComponentDefaults | - | Sets the root tooltip defaults through the main Kikita UI provider. |
| role | 'tooltip' | 'tooltip' | The floating element is exposed as a tooltip while it exists. |
| aria-describedby | string \| null | null | Applied only while the tooltip is visible, preventing stale removed ids. |
| CSS variables | --kui-tooltip-* | - | Controls padding, radius, colors, and shadow through documented tooltip tokens. |

## Accessibility

- Use a native interactive element, normally a `<button>`, for an information trigger.
- Keep tooltip content short, supplemental, and non-interactive.
- The trigger receives `aria-describedby` only while the tooltip is rendered.
- Tap-open tooltips remain available until the user taps again, moves focus outside, taps outside, or presses Escape.

## Playground

Available at /components/tooltip/playground.

---

<!-- route: /components/tree -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/components/tree.md -->
<!-- source: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/tree.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Tree

> Hierarchical list.

- Status: available
- Route: /components/tree
- Package: @kikita-labs/ui@2.0.0
- Import: KuiTree from @kikita-labs/ui
- Source docs: https://github.com/kikita-labs/kikita-ui/blob/v2.0.0/docs/tree.md

## Install

```bash
pnpm add @kikita-labs/ui
ng add @kikita-labs/ui
```

## Usage

```html
<kui-tree ariaLabel="Project explorer" [data]="nodes" [(value)]="selectedId" />
```

```ts
protected readonly nodes: KuiTreeNode[] = [
  {
    id: 'src',
    label: 'src',
    icon: 'folder',
    children: [
      { id: 'main-ts', label: 'main.ts', icon: 'file' },
      { id: 'readme', label: 'README.md', icon: 'file' },
    ],
  },
];
protected readonly selectedId = signal<string | null>(null);
```

## Examples

Rendered at /components/tree:

### basic-tree-example

#### basic-tree-example.html

```html
<div class="basic-tree-example">
  <kui-tree
    ariaLabel="Project files"
    [data]="nodes"
    [(value)]="selectedId"
    [(expandedIds)]="expandedIds"
  />
</div>
```

#### basic-tree-example.ts

```ts
import { Component, signal } from '@angular/core';

import { KuiTree, type KuiTreeNode } from '@kikita-labs/ui';

const PROJECT_NODES: readonly KuiTreeNode[] = [
  {
    id: 'src',
    label: 'src',
    icon: 'folder',
    children: [
      { id: 'main-ts', label: 'main.ts', icon: 'file' },
      { id: 'styles', label: 'styles', icon: 'folder', children: [] },
    ],
  },
  {
    id: 'docs',
    label: 'docs',
    icon: 'folder',
    children: [{ id: 'readme', label: 'README.md', icon: 'file' }],
  },
];

@Component({
  selector: 'app-basic-tree-example',
  imports: [KuiTree],
  templateUrl: './basic-tree-example.html',
  styleUrl: './basic-tree-example.scss',
})
export class BasicTreeExample {
  protected readonly nodes = PROJECT_NODES;
  protected readonly selectedId = signal<string | null>('main-ts');
  protected readonly expandedIds = signal<string[]>(['src']);
}
```

#### basic-tree-example.scss

```scss
.basic-tree-example {
  display: grid;
  min-width: 0;
  max-width: 24rem;
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| mode | 'display' \| 'checkable' \| undefined | undefined | Selects navigation-style rows or checkbox rows with cascade. Falls back to defaults.tree.mode, then display. |
| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| undefined | undefined | Controls row height and label scale; only sm, md and lg have dedicated styling. Falls back to defaults.tree.size, then the root size, then md. |
| data | readonly KuiTreeNode[] | [] | Root nodes rendered by the tree. |
| ariaLabel | string \| undefined | undefined | Accessible name for the role="tree" container. Falls back to the tree.label message (Tree). |
| mobile | boolean | false | Increases toggle hit targets to support touch layouts. |
| [(value)] | string \| null | null | Controlled selected node id in display mode. |
| [(selected)] | string \| null | null | Deprecated alias for value, kept in sync with it. Use value instead; planned for removal in the next major version. |
| [(checkedIds)] | string[] | [] | Controlled checked node ids in checkable mode. |
| [(expandedIds)] | string[] | [] | Controlled expanded node ids. |
| loadChildren | (node: KuiTreeNode) => Promise<readonly KuiTreeNode[]> | - | Lazy child loader called once for nodes marked lazy. |
| KuiTreeNode.icon | 'folder' \| 'file' | - | Optional built-in glyph. Custom icon templates are not implemented. |
| KuiTreeOptions | interface | - | Shape of defaults.tree: size, mode and disclosureIcon. |

## Accessibility

`role="tree"` on the root, `role="treeitem"` on every node, `role="group"` on
nested children. `aria-expanded` on nodes with children, `aria-selected`
(`display` mode) or `aria-checked` (`checkable` mode, including `"mixed"`),
`aria-level`/`aria-setsize`/`aria-posinset` for depth and position, and
`aria-disabled="true"` on disabled nodes. Exactly one node is in the tab order
(`tabindex="0"`, roving tabindex); the rest are `tabindex="-1"`.

## Playground

Available at /components/tree/playground.

---

<!-- route: /resources/ai-support -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/resources/ai-support.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# AI Support

> Agent-readable docs, llms.txt, and local MCP setup for Kikita UI.

- Status: available
- Route: /resources/ai-support
- Package: @kikita-labs/ui@2.0.0

## Content

### Context files
Use llms.txt for a concise index and llms-full.txt when an agent needs the full public documentation context.
#### agent-context.md

```md
Start with:
https://kikita-labs.github.io/kikita-ui-docs/llms.txt

Use full context only when the curated index is not enough:
https://kikita-labs.github.io/kikita-ui-docs/llms-full.txt
```

### Local MCP
Run the read-only stdio MCP server locally with npx. It exposes package docs, component examples, API sections, search, and prompt templates.
#### mcp.json

```json
{
  "mcpServers": {
    "kikita-ui": {
      "command": "npx",
      "args": ["-y", "@kikita-labs/ui-mcp@latest"]
    }
  }
}
```

### Agent instruction
Give agents a short rule that keeps them on published package APIs and the generated Kikita documentation surface.
#### agent-instructions.md

```md
Use Kikita UI docs through the kikita-ui MCP server.
Prefer package APIs and examples returned by the server.
Do not invent component inputs, outputs, CSS hooks, or imports.
If MCP is unavailable, use https://kikita-labs.github.io/kikita-ui-docs/llms.txt first, then llms-full.txt when full context is needed.
```

### Version boundary
The MCP package is generated from this docs site's installed @kikita-labs/ui version. If the package dependency changes, regenerate the agent surface before publishing docs or MCP data.

---

<!-- route: /resources/smoke -->
<!-- markdown: https://kikita-labs.github.io/kikita-ui-docs/llms/resources/smoke.md -->
<!-- package: @kikita-labs/ui@2.0.0 -->

# Package Smoke

> External consumer verification for package imports, styles, and providers.

- Status: available
- Route: /resources/smoke
- Package: @kikita-labs/ui@2.0.0

## Content

Rendered documentation, interactive examples, and the playground live at the HTML route above.