feat(grid): add navigateTo method with optional activation

Author: damyanpetev

src/components/grid.ts

@@ -401,6 +401,16 @@ export class IgcGridLite<T extends object> extends EventEmitterBase<IgcGridLiteE
     this.requestUpdate(PIPELINE);
   }
 
+  /**
+   * Navigates to a position in the grid based on provided row index and column field.
+   * @param row The row index to navigate to
+   * @param column The column field to navigate to, if any
+   * @param activate Optionally also active the navigated cell
+   */
+  public async navigateTo(row: number, column?: Keys<T>, activate = false) {
+    await this._stateController.navigation.navigateTo(row, column, activate);
+  }
+
   /**
    * Returns a {@link ColumnConfiguration} for a given column.
    */

src/controllers/navigation.ts

@@ -53,10 +53,14 @@ export class NavigationController<T extends object> implements ReactiveControlle
     ].field;
   }
 
-  protected scrollToCell(node: ActiveNode<T>) {
-    const row = Array.from(this._virtualizer?.querySelectorAll(GRID_ROW_TAG) ?? []).find(
-      (row) => row.index === node.row
+  protected queryRowByIndex(index: number) {
+    return Array.from(this._virtualizer?.querySelectorAll(GRID_ROW_TAG) ?? []).find(
+      (row) => row.index === index
     ) as unknown as IgcGridLiteRow<T>;
+  }
+
+  protected scrollToCell(node: ActiveNode<T>) {
+    const row = this.queryRowByIndex(node.row);
 
     if (row) {
       row.cells
@@ -128,4 +132,21 @@ export class NavigationController<T extends object> implements ReactiveControlle
       this.handlers.get(event.key)!.call(this);
     }
   }
+
+  public async navigateTo(row: number, column?: Keys<T>, activate = false) {
+    if (activate) this.active = Object.assign(this.nextNode, { row, column });
+
+    // attempt to resolve row in DOM first as a check if layout change will be needed
+    let item: Pick<HTMLElement, 'scrollIntoView'> | undefined = this.queryRowByIndex(row);
+    let completePromise: Promise<void> | undefined;
+
+    if (!item) {
+      item = this._virtualizer?.element(row);
+      completePromise = item && this._virtualizer?.layoutComplete;
+    }
+
+    item?.scrollIntoView({ block: 'nearest' });
+    await completePromise;
+    if (column) this.scrollToCell({ row, column });
+  }
 }

test/activation.test.ts

@@ -1,12 +1,23 @@
+import { setupIgnoreWindowResizeObserverLoopErrors } from '@lit-labs/virtualizer/support/resize-observer-errors.js';
 import { expect } from '@open-wc/testing';
 import type { Keys } from '../src/internal/types.js';
 import GridTestFixture from './utils/grid-fixture.js';
 import data, { type TestData } from './utils/test-data.js';
 
-const TDD = new GridTestFixture(data);
+// reduced width to force scroll:
+const TDD = new GridTestFixture(data, { width: '300px' });
 const keys = Object.keys(data[0]) as Array<Keys<TestData>>;
 
+function isVisibleGrid(element: Element): boolean {
+  const rect = element.getBoundingClientRect();
+  const { top, bottom } = TDD.gridBody.getBoundingClientRect();
+  const { left, right } = TDD.grid.getBoundingClientRect();
+
+  return rect.top >= top && rect.bottom <= bottom && rect.left >= left && rect.right <= right;
+}
+
 describe('Grid activation', () => {
+  setupIgnoreWindowResizeObserverLoopErrors(beforeEach, afterEach);
   beforeEach(async () => await TDD.setUp());
   afterEach(() => TDD.tearDown());
 
@@ -118,4 +129,108 @@ describe('Grid activation', () => {
       expect(TDD.rows.last.cells.first.active).to.be.true;
     });
   });
+
+  describe('navigateTo API', () => {
+    // extend test data to move into virtualized scroll:
+    const testData = [
+      ...data,
+      ...data.map((x) => ({ ...x, id: x.id + data.length })),
+      ...data.map((x) => ({ ...x, id: x.id + data.length * 2 })),
+    ];
+
+    beforeEach(async () => {
+      await TDD.updateProperty('data', testData);
+      // expect horizontal and vertical scroll to ensure test setup doesn't change
+      expect(TDD.grid.scrollWidth > TDD.grid.clientWidth).to.be.true;
+      expect(TDD.gridBody.scrollHeight > TDD.gridBody.clientHeight).to.be.true;
+    });
+
+    it('navigates to rows only', async () => {
+      await TDD.grid.navigateTo(testData.length - 1);
+
+      let cell = TDD.rows.last.cells.first;
+      expect(cell.active).to.be.false;
+      expect(isVisibleGrid(cell.element)).to.be.true;
+
+      await TDD.grid.navigateTo(0);
+
+      cell = TDD.rows.first.cells.first;
+      expect(cell.active).to.be.false;
+      expect(isVisibleGrid(cell.element)).to.be.true;
+    });
+
+    it('navigates to a specific row and column', async () => {
+      await TDD.grid.navigateTo(testData.length - 2, 'name');
+
+      const cell = TDD.rows.get(-2).cells.get('name');
+      expect(cell.active).to.be.false;
+      expect(isVisibleGrid(cell.element)).to.be.true;
+    });
+
+    it('navigates to a cell within already scrolled-to row', async () => {
+      await TDD.grid.navigateTo(testData.length - 1, 'id');
+
+      let cell = TDD.rows.last.cells.get('id');
+      expect(isVisibleGrid(cell.element)).to.be.true;
+
+      // last cell
+      cell = TDD.rows.last.cells.last;
+      expect(isVisibleGrid(cell.element)).to.be.false;
+      await TDD.grid.navigateTo(testData.length - 1, keys.at(-1));
+
+      expect(isVisibleGrid(cell.element)).to.be.true;
+    });
+
+    it('navigates through all columns', async () => {
+      for (const key of keys) {
+        await TDD.grid.navigateTo(0, key);
+        const cell = TDD.rows.first.cells.get(key);
+        expect(isVisibleGrid(cell.element)).to.be.true;
+      }
+    });
+
+    it('updates active state when navigating', async () => {
+      await TDD.grid.navigateTo(0, 'id', true);
+      expect(TDD.rows.first.cells.get('id').active).to.be.true;
+
+      await TDD.grid.navigateTo(1, 'name', true);
+      expect(TDD.rows.first.cells.get('id').active).to.be.false;
+
+      let cell = TDD.rows.get(1).cells.get('name');
+      expect(cell.active).to.be.true;
+      expect(isVisibleGrid(cell.element)).to.be.true;
+
+      // last cell
+      await TDD.grid.navigateTo(testData.length - 1, keys.at(-1), true);
+
+      cell = TDD.rows.last.cells.last;
+      expect(cell.active).to.be.true;
+      expect(isVisibleGrid(cell.element)).to.be.true;
+    });
+
+    it('can navigate after click activation', async () => {
+      await TDD.clickCell(TDD.rows.first.cells.first);
+      expect(TDD.rows.first.cells.first.active).to.be.true;
+
+      await TDD.grid.navigateTo(3, 'active', true);
+      expect(TDD.rows.first.cells.first.active).to.be.false;
+
+      const cell = TDD.rows.get(3).cells.get('active');
+      expect(cell.active).to.be.true;
+      expect(isVisibleGrid(cell.element)).to.be.true;
+    });
+
+    it('keyboard navigation works after navigateTo', async () => {
+      await TDD.grid.navigateTo(2, 'id', true);
+      expect(TDD.rows.get(2).cells.get('id').active).to.be.true;
+
+      await TDD.fireNavigationEvent({ key: 'ArrowRight' });
+      expect(TDD.rows.get(2).cells.get('name').active).to.be.true;
+
+      await TDD.fireNavigationEvent({ key: 'ArrowDown' });
+      const cell = TDD.rows.get(3).cells.get('name');
+      expect(cell.active).to.be.true;
+      expect(isVisibleGrid(cell.element)).to.be.true;
+    });
+  });
 });