element-vir 6.1.6 → 6.2.1

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.
@@ -325,7 +359,8 @@ export const MyAppWithHostClasses = defineElementNoInputs({
     hostClasses: {
         /**
          * Setting the value to false means this host class will not ever automatically be applied.
-         * It will simply be a static member on the element for manual application in consumers when desired.
+         * It will simply be a static member on the element for manual application in consumers when
+         * desired.
          */
         styleVariationA: false,
         /**

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/define-element-no-inputs.js

@@ -83,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/dist/declarative-element/directives/awaiting.directive.d.ts

@@ -0,0 +1,18 @@
+export declare type MaybePromise<T> = (T extends Promise<infer ValueType> ? T | ValueType : Promise<T> | T) | undefined | {
+    error: Error;
+};
+export declare type CreateStateUpdatingPromiseInputs<InnerValueGeneric, KeyGeneric extends PropertyKey, StateGeneric extends Readonly<Record<KeyGeneric, MaybePromise<InnerValueGeneric>>>> = {
+    updateState: (newState: Partial<StateGeneric>) => void;
+    stateKey: KeyGeneric;
+} & ({
+    createPromiseCallback: () => Promise<InnerValueGeneric>;
+    promise?: undefined;
+} | {
+    promise: Promise<InnerValueGeneric>;
+    createPromiseCallback?: undefined;
+});
+export declare function createStateUpdatingPromiseIfUndefined<InnerValueGeneric, KeyGeneric extends PropertyKey, StateGeneric extends Readonly<Record<KeyGeneric, MaybePromise<InnerValueGeneric>>>>(inputs: CreateStateUpdatingPromiseInputs<InnerValueGeneric, KeyGeneric, StateGeneric> & {
+    state: StateGeneric;
+}): void;
+export declare function awaiting<ValueGeneric, FallbackGeneric, CallbackReturnGeneric>(input: MaybePromise<ValueGeneric>, notResolvedYetFallback: FallbackGeneric, resolvedCallback: (resolved: ValueGeneric) => CallbackReturnGeneric): CallbackReturnGeneric | FallbackGeneric | Error | undefined;
+export declare function ensureError(input: unknown): Error;

package/dist/declarative-element/directives/awaiting.directive.js

@@ -0,0 +1,42 @@
+import { extractErrorMessage, isPromiseLike, typedHasProperty } from 'augment-vir';
+export function createStateUpdatingPromiseIfUndefined(inputs) {
+    const { state, stateKey } = inputs;
+    const currentValue = state[stateKey];
+    if (currentValue === undefined) {
+        createStateUpdatingPromise(inputs);
+    }
+}
+function createStateUpdatingPromise({ updateState, stateKey, createPromiseCallback: promiseCallback, promise, }) {
+    const output = promise !== null && promise !== void 0 ? promise : promiseCallback();
+    // as casts below are required because, even though all the generics agree, TypeScript can't figure that out here
+    if (output instanceof Promise) {
+        output
+            .then((result) => {
+            updateState({ [stateKey]: result });
+        })
+            .catch((thrownError) => {
+            const guaranteedError = ensureError(thrownError);
+            updateState({ [stateKey]: { error: guaranteedError } });
+        });
+    }
+    updateState({ [stateKey]: output });
+}
+export function awaiting(input, notResolvedYetFallback, resolvedCallback) {
+    if (isPromiseLike(input) || input == undefined) {
+        return notResolvedYetFallback;
+    }
+    else if (typedHasProperty(input, 'error')) {
+        return input.error;
+    }
+    else {
+        return resolvedCallback(input);
+    }
+}
+export function ensureError(input) {
+    if (input instanceof Error) {
+        return input;
+    }
+    else {
+        return new Error(extractErrorMessage(input));
+    }
+}

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

@@ -5,7 +5,8 @@ import { DefinedTypedEvent, TypedEvent } from '../../typed-event/typed-event';
  * typed events (pass in a return value from defineTypedEvent).
  *
  * @param definedTypedEvent Needs to come either from a declarative element (like
- *   MyDeclarativeElement.events.eventName) or from a typed event created via the defineTypedEvent function.
+ *   MyDeclarativeElement.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.
  */

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './declarative-element/define-element-no-inputs';
 export type { DeclarativeElementDefinitionOptions } from './declarative-element/definition-options';
 export * from './declarative-element/directives/assign-with-clean-up.directive';
 export * from './declarative-element/directives/assign.directive';
+export * from './declarative-element/directives/awaiting.directive';
 export * from './declarative-element/directives/directive-helpers';
 export * from './declarative-element/directives/listen.directive';
 export * from './declarative-element/directives/on-dom-created.directive';

package/dist/index.js

@@ -3,6 +3,7 @@ export * from './declarative-element/define-element';
 export * from './declarative-element/define-element-no-inputs';
 export * from './declarative-element/directives/assign-with-clean-up.directive';
 export * from './declarative-element/directives/assign.directive';
+export * from './declarative-element/directives/awaiting.directive';
 export * from './declarative-element/directives/directive-helpers';
 export * from './declarative-element/directives/listen.directive';
 export * from './declarative-element/directives/on-dom-created.directive';

package/dist/template-transforms/nested-mapped-templates.js

@@ -1,8 +1,8 @@
-import { typedHasOwnProperties } from 'augment-vir';
+import { typedHasProperties } from 'augment-vir';
 import { DeclarativeElementMarkerSymbol } from '../declarative-element-marker-symbol';
 function extractElementKeys(values) {
     return values.filter((value) => {
-        return (typedHasOwnProperties(value, [
+        return (typedHasProperties(value, [
             'tagName',
             DeclarativeElementMarkerSymbol,
         ]) &&

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

@@ -1,4 +1,4 @@
-import { typedHasOwnProperties } from 'augment-vir';
+import { typedHasProperties } from 'augment-vir';
 import { filterOutArrayIndexes } from '../augments/array';
 import { DeclarativeElementMarkerSymbol } from '../declarative-element-marker-symbol';
 import { getAlreadyMappedTemplate, setMappedTemplate } from './nested-mapped-templates';
@@ -20,7 +20,7 @@ export function makeCheckTransform(name, check, transform) {
 const transformedTemplateStrings = new WeakMap();
 function extractElementValues(values) {
     return values.filter((value) => {
-        return (typedHasOwnProperties(value, [
+        return (typedHasProperties(value, [
             'tagName',
             DeclarativeElementMarkerSymbol,
         ]) &&

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-vir",
-    "version": "6.1.6",
+    "version": "6.2.1",
     "keywords": [
         "custom",
         "web",
@@ -25,24 +25,51 @@
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
+        "build": "virmator frontend build",
         "compile": "rm -rf dist && tsc --project tsconfig.json",
+        "docs:update": "virmator code-in-markdown",
         "format": "virmator format",
-        "prepublishOnly": "npm run compile && npm run test:full",
+        "prepublishOnly": "npm run compile && npm run test:all",
+        "preview": "virmator frontend preview",
         "spellcheck": "virmator spellcheck",
         "start": "npm install && virmator frontend",
         "test": "npm run test:types && virmator test-web",
-        "test:full": "npm test && npm run spellcheck && virmator format check && npm run update-docs -- --check",
+        "test:all": "npm run test:types && npm test && npm run spellcheck && npm run test:format && npm run test:docs",
+        "test:docs": "virmator code-in-markdown check",
+        "test:format": "virmator format check",
         "test:types": "tsc --noEmit",
-        "update-docs": "virmator code-in-markdown README.md --index src/index.ts"
+        "test:web": "virmator test-web"
     },
     "dependencies": {
-        "augment-vir": "2.5.0",
+        "augment-vir": "^3.0.4",
         "lit": "2.4.0"
     },
     "devDependencies": {
-        "@open-wc/testing": "3.1.6",
-        "@web/dev-server-esbuild": "0.3.2",
-        "@web/test-runner": "0.14.0",
-        "virmator": "3.0.6"
+        "@istanbuljs/nyc-config-typescript": "^1.0.2",
+        "@open-wc/testing": "^3.1.6",
+        "@types/chai": "^4.3.3",
+        "@types/mocha": "^10.0.0",
+        "@web/dev-server-esbuild": "^0.3.3",
+        "@web/test-runner": "^0.15.0",
+        "@web/test-runner-commands": "^0.6.5",
+        "@web/test-runner-playwright": "^0.9.0",
+        "ansi-colors": "^4.1.3",
+        "chai": "^4.3.6",
+        "cspell": "^6.12.0",
+        "istanbul-smart-text-reporter": "^0.0.1",
+        "markdown-code-example-inserter": "^0.1.11",
+        "mocha": "^10.1.0",
+        "mocha-spec-reporter-with-file-names": "^0.0.0",
+        "nyc": "^15.1.0",
+        "prettier": "^2.7.1",
+        "prettier-plugin-jsdoc": "^0.4.2",
+        "prettier-plugin-multiline-arrays": "^1.1.1",
+        "prettier-plugin-organize-imports": "^3.1.1",
+        "prettier-plugin-packagejson": "^2.3.0",
+        "prettier-plugin-sort-json": "^0.0.3",
+        "prettier-plugin-toml": "^0.3.1",
+        "ts-node": "^10.9.1",
+        "virmator": "^4.2.13",
+        "vite": "^3.2.0"
     }
 }