element-vir 3.0.1 → 4.0.2

package/README.md

@@ -1,18 +1,19 @@
 # element-vir
 
-Heroic, reactive, functional, type safe, custom web components.
+Heroic. Reactive. Functional. Type safe. Web components without compromise.
 
 No need for an extra build step,<br>
-no need for weird file extensions,<br>
+no need for side effect imports, <br>
+no need for unique file extensions,<br>
 no need for extra static analysis tools,<br>
-no need for a dedicated funky syntax.<br>
+no need for a dedicated, unique syntax.<br>
 _**It's just TypeScript.**_
 
-Built using the power of _native_ JavaScript custom web elements, _native_ JavaScript template literals, _native_ JavaScript functions<sup>\*</sup>, _native_ HTML, and [lit-element](http://lit.dev).
+Uses the power of _native_ JavaScript custom web elements, _native_ JavaScript template literals, _native_ JavaScript functions<sup>\*</sup>, _native_ HTML, and [lit-element](http://lit.dev).
 
-This is basically a [lit-element](http://lit.dev) wrapper that adds type-safe I/O and functional-programming style component definition.
+In reality this is basically a [lit-element](http://lit.dev) wrapper that adds type-safe element tag usage and I/O with functional-programming style component definition.
 
-[Works in every major browser except Internet Explorer.](https://caniuse.com/mdn-api_window_customelements) <sub>(Heaven help you if you still need to support IE.)</sub>
+[Works in every major web browser except Internet Explorer.](https://caniuse.com/mdn-api_window_customelements)
 
 <sub>\*okay I hope it's obvious that functions are native</sub>
 
@@ -24,15 +25,17 @@ This is basically a [lit-element](http://lit.dev) wrapper that adds type-safe I/
 npm i element-vir
 ```
 
+Make sure to install this as a normal dependency (not just a dev dependency) because it needs to exist at run time.
+
 # Usage
 
 Most usage of this package is done through the [`defineFunctionalElement` function](https://github.com/electrovir/element-vir/blob/main/src/functional-element/define-functional-element.ts#L25-L30). See the [`FunctionalElementInit` type](https://github.com/electrovir/element-vir/blob/main/src/functional-element/functional-element-init.ts#L7-L20) for that function's inputs. These inputs are also described below with examples.
 
-All of [`lit`](https://lit.dev)'s syntax and functionality is also available for use.
+All of [`lit`](https://lit.dev)'s syntax and functionality is also available for use if you wish.
 
 ## Simple element definition
 
-Use `defineFunctionalElement` to define your element. This is apparent if you inspect the types but it must be given an object with at least `tagName` and `renderCallback` properties. This is a bare-minimum example custom element:
+Use `defineFunctionalElement` to define your element. Tt must be given an object with at least `tagName` and `renderCallback` properties (the types enforce this). Here is a bare-minimum example custom element:
 
 <!-- example-link: src/readme-examples/my-simple.element.ts -->
 
@@ -47,7 +50,7 @@ export const MySimpleElement = defineFunctionalElement({
 });
 ```
 
-Make sure to export your element definition as that will be used to instantiate it in your HTML templates.
+Make sure to export your element definition if you need to use it in other files.
 
 ## Using in other elements
 
@@ -70,17 +73,16 @@ export const MyAppElement = defineFunctionalElement({
 
 This requirement ensures that the element is properly imported and registered with the browser. (Compare to pure [lit](http://lit.dev) where you must remember to import each element file as a side effect, or without actually referencing any of its exports in your code.)
 
-If you wish to bypass this interpolation requirement, instead [import `html` directly from `lit`](https://lit.dev/docs/components/overview/).
+If you wish to bypass this interpolation, make sure to [import the `html` tagged template directly from `lit`](https://lit.dev/docs/components/overview/), `import {html} from 'lit';`, instead of version contained in `element-vir`.
 
 ## Adding styles
 
-Styles are added through `styles` when defining a functional element (similar to [how they are defined in `lit`](https://lit.dev/docs/components/styles/)):
+Styles are added through the `styles` property when defining a functional element (similar to [how they are defined in `lit`](https://lit.dev/docs/components/styles/)):
 
 <!-- example-link: src/readme-examples/my-simple-app-with-styles.element.ts -->
 
 ```TypeScript
-import {css} from 'lit';
-import {defineFunctionalElement, html} from 'element-vir';
+import {css, defineFunctionalElement, html} from 'element-vir';
 
 export const MySimpleWithStylesElement = defineFunctionalElement({
     tagName: 'my-simple-with-styles-element',
@@ -102,9 +104,32 @@ export const MySimpleWithStylesElement = defineFunctionalElement({
 });
 ```
 
+### Element definition as style selector
+
+Functional element definitions can be used in the `css` tagged template just like in the `html` tagged template. This will be replaced by the element's tag name:
+
+<!-- example-link: src/readme-examples/my-simple-app-with-styles-and-interpolated-selector.element.ts -->
+
+```TypeScript
+import {css, defineFunctionalElement, html} from 'element-vir';
+import {MySimpleElement} from './my-simple.element';
+
+export const MySimpleWithStylesAndInterpolatedSelectorElement = defineFunctionalElement({
+    tagName: 'my-simple-with-styles-and-interpolated-selector-element',
+    styles: css`
+        ${MySimpleElement} {
+            background-color: blue;
+        }
+    `,
+    renderCallback: () => html`
+        <${MySimpleElement}></${MySimpleElement}>
+    `,
+});
+```
+
 ## Defining and using properties (inputs)
 
-Define properties with `props` when defining a functional element. Each property must be given a default value. If you wish to leave the property's default value as `undefined`, give it a type as well (shown below with `as string | undefined`) so you can assign a defined value of that type to it later.
+Define element properties with `props` when making a functional element. Each property must be given a default value. If you wish to leave the property's default value as `undefined`, give it a type as well (shown below with `as string | undefined`) so you can assign a defined value of that type to it later.
 
 To use a custom element's properties, grab `props` from `renderCallback`'s parameters and interpolate it into your HTML template:
 
@@ -148,43 +173,37 @@ export const MyAppWithPropsElement = defineFunctionalElement({
 });
 ```
 
-## Defining and dispatching custom events (outputs)
+## Element events (outputs)
 
-Define events with `events` when defining a functional element. Each event must be initialized with `eventInit` and a type parameter. `eventInit` accepts no inputs as it doesn't make sense for events to have a default value.
+Define events with `events` when making a functional element. Each event must be initialized with `defineElementEvent` and a type parameter. `defineElementEvent` accepts no inputs as it doesn't make sense for events to have default values.
 
-To dispatch an event, grab `dispatchElementEvent` from `renderCallback`'s parameters.
+To dispatch an event, grab `dispatch` from `renderCallback`'s parameters.
 
 <!-- example-link: src/readme-examples/my-simple-with-events.element.ts -->
 
 ```TypeScript
-import {defineFunctionalElement, ElementEvent, eventInit, html} from 'element-vir';
+import {defineElementEvent, defineFunctionalElement, html, listen} from 'element-vir';
 
 export const MySimpleWithEventsElement = defineFunctionalElement({
     tagName: 'my-simple-element-with-events',
     events: {
-        logoutClick: eventInit<void>(),
-        randomNumber: eventInit<number>(),
+        logoutClick: defineElementEvent<void>(),
+        randomNumber: defineElementEvent<number>(),
     },
-    renderCallback: ({dispatchElementEvent, events}) => html`
-        <!-- normal DOM events must be listened to with the "@" keyword from lit. -->
-        <button
-            @click=${() => dispatchElementEvent(new ElementEvent(events.logoutClick, undefined))}
-        >
+    renderCallback: ({dispatch, events}) => html`
+        <button ${listen('click', () => dispatch(new events.logoutClick(undefined)))}>
             log out
         </button>
-        <button
-            @click=${() =>
-                dispatchElementEvent(new ElementEvent(events.randomNumber, Math.random()))}
-        >
+        <button ${listen('click', () => dispatch(new events.randomNumber(Math.random())))}>
             generate random number
         </button>
     `,
 });
 ```
 
-## Listening to custom events (outputs)
+## Listening to typed events (outputs)
 
-Use the `listen` directive to listen to custom events emitted by your custom functional elements:
+Use the `listen` directive to listen to typed events emitted by your custom functional elements:
 
 <!-- example-link: src/readme-examples/my-app-with-events.element.ts -->
 
@@ -213,21 +232,25 @@ export const MyAppWithEventsElement = defineFunctionalElement({
 });
 ```
 
-## Custom events without an element
+`listen` can also be used to listen to native DOM events (like `click`) and the proper event type will be provided for the listener callback.
+
+## Typed events without an element
 
-Create a custom event type with `defineCustomEvent`. Make sure to include the type generics (like this: `defineCustomEvent<'customEventName', string>`) to ensure type safety when using your event.
+Create a custom event type with `defineTypedEvent`. Make sure to include the type generic (like this: `defineTypedEvent<number>`) and call it twice, the second time with the event type string, (like this: `defineTypedEvent<number>()('my-event-type-name')`) to ensure type safety when using your event. Note that event type names should probably be unique, or they may clash with each other.
 
-Creating a custom event:
+### Creating a typed event
 
 <!-- example-link: src/readme-examples/custom-event-no-element.ts -->
 
 ```TypeScript
-import {defineCustomEvent} from 'element-vir';
+import {defineTypedEvent} from 'element-vir';
 
-export const MyCustomEvent = defineCustomEvent<'myCustomEventName', number>('myCustomEventName');
+export const MyCustomEvent = defineTypedEvent<number>()('myCustomEventName');
 ```
 
-Using a custom event (both dispatching and listening):
+### Using a typed event
+
+Both dispatching a custom event and listening to a custom event:
 
 <!-- example-link: src/readme-examples/custom-event-usage.element.ts -->
 
@@ -237,16 +260,16 @@ import {MyCustomEvent} from './custom-event-no-element';
 
 export const MyElementWithCustomEvents = defineFunctionalElement({
     tagName: 'my-app-with-custom-events',
-    renderCallback: ({dispatchEvent: defaultDispatchEvent}) => html`
+    renderCallback: ({genericDispatch}) => html`
         <div
             ${listen(MyCustomEvent, (event) => {
                 console.log(`Got a number! ${event.detail}`);
             })}
         >
             <div
-                @click=${() => {
-                    defaultDispatchEvent(new MyCustomEvent(Math.random()));
-                }}
+                ${listen('click', () => {
+                    genericDispatch(new MyCustomEvent(Math.random()));
+                })}
             ></div>
         </div>
     `,
@@ -255,13 +278,13 @@ export const MyElementWithCustomEvents = defineFunctionalElement({
 
 ## Directives
 
-Some custom [`lit` directives](https://lit.dev/docs/templates/custom-directives/) are also contained within this package.
+The following custom [`lit` directives](https://lit.dev/docs/templates/custom-directives/) are contained within this package.
 
 ### onDomCreated
 
 This directive should be used instead of trying to use `querySelector` directly on the custom element.
 
-This triggers only once when the element it's contained within is created in the DOM. If it's containing element changes, the callback will be triggered again.
+This triggers only once when the element it's attached has actually been created in the DOM. If it's attached element changes, the callback will be triggered again.
 
 <!-- example-link: src/readme-examples/my-simple-with-on-dom-created.element.ts -->
 
@@ -285,7 +308,7 @@ export const MySimpleWithOnDomCreatedElement = defineFunctionalElement({
 
 ### onResize
 
-This directive fulfills a common use case of triggering callbacks when something resizes. Instead of just tracking the _globally_ resizing window though, this allows you to track resizes of an individual element. The callback here is given a portion of the [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) (since not all properties are supported well in browsers).
+This directive fulfills a common use case of triggering callbacks when something resizes. Instead of just tracking the _globally_ resizing window though, this allows you to track resizes of an individual element. The callback here is passed an object with a portion of the [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) properties (since not all properties are supported well in browsers).
 
 <!-- example-link: src/readme-examples/my-simple-with-on-resize.element.ts -->
 
@@ -316,33 +339,14 @@ Assign a value to one of a custom element's properties. This is explained in the
 
 Listen to a specific event emitted from a custom element. This is explained in the **Listening to custom events (outputs)** section earlier in this README.
 
-### namedListen
-
-Listen to an event by name directly. This can be used to listen to native events as well as custom events. However, `listen` (explained above) is better for custom events as it'll give you better type information. When using `namedListen` for native DOM events (like `'click'`) the callback will be typed correctly. When listening to custom events, however, it can't guess the callback type from anywhere so the event parameter type will be unknown.
-
-<!-- example-link: src/readme-examples/my-simple-with-named-listen.element.ts -->
-
-```TypeScript
-import {defineFunctionalElement, html, namedListen} from 'element-vir';
-
-export const MySimpleWithNamedListenElement = defineFunctionalElement({
-    tagName: 'my-simple-element-with-named-listen',
-    renderCallback: () => html`
-        <!-- normal DOM events can be listened to  -->
-        <button ${namedListen('click', (event) => console.log(event.buttons))}>click me</button>
-    `,
-});
-```
-
 ### assignWithCleanup
 
-This directive is the same as the `assign` directive but it accepts an additional `cleanupCallback` input. Use this directive to assign values which need some kind of cleanup if they're overwritten. For example, a 3D rendering engine which uses the canvas that should free up memory when it's swapped out.
+This directive is the same as the `assign` directive but it accepts an additional `cleanupCallback` input. Use this directive to assign values which need some kind of cleanup when they're overwritten. For example, a 3D rendering engine which uses the canvas that should free up memory when it's swapped out.
 
 <!-- example-link: src/readme-examples/my-app-with-cleanup.element.ts -->
 
 ```TypeScript
-import {assign, defineFunctionalElement, html} from 'element-vir';
-import {assignWithCleanup} from '../functional-element/directives/assign-with-clean-up.directive';
+import {assign, assignWithCleanup, defineFunctionalElement, html} from 'element-vir';
 import {MySimpleWithPropsElement} from './my-simple-with-props.element';
 
 export const MyAppWithPropsElement = defineFunctionalElement({
@@ -373,7 +377,13 @@ To require all child elements to be functional elements defined by this package,
 <!-- example-link: src/readme-examples/require-functional-element.ts -->
 
 ```TypeScript
-import {requireAllCustomElementsToBeFunctionalElement} from '../require-functional-element';
+import {requireAllCustomElementsToBeFunctionalElement} from 'element-vir';
 
 requireAllCustomElementsToBeFunctionalElement();
 ```
+
+# Dev
+
+## markdown out of date
+
+If you see this: `Code in Markdown file(s) is out of date. Run without --check to update. code-in-markdown failed.`, run `npm run update-docs` to fix it.

package/dist/augments/type.d.ts

@@ -0,0 +1 @@
+export declare type NonEmptyString<T> = T extends '' ? never : T;

package/dist/augments/type.js

@@ -0,0 +1 @@
+export {};

package/dist/functional-element/define-functional-element.js

@@ -5,33 +5,30 @@ import { createPropertyDescriptorMap, createPropertyProxy, } from './element-pro
 import { FunctionalElementBaseClass, } from './functional-element';
 import { createRenderParams } from './render-callback';
 export function defineFunctionalElement(functionalElementInit) {
-    var _a;
     const eventsMap = createEventDescriptorMap(functionalElementInit.events);
-    const anonymousClass = (_a = class extends FunctionalElementBaseClass {
-            constructor() {
-                super();
-                this.instanceProps = createPropertyProxy(functionalElementInit.props, this);
-                const initProps = functionalElementInit.props || {};
-                Object.keys(initProps).forEach((propName) => {
-                    const functionalElementInstance = this;
-                    property()(functionalElementInstance, propName);
-                    functionalElementInstance[propName] = initProps[propName];
-                });
-            }
-            createRenderParams() {
-                return createRenderParams(this, eventsMap);
-            }
-            render() {
-                return functionalElementInit.renderCallback(this.createRenderParams());
-            }
-        },
-        _a.tagName = functionalElementInit.tagName,
-        _a.styles = functionalElementInit.styles || css ``,
-        _a.propNames = Object.keys(functionalElementInit.props || {}),
-        _a.events = eventsMap,
-        _a.renderCallback = functionalElementInit.renderCallback,
-        _a.props = createPropertyDescriptorMap(functionalElementInit.props),
-        _a);
+    const anonymousClass = class extends FunctionalElementBaseClass {
+        static tagName = functionalElementInit.tagName;
+        static styles = functionalElementInit.styles || css ``;
+        createRenderParams() {
+            return createRenderParams(this, eventsMap);
+        }
+        static events = eventsMap;
+        static renderCallback = functionalElementInit.renderCallback;
+        static props = createPropertyDescriptorMap(functionalElementInit.props);
+        render() {
+            return functionalElementInit.renderCallback(this.createRenderParams());
+        }
+        instanceProps = createPropertyProxy(functionalElementInit.props, this);
+        constructor() {
+            super();
+            const initProps = functionalElementInit.props || {};
+            Object.keys(initProps).forEach((propName) => {
+                const functionalElementInstance = this;
+                property()(functionalElementInstance, propName);
+                functionalElementInstance[propName] = initProps[propName];
+            });
+        }
+    };
     window.customElements.define(functionalElementInit.tagName, anonymousClass);
     return anonymousClass;
 }

package/dist/functional-element/directives/assign-with-clean-up.directive.js

@@ -10,6 +10,9 @@ export function assignWithCleanup(propertyDescriptor, value, cleanupCallback) {
     return assignWithCleanupDirective(propertyDescriptor.propName, value, cleanupCallback);
 }
 class AssignWithCleanupDirectiveClass extends AsyncDirective {
+    element;
+    lastValue;
+    lastCallback;
     constructor(partInfo) {
         super(partInfo);
         this.element = extractFunctionalElement(partInfo, 'assign');

package/dist/functional-element/directives/assign.directive.js

@@ -9,6 +9,7 @@ export function assign(propertyDescriptor, value) {
     return assignDirective(propertyDescriptor.propName, value);
 }
 const assignDirective = directive(class extends Directive {
+    element;
     constructor(partInfo) {
         super(partInfo);
         this.element = extractFunctionalElement(partInfo, 'assign');

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

@@ -1,28 +1,13 @@
-import { PartInfo } from 'lit/directive.js';
-import { ElementEvent, EventDescriptor } from '../element-events';
+import { DirectiveResult } from 'lit/directive.js';
+import { DefinedTypedEvent, TypedEvent } from '../../typed-event/typed-event';
 /**
- * Listen to element events.
+ * 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 defineTypedEvent).
  *
- * @param eventDescriptor Needs to come either from a functional element (like
- *   MyFunctionalElement.events.eventName) or from a custom element event created via the
- *   createCustomEvent function.
- * @param listener The callback to fire when an event is caught. Assuming the eventDescriptor input
- *   is properly typed, the event given to this callback will also be typed.
+ * @param definedTypedEvent Needs to come either from a functional element (like
+ *   MyFunctionalElement.events.eventName) or from a typed event created via the defineTypedEvent function.
+ * @param listener The callback to fire when an event is caught. Assuming the definedTypedEvent
+ *   input is properly typed, the event given to this callback will also be typed.
  */
-export declare function listen<EventName extends string, DetailType>(eventDescriptor: EventDescriptor<EventName, DetailType>, listener: (event: ElementEvent<EventName, DetailType>) => void): import("lit-html/directive").DirectiveResult<{
-    new (partInfo: PartInfo): {
-        readonly element: HTMLElement;
-        lastListenerMetaData: ListenerMetaData<unknown> | undefined;
-        resetListener(listenerMetaData: ListenerMetaData<any>): void;
-        createListenerMetaData(eventType: string, callback: (event: ElementEvent<string, unknown>) => void): ListenerMetaData<unknown>;
-        render(eventObject: EventDescriptor<string, any>, callback: (event: ElementEvent<any, any>) => void): symbol;
-        readonly _$isConnected: boolean;
-        update(_part: import("lit-html").Part, props: unknown[]): unknown;
-    };
-}>;
-declare type ListenerMetaData<EventDetail> = {
-    eventType: string;
-    callback: (event: ElementEvent<string, EventDetail>) => void;
-    listener: (event: any) => void;
-};
-export {};
+export declare function listen<TypedEventTypeNameGeneric extends string, TypedEventDetailGeneric, NativeElementEventNameGeneric extends keyof HTMLElementEventMap>(eventType: DefinedTypedEvent<TypedEventTypeNameGeneric, TypedEventDetailGeneric>, listener: (event: TypedEvent<TypedEventTypeNameGeneric, TypedEventDetailGeneric>) => void): DirectiveResult<any>;
+export declare function listen<TypedEventTypeNameGeneric extends string, TypedEventDetailGeneric, NativeElementEventNameGeneric extends keyof HTMLElementEventMap>(eventType: NativeElementEventNameGeneric, listener: (event: HTMLElementEventMap[NativeElementEventNameGeneric]) => void): DirectiveResult<any>;

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

@@ -1,23 +1,16 @@
 import { noChange } from 'lit';
 import { directive, Directive } from 'lit/directive.js';
 import { extractElement } from './directive-util';
-/**
- * Listen to element events.
- *
- * @param eventDescriptor Needs to come either from a functional element (like
- *   MyFunctionalElement.events.eventName) or from a custom element event created via the
- *   createCustomEvent function.
- * @param listener The callback to fire when an event is caught. Assuming the eventDescriptor input
- *   is properly typed, the event given to this callback will also be typed.
- */
-export function listen(eventDescriptor, listener) {
-    return listenDirective(eventDescriptor, listener);
+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', HTMLElement);
@@ -33,11 +26,11 @@ const listenDirective = directive(class extends Directive {
         return {
             eventType,
             callback,
-            listener: (event) => { var _a; return (_a = this.lastListenerMetaData) === null || _a === void 0 ? void 0 : _a.callback(event); },
+            listener: (event) => this.lastListenerMetaData?.callback(event),
         };
     }
-    render(eventObject, callback) {
-        const eventType = eventObject.eventName;
+    render(eventTypeInput, callback) {
+        const eventType = typeof eventTypeInput === 'string' ? eventTypeInput : eventTypeInput.type;
         if (typeof eventType !== 'string') {
             throw new Error(`Cannot listen to an event with a name that is not a string. Given event name: "${eventType}"`);
         }

package/dist/functional-element/directives/on-dom-created.directive.js

@@ -3,6 +3,7 @@ import { assertsIsElementPartInfo } from './directive-util';
 const directiveName = 'onDomCreated';
 /** Only fires once, when the element has been created. */
 export const onDomCreated = directive(class extends Directive {
+    element;
     constructor(partInfo) {
         super(partInfo);
         assertsIsElementPartInfo(partInfo, directiveName);
@@ -11,8 +12,8 @@ export const onDomCreated = directive(class extends Directive {
         assertsIsElementPartInfo(partInfo, directiveName);
         const newElement = partInfo.element;
         if (newElement !== this.element) {
-            // use setTimeout here so it can fire property changes outside of a render loop
-            setTimeout(() => callback(newElement), 0);
+            // use requestAnimationFrame here so it can fire property changes outside of a render loop
+            requestAnimationFrame(() => callback(newElement));
             this.element = newElement;
         }
         return this.render(callback);

package/dist/functional-element/directives/on-resize.directive.js

@@ -2,19 +2,20 @@ import { directive, Directive } from 'lit/directive.js';
 import { assertsIsElementPartInfo } from './directive-util';
 const directiveName = 'onResize';
 export const onResize = directive(class extends Directive {
+    element;
+    resizeObserver = new ResizeObserver((entries) => this.fireCallback(entries));
+    callback;
     constructor(partInfo) {
         super(partInfo);
-        this.resizeObserver = new ResizeObserver((entries) => this.fireCallback(entries));
         assertsIsElementPartInfo(partInfo, directiveName);
     }
     fireCallback(entries) {
-        var _a;
         const resizeEntry = entries[0];
         if (!resizeEntry) {
             console.error(entries);
             throw new Error(`${directiveName} observation triggered but the first entry was empty.`);
         }
-        (_a = this.callback) === null || _a === void 0 ? void 0 : _a.call(this, { target: resizeEntry.target, contentRect: resizeEntry.contentRect });
+        this.callback?.({ target: resizeEntry.target, contentRect: resizeEntry.contentRect });
     }
     update(partInfo, [callback]) {
         assertsIsElementPartInfo(partInfo, directiveName);

package/dist/functional-element/element-events.d.ts

@@ -1,29 +1,10 @@
-export declare type EventsInitMap = Record<string, new () => ElementEvent<string, unknown>>;
-export declare type EventCreator<T> = (new () => ElementEvent<string, T>) & {
-    eventName: string;
-};
-export declare function eventInit<T>(): new () => ElementEvent<string, T>;
-export declare type EventInitInfo<EventNameGeneric extends string> = {
-    eventName: EventNameGeneric;
-};
-export declare class ElementEvent<EventName extends string, EventValue> extends CustomEvent<EventValue> {
-    readonly eventInitInfo: EventInitInfo<EventName>;
-    readonly eventName: string;
-    constructor(eventInitInfo: EventInitInfo<EventName>, initDetail: EventValue);
-}
-export declare function defineCustomEvent<EventName extends string, EventValue>(eventName: EventName): (new (eventValue: EventValue) => ElementEvent<EventName, EventValue>) & EventDescriptor<EventName, EventValue>;
-export declare type EventExtraProperties<DetailType> = {
-    /**
-     * The event constructor property is needed in order to store sufficient type data for event
-     * listeners to work.
-     */
-    eventConstructor: new (outputObject: EventDescriptor<string, DetailType>, initDetail: DetailType) => ElementEvent<string, DetailType>;
-};
-export declare type EventObjectEventDetailExtractor<EventObjectGeneric extends EventDescriptor<any, any>> = EventObjectGeneric extends EventDescriptor<string, infer R> ? R : never;
-export declare type ElementEventDetailExtractor<ElementEventGeneric extends ElementEvent<any, any>> = ElementEventGeneric extends ElementEvent<string, infer R> ? R : never;
-export declare type EventInitMapEventDetailExtractor<Property extends keyof EventsInitGeneric, EventsInitGeneric extends EventsInitMap> = InstanceType<EventsInitGeneric[Property]> extends ElementEvent<string, infer R> ? R : never;
-export declare type EventDescriptor<EventNameGeneric extends string, DetailType> = EventInitInfo<EventNameGeneric> & EventExtraProperties<DetailType>;
+import { DefinedTypedEvent, DefinedTypedEventNameDefinition, TypedEvent } from '../typed-event/typed-event';
+export declare type EventsInitMap = Record<string, DefinedTypedEventNameDefinition<any>>;
+export declare function defineElementEvent<EventDetailGeneric>(): DefinedTypedEventNameDefinition<EventDetailGeneric>;
+export declare type EventInitMapEventDetailExtractor<EventTypeNameGeneric extends keyof EventsInitGeneric, EventsInitGeneric extends EventsInitMap> = EventsInitGeneric[EventTypeNameGeneric] extends DefinedTypedEventNameDefinition<infer R> ? R : never;
 export declare type EventDescriptorMap<EventsInitGeneric extends EventsInitMap> = {
-    [Property in keyof EventsInitGeneric]: EventDescriptor<Property extends string ? Property : never, EventInitMapEventDetailExtractor<Property, EventsInitGeneric>>;
+    [CurrentEventTypeName in keyof EventsInitGeneric]: DefinedTypedEvent<CurrentEventTypeName extends string ? CurrentEventTypeName : never, EventInitMapEventDetailExtractor<CurrentEventTypeName, EventsInitGeneric>>;
 };
+export declare type EventObjectEventDetailExtractor<EventObjectGeneric extends DefinedTypedEvent<any, any>> = EventObjectGeneric extends DefinedTypedEvent<string, infer R> ? R : never;
+export declare type ElementEventDetailExtractor<ElementEventGeneric extends TypedEvent<any, any>> = ElementEventGeneric extends TypedEvent<string, infer R> ? R : never;
 export declare function createEventDescriptorMap<EventsInitGeneric extends EventsInitMap>(eventsInit: EventsInitGeneric | undefined): EventDescriptorMap<EventsInitGeneric>;

package/dist/functional-element/element-events.js

@@ -1,45 +1,24 @@
-export function eventInit() {
-    const customEventElement = class extends ElementEvent {
-    };
-    return customEventElement;
-}
-export class ElementEvent extends CustomEvent {
-    constructor(eventInitInfo, initDetail) {
-        super(String(eventInitInfo.eventName), { detail: initDetail, bubbles: true, composed: true });
-        this.eventInitInfo = eventInitInfo;
-        this.eventName = String(this.eventInitInfo.eventName);
-    }
-}
-export function defineCustomEvent(eventName) {
-    var _a;
-    return _a = class extends ElementEvent {
-            constructor(eventValue) {
-                super({ eventName: eventName }, eventValue);
-                window.ElementEvent = ElementEvent;
-            }
-        },
-        _a.eventName = eventName,
-        // this allows sub classes of ElementEvent to be directly listened to
-        _a.eventConstructor = ElementEvent.constructor,
-        _a;
+import { defineTypedEvent, } from '../typed-event/typed-event';
+export function defineElementEvent() {
+    return defineTypedEvent();
 }
 export function createEventDescriptorMap(eventsInit) {
     if (!eventsInit) {
         return {};
     }
     return Object.keys(eventsInit)
-        .filter((currentKey) => {
-        if (typeof currentKey !== 'string') {
-            throw new Error(`Expected event key of type string but got type "${typeof currentKey}" for key ${currentKey}`);
+        .filter((currentElementEventKey) => {
+        if (typeof currentElementEventKey !== 'string') {
+            throw new Error(`Expected event key of type string but got type "${typeof currentElementEventKey}" for key ${currentElementEventKey}`);
+        }
+        if (currentElementEventKey === '') {
+            throw new Error(`Got empty string for events key.`);
         }
         return true;
     })
-        .reduce((accum, currentKey) => {
-        const eventObject = {
-            eventName: currentKey,
-            eventConstructor: eventsInit[currentKey],
-        };
-        accum[currentKey] = eventObject;
+        .reduce((accum, currentElementEventKey) => {
+        const eventObject = defineTypedEvent()(currentElementEventKey);
+        accum[currentElementEventKey] = eventObject;
         return accum;
     }, {});
 }

package/dist/functional-element/functional-element.d.ts

@@ -20,7 +20,6 @@ export declare type FunctionalElementInit<PropertyInitGeneric extends PropertyIn
 export declare abstract class FunctionalElementBaseClass<PropertyInitGeneric extends PropertyInitMapBase> extends LitElement {
     static readonly tagName: string;
     static readonly styles: CSSResult;
-    static readonly propNames: string[];
     abstract render(): TemplateResult | Promise<TemplateResult>;
     abstract readonly instanceProps: PropertyInitGeneric;
 }
@@ -37,5 +36,4 @@ export declare type ExtraStaticFunctionalElementProperties<PropertyInitGeneric e
      */
     tagName: string;
     styles: CSSResult;
-    propNames: string[];
 }>;

package/dist/functional-element/functional-element.js

@@ -1,3 +1,5 @@
 import { LitElement } from 'lit';
 export class FunctionalElementBaseClass extends LitElement {
+    static tagName;
+    static styles;
 }

package/dist/functional-element/render-callback.d.ts

@@ -1,16 +1,18 @@
 import { TemplateResult } from 'lit';
-import { ElementEvent, EventDescriptorMap, EventInitMapEventDetailExtractor, EventsInitMap } from './element-events';
+import { TypedEvent } from '../typed-event/typed-event';
+import { EventDescriptorMap, EventInitMapEventDetailExtractor, EventsInitMap } from './element-events';
 import { PropertyInitMapBase } from './element-properties';
 import { FunctionalElementInstance } from './functional-element';
 export declare type RenderCallback<PropertyInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap> = (params: RenderParams<PropertyInitGeneric, EventsInitGeneric>) => TemplateResult | Promise<TemplateResult>;
 export declare type RenderParams<PropertyInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap> = {
     props: PropertyInitGeneric;
     events: EventDescriptorMap<EventsInitGeneric>;
-    dispatchElementEvent: <EventName extends keyof EventsInitGeneric>(event: ElementEvent<EventName extends string ? EventName : never, EventInitMapEventDetailExtractor<EventName, EventsInitGeneric>>) => boolean;
+    host: FunctionalElementInstance<PropertyInitGeneric>;
+    dispatch: <EventTypeNameGeneric extends keyof EventsInitGeneric>(event: TypedEvent<EventTypeNameGeneric extends string ? EventTypeNameGeneric : never, EventInitMapEventDetailExtractor<EventTypeNameGeneric, EventsInitGeneric>>) => boolean;
     /**
      * Same as dispatchElementEvent but without the extra types. This allows you to emit any events,
      * even events from other custom elements.
      */
-    dispatchEvent: (event: Event) => boolean;
+    genericDispatch: (event: Event) => boolean;
 };
 export declare function createRenderParams<PropertyInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap>(element: FunctionalElementInstance<PropertyInitGeneric>, eventsMap: EventDescriptorMap<EventsInitGeneric>): RenderParams<PropertyInitGeneric, EventsInitGeneric>;

package/dist/functional-element/render-callback.js

@@ -4,8 +4,9 @@ export function createRenderParams(element, eventsMap) {
          * These two dispatch properties do the same thing but their interfaces are different.
          * DispatchEvent's type interface is much stricter.
          */
-        dispatchElementEvent: (event) => element.dispatchEvent(event),
-        dispatchEvent: (event) => element.dispatchEvent(event),
+        dispatch: (event) => element.dispatchEvent(event),
+        genericDispatch: (event) => element.dispatchEvent(event),
+        host: element,
         props: element.instanceProps,
         events: eventsMap,
     };

package/dist/index.d.ts

@@ -2,7 +2,6 @@ export * from './functional-element/define-functional-element';
 export * from './functional-element/directives/assign-with-clean-up.directive';
 export * from './functional-element/directives/assign.directive';
 export * from './functional-element/directives/listen.directive';
-export * from './functional-element/directives/named-listen.directive';
 export * from './functional-element/directives/on-dom-created.directive';
 export * from './functional-element/directives/on-resize.directive';
 export * from './functional-element/element-events';
@@ -12,3 +11,4 @@ export * from './functional-element/render-callback';
 export { requireAllCustomElementsToBeFunctionalElement } from './require-functional-element';
 export * from './template-transforms/vir-css/vir-css';
 export * from './template-transforms/vir-html/vir-html';
+export * from './typed-event/typed-event';

package/dist/index.js

@@ -2,7 +2,6 @@ export * from './functional-element/define-functional-element';
 export * from './functional-element/directives/assign-with-clean-up.directive';
 export * from './functional-element/directives/assign.directive';
 export * from './functional-element/directives/listen.directive';
-export * from './functional-element/directives/named-listen.directive';
 export * from './functional-element/directives/on-dom-created.directive';
 export * from './functional-element/directives/on-resize.directive';
 export * from './functional-element/element-events';
@@ -12,3 +11,4 @@ export * from './functional-element/render-callback';
 export { requireAllCustomElementsToBeFunctionalElement } from './require-functional-element';
 export * from './template-transforms/vir-css/vir-css';
 export * from './template-transforms/vir-html/vir-html';
+export * from './typed-event/typed-event';

package/dist/template-transforms/transform-template.js

@@ -17,7 +17,7 @@ export function makeCheckTransform(name, check, transform) {
 const transformedTemplateStrings = new WeakMap();
 export function getTransformedTemplate(templateStringsKey, values, fallbackTransform) {
     const alreadyTransformedTemplateStrings = transformedTemplateStrings.get(templateStringsKey);
-    const templateTransform = alreadyTransformedTemplateStrings !== null && alreadyTransformedTemplateStrings !== void 0 ? alreadyTransformedTemplateStrings : fallbackTransform();
+    const templateTransform = alreadyTransformedTemplateStrings ?? fallbackTransform();
     if (!alreadyTransformedTemplateStrings) {
         transformedTemplateStrings.set(templateStringsKey, templateTransform);
     }
@@ -29,7 +29,6 @@ export function transformTemplate(inputTemplateStrings, inputValues, checksAndTr
     const newRaws = [];
     const valueDeletions = [];
     inputTemplateStrings.forEach((currentTemplateString, index) => {
-        var _a;
         const lastNewStringsIndex = newStrings.length - 1;
         const lastNewString = newStrings[lastNewStringsIndex];
         const currentValueIndex = index - 1;
@@ -37,9 +36,9 @@ export function transformTemplate(inputTemplateStrings, inputValues, checksAndTr
         let validTransform;
         assertValidString && assertValidString(currentTemplateString);
         if (typeof lastNewString === 'string') {
-            validTransform = (_a = checksAndTransforms.find((checkAndTransform) => {
+            validTransform = checksAndTransforms.find((checkAndTransform) => {
                 return checkAndTransform.check(lastNewString, currentTemplateString, currentValue);
-            })) === null || _a === void 0 ? void 0 : _a.transform;
+            })?.transform;
             if (validTransform) {
                 newStrings[lastNewStringsIndex] =
                     lastNewString + validTransform(currentValue) + currentTemplateString;

package/dist/template-transforms/vir-html/html-transform.js

@@ -5,7 +5,7 @@ import { makeCheckTransform, transformTemplate, } from '../transform-template';
 const htmlChecksAndTransforms = [
     makeCheckTransform('tag name interpolation', (lastNewString, currentLitString, currentValue) => {
         const shouldHaveTagNameHere = (lastNewString.trim().endsWith('<') && !!currentLitString.match(/^[\s\n>]/)) ||
-            ((lastNewString === null || lastNewString === void 0 ? void 0 : lastNewString.trim().endsWith('</')) && currentLitString.trim().startsWith('>'));
+            (lastNewString?.trim().endsWith('</') && currentLitString.trim().startsWith('>'));
         const staticTagName = hasStaticTagName(currentValue);
         if (shouldHaveTagNameHere && !staticTagName) {
             console.error({

package/dist/typed-event/typed-event.d.ts

@@ -0,0 +1,19 @@
+import { NonEmptyString } from '../augments/type';
+export declare class TypedEvent<EventTypeNameGeneric extends string = '', EventDetailGeneric = undefined> extends CustomEvent<EventDetailGeneric> {
+    readonly _type: EventTypeNameGeneric;
+    get type(): EventTypeNameGeneric;
+    constructor(type: EventTypeNameGeneric | {
+        type: EventTypeNameGeneric;
+    }, value: EventDetailGeneric);
+}
+export declare type DefinedTypedEventNameDefinition<EventDetailGeneric> = <EventTypeNameGeneric extends string>(eventType: NonEmptyString<EventTypeNameGeneric>) => DefinedTypedEvent<EventTypeNameGeneric, EventDetailGeneric>;
+export declare type DefinedTypedEvent<EventTypeNameGeneric extends string, EventDetailGeneric> = (new (eventValue: EventDetailGeneric) => TypedEvent<EventTypeNameGeneric, EventDetailGeneric>) & {
+    type: EventTypeNameGeneric;
+};
+/**
+ * Defined a typed event. Make sure to use currying and call this function twice! Typescript's
+ * generic restrictions require this setup to get the types right without excessive verbosity.
+ *
+ * Example: const myCustomEvent = defineTypedEvent<number>()('my-custom-event')
+ */
+export declare function defineTypedEvent<EventDetailGeneric>(): <EventTypeNameGeneric extends string>(eventType: NonEmptyString<EventTypeNameGeneric>) => DefinedTypedEvent<EventTypeNameGeneric, EventDetailGeneric>;

package/dist/typed-event/typed-event.js

@@ -0,0 +1,30 @@
+export class TypedEvent extends CustomEvent {
+    _type = '';
+    get type() {
+        return this._type;
+    }
+    constructor(type, value) {
+        super(typeof type === 'string' ? type : type.type, {
+            detail: value,
+            bubbles: true,
+            composed: true,
+        });
+    }
+}
+/**
+ * Defined a typed event. Make sure to use currying and call this function twice! Typescript's
+ * generic restrictions require this setup to get the types right without excessive verbosity.
+ *
+ * Example: const myCustomEvent = defineTypedEvent<number>()('my-custom-event')
+ */
+export function defineTypedEvent() {
+    return (eventType) => {
+        return class extends TypedEvent {
+            static type = eventType;
+            _type = eventType;
+            constructor(value) {
+                super(eventType, value);
+            }
+        };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-vir",
-    "version": "3.0.1",
+    "version": "4.0.2",
     "keywords": [
         "custom",
         "web",
@@ -25,23 +25,28 @@
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
-        "compile": "virmator compile",
+        "compile": "rm -rf dist && tsc",
         "format": "virmator format write",
-        "prepublishOnly": "npm run test:full",
+        "jest": "jest --config ./src/jest/jest.config.ts",
+        "prepublishOnly": "npm run compile && npm run test:full",
         "spellcheck": "virmator spellcheck",
-        "start": "npm install && snowpack dev",
-        "test": "npm run compile",
+        "start": "npm install && vite --force --config ./src/vite/vite.config.ts",
+        "test": "npm run type-check && npm run jest",
         "test:full": "npm test && npm run spellcheck && virmator format check && npm run update-docs -- --check",
-        "update-docs": "virmator code-in-markdown README.md"
+        "type-check": "tsc --noEmit",
+        "update-docs": "virmator code-in-markdown README.md --index src/index.ts"
     },
     "dependencies": {
-        "augment-vir": "^1.4.1",
-        "lit": "^2.0.2"
+        "augment-vir": "^1.4.3",
+        "lit": "^2.1.1"
     },
     "devDependencies": {
-        "@snowpack/plugin-typescript": "^1.2.1",
-        "snowpack": "^3.8.8",
-        "typescript": "^4.4.4",
-        "virmator": "^1.3.7"
+        "@types/jest": "^27.4.0",
+        "jest": "^27.4.7",
+        "ts-jest": "^27.1.3",
+        "ts-node": "^10.4.0",
+        "typescript": "^4.5.4",
+        "virmator": "^1.3.7",
+        "vite": "^2.7.12"
     }
 }

package/dist/functional-element/directives/named-listen.directive.d.ts

@@ -1,15 +0,0 @@
-import { DirectiveResult } from 'lit/directive.js';
-/**
- * Listen to events. First parameter is just a string for an event name/type, vs. the more
- * complicated first parameter type for the "listen" directive. If the given eventName is a native
- * DOM event, the event type given to the callback will be the event type associated with that
- * native event type. Otherwise, specific event types given to the callback are unknown.
- *
- * If you are listening to your custom events, it is better to use the "listen" directive directly
- * so your callbacks are more tightly typed.
- *
- * @param eventName Name of the event to listen to.
- * @param listener The callback to fire when an event is caught.
- */
-export declare function namedListen<EventName extends keyof HTMLElementEventMap>(eventName: EventName, listener: (event: HTMLElementEventMap[EventName]) => void): DirectiveResult;
-export declare function namedListen<EventName extends string>(eventName: EventName, listener: (event: Event) => void): DirectiveResult;

package/dist/functional-element/directives/named-listen.directive.js

@@ -1,42 +0,0 @@
-import { noChange } from 'lit';
-import { directive, Directive } from 'lit/directive.js';
-import { extractElement } from './directive-util';
-export function namedListen(eventName, listener) {
-    return listenDirective(eventName, listener);
-}
-const listenDirective = directive(class extends Directive {
-    constructor(partInfo) {
-        super(partInfo);
-        this.element = extractElement(partInfo, 'listen', HTMLElement);
-    }
-    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) => { var _a; return (_a = this.lastListenerMetaData) === null || _a === void 0 ? void 0 : _a.callback(event); },
-        };
-    }
-    render(eventName, callback) {
-        if (typeof eventName !== 'string') {
-            throw new Error(`Cannot listen to an event with a name that is not a string. Given event name: "${eventName}"`);
-        }
-        if (this.lastListenerMetaData && this.lastListenerMetaData.eventType === eventName) {
-            /**
-             * 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(eventName, callback));
-        }
-        return noChange;
-    }
-});