@vaadin/grid 24.2.0-alpha4 → 24.2.0-dev.538d07bdf

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/grid",
-  "version": "24.2.0-alpha4",
+  "version": "24.2.0-dev.538d07bdf",
   "publishConfig": {
     "access": "public"
   },
@@ -46,18 +46,18 @@
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/a11y-base": "24.2.0-alpha4",
-    "@vaadin/checkbox": "24.2.0-alpha4",
-    "@vaadin/component-base": "24.2.0-alpha4",
-    "@vaadin/lit-renderer": "24.2.0-alpha4",
-    "@vaadin/text-field": "24.2.0-alpha4",
-    "@vaadin/vaadin-lumo-styles": "24.2.0-alpha4",
-    "@vaadin/vaadin-material-styles": "24.2.0-alpha4",
-    "@vaadin/vaadin-themable-mixin": "24.2.0-alpha4"
+    "@vaadin/a11y-base": "24.2.0-dev.538d07bdf",
+    "@vaadin/checkbox": "24.2.0-dev.538d07bdf",
+    "@vaadin/component-base": "24.2.0-dev.538d07bdf",
+    "@vaadin/lit-renderer": "24.2.0-dev.538d07bdf",
+    "@vaadin/text-field": "24.2.0-dev.538d07bdf",
+    "@vaadin/vaadin-lumo-styles": "24.2.0-dev.538d07bdf",
+    "@vaadin/vaadin-material-styles": "24.2.0-dev.538d07bdf",
+    "@vaadin/vaadin-themable-mixin": "24.2.0-dev.538d07bdf"
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/testing-helpers": "^0.4.2",
+    "@vaadin/testing-helpers": "^0.4.3",
     "lit": "^2.0.0",
     "sinon": "^13.0.2"
   },
@@ -65,5 +65,5 @@
     "web-types.json",
     "web-types.lit.json"
   ],
-  "gitHead": "aaf7c5ebfea62628210eead4229be1718ac6b129"
+  "gitHead": "86c2fd5f37cf1240af98f7c7d752518c8d701db2"
 }

package/src/lit/column-renderer-directives.d.ts

@@ -4,9 +4,8 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 /* eslint-disable max-classes-per-file */
-import type { TemplateResult } from 'lit';
 import type { DirectiveResult } from 'lit/directive';
-import type { LitRenderer } from '@vaadin/lit-renderer';
+import type { LitRenderer, LitRendererResult } from '@vaadin/lit-renderer';
 import { LitRendererDirective } from '@vaadin/lit-renderer';
 import type { GridItemModel } from '../vaadin-grid.js';
 import type { GridColumn } from '../vaadin-grid-column.js';
@@ -15,10 +14,10 @@ export type GridColumnBodyLitRenderer<TItem> = (
   item: TItem,
   model: GridItemModel<TItem>,
   column: GridColumn,
-) => TemplateResult;
+) => LitRendererResult;
 
-export type GridColumnHeaderLitRenderer = (column: GridColumn) => TemplateResult;
-export type GridColumnFooterLitRenderer = (column: GridColumn) => TemplateResult;
+export type GridColumnHeaderLitRenderer = (column: GridColumn) => LitRendererResult;
+export type GridColumnFooterLitRenderer = (column: GridColumn) => LitRendererResult;
 
 declare abstract class AbstractGridColumnRendererDirective<R extends LitRenderer> extends LitRendererDirective<
   GridColumn,

package/src/lit/renderer-directives.d.ts

@@ -3,12 +3,16 @@
  * Copyright (c) 2017 - 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import type { TemplateResult } from 'lit';
 import type { DirectiveResult } from 'lit/directive';
+import type { LitRendererResult } from '@vaadin/lit-renderer';
 import { LitRendererDirective } from '@vaadin/lit-renderer';
 import type { Grid, GridItemModel } from '../vaadin-grid.js';
 
-export type GridRowDetailsLitRenderer<TItem> = (item: TItem, model: GridItemModel<TItem>, grid: Grid) => TemplateResult;
+export type GridRowDetailsLitRenderer<TItem> = (
+  item: TItem,
+  model: GridItemModel<TItem>,
+  grid: Grid,
+) => LitRendererResult;
 
 export declare class GridRowDetailsRendererDirective<TItem> extends LitRendererDirective<
   Grid,

package/src/vaadin-grid-column.d.ts

@@ -43,6 +43,17 @@ export declare class ColumnBaseMixinClass<TItem> {
    */
   frozenToEnd: boolean;
 
+  /**
+   * When true, the cells for this column will be rendered with the `role` attribute
+   * set as `rowheader`, instead of the `gridcell` role value used by default.
+   *
+   * When a column is set as row header, its cells will be announced by screen readers
+   * while navigating to help user identify the current row as uniquely as possible.
+   *
+   * @attr {boolean} row-header
+   */
+  rowHeader: boolean;
+
   /**
    * When set to true, the cells for this column are hidden.
    */

package/src/vaadin-grid-column.js

@@ -61,6 +61,21 @@ export const ColumnBaseMixin = (superClass) =>
           value: false,
         },
 
+        /**
+         * When true, the cells for this column will be rendered with the `role` attribute
+         * set as `rowheader`, instead of the `gridcell` role value used by default.
+         *
+         * When a column is set as row header, its cells will be announced by screen readers
+         * while navigating to help user identify the current row as uniquely as possible.
+         *
+         * @attr {boolean} row-header
+         * @type {boolean}
+         */
+        rowHeader: {
+          type: Boolean,
+          value: false,
+        },
+
         /**
          * When set to true, the cells for this column are hidden.
          */
@@ -222,6 +237,7 @@ export const ColumnBaseMixin = (superClass) =>
         '_resizableChanged(resizable, _headerCell)',
         '_reorderStatusChanged(_reorderStatus, _headerCell, _footerCell, _cells.*)',
         '_hiddenChanged(hidden, _headerCell, _footerCell, _cells.*)',
+        '_rowHeaderChanged(rowHeader, _cells.*)',
       ];
     }
 
@@ -407,6 +423,17 @@ export const ColumnBaseMixin = (superClass) =>
       }
     }
 
+    /** @private */
+    _rowHeaderChanged(rowHeader, cells) {
+      if (!cells.value) {
+        return;
+      }
+
+      cells.value.forEach((cell) => {
+        cell.setAttribute('role', rowHeader ? 'rowheader' : 'gridcell');
+      });
+    }
+
     /**
      * @param {string} path
      * @return {string}

package/src/vaadin-grid-data-provider-mixin.d.ts

@@ -33,31 +33,6 @@ export type GridDataProvider<TItem> = (
   callback: GridDataProviderCallback<TItem>,
 ) => void;
 
-export declare class ItemCache<TItem> {
-  grid: HTMLElement;
-  parentCache: ItemCache<TItem> | undefined;
-  parentItem: TItem | undefined;
-  itemCaches: object | null;
-  items: object | null;
-  effectiveSize: number;
-  size: number;
-  pendingRequests: object | null;
-
-  constructor(grid: HTMLElement, parentCache: ItemCache<TItem> | undefined, parentItem: TItem | undefined);
-
-  isLoading(): boolean;
-
-  getItemForIndex(index: number): TItem | undefined;
-
-  updateSize(): void;
-
-  ensureSubCacheForScaledIndex(scaledIndex: number): void;
-
-  getCacheAndIndex(index: number): { cache: ItemCache<TItem>; scaledIndex: number };
-
-  getFlatIndex(scaledIndex: number): number;
-}
-
 export declare function DataProviderMixin<TItem, T extends Constructor<HTMLElement>>(
   base: T,
 ): Constructor<DataProviderMixinClass<TItem>> & T;

package/src/vaadin-grid-data-provider-mixin.js

@@ -4,115 +4,10 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { timeOut } from '@vaadin/component-base/src/async.js';
+import { DataProviderController } from '@vaadin/component-base/src/data-provider-controller.js';
 import { Debouncer } from '@vaadin/component-base/src/debounce.js';
 import { getBodyRowCells, updateCellsPart, updateState } from './vaadin-grid-helpers.js';
 
-/**
- * @private
- */
-export const ItemCache = class ItemCache {
-  /**
-   * @param {!HTMLElement} grid
-   * @param {!ItemCache | undefined} parentCache
-   * @param {!GridItem | undefined} parentItem
-   */
-  constructor(grid, parentCache, parentItem) {
-    /** @type {!HTMLElement} */
-    this.grid = grid;
-    /** @type {!ItemCache | undefined} */
-    this.parentCache = parentCache;
-    /** @type {!GridItem | undefined} */
-    this.parentItem = parentItem;
-    /** @type {object} */
-    this.itemCaches = {};
-    /** @type {object[]} */
-    this.items = [];
-    /** @type {number} */
-    this.effectiveSize = 0;
-    /** @type {number} */
-    this.size = 0;
-    /** @type {object} */
-    this.pendingRequests = {};
-  }
-
-  /**
-   * @return {boolean}
-   */
-  isLoading() {
-    return Boolean(
-      Object.keys(this.pendingRequests).length ||
-        Object.keys(this.itemCaches).filter((index) => {
-          return this.itemCaches[index].isLoading();
-        })[0],
-    );
-  }
-
-  /**
-   * @param {number} index
-   * @return {!GridItem | undefined}
-   */
-  getItemForIndex(index) {
-    const { cache, scaledIndex } = this.getCacheAndIndex(index);
-    return cache.items[scaledIndex];
-  }
-
-  updateSize() {
-    this.effectiveSize =
-      !this.parentItem || this.grid._isExpanded(this.parentItem)
-        ? this.size +
-          Object.keys(this.itemCaches).reduce((prev, curr) => {
-            const subCache = this.itemCaches[curr];
-            subCache.updateSize();
-            return prev + subCache.effectiveSize;
-          }, 0)
-        : 0;
-  }
-
-  /**
-   * @param {number} scaledIndex
-   */
-  ensureSubCacheForScaledIndex(scaledIndex) {
-    if (!this.itemCaches[scaledIndex]) {
-      const subCache = new ItemCache(this.grid, this, this.items[scaledIndex]);
-      this.itemCaches[scaledIndex] = subCache;
-      this.grid._loadPage(0, subCache);
-    }
-  }
-
-  /**
-   * @param {number} index
-   * @return {{cache: !ItemCache, scaledIndex: number}}
-   */
-  getCacheAndIndex(index) {
-    let thisLevelIndex = index;
-    for (const [index, subCache] of Object.entries(this.itemCaches)) {
-      const numberIndex = Number(index);
-      if (thisLevelIndex <= numberIndex) {
-        return { cache: this, scaledIndex: thisLevelIndex };
-      } else if (thisLevelIndex <= numberIndex + subCache.effectiveSize) {
-        return subCache.getCacheAndIndex(thisLevelIndex - numberIndex - 1);
-      }
-      thisLevelIndex -= subCache.effectiveSize;
-    }
-    return { cache: this, scaledIndex: thisLevelIndex };
-  }
-
-  /**
-   * Gets the scaled index as flattened index on this cache level.
-   * In practice, this means that the effective size of any expanded
-   * subcaches preceding the index are added to the value.
-   * @param {number} scaledIndex
-   * @return {number} The flat index on this cache level.
-   */
-  getFlatIndex(scaledIndex) {
-    const clampedIndex = Math.max(0, Math.min(this.size - 1, scaledIndex));
-
-    return Object.entries(this.itemCaches).reduce((prev, [index, subCache]) => {
-      return clampedIndex > Number(index) ? prev + subCache.effectiveSize : prev;
-    }, clampedIndex);
-  }
-};
-
 /**
  * @polymerMixin
  */
@@ -180,18 +75,6 @@ export const DataProviderMixin = (superClass) =>
           reflectToAttribute: true,
         },
 
-        /**
-         * @type {!ItemCache}
-         * @protected
-         */
-        _cache: {
-          type: Object,
-          value() {
-            const cache = new ItemCache(this);
-            return cache;
-          },
-        },
-
         /**
          * @protected
          */
@@ -243,12 +126,32 @@ export const DataProviderMixin = (superClass) =>
       return ['_sizeChanged(size)', '_expandedItemsChanged(expandedItems.*)'];
     }
 
+    constructor() {
+      super();
+
+      /** @type {DataProviderController} */
+      this._dataProviderController = new DataProviderController(this, {
+        size: this.size,
+        pageSize: this.pageSize,
+        isExpanded: this._isExpanded.bind(this),
+        dataProvider: this.dataProvider ? this.dataProvider.bind(this) : null,
+        dataProviderParams: () => {
+          return {
+            sortOrders: this._mapSorters(),
+            filters: this._mapFilters(),
+          };
+        },
+      });
+
+      this._dataProviderController.addEventListener('page-requested', this._onDataProviderPageRequested.bind(this));
+      this._dataProviderController.addEventListener('page-received', this._onDataProviderPageReceived.bind(this));
+      this._dataProviderController.addEventListener('page-loaded', this._onDataProviderPageLoaded.bind(this));
+    }
+
     /** @private */
     _sizeChanged(size) {
-      const delta = size - this._cache.size;
-      this._cache.size += delta;
-      this._cache.effectiveSize += delta;
-      this._effectiveSize = this._cache.effectiveSize;
+      this._dataProviderController.setSize(size);
+      this._effectiveSize = this._dataProviderController.effectiveSize;
     }
 
     /** @private */
@@ -271,17 +174,17 @@ export const DataProviderMixin = (superClass) =>
       }
 
       el.index = index;
-      const { cache, scaledIndex } = this._cache.getCacheAndIndex(index);
-      const item = cache.items[scaledIndex];
+
+      const { item } = this._dataProviderController.getFlatIndexInfo(index);
       if (item) {
         this.__updateLoading(el, false);
         this._updateItem(el, item);
         if (this._isExpanded(item)) {
-          cache.ensureSubCacheForScaledIndex(scaledIndex);
+          this._dataProviderController.ensureFlatIndexChildrenLoaded(index);
         }
       } else {
         this.__updateLoading(el, true);
-        this._loadPage(this._getPageForIndex(scaledIndex), cache);
+        this._dataProviderController.ensureFlatIndexLoaded(index);
       }
     }
 
@@ -321,8 +224,8 @@ export const DataProviderMixin = (superClass) =>
 
     /** @private */
     _expandedItemsChanged() {
-      this._cache.updateSize();
-      this._effectiveSize = this._cache.effectiveSize;
+      this._dataProviderController.recalculateEffectiveSize();
+      this._effectiveSize = this._dataProviderController.effectiveSize;
       this.__updateVisibleRows();
     }
 
@@ -362,121 +265,68 @@ export const DataProviderMixin = (superClass) =>
      * @return {number}
      * @protected
      */
-    _getIndexLevel(index) {
-      let { cache } = this._cache.getCacheAndIndex(index);
-      let level = 0;
-      while (cache.parentCache) {
-        cache = cache.parentCache;
-        level += 1;
-      }
+    _getIndexLevel(index = 0) {
+      const { level } = this._dataProviderController.getFlatIndexInfo(index);
       return level;
     }
 
-    /**
-     * @param {number} page
-     * @param {ItemCache} cache
-     * @protected
-     */
-    _loadPage(page, cache) {
-      // Make sure same page isn't requested multiple times.
-      if (!cache.pendingRequests[page] && this.dataProvider) {
-        this._setLoading(true);
-        cache.pendingRequests[page] = true;
-        const params = {
-          page,
-          pageSize: this.pageSize,
-          sortOrders: this._mapSorters(),
-          filters: this._mapFilters(),
-          parentItem: cache.parentItem,
-        };
-
-        this.dataProvider(params, (items, size) => {
-          if (size !== undefined) {
-            cache.size = size;
-          } else if (params.parentItem) {
-            cache.size = items.length;
-          }
+    /** @protected */
+    _onDataProviderPageRequested() {
+      this._setLoading(true);
+    }
 
-          // Populate the cache with new items
-          items.forEach((item, itemsIndex) => {
-            const itemIndex = page * this.pageSize + itemsIndex;
-            cache.items[itemIndex] = item;
-          });
-
-          // With the new items added, update the cache size and the grid's effective size
-          this._cache.updateSize();
-          this._effectiveSize = this._cache.effectiveSize;
-
-          // After updating the cache, check if some of the expanded items should have sub-caches loaded
-          this._getRenderedRows().forEach((row) => {
-            const { cache, scaledIndex } = this._cache.getCacheAndIndex(row.index);
-            const item = cache.items[scaledIndex];
-            if (item && this._isExpanded(item)) {
-              cache.ensureSubCacheForScaledIndex(scaledIndex);
-            }
-          });
-
-          this._hasData = true;
-
-          // Remove the pending request
-          delete cache.pendingRequests[page];
-
-          // Schedule a debouncer to update the visible rows
-          this._debouncerApplyCachedData = Debouncer.debounce(this._debouncerApplyCachedData, timeOut.after(0), () => {
-            this._setLoading(false);
-
-            this._getRenderedRows().forEach((row) => {
-              const cachedItem = this._cache.getItemForIndex(row.index);
-              if (cachedItem) {
-                this._getItem(row.index, row);
-              }
-            });
-
-            this.__scrollToPendingIndexes();
-          });
-
-          // If the grid is not loading anything, flush the debouncer immediately
-          if (!this._cache.isLoading()) {
-            this._debouncerApplyCachedData.flush();
-          }
+    /** @protected */
+    _onDataProviderPageReceived() {
+      // With the new items added, update the cache size and the grid's effective size
+      this._effectiveSize = this._dataProviderController.effectiveSize;
 
-          // Notify that new data has been received
-          this._onDataProviderPageLoaded();
-        });
-      }
+      // After updating the cache, check if some of the expanded items should have sub-caches loaded
+      this._getRenderedRows().forEach((row) => {
+        this._dataProviderController.ensureFlatIndexChildrenLoaded(row.index);
+      });
+
+      this._hasData = true;
     }
 
     /** @protected */
-    _onDataProviderPageLoaded() {}
+    _onDataProviderPageLoaded() {
+      // Schedule a debouncer to update the visible rows
+      this._debouncerApplyCachedData = Debouncer.debounce(this._debouncerApplyCachedData, timeOut.after(0), () => {
+        this._setLoading(false);
+
+        this._getRenderedRows().forEach((row) => {
+          const { item } = this._dataProviderController.getFlatIndexInfo(row.index);
+          if (item) {
+            this._getItem(row.index, row);
+          }
+        });
 
-    /**
-     * @param {number} index
-     * @return {number}
-     * @private
-     */
-    _getPageForIndex(index) {
-      return Math.floor(index / this.pageSize);
+        this.__scrollToPendingIndexes();
+      });
+
+      // If the grid is not loading anything, flush the debouncer immediately
+      if (!this._dataProviderController.isLoading) {
+        this._debouncerApplyCachedData.flush();
+      }
     }
 
     /**
      * Clears the cached pages and reloads data from dataprovider when needed.
      */
     clearCache() {
-      this._cache = new ItemCache(this);
-      this._cache.size = this.size || 0;
-      this._cache.updateSize();
+      this._dataProviderController.clearCache();
       this._hasData = false;
       this.__updateVisibleRows();
-
-      if (!this._effectiveSize) {
-        this._loadPage(0, this._cache);
-      }
+      this._ensureFirstPageLoaded();
     }
 
     /** @private */
     _pageSizeChanged(pageSize, oldPageSize) {
       if (oldPageSize !== undefined && pageSize !== oldPageSize) {
-        this.clearCache();
+        this._dataProviderController.setPageSize(pageSize);
+        this._hasData = false;
+        this.__updateVisibleRows();
+        this._ensureFirstPageLoaded();
       }
     }
 
@@ -494,8 +344,11 @@ export const DataProviderMixin = (superClass) =>
 
     /** @private */
     _dataProviderChanged(dataProvider, oldDataProvider) {
+      this._dataProviderController.setDataProvider(dataProvider ? dataProvider.bind(this) : null);
+
       if (oldDataProvider !== undefined) {
-        this.clearCache();
+        this._hasData = false;
+        this.__updateVisibleRows();
       }
 
       this._ensureFirstPageLoaded();
@@ -512,7 +365,7 @@ export const DataProviderMixin = (superClass) =>
       if (!this._hasData) {
         // Load data before adding rows to make sure they have content when
         // rendered for the first time.
-        this._loadPage(0, this._cache);
+        this._dataProviderController.ensureFirstPageLoaded();
       }
     }
 
@@ -562,39 +415,15 @@ export const DataProviderMixin = (superClass) =>
       // ending up in a loading state. Try scrolling to the index until the target
       // index stabilizes.
       let targetIndex;
-      while (targetIndex !== (targetIndex = this.__getGlobalFlatIndex(indexes))) {
+      while (targetIndex !== (targetIndex = this._dataProviderController.getFlatIndexByPath(indexes))) {
         this._scrollToFlatIndex(targetIndex);
       }
 
-      if (this._cache.isLoading() || !this.clientHeight) {
+      if (this._dataProviderController.isLoading || !this.clientHeight) {
         this.__pendingScrollToIndexes = indexes;
       }
     }
 
-    /**
-     * Recursively returns the globally flat index of the item the given indexes point to.
-     * Each index in the array points to a sub-item of the previous index.
-     * Using `Infinity` as an index will point to the last item on the level.
-     *
-     * @param {!Array<number>} indexes
-     * @param {!ItemCache} cache
-     * @param {number} flatIndex
-     * @return {number}
-     * @private
-     */
-    __getGlobalFlatIndex([levelIndex, ...subIndexes], cache = this._cache, flatIndex = 0) {
-      if (levelIndex === Infinity) {
-        // Treat Infinity as the last index on the level
-        levelIndex = cache.size - 1;
-      }
-      const flatIndexOnLevel = cache.getFlatIndex(levelIndex);
-      const subCache = cache.itemCaches[levelIndex];
-      if (subCache && subCache.effectiveSize && subIndexes.length) {
-        return this.__getGlobalFlatIndex(subIndexes, subCache, flatIndex + flatIndexOnLevel + 1);
-      }
-      return flatIndex + flatIndexOnLevel;
-    }
-
     /** @private */
     __scrollToPendingIndexes() {
       if (this.__pendingScrollToIndexes && this.$.items.children.length) {

package/src/vaadin-grid-keyboard-navigation-mixin.js

@@ -475,7 +475,7 @@ export const KeyboardNavigationMixin = (superClass) =>
         // Row details navigation logic
         if (activeRowGroup === this.$.items) {
           const item = activeRow._item;
-          const dstItem = this._cache.getItemForIndex(dstRowIndex);
+          const { item: dstItem } = this._dataProviderController.getFlatIndexInfo(dstRowIndex);
           // Should we navigate to row details?
           if (isRowDetails) {
             dstIsRowDetails = dy === 0;

package/src/vaadin-grid-selection-column-base-mixin.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright (c) 2016 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+
+export declare function GridSelectionColumnBaseMixin<TItem, T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<GridSelectionColumnBaseMixinClass<TItem>> & T;
+
+/**
+ * A mixin that provides basic functionality for the
+ * `<vaadin-grid-selection-column>`. This includes properties, cell rendering,
+ * and overridable methods for handling changes to the selection state.
+ *
+ * **NOTE**: This mixin is re-used by the Flow component, and as such must not
+ * implement any selection state updates for the column element or the grid.
+ * Web component-specific selection state updates must be implemented in the
+ * `<vaadin-grid-selection-column>` itself, by overriding the protected methods
+ * provided by this mixin.
+ *
+ * @polymerMixin
+ */
+export declare class GridSelectionColumnBaseMixinClass<TItem> {
+  /**
+   * When true, all the items are selected.
+   * @attr {boolean} select-all
+   */
+  selectAll: boolean;
+
+  /**
+   * When true, the active gets automatically selected.
+   * @attr {boolean} auto-select
+   */
+  autoSelect: boolean;
+
+  /**
+   * Override to handle the user selecting all items.
+   */
+  protected _selectAll(): void;
+
+  /**
+   * Override to handle the user deselecting all items.
+   */
+  protected _deselectAll(): void;
+
+  /**
+   * Override to handle the user selecting an item.
+   */
+  protected _selectItem(item: TItem): void;
+
+  /**
+   * Override to handle the user deselecting an item.
+   */
+  protected _deselectItem(item: TItem): void;
+}