element-vir 10.2.2 → 11.0.0

package/README.md

@@ -200,36 +200,6 @@ export const MyWithAssignmentElement = defineElementNoInputs({
 });
 ```
 
-## Rendering promises
-
-A handy directive is built in for rendering promises: `renderPromise`. See how it works below:
-
-<!-- example-link: src/readme-examples/my-async-render.element.ts -->
-
-```TypeScript
-import {defineElementNoInputs, html, renderPromise} from 'element-vir';
-
-export const MyAsyncRenderElement = defineElementNoInputs({
-    tagName: 'my-async-render',
-    stateInit: {
-        data: fetch('https://example.org'),
-    },
-    renderCallback: ({state}) => html`
-        ${renderPromise(state.data, ({promise, error, resolved}) => {
-            if (promise) {
-                return 'Still loading...';
-            } else if (resolved) {
-                return html`
-                    Load done!
-                `;
-            } else {
-                return `Load failed: ${error.message}`;
-            }
-        })}
-    `,
-});
-```
-
 ## 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.
@@ -624,6 +594,74 @@ export const MyWithRenderIfElement = defineElement<{shouldRender: boolean}>()({
 });
 ```
 
+### asyncState
+
+Use the `renderAsyncState` directive in conjunction with the `asyncState` property definer to seamlessly render and update element state based on async values:
+
+<!-- example-link: src/readme-examples/my-with-async-prop.element.ts -->
+
+```TypeScript
+import {asyncState, defineElement, html, listen, renderAsyncState} from 'element-vir';
+
+type EndpointData = number[];
+
+async function loadSomething(endpoint: string): Promise<EndpointData> {
+    // load something from the network
+    const data = await (
+        await fetch(
+            [
+                '',
+                'api',
+                endpoint,
+            ].join('/'),
+        )
+    ).json();
+    return data;
+}
+
+export const MyWithAsyncStateElement = defineElement<{endpoint: string}>()({
+    tagName: 'my-simple-with-render-if',
+    stateInit: {
+        data: asyncState<EndpointData>(),
+    },
+    renderCallback: ({inputs, state, updateState}) => {
+        /**
+         * This creates a promise which automatically updates the state.loadsLater prop once the
+         * promise resolves. It only creates a new promise if the "trigger" value changes.
+         */
+        updateState({
+            data: {
+                createPromise: () => loadSomething(inputs.endpoint),
+                trigger: inputs.endpoint,
+            },
+        });
+
+        return html`
+            Here's the data:
+            <br />
+            ${renderAsyncState(state.data, 'Loading...', (loadedData) => {
+                return html`
+                    Got the data: ${loadedData}
+                `;
+            })}
+            <br />
+            <button
+                ${listen('click', () => {
+                    updateState({
+                        data: {
+                            /** You can force asyncState to update by passing in forceUpdate: true. */
+                            forceUpdate: true,
+                        },
+                    });
+                })}
+            >
+                Refresh
+            </button>
+        `;
+    },
+});
+```
+
 ## Require all child custom elements to be declarative elements
 
 To require all child elements to be declarative elements defined by this package, call `requireAllCustomElementsToBeDeclarativeElements` anywhere in your app. This is a global setting so do not enable it unless you want it to be true _everywhere_ in your current run-time. This should not be used if you're using custom elements from other libraries (unless they happen to also use this package to define their custom elements).

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

@@ -1,6 +1,7 @@
 import { CSSResult } from 'lit';
 import { RequireNonVoidReturn } from '../augments/type';
 import { DeclarativeElementDefinitionOptions } from './definition-options';
+import { MaybeAsyncStateToSync } from './properties/async-state';
 import { CssVarsInitMap } from './properties/css-vars';
 import { EventsInitMap } from './properties/element-events';
 import { PropertyInitMapBase } from './properties/element-properties';
@@ -8,7 +9,7 @@ import { HostClassesInitMap } from './properties/host-classes';
 import { StylesCallback } from './properties/styles';
 import { InitCallback, RenderCallback } from './render-callback';
 export type CustomElementTagName = `${string}-${string}`;
-export type DeclarativeElementInit<TagNameGeneric extends CustomElementTagName, InputsGeneric extends PropertyInitMapBase, StateInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeysGeneric extends string, CssVarKeysGeneric extends string, RenderOutputGeneric> = {
+export type DeclarativeElementInit<TagNameGeneric extends CustomElementTagName, InputsGeneric extends PropertyInitMapBase, StateInitMaybeAsyncGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeysGeneric extends string, CssVarKeysGeneric extends string, RenderOutputGeneric> = {
     /**
      * HTML tag name. This should not be used directly, as interpolating it with the html tagged
      * template from this package is preferred.
@@ -17,7 +18,7 @@ export type DeclarativeElementInit<TagNameGeneric extends CustomElementTagName,
     /** Static styles. These should not and cannot change. */
     styles?: CSSResult | StylesCallback<HostClassKeysGeneric, CssVarKeysGeneric>;
     /** Element properties. (These can be thought of as "inputs".) */
-    stateInit?: StateInitGeneric;
+    stateInit?: StateInitMaybeAsyncGeneric;
     /** Events that the element can dispatch. (These can be thought of as "outputs".) */
     events?: EventsInitGeneric;
     /**
@@ -25,7 +26,7 @@ export type DeclarativeElementInit<TagNameGeneric extends CustomElementTagName,
      * based on current instance state or inputs, or just undefined to indicate that the host class
      * will only be manually set.
      */
-    hostClasses?: HostClassesInitMap<HostClassKeysGeneric, InputsGeneric, StateInitGeneric>;
+    hostClasses?: HostClassesInitMap<HostClassKeysGeneric, InputsGeneric, MaybeAsyncStateToSync<StateInitMaybeAsyncGeneric>>;
     /**
      * CSS Vars for the component. Keys of this object should be camelCased (or whatever your casing
      * convention is). They will be transformed, at runtime, to CSS vars with kebab-casing, to match
@@ -38,9 +39,9 @@ export type DeclarativeElementInit<TagNameGeneric extends CustomElementTagName,
      */
     cssVars?: CssVarsInitMap<CssVarKeysGeneric>;
     /** Called as part of the first renderCallback call, before the first renderCallback call. */
-    initCallback?: InitCallback<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeysGeneric, CssVarKeysGeneric, void>;
-    renderCallback: RequireNonVoidReturn<RenderOutputGeneric, RenderCallback<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeysGeneric, CssVarKeysGeneric, RenderOutputGeneric>>;
-    cleanupCallback?: InitCallback<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeysGeneric, CssVarKeysGeneric, void>;
+    initCallback?: InitCallback<TagNameGeneric, InputsGeneric, StateInitMaybeAsyncGeneric, EventsInitGeneric, HostClassKeysGeneric, CssVarKeysGeneric, void>;
+    renderCallback: RequireNonVoidReturn<RenderOutputGeneric, RenderCallback<TagNameGeneric, InputsGeneric, StateInitMaybeAsyncGeneric, EventsInitGeneric, HostClassKeysGeneric, CssVarKeysGeneric, RenderOutputGeneric>>;
+    cleanupCallback?: InitCallback<TagNameGeneric, InputsGeneric, StateInitMaybeAsyncGeneric, EventsInitGeneric, HostClassKeysGeneric, CssVarKeysGeneric, void>;
     options?: Partial<DeclarativeElementDefinitionOptions> | undefined;
 };
 //# sourceMappingURL=declarative-element-init.d.ts.map

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

@@ -1,16 +1,17 @@
 import { RequiredAndNotNullBy, RequiredBy } from '@augment-vir/common';
 import { CSSResult, LitElement } from 'lit';
 import { CustomElementTagName, DeclarativeElementInit } from './declarative-element-init';
+import { AsyncStateHandlerMap, MaybeAsyncStateToSync } from './properties/async-state';
 import { CssVarNameOrValueMap } from './properties/css-vars';
 import { EventDescriptorMap, EventsInitMap } from './properties/element-events';
 import { ElementPropertyDescriptorMap, PropertyInitMapBase } from './properties/element-properties';
 import { HostClassNamesMap } from './properties/host-classes';
 import { RenderCallback } from './render-callback';
-export type HostInstanceType<TagNameGeneric extends CustomElementTagName, InputsGeneric extends PropertyInitMapBase, StateInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeys extends string, CssVarKeys extends string, RenderOutputGeneric> = RequiredAndNotNullBy<DeclarativeElement<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>, 'shadowRoot'>;
-export type DeclarativeElementDefinition<TagNameGeneric extends CustomElementTagName = any, InputsGeneric extends PropertyInitMapBase = any, StateInitGeneric extends PropertyInitMapBase = any, EventsInitGeneric extends EventsInitMap = any, HostClassKeys extends string = string, CssVarKeys extends string = string, RenderOutputGeneric = any> = (new () => HostInstanceType<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>) & StaticDeclarativeElementProperties<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric> & {
-    instanceType: HostInstanceType<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>;
+export type HostInstanceType<TagNameGeneric extends CustomElementTagName, InputsGeneric extends PropertyInitMapBase, StateInitMaybeAsyncGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeys extends string, CssVarKeys extends string, RenderOutputGeneric> = RequiredAndNotNullBy<DeclarativeElement<TagNameGeneric, InputsGeneric, StateInitMaybeAsyncGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>, 'shadowRoot'>;
+export type DeclarativeElementDefinition<TagNameGeneric extends CustomElementTagName = any, InputsGeneric extends PropertyInitMapBase = any, StateInitMaybeAsyncGeneric extends PropertyInitMapBase = any, EventsInitGeneric extends EventsInitMap = any, HostClassKeys extends string = string, CssVarKeys extends string = string, RenderOutputGeneric = any> = (new () => HostInstanceType<TagNameGeneric, InputsGeneric, StateInitMaybeAsyncGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>) & StaticDeclarativeElementProperties<TagNameGeneric, InputsGeneric, StateInitMaybeAsyncGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric> & {
+    instanceType: HostInstanceType<TagNameGeneric, InputsGeneric, StateInitMaybeAsyncGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>;
 };
-export declare abstract class DeclarativeElement<TagNameGeneric extends CustomElementTagName = any, InputsGeneric extends PropertyInitMapBase = any, StateInitGeneric extends PropertyInitMapBase = any, EventsInitGeneric extends EventsInitMap = any, HostClassKeys extends string = string, CssVarKeys extends string = string, RenderOutputGeneric = any> extends LitElement {
+export declare abstract class DeclarativeElement<TagNameGeneric extends CustomElementTagName = any, InputsGeneric extends PropertyInitMapBase = any, StateInitMaybeAsyncGeneric extends PropertyInitMapBase = any, EventsInitGeneric extends EventsInitMap = any, HostClassKeys extends string = string, CssVarKeys extends string = string, RenderOutputGeneric = any> extends LitElement {
     static readonly tagName: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string, unknown>['tagName'];
     static readonly styles: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string, unknown>['styles'];
     static readonly isStrictInstance: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string, unknown>['isStrictInstance'];
@@ -24,22 +25,23 @@ export declare abstract class DeclarativeElement<TagNameGeneric extends CustomEl
     static readonly cssVarNames: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string, unknown>['cssVarNames'];
     static readonly cssVarValues: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string, unknown>['cssVarValues'];
     abstract render(): unknown;
-    abstract readonly instanceState: StateInitGeneric;
+    abstract readonly instanceState: MaybeAsyncStateToSync<StateInitMaybeAsyncGeneric>;
+    abstract readonly asyncStateHandlerMap: AsyncStateHandlerMap<StateInitMaybeAsyncGeneric>;
     abstract readonly instanceInputs: InputsGeneric;
     abstract assignInputs(inputs: InputsGeneric): void;
     abstract haveInputsBeenSet: boolean;
     abstract markInputsAsHavingBeenSet(): void;
-    abstract readonly definition: DeclarativeElementDefinition<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>;
+    abstract readonly definition: DeclarativeElementDefinition<TagNameGeneric, InputsGeneric, StateInitMaybeAsyncGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>;
 }
-export interface StaticDeclarativeElementProperties<TagNameGeneric extends CustomElementTagName, InputsGeneric extends PropertyInitMapBase, StateInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeys extends string, CssVarKeys extends string, RenderOutputGeneric> {
+export interface StaticDeclarativeElementProperties<TagNameGeneric extends CustomElementTagName, InputsGeneric extends PropertyInitMapBase, StateInitMaybeAsyncGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeys extends string, CssVarKeys extends string, RenderOutputGeneric> {
     /** Pass through the render callback for direct unit testability */
-    readonly renderCallback: RenderCallback<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>;
+    readonly renderCallback: RenderCallback<TagNameGeneric, InputsGeneric, StateInitMaybeAsyncGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>;
     events: EventDescriptorMap<EventsInitGeneric>;
-    stateInit: ElementPropertyDescriptorMap<StateInitGeneric>;
-    init: RequiredBy<DeclarativeElementInit<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>, 'stateInit' | 'events'>;
+    stateInit: ElementPropertyDescriptorMap<StateInitMaybeAsyncGeneric>;
+    init: RequiredBy<DeclarativeElementInit<TagNameGeneric, InputsGeneric, StateInitMaybeAsyncGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>, 'stateInit' | 'events'>;
     inputsType: InputsGeneric;
-    stateType: StateInitGeneric;
-    isStrictInstance: (element: unknown) => element is DeclarativeElement<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>;
+    stateType: MaybeAsyncStateToSync<StateInitMaybeAsyncGeneric>;
+    isStrictInstance: (element: unknown) => element is DeclarativeElement<TagNameGeneric, InputsGeneric, StateInitMaybeAsyncGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>;
     hostClasses: HostClassNamesMap<string, HostClassKeys>;
     cssVarNames: CssVarNameOrValueMap<CssVarKeys>;
     cssVarValues: CssVarNameOrValueMap<CssVarKeys>;

package/dist/declarative-element/define-element-no-inputs.d.ts

@@ -2,5 +2,5 @@ import { DeclarativeElementDefinition } from './declarative-element';
 import { CustomElementTagName, DeclarativeElementInit } from './declarative-element-init';
 import { EventsInitMap } from './properties/element-events';
 import { PropertyInitMapBase } from './properties/element-properties';
-export declare function defineElementNoInputs<TagNameGeneric extends CustomElementTagName = '-', InputsGeneric extends PropertyInitMapBase = {}, StateInitGeneric extends PropertyInitMapBase = {}, EventsInitGeneric extends EventsInitMap = {}, HostClassKeys extends string = '', CssVarKeys extends string = '', RenderOutputGeneric = any>(initInput: DeclarativeElementInit<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>): DeclarativeElementDefinition<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>;
+export declare function defineElementNoInputs<TagNameGeneric extends CustomElementTagName = '-', InputsGeneric extends PropertyInitMapBase = {}, MaybeAsyncStateInitGeneric extends PropertyInitMapBase = {}, EventsInitGeneric extends EventsInitMap = {}, HostClassKeys extends string = '', CssVarKeys extends string = '', RenderOutputGeneric = any>(initInput: DeclarativeElementInit<TagNameGeneric, InputsGeneric, MaybeAsyncStateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>): DeclarativeElementDefinition<TagNameGeneric, InputsGeneric, MaybeAsyncStateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>;
 //# sourceMappingURL=define-element-no-inputs.d.ts.map

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

@@ -11,6 +11,7 @@ import { IgnoreInputsNotBeenSetBeforeRenderWarningSymbol, defaultDeclarativeElem
 import { assign } from './directives/assign.directive';
 import { hasDeclarativeElementParent } from './has-declarative-element-parent';
 import { assignInputs, markInputsAsHavingBeenSet } from './properties/assign-inputs';
+import { toAsyncStateHandlerMap } from './properties/async-state';
 import { createCssVarNamesMap, createCssVarValuesMap } from './properties/css-vars';
 import { createEventDescriptorMap } from './properties/element-events';
 import { createElementUpdaterProxy } from './properties/element-updater-proxy';
@@ -108,12 +109,24 @@ export function defineElementNoInputs(initInput) {
                 this.haveInputsBeenSet = false;
                 // this is set below in Object.defineProperties
                 this.definition = {};
+                this.asyncStateHandlerMap = toAsyncStateHandlerMap(initInput.stateInit);
                 this.instanceInputs = createElementUpdaterProxy(this, false);
                 this.instanceState = createElementUpdaterProxy(this, true);
-                const stateInit = initInput.stateInit || {};
+                const stateInit = initInput.stateInit ||
+                    {};
                 getObjectTypedKeys(stateInit).forEach((stateKey) => {
                     property()(this, stateKey);
-                    this.instanceState[stateKey] = stateInit[stateKey];
+                    const asyncStateClassInstance = this.asyncStateHandlerMap[stateKey];
+                    if (asyncStateClassInstance) {
+                        this.instanceState[stateKey] = asyncStateClassInstance.getValue();
+                        asyncStateClassInstance.addSettleListener(() => {
+                            this[stateKey] =
+                                asyncStateClassInstance.getValue();
+                        });
+                    }
+                    else {
+                        this.instanceState[stateKey] = stateInit[stateKey];
+                    }
                 });
                 this.definition = anonymousClass;
             }

package/dist/declarative-element/directives/render-async-state.directive.d.ts

@@ -0,0 +1,7 @@
+import { UnPromise } from '@augment-vir/common';
+import { AsyncState } from '../properties/async-state';
+export declare function renderAsyncState<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncState: AsyncState<T>, fallback: FallbackResult, resolutionRender: (resolved: UnPromise<T>) => ResolutionRenderResult, errorRender: (error: Error) => ErrorRenderResult): FallbackResult | ResolutionRenderResult | ErrorRenderResult;
+export declare function renderAsyncState<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncState: AsyncState<T>, fallback: FallbackResult, resolutionRender: (resolved: UnPromise<T>) => ResolutionRenderResult, errorRender?: undefined): FallbackResult | ResolutionRenderResult | string;
+export declare function renderAsyncState<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncState: AsyncState<T>, fallback: FallbackResult, resolutionRender: undefined, errorRender: (error: Error) => ErrorRenderResult): FallbackResult | UnPromise<T> | ErrorRenderResult;
+export declare function renderAsyncState<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncState: AsyncState<T>, fallback: FallbackResult, resolutionRender?: undefined, errorRender?: undefined): FallbackResult | UnPromise<T> | string;
+//# sourceMappingURL=render-async-state.directive.d.ts.map

package/dist/declarative-element/directives/render-async-state.directive.js

@@ -0,0 +1,22 @@
+import { extractErrorMessage, isPromiseLike } from '@augment-vir/common';
+// full function type
+export function renderAsyncState(asyncState, 
+/** This value will be rendered if the async state has not settled yet. */
+fallback, resolutionRender, errorRender) {
+    if (asyncState instanceof Error) {
+        const errorResult = errorRender
+            ? errorRender(asyncState)
+            : extractErrorMessage(asyncState);
+        return errorResult;
+    }
+    else if (isPromiseLike(asyncState)) {
+        const fallbackResult = fallback;
+        return fallbackResult;
+    }
+    else {
+        const resolutionResult = resolutionRender
+            ? resolutionRender(asyncState)
+            : asyncState;
+        return resolutionResult;
+    }
+}

package/dist/declarative-element/properties/async-state.d.ts

@@ -0,0 +1,49 @@
+import { JsonCompatibleValue, UnPromise } from '@augment-vir/common';
+import { Promisable } from 'type-fest';
+import { PickAndBlockOthers } from '../../augments/type';
+import { PropertyInitMapBase } from './element-properties';
+export type AsyncState<ValueGeneric> = Error | Promisable<UnPromise<ValueGeneric>>;
+export declare function isRenderReady<T>(asyncStateInput: AsyncState<T>): asyncStateInput is UnPromise<T>;
+type AllSetValueProperties<ValueGeneric> = {
+    /** Set a new value directly without using any promises. */
+    resolvedValue: UnPromise<ValueGeneric>;
+    createPromise: () => Promise<UnPromise<ValueGeneric>>;
+    /**
+     * When trigger changes (according to deep equality checking through JSON stringify), the
+     * createPromise callback will be called and the element's state will be updated again.
+     * Otherwise, the createPromise callback will only be called the first time.
+     *
+     * Set this to undefined to disabled automatic updating. Meaning, createPromise will only be
+     * called the first time.
+     */
+    trigger: JsonCompatibleValue;
+    newPromise: Promise<UnPromise<ValueGeneric>>;
+    /** Clear the current value and trigger createPromise to get called again on the next render. */
+    forceUpdate: true;
+};
+export type AsyncStateSetValue<ValueGeneric> = PickAndBlockOthers<AllSetValueProperties<ValueGeneric>, 'createPromise' | 'trigger'> | PickAndBlockOthers<AllSetValueProperties<ValueGeneric>, 'newPromise'> | PickAndBlockOthers<AllSetValueProperties<ValueGeneric>, 'forceUpdate'> | PickAndBlockOthers<AllSetValueProperties<ValueGeneric>, 'resolvedValue'>;
+export type MaybeAsyncStateToSync<PropertyMapInit extends PropertyInitMapBase> = {
+    [Prop in keyof PropertyMapInit]: PropertyMapInit[Prop] extends AsyncStateHandler<infer ValueGeneric> | AsyncStateInit<infer ValueGeneric> ? AsyncState<ValueGeneric> : PropertyMapInit[Prop];
+};
+export type AsyncStateInputs<PropertyMapInit extends PropertyInitMapBase> = {
+    [Prop in keyof PropertyMapInit]: PropertyMapInit[Prop] extends AsyncStateHandler<infer ValueGeneric> | AsyncStateInit<infer ValueGeneric> ? AsyncStateSetValue<ValueGeneric> : PropertyMapInit[Prop];
+};
+export type AsyncStateHandlerMap<OriginalObjectGeneric extends PropertyInitMapBase> = Partial<Record<keyof OriginalObjectGeneric, AsyncStateHandler<any>>>;
+export declare function toAsyncStateHandlerMap(propertyInitMap?: PropertyInitMapBase | undefined): AsyncStateHandlerMap<PropertyInitMapBase>;
+export declare class AsyncStateHandler<ValueGeneric> {
+    #private;
+    readonly asyncMarkerSymbol: symbol;
+    constructor(initialValue: Promise<UnPromise<ValueGeneric>> | undefined);
+    setValue(setInputs: AsyncStateSetValue<ValueGeneric>): void;
+    getValue(): AsyncState<ValueGeneric>;
+    addSettleListener(callback: () => void): void;
+    removeSettleListener(callback: (value: AsyncState<ValueGeneric>) => void): void;
+}
+export declare class AsyncStateInit<ValueGeneric> {
+    readonly initialValue?: Promise<UnPromise<ValueGeneric>> | undefined;
+    constructor(initialValue?: Promise<UnPromise<ValueGeneric>> | undefined);
+    readonly asyncMarkerSymbol: symbol;
+}
+export declare function asyncState<ValueGeneric>(initialValue?: Promise<UnPromise<ValueGeneric>> | undefined): AsyncStateInit<ValueGeneric>;
+export {};
+//# sourceMappingURL=async-state.d.ts.map

package/dist/declarative-element/properties/async-state.js

@@ -0,0 +1,158 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var _AsyncStateHandler_instances, _AsyncStateHandler_lastTrigger, _AsyncStateHandler_resolutionValue, _AsyncStateHandler_rejectionError, _AsyncStateHandler_listeners, _AsyncStateHandler_lastSetPromise, _AsyncStateHandler_waitingForValuePromise, _AsyncStateHandler_fireListeners, _AsyncStateHandler_setPromise, _AsyncStateHandler_resolveValue;
+import { areJsonEqual, createDeferredPromiseWrapper, ensureError, filterObject, isPromiseLike, mapObjectValues, } from '@augment-vir/common';
+const asyncMarkerSymbol = Symbol('element-vir-async-state-marker');
+export function isRenderReady(asyncStateInput) {
+    if (asyncStateInput instanceof Error) {
+        return false;
+    }
+    else if (isPromiseLike(asyncStateInput)) {
+        return false;
+    }
+    else {
+        return true;
+    }
+}
+export function toAsyncStateHandlerMap(propertyInitMap) {
+    if (!propertyInitMap) {
+        return {};
+    }
+    const asyncStateInit = filterObject(propertyInitMap, (key, value) => {
+        return value instanceof AsyncStateInit;
+    });
+    const asyncStateHandlers = mapObjectValues(asyncStateInit, (key, value) => {
+        return new AsyncStateHandler(value.initialValue);
+    });
+    return asyncStateHandlers;
+}
+const notSetSymbol = Symbol('not set');
+export class AsyncStateHandler {
+    constructor(initialValue) {
+        _AsyncStateHandler_instances.add(this);
+        _AsyncStateHandler_lastTrigger.set(this, notSetSymbol);
+        _AsyncStateHandler_resolutionValue.set(this, void 0);
+        _AsyncStateHandler_rejectionError.set(this, void 0);
+        _AsyncStateHandler_listeners.set(this, []);
+        _AsyncStateHandler_lastSetPromise.set(this, void 0);
+        _AsyncStateHandler_waitingForValuePromise.set(this, createDeferredPromiseWrapper());
+        this.asyncMarkerSymbol = asyncMarkerSymbol;
+        if (initialValue) {
+            this.setValue({ newPromise: initialValue });
+        }
+    }
+    setValue(setInputs) {
+        if ('createPromise' in setInputs) {
+            if (__classPrivateFieldGet(this, _AsyncStateHandler_lastTrigger, "f") === notSetSymbol ||
+                !areJsonEqual(setInputs.trigger, __classPrivateFieldGet(this, _AsyncStateHandler_lastTrigger, "f"))) {
+                __classPrivateFieldSet(this, _AsyncStateHandler_lastTrigger, setInputs.trigger, "f");
+                const newValue = setInputs.createPromise();
+                __classPrivateFieldGet(this, _AsyncStateHandler_instances, "m", _AsyncStateHandler_setPromise).call(this, newValue);
+            }
+        }
+        else if ('newPromise' in setInputs) {
+            __classPrivateFieldGet(this, _AsyncStateHandler_lastTrigger, "f") === notSetSymbol;
+            __classPrivateFieldGet(this, _AsyncStateHandler_instances, "m", _AsyncStateHandler_setPromise).call(this, setInputs.newPromise);
+            // force a re-render
+            __classPrivateFieldGet(this, _AsyncStateHandler_instances, "m", _AsyncStateHandler_fireListeners).call(this);
+        }
+        else if ('resolvedValue' in setInputs) {
+            __classPrivateFieldGet(this, _AsyncStateHandler_instances, "m", _AsyncStateHandler_resolveValue).call(this, setInputs.resolvedValue);
+        }
+        else {
+            if (setInputs.forceUpdate) {
+                __classPrivateFieldSet(this, _AsyncStateHandler_lastTrigger, notSetSymbol, "f");
+                __classPrivateFieldSet(this, _AsyncStateHandler_resolutionValue, undefined, "f");
+                if (!__classPrivateFieldGet(this, _AsyncStateHandler_waitingForValuePromise, "f").isSettled()) {
+                    __classPrivateFieldGet(this, _AsyncStateHandler_waitingForValuePromise, "f").reject('Canceled by force update');
+                }
+                __classPrivateFieldSet(this, _AsyncStateHandler_waitingForValuePromise, createDeferredPromiseWrapper(), "f");
+                // force a re-render
+                __classPrivateFieldGet(this, _AsyncStateHandler_instances, "m", _AsyncStateHandler_fireListeners).call(this);
+            }
+        }
+    }
+    getValue() {
+        if (__classPrivateFieldGet(this, _AsyncStateHandler_waitingForValuePromise, "f").isSettled()) {
+            if (__classPrivateFieldGet(this, _AsyncStateHandler_rejectionError, "f")) {
+                return __classPrivateFieldGet(this, _AsyncStateHandler_rejectionError, "f");
+            }
+            else
+                return __classPrivateFieldGet(this, _AsyncStateHandler_resolutionValue, "f");
+        }
+        else {
+            return __classPrivateFieldGet(this, _AsyncStateHandler_waitingForValuePromise, "f").promise;
+        }
+    }
+    addSettleListener(callback) {
+        __classPrivateFieldGet(this, _AsyncStateHandler_listeners, "f").push(callback);
+    }
+    removeSettleListener(callback) {
+        __classPrivateFieldSet(this, _AsyncStateHandler_listeners, __classPrivateFieldGet(this, _AsyncStateHandler_listeners, "f").filter((listener) => listener !== callback), "f");
+    }
+}
+_AsyncStateHandler_lastTrigger = new WeakMap(), _AsyncStateHandler_resolutionValue = new WeakMap(), _AsyncStateHandler_rejectionError = new WeakMap(), _AsyncStateHandler_listeners = new WeakMap(), _AsyncStateHandler_lastSetPromise = new WeakMap(), _AsyncStateHandler_waitingForValuePromise = new WeakMap(), _AsyncStateHandler_instances = new WeakSet(), _AsyncStateHandler_fireListeners = function _AsyncStateHandler_fireListeners() {
+    __classPrivateFieldGet(this, _AsyncStateHandler_listeners, "f").forEach((listener) => {
+        listener();
+    });
+}, _AsyncStateHandler_setPromise = function _AsyncStateHandler_setPromise(newPromise) {
+    if (newPromise === __classPrivateFieldGet(this, _AsyncStateHandler_lastSetPromise, "f")) {
+        // abort setting the promise if we already have set this promise
+        return;
+    }
+    __classPrivateFieldSet(this, _AsyncStateHandler_resolutionValue, undefined, "f");
+    __classPrivateFieldSet(this, _AsyncStateHandler_rejectionError, undefined, "f");
+    __classPrivateFieldSet(this, _AsyncStateHandler_lastSetPromise, newPromise, "f");
+    if (__classPrivateFieldGet(this, _AsyncStateHandler_waitingForValuePromise, "f").isSettled()) {
+        __classPrivateFieldSet(this, _AsyncStateHandler_waitingForValuePromise, createDeferredPromiseWrapper(), "f");
+    }
+    newPromise
+        .then((value) => {
+        // make sure we're still actually waiting for this promise
+        if (__classPrivateFieldGet(this, _AsyncStateHandler_lastSetPromise, "f") === newPromise) {
+            __classPrivateFieldGet(this, _AsyncStateHandler_instances, "m", _AsyncStateHandler_resolveValue).call(this, value);
+        }
+    })
+        .catch((reason) => {
+        // make sure we're still actually waiting for this promise
+        if (__classPrivateFieldGet(this, _AsyncStateHandler_lastSetPromise, "f") === newPromise) {
+            __classPrivateFieldSet(this, _AsyncStateHandler_rejectionError, ensureError(reason), "f");
+            __classPrivateFieldGet(this, _AsyncStateHandler_waitingForValuePromise, "f").promise.catch(() => {
+                /**
+                 * Don't actually do anything, we just want to make sure the error is
+                 * handled so it doesn't throw errors in the browser.
+                 */
+            });
+            __classPrivateFieldGet(this, _AsyncStateHandler_waitingForValuePromise, "f").reject(reason);
+            __classPrivateFieldGet(this, _AsyncStateHandler_instances, "m", _AsyncStateHandler_fireListeners).call(this);
+        }
+    });
+}, _AsyncStateHandler_resolveValue = function _AsyncStateHandler_resolveValue(value) {
+    if (value !== __classPrivateFieldGet(this, _AsyncStateHandler_resolutionValue, "f")) {
+        __classPrivateFieldSet(this, _AsyncStateHandler_rejectionError, undefined, "f");
+        __classPrivateFieldSet(this, _AsyncStateHandler_resolutionValue, value, "f");
+        if (__classPrivateFieldGet(this, _AsyncStateHandler_waitingForValuePromise, "f").isSettled()) {
+            __classPrivateFieldSet(this, _AsyncStateHandler_waitingForValuePromise, createDeferredPromiseWrapper(), "f");
+        }
+        __classPrivateFieldGet(this, _AsyncStateHandler_waitingForValuePromise, "f").resolve(value);
+        __classPrivateFieldGet(this, _AsyncStateHandler_instances, "m", _AsyncStateHandler_fireListeners).call(this);
+    }
+};
+export class AsyncStateInit {
+    constructor(initialValue) {
+        this.initialValue = initialValue;
+        this.asyncMarkerSymbol = asyncMarkerSymbol;
+    }
+}
+export function asyncState(initialValue) {
+    return new AsyncStateInit(initialValue);
+}

package/dist/declarative-element/properties/element-updater-proxy.js

@@ -17,7 +17,13 @@ export function createElementUpdaterProxy(element, verifyExists) {
         if (verifyExists) {
             assertValidPropertyName(propertyName, element, element.tagName);
         }
-        return elementAsProps[propertyName];
+        const asyncState = element.asyncStateHandlerMap[propertyName];
+        if (asyncState) {
+            return asyncState.getValue();
+        }
+        else {
+            return elementAsProps[propertyName];
+        }
     }
     const propsProxy = new Proxy({}, {
         get: valueGetter,
@@ -31,7 +37,13 @@ export function createElementUpdaterProxy(element, verifyExists) {
              * "getOwnPropertyDescriptor".
              */
             target[propertyName] = undefined;
-            elementAsProps[propertyName] = newValue;
+            const asyncState = element.asyncStateHandlerMap[propertyName];
+            if (asyncState) {
+                asyncState.setValue(newValue);
+            }
+            else {
+                elementAsProps[propertyName] = newValue;
+            }
             return true;
         },
         ownKeys: (target) => {

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

@@ -1,13 +1,14 @@
 import { TypedEvent } from '../typed-event/typed-event';
 import { DeclarativeElement, HostInstanceType } from './declarative-element';
 import { CustomElementTagName } from './declarative-element-init';
+import { AsyncStateInputs, MaybeAsyncStateToSync } from './properties/async-state';
 import { EventDescriptorMap, EventInitMapEventDetailExtractor, EventsInitMap } from './properties/element-events';
 import { PropertyInitMapBase } from './properties/element-properties';
 export type RenderCallback<TagNameGeneric extends CustomElementTagName = any, InputsGeneric extends PropertyInitMapBase = any, StateGeneric extends PropertyInitMapBase = any, EventsInitGeneric extends EventsInitMap = any, HostClassKeys extends string = any, CssVarKeys extends string = any, RenderOutputGeneric = any> = (params: RenderParams<TagNameGeneric, InputsGeneric, StateGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>) => RenderOutputGeneric;
 export type InitCallback<TagNameGeneric extends CustomElementTagName, InputsGeneric extends PropertyInitMapBase, StateGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeys extends string, CssVarKeys extends string, RenderOutputGeneric> = (params: RenderParams<TagNameGeneric, InputsGeneric, StateGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>) => void;
-export type UpdateStateCallback<StateGeneric extends PropertyInitMapBase> = (newState: Partial<StateGeneric>) => void;
+export type UpdateStateCallback<StateGeneric extends PropertyInitMapBase> = (newState: Partial<AsyncStateInputs<StateGeneric>>) => void;
 export type RenderParams<TagNameGeneric extends CustomElementTagName, InputsGeneric extends PropertyInitMapBase, StateInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeys extends string, CssVarKeys extends string, RenderOutputGeneric> = {
-    state: Readonly<StateInitGeneric>;
+    state: Readonly<MaybeAsyncStateToSync<StateInitGeneric>>;
     updateState: UpdateStateCallback<StateInitGeneric>;
     events: EventDescriptorMap<EventsInitGeneric>;
     host: HostInstanceType<TagNameGeneric, InputsGeneric, StateInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys, RenderOutputGeneric>;

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

@@ -3,7 +3,13 @@ export function createRenderParams(element, eventsMap) {
     function updateState(newStatePartial) {
         getObjectTypedKeys(newStatePartial).forEach((stateKey) => {
             const newValue = newStatePartial[stateKey];
-            element.instanceState[stateKey] = newValue;
+            const asyncState = element.asyncStateHandlerMap[stateKey];
+            if (asyncState) {
+                asyncState.setValue(newValue);
+            }
+            else {
+                element.instanceState[stateKey] = newValue;
+            }
         });
     }
     const renderParams = {

package/dist/index.d.ts

@@ -1,4 +1,3 @@
-export * from '@electrovir/cached-promise';
 export * from './built-in-lit-directives';
 export * from './declarative-element/declarative-element';
 export * from './declarative-element/declarative-element-init';
@@ -11,8 +10,9 @@ export * from './declarative-element/directives/directive-helpers';
 export * from './declarative-element/directives/listen.directive';
 export * from './declarative-element/directives/on-dom-created.directive';
 export * from './declarative-element/directives/on-resize.directive';
+export * from './declarative-element/directives/render-async-state.directive';
 export * from './declarative-element/directives/render-if.directive';
-export * from './declarative-element/directives/render-promise.directive';
+export * from './declarative-element/properties/async-state';
 export * from './declarative-element/properties/css-vars';
 export * from './declarative-element/properties/element-events';
 export * from './declarative-element/properties/element-properties';

package/dist/index.js

@@ -1,4 +1,3 @@
-export * from '@electrovir/cached-promise';
 export * from './built-in-lit-directives';
 export * from './declarative-element/declarative-element';
 export * from './declarative-element/declarative-element-init';
@@ -10,8 +9,9 @@ export * from './declarative-element/directives/directive-helpers';
 export * from './declarative-element/directives/listen.directive';
 export * from './declarative-element/directives/on-dom-created.directive';
 export * from './declarative-element/directives/on-resize.directive';
+export * from './declarative-element/directives/render-async-state.directive';
 export * from './declarative-element/directives/render-if.directive';
-export * from './declarative-element/directives/render-promise.directive';
+export * from './declarative-element/properties/async-state';
 export * from './declarative-element/properties/css-vars';
 export * from './declarative-element/properties/element-events';
 export * from './declarative-element/properties/element-properties';

package/dist/template-transforms/vir-css/css-transform.d.ts

@@ -1,8 +1,8 @@
 import { CSSResultGroup } from 'lit';
-import { DeclarativeElementDefinition } from '../../declarative-element/declarative-element';
+import { ConstructorWithTagName } from '../has-static-tag-name';
 export type CssTemplateTransform = {
     templateStrings: TemplateStringsArray;
     valueIndexDeletions: number[];
 };
-export declare function transformCssTemplate(inputTemplateStrings: TemplateStringsArray, inputValues: (number | CSSResultGroup | DeclarativeElementDefinition)[]): CssTemplateTransform;
+export declare function transformCssTemplate(inputTemplateStrings: TemplateStringsArray, inputValues: (number | CSSResultGroup | ConstructorWithTagName)[]): CssTemplateTransform;
 //# sourceMappingURL=css-transform.d.ts.map

package/dist/template-transforms/vir-css/vir-css.d.ts

@@ -1,4 +1,4 @@
 import { CSSResult, CSSResultGroup } from 'lit';
-import { DeclarativeElementDefinition } from '../../declarative-element/declarative-element';
-export declare function css(inputTemplateStrings: TemplateStringsArray, ...inputValues: (number | CSSResultGroup | DeclarativeElementDefinition)[]): CSSResult;
+import { ConstructorWithTagName } from '../has-static-tag-name';
+export declare function css(inputTemplateStrings: TemplateStringsArray, ...inputValues: (number | CSSResultGroup | ConstructorWithTagName)[]): CSSResult;
 //# sourceMappingURL=vir-css.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-vir",
-    "version": "10.2.2",
+    "version": "11.0.0",
     "keywords": [
         "custom",
         "web",
@@ -41,7 +41,6 @@
     "dependencies": {
         "@augment-vir/browser": "^13.2.1",
         "@augment-vir/common": "^13.2.1",
-        "@electrovir/cached-promise": "^0.0.1",
         "lit": "2.7.0"
     },
     "devDependencies": {
@@ -70,7 +69,7 @@
         "prettier-plugin-sort-json": "^1.0.0",
         "prettier-plugin-toml": "^0.3.1",
         "ts-node": "^10.9.1",
-        "type-fest": "^3.7.0",
+        "type-fest": "^3.7.1",
         "typescript": "^5.0.2",
         "virmator": "^6.2.2",
         "vite": "^4.2.1"

package/dist/declarative-element/directives/render-promise.directive.d.ts

@@ -1,16 +0,0 @@
-import { CachedPromise, GetCachedPromiseInput } from '@electrovir/cached-promise';
-import { RequireExactlyOne } from 'type-fest';
-import { RequireNonVoidReturn } from '../../augments/type';
-export type RenderPromiseInput<ValueType> = RequireExactlyOne<{
-    promise: Promise<ValueType>;
-    resolved: ValueType;
-    error: Error;
-}>;
-export type RenderPromiseRenderer<ValueType, RenderOutput> = RequireNonVoidReturn<RenderOutput, (input: RenderPromiseInput<ValueType>) => RenderOutput>;
-export declare function renderPromise<ValueType, RenderOutput>(maybePromise: Promise<ValueType> | ValueType, renderer: RenderPromiseRenderer<ValueType, RenderOutput>): RenderOutput | import("lit-html/directive").DirectiveResult<typeof import("lit-html/directives/until").UntilDirective>;
-export type RenderCachedPromiseInputs<ValueType, RenderOutput> = {
-    cachedPromise: CachedPromise<ValueType>;
-    render: RenderPromiseRenderer<ValueType, RenderOutput>;
-} & GetCachedPromiseInput<ValueType>;
-export declare function renderCachedPromise<ValueType, RenderOutput>({ cachedPromise, render, triggers, createPromise, }: RenderCachedPromiseInputs<ValueType, RenderOutput>): import("lit-html/directive").DirectiveResult<typeof import("lit-html/directives/until").UntilDirective> | RenderOutput;
-//# sourceMappingURL=render-promise.directive.d.ts.map

package/dist/declarative-element/directives/render-promise.directive.js

@@ -1,30 +0,0 @@
-import { ensureError } from '@augment-vir/common';
-import { until } from 'lit/directives/until.js';
-export function renderPromise(maybePromise, renderer) {
-    if (typeof renderer === 'string') {
-        throw new Error(`Cannot pass string renderer`);
-    }
-    if (maybePromise instanceof Promise) {
-        return until(maybePromise
-            .catch((error) => {
-            return ensureError(error);
-        })
-            .then((resolved) => {
-            if (resolved instanceof Error) {
-                return renderer({ error: resolved });
-            }
-            else {
-                return renderer({ resolved });
-            }
-        }), renderer({ promise: maybePromise }));
-    }
-    else {
-        return renderer({ resolved: maybePromise });
-    }
-}
-export function renderCachedPromise({ cachedPromise, render, triggers, createPromise, }) {
-    return renderPromise(cachedPromise.get({
-        createPromise,
-        triggers,
-    }), render);
-}