element-vir 26.11.2 → 26.12.0

package/{dist/readme-examples/my-with-event-listening.element.js → src/readme-examples/my-with-event-listening.element.ts}

@@ -1,6 +1,7 @@
-import { defineElement } from 'element-vir';
-import { html, listen } from '../index.js';
-import { MyWithEvents } from './my-with-events.element.js';
+import {defineElement} from 'element-vir';
+import {html, listen} from '../index.js';
+import {MyWithEvents} from './my-with-events.element.js';
+
 export const MyWithEventListening = defineElement()({
     tagName: 'my-with-event-listening',
     state() {
@@ -8,16 +9,16 @@ export const MyWithEventListening = defineElement()({
             myNumber: -1,
         };
     },
-    render({ state, updateState }) {
-        return html `
+    render({state, updateState}) {
+        return html`
             <h1>My App</h1>
             <${MyWithEvents}
                 ${listen(MyWithEvents.events.logoutClick, () => {
-            console.info('logout triggered');
-        })}
+                    console.info('logout triggered');
+                })}
                 ${listen(MyWithEvents.events.randomNumber, (event) => {
-            updateState({ myNumber: event.detail });
-        })}
+                    updateState({myNumber: event.detail});
+                })}
             ></${MyWithEvents}>
             <span>${state.myNumber}</span>
         `;

package/src/readme-examples/my-with-events.element.ts

@@ -0,0 +1,23 @@
+import {randomInteger} from '@augment-vir/common';
+import {defineElement} from 'element-vir';
+import {defineElementEvent, html, listen} from '../index.js';
+
+export const MyWithEvents = defineElement()({
+    tagName: 'my-with-events',
+    events: {
+        logoutClick: defineElementEvent<void>(),
+        randomNumber: defineElementEvent<number>(),
+    },
+    render({dispatch, events}) {
+        return html`
+            <button ${listen('click', () => dispatch(new events.logoutClick()))}>log out</button>
+            <button
+                ${listen('click', () =>
+                    dispatch(new events.randomNumber(randomInteger({min: 0, max: 1_000_000}))),
+                )}
+            >
+                generate random number
+            </button>
+        `;
+    },
+});

package/{dist/readme-examples/my-with-host-class-definition.element.js → src/readme-examples/my-with-host-class-definition.element.ts}

@@ -1,5 +1,6 @@
-import { defineElement } from 'element-vir';
-import { css, html } from '../index.js';
+import {defineElement} from 'element-vir';
+import {css, html} from '../index.js';
+
 export const MyWithHostClassDefinition = defineElement()({
     tagName: 'my-with-host-class-definition',
     state() {
@@ -17,7 +18,7 @@ export const MyWithHostClassDefinition = defineElement()({
          * This host class will be automatically applied if the given callback is evaluated to true
          * after a call to render.
          */
-        'my-with-host-class-definition-automatic': ({ state }) => {
+        'my-with-host-class-definition-automatic': ({state}) => {
             return state.myProp === 'foo';
         },
     },
@@ -25,7 +26,7 @@ export const MyWithHostClassDefinition = defineElement()({
      * Apply styles to the host classes by using a callback for "styles". The callback's argument
      * contains the host classes defined above in the "hostClasses" property.
      */
-    styles: ({ hostClasses }) => css `
+    styles: ({hostClasses}) => css`
         ${hostClasses['my-with-host-class-definition-automatic'].selector} {
             color: blue;
         }
@@ -34,8 +35,8 @@ export const MyWithHostClassDefinition = defineElement()({
             color: red;
         }
     `,
-    render({ state }) {
-        return html `
+    render({state}) {
+        return html`
             ${state.myProp}
         `;
     },

package/{dist/readme-examples/my-with-host-class-usage.element.js → src/readme-examples/my-with-host-class-usage.element.ts}

@@ -1,10 +1,11 @@
-import { defineElement } from 'element-vir';
-import { html } from '../index.js';
-import { MyWithHostClassDefinition } from './my-with-host-class-definition.element.js';
+import {defineElement} from 'element-vir';
+import {html} from '../index.js';
+import {MyWithHostClassDefinition} from './my-with-host-class-definition.element.js';
+
 export const MyWithHostClassUsage = defineElement()({
     tagName: 'my-with-host-class-usage',
     render() {
-        return html `
+        return html`
             <${MyWithHostClassDefinition}
                 class=${MyWithHostClassDefinition.hostClasses['my-with-host-class-definition-a']}
             ></${MyWithHostClassDefinition}>

package/src/readme-examples/my-with-inputs.element.ts

@@ -0,0 +1,13 @@
+import {defineElement, html} from '../index.js';
+
+export const MyWithInputs = defineElement<{
+    username: string;
+    email: string;
+}>()({
+    tagName: 'my-with-inputs',
+    render({inputs}) {
+        return html`
+            <span>Hello there ${inputs.username}!</span>
+        `;
+    },
+});

package/{dist/readme-examples/my-with-on-dom-created.element.js → src/readme-examples/my-with-on-dom-created.element.ts}

@@ -1,14 +1,15 @@
-import { defineElement } from 'element-vir';
-import { html, onDomCreated } from '../index.js';
+import {defineElement} from 'element-vir';
+import {html, onDomCreated} from '../index.js';
+
 export const MyWithOnDomCreated = defineElement()({
     tagName: 'my-with-on-dom-created',
     render() {
-        return html `
+        return html`
             <span
                 ${onDomCreated((element) => {
-            // logs a span element
-            console.info(element);
-        })}
+                    // logs a span element
+                    console.info(element);
+                })}
             >
                 Hello there!
             </span>

package/src/readme-examples/my-with-on-resize.element.ts

@@ -0,0 +1,19 @@
+import {defineElement} from 'element-vir';
+import {html, onResize} from '../index.js';
+
+export const MyWithOnResize = defineElement()({
+    tagName: 'my-with-on-resize',
+    render() {
+        return html`
+            <span
+                ${onResize((entry) => {
+                    // this will track resizing of this span
+                    // the entry parameter contains target and contentRect properties
+                    console.info(entry);
+                })}
+            >
+                Hello there!
+            </span>
+        `;
+    },
+});

package/src/readme-examples/my-with-render-if.element.ts

@@ -0,0 +1,15 @@
+import {defineElement, html, renderIf} from '../index.js';
+
+export const MyWithRenderIf = defineElement<{shouldRender: boolean}>()({
+    tagName: 'my-with-render-if',
+    render({inputs}) {
+        return html`
+            ${renderIf(
+                inputs.shouldRender,
+                html`
+                    I'm conditionally rendered!
+                `,
+            )}
+        `;
+    },
+});

package/{dist/readme-examples/my-with-styles-and-interpolated-selector.element.js → src/readme-examples/my-with-styles-and-interpolated-selector.element.ts}

@@ -1,15 +1,16 @@
-import { defineElement } from 'element-vir';
-import { css, html } from '../index.js';
-import { MySimple } from './my-simple.element.js';
+import {defineElement} from 'element-vir';
+import {css, html} from '../index.js';
+import {MySimple} from './my-simple.element.js';
+
 export const MyWithStylesAndInterpolatedSelector = defineElement()({
     tagName: 'my-with-styles-and-interpolated-selector',
-    styles: css `
+    styles: css`
         ${MySimple} {
             background-color: blue;
         }
     `,
     render() {
-        return html `
+        return html`
             <${MySimple}></${MySimple}>
         `;
     },

package/{dist/readme-examples/my-with-styles.element.js → src/readme-examples/my-with-styles.element.ts}

@@ -1,8 +1,9 @@
-import { defineElement } from 'element-vir';
-import { css, html } from '../index.js';
+import {defineElement} from 'element-vir';
+import {css, html} from '../index.js';
+
 export const MyWithStyles = defineElement()({
     tagName: 'my-with-styles',
-    styles: css `
+    styles: css`
         :host {
             display: flex;
             flex-direction: column;
@@ -14,7 +15,7 @@ export const MyWithStyles = defineElement()({
         }
     `,
     render() {
-        return html `
+        return html`
             <span>Hello there!</span>
             <span>How are you doing?</span>
         `;

package/{dist/readme-examples/my-with-update-state.element.js → src/readme-examples/my-with-update-state.element.ts}

@@ -1,5 +1,6 @@
-import { defineElement } from 'element-vir';
-import { html, listen } from '../index.js';
+import {defineElement} from 'element-vir';
+import {html, listen} from '../index.js';
+
 export const MyWithUpdateState = defineElement()({
     tagName: 'my-with-update-state',
     state() {
@@ -9,15 +10,15 @@ export const MyWithUpdateState = defineElement()({
              * Use "as" to create state properties that can be types other than the initial value's
              * type. This is particularly useful when, as below, the initial value is undefined.
              */
-            email: undefined,
+            email: undefined as string | undefined,
         };
     },
-    render({ state, updateState }) {
-        return html `
+    render({state, updateState}) {
+        return html`
             <span
                 ${listen('click', () => {
-            updateState({ username: 'new name!' });
-        })}
+                    updateState({username: 'new name!'});
+                })}
             >
                 Hello there ${state.username}!
             </span>

package/src/readme-examples/require-declarative-element.ts

@@ -0,0 +1,3 @@
+import {requireAllCustomElementsToBeDeclarativeElements} from '../index.js';
+
+requireAllCustomElementsToBeDeclarativeElements();

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

@@ -5,6 +5,7 @@
  * @category Internal
  */
 export let declarativeElementRequired = false;
+
 /**
  * Calling this requires all custom element children to be declarative elements defined by
  * element-vir.

package/{dist/template-transforms/minimal-element-definition.d.ts → src/template-transforms/minimal-element-definition.ts}

@@ -1,5 +1,7 @@
-import { type DeclarativeElementDefinitionOptions } from '../declarative-element/definition-options.js';
-import { type PropertyInitMapBase } from '../declarative-element/properties/element-properties.js';
+import {check} from '@augment-vir/assert';
+import {type DeclarativeElementDefinitionOptions} from '../declarative-element/definition-options.js';
+import {type PropertyInitMapBase} from '../declarative-element/properties/element-properties.js';
+
 /**
  * A minimal element definition used for interpolating element definitions into HTML templates with
  * a more generic type (to prevent insane circular dependencies).
@@ -10,10 +12,9 @@ export type MinimalElementDefinition<TagName extends string = string> = {
     tagName: TagName;
     elementOptions?: DeclarativeElementDefinitionOptions | undefined;
     /** This is used when wrapping interpolated raw tag name strings. */
-    tagInterpolationKey?: {
-        tagName: string;
-    } | undefined;
+    tagInterpolationKey?: {tagName: string} | undefined;
 };
+
 /**
  * A parent definition of {@link MinimalElementDefinition} with inputs also specified with allows the
  * `.assign()` method to be used inside of HTML templates.
@@ -30,16 +31,27 @@ export type MinimalDefinitionWithInputs<TagName extends string = string> = {
     definition: MinimalElementDefinition<TagName>;
     inputs: PropertyInitMapBase;
 };
+
 /**
  * Checks if the input is an instance of {@link MinimalDefinitionWithInputs}.
  *
  * @category Internal
  */
-export declare function isMinimalDefinitionWithInputs(value: unknown): value is MinimalDefinitionWithInputs;
+export function isMinimalDefinitionWithInputs(
+    value: unknown,
+): value is MinimalDefinitionWithInputs {
+    return (
+        check.hasKey(value, '_elementVirIsMinimalDefinitionWithInputs') &&
+        !!value._elementVirIsMinimalDefinitionWithInputs
+    );
+}
+
 /**
  * Checks if the input is an object that has a `tagName` property. Used inside of the HTML tagged
  * template functions for checking if interpolated values should be treated as element tags.
  *
  * @category Internal
  */
-export declare function hasTagName(value: unknown): value is MinimalElementDefinition;
+export function hasTagName(value: unknown): value is MinimalElementDefinition {
+    return check.hasKey(value, 'tagName') && !!value.tagName && typeof value.tagName === 'string';
+}

package/src/template-transforms/nested-mapped-templates.ts

@@ -0,0 +1,157 @@
+import {check} from '@augment-vir/assert';
+import {filterMap} from '@augment-vir/common';
+import {hasTagName, isMinimalDefinitionWithInputs} from './minimal-element-definition.js';
+import {type TemplateTransform} from './template-transform-type.js';
+
+type WeakMapElementKey = {
+    tagName: string;
+};
+
+type TemplateAndNested = {
+    template: TemplateTransform | undefined;
+    nested: NestedTemplatesWeakMap | undefined;
+};
+type NestedTemplatesWeakMap = WeakMap<WeakMapElementKey, TemplateAndNested>;
+type TemplatesWeakMap = WeakMap<TemplateStringsArray, TemplateAndNested>;
+
+function extractElementKeys(values: unknown[]): WeakMapElementKey[] {
+    return filterMap(
+        values,
+        (value): WeakMapElementKey | undefined => {
+            if (isMinimalDefinitionWithInputs(value)) {
+                return value.definition;
+            }
+            if (hasTagName(value)) {
+                return value.tagInterpolationKey || value;
+            }
+
+            return undefined;
+        },
+        check.isTruthy,
+    );
+}
+
+/**
+ * The transformed templates are written to a map so that we can preserve reference equality between
+ * calls. Without maintaining reference equality between html`` calls, lit-element reconstructs all
+ * of its children on every render.
+ *
+ * This is a WeakMap because we only care about the transformed array value as long as the original
+ * template array key exists.
+ */
+const transformedTemplateStrings: TemplatesWeakMap = new WeakMap();
+
+export function getAlreadyMappedTemplate<PossibleValues>(
+    templateStringsKey: TemplateStringsArray,
+    values: PossibleValues[],
+) {
+    const elementKeys = extractElementKeys(values);
+    const nestedValue = getNestedValues(transformedTemplateStrings, [
+        templateStringsKey,
+        ...elementKeys,
+    ]);
+    return nestedValue.value?.template;
+}
+
+export function setMappedTemplate<PossibleValues>(
+    templateStringsKey: TemplateStringsArray,
+    values: PossibleValues[],
+    valueToSet: TemplateTransform,
+) {
+    const elementKeys = extractElementKeys(values);
+    return setNestedValues(
+        transformedTemplateStrings,
+        [
+            templateStringsKey,
+            ...elementKeys,
+        ],
+        valueToSet,
+    );
+}
+
+function getNestedValues(
+    map: TemplatesWeakMap | NestedTemplatesWeakMap,
+    keys: (TemplateStringsArray | WeakMapElementKey)[],
+    index = 0,
+): {value: undefined | TemplateAndNested; reason: string} {
+    const {currentTemplateAndNested, reason} = getCurrentKeyAndValue(map, keys, index);
+    if (!currentTemplateAndNested) {
+        return {value: currentTemplateAndNested, reason};
+    }
+
+    if (index === keys.length - 1) {
+        return {value: currentTemplateAndNested, reason: `reached end of keys array`};
+    }
+
+    if (!currentTemplateAndNested.nested) {
+        return {value: undefined, reason: `map at key index ${index} did not have nested maps`};
+    }
+
+    return getNestedValues(currentTemplateAndNested.nested, keys, index + 1);
+}
+
+function getCurrentKeyAndValue(
+    map: TemplatesWeakMap | NestedTemplatesWeakMap,
+    keys: (TemplateStringsArray | WeakMapElementKey)[],
+    index: number,
+): {
+    currentKey: TemplateStringsArray | WeakMapElementKey | undefined;
+    currentTemplateAndNested: TemplateAndNested | undefined;
+    reason: string;
+} {
+    const currentKey = keys[index];
+    if (currentKey == undefined) {
+        return {
+            currentKey: undefined,
+            currentTemplateAndNested: undefined,
+            reason: `key at index ${index} not found`,
+        };
+    }
+    if (!map.has(currentKey as any)) {
+        return {
+            currentKey,
+            currentTemplateAndNested: undefined,
+            reason: `key at index ${index} was not in the map`,
+        };
+    }
+    const currentTemplateAndNested = map.get(currentKey as any);
+    if (currentTemplateAndNested == undefined) {
+        return {
+            currentKey,
+            currentTemplateAndNested: undefined,
+            reason: `value at key at index ${index} was undefined`,
+        };
+    }
+
+    return {currentKey, currentTemplateAndNested, reason: `key and value exists`};
+}
+
+function setNestedValues(
+    map: TemplatesWeakMap | NestedTemplatesWeakMap,
+    keys: (TemplateStringsArray | WeakMapElementKey)[],
+    valueToSet: TemplateTransform,
+    index = 0,
+): {result: boolean; reason: string} {
+    const {currentTemplateAndNested, currentKey, reason} = getCurrentKeyAndValue(map, keys, index);
+    if (!currentKey) {
+        return {result: false, reason};
+    }
+
+    const nestedAndTemplate = currentTemplateAndNested ?? {nested: undefined, template: undefined};
+    if (!currentTemplateAndNested) {
+        map.set(currentKey as any, nestedAndTemplate);
+    }
+
+    if (index === keys.length - 1) {
+        nestedAndTemplate.template = valueToSet;
+        return {result: true, reason: `set value at end of keys array`};
+    }
+
+    const nestedWeakMap = nestedAndTemplate.nested ?? new WeakMap();
+
+    if (!nestedAndTemplate.nested) {
+        nestedAndTemplate.nested = nestedWeakMap;
+    }
+
+    return setNestedValues(nestedWeakMap, keys, valueToSet, index + 1);
+}

package/{dist/template-transforms/template-transform-type.d.ts → src/template-transforms/template-transform-type.ts}

@@ -1,8 +1,10 @@
-import { type ArrayInsertion } from '../util/array.js';
+import {type ArrayInsertion} from '../util/array.js';
+
 export type AllValueTransforms = {
     valueIndexDeletions: number[];
     valueInsertions: ArrayInsertion<unknown>[];
 };
+
 export type TemplateTransform = {
     templateStrings: TemplateStringsArray;
     valuesTransform(values: unknown[]): AllValueTransforms;

package/{dist/template-transforms/transform-template.js → src/template-transforms/transform-template.ts}

@@ -1,36 +1,78 @@
-import { insertAndRemoveValues } from '../util/array.js';
-import { getAlreadyMappedTemplate, setMappedTemplate } from './nested-mapped-templates.js';
-export function getTransformedTemplate(templateStringsKey, values, fallbackTransform) {
+import {type ArrayInsertion, insertAndRemoveValues} from '../util/array.js';
+import {getAlreadyMappedTemplate, setMappedTemplate} from './nested-mapped-templates.js';
+import {type AllValueTransforms, type TemplateTransform} from './template-transform-type.js';
+
+export type ValueInsertion = {
+    index: number;
+    value: unknown;
+};
+
+export type ValueTransformCallback = (
+    lastNewString: string,
+    currentLitString: string,
+    currentValue: unknown,
+) =>
+    | {
+          replacement: unknown;
+          getExtraValues: ((currentValue: unknown) => unknown[]) | undefined;
+      }
+    | undefined;
+
+export function getTransformedTemplate<PossibleValues>(
+    templateStringsKey: TemplateStringsArray,
+    values: PossibleValues[],
+    fallbackTransform: () => TemplateTransform,
+) {
     const alreadyTransformedTemplateStrings = getAlreadyMappedTemplate(templateStringsKey, values);
-    const templateTransform = alreadyTransformedTemplateStrings ?? fallbackTransform();
+
+    const templateTransform: TemplateTransform =
+        alreadyTransformedTemplateStrings ?? fallbackTransform();
+
     if (!alreadyTransformedTemplateStrings) {
         const result = setMappedTemplate(templateStringsKey, values, templateTransform);
         if (!result.result) {
             throw new Error(`Failed to set template transform: ${result.reason}`);
         }
     }
+
     const valueTransforms = templateTransform.valuesTransform(values);
-    const transformedValuesArray = insertAndRemoveValues(values, valueTransforms.valueInsertions, valueTransforms.valueIndexDeletions);
+
+    const transformedValuesArray: PossibleValues[] = insertAndRemoveValues(
+        values,
+        valueTransforms.valueInsertions,
+        valueTransforms.valueIndexDeletions,
+    ) as PossibleValues[];
+
     return {
         strings: templateTransform.templateStrings,
         values: transformedValuesArray,
     };
 }
-export function transformTemplate(inputTemplateStrings, inputValues, transformValue, assertValidString) {
-    const newStrings = [];
-    const newRaws = [];
-    const valueIndexDeletions = [];
-    const valueTransforms = [];
+
+export function transformTemplate<PossibleValues>(
+    inputTemplateStrings: TemplateStringsArray,
+    inputValues: PossibleValues[],
+    transformValue: ValueTransformCallback,
+    assertValidString?: (templateStringPart: string) => void,
+): TemplateTransform {
+    const newStrings: string[] = [];
+    const newRaws: string[] = [];
+    const valueIndexDeletions: AllValueTransforms['valueIndexDeletions'] = [];
+    const valueTransforms: ((values: unknown[]) => ArrayInsertion<unknown>)[] = [];
+
     inputTemplateStrings.forEach((currentTemplateString, currentTemplateStringIndex) => {
         const lastNewStringsIndex = newStrings.length - 1;
         const lastNewString = newStrings[lastNewStringsIndex];
         const currentValueIndex = currentTemplateStringIndex - 1;
         const currentValue = inputValues[currentValueIndex];
+
         if (assertValidString) {
             assertValidString(currentTemplateString);
         }
-        let transformOutput = undefined;
-        let extraValues = [];
+
+        let transformOutput: ReturnType<ValueTransformCallback> | undefined = undefined;
+        let extraValues: unknown[] = [];
+
         if (typeof lastNewString === 'string') {
             transformOutput = transformValue(lastNewString, currentTemplateString, currentValue);
             if (transformOutput) {
@@ -41,6 +83,7 @@ export function transformTemplate(inputTemplateStrings, inputValues, transformVa
                 valueIndexDeletions.push(currentValueIndex);
                 const getExtraValuesCallback = transformOutput.getExtraValues;
                 extraValues = getExtraValuesCallback ? getExtraValuesCallback(currentValue) : [];
+
                 if (extraValues.length && getExtraValuesCallback) {
                     newStrings[lastNewStringsIndex] += ' ';
                     extraValues.forEach((value, index) => {
@@ -49,7 +92,7 @@ export function transformTemplate(inputTemplateStrings, inputValues, transformVa
                             newStrings.push(' ');
                         }
                     });
-                    valueTransforms.push((values) => {
+                    valueTransforms.push((values): ArrayInsertion<unknown> => {
                         const latestCurrentValue = values[currentValueIndex];
                         const insertions = getExtraValuesCallback(latestCurrentValue);
                         return {
@@ -58,21 +101,22 @@ export function transformTemplate(inputTemplateStrings, inputValues, transformVa
                         };
                     });
                     newStrings.push(currentTemplateString);
-                }
-                else {
+                } else {
                     newStrings[lastNewStringsIndex] += currentTemplateString;
                 }
             }
         }
+
         if (!transformOutput) {
             newStrings.push(currentTemplateString);
         }
+
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        const currentRawLitString = inputTemplateStrings.raw[currentTemplateStringIndex];
+        const currentRawLitString = inputTemplateStrings.raw[currentTemplateStringIndex]!;
         if (transformOutput) {
             newRaws[lastNewStringsIndex] = [
                 // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-                newRaws[lastNewStringsIndex],
+                newRaws[lastNewStringsIndex]!,
                 transformOutput.replacement,
                 currentRawLitString,
             ].join('');
@@ -81,18 +125,22 @@ export function transformTemplate(inputTemplateStrings, inputValues, transformVa
                     newRaws.push('');
                 });
             }
-        }
-        else {
+        } else {
             newRaws.push(currentRawLitString);
         }
     });
-    const newTemplateStrings = Object.assign([], newStrings, {
+
+    const newTemplateStrings: TemplateStringsArray = Object.assign([], newStrings, {
         raw: newRaws,
     });
+
     return {
         templateStrings: newTemplateStrings,
-        valuesTransform(values) {
-            const insertions = valueTransforms.flatMap((transformCallback) => transformCallback(values));
+        valuesTransform(values): AllValueTransforms {
+            const insertions: ArrayInsertion<unknown>[] = valueTransforms.flatMap(
+                (transformCallback) => transformCallback(values),
+            );
+
             return {
                 valueIndexDeletions,
                 valueInsertions: insertions,