element-vir 23.1.2 → 23.2.0

package/dist/declarative-element/directives/on-intersect.directive.d.ts

@@ -0,0 +1,64 @@
+import type { MaybePromise } from '@augment-vir/common';
+import { PartInfo } from '../../lit-exports/all-lit-exports.js';
+/**
+ * Callback called by the {@link onIntersect} directive.
+ *
+ * @category Internal
+ */
+export type OnIntersectCallback = (params: {
+    entry: IntersectionObserverEntry;
+    allEntries: IntersectionObserverEntry[];
+    observer: IntersectionObserver;
+    element: Element;
+}) => MaybePromise<void>;
+/**
+ * Options used for the {@link onIntersect} directive.
+ *
+ * @category Internal
+ */
+export type OnIntersectOptions = IntersectionObserverInit;
+/**
+ * A directive that fires its listener any time the element's configured "intersection" is crossed.
+ * This is commonly use for detecting when an element has scrolled into view. This uses the
+ * [built-in `IntersectionObserver`
+ * API](https://developer.mozilla.org/docs/Web/API/IntersectionObserver/IntersectionObserver), so it
+ * is very efficient.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElementNoInputs, onIntersect} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div
+ *                 ${onIntersect({threshold: 1}, ({element, entry}) => {
+ *                     if (entry.isIntersecting) {
+ *                         console.log('is intersecting!');
+ *                     } else {
+ *                         console.log('is not intersecting');
+ *                     }
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export declare const onIntersect: (options: IntersectionObserverInit, callback: OnIntersectCallback) => import("lit-html/directive.js").DirectiveResult<{
+    new (partInfo: PartInfo): {
+        element: Element | undefined;
+        options: OnIntersectOptions | undefined;
+        intersectionObserver: undefined | IntersectionObserver;
+        callback: OnIntersectCallback | undefined;
+        fireCallback(entries: IntersectionObserverEntry[], observer: IntersectionObserver): void;
+        update(partInfo: PartInfo, [options, callback,]: [OnIntersectOptions, OnIntersectCallback]): undefined;
+        render(options: OnIntersectOptions, callback: OnIntersectCallback): undefined;
+        readonly _$isConnected: boolean;
+    };
+}>;

package/dist/declarative-element/directives/on-intersect.directive.js

@@ -0,0 +1,89 @@
+import { assert, assertWrap, check } from '@augment-vir/assert';
+import { directive, Directive } from '../../lit-exports/all-lit-exports.js';
+import { assertIsElementPartInfo } from './directive-helpers.js';
+const directiveName = 'onIntersect';
+/**
+ * A directive that fires its listener any time the element's configured "intersection" is crossed.
+ * This is commonly use for detecting when an element has scrolled into view. This uses the
+ * [built-in `IntersectionObserver`
+ * API](https://developer.mozilla.org/docs/Web/API/IntersectionObserver/IntersectionObserver), so it
+ * is very efficient.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElementNoInputs, onIntersect} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div
+ *                 ${onIntersect({threshold: 1}, ({element, entry}) => {
+ *                     if (entry.isIntersecting) {
+ *                         console.log('is intersecting!');
+ *                     } else {
+ *                         console.log('is not intersecting');
+ *                     }
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export const onIntersect = directive(class extends Directive {
+    element;
+    options;
+    intersectionObserver;
+    callback;
+    constructor(partInfo) {
+        super(partInfo);
+        assertIsElementPartInfo(partInfo, directiveName);
+    }
+    fireCallback(entries, observer) {
+        assert.isLengthAtLeast(entries, 1);
+        void this.callback?.({
+            element: assertWrap.isDefined(this.element),
+            allEntries: entries,
+            observer,
+            entry: entries[0],
+        });
+    }
+    update(partInfo, [options, callback,]) {
+        assertIsElementPartInfo(partInfo, directiveName);
+        this.callback = callback;
+        let needsObserving = false;
+        const newOptions = options;
+        const oldOptions = this.options;
+        if (!this.intersectionObserver ||
+            !oldOptions ||
+            !check.entriesEqual(newOptions, oldOptions)) {
+            this.options = options;
+            this.intersectionObserver?.disconnect();
+            this.intersectionObserver = new IntersectionObserver((entries, observer) => this.fireCallback(entries, observer), options);
+            needsObserving = true;
+        }
+        const newElement = partInfo.element;
+        const oldElement = this.element;
+        // if the element changes we need to observe the new one
+        if (newElement !== oldElement) {
+            this.element = newElement;
+            if (oldElement) {
+                this.intersectionObserver.unobserve(oldElement);
+            }
+            needsObserving = true;
+        }
+        if (needsObserving) {
+            this.intersectionObserver.observe(newElement);
+        }
+        return this.render(options, callback);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    render(options, callback) {
+        return undefined;
+    }
+});

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from './declarative-element/directives/is-resolved.directive.js';
 export * from './declarative-element/directives/listen.directive.js';
 export * from './declarative-element/directives/on-dom-created.directive.js';
 export * from './declarative-element/directives/on-dom-rendered.directive.js';
+export * from './declarative-element/directives/on-intersect.directive.js';
 export * from './declarative-element/directives/on-resize.directive.js';
 export * from './declarative-element/directives/render-async.directive.js';
 export * from './declarative-element/directives/render-if.directive.js';

package/dist/index.js

@@ -12,6 +12,7 @@ export * from './declarative-element/directives/is-resolved.directive.js';
 export * from './declarative-element/directives/listen.directive.js';
 export * from './declarative-element/directives/on-dom-created.directive.js';
 export * from './declarative-element/directives/on-dom-rendered.directive.js';
+export * from './declarative-element/directives/on-intersect.directive.js';
 export * from './declarative-element/directives/on-resize.directive.js';
 export * from './declarative-element/directives/render-async.directive.js';
 export * from './declarative-element/directives/render-if.directive.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-vir",
-    "version": "23.1.2",
+    "version": "23.2.0",
     "keywords": [
         "custom",
         "web",