@kouji-ui/core 0.0.3 → 0.1.1

package/src/combobox/combobox.spec.ts

@@ -0,0 +1,75 @@
+import { Component } from '@angular/core';
+import { render } from '@testing-library/angular';
+import { describe, it, expect } from 'vitest';
+import {
+  KjCombobox,
+  KjComboboxInput,
+  KjComboboxListbox,
+  KjComboboxOption,
+} from './combobox';
+
+describe('KjCombobox', () => {
+  it('input has role=combobox and aria-haspopup=listbox', async () => {
+    @Component({
+      selector: 'kj-cb-host',
+      standalone: true,
+      imports: [KjCombobox, KjComboboxInput, KjComboboxListbox, KjComboboxOption],
+      template: `
+        <div kjCombobox>
+          <input kjComboboxInput #t="kjOverlayTrigger" aria-label="Country" />
+          <div kjComboboxListbox [kjFor]="t">
+            <button kjComboboxOption [kjOptionValue]="'fr'">France</button>
+          </div>
+        </div>
+      `,
+    })
+    class Host {}
+    const { container } = await render(Host);
+    const input = container.querySelector('input[kjComboboxInput]')!;
+    expect(input.getAttribute('role')).toBe('combobox');
+    expect(input.getAttribute('aria-haspopup')).toBe('listbox');
+    expect(input.getAttribute('aria-expanded')).toBe('false');
+  });
+
+  it('panel exposes role=listbox', async () => {
+    @Component({
+      selector: 'kj-cb-host',
+      standalone: true,
+      imports: [KjCombobox, KjComboboxInput, KjComboboxListbox, KjComboboxOption],
+      template: `
+        <div kjCombobox>
+          <input kjComboboxInput #t="kjOverlayTrigger" aria-label="Country" />
+          <div kjComboboxListbox [kjFor]="t">
+            <button kjComboboxOption [kjOptionValue]="'fr'">France</button>
+          </div>
+        </div>
+      `,
+    })
+    class Host {}
+    const { container } = await render(Host);
+    const panel = container.querySelector('[kjComboboxListbox]') as HTMLElement;
+    expect(panel.getAttribute('role')).toBe('listbox');
+  });
+
+  it('options carry role=option', async () => {
+    @Component({
+      selector: 'kj-cb-host',
+      standalone: true,
+      imports: [KjCombobox, KjComboboxInput, KjComboboxListbox, KjComboboxOption],
+      template: `
+        <div kjCombobox>
+          <input kjComboboxInput #t="kjOverlayTrigger" aria-label="Country" />
+          <div kjComboboxListbox [kjFor]="t">
+            <button kjComboboxOption [kjOptionValue]="'fr'">France</button>
+            <button kjComboboxOption [kjOptionValue]="'de'">Germany</button>
+          </div>
+        </div>
+      `,
+    })
+    class Host {}
+    const { container } = await render(Host);
+    const opts = container.querySelectorAll('[kjComboboxOption]');
+    expect(opts.length).toBe(2);
+    opts.forEach(o => expect(o.getAttribute('role')).toBe('option'));
+  });
+});

package/src/combobox/combobox.ts

@@ -0,0 +1,4 @@
+export * from './combobox-root';
+export * from './combobox-input';
+export * from './combobox-listbox';
+export * from './combobox-option';

package/src/combobox/index.ts

@@ -0,0 +1,4 @@
+export * from './combobox-root';
+export * from './combobox-input';
+export * from './combobox-listbox';
+export * from './combobox-option';

package/src/command-palette/command-empty.ts

@@ -0,0 +1,36 @@
+import { Directive, computed, inject } from '@angular/core';
+import { KjCommandPalette } from './command-palette';
+
+/**
+ * Slot shown when the palette has no visible items and is not loading.
+ * Sets `role="status"` and `aria-live="polite"` for live-region announcements.
+ * Hidden when items are visible or loading is active.
+ *
+ * @example
+ * ```html
+ * <div kjCommandList>
+ *   <div kjCommandEmpty>No results found.</div>
+ *   <button kjCommandItem>…</button>
+ * </div>
+ * ```
+ * @doc-category Core/Actions
+ * @doc
+ * @doc-name command-palette
+ */
+@Directive({
+  selector: '[kjCommandEmpty]',
+  standalone: true,
+  host: {
+    'role': 'status',
+    'aria-live': 'polite',
+    '[hidden]': 'isHidden()',
+  },
+})
+export class KjCommandEmpty {
+  private readonly ctx = inject(KjCommandPalette);
+
+  /** Hidden unless there are no visible items and loading is false. */
+  readonly isHidden = computed(() =>
+    this.ctx.visibleItems().length > 0 || this.ctx.loading()
+  );
+}

package/src/command-palette/command-group.ts

@@ -0,0 +1,21 @@
+import { Directive } from '@angular/core';
+import { KjListGroup } from '../primitives/list';
+
+/**
+ * Group wrapper for command items. Composes `KjListGroup` for the
+ * shared role=group / aria-labelledby / auto-hide-when-empty behavior;
+ * this selector exists so existing command-palette templates keep
+ * working unchanged.
+ *
+ * Pair with a `[kjListGroupLabel]` heading element for the section title.
+ *
+ * @doc-category Core/Actions
+ * @doc
+ * @doc-name command-palette
+ */
+@Directive({
+  selector: '[kjCommandGroup]',
+  standalone: true,
+  hostDirectives: [KjListGroup],
+})
+export class KjCommandGroup {}

package/src/command-palette/command-input.ts

@@ -0,0 +1,70 @@
+import {
+  Directive,
+  ElementRef,
+  HostListener,
+  OnDestroy,
+  OnInit,
+  inject,
+} from '@angular/core';
+import { KjListNavigator } from '../primitives/list';
+import { KjCommandPalette } from './command-palette';
+
+/**
+ * Search input inside the command palette. Composes `KjListNavigator`
+ * — `aria-activedescendant` and the APG combobox 1.2 keyboard contract
+ * live here, not on the listbox.
+ *
+ * Keyboard contract:
+ * - `ArrowDown` / `ArrowUp` — move active item (handled by `KjListNavigator`)
+ * - `Home` / `End` — jump to first/last (handled by `KjListNavigator`)
+ * - `Enter` — activate active item (handled by `KjListNavigator`)
+ * - `Escape` — first press clears query; second press propagates to dialog
+ *
+ * @doc-category Core/Actions
+ * @doc
+ * @doc-name command-palette
+ */
+@Directive({
+  selector: 'input[kjCommandInput]',
+  standalone: true,
+  exportAs: 'kjCommandInput',
+  hostDirectives: [KjListNavigator],
+  host: {
+    'role': 'combobox',
+    'autocomplete': 'off',
+    'autocorrect': 'off',
+    'spellcheck': 'false',
+    'aria-autocomplete': 'list',
+    'aria-haspopup': 'listbox',
+    '[attr.aria-controls]': 'palette.listId',
+    '[attr.aria-expanded]': '"true"',
+    '[attr.aria-busy]': 'palette.loading() ? "true" : null',
+    '(input)': 'palette.setQuery($any($event.target).value)',
+  },
+})
+export class KjCommandInput implements OnInit, OnDestroy {
+  protected readonly palette = inject(KjCommandPalette);
+  private readonly nav = inject(KjListNavigator);
+  private readonly el = inject<ElementRef<HTMLInputElement>>(ElementRef);
+
+  ngOnInit(): void {
+    this.palette._setNavigator(this.nav);
+  }
+
+  ngOnDestroy(): void {
+    this.palette._setNavigator(null);
+  }
+
+  @HostListener('keydown', ['$event'])
+  onKeydown(event: KeyboardEvent): void {
+    if (event.key === 'Escape') {
+      // First press: clear query. Second press propagates to the dialog.
+      if (this.palette.query()) {
+        event.stopPropagation();
+        this.palette.setQuery('');
+        this.el.nativeElement.value = '';
+      }
+      // If query is already empty, let the event bubble to KjDialog's Escape handler
+    }
+  }
+}

package/src/command-palette/command-item.ts

@@ -0,0 +1,60 @@
+import {
+  Directive,
+  computed,
+  inject,
+} from '@angular/core';
+import { KjListItem, injectListItem } from '../primitives/list';
+import { KjCommandPalette } from './command-palette';
+
+/**
+ * Individual command item (`role="option"`). Composes `KjListItem` for
+ * id / value / label / keywords / disabled / click+keyboard activation.
+ * The activation → `palette.activate(value)` wiring is now handled
+ * centrally by `KjCommandPalette.afterSelect`, called from
+ * `KjListItem` — this directive only contributes role, classes, the
+ * `kj*` input aliases, and the active-item ARIA / data attributes.
+ *
+ * @example
+ * ```html
+ * <div kjCommandPalette>
+ *   <div kjCommandList>
+ *     <button kjCommandItem [kjValue]="'open-settings'">Settings</button>
+ *   </div>
+ * </div>
+ * ```
+ * @doc-category Core/Actions
+ * @doc
+ * @doc-name command-palette
+ */
+@Directive({
+  selector: '[kjCommandItem]',
+  standalone: true,
+  exportAs: 'kjCommandItem',
+  hostDirectives: [
+    {
+      directive: KjListItem,
+      inputs: [
+        'kjItemValue:kjValue',
+        'kjItemLabel:kjLabel',
+        'kjItemKeywords:kjKeywords',
+        'kjShortcut:kjShortcut',
+        'kjDisabled:kjDisabled',
+      ],
+    },
+  ],
+  host: {
+    'class': 'kj-command-item',
+    'role': 'option',
+    '[attr.aria-selected]': 'isActive() ? "true" : "false"',
+    '[attr.data-active]': 'isActive() ? "" : null',
+  },
+})
+export class KjCommandItem {
+  private readonly item    = injectListItem<unknown>();
+  private readonly palette = inject(KjCommandPalette);
+
+  /** Whether this item is the active (highlighted) item. */
+  readonly isActive = computed(() =>
+    this.palette.activeId() !== null && this.palette.activeId() === this.item.id,
+  );
+}

package/src/command-palette/command-list.ts

@@ -0,0 +1,25 @@
+import { Directive, inject } from '@angular/core';
+import { KjCommandPalette } from './command-palette';
+
+/**
+ * Listbox panel for the command palette. Role-only — keyboard nav
+ * lives on `KjCommandInput` per APG combobox 1.2.
+ *
+ * @doc-category Core/Actions
+ * @doc
+ * @doc-name command-palette
+ */
+@Directive({
+  selector: '[kjCommandList]',
+  standalone: true,
+  host: {
+    'role': 'listbox',
+    '[id]': 'palette.listId',
+    'class': 'kj-command-list',
+    '[attr.aria-label]': '"Commands"',
+  },
+})
+export class KjCommandList {
+  /** @internal — for the [id] host binding. */
+  protected readonly palette = inject(KjCommandPalette);
+}

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

@@ -0,0 +1,74 @@
+// command-palette-dialog.ts
+import {
+  Component,
+  ChangeDetectionStrategy,
+  ViewEncapsulation,
+} from '@angular/core';
+import { KjOverlayPanel } from '../primitives/overlay/panel';
+import { KjOverlayController } from '../primitives/overlay/controller';
+import {
+  KJ_OVERLAY_MOUNT_STRATEGY,
+  KJ_OVERLAY_POSITION_STRATEGY,
+  KJ_OVERLAY_BACKDROP_STRATEGY,
+  KJ_OVERLAY_FOCUS_TRAP_STRATEGY,
+  KJ_OVERLAY_SCROLL_LOCK_STRATEGY,
+  KJ_OVERLAY_LIVE_ANNOUNCER_STRATEGY,
+  KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,
+  KJ_OVERLAY_PANEL_ROLE,
+} from '../primitives/overlay/tokens';
+import { bodyPortal } from '../primitives/overlay/strategies/mount/body-portal';
+import { viewportCentered } from '../primitives/overlay/strategies/position/viewport-centered';
+import { solidBackdrop } from '../primitives/overlay/strategies/backdrop/solid';
+import { tabCycle } from '../primitives/overlay/strategies/focus-trap/tab-cycle';
+import { htmlOverflow } from '../primitives/overlay/strategies/scroll-lock/html-overflow';
+import { silent } from '../primitives/overlay/strategies/live-announcer/silent';
+import { programmatic } from '../primitives/overlay/strategies/trigger-event/programmatic';
+
+/**
+ * Modal panel for the command palette (Cmd-K pattern). Composes
+ * `KjOverlayPanel` and provides the modal-list strategy bundle: portalled
+ * mount, viewport-centered position, solid (inert + close-on-click) backdrop,
+ * tab-cycle focus trap with first-focus + return, html-overflow scroll lock,
+ * and a silent live announcer.
+ *
+ * Pair with `[kjCommandPaletteTrigger]` (which supplies an `onHotkey`
+ * trigger-event strategy) for the standard mod+k flow, or use programmatic
+ * open/close via the bound `KjOverlayController`.
+ *
+ * The host element gets `aria-label="Command palette"` and `role="dialog"`.
+ *
+ * @doc-category Core/Actions
+ * @doc
+ * @doc-name command-palette
+ */
+@Component({
+  selector: 'kj-command-palette-dialog',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjOverlayPanel, inputs: ['kjFor'] },
+  ],
+  providers: [
+    KjOverlayController,
+    { provide: KJ_OVERLAY_MOUNT_STRATEGY,    useFactory: () => bodyPortal() },
+    { provide: KJ_OVERLAY_POSITION_STRATEGY, useFactory: () => viewportCentered() },
+    {
+      provide: KJ_OVERLAY_BACKDROP_STRATEGY,
+      useFactory: () => solidBackdrop({ inert: true, closeOnClick: true }),
+    },
+    {
+      provide: KJ_OVERLAY_FOCUS_TRAP_STRATEGY,
+      useFactory: () => tabCycle({ initialFocus: 'first', returnFocus: true }),
+    },
+    { provide: KJ_OVERLAY_SCROLL_LOCK_STRATEGY,    useFactory: () => htmlOverflow() },
+    { provide: KJ_OVERLAY_LIVE_ANNOUNCER_STRATEGY, useFactory: () => silent() },
+    { provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,  useFactory: () => programmatic() },
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'dialog' as const },
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    '[attr.aria-label]': '"Command palette"',
+  },
+  template: `<ng-content />`,
+})
+export class KjCommandPaletteDialog {}

package/src/command-palette/command-palette-trigger.ts

@@ -0,0 +1,64 @@
+// command-palette-trigger.ts
+import { Directive, inject, input } from '@angular/core';
+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 { onHotkey } from '../primitives/overlay/strategies/trigger-event/on-hotkey';
+
+/**
+ * Hotkey-driven trigger for the command palette. Toggles the linked
+ * `<kj-command-palette-dialog>` panel when the configured chord fires
+ * (default `mod+k` — Cmd+K on macOS, Ctrl+K elsewhere).
+ *
+ * Composes `KjOverlayTrigger` via `hostDirectives` and provides an
+ * `onHotkey()` trigger-event strategy (replacing the legacy
+ * `KjCommandPaletteHotkey` directive).
+ *
+ * @example
+ * ```html
+ * <button kjCommandPaletteTrigger #t="kjCommandPaletteTrigger" kjHotkey="mod+k">
+ *   Open palette
+ * </button>
+ * <kj-command-palette-dialog [kjFor]="t">
+ *   <div kjCommandPalette>...</div>
+ * </kj-command-palette-dialog>
+ * ```
+ *
+ * @doc-category Core/Actions
+ */
+@Directive({
+  selector: '[kjCommandPaletteTrigger]',
+  exportAs: 'kjCommandPaletteTrigger',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjOverlayTrigger, inputs: ['kjOpen'] },
+  ],
+  providers: [
+    KjOverlayController,
+    {
+      provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,
+      useFactory: () => onHotkey('mod+k'),
+    },
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'dialog' as const },
+  ],
+})
+export class KjCommandPaletteTrigger {
+  /**
+   * Keyboard chord. `mod` resolves to `Meta` on macOS, `Ctrl` elsewhere.
+   * Captured at provider construction; reactive switching is a follow-up.
+   */
+  readonly kjHotkey = input<string>('mod+k');
+
+  private readonly _overlayTrigger = inject(KjOverlayTrigger, { self: true });
+  /** The controller of the composed `KjOverlayTrigger`, exposed for sibling `[kjFor]` panels. */
+  get controller(): KjOverlayController {
+    return this._overlayTrigger.controller;
+  }
+  attachPanel(panel: KjOverlayPanel): void {
+    this._overlayTrigger.attachPanel(panel);
+  }
+}

package/src/command-palette/command-palette.filters.ts

@@ -0,0 +1,53 @@
+/**
+ * Filter function type for the command palette.
+ * Returns a numeric score: > 0 means the item is visible, 0 means hidden.
+ * Higher scores are more relevant when sorting by score.
+ */
+export type KjCommandFilter = (query: string, haystacks: readonly string[]) => number;
+
+/**
+ * Strip diacritic marks from a string (e.g. `café` → `cafe`).
+ * Uses NFD normalisation followed by removal of Unicode diacritic characters.
+ * Note: locale-naive for v1 (Turkish/German edge cases are documented).
+ */
+export function stripDiacritics(str: string): string {
+  return str.normalize('NFD').replace(/\p{Diacritic}/gu, '');
+}
+
+/**
+ * Default filter: case- and diacritic-insensitive substring match.
+ * Returns score 1 if any haystack contains the needle, 0 otherwise.
+ * Returns 1 for empty queries (all items visible).
+ */
+export const kjSubstringFilter: KjCommandFilter = (query, haystacks) => {
+  if (!query) return 1;
+  const needle = stripDiacritics(query.toLowerCase());
+  return haystacks.some(h => stripDiacritics(h.toLowerCase()).includes(needle)) ? 1 : 0;
+};
+
+/**
+ * Optional fuzzy filter: checks whether all characters of the query appear
+ * in the haystack in order (abbreviation matching).
+ * E.g. `gth` matches `git checkout`.
+ * Returns score 1 if any haystack matches, 0 otherwise.
+ * Returns 1 for empty queries.
+ *
+ * @example
+ * ```html
+ * <div kjCommandPalette [kjFilter]="kjFuzzyFilter">…</div>
+ * ```
+ */
+export const kjFuzzyFilter: KjCommandFilter = (query, haystacks) => {
+  if (!query) return 1;
+  const needle = query.toLowerCase();
+  return haystacks.some(h => {
+    const hay = h.toLowerCase();
+    let i = 0;
+    for (const c of needle) {
+      const j = hay.indexOf(c, i);
+      if (j < 0) return false;
+      i = j + 1;
+    }
+    return true;
+  }) ? 1 : 0;
+};