element-vir 26.11.2 → 26.12.0

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

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

@@ -0,0 +1,63 @@
+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/{dist/declarative-element/properties/property-proxy.js → src/declarative-element/properties/property-proxy.ts}

@@ -1,54 +1,85 @@
-import { isObservableBase } from 'observavir';
-import { property } from '../../lit-exports/base-lit-exports.js';
+import {type ObservableListener, isObservableBase} from 'observavir';
+import {property} from '../../lit-exports/base-lit-exports.js';
+import {type DeclarativeElement} from '../declarative-element.js';
+import {type PropertyInitMapBase} from './element-properties.js';
+
+/**
+ * Used for a map of all observables registered to an element instance.
+ *
+ * @category Internal
+ */
+export type ObservableListenerMap<OriginalPropertyMap extends PropertyInitMapBase> = Partial<
+    Record<keyof OriginalPropertyMap, ObservableListener<any> | undefined>
+>;
+
 /**
  * Binds the given property key as a reactive property on the given element.
  *
  * @category Internal
  */
-export function bindReactiveProperty(element, propertyKey) {
+export function bindReactiveProperty(element: HTMLElement, propertyKey: PropertyKey) {
     if (!(propertyKey in element)) {
         property()(element, propertyKey);
     }
 }
-function assertValidPropertyName(propKey, element, elementTagName) {
+
+function assertValidPropertyName<PropertyInitGeneric extends PropertyInitMapBase>(
+    propKey: any,
+    element: DeclarativeElement,
+    elementTagName: string,
+): asserts propKey is keyof PropertyInitGeneric {
     if (typeof propKey !== 'string' && typeof propKey !== 'number' && typeof propKey !== 'symbol') {
-        throw new TypeError(`Property name must be a string, got type '${typeof propKey}' from: '${String(propKey)}' for '${elementTagName.toLowerCase()}'`);
+        throw new TypeError(
+            `Property name must be a string, got type '${typeof propKey}' from: '${String(
+                propKey,
+            )}' for '${elementTagName.toLowerCase()}'`,
+        );
     }
     if (!(propKey in element)) {
-        throw new Error(`Property '${String(propKey)}' does not exist on '${elementTagName.toLowerCase()}'.`);
+        throw new Error(
+            `Property '${String(propKey)}' does not exist on '${elementTagName.toLowerCase()}'.`,
+        );
     }
 }
+
 /**
  * Creates an internal proxy for setting inputs and state properties and then updating them on the
  * element itself so they will trigger lit's change detection.
  *
  * @category Internal
  */
-export function createElementPropertyProxy(element, shouldAlreadyExist) {
+export function createElementPropertyProxy<PropertyInitGeneric extends PropertyInitMapBase>(
+    element: DeclarativeElement,
+    shouldAlreadyExist: boolean,
+): PropertyInitGeneric {
     /**
      * Lit element updates state and inputs by setting them directly on the element, so we must do
      * that here. DeclarativeElement's types, however, do not expose this behavior, so we add that
      * back in here.
      */
-    const elementAsProps = element;
-    function verifyProperty(propertyKey) {
+    const elementAsProps = element as DeclarativeElement & PropertyInitGeneric;
+
+    function verifyProperty(propertyKey: PropertyKey) {
         if (shouldAlreadyExist) {
             assertValidPropertyName(propertyKey, element, element.tagName);
-        }
-        else {
+        } else {
             bindReactiveProperty(element, propertyKey);
         }
     }
-    function valueGetter(target, propertyKey) {
+
+    function valueGetter(target: any, propertyKey: keyof PropertyInitGeneric | symbol) {
         verifyProperty(propertyKey);
+
         return elementAsProps[propertyKey];
     }
-    const propsProxy = new Proxy({}, {
+
+    const propsProxy = new Proxy({} as Record<PropertyKey, unknown>, {
         get: valueGetter,
-        set(target, propertyKey, newValue) {
+        set(target, propertyKey: keyof PropertyInitGeneric | symbol, newValue) {
             verifyProperty(propertyKey);
             const oldValue = elementAsProps[propertyKey];
-            function setValueOnElement(value) {
+
+            function setValueOnElement(value: typeof newValue) {
                 /**
                  * We need to at least set the property on target so we can detect it in "ownKeys"
                  * and "getOwnPropertyDescriptor". We don't need duplicates of the values stored in
@@ -57,29 +88,33 @@ export function createElementPropertyProxy(element, shouldAlreadyExist) {
                 target[propertyKey] = value;
                 elementAsProps[propertyKey] = value;
             }
-            const existingPropertyListener = element.observablePropertyListenerMap[propertyKey];
+
+            const existingPropertyListener: ObservableListener<any> | undefined =
+                element.observablePropertyListenerMap[propertyKey];
+
             if (oldValue !== newValue && isObservableBase(oldValue) && existingPropertyListener) {
                 /** Stop listening to the old value now that we have a new value */
                 oldValue.removeListener(existingPropertyListener);
             }
+
             if (isObservableBase(newValue)) {
                 /** If we're using an existing observable property */
                 if (existingPropertyListener) {
                     newValue.listen(false, existingPropertyListener);
-                }
-                else {
+                } else {
                     function newListener() {
                         element.requestUpdate();
                     }
                     element.observablePropertyListenerMap[propertyKey] = newListener;
                     newValue.listen(false, newListener);
                 }
-            }
-            else if (isObservableBase(oldValue)) {
+            } else if (isObservableBase(oldValue)) {
                 /** Clear out old listener that is no longer used. */
                 element.observablePropertyListenerMap[propertyKey] = undefined;
             }
+
             setValueOnElement(newValue);
+
             return true;
         },
         ownKeys(target) {
@@ -95,11 +130,13 @@ export function createElementPropertyProxy(element, shouldAlreadyExist) {
                     enumerable: true,
                 };
             }
+
             return undefined;
         },
         has(target, propertyName) {
             return Reflect.has(target, propertyName);
         },
     });
-    return propsProxy;
+
+    return propsProxy as PropertyInitGeneric;
 }

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

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

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

@@ -0,0 +1,112 @@
+import {getObjectTypedKeys, mapObjectValues} from '@augment-vir/common';
+import {type CSSResult, unsafeCSS} from '../../lit-exports/base-lit-exports.js';
+import {type CustomElementTagName} from '../custom-tag-name.js';
+import {type CssVars} from './css-vars.js';
+import {type PropertyInitMapBase} from './element-properties.js';
+import {type HostClassNamesMap, type HostClassesInitMap} from './host-classes.js';
+import {type BaseStringName} from './string-names.js';
+
+/**
+ * A host class instance to be referenced inside of an element definition's `styles` callback.
+ *
+ * @category Internal
+ */
+export type HostClass = {
+    selector: CSSResult;
+    name: CSSResult;
+};
+
+/**
+ * Input type for an element definition's `styles` callback.
+ *
+ * @category Internal
+ */
+export type StylesCallbackInput<
+    TagName extends CustomElementTagName,
+    HostClassKeys extends BaseStringName<TagName>,
+    CssVarKeys extends BaseStringName<TagName>,
+> = {
+    hostClasses: Record<HostClassKeys, HostClass>;
+    cssVars: Readonly<CssVars<TagName, CssVarKeys>>;
+};
+
+/**
+ * The type for an element definition's `styles` callback.
+ *
+ * @category Internal
+ */
+export type StylesCallback<
+    TagName extends CustomElementTagName,
+    HostClassKeys extends BaseStringName<TagName>,
+    CssVarKeys extends BaseStringName<TagName>,
+> = (input: StylesCallbackInput<TagName, HostClassKeys, CssVarKeys>) => CSSResult;
+
+/**
+ * Creates the input for an element definition's `styles` callback.
+ *
+ * @category Internal
+ */
+export function createStylesCallbackInput<
+    TagName extends CustomElementTagName,
+    HostClassKeys extends BaseStringName<TagName>,
+    CssVarKeys extends BaseStringName<TagName>,
+>({
+    hostClassNames,
+    cssVars,
+}: {
+    hostClassNames: HostClassNamesMap<TagName, HostClassKeys>;
+    cssVars: Readonly<CssVars<TagName, CssVarKeys>>;
+}): StylesCallbackInput<TagName, HostClassKeys, CssVarKeys> {
+    return {
+        hostClasses: mapObjectValues(hostClassNames, (key, name): HostClass => {
+            return {
+                name: unsafeCSS(name),
+                selector: unsafeCSS(`:host(.${name})`),
+            };
+        }),
+        cssVars,
+    };
+}
+
+/**
+ * Used inside of an element instance to apply host classes on each render.
+ *
+ * @category Internal
+ */
+export function applyHostClasses<
+    TagName extends CustomElementTagName,
+    Inputs extends PropertyInitMapBase,
+    State extends PropertyInitMapBase,
+    HostClassKeys extends BaseStringName<TagName>,
+>({
+    host,
+    hostClassesInit,
+    hostClassNames,
+    state,
+    inputs,
+}: {
+    host: HTMLElement;
+    hostClassesInit:
+        | Readonly<HostClassesInitMap<TagName, HostClassKeys, Inputs, State>>
+        | undefined;
+    hostClassNames: HostClassNamesMap<string, HostClassKeys>;
+    state: Readonly<State>;
+    inputs: Readonly<Inputs>;
+}): void {
+    if (!hostClassesInit) {
+        return;
+    }
+    getObjectTypedKeys(hostClassesInit).forEach((hostClassKey) => {
+        const maybeCallback = hostClassesInit[hostClassKey];
+        const hostClassName = hostClassNames[hostClassKey];
+
+        if (typeof maybeCallback === 'function') {
+            const shouldApplyHostClass = maybeCallback({state, inputs});
+            if (shouldApplyHostClass) {
+                host.classList.add(hostClassName);
+            } else {
+                host.classList.remove(hostClassName);
+            }
+        }
+    });
+}