element-vir 26.12.0 → 26.12.1

package/src/declarative-element/directives/on-resize.directive.ts

@@ -1,142 +0,0 @@
-import {type MaybePromise} from '@augment-vir/common';
-import {directive, Directive, type PartInfo} from '../../lit-exports/all-lit-exports.js';
-import {assertIsElementPartInfo} from './directive-helpers.js';
-
-/**
- * Callback called by the {@link onResize} directive.
- *
- * @category Internal
- */
-export type OnResizeCallback = (
-    size: Readonly<
-        Pick<
-            ResizeObserverEntry,
-            /** Only these two properties are supported in all major modern browsers */
-            'target' | 'contentRect'
-        >
-    >,
-    element: Element,
-) => MaybePromise<void>;
-
-const directiveName = 'onResize';
-
-/**
- * A directive that fires its listener any time the element that it's attached to is resized. This
- * uses the [built-in `ResizeObserver`
- * API](https://developer.mozilla.org/docs/Web/API/ResizeObserver), so it is very efficient.
- *
- * @category Directives
- * @example
- *
- * ```ts
- * import {html, defineElement, onResize} from 'element-vir';
- *
- * const MyElement = defineElement()({
- *     tagName: 'my-element',
- *     render() {
- *         return html`
- *             <div
- *                 ${onResize((size, element) => {
- *                     console.log('resized!', element, size);
- *                 })}
- *             >
- *                 Some div
- *             </div>
- *         `;
- *     },
- * });
- * ```
- */
-export const onResize = directive(
-    class extends Directive {
-        public element: Element | undefined;
-        public readonly resizeObserver = new ResizeObserver((entries) => {
-            if (this.element && this.callback) {
-                handleOnResizeCallback(this.element, this.callback, entries);
-            }
-        });
-        public callback: OnResizeCallback | undefined;
-
-        constructor(partInfo: PartInfo) {
-            super(partInfo);
-
-            assertIsElementPartInfo(partInfo, directiveName);
-        }
-
-        public override update(partInfo: PartInfo, [callback]: [OnResizeCallback]) {
-            assertIsElementPartInfo(partInfo, directiveName);
-            this.callback = callback;
-            const newElement = partInfo.element;
-            const oldElement = this.element;
-            // if the element changes we need to observe the new one
-            if (newElement !== oldElement) {
-                this.element = newElement;
-                if (oldElement) {
-                    this.resizeObserver.unobserve(oldElement);
-                }
-                this.resizeObserver.observe(newElement);
-            }
-            return this.render(callback);
-        }
-
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        public render(callback: OnResizeCallback) {
-            return undefined;
-        }
-    },
-);
-
-function handleOnResizeCallback(
-    element: Element,
-    callback: OnResizeCallback,
-    entries: ResizeObserverEntry[],
-) {
-    const resizeEntry = entries[0];
-    if (!resizeEntry) {
-        console.error(entries);
-        throw new Error(`Resize observation triggered but the first entry was empty.`);
-    }
-    void callback(
-        {
-            target: resizeEntry.target,
-            contentRect: resizeEntry.contentRect,
-        },
-        element,
-    );
-}
-
-/**
- * A function that attaches a
- * [`ResizeObserver`](https://developer.mozilla.org/docs/Web/API/ResizeObserver) to any given
- * element, so it is very efficient.
- *
- * @category Directives
- * @example
- *
- * ```ts
- * import {html, defineElement, attachOnResize} from 'element-vir';
- *
- * const MyElement = defineElement()({
- *     tagName: 'my-element',
- *     render({host}) {
- *         attachOnResize(host, (size, element) => {
- *             console.log('resized!', element, size);
- *         });
- *
- *         return '';
- *     },
- * });
- * ```
- */
-export function attachOnResize(element: Element, callback: OnResizeCallback) {
-    const resizeObserver = new ResizeObserver((entries) => {
-        handleOnResizeCallback(element, callback, entries);
-    });
-
-    resizeObserver.observe(element);
-
-    return {
-        resizeObserver,
-        element,
-    };
-}

package/src/declarative-element/directives/render-async.directive.ts

@@ -1,111 +0,0 @@
-import {check} from '@augment-vir/assert';
-import {extractErrorMessage} from '@augment-vir/common';
-import {type AsyncProp} from './async-prop.js';
-
-/**
- * Given a {@link AsyncProp} instance, call and return the output of the `resolutionRender` parameter
- * once the {@link AsyncProp} has been resolved, call and return the output of the `errorRender`
- * parameter if the {@link AsyncProp} errored out, return the `fallback` parameter in all other
- * cases.
- *
- * This is the overload for when `resolutionRender` and `errorRender` are both provided.
- *
- * @category Async
- */
-export function renderAsync<
-    T,
-    FallbackResult,
-    ResolutionRenderResult = never,
-    ErrorRenderResult = never,
->(
-    asyncProp: Pick<AsyncProp<T, any>, 'value'>,
-    fallback: FallbackResult,
-    resolutionRender: (resolved: Awaited<T>) => ResolutionRenderResult,
-    errorRender: (error: Error) => ErrorRenderResult,
-): FallbackResult | ResolutionRenderResult | ErrorRenderResult;
-/**
- * Given a {@link AsyncProp} instance, call and return the output of the `resolutionRender` parameter
- * once the {@link AsyncProp} has been resolved, call and return the output of the `errorRender`
- * parameter if the {@link AsyncProp} errored out, return the `fallback` parameter in all other
- * cases.
- *
- * This is the overload for when `resolutionRender` is provided but `errorRender` is not.
- *
- * @category Async
- */
-export function renderAsync<T, FallbackResult, ResolutionRenderResult = never>(
-    asyncProp: Pick<AsyncProp<T, any>, 'value'>,
-    fallback: FallbackResult,
-    resolutionRender: (resolved: Awaited<T>) => ResolutionRenderResult,
-    errorRender?: undefined,
-): FallbackResult | ResolutionRenderResult | string;
-/**
- * Given a {@link AsyncProp} instance, call and return the output of the `resolutionRender` parameter
- * once the {@link AsyncProp} has been resolved, call and return the output of the `errorRender`
- * parameter if the {@link AsyncProp} errored out, return the `fallback` parameter in all other
- * cases.
- *
- * This is the overload for when `resolutionRender` is not provided but `errorRender` is.
- *
- * @category Async
- */
-export function renderAsync<T, FallbackResult, ErrorRenderResult = never>(
-    asyncProp: Pick<AsyncProp<T, any>, 'value'>,
-    fallback: FallbackResult,
-    resolutionRender: undefined,
-    errorRender: (error: Error) => ErrorRenderResult,
-): FallbackResult | Awaited<T> | ErrorRenderResult;
-/**
- * Given a {@link AsyncProp} instance, call and return the output of the `resolutionRender` parameter
- * once the {@link AsyncProp} has been resolved, call and return the output of the `errorRender`
- * parameter if the {@link AsyncProp} errored out, return the `fallback` parameter in all other
- * cases.
- *
- * This is the overload for when neither `resolutionRender` or `errorRender` are provided.
- *
- * @category Async
- */
-export function renderAsync<T, FallbackResult>(
-    asyncProp: Pick<AsyncProp<T, any>, 'value'>,
-    fallback: FallbackResult,
-    resolutionRender?: undefined,
-    errorRender?: undefined,
-): FallbackResult | Awaited<T> | string;
-/**
- * Given a {@link AsyncProp} instance, call and return the output of the `resolutionRender` parameter
- * once the {@link AsyncProp} has been resolved, call and return the output of the `errorRender`
- * parameter if the {@link AsyncProp} errored out, return the `fallback` parameter in all other
- * cases.
- *
- * This is the full function definition and implementation.
- *
- * @category Async
- */
-export function renderAsync<
-    T,
-    FallbackResult,
-    ResolutionRenderResult = never,
-    ErrorRenderResult = never,
->(
-    asyncProp: Pick<AsyncProp<T, any>, 'value'>,
-    /** This value will be rendered if the async prop has not settled yet. */
-    fallback: FallbackResult,
-    resolutionRender?: ((resolved: Awaited<T>) => ResolutionRenderResult) | undefined,
-    errorRender?: ((error: Error) => ErrorRenderResult) | undefined,
-): FallbackResult | Awaited<T> | ResolutionRenderResult | string | ErrorRenderResult {
-    const asyncPropValue = asyncProp.value;
-    if (asyncPropValue instanceof Error) {
-        const errorResult: string | ErrorRenderResult = errorRender
-            ? errorRender(asyncPropValue)
-            : extractErrorMessage(asyncPropValue);
-        return errorResult as any;
-    } else if (check.isPromiseLike(asyncPropValue)) {
-        const fallbackResult: FallbackResult = fallback;
-        return fallbackResult as any;
-    } else {
-        const resolutionResult: ResolutionRenderResult | Awaited<T> = resolutionRender
-            ? resolutionRender(asyncPropValue)
-            : asyncPropValue;
-        return resolutionResult as any;
-    }
-}

package/src/declarative-element/properties/assign-inputs.ts

@@ -1,30 +0,0 @@
-import {getObjectTypedKeys} from '@augment-vir/common';
-import {type DeclarativeElement} from '../declarative-element.js';
-
-export function assignInputs(element: Element, inputs: object): void {
-    const instanceState = (element as Partial<DeclarativeElement>).instanceState;
-
-    getObjectTypedKeys(inputs).forEach((newInputKey) => {
-        if (instanceState && newInputKey in instanceState) {
-            throw new Error(
-                `Cannot set input '${String(newInputKey)}' on '${element.tagName}'. '${element.tagName}' already has a state property with the same name.`,
-            );
-        }
-        if ('instanceInputs' in element) {
-            (element.instanceInputs as DeclarativeElement['instanceInputs'])[newInputKey] =
-                inputs[newInputKey];
-        } else {
-            element[newInputKey] = inputs[newInputKey];
-        }
-    });
-
-    /** Wipe out all inputs that weren't set to undefined (as expected) */
-    if ('instanceInputs' in element) {
-        getObjectTypedKeys(element.instanceInputs).forEach((existingKey) => {
-            if (!(existingKey in inputs)) {
-                (element.instanceInputs as DeclarativeElement['instanceInputs'])[existingKey] =
-                    undefined;
-            }
-        });
-    }
-}

package/src/declarative-element/properties/css-vars.ts

@@ -1,24 +0,0 @@
-import {type Values} from '@augment-vir/common';
-import {type CssVarDefinitions, type CssVarsSetup} from 'lit-css-vars';
-import {type CustomElementTagName} from '../custom-tag-name.js';
-import {type BaseStringName} from './string-names.js';
-
-/**
- * Base type for a declarative element definition's CSS vars.
- *
- * @category Internal
- */
-export type CssVarsInitMap<
-    ElementTagName extends CustomElementTagName,
-    CssVarKeys extends BaseStringName<ElementTagName>,
-> = Readonly<Record<CssVarKeys, Values<CssVarsSetup>>>;
-
-/**
- * CSS vars ready for use within a declarative element's `render` or `styles` method.
- *
- * @category Internal
- */
-export type CssVars<
-    ElementTagName extends CustomElementTagName,
-    CssVarKeys extends BaseStringName<ElementTagName>,
-> = CssVarDefinitions<CssVarsInitMap<ElementTagName, CssVarKeys>>;

package/src/declarative-element/properties/element-events.ts

@@ -1,161 +0,0 @@
-import {
-    type DefinedTypedEvent,
-    type DefineEvent,
-    defineTypedEvent,
-    type TypedEvent,
-} from '../../typed-event/typed-event.js';
-import {type NonEmptyString} from '../../util/type.js';
-import {type CustomElementTagName} from '../custom-tag-name.js';
-
-/**
- * Base type for defining element events inside of an element definition.
- *
- * @category Internal
- */
-export type EventsInitMap = Record<string, DefineEvent<any>>;
-
-/**
- * Used to define element events, with a type.
- *
- * @category Element Definition
- * @example
- *
- * ```ts
- * import {html, defineElement, defineElementEvent, listen} from 'element-vir';
- *
- * const MyElement = defineElement()({
- *     tagName: 'my-element',
- *     events: {
- *         myOutput: defineElementEvent<number>(),
- *     },
- *     render({events, dispatch}) {
- *         return html`
- *             <div
- *                 ${listen('click', () => {
- *                     dispatch(new events.myOutput(1));
- *                 })}
- *             >
- *                 Some div
- *             </div>
- *         `;
- *     },
- * });
- * ```
- */
-export function defineElementEvent<EventDetailGeneric>(): DefineEvent<EventDetailGeneric> {
-    return defineTypedEvent<EventDetailGeneric>();
-}
-
-/**
- * Extracts the detail type of the given event name from the given event init map.
- *
- * @category Internal
- */
-export type EventInitMapEventDetailExtractor<
-    EventTypeNameGeneric extends keyof EventsInitGeneric,
-    EventsInitGeneric extends EventsInitMap,
-> = EventsInitGeneric[EventTypeNameGeneric] extends DefineEvent<infer Detail> ? Detail : never;
-
-/**
- * Maps the given element tag name and map of event names to their run-time event type strings.
- *
- * @category Internal
- */
-export type EventDescriptorMap<
-    TagName extends CustomElementTagName,
-    EventsInitGeneric extends EventsInitMap,
-> = {
-    [CurrentEventTypeName in keyof EventsInitGeneric]: DefinedTypedEvent<
-        CurrentEventTypeName extends string ? `${TagName}-${CurrentEventTypeName}` : never,
-        EventInitMapEventDetailExtractor<CurrentEventTypeName, EventsInitGeneric>
-    >;
-};
-
-/**
- * Extract the event detail type from a {@link TypedEvent}, {@link DefinedTypedEvent}, or
- * `CustomEvent.
- *
- * @category Internal
- */
-export type EventDetail<
-    ElementEvent extends TypedEvent<any, any> | DefinedTypedEvent<any, any> | CustomEvent,
-> =
-    ElementEvent extends TypedEvent<string, infer Detail>
-        ? Detail
-        : ElementEvent extends DefinedTypedEvent<any, infer Detail>
-          ? Detail
-          : ElementEvent extends CustomEvent<infer Detail>
-            ? Detail
-            : 'TYPE ERROR: failed to extract event detail type';
-
-/**
- * Maps an element definition initialization's tag name and event map to a map of ready-to-construct
- * event classes. This also verifies that the input event init map has valid keys.
- *
- * @category Internal
- */
-export function createEventDescriptorMap<
-    TagName extends CustomElementTagName,
-    EventsInitGeneric extends EventsInitMap,
->(
-    tagName: CustomElementTagName,
-    eventsInit: EventsInitGeneric | undefined,
-): EventDescriptorMap<TagName, EventsInitGeneric> {
-    if (!eventsInit) {
-        return {} as EventDescriptorMap<TagName, EventsInitGeneric>;
-    }
-    return (
-        Object.keys(eventsInit)
-            /** Verify event keys. */
-            .filter(
-                (
-                    currentElementEventKey: keyof EventsInitGeneric,
-                ): currentElementEventKey is NonEmptyString<keyof EventsInitGeneric> => {
-                    if (typeof currentElementEventKey !== 'string') {
-                        throw new TypeError(
-                            `Expected event key of type string but got type '${typeof currentElementEventKey}' for key ${String(
-                                currentElementEventKey,
-                            )}`,
-                        );
-                    } else if (currentElementEventKey === '') {
-                        throw new Error(`Got empty string for events key.`);
-                    }
-                    return true;
-                },
-            )
-            .reduce(
-                (
-                    accum: EventDescriptorMap<TagName, EventsInitGeneric>,
-                    currentElementEventKey: keyof EventsInitGeneric,
-                ): EventDescriptorMap<TagName, EventsInitGeneric> => {
-                    const eventObject: DefinedTypedEvent<
-                        typeof currentElementEventKey extends string
-                            ? typeof currentElementEventKey
-                            : never,
-                        EventInitMapEventDetailExtractor<
-                            typeof currentElementEventKey,
-                            EventsInitGeneric
-                        >
-                    > = defineTypedEvent<
-                        EventInitMapEventDetailExtractor<
-                            typeof currentElementEventKey,
-                            EventsInitGeneric
-                        >
-                    >()<
-                        typeof currentElementEventKey extends string
-                            ? typeof currentElementEventKey
-                            : never
-                    >(
-                        [
-                            tagName,
-                            currentElementEventKey,
-                        ].join('-') as any,
-                    );
-
-                    accum[currentElementEventKey] = eventObject as any;
-                    return accum;
-                },
-                {} as EventDescriptorMap<TagName, EventsInitGeneric>,
-            )
-    );
-}

package/src/declarative-element/properties/host-classes.ts

@@ -1,63 +0,0 @@
-import {mapObjectValues} from '@augment-vir/common';
-import {type CustomElementTagName} from '../custom-tag-name.js';
-import {type PropertyInitMapBase} from './element-properties.js';
-import {type BaseStringName} from './string-names.js';
-import {type WithTagName} from './tag-name.js';
-
-/**
- * Base init map for defining host classes in an element definition.
- *
- * @category Internal
- */
-export type HostClassesInitMap<
-    TagName extends CustomElementTagName,
-    HostClassKeys extends BaseStringName<TagName>,
-    Inputs extends PropertyInitMapBase,
-    State extends PropertyInitMapBase,
-> = Record<
-    HostClassKeys,
-    /**
-     * Callback to determine when host class should be enabled (based on current inputs and state),
-     * or just undefined to mark that this host class name will only be manually applied.
-     */
-    ((inputs: {state: Readonly<State>; inputs: Readonly<Inputs>}) => boolean) | false
->;
-
-/**
- * Creates a mapping of host class keys (as defined in an element definition) to their runtime host
- * class names.
- *
- * @category Internal
- */
-export type HostClassNamesMap<TagName extends string, HostClassKeys extends string> = Record<
-    HostClassKeys,
-    WithTagName<TagName, string>
->;
-
-/**
- * Maps element definition host class definitions to their runtime host class name equivalents.
- *
- * @category Internal
- */
-export function createHostClassNamesMap<
-    TagName extends CustomElementTagName,
-    HostClassKeys extends BaseStringName<TagName>,
-    HostClassesInit extends HostClassesInitMap<
-        TagName,
-        HostClassKeys,
-        /**
-         * We can use any here because we don't care what the state or input names are, we just care
-         * what the host class names are
-         */
-        any,
-        any
-    >,
->(hostClassesInit?: HostClassesInit): HostClassNamesMap<TagName, HostClassKeys> {
-    if (hostClassesInit) {
-        return mapObjectValues(hostClassesInit, (key) => {
-            return key;
-        }) as HostClassNamesMap<TagName, HostClassKeys>;
-    } else {
-        return {} as HostClassNamesMap<TagName, HostClassKeys>;
-    }
-}

package/src/declarative-element/properties/string-names.ts

@@ -1,83 +0,0 @@
-import {arrayToObject, type ArrayElement} from '@augment-vir/common';
-import {type CustomElementTagName} from '../custom-tag-name.js';
-
-/**
- * Base requirement for all string names with the element tag name prepended.
- *
- * @category Internal
- */
-export type BaseStringName<ElementTagName extends CustomElementTagName> =
-    `${ElementTagName}-${string}`;
-
-/**
- * Asserts that all the given string names for the given element are valid.
- *
- * @category Internal
- */
-export function assertValidStringNames(
-    elementTagName: CustomElementTagName,
-    stringNames: Record<BaseStringName<CustomElementTagName>, any>,
-): void {
-    const requiredNameStart = [
-        elementTagName,
-        '-',
-    ].join('');
-
-    Object.keys(stringNames).forEach((stringName) => {
-        if (!stringName.startsWith(requiredNameStart)) {
-            throw new Error(
-                `Invalid element string name '${stringName}' in '${elementTagName}': element string names must begin with the element's tag name.`,
-            );
-        }
-    });
-}
-
-/**
- * Type safe mapping of string names to themself with the element tag name inserted.
- *
- * @category Internal
- */
-export type StringNameMap<
-    ElementTagName extends CustomElementTagName,
-    NameType extends string,
-    StringNames extends ReadonlyArray<string>,
-> = Readonly<{
-    [StringName in ArrayElement<StringNames>]: `${ElementTagName}-${NameType}-${StringName}`;
-}>;
-
-/**
- * Converts an array of string names into a `StringNameMap`.
- *
- * @category Internal
- */
-export function createStringNameMap<
-    ElementTagName extends CustomElementTagName,
-    NameType extends string,
-    StringNames extends ReadonlyArray<string>,
->(
-    elementTagName: ElementTagName,
-    nameType: NameType,
-    stringNames: StringNames | undefined,
-): StringNameMap<ElementTagName, NameType, StringNames> {
-    if (!stringNames) {
-        return {} as StringNameMap<ElementTagName, NameType, StringNames>;
-    }
-    const stringNameMap: Record<string, string> = arrayToObject(
-        stringNames,
-        (stringName) => {
-            return {
-                key: stringName,
-                value: [
-                    elementTagName,
-                    nameType,
-                    stringName,
-                ].join('-'),
-            };
-        },
-        {
-            useRequired: true,
-        },
-    );
-
-    return stringNameMap as StringNameMap<ElementTagName, NameType, StringNames>;
-}