element-vir 23.4.2 → 25.0.0

package/README.md

@@ -169,13 +169,15 @@ import {defineElementNoInputs, html, listen} from 'element-vir';
 
 export const MyWithUpdateState = defineElementNoInputs({
     tagName: 'my-with-update-state',
-    stateInitStatic: {
-        username: 'dev',
-        /**
-         * Use "as" to create state properties that can be types other than the initial value's
-         * type. This is particularly useful when, as below, the initial value is undefined.
-         */
-        email: undefined as string | undefined,
+    state() {
+        return {
+            username: 'dev',
+            /**
+             * Use "as" to create state properties that can be types other than the initial value's
+             * type. This is particularly useful when, as below, the initial value is undefined.
+             */
+            email: undefined as string | undefined,
+        };
     },
     render({state, updateState}) {
         return html`
@@ -219,8 +221,8 @@ export const MyWithAssignment = defineElementNoInputs({
 
 There are two other callbacks you can define that are sort of similar to lifecycle callbacks. They are much simpler than lifecycle callbacks however.
 
-- `init`: called right before the first render and has all state and inputs setup. (This is similar to `connectedCallback` in standard HTMLElement classes but is fired much later, after inputs are assigned, to avoid race conditions.)
-- `cleanup`: called when an element is removed from the DOM. (This is the same as the `disconnectedCallback` in standard HTMLElement classes.)
+-   `init`: called right before the first render and has all state and inputs setup. (This is similar to `connectedCallback` in standard HTMLElement classes but is fired much later, after inputs are assigned, to avoid race conditions.)
+-   `cleanup`: 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-with-cleanup-callback.element.ts -->
 
@@ -229,24 +231,18 @@ import {defineElementNoInputs, html} from 'element-vir';
 
 export const MyWithAssignmentCleanupCallback = defineElementNoInputs({
     tagName: 'my-with-cleanup-callback',
-    stateInitStatic: {
-        intervalId: undefined as undefined | number,
-    },
-    init: ({updateState}) => {
-        updateState({
+    state() {
+        return {
             intervalId: window.setInterval(() => console.info('hi'), 1000),
-        });
+        };
     },
     render() {
         return html`
             <h1>My App</h1>
         `;
     },
-    cleanup: ({state, updateState}) => {
+    cleanup({state}) {
         window.clearInterval(state.intervalId);
-        updateState({
-            intervalId: undefined,
-        });
     },
 });
 ```
@@ -296,8 +292,10 @@ import {MyWithEvents} from './my-with-events.element.js';
 
 export const MyWithEventListening = defineElementNoInputs({
     tagName: 'my-with-event-listening',
-    stateInitStatic: {
-        myNumber: -1,
+    state() {
+        return {
+            myNumber: -1,
+        };
     },
     render({state, updateState}) {
         return html`
@@ -369,8 +367,8 @@ Host classes can be defined and used with type safety. Host classes are used to
 
 Host classes are defined by passing an object to `hostClasses` at element definition time. Each property name in the `hostClasses` object creates a host class name (note that host class names must start with the element's tag name). Each value in the `hostClasses` object defines behavior for the host class:
 
-- if the value is a callback, that host class will automatically be applied if the callback returns true after a render is executed.
-- if the value is `false`, the host class is never automatically applied, it must be manually applied by consumers.
+-   if the value is a callback, that host class will automatically be applied if the callback returns true after a render is executed.
+-   if the value is `false`, the host class is never automatically applied, it must be manually applied by consumers.
 
 Apply host classes in the element's stylesheet by using a callback for the styles property:
 
@@ -381,8 +379,10 @@ import {css, defineElementNoInputs, html} from 'element-vir';
 
 export const MyWithHostClassDefinition = defineElementNoInputs({
     tagName: 'my-with-host-class-definition',
-    stateInitStatic: {
-        myProp: 'hello there',
+    state() {
+        return {
+            myProp: 'hello there',
+        };
     },
     hostClasses: {
         /**
@@ -629,12 +629,15 @@ async function loadSomething(endpoint: string): Promise<EndpointData> {
 
 export const MyWithAsyncProp = defineElement<{endpoint: string}>()({
     tagName: 'my-with-async-prop',
-    stateInitStatic: {
-        data: asyncProp({
-            async updateCallback({endpoint}: {endpoint: string}) {
-                return loadSomething(endpoint);
-            },
-        }),
+    state() {
+        return {
+            data: asyncProp({
+                async updateCallback({endpoint}: {endpoint: string}) {
+                    return loadSomething(endpoint);
+                },
+            }),
+            hi: '',
+        };
     },
     render({inputs, state}) {
         /**

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

@@ -7,36 +7,30 @@ import { type EventsInitMap } from './properties/element-events.js';
 import { type PropertyInitMapBase } from './properties/element-properties.js';
 import { type HostClassesInitMap } from './properties/host-classes.js';
 import { type StylesCallback } from './properties/styles.js';
-import { type InitCallback, type RenderCallback } from './render-callback.js';
+import { type InitCallback, type RenderCallback, type RenderParams } from './render-callback.js';
 /**
  * Initialization for an element-vir declarative element. This defines all the pieces required for
  * rendering the element.
  *
  * @category Internal
  */
-export type DeclarativeElementInit<TagName extends CustomElementTagName, Inputs extends PropertyInitMapBase, StateInit extends PropertyInitMapBase, EventsInit extends EventsInitMap, HostClassKeys extends BaseCssPropertyName<TagName>, CssVarKeys extends BaseCssPropertyName<TagName>, SlotNames extends ReadonlyArray<string>> = {
+export type DeclarativeElementInit<TagName extends CustomElementTagName, Inputs extends PropertyInitMapBase, State extends PropertyInitMapBase, EventsInit extends EventsInitMap, HostClassKeys extends BaseCssPropertyName<TagName>, CssVarKeys extends BaseCssPropertyName<TagName>, SlotNames extends ReadonlyArray<string>> = {
     /**
      * HTML tag name. This should not be used directly, as interpolating it with the html tagged
      * template from this package is preferred.
      */
     tagName: TagName;
     /** Static styles. These should not and cannot change. */
-    styles?: CSSResult | StylesCallback<TagName, HostClassKeys, CssVarKeys>;
-    /**
-     * The definition of and initial values for the element's internal state. Note that this is
-     * defined statically: the init value will be the same for all instances of this element because
-     * it is only defined once.
-     */
-    stateInitStatic?: StateInit;
+    styles?: CSSResult | StylesCallback<TagName, HostClassKeys, CssVarKeys> | undefined;
     /** Events that the element can dispatch. (These can be thought of as "outputs".) */
-    events?: EventsInit;
-    slotNames?: SlotNames;
+    events?: EventsInit | undefined;
+    slotNames?: SlotNames | undefined;
     /**
      * HTML host classes. Values can be callbacks to determine when a host class should be defined,
      * based on current instance state or inputs, or just false to indicate that the host class will
      * only be manually set.
      */
-    hostClasses?: HostClassesInitMap<TagName, HostClassKeys, Inputs, StateInit>;
+    hostClasses?: HostClassesInitMap<TagName, HostClassKeys, Inputs, State> | undefined;
     /**
      * CSS Vars for the component. Keys of this object should be kebab-case and start with the
      * element's tag name.
@@ -45,9 +39,17 @@ export type DeclarativeElementInit<TagName extends CustomElementTagName, Inputs
      * then passed to the styles property, which must be a callback to take advantage of these.
      */
     cssVars?: CssVarsInitMap<TagName, CssVarKeys>;
+    /**
+     * Make sure to define this at the top of your element init object or TypeScript will fail to
+     * infer the element's state type.
+     *
+     * Setup the element's initial state. This is only called once per element instance, before the
+     * first render. The return type of this method becomes the element's state type.
+     */
+    state?: (params: Omit<RenderParams<TagName, Inputs, any, EventsInit, HostClassKeys, CssVarKeys, SlotNames>, 'state' | 'updateState'>) => Extract<keyof State, keyof HTMLElement> extends never ? Extract<keyof State, keyof Inputs> extends never ? State : `ERROR: Cannot define an element state property that clashes with input properties: ${Extract<keyof State, keyof Inputs> extends string | number | bigint | boolean | null | undefined ? Extract<keyof State, keyof Inputs> : ''}` : `ERROR: Cannot define an element state property that clashes with native HTMLElement properties: ${Extract<keyof State, keyof HTMLElement>}`;
     /** Called as part of the first render call, before the first render call. */
-    init?: InitCallback<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
-    render: RenderCallback<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
-    cleanup?: InitCallback<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+    init?: InitCallback<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames> | undefined;
+    render: RenderCallback<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+    cleanup?: InitCallback<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames> | undefined;
     options?: Partial<DeclarativeElementDefinitionOptions> | undefined;
 };

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

@@ -8,8 +8,7 @@ import { type DeclarativeElementDefinitionOptions } from './definition-options.j
 import { type BaseCssPropertyName } from './properties/css-properties.js';
 import { type CssVars } from './properties/css-vars.js';
 import { type EventDescriptorMap, type EventsInitMap } from './properties/element-events.js';
-import { type ElementPropertyDescriptorMap, type PropertyInitMapBase } from './properties/element-properties.js';
-import { type FlattenElementVirStateSetup } from './properties/element-vir-state-setup.js';
+import { type PropertyInitMapBase } from './properties/element-properties.js';
 import { type HostClassNamesMap } from './properties/host-classes.js';
 import { type ObservableListenerMap } from './properties/property-proxy.js';
 import { type RenderCallback, type RenderParams, type UpdateStateCallback } from './render-callback.js';
@@ -20,21 +19,21 @@ import { type SlotNameMap } from './slot-names.js';
  *
  * @category Internal
  */
-export type DeclarativeElementHost<TagName extends CustomElementTagName = any, Inputs extends PropertyInitMapBase = any, StateInit extends PropertyInitMapBase = any, EventsInit extends EventsInitMap = any, HostClassKeys extends BaseCssPropertyName<TagName> = any, CssVarKeys extends BaseCssPropertyName<TagName> = any, SlotNames extends ReadonlyArray<string> = any> = SetRequiredAndNotNull<Omit<DeclarativeElement<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>, Exclude<keyof StaticDeclarativeElementProperties<any, any, any, any, any, any, any>, keyof HTMLElement>>, 'shadowRoot'>;
+export type DeclarativeElementHost<TagName extends CustomElementTagName = any, Inputs extends PropertyInitMapBase = any, State extends PropertyInitMapBase = any, EventsInit extends EventsInitMap = any, HostClassKeys extends BaseCssPropertyName<TagName> = any, CssVarKeys extends BaseCssPropertyName<TagName> = any, SlotNames extends ReadonlyArray<string> = any> = SetRequiredAndNotNull<Omit<DeclarativeElement<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>, Exclude<keyof StaticDeclarativeElementProperties<any, any, any, any, any, any, any>, keyof HTMLElement>>, 'shadowRoot'>;
 /**
  * The full definition for a declarative element.
  *
  * @category Internal
  */
-export type DeclarativeElementDefinition<TagName extends CustomElementTagName = any, Inputs extends PropertyInitMapBase = any, StateInit extends PropertyInitMapBase = any, EventsInit extends EventsInitMap = any, HostClassKeys extends BaseCssPropertyName<TagName> = any, CssVarKeys extends BaseCssPropertyName<TagName> = any, SlotNames extends ReadonlyArray<string> = any> = (new () => DeclarativeElementHost<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>) & StaticDeclarativeElementProperties<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames> & {
-    instanceType: DeclarativeElementHost<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+export type DeclarativeElementDefinition<TagName extends CustomElementTagName = any, Inputs extends PropertyInitMapBase = any, State extends PropertyInitMapBase = any, EventsInit extends EventsInitMap = any, HostClassKeys extends BaseCssPropertyName<TagName> = any, CssVarKeys extends BaseCssPropertyName<TagName> = any, SlotNames extends ReadonlyArray<string> = any> = (new () => DeclarativeElementHost<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>) & StaticDeclarativeElementProperties<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames> & {
+    InstanceType: DeclarativeElementHost<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
 };
 /**
  * Abstract class base for all declarative elements.
  *
  * @category Internal
  */
-export declare abstract class DeclarativeElement<TagName extends CustomElementTagName = any, Inputs extends PropertyInitMapBase = any, StateInit extends PropertyInitMapBase = any, EventsInit extends EventsInitMap = any, HostClassKeys extends BaseCssPropertyName<TagName> = any, CssVarKeys extends BaseCssPropertyName<TagName> = any, SlotNames extends ReadonlyArray<string> = any> extends LitElement {
+export declare abstract class DeclarativeElement<TagName extends CustomElementTagName = any, Inputs extends PropertyInitMapBase = any, State extends PropertyInitMapBase = any, EventsInit extends EventsInitMap = any, HostClassKeys extends BaseCssPropertyName<TagName> = any, CssVarKeys extends BaseCssPropertyName<TagName> = any, SlotNames extends ReadonlyArray<string> = any> extends LitElement {
     /**
      * Assign inputs to an element instantiation. Use only on the opening tag.
      *
@@ -53,11 +52,10 @@ export declare abstract class DeclarativeElement<TagName extends CustomElementTa
     static readonly tagName: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['tagName'];
     static readonly styles: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['styles'];
     static readonly render: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['render'];
-    static readonly inputsType: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['inputsType'];
-    static readonly stateType: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['stateType'];
-    static readonly updateStateType: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['updateStateType'];
+    static readonly InputsType: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['InputsType'];
+    static readonly StateType: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['StateType'];
+    static readonly UpdateStateType: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['UpdateStateType'];
     static readonly events: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['events'];
-    static readonly stateInitStatic: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['stateInitStatic'];
     static readonly init: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['init'];
     static readonly elementOptions: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['elementOptions'];
     static readonly hostClasses: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['hostClasses'];
@@ -65,15 +63,15 @@ export declare abstract class DeclarativeElement<TagName extends CustomElementTa
     static readonly slotNames: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['slotNames'];
     abstract _lastRenderError: Error | undefined;
     abstract _internalRenderCount: number;
-    abstract _lastRenderedProps: Readonly<Pick<RenderParams<any, Inputs, StateInit, any, any, any, any>, 'inputs' | 'state'>>;
+    abstract _lastRenderedProps: Readonly<Pick<RenderParams<any, Inputs, State, any, any, any, any>, 'inputs' | 'state'>>;
     /**
      * Calls all destroy methods on all state properties, if they exist. This is automatically
      * called whenever the element is detached.
      */
     abstract destroy(): void;
     abstract render(): unknown;
-    abstract readonly instanceState: FlattenElementVirStateSetup<StateInit>;
-    abstract readonly observablePropertyListenerMap: ObservableListenerMap<StateInit & Inputs>;
+    abstract readonly instanceState: State;
+    abstract readonly observablePropertyListenerMap: ObservableListenerMap<State & Inputs>;
     abstract readonly instanceInputs: Inputs;
     /**
      * Used to assign inputs to the given element. This can be externally called as an API for
@@ -83,7 +81,7 @@ export declare abstract class DeclarativeElement<TagName extends CustomElementTa
     abstract assignInputs(inputs: EmptyObject extends Required<Inputs> ? never : Partial<Inputs>): void;
     abstract _haveInputsBeenSet: boolean;
     /** The element definition for this element instance. */
-    abstract readonly definition: DeclarativeElementDefinition<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+    abstract readonly definition: DeclarativeElementDefinition<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
 }
 /**
  * The assign inputs method of a declarative element.
@@ -96,20 +94,19 @@ export type AssignMethod<Inputs extends PropertyInitMapBase> = IsAny<Inputs> ext
  *
  * @category Internal
  */
-export type StaticDeclarativeElementProperties<TagName extends CustomElementTagName, Inputs extends PropertyInitMapBase, StateInit extends PropertyInitMapBase, EventsInit extends EventsInitMap, HostClassKeys extends BaseCssPropertyName<TagName>, CssVarKeys extends BaseCssPropertyName<TagName>, SlotNames extends ReadonlyArray<string>> = {
+export type StaticDeclarativeElementProperties<TagName extends CustomElementTagName, Inputs extends PropertyInitMapBase, State extends PropertyInitMapBase, EventsInit extends EventsInitMap, HostClassKeys extends BaseCssPropertyName<TagName>, CssVarKeys extends BaseCssPropertyName<TagName>, SlotNames extends ReadonlyArray<string>> = {
     /** Assign inputs to an element directly on its interpolated tag. */
     readonly assign: AssignMethod<Inputs>;
     assignedInputs: Inputs | undefined;
     /** Pass through the render callback for direct unit testability */
-    readonly render: RenderCallback<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+    readonly render: RenderCallback<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
     readonly events: EventDescriptorMap<TagName, EventsInit>;
-    readonly stateInitStatic: ElementPropertyDescriptorMap<StateInit>;
     readonly slotNames: SlotNameMap<SlotNames>;
-    readonly init: DeclarativeElementInit<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+    readonly init: DeclarativeElementInit<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
     readonly elementOptions: DeclarativeElementDefinitionOptions;
-    readonly inputsType: Inputs;
-    readonly stateType: Readonly<FlattenElementVirStateSetup<StateInit>>;
-    readonly updateStateType: UpdateStateCallback<StateInit>;
+    readonly InputsType: Inputs;
+    readonly StateType: Readonly<State>;
+    readonly UpdateStateType: UpdateStateCallback<State>;
     readonly hostClasses: HostClassNamesMap<string, HostClassKeys>;
     readonly cssVars: CssVars<TagName, CssVarKeys>;
     readonly tagName: string;

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

@@ -23,11 +23,10 @@ export class DeclarativeElement extends LitElement {
     static tagName;
     static styles;
     static render;
-    static inputsType;
-    static stateType;
-    static updateStateType;
+    static InputsType;
+    static StateType;
+    static UpdateStateType;
     static events;
-    static stateInitStatic;
     static init;
     static elementOptions;
     static hostClasses;

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

@@ -4,13 +4,6 @@ import { DeclarativeElementDefinition } from './declarative-element.js';
 import { BaseCssPropertyName } from './properties/css-properties.js';
 import { EventsInitMap } from './properties/element-events.js';
 import { PropertyInitMapBase } from './properties/element-properties.js';
-/**
- * Verifies that the given {@link DeclarativeElementInit} for an element definition without inputs
- * does not have any state properties that clash with built-in HTML element properties.
- *
- * @category Internal
- */
-export type VerifiedElementNoInputsInit<TagName extends CustomElementTagName, Inputs extends PropertyInitMapBase, StateInit extends PropertyInitMapBase, EventsInit extends EventsInitMap, HostClassKeys extends BaseCssPropertyName<TagName>, CssVarKeys extends BaseCssPropertyName<TagName>, SlotNames extends ReadonlyArray<string>> = Extract<keyof StateInit, keyof HTMLElement> extends never ? DeclarativeElementInit<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames> : 'ERROR: Cannot define an element state property that clashes with native HTMLElement properties.';
 /**
  * Defines an element without any inputs.
  *
@@ -30,4 +23,4 @@ export type VerifiedElementNoInputsInit<TagName extends CustomElementTagName, In
  * });
  * ```
  */
-export declare function defineElementNoInputs<const TagName extends CustomElementTagName = '-', Inputs extends PropertyInitMapBase = {}, StateInit extends PropertyInitMapBase = {}, EventsInit extends EventsInitMap = {}, const HostClassKeys extends BaseCssPropertyName<TagName> = `${TagName}-`, const CssVarKeys extends BaseCssPropertyName<TagName> = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = Readonly<[]>>(initInput: VerifiedElementNoInputsInit<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>): DeclarativeElementDefinition<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+export declare function defineElementNoInputs<const TagName extends CustomElementTagName = '-', Inputs extends PropertyInitMapBase = {}, State extends PropertyInitMapBase = {}, EventsInit extends EventsInitMap = {}, const HostClassKeys extends BaseCssPropertyName<TagName> = `${TagName}-`, const CssVarKeys extends BaseCssPropertyName<TagName> = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = Readonly<[]>>(init: DeclarativeElementInit<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>): DeclarativeElementDefinition<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;

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

@@ -33,9 +33,7 @@ import { createSlotNamesMap } from './slot-names.js';
  * });
  * ```
  */
-export function defineElementNoInputs(initInput) {
-    /** This as cast is safe only because of the following run-time type check. */
-    const init = initInput;
+export function defineElementNoInputs(init) {
     if (!check.isObject(init)) {
         throw new TypeError('Cannot define element with non-object init: ${init}');
     }
@@ -94,17 +92,20 @@ export function defineElementNoInputs(initInput) {
         static cssVars = cssVars;
         static init = init;
         static slotNames = slotNamesMap;
-        static stateInitStatic = init.stateInitStatic;
-        get instanceType() {
-            throw new Error(`"instanceType" was called on ${init.tagName} as a value but it is only for types.`);
+        get InstanceType() {
+            throw new Error(`'InstanceType' was called on ${init.tagName} as a value but it is only a type.`);
         }
-        static get inputsType() {
-            throw new Error(`"inputsType" was called on ${init.tagName} as a value but it is only for types.`);
+        static get InputsType() {
+            throw new Error(`'InputsType' was called on ${init.tagName} as a value but it is only a type.`);
         }
-        static get stateType() {
-            throw new Error(`"stateType" was called on ${init.tagName} as a value but it is only for types.`);
+        static get StateType() {
+            throw new Error(`'StateType' was called on ${init.tagName} as a value but it is only a type.`);
+        }
+        static get UpdateStateType() {
+            throw new Error(`'UpdateStateType' was called on ${init.tagName} as a value but it is only a type.`);
         }
         _initCalled = false;
+        _stateCalled = false;
         _hasRendered = false;
         _lastRenderedProps = undefined;
         _haveInputsBeenSet = false;
@@ -121,6 +122,17 @@ export function defineElementNoInputs(initInput) {
                 }
                 this._hasRendered = true;
                 const renderParams = this.createRenderParams();
+                if (!this._stateCalled && init.state) {
+                    this._stateCalled = true;
+                    const stateInit = init.state(renderParams);
+                    if (stateInit instanceof Promise) {
+                        throw new TypeError('init cannot be asynchronous');
+                    }
+                    getObjectTypedKeys(stateInit).forEach((stateKey) => {
+                        bindReactiveProperty(this, stateKey);
+                        this.instanceState[stateKey] = stateInit[stateKey];
+                    });
+                }
                 if (!this._initCalled && init.init) {
                     this._initCalled = true;
                     if (init.init(renderParams) instanceof Promise) {
@@ -189,13 +201,6 @@ export function defineElementNoInputs(initInput) {
         instanceState = createElementPropertyProxy(this, !elementOptions.allowPolymorphicState);
         constructor() {
             super();
-            const stateInitStatic = 
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            init.stateInitStatic || {};
-            getObjectTypedKeys(stateInitStatic).forEach((stateKey) => {
-                bindReactiveProperty(this, stateKey);
-                this.instanceState[stateKey] = stateInitStatic[stateKey];
-            });
             this.definition = anonymousClass;
         }
     };

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

@@ -1,17 +1,18 @@
 import { CustomElementTagName } from './custom-tag-name.js';
+import { DeclarativeElementInit } from './declarative-element-init.js';
 import { DeclarativeElementDefinition } from './declarative-element.js';
-import { VerifiedElementNoInputsInit } from './define-element-no-inputs.js';
 import { BaseCssPropertyName } from './properties/css-properties.js';
 import { EventsInitMap } from './properties/element-events.js';
 import { PropertyInitMapBase } from './properties/element-properties.js';
 /**
- * Verifies that the given {@link DeclarativeElementInit} for an element definition with inputs does
- * not have any state or input properties that clash with built-in HTML element properties, or state
- * / input properties that clash with each other.
+ * Verifies that the given `Inputs` type does not clash with built-in HTMLElement properties. This
+ * is used within {@link defineElement}.
  *
  * @category Internal
  */
-export type VerifiedElementInit<TagName extends CustomElementTagName, Inputs extends PropertyInitMapBase, StateInit extends PropertyInitMapBase, EventsInit extends EventsInitMap, HostClassKeys extends BaseCssPropertyName<TagName>, CssVarKeys extends BaseCssPropertyName<TagName>, SlotNames extends ReadonlyArray<string>> = Extract<keyof StateInit, keyof Inputs> extends never ? Extract<keyof Inputs, keyof HTMLElement> extends never ? VerifiedElementNoInputsInit<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames> : 'ERROR: Cannot define an element input property that clashes with native HTMLElement properties.' : "ERROR: Cannot define an element state property that clashes with the element's input properties.";
+export type DeclarativeElementInputErrorParams<Inputs extends PropertyInitMapBase> = Extract<keyof Inputs, keyof HTMLElement> extends never ? [] : [
+    'ERROR: Cannot define an element input property that clashes with native HTMLElement properties.'
+];
 /**
  * Defines an element with inputs. If the element actually has no inputs, use
  * {@link defineElementNoInputs} instead. Note that this function must be called twice, due to
@@ -33,4 +34,9 @@ export type VerifiedElementInit<TagName extends CustomElementTagName, Inputs ext
  * });
  * ```
  */
-export declare function defineElement<Inputs extends PropertyInitMapBase = {}>(): <const TagName extends CustomElementTagName, StateInit extends PropertyInitMapBase = {}, EventsInit extends EventsInitMap = {}, const HostClassKeys extends BaseCssPropertyName<TagName> = `${TagName}-`, const CssVarKeys extends BaseCssPropertyName<TagName> = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = readonly []>(initInput: VerifiedElementInit<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>) => DeclarativeElementDefinition<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+export declare function defineElement<Inputs extends PropertyInitMapBase = {}>(
+/**
+ * These `errorParams` is present when there are problems with the `Inputs` type. If it is
+ * present, the error should be fixed. This should always be empty.
+ */
+...errorParams: DeclarativeElementInputErrorParams<Inputs>): <const TagName extends CustomElementTagName, State extends PropertyInitMapBase = {}, EventsInit extends EventsInitMap = {}, const HostClassKeys extends BaseCssPropertyName<TagName> = `${TagName}-`, const CssVarKeys extends BaseCssPropertyName<TagName> = `${TagName}-`, const SlotNames extends ReadonlyArray<string> = Readonly<[]>>(initInput: DeclarativeElementInit<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>) => DeclarativeElementDefinition<TagName, Inputs, State, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;

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

@@ -1,5 +1,5 @@
 /* eslint-disable @typescript-eslint/no-empty-object-type */
-import { check } from '@augment-vir/assert';
+import { assert, check } from '@augment-vir/assert';
 import { defineElementNoInputs } from './define-element-no-inputs.js';
 /**
  * Defines an element with inputs. If the element actually has no inputs, use
@@ -22,7 +22,13 @@ import { defineElementNoInputs } from './define-element-no-inputs.js';
  * });
  * ```
  */
-export function defineElement() {
+export function defineElement(
+/**
+ * These `errorParams` is present when there are problems with the `Inputs` type. If it is
+ * present, the error should be fixed. This should always be empty.
+ */
+...errorParams) {
+    assert.isEmpty(errorParams);
     return (initInput) => {
         const init = initInput;
         if (!check.isObject(init)) {

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

@@ -2,7 +2,7 @@ import type { EmptyObject } from 'type-fest';
 import { DirectiveResult } from '../../lit-exports/all-lit-exports.js';
 import { PropertyInitMapBase } from '../properties/element-properties.js';
 export type ElementDefinitionWithInputsType<InputsType extends PropertyInitMapBase = PropertyInitMapBase> = {
-    inputsType: InputsType;
+    InputsType: InputsType;
 };
 /**
  * Assign an object matching an element's inputs to its inputs.
@@ -12,7 +12,7 @@ export type ElementDefinitionWithInputsType<InputsType extends PropertyInitMapBa
  * @example Html`<${MyElement} ${assign(MyElement, {value: 1})}>...` should be
  * html`<${MyElement.assign({value: 1})}>...`
  */
-export declare function assign<const SpecificDeclarativeElement extends ElementDefinitionWithInputsType>(declarativeElement: SpecificDeclarativeElement, inputsObject: EmptyObject extends Required<SpecificDeclarativeElement['inputsType']> ? never : SpecificDeclarativeElement['inputsType']): DirectiveResult;
+export declare function assign<const SpecificDeclarativeElement extends ElementDefinitionWithInputsType>(declarativeElement: SpecificDeclarativeElement, inputsObject: EmptyObject extends Required<SpecificDeclarativeElement['InputsType']> ? never : SpecificDeclarativeElement['InputsType']): DirectiveResult;
 /**
  * Assign an object matching an element's inputs to its inputs.
  *
@@ -21,4 +21,4 @@ export declare function assign<const SpecificDeclarativeElement extends ElementD
  * @example Html`<${MyElement} ${assign(MyElement, {value: 1})}>...` should be
  * html`<${MyElement.assign({value: 1})}>...`
  */
-export declare function assign<const SpecificDeclarativeElement extends ElementDefinitionWithInputsType, const SpecificInput extends SpecificDeclarativeElement['inputsType']>(inputsObject: SpecificInput extends typeof HTMLElement ? never : SpecificInput): DirectiveResult;
+export declare function assign<const SpecificDeclarativeElement extends ElementDefinitionWithInputsType, const SpecificInput extends SpecificDeclarativeElement['InputsType']>(inputsObject: SpecificInput extends typeof HTMLElement ? never : SpecificInput): DirectiveResult;

package/dist/declarative-element/directives/async-prop.d.ts

@@ -1,27 +1,74 @@
-import { CallbackObservable, CallbackObservableInit } from 'observavir';
-import { Constructor } from 'type-fest';
-import { ElementVirStateSetup } from '../properties/element-vir-state-setup.js';
+import type { Overwrite } from '@augment-vir/common';
+import { CallbackObservable, CallbackObservableInit, type AsyncValue } from 'observavir';
 export type { AsyncValue } from 'observavir';
-/** Class for constructing async props. Should not be referenced directly, use `AsyncProp` instead. */
-declare class InternalAsyncPropClass<Value, Params> extends CallbackObservable<Value, Params> {
+/**
+ * The current state of an {@link AsyncProp}'s value.
+ *
+ * @category Internal
+ */
+export declare enum AsyncValueState {
+    /** The `.value` Promise has been rejected. */
+    Rejected = "rejected",
+    /** The `.value` Promise has not settled yet. */
+    Waiting = "waiting",
+    /** The `.value` Promise has been resolved into an awaited value. */
+    Resolved = "resolved"
 }
 /**
- * An async property created by {@link asyncProp} for use within declarative elements.
+ * Class for constructing async props. Do not use this directly as its internal types won't be
+ * inferred correctly. Instead use {@link asyncProp} an async prop or {@link AsyncProp} for types.
  *
  * @category Internal
  */
-export type AsyncProp<Value, Params> = Omit<InternalAsyncPropClass<Value, Params>, 
-/** Hide these properties to make the `AsyncProp` interface much simpler. */
-'dispatch' | 'equalityCheck' | 'getListenerCount' | 'updateCallback' | 'removeListener' | 'removeAllListeners' | 'listenToEvent' | 'listen'>;
+export declare class InternalAsyncPropClass<Value, Params> extends CallbackObservable<Value, Params> {
+    /**
+     * The current `.value` if it has settled (into either a resolved value or an Error), or
+     * `undefined` if it has not.
+     */
+    get resolvedValue(): Exclude<typeof this.value, Promise<any>> | undefined;
+    /** The state of the current `.value`. */
+    get state(): AsyncValueState;
+    /**
+     * Checks if the current `.value` has resolved (meaning the Promise has settled and it was not
+     * rejected). This type guards the current instance's `.value` property.
+     */
+    isResolved(): this is Overwrite<this, {
+        value: Exclude<AsyncValue<Value>, Promise<any> | Error>;
+    }>;
+    /**
+     * Checks if the current `.value` has settled (meaning it is either a rejection error or a
+     * resolved value). This type guards the current instance's `.value` property.
+     */
+    isSettled(): this is Overwrite<this, {
+        value: Exclude<AsyncValue<Value>, Promise<any>>;
+    }>;
+    /**
+     * Checks if the current `.value` has not settled yet settled (meaning it is still an unsettled
+     * Promise). This type guards the current instance's `.value` property.
+     */
+    isWaiting(): this is Overwrite<this, {
+        value: Extract<AsyncValue<Value>, Promise<any> | Error>;
+    }>;
+    /**
+     * Checks if the current `.value` is a rejection error. This type guards the current instance's
+     * `.value` property.
+     */
+    isError(): this is Overwrite<this, {
+        value: Extract<AsyncValue<Value>, Error>;
+    }>;
+}
 /**
- * An async property created by {@link asyncProp} for use within declarative elements.
+ * An async property created by {@link asyncProp} for use within declarative elements. Do not use
+ * this directly as its internal types won't be inferred correctly.
  *
  * @category Internal
  */
-export declare const AsyncProp: Constructor<AsyncProp<unknown, unknown>, ConstructorParameters<typeof InternalAsyncPropClass<unknown, unknown>>>;
+export type AsyncProp<Value, Params> = Omit<InternalAsyncPropClass<Value, Params>, 
+/** Hide these properties to make the `AsyncProp` interface much simpler. */
+'dispatch' | 'equalityCheck' | 'getListenerCount' | 'updateCallback' | 'removeListener' | 'removeAllListeners' | 'listenToEvent' | 'listen'>;
 /**
  * Create an async prop for a declarative element's state.
  *
  * @category Async
  */
-export declare function asyncProp<Value, Params = void>(init?: CallbackObservableInit<Value, Params>): ElementVirStateSetup<AsyncProp<Value, Params>>;
+export declare function asyncProp<Value, Params = void>(init?: CallbackObservableInit<Value, Params>): AsyncProp<Value, Params>;