@kouji-ui/core 0.0.4 → 0.1.1

package/src/primitives/list/navigator.ts

@@ -0,0 +1,238 @@
+// packages/core/src/primitives/list/navigator.ts
+import {
+  Directive,
+  computed,
+  effect,
+  inject,
+  input,
+  output,
+  signal,
+} from '@angular/core';
+import {
+  KJ_LIST_FOCUS_MODE,
+  KJ_LIST_NAVIGATOR_CONFIG,
+  type KjListFocusMode,
+  type KjListOrientation,
+} from './tokens';
+import { KjTypeAhead } from './type-ahead';
+import type { KjListItem } from './item';
+
+/**
+ * Container-side keyboard / active-descendant primitive. Hosted on the
+ * listbox panel (select / command-palette) or the input element
+ * (combobox). Owns `aria-activedescendant` and the ArrowUp/Down /
+ * Home/End / PageUp/Down / Enter / Space / type-ahead contract for the
+ * WAI-ARIA APG listbox + combobox patterns.
+ *
+ * @doc-category Core/Primitives
+ */
+@Directive({
+  selector: '[kjListNavigator]',
+  exportAs: 'kjListNavigator',
+  standalone: true,
+  providers: [
+    {
+      provide: KJ_LIST_FOCUS_MODE,
+      // The factory closes over the directive instance via `inject`,
+      // exposing the live `kjFocusMode` signal to child `KjListItem`s.
+      useFactory: () => inject(KjListNavigator).kjFocusMode,
+    },
+  ],
+  host: {
+    '[attr.aria-activedescendant]': 'kjFocusMode() === "activedescendant" ? activeId() : null',
+    '(keydown)': '_onKeydown($event)',
+  },
+})
+export class KjListNavigator {
+  /** Which axis the navigator responds to. Default: `'vertical'`. */
+  readonly kjOrientation     = input<KjListOrientation>('vertical');
+  /** Wrap at ends instead of clamping. Default: `true`. */
+  readonly kjWrap            = input<boolean>(true);
+  /** Items to skip per PageUp / PageDown. Default: `10`. */
+  readonly kjPageSize        = input<number>(10);
+  /** Activate item on pointer hover. Default: `false`. */
+  readonly kjActivateOnHover = input<boolean>(false);
+  /**
+   * Focus model. `'activedescendant'` (default) keeps DOM focus on the
+   * navigator host and signals the active option via
+   * `aria-activedescendant`. `'roving'` moves DOM focus onto the active
+   * option itself via roving `tabindex`. Switch to `'roving'` for menu
+   * / menubar / tree-select patterns where each item must be the focus
+   * target (so screen-reader virtual-cursor and JAWS / NVDA forms-mode
+   * line up with the visual highlight).
+   */
+  readonly kjFocusMode       = input<KjListFocusMode>('activedescendant');
+
+  /** Fires when the active item changes. Emits the new id or `null`. */
+  readonly kjActiveChange = output<string | null>();
+
+  private readonly cfg = inject(KJ_LIST_NAVIGATOR_CONFIG);
+  private readonly typeAhead = inject(KjTypeAhead, { optional: true });
+
+  private readonly _activeId = signal<string | null>(null);
+  /**
+   * Currently active item id, or `null`.
+   * Bound to `aria-activedescendant` on the host element.
+   */
+  readonly activeId = this._activeId.asReadonly();
+
+  /** Visible + non-disabled items in DOM order — the navigable set. */
+  private readonly navigable = computed<readonly KjListItem<unknown>[]>(() => {
+    const source = this.cfg.visibleItems?.() ?? this.cfg.items();
+    return source.filter(i => !i.disabled());
+  });
+
+  constructor() {
+    // Roving seed: when the focus model is `'roving'` and no item is
+    // active yet, point at the first navigable so its `tabindex=0`
+    // makes the list reachable by Tab on first render — required by
+    // WAI-ARIA APG (menu / tree). In `'activedescendant'` mode the
+    // listbox host itself is the Tab target, so seeding would
+    // pre-highlight an option before the user has interacted, hurting
+    // accessibility (false "selected" cue). Hence: roving only.
+    effect(() => {
+      if (this.kjFocusMode() !== 'roving') return;
+      if (this._activeId() !== null) return;
+      const first = this.navigable()[0];
+      if (first) this._activeId.set(first.id);
+    });
+
+    // Roving focus follow: when the active item changes (keyboard nav,
+    // pointer hover, programmatic setActive), move DOM focus onto its
+    // host element so the browser's focus ring + screen-reader virtual
+    // cursor track the visual highlight. Only relevant in roving mode
+    // — activedescendant keeps focus on the navigator host element.
+    effect(() => {
+      if (this.kjFocusMode() !== 'roving') return;
+      const item = this.activeItem();
+      if (!item) return;
+      const host = item._host();
+      if (host && document.activeElement !== host) host.focus();
+    });
+  }
+
+  /**
+   * The resolved active item object, or `null` when nothing is active.
+   * Derived from `activeId` and the current navigable set.
+   */
+  readonly activeItem = computed<KjListItem<unknown> | null>(() => {
+    const id = this._activeId();
+    return id ? this.navigable().find(i => i.id === id) ?? null : null;
+  });
+
+  /**
+   * Set the active item by id. No-op when unchanged; emits `kjActiveChange`.
+   * The `[attr.aria-activedescendant]` host binding flushes the change to
+   * the DOM on the next change-detection cycle.
+   */
+  setActive(id: string | null): void {
+    if (this._activeId() === id) return;
+    this._activeId.set(id);
+    this.kjActiveChange.emit(id);
+  }
+
+  /**
+   * Move the active index by `delta` positions in the navigable set.
+   * Respects `kjWrap` (wrap vs. clamp) and skips disabled items.
+   */
+  moveBy(delta: number): void {
+    const items = this.navigable();
+    if (!items.length) return;
+    const currentIdx = items.findIndex(i => i.id === this._activeId());
+    // When nothing is active and moving forward, start at -1 so that
+    // +1 lands on index 0 (first item). Moving backward from nothing
+    // starts at items.length so -1 lands on the last item.
+    const startIdx = currentIdx === -1 ? (delta > 0 ? -1 : items.length) : currentIdx;
+    let next = startIdx + delta;
+    const last = items.length - 1;
+    if (this.kjWrap()) {
+      next = ((next % items.length) + items.length) % items.length;
+    } else {
+      if (next < 0) next = 0;
+      if (next > last) next = last;
+    }
+    this.setActive(items[next].id);
+  }
+
+  /** Move the active item to the first item in the navigable set. */
+  moveToFirst(): void {
+    const items = this.navigable();
+    if (items.length) this.setActive(items[0].id);
+  }
+
+  /** Move the active item to the last item in the navigable set. */
+  moveToLast(): void {
+    const items = this.navigable();
+    if (items.length) this.setActive(items[items.length - 1].id);
+  }
+
+  /**
+   * Invoke `_activate()` on the currently active item.
+   * No-op when nothing is active.
+   */
+  activateCurrent(): void {
+    this.activeItem()?._activate();
+  }
+
+  /** @internal Keydown handler bound via host binding. */
+  _onKeydown(e: KeyboardEvent): void {
+    const o = this.kjOrientation();
+    const isV = o === 'vertical' || o === 'both';
+    const isH = o === 'horizontal' || o === 'both';
+
+    switch (e.key) {
+      case 'ArrowDown':
+        if (!isV) return;
+        e.preventDefault();
+        this.moveBy(1);
+        return;
+      case 'ArrowUp':
+        if (!isV) return;
+        e.preventDefault();
+        this.moveBy(-1);
+        return;
+      case 'ArrowRight':
+        if (!isH) return;
+        e.preventDefault();
+        this.moveBy(1);
+        return;
+      case 'ArrowLeft':
+        if (!isH) return;
+        e.preventDefault();
+        this.moveBy(-1);
+        return;
+      case 'Home':
+        e.preventDefault();
+        this.moveToFirst();
+        return;
+      case 'End':
+        e.preventDefault();
+        this.moveToLast();
+        return;
+      case 'PageDown':
+        e.preventDefault();
+        this.moveBy(this.kjPageSize());
+        return;
+      case 'PageUp':
+        e.preventDefault();
+        this.moveBy(-this.kjPageSize());
+        return;
+      case 'Enter':
+      case ' ':
+        // Only preventDefault when we actually activate. Lets consumers
+        // (e.g. combobox free-text Enter) fall through when nothing is
+        // active, and lets Space type a literal space in a combobox input.
+        if (this.activeItem()) {
+          e.preventDefault();
+          this.activateCurrent();
+        }
+        return;
+      default: {
+        if (e.key.length !== 1 || e.ctrlKey || e.metaKey || e.altKey) return;
+        if (!this.typeAhead) return;
+        const id = this.typeAhead.match(e.key, this.navigable());
+        if (id) this.setActive(id);
+      }
+    }
+  }
+}

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

@@ -0,0 +1,214 @@
+// packages/core/src/primitives/list/selection.spec.ts
+import { TestBed } from '@angular/core/testing';
+import { signal, type WritableSignal } from '@angular/core';
+import { describe, it, expect } from 'vitest';
+import { KjSelectionModel } from './selection';
+import { KJ_LIST_NAVIGATOR_CONFIG, type KjTreeShape } from './tokens';
+
+/**
+ * Provide an explicit `value` signal via the shared config token so the
+ * model writes through it. Tests assert on this signal directly — same
+ * way real consumers (KjSelect / KjCombobox) wire up.
+ */
+function setup<T>(): {
+  m: KjSelectionModel<T>;
+  value: WritableSignal<T | readonly T[] | null>;
+} {
+  const value = signal<T | readonly T[] | null>(null);
+  TestBed.configureTestingModule({
+    providers: [
+      KjSelectionModel,
+      {
+        provide: KJ_LIST_NAVIGATOR_CONFIG,
+        useValue: { items: signal([]), value },
+      },
+    ],
+  });
+  return { m: TestBed.inject(KjSelectionModel) as KjSelectionModel<T>, value };
+}
+
+/**
+ * Test tree:
+ *     root
+ *    /    \
+ *   A      B
+ *  / \    /
+ * A1 A2  B1
+ */
+type N = 'root' | 'A' | 'A1' | 'A2' | 'B' | 'B1';
+const TREE: KjTreeShape<N> = {
+  getParent: (n) => ({ A: 'root', B: 'root', A1: 'A', A2: 'A', B1: 'B', root: null } as Record<N, N | null>)[n],
+  getChildren: (n) => ({ root: ['A', 'B'] as N[], A: ['A1', 'A2'] as N[], B: ['B1'] as N[], A1: [] as N[], A2: [] as N[], B1: [] as N[] } as Record<N, readonly N[]>)[n],
+  isLeaf: (n) => n === 'A1' || n === 'A2' || n === 'B1',
+};
+
+describe('KjSelectionModel', () => {
+  it('defaults to single mode with null value', () => {
+    const { m, value } = setup<string>();
+    expect(m.mode()).toBe('single');
+    expect(value()).toBeNull();
+  });
+
+  it('isSelected uses Object.is by default', () => {
+    const { m } = setup<string>();
+    m.setValue('a');
+    expect(m.isSelected('a')).toBe(true);
+    expect(m.isSelected('b')).toBe(false);
+  });
+
+  it('toggle in single mode replaces value and returns closeRequested=true', () => {
+    const { m, value } = setup<string>();
+    const r = m.toggle('a');
+    expect(value()).toBe('a');
+    expect(r.closeRequested).toBe(true);
+  });
+
+  it('toggle in multi mode adds/removes and returns closeRequested=false', () => {
+    const { m, value } = setup<string>();
+    m.setMode('multi');
+    m.toggle('a');
+    m.toggle('b');
+    expect(value()).toEqual(['a', 'b']);
+
+    const r = m.toggle('a');
+    expect(value()).toEqual(['b']);
+    expect(r.closeRequested).toBe(false);
+  });
+
+  it('clear in single mode sets null, in multi mode sets []', () => {
+    const { m, value } = setup<string>();
+    m.setValue('a');
+    m.clear();
+    expect(value()).toBeNull();
+
+    m.setMode('multi');
+    m.setValue(['a', 'b']);
+    m.clear();
+    expect(value()).toEqual([]);
+  });
+
+  it('compareBy custom fn — by id field', () => {
+    type Item = { id: string; label: string };
+    const { m } = setup<Item>();
+    m.setCompareBy((a, b) => a.id === b.id);
+    m.setValue({ id: 'fr', label: 'France' });
+    expect(m.isSelected({ id: 'fr', label: 'France (canonical)' })).toBe(true);
+    expect(m.isSelected({ id: 'de', label: 'Germany' })).toBe(false);
+  });
+
+  it('isSelected returns false when value is null', () => {
+    const { m } = setup<string>();
+    expect(m.isSelected('a')).toBe(false);
+  });
+
+  describe('leaf mode', () => {
+    it('toggle on a leaf adds it to the value array', () => {
+      const { m, value } = setup<N>();
+      m.setMode('leaf');
+      m.setTreeShape(TREE);
+      m.toggle('A1');
+      m.toggle('B1');
+      expect(value()).toEqual(['A1', 'B1']);
+    });
+
+    it('toggle on a branch is a no-op', () => {
+      const { m, value } = setup<N>();
+      m.setMode('leaf');
+      m.setTreeShape(TREE);
+      m.setValue([]);
+      m.toggle('A');
+      expect(value()).toEqual([]);
+    });
+
+    it('falls back to multi behavior when no tree shape is set', () => {
+      const { m, value } = setup<N>();
+      m.setMode('leaf');
+      m.toggle('A'); // would be no-op with shape, but no shape → multi toggle
+      expect(value()).toEqual(['A']);
+    });
+  });
+
+  describe('cascade mode', () => {
+    it('cascadeState of an unselected leaf is "false"', () => {
+      const { m } = setup<N>();
+      m.setMode('cascade');
+      m.setTreeShape(TREE);
+      expect(m.cascadeState('A1')).toBe('false');
+    });
+
+    it('toggling a leaf adds only that leaf', () => {
+      const { m, value } = setup<N>();
+      m.setMode('cascade');
+      m.setTreeShape(TREE);
+      m.toggle('A1');
+      expect(value()).toEqual(['A1']);
+      expect(m.cascadeState('A1')).toBe('true');
+    });
+
+    it('parent state is "mixed" when some descendants are selected', () => {
+      const { m } = setup<N>();
+      m.setMode('cascade');
+      m.setTreeShape(TREE);
+      m.toggle('A1');
+      expect(m.cascadeState('A')).toBe('mixed');
+      expect(m.cascadeState('root')).toBe('mixed');
+    });
+
+    it('parent state is "true" when all leaf descendants are selected', () => {
+      const { m } = setup<N>();
+      m.setMode('cascade');
+      m.setTreeShape(TREE);
+      m.toggle('A1');
+      m.toggle('A2');
+      expect(m.cascadeState('A')).toBe('true');
+    });
+
+    it('toggling a branch cascades to all leaf descendants', () => {
+      const { m, value } = setup<N>();
+      m.setMode('cascade');
+      m.setTreeShape(TREE);
+      m.toggle('A');
+      expect([...(value() as N[])].sort()).toEqual(['A1', 'A2']);
+      expect(m.cascadeState('A')).toBe('true');
+    });
+
+    it('toggling root selects every leaf in the tree', () => {
+      const { m, value } = setup<N>();
+      m.setMode('cascade');
+      m.setTreeShape(TREE);
+      m.toggle('root');
+      expect([...(value() as N[])].sort()).toEqual(['A1', 'A2', 'B1']);
+      expect(m.cascadeState('root')).toBe('true');
+      expect(m.cascadeState('A')).toBe('true');
+      expect(m.cascadeState('B')).toBe('true');
+    });
+
+    it('toggling a fully-selected branch deselects all its leaves', () => {
+      const { m, value } = setup<N>();
+      m.setMode('cascade');
+      m.setTreeShape(TREE);
+      m.toggle('A'); // selects A1, A2
+      m.toggle('A'); // deselects them
+      expect(value()).toEqual([]);
+      expect(m.cascadeState('A')).toBe('false');
+    });
+
+    it('toggling a mixed branch fully selects all its leaves', () => {
+      const { m, value } = setup<N>();
+      m.setMode('cascade');
+      m.setTreeShape(TREE);
+      m.toggle('A1');               // A is now mixed
+      expect(m.cascadeState('A')).toBe('mixed');
+      m.toggle('A');                // mixed → true: should select A2 too
+      expect([...(value() as N[])].sort()).toEqual(['A1', 'A2']);
+      expect(m.cascadeState('A')).toBe('true');
+    });
+
+    it('cascade mode falls back to multi when no tree shape is set', () => {
+      const { m, value } = setup<N>();
+      m.setMode('cascade');
+      m.toggle('A');
+      expect(value()).toEqual(['A']);
+    });
+  });
+});