@kouji-ui/core 0.0.4 → 0.1.1

package/src/color-picker/color-picker.utils.ts

@@ -0,0 +1,140 @@
+/**
+ * Color-model conversion helpers used by `KjColorPicker`.
+ *
+ * The picker keeps its canonical state in HSV+alpha — every other
+ * representation is derived from these via the helpers in this module.
+ *
+ * @internal
+ */
+
+/** Clamp `n` into the inclusive `[lo, hi]` range. */
+export function kjClamp(n: number, lo: number, hi: number): number {
+  return n < lo ? lo : n > hi ? hi : n;
+}
+
+/** Round to `digits` decimal places without floating-point ugliness. */
+export function kjRound(n: number, digits = 0): number {
+  const f = Math.pow(10, digits);
+  return Math.round(n * f) / f;
+}
+
+/** Pad a non-negative integer to two lowercase hex digits. */
+function toHex2(n: number): string {
+  const v = kjClamp(Math.round(n), 0, 255);
+  return v.toString(16).padStart(2, '0');
+}
+
+export interface KjRgb {
+  r: number; // 0..255
+  g: number; // 0..255
+  b: number; // 0..255
+  a: number; // 0..1
+}
+
+export interface KjHsv {
+  h: number; // 0..360
+  s: number; // 0..1
+  v: number; // 0..1
+  a: number; // 0..1
+}
+
+export interface KjHsl {
+  h: number; // 0..360
+  s: number; // 0..1
+  l: number; // 0..1
+  a: number; // 0..1
+}
+
+/**
+ * Convert HSV (with alpha) to RGB. Algorithm follows the standard
+ * formulation from Smith 1978 / W3C CSS Color spec.
+ */
+export function kjHsvToRgb(hsv: KjHsv): KjRgb {
+  const h = ((hsv.h % 360) + 360) % 360;
+  const s = kjClamp(hsv.s, 0, 1);
+  const v = kjClamp(hsv.v, 0, 1);
+  const c = v * s;
+  const hp = h / 60;
+  const x = c * (1 - Math.abs((hp % 2) - 1));
+  let r = 0, g = 0, b = 0;
+  if (hp < 1)      { r = c; g = x; }
+  else if (hp < 2) { r = x; g = c; }
+  else if (hp < 3) { g = c; b = x; }
+  else if (hp < 4) { g = x; b = c; }
+  else if (hp < 5) { r = x; b = c; }
+  else             { r = c; b = x; }
+  const m = v - c;
+  return {
+    r: kjRound((r + m) * 255),
+    g: kjRound((g + m) * 255),
+    b: kjRound((b + m) * 255),
+    a: kjClamp(hsv.a, 0, 1),
+  };
+}
+
+/** Convert RGB (0..255) to HSV. */
+export function kjRgbToHsv(rgb: KjRgb): KjHsv {
+  const r = kjClamp(rgb.r, 0, 255) / 255;
+  const g = kjClamp(rgb.g, 0, 255) / 255;
+  const b = kjClamp(rgb.b, 0, 255) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const d = max - min;
+  let h = 0;
+  if (d !== 0) {
+    if (max === r)      h = ((g - b) / d) % 6;
+    else if (max === g) h = (b - r) / d + 2;
+    else                h = (r - g) / d + 4;
+    h *= 60;
+    if (h < 0) h += 360;
+  }
+  const s = max === 0 ? 0 : d / max;
+  const v = max;
+  return { h, s, v, a: kjClamp(rgb.a, 0, 1) };
+}
+
+/** Convert HSV to HSL. */
+export function kjHsvToHsl(hsv: KjHsv): KjHsl {
+  const v = kjClamp(hsv.v, 0, 1);
+  const s = kjClamp(hsv.s, 0, 1);
+  const l = v * (1 - s / 2);
+  const sl = (l === 0 || l === 1) ? 0 : (v - l) / Math.min(l, 1 - l);
+  return { h: ((hsv.h % 360) + 360) % 360, s: sl, l, a: kjClamp(hsv.a, 0, 1) };
+}
+
+/** Format an RGB triple plus alpha as a `#rrggbb` or `#rrggbbaa` string. */
+export function kjRgbToHex(rgb: KjRgb, includeAlpha: boolean): string {
+  const base = '#' + toHex2(rgb.r) + toHex2(rgb.g) + toHex2(rgb.b);
+  if (!includeAlpha) return base;
+  return base + toHex2(rgb.a * 255);
+}
+
+/**
+ * Parse a hex color string. Accepts `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`
+ * with or without the leading `#`. Returns `null` on invalid input.
+ */
+export function kjParseHex(input: string): KjRgb | null {
+  if (typeof input !== 'string') return null;
+  let s = input.trim().toLowerCase();
+  if (s.startsWith('#')) s = s.slice(1);
+  if (!/^[0-9a-f]+$/.test(s)) return null;
+
+  let r: string, g: string, b: string, a = 'ff';
+  if (s.length === 3) {
+    r = s[0] + s[0]; g = s[1] + s[1]; b = s[2] + s[2];
+  } else if (s.length === 4) {
+    r = s[0] + s[0]; g = s[1] + s[1]; b = s[2] + s[2]; a = s[3] + s[3];
+  } else if (s.length === 6) {
+    r = s.slice(0, 2); g = s.slice(2, 4); b = s.slice(4, 6);
+  } else if (s.length === 8) {
+    r = s.slice(0, 2); g = s.slice(2, 4); b = s.slice(4, 6); a = s.slice(6, 8);
+  } else {
+    return null;
+  }
+  return {
+    r: parseInt(r, 16),
+    g: parseInt(g, 16),
+    b: parseInt(b, 16),
+    a: parseInt(a, 16) / 255,
+  };
+}

package/src/color-picker/index.ts

@@ -0,0 +1,28 @@
+export {
+  KjColorPicker,
+  KjColorPickerTrigger,
+  KjColorPickerPanel,
+  KjColorPickerArea,
+  KjColorPickerHueSlider,
+  KjColorPickerAlphaSlider,
+  KjColorPickerInput,
+} from './color-picker';
+
+export {
+  KJ_COLOR_PICKER,
+  type KjColorFormat,
+  type KjColorPickerContext,
+  type KjColorPreset,
+  type KjColorValue,
+} from './color-picker.context';
+
+export {
+  kjParseHex,
+  kjRgbToHex,
+  kjRgbToHsv,
+  kjHsvToRgb,
+  kjHsvToHsl,
+  type KjRgb,
+  type KjHsv,
+  type KjHsl,
+} from './color-picker.utils';

package/src/combobox/combobox-input.ts

@@ -0,0 +1,143 @@
+import {
+  afterNextRender,
+  Directive,
+  ElementRef,
+  OnDestroy,
+  OnInit,
+  inject,
+} from '@angular/core';
+import { KjDisabled, KjFocusRing, KjFormControl } from '../primitives';
+import { KjOverlayTrigger } from '../primitives/overlay/trigger';
+import type { KjOverlayPanel } from '../primitives/overlay/panel';
+import { KjOverlayController } from '../primitives/overlay/controller';
+import {
+  KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,
+  KJ_OVERLAY_PANEL_ROLE,
+} from '../primitives/overlay/tokens';
+import { onFocusOrInput } from '../primitives/overlay/strategies/trigger-event/on-focus-or-input';
+import { KjListNavigator } from '../primitives/list';
+import { KjCombobox } from './combobox-root';
+
+/**
+ * Decorates a native `<input>` to act as the combobox trigger. Composes the
+ * overlay primitive `KjOverlayTrigger` (wires `aria-expanded`,
+ * `aria-controls`, `aria-haspopup`) and `KjListNavigator` (APG combobox 1.2
+ * keyboard contract: ArrowUp/Down/Home/End/PageUp/PageDown/Enter/Space).
+ * Provides an `onFocusOrInput()` trigger event strategy so the panel opens
+ * both on focus and on the first keystroke.
+ *
+ * Adds a free-text Enter handler that fires only when the navigator had no
+ * active item (signaled via `e.defaultPrevented === false` after the
+ * navigator's host listener runs first).
+ *
+ * Keyboard contract:
+ * - ArrowDown / ArrowUp: move active option (handled by KjListNavigator).
+ * - Enter: commit active option (KjListNavigator); or free-text query when no
+ *   active item and `kjFreeText=true`.
+ * - Escape: close the listbox.
+ *
+ * @doc-category Core/Inputs
+ */
+@Directive({
+  selector: 'input[kjComboboxInput]',
+  exportAs: 'kjComboboxInput',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjDisabled, inputs: ['kjDisabled'] },
+    KjFocusRing,
+    KjFormControl,
+    { directive: KjOverlayTrigger, inputs: ['kjOpen'] },
+    KjListNavigator,
+  ],
+  providers: [
+    { provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY, useFactory: () => onFocusOrInput() },
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'listbox' as const },
+  ],
+  host: {
+    'role': 'combobox',
+    'autocomplete': 'off',
+    'autocapitalize': 'off',
+    'autocorrect': 'off',
+    'spellcheck': 'false',
+    '[attr.aria-autocomplete]': '"list"',
+    '[attr.aria-busy]': 'ctx.loading() ? "true" : null',
+    '[value]': 'ctx.query()',
+    '(input)': 'onInput($event)',
+    '(click)': 'onClick()',
+    '(keydown.enter)': 'onEnter($event)',
+    '(keydown.escape)': 'onEscape($event)',
+    '(keydown.alt.arrowdown)': '$event.preventDefault(); ctx.show()',
+    '(keydown.alt.arrowup)': '$event.preventDefault(); ctx.hide()',
+    '(keydown.tab)': 'ctx.open() && ctx.hide()',
+  },
+})
+export class KjComboboxInput implements OnInit, OnDestroy {
+  /** @internal */
+  readonly ctx = inject(KjCombobox);
+  private readonly el = inject<ElementRef<HTMLInputElement>>(ElementRef);
+  private readonly nav = inject(KjListNavigator);
+
+  /** @internal — public so sibling `[kjFor]` panels can read it. */
+  readonly controller = inject(KjOverlayController);
+
+  constructor() {
+    afterNextRender(() => {
+      this.ctx.setInputElement(this.el.nativeElement);
+    });
+  }
+
+  ngOnInit(): void {
+    this.ctx._setNavigator(this.nav);
+  }
+
+  ngOnDestroy(): void {
+    this.ctx.setInputElement(null);
+    this.ctx._setNavigator(null);
+  }
+
+  /** @internal */
+  onInput(e: Event): void {
+    const v = (e.target as HTMLInputElement).value;
+    this.ctx.setQuery(v);
+  }
+
+  /**
+   * Re-open the listbox on click. The `onFocusOrInput` trigger strategy
+   * opens on first focus; after a commit-close, focus typically stays
+   * on the input so no new focus event fires. A click here reopens
+   * without requiring the user to blur + refocus first.
+   */
+  onClick(): void {
+    if (!this.ctx.open()) this.ctx.show();
+  }
+
+  /**
+   * Handle Enter for free-text fallback. `KjListNavigator`'s host listener
+   * fires first (hostDirectives run before consumer host listeners). When the
+   * navigator had an active item it called `preventDefault()` and committed it
+   * — we exit early. Otherwise this is the no-active-item case — commit the
+   * query only when `kjFreeText` is enabled.
+   */
+  onEnter(e: Event): void {
+    if (e.defaultPrevented) return;
+    if (this.ctx.open() || this.ctx.allowFreeText()) {
+      if (this.ctx.allowFreeText()) {
+        e.preventDefault();
+        this.ctx.select(this.ctx.query());
+      }
+    }
+  }
+
+  /** @internal */
+  onEscape(e: Event): void {
+    if (this.ctx.open()) {
+      e.preventDefault();
+      this.ctx.hide();
+    }
+  }
+
+  private readonly _overlayTrigger = inject(KjOverlayTrigger, { self: true });
+  attachPanel(panel: KjOverlayPanel): void {
+    this._overlayTrigger.attachPanel(panel);
+  }
+}

package/src/combobox/combobox-listbox.ts

@@ -0,0 +1,49 @@
+import { Directive, inject, input } from '@angular/core';
+import { KjOverlayPanel } from '../primitives/overlay/panel';
+import {
+  KJ_OVERLAY_MOUNT_STRATEGY,
+  KJ_OVERLAY_POSITION_STRATEGY,
+  KJ_OVERLAY_PANEL_ROLE,
+} from '../primitives/overlay/tokens';
+import type { KjSide, KjAlign } from '../primitives/overlay/types';
+import { bodyPortal } from '../primitives/overlay/strategies/mount/body-portal';
+import { anchoredTo } from '../primitives/overlay/strategies/position/anchored-to';
+import { KjCombobox } from './combobox-root';
+
+/**
+ * The popup listbox that contains [kjComboboxOption] children. Composes the
+ * overlay primitive `KjOverlayPanel` for mount + position + role wiring; the
+ * panel is portalled into `<body>` and anchored beneath the input via the
+ * `anchoredTo()` strategy. `role="listbox"` and the `[hidden]` attribute are
+ * driven by `KjOverlayPanel`.
+ *
+ * @doc-category Core/Inputs
+ */
+@Directive({
+  selector: '[kjComboboxListbox]',
+  standalone: true,
+  hostDirectives: [{ directive: KjOverlayPanel, inputs: ['kjFor'] }],
+  providers: [
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'listbox' as const },
+    { provide: KJ_OVERLAY_MOUNT_STRATEGY, useFactory: () => bodyPortal() },
+    { provide: KJ_OVERLAY_POSITION_STRATEGY, useFactory: () => anchoredTo() },
+  ],
+  host: {
+    '(mousedown)': '$event.preventDefault()',
+  },
+})
+export class KjComboboxListbox {
+  /** @internal */
+  readonly ctx = inject(KjCombobox);
+
+  readonly kjSide = input<KjSide>('bottom');
+  readonly kjAlign = input<KjAlign>('start');
+  readonly kjOffset = input<number, unknown>(4, {
+    transform: v => Number(v) || 4,
+  });
+
+  constructor() {
+    const pos = inject(KJ_OVERLAY_POSITION_STRATEGY) as ReturnType<typeof anchoredTo>;
+    pos.configure({ side: this.kjSide, align: this.kjAlign, offset: this.kjOffset, matchTriggerWidth: 'min' });
+  }
+}

package/src/combobox/combobox-option.ts

@@ -0,0 +1,43 @@
+import { computed, Directive, inject } from '@angular/core';
+import { KjListItem, injectListItem } from '../primitives/list';
+import { KjCombobox } from './combobox-root';
+
+/**
+ * One option inside the combobox listbox. Composes `KjListItem` for
+ * id/value/label/disabled, activation (click + Enter/Space), and the
+ * shared selection toggle. Post-selection side-effects (close overlay,
+ * set query, emit commit) are run by `KjCombobox.afterSelect`, called
+ * from `KjListItem` — this directive only contributes the option role,
+ * the `kjOption*` input aliases, and the `aria-activedescendant`-driven
+ * `data-active` styling hook.
+ *
+ * @doc-category Core/Inputs
+ */
+@Directive({
+  selector: '[kjComboboxOption]',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjListItem,
+      inputs: [
+        'kjItemValue:kjOptionValue',
+        'kjItemLabel:kjOptionLabel',
+        'kjItemKeywords:kjOptionKeywords',
+      ],
+    },
+  ],
+  host: {
+    'class': 'kj-combobox-option',
+    'role': 'option',
+    '[attr.data-active]': 'isActive() ? "" : null',
+  },
+})
+export class KjComboboxOption {
+  private readonly item     = injectListItem<unknown>();
+  private readonly combobox = inject(KjCombobox);
+
+  /** Whether this option is the currently active (aria-activedescendant) item. */
+  readonly isActive = computed(() =>
+    this.combobox.activeId() !== null && this.combobox.activeId() === this.item.id,
+  );
+}

package/src/combobox/combobox-root.ts

@@ -0,0 +1,281 @@
+import {
+  Directive,
+  booleanAttribute,
+  computed,
+  contentChildren,
+  effect,
+  forwardRef,
+  inject,
+  input,
+  linkedSignal,
+  model,
+  output,
+  signal,
+  untracked,
+  type Signal,
+  type WritableSignal,
+} from '@angular/core';
+import { KjDisabled } from '../primitives';
+import { KjOverlayController } from '../primitives/overlay/controller';
+import {
+  KJ_LIST_NAVIGATOR_CONFIG,
+  KjFilterableList,
+  KjListItem,
+  KjListNavigator,
+  KjSelectionModel,
+  type KjFilterFn,
+  type KjListNavigatorConfig,
+  type KjListSelectionMode,
+} from '../primitives/list';
+
+let _idCounter = 0;
+const nextId = (): string => `kj-combobox-${++_idCounter}`;
+
+/** Default substring filter — case-insensitive contains match. */
+export const kjContainsFilter = (query: string, label: string): boolean => {
+  if (!query) return true;
+  return label.toLowerCase().includes(query.toLowerCase());
+};
+
+/** Case-insensitive prefix match. */
+export const kjStartsWithFilter = (query: string, label: string): boolean => {
+  if (!query) return true;
+  return label.toLowerCase().startsWith(query.toLowerCase());
+};
+
+/**
+ * Root combobox / autocomplete container. Provides
+ * KJ_LIST_NAVIGATOR_CONFIG via contentChildren(KjListItem),
+ * KjSelectionModel (single mode), KjFilterableList, and the shared
+ * KjOverlayController. Children (`KjComboboxInput`, `KjComboboxListbox`,
+ * `KjComboboxOption`) inject `KjCombobox` directly.
+ *
+ * Compound shape — pair with [kjComboboxInput], [kjComboboxListbox] and
+ * [kjComboboxOption]:
+ *
+ * ```html
+ * <div kjCombobox [(kjValue)]="country" [(kjQuery)]="q">
+ *   <input kjComboboxInput placeholder="Search countries" />
+ *   <div kjComboboxListbox>
+ *     <button kjComboboxOption [kjOptionValue]="'fr'">France</button>
+ *     <button kjComboboxOption [kjOptionValue]="'de'">Germany</button>
+ *   </div>
+ * </div>
+ * ```
+ *
+ * @doc-category Core/Inputs
+ */
+@Directive({
+  selector: '[kjCombobox]',
+  standalone: true,
+  exportAs: 'kjCombobox',
+  hostDirectives: [{ directive: KjDisabled, inputs: ['kjDisabled'] }],
+  providers: [
+    { provide: KJ_LIST_NAVIGATOR_CONFIG, useExisting: forwardRef(() => KjCombobox) },
+    KjSelectionModel,
+    KjFilterableList,
+    KjOverlayController,
+  ],
+  host: {
+    '[attr.data-state]': "open() ? 'open' : 'closed'",
+  },
+})
+export class KjCombobox implements KjListNavigatorConfig {
+  /** The currently selected value. Two-way bindable. */
+  readonly kjValue = model<unknown>(null);
+
+  /**
+   * Implements `KjListNavigatorConfig.value`. The selection model reads
+   * and writes through this same signal — one source of truth.
+   */
+  readonly value = this.kjValue as unknown as WritableSignal<
+    unknown | readonly unknown[] | null
+  >;
+
+  /** Implements `KjListNavigatorConfig.mode`. Combobox is always single. */
+  readonly mode: Signal<KjListSelectionMode> = signal('single');
+
+  /** The current query string typed into the input. Two-way bindable. */
+  // eslint-disable-next-line @angular-eslint/no-input-rename -- alias keeps the public `kjQuery` name distinct from this internal linkedSignal-backed property
+  readonly kjQueryInput = input<string>('', { alias: 'kjQuery' });
+  readonly kjQuery: WritableSignal<string> = linkedSignal(this.kjQueryInput);
+
+  /** Whether the directive should run its built-in synchronous filter. Default `true`. */
+  readonly kjShouldFilter = input(true, { transform: booleanAttribute });
+
+  /** Whether the consumer is currently fetching options. Reflects `aria-busy` on the input. */
+  readonly kjLoading = input(false, { transform: booleanAttribute });
+
+  /** Whether free-text values (not from the option set) may be committed. */
+  readonly kjFreeText = input(false, { transform: booleanAttribute });
+
+  /** Filter function used for synchronous filtering. Default {@link kjContainsFilter}. */
+  readonly kjFilter = input<(query: string, label: string) => boolean>(kjContainsFilter);
+
+  /** Whether the first matching option is auto-activated as the user types. Default `true`. */
+  readonly kjAutoActivateFirst = input(true, { transform: booleanAttribute });
+
+  /** Emitted with the new query on every keystroke. */
+  readonly kjQueryChange = output<string>();
+
+  /** Emitted on commit (option selected, free-text submitted). */
+  readonly kjCommit = output<unknown>();
+
+  private readonly controller = inject(KjOverlayController);
+  private readonly filter     = inject(KjFilterableList);
+  private readonly _selection = inject(KjSelectionModel);
+
+  /** Implements `KjListNavigatorConfig.compareBy`. */
+  readonly compareBy = signal((a: unknown, b: unknown) => Object.is(a, b));
+
+  /** Stable listbox id for `aria-controls` wiring. */
+  readonly listboxId = nextId();
+
+  /** All `KjListItem`s under this combobox — source for nav + filter. */
+  readonly items = contentChildren(KjListItem, { descendants: true });
+
+  /** Filter-aware visible items, exposed for KjListNavigatorConfig. */
+  readonly visibleItems = computed(
+    () => this.filter.visibleItems() as readonly KjListItem<unknown>[],
+  );
+
+  /** Public surface read by children. */
+  readonly query         = this.kjQuery.asReadonly();
+  readonly open          = this.controller.isOpen;
+  readonly loading       = this.kjLoading;
+  readonly allowFreeText = this.kjFreeText;
+  readonly shouldFilter  = this.kjShouldFilter;
+  readonly visibleCount  = computed(() => this.filter.visibleCount());
+
+  private readonly _inputEl = signal<HTMLElement | null>(null);
+  readonly inputElement = this._inputEl.asReadonly();
+
+  /** @internal — set by KjComboboxInput's lifecycle. Signal so auto-activate
+   *  effects can re-run when the navigator becomes available. */
+  private readonly _nav = signal<KjListNavigator | null>(null);
+  _setNavigator(n: KjListNavigator | null): void { this._nav.set(n); }
+
+  /** Currently active descendant id (or null). */
+  readonly activeId = computed(() => this._nav()?.activeId() ?? null);
+
+  /** Adapts the consumer `(query, label) => boolean` shape into the
+   *  primitive's `KjFilterFn` shape. Derived; no effect/setter needed. */
+  private readonly adaptedFilter = computed<KjFilterFn>(() => {
+    const userFn = this.kjFilter();
+    return (q, hs) => (hs.some(h => userFn(q, h)) ? 1 : 0);
+  });
+
+  constructor() {
+    this.filter.bind({
+      items:             this.items,
+      query:             this.kjQuery,
+      filterFn:          this.adaptedFilter,
+      shouldFilter:      this.kjShouldFilter,
+      autoActivateFirst: this.kjAutoActivateFirst,
+    });
+    this._selection.bind({
+      value:     this.value,
+      items:     this.items,
+      mode:      this.mode,
+      compareBy: this.compareBy,
+    });
+    effect(() => this.kjQueryChange.emit(this.kjQuery()));
+
+    // Auto-activate first visible item on query change so Enter can
+    // commit it without an explicit ArrowDown press. APG combobox 1.2
+    // discoverability pattern.
+    effect(() => {
+      this.kjQuery();
+      const autoFirst = this.kjAutoActivateFirst();
+      const nav = this._nav();
+      if (!autoFirst || !nav) return;
+      untracked(() => {
+        const visible = this.filter.visibleItems() as readonly KjListItem<unknown>[];
+        nav.setActive(visible.length ? visible[0].id : null);
+      });
+    });
+
+    // Seed the active item once the navigator attaches (input mounts).
+    effect(() => {
+      const nav = this._nav();
+      if (!nav || !this.kjAutoActivateFirst()) return;
+      if (nav.activeId() !== null) return;
+      untracked(() => {
+        const visible = this.filter.visibleItems() as readonly KjListItem<unknown>[];
+        if (visible.length > 0) nav.setActive(visible[0].id);
+      });
+    });
+
+    // Seed `kjQuery` from the selected item's label whenever the input
+    // would otherwise render blank. Covers the case where `kjValue` is
+    // bound up-front (preset) but no query text has been typed yet.
+    effect(() => {
+      const items = this.items();
+      const v = this.kjValue();
+      if (v === null || v === undefined) return;
+      if (this.kjQuery() !== '') return;
+      untracked(() => {
+        const match = items.find(i => i.value() === v);
+        if (match) this.kjQuery.set(match.label());
+      });
+    });
+  }
+
+  setQuery(value: string): void {
+    if (this.kjQuery() !== value) this.kjQuery.set(value);
+    this.controller.open();
+  }
+
+  /**
+   * Programmatic select used by `commitActive()` (Enter on the input
+   * with a navigator-active item) and the free-text Enter fallback in
+   * `KjComboboxInput`. Sets the value through the shared signal, then
+   * runs the same post-selection side-effects `afterSelect()` runs for
+   * option clicks — keeping both paths converged.
+   */
+  select(value: unknown): void {
+    this.kjValue.set(value);
+    this._finishSelect(value);
+  }
+
+  /**
+   * Implements `KjListNavigatorConfig.afterSelect`. Called by
+   * `KjListItem` after it toggles the shared selection model, so option
+   * clicks / Enter / Space don't need a per-option `activate.subscribe`.
+   */
+  afterSelect(value: unknown, closeRequested: boolean): void {
+    if (!closeRequested) return;
+    this._finishSelect(value);
+  }
+
+  private _finishSelect(value: unknown): void {
+    this.controller.close('programmatic');
+    // Reflect the chosen item's label in the input so the combobox
+    // reads as a picker (e.g. "France") instead of leaving the user's
+    // typed query text behind. Matches the autocomplete UX of
+    // `kj-select`.
+    const match = this.items().find(i => i.value() === value);
+    this.kjQuery.set(match ? match.label() : String(value ?? ''));
+    this.kjCommit.emit(value);
+  }
+
+  show():   void { this.controller.open(); }
+  hide():   void { this.controller.close('programmatic'); }
+  toggle(): void { this.controller.toggle(); }
+
+  move(delta: 1 | -1): void {
+    if (!this.controller.isOpen()) this.controller.open();
+    this._nav()?.moveBy(delta);
+  }
+
+  commitActive(): void {
+    const item = this._nav()?.activeItem();
+    if (item && !item.disabled()) {
+      const v = item.value();
+      if (v !== undefined) { this.select(v); return; }
+    }
+    if (this.kjFreeText()) this.select(this.kjQuery());
+  }
+
+  setInputElement(el: HTMLElement | null): void { this._inputEl.set(el); }
+}