@kouji-ui/components 0.1.1

package/src/combobox/combobox.ts

@@ -0,0 +1,219 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  booleanAttribute,
+  inject,
+  input,
+} from '@angular/core';
+import {
+  KjCombobox,
+  KjComboboxInput,
+  KjComboboxListbox,
+  KjComboboxOption,
+} from '@kouji-ui/core';
+
+/**
+ * Combobox / autocomplete root component.
+ *
+ * A typeable input bound to a filterable listbox. The default mode runs a
+ * synchronous case-insensitive substring filter against the projected
+ * `<kj-combobox-option>` children. Set `[shouldFilter]="false"` and bind
+ * `(queryChange)` for async / consumer-driven flows. Set `[freeText]="true"`
+ * to let the user commit arbitrary typed values that are not in the option
+ * set (e.g. a tags input).
+ *
+ * @doc-example Default — country picker
+ *   Country picker with built-in synchronous substring filtering.
+ *   @doc-file combobox.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common combobox usages — sync filtering,
+ *   placeholder, value binding, and disabled.
+ *   @doc-file combobox.usage.example.ts
+ * @doc-example Async search
+ *   Consumer-driven filtering via `(queryChange)` for remote results.
+ *   @doc-file combobox.async.example.ts
+ * @doc-example Free-text values
+ *   `[freeText]="true"` accepts arbitrary typed input not in the option set.
+ *   @doc-file combobox.free-text.example.ts
+ * @doc-example Empty state
+ *   `<kj-combobox-empty>` slot for the "no matches" message.
+ *   @doc-file combobox.empty-state.example.ts
+ * @doc-example With icons
+ *   Each option projects a leading icon next to the label text.
+ *   @doc-file combobox.with-icons.example.ts
+ *
+ * @doc-keyboard
+ *   ArrowDown        — Opens the listbox; moves to the next option when open
+ *   ArrowUp          — Moves to the previous option (wraps at the top)
+ *   Home|End         — Jumps to the first / last visible option
+ *   Enter            — Selects the active option (or commits the typed value when `freeText`)
+ *   Escape           — Closes the listbox and clears the active option
+ *   Tab              — Closes the listbox and continues focus
+ *   Printable keys   — Filter the listbox in real-time
+ *
+ * @doc-aria
+ *   role="combobox"    — On the input (via `[kjComboboxInput]`)
+ *   aria-haspopup      — "listbox" on the input
+ *   aria-expanded      — Reflects open / closed state
+ *   aria-controls      — Links the input to the listbox id
+ *   aria-activedescendant — Tracks the currently-active option without moving DOM focus
+ *   aria-busy          — Reflected on the input when `[loading]="true"`
+ *   role="option"      — On each `<kj-combobox-option>`
+ *   aria-selected      — Mirrors which option matches the committed value
+ *
+ * @doc-css-var
+ *   --kj-bg-field         — Input background. Inherited from the theme.
+ *   --kj-border-default   — Input and listbox border color.
+ *   --kj-bg-elevated      — Listbox panel background.
+ *   --kj-radius-field     — Input and listbox corner radius.
+ *
+ * @doc-touch
+ *   The input grows with its container — pair with a `lg` size from your form
+ *   row for ≥ 44px touch height. Options reach 44px via padding plus the
+ *   inline-text-link exception inside the listbox.
+ *
+ * @doc-a11y
+ *   The combobox follows the WAI-ARIA Combobox + Listbox pattern. The input
+ *   keeps focus; the active option is tracked via `aria-activedescendant`
+ *   without moving DOM focus into the listbox. The listbox auto-mounts to
+ *   `document.body` to escape clipping and re-anchors to the input. The
+ *   `<kj-combobox-empty>` slot uses `role="status"` with `aria-live="polite"`
+ *   so screen readers announce the no-results state.
+ *
+ * @doc-related select,command-palette,field
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name combobox
+ * @doc-description Themed autocomplete combobox with built-in filtering, async search support, and free-text mode.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-combobox',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjCombobox,
+      inputs: [
+        'kjValue: value',
+        'kjQuery: query',
+        'kjShouldFilter: shouldFilter',
+        'kjLoading: loading',
+        'kjFreeText: freeText',
+        'kjFilter: filter',
+        'kjAutoActivateFirst: autoActivateFirst',
+      ],
+      outputs: [
+        'kjValueChange: valueChange',
+        'kjQueryChange: queryChange',
+        'kjCommit: commit',
+      ],
+    },
+  ],
+  imports: [KjComboboxInput, KjComboboxListbox],
+  template: `
+    <input
+      kjComboboxInput
+      #trig="kjComboboxInput"
+      class="kj-combobox-input"
+      [placeholder]="placeholder()"
+      [disabled]="disabled() || null" />
+    <div kjComboboxListbox [kjFor]="trig" class="kj-combobox-listbox">
+      <ng-content />
+    </div>
+  `,
+  styleUrl: './combobox.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    'class': 'kj-combobox',
+    '[attr.data-disabled]': "disabled() ? '' : null",
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjComboboxComponent {
+  /** Placeholder text shown in the input when empty. */
+  readonly placeholder = input<string>('');
+  /** Whether the combobox is disabled. */
+  readonly disabled = input(false, { transform: booleanAttribute });
+}
+
+/**
+ * Single combobox option. Project as a child of `<kj-combobox>`.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name combobox
+ */
+@Component({
+  selector: 'kj-combobox-option',
+  standalone: true,
+  imports: [KjComboboxOption],
+  template: `<button type="button" kjComboboxOption [kjOptionValue]="value()" class="kj-combobox-option" [disabled]="disabled() || null"><ng-content /></button>`,
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjComboboxOptionComponent {
+  /** Value committed when this option is selected. */
+  readonly value = input.required<unknown>();
+  /** Whether this option is disabled. */
+  readonly disabled = input(false, { transform: booleanAttribute });
+}
+
+/**
+ * Empty-state slot rendered when no options match the query. Place inside
+ * `<kj-combobox>`.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name combobox
+ */
+@Component({
+  selector: 'kj-combobox-empty',
+  standalone: true,
+  template: `<ng-content />`,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    'class': 'kj-combobox-empty',
+    'role': 'status',
+    'aria-live': 'polite',
+    '[attr.hidden]': 'shouldShow() ? null : ""',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjComboboxEmptyComponent {
+  private readonly cb = inject(KjCombobox);
+  /** @internal */
+  shouldShow(): boolean {
+    return this.cb.open()
+      && !this.cb.loading()
+      && this.cb.visibleCount() === 0
+      && this.cb.query().length > 0;
+  }
+}
+
+/**
+ * Loading-state slot rendered while `loading=true`. Place inside `<kj-combobox>`.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name combobox
+ */
+@Component({
+  selector: 'kj-combobox-loading',
+  standalone: true,
+  template: `<ng-content />`,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    'class': 'kj-combobox-loading',
+    'role': 'status',
+    'aria-live': 'polite',
+    '[attr.hidden]': 'cb.loading() ? null : ""',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjComboboxLoadingComponent {
+  /** @internal */
+  readonly cb = inject(KjCombobox);
+}

package/src/combobox/index.ts

@@ -0,0 +1,6 @@
+export {
+  KjComboboxComponent,
+  KjComboboxOptionComponent,
+  KjComboboxEmptyComponent,
+  KjComboboxLoadingComponent,
+} from './combobox';

package/src/command-palette/_examples/command-palette.async.example.ts

@@ -0,0 +1,99 @@
+import { Component, effect, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import {
+  KjCommandPaletteComponent,
+  KjCommandItemComponent,
+  KjCommandPaletteItemTemplate,
+} from '../command-palette';
+
+interface SearchResult {
+  id: string;
+  label: string;
+}
+
+const ALL_RESULTS: SearchResult[] = [
+  { id: 'ng-docs', label: 'Angular Documentation' },
+  { id: 'ng-signals', label: 'Angular Signals Guide' },
+  { id: 'ng-forms', label: 'Angular Forms' },
+  { id: 'ng-routing', label: 'Angular Routing' },
+  { id: 'ng-di', label: 'Angular Dependency Injection' },
+];
+
+/**
+ * Async-search pattern using `[kjItems]` + `<ng-template kjCommandPaletteItemTemplate>`.
+ * `kjShouldFilter="false"` delegates filtering to the consumer; results
+ * update after a simulated 300ms delay.
+ */
+@Component({
+  selector: 'kj-command-palette-async-example',
+  standalone: true,
+  imports: [
+    KjCommandPaletteComponent,
+    KjCommandItemComponent,
+    KjCommandPaletteItemTemplate,
+    KjButtonComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+        align-items: flex-start;
+        min-height: 16rem;
+      }
+      .activated {
+        font-family: var(--kj-font-mono);
+        font-size: 0.75rem;
+        color: var(--kj-fg-muted);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjVariant="outline" (click)="open.set(true)">Search Angular docs…</kj-button>
+
+    @if (lastActivated()) {
+      <p class="activated">
+        Activated: <strong>{{ lastActivated() }}</strong>
+      </p>
+    }
+
+    <kj-command-palette
+      [(kjOpen)]="open"
+      [(kjQuery)]="query"
+      [kjShouldFilter]="false"
+      [kjLoading]="loading()"
+      [kjItems]="results()"
+      kjPlaceholder="Search Angular docs…"
+      (kjActivate)="lastActivated.set($any($event).value)"
+    >
+      <ng-template kjCommandPaletteItemTemplate let-result>
+        <kj-command-item [kjValue]="result.id">{{ result.label }}</kj-command-item>
+      </ng-template>
+    </kj-command-palette>
+  `,
+})
+export class KjCommandPaletteAsyncExample {
+  readonly open = signal(false);
+  readonly query = signal('');
+  readonly loading = signal(false);
+  readonly results = signal<SearchResult[]>(ALL_RESULTS);
+  readonly lastActivated = signal<string | null>(null);
+
+  private searchTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor() {
+    effect(() => {
+      const q = this.query();
+      if (this.searchTimer) clearTimeout(this.searchTimer);
+      this.loading.set(true);
+      this.results.set([]);
+      this.searchTimer = setTimeout(() => {
+        const filtered = ALL_RESULTS.filter((r) => r.label.toLowerCase().includes(q.toLowerCase()));
+        this.results.set(filtered);
+        this.loading.set(false);
+      }, 300);
+    });
+  }
+}

package/src/command-palette/_examples/command-palette.dialog.example.ts

@@ -0,0 +1,90 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import {
+  KjCommandPaletteComponent,
+  KjCommandItemComponent,
+  KjCommandGroupComponent,
+  KjCommandSeparatorComponent,
+} from '../command-palette';
+
+/**
+ * Modal command palette with Cmd-K / Ctrl-K hotkey wired in.
+ * Click the trigger button or press the chord to toggle.
+ */
+@Component({
+  selector: 'kj-command-palette-dialog-example',
+  standalone: true,
+  imports: [
+    KjCommandPaletteComponent,
+    KjCommandItemComponent,
+    KjCommandGroupComponent,
+    KjCommandSeparatorComponent,
+    KjButtonComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+        align-items: flex-start;
+        min-height: 16rem;
+      }
+      kbd {
+        border: 1px solid var(--kj-border-default);
+        color: var(--kj-fg-muted);
+        font-family: var(--kj-font-mono);
+        font-size: 0.7rem;
+        padding: 0.1rem 0.35rem;
+        margin-inline-start: var(--kj-space-md);
+      }
+      .activated {
+        font-family: var(--kj-font-mono);
+        font-size: 0.75rem;
+        color: var(--kj-fg-muted);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjVariant="outline" (click)="open.set(true)">
+      Search commands… <kbd>⌘K</kbd>
+    </kj-button>
+
+    @if (lastActivated()) {
+      <p class="activated">
+        Activated: <strong>{{ lastActivated() }}</strong>
+      </p>
+    }
+
+    <kj-command-palette
+      [(kjOpen)]="open"
+      kjHotkey="mod+k"
+      kjPlaceholder="Search commands…"
+      (kjActivate)="onActivate($any($event))"
+    >
+      <kj-command-group kjLabel="Suggestions">
+        <kj-command-item kjValue="calendar">Calendar</kj-command-item>
+        <kj-command-item kjValue="search-emoji">Search Emoji</kj-command-item>
+        <kj-command-item kjValue="calculator">Calculator</kj-command-item>
+      </kj-command-group>
+
+      <kj-command-separator></kj-command-separator>
+
+      <kj-command-group kjLabel="Settings">
+        <kj-command-item kjValue="profile">Profile</kj-command-item>
+        <kj-command-item kjValue="billing">Billing</kj-command-item>
+        <kj-command-item kjValue="settings">Settings</kj-command-item>
+        <kj-command-item kjValue="logout">Logout</kj-command-item>
+      </kj-command-group>
+    </kj-command-palette>
+  `,
+})
+export class KjCommandPaletteDialogExample {
+  readonly open = signal(false);
+  readonly lastActivated = signal<string | null>(null);
+
+  onActivate(event: { value: unknown; query: string }): void {
+    this.lastActivated.set(String(event.value));
+  }
+}

package/src/command-palette/_examples/command-palette.example.ts

@@ -0,0 +1,40 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjCommandPaletteComponent, KjCommandItemComponent } from '../command-palette';
+
+/**
+ * Default modal command palette. Click the trigger button (or use the
+ * `[(kjOpen)]` 2-way binding) to open. Type to filter — items are projected
+ * directly via `<kj-command-item>`.
+ */
+@Component({
+  selector: 'kj-command-palette-example',
+  standalone: true,
+  imports: [KjCommandPaletteComponent, KjCommandItemComponent, KjButtonComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        justify-content: center;
+        min-height: 16rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjVariant="outline" (click)="open.set(true)">Open palette</kj-button>
+
+    <kj-command-palette [(kjOpen)]="open" kjPlaceholder="Search commands…">
+      <kj-command-item kjValue="new-file">New File</kj-command-item>
+      <kj-command-item kjValue="open-folder">Open Folder</kj-command-item>
+      <kj-command-item kjValue="save">Save</kj-command-item>
+      <kj-command-item kjValue="settings">Settings</kj-command-item>
+      <kj-command-item kjValue="toggle-theme">Toggle Theme</kj-command-item>
+      <kj-command-item kjValue="profile">Profile</kj-command-item>
+      <kj-command-item kjValue="logout">Logout</kj-command-item>
+    </kj-command-palette>
+  `,
+})
+export class KjCommandPaletteExample {
+  readonly open = signal(false);
+}

package/src/command-palette/_examples/command-palette.fuzzy.example.ts

@@ -0,0 +1,54 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { kjFuzzyFilter } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjCommandPaletteComponent, KjCommandItemComponent } from '../command-palette';
+
+/**
+ * Modal command palette with a custom fuzzy filter — type abbreviations
+ * to match commands. For example, type `gth` to match "git checkout",
+ * or `tth` for "Toggle Theme".
+ */
+@Component({
+  selector: 'kj-command-palette-fuzzy-example',
+  standalone: true,
+  imports: [KjCommandPaletteComponent, KjCommandItemComponent, KjButtonComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+        align-items: flex-start;
+        min-height: 18rem;
+      }
+      .hint {
+        margin: 0;
+        font-family: var(--kj-font-mono);
+        font-size: 0.75rem;
+        color: var(--kj-fg-muted);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjVariant="outline" (click)="open.set(true)">Open fuzzy palette</kj-button>
+    <p class="hint">Try typing: <code>gth</code>, <code>tth</code>, <code>ofil</code></p>
+
+    <kj-command-palette
+      [(kjOpen)]="open"
+      [kjFilter]="fuzzyFilter"
+      kjPlaceholder="Fuzzy search (try gth)…"
+    >
+      <kj-command-item kjValue="git-checkout">git checkout</kj-command-item>
+      <kj-command-item kjValue="toggle-theme">Toggle Theme</kj-command-item>
+      <kj-command-item kjValue="open-file">Open File</kj-command-item>
+      <kj-command-item kjValue="new-window">New Window</kj-command-item>
+      <kj-command-item kjValue="find-replace">Find and Replace</kj-command-item>
+      <kj-command-item kjValue="format-doc">Format Document</kj-command-item>
+    </kj-command-palette>
+  `,
+})
+export class KjCommandPaletteFuzzyExample {
+  readonly open = signal(false);
+  readonly fuzzyFilter = kjFuzzyFilter;
+}

package/src/command-palette/_examples/command-palette.groups.example.ts

@@ -0,0 +1,55 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import {
+  KjCommandPaletteComponent,
+  KjCommandItemComponent,
+  KjCommandGroupComponent,
+  KjCommandSeparatorComponent,
+} from '../command-palette';
+
+/**
+ * Modal command palette with grouped items. Type to filter — groups with no
+ * matching items hide automatically, including their heading.
+ */
+@Component({
+  selector: 'kj-command-palette-groups-example',
+  standalone: true,
+  imports: [
+    KjCommandPaletteComponent,
+    KjCommandItemComponent,
+    KjCommandGroupComponent,
+    KjCommandSeparatorComponent,
+    KjButtonComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: flex;
+        justify-content: center;
+        min-height: 16rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjVariant="outline" (click)="open.set(true)">Open palette</kj-button>
+
+    <kj-command-palette [(kjOpen)]="open" kjPlaceholder="Search…">
+      <kj-command-group kjLabel="Recent">
+        <kj-command-item kjValue="recent-settings">Settings</kj-command-item>
+        <kj-command-item kjValue="recent-profile">Profile</kj-command-item>
+      </kj-command-group>
+
+      <kj-command-separator></kj-command-separator>
+
+      <kj-command-group kjLabel="Settings">
+        <kj-command-item kjValue="theme">Toggle Theme</kj-command-item>
+        <kj-command-item kjValue="language">Language</kj-command-item>
+        <kj-command-item kjValue="shortcuts">Keyboard Shortcuts</kj-command-item>
+      </kj-command-group>
+    </kj-command-palette>
+  `,
+})
+export class KjCommandPaletteGroupsExample {
+  readonly open = signal(false);
+}

package/src/command-palette/_examples/command-palette.usage.example.ts

@@ -0,0 +1,49 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import {
+  KjCommandPaletteComponent,
+  KjCommandItemComponent,
+  KjCommandGroupComponent,
+} from '../command-palette';
+
+/**
+ * A walkthrough of the most common command-palette usages — a trigger button
+ * that opens the modal, a global Cmd-K hotkey, and grouped command rows.
+ */
+@Component({
+  selector: 'kj-command-palette-usage-example',
+  standalone: true,
+  imports: [
+    KjCommandPaletteComponent,
+    KjCommandItemComponent,
+    KjCommandGroupComponent,
+    KjButtonComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: flex;
+        justify-content: center;
+        min-height: 16rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjVariant="outline" (click)="open.set(true)"> Open palette (or press ⌘K) </kj-button>
+
+    <kj-command-palette [(kjOpen)]="open" kjHotkey="mod+k" kjPlaceholder="Type a command…">
+      <kj-command-group kjLabel="Actions">
+        <kj-command-item kjValue="new-file">New file</kj-command-item>
+        <kj-command-item kjValue="save">Save</kj-command-item>
+      </kj-command-group>
+      <kj-command-group kjLabel="Navigation">
+        <kj-command-item kjValue="settings">Settings</kj-command-item>
+        <kj-command-item kjValue="profile">Profile</kj-command-item>
+      </kj-command-group>
+    </kj-command-palette>
+  `,
+})
+export class KjCommandPaletteUsageExample {
+  readonly open = signal(false);
+}

package/src/command-palette/_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 { KjCommandPaletteAsyncExample } from './command-palette.async.example';
+export { KjCommandPaletteDialogExample } from './command-palette.dialog.example';
+export { KjCommandPaletteExample } from './command-palette.example';
+export { KjCommandPaletteFuzzyExample } from './command-palette.fuzzy.example';
+export { KjCommandPaletteGroupsExample } from './command-palette.groups.example';
+export { KjCommandPaletteUsageExample } from './command-palette.usage.example';