@kouji-ui/core 0.1.1 → 0.1.3

package/src/primitives/list/navigator.ts

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

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