@vaadin/virtual-list 23.1.0-beta1 → 23.1.0-beta4

package/lit.d.ts

@@ -0,0 +1 @@
+export * from './src/lit/renderer-directives.js';

package/lit.js

@@ -0,0 +1 @@
+export * from './src/lit/renderer-directives.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/virtual-list",
-  "version": "23.1.0-beta1",
+  "version": "23.1.0-beta4",
   "publishConfig": {
     "access": "public"
   },
@@ -20,6 +20,8 @@
   "module": "vaadin-virtual-list.js",
   "type": "module",
   "files": [
+    "lit.d.ts",
+    "lit.js",
     "src",
     "theme",
     "vaadin-*.d.ts",
@@ -34,17 +36,18 @@
   ],
   "dependencies": {
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/component-base": "23.1.0-beta1",
-    "@vaadin/vaadin-lumo-styles": "23.1.0-beta1",
-    "@vaadin/vaadin-material-styles": "23.1.0-beta1",
-    "@vaadin/vaadin-themable-mixin": "23.1.0-beta1"
+    "@vaadin/component-base": "23.1.0-beta4",
+    "@vaadin/lit-renderer": "23.1.0-beta4",
+    "@vaadin/vaadin-lumo-styles": "23.1.0-beta4",
+    "@vaadin/vaadin-material-styles": "23.1.0-beta4",
+    "@vaadin/vaadin-themable-mixin": "23.1.0-beta4"
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/polymer-legacy-adapter": "23.1.0-beta1",
+    "@vaadin/polymer-legacy-adapter": "23.1.0-beta4",
     "@vaadin/testing-helpers": "^0.3.2",
     "lit": "^2.0.0",
     "sinon": "^13.0.2"
   },
-  "gitHead": "8be43cf83102a6b9ccf309687446e590ce0164e8"
+  "gitHead": "06e283473964ecb3085aacf3eddb5333d052a045"
 }

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

@@ -0,0 +1,66 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2022 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { TemplateResult } from 'lit';
+import { DirectiveResult } from 'lit/directive.js';
+import { LitRendererDirective } from '@vaadin/lit-renderer';
+import { VirtualList, VirtualListItemModel } from '../vaadin-virtual-list.js';
+
+export type VirtualListLitRenderer<TItem> = (
+  item: TItem,
+  model: VirtualListItemModel<TItem>,
+  virtualList: VirtualList<TItem>,
+) => TemplateResult;
+
+export class VirtualListRendererDirective<TItem> extends LitRendererDirective<
+  VirtualList,
+  VirtualListLitRenderer<TItem>
+> {
+  /**
+   * Adds the renderer callback to the virtual list.
+   */
+  addRenderer(): void;
+
+  /**
+   * Runs the renderer callback on the virtual list.
+   */
+  runRenderer(): void;
+
+  /**
+   * Removes the renderer callback from the virtual list.
+   */
+  removeRenderer(): void;
+}
+
+/**
+ * A Lit directive for rendering the content of the `<vaadin-virtual-list>` item elements.
+ *
+ * The directive accepts a renderer callback returning a Lit template and assigns it to the virtual
+ * list via the `renderer` property. The renderer is called once to populate the content when
+ * assigned and whenever a single dependency or an array of dependencies changes.
+ * It is not guaranteed that the renderer will be called immediately (synchronously) in both cases.
+ *
+ * Dependencies can be a single value or an array of values.
+ * Values are checked against previous values with strict equality (`===`),
+ * so the check won't detect nested property changes inside objects or arrays.
+ * When dependencies are provided as an array, each item is checked against the previous value
+ * at the same index with strict equality. Nested arrays are also checked only by strict
+ * equality.
+ *
+ * Example of usage:
+ * ```js
+ * `<vaadin-virtual-list
+ *   ${virtualListRenderer((item, model, virtualList) => html`...`)}
+ * ></vaadin-virtual-list>`
+ * ```
+ *
+ * @param renderer the renderer callback that returns a Lit template.
+ * @param dependencies a single dependency or an array of dependencies
+ *                     which trigger a re-render when changed.
+ */
+export declare function virtualListRenderer<TItem>(
+  renderer: VirtualListLitRenderer<TItem>,
+  dependencies?: unknown,
+): DirectiveResult<typeof VirtualListRendererDirective>;

package/src/lit/renderer-directives.js

@@ -0,0 +1,60 @@
+/**
+ * @license
+ * Copyright (c) 2017 - 2022 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { directive } from 'lit/directive.js';
+import { LitRendererDirective } from '@vaadin/lit-renderer';
+
+export class VirtualListRendererDirective extends LitRendererDirective {
+  /**
+   * Adds the renderer callback to the virtual list.
+   */
+  addRenderer() {
+    this.element.renderer = (root, virtualList, model) => {
+      this.renderRenderer(root, model.item, model, virtualList);
+    };
+  }
+
+  /**
+   * Runs the renderer callback on the virtual list.
+   */
+  runRenderer() {
+    this.element.requestContentUpdate();
+  }
+
+  /**
+   * Removes the renderer callback from the virtual list.
+   */
+  removeRenderer() {
+    this.element.renderer = null;
+  }
+}
+
+/**
+ * A Lit directive for rendering the content of the `<vaadin-virtual-list>` item elements.
+ *
+ * The directive accepts a renderer callback returning a Lit template and assigns it to the virtual
+ * list via the `renderer` property. The renderer is called once to populate the content when
+ * assigned and whenever a single dependency or an array of dependencies changes.
+ * It is not guaranteed that the renderer will be called immediately (synchronously) in both cases.
+ *
+ * Dependencies can be a single value or an array of values.
+ * Values are checked against previous values with strict equality (`===`),
+ * so the check won't detect nested property changes inside objects or arrays.
+ * When dependencies are provided as an array, each item is checked against the previous value
+ * at the same index with strict equality. Nested arrays are also checked only by strict
+ * equality.
+ *
+ * Example of usage:
+ * ```js
+ * `<vaadin-virtual-list
+ *   ${virtualListRenderer((item, model, virtualList) => html`...`)}
+ * ></vaadin-virtual-list>`
+ * ```
+ *
+ * @param renderer the renderer callback that returns a Lit template.
+ * @param dependencies a single dependency or an array of dependencies
+ *                     which trigger a re-render when changed.
+ */
+export const virtualListRenderer = directive(VirtualListRendererDirective);