@kouji-ui/core 0.1.1 → 0.1.3

package/src/primitives/list/item.ts

@@ -1,222 +0,0 @@
-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

@@ -1,286 +0,0 @@
-// 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');
-  });
-});