element-vir 22.2.2 → 23.1.0

package/README.md

@@ -36,7 +36,7 @@ All of [`lit`](https://lit.dev)'s syntax and functionality is available for use
 
 ## Simple element definition
 
-Use `defineElementNoInputs` to define your element if it's not going to accept any inputs (or if you're just getting started). It's only input is 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 if you're just getting started). It's only input is an object with at least `tagName` and `render` properties (the types enforce this). Here is a bare-minimum example custom element:
 
 <!-- example-link: src/readme-examples/my-simple.element.ts -->
 
@@ -45,7 +45,7 @@ import {defineElementNoInputs, html} from 'element-vir';
 
 export const MySimple = defineElementNoInputs({
     tagName: 'my-simple',
-    renderCallback() {
+    render() {
         return html`
             <span>Hello there!</span>
         `;
@@ -63,11 +63,11 @@ To use already defined elements (like the example above), they must be interpola
 
 ```TypeScript
 import {defineElementNoInputs, html} from 'element-vir';
-import {MySimple} from './my-simple.element';
+import {MySimple} from './my-simple.element.js';
 
 export const MyApp = defineElementNoInputs({
     tagName: 'my-app',
-    renderCallback() {
+    render() {
         return html`
             <h1>My App</h1>
             <${MySimple}></${MySimple}>
@@ -100,7 +100,7 @@ export const MyWithStyles = defineElementNoInputs({
             margin-top: 16px;
         }
     `,
-    renderCallback() {
+    render() {
         return html`
             <span>Hello there!</span>
             <span>How are you doing?</span>
@@ -117,7 +117,7 @@ Declarative element definitions can be used in the `css` tagged template just li
 
 ```TypeScript
 import {css, defineElementNoInputs, html} from 'element-vir';
-import {MySimple} from './my-simple.element';
+import {MySimple} from './my-simple.element.js';
 
 export const MyWithStylesAndInterpolatedSelector = defineElementNoInputs({
     tagName: 'my-with-styles-and-interpolated-selector',
@@ -126,7 +126,7 @@ export const MyWithStylesAndInterpolatedSelector = defineElementNoInputs({
             background-color: blue;
         }
     `,
-    renderCallback() {
+    render() {
         return html`
             <${MySimple}></${MySimple}>
         `;
@@ -138,7 +138,7 @@ export const MyWithStylesAndInterpolatedSelector = defineElementNoInputs({
 
 Define element inputs by using `defineElement` to define a declarative element. Pass your input type as a generic to the `defineElement` call. Then call _that_ with the normal definition input (like when using `defineElementNoInputs`).
 
-To use an element's inputs for use in its template, grab `inputs` from `renderCallback`'s parameters and interpolate it into your HTML template:
+To use an element's inputs for use in its template, grab `inputs` from `render`'s parameters and interpolate it into your HTML template:
 
 <!-- example-link: src/readme-examples/my-with-inputs.element.ts -->
 
@@ -150,7 +150,7 @@ export const MyWithInputs = defineElement<{
     email: string;
 }>()({
     tagName: 'my-with-inputs',
-    renderCallback({inputs}) {
+    render({inputs}) {
         return html`
             <span>Hello there ${inputs.username}!</span>
         `;
@@ -160,7 +160,7 @@ export const MyWithInputs = defineElement<{
 
 ## Defining internal state
 
-Define initial internal state values and types with the `stateInit` property when defining an element. Grab it with `state` in `renderCallback` to use state. Grab `updateState` in `renderCallback` to update state:
+Define initial internal state values and types with the `stateInit` property when defining an element. Grab it with `state` in `render` to use state. Grab `updateState` in `render` to update state:
 
 <!-- example-link: src/readme-examples/my-with-update-state.element.ts -->
 
@@ -177,7 +177,7 @@ export const MyWithUpdateState = defineElementNoInputs({
          */
         email: undefined as string | undefined,
     },
-    renderCallback({state, updateState}) {
+    render({state, updateState}) {
         return html`
             <span
                 ${listen('click', () => {
@@ -199,11 +199,11 @@ Use the `assign` directive to assign values to child custom elements inputs:
 
 ```TypeScript
 import {defineElementNoInputs, html} from 'element-vir';
-import {MyWithInputs} from './my-with-inputs.element';
+import {MyWithInputs} from './my-with-inputs.element.js';
 
 export const MyWithAssignment = defineElementNoInputs({
     tagName: 'my-with-assignment',
-    renderCallback() {
+    render() {
         return html`
             <h1>My App</h1>
             <${MyWithInputs.assign({
@@ -219,8 +219,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.
 
--   `initCallback`: 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.)
--   `cleanupCallback`: 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 -->
 
@@ -232,17 +232,17 @@ export const MyWithAssignmentCleanupCallback = defineElementNoInputs({
     stateInitStatic: {
         intervalId: undefined as undefined | number,
     },
-    initCallback: ({updateState}) => {
+    init: ({updateState}) => {
         updateState({
             intervalId: window.setInterval(() => console.info('hi'), 1000),
         });
     },
-    renderCallback() {
+    render() {
         return html`
             <h1>My App</h1>
         `;
     },
-    cleanupCallback: ({state, updateState}) => {
+    cleanup: ({state, updateState}) => {
         window.clearInterval(state.intervalId);
         updateState({
             intervalId: undefined,
@@ -255,11 +255,12 @@ export const MyWithAssignmentCleanupCallback = defineElementNoInputs({
 
 When defining a declarative element, use `events` to setup event names and types. Each event must be initialized with `defineElementEvent` and a type parameter but no run-time inputs.
 
-To dispatch an event, grab `dispatch` and `events` from `renderCallback`'s parameters.
+To dispatch an event, grab `dispatch` and `events` from `render`'s parameters.
 
 <!-- example-link: src/readme-examples/my-with-events.element.ts -->
 
 ```TypeScript
+import {randomInteger} from '@augment-vir/common';
 import {defineElementEvent, defineElementNoInputs, html, listen} from 'element-vir';
 
 export const MyWithEvents = defineElementNoInputs({
@@ -268,10 +269,14 @@ export const MyWithEvents = defineElementNoInputs({
         logoutClick: defineElementEvent<void>(),
         randomNumber: defineElementEvent<number>(),
     },
-    renderCallback({dispatch, events}) {
+    render({dispatch, events}) {
         return html`
             <button ${listen('click', () => dispatch(new events.logoutClick()))}>log out</button>
-            <button ${listen('click', () => dispatch(new events.randomNumber(Math.random())))}>
+            <button
+                ${listen('click', () =>
+                    dispatch(new events.randomNumber(randomInteger({min: 0, max: 1_000_000}))),
+                )}
+            >
                 generate random number
             </button>
         `;
@@ -287,14 +292,14 @@ Use the `listen` directive to listen to events emitted by your custom elements:
 
 ```TypeScript
 import {defineElementNoInputs, html, listen} from 'element-vir';
-import {MyWithEvents} from './my-with-events.element';
+import {MyWithEvents} from './my-with-events.element.js';
 
 export const MyWithEventListening = defineElementNoInputs({
     tagName: 'my-with-event-listening',
     stateInitStatic: {
         myNumber: -1,
     },
-    renderCallback({state, updateState}) {
+    render({state, updateState}) {
         return html`
             <h1>My App</h1>
             <${MyWithEvents}
@@ -332,12 +337,13 @@ Dispatching a custom event and listening to a custom event is the same as doing
 <!-- example-link: src/readme-examples/my-with-custom-events.element.ts -->
 
 ```TypeScript
+import {randomInteger} from '@augment-vir/common';
 import {defineElementNoInputs, html, listen} from 'element-vir';
-import {MyCustomActionEvent} from './my-custom-action.event';
+import {MyCustomActionEvent} from './my-custom-action.event.js';
 
 export const MyWithCustomEvents = defineElementNoInputs({
     tagName: 'my-with-custom-events',
-    renderCallback({dispatch}) {
+    render({dispatch}) {
         return html`
             <div
                 ${listen(MyCustomActionEvent, (event) => {
@@ -346,7 +352,7 @@ export const MyWithCustomEvents = defineElementNoInputs({
             >
                 <div
                     ${listen('click', () => {
-                        dispatch(new MyCustomActionEvent(Math.random()));
+                        dispatch(new MyCustomActionEvent(randomInteger({min: 0, max: 1_000_000})));
                     })}
                 ></div>
             </div>
@@ -361,10 +367,10 @@ export const MyWithCustomEvents = defineElementNoInputs({
 
 Host classes can be defined and used with type safety. Host classes are used to provide alternative styles for custom elements. They are purely driven by CSS and are thus applied to the the `class` HTML attribute.
 
-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 teh host class:
+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:
 
@@ -386,7 +392,7 @@ export const MyWithHostClassDefinition = defineElementNoInputs({
         'my-with-host-class-definition-a': false,
         /**
          * This host class will be automatically applied if the given callback is evaluated to true
-         * after a call to renderCallback.
+         * after a call to render.
          */
         'my-with-host-class-definition-automatic': ({state}) => {
             return state.myProp === 'foo';
@@ -405,7 +411,7 @@ export const MyWithHostClassDefinition = defineElementNoInputs({
             color: red;
         }
     `,
-    renderCallback({state}) {
+    render({state}) {
         return html`
             ${state.myProp}
         `;
@@ -421,11 +427,11 @@ To apply a host class in a consumer, access the child element's `.hostClasses` p
 
 ```TypeScript
 import {defineElementNoInputs, html} from 'element-vir';
-import {MyWithHostClassDefinition} from './my-with-host-class-definition.element';
+import {MyWithHostClassDefinition} from './my-with-host-class-definition.element.js';
 
 export const MyWithHostClassUsage = defineElementNoInputs({
     tagName: 'my-with-host-class-usage',
-    renderCallback() {
+    render() {
         return html`
             <${MyWithHostClassDefinition}
                 class=${MyWithHostClassDefinition.hostClasses['my-with-host-class-definition-a']}
@@ -463,7 +469,7 @@ export const MyWithCssVars = defineElementNoInputs({
             color: ${cssVars['my-with-css-vars-my-var'].value};
         }
     `,
-    renderCallback() {
+    render() {
         return html``;
     },
 });
@@ -526,7 +532,7 @@ import {defineElementNoInputs, html, onDomCreated} from 'element-vir';
 
 export const MyWithOnDomCreated = defineElementNoInputs({
     tagName: 'my-with-on-dom-created',
-    renderCallback() {
+    render() {
         return html`
             <span
                 ${onDomCreated((element) => {
@@ -552,7 +558,7 @@ import {defineElementNoInputs, html, onResize} from 'element-vir';
 
 export const MyWithOnResize = defineElementNoInputs({
     tagName: 'my-with-on-resize',
-    renderCallback() {
+    render() {
         return html`
             <span
                 ${onResize((entry) => {
@@ -583,7 +589,7 @@ import {defineElement, html, renderIf} from 'element-vir';
 
 export const MyWithRenderIf = defineElement<{shouldRender: boolean}>()({
     tagName: 'my-with-render-if',
-    renderCallback({inputs}) {
+    render({inputs}) {
         return html`
             ${renderIf(
                 inputs.shouldRender,
@@ -630,7 +636,7 @@ export const MyWithAsyncProp = defineElement<{endpoint: string}>()({
             },
         }),
     },
-    renderCallback({inputs, state}) {
+    render({inputs, state}) {
         /**
          * This causes the a promise which automatically updates the state.data prop once the
          * promise resolves. It only creates a new promise if the first input, the trigger, value

package/dist/declarative-element/custom-tag-name.d.ts

@@ -1 +1,7 @@
+/**
+ * The spec-required type for all custom tag names (they must contain a hyphen).
+ *
+ * @category Internal
+ * @see https://developer.mozilla.org/docs/Web/API/Web_components/Using_custom_elements#name
+ */
 export type CustomElementTagName = `${string}-${string}`;

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

@@ -1,13 +1,19 @@
-import { CSSResult } from '../lit-exports/all-lit-exports';
-import { CustomElementTagName } from './custom-tag-name';
-import { DeclarativeElementDefinitionOptions } from './definition-options';
-import { BaseCssPropertyName } from './properties/css-properties';
-import { CssVarsInitMap } from './properties/css-vars';
-import { EventsInitMap } from './properties/element-events';
-import { PropertyInitMapBase } from './properties/element-properties';
-import { HostClassesInitMap } from './properties/host-classes';
-import { StylesCallback } from './properties/styles';
-import { InitCallback, RenderCallback } from './render-callback';
+import { type CSSResult } from '../lit-exports/base-lit-exports.js';
+import { type CustomElementTagName } from './custom-tag-name.js';
+import { type DeclarativeElementDefinitionOptions } from './definition-options.js';
+import { type BaseCssPropertyName } from './properties/css-properties.js';
+import { type CssVarsInitMap } from './properties/css-vars.js';
+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';
+/**
+ * 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>> = {
     /**
      * HTML tag name. This should not be used directly, as interpolating it with the html tagged
@@ -39,9 +45,9 @@ 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>;
-    /** Called as part of the first renderCallback call, before the first renderCallback call. */
-    initCallback?: InitCallback<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
-    renderCallback: RenderCallback<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
-    cleanupCallback?: InitCallback<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+    /** 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>;
     options?: Partial<DeclarativeElementDefinitionOptions> | undefined;
 };

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

@@ -1,30 +1,58 @@
-import { RequiredAndNotNullBy } from '@augment-vir/common';
-import { IsAny, IsEmptyObject } from 'type-fest';
-import { CSSResult, LitElement } from '../lit-exports/all-lit-exports';
-import { MinimalDefinitionWithInputs } from '../template-transforms/minimal-element-definition';
-import { CustomElementTagName } from './custom-tag-name';
-import { DeclarativeElementInit } from './declarative-element-init';
-import { DeclarativeElementDefinitionOptions } from './definition-options';
-import { BaseCssPropertyName } from './properties/css-properties';
-import { CssVars } from './properties/css-vars';
-import { EventDescriptorMap, EventsInitMap } from './properties/element-events';
-import { ElementPropertyDescriptorMap, PropertyInitMapBase } from './properties/element-properties';
-import { FlattenElementVirStateSetup } from './properties/element-vir-state-setup';
-import { HostClassNamesMap } from './properties/host-classes';
-import { ObservableListenerMap } from './properties/property-proxy';
-import type { RenderCallback, RenderParams, UpdateStateCallback } from './render-callback';
-import { SlotNameMap } from './slot-names';
-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> = RequiredAndNotNullBy<Omit<DeclarativeElement<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>, Exclude<keyof StaticDeclarativeElementProperties<any, any, any, any, any, any, any>, keyof HTMLElement>>, 'shadowRoot'>;
+import { type SetRequiredAndNotNull } from '@augment-vir/common';
+import { type EmptyObject, type IsAny, type IsEmptyObject } from 'type-fest';
+import { LitElement, type CSSResult } from '../lit-exports/base-lit-exports.js';
+import { type MinimalDefinitionWithInputs } from '../template-transforms/minimal-element-definition.js';
+import { type CustomElementTagName } from './custom-tag-name.js';
+import { type DeclarativeElementInit } from './declarative-element-init.js';
+import { type DeclarativeElementDefinitionOptions } from './definition-options.js';
+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 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';
+import { type SlotNameMap } from './slot-names.js';
+/**
+ * The `host` type for a declarative element. This references a declarative element instance's
+ * top-level HTML element and always contains a shadow root (wherein the element is rendered).
+ *
+ * @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'>;
+/**
+ * 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>;
 };
+/**
+ * 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 {
-    static assign: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['assign'];
-    static assignedInputs: PropertyInitMapBase | undefined;
+    /**
+     * Assign inputs to an element instantiation. Use only on the opening tag.
+     *
+     * @example
+     *
+     * ```ts
+     * import {html} from 'element-vir';
+     *
+     * const myTemplate = html`
+     *     <${MyElement.assign({input1: 'a', input2: 'b'})}></${MyElement}>
+     * `;
+     * ```
+     */
+    static readonly assign: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['assign'];
+    static readonly assignedInputs: PropertyInitMapBase | undefined;
     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 isStrictInstance: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['isStrictInstance'];
-    static readonly renderCallback: StaticDeclarativeElementProperties<CustomElementTagName, PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, BaseCssPropertyName<CustomElementTagName>, BaseCssPropertyName<CustomElementTagName>, ReadonlyArray<string>>['renderCallback'];
+    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'];
@@ -38,23 +66,42 @@ export declare abstract class DeclarativeElement<TagName extends CustomElementTa
     abstract _lastRenderError: Error | undefined;
     abstract _internalRenderCount: number;
     abstract _lastRenderedProps: Readonly<Pick<RenderParams<any, Inputs, StateInit, 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 instanceInputs: Inputs;
-    abstract assignInputs(inputs: {} extends Required<Inputs> ? never : Partial<Inputs>): void;
+    /**
+     * Used to assign inputs to the given element. This can be externally called as an API for
+     * setting inputs on an element reference, though this is discouraged. Inputs should typically
+     * be called using the `.assign()` method on an element definition inside of an HTML template.
+     */
+    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>;
 }
+/**
+ * The assign inputs method of a declarative element.
+ *
+ * @category Internal
+ */
 export type AssignMethod<Inputs extends PropertyInitMapBase> = IsAny<Inputs> extends true ? any : IsEmptyObject<Required<Inputs>> extends true ? (inputsObject: never) => never : (inputsObject: IsEmptyObject<Required<Inputs>> extends true ? never : Inputs) => MinimalDefinitionWithInputs;
+/**
+ * All static properties on a declarative element. These all come from the element's definition.
+ *
+ * @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>> = {
     /** 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 renderCallback: RenderCallback<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
+    readonly render: RenderCallback<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
     readonly events: EventDescriptorMap<TagName, EventsInit>;
     readonly stateInitStatic: ElementPropertyDescriptorMap<StateInit>;
     readonly slotNames: SlotNameMap<SlotNames>;
@@ -63,7 +110,6 @@ export type StaticDeclarativeElementProperties<TagName extends CustomElementTagN
     readonly inputsType: Inputs;
     readonly stateType: Readonly<FlattenElementVirStateSetup<StateInit>>;
     readonly updateStateType: UpdateStateCallback<StateInit>;
-    readonly isStrictInstance: (element: unknown) => element is DeclarativeElement<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, SlotNames>;
     readonly hostClasses: HostClassNamesMap<string, HostClassKeys>;
     readonly cssVars: CssVars<TagName, CssVarKeys>;
     readonly tagName: string;

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

@@ -1,3 +1,36 @@
-import { LitElement } from '../lit-exports/all-lit-exports';
+import { LitElement } from '../lit-exports/base-lit-exports.js';
+/**
+ * Abstract class base for all declarative elements.
+ *
+ * @category Internal
+ */
 export class DeclarativeElement extends LitElement {
+    /**
+     * Assign inputs to an element instantiation. Use only on the opening tag.
+     *
+     * @example
+     *
+     * ```ts
+     * import {html} from 'element-vir';
+     *
+     * const myTemplate = html`
+     *     <${MyElement.assign({input1: 'a', input2: 'b'})}></${MyElement}>
+     * `;
+     * ```
+     */
+    static assign;
+    static assignedInputs;
+    static tagName;
+    static styles;
+    static render;
+    static inputsType;
+    static stateType;
+    static updateStateType;
+    static events;
+    static stateInitStatic;
+    static init;
+    static elementOptions;
+    static hostClasses;
+    static cssVars;
+    static slotNames;
 }

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

@@ -1,8 +1,33 @@
-import { CustomElementTagName } from './custom-tag-name';
-import { DeclarativeElementDefinition } from './declarative-element';
-import { DeclarativeElementInit } from './declarative-element-init';
-import { BaseCssPropertyName } from './properties/css-properties';
-import { EventsInitMap } from './properties/element-events';
-import { PropertyInitMapBase } from './properties/element-properties';
+import { CustomElementTagName } from './custom-tag-name.js';
+import { DeclarativeElementInit } from './declarative-element-init.js';
+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.
+ *
+ * @category Element Definition
+ * @example
+ *
+ * ```ts
+ * import {defineElementNoInputs, html} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <p>hi</p>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
 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>;