element-vir 26.11.2 → 26.12.0

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

@@ -0,0 +1,61 @@
+import {type MaybePromise} from '@augment-vir/common';
+import {directive, Directive, type PartInfo} from '../../lit-exports/all-lit-exports.js';
+import {assertIsElementPartInfo} from './directive-helpers.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>;
+
+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: PartInfo) {
+            super(partInfo);
+
+            assertIsElementPartInfo(partInfo, directiveName);
+        }
+
+        public override update(partInfo: PartInfo, [callback]: [OnDomRenderedCallback]) {
+            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
+        public render(callback: OnDomRenderedCallback) {
+            return undefined;
+        }
+    },
+);

package/src/declarative-element/directives/on-intersect.directive.ts

@@ -0,0 +1,139 @@
+import {assert, assertWrap, check} from '@augment-vir/assert';
+import {type MaybePromise} from '@augment-vir/common';
+import {directive, Directive, type PartInfo} from '../../lit-exports/all-lit-exports.js';
+import {assertIsElementPartInfo} from './directive-helpers.js';
+
+const directiveName = 'onIntersect';
+
+/**
+ * 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 const onIntersect = directive(
+    class extends Directive {
+        public element: Element | undefined;
+        public options: OnIntersectOptions | undefined;
+        public intersectionObserver: undefined | IntersectionObserver;
+        public callback: OnIntersectCallback | undefined;
+
+        constructor(partInfo: PartInfo) {
+            super(partInfo);
+
+            assertIsElementPartInfo(partInfo, directiveName);
+        }
+
+        public fireCallback(entries: IntersectionObserverEntry[], observer: IntersectionObserver) {
+            assert.isLengthAtLeast(entries, 1);
+
+            void this.callback?.({
+                element: assertWrap.isDefined(this.element),
+                allEntries: entries,
+                observer,
+                entry: entries[0],
+            });
+        }
+
+        public override update(
+            partInfo: PartInfo,
+            [
+                options,
+                callback,
+            ]: [
+                OnIntersectOptions,
+                OnIntersectCallback,
+            ],
+        ) {
+            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
+        public render(options: OnIntersectOptions, callback: OnIntersectCallback) {
+            return undefined;
+        }
+    },
+);

package/src/declarative-element/directives/on-resize.directive.ts

@@ -0,0 +1,142 @@
+import {type MaybePromise} from '@augment-vir/common';
+import {directive, Directive, type PartInfo} from '../../lit-exports/all-lit-exports.js';
+import {assertIsElementPartInfo} from './directive-helpers.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>;
+
+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 {
+        public element: Element | undefined;
+        public readonly resizeObserver = new ResizeObserver((entries) => {
+            if (this.element && this.callback) {
+                handleOnResizeCallback(this.element, this.callback, entries);
+            }
+        });
+        public callback: OnResizeCallback | undefined;
+
+        constructor(partInfo: PartInfo) {
+            super(partInfo);
+
+            assertIsElementPartInfo(partInfo, directiveName);
+        }
+
+        public override update(partInfo: PartInfo, [callback]: [OnResizeCallback]) {
+            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
+        public render(callback: OnResizeCallback) {
+            return undefined;
+        }
+    },
+);
+
+function handleOnResizeCallback(
+    element: Element,
+    callback: OnResizeCallback,
+    entries: ResizeObserverEntry[],
+) {
+    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: Element, callback: OnResizeCallback) {
+    const resizeObserver = new ResizeObserver((entries) => {
+        handleOnResizeCallback(element, callback, entries);
+    });
+
+    resizeObserver.observe(element);
+
+    return {
+        resizeObserver,
+        element,
+    };
+}

package/src/declarative-element/directives/render-async.directive.ts

@@ -0,0 +1,111 @@
+import {check} from '@augment-vir/assert';
+import {extractErrorMessage} from '@augment-vir/common';
+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 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 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 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 function renderAsync<T, FallbackResult>(
+    asyncProp: Pick<AsyncProp<T, any>, 'value'>,
+    fallback: FallbackResult,
+    resolutionRender?: undefined,
+    errorRender?: undefined,
+): FallbackResult | Awaited<T> | 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 full function definition and implementation.
+ *
+ * @category Async
+ */
+export function renderAsync<
+    T,
+    FallbackResult,
+    ResolutionRenderResult = never,
+    ErrorRenderResult = never,
+>(
+    asyncProp: Pick<AsyncProp<T, any>, 'value'>,
+    /** This value will be rendered if the async prop has not settled yet. */
+    fallback: FallbackResult,
+    resolutionRender?: ((resolved: Awaited<T>) => ResolutionRenderResult) | undefined,
+    errorRender?: ((error: Error) => ErrorRenderResult) | undefined,
+): FallbackResult | Awaited<T> | ResolutionRenderResult | string | ErrorRenderResult {
+    const asyncPropValue = asyncProp.value;
+    if (asyncPropValue instanceof Error) {
+        const errorResult: string | ErrorRenderResult = errorRender
+            ? errorRender(asyncPropValue)
+            : extractErrorMessage(asyncPropValue);
+        return errorResult as any;
+    } else if (check.isPromiseLike(asyncPropValue)) {
+        const fallbackResult: FallbackResult = fallback;
+        return fallbackResult as any;
+    } else {
+        const resolutionResult: ResolutionRenderResult | Awaited<T> = resolutionRender
+            ? resolutionRender(asyncPropValue)
+            : asyncPropValue;
+        return resolutionResult as any;
+    }
+}

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

@@ -1,4 +1,5 @@
-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
@@ -30,6 +31,14 @@ import { when } from '../../lit-exports/all-lit-exports.js';
  * });
  * ```
  */
-export function renderIf(condition, ifTrue, ifFalse) {
-    return when(condition, () => ifTrue, () => ifFalse);
+export function renderIf<TrueCondition = unknown, FalseCondition = undefined>(
+    condition: boolean,
+    ifTrue: TrueCondition,
+    ifFalse?: FalseCondition,
+): TrueCondition | FalseCondition {
+    return when(
+        condition,
+        () => ifTrue,
+        () => ifFalse,
+    ) as TrueCondition | FalseCondition;
 }

package/{dist/declarative-element/directives/test-id.directive.js → src/declarative-element/directives/test-id.directive.ts}

@@ -1,5 +1,8 @@
-import { createAttributeDirective } from './create-attribute-directive.js';
-const { attributeDirective, attributeSelector, attributeName } = createAttributeDirective('data-test-id');
+import {createAttributeDirective} from './create-attribute-directive.js';
+
+const {attributeDirective, attributeSelector, attributeName} =
+    createAttributeDirective('data-test-id');
+
 /**
  * Assigns the given id as a test id attribute to the attached element.
  *
@@ -20,6 +23,7 @@ const { attributeDirective, attributeSelector, attributeName } = createAttribute
  * ```
  */
 export const testId = attributeDirective;
+
 /**
  * Construct an attribute selector for the given test id.
  *
@@ -39,6 +43,7 @@ export const testId = attributeDirective;
  * ```
  */
 export const testIdSelector = attributeSelector;
+
 /**
  * The test id attribute name.
  *

package/{dist/declarative-element/has-declarative-element-parent.js → src/declarative-element/has-declarative-element-parent.ts}

@@ -1,16 +1,19 @@
-import { DeclarativeElement } from './declarative-element.js';
-export function hasDeclarativeElementParent(input) {
+import {DeclarativeElement} from './declarative-element.js';
+
+export function hasDeclarativeElementParent(input: Element): boolean {
     const rootNode = input.getRootNode();
+
     if (!(rootNode instanceof ShadowRoot)) {
         // declarative elements all use shadow DOM, so if a shadow root doesn't exist then we're not
         // in a declarative element.
         return false;
     }
+
     const host = rootNode.host;
+
     if (host instanceof DeclarativeElement) {
         return true;
-    }
-    else {
+    } else {
         return hasDeclarativeElementParent(host);
     }
 }

package/{dist/declarative-element/is-declarative-element-definition.js → src/declarative-element/is-declarative-element-definition.ts}

@@ -1,5 +1,10 @@
-import { AssertionError, check } from '@augment-vir/assert';
-import { getObjectTypedKeys, wrapInTry } from '@augment-vir/common';
+import {AssertionError, check} from '@augment-vir/assert';
+import {getObjectTypedKeys, wrapInTry} from '@augment-vir/common';
+import {
+    type DeclarativeElementDefinition,
+    type StaticDeclarativeElementProperties,
+} from './declarative-element.js';
+
 const expectedStaticProperties = getObjectTypedKeys({
     assign: '',
     assignedInputs: '',
@@ -16,7 +21,10 @@ const expectedStaticProperties = getObjectTypedKeys({
     styles: '',
     tagName: '',
     UpdateStateType: '',
-});
+} satisfies Readonly<
+    Record<keyof StaticDeclarativeElementProperties<any, any, any, any, any, any, any, any>, ''>
+>);
+
 /**
  * Asserts that the given input is a declarative element definition.
  *
@@ -24,7 +32,10 @@ const expectedStaticProperties = getObjectTypedKeys({
  * @see
  * - {@link isDeclarativeElementDefinition}
  */
-export function assertDeclarativeElementDefinition(input, failMessage) {
+export function assertDeclarativeElementDefinition(
+    input: unknown,
+    failMessage?: string | undefined,
+): asserts input is DeclarativeElementDefinition {
     if (!check.isFunction(input)) {
         throw new AssertionError('Input is not a declarative element constructor', failMessage);
     }
@@ -34,6 +45,7 @@ export function assertDeclarativeElementDefinition(input, failMessage) {
         }
     });
 }
+
 /**
  * Checks that the given input is a declarative element definition.
  *
@@ -41,11 +53,16 @@ export function assertDeclarativeElementDefinition(input, failMessage) {
  * @see
  * - {@link assertDeclarativeElementDefinition}
  */
-export function isDeclarativeElementDefinition(input) {
-    return wrapInTry(() => {
-        assertDeclarativeElementDefinition(input);
-        return true;
-    }, {
-        fallbackValue: false,
-    });
+export function isDeclarativeElementDefinition(
+    input: unknown,
+): input is DeclarativeElementDefinition {
+    return wrapInTry(
+        () => {
+            assertDeclarativeElementDefinition(input);
+            return true;
+        },
+        {
+            fallbackValue: false,
+        },
+    );
 }

package/{dist/declarative-element/is-declarative-element.js → src/declarative-element/is-declarative-element.ts}

@@ -1,12 +1,14 @@
-import { check } from '@augment-vir/assert';
+import {check} from '@augment-vir/assert';
+import {type DeclarativeElement} from './declarative-element.js';
+
 /**
  * Checks if the input is an instance of a DeclarativeElement, the super class of all custom
  * elements defined with element-vir.
  *
  * @category Util
  */
-export function isDeclarativeElement(input) {
-    const markerProperties = [
+export function isDeclarativeElement(input: unknown): input is DeclarativeElement {
+    const markerProperties: ReadonlyArray<keyof DeclarativeElement> = [
         'instanceInputs',
         'instanceState',
         'definition',
@@ -19,9 +21,13 @@ export function isDeclarativeElement(input) {
  *
  * @category Util
  */
-export function assertIsDeclarativeElement(input) {
+export function assertIsDeclarativeElement(input: unknown): asserts input is DeclarativeElement {
     if (!isDeclarativeElement(input)) {
         console.error('this is not a declarative element:', input);
-        throw new Error(`${String(check.hasKey(input, 'tagName') ? input.tagName : input)} is not a declarative element.`);
+        throw new Error(
+            `${String(
+                check.hasKey(input, 'tagName') ? input.tagName : input,
+            )} is not a declarative element.`,
+        );
     }
 }

package/src/declarative-element/properties/assign-inputs.ts

@@ -0,0 +1,30 @@
+import {getObjectTypedKeys} from '@augment-vir/common';
+import {type DeclarativeElement} from '../declarative-element.js';
+
+export function assignInputs(element: Element, inputs: object): void {
+    const instanceState = (element as Partial<DeclarativeElement>).instanceState;
+
+    getObjectTypedKeys(inputs).forEach((newInputKey) => {
+        if (instanceState && newInputKey in instanceState) {
+            throw new Error(
+                `Cannot set input '${String(newInputKey)}' on '${element.tagName}'. '${element.tagName}' already has a state property with the same name.`,
+            );
+        }
+        if ('instanceInputs' in element) {
+            (element.instanceInputs as DeclarativeElement['instanceInputs'])[newInputKey] =
+                inputs[newInputKey];
+        } else {
+            element[newInputKey] = inputs[newInputKey];
+        }
+    });
+
+    /** Wipe out all inputs that weren't set to undefined (as expected) */
+    if ('instanceInputs' in element) {
+        getObjectTypedKeys(element.instanceInputs).forEach((existingKey) => {
+            if (!(existingKey in inputs)) {
+                (element.instanceInputs as DeclarativeElement['instanceInputs'])[existingKey] =
+                    undefined;
+            }
+        });
+    }
+}

package/src/declarative-element/properties/css-vars.ts

@@ -0,0 +1,24 @@
+import {type Values} from '@augment-vir/common';
+import {type CssVarDefinitions, type CssVarsSetup} from 'lit-css-vars';
+import {type CustomElementTagName} from '../custom-tag-name.js';
+import {type BaseStringName} from './string-names.js';
+
+/**
+ * Base type for a declarative element definition's CSS vars.
+ *
+ * @category Internal
+ */
+export type CssVarsInitMap<
+    ElementTagName extends CustomElementTagName,
+    CssVarKeys extends BaseStringName<ElementTagName>,
+> = Readonly<Record<CssVarKeys, Values<CssVarsSetup>>>;
+
+/**
+ * CSS vars ready for use within a declarative element's `render` or `styles` method.
+ *
+ * @category Internal
+ */
+export type CssVars<
+    ElementTagName extends CustomElementTagName,
+    CssVarKeys extends BaseStringName<ElementTagName>,
+> = CssVarDefinitions<CssVarsInitMap<ElementTagName, CssVarKeys>>;