@kraft.stitch/angular 0.0.3 → 0.0.4-beta.1

package/src/lib/Buttons/split-button/split-button.ts

@@ -0,0 +1,111 @@
+// Side-effect import: registers the `ks-split-button` tag (and its `ks-icon`
+// dependency) — see `button/button.ts` for the full explanation of this
+// pattern (Stencil owns rendering, this class only translates
+// Angular-idiomatic Input/Output into DOM property writes + event listeners).
+import '@kraft.stitch/core/dist/components/ks-split-button.js';
+
+import { ChangeDetectionStrategy, Component, DestroyRef, ElementRef, effect, inject, input, output } from '@angular/core';
+import type { KsBaseSize, KsVariant } from '@kraft.stitch/core';
+
+/**
+ * Mirrors `KsSplitButtonItem` exported by
+ * `core/src/components/Buttons/split-button/split-button.tsx`. Duplicated
+ * locally — see the note in `button-group/button-group.ts` for why.
+ */
+export interface KsSplitButtonItem {
+  key: string;
+  label?: string;
+  /** Icon class string (e.g. ks-icon-pencil) */
+  icon?: string;
+  disabled?: boolean;
+  /** Renders the item in the danger colour */
+  destructive?: boolean;
+  /** Renders a divider line instead of an item */
+  separator?: boolean;
+}
+
+/** DOM shape of the real `<ks-split-button>` custom element, typed for the wrapper. */
+type KsSplitButtonElement = HTMLElement & {
+  label: string;
+  icon: string;
+  variant: KsVariant;
+  size: KsBaseSize;
+  disabled: boolean;
+  items: KsSplitButtonItem[];
+};
+
+/**
+ * Angular wrapper around the `<ks-split-button>` Stencil custom element.
+ *
+ * Outputs are prefixed with `ks` (`ksClick`, `ksItemSelected`) instead of
+ * reusing the native event names `clicked` / `itemSelected` — see
+ * `button/button.ts` for why a same-named output would fire twice.
+ * `template: ''` — the wrapped Stencil `render()` has no `<slot>`.
+ *
+ * @example
+ * ```html
+ * <ks-split-button
+ *   label="Save"
+ *   [items]="items"
+ *   (ksClick)="save()"
+ *   (ksItemSelected)="onSelect($event)"
+ * ></ks-split-button>
+ * ```
+ */
+@Component({
+  selector: 'ks-split-button',
+  standalone: true,
+  template: '',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KsSplitButtonComponent {
+  private readonly el: KsSplitButtonElement;
+
+  /** Main button label */
+  readonly label = input('');
+
+  /** Main button icon class */
+  readonly icon = input('');
+
+  /** Visual style variant */
+  readonly variant = input<KsVariant>('brand');
+
+  /** Size */
+  readonly size = input<KsBaseSize>('md');
+
+  /** Disables both buttons */
+  readonly disabled = input(false);
+
+  /** Menu entries */
+  readonly items = input<KsSplitButtonItem[]>([]);
+
+  /** Emits the `MouseEvent` when the main button is clicked. From the native `clicked` event. */
+  readonly ksClick = output<MouseEvent>();
+
+  /** Emits the selected item's `key`. From the native `itemSelected` event. */
+  readonly ksItemSelected = output<string>();
+
+  constructor(ref: ElementRef<KsSplitButtonElement>) {
+    this.el = ref.nativeElement;
+
+    effect(() => (this.el.label = this.label()));
+    effect(() => (this.el.icon = this.icon()));
+    effect(() => (this.el.variant = this.variant()));
+    effect(() => (this.el.size = this.size()));
+    effect(() => (this.el.disabled = this.disabled()));
+    effect(() => (this.el.items = this.items()));
+
+    const onNativeClicked = (event: Event): void => {
+      this.ksClick.emit((event as CustomEvent<MouseEvent>).detail);
+    };
+    const onNativeItemSelected = (event: Event): void => {
+      this.ksItemSelected.emit((event as CustomEvent<string>).detail);
+    };
+    this.el.addEventListener('clicked', onNativeClicked);
+    this.el.addEventListener('itemSelected', onNativeItemSelected);
+    inject(DestroyRef).onDestroy(() => {
+      this.el.removeEventListener('clicked', onNativeClicked);
+      this.el.removeEventListener('itemSelected', onNativeItemSelected);
+    });
+  }
+}

package/src/lib/Calendars/datepicker/datepicker.ts

@@ -0,0 +1,105 @@
+// Side-effect import: registers the `ks-datepicker` tag — see
+// `button/button.ts` for the full explanation of this pattern.
+import '@kraft.stitch/core/dist/components/ks-datepicker.js';
+
+import { ChangeDetectionStrategy, Component, DestroyRef, ElementRef, effect, inject, input, output } from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+
+/** DOM shape of the real `<ks-datepicker>` custom element, typed for the wrapper. */
+type KsDatepickerElement = HTMLElement & {
+  label: string;
+  placeholder: string;
+  minDate: Date | null;
+  maxDate: Date | null;
+  disabled: boolean;
+  selectedDate: Date | null;
+  writeValue(val: Date | null): Promise<void>;
+};
+
+/**
+ * Angular wrapper around the `<ks-datepicker>` Stencil custom element.
+ *
+ * Two-way binding is via `ControlValueAccessor` — use `[(ngModel)]` or
+ * `formControlName` and it works through DI (`writeValue` /
+ * `registerOnChange`), with no template event-name collision to worry
+ * about. See `chips/chips.ts` for the full rationale (same pattern, same
+ * reason the native `selectedDateChange` event can't be reused verbatim as
+ * an Angular output name).
+ *
+ * For plain (non-forms) two-way use, bind explicitly instead:
+ * `[selectedDate]="d" (ksSelectedDateChange)="d = $event"`.
+ *
+ * `template: ''` — the projected panel content in the Stencil render is
+ * internal (calendar grid projected into the shared `<ks-overlay-field>`
+ * default slot); there is no slot exposed on `<ks-datepicker>` itself for
+ * a consumer to project into.
+ */
+@Component({
+  selector: 'ks-datepicker',
+  standalone: true,
+  template: '',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  providers: [{ provide: NG_VALUE_ACCESSOR, useExisting: KsDatepickerComponent, multi: true }],
+})
+export class KsDatepickerComponent implements ControlValueAccessor {
+  private readonly el: KsDatepickerElement;
+  private onChange: (value: Date | null) => void = () => {};
+  private onTouched: () => void = () => {};
+
+  /** Field label */
+  readonly label = input('');
+
+  /** Placeholder text */
+  readonly placeholder = input('Select date');
+
+  /** Min selectable date */
+  readonly minDate = input<Date | null>(null);
+
+  /** Max selectable date */
+  readonly maxDate = input<Date | null>(null);
+
+  /** Disabled state */
+  readonly disabled = input(false);
+
+  /** Initial/controlled value for plain (non-forms) usage. Prefer `[(ngModel)]` / `formControlName` when inside a form. */
+  readonly selectedDate = input<Date | null>(null);
+
+  /** Emits the newly-picked date. From the native `selectedDateChange` event. */
+  readonly ksSelectedDateChange = output<Date | null>();
+
+  constructor(ref: ElementRef<KsDatepickerElement>) {
+    this.el = ref.nativeElement;
+
+    effect(() => (this.el.label = this.label()));
+    effect(() => (this.el.placeholder = this.placeholder()));
+    effect(() => (this.el.minDate = this.minDate()));
+    effect(() => (this.el.maxDate = this.maxDate()));
+    effect(() => (this.el.disabled = this.disabled()));
+    effect(() => void this.el.writeValue(this.selectedDate()));
+
+    const onNativeSelectedDateChange = (event: Event): void => {
+      const detail = (event as CustomEvent<Date | null>).detail;
+      this.ksSelectedDateChange.emit(detail);
+      this.onChange(detail);
+      this.onTouched();
+    };
+    this.el.addEventListener('selectedDateChange', onNativeSelectedDateChange);
+    inject(DestroyRef).onDestroy(() => this.el.removeEventListener('selectedDateChange', onNativeSelectedDateChange));
+  }
+
+  writeValue(value: Date | null): void {
+    void this.el.writeValue(value ?? null);
+  }
+
+  registerOnChange(fn: (value: Date | null) => void): void {
+    this.onChange = fn;
+  }
+
+  registerOnTouched(fn: () => void): void {
+    this.onTouched = fn;
+  }
+
+  setDisabledState(isDisabled: boolean): void {
+    this.el.disabled = isDisabled;
+  }
+}

package/src/lib/Calendars/daterange/daterange.ts

@@ -0,0 +1,112 @@
+// Side-effect import: registers the `ks-daterange` tag — see
+// `button/button.ts` for the full explanation of this pattern.
+import '@kraft.stitch/core/dist/components/ks-daterange.js';
+
+import { ChangeDetectionStrategy, Component, DestroyRef, ElementRef, effect, inject, input, output } from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+
+/**
+ * Mirrors `KsDateRange` / `KsPresetRange` exported by
+ * `core/src/components/Calendars/daterange/daterange.types.ts`. Duplicated
+ * locally — see the note in `button-group/button-group.ts` for why.
+ */
+export interface KsDateRange {
+  start: Date | null;
+  end: Date | null;
+}
+
+export interface KsPresetRange {
+  label: string;
+  range: () => KsDateRange;
+}
+
+/** DOM shape of the real `<ks-daterange>` custom element, typed for the wrapper. */
+type KsDaterangeElement = HTMLElement & {
+  label: string;
+  placeholder: string;
+  minDate: Date | null;
+  maxDate: Date | null;
+  presets: KsPresetRange[];
+  showPresets: boolean;
+  disabled: boolean;
+  range: KsDateRange;
+  writeValue(val: KsDateRange | null): Promise<void>;
+};
+
+/**
+ * Angular wrapper around the `<ks-daterange>` Stencil custom element.
+ *
+ * Two-way binding is via `ControlValueAccessor` — use `[(ngModel)]` or
+ * `formControlName`. See `chips/chips.ts` for the full rationale (the
+ * native `rangeChange` event can't be reused verbatim as an Angular output
+ * name without a double-fire risk).
+ *
+ * For plain (non-forms) two-way use, bind explicitly instead:
+ * `[range]="r" (ksRangeChange)="r = $event"`.
+ *
+ * `template: ''` — no slot is exposed on `<ks-daterange>` itself.
+ */
+@Component({
+  selector: 'ks-daterange',
+  standalone: true,
+  template: '',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  providers: [{ provide: NG_VALUE_ACCESSOR, useExisting: KsDaterangeComponent, multi: true }],
+})
+export class KsDaterangeComponent implements ControlValueAccessor {
+  private readonly el: KsDaterangeElement;
+  private onChange: (value: KsDateRange) => void = () => {};
+  private onTouched: () => void = () => {};
+
+  readonly label = input('');
+  readonly placeholder = input('Select date range…');
+  readonly minDate = input<Date | null>(null);
+  readonly maxDate = input<Date | null>(null);
+  readonly presets = input<KsPresetRange[]>([]);
+  readonly showPresets = input(true);
+  readonly disabled = input(false);
+
+  /** Initial/controlled value for plain (non-forms) usage. Prefer `[(ngModel)]` / `formControlName` when inside a form. */
+  readonly range = input<KsDateRange>({ start: null, end: null });
+
+  /** Emits the newly-picked range. From the native `rangeChange` event. */
+  readonly ksRangeChange = output<KsDateRange>();
+
+  constructor(ref: ElementRef<KsDaterangeElement>) {
+    this.el = ref.nativeElement;
+
+    effect(() => (this.el.label = this.label()));
+    effect(() => (this.el.placeholder = this.placeholder()));
+    effect(() => (this.el.minDate = this.minDate()));
+    effect(() => (this.el.maxDate = this.maxDate()));
+    effect(() => (this.el.presets = this.presets()));
+    effect(() => (this.el.showPresets = this.showPresets()));
+    effect(() => (this.el.disabled = this.disabled()));
+    effect(() => void this.el.writeValue(this.range()));
+
+    const onNativeRangeChange = (event: Event): void => {
+      const detail = (event as CustomEvent<KsDateRange>).detail;
+      this.ksRangeChange.emit(detail);
+      this.onChange(detail);
+      this.onTouched();
+    };
+    this.el.addEventListener('rangeChange', onNativeRangeChange);
+    inject(DestroyRef).onDestroy(() => this.el.removeEventListener('rangeChange', onNativeRangeChange));
+  }
+
+  writeValue(value: KsDateRange | null): void {
+    void this.el.writeValue(value ?? { start: null, end: null });
+  }
+
+  registerOnChange(fn: (value: KsDateRange) => void): void {
+    this.onChange = fn;
+  }
+
+  registerOnTouched(fn: () => void): void {
+    this.onTouched = fn;
+  }
+
+  setDisabledState(isDisabled: boolean): void {
+    this.el.disabled = isDisabled;
+  }
+}

package/src/lib/Calendars/timepicker/timepicker.ts

@@ -0,0 +1,117 @@
+// Side-effect import: registers the `ks-timepicker` tag — see
+// `button/button.ts` for the full explanation of this pattern.
+import '@kraft.stitch/core/dist/components/ks-timepicker.js';
+
+import { ChangeDetectionStrategy, Component, DestroyRef, ElementRef, effect, inject, input, model, output } from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+
+/**
+ * Mirrors `KsTimeValue` exported by
+ * `core/src/components/Calendars/timepicker/timepicker.tsx`. Duplicated
+ * locally — see the note in `button-group/button-group.ts` for why.
+ */
+export interface KsTimeValue {
+  hours: number;
+  minutes: number;
+  seconds?: number;
+  period?: 'AM' | 'PM';
+}
+
+/** DOM shape of the real `<ks-timepicker>` custom element, typed for the wrapper. */
+type KsTimepickerElement = HTMLElement & {
+  label: string;
+  placeholder: string;
+  use12Hour: boolean;
+  showSeconds: boolean;
+  disabled: boolean;
+  error: string;
+  value: KsTimeValue | null;
+  writeValue(val: KsTimeValue | null): Promise<void>;
+};
+
+/**
+ * Angular wrapper around the `<ks-timepicker>` Stencil custom element.
+ *
+ * Two-way binding is via `ControlValueAccessor` — use `[(ngModel)]` or
+ * `formControlName`. See `chips/chips.ts` for the full rationale (the
+ * native `valueChange` event can't be reused verbatim as an Angular output
+ * name without a double-fire risk).
+ *
+ * For plain (non-forms) two-way use, bind explicitly instead:
+ * `[value]="t" (ksValueChange)="t = $event"`.
+ *
+ * `template: ''` — no slot is exposed on `<ks-timepicker>` itself.
+ */
+@Component({
+  selector: 'ks-timepicker',
+  standalone: true,
+  template: '',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  providers: [{ provide: NG_VALUE_ACCESSOR, useExisting: KsTimepickerComponent, multi: true }],
+})
+export class KsTimepickerComponent implements ControlValueAccessor {
+  private readonly el: KsTimepickerElement;
+  private onChange: (value: KsTimeValue) => void = () => {};
+  private onTouched: () => void = () => {};
+
+  /** Field label */
+  readonly label = input('');
+
+  /** Placeholder */
+  readonly placeholder = input('Select time…');
+
+  /** Use 12-hour clock (AM/PM) */
+  readonly use12Hour = input(false);
+
+  /** Show seconds */
+  readonly showSeconds = input(false);
+
+  /** Disabled */
+  readonly disabled = input(false);
+
+  /** Error message */
+  readonly error = input('');
+
+  /** Initial/controlled value for plain (non-forms) usage. Prefer `[(ngModel)]` / `formControlName` when inside a form. */
+  readonly value = model<KsTimeValue | null>(null);
+
+  /** Emits the confirmed time. From the native `valueChange` event. */
+  readonly ksValueChange = output<KsTimeValue>();
+
+  constructor(ref: ElementRef<KsTimepickerElement>) {
+    this.el = ref.nativeElement;
+
+    effect(() => (this.el.label = this.label()));
+    effect(() => (this.el.placeholder = this.placeholder()));
+    effect(() => (this.el.use12Hour = this.use12Hour()));
+    effect(() => (this.el.showSeconds = this.showSeconds()));
+    effect(() => (this.el.disabled = this.disabled()));
+    effect(() => (this.el.error = this.error()));
+    effect(() => void this.el.writeValue(this.value()));
+
+    const onNativeValueChange = (event: Event): void => {
+      const detail = (event as CustomEvent<KsTimeValue>).detail;
+      this.ksValueChange.emit(detail);
+      this.onChange(detail);
+      this.onTouched();
+    };
+    this.el.addEventListener('valueChange', onNativeValueChange);
+    inject(DestroyRef).onDestroy(() => this.el.removeEventListener('valueChange', onNativeValueChange));
+  }
+
+  writeValue(value: KsTimeValue | null): void {
+    void this.el.writeValue(value ?? null);
+  }
+
+  registerOnChange(fn: (value: KsTimeValue) => void): void {
+    this.onChange = fn;
+  }
+
+  registerOnTouched(fn: () => void): void {
+    this.onTouched = fn;
+  }
+
+  setDisabledState(isDisabled: boolean): void {
+    this.el.disabled = isDisabled;
+  }
+}

package/src/lib/Dropdowns/dropdown/dropdown.ts

@@ -0,0 +1,121 @@
+// Side-effect import: registers the `ks-dropdown` tag — see
+// `button/button.ts` for the full explanation of this pattern.
+import '@kraft.stitch/core/dist/components/ks-dropdown.js';
+
+import { ChangeDetectionStrategy, Component, DestroyRef, ElementRef, effect, inject, input, output } from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+
+/**
+ * Mirrors `KsDropdownOption` exported by
+ * `core/src/components/Dropdowns/dropdown/dropdown.tsx`. Duplicated
+ * locally — see the note in `button-group/button-group.ts` for why.
+ */
+export interface KsDropdownOption {
+  value: string | number;
+  label: string;
+  icon?: string;
+  disabled?: boolean;
+}
+
+export type KsDropdownValue = (string | number)[] | string | number;
+
+/** DOM shape of the real `<ks-dropdown>` custom element, typed for the wrapper. */
+type KsDropdownElement = HTMLElement & {
+  options: KsDropdownOption[];
+  placeholder: string;
+  multi: boolean;
+  searchable: boolean;
+  label: string;
+  disabled: boolean;
+  selectedValues: (string | number)[];
+  writeValue(val: (string | number) | (string | number)[] | null): Promise<void>;
+};
+
+/**
+ * Angular wrapper around the `<ks-dropdown>` Stencil custom element.
+ *
+ * Two-way binding is via `ControlValueAccessor` — use `[(ngModel)]` or
+ * `formControlName`. See `chips/chips.ts` for the full rationale (the
+ * native `selectedValuesChange` event can't be reused verbatim as an
+ * Angular output name without a double-fire risk).
+ *
+ * For plain (non-forms) two-way use, bind explicitly instead:
+ * `[selectedValues]="v" (ksSelectedValuesChange)="v = $event"`.
+ *
+ * `template: ''` — the option list / search box in the Stencil render are
+ * projected into the shared, internal `<ks-overlay-field>` slot; there is
+ * no slot exposed on `<ks-dropdown>` itself for a consumer to project into.
+ */
+@Component({
+  selector: 'ks-dropdown',
+  standalone: true,
+  template: '',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  providers: [{ provide: NG_VALUE_ACCESSOR, useExisting: KsDropdownComponent, multi: true }],
+})
+export class KsDropdownComponent implements ControlValueAccessor {
+  private readonly el: KsDropdownElement;
+  private onChange: (value: KsDropdownValue) => void = () => {};
+  private onTouched: () => void = () => {};
+
+  /** Full list of options */
+  readonly options = input<KsDropdownOption[]>([]);
+
+  /** Placeholder text shown when nothing is selected */
+  readonly placeholder = input('Select…');
+
+  /** Allow selecting multiple options */
+  readonly multi = input(false);
+
+  /** Show a search box inside the dropdown */
+  readonly searchable = input(false);
+
+  /** Field label */
+  readonly label = input('');
+
+  /** Disabled state */
+  readonly disabled = input(false);
+
+  /** Initial/controlled selected value(s) for plain (non-forms) usage. Prefer `[(ngModel)]` / `formControlName` when inside a form. */
+  readonly selectedValues = input<(string | number)[]>([]);
+
+  /** Emits the new selection — an array when `multi`, otherwise a single value. From the native `selectedValuesChange` event. */
+  readonly ksSelectedValuesChange = output<KsDropdownValue>();
+
+  constructor(ref: ElementRef<KsDropdownElement>) {
+    this.el = ref.nativeElement;
+
+    effect(() => (this.el.options = this.options()));
+    effect(() => (this.el.placeholder = this.placeholder()));
+    effect(() => (this.el.multi = this.multi()));
+    effect(() => (this.el.searchable = this.searchable()));
+    effect(() => (this.el.label = this.label()));
+    effect(() => (this.el.disabled = this.disabled()));
+    effect(() => void this.el.writeValue(this.selectedValues()));
+
+    const onNativeSelectedValuesChange = (event: Event): void => {
+      const detail = (event as CustomEvent<KsDropdownValue>).detail;
+      this.ksSelectedValuesChange.emit(detail);
+      this.onChange(detail);
+      this.onTouched();
+    };
+    this.el.addEventListener('selectedValuesChange', onNativeSelectedValuesChange);
+    inject(DestroyRef).onDestroy(() => this.el.removeEventListener('selectedValuesChange', onNativeSelectedValuesChange));
+  }
+
+  writeValue(value: KsDropdownValue | null): void {
+    void this.el.writeValue(value ?? null);
+  }
+
+  registerOnChange(fn: (value: KsDropdownValue) => void): void {
+    this.onChange = fn;
+  }
+
+  registerOnTouched(fn: () => void): void {
+    this.onTouched = fn;
+  }
+
+  setDisabledState(isDisabled: boolean): void {
+    this.el.disabled = isDisabled;
+  }
+}

package/src/lib/Dropdowns/listbox/listbox.ts

@@ -0,0 +1,116 @@
+// Side-effect import: registers the `ks-listbox` tag — see
+// `button/button.ts` for the full explanation of this pattern.
+import '@kraft.stitch/core/dist/components/ks-listbox.js';
+
+import { ChangeDetectionStrategy, Component, DestroyRef, ElementRef, effect, inject, input, output } from '@angular/core';
+import { ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';
+
+/**
+ * Mirrors `KsListBoxOption` exported by
+ * `core/src/components/Dropdowns/listbox/listbox.tsx`. Duplicated locally
+ * — see the note in `button-group/button-group.ts` for why.
+ */
+export interface KsListBoxOption {
+  value: string | number;
+  label: string;
+  icon?: string;
+  disabled?: boolean;
+  /** Optional group key — used when `groupBy` is enabled */
+  group?: string;
+}
+
+export type KsListBoxValue = (string | number)[] | string | number;
+
+/** DOM shape of the real `<ks-listbox>` custom element, typed for the wrapper. */
+type KsListBoxElement = HTMLElement & {
+  options: KsListBoxOption[];
+  multi: boolean;
+  searchable: boolean;
+  disabled: boolean;
+  selected: (string | number)[];
+  groupBy: boolean;
+  writeValue(val: (string | number) | (string | number)[] | null): Promise<void>;
+};
+
+/**
+ * Angular wrapper around the `<ks-listbox>` Stencil custom element.
+ *
+ * Two-way binding is via `ControlValueAccessor` — use `[(ngModel)]` or
+ * `formControlName`. See `chips/chips.ts` for the full rationale (the
+ * native `selectedChange` event can't be reused verbatim as an Angular
+ * output name without a double-fire risk).
+ *
+ * For plain (non-forms) two-way use, bind explicitly instead:
+ * `[selected]="v" (ksSelectedChange)="v = $event"`.
+ *
+ * `template: ''` — no slot is exposed on `<ks-listbox>` itself.
+ */
+@Component({
+  selector: 'ks-listbox',
+  standalone: true,
+  template: '',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  providers: [{ provide: NG_VALUE_ACCESSOR, useExisting: KsListBoxComponent, multi: true }],
+})
+export class KsListBoxComponent implements ControlValueAccessor {
+  private readonly el: KsListBoxElement;
+  private onChange: (value: KsListBoxValue) => void = () => {};
+  private onTouched: () => void = () => {};
+
+  /** Options list */
+  readonly options = input<KsListBoxOption[]>([]);
+
+  /** Allow multi-select */
+  readonly multi = input(false);
+
+  /** Show search box */
+  readonly searchable = input(false);
+
+  /** Disabled */
+  readonly disabled = input(false);
+
+  /** Enable group headers using the `group` field on each option */
+  readonly groupBy = input(false);
+
+  /** Initial/controlled selected value(s) for plain (non-forms) usage. Prefer `[(ngModel)]` / `formControlName` when inside a form. */
+  readonly selected = input<(string | number)[]>([]);
+
+  /** Emits the new selection — an array when `multi`, otherwise a single value. From the native `selectedChange` event. */
+  readonly ksSelectedChange = output<KsListBoxValue>();
+
+  constructor(ref: ElementRef<KsListBoxElement>) {
+    this.el = ref.nativeElement;
+
+    effect(() => (this.el.options = this.options()));
+    effect(() => (this.el.multi = this.multi()));
+    effect(() => (this.el.searchable = this.searchable()));
+    effect(() => (this.el.disabled = this.disabled()));
+    effect(() => (this.el.groupBy = this.groupBy()));
+    effect(() => void this.el.writeValue(this.selected()));
+
+    const onNativeSelectedChange = (event: Event): void => {
+      const detail = (event as CustomEvent<KsListBoxValue>).detail;
+      this.ksSelectedChange.emit(detail);
+      this.onChange(detail);
+      this.onTouched();
+    };
+    this.el.addEventListener('selectedChange', onNativeSelectedChange);
+    inject(DestroyRef).onDestroy(() => this.el.removeEventListener('selectedChange', onNativeSelectedChange));
+  }
+
+  writeValue(value: KsListBoxValue | null): void {
+    void this.el.writeValue(value ?? null);
+  }
+
+  registerOnChange(fn: (value: KsListBoxValue) => void): void {
+    this.onChange = fn;
+  }
+
+  registerOnTouched(fn: () => void): void {
+    this.onTouched = fn;
+  }
+
+  setDisabledState(isDisabled: boolean): void {
+    this.el.disabled = isDisabled;
+  }
+}