@vaadin/grid 22.0.0-alpha7

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

@@ -0,0 +1,108 @@
+import { GridDataProvider } from './interfaces';
+
+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 };
+}
+
+declare function DataProviderMixin<TItem, T extends new (...args: any[]) => {}>(
+  base: T
+): T & DataProviderMixinConstructor<TItem>;
+
+interface DataProviderMixinConstructor<TItem> {
+  new (...args: any[]): DataProviderMixin<TItem>;
+}
+
+interface DataProviderMixin<TItem> {
+  /**
+   * Number of items fetched at a time from the dataprovider.
+   * @attr {number} page-size
+   */
+  pageSize: number;
+
+  /**
+   * The number of root-level items in the grid.
+   * @attr {number} size
+   */
+  size: number;
+
+  /**
+   * Function that provides items lazily. Receives arguments `params`, `callback`
+   *
+   * `params.page` Requested page index
+   *
+   * `params.pageSize` Current page size
+   *
+   * `params.filters` Currently applied filters
+   *
+   * `params.sortOrders` Currently applied sorting orders
+   *
+   * `params.parentItem` When tree is used, and sublevel items
+   * are requested, reference to parent item of the requested sublevel.
+   * Otherwise `undefined`.
+   *
+   * `callback(items, size)` Callback function with arguments:
+   *   - `items` Current page of items
+   *   - `size` Total number of items. When tree sublevel items
+   *     are requested, total number of items in the requested sublevel.
+   *     Optional when tree is not used, required for tree.
+   */
+  dataProvider: GridDataProvider<TItem> | null | undefined;
+
+  /**
+   * `true` while data is being requested from the data provider.
+   */
+  readonly loading: boolean | null | undefined;
+
+  /**
+   * Path to an item sub-property that identifies the item.
+   * @attr {string} item-id-path
+   */
+  itemIdPath: string | null | undefined;
+
+  /**
+   * An array that contains the expanded items.
+   */
+  expandedItems: TItem[];
+
+  /**
+   * Returns a value that identifies the item. Uses `itemIdPath` if available.
+   * Can be customized by overriding.
+   */
+  getItemId(item: TItem): TItem | unknown;
+
+  /**
+   * Expands the given item tree.
+   */
+  expandItem(item: TItem): void;
+
+  /**
+   * Collapses the given item tree.
+   */
+  collapseItem(item: TItem): void;
+
+  /**
+   * Clears the cached pages and reloads data from dataprovider when needed.
+   */
+  clearCache(): void;
+}
+
+export { DataProviderMixin, DataProviderMixinConstructor, ItemCache };

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

@@ -0,0 +1,520 @@
+/**
+ * @license
+ * Copyright (c) 2021 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { Debouncer } from '@vaadin/component-base/src/debounce.js';
+import { timeOut } from '@vaadin/component-base/src/async.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;
+    const keys = Object.keys(this.itemCaches);
+    for (let i = 0; i < keys.length; i++) {
+      const expandedIndex = Number(keys[i]);
+      const subCache = this.itemCaches[expandedIndex];
+      if (thisLevelIndex <= expandedIndex) {
+        return { cache: this, scaledIndex: thisLevelIndex };
+      } else if (thisLevelIndex <= expandedIndex + subCache.effectiveSize) {
+        return subCache.getCacheAndIndex(thisLevelIndex - expandedIndex - 1);
+      }
+      thisLevelIndex -= subCache.effectiveSize;
+    }
+    return { cache: this, scaledIndex: thisLevelIndex };
+  }
+};
+
+/**
+ * @polymerMixin
+ */
+export const DataProviderMixin = (superClass) =>
+  class DataProviderMixin extends superClass {
+    static get properties() {
+      return {
+        /**
+         * The number of root-level items in the grid.
+         * @attr {number} size
+         * @type {number}
+         */
+        size: {
+          type: Number,
+          notify: true
+        },
+
+        /**
+         * Number of items fetched at a time from the dataprovider.
+         * @attr {number} page-size
+         * @type {number}
+         */
+        pageSize: {
+          type: Number,
+          value: 50,
+          observer: '_pageSizeChanged'
+        },
+
+        /**
+         * Function that provides items lazily. Receives arguments `params`, `callback`
+         *
+         * `params.page` Requested page index
+         *
+         * `params.pageSize` Current page size
+         *
+         * `params.filters` Currently applied filters
+         *
+         * `params.sortOrders` Currently applied sorting orders
+         *
+         * `params.parentItem` When tree is used, and sublevel items
+         * are requested, reference to parent item of the requested sublevel.
+         * Otherwise `undefined`.
+         *
+         * `callback(items, size)` Callback function with arguments:
+         *   - `items` Current page of items
+         *   - `size` Total number of items. When tree sublevel items
+         *     are requested, total number of items in the requested sublevel.
+         *     Optional when tree is not used, required for tree.
+         *
+         * @type {GridDataProvider | null | undefined}
+         */
+        dataProvider: {
+          type: Object,
+          notify: true,
+          observer: '_dataProviderChanged'
+        },
+
+        /**
+         * `true` while data is being requested from the data provider.
+         */
+        loading: {
+          type: Boolean,
+          notify: true,
+          readOnly: true,
+          reflectToAttribute: true
+        },
+
+        /**
+         * @type {!ItemCache}
+         * @protected
+         */
+        _cache: {
+          type: Object,
+          value: function () {
+            const cache = new ItemCache(this);
+            return cache;
+          }
+        },
+
+        /**
+         * @protected
+         */
+        _hasData: {
+          type: Boolean,
+          value: false
+        },
+
+        /**
+         * Path to an item sub-property that identifies the item.
+         * @attr {string} item-id-path
+         */
+        itemIdPath: {
+          type: String,
+          value: null
+        },
+
+        /**
+         * An array that contains the expanded items.
+         * @type {!Array<!GridItem>}
+         */
+        expandedItems: {
+          type: Object,
+          notify: true,
+          value: () => []
+        },
+
+        /**
+         * @private
+         */
+        __expandedKeys: {
+          type: Object,
+          value: () => new Set()
+        }
+      };
+    }
+
+    static get observers() {
+      return ['_sizeChanged(size)', '_itemIdPathChanged(itemIdPath)', '_expandedItemsChanged(expandedItems.*)'];
+    }
+
+    /** @private */
+    _sizeChanged(size) {
+      const delta = size - this._cache.size;
+      this._cache.size += delta;
+      this._cache.effectiveSize += delta;
+      this._effectiveSize = this._cache.effectiveSize;
+    }
+
+    /**
+     * @param {number} index
+     * @param {HTMLElement} el
+     * @protected
+     */
+    _getItem(index, el) {
+      if (index >= this._effectiveSize) {
+        return;
+      }
+
+      el.index = index;
+      const { cache, scaledIndex } = this._cache.getCacheAndIndex(index);
+      const item = cache.items[scaledIndex];
+      if (item) {
+        el.toggleAttribute('loading', false);
+        this._updateItem(el, item);
+        if (this._isExpanded(item)) {
+          cache.ensureSubCacheForScaledIndex(scaledIndex);
+        }
+      } else {
+        el.toggleAttribute('loading', true);
+        this._loadPage(this._getPageForIndex(scaledIndex), cache);
+      }
+    }
+
+    /**
+     * Returns a value that identifies the item. Uses `itemIdPath` if available.
+     * Can be customized by overriding.
+     * @param {!GridItem} item
+     * @return {!GridItem | !unknown}
+     */
+    getItemId(item) {
+      return this.itemIdPath ? this.get(this.itemIdPath, item) : item;
+    }
+
+    /**
+     * @param {!GridItem} item
+     * @return {boolean}
+     * @protected
+     */
+    _isExpanded(item) {
+      return this.__expandedKeys.has(this.getItemId(item));
+    }
+
+    /** @private */
+    _expandedItemsChanged() {
+      this.__cacheExpandedKeys();
+      this._cache.updateSize();
+      this._effectiveSize = this._cache.effectiveSize;
+      this.__updateVisibleRows();
+    }
+
+    /** @private */
+    _itemIdPathChanged() {
+      this.__cacheExpandedKeys();
+    }
+
+    /** @private */
+    __cacheExpandedKeys() {
+      if (this.expandedItems) {
+        this.__expandedKeys = new Set();
+        this.expandedItems.forEach((item) => {
+          this.__expandedKeys.add(this.getItemId(item));
+        });
+      }
+    }
+
+    /**
+     * Expands the given item tree.
+     * @param {!GridItem} item
+     */
+    expandItem(item) {
+      if (!this._isExpanded(item)) {
+        this.expandedItems = [...this.expandedItems, item];
+      }
+    }
+
+    /**
+     * Collapses the given item tree.
+     * @param {!GridItem} item
+     */
+    collapseItem(item) {
+      if (this._isExpanded(item)) {
+        this.expandedItems = this.expandedItems.filter((i) => !this._itemsEqual(i, item));
+      }
+    }
+
+    /**
+     * @param {number} index
+     * @return {number}
+     * @protected
+     */
+    _getIndexLevel(index) {
+      let { cache } = this._cache.getCacheAndIndex(index);
+      let level = 0;
+      while (cache.parentCache) {
+        cache = cache.parentCache;
+        level++;
+      }
+      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;
+            }
+          }
+
+          const currentItems = Array.from(this.$.items.children).map((row) => row._item);
+
+          // Populate the cache with new items
+          items.forEach((item, itemsIndex) => {
+            const itemIndex = page * this.pageSize + itemsIndex;
+            cache.items[itemIndex] = item;
+            if (this._isExpanded(item) && currentItems.indexOf(item) > -1) {
+              // Force synchronous data request for expanded item sub-cache
+              cache.ensureSubCacheForScaledIndex(itemIndex);
+            }
+          });
+
+          this._hasData = true;
+
+          delete cache.pendingRequests[page];
+
+          this._debouncerApplyCachedData = Debouncer.debounce(this._debouncerApplyCachedData, timeOut.after(0), () => {
+            this._setLoading(false);
+            this._cache.updateSize();
+            this._effectiveSize = this._cache.effectiveSize;
+
+            Array.from(this.$.items.children)
+              .filter((row) => !row.hidden)
+              .forEach((row) => {
+                const cachedItem = this._cache.getItemForIndex(row.index);
+                if (cachedItem) {
+                  this._getItem(row.index, row);
+                }
+              });
+
+            this.__scrollToPendingIndex();
+          });
+
+          if (!this._cache.isLoading()) {
+            this._debouncerApplyCachedData.flush();
+          }
+
+          this.__itemsReceived();
+        });
+      }
+    }
+
+    /**
+     * @param {number} index
+     * @return {number}
+     * @private
+     */
+    _getPageForIndex(index) {
+      return Math.floor(index / this.pageSize);
+    }
+
+    /**
+     * 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._hasData = false;
+      this.__updateVisibleRows();
+
+      if (!this._effectiveSize) {
+        this._loadPage(0, this._cache);
+      }
+    }
+
+    /** @private */
+    _pageSizeChanged(pageSize, oldPageSize) {
+      if (oldPageSize !== undefined && pageSize !== oldPageSize) {
+        this.clearCache();
+      }
+    }
+
+    /** @protected */
+    _checkSize() {
+      if (this.size === undefined && this._effectiveSize === 0) {
+        console.warn(
+          'The <vaadin-grid> needs the total number of items' +
+            ' in order to display rows. Set the total number of items' +
+            ' to the `size` property, or provide the total number of items' +
+            ' in the second argument of the `dataProvider`’s `callback` call.'
+        );
+      }
+    }
+
+    /** @private */
+    _dataProviderChanged(dataProvider, oldDataProvider) {
+      if (oldDataProvider !== undefined) {
+        this.clearCache();
+      }
+
+      this._ensureFirstPageLoaded();
+
+      this._debouncerCheckSize = Debouncer.debounce(
+        this._debouncerCheckSize,
+        timeOut.after(2000),
+        this._checkSize.bind(this)
+      );
+    }
+
+    /** @protected */
+    _ensureFirstPageLoaded() {
+      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);
+      }
+    }
+
+    /**
+     * @param {!GridItem} item1
+     * @param {!GridItem} item2
+     * @return {boolean}
+     * @protected
+     */
+    _itemsEqual(item1, item2) {
+      return this.getItemId(item1) === this.getItemId(item2);
+    }
+
+    /**
+     * @param {!GridItem} item
+     * @param {!Array<!GridItem>} array
+     * @return {number}
+     * @protected
+     */
+    _getItemIndexInArray(item, array) {
+      let result = -1;
+      array.forEach((i, idx) => {
+        if (this._itemsEqual(i, item)) {
+          result = idx;
+        }
+      });
+      return result;
+    }
+
+    scrollToIndex(index) {
+      super.scrollToIndex(index);
+      if (!isNaN(index) && (this._cache.isLoading() || !this.clientHeight)) {
+        this.__pendingScrollToIndex = index;
+      }
+    }
+
+    __scrollToPendingIndex() {
+      if (this.__pendingScrollToIndex && this.$.items.children.length) {
+        const index = this.__pendingScrollToIndex;
+        delete this.__pendingScrollToIndex;
+        this.scrollToIndex(index);
+      }
+    }
+
+    /**
+     * Fired when the `expandedItems` property changes.
+     *
+     * @event expanded-items-changed
+     */
+
+    /**
+     * Fired when the `loading` property changes.
+     *
+     * @event loading-changed
+     */
+  };

package/src/vaadin-grid-drag-and-drop-mixin.d.ts

@@ -0,0 +1,69 @@
+import { GridDragAndDropFilter, GridDropMode } from './interfaces';
+
+declare function DragAndDropMixin<TItem, T extends new (...args: any[]) => {}>(
+  base: T
+): T & DragAndDropMixinConstructor<TItem>;
+
+interface DragAndDropMixinConstructor<TItem> {
+  new (...args: any[]): DragAndDropMixin<TItem>;
+}
+
+interface DragAndDropMixin<TItem> {
+  /**
+   * Defines the locations within the Grid row where an element can be dropped.
+   *
+   * Possible values are:
+   * - `between`: The drop event can happen between Grid rows.
+   * - `on-top`: The drop event can happen on top of Grid rows.
+   * - `on-top-or-between`: The drop event can happen either on top of or between Grid rows.
+   * - `on-grid`: The drop event will not happen on any specific row, it will show the drop target outline around the whole grid.
+   * @attr {between|on-top|on-top-or-between|on-grid} drop-mode
+   */
+  dropMode: GridDropMode | null | undefined;
+
+  /**
+   * Marks the grid's rows to be available for dragging.
+   * @attr {boolean} rows-draggable
+   */
+  rowsDraggable: boolean | null | undefined;
+
+  /**
+   * A function that filters dragging of specific grid rows. The return value should be false
+   * if dragging of the row should be disabled.
+   *
+   * Receives one argument:
+   * - `model` The object with the properties related with
+   *   the rendered item, contains:
+   *   - `model.index` The index of the item.
+   *   - `model.item` The item.
+   *   - `model.expanded` Sublevel toggle state.
+   *   - `model.level` Level of the tree represented with a horizontal offset of the toggle button.
+   *   - `model.selected` Selected state.
+   */
+  dragFilter: GridDragAndDropFilter<TItem> | null | undefined;
+
+  /**
+   * A function that filters dropping on specific grid rows. The return value should be false
+   * if dropping on the row should be disabled.
+   *
+   * Receives one argument:
+   * - `model` The object with the properties related with
+   *   the rendered item, contains:
+   *   - `model.index` The index of the item.
+   *   - `model.item` The item.
+   *   - `model.expanded` Sublevel toggle state.
+   *   - `model.level` Level of the tree represented with a horizontal offset of the toggle button.
+   *   - `model.selected` Selected state.
+   */
+  dropFilter: GridDragAndDropFilter<TItem> | null | undefined;
+
+  /**
+   * Runs the `dragFilter` and `dropFilter` hooks for the visible cells.
+   * If the filter depends on varying conditions, you may need to
+   * call this function manually in order to update the draggability when
+   * the conditions change.
+   */
+  filterDragAndDrop(): void;
+}
+
+export { DragAndDropMixin, DragAndDropMixinConstructor };