element-vir 22.2.2 → 23.1.0

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

@@ -1,12 +1,27 @@
 import { CallbackObservable, CallbackObservableInit } from 'observavir';
 import { Constructor } from 'type-fest';
-import { ElementVirStateSetup } from '../properties/element-vir-state-setup';
+import { ElementVirStateSetup } from '../properties/element-vir-state-setup.js';
 export type { AsyncValue } from 'observavir';
 /** Class for constructing async props. Should not be referenced directly, use `AsyncProp` instead. */
-declare class _AsyncPropClass<Value, Params> extends CallbackObservable<Value, Params> {
+declare class InternalAsyncPropClass<Value, Params> extends CallbackObservable<Value, Params> {
 }
-export type AsyncProp<Value, Params> = Omit<_AsyncPropClass<Value, Params>, 
+/**
+ * An async property created by {@link asyncProp} for use within declarative elements.
+ *
+ * @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 const AsyncProp: Constructor<AsyncProp<unknown, unknown>, ConstructorParameters<typeof _AsyncPropClass<unknown, unknown>>>;
+/**
+ * An async property created by {@link asyncProp} for use within declarative elements.
+ *
+ * @category Internal
+ */
+export declare const AsyncProp: Constructor<AsyncProp<unknown, unknown>, ConstructorParameters<typeof InternalAsyncPropClass<unknown, unknown>>>;
+/**
+ * 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>>;

package/dist/declarative-element/directives/async-prop.js

@@ -1,13 +1,23 @@
 import { CallbackObservable } from 'observavir';
-import { stateSetupKey } from '../properties/element-vir-state-setup';
+import { stateSetupKey } from '../properties/element-vir-state-setup.js';
 /** Class for constructing async props. Should not be referenced directly, use `AsyncProp` instead. */
-class _AsyncPropClass extends CallbackObservable {
+class InternalAsyncPropClass extends CallbackObservable {
 }
-export const AsyncProp = _AsyncPropClass;
+/**
+ * An async property created by {@link asyncProp} for use within declarative elements.
+ *
+ * @category Internal
+ */
+export const AsyncProp = InternalAsyncPropClass;
+/**
+ * Create an async prop for a declarative element's state.
+ *
+ * @category Async
+ */
 export function asyncProp(init) {
     return {
         [stateSetupKey]() {
-            return new _AsyncPropClass(init);
+            return new InternalAsyncPropClass(init);
         },
     };
 }

package/dist/declarative-element/directives/create-attribute-directive.d.ts

@@ -1,13 +1,28 @@
-import { PartInfo } from '../../lit-exports/all-lit-exports';
+import { PartInfo } from '../../lit-exports/all-lit-exports.js';
+/**
+ * Creates a lit directive that used simply for setting attributes on its parent element.
+ *
+ * @category Internal
+ */
 export declare function createAttributeDirective(attributeName: string): {
-    attributeSelector(attributeValue: string): string;
-    attributeDirective(attributeValue: string): import("lit-html/directive").DirectiveResult<{
+    /**
+     * Creates a string for use with the
+     * [`querySelector`](https://developer.mozilla.org/docs/Web/API/Document/querySelector) API
+     * that selects this directive's attribute set to the given `attributeValue`.
+     */
+    attributeSelector(this: void, attributeValue: string): string;
+    /**
+     * Instantiates the attribute directive. This must be used on an element inside of an HTML
+     * template.
+     */
+    attributeDirective(this: void, attributeValue: string): import("lit-html/directive.js").DirectiveResult<{
         new (partInfo: PartInfo): {
             readonly element: Element;
             render(attributeValue: string): symbol;
             readonly _$isConnected: boolean;
-            update(_part: import("lit-html").Part, props: unknown[]): unknown;
+            update(_part: import("lit-html").Part, props: Array<unknown>): unknown;
         };
     }>;
+    /** The name of the attribute used in the directive. */
     attributeName: string;
 };

package/dist/declarative-element/directives/create-attribute-directive.js

@@ -1,17 +1,17 @@
-import { directive, Directive, noChange } from '../../lit-exports/all-lit-exports';
-import { extractElement } from './directive-helpers';
+import { directive, Directive, noChange } from '../../lit-exports/all-lit-exports.js';
+import { extractElement } from './directive-helpers.js';
+/**
+ * Creates a lit directive that used simply for setting attributes on its parent element.
+ *
+ * @category Internal
+ */
 export function createAttributeDirective(attributeName) {
     const newDirective = directive(
     /** @internal */
     class extends Directive {
+        element;
         constructor(partInfo) {
             super(partInfo);
-            Object.defineProperty(this, "element", {
-                enumerable: true,
-                configurable: true,
-                writable: true,
-                value: void 0
-            });
             this.element = extractElement(partInfo, attributeName);
         }
         render(attributeValue) {
@@ -20,12 +20,22 @@ export function createAttributeDirective(attributeName) {
         }
     });
     return {
+        /**
+         * Creates a string for use with the
+         * [`querySelector`](https://developer.mozilla.org/docs/Web/API/Document/querySelector) API
+         * that selects this directive's attribute set to the given `attributeValue`.
+         */
         attributeSelector(attributeValue) {
             return `[${attributeName}="${attributeValue}"]`;
         },
+        /**
+         * Instantiates the attribute directive. This must be used on an element inside of an HTML
+         * template.
+         */
         attributeDirective(attributeValue) {
             return newDirective(attributeValue);
         },
+        /** The name of the attribute used in the directive. */
         attributeName,
     };
 }

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

@@ -1,6 +1,11 @@
-import { ElementPartInfo, PartInfo } from '../../lit-exports/all-lit-exports';
-/** For some reason these aren't defined in lit's types already. */
-export type ExtraPartInfoProperties = {
+import { ElementPartInfo, PartInfo } from '../../lit-exports/all-lit-exports.js';
+/**
+ * The full type for `ElementPartInfo` because `lit`'s built-in type leaves out of most of its
+ * interface.
+ *
+ * @category Internal
+ */
+export type FullElementPartInfo = ElementPartInfo /** For some reason these aren't defined in lit's types already, even though they _do_ exist. */ & {
     element: Element;
     options: {
         host: Element;
@@ -8,5 +13,15 @@ export type ExtraPartInfoProperties = {
         isConnected: boolean;
     };
 };
+/**
+ * Extracts the element from the given part info. Used in lit directives.
+ *
+ * @category Internal
+ */
 export declare function extractElement(partInfo: PartInfo, directiveName: string): Element;
-export declare function assertIsElementPartInfo(partInfo: PartInfo, directiveName: string): asserts partInfo is ElementPartInfo & ExtraPartInfoProperties;
+/**
+ * Asserts that the given part info is an instance of {@link FullElementPartInfo}.
+ *
+ * @category Internal
+ */
+export declare function assertIsElementPartInfo(partInfo: PartInfo, directiveName: string): asserts partInfo is FullElementPartInfo;

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

@@ -1,4 +1,9 @@
-import { PartType } from '../../lit-exports/all-lit-exports';
+import { PartType } from '../../lit-exports/all-lit-exports.js';
+/**
+ * Extracts the element from the given part info. Used in lit directives.
+ *
+ * @category Internal
+ */
 export function extractElement(partInfo, directiveName) {
     assertIsElementPartInfo(partInfo, directiveName);
     const element = partInfo.element;
@@ -6,19 +11,26 @@ export function extractElement(partInfo, directiveName) {
 }
 function getPartHostTagName(partInfo) {
     try {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         const tagName = partInfo.options.host.tagName.toLowerCase();
         return tagName;
     }
-    catch (error) {
+    catch {
         return undefined;
     }
 }
+/**
+ * Asserts that the given part info is an instance of {@link FullElementPartInfo}.
+ *
+ * @category Internal
+ */
 export function assertIsElementPartInfo(partInfo, directiveName) {
     const hostTagName = getPartHostTagName(partInfo);
     const hostTagMessage = hostTagName ? `: in ${hostTagName}` : '';
     if (partInfo.type !== PartType.ELEMENT) {
         throw new Error(`${directiveName} directive can only be attached directly to an element${hostTagMessage}.`);
     }
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     if (!partInfo.element) {
         throw new Error(`${directiveName} directive found no element${hostTagMessage}.`);
     }

package/dist/declarative-element/directives/is-resolved.directive.d.ts

@@ -1,4 +1,110 @@
-import { AsyncProp, AsyncValue } from './async-prop';
+import { AsyncProp, AsyncValue } from './async-prop.js';
+/**
+ * Checks and type guards that the given async value is resolved, meaning that it is no longer a
+ * promise. It may be an error though. This must be passed an {@link AsyncProp}'s `.value` property,
+ * not the async prop itself.
+ *
+ * @category Async
+ * @example
+ *
+ * ```ts
+ * import {waitValue, extractErrorMessage} from '@augment-vir/common';
+ * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     stateInitStatic: {
+ *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
+ *     },
+ *     render({state}) {
+ *         if (isAsyncError(state.myProp.value)) {
+ *             return html`
+ *                 Error: ${extractErrorMessage(state.myProp.value)}
+ *             `;
+ *         } else if (isResolved(state.myProp.value)) {
+ *             return html`
+ *                 Done!
+ *             `;
+ *         } else {
+ *             return html`
+ *                 Still waiting...
+ *             `;
+ *         }
+ *     },
+ * });
+ * ```
+ */
 export declare function isResolved<Value extends AsyncValue<any>>(asyncValue: Value extends AsyncProp<any, any> ? 'Error: pass AsyncProp.value, not AsyncProp itself.' : Value): asyncValue is Exclude<typeof asyncValue, Promise<any>>;
+/**
+ * Checks and type guards that the given async value is an error, meaning that the async prop's
+ * promise was rejected. This must be passed an {@link AsyncProp}'s `.value` property, not the async
+ * prop itself.
+ *
+ * @category Async
+ * @example
+ *
+ * ```ts
+ * import {waitValue, extractErrorMessage} from '@augment-vir/common';
+ * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     stateInitStatic: {
+ *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
+ *     },
+ *     render({state}) {
+ *         if (isAsyncError(state.myProp.value)) {
+ *             return html`
+ *                 Error: ${extractErrorMessage(state.myProp.value)}
+ *             `;
+ *         } else if (isResolved(state.myProp.value)) {
+ *             return html`
+ *                 Done!
+ *             `;
+ *         } else {
+ *             return html`
+ *                 Still waiting...
+ *             `;
+ *         }
+ *     },
+ * });
+ * ```
+ */
 export declare function isAsyncError<Value extends AsyncValue<any>>(asyncValue: Value extends AsyncProp<any, any> ? 'Error: pass AsyncProp.value, not AsyncProp itself.' : Value): asyncValue is Extract<typeof asyncValue, Error>;
+/**
+ * Same as {@link isResolved} but instead of a returning a boolean, it returns either the resolved
+ * value or `undefined`.
+ *
+ * @category Async
+ * @example
+ *
+ * ```ts
+ * import {waitValue, extractErrorMessage} from '@augment-vir/common';
+ * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     stateInitStatic: {
+ *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
+ *     },
+ *     render({state}) {
+ *         const resolvedValue = resolvedOrUndefined(state.myProp.value);
+ *
+ *         if (!resolvedValue) {
+ *             return html`
+ *                 Still waiting...
+ *             `;
+ *         } else if (isAsyncError(resolvedValue)) {
+ *             return html`
+ *                 Error: ${extractErrorMessage(state.myProp.value)}
+ *             `;
+ *         }
+ *
+ *         return html`
+ *             Value: ${resolvedValue}
+ *         `;
+ *     },
+ * });
+ * ```
+ */
 export declare function resolvedOrUndefined<Value extends AsyncValue<any>>(asyncValue: Value extends AsyncProp<any, any> ? 'Error: pass AsyncProp.value, not AsyncProp itself.' : Value): Exclude<typeof asyncValue, Promise<any>> | undefined;

package/dist/declarative-element/directives/is-resolved.directive.js

@@ -1,16 +1,122 @@
-import { AsyncProp } from './async-prop';
+import { AsyncProp } from './async-prop.js';
+/**
+ * Checks and type guards that the given async value is resolved, meaning that it is no longer a
+ * promise. It may be an error though. This must be passed an {@link AsyncProp}'s `.value` property,
+ * not the async prop itself.
+ *
+ * @category Async
+ * @example
+ *
+ * ```ts
+ * import {waitValue, extractErrorMessage} from '@augment-vir/common';
+ * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     stateInitStatic: {
+ *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
+ *     },
+ *     render({state}) {
+ *         if (isAsyncError(state.myProp.value)) {
+ *             return html`
+ *                 Error: ${extractErrorMessage(state.myProp.value)}
+ *             `;
+ *         } else if (isResolved(state.myProp.value)) {
+ *             return html`
+ *                 Done!
+ *             `;
+ *         } else {
+ *             return html`
+ *                 Still waiting...
+ *             `;
+ *         }
+ *     },
+ * });
+ * ```
+ */
 export function isResolved(asyncValue) {
     if (asyncValue instanceof AsyncProp) {
         throw new TypeError('Pass AsyncProp.value, not AsyncProp itself.');
     }
     return !(asyncValue instanceof Promise);
 }
+/**
+ * Checks and type guards that the given async value is an error, meaning that the async prop's
+ * promise was rejected. This must be passed an {@link AsyncProp}'s `.value` property, not the async
+ * prop itself.
+ *
+ * @category Async
+ * @example
+ *
+ * ```ts
+ * import {waitValue, extractErrorMessage} from '@augment-vir/common';
+ * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     stateInitStatic: {
+ *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
+ *     },
+ *     render({state}) {
+ *         if (isAsyncError(state.myProp.value)) {
+ *             return html`
+ *                 Error: ${extractErrorMessage(state.myProp.value)}
+ *             `;
+ *         } else if (isResolved(state.myProp.value)) {
+ *             return html`
+ *                 Done!
+ *             `;
+ *         } else {
+ *             return html`
+ *                 Still waiting...
+ *             `;
+ *         }
+ *     },
+ * });
+ * ```
+ */
 export function isAsyncError(asyncValue) {
     if (asyncValue instanceof AsyncProp) {
         throw new TypeError('Pass AsyncProp.value, not AsyncProp itself.');
     }
     return asyncValue instanceof Error;
 }
+/**
+ * Same as {@link isResolved} but instead of a returning a boolean, it returns either the resolved
+ * value or `undefined`.
+ *
+ * @category Async
+ * @example
+ *
+ * ```ts
+ * import {waitValue, extractErrorMessage} from '@augment-vir/common';
+ * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     stateInitStatic: {
+ *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
+ *     },
+ *     render({state}) {
+ *         const resolvedValue = resolvedOrUndefined(state.myProp.value);
+ *
+ *         if (!resolvedValue) {
+ *             return html`
+ *                 Still waiting...
+ *             `;
+ *         } else if (isAsyncError(resolvedValue)) {
+ *             return html`
+ *                 Error: ${extractErrorMessage(state.myProp.value)}
+ *             `;
+ *         }
+ *
+ *         return html`
+ *             Value: ${resolvedValue}
+ *         `;
+ *     },
+ * });
+ * ```
+ */
 export function resolvedOrUndefined(asyncValue) {
     if (isResolved(asyncValue)) {
         return asyncValue;

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

@@ -1,18 +1,92 @@
 import { MaybePromise } from '@augment-vir/common';
-import { DirectiveResult } from '../../lit-exports/all-lit-exports';
-import { DefinedTypedEvent, TypedEvent } from '../../typed-event/typed-event';
+import { DirectiveResult } from '../../lit-exports/all-lit-exports.js';
+import { DefinedTypedEvent, TypedEvent } from '../../typed-event/typed-event.js';
 /** We don't care at all what this returns, just allow anything! */
 type ListenCallbackReturn = MaybePromise<any>;
 /**
  * Listen to events. These can be native DOM events (use a string for the inputType argument) or
- * typed events (pass in a return value from defineTypedEvent).
+ * typed events (pass in a return value from {@link defineTypedEvent}).
  *
- * @param eventType Needs to come either from a declarative element (like
- *   MyDeclarativeElement.events.eventName) or from a typed event created via the defineTypedEvent
- *   function.
- * @param listener The callback to fire when an event is caught. Assuming the definedTypedEvent
- *   input is properly typed, the event given to this callback will also be typed.
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElementNoInputs, listen} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div
+ *                 ${listen('click', () => {
+ *                     console.log('clicked!');
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *             <${MyOtherElement}
+ *                 ${listen(MyOtherElement.events.someEvent, (event) => {
+ *                     console.log('event value', event.detail);
+ *                 })}
+ *             ></${MyOtherElement}>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export declare function listen<TypedEventTypeNameGeneric extends string, TypedEventDetailGeneric>(
+/**
+ * Needs to come either from a declarative element (like MyDeclarativeElement.events.eventName),
+ * from a typed event created via the {@link defineTypedEvent} function, or be the name of a
+ * built-in event (like `'click'`).
+ */
+eventType: DefinedTypedEvent<TypedEventTypeNameGeneric, TypedEventDetailGeneric>, 
+/**
+ * The callback to fire when an event is caught. Assuming the {@link defineTypedEvent} input is
+ * properly typed, the event given to this callback will also be typed.
+ */
+listener: (event: TypedEvent<TypedEventTypeNameGeneric, TypedEventDetailGeneric>) => ListenCallbackReturn): DirectiveResult<any>;
+/**
+ * Listen to events. These can be native DOM events (use a string for the inputType argument) or
+ * typed events (pass in a return value from {@link defineTypedEvent}).
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElementNoInputs, listen} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div
+ *                 ${listen('click', () => {
+ *                     console.log('clicked!');
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *             <${MyOtherElement}
+ *                 ${listen(MyOtherElement.events.someEvent, (event) => {
+ *                     console.log('event value', event.detail);
+ *                 })}
+ *             ></${MyOtherElement}>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export declare function listen<NativeElementEventNameGeneric extends keyof HTMLElementEventMap>(
+/**
+ * Needs to come either from a declarative element (like MyDeclarativeElement.events.eventName),
+ * from a typed event created via the {@link defineTypedEvent} function, or be the name of a
+ * built-in event (like `'click'`).
+ */
+eventType: NativeElementEventNameGeneric, 
+/**
+ * The callback to fire when an event is caught. Assuming the {@link defineTypedEvent} input is
+ * properly typed, the event given to this callback will also be typed.
  */
-export declare function listen<TypedEventTypeNameGeneric extends string, TypedEventDetailGeneric, NativeElementEventNameGeneric extends keyof HTMLElementEventMap>(eventType: DefinedTypedEvent<TypedEventTypeNameGeneric, TypedEventDetailGeneric>, listener: (event: TypedEvent<TypedEventTypeNameGeneric, TypedEventDetailGeneric>) => ListenCallbackReturn): DirectiveResult<any>;
-export declare function listen<TypedEventTypeNameGeneric extends string, TypedEventDetailGeneric, NativeElementEventNameGeneric extends keyof HTMLElementEventMap>(eventType: NativeElementEventNameGeneric, listener: (event: HTMLElementEventMap[NativeElementEventNameGeneric]) => ListenCallbackReturn): DirectiveResult<any>;
+listener: (event: HTMLElementEventMap[NativeElementEventNameGeneric]) => ListenCallbackReturn): DirectiveResult<any>;
 export {};

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

@@ -1,5 +1,5 @@
-import { directive, Directive, noChange, } from '../../lit-exports/all-lit-exports';
-import { extractElement } from './directive-helpers';
+import { directive, Directive, noChange, } from '../../lit-exports/all-lit-exports.js';
+import { extractElement } from './directive-helpers.js';
 export function listen(eventType, listener) {
     return listenDirective(eventType, listener);
 }
@@ -8,20 +8,10 @@ export function listen(eventType, listener) {
  * call is wrapped in the function above.
  */
 const listenDirective = directive(class extends Directive {
+    element;
+    lastListenerMetaData;
     constructor(partInfo) {
         super(partInfo);
-        Object.defineProperty(this, "element", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "lastListenerMetaData", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
         this.element = extractElement(partInfo, 'listen');
     }
     resetListener(listenerMetaData) {
@@ -41,7 +31,7 @@ const listenDirective = directive(class extends Directive {
     render(eventTypeInput, callback) {
         const eventType = typeof eventTypeInput === 'string' ? eventTypeInput : eventTypeInput.type;
         if (typeof eventType !== 'string') {
-            throw new Error(`Cannot listen to an event with a name that is not a string. Given event name: "${eventType}"`);
+            throw new TypeError(`Cannot listen to an event with a name that is not a string. Given event name: '${String(eventType)}'`);
         }
         if (this.lastListenerMetaData && this.lastListenerMetaData.eventType === eventType) {
             /**

package/dist/declarative-element/directives/on-dom-created.directive.d.ts

@@ -1,7 +1,40 @@
-import { PartInfo } from '../../lit-exports/all-lit-exports';
-export type OnDomCreatedCallback = (element: Element) => void;
-/** Only fires once, when the element has been created. */
-export declare const onDomCreated: (callback: OnDomCreatedCallback) => import("lit-html/directive").DirectiveResult<{
+import type { MaybePromise } from '@augment-vir/common';
+import { PartInfo } from '../../lit-exports/all-lit-exports.js';
+/**
+ * The callback / listener passed to {@link onDomCreated}. The `element` parameter is a reference to
+ * the DOM element that the directive was attached to.
+ *
+ * @category Internal
+ */
+export type OnDomCreatedCallback = (element: Element) => MaybePromise<void>;
+/**
+ * A directive that fires its listener only once, when the element that it's attached to is
+ * constructed. This is particularly useful for getting references to internal elements immediately
+ * after they've rendered.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {html, defineElementNoInputs, onDomCreated} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     render() {
+ *         return html`
+ *             <div
+ *                 ${onDomCreated((element) => {
+ *                     console.log('created!', element);
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export declare const onDomCreated: (callback: OnDomCreatedCallback) => import("lit-html/directive.js").DirectiveResult<{
     new (partInfo: PartInfo): {
         element: Element | undefined;
         update(partInfo: PartInfo, [callback]: [OnDomCreatedCallback]): undefined;