element-vir 22.2.1 → 23.0.0

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

@@ -1,7 +1,9 @@
-import { typedHasProperties, typedHasProperty } from '@augment-vir/common';
+import { check } from '@augment-vir/assert';
 /**
  * Checks if the input is an instance of a DeclarativeElement, the super class of all custom
  * elements defined with element-vir.
+ *
+ * @category Util
  */
 export function isDeclarativeElement(input) {
     const markerProperties = [
@@ -9,15 +11,17 @@ export function isDeclarativeElement(input) {
         'instanceState',
         'definition',
     ];
-    return typedHasProperties(input, markerProperties);
+    return check.hasKeys(input, markerProperties);
 }
 /**
  * Checks if the input is an instance of a DeclarativeElement, the super class of all custom
  * elements defined with element-vir.
+ *
+ * @category Util
  */
 export function assertIsDeclarativeElement(input) {
     if (!isDeclarativeElement(input)) {
         console.error('this is not a declarative element:', input);
-        throw new Error(`${typedHasProperty(input, 'tagName') ? input.tagName : input} is not a declarative element.`);
+        throw new Error(`${String(check.hasKey(input, 'tagName') ? input.tagName : input)} is not a declarative element.`);
     }
 }

package/dist/declarative-element/properties/assign-inputs.js

@@ -3,7 +3,7 @@ export function assignInputs(element, inputs) {
     const instanceState = element.instanceState;
     getObjectTypedKeys(inputs).forEach((newInputKey) => {
         if (instanceState && newInputKey in instanceState) {
-            throw new Error(`Cannot set input '${newInputKey}' on '${element.tagName}'. '${element.tagName}' already has a state property with the same name.`);
+            throw new Error(`Cannot set input '${String(newInputKey)}' on '${element.tagName}'. '${element.tagName}' already has a state property with the same name.`);
         }
         if ('instanceInputs' in element) {
             element.instanceInputs[newInputKey] =

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

@@ -1,3 +1,13 @@
-import { CustomElementTagName } from '../custom-tag-name';
+import { CustomElementTagName } from '../custom-tag-name.js';
+/**
+ * Base requirement for all CSS property names (like CSS var names).
+ *
+ * @category Internal
+ */
 export type BaseCssPropertyName<ElementTagName extends CustomElementTagName> = `${ElementTagName}-${string}`;
+/**
+ * Asserts that all the given CSS properties for the given element are valid.
+ *
+ * @category Internal
+ */
 export declare function assertValidCssProperties(elementTagName: CustomElementTagName, cssProperties: Record<BaseCssPropertyName<CustomElementTagName>, any>): void;

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

@@ -1,3 +1,8 @@
+/**
+ * Asserts that all the given CSS properties for the given element are valid.
+ *
+ * @category Internal
+ */
 export function assertValidCssProperties(elementTagName, cssProperties) {
     const requiredCssPropKeyStart = [
         elementTagName,

package/dist/declarative-element/properties/css-vars.d.ts

@@ -1,6 +1,16 @@
-import { PropertyValueType } from '@augment-vir/common';
+import { Values } from '@augment-vir/common';
 import { CssVarDefinitions, CssVarsSetup } from 'lit-css-vars';
-import { CustomElementTagName } from '../custom-tag-name';
-import { BaseCssPropertyName } from './css-properties';
-export type CssVarsInitMap<ElementTagName extends CustomElementTagName, CssVarKeys extends BaseCssPropertyName<ElementTagName>> = Readonly<Record<CssVarKeys, PropertyValueType<CssVarsSetup>>>;
+import { CustomElementTagName } from '../custom-tag-name.js';
+import { BaseCssPropertyName } from './css-properties.js';
+/**
+ * Base type for a declarative element definition's CSS vars.
+ *
+ * @category Internal
+ */
+export type CssVarsInitMap<ElementTagName extends CustomElementTagName, CssVarKeys extends BaseCssPropertyName<ElementTagName>> = Readonly<Record<CssVarKeys, Values<CssVarsSetup>>>;
+/**
+ * CSS vars ready for use within a declarative element's `render` or `styles` method.
+ *
+ * @category Internal
+ */
 export type CssVars<ElementTagName extends CustomElementTagName, CssVarKeys extends BaseCssPropertyName<ElementTagName>> = CssVarDefinitions<CssVarsInitMap<ElementTagName, CssVarKeys>>;

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

@@ -1,11 +1,65 @@
-import { DefinedTypedEvent, DefinedTypedEventNameDefinition, TypedEvent } from '../../typed-event/typed-event';
-import { CustomElementTagName } from '../custom-tag-name';
-export type EventsInitMap = Record<string, DefinedTypedEventNameDefinition<any>>;
-export declare function defineElementEvent<EventDetailGeneric>(): DefinedTypedEventNameDefinition<EventDetailGeneric>;
-export type EventInitMapEventDetailExtractor<EventTypeNameGeneric extends keyof EventsInitGeneric, EventsInitGeneric extends EventsInitMap> = EventsInitGeneric[EventTypeNameGeneric] extends DefinedTypedEventNameDefinition<infer R> ? R : never;
+import { DefinedTypedEvent, DefineEvent, TypedEvent } from '../../typed-event/typed-event.js';
+import { CustomElementTagName } from '../custom-tag-name.js';
+/**
+ * Base type for defining element events inside of an element definition.
+ *
+ * @category Internal
+ */
+export type EventsInitMap = Record<string, DefineEvent<any>>;
+/**
+ * Used to define element events, with a type.
+ *
+ * @category Element Definition
+ * @example
+ *
+ * ```ts
+ * import {html, defineElementNoInputs, defineElementEvent, listen} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     events: {
+ *         myOutput: defineElementEvent<number>(),
+ *     },
+ *     render({events, dispatch}) {
+ *         return html`
+ *             <div
+ *                 ${listen('click', () => {
+ *                     dispatch(new events.myOutput(1));
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
+export declare function defineElementEvent<EventDetailGeneric>(): DefineEvent<EventDetailGeneric>;
+/**
+ * Extracts the detail type of the given event name from the given event init map.
+ *
+ * @category Internal
+ */
+export type EventInitMapEventDetailExtractor<EventTypeNameGeneric extends keyof EventsInitGeneric, EventsInitGeneric extends EventsInitMap> = EventsInitGeneric[EventTypeNameGeneric] extends DefineEvent<infer Detail> ? Detail : never;
+/**
+ * Maps the given element tag name and map of event names to their run-time event type strings.
+ *
+ * @category Internal
+ */
 export type EventDescriptorMap<TagName extends CustomElementTagName, EventsInitGeneric extends EventsInitMap> = {
     [CurrentEventTypeName in keyof EventsInitGeneric]: DefinedTypedEvent<CurrentEventTypeName extends string ? `${TagName}-${CurrentEventTypeName}` : never, EventInitMapEventDetailExtractor<CurrentEventTypeName, EventsInitGeneric>>;
 };
-export type EventObjectEventDetailExtractor<EventObjectGeneric extends DefinedTypedEvent<any, any>> = EventObjectGeneric extends DefinedTypedEvent<string, infer R> ? R : never;
-export type ElementEventDetailExtractor<ElementEventGeneric extends TypedEvent<any, any>> = ElementEventGeneric extends TypedEvent<string, infer R> ? R : never;
+/**
+ * Extract the event detail type from a {@link TypedEvent}, {@link DefinedTypedEvent}, or
+ * `CustomEvent.
+ *
+ * @category Internal
+ */
+export type EventDetail<ElementEvent extends TypedEvent<any, any> | DefinedTypedEvent<any, any> | CustomEvent> = ElementEvent extends TypedEvent<string, infer Detail> ? Detail : ElementEvent extends DefinedTypedEvent<any, infer Detail> ? Detail : ElementEvent extends CustomEvent<infer Detail> ? Detail : 'TYPE ERROR: failed to extract event detail type';
+/**
+ * Maps an element definition initialization's tag name and event map to a map of ready-to-construct
+ * event classes. This also verifies that the input event init map has valid keys.
+ *
+ * @category Internal
+ */
 export declare function createEventDescriptorMap<TagName extends CustomElementTagName, EventsInitGeneric extends EventsInitMap>(tagName: CustomElementTagName, eventsInit: EventsInitGeneric | undefined): EventDescriptorMap<TagName, EventsInitGeneric>;

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

@@ -1,17 +1,52 @@
-import { defineTypedEvent, } from '../../typed-event/typed-event';
+import { defineTypedEvent, } from '../../typed-event/typed-event.js';
+/**
+ * Used to define element events, with a type.
+ *
+ * @category Element Definition
+ * @example
+ *
+ * ```ts
+ * import {html, defineElementNoInputs, defineElementEvent, listen} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     events: {
+ *         myOutput: defineElementEvent<number>(),
+ *     },
+ *     render({events, dispatch}) {
+ *         return html`
+ *             <div
+ *                 ${listen('click', () => {
+ *                     dispatch(new events.myOutput(1));
+ *                 })}
+ *             >
+ *                 Some div
+ *             </div>
+ *         `;
+ *     },
+ * });
+ * ```
+ */
 export function defineElementEvent() {
     return defineTypedEvent();
 }
+/**
+ * Maps an element definition initialization's tag name and event map to a map of ready-to-construct
+ * event classes. This also verifies that the input event init map has valid keys.
+ *
+ * @category Internal
+ */
 export function createEventDescriptorMap(tagName, eventsInit) {
     if (!eventsInit) {
         return {};
     }
-    return Object.keys(eventsInit)
+    return (Object.keys(eventsInit)
+        /** Verify event keys. */
         .filter((currentElementEventKey) => {
         if (typeof currentElementEventKey !== 'string') {
-            throw new Error(`Expected event key of type string but got type "${typeof currentElementEventKey}" for key ${String(currentElementEventKey)}`);
+            throw new TypeError(`Expected event key of type string but got type '${typeof currentElementEventKey}' for key ${String(currentElementEventKey)}`);
         }
-        if (currentElementEventKey === '') {
+        else if (currentElementEventKey === '') {
             throw new Error(`Got empty string for events key.`);
         }
         return true;
@@ -23,5 +58,5 @@ export function createEventDescriptorMap(tagName, eventsInit) {
         ].join('-'));
         accum[currentElementEventKey] = eventObject;
         return accum;
-    }, {});
+    }, {}));
 }

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

@@ -1,14 +1,23 @@
+/**
+ * The base type for any property maps (like state or inputs).
+ *
+ * @category Internal
+ */
 export type PropertyInitMapBase = Record<PropertyKey, unknown>;
-export type ElementProperty<KeyGeneric extends string | number | symbol, ValueGeneric> = {
-    name: KeyGeneric;
-    setProp(value: ValueGeneric): void;
-    getProp(): ValueGeneric;
-};
+/**
+ * Describes a static element property.
+ *
+ * @category Internal
+ */
 export type StaticElementPropertyDescriptor<PropName extends string, PropValue> = {
     propName: PropName;
     initValue: PropValue;
 };
+/**
+ * Maps a property init map into static element descriptions.
+ *
+ * @category Internal
+ */
 export type ElementPropertyDescriptorMap<PropertyInitGeneric extends PropertyInitMapBase> = {
     [Property in keyof PropertyInitGeneric]: StaticElementPropertyDescriptor<string, PropertyInitGeneric[Property]>;
 };
-export declare function createPropertyDescriptorMap<PropertyInitGeneric extends PropertyInitMapBase>(propertyInit: PropertyInitGeneric | undefined): ElementPropertyDescriptorMap<PropertyInitGeneric>;

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

@@ -1,21 +1 @@
-export function createPropertyDescriptorMap(propertyInit) {
-    if (!propertyInit) {
-        return {};
-    }
-    return Object.keys(propertyInit)
-        .filter((key) => {
-        if (typeof key === 'string') {
-            return true;
-        }
-        else {
-            throw new Error(`Property init cannot have non string keys: "${key}"`);
-        }
-    })
-        .reduce((accum, currentKey) => {
-        accum[currentKey] = {
-            propName: currentKey,
-            initValue: propertyInit[currentKey],
-        };
-        return accum;
-    }, {});
-}
+export {};

package/dist/declarative-element/properties/element-vir-state-setup.d.ts

@@ -1,14 +1,54 @@
-import { PropertyInitMapBase } from './element-properties';
+import { PropertyInitMapBase } from './element-properties.js';
+/**
+ * Use this key with a function value on any object set in `stateInitStatic` to, rather than using
+ * the object itself, call the function during each element's initialization and use the output of
+ * that function rather than the object itself.
+ *
+ * See `perInstance` for an example usage.
+ *
+ * @category Util
+ */
 export declare const stateSetupKey: unique symbol;
+/**
+ * The type for an object that uses {@link stateSetupKey}.
+ *
+ * @category Internal
+ */
 export type ElementVirStateSetup<InnerValue> = {
     [key in typeof stateSetupKey]: () => InnerValue;
 };
+/**
+ * Check if the given value is a value {@link ElementVirStateSetup} implementation.
+ *
+ * @category Internal
+ */
 export declare function isElementVirStateSetup<T = unknown>(input: unknown): input is ElementVirStateSetup<T>;
+/**
+ * If the type parameter is an instance of {@link ElementVirStateSetup}, this unwraps that instance
+ * to its type parameter. Otherwise, the original type parameter is used.
+ *
+ * @category Internal
+ */
 export type UnwrapElementVirStateSetup<T> = T extends ElementVirStateSetup<infer U> ? U : T;
+/**
+ * Allow wrapped state setup objects.
+ *
+ * @category Internal
+ */
 export type MaybeElementVirStateSetup<T> = UnwrapElementVirStateSetup<T> | ElementVirStateSetup<UnwrapElementVirStateSetup<T>>;
-export type FlattenElementVirStateSetup<OriginalObject extends PropertyInitMapBase> = {
-    [Prop in keyof OriginalObject]: Extract<OriginalObject[Prop], ElementVirStateSetup<any>> extends never ? OriginalObject[Prop] : Extract<OriginalObject[Prop], ElementVirStateSetup<any>> extends ElementVirStateSetup<infer InnerValue> ? InnerValue | Exclude<OriginalObject[Prop], ElementVirStateSetup<any>> : OriginalObject[Prop];
+/**
+ * Unwraps all {@link ElementVirStateSetup} properties in the given state init object type parameter.
+ *
+ * @category Internal
+ */
+export type FlattenElementVirStateSetup<StateInit extends PropertyInitMapBase> = {
+    [Prop in keyof StateInit]: Extract<StateInit[Prop], ElementVirStateSetup<any>> extends never ? StateInit[Prop] : Extract<StateInit[Prop], ElementVirStateSetup<any>> extends ElementVirStateSetup<infer InnerValue> ? InnerValue | Exclude<StateInit[Prop], ElementVirStateSetup<any>> : StateInit[Prop];
 };
+/**
+ * Allows setting stat with {@link ElementVirStateSetup} properties.
+ *
+ * @category Internal
+ */
 export type AllowElementVirStateSetup<OriginalObject extends PropertyInitMapBase> = {
     [Prop in keyof OriginalObject]: MaybeElementVirStateSetup<OriginalObject[Prop]>;
 };

package/dist/declarative-element/properties/element-vir-state-setup.js

@@ -1,8 +1,22 @@
-import { isObject } from '@augment-vir/common';
+import { check } from '@augment-vir/assert';
+/**
+ * Use this key with a function value on any object set in `stateInitStatic` to, rather than using
+ * the object itself, call the function during each element's initialization and use the output of
+ * that function rather than the object itself.
+ *
+ * See `perInstance` for an example usage.
+ *
+ * @category Util
+ */
 export const stateSetupKey = Symbol('element-vir-state-setup');
+/**
+ * Check if the given value is a value {@link ElementVirStateSetup} implementation.
+ *
+ * @category Internal
+ */
 export function isElementVirStateSetup(input) {
-    if (!isObject(input)) {
+    if (!check.isObject(input)) {
         return false;
     }
-    return stateSetupKey in input;
+    return stateSetupKey in input && check.isFunction(input[stateSetupKey]);
 }

package/dist/declarative-element/properties/host-classes.d.ts

@@ -1,21 +1,34 @@
-import { CustomElementTagName } from '../custom-tag-name';
-import { BaseCssPropertyName } from './css-properties';
-import { PropertyInitMapBase } from './element-properties';
-import { FlattenElementVirStateSetup } from './element-vir-state-setup';
-import { WithTagName } from './tag-name';
-export type HostClassToggleCallbackInput<Inputs extends PropertyInitMapBase, StateInit extends PropertyInitMapBase> = {
-    state: Readonly<FlattenElementVirStateSetup<StateInit>>;
-    inputs: Readonly<Inputs>;
-};
-export type HostClassToggleCallback<Inputs extends PropertyInitMapBase, StateInit extends PropertyInitMapBase> = (inputs: HostClassToggleCallbackInput<Inputs, StateInit>) => boolean;
+import { CustomElementTagName } from '../custom-tag-name.js';
+import { BaseCssPropertyName } from './css-properties.js';
+import { PropertyInitMapBase } from './element-properties.js';
+import { FlattenElementVirStateSetup } from './element-vir-state-setup.js';
+import { WithTagName } from './tag-name.js';
+/**
+ * Base init map for defining host classes in an element definition.
+ *
+ * @category Internal
+ */
 export type HostClassesInitMap<TagName extends CustomElementTagName, HostClassKeys extends BaseCssPropertyName<TagName>, Inputs extends PropertyInitMapBase, StateInit extends PropertyInitMapBase> = Record<HostClassKeys, 
 /**
  * Callback to determine when host class should be enabled (based on current inputs and state),
  * or just undefined to mark that this host class name will only be manually applied.
  */
-HostClassToggleCallback<Inputs, StateInit> | false>;
-export type HostClassName<TagName extends string, HostClassPropName extends string> = `${TagName}-${HostClassPropName}`;
+((inputs: {
+    state: Readonly<FlattenElementVirStateSetup<StateInit>>;
+    inputs: Readonly<Inputs>;
+}) => boolean) | false>;
+/**
+ * Creates a mapping of host class keys (as defined in an element definition) to their runtime host
+ * class names.
+ *
+ * @category Internal
+ */
 export type HostClassNamesMap<TagName extends string, HostClassKeys extends string> = Record<HostClassKeys, WithTagName<TagName, string>>;
+/**
+ * Maps element definition host class definitions to their runtime host class name equivalents.
+ *
+ * @category Internal
+ */
 export declare function createHostClassNamesMap<TagName extends CustomElementTagName, HostClassKeys extends BaseCssPropertyName<TagName>, HostClassesInit extends HostClassesInitMap<TagName, HostClassKeys, 
 /**
  * We can use any here because we don't care what the state or input names are, we just care

package/dist/declarative-element/properties/host-classes.js

@@ -1,4 +1,9 @@
 import { mapObjectValues } from '@augment-vir/common';
+/**
+ * Maps element definition host class definitions to their runtime host class name equivalents.
+ *
+ * @category Internal
+ */
 export function createHostClassNamesMap(hostClassesInit) {
     if (hostClassesInit) {
         return mapObjectValues(hostClassesInit, (key) => {

package/dist/declarative-element/properties/per-instance.d.ts

@@ -1,5 +1,26 @@
 /**
- * A state prop helper that sets up the given callback for each instance of the element that this
- * state is contained within.
+ * For use within `stateInitStatic`: use this as the value of a state prop to call the given
+ * callback on each element's creation rather than creating a static state init value.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {waitValue, extractErrorMessage} from '@augment-vir/common';
+ * import {isResolved, html, defineElementNoInputs, perInstance} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     stateInitStatic: {
+ *         // each instance of `MyElement` will have a different `randomValue`
+ *         randomValue: perInstance(() => Math.random()),
+ *     },
+ *     render({state}) {
+ *         return html`
+ *             Value: ${state.randomValue}
+ *         `;
+ *     },
+ * });
+ * ```
  */
 export declare function perInstance<T>(creationCallback: () => T): T;

package/dist/declarative-element/properties/per-instance.js

@@ -1,7 +1,28 @@
-import { stateSetupKey } from './element-vir-state-setup';
+import { stateSetupKey } from './element-vir-state-setup.js';
 /**
- * A state prop helper that sets up the given callback for each instance of the element that this
- * state is contained within.
+ * For use within `stateInitStatic`: use this as the value of a state prop to call the given
+ * callback on each element's creation rather than creating a static state init value.
+ *
+ * @category Directives
+ * @example
+ *
+ * ```ts
+ * import {waitValue, extractErrorMessage} from '@augment-vir/common';
+ * import {isResolved, html, defineElementNoInputs, perInstance} from 'element-vir';
+ *
+ * const MyElement = defineElementNoInputs({
+ *     tagName: 'my-element',
+ *     stateInitStatic: {
+ *         // each instance of `MyElement` will have a different `randomValue`
+ *         randomValue: perInstance(() => Math.random()),
+ *     },
+ *     render({state}) {
+ *         return html`
+ *             Value: ${state.randomValue}
+ *         `;
+ *     },
+ * });
+ * ```
  */
 export function perInstance(creationCallback) {
     const stateSetup = {

package/dist/declarative-element/properties/property-proxy.d.ts

@@ -1,7 +1,22 @@
-import { ObservableListener } from 'observavir';
-import { DeclarativeElement } from '../declarative-element';
-import { PropertyInitMapBase } from './element-properties';
+import { type ObservableListener } from 'observavir';
+import { type DeclarativeElement } from '../declarative-element.js';
+import { type PropertyInitMapBase } from './element-properties.js';
+/**
+ * Used for a map of all observables registered to an element instance.
+ *
+ * @category Internal
+ */
 export type ObservableListenerMap<OriginalPropertyMap extends PropertyInitMapBase> = Partial<Record<keyof OriginalPropertyMap, ObservableListener<any> | undefined>>;
-/** Binds the given property key as a reactive property on the given element. */
+/**
+ * Binds the given property key as a reactive property on the given element.
+ *
+ * @category Internal
+ */
 export declare function bindReactiveProperty(element: HTMLElement, propertyKey: PropertyKey): void;
+/**
+ * Creates an internal proxy for setting inputs and state properties and then updating them on the
+ * element itself so they will trigger lit's change detection.
+ *
+ * @category Internal
+ */
 export declare function createElementPropertyProxy<PropertyInitGeneric extends PropertyInitMapBase>(element: DeclarativeElement, shouldAlreadyExist: boolean): PropertyInitGeneric;

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

@@ -1,7 +1,11 @@
 import { isObservableBase } from 'observavir';
-import { property } from '../../lit-exports/all-lit-exports';
-import { isElementVirStateSetup, stateSetupKey } from './element-vir-state-setup';
-/** Binds the given property key as a reactive property on the given element. */
+import { property } from '../../lit-exports/base-lit-exports.js';
+import { isElementVirStateSetup, stateSetupKey } from './element-vir-state-setup.js';
+/**
+ * Binds the given property key as a reactive property on the given element.
+ *
+ * @category Internal
+ */
 export function bindReactiveProperty(element, propertyKey) {
     if (!(propertyKey in element)) {
         property()(element, propertyKey);
@@ -9,12 +13,18 @@ export function bindReactiveProperty(element, propertyKey) {
 }
 function assertValidPropertyName(propKey, element, elementTagName) {
     if (typeof propKey !== 'string' && typeof propKey !== 'number' && typeof propKey !== 'symbol') {
-        throw new Error(`Property name must be a string, got type '${typeof propKey}' from: '${String(propKey)}' for '${elementTagName.toLowerCase()}'`);
+        throw new TypeError(`Property name must be a string, got type '${typeof propKey}' from: '${String(propKey)}' for '${elementTagName.toLowerCase()}'`);
     }
     if (!(propKey in element)) {
         throw new Error(`Property '${String(propKey)}' does not exist on '${elementTagName.toLowerCase()}'.`);
     }
 }
+/**
+ * Creates an internal proxy for setting inputs and state properties and then updating them on the
+ * element itself so they will trigger lit's change detection.
+ *
+ * @category Internal
+ */
 export function createElementPropertyProxy(element, shouldAlreadyExist) {
     /**
      * Lit element updates state and inputs by setting them directly on the element, so we must do
@@ -23,6 +33,7 @@ export function createElementPropertyProxy(element, shouldAlreadyExist) {
      */
     const elementAsProps = element;
     function verifyProperty(propertyKey) {
+        // eslint-disable-next-line sonarjs/no-selector-parameter
         if (shouldAlreadyExist) {
             assertValidPropertyName(propertyKey, element, element.tagName);
         }

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

@@ -1,23 +1,48 @@
-import { CSSResult } from '../../lit-exports/all-lit-exports';
-import { CustomElementTagName } from '../custom-tag-name';
-import { BaseCssPropertyName } from './css-properties';
-import { CssVars } from './css-vars';
-import { PropertyInitMapBase } from './element-properties';
-import { FlattenElementVirStateSetup } from './element-vir-state-setup';
-import { HostClassNamesMap, HostClassesInitMap } from './host-classes';
+import { type CSSResult } from '../../lit-exports/base-lit-exports.js';
+import { type CustomElementTagName } from '../custom-tag-name.js';
+import { type BaseCssPropertyName } from './css-properties.js';
+import { type CssVars } from './css-vars.js';
+import { type PropertyInitMapBase } from './element-properties.js';
+import { type FlattenElementVirStateSetup } from './element-vir-state-setup.js';
+import { type HostClassNamesMap, type HostClassesInitMap } from './host-classes.js';
+/**
+ * A host class instance to be referenced inside of an element definition's `styles` callback.
+ *
+ * @category Internal
+ */
 export type HostClass = {
     selector: CSSResult;
     name: CSSResult;
 };
+/**
+ * Input type for an element definition's `styles` callback.
+ *
+ * @category Internal
+ */
 export type StylesCallbackInput<TagName extends CustomElementTagName, HostClassKeys extends BaseCssPropertyName<TagName>, CssVarKeys extends BaseCssPropertyName<TagName>> = {
     hostClasses: Record<HostClassKeys, HostClass>;
     cssVars: Readonly<CssVars<TagName, CssVarKeys>>;
 };
+/**
+ * The type for an element definition's `styles` callback.
+ *
+ * @category Internal
+ */
 export type StylesCallback<TagName extends CustomElementTagName, HostClassKeys extends BaseCssPropertyName<TagName>, CssVarKeys extends BaseCssPropertyName<TagName>> = (input: StylesCallbackInput<TagName, HostClassKeys, CssVarKeys>) => CSSResult;
-export declare function hostClassNamesToStylesInput<TagName extends CustomElementTagName, HostClassKeys extends BaseCssPropertyName<TagName>, CssVarKeys extends BaseCssPropertyName<TagName>>({ hostClassNames, cssVars, }: {
+/**
+ * Creates the input for an element definition's `styles` callback.
+ *
+ * @category Internal
+ */
+export declare function createStylesCallbackInput<TagName extends CustomElementTagName, HostClassKeys extends BaseCssPropertyName<TagName>, CssVarKeys extends BaseCssPropertyName<TagName>>({ hostClassNames, cssVars, }: {
     hostClassNames: HostClassNamesMap<TagName, HostClassKeys>;
     cssVars: Readonly<CssVars<TagName, CssVarKeys>>;
 }): StylesCallbackInput<TagName, HostClassKeys, CssVarKeys>;
+/**
+ * Used inside of an element instance to apply host classes on each render.
+ *
+ * @category Internal
+ */
 export declare function applyHostClasses<TagName extends CustomElementTagName, Inputs extends PropertyInitMapBase, StateInit extends PropertyInitMapBase, HostClassKeys extends BaseCssPropertyName<TagName>>({ host, hostClassesInit, hostClassNames, state, inputs, }: {
     host: HTMLElement;
     hostClassesInit: Readonly<HostClassesInitMap<TagName, HostClassKeys, Inputs, StateInit>> | undefined;

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

@@ -1,6 +1,11 @@
 import { getObjectTypedKeys, mapObjectValues } from '@augment-vir/common';
-import { unsafeCSS } from '../../lit-exports/all-lit-exports';
-export function hostClassNamesToStylesInput({ hostClassNames, cssVars, }) {
+import { unsafeCSS } from '../../lit-exports/base-lit-exports.js';
+/**
+ * Creates the input for an element definition's `styles` callback.
+ *
+ * @category Internal
+ */
+export function createStylesCallbackInput({ hostClassNames, cssVars, }) {
     return {
         hostClasses: mapObjectValues(hostClassNames, (key, name) => {
             return {
@@ -11,6 +16,11 @@ export function hostClassNamesToStylesInput({ hostClassNames, cssVars, }) {
         cssVars,
     };
 }
+/**
+ * Used inside of an element instance to apply host classes on each render.
+ *
+ * @category Internal
+ */
 export function applyHostClasses({ host, hostClassesInit, hostClassNames, state, inputs, }) {
     if (!hostClassesInit) {
         return;

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

@@ -1 +1,6 @@
+/**
+ * Prefixes any given `Suffix` with a element's `TagName`.
+ *
+ * @category Internal
+ */
 export type WithTagName<TagName extends string, Suffix extends string> = `${TagName}-${Suffix}`;