element-vir 5.6.0 → 6.0.0

package/README.md

@@ -1,6 +1,6 @@
 # element-vir
 
-Heroic. Reactive. Functional. Type safe. Web components without compromise.
+Heroic. Reactive. Declarative. Type safe. Web components without compromise.
 
 No need for an extra build step,<br>
 no need for side effect imports, <br>
@@ -11,7 +11,7 @@ _**It's just TypeScript.**_
 
 Uses the power of _native_ JavaScript custom web elements, _native_ JavaScript template literals, _native_ JavaScript functions<sup>\*</sup>, _native_ HTML, and [lit-element](http://lit.dev).
 
-In reality this is basically a [lit-element](http://lit.dev) wrapper that adds type-safe element tag usage and I/O with functional-programming style component definition. (As functional as possible, element property mutations are still possible cause without that, how would you do anything?)
+In reality this is basically a [lit-element](http://lit.dev) wrapper that adds type-safe element tag usage and I/O with declarative style component definition.
 
 [Works in every major web browser except Internet Explorer.](https://caniuse.com/mdn-api_window_customelements)
 
@@ -29,20 +29,20 @@ Make sure to install this as a normal dependency (not just a dev dependency) bec
 
 # Usage
 
-Most usage of this package is done through the [`defineFunctionalElement` function](https://github.com/electrovir/element-vir/blob/main/src/functional-element/define-functional-element.ts#L25-L30). See the [`FunctionalElementInit` type](https://github.com/electrovir/element-vir/blob/main/src/functional-element/functional-element-init.ts#L7-L20) for that function's inputs. These inputs are also described below with examples.
+Most usage of this package is done through the [`defineElementNoInputs` function](https://github.com/electrovir/element-vir/blob/main/src/declarative-element/define-declarative-element.ts#L25-L30). See the [`DeclarativeElementInit` type](https://github.com/electrovir/element-vir/blob/main/src/declarative-element/declarative-element-init.ts#L7-L20) for that function's inputs. These inputs are also described below with examples.
 
 All of [`lit`](https://lit.dev)'s syntax and functionality is also available for use if you wish.
 
 ## Simple element definition
 
-Use `defineFunctionalElement` to define your element. Tt must be given 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 you're not setting inputs (or just for now as you're getting started). It must be given an object with at least `tagName` and `renderCallback` properties (the types enforce this). Here is a bare-minimum example custom element:
 
 <!-- example-link: src/readme-examples/my-simple.element.ts -->
 
 ```TypeScript
-import {defineFunctionalElement, html} from 'element-vir';
+import {defineElementNoInputs, html} from 'element-vir';
 
-export const MySimpleElement = defineFunctionalElement({
+export const MySimpleElement = defineElementNoInputs({
     tagName: 'my-simple-element',
     renderCallback: () => html`
         <span>Hello there!</span>
@@ -54,15 +54,15 @@ Make sure to export your element definition if you need to use it in other files
 
 ## Using in other elements
 
-To use already defined functional elements (like `my-simple-element` above), they must be interpolated into HTML templates like so:
+To use already defined elements (like `my-simple-element` above), they must be interpolated into HTML templates like so:
 
 <!-- example-link: src/readme-examples/my-app.element.ts -->
 
 ```TypeScript
-import {defineFunctionalElement, html} from 'element-vir';
+import {defineElementNoInputs, html} from 'element-vir';
 import {MySimpleElement} from './my-simple.element';
 
-export const MyAppElement = defineFunctionalElement({
+export const MyAppElement = defineElementNoInputs({
     tagName: 'my-app-element',
     renderCallback: () => html`
         <h1>My App</h1>
@@ -77,14 +77,14 @@ If you wish to bypass this interpolation, make sure to [import the `html` tagged
 
 ## Adding styles
 
-Styles are added through the `styles` property when defining a functional element (similar to [how they are defined in `lit`](https://lit.dev/docs/components/styles/)):
+Styles are added through the `styles` property when defining a declarative element (similar to [how they are defined in `lit`](https://lit.dev/docs/components/styles/)):
 
 <!-- example-link: src/readme-examples/my-simple-app-with-styles.element.ts -->
 
 ```TypeScript
-import {css, defineFunctionalElement, html} from 'element-vir';
+import {css, defineElementNoInputs, html} from 'element-vir';
 
-export const MySimpleWithStylesElement = defineFunctionalElement({
+export const MySimpleWithStylesElement = defineElementNoInputs({
     tagName: 'my-simple-with-styles-element',
     styles: css`
         :host {
@@ -106,15 +106,15 @@ export const MySimpleWithStylesElement = defineFunctionalElement({
 
 ### Element definition as style selector
 
-Functional element definitions can be used in the `css` tagged template just like in the `html` tagged template. This will be replaced by the element's tag name:
+Declarative element definitions can be used in the `css` tagged template just like in the `html` tagged template. This will be replaced by the element's tag name:
 
 <!-- example-link: src/readme-examples/my-simple-app-with-styles-and-interpolated-selector.element.ts -->
 
 ```TypeScript
-import {css, defineFunctionalElement, html} from 'element-vir';
+import {css, defineElementNoInputs, html} from 'element-vir';
 import {MySimpleElement} from './my-simple.element';
 
-export const MySimpleWithStylesAndInterpolatedSelectorElement = defineFunctionalElement({
+export const MySimpleWithStylesAndInterpolatedSelectorElement = defineElementNoInputs({
     tagName: 'my-simple-with-styles-and-interpolated-selector-element',
     styles: css`
         ${MySimpleElement} {
@@ -127,51 +127,50 @@ export const MySimpleWithStylesAndInterpolatedSelectorElement = defineFunctional
 });
 ```
 
-## Defining and using properties (inputs)
+## Defining and using Inputs
 
-Define element properties with `props` when making a functional element. Each property must be given a default value. If you wish to leave the property's default value as `undefined`, give it a type as well (shown below with `as string | undefined`) so you can assign a defined value of that type to it later.
+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 a custom element's properties, grab `props` 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 `renderCallback`'s parameters and interpolate it into your HTML template:
 
-<!-- example-link: src/readme-examples/my-simple-with-props.element.ts -->
+<!-- example-link: src/readme-examples/my-simple-with-inputs.element.ts -->
 
 ```TypeScript
-import {defineFunctionalElement, html} from 'element-vir';
-
-export const MySimpleWithPropsElement = defineFunctionalElement({
-    tagName: 'my-simple-element-with-props',
-    props: {
-        currentUsername: 'dev',
-        currentEmail: undefined as string | undefined,
-    },
-    renderCallback: ({props}) => html`
-        <span>Hello there ${props.currentUsername}!</span>
+import {defineElement, html} from 'element-vir';
+
+export const MySimpleWithInputsElement = defineElement<{
+    username: string;
+    email: string;
+}>()({
+    tagName: 'my-simple-element-with-inputs',
+    renderCallback: ({inputs}) => html`
+        <span>Hello there ${inputs.username}!</span>
     `,
 });
 ```
 
-### Updating properties
+## Defining internal state
 
-Grab `setProps` from `renderCallback`'s parameters to update the values in `props`. This causes a re-render. (Note that this example also uses the `listen` directive to respond to click events.)
+Define internal state with the `stateInit` property when defining an element. Grab it with `state` in `renderCallback` to use state. Grab `updateState` in `renderCallback` to update state:
 
-<!-- example-link: src/readme-examples/my-simple-with-set-props.element.ts -->
+<!-- example-link: src/readme-examples/my-simple-with-update-state.element.ts -->
 
 ```TypeScript
-import {defineFunctionalElement, html, listen} from 'element-vir';
+import {defineElementNoInputs, html, listen} from 'element-vir';
 
-export const MySimpleWithPropsElement = defineFunctionalElement({
-    tagName: 'my-simple-element-with-props',
-    props: {
-        currentUsername: 'dev',
-        currentEmail: undefined as string | undefined,
+export const MySimpleWithUpdateStateElement = defineElementNoInputs({
+    tagName: 'my-simple-element-with-update-state',
+    stateInit: {
+        username: 'dev',
+        email: undefined as string | undefined,
     },
-    renderCallback: ({props, setProps}) => html`
+    renderCallback: ({state, updateState}) => html`
         <span
             ${listen('click', () => {
-                setProps({currentUsername: 'new name!'});
+                updateState({username: 'new name!'});
             })}
         >
-            Hello there ${props.currentUsername}!
+            Hello there ${state.username}!
         </span>
     `,
 });
@@ -181,37 +180,39 @@ export const MySimpleWithPropsElement = defineFunctionalElement({
 
 Use the `assign` directive to assign properties to child custom elements:
 
-<!-- example-link: src/readme-examples/my-app-with-props.element.ts -->
+<!-- example-link: src/readme-examples/my-app-with-assignment.element.ts -->
 
 ```TypeScript
-import {assign, defineFunctionalElement, html} from 'element-vir';
-import {MySimpleWithPropsElement} from './my-simple-with-props.element';
+import {assign, defineElementNoInputs, html} from 'element-vir';
+import {MySimpleWithInputsElement} from './my-simple-with-inputs.element';
 
-export const MyAppWithPropsElement = defineFunctionalElement({
-    tagName: 'my-app-with-props-element',
+export const MyAppWithAssignmentElement = defineElementNoInputs({
+    tagName: 'my-app-with-assignment-element',
     renderCallback: () => html`
         <h1>My App</h1>
-        <${MySimpleWithPropsElement}
-            ${assign(MySimpleWithPropsElement.props.currentUsername, 'user')}
-            ${assign(MySimpleWithPropsElement.props.currentEmail, 'user@example.com')}
+        <${MySimpleWithInputsElement}
+            ${assign(MySimpleWithInputsElement, {
+                email: 'user@example.com',
+                username: 'user',
+            })}
         >
-        </${MySimpleWithPropsElement}>
+        </${MySimpleWithInputsElement}>
     `,
 });
 ```
 
 ## Element events (outputs)
 
-Define events with `events` when making a functional element. Each event must be initialized with `defineElementEvent` and a type parameter. `defineElementEvent` accepts no inputs as it doesn't make sense for events to have default values.
+Define events with `events` when defining a declarative element. Each event must be initialized with `defineElementEvent` and a type parameter. `defineElementEvent` accepts no inputs as it doesn't make sense for events to have default values.
 
 To dispatch an event, grab `dispatch` from `renderCallback`'s parameters.
 
 <!-- example-link: src/readme-examples/my-simple-with-events.element.ts -->
 
 ```TypeScript
-import {defineElementEvent, defineFunctionalElement, html, listen} from 'element-vir';
+import {defineElementEvent, defineElementNoInputs, html, listen} from 'element-vir';
 
-export const MySimpleWithEventsElement = defineFunctionalElement({
+export const MySimpleWithEventsElement = defineElementNoInputs({
     tagName: 'my-simple-element-with-events',
     events: {
         logoutClick: defineElementEvent<void>(),
@@ -230,31 +231,31 @@ export const MySimpleWithEventsElement = defineFunctionalElement({
 
 ### Listening to typed events (outputs)
 
-Use the `listen` directive to listen to typed events emitted by your custom functional elements:
+Use the `listen` directive to listen to typed events emitted by your custom elements:
 
 <!-- example-link: src/readme-examples/my-app-with-events.element.ts -->
 
 ```TypeScript
-import {defineFunctionalElement, html, listen} from 'element-vir';
+import {defineElementNoInputs, html, listen} from 'element-vir';
 import {MySimpleWithEventsElement} from './my-simple-with-events.element';
 
-export const MyAppWithEventsElement = defineFunctionalElement({
+export const MyAppWithEventsElement = defineElementNoInputs({
     tagName: 'my-app-with-events-element',
-    props: {
+    stateInit: {
         myNumber: -1,
     },
-    renderCallback: ({props, setProps}) => html`
+    renderCallback: ({state, updateState}) => html`
         <h1>My App</h1>
         <${MySimpleWithEventsElement}
             ${listen(MySimpleWithEventsElement.events.logoutClick, () => {
                 console.info('logout triggered');
             })}
             ${listen(MySimpleWithEventsElement.events.randomNumber, (event) => {
-                setProps({myNumber: event.detail});
+                updateState({myNumber: event.detail});
             })}
         >
         </${MySimpleWithEventsElement}>
-        <span>${props.myNumber}</span>
+        <span>${state.myNumber}</span>
     `,
 });
 ```
@@ -282,15 +283,15 @@ Both dispatching a custom event and listening to a custom event:
 <!-- example-link: src/readme-examples/custom-event-usage.element.ts -->
 
 ```TypeScript
-import {defineFunctionalElement, html, listen} from 'element-vir';
+import {defineElementNoInputs, html, listen} from 'element-vir';
 import {MyCustomEvent} from './custom-event-no-element';
 
-export const MyElementWithCustomEvents = defineFunctionalElement({
+export const MyElementWithCustomEvents = defineElementNoInputs({
     tagName: 'my-app-with-custom-events',
     renderCallback: ({genericDispatch}) => html`
         <div
             ${listen(MyCustomEvent, (event) => {
-                console.log(`Got a number! ${event.detail}`);
+                console.info(`Got a number! ${event.detail}`);
             })}
         >
             <div
@@ -314,11 +315,11 @@ Apply host classes in the element's stylesheet by using a callback for the style
 <!-- example-link: src/readme-examples/host-class-definition.ts -->
 
 ```TypeScript
-import {css, defineFunctionalElement, html} from 'element-vir';
+import {css, defineElementNoInputs, html} from 'element-vir';
 
-export const MyAppWithHostClasses = defineFunctionalElement({
+export const MyAppWithHostClasses = defineElementNoInputs({
     tagName: 'my-app-with-host-classes',
-    props: {
+    stateInit: {
         myProp: 'hello there',
     },
     hostClasses: {
@@ -331,8 +332,8 @@ export const MyAppWithHostClasses = defineFunctionalElement({
          * This host class will be automatically applied if the given callback evaluated to true
          * after a call to renderCallback.
          */
-        automaticallyAppliedVariation: ({props}) => {
-            return props.myProp === 'foo';
+        automaticallyAppliedVariation: ({state}) => {
+            return state.myProp === 'foo';
         },
     },
     /**
@@ -348,8 +349,8 @@ export const MyAppWithHostClasses = defineFunctionalElement({
             color: red;
         }
     `,
-    renderCallback: ({props}) => html`
-        ${props.myProp}
+    renderCallback: ({state}) => html`
+        ${state.myProp}
     `,
 });
 ```
@@ -361,9 +362,9 @@ Typed CSS vars are created in a similar way as host classes:
 <!-- example-link: src/readme-examples/css-vars-definition.ts -->
 
 ```TypeScript
-import {css, defineFunctionalElement, html} from 'element-vir';
+import {css, defineElementNoInputs, html} from 'element-vir';
 
-export const MyAppWithCssVars = defineFunctionalElement({
+export const MyAppWithCssVars = defineElementNoInputs({
     tagName: 'my-app-with-css-vars',
     cssVars: {
         /**
@@ -397,15 +398,15 @@ This triggers only once when the element it's attached has actually been created
 <!-- example-link: src/readme-examples/my-simple-with-on-dom-created.element.ts -->
 
 ```TypeScript
-import {defineFunctionalElement, html, onDomCreated} from 'element-vir';
+import {defineElementNoInputs, html, onDomCreated} from 'element-vir';
 
-export const MySimpleWithOnDomCreatedElement = defineFunctionalElement({
+export const MySimpleWithOnDomCreatedElement = defineElementNoInputs({
     tagName: 'my-simple-with-on-dom-created-element',
     renderCallback: () => html`
         <span
             ${onDomCreated((element) => {
                 // logs a span element
-                console.log(element);
+                console.info(element);
             })}
         >
             Hello there!
@@ -421,16 +422,16 @@ This directive fulfills a common use case of triggering callbacks when something
 <!-- example-link: src/readme-examples/my-simple-with-on-resize.element.ts -->
 
 ```TypeScript
-import {defineFunctionalElement, html, onResize} from 'element-vir';
+import {defineElementNoInputs, html, onResize} from 'element-vir';
 
-export const MySimpleWithOnResizeElement = defineFunctionalElement({
+export const MySimpleWithOnResizeElement = defineElementNoInputs({
     tagName: 'my-simple-with-on-dom-created-element',
     renderCallback: () => html`
         <span
             ${onResize((entry) => {
                 // this will track resizing of this span
                 // the entry parameter contains target and contentRect properties
-                console.log(entry);
+                console.info(entry);
             })}
         >
             Hello there!
@@ -454,40 +455,43 @@ This directive is the same as the `assign` directive but it accepts an additiona
 <!-- example-link: src/readme-examples/my-app-with-cleanup.element.ts -->
 
 ```TypeScript
-import {assign, assignWithCleanup, defineFunctionalElement, html} from 'element-vir';
-import {MySimpleWithPropsElement} from './my-simple-with-props.element';
+import {assignWithCleanup, defineElementNoInputs, html} from 'element-vir';
+import {MySimpleWithInputsElement} from './my-simple-with-inputs.element';
 
-export const MyAppWithPropsElement = defineFunctionalElement({
+export const MyAppWithAssignmentCleanupElement = defineElementNoInputs({
     tagName: 'my-app-with-cleanup',
     renderCallback: () => html`
         <h1>My App</h1>
-        <${MySimpleWithPropsElement}
+        <${MySimpleWithInputsElement}
             ${assignWithCleanup(
-                MySimpleWithPropsElement.props.currentUsername,
-                'user',
+                MySimpleWithInputsElement,
+                {
+                    email: 'user@example.com',
+                    username: 'user',
+                },
                 (previousValue) => {
                     // here would be the cleanup code.
-                    // In this specific example the value is just a string, so no cleanup is needed.
-                    previousValue.trim();
+                    // In this specific example the value is just a string, so no cleanup is needed
+                    // and the following line isn't actually doing anything.
+                    previousValue.username.trim();
                 },
             )}
-            ${assign(MySimpleWithPropsElement.props.currentEmail, 'user@example.com')}
         >
-        </${MySimpleWithPropsElement}>
+        </${MySimpleWithInputsElement}>
     `,
 });
 ```
 
-## Require all child custom elements to be functional elements
+## Require all child custom elements to be declarative elements
 
-To require all child elements to be functional elements defined by this package, call `requireAllCustomElementsToBeFunctionalElement` anywhere in your app. This is a global setting so do not enable it unless you want it to be true _everywhere_ in your current run-time. This should not be used if you're using custom elements from other libraries (unless they happen to also use this package to define their custom elements).
+To require all child elements to be declarative elements defined by this package, call `requireAllCustomElementsToBeDeclarativeElements` anywhere in your app. This is a global setting so do not enable it unless you want it to be true _everywhere_ in your current run-time. This should not be used if you're using custom elements from other libraries (unless they happen to also use this package to define their custom elements).
 
-<!-- example-link: src/readme-examples/require-functional-element.ts -->
+<!-- example-link: src/readme-examples/require-declarative-element.ts -->
 
 ```TypeScript
-import {requireAllCustomElementsToBeFunctionalElement} from 'element-vir';
+import {requireAllCustomElementsToBeDeclarativeElements} from 'element-vir';
 
-requireAllCustomElementsToBeFunctionalElement();
+requireAllCustomElementsToBeDeclarativeElements();
 ```
 
 # Dev

package/dist/augments/testing.d.ts

@@ -0,0 +1,15 @@
+import { DeclarativeElementDefinition } from '../declarative-element/declarative-element';
+/**
+ * Wrapper for assert.instanceOf that also works with TypeScript in setting the proper types.
+ *
+ * Do not use this in production code! It should only be used in testing code.
+ */
+export declare function assertInstanceOf<T>(value: unknown, constructor: new (...args: any) => T, message?: string): asserts value is T;
+export declare function isInstanceOf<T>(value: unknown, constructor: new (...args: any) => T): value is T;
+export declare function getAssertedDeclarativeElement<DeclarativeElementGeneric extends DeclarativeElementDefinition>(searchFor: DeclarativeElementGeneric, searchIn: Element): DeclarativeElementGeneric['instanceType'];
+export declare function testIdSelector(testId: string): string;
+export declare function getCenterOfElement(element: Element): [number, number];
+export declare function queryWithAssert<T extends Element>(query: string | [string, ...string[]], constructor: new (...args: any) => T, searchIn: Element | Document): T;
+export declare function assertRejects(input: () => PromiseLike<any>, message?: string): Promise<void>;
+export declare function assertRejects(input: () => PromiseLike<any>, errType: RegExp | ErrorConstructor, message?: string): Promise<void>;
+export declare function assertRejects(input: () => PromiseLike<any>, errType: ErrorConstructor, regExp: RegExp): Promise<void>;

package/dist/augments/testing.js

@@ -0,0 +1,76 @@
+import { assert } from '@open-wc/testing';
+/**
+ * Wrapper for assert.instanceOf that also works with TypeScript in setting the proper types.
+ *
+ * Do not use this in production code! It should only be used in testing code.
+ */
+export function assertInstanceOf(value, constructor, message) {
+    assert.instanceOf(value, constructor, message);
+}
+export function isInstanceOf(value, constructor) {
+    return value instanceof constructor;
+}
+export function getAssertedDeclarativeElement(searchFor, searchIn) {
+    if (searchIn.tagName.toLowerCase() === searchFor.tagName.toLowerCase()) {
+        assertInstanceOf(searchIn, searchFor);
+        return searchIn;
+    }
+    const result = queryTree(searchIn, [searchFor.tagName]);
+    assertInstanceOf(result, searchFor);
+    assert.strictEqual(result.tagName, searchFor.tagName);
+    return result;
+}
+export function testIdSelector(testId) {
+    return `[data-test-id="${testId}"]`;
+}
+export function getCenterOfElement(element) {
+    const rect = element.getBoundingClientRect();
+    return [
+        Math.floor((rect.left + rect.right) / 2),
+        Math.floor((rect.bottom + rect.top) / 2),
+    ];
+}
+export function queryWithAssert(query, constructor, searchIn) {
+    if (!Array.isArray(query)) {
+        query = [query];
+    }
+    const result = queryTree(searchIn, query);
+    assertInstanceOf(result, constructor);
+    return result;
+}
+/** Accounts for shadow DOM */
+function queryTree(context, 
+// at least one string is required or this function makes no sense
+selectors) {
+    /**
+     * The callback is split out here to appease the Type Gods. Without it, finalElement will be the
+     * type of the internal currentContext (which is incorrect).
+     */
+    const reduceCallback = (currentContext, selector) => {
+        var _a;
+        if (!currentContext) {
+            return undefined;
+        }
+        if ('shadowRoot' in currentContext && currentContext.shadowRoot) {
+            currentContext = currentContext.shadowRoot;
+        }
+        return (_a = currentContext.querySelector(selector)) !== null && _a !== void 0 ? _a : undefined;
+    };
+    const finalElement = selectors.reduce(reduceCallback, context);
+    return finalElement;
+}
+export async function assertRejects(input, messageOrRegExpOrError, messageOrRegExp) {
+    let thrown = undefined;
+    let errorThrown = false;
+    try {
+        await input();
+    }
+    catch (error) {
+        errorThrown = true;
+        thrown = error;
+    }
+    assert.isTrue(errorThrown, 'No error was thrown.');
+    assert.throws(() => {
+        throw thrown;
+    }, messageOrRegExpOrError, messageOrRegExp);
+}

package/dist/augments/type.d.ts

@@ -1 +1,8 @@
 export declare type NonEmptyString<T> = T extends '' ? never : T;
+/**
+ * If the given value is not an instance of the given constructor, an error is thrown.
+ *
+ * This is a variation of assertInstanceOf that can be run in run-time code and doesn't require
+ * testing packages.
+ */
+export declare function ensureInstanceOf<T>(value: unknown, constructor: new (...args: any) => T, message?: string): asserts value is T;

package/dist/augments/type.js

@@ -1 +1,13 @@
-export {};
+/**
+ * If the given value is not an instance of the given constructor, an error is thrown.
+ *
+ * This is a variation of assertInstanceOf that can be run in run-time code and doesn't require
+ * testing packages.
+ */
+export function ensureInstanceOf(value, constructor, message) {
+    if (!(value instanceof constructor)) {
+        const extraMessage = message ? `: ${message}` : '';
+        const errorMessage = `${value} is not an instanceof of ${constructor.name}${extraMessage}`;
+        throw new TypeError(errorMessage);
+    }
+}

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

@@ -0,0 +1,33 @@
+import { CSSResult } from 'lit';
+import { CssVarsInitMap } from './css-vars';
+import { DeclarativeElementDefinitionOptions } from './definition-options';
+import { EventsInitMap } from './element-events';
+import { PropertyInitMapBase } from './element-properties';
+import { HostClassesInitMap } from './host-classes';
+import { InitCallback, RenderCallback } from './render-callback';
+import { StylesCallback } from './styles';
+export declare type CustomElementTagName = `${string}-${string}`;
+export declare type DeclarativeElementInit<InputsGeneric extends PropertyInitMapBase, StateInit extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeys extends string, CssVarKeys extends string> = {
+    /**
+     * HTML tag name. This should not be used directly, as interpolating it with the html tagged
+     * template from this package is preferred.
+     */
+    tagName: CustomElementTagName;
+    /** Static styles. These should not and cannot change. */
+    styles?: CSSResult | StylesCallback<HostClassKeys, CssVarKeys>;
+    /** Element properties. (These can be thought of as "inputs".) */
+    stateInit?: StateInit;
+    /** Events that the element can dispatch. (These can be thought of as "outputs".) */
+    events?: EventsInitGeneric;
+    /**
+     * CSS host classes. Values can be callbacks to determine when a host class should be defined,
+     * based on current instance state or inputs, or just undefined to indicate that the host class
+     * will only be manually set.
+     */
+    hostClasses?: HostClassesInitMap<HostClassKeys, InputsGeneric, StateInit>;
+    cssVars?: CssVarsInitMap<CssVarKeys>;
+    /** Called as part of the first renderCallback call, before the first renderCallback call. */
+    initCallback?: InitCallback<InputsGeneric, StateInit, EventsInitGeneric, HostClassKeys, CssVarKeys>;
+    renderCallback: RenderCallback<InputsGeneric, StateInit, EventsInitGeneric, HostClassKeys, CssVarKeys>;
+    options?: Partial<DeclarativeElementDefinitionOptions> | undefined;
+};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,44 @@
+import { RequiredBy } from 'augment-vir';
+import { CSSResult, LitElement, TemplateResult } from 'lit';
+import { CssVarNameOrValueMap } from './css-vars';
+import { DeclarativeElementInit } from './declarative-element-init';
+import { EventDescriptorMap, EventsInitMap } from './element-events';
+import { ElementPropertyDescriptorMap, PropertyInitMapBase } from './element-properties';
+import { HostClassNamesMap } from './host-classes';
+import { RenderCallback } from './render-callback';
+export declare type DeclarativeElementDefinition<InputsGeneric extends PropertyInitMapBase = any, PropertyInitGeneric extends PropertyInitMapBase = any, EventsInitGeneric extends EventsInitMap = any, HostClassKeys extends string = string, CssVarKeys extends string = string> = (new () => DeclarativeElement<InputsGeneric, PropertyInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>) & StaticDeclarativeElementProperties<InputsGeneric, PropertyInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys> & {
+    instanceType: DeclarativeElement<InputsGeneric, PropertyInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>;
+};
+export declare abstract class DeclarativeElement<InputsGeneric extends PropertyInitMapBase = any, PropertyInitGeneric extends PropertyInitMapBase = any, EventsInitGeneric extends EventsInitMap = any, HostClassKeys extends string = string, CssVarKeys extends string = string> extends LitElement {
+    static readonly tagName: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['tagName'];
+    static readonly styles: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['styles'];
+    static readonly isStrictInstance: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['isStrictInstance'];
+    static readonly renderCallback: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['renderCallback'];
+    static readonly inputsType: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['inputsType'];
+    static readonly events: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['events'];
+    static readonly stateInit: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['stateInit'];
+    static readonly init: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['init'];
+    static readonly hostClasses: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['hostClasses'];
+    static readonly cssVarNames: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['cssVarNames'];
+    static readonly cssVarValues: StaticDeclarativeElementProperties<PropertyInitMapBase, PropertyInitMapBase, EventsInitMap, string, string>['cssVarValues'];
+    abstract render(): TemplateResult | Promise<TemplateResult>;
+    abstract readonly instanceState: PropertyInitGeneric;
+    abstract readonly instanceInputs: InputsGeneric;
+    abstract readonly haveInputsBeenSet: boolean;
+    abstract markInputsAsHavingBeenSet(): void;
+    abstract readonly creator: DeclarativeElementDefinition<InputsGeneric, PropertyInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>;
+}
+export interface StaticDeclarativeElementProperties<InputsGeneric extends PropertyInitMapBase, PropertyInitGeneric extends PropertyInitMapBase, EventsInitGeneric extends EventsInitMap, HostClassKeys extends string, CssVarKeys extends string> {
+    /** Pass through the render callback for direct unit testability */
+    readonly renderCallback: RenderCallback<InputsGeneric, PropertyInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>;
+    events: EventDescriptorMap<EventsInitGeneric>;
+    stateInit: ElementPropertyDescriptorMap<PropertyInitGeneric>;
+    init: RequiredBy<DeclarativeElementInit<InputsGeneric, PropertyInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>, 'stateInit' | 'events'>;
+    inputsType: InputsGeneric;
+    isStrictInstance: (element: unknown) => element is DeclarativeElement<InputsGeneric, PropertyInitGeneric, EventsInitGeneric, HostClassKeys, CssVarKeys>;
+    hostClasses: HostClassNamesMap<string, HostClassKeys>;
+    cssVarNames: CssVarNameOrValueMap<CssVarKeys>;
+    cssVarValues: CssVarNameOrValueMap<CssVarKeys>;
+    tagName: string;
+    styles: CSSResult;
+}