element-vir 22.2.2 → 23.1.0

package/dist/template-transforms/vir-css/css-transform.js

@@ -1,5 +1,6 @@
-import { hasTagName } from '../minimal-element-definition';
-import { transformTemplate } from '../transform-template';
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { hasTagName } from '../minimal-element-definition.js';
+import { transformTemplate } from '../transform-template.js';
 function transformCss(...[lastNewString, currentLitString, currentValue,]) {
     if (!hasTagName(currentValue)) {
         return undefined;

package/dist/template-transforms/vir-css/vir-css.d.ts

@@ -1,3 +1,12 @@
-import { CSSResult, CSSResultGroup } from '../../lit-exports/all-lit-exports';
-import { MinimalElementDefinition } from '../minimal-element-definition';
+import { CSSResult, CSSResultGroup } from '../../lit-exports/all-lit-exports.js';
+import { MinimalElementDefinition } from '../minimal-element-definition.js';
+/**
+ * A template literal tag used to define styles for element definitions. In particular, this is used
+ * for the `styles` property in an element definitions init object.
+ *
+ * For security reasons, only literal string or number values may be interpolated inside of this
+ * taggedTemplate. To incorporate non-literal values, wrap the value in a call to `unsafeCSS`.
+ *
+ * @category Element Definition
+ */
 export declare function css(inputTemplateStrings: TemplateStringsArray, ...inputValues: (number | CSSResultGroup | MinimalElementDefinition | CSSResult)[]): CSSResult;

package/dist/template-transforms/vir-css/vir-css.js

@@ -1,6 +1,15 @@
 import { css as litCss } from 'lit';
-import { getTransformedTemplate } from '../transform-template';
-import { transformCssTemplate } from './css-transform';
+import { getTransformedTemplate } from '../transform-template.js';
+import { transformCssTemplate } from './css-transform.js';
+/**
+ * A template literal tag used to define styles for element definitions. In particular, this is used
+ * for the `styles` property in an element definitions init object.
+ *
+ * For security reasons, only literal string or number values may be interpolated inside of this
+ * taggedTemplate. To incorporate non-literal values, wrap the value in a call to `unsafeCSS`.
+ *
+ * @category Element Definition
+ */
 export function css(inputTemplateStrings, ...inputValues) {
     const transformedTemplate = getTransformedTemplate(inputTemplateStrings, inputValues, () => {
         return transformCssTemplate(inputTemplateStrings, inputValues);

package/dist/template-transforms/vir-html/html-interpolation.d.ts

@@ -1,15 +1,19 @@
-import { AnyFunction } from '@augment-vir/common';
-import { CSSResult, TemplateResult, nothing } from 'lit';
-import { EmptyObject } from 'type-fest';
-import { DeclarativeElementDefinition } from '../../declarative-element/declarative-element';
-import { MinimalDefinitionWithInputs, MinimalElementDefinition } from '../minimal-element-definition';
+import { type AnyFunction } from '@augment-vir/common';
+import { type CSSResult, type TemplateResult, type nothing } from 'lit';
+import { type EmptyObject } from 'type-fest';
+import { type DeclarativeElementDefinition } from '../../declarative-element/declarative-element.js';
+import { type MinimalDefinitionWithInputs, type MinimalElementDefinition } from '../minimal-element-definition.js';
 /**
  * Unfortunately the type for `DirectiveResult` means it's just an empty object. So in order to
  * block actual objects, we have to narrow `DirectiveResult` further to this empty object type.
+ *
+ * @category Internal
  */
 export type DirectiveOutput = EmptyObject;
 /**
  * This is used in order to block accidental object interpolations into HTML, which get stringified
  * into `'[object Object]'`, which nobody ever wants that.
+ *
+ * @category Internal
  */
 export type HtmlInterpolation = null | undefined | string | number | boolean | bigint | CSSResult | Readonly<CSSResult> | Element | Readonly<Element> | TemplateResult | Readonly<TemplateResult> | MinimalElementDefinition | Readonly<MinimalElementDefinition> | MinimalDefinitionWithInputs | Readonly<MinimalDefinitionWithInputs> | DeclarativeElementDefinition | Readonly<DeclarativeElementDefinition> | DirectiveOutput | Readonly<DirectiveOutput> | AnyFunction | typeof nothing | HtmlInterpolation[] | ReadonlyArray<HtmlInterpolation>;

package/dist/template-transforms/vir-html/html-transform.d.ts

@@ -1,5 +1,5 @@
-import { HTMLTemplateResult } from '../../lit-exports/all-lit-exports';
-import { TemplateTransform } from '../template-transform-type';
-import { HtmlInterpolation } from './html-interpolation';
+import { HTMLTemplateResult } from '../../lit-exports/all-lit-exports.js';
+import { TemplateTransform } from '../template-transform-type.js';
+import { HtmlInterpolation } from './html-interpolation.js';
 export declare function mapHtmlValues(inputTemplateStrings: TemplateStringsArray, inputValues: HtmlInterpolation[]): HtmlInterpolation[];
 export declare function transformHtmlTemplate(litTemplate: HTMLTemplateResult): TemplateTransform;

package/dist/template-transforms/vir-html/html-transform.js

@@ -1,17 +1,19 @@
-import { collapseWhiteSpace, getOrSet, isTruthy, safeMatch } from '@augment-vir/common';
-import { isRunTimeType } from 'run-time-assertions';
-import { assign } from '../../declarative-element/directives/assign.directive';
-import { declarativeElementRequired } from '../../require-declarative-element';
-import { hasTagName, isMinimalDefinitionWithInputs, } from '../minimal-element-definition';
-import { transformTemplate } from '../transform-template';
-import { tagNameKeys } from './tag-name-keys';
+/* eslint-disable @typescript-eslint/no-deprecated */
+/* eslint-disable sonarjs/deprecation */
+import { check } from '@augment-vir/assert';
+import { collapseWhiteSpace, getOrSet, safeMatch } from '@augment-vir/common';
+import { assign } from '../../declarative-element/directives/assign.directive.js';
+import { declarativeElementRequired } from '../../require-declarative-element.js';
+import { hasTagName, isMinimalDefinitionWithInputs, } from '../minimal-element-definition.js';
+import { transformTemplate } from '../transform-template.js';
+import { tagNameKeys } from './tag-name-keys.js';
 export function mapHtmlValues(inputTemplateStrings, inputValues) {
     return inputValues.map((currentValue, currentValueIndex) => {
         const lastString = inputTemplateStrings[currentValueIndex];
         const nextString = inputTemplateStrings[currentValueIndex + 1];
         if (lastString && nextString) {
             const { shouldHaveTagNameHere } = classifyValue(lastString, nextString);
-            if (shouldHaveTagNameHere && isRunTimeType(currentValue, 'string')) {
+            if (shouldHaveTagNameHere && check.isString(currentValue)) {
                 const replacement = {
                     tagName: currentValue,
                     tagInterpolationKey: getOrSet(tagNameKeys, currentValue, () => {
@@ -25,8 +27,8 @@ export function mapHtmlValues(inputTemplateStrings, inputValues) {
     });
 }
 function classifyValue(lastNewString, currentTemplateString) {
-    const isOpeningTag = lastNewString.trim().endsWith('<') && !!currentTemplateString.match(/^[\s\n>]/);
-    const isClosingTag = lastNewString?.trim().endsWith('</') && currentTemplateString.trim().startsWith('>');
+    const isOpeningTag = lastNewString.trim().endsWith('<') && !!currentTemplateString.match(/^[\s>]/);
+    const isClosingTag = lastNewString.trim().endsWith('</') && currentTemplateString.trim().startsWith('>');
     const shouldHaveTagNameHere = isOpeningTag || isClosingTag;
     return {
         isOpeningTag,
@@ -73,12 +75,12 @@ function transformHtml(...[lastNewString, currentTemplateString, rawCurrentValue
                 : undefined;
             return [
                 isOpeningTag && assignedInputs ? assign(assignedInputs) : undefined,
-            ].filter(isTruthy);
+            ].filter(check.isTruthy);
         },
     };
 }
 function extractCustomElementTags(input) {
-    const tagNameMatches = safeMatch(input, /<\/[\s\n]*[^\s\n><]+[\s\n]*>/g);
+    const tagNameMatches = safeMatch(input, /<\/\s*[^\s><]+\s*>/g);
     return tagNameMatches.reduce((accum, match) => {
         const tagName = collapseWhiteSpace(match.replace(/\n/g, ' ')).replace(/<\/|>/g, '');
         // custom elements always have a dash in them

package/dist/template-transforms/vir-html/vir-html.d.ts

@@ -1,9 +1,11 @@
-import { HTMLTemplateResult } from '../../lit-exports/all-lit-exports';
-import { HtmlInterpolation } from './html-interpolation';
+import { HTMLTemplateResult } from '../../lit-exports/all-lit-exports.js';
+import { HtmlInterpolation } from './html-interpolation.js';
 /**
  * Interprets a template literal as an HTML template which is lazily rendered to the DOM.
  *
  * Wraps lit-html's html tagged template and enables interpolations of
  * `DeclarativeElementDefinition` for tag names.
+ *
+ * @category Element Definition
  */
 export declare function html(inputTemplateStrings: TemplateStringsArray, ...inputValues: HtmlInterpolation[]): HTMLTemplateResult;

package/dist/template-transforms/vir-html/vir-html.js

@@ -1,11 +1,13 @@
 import { html as litHtml } from 'lit';
-import { getTransformedTemplate } from '../transform-template';
-import { mapHtmlValues, transformHtmlTemplate } from './html-transform';
+import { getTransformedTemplate } from '../transform-template.js';
+import { mapHtmlValues, transformHtmlTemplate } from './html-transform.js';
 /**
  * Interprets a template literal as an HTML template which is lazily rendered to the DOM.
  *
  * Wraps lit-html's html tagged template and enables interpolations of
  * `DeclarativeElementDefinition` for tag names.
+ *
+ * @category Element Definition
  */
 export function html(inputTemplateStrings, ...inputValues) {
     const mappedValues = mapHtmlValues(inputTemplateStrings, inputValues);

package/dist/typed-event/typed-event.d.ts

@@ -1,4 +1,9 @@
-import { NonEmptyString } from '../util/type';
+import { NonEmptyString } from '../util/type.js';
+/**
+ * A custom event with strict types for details and the event's `type` property.
+ *
+ * @category Internal
+ */
 export declare class TypedEvent<EventTypeNameGeneric extends string = '', EventDetailGeneric = undefined> extends CustomEvent<EventDetailGeneric> {
     readonly _type: EventTypeNameGeneric;
     get type(): EventTypeNameGeneric;
@@ -6,14 +11,45 @@ export declare class TypedEvent<EventTypeNameGeneric extends string = '', EventD
         type: EventTypeNameGeneric;
     }, value: EventDetailGeneric);
 }
-export type DefinedTypedEventNameDefinition<EventDetailGeneric> = <EventTypeNameGeneric extends string>(eventType: NonEmptyString<EventTypeNameGeneric>) => DefinedTypedEvent<EventTypeNameGeneric, EventDetailGeneric>;
+/**
+ * A function that defines a typed event, used for defining element events in an element's
+ * definition.
+ *
+ * @category Internal
+ */
+export type DefineEvent<EventDetailGeneric> = <EventTypeNameGeneric extends string>(eventType: NonEmptyString<EventTypeNameGeneric>) => DefinedTypedEvent<EventTypeNameGeneric, EventDetailGeneric>;
+/**
+ * A concrete typed event definition.
+ *
+ * @category Internal
+ */
 export type DefinedTypedEvent<EventTypeNameGeneric extends string, EventDetailGeneric> = (new (eventValue: EventDetailGeneric) => TypedEvent<EventTypeNameGeneric, EventDetailGeneric>) & {
     type: EventTypeNameGeneric;
 };
 /**
- * Defined a typed event. Make sure to use currying and call this function twice! Typescript's
- * generic restrictions require this setup to get the types right without excessive verbosity.
+ * Define a stand-alone typed event that can be emitted and listened to inside of HTML templates.
+ *
+ * Make sure to use currying and call this function twice! (This is required by TypeScript's type
+ * parameter inference system.)
+ *
+ * @category Element Definition
+ * @example
+ *
+ * ```ts
+ * import {defineTypedEvent} from 'element-vir';
  *
- * Example: const myCustomEvent = defineTypedEvent<number>()('my-custom-event')
+ * const myCustomEvent = defineTypedEvent<number>()('my-custom-event');
+ *
+ * const myCustomEvent2 = defineTypedEvent<// the event's `.detail` type
+ * number>()(
+ *     // the event's `.type` string
+ *     'my-custom-event2',
+ * );
+ * ```
+ */
+export declare function defineTypedEvent<EventDetailGeneric>(): <
+/**
+ * EventTypeNameGeneric is used for the event type property but not for the event value
+ * type... so it's named "name" instead of "type" cause type is overloaded here.
  */
-export declare function defineTypedEvent<EventDetailGeneric>(): <EventTypeNameGeneric extends string>(eventType: NonEmptyString<EventTypeNameGeneric>) => DefinedTypedEvent<EventTypeNameGeneric, EventDetailGeneric>;
+EventTypeNameGeneric extends string>(eventType: NonEmptyString<EventTypeNameGeneric>) => DefinedTypedEvent<EventTypeNameGeneric, EventDetailGeneric>;

package/dist/typed-event/typed-event.js

@@ -1,4 +1,10 @@
+/**
+ * A custom event with strict types for details and the event's `type` property.
+ *
+ * @category Internal
+ */
 export class TypedEvent extends CustomEvent {
+    _type = '';
     get type() {
         return this._type;
     }
@@ -8,40 +14,37 @@ export class TypedEvent extends CustomEvent {
             bubbles: true,
             composed: true,
         });
-        Object.defineProperty(this, "_type", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: ''
-        });
     }
 }
 /**
- * Defined a typed event. Make sure to use currying and call this function twice! Typescript's
- * generic restrictions require this setup to get the types right without excessive verbosity.
+ * Define a stand-alone typed event that can be emitted and listened to inside of HTML templates.
+ *
+ * Make sure to use currying and call this function twice! (This is required by TypeScript's type
+ * parameter inference system.)
+ *
+ * @category Element Definition
+ * @example
+ *
+ * ```ts
+ * import {defineTypedEvent} from 'element-vir';
+ *
+ * const myCustomEvent = defineTypedEvent<number>()('my-custom-event');
  *
- * Example: const myCustomEvent = defineTypedEvent<number>()('my-custom-event')
+ * const myCustomEvent2 = defineTypedEvent<// the event's `.detail` type
+ * number>()(
+ *     // the event's `.type` string
+ *     'my-custom-event2',
+ * );
+ * ```
  */
 export function defineTypedEvent() {
     return (eventType) => {
-        var _a;
-        return _a = class extends TypedEvent {
-                constructor(value) {
-                    super(eventType, value);
-                    Object.defineProperty(this, "_type", {
-                        enumerable: true,
-                        configurable: true,
-                        writable: true,
-                        value: eventType
-                    });
-                }
-            },
-            Object.defineProperty(_a, "type", {
-                enumerable: true,
-                configurable: true,
-                writable: true,
-                value: eventType
-            }),
-            _a;
+        return class extends TypedEvent {
+            static type = eventType;
+            _type = eventType;
+            constructor(value) {
+                super(eventType, value);
+            }
+        };
     };
 }

package/dist/util/lit-template.d.ts

@@ -1,4 +1,9 @@
-import type { TemplateResult, unsafeHTML, unsafeSVG } from '../lit-exports/all-lit-exports';
+import type { TemplateResult, unsafeHTML, unsafeSVG } from '../lit-exports/all-lit-exports.js';
+/**
+ * Converts an HTML or SVG template into a raw string.
+ *
+ * @category Util
+ */
 export declare function convertTemplateToString(template: TemplateResult | ReturnType<typeof unsafeSVG> | ReturnType<typeof unsafeHTML> | {
     templateString: string;
 }): string;

package/dist/util/lit-template.js

@@ -1,10 +1,15 @@
 import { collapseWhiteSpace } from '@augment-vir/common';
+/**
+ * Converts an HTML or SVG template into a raw string.
+ *
+ * @category Util
+ */
 export function convertTemplateToString(template) {
     if ('templateString' in template) {
         return template.templateString;
     }
     const { strings, values } = template;
-    if ((!strings || !strings?.length) && (!values || !values.length)) {
+    if (!strings?.length && !values?.length) {
         return '';
     }
     const valueList = [
@@ -28,12 +33,10 @@ function extractValue(previousString, value) {
         const values = value.map((innerValue) => convertTemplateToString(innerValue));
         return values.join('');
     }
+    else if (previousString.endsWith('=')) {
+        return `"${value}"`;
+    }
     else {
-        if (previousString.endsWith('=')) {
-            return `"${value}"`;
-        }
-        else {
-            return value;
-        }
+        return value;
     }
 }

package/dist/util/type.d.ts

@@ -1 +1,6 @@
+/**
+ * Blocks empty string literal types.
+ *
+ * @category Internal
+ */
 export type NonEmptyString<T> = T extends '' ? never : T;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-vir",
-    "version": "22.2.2",
+    "version": "23.1.0",
     "keywords": [
         "custom",
         "web",
@@ -18,55 +18,57 @@
     },
     "repository": {
         "type": "git",
-        "url": "https://github.com/electrovir/element-vir"
+        "url": "git+https://github.com/electrovir/element-vir.git"
     },
     "license": "(MIT or CC0 1.0)",
     "author": {
         "name": "electrovir",
         "url": "https://github.com/electrovir"
     },
+    "type": "module",
     "main": "dist/index.js",
+    "module": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
-        "build:pages": "npm run docs",
-        "compile": "rm -rf dist && tsc -b -f --pretty",
+        "build": "npm run docs",
+        "compile": "virmator compile",
         "docs": "virmator docs",
-        "start": "cd ../element-vir-example && npm start",
-        "test": "virmator test-web",
-        "test:docs": "virmator docs check",
-        "test:types": "tsc --pretty --noEmit"
+        "test": "virmator test web",
+        "test:coverage": "npm run test coverage",
+        "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@augment-vir/common": "^28.0.0",
-        "date-vir": "^5.1.4",
-        "lit": "^3.1.3",
-        "lit-css-vars": "^3.0.9",
-        "lit-html": "^3.1.3",
-        "object-shape-tester": "^2.3.2",
-        "observavir": "^2.0.2",
-        "run-time-assertions": "^1.5.0",
-        "typed-event-target": "^3.4.0"
+        "@augment-vir/assert": "^31.0.1",
+        "@augment-vir/common": "^31.0.1",
+        "date-vir": "^7.0.3",
+        "lit": "^3.2.1",
+        "lit-css-vars": "^3.0.11",
+        "lit-html": "^3.2.1",
+        "object-shape-tester": "^3.1.4",
+        "observavir": "^2.0.4",
+        "typed-event-target": "^4.0.2"
     },
     "devDependencies": {
-        "@augment-vir/browser": "^28.0.0",
-        "@augment-vir/browser-testing": "^28.0.0",
-        "@augment-vir/node-js": "^28.0.0",
-        "@istanbuljs/nyc-config-typescript": "^1.0.2",
-        "@open-wc/testing": "^4.0.0",
-        "@types/chai": "^4.3.16",
-        "@types/mocha": "^10.0.6",
-        "@web/dev-server-esbuild": "^1.0.2",
-        "@web/test-runner": "^0.18.1",
+        "@augment-vir/test": "^31.0.1",
+        "@augment-vir/web": "^31.0.1",
+        "@web/dev-server-esbuild": "^1.0.3",
+        "@web/test-runner": "^0.19.0",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.0",
-        "@web/test-runner-visual-regression": "^0.9.0",
-        "html-spec-tags": "^2.2.0",
-        "istanbul-smart-text-reporter": "^1.1.4",
-        "markdown-code-example-inserter": "^1.0.0",
-        "type-fest": "^4.18.2",
-        "typedoc": "^0.25.13",
-        "typescript": "5.4.5",
-        "vite": "^4.5.0",
-        "vite-tsconfig-paths": "^4.3.2"
+        "@web/test-runner-visual-regression": "^0.10.0",
+        "html-spec-tags": "^2.2.2",
+        "istanbul-smart-text-reporter": "^1.1.5",
+        "markdown-code-example-inserter": "^3.0.3",
+        "type-fest": "^4.30.0",
+        "typedoc": "^0.27.4",
+        "typescript": "5.7.2",
+        "vite": "^6.0.3",
+        "vite-tsconfig-paths": "^5.1.4"
+    },
+    "engines": {
+        "node": ">=22"
+    },
+    "publishConfig": {
+        "access": "public"
     }
 }