feat(cdk-experimental/ui-patterns): create grid navigation behavior (angular#31290)

* feat(cdk-experimental/ui-patterns): create grid navigation behavior

* fixup! feat(cdk-experimental/ui-patterns): create grid navigation behavior

Author: wagnermaciel

src/cdk-experimental/ui-patterns/behaviors/grid-focus/grid-focus.spec.ts

@@ -7,7 +7,7 @@
  */
 
 import {computed, Signal, signal, WritableSignal} from '@angular/core';
-import {GridFocus, GridFocusInputs, GridFocusCell} from './grid-focus';
+import {GridFocus, GridFocusInputs, GridFocusCell, RowCol} from './grid-focus';
 
 // Helper type for test cells, extending GridFocusCell
 interface TestGridCell extends GridFocusCell {
@@ -23,13 +23,13 @@ type TestSetupInputs = Partial<GridFocusInputs<TestGridCell>> & {
   gridFocus?: WritableSignal<GridFocus<TestGridCell> | undefined>;
 };
 
-function createTestCell(
+export function createTestCell(
   gridFocus: Signal<GridFocus<TestGridCell> | undefined>,
   opts: {id: string; rowspan?: number; colspan?: number},
 ): TestGridCell {
   const el = document.createElement('div');
   spyOn(el, 'focus').and.callThrough();
-  let coordinates: Signal<{row: number; column: number}> = signal({row: -1, column: -1});
+  let coordinates: Signal<RowCol> = signal({row: -1, col: -1});
   const cell: TestGridCell = {
     id: signal(opts.id),
     element: signal(el as HTMLElement),
@@ -39,13 +39,13 @@ function createTestCell(
     rowindex: signal(-1),
     colindex: signal(-1),
   };
-  coordinates = computed(() => gridFocus()?.getCoordinates(cell) ?? {row: -1, column: -1});
+  coordinates = computed(() => gridFocus()?.getCoordinates(cell) ?? {row: -1, col: -1});
   cell.rowindex = computed(() => coordinates().row);
-  cell.colindex = computed(() => coordinates().column);
+  cell.colindex = computed(() => coordinates().col);
   return cell;
 }
 
-function createTestCells(
+export function createTestCells(
   gridFocus: Signal<GridFocus<TestGridCell> | undefined>,
   numRows: number,
   numCols: number,
@@ -60,7 +60,7 @@ function createTestCells(
 }
 
 // Main helper function to instantiate GridFocus and its dependencies for testing
-function setupGridFocus(inputs: TestSetupInputs = {}): {
+export function setupGridFocus(inputs: TestSetupInputs = {}): {
   cells: TestGridCell[][];
   gridFocus: GridFocus<TestGridCell>;
 } {
@@ -70,7 +70,7 @@ function setupGridFocus(inputs: TestSetupInputs = {}): {
   const gridFocus = inputs.gridFocus ?? signal<GridFocus<TestGridCell> | undefined>(undefined);
   const cells = inputs.cells ?? createTestCells(gridFocus, numRows, numCols);
 
-  const activeCoords = inputs.activeCoords ?? signal({row: 0, column: 0});
+  const activeCoords = inputs.activeCoords ?? signal({row: 0, col: 0});
   const focusMode = signal<'roving' | 'activedescendant'>(
     inputs.focusMode ? inputs.focusMode() : 'roving',
   );
@@ -95,20 +95,20 @@ function setupGridFocus(inputs: TestSetupInputs = {}): {
 
 describe('GridFocus', () => {
   describe('Initialization', () => {
-    it('should initialize with activeCell at {row: 0, column: 0} by default', () => {
+    it('should initialize with activeCell at {row: 0, col: 0} by default', () => {
       const {gridFocus} = setupGridFocus();
-      expect(gridFocus.inputs.activeCoords()).toEqual({row: 0, column: 0});
+      expect(gridFocus.inputs.activeCoords()).toEqual({row: 0, col: 0});
     });
 
     it('should compute activeCell based on activeCell', () => {
       const {gridFocus, cells} = setupGridFocus({
-        activeCoords: signal({row: 1, column: 1}),
+        activeCoords: signal({row: 1, col: 1}),
       });
       expect(gridFocus.activeCell()).toBe(cells[1][1]);
     });
 
     it('should compute activeCell correctly when rowspan and colspan are set', () => {
-      const activeCoords = signal({row: 0, column: 0});
+      const activeCoords = signal({row: 0, col: 0});
       const gridFocusSignal = signal<GridFocus<TestGridCell> | undefined>(undefined);
 
       // Visualization of this irregular grid.
@@ -130,24 +130,58 @@ describe('GridFocus', () => {
         gridFocus: gridFocusSignal,
       });
 
-      activeCoords.set({row: 0, column: 0});
+      activeCoords.set({row: 0, col: 0});
       expect(gridFocus.activeCell()).toBe(cell_0_0);
-      activeCoords.set({row: 0, column: 1});
+      activeCoords.set({row: 0, col: 1});
       expect(gridFocus.activeCell()).toBe(cell_0_0);
-      activeCoords.set({row: 1, column: 0});
+      activeCoords.set({row: 1, col: 0});
       expect(gridFocus.activeCell()).toBe(cell_0_0);
-      activeCoords.set({row: 1, column: 1});
+      activeCoords.set({row: 1, col: 1});
       expect(gridFocus.activeCell()).toBe(cell_0_0);
 
-      activeCoords.set({row: 0, column: 2});
+      activeCoords.set({row: 0, col: 2});
       expect(gridFocus.activeCell()).toBe(cell_0_2);
 
-      activeCoords.set({row: 1, column: 2});
+      activeCoords.set({row: 1, col: 2});
       expect(gridFocus.activeCell()).toBe(cell_1_2);
     });
+
+    it('should compute rowCount and colCount correctly', () => {
+      const {gridFocus} = setupGridFocus({
+        numRows: 2,
+        numCols: 3,
+      });
+      expect(gridFocus.rowCount()).toBe(2);
+      expect(gridFocus.colCount()).toBe(3);
+    });
+
+    it('should compute rowCount and colCount correctly when rowspan and colspan are set', () => {
+      const gridFocusSignal = signal<GridFocus<TestGridCell> | undefined>(undefined);
+
+      // Visualization of this irregular grid.
+      //
+      //   +---+---+---+
+      //   |       |0,2|
+      //   +  0,0  +---+
+      //   |       |1,2|
+      //   +---+---+---+
+      //
+      const cell_0_0 = createTestCell(gridFocusSignal, {id: `cell-0-0`, rowspan: 2, colspan: 2});
+      const cell_0_2 = createTestCell(gridFocusSignal, {id: `cell-0-2`});
+      const cell_1_2 = createTestCell(gridFocusSignal, {id: `cell-1-2`});
+      const cells = signal<TestGridCell[][]>([[cell_0_0, cell_0_2], [cell_1_2]]);
+
+      const {gridFocus} = setupGridFocus({
+        cells,
+        gridFocus: gridFocusSignal,
+      });
+
+      expect(gridFocus.rowCount()).toBe(2);
+      expect(gridFocus.colCount()).toBe(3);
+    });
   });
 
-  describe('isGridDisabled()', () => {
+  describe('isGridDisabled', () => {
     it('should return true if inputs.disabled is true', () => {
       const {gridFocus} = setupGridFocus({disabled: signal(true)});
       expect(gridFocus.isGridDisabled()).toBeTrue();
@@ -171,7 +205,7 @@ describe('GridFocus', () => {
     });
   });
 
-  describe('getActiveDescendant()', () => {
+  describe('getActiveDescendant', () => {
     it('should return undefined if focusMode is "roving"', () => {
       const {gridFocus} = setupGridFocus({focusMode: signal('roving')});
       expect(gridFocus.getActiveDescendant()).toBeUndefined();
@@ -188,13 +222,13 @@ describe('GridFocus', () => {
     it('should return the activeCell id if focusMode is "activedescendant"', () => {
       const {gridFocus, cells} = setupGridFocus({
         focusMode: signal('activedescendant'),
-        activeCoords: signal({row: 2, column: 2}),
+        activeCoords: signal({row: 2, col: 2}),
       });
       expect(gridFocus.getActiveDescendant()).toBe(cells[2][2].id());
     });
   });
 
-  describe('getGridTabindex()', () => {
+  describe('getGridTabindex', () => {
     it('should return 0 if grid is disabled', () => {
       const {gridFocus} = setupGridFocus({disabled: signal(true)});
       expect(gridFocus.getGridTabindex()).toBe(0);
@@ -211,7 +245,7 @@ describe('GridFocus', () => {
     });
   });
 
-  describe('getCellTabindex(cell)', () => {
+  describe('getCellTabindex', () => {
     it('should return -1 if grid is disabled', () => {
       const {gridFocus, cells} = setupGridFocus({
         numRows: 1,
@@ -247,7 +281,7 @@ describe('GridFocus', () => {
     });
   });
 
-  describe('isFocusable(cell)', () => {
+  describe('isFocusable', () => {
     it('should return true if cell is not disabled', () => {
       const {gridFocus, cells} = setupGridFocus({
         numRows: 1,
@@ -283,65 +317,127 @@ describe('GridFocus', () => {
     });
   });
 
-  describe('focus(cell)', () => {
+  describe('focusCoordinates', () => {
+    it('should return false and not change state if grid is disabled', () => {
+      const activeCoords = signal({row: 0, col: 0});
+      const {gridFocus, cells} = setupGridFocus({
+        activeCoords,
+        disabled: signal(true),
+      });
+
+      const success = gridFocus.focusCoordinates({row: 1, col: 0});
+
+      expect(success).toBeFalse();
+      expect(activeCoords()).toEqual({row: 0, col: 0});
+      expect(cells[1][0].element().focus).not.toHaveBeenCalled();
+    });
+
+    it('should return false and not change state if cell is not focusable', () => {
+      const activeCoords = signal({row: 0, col: 0});
+      const {gridFocus, cells} = setupGridFocus({activeCoords});
+      cells[1][0].disabled.set(true);
+
+      const success = gridFocus.focusCoordinates({row: 1, col: 0});
+
+      expect(success).toBeFalse();
+      expect(activeCoords()).toEqual({row: 0, col: 0});
+      expect(cells[1][0].element().focus).not.toHaveBeenCalled();
+    });
+
+    it('should focus cell, update activeCell and prevActiveCell in "roving" mode', () => {
+      const activeCoords = signal({row: 0, col: 0});
+      const {gridFocus, cells} = setupGridFocus({
+        activeCoords,
+        focusMode: signal('roving'),
+      });
+
+      const success = gridFocus.focusCoordinates({row: 1, col: 0});
+
+      expect(success).toBeTrue();
+      expect(activeCoords()).toEqual({row: 1, col: 0});
+      expect(cells[1][0].element().focus).toHaveBeenCalled();
+
+      expect(gridFocus.activeCell()).toBe(cells[1][0]);
+      expect(gridFocus.prevActiveCoords()).toEqual({row: 0, col: 0});
+    });
+
+    it('should update activeCell and prevActiveCell but not call element.focus in "activedescendant" mode', () => {
+      const activeCoords = signal({row: 0, col: 0});
+      const {gridFocus, cells} = setupGridFocus({
+        activeCoords,
+        focusMode: signal('activedescendant'),
+      });
+
+      const success = gridFocus.focusCoordinates({row: 1, col: 0});
+
+      expect(success).toBeTrue();
+      expect(activeCoords()).toEqual({row: 1, col: 0});
+      expect(cells[1][0].element().focus).not.toHaveBeenCalled();
+
+      expect(gridFocus.activeCell()).toBe(cells[1][0]);
+      expect(gridFocus.prevActiveCoords()).toEqual({row: 0, col: 0});
+    });
+  });
+
+  describe('focusCell', () => {
     it('should return false and not change state if grid is disabled', () => {
-      const activeCoords = signal({row: 0, column: 0});
+      const activeCoords = signal({row: 0, col: 0});
       const {gridFocus, cells} = setupGridFocus({
         activeCoords,
         disabled: signal(true),
       });
 
-      const success = gridFocus.focus({row: 1, column: 0});
+      const success = gridFocus.focusCell(cells[1][0]);
 
       expect(success).toBeFalse();
-      expect(activeCoords()).toEqual({row: 0, column: 0});
+      expect(activeCoords()).toEqual({row: 0, col: 0});
       expect(cells[1][0].element().focus).not.toHaveBeenCalled();
     });
 
     it('should return false and not change state if cell is not focusable', () => {
-      const activeCoords = signal({row: 0, column: 0});
+      const activeCoords = signal({row: 0, col: 0});
       const {gridFocus, cells} = setupGridFocus({activeCoords});
       cells[1][0].disabled.set(true);
 
-      const success = gridFocus.focus({row: 1, column: 0});
+      const success = gridFocus.focusCell(cells[1][0]);
 
       expect(success).toBeFalse();
-      expect(activeCoords()).toEqual({row: 0, column: 0});
+      expect(activeCoords()).toEqual({row: 0, col: 0});
       expect(cells[1][0].element().focus).not.toHaveBeenCalled();
     });
 
     it('should focus cell, update activeCell and prevActiveCell in "roving" mode', () => {
-      const activeCoords = signal({row: 0, column: 0});
+      const activeCoords = signal({row: 0, col: 0});
       const {gridFocus, cells} = setupGridFocus({
         activeCoords,
         focusMode: signal('roving'),
       });
 
-      const success = gridFocus.focus({row: 1, column: 0});
+      const success = gridFocus.focusCell(cells[1][0]);
 
       expect(success).toBeTrue();
-      expect(activeCoords()).toEqual({row: 1, column: 0});
+      expect(activeCoords()).toEqual({row: 1, col: 0});
       expect(cells[1][0].element().focus).toHaveBeenCalled();
 
       expect(gridFocus.activeCell()).toBe(cells[1][0]);
-      expect(gridFocus.prevActiveCoords()).toEqual({row: 0, column: 0});
+      expect(gridFocus.prevActiveCoords()).toEqual({row: 0, col: 0});
     });
 
     it('should update activeCell and prevActiveCell but not call element.focus in "activedescendant" mode', () => {
-      const activeCoords = signal({row: 0, column: 0});
+      const activeCoords = signal({row: 0, col: 0});
       const {gridFocus, cells} = setupGridFocus({
         activeCoords,
         focusMode: signal('activedescendant'),
       });
 
-      const success = gridFocus.focus({row: 1, column: 0});
+      const success = gridFocus.focusCell(cells[1][0]);
 
       expect(success).toBeTrue();
-      expect(activeCoords()).toEqual({row: 1, column: 0});
+      expect(activeCoords()).toEqual({row: 1, col: 0});
       expect(cells[1][0].element().focus).not.toHaveBeenCalled();
 
       expect(gridFocus.activeCell()).toBe(cells[1][0]);
-      expect(gridFocus.prevActiveCoords()).toEqual({row: 0, column: 0});
+      expect(gridFocus.prevActiveCoords()).toEqual({row: 0, col: 0});
     });
   });
 });

src/cdk-experimental/ui-patterns/behaviors/grid-focus/grid-focus.ts

@@ -45,20 +45,37 @@ export interface GridFocusInputs<T extends GridFocusCell> {
   cells: SignalLike<T[][]>;
 
   /** The coordinates (row and column) of the current active cell. */
-  activeCoords: WritableSignalLike<{row: number; column: number}>;
+  activeCoords: WritableSignalLike<RowCol>;
 
   /** Whether disabled cells in the grid should be skipped when navigating. */
   skipDisabled: SignalLike<boolean>;
 }
 
+/** Represents coordinates in a grid. */
+export interface RowCol {
+  /** The row index. */
+  row: number;
+
+  /** The column index. */
+  col: number;
+}
+
 /** Controls focus for a 2D grid of cells. */
 export class GridFocus<T extends GridFocusCell> {
   /** The last active cell coordinates. */
-  prevActiveCoords = signal<{row: number; column: number}>({row: 0, column: 0});
+  prevActiveCoords = signal<RowCol>({row: 0, col: 0});
 
   /** The current active cell based on `activeCoords` coordinates. */
   activeCell = computed(() => this.getCell(this.inputs.activeCoords()));
 
+  /** The number of rows in the grid. */
+  rowCount = computed(() => this.inputs.cells().length);
+
+  /** The number of columns in the grid. */
+  colCount = computed(() => {
+    return this.inputs.cells()[0].reduce((count, curr) => count + curr.colspan(), 0);
+  });
+
   constructor(readonly inputs: GridFocusInputs<T>) {}
 
   /** The id of the current active cell, for ARIA activedescendant. */
@@ -98,28 +115,50 @@ export class GridFocus<T extends GridFocusCell> {
     return this.activeCell() === cell ? 0 : -1;
   }
 
+  /** Focuses the given cell. */
+  focusCell(cell: T): boolean {
+    if (this.isGridDisabled()) {
+      return false;
+    }
+
+    if (!this.isFocusable(cell)) {
+      return false;
+    }
+
+    this.prevActiveCoords.set(this.inputs.activeCoords());
+    this.inputs.activeCoords.set({row: cell.rowindex(), col: cell.colindex()});
+    this._focus(cell);
+
+    return true;
+  }
+
   /** Moves focus to the cell at the given coordinates if it's part of a focusable cell. */
-  focus(coordinates: {row: number; column: number}): boolean {
+  focusCoordinates(coordinates: RowCol): boolean {
     if (this.isGridDisabled()) {
       return false;
     }
 
     const cell = this.getCell(coordinates);
 
     if (!cell || !this.isFocusable(cell)) {
-      return false; // No cell at coordinates, or cell is not focusable.
+      return false;
     }
 
     this.prevActiveCoords.set(this.inputs.activeCoords());
-    this.inputs.activeCoords.set(coordinates); // Set activeCoords to the exact coordinates
+    this.inputs.activeCoords.set(coordinates);
+    this._focus(cell);
 
+    return true;
+  }
+
+  /** Handles conditionally calling `focus` on the HTML element of the cell. */
+  private _focus(cell: T) {
     if (this.inputs.focusMode() === 'roving') {
-      const element = cell.element(); // Element of the cell that *covers* these coordinates
+      const element = cell.element();
       if (element && typeof element.focus === 'function') {
         element.focus();
       }
     }
-    return true;
   }
 
   /** Returns true if the given cell can be navigated to. */
@@ -128,9 +167,9 @@ export class GridFocus<T extends GridFocusCell> {
   }
 
   /** Finds the top-left anchor coordinates of a given cell instance in the grid. */
-  getCoordinates(cellToFind: T): {row: number; column: number} | void {
+  getCoordinates(cellToFind: T): RowCol | void {
     const grid = this.inputs.cells();
-    const occupiedCells = new Set<string>(); // Stores "row,column" string keys for occupied cells.
+    const occupiedCells = new Set<string>();
 
     for (let rowindex = 0; rowindex < grid.length; rowindex++) {
       let colindex = 0;
@@ -144,7 +183,7 @@ export class GridFocus<T extends GridFocusCell> {
 
         // Check if this is the cell we're looking for.
         if (gridCell === cellToFind) {
-          return {row: rowindex, column: colindex};
+          return {row: rowindex, col: colindex};
         }
 
         const rowspan = gridCell.rowspan();
@@ -167,14 +206,14 @@ export class GridFocus<T extends GridFocusCell> {
   }
 
   /** Gets the cell that covers the given coordinates, considering rowspan and colspan. */
-  getCell(coords: {row: number; column: number}): T | void {
+  getCell(coords: RowCol): T | void {
     for (const row of this.inputs.cells()) {
       for (const cell of row) {
         if (
           coords.row >= cell.rowindex() &&
           coords.row <= cell.rowindex() + cell.rowspan() - 1 &&
-          coords.column >= cell.colindex() &&
-          coords.column <= cell.colindex() + cell.colspan() - 1
+          coords.col >= cell.colindex() &&
+          coords.col <= cell.colindex() + cell.colspan() - 1
         ) {
           return cell;
         }

src/cdk-experimental/ui-patterns/behaviors/grid-navigation/BUILD.bazel

@@ -0,0 +1,28 @@
+load("//tools:defaults.bzl", "ng_web_test_suite", "ts_project")
+
+package(default_visibility = ["//visibility:public"])
+
+ts_project(
+    name = "grid-navigation",
+    srcs = ["grid-navigation.ts"],
+    deps = [
+        "//:node_modules/@angular/core",
+        "//src/cdk-experimental/ui-patterns/behaviors/grid-focus",
+        "//src/cdk-experimental/ui-patterns/behaviors/signal-like",
+    ],
+)
+
+ts_project(
+    name = "unit_test_sources",
+    testonly = True,
+    srcs = ["grid-navigation.spec.ts"],
+    deps = [
+        ":grid-navigation",
+        "//:node_modules/@angular/core",
+    ],
+)
+
+ng_web_test_suite(
+    name = "unit_tests",
+    deps = [":unit_test_sources"],
+)

src/cdk-experimental/ui-patterns/behaviors/grid-navigation/grid-navigation.spec.ts

@@ -0,0 +1,158 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {SignalLike} from '../signal-like/signal-like';
+import {GridFocus, GridFocusCell, GridFocusInputs, RowCol} from '../grid-focus/grid-focus';
+import {computed} from '@angular/core';
+
+/** Represents an item in a collection, such as a listbox option, than can be navigated to. */
+export interface GridNavigationCell extends GridFocusCell {}
+
+/** Represents the required inputs for a collection that has navigable items. */
+export interface GridNavigationInputs<T extends GridNavigationCell> extends GridFocusInputs<T> {
+  gridFocus: GridFocus<T>;
+  wrap: SignalLike<boolean>;
+  wrapBehavior: SignalLike<'continuous' | 'loop'>;
+}
+
+/** Controls navigation for a grid of items. */
+export class GridNavigation<T extends GridNavigationCell> {
+  rowcount = computed(() => this.inputs.gridFocus.rowCount());
+  colcount = computed(() => this.inputs.gridFocus.colCount());
+
+  constructor(readonly inputs: GridNavigationInputs<T>) {}
+
+  /** Navigates to the given item. */
+  gotoCell(cell?: T): boolean {
+    return cell ? this.inputs.gridFocus.focusCell(cell) : false;
+  }
+
+  /** Navigates to the given coordinates. */
+  gotoCoords(coords: RowCol): boolean {
+    return this.inputs.gridFocus.focusCoordinates(coords);
+  }
+
+  /** Navigates to the item above the current item. */
+  up(): boolean {
+    return this._advance((cell: T, {col}: RowCol) => {
+      const rowindex = cell.rowindex();
+      const isRowWrapping = this.inputs.wrap() && rowindex - 1 < 0;
+      const isColumnWrapping = isRowWrapping && this.inputs.wrapBehavior() === 'continuous';
+
+      const nextCoords = {
+        row: isRowWrapping
+          ? (rowindex - 1 + this.rowcount()) % this.rowcount()
+          : Math.max(rowindex - 1, 0),
+        col: isColumnWrapping ? (col - 1 + this.colcount()) % this.colcount() : col,
+      };
+
+      const nextCell = this.inputs.gridFocus.getCell(nextCoords)!;
+
+      return {
+        row: nextCell.rowindex(),
+        col: nextCoords.col,
+      };
+    });
+  }
+
+  /** Navigates to the item below the current item. */
+  down(): boolean {
+    return this._advance((cell: T, {col}: RowCol) => {
+      const rowspan = cell.rowspan();
+      const rowindex = cell.rowindex();
+      const isRowWrapping = this.inputs.wrap() && rowindex + rowspan >= this.rowcount();
+      const isColumnWrapping = isRowWrapping && this.inputs.wrapBehavior() === 'continuous';
+
+      return {
+        row: isRowWrapping
+          ? (rowindex + rowspan) % this.rowcount()
+          : Math.min(rowindex + rowspan, this.rowcount() - 1),
+        col: isColumnWrapping ? (col + 1 + this.colcount()) % this.colcount() : col,
+      };
+    });
+  }
+
+  /** Navigates to the item to the left of the current item. */
+  left(): boolean {
+    return this._advance((cell: T, {row, col}: RowCol) => {
+      const colindex = cell.colindex();
+      const isColumnWrapping = this.inputs.wrap() && colindex - 1 < 0;
+      const isRowWrapping = isColumnWrapping && this.inputs.wrapBehavior() === 'continuous';
+
+      const nextCoords = {
+        row: isRowWrapping ? (row - 1 + this.rowcount()) % this.rowcount() : row,
+        col: isColumnWrapping
+          ? (colindex - 1 + this.colcount()) % this.colcount()
+          : Math.max(colindex - 1, 0),
+      };
+
+      const nextCell = this.inputs.gridFocus.getCell(nextCoords)!;
+
+      return {
+        row: nextCoords.row,
+        col: nextCell.colindex(),
+      };
+    });
+  }
+
+  /** Navigates to the item to the right of the current item. */
+  right(): boolean {
+    return this._advance((cell: T, {row}: RowCol) => {
+      const colspan = cell.colspan();
+      const colindex = cell.colindex();
+      const isColumnWrapping = this.inputs.wrap() && colindex + colspan >= this.colcount();
+      const isRowWrapping = isColumnWrapping && this.inputs.wrapBehavior() === 'continuous';
+
+      return {
+        row: isRowWrapping ? (row + 1 + this.rowcount()) % this.rowcount() : row,
+        col: isColumnWrapping
+          ? (colindex + colspan + this.colcount()) % this.colcount()
+          : Math.min(colindex + colspan, this.colcount() - 1),
+      };
+    });
+  }
+
+  /**
+   * Continuously calls the given stepFn starting at the given coordinates
+   * until either a new focusable cell is reached or the grid fully loops.
+   */
+  private _advance(stepFn: (cell: T, coords: RowCol) => RowCol) {
+    const startCoords = this.inputs.activeCoords();
+    let prevCoords = {row: startCoords.row, col: startCoords.col};
+    let nextCoords = {row: startCoords.row, col: startCoords.col};
+    let nextCell = this.inputs.gridFocus.activeCell()!;
+
+    while (true) {
+      prevCoords = {row: nextCoords.row, col: nextCoords.col};
+      nextCoords = stepFn(nextCell, nextCoords);
+
+      // The step did not result in any change in coordinates.
+      //
+      // This will happen if the user is at a boundary (start/end row or col)
+      // and tries to advance past it while `wrap` is false.
+      if (nextCoords.row === prevCoords.row && nextCoords.col === prevCoords.col) {
+        return false;
+      }
+
+      // The step has resulted in arriving back to the original coordinates.
+      //
+      // This will happen if the other cells in the grid are unfocusable and `wrap`
+      // is true. The `stepFn` will eventually loop all the way back to the original cells.
+      if (nextCoords.row === startCoords.row && nextCoords.col === startCoords.col) {
+        return false;
+      }
+
+      nextCell = this.inputs.gridFocus.getCell(nextCoords)!;
+
+      // The `stepFn` has successfully reached a cell that is focusable.
+      if (this.inputs.gridFocus.isFocusable(nextCell)) {
+        return this.gotoCoords(nextCoords);
+      }
+    }
+  }
+}