element-vir 26.12.0 → 26.12.1

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

@@ -0,0 +1,44 @@
+import { type MaybePromise } from '@augment-vir/common';
+import { type PartInfo } from '../../lit-exports/all-lit-exports.js';
+/**
+ * The callback / listener passed to {@link onDomCreated}. The `element` parameter is a reference to
+ * the DOM element that the directive was attached to.
+ *
+ * @category Internal
+ */
+export type OnDomCreatedCallback = (element: Element) => MaybePromise<void>;
+/**
+ * A directive that fires its listener only once, when the element that it's attached to is
+ * constructed. This is particularly useful for getting references to internal elements immediately
+ * after they've rendered.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElement, onDomCreated} from 'element-vir';
+ *
+ * const MyElement = defineElement()({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div
+ *                 ${onDomCreated((element) => {
+ *                     console.log('created!', element);
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export declare const onDomCreated: (callback: OnDomCreatedCallback) => import("lit-html/directive.js").DirectiveResult<{
+    new (partInfo: PartInfo): {
+        element: Element | undefined;
+        update(partInfo: PartInfo, [callback]: [OnDomCreatedCallback]): undefined;
+        render(callback: OnDomCreatedCallback): undefined;
+        get _$isConnected(): boolean;
+    };
+}>;

package/dist/declarative-element/directives/on-dom-created.directive.js

@@ -0,0 +1,51 @@
+import { directive, Directive } from '../../lit-exports/all-lit-exports.js';
+import { assertIsElementPartInfo } from './directive-helpers.js';
+const directiveName = 'onDomCreated';
+/**
+ * A directive that fires its listener only once, when the element that it's attached to is
+ * constructed. This is particularly useful for getting references to internal elements immediately
+ * after they've rendered.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElement, onDomCreated} from 'element-vir';
+ *
+ * const MyElement = defineElement()({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div
+ *                 ${onDomCreated((element) => {
+ *                     console.log('created!', element);
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export const onDomCreated = directive(class extends Directive {
+    element;
+    constructor(partInfo) {
+        super(partInfo);
+        assertIsElementPartInfo(partInfo, directiveName);
+    }
+    update(partInfo, [callback]) {
+        assertIsElementPartInfo(partInfo, directiveName);
+        const newElement = partInfo.element;
+        if (newElement !== this.element) {
+            // use requestAnimationFrame here so it can fire property changes outside of a render loop
+            window.requestAnimationFrame(() => callback(newElement));
+            this.element = newElement;
+        }
+        return this.render(callback);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    render(callback) {
+        return undefined;
+    }
+});

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

@@ -0,0 +1,41 @@
+import { type MaybePromise } from '@augment-vir/common';
+import { type PartInfo } from '../../lit-exports/all-lit-exports.js';
+/**
+ * The callback / listener passed to {@link onDomRendered}. The `element` parameter is a reference to
+ * the DOM element that the directive was attached to.
+ *
+ * @category Internal
+ */
+export type OnDomRenderedCallback = (element: Element) => MaybePromise<void>;
+/**
+ * A directive that fires its listener each time the element that it's attached to is rendered.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElement, onDomRendered} from 'element-vir';
+ *
+ * const MyElement = defineElement()({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div
+ *                 ${onDomRendered((element) => {
+ *                     console.log('rendered!', element);
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export declare const onDomRendered: (callback: OnDomRenderedCallback) => import("lit-html/directive.js").DirectiveResult<{
+    new (partInfo: PartInfo): {
+        update(partInfo: PartInfo, [callback]: [OnDomRenderedCallback]): undefined;
+        render(callback: OnDomRenderedCallback): undefined;
+        get _$isConnected(): boolean;
+    };
+}>;

package/dist/declarative-element/directives/on-dom-rendered.directive.js

@@ -0,0 +1,45 @@
+import { directive, Directive } from '../../lit-exports/all-lit-exports.js';
+import { assertIsElementPartInfo } from './directive-helpers.js';
+const directiveName = 'onDomRendered';
+/**
+ * A directive that fires its listener each time the element that it's attached to is rendered.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElement, onDomRendered} from 'element-vir';
+ *
+ * const MyElement = defineElement()({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div
+ *                 ${onDomRendered((element) => {
+ *                     console.log('rendered!', element);
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export const onDomRendered = directive(class extends Directive {
+    constructor(partInfo) {
+        super(partInfo);
+        assertIsElementPartInfo(partInfo, directiveName);
+    }
+    update(partInfo, [callback]) {
+        assertIsElementPartInfo(partInfo, directiveName);
+        const element = partInfo.element;
+        // use `requestAnimationFrame` here so it can fire property changes outside of a render loop
+        window.requestAnimationFrame(() => callback(element));
+        return this.render(callback);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    render(callback) {
+        return undefined;
+    }
+});

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

@@ -0,0 +1,64 @@
+import { type MaybePromise } from '@augment-vir/common';
+import { type 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, defineElement, onIntersect} from 'element-vir';
+ *
+ * const MyElement = defineElement()({
+ *     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;
+        get _$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, defineElement, onIntersect} from 'element-vir';
+ *
+ * const MyElement = defineElement()({
+ *     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/declarative-element/directives/on-resize.directive.d.ts

@@ -0,0 +1,74 @@
+import { type MaybePromise } from '@augment-vir/common';
+import { type PartInfo } from '../../lit-exports/all-lit-exports.js';
+/**
+ * Callback called by the {@link onResize} directive.
+ *
+ * @category Internal
+ */
+export type OnResizeCallback = (size: Readonly<Pick<ResizeObserverEntry, 
+/** Only these two properties are supported in all major modern browsers */
+'target' | 'contentRect'>>, element: Element) => MaybePromise<void>;
+/**
+ * A directive that fires its listener any time the element that it's attached to is resized. This
+ * uses the [built-in `ResizeObserver`
+ * API](https://developer.mozilla.org/docs/Web/API/ResizeObserver), so it is very efficient.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElement, onResize} from 'element-vir';
+ *
+ * const MyElement = defineElement()({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div
+ *                 ${onResize((size, element) => {
+ *                     console.log('resized!', element, size);
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export declare const onResize: (callback: OnResizeCallback) => import("lit-html/directive.js").DirectiveResult<{
+    new (partInfo: PartInfo): {
+        element: Element | undefined;
+        readonly resizeObserver: ResizeObserver;
+        callback: OnResizeCallback | undefined;
+        update(partInfo: PartInfo, [callback]: [OnResizeCallback]): undefined;
+        render(callback: OnResizeCallback): undefined;
+        get _$isConnected(): boolean;
+    };
+}>;
+/**
+ * A function that attaches a
+ * [`ResizeObserver`](https://developer.mozilla.org/docs/Web/API/ResizeObserver) to any given
+ * element, so it is very efficient.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElement, attachOnResize} from 'element-vir';
+ *
+ * const MyElement = defineElement()({
+ *     tagName: 'my-element',
+ *     render({host}) {
+ *         attachOnResize(host, (size, element) => {
+ *             console.log('resized!', element, size);
+ *         });
+ *
+ *         return '';
+ *     },
+ * });
+ * ```
+ */
+export declare function attachOnResize(element: Element, callback: OnResizeCallback): {
+    resizeObserver: ResizeObserver;
+    element: Element;
+};

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

@@ -0,0 +1,106 @@
+import { directive, Directive } from '../../lit-exports/all-lit-exports.js';
+import { assertIsElementPartInfo } from './directive-helpers.js';
+const directiveName = 'onResize';
+/**
+ * A directive that fires its listener any time the element that it's attached to is resized. This
+ * uses the [built-in `ResizeObserver`
+ * API](https://developer.mozilla.org/docs/Web/API/ResizeObserver), so it is very efficient.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElement, onResize} from 'element-vir';
+ *
+ * const MyElement = defineElement()({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div
+ *                 ${onResize((size, element) => {
+ *                     console.log('resized!', element, size);
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export const onResize = directive(class extends Directive {
+    element;
+    resizeObserver = new ResizeObserver((entries) => {
+        if (this.element && this.callback) {
+            handleOnResizeCallback(this.element, this.callback, entries);
+        }
+    });
+    callback;
+    constructor(partInfo) {
+        super(partInfo);
+        assertIsElementPartInfo(partInfo, directiveName);
+    }
+    update(partInfo, [callback]) {
+        assertIsElementPartInfo(partInfo, directiveName);
+        this.callback = callback;
+        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.resizeObserver.unobserve(oldElement);
+            }
+            this.resizeObserver.observe(newElement);
+        }
+        return this.render(callback);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    render(callback) {
+        return undefined;
+    }
+});
+function handleOnResizeCallback(element, callback, entries) {
+    const resizeEntry = entries[0];
+    if (!resizeEntry) {
+        console.error(entries);
+        throw new Error(`Resize observation triggered but the first entry was empty.`);
+    }
+    void callback({
+        target: resizeEntry.target,
+        contentRect: resizeEntry.contentRect,
+    }, element);
+}
+/**
+ * A function that attaches a
+ * [`ResizeObserver`](https://developer.mozilla.org/docs/Web/API/ResizeObserver) to any given
+ * element, so it is very efficient.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElement, attachOnResize} from 'element-vir';
+ *
+ * const MyElement = defineElement()({
+ *     tagName: 'my-element',
+ *     render({host}) {
+ *         attachOnResize(host, (size, element) => {
+ *             console.log('resized!', element, size);
+ *         });
+ *
+ *         return '';
+ *     },
+ * });
+ * ```
+ */
+export function attachOnResize(element, callback) {
+    const resizeObserver = new ResizeObserver((entries) => {
+        handleOnResizeCallback(element, callback, entries);
+    });
+    resizeObserver.observe(element);
+    return {
+        resizeObserver,
+        element,
+    };
+}

package/dist/declarative-element/directives/render-async.directive.d.ts

@@ -0,0 +1,45 @@
+import { type AsyncProp } from './async-prop.js';
+/**
+ * Given a {@link AsyncProp} instance, call and return the output of the `resolutionRender` parameter
+ * once the {@link AsyncProp} has been resolved, call and return the output of the `errorRender`
+ * parameter if the {@link AsyncProp} errored out, return the `fallback` parameter in all other
+ * cases.
+ *
+ * This is the overload for when `resolutionRender` and `errorRender` are both provided.
+ *
+ * @category Async
+ */
+export declare function renderAsync<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncProp: Pick<AsyncProp<T, any>, 'value'>, fallback: FallbackResult, resolutionRender: (resolved: Awaited<T>) => ResolutionRenderResult, errorRender: (error: Error) => ErrorRenderResult): FallbackResult | ResolutionRenderResult | ErrorRenderResult;
+/**
+ * Given a {@link AsyncProp} instance, call and return the output of the `resolutionRender` parameter
+ * once the {@link AsyncProp} has been resolved, call and return the output of the `errorRender`
+ * parameter if the {@link AsyncProp} errored out, return the `fallback` parameter in all other
+ * cases.
+ *
+ * This is the overload for when `resolutionRender` is provided but `errorRender` is not.
+ *
+ * @category Async
+ */
+export declare function renderAsync<T, FallbackResult, ResolutionRenderResult = never>(asyncProp: Pick<AsyncProp<T, any>, 'value'>, fallback: FallbackResult, resolutionRender: (resolved: Awaited<T>) => ResolutionRenderResult, errorRender?: undefined): FallbackResult | ResolutionRenderResult | string;
+/**
+ * Given a {@link AsyncProp} instance, call and return the output of the `resolutionRender` parameter
+ * once the {@link AsyncProp} has been resolved, call and return the output of the `errorRender`
+ * parameter if the {@link AsyncProp} errored out, return the `fallback` parameter in all other
+ * cases.
+ *
+ * This is the overload for when `resolutionRender` is not provided but `errorRender` is.
+ *
+ * @category Async
+ */
+export declare function renderAsync<T, FallbackResult, ErrorRenderResult = never>(asyncProp: Pick<AsyncProp<T, any>, 'value'>, fallback: FallbackResult, resolutionRender: undefined, errorRender: (error: Error) => ErrorRenderResult): FallbackResult | Awaited<T> | ErrorRenderResult;
+/**
+ * Given a {@link AsyncProp} instance, call and return the output of the `resolutionRender` parameter
+ * once the {@link AsyncProp} has been resolved, call and return the output of the `errorRender`
+ * parameter if the {@link AsyncProp} errored out, return the `fallback` parameter in all other
+ * cases.
+ *
+ * This is the overload for when neither `resolutionRender` or `errorRender` are provided.
+ *
+ * @category Async
+ */
+export declare function renderAsync<T, FallbackResult>(asyncProp: Pick<AsyncProp<T, any>, 'value'>, fallback: FallbackResult, resolutionRender?: undefined, errorRender?: undefined): FallbackResult | Awaited<T> | string;

package/dist/declarative-element/directives/render-async.directive.js

@@ -0,0 +1,33 @@
+import { check } from '@augment-vir/assert';
+import { extractErrorMessage } from '@augment-vir/common';
+/**
+ * Given a {@link AsyncProp} instance, call and return the output of the `resolutionRender` parameter
+ * once the {@link AsyncProp} has been resolved, call and return the output of the `errorRender`
+ * parameter if the {@link AsyncProp} errored out, return the `fallback` parameter in all other
+ * cases.
+ *
+ * This is the full function definition and implementation.
+ *
+ * @category Async
+ */
+export function renderAsync(asyncProp, 
+/** This value will be rendered if the async prop has not settled yet. */
+fallback, resolutionRender, errorRender) {
+    const asyncPropValue = asyncProp.value;
+    if (asyncPropValue instanceof Error) {
+        const errorResult = errorRender
+            ? errorRender(asyncPropValue)
+            : extractErrorMessage(asyncPropValue);
+        return errorResult;
+    }
+    else if (check.isPromiseLike(asyncPropValue)) {
+        const fallbackResult = fallback;
+        return fallbackResult;
+    }
+    else {
+        const resolutionResult = resolutionRender
+            ? resolutionRender(asyncPropValue)
+            : asyncPropValue;
+        return resolutionResult;
+    }
+}

package/dist/declarative-element/directives/render-if.directive.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A directive that, given a condition, chooses between two inputs: `ifTrue` and `ifFalse`. If
+ * `ifFalse` is omitted (which is allowed), the false case defaults to `undefined`, which won't get
+ * rendered at all inside of an HTML template.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElement, renderIf} from 'element-vir';
+ *
+ * const MyElement = defineElement()({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div>
+ *                 ${renderIf(
+ *                     Math.random() > 0.5,
+ *                     html`
+ *                         True!
+ *                     `,
+ *                     html`
+ *                         False!
+ *                     `,
+ *                 )}
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export declare function renderIf<TrueCondition = unknown, FalseCondition = undefined>(condition: boolean, ifTrue: TrueCondition, ifFalse?: FalseCondition): TrueCondition | FalseCondition;

package/{src/declarative-element/directives/render-if.directive.ts → dist/declarative-element/directives/render-if.directive.js}

@@ -1,5 +1,4 @@
-import {when} from '../../lit-exports/all-lit-exports.js';
-
+import { when } from '../../lit-exports/all-lit-exports.js';
 /**
  * A directive that, given a condition, chooses between two inputs: `ifTrue` and `ifFalse`. If
  * `ifFalse` is omitted (which is allowed), the false case defaults to `undefined`, which won't get
@@ -31,14 +30,6 @@ import {when} from '../../lit-exports/all-lit-exports.js';
  * });
  * ```
  */
-export function renderIf<TrueCondition = unknown, FalseCondition = undefined>(
-    condition: boolean,
-    ifTrue: TrueCondition,
-    ifFalse?: FalseCondition,
-): TrueCondition | FalseCondition {
-    return when(
-        condition,
-        () => ifTrue,
-        () => ifFalse,
-    ) as TrueCondition | FalseCondition;
+export function renderIf(condition, ifTrue, ifFalse) {
+    return when(condition, () => ifTrue, () => ifFalse);
 }