element-vir 26.12.0 → 26.12.1

package/src/template-transforms/nested-mapped-templates.ts

@@ -1,157 +0,0 @@
-import {check} from '@augment-vir/assert';
-import {filterMap} from '@augment-vir/common';
-import {hasTagName, isMinimalDefinitionWithInputs} from './minimal-element-definition.js';
-import {type TemplateTransform} from './template-transform-type.js';
-
-type WeakMapElementKey = {
-    tagName: string;
-};
-
-type TemplateAndNested = {
-    template: TemplateTransform | undefined;
-    nested: NestedTemplatesWeakMap | undefined;
-};
-type NestedTemplatesWeakMap = WeakMap<WeakMapElementKey, TemplateAndNested>;
-type TemplatesWeakMap = WeakMap<TemplateStringsArray, TemplateAndNested>;
-
-function extractElementKeys(values: unknown[]): WeakMapElementKey[] {
-    return filterMap(
-        values,
-        (value): WeakMapElementKey | undefined => {
-            if (isMinimalDefinitionWithInputs(value)) {
-                return value.definition;
-            }
-            if (hasTagName(value)) {
-                return value.tagInterpolationKey || value;
-            }
-
-            return undefined;
-        },
-        check.isTruthy,
-    );
-}
-
-/**
- * The transformed templates are written to a map so that we can preserve reference equality between
- * calls. Without maintaining reference equality between html`` calls, lit-element reconstructs all
- * of its children on every render.
- *
- * This is a WeakMap because we only care about the transformed array value as long as the original
- * template array key exists.
- */
-const transformedTemplateStrings: TemplatesWeakMap = new WeakMap();
-
-export function getAlreadyMappedTemplate<PossibleValues>(
-    templateStringsKey: TemplateStringsArray,
-    values: PossibleValues[],
-) {
-    const elementKeys = extractElementKeys(values);
-    const nestedValue = getNestedValues(transformedTemplateStrings, [
-        templateStringsKey,
-        ...elementKeys,
-    ]);
-    return nestedValue.value?.template;
-}
-
-export function setMappedTemplate<PossibleValues>(
-    templateStringsKey: TemplateStringsArray,
-    values: PossibleValues[],
-    valueToSet: TemplateTransform,
-) {
-    const elementKeys = extractElementKeys(values);
-    return setNestedValues(
-        transformedTemplateStrings,
-        [
-            templateStringsKey,
-            ...elementKeys,
-        ],
-        valueToSet,
-    );
-}
-
-function getNestedValues(
-    map: TemplatesWeakMap | NestedTemplatesWeakMap,
-    keys: (TemplateStringsArray | WeakMapElementKey)[],
-    index = 0,
-): {value: undefined | TemplateAndNested; reason: string} {
-    const {currentTemplateAndNested, reason} = getCurrentKeyAndValue(map, keys, index);
-    if (!currentTemplateAndNested) {
-        return {value: currentTemplateAndNested, reason};
-    }
-
-    if (index === keys.length - 1) {
-        return {value: currentTemplateAndNested, reason: `reached end of keys array`};
-    }
-
-    if (!currentTemplateAndNested.nested) {
-        return {value: undefined, reason: `map at key index ${index} did not have nested maps`};
-    }
-
-    return getNestedValues(currentTemplateAndNested.nested, keys, index + 1);
-}
-
-function getCurrentKeyAndValue(
-    map: TemplatesWeakMap | NestedTemplatesWeakMap,
-    keys: (TemplateStringsArray | WeakMapElementKey)[],
-    index: number,
-): {
-    currentKey: TemplateStringsArray | WeakMapElementKey | undefined;
-    currentTemplateAndNested: TemplateAndNested | undefined;
-    reason: string;
-} {
-    const currentKey = keys[index];
-    if (currentKey == undefined) {
-        return {
-            currentKey: undefined,
-            currentTemplateAndNested: undefined,
-            reason: `key at index ${index} not found`,
-        };
-    }
-    if (!map.has(currentKey as any)) {
-        return {
-            currentKey,
-            currentTemplateAndNested: undefined,
-            reason: `key at index ${index} was not in the map`,
-        };
-    }
-    const currentTemplateAndNested = map.get(currentKey as any);
-    if (currentTemplateAndNested == undefined) {
-        return {
-            currentKey,
-            currentTemplateAndNested: undefined,
-            reason: `value at key at index ${index} was undefined`,
-        };
-    }
-
-    return {currentKey, currentTemplateAndNested, reason: `key and value exists`};
-}
-
-function setNestedValues(
-    map: TemplatesWeakMap | NestedTemplatesWeakMap,
-    keys: (TemplateStringsArray | WeakMapElementKey)[],
-    valueToSet: TemplateTransform,
-    index = 0,
-): {result: boolean; reason: string} {
-    const {currentTemplateAndNested, currentKey, reason} = getCurrentKeyAndValue(map, keys, index);
-    if (!currentKey) {
-        return {result: false, reason};
-    }
-
-    const nestedAndTemplate = currentTemplateAndNested ?? {nested: undefined, template: undefined};
-    if (!currentTemplateAndNested) {
-        map.set(currentKey as any, nestedAndTemplate);
-    }
-
-    if (index === keys.length - 1) {
-        nestedAndTemplate.template = valueToSet;
-        return {result: true, reason: `set value at end of keys array`};
-    }
-
-    const nestedWeakMap = nestedAndTemplate.nested ?? new WeakMap();
-
-    if (!nestedAndTemplate.nested) {
-        nestedAndTemplate.nested = nestedWeakMap;
-    }
-
-    return setNestedValues(nestedWeakMap, keys, valueToSet, index + 1);
-}

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

@@ -1,30 +0,0 @@
-/* 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

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

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

@@ -1,149 +0,0 @@
-/* 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/src/typed-event/typed-event.ts

@@ -1,90 +0,0 @@
-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);
-            }
-        };
-    };
-}