element-vir 6.1.5 → 6.2.0

package/README.md

@@ -1,5 +1,7 @@
 # element-vir
 
+A wrapper for [lit-element](http://lit.dev) that adds type-safe custom element usage and I/O with declarative custom element definition.
+
 Heroic. Reactive. Declarative. Type safe. Web components without compromise.
 
 No need for an extra build step,<br>
@@ -11,8 +13,6 @@ _**It's just TypeScript.**_
 
 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).
 
-In reality this is basically a [lit-element](http://lit.dev) wrapper that adds type-safe element tag usage and I/O with declarative style component definition.
-
 [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>
@@ -29,13 +29,13 @@ Make sure to install this as a normal dependency (not just a dev dependency) bec
 
 # Usage
 
-Most usage of this package is done through the [`defineElementNoInputs` function](https://github.com/electrovir/element-vir/blob/main/src/declarative-element/define-declarative-element.ts#L25-L30). See the [`DeclarativeElementInit` type](https://github.com/electrovir/element-vir/blob/main/src/declarative-element/declarative-element-init.ts#L7-L20) for that function's inputs. These inputs are also described below with examples.
+Most usage of this package is done through the `defineElement` or `defineElementNoInputs` functions. See the `DeclarativeElementInit` type 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 if you wish.
 
 ## Simple element definition
 
-Use `defineElementNoInputs` to define your element if you're not setting inputs (or just for now as you're getting started). It must be given an object with at least `tagName` and `renderCallback` properties (the types enforce this). Here is a bare-minimum example custom element:
+Use `defineElementNoInputs` to define your element if it's not going to accept any inputs (or just for now as you're getting started). It 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 -->
 
@@ -201,6 +201,40 @@ export const MyAppWithAssignmentElement = defineElementNoInputs({
 });
 ```
 
+## Other callbacks
+
+There are two other callbacks you can define that are sort of similar to lifecycle callbacks. They are much simpler than lifecycle callbacks however.
+
+-   `initCallback`: called right before the first render, has all state and inputs setup.
+-   `cleanupCallback`: called when an element is removed from the DOM. (This is the same as the `disconnectedCallback` in standard HTMLElement classes.)
+
+<!-- example-link: src/readme-examples/my-app-with-cleanup-callback.element.ts -->
+
+```TypeScript
+import {defineElementNoInputs, html} from 'element-vir';
+
+export const MyAppWithAssignmentCleanupCallbackElement = defineElementNoInputs({
+    tagName: 'my-app-with-cleanup-callback',
+    stateInit: {
+        intervalId: undefined as undefined | number,
+    },
+    initCallback: ({updateState}) => {
+        updateState({
+            intervalId: window.setInterval(() => console.log('hi'), 1000),
+        });
+    },
+    renderCallback: () => html`
+        <h1>My App</h1>
+    `,
+    cleanupCallback: ({state, updateState}) => {
+        window.clearInterval(state.intervalId);
+        updateState({
+            intervalId: undefined,
+        });
+    },
+});
+```
+
 ## Element events (outputs)
 
 Define events with `events` when defining a declarative 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.

package/dist/declarative-element/declarative-element-init.d.ts

@@ -29,5 +29,6 @@ export declare type DeclarativeElementInit<InputsGeneric extends PropertyInitMap
     /** Called as part of the first renderCallback call, before the first renderCallback call. */
     initCallback?: InitCallback<InputsGeneric, StateInit, EventsInitGeneric, HostClassKeys, CssVarKeys>;
     renderCallback: RenderCallback<InputsGeneric, StateInit, EventsInitGeneric, HostClassKeys, CssVarKeys>;
+    cleanupCallback?: InitCallback<InputsGeneric, StateInit, EventsInitGeneric, HostClassKeys, CssVarKeys>;
     options?: Partial<DeclarativeElementDefinitionOptions> | undefined;
 };

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

@@ -16,6 +16,7 @@ export declare abstract class DeclarativeElement<InputsGeneric extends PropertyI
     static readonly isStrictInstance: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['isStrictInstance'];
     static readonly renderCallback: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['renderCallback'];
     static readonly inputsType: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['inputsType'];
+    static readonly stateType: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['stateType'];
     static readonly events: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['events'];
     static readonly stateInit: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['stateInit'];
     static readonly init: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['init'];
@@ -30,14 +31,15 @@ export declare abstract class DeclarativeElement<InputsGeneric extends PropertyI
     abstract markInputsAsHavingBeenSet(): void;
     abstract readonly definition: DeclarativeElementDefinition<InputsGeneric, PropertyInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>;
 }
-export interface StaticDeclarativeElementProperties<InputsGeneric extends PropertyInitMapBase, PropertyInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeys extends string, CssVarKeys extends string> {
+export interface StaticDeclarativeElementProperties<InputsGeneric extends PropertyInitMapBase, StateInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeys extends string, CssVarKeys extends string> {
     /** Pass through the render callback for direct unit testability */
-    readonly renderCallback: RenderCallback<InputsGeneric, PropertyInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>;
+    readonly renderCallback: RenderCallback<InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>;
     events: EventDescriptorMap<EventsInitGeneric>;
-    stateInit: ElementPropertyDescriptorMap<PropertyInitGeneric>;
-    init: RequiredBy<DeclarativeElementInit<InputsGeneric, PropertyInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>, 'stateInit' | 'events'>;
+    stateInit: ElementPropertyDescriptorMap<StateInitGeneric>;
+    init: RequiredBy<DeclarativeElementInit<InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>, 'stateInit' | 'events'>;
     inputsType: InputsGeneric;
-    isStrictInstance: (element: unknown) => element is DeclarativeElement<InputsGeneric, PropertyInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>;
+    stateType: StateInitGeneric;
+    isStrictInstance: (element: unknown) => element is DeclarativeElement<InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>;
     hostClasses: HostClassNamesMap<string, HostClassKeys>;
     cssVarNames: CssVarNameOrValueMap<CssVarKeys>;
     cssVarValues: CssVarNameOrValueMap<CssVarKeys>;

package/dist/declarative-element/define-element-no-inputs.js

@@ -51,6 +51,9 @@ export function defineElementNoInputs(initInput) {
             static get inputsType() {
                 throw new Error(`"inputsType" was called on ${initInput.tagName} as a value but it is only for types.`);
             }
+            static get stateType() {
+                throw new Error(`"stateType" was called on ${initInput.tagName} as a value but it is only for types.`);
+            }
             markInputsAsHavingBeenSet() {
                 if (!this.haveInputsBeenSet) {
                     this.haveInputsBeenSet = true;
@@ -80,6 +83,14 @@ export function defineElementNoInputs(initInput) {
                 });
                 return renderResult;
             }
+            disconnectedCallback() {
+                super.disconnectedCallback();
+                if (initInput.cleanupCallback) {
+                    const renderParams = this.createRenderParams();
+                    initInput.cleanupCallback(renderParams);
+                }
+                this.initCalled = false;
+            }
             assignInputs(inputs) {
                 getObjectTypedKeys(inputs).forEach((key) => {
                     property()(this, key);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-vir",
-    "version": "6.1.5",
+    "version": "6.2.0",
     "keywords": [
         "custom",
         "web",
@@ -37,7 +37,7 @@
     },
     "dependencies": {
         "augment-vir": "2.5.0",
-        "lit": "2.3.1"
+        "lit": "2.4.0"
     },
     "devDependencies": {
         "@open-wc/testing": "3.1.6",