feat(multiple): add subset support to list nav

Author: wagnermaciel

src/aria/private/behaviors/list-navigation/list-navigation.spec.ts

@@ -254,4 +254,55 @@ describe('List Navigation', () => {
       expect(nav.inputs.activeItem()).toBe(nav.inputs.items()[4]);
     });
   });
+
+  describe('with items subset', () => {
+    it('should navigate only within the provided subset for next/prev', () => {
+      const nav = getNavigation();
+      const allItems = nav.inputs.items();
+      const subset = [allItems[0], allItems[2], allItems[4]];
+
+      // Start at 0
+      expect(nav.inputs.activeItem()).toBe(allItems[0]);
+
+      // next(subset) -> 2 (skip 1)
+      nav.next({focusElement: false, items: subset});
+      expect(nav.inputs.activeItem()).toBe(allItems[2]);
+
+      // next(subset) -> 4 (skip 3)
+      nav.next({focusElement: false, items: subset});
+      expect(nav.inputs.activeItem()).toBe(allItems[4]);
+
+      // prev(subset) -> 2 (skip 3)
+      nav.prev({focusElement: false, items: subset});
+      expect(nav.inputs.activeItem()).toBe(allItems[2]);
+    });
+
+    it('should wrap within the subset', () => {
+      const nav = getNavigation({wrap: signal(true)});
+      const allItems = nav.inputs.items();
+      const subset = [allItems[0], allItems[2], allItems[4]];
+
+      nav.goto(allItems[4]);
+
+      // next(subset) -> 0 (wrap)
+      nav.next({focusElement: false, items: subset});
+      expect(nav.inputs.activeItem()).toBe(allItems[0]);
+
+      // prev(subset) -> 4 (wrap)
+      nav.prev({focusElement: false, items: subset});
+      expect(nav.inputs.activeItem()).toBe(allItems[4]);
+    });
+
+    it('should find first/last within the subset', () => {
+      const nav = getNavigation();
+      const allItems = nav.inputs.items();
+      const subset = [allItems[1], allItems[2], allItems[3]];
+
+      nav.first({focusElement: false, items: subset});
+      expect(nav.inputs.activeItem()).toBe(allItems[1]);
+
+      nav.last({focusElement: false, items: subset});
+      expect(nav.inputs.activeItem()).toBe(allItems[3]);
+    });
+  });
 });

src/aria/private/behaviors/list-navigation/list-navigation.ts

@@ -24,54 +24,71 @@ export interface ListNavigationInputs<T extends ListNavigationItem> extends List
   textDirection: SignalLike<'rtl' | 'ltr'>;
 }
 
+/** Options for list navigation. */
+export interface ListNavigationOpts<T> {
+  /**
+   * Whether to focus the item's element.
+   * Defaults to true.
+   */
+  focusElement?: boolean;
+
+  /**
+   * The list of items to navigate through.
+   * Defaults to the list of items from the inputs.
+   */
+  items?: T[];
+}
+
 /** Controls navigation for a list of items. */
 export class ListNavigation<T extends ListNavigationItem> {
   constructor(readonly inputs: ListNavigationInputs<T> & {focusManager: ListFocus<T>}) {}
 
   /** Navigates to the given item. */
-  goto(item?: T, opts?: {focusElement?: boolean}): boolean {
+  goto(item?: T, opts?: ListNavigationOpts<T>): boolean {
     return item ? this.inputs.focusManager.focus(item, opts) : false;
   }
 
   /** Navigates to the next item in the list. */
-  next(opts?: {focusElement?: boolean}): boolean {
+  next(opts?: ListNavigationOpts<T>): boolean {
     return this._advance(1, opts);
   }
 
   /** Peeks the next item in the list. */
-  peekNext(): T | undefined {
-    return this._peek(1);
+  peekNext(opts?: ListNavigationOpts<T>): T | undefined {
+    return this._peek(1, opts);
   }
 
   /** Navigates to the previous item in the list. */
-  prev(opts?: {focusElement?: boolean}): boolean {
+  prev(opts?: ListNavigationOpts<T>): boolean {
     return this._advance(-1, opts);
   }
 
   /** Peeks the previous item in the list. */
-  peekPrev(): T | undefined {
-    return this._peek(-1);
+  peekPrev(opts?: ListNavigationOpts<T>): T | undefined {
+    return this._peek(-1, opts);
   }
 
   /** Navigates to the first item in the list. */
-  first(opts?: {focusElement?: boolean}): boolean {
-    const item = this.peekFirst();
+  first(opts?: ListNavigationOpts<T>): boolean {
+    const item = this.peekFirst(opts);
     return item ? this.goto(item, opts) : false;
   }
 
   /** Navigates to the last item in the list. */
-  last(opts?: {focusElement?: boolean}): boolean {
-    const item = this.peekLast();
+  last(opts?: ListNavigationOpts<T>): boolean {
+    const item = this.peekLast(opts);
     return item ? this.goto(item, opts) : false;
   }
 
   /** Gets the first focusable item from the given list of items. */
-  peekFirst(items: T[] = this.inputs.items()): T | undefined {
+  peekFirst(opts?: ListNavigationOpts<T>): T | undefined {
+    const items = opts?.items ?? this.inputs.items();
     return items.find(i => this.inputs.focusManager.isFocusable(i));
   }
 
   /** Gets the last focusable item from the given list of items. */
-  peekLast(items: T[] = this.inputs.items()): T | undefined {
+  peekLast(opts?: ListNavigationOpts<T>): T | undefined {
+    const items = opts?.items ?? this.inputs.items();
     for (let i = items.length - 1; i >= 0; i--) {
       if (this.inputs.focusManager.isFocusable(items[i])) {
         return items[i];
@@ -81,16 +98,17 @@ export class ListNavigation<T extends ListNavigationItem> {
   }
 
   /** Advances to the next or previous focusable item in the list based on the given delta. */
-  private _advance(delta: 1 | -1, opts?: {focusElement?: boolean}): boolean {
-    const item = this._peek(delta);
+  private _advance(delta: 1 | -1, opts?: ListNavigationOpts<T>): boolean {
+    const item = this._peek(delta, opts);
     return item ? this.goto(item, opts) : false;
   }
 
   /** Peeks the next or previous focusable item in the list based on the given delta. */
-  private _peek(delta: 1 | -1): T | undefined {
-    const items = this.inputs.items();
+  private _peek(delta: 1 | -1, opts?: ListNavigationOpts<T>): T | undefined {
+    const items = opts?.items ?? this.inputs.items();
     const itemCount = items.length;
-    const startIndex = this.inputs.focusManager.activeIndex();
+    const activeItem = this.inputs.focusManager.inputs.activeItem();
+    const startIndex = activeItem ? items.indexOf(activeItem) : -1;
     const step = (i: number) =>
       this.inputs.wrap() ? (i + delta + itemCount) % itemCount : i + delta;
 

src/aria/private/behaviors/list/list.spec.ts

@@ -245,6 +245,39 @@ describe('List Behavior', () => {
       list.prev();
       expect(list.inputs.activeItem()).toBe(list.inputs.items()[0]);
     });
+
+    describe('with items subset', () => {
+      it('should navigate next/prev within subset', () => {
+        const {list, items} = getDefaultPatterns();
+        const subset = [items[0], items[2], items[4]];
+
+        // Start at 0
+        expect(list.inputs.activeItem()).toBe(items[0]);
+
+        // next(subset) -> 2 (skip 1)
+        list.next({items: subset});
+        expect(list.inputs.activeItem()).toBe(items[2]);
+
+        // next(subset) -> 4 (skip 3)
+        list.next({items: subset});
+        expect(list.inputs.activeItem()).toBe(items[4]);
+
+        // prev(subset) -> 2 (skip 3)
+        list.prev({items: subset});
+        expect(list.inputs.activeItem()).toBe(items[2]);
+      });
+
+      it('should verify first/last within subset', () => {
+        const {list, items} = getDefaultPatterns();
+        const subset = [items[1], items[2], items[3]];
+
+        list.first({items: subset});
+        expect(list.inputs.activeItem()).toBe(items[1]);
+
+        list.last({items: subset});
+        expect(list.inputs.activeItem()).toBe(items[3]);
+      });
+    });
   });
 
   describe('Selection', () => {

src/aria/private/behaviors/list/list.ts

@@ -25,13 +25,14 @@ import {
 } from '../list-typeahead/list-typeahead';
 
 /** The operations that the list can perform after navigation. */
-interface NavOptions {
+export interface NavOptions<T = any> {
   toggle?: boolean;
   select?: boolean;
   selectOne?: boolean;
   selectRange?: boolean;
   anchor?: boolean;
   focusElement?: boolean;
+  items?: T[];
 }
 
 /** Represents an item in the list. */
@@ -106,27 +107,27 @@ export class List<T extends ListItem<V>, V> {
   }
 
   /** Navigates to the first option in the list. */
-  first(opts?: NavOptions) {
+  first(opts?: NavOptions<T>) {
     this._navigate(opts, () => this.navigationBehavior.first(opts));
   }
 
   /** Navigates to the last option in the list. */
-  last(opts?: NavOptions) {
+  last(opts?: NavOptions<T>) {
     this._navigate(opts, () => this.navigationBehavior.last(opts));
   }
 
   /** Navigates to the next option in the list. */
-  next(opts?: NavOptions) {
+  next(opts?: NavOptions<T>) {
     this._navigate(opts, () => this.navigationBehavior.next(opts));
   }
 
   /** Navigates to the previous option in the list. */
-  prev(opts?: NavOptions) {
+  prev(opts?: NavOptions<T>) {
     this._navigate(opts, () => this.navigationBehavior.prev(opts));
   }
 
   /** Navigates to the given item in the list. */
-  goto(item: T, opts?: NavOptions) {
+  goto(item: T, opts?: NavOptions<T>) {
     this._navigate(opts, () => this.navigationBehavior.goto(item, opts));
   }
 

src/aria/private/toolbar/toolbar.ts

@@ -101,7 +101,9 @@ export class ToolbarPattern<V> {
 
     if (currGroup !== nextGroup) {
       this.listBehavior.goto(
-        this.listBehavior.navigationBehavior.peekFirst(currGroup.inputs.items())!,
+        this.listBehavior.navigationBehavior.peekFirst({
+          items: currGroup.inputs.items(),
+        })!,
       );
 
       return;
@@ -121,7 +123,9 @@ export class ToolbarPattern<V> {
 
     if (currGroup !== nextGroup) {
       this.listBehavior.goto(
-        this.listBehavior.navigationBehavior.peekLast(currGroup.inputs.items())!,
+        this.listBehavior.navigationBehavior.peekLast({
+          items: currGroup.inputs.items(),
+        })!,
       );
 
       return;
@@ -186,7 +190,9 @@ export class ToolbarPattern<V> {
    * Otherwise, sets the active index to the first focusable widget.
    */
   setDefaultState() {
-    const firstItem = this.listBehavior.navigationBehavior.peekFirst(this.inputs.items());
+    const firstItem = this.listBehavior.navigationBehavior.peekFirst({
+      items: this.inputs.items(),
+    });
 
     if (firstItem) {
       this.inputs.activeItem.set(firstItem);