element-vir 5.5.1 → 6.0.0-beta.1

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.
+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,91 +127,92 @@ 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>
     `,
 });
 ```
 
-## Assigning to properties (inputs)
+### Assigning to properties (inputs)
 
 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>(),
@@ -228,33 +229,33 @@ export const MySimpleWithEventsElement = defineFunctionalElement({
 });
 ```
 
-## Listening to typed events (outputs)
+### 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
@@ -303,6 +304,87 @@ export const MyElementWithCustomEvents = defineFunctionalElement({
 });
 ```
 
+## Host classes
+
+Host classes can be defined and used with type safety. Host classes are used to provide alternative styles for components. They are purely driven by CSS and are thus applied via the `class` HTML attribute.
+
+Host classes that are defined with a callback will automatically get applied if that callback returns true after a render is executed. These are executed _after_ `renderCallback` is executed. When a definition is set to `false`, it's left to the element's consumer to apply the host class.
+
+Apply host classes in the element's stylesheet by using a callback for the styles property.
+
+<!-- example-link: src/readme-examples/host-class-definition.ts -->
+
+```TypeScript
+import {css, defineElementNoInputs, html} from 'element-vir';
+
+export const MyAppWithHostClasses = defineElementNoInputs({
+    tagName: 'my-app-with-host-classes',
+    stateInit: {
+        myProp: 'hello there',
+    },
+    hostClasses: {
+        /**
+         * Setting the value to false means this host class will not ever automatically be applied.
+         * It will simply be a static member on the element for manual application in consumers when desired.
+         */
+        styleVariationA: false,
+        /**
+         * This host class will be automatically applied if the given callback evaluated to true
+         * after a call to renderCallback.
+         */
+        automaticallyAppliedVariation: ({state}) => {
+            return state.myProp === 'foo';
+        },
+    },
+    /**
+     * Apply styles to the host classes by using a callback for "styles". The callback's argument
+     * contains the host classes defined above in the "hostClasses" property.
+     */
+    styles: ({hostClass}) => css`
+        ${hostClass.automaticallyAppliedVariation} {
+            color: blue;
+        }
+
+        ${hostClass.styleVariationA} {
+            color: red;
+        }
+    `,
+    renderCallback: ({state}) => html`
+        ${state.myProp}
+    `,
+});
+```
+
+## CSS Vars
+
+Typed CSS vars are created in a similar way as host classes:
+
+<!-- example-link: src/readme-examples/css-vars-definition.ts -->
+
+```TypeScript
+import {css, defineElementNoInputs, html} from 'element-vir';
+
+export const MyAppWithCssVars = defineElementNoInputs({
+    tagName: 'my-app-with-css-vars',
+    cssVars: {
+        /**
+         * The value assigned here ('blue') becomes the fallback value for this CSS var when used
+         * via "cssVarValue".
+         */
+        myCssVar: 'blue',
+    },
+    styles: ({cssVarName, cssVarValue}) => css`
+        :host {
+            /* Set CSS vars (or reference the name directly) via "cssVarName" */
+            ${cssVarName.myCssVar}: yellow;
+            /* Use CSS vars with "cssVarValue". This includes a "var" wrapper and the assigned fallback value (which in this case is 'blue'). */
+            color: ${cssVarValue.myCssVar};
+        }
+    `,
+    renderCallback: () => html``,
+});
+```
+
 ## Directives
 
 The following custom [`lit` directives](https://lit.dev/docs/templates/custom-directives/) are contained within this package.
@@ -316,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!
@@ -340,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!
@@ -373,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

@@ -0,0 +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

@@ -0,0 +1,13 @@
+/**
+ * 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/css-vars.d.ts

@@ -0,0 +1,6 @@
+import { CSSResult } from 'lit';
+export declare type CssVarsInitMap<CssVarKeys extends string> = Record<CssVarKeys, string>;
+export declare type CssVarName<TagName extends string> = `--${TagName}-string`;
+export declare type CssVarNameOrValueMap<CssVarKeys extends string> = Record<CssVarKeys, CSSResult>;
+export declare function createCssVarNamesMap<TagName extends string, CssVarKeys extends string>(tagName: TagName, cssVarsInit: CssVarsInitMap<CssVarKeys> | undefined): CssVarNameOrValueMap<CssVarKeys>;
+export declare function createCssVarValuesMap<CssVarKeys extends string>(cssVarInitMap: CssVarsInitMap<CssVarKeys> | undefined, cssVarNamesMap: CssVarNameOrValueMap<CssVarKeys>): CssVarNameOrValueMap<CssVarKeys>;

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

@@ -0,0 +1,22 @@
+import { mapObject } from 'augment-vir';
+import { unsafeCSS } from 'lit';
+import { toHtmlSafeWithTagName } from './tag-name';
+export function createCssVarNamesMap(tagName, cssVarsInit) {
+    if (cssVarsInit) {
+        return mapObject(cssVarsInit, (key) => {
+            return unsafeCSS(`--${toHtmlSafeWithTagName(tagName, String(key))}`);
+        });
+    }
+    else {
+        return {};
+    }
+}
+export function createCssVarValuesMap(cssVarInitMap, cssVarNamesMap) {
+    if (!cssVarInitMap) {
+        return {};
+    }
+    return mapObject(cssVarInitMap, (key, fallbackValue) => {
+        const name = cssVarNamesMap[key];
+        return unsafeCSS(`var(${name}, ${fallbackValue})`);
+    });
+}