element-vir 26.11.2 → 26.12.0

package/src/template-transforms/vir-css/css-transform.ts

@@ -0,0 +1,30 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import {type CSSResultGroup} from '../../lit-exports/all-lit-exports.js';
+import {type MinimalElementDefinition, hasTagName} from '../minimal-element-definition.js';
+import {type TemplateTransform} from '../template-transform-type.js';
+import {type ValueTransformCallback, transformTemplate} from '../transform-template.js';
+
+function transformCss(
+    ...[
+        lastNewString,
+        currentLitString,
+        currentValue,
+    ]: Parameters<ValueTransformCallback>
+): ReturnType<ValueTransformCallback> {
+    if (!hasTagName(currentValue)) {
+        return undefined;
+    }
+
+    return {
+        replacement: currentValue.tagName,
+        getExtraValues: undefined,
+    };
+}
+
+export function transformCssTemplate(
+    inputTemplateStrings: TemplateStringsArray,
+    inputValues: (number | CSSResultGroup | MinimalElementDefinition)[],
+): TemplateTransform {
+    return transformTemplate(inputTemplateStrings, inputValues, transformCss);
+}

package/src/template-transforms/vir-css/vir-css.ts

@@ -0,0 +1,30 @@
+import {css as litCss} from 'lit';
+import {type CSSResult, type CSSResultGroup} from '../../lit-exports/all-lit-exports.js';
+import {type MinimalElementDefinition} from '../minimal-element-definition.js';
+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: TemplateStringsArray,
+    ...inputValues: (number | CSSResultGroup | MinimalElementDefinition | CSSResult)[]
+): CSSResult {
+    const transformedTemplate = getTransformedTemplate(inputTemplateStrings, inputValues, () => {
+        return transformCssTemplate(inputTemplateStrings, inputValues);
+    });
+
+    const cssResult = litCss(
+        transformedTemplate.strings,
+        /** The filter will remove the DeclarativeElement elements */
+        ...(transformedTemplate.values as (number | CSSResultGroup)[]),
+    );
+    return cssResult;
+}

package/src/template-transforms/vir-html/html-interpolation.ts

@@ -0,0 +1,103 @@
+import {type AnyFunction, type Overwrite} from '@augment-vir/common';
+import {type CSSResult, type TemplateResult, type nothing} from 'lit';
+import {type EmptyObject, type HasRequiredKeys, type IsNever} from 'type-fest';
+import {type DeclarativeElementDefinition} from '../../declarative-element/declarative-element.js';
+import {type Decrement, type Increment} from '../../util/increment.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>
+    | Iterable<HtmlInterpolation>
+    | Readonly<Iterable<HtmlInterpolation>>;
+
+/**
+ * This type ensures that interpolated element definitions are not missing their inputs, when inputs
+ * are required.
+ *
+ * @category Internal
+ */
+export type VerifyHtmlValues<
+    Values extends HtmlInterpolation[],
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+    WaitingForEndTags extends Record<string, number> = {},
+> = Values extends [
+    infer CurrentDefinition extends DeclarativeElementDefinition,
+    ...infer Rest extends HtmlInterpolation[],
+]
+    ? CurrentDefinition extends DeclarativeElementDefinition<infer TagName, infer Inputs>
+        ? HasRequiredKeys<Inputs> extends true
+            ? IsNever<Decrement<WaitingForEndTags[TagName]>> extends true
+                ? [
+                      `ERROR: This element is missing its inputs.`,
+                      ...VerifyHtmlValues<Rest, WaitingForEndTags>,
+                  ]
+                : [
+                      CurrentDefinition,
+                      ...VerifyHtmlValues<
+                          Rest,
+                          Overwrite<
+                              WaitingForEndTags,
+                              Record<TagName, Decrement<WaitingForEndTags[TagName]>>
+                          >
+                      >,
+                  ]
+            : [CurrentDefinition, ...VerifyHtmlValues<Rest, WaitingForEndTags>]
+        : [CurrentDefinition, ...VerifyHtmlValues<Rest, WaitingForEndTags>]
+    : Values extends [
+            infer CurrentDefinition extends MinimalDefinitionWithInputs,
+            ...infer Rest extends HtmlInterpolation[],
+        ]
+      ? [
+            CurrentDefinition,
+            ...VerifyHtmlValues<
+                Rest,
+                Overwrite<
+                    WaitingForEndTags,
+                    Record<
+                        CurrentDefinition['definition']['tagName'],
+                        Increment<WaitingForEndTags[CurrentDefinition['definition']['tagName']]>
+                    >
+                >
+            >,
+        ]
+      : Values;

package/src/template-transforms/vir-html/html-transform.ts

@@ -0,0 +1,149 @@
+/* eslint-disable @typescript-eslint/no-deprecated */
+
+import {check} from '@augment-vir/assert';
+import {collapseWhiteSpace, getOrSet, safeMatch} from '@augment-vir/common';
+import {assign} from '../../declarative-element/directives/assign.directive.js';
+import {type HTMLTemplateResult} from '../../lit-exports/all-lit-exports.js';
+import {declarativeElementRequired} from '../../require-declarative-element.js';
+import {
+    type MinimalElementDefinition,
+    hasTagName,
+    isMinimalDefinitionWithInputs,
+} from '../minimal-element-definition.js';
+import {type TemplateTransform} from '../template-transform-type.js';
+import {type ValueTransformCallback, transformTemplate} from '../transform-template.js';
+import {type HtmlInterpolation} from './html-interpolation.js';
+import {tagNameKeys} from './tag-name-keys.js';
+
+export function mapHtmlValues(
+    inputTemplateStrings: TemplateStringsArray,
+    inputValues: HtmlInterpolation[],
+): HtmlInterpolation[] {
+    return inputValues.map((currentValue, currentValueIndex): HtmlInterpolation => {
+        const lastString = inputTemplateStrings[currentValueIndex];
+        const nextString = inputTemplateStrings[currentValueIndex + 1];
+
+        if (lastString && nextString) {
+            const {shouldHaveTagNameHere} = classifyValue(lastString, nextString);
+
+            if (shouldHaveTagNameHere && check.isString(currentValue)) {
+                const replacement: MinimalElementDefinition = {
+                    tagName: currentValue,
+                    tagInterpolationKey: getOrSet(tagNameKeys, currentValue, () => {
+                        return {tagName: currentValue};
+                    }),
+                };
+
+                return replacement;
+            }
+        }
+
+        return currentValue;
+    });
+}
+
+function classifyValue(lastNewString: string, currentTemplateString: string) {
+    const isOpeningTag =
+        lastNewString.trim().endsWith('<') && !!currentTemplateString.match(/^[\s>]/);
+    const isClosingTag =
+        lastNewString.trim().endsWith('</') && currentTemplateString.trim().startsWith('>');
+    const shouldHaveTagNameHere: boolean = isOpeningTag || isClosingTag;
+
+    return {
+        isOpeningTag,
+        shouldHaveTagNameHere,
+    };
+}
+
+function transformHtml(
+    ...[
+        lastNewString,
+        currentTemplateString,
+        rawCurrentValue,
+    ]: Parameters<ValueTransformCallback>
+): ReturnType<ValueTransformCallback> {
+    const currentValue = isMinimalDefinitionWithInputs(rawCurrentValue)
+        ? rawCurrentValue.definition
+        : rawCurrentValue;
+
+    const {isOpeningTag, shouldHaveTagNameHere} = classifyValue(
+        lastNewString,
+        currentTemplateString,
+    );
+    const isTagNameWrapper = hasTagName(currentValue);
+
+    if (isTagNameWrapper && shouldHaveTagNameHere && currentValue.tagInterpolationKey) {
+        return {
+            replacement: currentValue.tagName,
+            getExtraValues: undefined,
+        };
+    }
+
+    if (shouldHaveTagNameHere && !isTagNameWrapper) {
+        console.error({
+            lastNewString,
+            currentTemplateString,
+            currentValue,
+        });
+        throw new Error(
+            `Got interpolated tag name but found no tag name on the given value: '${
+                (currentValue as any)?.tagName ||
+                (currentValue as any)?.prototype?.constructor?.name ||
+                (currentValue as any)?.constructor?.name
+            }'`,
+        );
+    }
+
+    if (!shouldHaveTagNameHere || !isTagNameWrapper) {
+        return undefined;
+    }
+
+    const replacement = currentValue.tagName;
+
+    return {
+        replacement,
+        getExtraValues(extraValueCurrentValue) {
+            const assignedInputs = isMinimalDefinitionWithInputs(extraValueCurrentValue)
+                ? extraValueCurrentValue.inputs
+                : undefined;
+
+            return [
+                isOpeningTag && assignedInputs ? assign(assignedInputs) : undefined,
+            ].filter(check.isTruthy);
+        },
+    };
+}
+
+function extractCustomElementTags(input: string): string[] {
+    const tagNameMatches = safeMatch(input, /<\/\s*[^\s><]+\s*>/g);
+    return tagNameMatches.reduce((accum: string[], match) => {
+        const tagName = collapseWhiteSpace(match.replace(/\n/g, ' ')).replace(/<\/|>/g, '');
+        // custom elements always have a dash in them
+        if (tagName.includes('-')) {
+            return accum.concat(tagName);
+        }
+        return accum;
+    }, []);
+}
+
+function stringValidator(input: string): void {
+    if (declarativeElementRequired) {
+        const customElementTagNames = extractCustomElementTags(input);
+        if (customElementTagNames.length) {
+            console.error(
+                `Custom element tags must be interpolated from declarative elements: ${customElementTagNames.join(
+                    ', ',
+                )}`,
+            );
+        }
+    }
+}
+
+export function transformHtmlTemplate(litTemplate: HTMLTemplateResult): TemplateTransform {
+    return transformTemplate(
+        litTemplate.strings,
+        litTemplate.values,
+        transformHtml,
+        stringValidator,
+    );
+}

package/{dist/template-transforms/vir-html/tag-name-keys.js → src/template-transforms/vir-html/tag-name-keys.ts}

@@ -2,4 +2,4 @@
  * Used to create objects for each interpolated tag name string (tag names that aren't wrapped in a
  * `DeclarativeElementDefinition`) so that we can use them as keys for the mapped template weakmap.
  */
-export const tagNameKeys = {};
+export const tagNameKeys: Record<string, {tagName: string}> = {};

package/{dist/template-transforms/vir-html/vir-html.js → src/template-transforms/vir-html/vir-html.ts}

@@ -1,6 +1,9 @@
-import { html as litHtml } from 'lit';
-import { getTransformedTemplate } from '../transform-template.js';
-import { mapHtmlValues, transformHtmlTemplate } from './html-transform.js';
+import {html as litHtml} from 'lit';
+import {type HTMLTemplateResult} from '../../lit-exports/all-lit-exports.js';
+import {getTransformedTemplate} from '../transform-template.js';
+import {type HtmlInterpolation, type VerifyHtmlValues} from './html-interpolation.js';
+import {mapHtmlValues, transformHtmlTemplate} from './html-transform.js';
+
 /**
  * Interprets a template literal as an HTML template which is lazily rendered to the DOM.
  *
@@ -9,13 +12,18 @@ import { mapHtmlValues, transformHtmlTemplate } from './html-transform.js';
  *
  * @category Element Definition
  */
-export function html(inputTemplateStrings, ...inputValues) {
+export function html<const Values extends HtmlInterpolation[]>(
+    inputTemplateStrings: TemplateStringsArray,
+    ...inputValues: VerifyHtmlValues<Values>
+): HTMLTemplateResult {
     const mappedValues = mapHtmlValues(inputTemplateStrings, inputValues);
+
     const litTemplate = litHtml(inputTemplateStrings, ...mappedValues);
     const transformedTemplate = getTransformedTemplate(inputTemplateStrings, mappedValues, () => {
         return transformHtmlTemplate(litTemplate);
     });
-    const htmlTemplate = {
+
+    const htmlTemplate: HTMLTemplateResult = {
         ...litTemplate,
         strings: transformedTemplate.strings,
         values: transformedTemplate.values,

package/src/typed-event/typed-event.ts

@@ -0,0 +1,90 @@
+import {type NonEmptyString} from '../util/type.js';
+
+/**
+ * A custom event with strict types for details and the event's `type` property.
+ *
+ * @category Internal
+ */
+export class TypedEvent<
+    EventTypeNameGeneric extends string = '',
+    EventDetailGeneric = undefined,
+> extends CustomEvent<EventDetailGeneric> {
+    public readonly _type: EventTypeNameGeneric = '' as EventTypeNameGeneric;
+    public override get type(): EventTypeNameGeneric {
+        return this._type;
+    }
+
+    constructor(
+        type: EventTypeNameGeneric | {type: EventTypeNameGeneric},
+        value: EventDetailGeneric,
+    ) {
+        super(typeof type === 'string' ? type : type.type, {
+            detail: value,
+            bubbles: true,
+            composed: true,
+        });
+    }
+}
+
+/**
+ * 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;
+};
+
+/**
+ * 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');
+ *
+ * const myCustomEvent2 = defineTypedEvent<// the event's `.detail` type
+ * number>()(
+ *     // the event's `.type` string
+ *     'my-custom-event2',
+ * );
+ * ```
+ */
+export function defineTypedEvent<EventDetailGeneric>() {
+    return <
+        /**
+         * 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.
+         */
+        EventTypeNameGeneric extends string,
+    >(
+        eventType: NonEmptyString<EventTypeNameGeneric>,
+    ): DefinedTypedEvent<EventTypeNameGeneric, EventDetailGeneric> => {
+        return class extends TypedEvent<EventTypeNameGeneric, EventDetailGeneric> {
+            public static readonly type = eventType;
+            public override readonly _type = eventType;
+
+            constructor(value: EventDetailGeneric) {
+                super(eventType, value);
+            }
+        };
+    };
+}

package/{dist/util/array.js → src/util/array.ts}

@@ -1,23 +1,34 @@
-export function insertAndRemoveValues(originalArray, valuesToInsert, indexesToRemove) {
-    const noOperations = !valuesToInsert.length && !indexesToRemove.length;
-    const nothingToDoBecauseEmptyArray = originalArray.length
+export type ArrayInsertion<T> = {index: number; values: ReadonlyArray<T>};
+
+export function insertAndRemoveValues<Entry>(
+    originalArray: ReadonlyArray<Entry>,
+    valuesToInsert: ReadonlyArray<ArrayInsertion<Entry>>,
+    indexesToRemove: ReadonlyArray<number>,
+): Entry[] {
+    const noOperations: boolean = !valuesToInsert.length && !indexesToRemove.length;
+    const nothingToDoBecauseEmptyArray: boolean = originalArray.length
         ? false
         : !valuesToInsert.filter((value) => !!value.index).length;
+
     if (noOperations || nothingToDoBecauseEmptyArray) {
         // there's nothing to do
         return [...originalArray];
     }
-    const arrayValues = originalArray.map((entry) => {
+
+    const arrayValues: Entry[][] = originalArray.map((entry) => {
         return [entry];
     });
+
     if (!arrayValues.length) {
         arrayValues[0] = [];
     }
+
     indexesToRemove.forEach((index) => {
         if (index >= 0 && index < originalArray.length) {
             arrayValues[index] = [];
         }
     });
+
     valuesToInsert.forEach((valueWrapper) => {
         const indexEntry = arrayValues[valueWrapper.index];
         if (indexEntry) {
@@ -25,6 +36,8 @@ export function insertAndRemoveValues(originalArray, valuesToInsert, indexesToRe
             indexEntry.splice(0, 0, ...valueWrapper.values);
         }
     });
-    const finalArray = arrayValues.flat();
+
+    const finalArray: Entry[] = arrayValues.flat();
+
     return finalArray;
 }

package/{dist/util/increment.d.ts → src/util/increment.ts}

@@ -1,5 +1,6 @@
-import { type ArrayElement } from '@augment-vir/common';
-import { type IsNever } from 'type-fest';
+import {type ArrayElement} from '@augment-vir/common';
+import {type IsNever} from 'type-fest';
+
 /**
  * The largest number in this tuple is the largest number of nestings of the same element that
  * `element-vir` will support with types (in runtime it'll support any level of nesting the same
@@ -38,18 +39,36 @@ export type Incrementable = [
     27,
     28,
     29,
-    30
+    30,
 ];
+
 /**
  * Increments the given number. If an invalid type parameter is given, it is treated as `0` and this
  * will output `1`. If the upper bound of increments has been reached, this will output `never`.
  *
  * @category Internal
  */
-export type Increment<T> = IsNever<Extract<ArrayElement<Incrementable>, T>> extends true ? IsNever<T> extends true ? 1 : never : Incrementable extends [any, ...infer Rest] ? T extends keyof Rest ? Rest[T] extends undefined ? never : Rest[T] : 1 : 1;
+export type Increment<T> =
+    IsNever<Extract<ArrayElement<Incrementable>, T>> extends true
+        ? IsNever<T> extends true
+            ? 1
+            : never
+        : Incrementable extends [any, ...infer Rest]
+          ? T extends keyof Rest
+              ? Rest[T] extends undefined
+                  ? never
+                  : Rest[T]
+              : 1
+          : 1;
+
 /**
  * Decrements the given number. If an invalid type parameter is given, `never` is the output.
  *
  * @category Internal
  */
-export type Decrement<T> = IsNever<Extract<ArrayElement<Incrementable>, T>> extends true ? never : T extends keyof Incrementable ? [never, ...Incrementable][T] : never;
+export type Decrement<T> =
+    IsNever<Extract<ArrayElement<Incrementable>, T>> extends true
+        ? never
+        : T extends keyof Incrementable
+          ? [never, ...Incrementable][T]
+          : never;

package/{dist/util/lit-template.js → src/util/lit-template.ts}

@@ -1,42 +1,62 @@
-import { collapseWhiteSpace } from '@augment-vir/common';
+import {collapseWhiteSpace} from '@augment-vir/common';
+import {
+    type TemplateResult,
+    type unsafeHTML,
+    type unsafeSVG,
+} from '../lit-exports/all-lit-exports.js';
+
 /**
  * Converts an HTML or SVG template into a raw string.
  *
  * @category Util
  */
-export function convertTemplateToString(template) {
+export function convertTemplateToString(
+    template:
+        | TemplateResult
+        | ReturnType<typeof unsafeSVG>
+        | ReturnType<typeof unsafeHTML>
+        | {templateString: string},
+): string {
     if ('templateString' in template) {
         return template.templateString;
     }
-    const { strings, values } = template;
+
+    const {strings, values} = template as
+        | TemplateResult
+        | {
+              strings: undefined | string[];
+              values: undefined | unknown[];
+          };
+
     if (!strings?.length && !values?.length) {
         return '';
     }
+
     const valueList = [
         ...(values || []),
         '', // this last empty string is so it's easier to deal with indexes
     ];
     const stringsList = strings ?? [''];
+
     const all = stringsList.map((stringValue, index) => {
         const value = extractValue(stringValue, valueList[index]);
         return `${stringValue}${value}`;
     });
+
     return collapseWhiteSpace(all.join(''));
 }
-function extractValue(previousString, value) {
+
+function extractValue(previousString: string, value: any) {
     if (value._$litType$ != undefined || value._$litDirective$ != undefined) {
         // nested templates
         return convertTemplateToString(value);
-    }
-    else if (Array.isArray(value)) {
+    } else if (Array.isArray(value)) {
         // array of strings or templates.
         const values = value.map((innerValue) => convertTemplateToString(innerValue));
         return values.join('');
-    }
-    else if (previousString.endsWith('=')) {
+    } else if (previousString.endsWith('=')) {
         return `"${value}"`;
-    }
-    else {
+    } else {
         return value;
     }
 }

package/src/util/map-async-value.ts

@@ -0,0 +1,33 @@
+import {isNotNoUpdate, type AsyncValue} from 'observavir';
+
+/**
+ * Maps an async value to a new async value.
+ *
+ * @category Util
+ */
+export function mapAsyncValue<const OriginalValue, const MappedValue>(
+    asyncValue: AsyncValue<OriginalValue>,
+    mapper: (value: NoInfer<OriginalValue>) => MappedValue,
+): AsyncValue<MappedValue> {
+    if (asyncValue instanceof Error) {
+        return asyncValue;
+    } else if (asyncValue instanceof Promise) {
+        return asyncValue.then((value) => {
+            const mapped = mapper(value);
+
+            if (isNotNoUpdate(mapped)) {
+                return mapped;
+            } else {
+                throw new Error('Cannot map to no update.');
+            }
+        });
+    } else {
+        const mapped = mapper(asyncValue);
+
+        if (isNotNoUpdate(mapped)) {
+            return mapped;
+        } else {
+            throw new Error('Cannot map to no update.');
+        }
+    }
+}

package/dist/declarative-element/custom-tag-name.js

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