element-vir 26.12.0 → 26.12.1

package/dist/declarative-element/directives/async-prop.d.ts

@@ -0,0 +1,61 @@
+import { type Overwrite } from '@augment-vir/common';
+import { CallbackObservable, type AsyncValue, type CallbackObservableInit } from 'observavir';
+export type { AsyncValue } from 'observavir';
+/**
+ * Class for constructing async props. Do not use this directly as its internal types won't be
+ * inferred correctly. Instead use {@link asyncProp} an async prop or {@link AsyncProp} for types.
+ *
+ * @category Internal
+ */
+export declare class InternalAsyncPropClass<Value, Params> extends CallbackObservable<Value, Params> {
+    /**
+     * Checks if the current `.value` has resolved (meaning the Promise has settled and it was not
+     * rejected). This type guards the current instance's `.value` property.
+     */
+    isResolved(): this is Overwrite<this, {
+        value: Exclude<AsyncValue<Value>, Promise<any> | Error>;
+    }>;
+    /**
+     * Checks if the current `.value` has settled (meaning it is either a rejection error or a
+     * resolved value). This type guards the current instance's `.value` property.
+     */
+    isSettled(): this is Overwrite<this, {
+        value: Exclude<AsyncValue<Value>, Promise<any>>;
+    }>;
+    /**
+     * Checks if the current `.value` has not settled yet settled (meaning it is still an unsettled
+     * Promise). This type guards the current instance's `.value` property.
+     */
+    isWaiting(): this is Overwrite<this, {
+        value: Extract<AsyncValue<Value>, Promise<any>>;
+    }>;
+    /**
+     * Checks if the current `.value` is a rejection error. This type guards the current instance's
+     * `.value` property.
+     */
+    isError(): this is Overwrite<this, {
+        value: Extract<AsyncValue<Value>, Error>;
+    }>;
+    /**
+     * Checks if the current `.value` is resolved (and not an error) or still waiting. This type
+     * guards the current instance's `.value` property.
+     */
+    isNotError(): this is Overwrite<this, {
+        value: Exclude<AsyncValue<Value>, Error>;
+    }>;
+}
+/**
+ * An async property created by {@link asyncProp} for use within declarative elements. Do not use
+ * this directly as its internal types won't be inferred correctly.
+ *
+ * @category Internal
+ */
+export type AsyncProp<Value, Params> = Omit<InternalAsyncPropClass<Value, Params>, 
+/** Hide these properties to make the `AsyncProp` interface much simpler. */
+'dispatch' | 'equalityCheck' | 'getListenerCount' | 'updateCallback' | 'removeListener' | 'removeAllListeners' | 'listenToEvent' | 'listen' | 'resolvedValue'>;
+/**
+ * Create an async prop for a declarative element's state.
+ *
+ * @category Async
+ */
+export declare function asyncProp<Value, Params = void>(init?: CallbackObservableInit<Value, Params>): AsyncProp<Value, Params>;

package/{src/declarative-element/directives/async-prop.ts → dist/declarative-element/directives/async-prop.js}

@@ -1,86 +1,52 @@
-import {type Overwrite} from '@augment-vir/common';
-import {CallbackObservable, type AsyncValue, type CallbackObservableInit} from 'observavir';
-
-export type {AsyncValue} from 'observavir';
-
+import { CallbackObservable } from 'observavir';
 /**
  * Class for constructing async props. Do not use this directly as its internal types won't be
  * inferred correctly. Instead use {@link asyncProp} an async prop or {@link AsyncProp} for types.
  *
  * @category Internal
  */
-export class InternalAsyncPropClass<Value, Params> extends CallbackObservable<Value, Params> {
+export class InternalAsyncPropClass extends CallbackObservable {
     /**
      * Checks if the current `.value` has resolved (meaning the Promise has settled and it was not
      * rejected). This type guards the current instance's `.value` property.
      */
-    public isResolved(): this is Overwrite<
-        this,
-        {value: Exclude<AsyncValue<Value>, Promise<any> | Error>}
-    > {
+    isResolved() {
         return !(this.value instanceof Promise);
     }
-
     /**
      * Checks if the current `.value` has settled (meaning it is either a rejection error or a
      * resolved value). This type guards the current instance's `.value` property.
      */
-    public isSettled(): this is Overwrite<this, {value: Exclude<AsyncValue<Value>, Promise<any>>}> {
+    isSettled() {
         return !(this.value instanceof Promise);
     }
-
     /**
      * Checks if the current `.value` has not settled yet settled (meaning it is still an unsettled
      * Promise). This type guards the current instance's `.value` property.
      */
-    public isWaiting(): this is Overwrite<this, {value: Extract<AsyncValue<Value>, Promise<any>>}> {
+    isWaiting() {
         return this.value instanceof Promise;
     }
-
     /**
      * Checks if the current `.value` is a rejection error. This type guards the current instance's
      * `.value` property.
      */
-    public isError(): this is Overwrite<this, {value: Extract<AsyncValue<Value>, Error>}> {
+    isError() {
         return this.value instanceof Error;
     }
-
     /**
      * Checks if the current `.value` is resolved (and not an error) or still waiting. This type
      * guards the current instance's `.value` property.
      */
-    public isNotError(): this is Overwrite<this, {value: Exclude<AsyncValue<Value>, Error>}> {
+    isNotError() {
         return !(this.value instanceof Error);
     }
 }
-
-/**
- * An async property created by {@link asyncProp} for use within declarative elements. Do not use
- * this directly as its internal types won't be inferred correctly.
- *
- * @category Internal
- */
-export type AsyncProp<Value, Params> = Omit<
-    InternalAsyncPropClass<Value, Params>,
-    /** Hide these properties to make the `AsyncProp` interface much simpler. */
-    | 'dispatch'
-    | 'equalityCheck'
-    | 'getListenerCount'
-    | 'updateCallback'
-    | 'removeListener'
-    | 'removeAllListeners'
-    | 'listenToEvent'
-    | 'listen'
-    | 'resolvedValue'
->;
-
 /**
  * Create an async prop for a declarative element's state.
  *
  * @category Async
  */
-export function asyncProp<Value, Params = void>(
-    init?: CallbackObservableInit<Value, Params>,
-): AsyncProp<Value, Params> {
+export function asyncProp(init) {
     return new InternalAsyncPropClass(init);
 }

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

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

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

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

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

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

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

@@ -0,0 +1,15 @@
+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/{src/declarative-element/directives/listen-to-activate.ts → dist/declarative-element/directives/listen-to-activate.js}

@@ -1,16 +1,13 @@
-import {type MaybePromise} from '@augment-vir/common';
-import {listen} from './listen.directive.js';
-
+import { listen } from './listen.directive.js';
 /**
  * Listens to enter, return, and space key hits on an element. Similar to {@link listenToEnter} but
  * includes space.
  *
  * @category Directives
  */
-export function listenToActivate(callback: () => MaybePromise<void>) {
+export function listenToActivate(callback) {
     return listen('keydown', async (event) => {
         const key = event.code.toLowerCase();
-
         if (key.includes('enter') || key.includes('return') || key === 'space') {
             event.stopImmediatePropagation();
             event.preventDefault();
@@ -18,17 +15,15 @@ export function listenToActivate(callback: () => MaybePromise<void>) {
         }
     });
 }
-
 /**
  * Listens to enter and return key hits on an element. Similar to {@link listenToActivate} but
  * doesn't include space.
  *
  * @category Directives
  */
-export function listenToEnter(callback: () => MaybePromise<void>) {
+export function listenToEnter(callback) {
     return listen('keydown', async (event) => {
         const key = event.code.toLowerCase();
-
         if (key.includes('enter') || key.includes('return')) {
             event.stopImmediatePropagation();
             event.preventDefault();

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

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

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

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

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