@kouji-ui/components 0.1.1

package/src/combobox/_examples/combobox.async.example.ts

@@ -0,0 +1,85 @@
+import { Component, signal, effect, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjComboboxComponent,
+  KjComboboxOptionComponent,
+  KjComboboxLoadingComponent,
+  KjComboboxEmptyComponent,
+} from '../combobox';
+
+const ALL_USERS = [
+  { id: 1, name: 'Ada Lovelace' },
+  { id: 2, name: 'Alan Turing' },
+  { id: 3, name: 'Brian Kernighan' },
+  { id: 4, name: 'Dennis Ritchie' },
+  { id: 5, name: 'Donald Knuth' },
+  { id: 6, name: 'Edsger Dijkstra' },
+  { id: 7, name: 'Grace Hopper' },
+  { id: 8, name: 'Ken Thompson' },
+  { id: 9, name: 'Linus Torvalds' },
+  { id: 10, name: 'Margaret Hamilton' },
+];
+
+/**
+ * Async / consumer-driven search example — debounced fetch with loading
+ * and empty states. Shows the pattern of `[shouldFilter]="false"` plus a
+ * `(queryChange)` handler that performs the filter / fetch.
+ */
+@Component({
+  selector: 'kj-combobox-async-example',
+  standalone: true,
+  imports: [
+    KjComboboxComponent,
+    KjComboboxOptionComponent,
+    KjComboboxLoadingComponent,
+    KjComboboxEmptyComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-combobox
+      [(value)]="user"
+      [(query)]="query"
+      [shouldFilter]="false"
+      [loading]="loading()"
+      placeholder="Search users…"
+    >
+      @for (u of results(); track u.id) {
+        <kj-combobox-option [value]="u.name">{{ u.name }}</kj-combobox-option>
+      }
+      <kj-combobox-loading>Searching…</kj-combobox-loading>
+      <kj-combobox-empty>No users found.</kj-combobox-empty>
+    </kj-combobox>
+  `,
+})
+export class KjComboboxAsyncExample {
+  readonly user = signal<string | null>(null);
+  readonly query = signal('');
+  readonly loading = signal(false);
+  readonly results = signal<typeof ALL_USERS>([]);
+
+  private timer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor() {
+    effect(() => {
+      const q = this.query();
+      if (this.timer) clearTimeout(this.timer);
+      if (!q) {
+        this.results.set([]);
+        this.loading.set(false);
+        return;
+      }
+      this.loading.set(true);
+      this.timer = setTimeout(() => {
+        const needle = q.toLowerCase();
+        this.results.set(ALL_USERS.filter((u) => u.name.toLowerCase().includes(needle)));
+        this.loading.set(false);
+      }, 250);
+    });
+  }
+}

package/src/combobox/_examples/combobox.empty-state.example.ts

@@ -0,0 +1,36 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjComboboxComponent,
+  KjComboboxOptionComponent,
+  KjComboboxEmptyComponent,
+} from '../combobox';
+
+/**
+ * Combobox with an empty-state slot — when the typed query matches nothing
+ * in the option set, the `<kj-combobox-empty>` slot is announced (role
+ * status, aria-live polite) instead of an empty list.
+ */
+@Component({
+  selector: 'kj-combobox-empty-state-example',
+  standalone: true,
+  imports: [KjComboboxComponent, KjComboboxOptionComponent, KjComboboxEmptyComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-combobox [(value)]="fruit" placeholder="Try typing 'xyz'…">
+      <kj-combobox-option [value]="'apple'">Apple</kj-combobox-option>
+      <kj-combobox-option [value]="'banana'">Banana</kj-combobox-option>
+      <kj-combobox-option [value]="'cherry'">Cherry</kj-combobox-option>
+      <kj-combobox-empty>No fruit matches your search.</kj-combobox-empty>
+    </kj-combobox>
+  `,
+})
+export class KjComboboxEmptyStateExample {
+  readonly fruit = signal<string | null>(null);
+}

package/src/combobox/_examples/combobox.example.ts

@@ -0,0 +1,36 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjComboboxComponent, KjComboboxOptionComponent } from '../combobox';
+
+/**
+ * Default usage example for KjComboboxComponent — country picker with
+ * synchronous filtering.
+ */
+@Component({
+  selector: 'kj-combobox-example',
+  standalone: true,
+  imports: [KjComboboxComponent, KjComboboxOptionComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-combobox [(value)]="country" placeholder="Search countries…">
+      <kj-combobox-option [value]="'fr'">France</kj-combobox-option>
+      <kj-combobox-option [value]="'de'">Germany</kj-combobox-option>
+      <kj-combobox-option [value]="'es'">Spain</kj-combobox-option>
+      <kj-combobox-option [value]="'it'">Italy</kj-combobox-option>
+      <kj-combobox-option [value]="'pt'">Portugal</kj-combobox-option>
+      <kj-combobox-option [value]="'us'">United States</kj-combobox-option>
+      <kj-combobox-option [value]="'gb'">United Kingdom</kj-combobox-option>
+      <kj-combobox-option [value]="'jp'">Japan</kj-combobox-option>
+      <kj-combobox-option [value]="'br'">Brazil</kj-combobox-option>
+    </kj-combobox>
+  `,
+})
+export class KjComboboxExample {
+  readonly country = signal<string | null>(null);
+}

package/src/combobox/_examples/combobox.free-text.example.ts

@@ -0,0 +1,42 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjComboboxComponent, KjComboboxOptionComponent } from '../combobox';
+
+/**
+ * Free-text combobox — `freeText=true` lets the user commit any typed
+ * string (canonical "tags" / "categories" pattern). Pressing Enter when no
+ * option matches commits the typed string as the value.
+ */
+@Component({
+  selector: 'kj-combobox-free-text-example',
+  standalone: true,
+  imports: [KjComboboxComponent, KjComboboxOptionComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .out {
+        font: 0.875rem var(--kj-font-mono, monospace);
+        margin-top: var(--kj-space-md);
+        color: var(--kj-fg-default);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-combobox
+      [(value)]="tag"
+      [freeText]="true"
+      [autoActivateFirst]="false"
+      placeholder="Type a tag and press Enter…"
+    >
+      <kj-combobox-option [value]="'design'">Design</kj-combobox-option>
+      <kj-combobox-option [value]="'engineering'">Engineering</kj-combobox-option>
+      <kj-combobox-option [value]="'research'">Research</kj-combobox-option>
+    </kj-combobox>
+    <p class="out">Selected: {{ tag() ?? '(none)' }}</p>
+  `,
+})
+export class KjComboboxFreeTextExample {
+  readonly tag = signal<string | null>(null);
+}

package/src/combobox/_examples/combobox.usage.example.ts

@@ -0,0 +1,51 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjComboboxComponent, KjComboboxOptionComponent } from '../combobox';
+
+/**
+ * A walkthrough of the most common combobox usages — synchronous filtering,
+ * a placeholder, two-way binding to a `signal`, and a disabled state.
+ */
+@Component({
+  selector: 'kj-combobox-usage-example',
+  standalone: true,
+  imports: [KjComboboxComponent, KjComboboxOptionComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+      }
+      .row {
+        display: flex;
+        gap: var(--kj-space-md);
+        align-items: center;
+      }
+      code {
+        font: 0.8125rem/1 var(--kj-font-mono, monospace);
+        color: var(--kj-fg-muted);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <kj-combobox [(value)]="framework" placeholder="Pick a framework…">
+        <kj-combobox-option [value]="'angular'">Angular</kj-combobox-option>
+        <kj-combobox-option [value]="'react'">React</kj-combobox-option>
+        <kj-combobox-option [value]="'svelte'">Svelte</kj-combobox-option>
+        <kj-combobox-option [value]="'vue'">Vue</kj-combobox-option>
+      </kj-combobox>
+      <code>{{ framework() ?? '—' }}</code>
+    </div>
+
+    <div class="row">
+      <kj-combobox [disabled]="true" placeholder="Disabled">
+        <kj-combobox-option [value]="'a'">A</kj-combobox-option>
+      </kj-combobox>
+    </div>
+  `,
+})
+export class KjComboboxUsageExample {
+  readonly framework = signal<string | null>('angular');
+}

package/src/combobox/_examples/combobox.with-icons.example.ts

@@ -0,0 +1,49 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjComboboxComponent, KjComboboxOptionComponent } from '../combobox';
+
+/**
+ * Combobox options with leading icons. The option projects arbitrary
+ * content; consumers can prepend a flag, avatar, or status indicator.
+ */
+@Component({
+  selector: 'kj-combobox-with-icons-example',
+  standalone: true,
+  imports: [KjComboboxComponent, KjComboboxOptionComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      .flag {
+        display: inline-block;
+        width: 1.5rem;
+        text-align: center;
+        margin-right: var(--kj-space-sm);
+        font-size: 1rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-combobox [(value)]="lang" placeholder="Pick a language…">
+      <kj-combobox-option [value]="'en'"
+        ><span class="flag" aria-hidden="true">🇬🇧</span>English</kj-combobox-option
+      >
+      <kj-combobox-option [value]="'fr'"
+        ><span class="flag" aria-hidden="true">🇫🇷</span>French</kj-combobox-option
+      >
+      <kj-combobox-option [value]="'de'"
+        ><span class="flag" aria-hidden="true">🇩🇪</span>German</kj-combobox-option
+      >
+      <kj-combobox-option [value]="'es'"
+        ><span class="flag" aria-hidden="true">🇪🇸</span>Spanish</kj-combobox-option
+      >
+      <kj-combobox-option [value]="'jp'"
+        ><span class="flag" aria-hidden="true">🇯🇵</span>Japanese</kj-combobox-option
+      >
+    </kj-combobox>
+  `,
+})
+export class KjComboboxWithIconsExample {
+  readonly lang = signal<string | null>(null);
+}

package/src/combobox/_examples/index.ts

@@ -0,0 +1,8 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjComboboxAsyncExample } from './combobox.async.example';
+export { KjComboboxEmptyStateExample } from './combobox.empty-state.example';
+export { KjComboboxExample } from './combobox.example';
+export { KjComboboxFreeTextExample } from './combobox.free-text.example';
+export { KjComboboxUsageExample } from './combobox.usage.example';
+export { KjComboboxWithIconsExample } from './combobox.with-icons.example';

package/src/combobox/combobox.css

@@ -0,0 +1,101 @@
+@layer kj.component {
+  .kj-combobox {
+    position: relative;
+    display: inline-block;
+    min-width: 16rem;
+  }
+
+  .kj-combobox-input {
+    width: 100%;
+    background: var(--kj-bg-field);
+    color: var(--kj-fg-default);
+    border: var(--kj-border) solid var(--kj-border-default);
+    border-radius: var(--kj-radius-field);
+    padding: var(--kj-space-sm) var(--kj-space-md);
+    font: 0.875rem var(--kj-font-sans);
+  }
+  .kj-combobox-input:focus-visible {
+    outline: 2px solid var(--kj-border-focus);
+    outline-offset: 2px;
+  }
+  .kj-combobox-input[aria-busy="true"] {
+    background-image: linear-gradient(
+      90deg,
+      transparent 0%,
+      var(--kj-bg-surface) 50%,
+      transparent 100%
+    );
+    background-size: 200% 100%;
+    animation: kj-combobox-shimmer 1.4s linear infinite;
+  }
+  .kj-combobox[data-disabled] .kj-combobox-input {
+    opacity: 0.45;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  .kj-combobox-listbox {
+    box-sizing: border-box;
+    min-width: 16rem;
+    width: max-content;
+    background: var(--kj-bg-elevated);
+    border: var(--kj-border) solid var(--kj-border-default);
+    border-radius: var(--kj-radius-field);
+    box-shadow: var(--kj-shadow-md);
+    padding: 4px;
+    max-height: 16rem;
+    overflow: auto;
+    z-index: 100;
+    display: flex;
+    flex-direction: column;
+  }
+  .kj-combobox-listbox[hidden] { display: none; }
+
+  .kj-combobox-option {
+    display: flex;
+    align-items: center;
+    gap: var(--kj-space-sm);
+    width: 100%;
+    text-align: left;
+    padding: var(--kj-space-sm) var(--kj-space-md);
+    border: none;
+    background: transparent;
+    color: var(--kj-fg-default);
+    border-radius: var(--kj-radius-selector);
+    cursor: pointer;
+    font: 0.875rem var(--kj-font-sans);
+  }
+  .kj-combobox-option:hover,
+  .kj-combobox-option[data-active] {
+    background: var(--kj-bg-surface);
+  }
+  .kj-combobox-option[aria-selected="true"] {
+    background: var(--kj-bg-surface);
+    font-weight: 600;
+  }
+  .kj-combobox-option[hidden] { display: none; }
+  .kj-combobox-option[aria-disabled="true"],
+  .kj-combobox-option[disabled] {
+    opacity: 0.45;
+    cursor: not-allowed;
+  }
+
+  .kj-combobox-empty,
+  .kj-combobox-loading {
+    padding: var(--kj-space-md);
+    color: var(--kj-fg-default);
+    opacity: 0.7;
+    font: 0.875rem var(--kj-font-sans);
+    text-align: center;
+  }
+  .kj-combobox-empty[hidden],
+  .kj-combobox-loading[hidden] { display: none; }
+
+  @keyframes kj-combobox-shimmer {
+    0%   { background-position: 200% 0; }
+    100% { background-position: -200% 0; }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .kj-combobox-input[aria-busy="true"] { animation: none; }
+  }
+}

package/src/combobox/combobox.playground.ts

@@ -0,0 +1,90 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjComboboxComponent, KjComboboxOptionComponent } from './combobox';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Knobs cover the placeholder text,
+ * the disabled posture, the free-text + autoActivateFirst behavioural axes,
+ * and the visible option count so users can preview shorter / longer lists.
+ */
+const placeholder = signal('Pick a framework…');
+const optionCount = signal<3 | 5 | 7>(5);
+const disabled = signal(false);
+const freeText = signal(false);
+const autoActivateFirst = signal(false);
+
+const OPTIONS: ReadonlyArray<{ value: string; label: string }> = [
+  { value: 'angular', label: 'Angular' },
+  { value: 'react', label: 'React' },
+  { value: 'vue', label: 'Vue' },
+  { value: 'svelte', label: 'Svelte' },
+  { value: 'solid', label: 'Solid' },
+  { value: 'qwik', label: 'Qwik' },
+  { value: 'lit', label: 'Lit' },
+];
+
+@Component({
+  selector: 'kj-combobox-playground',
+  standalone: true,
+  imports: [KjComboboxComponent, KjComboboxOptionComponent],
+  styles: [`:host { display: block; min-height: 14rem; }`],
+  template: `
+    <kj-combobox
+      [placeholder]="placeholder()"
+      [disabled]="disabled()"
+      [freeText]="freeText()"
+      [autoActivateFirst]="autoActivateFirst()"
+    >
+      @for (opt of visibleOptions(); track opt.value) {
+        <kj-combobox-option [value]="opt.value">{{ opt.label }}</kj-combobox-option>
+      }
+    </kj-combobox>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjComboboxPlaygroundDemo {
+  protected readonly placeholder = placeholder;
+  protected readonly optionCount = optionCount;
+  protected readonly disabled = disabled;
+  protected readonly freeText = freeText;
+  protected readonly autoActivateFirst = autoActivateFirst;
+
+  protected visibleOptions(): typeof OPTIONS {
+    return OPTIONS.slice(0, optionCount());
+  }
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjComboboxPlaygroundDemo,
+  state: {
+    placeholder: placeholder as unknown as ReturnType<typeof signal>,
+    optionCount: optionCount as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+    freeText: freeText as unknown as ReturnType<typeof signal>,
+    autoActivateFirst: autoActivateFirst as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'text', name: 'placeholder', label: 'placeholder' },
+    { kind: 'chips', name: 'optionCount', label: 'options', options: [3, 5, 7] },
+    { kind: 'toggle', name: 'freeText', label: 'free text' },
+    { kind: 'toggle', name: 'autoActivateFirst', label: 'auto-activate first' },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      placeholder: string;
+      optionCount: number;
+      disabled: boolean;
+      freeText: boolean;
+      autoActivateFirst: boolean;
+    };
+    const attrs: string[] = [`placeholder="${s.placeholder}"`];
+    if (s.freeText) attrs.push('[freeText]="true"');
+    if (s.autoActivateFirst) attrs.push('[autoActivateFirst]="true"');
+    if (s.disabled) attrs.push('[disabled]="true"');
+    const options = OPTIONS.slice(0, s.optionCount)
+      .map((o) => `  <kj-combobox-option [value]="'${o.value}'">${o.label}</kj-combobox-option>`)
+      .join('\n');
+    return `<kj-combobox\n  ${attrs.join('\n  ')}\n>\n${options}\n</kj-combobox>`;
+  },
+};

package/src/combobox/combobox.spec.ts

@@ -0,0 +1,111 @@
+import { render, fireEvent } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import {
+  KjComboboxComponent,
+  KjComboboxOptionComponent,
+  KjComboboxEmptyComponent,
+  KjComboboxLoadingComponent,
+} from './combobox';
+
+expect.extend(toHaveNoViolations);
+
+const imports = [
+  KjComboboxComponent,
+  KjComboboxOptionComponent,
+  KjComboboxEmptyComponent,
+  KjComboboxLoadingComponent,
+];
+
+describe('KjComboboxComponent (wrapper)', () => {
+  it('renders an input and a hidden listbox by default', async () => {
+    const { container } = await render(
+      `<kj-combobox [(value)]="val" placeholder="Pick">
+        <kj-combobox-option [value]="'a'">Apple</kj-combobox-option>
+        <kj-combobox-option [value]="'b'">Banana</kj-combobox-option>
+      </kj-combobox>`,
+      { imports, componentProperties: { val: null } },
+    );
+    expect(container.querySelector('input.kj-combobox-input')).toBeTruthy();
+    expect(container.querySelector('.kj-combobox-listbox')).toHaveAttribute('hidden', '');
+  });
+
+  it('typing filters options and clicking commits a value', async () => {
+    const props = { val: null as unknown };
+    const { container, fixture } = await render(
+      `<kj-combobox [(value)]="val">
+        <kj-combobox-option [value]="'apple'">Apple</kj-combobox-option>
+        <kj-combobox-option [value]="'banana'">Banana</kj-combobox-option>
+        <kj-combobox-option [value]="'cherry'">Cherry</kj-combobox-option>
+      </kj-combobox>`,
+      { imports, componentProperties: props },
+    );
+    const input = container.querySelector('input.kj-combobox-input') as HTMLInputElement;
+    fireEvent.focus(input);
+    fireEvent.input(input, { target: { value: 'ban' } });
+
+    const visible = Array.from(container.querySelectorAll('.kj-combobox-option'))
+      .filter(o => !o.hasAttribute('hidden'));
+    expect(visible).toHaveLength(1);
+    expect(visible[0].textContent?.trim()).toBe('Banana');
+
+    fireEvent.click(visible[0]);
+    expect((fixture.componentInstance as { val: unknown }).val).toBe('banana');
+  });
+
+  it('shows the empty slot when nothing matches', async () => {
+    const { container } = await render(
+      `<kj-combobox [(value)]="val">
+        <kj-combobox-option [value]="'a'">Apple</kj-combobox-option>
+        <kj-combobox-empty>No fruit found.</kj-combobox-empty>
+      </kj-combobox>`,
+      { imports, componentProperties: { val: null } },
+    );
+    const input = container.querySelector('input.kj-combobox-input') as HTMLInputElement;
+    fireEvent.focus(input);
+    fireEvent.input(input, { target: { value: 'zzz' } });
+    const empty = container.querySelector('.kj-combobox-empty') as HTMLElement;
+    expect(empty).not.toHaveAttribute('hidden');
+    expect(empty.textContent).toContain('No fruit found.');
+  });
+
+  it('shows the loading slot when loading=true', async () => {
+    const { container } = await render(
+      `<kj-combobox [loading]="true">
+        <kj-combobox-loading>Searching…</kj-combobox-loading>
+      </kj-combobox>`,
+      { imports },
+    );
+    const loading = container.querySelector('.kj-combobox-loading');
+    expect(loading).not.toHaveAttribute('hidden');
+    expect(container.querySelector('input.kj-combobox-input'))
+      .toHaveAttribute('aria-busy', 'true');
+  });
+
+  it('freeText commits a typed string on Enter when no option is active', async () => {
+    const props = { val: null as unknown };
+    const { container, fixture } = await render(
+      `<kj-combobox [(value)]="val" [freeText]="true" [autoActivateFirst]="false">
+        <kj-combobox-option [value]="'a'">Alpha</kj-combobox-option>
+      </kj-combobox>`,
+      { imports, componentProperties: props },
+    );
+    const input = container.querySelector('input.kj-combobox-input') as HTMLInputElement;
+    fireEvent.focus(input);
+    fireEvent.input(input, { target: { value: 'custom-tag' } });
+    fireEvent.keyDown(input, { key: 'Enter' });
+    expect((fixture.componentInstance as { val: unknown }).val).toBe('custom-tag');
+  });
+
+  it('passes axe audit when open', async () => {
+    const { container } = await render(
+      `<kj-combobox [(value)]="val" placeholder="Search">
+        <kj-combobox-option [value]="'a'">Apple</kj-combobox-option>
+        <kj-combobox-option [value]="'b'">Banana</kj-combobox-option>
+      </kj-combobox>`,
+      { imports, componentProperties: { val: null } },
+    );
+    const input = container.querySelector('input.kj-combobox-input') as HTMLInputElement;
+    fireEvent.focus(input);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});