element-vir 26.11.2 → 26.12.0

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

@@ -1,52 +1,86 @@
-import { CallbackObservable } from 'observavir';
+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 class InternalAsyncPropClass extends CallbackObservable {
+export 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() {
+    public isResolved(): this is Overwrite<
+        this,
+        {value: Exclude<AsyncValue<Value>, Promise<any> | Error>}
+    > {
         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.
      */
-    isSettled() {
+    public isSettled(): this is Overwrite<this, {value: Exclude<AsyncValue<Value>, Promise<any>>}> {
         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.
      */
-    isWaiting() {
+    public isWaiting(): this is Overwrite<this, {value: Extract<AsyncValue<Value>, Promise<any>>}> {
         return this.value instanceof Promise;
     }
+
     /**
      * Checks if the current `.value` is a rejection error. This type guards the current instance's
      * `.value` property.
      */
-    isError() {
+    public isError(): this is Overwrite<this, {value: Extract<AsyncValue<Value>, Error>}> {
         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.
      */
-    isNotError() {
+    public isNotError(): this is Overwrite<this, {value: Exclude<AsyncValue<Value>, Error>}> {
         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(init) {
+export function asyncProp<Value, Params = void>(
+    init?: CallbackObservableInit<Value, Params>,
+): AsyncProp<Value, Params> {
     return new InternalAsyncPropClass(init);
 }

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

@@ -0,0 +1,63 @@
+import {getObjectTypedKeys, getOrSet} from '@augment-vir/common';
+import {type Primitive} from 'type-fest';
+import {nothing} from '../../lit-exports/all-lit-exports.js';
+import {createMutateDirective} from './mutate.directive.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 const attributes = createMutateDirective<[AttributeValues | undefined]>(
+    'attributes',
+    ({element, params: [attributesToApply], directive: rawDirective}) => {
+        if (!attributesToApply) {
+            return;
+        }
+
+        type DirectiveWithAttributesList = typeof rawDirective & {
+            allAttributesApplied?: Set<Lowercase<string>>;
+        };
+        const directive = rawDirective as DirectiveWithAttributesList;
+        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/src/declarative-element/directives/create-attribute-directive.ts

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

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

@@ -1,13 +1,16 @@
-import { listen } from './listen.directive.js';
+import {type MaybePromise} from '@augment-vir/common';
+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) {
+export function listenToActivate(callback: () => MaybePromise<void>) {
     return listen('keydown', async (event) => {
         const key = event.code.toLowerCase();
+
         if (key.includes('enter') || key.includes('return') || key === 'space') {
             event.stopImmediatePropagation();
             event.preventDefault();
@@ -15,15 +18,17 @@ export function listenToActivate(callback) {
         }
     });
 }
+
 /**
  * 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) {
+export function listenToEnter(callback: () => MaybePromise<void>) {
     return listen('keydown', async (event) => {
         const key = event.code.toLowerCase();
+
         if (key.includes('enter') || key.includes('return')) {
             event.stopImmediatePropagation();
             event.preventDefault();

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

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

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

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