@kouji-ui/core 0.0.3 → 0.1.1

package/src/primitives/list/item.ts

@@ -0,0 +1,222 @@
+import {
+  AfterContentInit,
+  Directive,
+  ElementRef,
+  booleanAttribute,
+  computed,
+  forwardRef,
+  inject,
+  input,
+  output,
+  signal,
+} from '@angular/core';
+import { KjListNavigator } from './navigator';
+import { KjSelectionModel } from './selection';
+import { KJ_LIST_FOCUS_MODE, KJ_LIST_NAVIGATOR_CONFIG } from './tokens';
+
+let _id = 0;
+
+/**
+ * Behavior primitive for any item rendered inside a listbox / menu / tree.
+ * Composes `KjDisabled`; mints a stable id; exposes value/label/haystacks;
+ * binds `aria-disabled`, `aria-selected` (via injected `KjSelectionModel`),
+ * `aria-posinset`/`aria-setsize` (stamped by `KjFilterableList`), and
+ * `aria-keyshortcuts`. Activation (click / Enter / Space) fires an
+ * `activate` output the consumer subscribes to. Role is set by the
+ * consumer's outer directive — varies per cluster.
+ *
+ * @doc-category Core/Primitives
+ */
+@Directive({
+  selector: '[kjListItem]',
+  exportAs: 'kjListItem',
+  standalone: true,
+  host: {
+    '[hidden]': '!visible()',
+    '[attr.tabindex]': 'tabIndex()',
+    '[attr.aria-disabled]': 'disabled() ? "true" : null',
+    '[attr.data-disabled]': 'disabled() ? "" : null',
+    '[attr.aria-selected]': 'ariaSelected()',
+    '[attr.aria-checked]': 'ariaChecked()',
+    '[attr.aria-posinset]': 'posInSet()',
+    '[attr.aria-setsize]': 'setSize()',
+    '[attr.aria-keyshortcuts]': 'kjShortcut() || null',
+    '(click)': '_activate($event)',
+    '(keydown.enter)': '$event.preventDefault(); _activate($event)',
+    '(keydown.space)': '$event.preventDefault(); _activate($event)',
+  },
+})
+export class KjListItem<T = unknown> implements AfterContentInit {
+  /** Typed value emitted on activation. `undefined` when unset. */
+  readonly kjItemValue    = input<T | undefined>(undefined);
+  /** Display label. Falls back to element text content when empty. */
+  readonly kjItemLabel    = input<string>('');
+  /** Extra search terms merged into `haystacks` for type-ahead / filter matching. */
+  readonly kjItemKeywords = input<readonly string[]>([]);
+  /** ARIA keyboard shortcut string bound to `aria-keyshortcuts`. Omit to suppress the attribute. */
+  readonly kjShortcut     = input<string | null>(null);
+  /**
+   * Disabled flag. Declared as a top-level input (rather than as a
+   * `hostDirective` forward) so consumers that compose `KjListItem`
+   * inside their own `hostDirectives` (`KjOption`, `KjTreeSelectNode`,
+   * …) can re-forward it without falling foul of NG0311. The composed
+   * `KjDisabled` instance follows this signal via an effect below.
+   */
+  readonly kjDisabled     = input<boolean, unknown>(false, { transform: booleanAttribute });
+
+  /** Fires when the item is activated (click / Enter / Space) and not disabled. Emits `value()`. */
+  readonly activate = output<T | undefined>();
+
+  /**
+   * Stable id used by `aria-activedescendant`. Resolved at construction.
+   * Priority: existing host `id` attribute (static markup) → generated
+   * `kj-list-item-N`. To pin an id, write `<el id="my-id" kjListItem>`.
+   */
+  readonly id: string;
+
+  private readonly el = inject(ElementRef<HTMLElement>);
+  readonly disabled = this.kjDisabled;
+
+  /**
+   * Nearest ancestor `KjListItem` resolved via the element injector
+   * (`skipSelf`, `optional`). Surfaces the DOM-nested parent → child
+   * relationship to the selection model, which auto-derives a tree
+   * shape from these pointers when the consumer does not supply one
+   * via `cfg.treeShape`. Flat consumers (e.g. data-driven tree-select)
+   * pass an explicit shape and this pointer is ignored.
+   */
+  readonly parent = inject<KjListItem<unknown> | null>(KjListItem, {
+    skipSelf: true,
+    optional: true,
+  });
+
+  // Optional — only present when this item lives inside a
+  // `[kjListNavigator]` (the common case). Read by `tabIndex()` so the
+  // item can reactively re-bind its host `tabindex` as activeId moves.
+  // forwardRef avoids the navigator <-> item circular reference issue.
+  private readonly navigator = inject<KjListNavigator | null>(
+    forwardRef(() => KjListNavigator),
+    { optional: true },
+  );
+  // Focus mode signal provided by the navigator. Optional: when no
+  // navigator hosts this item, fall back to activedescendant behavior
+  // (always `-1`) — matches the legacy tabindex output.
+  private readonly focusMode = inject(KJ_LIST_FOCUS_MODE, { optional: true });
+
+  constructor() {
+    const host = this.el.nativeElement;
+    this.id = host.id || `kj-list-item-${++_id}`;
+    host.id = this.id;
+  }
+
+  /** @internal Native host element. Used by `KjListNavigator` to call `.focus()` in roving mode. */
+  _host(): HTMLElement {
+    return this.el.nativeElement;
+  }
+
+  /**
+   * Reactive `tabindex` for the host element:
+   * - No navigator / `'activedescendant'`: always `-1` — the navigator
+   *   host owns the Tab stop and signals activation via
+   *   `aria-activedescendant`.
+   * - `'roving'`: `0` for the currently active (focused) item and `-1`
+   *   for the rest. Disabled items are never active because
+   *   `KjListNavigator.navigable` filters them out, so they naturally
+   *   read `-1` here.
+   */
+  readonly tabIndex = computed<string>(() => {
+    const mode = this.focusMode?.();
+    if (mode !== 'roving') return '-1';
+    if (this.disabled()) return '-1';
+    return this.navigator?.activeId() === this.id ? '0' : '-1';
+  });
+
+  private readonly _elText = signal('');
+  readonly value     = computed<T | undefined>(() => this.kjItemValue());
+  readonly label     = computed(() => (this.kjItemLabel() || this._elText()).trim());
+  readonly haystacks = computed<readonly string[]>(() => [this.label(), ...this.kjItemKeywords()]);
+
+  private readonly _visible = signal(true);
+  readonly visible = this._visible.asReadonly();
+  setVisible(v: boolean): void { this._visible.set(v); }
+
+  /**
+   * Position in the visible (filter-aware) set, bound to `aria-posinset`.
+   * Writable for internal use by `KjFilterableList` only; consumers
+   * should treat it as read-only.
+   */
+  readonly posInSet = signal<number | null>(null);
+  /**
+   * Total size of the visible (filter-aware) set, bound to `aria-setsize`.
+   * Writable for internal use by `KjFilterableList` only; consumers
+   * should treat it as read-only.
+   */
+  readonly setSize  = signal<number | null>(null);
+
+  private readonly selection = inject(KjSelectionModel, { optional: true }) as KjSelectionModel<T> | null;
+  private readonly cfg       = inject(KJ_LIST_NAVIGATOR_CONFIG, { optional: true });
+
+  /**
+   * `aria-selected` driven by the injected selection model. `null` when
+   * no model is provided, the value is undefined, or the mode is
+   * `'cascade'` (which uses `aria-checked` instead, per WAI-ARIA tree).
+   */
+  readonly ariaSelected = computed<'true' | 'false' | null>(() => {
+    if (!this.selection) return null;
+    if (this.selection.mode() === 'cascade') return null;
+    const v = this.value();
+    if (v === undefined) return null;
+    return this.selection.isSelected(v) ? 'true' : 'false';
+  });
+
+  /**
+   * `aria-checked` driven by `KjSelectionModel.cascadeState()` when the
+   * mode is `'cascade'`. Returns `'true'` / `'false'` / `'mixed'` per
+   * the WAI-ARIA tree checkbox tri-state pattern. `null` (attribute
+   * omitted) in any other mode.
+   */
+  readonly ariaChecked = computed<'true' | 'false' | 'mixed' | null>(() => {
+    if (!this.selection || this.selection.mode() !== 'cascade') return null;
+    const v = this.value();
+    if (v === undefined) return null;
+    return this.selection.cascadeState(v);
+  });
+
+  ngAfterContentInit(): void {
+    this._elText.set(this.el.nativeElement.textContent ?? '');
+  }
+
+  _activate(event?: Event): void {
+    if (this.disabled()) return;
+    const v = this.value();
+    // Branch gate owned by the selection model: in `'single'` mode
+    // with a tree shape (consumer-supplied or auto-derived from
+    // KjListItem parent DI), non-leaf targets must not commit a value
+    // — they exist purely as disclosure controls (e.g. cascade-select
+    // branch options that only toggle their own sub-panel). Runs
+    // before `stopPropagation` so a blocked click can still reach the
+    // consumer's own host listener.
+    if (v !== undefined && this.selection && !this.selection.canActivate(v)) return;
+    // Stop bubbling so a click on a nested `kjListItem` doesn't also
+    // activate the ancestor item (matters for tree-style consumers
+    // where leaf nodes are rendered inside their parent branch's host
+    // element — without this, the leaf activation would be followed
+    // by the branch's `_activate` overriding the selection).
+    event?.stopPropagation();
+    // Selection toggle + consumer hook live here — not in the option
+    // wrapper — because every list-style cluster that wires a
+    // `KjSelectionModel` repeats the same two steps after activation:
+    // (1) toggle the value, (2) run consumer-specific side-effects
+    // (close the overlay, set an input query, emit a commit event).
+    // Centralizing both removes the per-option `activate.subscribe(...)`
+    // boilerplate. `afterSelect` is invoked even when the toggle was a
+    // no-op (e.g. leaf-mode branch click) so consumers can decide what
+    // counts as "select" — they receive `closeRequested` to gate on.
+    let closeRequested = false;
+    if (this.selection && v !== undefined) {
+      ({ closeRequested } = this.selection.toggle(v));
+    }
+    this.cfg?.afterSelect?.(v, closeRequested);
+    this.activate.emit(v);
+  }
+}

package/src/primitives/list/navigator.spec.ts

@@ -0,0 +1,286 @@
+// packages/core/src/primitives/list/navigator.spec.ts
+import { Component, Directive, contentChildren, forwardRef, signal } from '@angular/core';
+import { By } from '@angular/platform-browser';
+import { render, type RenderResult } from '@testing-library/angular';
+import { describe, it, expect } from 'vitest';
+import { KjListNavigator } from './navigator';
+import { KjListItem } from './item';
+import { KjTypeAhead } from './type-ahead';
+import { KJ_LIST_NAVIGATOR_CONFIG } from './tokens';
+
+/**
+ * Minimal test root that registers child KjListItems into
+ * KJ_LIST_NAVIGATOR_CONFIG via contentChildren — same pattern as
+ * KjSelect / KjCombobox. Used by the focus-mode tests below.
+ */
+@Directive({
+  selector: '[kjTestListRoot]',
+  standalone: true,
+  providers: [
+    { provide: KJ_LIST_NAVIGATOR_CONFIG, useExisting: forwardRef(() => TestListRoot) },
+  ],
+})
+class TestListRoot {
+  readonly items = contentChildren(KjListItem, { descendants: true });
+}
+
+/** Shape that mirrors the parts of KjListItem the navigator reads. */
+function fakeItem(id: string, label: string, disabled = false) {
+  let activated = 0;
+  return {
+    id,
+    label: () => label,
+    disabled: () => disabled,
+    _activate: () => { activated++; },
+    get activated() { return activated; },
+  } as unknown as KjListItem<unknown> & { activated: number; _activate: () => void };
+}
+
+function setup(items: ReturnType<typeof fakeItem>[], opts: { wrap?: boolean; orientation?: 'vertical' | 'horizontal' | 'both' } = {}) {
+  const orientationAttr = opts.orientation ? ` [kjOrientation]="'${opts.orientation}'"` : '';
+  const wrapAttr = opts.wrap === false ? ` [kjWrap]="false"` : '';
+  return render(
+    `<div kjListNavigator${orientationAttr}${wrapAttr}></div>`,
+    {
+      imports: [KjListNavigator],
+      providers: [
+        KjTypeAhead,
+        {
+          provide: KJ_LIST_NAVIGATOR_CONFIG,
+          useValue: { items: signal(items) },
+        },
+      ],
+    },
+  );
+}
+
+/** Dispatch a keydown and flush change detection so host bindings reach the DOM. */
+function press(host: HTMLElement, fixture: RenderResult<unknown>['fixture'], key: string): KeyboardEvent {
+  const e = new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true });
+  host.dispatchEvent(e);
+  fixture.detectChanges();
+  return e;
+}
+
+describe('KjListNavigator', () => {
+  it('starts with no active item', async () => {
+    const { container } = await setup([fakeItem('1', 'A'), fakeItem('2', 'B')]);
+    const host = container.querySelector('[kjListNavigator]')!;
+    expect(host.hasAttribute('aria-activedescendant')).toBe(false);
+  });
+
+  it('ArrowDown moves to next item, wraps past last when kjWrap=true', async () => {
+    const items = [fakeItem('1', 'A'), fakeItem('2', 'B')];
+    const { container, fixture } = await setup(items);
+    const host = container.querySelector('[kjListNavigator]') as HTMLElement;
+    press(host, fixture, 'ArrowDown');
+    expect(host.getAttribute('aria-activedescendant')).toBe('1');
+    press(host, fixture, 'ArrowDown');
+    expect(host.getAttribute('aria-activedescendant')).toBe('2');
+    press(host, fixture, 'ArrowDown');
+    expect(host.getAttribute('aria-activedescendant')).toBe('1');
+  });
+
+  it('ArrowUp wraps to last item from first', async () => {
+    const items = [fakeItem('1', 'A'), fakeItem('2', 'B')];
+    const { container, fixture } = await setup(items);
+    const host = container.querySelector('[kjListNavigator]') as HTMLElement;
+    press(host, fixture, 'ArrowUp');
+    expect(host.getAttribute('aria-activedescendant')).toBe('2');
+  });
+
+  it('skips disabled items during navigation', async () => {
+    const items = [fakeItem('1', 'A'), fakeItem('2', 'B', true), fakeItem('3', 'C')];
+    const { container, fixture } = await setup(items);
+    const host = container.querySelector('[kjListNavigator]') as HTMLElement;
+    press(host, fixture, 'ArrowDown');
+    expect(host.getAttribute('aria-activedescendant')).toBe('1');
+    press(host, fixture, 'ArrowDown');
+    expect(host.getAttribute('aria-activedescendant')).toBe('3');
+  });
+
+  it('Home moves to first, End moves to last', async () => {
+    const items = [fakeItem('1', 'A'), fakeItem('2', 'B'), fakeItem('3', 'C')];
+    const { container, fixture } = await setup(items);
+    const host = container.querySelector('[kjListNavigator]') as HTMLElement;
+    press(host, fixture, 'End');
+    expect(host.getAttribute('aria-activedescendant')).toBe('3');
+    press(host, fixture, 'Home');
+    expect(host.getAttribute('aria-activedescendant')).toBe('1');
+  });
+
+  it('Enter calls _activate on the current item and preventDefaults', async () => {
+    const items = [fakeItem('1', 'A'), fakeItem('2', 'B')];
+    const { container, fixture } = await setup(items);
+    const host = container.querySelector('[kjListNavigator]') as HTMLElement;
+    press(host, fixture, 'ArrowDown');
+    const e = press(host, fixture, 'Enter');
+    expect((items[0] as { activated: number }).activated).toBe(1);
+    expect(e.defaultPrevented).toBe(true);
+  });
+
+  it('Enter does NOT preventDefault when there is no active item', async () => {
+    const items = [fakeItem('1', 'A')];
+    const { container, fixture } = await setup(items);
+    const host = container.querySelector('[kjListNavigator]') as HTMLElement;
+    const e = press(host, fixture, 'Enter');
+    expect(e.defaultPrevented).toBe(false);
+    expect((items[0] as { activated: number }).activated).toBe(0);
+  });
+
+  it('Space activates current item', async () => {
+    const items = [fakeItem('1', 'A')];
+    const { container, fixture } = await setup(items);
+    const host = container.querySelector('[kjListNavigator]') as HTMLElement;
+    press(host, fixture, 'ArrowDown');
+    press(host, fixture, ' ');
+    expect((items[0] as { activated: number }).activated).toBe(1);
+  });
+
+  it('PageDown moves by kjPageSize (default 10)', async () => {
+    const items = Array.from({ length: 15 }, (_, i) => fakeItem(String(i + 1), 'Item ' + (i + 1)));
+    const { container, fixture } = await setup(items);
+    const host = container.querySelector('[kjListNavigator]') as HTMLElement;
+    press(host, fixture, 'ArrowDown');
+    press(host, fixture, 'PageDown');
+    expect(host.getAttribute('aria-activedescendant')).toBe('11');
+  });
+
+  it('delegates single-char keys to KjTypeAhead and activates the match', async () => {
+    const items = [fakeItem('1', 'Apple'), fakeItem('2', 'Banana')];
+    const { container, fixture } = await setup(items);
+    const host = container.querySelector('[kjListNavigator]') as HTMLElement;
+    press(host, fixture, 'b');
+    expect(host.getAttribute('aria-activedescendant')).toBe('2');
+  });
+
+  it('kjOrientation="horizontal" responds to ArrowLeft/Right not Up/Down', async () => {
+    const items = [fakeItem('1', 'A'), fakeItem('2', 'B')];
+    const { container, fixture } = await setup(items, { orientation: 'horizontal' });
+    const host = container.querySelector('[kjListNavigator]') as HTMLElement;
+    press(host, fixture, 'ArrowDown');
+    expect(host.hasAttribute('aria-activedescendant')).toBe(false);
+    press(host, fixture, 'ArrowRight');
+    expect(host.getAttribute('aria-activedescendant')).toBe('1');
+  });
+
+  it('kjWrap=false clamps at last item instead of wrapping', async () => {
+    const items = [fakeItem('1', 'A'), fakeItem('2', 'B')];
+    const { container, fixture } = await setup(items, { wrap: false });
+    const host = container.querySelector('[kjListNavigator]') as HTMLElement;
+    press(host, fixture, 'End');
+    press(host, fixture, 'ArrowDown');
+    expect(host.getAttribute('aria-activedescendant')).toBe('2');
+  });
+});
+
+describe('KjListNavigator focus modes', () => {
+  it('default activedescendant: all KjListItem tabindex=-1', async () => {
+    @Component({
+      standalone: true,
+      imports: [KjListNavigator, KjListItem, TestListRoot],
+      template: `
+        <div kjTestListRoot kjListNavigator>
+          <div role="option" aria-selected="false" kjListItem id="a" [kjItemValue]="'a'">A</div>
+          <div role="option" aria-selected="false" kjListItem id="b" [kjItemValue]="'b'">B</div>
+        </div>
+      `,
+    })
+    class Host {}
+    const { container } = await render(Host);
+    const els = container.querySelectorAll('[kjListItem]');
+    els.forEach(el => expect(el.getAttribute('tabindex')).toBe('-1'));
+  });
+
+  it('roving mode: first item is tabindex=0 on first render, others -1', async () => {
+    @Component({
+      standalone: true,
+      imports: [KjListNavigator, KjListItem, TestListRoot],
+      template: `
+        <div kjTestListRoot kjListNavigator [kjFocusMode]="'roving'">
+          <div role="option" aria-selected="false" kjListItem id="a" [kjItemValue]="'a'">A</div>
+          <div role="option" aria-selected="false" kjListItem id="b" [kjItemValue]="'b'">B</div>
+          <div role="option" aria-selected="false" kjListItem id="c" [kjItemValue]="'c'">C</div>
+        </div>
+      `,
+    })
+    class Host {}
+    const { container, fixture } = await render(Host);
+    fixture.detectChanges();
+    const a = container.querySelector('#a')!;
+    const b = container.querySelector('#b')!;
+    const c = container.querySelector('#c')!;
+    expect(a.getAttribute('tabindex')).toBe('0');
+    expect(b.getAttribute('tabindex')).toBe('-1');
+    expect(c.getAttribute('tabindex')).toBe('-1');
+  });
+
+  it('roving mode: moveBy(1) flips the tabbable item to the next', async () => {
+    @Component({
+      standalone: true,
+      imports: [KjListNavigator, KjListItem, TestListRoot],
+      template: `
+        <div kjTestListRoot kjListNavigator [kjFocusMode]="'roving'" #nav="kjListNavigator">
+          <div role="option" aria-selected="false" kjListItem id="a" [kjItemValue]="'a'">A</div>
+          <div role="option" aria-selected="false" kjListItem id="b" [kjItemValue]="'b'">B</div>
+        </div>
+      `,
+    })
+    class Host {}
+    const { container, fixture } = await render(Host);
+    fixture.detectChanges();
+    const nav = fixture.debugElement.query(By.directive(KjListNavigator)).injector.get(KjListNavigator);
+    nav.moveBy(1);
+    fixture.detectChanges();
+    const a = container.querySelector('#a')!;
+    const b = container.querySelector('#b')!;
+    expect(a.getAttribute('tabindex')).toBe('-1');
+    expect(b.getAttribute('tabindex')).toBe('0');
+  });
+
+  it('roving mode: disabled items get -1 even when first; first navigable seeded', async () => {
+    @Component({
+      standalone: true,
+      imports: [KjListNavigator, KjListItem, TestListRoot],
+      template: `
+        <div kjTestListRoot kjListNavigator [kjFocusMode]="'roving'">
+          <div role="option" aria-selected="false" kjListItem id="a" [kjDisabled]="true" [kjItemValue]="'a'">A</div>
+          <div role="option" aria-selected="false" kjListItem id="b" [kjItemValue]="'b'">B</div>
+          <div role="option" aria-selected="false" kjListItem id="c" [kjItemValue]="'c'">C</div>
+        </div>
+      `,
+    })
+    class Host {}
+    const { container, fixture } = await render(Host);
+    fixture.detectChanges();
+    const a = container.querySelector('#a')!;
+    const b = container.querySelector('#b')!;
+    const c = container.querySelector('#c')!;
+    // Disabled first item: tabindex=-1, first navigable (b) gets 0.
+    expect(a.getAttribute('tabindex')).toBe('-1');
+    expect(b.getAttribute('tabindex')).toBe('0');
+    expect(c.getAttribute('tabindex')).toBe('-1');
+  });
+
+  it('roving mode: setActive(id) moves focus to that item\'s host element', async () => {
+    @Component({
+      standalone: true,
+      imports: [KjListNavigator, KjListItem, TestListRoot],
+      template: `
+        <div kjTestListRoot kjListNavigator [kjFocusMode]="'roving'">
+          <div role="option" aria-selected="false" kjListItem id="a" [kjItemValue]="'a'">A</div>
+          <div role="option" aria-selected="false" kjListItem id="b" [kjItemValue]="'b'">B</div>
+        </div>
+      `,
+    })
+    class Host {}
+    const { container, fixture } = await render(Host);
+    fixture.detectChanges();
+    const nav = fixture.debugElement.query(By.directive(KjListNavigator)).injector.get(KjListNavigator);
+    const b = container.querySelector('#b') as HTMLElement;
+    nav.setActive('b');
+    fixture.detectChanges();
+    expect(document.activeElement).toBe(b);
+    expect(b.getAttribute('tabindex')).toBe('0');
+  });
+});