@vaadin/component-base 24.2.0-dev.e9803eea7 → 24.2.0-rc1

package/index.d.ts

@@ -4,3 +4,4 @@ export { DirMixin } from './src/dir-mixin.js';
 export { ElementMixin } from './src/element-mixin.js';
 export { ResizeMixin } from './src/resize-mixin.js';
 export { SlotController } from './src/slot-controller.js';
+export { SlotStylesMixin } from './src/slot-styles-mixin.js';

package/index.js

@@ -4,3 +4,4 @@ export { DirMixin } from './src/dir-mixin.js';
 export { ElementMixin } from './src/element-mixin.js';
 export { ResizeMixin } from './src/resize-mixin.js';
 export { SlotController } from './src/slot-controller.js';
+export { SlotStylesMixin } from './src/slot-styles-mixin.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/component-base",
-  "version": "24.2.0-dev.e9803eea7",
+  "version": "24.2.0-rc1",
   "publishConfig": {
     "access": "public"
   },
@@ -39,8 +39,8 @@
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/testing-helpers": "^0.4.3",
+    "@vaadin/testing-helpers": "^0.5.0",
     "sinon": "^13.0.2"
   },
-  "gitHead": "a065b79b9d5a189e457fab312cc8aff0d7f2f910"
+  "gitHead": "012bef350bbf29865748f4c78338dd17c6f61a74"
 }

package/src/define.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+export interface CustomElementType extends CustomElementConstructor {
+  is: string;
+}
+
+export declare function defineCustomElement(CustomElement: CustomElementConstructor): void;

package/src/define.js

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+export function defineCustomElement(CustomElement) {
+  const defined = customElements.get(CustomElement.is);
+  if (!defined) {
+    customElements.define(CustomElement.is, CustomElement);
+  } else {
+    const definedVersion = defined.version;
+    if (definedVersion && CustomElement.version && definedVersion === CustomElement.version) {
+      // Just loading the same thing again
+      console.warn(`The component ${CustomElement.is} has been loaded twice`);
+    } else {
+      console.error(
+        `Tried to define ${CustomElement.is} version ${CustomElement.version} when version ${defined.version} is already in use. Something will probably break.`,
+      );
+    }
+  }
+}

package/src/dom-utils.d.ts

@@ -13,6 +13,13 @@
  */
 export function getAncestorRootNodes(node: Node): Node[];
 
+/**
+ * Returns the list of flattened elements for the given `node`.
+ * This list consists of a node's children and, for any children that are
+ * `<slot>` elements, the expanded flattened list of `assignedElements`.
+ */
+export function getFlattenedElements(node: Node): Element[];
+
 /**
  * Traverses the given node and its parents, including those that are across
  * the shadow root boundaries, until it finds a node that matches the selector.

package/src/dom-utils.js

@@ -40,6 +40,27 @@ export function getAncestorRootNodes(node) {
   return result;
 }
 
+/**
+ * Returns the list of flattened elements for the given `node`.
+ * This list consists of a node's children and, for any children that are
+ * `<slot>` elements, the expanded flattened list of `assignedElements`.
+ *
+ * @param {Node} node
+ * @return {Element[]}
+ */
+export function getFlattenedElements(node) {
+  const result = [];
+  let elements;
+  if (node.localName === 'slot') {
+    elements = node.assignedElements();
+  } else {
+    result.push(node);
+    elements = [...node.children];
+  }
+  elements.forEach((elem) => result.push(...getFlattenedElements(elem)));
+  return result;
+}
+
 /**
  * Traverses the given node and its parents, including those that are across
  * the shadow root boundaries, until it finds a node that matches the selector.

package/src/element-mixin.d.ts

@@ -16,6 +16,7 @@ export declare function ElementMixin<T extends Constructor<HTMLElement>>(
 ): Constructor<DirMixinClass> & Constructor<ElementMixinClass> & T;
 
 export declare class ElementMixinClass {
+  static is: string;
   static version: string;
 
   protected static finalize(): void;

package/src/element-mixin.js

@@ -45,7 +45,7 @@ const registered = new Set();
 export const ElementMixin = (superClass) =>
   class VaadinElementMixin extends DirMixin(superClass) {
     static get version() {
-      return '24.2.0-alpha5';
+      return '24.2.0-rc1';
     }
 
     /** @protected */

package/src/overflow-controller.js

@@ -3,7 +3,6 @@
  * Copyright (c) 2021 - 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { FlattenedNodesObserver } from '@polymer/polymer/lib/utils/flattened-nodes-observer.js';
 import { animationFrame } from './async.js';
 import { Debouncer } from './debounce.js';
 
@@ -47,30 +46,41 @@ export class OverflowController {
    * @protected
    */
   observe() {
-    this.__resizeObserver = new ResizeObserver(() => {
+    const { host } = this;
+
+    this.__resizeObserver = new ResizeObserver((entries) => {
       this.__debounceOverflow = Debouncer.debounce(this.__debounceOverflow, animationFrame, () => {
         this.__updateOverflow();
       });
     });
 
-    this.__resizeObserver.observe(this.host);
+    this.__resizeObserver.observe(host);
 
-    this.__childObserver = new FlattenedNodesObserver(this.host, (info) => {
-      info.addedNodes.forEach((node) => {
-        if (node.nodeType === Node.ELEMENT_NODE) {
-          this.__resizeObserver.observe(node);
-        }
-      });
+    // Observe initial children
+    [...host.children].forEach((child) => {
+      this.__resizeObserver.observe(child);
+    });
 
-      info.removedNodes.forEach((node) => {
-        if (node.nodeType === Node.ELEMENT_NODE) {
-          this.__resizeObserver.unobserve(node);
-        }
+    this.__childObserver = new MutationObserver((mutations) => {
+      mutations.forEach(({ addedNodes, removedNodes }) => {
+        addedNodes.forEach((node) => {
+          if (node.nodeType === Node.ELEMENT_NODE) {
+            this.__resizeObserver.observe(node);
+          }
+        });
+
+        removedNodes.forEach((node) => {
+          if (node.nodeType === Node.ELEMENT_NODE) {
+            this.__resizeObserver.unobserve(node);
+          }
+        });
       });
 
       this.__updateOverflow();
     });
 
+    this.__childObserver.observe(host, { childList: true });
+
     // Update overflow attribute on scroll
     this.scrollTarget.addEventListener('scroll', this.__boundOnScroll);
 

package/src/path-utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright (c) 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * Convenience method for reading a value from a path.
+ */
+export function get(path: string, object: object): unknown;
+
+/**
+ * Convenience method for setting a value to a path.
+ */
+export function set(path: string, value: unknown, object: object): void;

package/src/path-utils.js

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright (c) 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * Convenience method for reading a value from a path.
+ *
+ * @param {string} path
+ * @param {object} object
+ */
+export function get(path, object) {
+  return path.split('.').reduce((obj, property) => (obj ? obj[property] : undefined), object);
+}
+
+/**
+ * Convenience method for setting a value to a path.
+ *
+ * @param {string} path
+ * @param {unknown} value
+ * @param {object} object
+ */
+export function set(path, value, object) {
+  const pathParts = path.split('.');
+  const lastPart = pathParts.pop();
+  const target = pathParts.reduce((target, part) => target[part], object);
+  target[lastPart] = value;
+}

package/src/polylit-mixin.js

@@ -4,6 +4,7 @@
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { dedupeMixin } from '@open-wc/dedupe-mixin';
+import { get, set } from './path-utils.js';
 
 const caseMap = {};
 
@@ -92,15 +93,22 @@ const PolylitMixinImplementation = (superclass) => {
 
       let result = defaultDescriptor;
 
-      if ('value' in options) {
-        // Set the default value
-        this.addCheckedInitializer((instance) => {
-          if (typeof options.value === 'function') {
-            instance[name] = options.value.call(instance);
-          } else {
-            instance[name] = options.value;
-          }
-        });
+      if (options.sync) {
+        result = {
+          get: defaultDescriptor.get,
+          set(value) {
+            const oldValue = this[name];
+            this[key] = value;
+            this.requestUpdate(name, oldValue, options);
+
+            // Enforce synchronous update
+            if (this.hasUpdated) {
+              this.performUpdate();
+            }
+          },
+          configurable: true,
+          enumerable: true,
+        };
       }
 
       if (options.readOnly) {
@@ -110,6 +118,10 @@ const PolylitMixinImplementation = (superclass) => {
           // This is run during construction of the element
           instance[`_set${upper(name)}`] = function (value) {
             setter.call(instance, value);
+
+            if (options.sync) {
+              this.performUpdate();
+            }
           };
         });
 
@@ -123,6 +135,19 @@ const PolylitMixinImplementation = (superclass) => {
         };
       }
 
+      if ('value' in options) {
+        // Set the default value
+        this.addCheckedInitializer((instance) => {
+          const value = typeof options.value === 'function' ? options.value.call(instance) : options.value;
+
+          if (options.readOnly) {
+            instance[`_set${upper(name)}`](value);
+          } else {
+            instance[name] = value;
+          }
+        });
+      }
+
       if (options.observer) {
         const method = options.observer;
 
@@ -175,7 +200,7 @@ const PolylitMixinImplementation = (superclass) => {
         this.$ = {};
       }
 
-      this.shadowRoot.querySelectorAll('[id]').forEach((node) => {
+      this.renderRoot.querySelectorAll('[id]').forEach((node) => {
         this.$[node.id] = node;
       });
     }
@@ -202,8 +227,8 @@ const PolylitMixinImplementation = (superclass) => {
       }
 
       if (!this.__isReadyInvoked) {
-        this.ready();
         this.__isReadyInvoked = true;
+        this.ready();
       }
     }
 
@@ -254,15 +279,12 @@ const PolylitMixinImplementation = (superclass) => {
 
     /** @protected */
     _get(path, object) {
-      return path.split('.').reduce((obj, property) => (obj ? obj[property] : undefined), object);
+      return get(path, object);
     }
 
     /** @protected */
     _set(path, value, object) {
-      const pathParts = path.split('.');
-      const lastPart = pathParts.pop();
-      const target = pathParts.reduce((target, part) => target[part], object);
-      target[lastPart] = value;
+      set(path, value, object);
     }
   }
 

package/src/slot-controller.js

@@ -3,8 +3,8 @@
  * Copyright (c) 2021 - 2023 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { FlattenedNodesObserver } from '@polymer/polymer/lib/utils/flattened-nodes-observer.js';
 import { isEmptyTextNode } from './dom-utils.js';
+import { SlotObserver } from './slot-observer.js';
 import { generateUniqueId } from './unique-id-utils.js';
 
 /**
@@ -199,17 +199,17 @@ export class SlotController extends EventTarget {
     const selector = slotName === '' ? 'slot:not([name])' : `slot[name=${slotName}]`;
     const slot = this.host.shadowRoot.querySelector(selector);
 
-    this.__slotObserver = new FlattenedNodesObserver(slot, (info) => {
+    this.__slotObserver = new SlotObserver(slot, ({ addedNodes, removedNodes }) => {
       const current = this.multiple ? this.nodes : [this.node];
 
       // Calling `slot.assignedNodes()` includes whitespace text nodes in case of default slot:
       // unlike comment nodes, they are not filtered out. So we need to manually ignore them.
-      const newNodes = info.addedNodes.filter((node) => !isEmptyTextNode(node) && !current.includes(node));
+      const newNodes = addedNodes.filter((node) => !isEmptyTextNode(node) && !current.includes(node));
 
-      if (info.removedNodes.length) {
-        this.nodes = current.filter((node) => !info.removedNodes.includes(node));
+      if (removedNodes.length) {
+        this.nodes = current.filter((node) => !removedNodes.includes(node));
 
-        info.removedNodes.forEach((node) => {
+        removedNodes.forEach((node) => {
           this.teardownNode(node);
         });
       }

package/src/slot-observer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright (c) 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * A helper for observing slot changes.
+ */
+export class SlotObserver {
+  constructor(
+    slot: HTMLSlotElement,
+    callback: (info: { addedNodes: Node[]; movedNodes: Node[]; removedNodes: Node[] }) => void,
+  );
+
+  /**
+   * Activates an observer. This method is automatically called when
+   * a `SlotObserver` is created. It should only be called to  re-activate
+   * an observer that has been deactivated via the `disconnect` method.
+   */
+  connect(): void;
+
+  /**
+   * Deactivates the observer. After calling this method the observer callback
+   * will not be called when changes to slotted nodes occur. The `connect` method
+   * may be subsequently called to reactivate the observer.
+   */
+  disconnect(): void;
+
+  /**
+   * Run the observer callback synchronously.
+   */
+  flush(): void;
+}

package/src/slot-observer.js

@@ -0,0 +1,105 @@
+/**
+ * @license
+ * Copyright (c) 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * A helper for observing slot changes.
+ */
+export class SlotObserver {
+  constructor(slot, callback) {
+    /** @type HTMLSlotElement */
+    this.slot = slot;
+
+    /** @type Function */
+    this.callback = callback;
+
+    /** @type {Node[]} */
+    this._storedNodes = [];
+
+    this._connected = false;
+    this._scheduled = false;
+
+    this._boundSchedule = () => {
+      this._schedule();
+    };
+
+    this.connect();
+    this._schedule();
+  }
+
+  /**
+   * Activates an observer. This method is automatically called when
+   * a `SlotObserver` is created. It should only be called to  re-activate
+   * an observer that has been deactivated via the `disconnect` method.
+   */
+  connect() {
+    this.slot.addEventListener('slotchange', this._boundSchedule);
+    this._connected = true;
+  }
+
+  /**
+   * Deactivates the observer. After calling this method the observer callback
+   * will not be called when changes to slotted nodes occur. The `connect` method
+   * may be subsequently called to reactivate the observer.
+   */
+  disconnect() {
+    this.slot.removeEventListener('slotchange', this._boundSchedule);
+    this._connected = false;
+  }
+
+  /** @private */
+  _schedule() {
+    if (!this._scheduled) {
+      this._scheduled = true;
+
+      queueMicrotask(() => {
+        this.flush();
+      });
+    }
+  }
+
+  /**
+   * Run the observer callback synchronously.
+   */
+  flush() {
+    if (!this._connected) {
+      return;
+    }
+
+    this._scheduled = false;
+
+    this._processNodes();
+  }
+
+  /** @private */
+  _processNodes() {
+    const currentNodes = this.slot.assignedNodes({ flatten: true });
+
+    let addedNodes = [];
+    const removedNodes = [];
+    const movedNodes = [];
+
+    if (currentNodes.length) {
+      addedNodes = currentNodes.filter((node) => !this._storedNodes.includes(node));
+    }
+
+    if (this._storedNodes.length) {
+      this._storedNodes.forEach((node, index) => {
+        const idx = currentNodes.indexOf(node);
+        if (idx === -1) {
+          removedNodes.push(node);
+        } else if (idx !== index) {
+          movedNodes.push(node);
+        }
+      });
+    }
+
+    if (addedNodes.length || removedNodes.length || movedNodes.length) {
+      this.callback({ addedNodes, movedNodes, removedNodes });
+    }
+
+    this._storedNodes = currentNodes;
+  }
+}

package/src/slot-styles-mixin.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 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';
+
+/**
+ * Mixin to insert styles into the outer scope to handle slotted components.
+ * This is useful e.g. to hide native `<input type="number">` controls.
+ */
+export declare function SlotStylesMixin<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<SlotStylesMixinClass> & T;
+
+export declare class SlotStylesMixinClass {
+  /**
+   * List of styles to insert into root.
+   */
+  protected readonly slotStyles: string[];
+}

package/src/slot-styles-mixin.js

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { dedupingMixin } from '@polymer/polymer/lib/utils/mixin.js';
+
+const stylesMap = new WeakMap();
+
+/**
+ * Get all the styles inserted into root.
+ * @param {DocumentOrShadowRoot} root
+ * @return {Set<string>}
+ */
+function getRootStyles(root) {
+  if (!stylesMap.has(root)) {
+    stylesMap.set(root, new Set());
+  }
+
+  return stylesMap.get(root);
+}
+
+/**
+ * Insert styles into the root.
+ * @param {string} styles
+ * @param {DocumentOrShadowRoot} root
+ */
+function insertStyles(styles, root) {
+  const style = document.createElement('style');
+  style.textContent = styles;
+
+  if (root === document) {
+    document.head.appendChild(style);
+  } else {
+    root.insertBefore(style, root.firstChild);
+  }
+}
+
+/**
+ * Mixin to insert styles into the outer scope to handle slotted components.
+ * This is useful e.g. to hide native `<input type="number">` controls.
+ *
+ * @polymerMixin
+ */
+export const SlotStylesMixin = dedupingMixin(
+  (superclass) =>
+    class SlotStylesMixinClass extends superclass {
+      /**
+       * List of styles to insert into root.
+       * @protected
+       */
+      get slotStyles() {
+        return {};
+      }
+
+      /** @protected */
+      connectedCallback() {
+        super.connectedCallback();
+
+        this.__applySlotStyles();
+      }
+
+      /** @private */
+      __applySlotStyles() {
+        const root = this.getRootNode();
+        const rootStyles = getRootStyles(root);
+
+        this.slotStyles.forEach((styles) => {
+          if (!rootStyles.has(styles)) {
+            insertStyles(styles, root);
+            rootStyles.add(styles);
+          }
+        });
+      }
+    },
+);

package/src/tooltip-controller.d.ts

@@ -23,6 +23,13 @@ type TooltipPosition =
  * A controller that manages the slotted tooltip element.
  */
 export class TooltipController extends SlotController {
+  /**
+   * An HTML element for linking with the tooltip overlay
+   * via `aria-describedby` attribute used by screen readers.
+   * When not set, defaults to `target`.
+   */
+  ariaTarget: HTMLElement | HTMLElement[];
+
   /**
    * Object with properties passed to `generator`
    * function to be used for generating tooltip text.
@@ -51,6 +58,12 @@ export class TooltipController extends SlotController {
    */
   target: HTMLElement;
 
+  /**
+   * Set an HTML element for linking with the tooltip overlay
+   * via `aria-describedby` attribute used by screen readers.
+   */
+  setAriaTarget(ariaTarget: HTMLElement | HTMLElement[]): void;
+
   /**
    * Set a context object to be used by generator.
    */

package/src/tooltip-controller.js

@@ -26,6 +26,10 @@ export class TooltipController extends SlotController {
   initCustomNode(tooltipNode) {
     tooltipNode.target = this.target;
 
+    if (this.ariaTarget !== undefined) {
+      tooltipNode.ariaTarget = this.ariaTarget;
+    }
+
     if (this.context !== undefined) {
       tooltipNode.context = this.context;
     }
@@ -45,6 +49,33 @@ export class TooltipController extends SlotController {
     if (this.shouldShow !== undefined) {
       tooltipNode.shouldShow = this.shouldShow;
     }
+
+    this.__notifyChange();
+  }
+
+  /**
+   * Override to notify the host when the tooltip is removed.
+   *
+   * @param {Node} tooltipNode
+   * @protected
+   * @override
+   */
+  teardownNode() {
+    this.__notifyChange();
+  }
+
+  /**
+   * Set an HTML element for linking with the tooltip overlay
+   * via `aria-describedby` attribute used by screen readers.
+   * @param {HTMLElement} ariaTarget
+   */
+  setAriaTarget(ariaTarget) {
+    this.ariaTarget = ariaTarget;
+
+    const tooltipNode = this.node;
+    if (tooltipNode) {
+      tooltipNode.ariaTarget = ariaTarget;
+    }
   }
 
   /**
@@ -127,4 +158,9 @@ export class TooltipController extends SlotController {
       tooltipNode.target = target;
     }
   }
+
+  /** @private */
+  __notifyChange() {
+    this.dispatchEvent(new CustomEvent('tooltip-changed', { detail: { node: this.node } }));
+  }
 }

package/src/data-provider-controller/cache.js

@@ -1,216 +0,0 @@
-export class Cache {
-  /**
-   * @type {import('../data-provider-controller.js').DataProviderController}
-   */
-  controller;
-
-  /**
-   * The number of items.
-   *
-   * @type {number}
-   */
-  size = 0;
-
-  /**
-   * The number of items to display per page.
-   *
-   * @type {number}
-   */
-  pageSize;
-
-  /**
-   * The total number of items, including items from expanded sub-caches.
-   *
-   * @type {number}
-   */
-  effectiveSize = 0;
-
-  /**
-   * An array of cached items.
-   *
-   * @type {object[]}
-   */
-  items = [];
-
-  /**
-   * A map where the key is a requested page and the value is a callback
-   * that will be called with data once the request is complete.
-   *
-   * @type {Map<number, Function>}
-   */
-  pendingRequests = new Map();
-
-  /**
-   * A map where the key is the index of an item in the `items` array
-   * and the value is a sub-cache associated with that item.
-   *
-   * Note, it's intentionally defined as an object instead of a Map
-   * to ensure that Object.entries() returns an array with keys sorted
-   * in alphabetical order, rather than the order they were added.
-   *
-   * @type {Record<number, Cache>}
-   */
-  #subCacheByIndex = {};
-
-  /**
-   * @param {Cache['controller']} controller
-   * @param {number} pageSize
-   * @param {number | undefined} size
-   * @param {Cache | undefined} parentCache
-   * @param {number | undefined} parentCacheIndex
-   */
-  constructor(controller, pageSize, size, parentCache, parentCacheIndex) {
-    this.controller = controller;
-    this.pageSize = pageSize;
-    this.size = size || 0;
-    this.effectiveSize = size || 0;
-    this.parentCache = parentCache;
-    this.parentCacheIndex = parentCacheIndex;
-  }
-
-  /**
-   * An item in the parent cache that the current cache is associated with.
-   *
-   * @return {object | undefined}
-   */
-  get parentItem() {
-    return this.parentCache && this.parentCache.items[this.parentCacheIndex];
-  }
-
-  /**
-   * Whether the cache or any of its descendant caches have pending requests.
-   *
-   * @return {boolean}
-   */
-  get isLoading() {
-    if (this.pendingRequests.size > 0) {
-      return true;
-    }
-
-    return Object.values(this.#subCacheByIndex).some((subCache) => subCache.isLoading);
-  }
-
-  /**
-   * An array of sub-caches sorted in the same order as their associated items
-   * appear in the `items` array.
-   *
-   * @return {Array<[number, Cache]>}
-   */
-  get subCaches() {
-    return Object.entries(this.#subCacheByIndex).map(([index, subCache]) => {
-      return [parseInt(index), subCache];
-    });
-  }
-
-  /**
-   * Recalculates the effective size for the cache and its descendant caches recursively.
-   */
-  recalculateEffectiveSize() {
-    this.effectiveSize =
-      !this.parentItem || this.controller.isExpanded(this.parentItem)
-        ? this.size +
-          Object.values(this.#subCacheByIndex).reduce((total, subCache) => {
-            subCache.recalculateEffectiveSize();
-            return total + subCache.effectiveSize;
-          }, 0)
-        : 0;
-  }
-
-  /**
-   * Adds an array of items corresponding to the given page
-   * to the `items` array.
-   *
-   * @param {number} page
-   * @param {object[]} items
-   */
-  setPage(page, items) {
-    const startIndex = page * this.pageSize;
-    items.forEach((item, i) => {
-      this.items[startIndex + i] = item;
-    });
-  }
-
-  /**
-   * Retrieves the sub-cache associated with the item at the given index
-   * in the `items` array.
-   *
-   * @param {number} index
-   * @return {Cache | undefined}
-   */
-  getSubCache(index) {
-    return this.#subCacheByIndex[index];
-  }
-
-  /**
-   * Removes the sub-cache associated with the item at the given index
-   * in the `items` array.
-   *
-   * @param {number} index
-   */
-  removeSubCache(index) {
-    const subCache = this.getSubCache(index);
-    delete this.#subCacheByIndex[index];
-
-    this.controller.dispatchEvent(
-      new CustomEvent('sub-cache-removed', {
-        detail: {
-          cache: this,
-          subCache,
-        },
-      }),
-    );
-  }
-
-  /**
-   * Removes all sub-caches.
-   */
-  removeSubCaches() {
-    this.#subCacheByIndex = {};
-
-    this.controller.dispatchEvent(
-      new CustomEvent('sub-caches-removed', {
-        detail: {
-          cache: this,
-        },
-      }),
-    );
-  }
-
-  /**
-   * Creates and associates a sub-cache for the item at the given index
-   * in the `items` array.
-   *
-   * @param {number} index
-   * @return {Cache}
-   */
-  createSubCache(index) {
-    const subCache = new Cache(this.controller, this.pageSize, 0, this, index);
-    this.#subCacheByIndex[index] = subCache;
-
-    this.controller.dispatchEvent(
-      new CustomEvent('sub-cache-created', {
-        detail: {
-          cache: this,
-          subCache,
-        },
-      }),
-    );
-
-    return subCache;
-  }
-
-  /**
-   * Retrieves the flattened index corresponding to the given index
-   * of an item in the `items` array.
-   *
-   * @param {number} index
-   * @return {number}
-   */
-  getFlatIndex(index) {
-    const clampedIndex = Math.max(0, Math.min(this.size - 1, index));
-
-    return this.subCaches.reduce((prev, [index, subCache]) => {
-      return clampedIndex > index ? prev + subCache.effectiveSize : prev;
-    }, clampedIndex);
-  }
-}

package/src/data-provider-controller/helpers.js

@@ -1,56 +0,0 @@
-/**
- * Retreives information for the given flattened index, including:
- * - the corresponding cache
- * - the associated item (if loaded)
- * - the corresponding index in the cache's items array.
- * - the page containing the index.
- * - the cache level
- *
- * @param {import('./cache.js').Cache} cache
- * @param {number} flatIndex
- * @return {{ cache: Cache, item: object | undefined, index: number, page: number, level: number }}
- */
-export function getFlatIndexInfo(cache, flatIndex, level = 0) {
-  let levelIndex = flatIndex;
-
-  for (const [index, subCache] of cache.subCaches) {
-    if (levelIndex <= index) {
-      break;
-    } else if (levelIndex <= index + subCache.effectiveSize) {
-      return getFlatIndexInfo(subCache, levelIndex - index - 1, level + 1);
-    }
-    levelIndex -= subCache.effectiveSize;
-  }
-
-  return {
-    cache,
-    item: cache.items[levelIndex],
-    index: levelIndex,
-    page: Math.floor(levelIndex / cache.pageSize),
-    level,
-  };
-}
-
-/**
- * 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 {!ItemCache} cache
- * @param {!Array<number>} indexes
- * @param {number} flatIndex
- * @return {number}
- */
-export function getFlatIndexByPath(cache, [levelIndex, ...subIndexes], 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.getSubCache(levelIndex);
-  if (subCache && subCache.effectiveSize > 0 && subIndexes.length) {
-    return getFlatIndexByPath(subCache, subIndexes, flatIndex + flatIndexOnLevel + 1);
-  }
-  return flatIndex + flatIndexOnLevel;
-}

package/src/data-provider-controller.js

@@ -1,116 +0,0 @@
-import { Cache } from './data-provider-controller/cache.js';
-import { getFlatIndexByPath, getFlatIndexInfo } from './data-provider-controller/helpers.js';
-
-export class DataProviderController extends EventTarget {
-  constructor(host, { size, pageSize, isExpanded, dataProvider, dataProviderParams }) {
-    super();
-    this.host = host;
-    this.size = size;
-    this.pageSize = pageSize;
-    this.isExpanded = isExpanded;
-    this.dataProvider = dataProvider;
-    this.dataProviderParams = dataProviderParams;
-    this.rootCache = this.#createRootCache();
-  }
-
-  get effectiveSize() {
-    return this.rootCache.effectiveSize;
-  }
-
-  isLoading() {
-    return this.rootCache.isLoading;
-  }
-
-  setSize(size) {
-    const delta = size - this.rootCache.size;
-    this.size = size;
-    this.rootCache.size += delta;
-    this.rootCache.effectiveSize += delta;
-  }
-
-  setPageSize(pageSize) {
-    this.pageSize = pageSize;
-  }
-
-  setDataProvider(dataProvider) {
-    this.dataProvider = dataProvider;
-  }
-
-  recalculateEffectiveSize() {
-    this.rootCache.recalculateEffectiveSize();
-  }
-
-  clearCache() {
-    this.rootCache = this.#createRootCache();
-  }
-
-  getFlatIndexInfo(flatIndex) {
-    return getFlatIndexInfo(this.rootCache, flatIndex);
-  }
-
-  getFlatIndexByPath(path) {
-    return getFlatIndexByPath(this.rootCache, path);
-  }
-
-  ensureFlatIndexLoaded(flatIndex) {
-    const { cache, page, item } = this.getFlatIndexInfo(flatIndex);
-
-    if (!item) {
-      this.#loadCachePage(cache, page);
-    }
-  }
-
-  ensureFlatIndexHierarchy(flatIndex) {
-    const { cache, item, index } = this.getFlatIndexInfo(flatIndex);
-
-    if (item && this.isExpanded(item) && !cache.getSubCache(index)) {
-      const subCache = cache.createSubCache(index);
-      this.#loadCachePage(subCache, 0);
-    }
-  }
-
-  loadFirstPage() {
-    this.#loadCachePage(this.rootCache, 0);
-  }
-
-  #createRootCache() {
-    return new Cache(this, this.pageSize, this.size);
-  }
-
-  #loadCachePage(cache, page) {
-    if (!this.dataProvider || cache.pendingRequests.has(page)) {
-      return;
-    }
-
-    const params = {
-      page,
-      pageSize: this.pageSize,
-      parentItem: cache.parentItem,
-      ...this.dataProviderParams(),
-    };
-
-    const callback = (items, size) => {
-      if (size !== undefined) {
-        cache.size = size;
-      } else if (params.parentItem) {
-        cache.size = items.length;
-      }
-
-      cache.setPage(page, items);
-
-      this.recalculateEffectiveSize();
-
-      this.dispatchEvent(new CustomEvent('page-received'));
-
-      cache.pendingRequests.delete(page);
-
-      this.dispatchEvent(new CustomEvent('page-loaded'));
-    };
-
-    cache.pendingRequests.set(page, callback);
-
-    this.dispatchEvent(new CustomEvent('page-requested'));
-
-    this.dataProvider(params, callback);
-  }
-}