element-vir 26.11.2 → 26.12.0

package/dist/declarative-element/directives/attributes.directive.d.ts

@@ -1,30 +0,0 @@
-import { type Primitive } from 'type-fest';
-import { nothing } from '../../lit-exports/all-lit-exports.js';
-/**
- * Possible attribute values for {@link AttributeValues}.
- *
- * @category Internal
- */
-export type AttributeValue = Exclude<Primitive, symbol> | string | typeof nothing;
-/**
- * Parameters object for applying attributes to an HTML element via the {@link attributes} directive.
- * Make sure that all keys (attribute names) are lowercase.
- *
- * @category Internal
- */
-export type AttributeValues = {
-    [LowercaseKey in Lowercase<string>]: AttributeValue;
-};
-/**
- * A directive applies multiple HTML attributes to the parent element all at once.
- *
- * @category Directives
- */
-export declare const attributes: (values_0: AttributeValues | undefined) => import("lit-html/directive.js").DirectiveResult<{
-    new (partInfo: import("lit-html/directive.js").PartInfo): {
-        readonly element: HTMLElement;
-        render(params_0: AttributeValues | undefined): symbol;
-        get _$isConnected(): boolean;
-        update(_part: import("lit-html").Part, props: Array<unknown>): unknown;
-    };
-}>;

package/dist/declarative-element/directives/attributes.directive.js

@@ -1,35 +0,0 @@
-import { getObjectTypedKeys, getOrSet } from '@augment-vir/common';
-import { nothing } from '../../lit-exports/all-lit-exports.js';
-import { createMutateDirective } from './mutate.directive.js';
-/**
- * A directive applies multiple HTML attributes to the parent element all at once.
- *
- * @category Directives
- */
-export const attributes = createMutateDirective('attributes', ({ element, params: [attributesToApply], directive: rawDirective }) => {
-    if (!attributesToApply) {
-        return;
-    }
-    const directive = rawDirective;
-    const allAttributeNames = getOrSet(directive, 'allAttributesApplied', () => new Set());
-    getObjectTypedKeys(attributesToApply).forEach((attributeName) => {
-        if (attributeName.toLowerCase() !== attributeName) {
-            throw new Error(`Cannot assign attribute name with uppercase letters: ${attributeName}`);
-        }
-        allAttributeNames.add(attributeName);
-    });
-    allAttributeNames.forEach((attributeName) => {
-        const attributeValue = attributesToApply[attributeName];
-        if (attributeValue == undefined ||
-            attributeValue === false ||
-            attributeValue === nothing) {
-            element.removeAttribute(attributeName);
-        }
-        else if (attributeValue === '' || attributeValue === true) {
-            element.setAttribute(attributeName, '');
-        }
-        else {
-            element.setAttribute(attributeName, String(attributeValue));
-        }
-    });
-});

package/dist/declarative-element/directives/create-attribute-directive.d.ts

@@ -1,28 +0,0 @@
-import { type PartInfo } from '../../lit-exports/all-lit-exports.js';
-/**
- * Creates a lit directive that used simply for setting attributes on its parent element.
- *
- * @category Internal
- */
-export declare function createAttributeDirective(attributeName: string): {
-    /**
-     * 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): string;
-    /**
-     * Instantiates the attribute directive. This must be used on an element inside of an HTML
-     * template.
-     */
-    attributeDirective(this: void, attributeValue: string): import("lit-html/directive.js").DirectiveResult<{
-        new (partInfo: PartInfo): {
-            readonly element: Element;
-            render(attributeValue: string): symbol;
-            get _$isConnected(): boolean;
-            update(_part: import("lit-html").Part, props: Array<unknown>): unknown;
-        };
-    }>;
-    /** The name of the attribute used in the directive. */
-    attributeName: string;
-};

package/dist/declarative-element/directives/create-attribute-directive.js

@@ -1,41 +0,0 @@
-import { directive, Directive, noChange } 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) {
-    const newDirective = directive(
-    /** @internal */
-    class extends Directive {
-        element;
-        constructor(partInfo) {
-            super(partInfo);
-            this.element = extractElement(partInfo, attributeName);
-        }
-        render(attributeValue) {
-            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(attributeValue) {
-            return `[${attributeName}="${attributeValue}"]`;
-        },
-        /**
-         * Instantiates the attribute directive. This must be used on an element inside of an HTML
-         * template.
-         */
-        attributeDirective(attributeValue) {
-            return newDirective(attributeValue);
-        },
-        /** The name of the attribute used in the directive. */
-        attributeName,
-    };
-}

package/dist/declarative-element/directives/directive-helpers.d.ts

@@ -1,27 +0,0 @@
-import { type ElementPartInfo, type PartInfo } 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 declare function extractElement(partInfo: PartInfo, directiveName: string): Element;
-/**
- * Asserts that the given part info is an instance of {@link FullElementPartInfo}.
- *
- * @category Internal
- */
-export declare function assertIsElementPartInfo(partInfo: PartInfo, directiveName: string): asserts partInfo is FullElementPartInfo;

package/dist/declarative-element/directives/directive-helpers.js

@@ -1,37 +0,0 @@
-import { PartType, } from '../../lit-exports/all-lit-exports.js';
-/**
- * Extracts the element from the given part info. Used in lit directives.
- *
- * @category Internal
- */
-export function extractElement(partInfo, directiveName) {
-    assertIsElementPartInfo(partInfo, directiveName);
-    const element = partInfo.element;
-    return element;
-}
-function getPartHostTagName(partInfo) {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        const tagName = partInfo.options.host.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, directiveName) {
-    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.element) {
-        throw new Error(`${directiveName} directive found no element${hostTagMessage}.`);
-    }
-}

package/dist/declarative-element/directives/listen-to-activate.d.ts

@@ -1,15 +0,0 @@
-import { type MaybePromise } from '@augment-vir/common';
-/**
- * Listens to enter, return, and space key hits on an element. Similar to {@link listenToEnter} but
- * includes space.
- *
- * @category Directives
- */
-export declare function listenToActivate(callback: () => MaybePromise<void>): import("lit-html/directive.js").DirectiveResult<any>;
-/**
- * Listens to enter and return key hits on an element. Similar to {@link listenToActivate} but
- * doesn't include space.
- *
- * @category Directives
- */
-export declare function listenToEnter(callback: () => MaybePromise<void>): import("lit-html/directive.js").DirectiveResult<any>;

package/dist/declarative-element/directives/listen.directive.d.ts

@@ -1,92 +0,0 @@
-import { type MaybePromise } from '@augment-vir/common';
-import { type DirectiveResult } from '../../lit-exports/all-lit-exports.js';
-import { type DefinedTypedEvent, type TypedEvent } from '../../typed-event/typed-event.js';
-/** We don't care at all what this returns, just allow anything! */
-type ListenCallbackReturn = MaybePromise<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 declare 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 declare 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 {};

package/dist/declarative-element/directives/listen.directive.js

@@ -1,48 +0,0 @@
-import { directive, Directive, noChange, } from '../../lit-exports/all-lit-exports.js';
-import { extractElement } from './directive-helpers.js';
-export function listen(eventType, listener) {
-    return listenDirective(eventType, listener);
-}
-/**
- * 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 {
-    element;
-    lastListenerMetaData;
-    constructor(partInfo) {
-        super(partInfo);
-        this.element = extractElement(partInfo, 'listen');
-    }
-    resetListener(listenerMetaData) {
-        if (this.lastListenerMetaData) {
-            this.element.removeEventListener(this.lastListenerMetaData.eventType, this.lastListenerMetaData.listener);
-        }
-        this.element.addEventListener(listenerMetaData.eventType, listenerMetaData.listener);
-        this.lastListenerMetaData = listenerMetaData;
-    }
-    createListenerMetaData(eventType, callback) {
-        return {
-            eventType,
-            callback,
-            listener: (event) => this.lastListenerMetaData?.callback(event),
-        };
-    }
-    render(eventTypeInput, callback) {
-        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/dist/declarative-element/directives/mutate.directive.d.ts

@@ -1,38 +0,0 @@
-import { Directive, type PartInfo } from '../../lit-exports/all-lit-exports.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 declare const mutate: (callback: (params: Omit<MutateDirectiveParams, "params">) => void) => import("lit-html/directive.js").DirectiveResult<{
-    new (partInfo: PartInfo): {
-        readonly element: HTMLElement;
-        lastKey: string | undefined;
-        render(callback: (params: Omit<MutateDirectiveParams, "params">) => void): symbol;
-        get _$isConnected(): boolean;
-        update(_part: import("lit-html").Part, props: Array<unknown>): unknown;
-    };
-}>;
-/**
- * A helper for making new directives.
- *
- * @category Internal
- */
-export declare function createMutateDirective<Params extends any[]>(directiveName: string, callback: (this: void, params: MutateDirectiveParams<Params>) => void): (...values: Params) => import("lit-html/directive.js").DirectiveResult<{
-    new (partInfo: PartInfo): {
-        readonly element: HTMLElement;
-        render(...params: Params): symbol;
-        get _$isConnected(): boolean;
-        update(_part: import("lit-html").Part, props: Array<unknown>): unknown;
-    };
-}>;

package/dist/declarative-element/directives/mutate.directive.js

@@ -1,45 +0,0 @@
-import { assertWrap } from '@augment-vir/assert';
-import { directive, Directive, noChange } from '../../lit-exports/all-lit-exports.js';
-import { extractElement } from './directive-helpers.js';
-/**
- * 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 {
-    element;
-    lastKey;
-    constructor(partInfo) {
-        super(partInfo);
-        this.element = assertWrap.instanceOf(extractElement(partInfo, 'modifyElement'), HTMLElement);
-    }
-    render(callback) {
-        callback({
-            directive: this,
-            element: this.element,
-        });
-        return noChange;
-    }
-});
-/**
- * A helper for making new directives.
- *
- * @category Internal
- */
-export function createMutateDirective(directiveName, callback) {
-    return directive(class extends Directive {
-        element;
-        constructor(partInfo) {
-            super(partInfo);
-            this.element = assertWrap.instanceOf(extractElement(partInfo, directiveName), HTMLElement);
-        }
-        render(...params) {
-            callback({
-                params,
-                directive: this,
-                element: this.element,
-            });
-            return noChange;
-        }
-    });
-}

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

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

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

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

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