element-vir 26.12.0 → 26.12.1

package/src/declarative-element/directives/create-attribute-directive.ts

@@ -1,47 +0,0 @@
-import {directive, Directive, noChange, type PartInfo} from '../../lit-exports/all-lit-exports.js';
-import {extractElement} from './directive-helpers.js';
-
-/**
- * Creates a lit directive that used simply for setting attributes on its parent element.
- *
- * @category Internal
- */
-export function createAttributeDirective(attributeName: string) {
-    const newDirective = directive(
-        /** @internal */
-        class extends Directive {
-            public readonly element: Element;
-
-            constructor(partInfo: PartInfo) {
-                super(partInfo);
-
-                this.element = extractElement(partInfo, attributeName);
-            }
-
-            public render(attributeValue: string) {
-                this.element.setAttribute(attributeName, attributeValue);
-                return noChange;
-            }
-        },
-    );
-
-    return {
-        /**
-         * Creates a string for use with the
-         * [`querySelector`](https://developer.mozilla.org/docs/Web/API/Document/querySelector) API
-         * that selects this directive's attribute set to the given `attributeValue`.
-         */
-        attributeSelector(this: void, attributeValue: string) {
-            return `[${attributeName}="${attributeValue}"]`;
-        },
-        /**
-         * Instantiates the attribute directive. This must be used on an element inside of an HTML
-         * template.
-         */
-        attributeDirective(this: void, attributeValue: string) {
-            return newDirective(attributeValue);
-        },
-        /** The name of the attribute used in the directive. */
-        attributeName,
-    };
-}

package/src/declarative-element/directives/directive-helpers.ts

@@ -1,67 +0,0 @@
-import {
-    type ChildPart,
-    type ElementPartInfo,
-    type PartInfo,
-    PartType,
-} from '../../lit-exports/all-lit-exports.js';
-
-/**
- * The full type for `ElementPartInfo` because `lit`'s built-in type leaves out of most of its
- * interface.
- *
- * @category Internal
- */
-export type FullElementPartInfo =
-    ElementPartInfo /** For some reason these aren't defined in lit's types already, even though they _do_ exist. */ & {
-        element: Element;
-        options: {
-            host: Element;
-            renderBefore: Element;
-            isConnected: boolean;
-        };
-    };
-
-/**
- * Extracts the element from the given part info. Used in lit directives.
- *
- * @category Internal
- */
-export function extractElement(partInfo: PartInfo, directiveName: string): Element {
-    assertIsElementPartInfo(partInfo, directiveName);
-    const element = partInfo.element;
-    return element;
-}
-
-function getPartHostTagName(partInfo: PartInfo): string | undefined {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        const tagName = ((partInfo as ChildPart).options!.host as Element).tagName.toLowerCase();
-
-        return tagName;
-    } catch {
-        return undefined;
-    }
-}
-
-/**
- * Asserts that the given part info is an instance of {@link FullElementPartInfo}.
- *
- * @category Internal
- */
-export function assertIsElementPartInfo(
-    partInfo: PartInfo,
-    directiveName: string,
-): asserts partInfo is FullElementPartInfo {
-    const hostTagName = getPartHostTagName(partInfo);
-    const hostTagMessage = hostTagName ? `: in ${hostTagName}` : '';
-
-    if (partInfo.type !== PartType.ELEMENT) {
-        throw new Error(
-            `${directiveName} directive can only be attached directly to an element${hostTagMessage}.`,
-        );
-    }
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    if (!(partInfo as FullElementPartInfo).element) {
-        throw new Error(`${directiveName} directive found no element${hostTagMessage}.`);
-    }
-}

package/src/declarative-element/directives/listen.directive.ts

@@ -1,206 +0,0 @@
-import {type MaybePromise} from '@augment-vir/common';
-import {
-    directive,
-    Directive,
-    type DirectiveResult,
-    noChange,
-    type PartInfo,
-} from '../../lit-exports/all-lit-exports.js';
-import {
-    type DefinedTypedEvent,
-    defineTypedEvent,
-    type TypedEvent,
-} from '../../typed-event/typed-event.js';
-import {extractElement} from './directive-helpers.js';
-
-/** We don't care at all what this returns, just allow anything! */
-type ListenCallbackReturn = MaybePromise<any>;
-
-type PossibleListenerCallbacks<
-    TypedEventTypeNameGeneric extends string,
-    TypedEventDetailGeneric,
-    NativeElementEventNameGeneric extends keyof HTMLElementEventMap,
-> =
-    | ((
-          event: TypedEvent<TypedEventTypeNameGeneric, TypedEventDetailGeneric>,
-      ) => ListenCallbackReturn)
-    | ((event: HTMLElementEventMap[NativeElementEventNameGeneric]) => ListenCallbackReturn);
-
-/**
- * Listen to events. These can be native DOM events (use a string for the inputType argument) or
- * typed events (pass in a return value from {@link defineTypedEvent}).
- *
- * @category Directives
- * @example
- *
- * ```ts
- * import {html, defineElement, listen} from 'element-vir';
- *
- * const MyElement = defineElement()({
- *     tagName: 'my-element',
- *     render() {
- *         return html`
- *             <div
- *                 ${listen('click', () => {
- *                     console.log('clicked!');
- *                 })}
- *             >
- *                 Some div
- *             </div>
- *             <${MyOtherElement}
- *                 ${listen(MyOtherElement.events.someEvent, (event) => {
- *                     console.log('event value', event.detail);
- *                 })}
- *             ></${MyOtherElement}>
- *         `;
- *     },
- * });
- * ```
- */
-export function listen<TypedEventTypeNameGeneric extends string, TypedEventDetailGeneric>(
-    /**
-     * Needs to come either from a declarative element (like MyDeclarativeElement.events.eventName),
-     * from a typed event created via the {@link defineTypedEvent} function, or be the name of a
-     * built-in event (like `'click'`).
-     */
-    eventType: DefinedTypedEvent<TypedEventTypeNameGeneric, TypedEventDetailGeneric>,
-    /**
-     * The callback to fire when an event is caught. Assuming the {@link defineTypedEvent} input is
-     * properly typed, the event given to this callback will also be typed.
-     */
-    listener: (
-        event: TypedEvent<TypedEventTypeNameGeneric, TypedEventDetailGeneric>,
-    ) => ListenCallbackReturn,
-): DirectiveResult<any>;
-/**
- * Listen to events. These can be native DOM events (use a string for the inputType argument) or
- * typed events (pass in a return value from {@link defineTypedEvent}).
- *
- * @category Directives
- * @example
- *
- * ```ts
- * import {html, defineElement, listen} from 'element-vir';
- *
- * const MyElement = defineElement()({
- *     tagName: 'my-element',
- *     render() {
- *         return html`
- *             <div
- *                 ${listen('click', () => {
- *                     console.log('clicked!');
- *                 })}
- *             >
- *                 Some div
- *             </div>
- *             <${MyOtherElement}
- *                 ${listen(MyOtherElement.events.someEvent, (event) => {
- *                     console.log('event value', event.detail);
- *                 })}
- *             ></${MyOtherElement}>
- *         `;
- *     },
- * });
- * ```
- */
-export function listen<NativeElementEventNameGeneric extends keyof HTMLElementEventMap>(
-    /**
-     * Needs to come either from a declarative element (like MyDeclarativeElement.events.eventName),
-     * from a typed event created via the {@link defineTypedEvent} function, or be the name of a
-     * built-in event (like `'click'`).
-     */
-    eventType: NativeElementEventNameGeneric,
-    /**
-     * The callback to fire when an event is caught. Assuming the {@link defineTypedEvent} input is
-     * properly typed, the event given to this callback will also be typed.
-     */
-    listener: (event: HTMLElementEventMap[NativeElementEventNameGeneric]) => ListenCallbackReturn,
-): DirectiveResult<any>;
-export function listen<
-    TypedEventTypeNameGeneric extends string,
-    TypedEventDetailGeneric,
-    NativeElementEventNameGeneric extends keyof HTMLElementEventMap,
->(
-    eventType:
-        | DefinedTypedEvent<TypedEventTypeNameGeneric, TypedEventDetailGeneric>
-        | NativeElementEventNameGeneric,
-    listener: PossibleListenerCallbacks<
-        TypedEventTypeNameGeneric,
-        TypedEventDetailGeneric,
-        NativeElementEventNameGeneric
-    >,
-): DirectiveResult<any> {
-    return listenDirective(eventType, listener);
-}
-
-type ListenerMetaData = {
-    eventType: string;
-    callback: PossibleListenerCallbacks<any, any, any>;
-    listener: (event: any) => ListenCallbackReturn;
-};
-
-/**
- * The directive generics here are not strong enough to maintain their values. Thus, the directive
- * call is wrapped in the function above.
- */
-const listenDirective = directive(
-    class extends Directive {
-        public readonly element: Element;
-        public lastListenerMetaData: ListenerMetaData | undefined;
-
-        constructor(partInfo: PartInfo) {
-            super(partInfo);
-
-            this.element = extractElement(partInfo, 'listen');
-        }
-
-        public resetListener(listenerMetaData: ListenerMetaData) {
-            if (this.lastListenerMetaData) {
-                this.element.removeEventListener(
-                    this.lastListenerMetaData.eventType,
-                    this.lastListenerMetaData.listener,
-                );
-            }
-            this.element.addEventListener(listenerMetaData.eventType, listenerMetaData.listener);
-            this.lastListenerMetaData = listenerMetaData;
-        }
-
-        public createListenerMetaData(
-            eventType: string,
-            callback: (event: TypedEvent<string, unknown>) => ListenCallbackReturn,
-        ): ListenerMetaData {
-            return {
-                eventType,
-                callback,
-                listener: (event: TypedEvent<string, unknown>) =>
-                    this.lastListenerMetaData?.callback(event),
-            };
-        }
-
-        public render(
-            eventTypeInput: {type: string} | string,
-            callback: PossibleListenerCallbacks<any, any, any>,
-        ) {
-            const eventType =
-                typeof eventTypeInput === 'string' ? eventTypeInput : eventTypeInput.type;
-
-            if (typeof eventType !== 'string') {
-                throw new TypeError(
-                    `Cannot listen to an event with a name that is not a string. Given event name: '${String(eventType)}'`,
-                );
-            }
-
-            if (this.lastListenerMetaData && this.lastListenerMetaData.eventType === eventType) {
-                /**
-                 * Store the callback here so we don't have to update the attached listener every
-                 * time the callback is updated.
-                 */
-                this.lastListenerMetaData.callback = callback;
-            } else {
-                this.resetListener(this.createListenerMetaData(eventType, callback));
-            }
-
-            return noChange;
-        }
-    },
-);

package/src/declarative-element/directives/mutate.directive.ts

@@ -1,78 +0,0 @@
-import {assertWrap} from '@augment-vir/assert';
-import {directive, Directive, noChange, type PartInfo} from '../../lit-exports/all-lit-exports.js';
-import {extractElement} from './directive-helpers.js';
-
-/**
- * Parameters for the callback given to the {@link mutate} directive.
- *
- * @category Internal
- */
-export type MutateDirectiveParams<Params extends any[] = []> = {
-    directive: Directive;
-    element: HTMLElement;
-    params: Params;
-};
-
-/**
- * A directive that allows arbitrary modifications to be made to the element that it's attached to.
- *
- * @category Directives
- */
-export const mutate = directive(
-    class extends Directive {
-        public readonly element: HTMLElement;
-        public lastKey: string | undefined;
-
-        constructor(partInfo: PartInfo) {
-            super(partInfo);
-
-            this.element = assertWrap.instanceOf(
-                extractElement(partInfo, 'modifyElement'),
-                HTMLElement,
-            );
-        }
-
-        public render(callback: (params: Omit<MutateDirectiveParams, 'params'>) => void) {
-            callback({
-                directive: this,
-                element: this.element,
-            });
-            return noChange;
-        }
-    },
-);
-
-/**
- * A helper for making new directives.
- *
- * @category Internal
- */
-export function createMutateDirective<Params extends any[]>(
-    directiveName: string,
-    callback: (this: void, params: MutateDirectiveParams<Params>) => void,
-) {
-    return directive(
-        class extends Directive {
-            public readonly element: HTMLElement;
-
-            constructor(partInfo: PartInfo) {
-                super(partInfo);
-
-                this.element = assertWrap.instanceOf(
-                    extractElement(partInfo, directiveName),
-                    HTMLElement,
-                );
-            }
-
-            public render(...params: Params) {
-                callback({
-                    params,
-                    directive: this,
-                    element: this.element,
-                });
-
-                return noChange;
-            }
-        },
-    );
-}

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

@@ -1,68 +0,0 @@
-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 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>;
-
-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 {
-        public element: Element | undefined;
-
-        constructor(partInfo: PartInfo) {
-            super(partInfo);
-
-            assertIsElementPartInfo(partInfo, directiveName);
-        }
-
-        public override update(partInfo: PartInfo, [callback]: [OnDomCreatedCallback]) {
-            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
-        public render(callback: OnDomCreatedCallback) {
-            return undefined;
-        }
-    },
-);

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

@@ -1,61 +0,0 @@
-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

@@ -1,139 +0,0 @@
-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;
-        }
-    },
-);