element-vir 17.0.2 → 18.0.0

package/dist/declarative-element/declarative-element.d.ts

@@ -9,7 +9,7 @@ import { EventDescriptorMap, EventsInitMap } from './properties/element-events';
 import { ElementPropertyDescriptorMap, PropertyInitMapBase } from './properties/element-properties';
 import { FlattenElementVirStateSetup } from './properties/element-vir-state-setup';
 import { HostClassNamesMap } from './properties/host-classes';
-import { ObservablePropertyListenerMap } from './properties/observable-property/observable-property';
+import { ObservablePropListenerMap } from './properties/observable-prop/observable-prop';
 import type { RenderCallback, RenderParams, UpdateStateCallback } from './render-callback';
 export type DeclarativeElementHost<TagName extends CustomElementTagName = any, Inputs extends PropertyInitMapBase = any, StateInit extends PropertyInitMapBase = any, EventsInit extends EventsInitMap = any, HostClassKeys extends BaseCssPropertyName<TagName> = any, CssVarKeys extends BaseCssPropertyName<TagName> = any> = RequiredAndNotNullBy<Omit<DeclarativeElement<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, any>, Exclude<keyof StaticDeclarativeElementProperties<any, any, any, any, any, any, any>, keyof HTMLElement>>, 'shadowRoot'>;
 export type DeclarativeElementDefinition<TagName extends CustomElementTagName = any, Inputs extends PropertyInitMapBase = any, StateInit extends PropertyInitMapBase = any, EventsInit extends EventsInitMap = any, HostClassKeys extends BaseCssPropertyName<TagName> = any, CssVarKeys extends BaseCssPropertyName<TagName> = any, RenderOutputGeneric = any> = (new () => DeclarativeElementHost<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys>) & StaticDeclarativeElementProperties<TagName, Inputs, StateInit, EventsInit, HostClassKeys, CssVarKeys, RenderOutputGeneric> & {
@@ -35,7 +35,7 @@ export declare abstract class DeclarativeElement<TagName extends CustomElementTa
     abstract _lastRenderedProps: Pick<RenderParams<any, Inputs, StateInit, any, any, any>, 'inputs' | 'state'>;
     abstract render(): unknown;
     abstract readonly instanceState: FlattenElementVirStateSetup<StateInit>;
-    abstract readonly observablePropertyListenerMap: ObservablePropertyListenerMap<StateInit & Inputs>;
+    abstract readonly observablePropertyListenerMap: ObservablePropListenerMap<StateInit & Inputs>;
     abstract readonly instanceInputs: Inputs;
     abstract assignInputs(inputs: {} extends Required<Inputs> ? never : Partial<Inputs>): void;
     abstract _haveInputsBeenSet: boolean;

package/dist/declarative-element/define-element-no-inputs.js

@@ -4,7 +4,6 @@ var __setFunctionName = (this && this.__setFunctionName) || function (f, name, p
 };
 import { ensureError, getObjectTypedKeys, kebabCaseToCamelCase, } from '@augment-vir/common';
 import { defineCssVars } from 'lit-css-vars';
-import { property } from 'lit/decorators.js';
 import { css } from '../template-transforms/vir-css/vir-css';
 import { DeclarativeElement, } from './declarative-element';
 import { IgnoreInputsNotBeenSetBeforeWarningSymbol, defaultDeclarativeElementDefinitionOptions, } from './definition-options';
@@ -12,7 +11,7 @@ import { hasDeclarativeElementParent } from './has-declarative-element-parent';
 import { assignInputs } from './properties/assign-inputs';
 import { assertValidCssProperties } from './properties/css-properties';
 import { createEventDescriptorMap } from './properties/element-events';
-import { createElementUpdaterProxy } from './properties/element-updater-proxy';
+import { bindReactiveProperty, createElementUpdaterProxy } from './properties/element-updater-proxy';
 import { createHostClassNamesMap } from './properties/host-classes';
 import { applyHostClasses, hostClassNamesToStylesInput } from './properties/styles';
 import { createRenderParams } from './render-callback';
@@ -146,7 +145,7 @@ export function defineElementNoInputs(initInput) {
                 this.instanceState = createElementUpdaterProxy(this, !initInput.options?.allowPolymorphicState);
                 const stateInitStatic = initInput.stateInitStatic || {};
                 getObjectTypedKeys(stateInitStatic).forEach((stateKey) => {
-                    property()(this, stateKey);
+                    bindReactiveProperty(this, stateKey);
                     this.instanceState[stateKey] = stateInitStatic[stateKey];
                 });
                 this.definition = anonymousClass;

package/dist/declarative-element/directives/async-prop.d.ts

@@ -1,6 +1,6 @@
 import { JsonCompatibleObject, MaybePromise } from '@augment-vir/common';
 import { ElementVirStateSetup } from '../properties/element-vir-state-setup';
-import { ObservableProperty } from '../properties/observable-property/observable-property';
+import { ObservableProp } from '../properties/observable-prop/observable-prop';
 export type AsyncPropValue<ValueType> = Error | MaybePromise<Awaited<ValueType>>;
 export type AsyncPropTriggerInputBase = JsonCompatibleObject;
 export type AsyncPropUpdateCallback<TriggerInput extends AsyncPropTriggerInputBase, UpdaterInput, ReturnType> = Exclude<TriggerInput, undefined> extends never ? () => ReturnType : Exclude<UpdaterInput, undefined> extends never ? (trigger: TriggerInput) => ReturnType : (trigger: TriggerInput, inputs: UpdaterInput) => ReturnType;
@@ -18,7 +18,7 @@ export type AsyncPropInit<ValueType, TriggerInput extends AsyncPropTriggerInputB
      */
     updateCallback: AsyncPropUpdateCallback<TriggerInput, UpdaterInput, Promise<Awaited<ValueType>>>;
 };
-export type AsyncObservableProperty<ValueType, TriggerInput extends AsyncPropTriggerInputBase, UpdaterInput> = ObservableProperty<AsyncPropValue<ValueType>> & {
+export type AsyncObservableProp<ValueType, TriggerInput extends AsyncPropTriggerInputBase, UpdaterInput> = ObservableProp<AsyncPropValue<ValueType>> & {
     setNewPromise(newPromise: Promise<Awaited<ValueType>>): void;
     updateTrigger: AsyncPropUpdateCallback<TriggerInput, UpdaterInput, void>;
     setResolvedValue(resolvedValue: Awaited<ValueType>): void;
@@ -28,4 +28,4 @@ export type AsyncObservableProperty<ValueType, TriggerInput extends AsyncPropTri
      */
     forceUpdate: AsyncPropUpdateCallback<TriggerInput, UpdaterInput, void>;
 };
-export declare function asyncProp<ValueType, TriggerInput extends AsyncPropTriggerInputBase = {}, UpdaterInput = undefined>(...args: [AsyncPropInit<ValueType, TriggerInput, UpdaterInput>] | []): ElementVirStateSetup<AsyncObservableProperty<ValueType, TriggerInput, UpdaterInput>>;
+export declare function asyncProp<ValueType, TriggerInput extends AsyncPropTriggerInputBase = {}, UpdaterInput = undefined>(...args: [AsyncPropInit<ValueType, TriggerInput, UpdaterInput>] | []): ElementVirStateSetup<AsyncObservableProp<ValueType, TriggerInput, UpdaterInput>>;

package/dist/declarative-element/directives/async-prop.js

@@ -1,23 +1,23 @@
 import { areJsonEqual, createDeferredPromiseWrapper, ensureError, } from '@augment-vir/common';
-import { createObservablePropertyWithSetter } from '../properties/observable-property/create-observable-property';
+import { createSetterObservableProp } from '../properties/observable-prop/setter-observable-prop';
 const notSetSymbol = Symbol('not set');
 function setupAsyncProp(init) {
     let lastTrigger = notSetSymbol;
     let lastSetPromise;
     const promiseUpdater = init && 'updateCallback' in init ? init.updateCallback : undefined;
     let waitingForValuePromise = createDeferredPromiseWrapper();
-    const baseObservableProperty = createObservablePropertyWithSetter(waitingForValuePromise.promise);
+    const baseObservableProp = createSetterObservableProp(waitingForValuePromise.promise);
     function resetWaitingForValuePromise() {
         waitingForValuePromise = createDeferredPromiseWrapper();
-        baseObservableProperty.setValue(waitingForValuePromise.promise);
+        baseObservableProp.setValue(waitingForValuePromise.promise);
     }
     function resolveValue(value) {
         waitingForValuePromise.resolve(value);
-        baseObservableProperty.setValue(value);
+        baseObservableProp.setValue(value);
     }
     function rejectValue(error) {
         waitingForValuePromise.reject(error);
-        baseObservableProperty.setValue(error);
+        baseObservableProp.setValue(error);
     }
     function setPromise(newPromise) {
         if (newPromise === lastSetPromise) {
@@ -89,7 +89,7 @@ function setupAsyncProp(init) {
             setPromise(newPromise);
         },
         setResolvedValue(value) {
-            if (value !== baseObservableProperty.value) {
+            if (value !== baseObservableProp.value) {
                 if (waitingForValuePromise.isSettled()) {
                     resetWaitingForValuePromise();
                 }
@@ -108,7 +108,7 @@ function setupAsyncProp(init) {
                 throw new Error('Cannot run forceUpdate when updateCallback was not set on the asyncProp.');
             }),
     };
-    return Object.assign(baseObservableProperty, extraProperties);
+    return Object.assign(baseObservableProp, extraProperties);
 }
 export function asyncProp(...args) {
     return {

package/dist/declarative-element/directives/create-attribute-directive.d.ts

@@ -4,7 +4,7 @@ export declare function createAttributeDirective(attributeName: string): {
     attributeDirective(attributeValue: string): import("lit-html/directive").DirectiveResult<{
         new (partInfo: PartInfo): {
             readonly element: Element;
-            render(testId: string): symbol;
+            render(attributeValue: string): symbol;
             readonly _$isConnected: boolean;
             update(_part: import("lit-html").Part, props: unknown[]): unknown;
         };

package/dist/declarative-element/directives/create-attribute-directive.js

@@ -7,10 +7,10 @@ export function createAttributeDirective(attributeName) {
     class extends Directive {
         constructor(partInfo) {
             super(partInfo);
-            this.element = extractElement(partInfo, 'testId');
+            this.element = extractElement(partInfo, attributeName);
         }
-        render(testId) {
-            this.element.setAttribute(attributeName, testId);
+        render(attributeValue) {
+            this.element.setAttribute(attributeName, attributeValue);
             return noChange;
         }
     });

package/dist/declarative-element/directives/render-async.directive.d.ts

@@ -1,5 +1,5 @@
-import { AsyncObservableProperty } from './async-prop';
-export declare function renderAsync<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncProp: AsyncObservableProperty<T, any, any>, fallback: FallbackResult, resolutionRender: (resolved: Awaited<T>) => ResolutionRenderResult, errorRender: (error: Error) => ErrorRenderResult): FallbackResult | ResolutionRenderResult | ErrorRenderResult;
-export declare function renderAsync<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncProp: AsyncObservableProperty<T, any, any>, fallback: FallbackResult, resolutionRender: (resolved: Awaited<T>) => ResolutionRenderResult, errorRender?: undefined): FallbackResult | ResolutionRenderResult | string;
-export declare function renderAsync<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncProp: AsyncObservableProperty<T, any, any>, fallback: FallbackResult, resolutionRender: undefined, errorRender: (error: Error) => ErrorRenderResult): FallbackResult | Awaited<T> | ErrorRenderResult;
-export declare function renderAsync<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncProp: AsyncObservableProperty<T, any, any>, fallback: FallbackResult, resolutionRender?: undefined, errorRender?: undefined): FallbackResult | Awaited<T> | string;
+import { AsyncObservableProp } from './async-prop';
+export declare function renderAsync<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncProp: AsyncObservableProp<T, any, any>, fallback: FallbackResult, resolutionRender: (resolved: Awaited<T>) => ResolutionRenderResult, errorRender: (error: Error) => ErrorRenderResult): FallbackResult | ResolutionRenderResult | ErrorRenderResult;
+export declare function renderAsync<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncProp: AsyncObservableProp<T, any, any>, fallback: FallbackResult, resolutionRender: (resolved: Awaited<T>) => ResolutionRenderResult, errorRender?: undefined): FallbackResult | ResolutionRenderResult | string;
+export declare function renderAsync<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncProp: AsyncObservableProp<T, any, any>, fallback: FallbackResult, resolutionRender: undefined, errorRender: (error: Error) => ErrorRenderResult): FallbackResult | Awaited<T> | ErrorRenderResult;
+export declare function renderAsync<T, FallbackResult, ResolutionRenderResult = never, ErrorRenderResult = never>(asyncProp: AsyncObservableProp<T, any, any>, fallback: FallbackResult, resolutionRender?: undefined, errorRender?: undefined): FallbackResult | Awaited<T> | string;

package/dist/declarative-element/directives/test-id.directive.d.ts

@@ -1,7 +1,7 @@
-export declare const testId: (attributeValue: string) => import("element-vir").DirectiveResult<{
-    new (partInfo: import("element-vir").PartInfo): {
+export declare const testId: (attributeValue: string) => import("lit-html/directive").DirectiveResult<{
+    new (partInfo: import("lit-html/directive").PartInfo): {
         readonly element: Element;
-        render(testId: string): symbol;
+        render(attributeValue: string): symbol;
         readonly _$isConnected: boolean;
         update(_part: import("lit-html").Part, props: unknown[]): unknown;
     };

package/dist/declarative-element/properties/element-events.js

@@ -20,7 +20,7 @@ export function createEventDescriptorMap(tagName, eventsInit) {
         const eventObject = defineTypedEvent()([
             tagName,
             currentElementEventKey,
-        ].join('-'));
+        ].join('_'));
         accum[currentElementEventKey] = eventObject;
         return accum;
     }, {});

package/dist/declarative-element/properties/element-updater-proxy.d.ts

@@ -1,3 +1,5 @@
 import { DeclarativeElement } from '../declarative-element';
 import { PropertyInitMapBase } from './element-properties';
+/** Binds the given property key as a reactive property on the given element. */
+export declare function bindReactiveProperty(element: HTMLElement, propertyKey: PropertyKey): void;
 export declare function createElementUpdaterProxy<PropertyInitGeneric extends PropertyInitMapBase>(element: DeclarativeElement, verifyExists: boolean): PropertyInitGeneric;

package/dist/declarative-element/properties/element-updater-proxy.js

@@ -1,6 +1,12 @@
 import { property } from 'lit/decorators.js';
 import { isElementVirStateSetup } from './element-vir-state-setup';
-import { isObservableProperty, } from './observable-property/observable-property';
+import { isObservableProp } from './observable-prop/observable-prop';
+/** Binds the given property key as a reactive property on the given element. */
+export function bindReactiveProperty(element, propertyKey) {
+    if (!(propertyKey in element)) {
+        property()(element, propertyKey);
+    }
+}
 function assertValidPropertyName(propKey, element, elementTagName) {
     if (typeof propKey !== 'string' && typeof propKey !== 'number' && typeof propKey !== 'symbol') {
         throw new Error(`Property name must be a string, got type '${typeof propKey}' from: '${String(propKey)}' for '${elementTagName.toLowerCase()}'`);
@@ -21,11 +27,7 @@ export function createElementUpdaterProxy(element, verifyExists) {
             assertValidPropertyName(propertyKey, element, element.tagName);
         }
         else {
-            /**
-             * No need to check if it's already a property or not, as the property function already
-             * makes that check.
-             */
-            property()(element, propertyKey);
+            bindReactiveProperty(element, propertyKey);
         }
     }
     function valueGetter(target, propertyKey) {
@@ -34,7 +36,7 @@ export function createElementUpdaterProxy(element, verifyExists) {
     }
     const propsProxy = new Proxy({}, {
         get: valueGetter,
-        set: (target, propertyKey, rawNewValue) => {
+        set(target, propertyKey, rawNewValue) {
             const newValue = isElementVirStateSetup(rawNewValue)
                 ? rawNewValue._elementVirStateSetup()
                 : rawNewValue;
@@ -51,12 +53,12 @@ export function createElementUpdaterProxy(element, verifyExists) {
             }
             const existingPropertyListener = element.observablePropertyListenerMap[propertyKey];
             if (oldValue !== newValue &&
-                isObservableProperty(oldValue) &&
+                isObservableProp(oldValue) &&
                 existingPropertyListener?.length) {
                 /** Stop listening to the old value now that we have a new value */
                 oldValue.removeListener(existingPropertyListener);
             }
-            if (isObservableProperty(newValue)) {
+            if (isObservableProp(newValue)) {
                 /** If we're using an existing observable property */
                 if (existingPropertyListener) {
                     newValue.addListener(existingPropertyListener);
@@ -69,14 +71,14 @@ export function createElementUpdaterProxy(element, verifyExists) {
                     newValue.addListener(newListener);
                 }
             }
-            else if (isObservableProperty(oldValue)) {
+            else if (isObservableProp(oldValue)) {
                 /** Clear out old listener that is no longer used. */
                 element.observablePropertyListenerMap[propertyKey] = undefined;
             }
             setValueOnElement(newValue);
             return true;
         },
-        ownKeys: (target) => {
+        ownKeys(target) {
             return Reflect.ownKeys(target);
         },
         getOwnPropertyDescriptor(target, propertyName) {
@@ -91,7 +93,7 @@ export function createElementUpdaterProxy(element, verifyExists) {
             }
             return undefined;
         },
-        has: (target, propertyName) => {
+        has(target, propertyName) {
             return Reflect.has(target, propertyName);
         },
     });

package/dist/declarative-element/properties/observable-prop/interval-observable-prop.d.ts

@@ -0,0 +1,37 @@
+import { Duration, DurationUnit } from 'date-vir';
+import { TriggerUpdateFunction, UpdatableObservableProp, UpdatableObservablePropSetup } from './updatable-observable-prop';
+export type IntervalObservablePropSetup<ValueType, UpdateInputType> = UpdatableObservablePropSetup<ValueType, UpdateInputType> & {
+    /** Update interval. */
+    updateInterval: Duration<DurationUnit.Milliseconds>;
+    /**
+     * If set to true, the interval observable prop will not automatically start its internal
+     * interval.
+     */
+    startPaused?: boolean | undefined;
+    /**
+     * The minimum duration between triggers. If an automatic or manual trigger happens twice within
+     * this duration, the second one will not do anything.
+     */
+    rateLimit?: Duration<DurationUnit.Milliseconds> | undefined;
+};
+export type IntervalObservableProp<ValueType, UpdateInputType> = Omit<UpdatableObservableProp<ValueType, UpdateInputType>, 'triggerUpdate'> & {
+    /** Manually force the observable prop to update outside of its normal interval. */
+    forceUpdate: TriggerUpdateFunction<ValueType, UpdateInputType>;
+    /**
+     * Pauses the update interval, if it isn't already paused. Use .resumeInterval() to start the
+     * interval again. Under the hood, this actually clears the interval entirely.
+     */
+    pauseInterval(): void;
+    /**
+     * Resumes the update interval if it was paused. Under the hood, this creates a new interval
+     * entirely, as .pauseInterval() actually clears it.
+     */
+    resumeInterval(): void;
+    /** Cleans up the interval observable prop. */
+    destroy(): void;
+};
+/**
+ * This creates an updatable observable prop that will automatically update itself at the given
+ * interval.
+ */
+export declare function createIntervalObservableProp<ValueType, UpdateInputType = undefined>(setup: IntervalObservablePropSetup<ValueType, UpdateInputType>): IntervalObservableProp<ValueType, UpdateInputType>;

package/dist/declarative-element/properties/observable-prop/interval-observable-prop.js

@@ -0,0 +1,55 @@
+import { createUpdatableObservableProp, } from './updatable-observable-prop';
+/**
+ * This creates an updatable observable prop that will automatically update itself at the given
+ * interval.
+ */
+export function createIntervalObservableProp(setup) {
+    let latestInputs = setup.initInput;
+    const baseObservableProp = createUpdatableObservableProp(setup);
+    let latestIntervalId = undefined;
+    let lastUpdateTimestamp = 0;
+    const shouldRunInterval = setup.updateInterval.milliseconds > 0 &&
+        Math.abs(setup.updateInterval.milliseconds) !== Infinity;
+    let lastOutput = baseObservableProp.value;
+    baseObservableProp.addListener((value) => (lastOutput = value));
+    function updateValue(...newInputs) {
+        if (newInputs.length) {
+            latestInputs = newInputs[0];
+        }
+        const now = Date.now();
+        const shouldIgnoreDueToRateLimiting = setup.rateLimit &&
+            setup.rateLimit.milliseconds > 0 &&
+            now - lastUpdateTimestamp < setup.rateLimit?.milliseconds;
+        if (shouldIgnoreDueToRateLimiting) {
+            return lastOutput;
+        }
+        lastUpdateTimestamp = now;
+        return baseObservableProp.triggerUpdate(latestInputs);
+    }
+    function resumeInterval() {
+        if (shouldRunInterval && latestIntervalId == undefined) {
+            latestIntervalId = window.setInterval(() => {
+                updateValue();
+            }, Math.ceil(setup.updateInterval.milliseconds));
+        }
+    }
+    function pauseInterval() {
+        if (latestIntervalId != undefined) {
+            window.clearInterval(latestIntervalId);
+            latestIntervalId = undefined;
+        }
+    }
+    if (!setup.startPaused) {
+        resumeInterval();
+    }
+    const observablePropertyWithInterval = Object.assign(baseObservableProp, {
+        forceUpdate: updateValue,
+        pauseInterval,
+        resumeInterval,
+        destroy() {
+            pauseInterval();
+            baseObservableProp.destroy();
+        },
+    });
+    return observablePropertyWithInterval;
+}

package/dist/declarative-element/properties/observable-prop/observable-prop.d.ts

@@ -0,0 +1,13 @@
+import { PropertyInitMapBase } from '../element-properties';
+export type ObservablePropListener<T> = (value: T) => void;
+export type ObservablePropListenerMap<OriginalPropertyMap extends PropertyInitMapBase> = Partial<Record<keyof OriginalPropertyMap, ObservablePropListener<any> | undefined>>;
+export type ObservableProp<ValueType> = {
+    /** Add the given listener. Returns a callback which will remove the listener. */
+    addListener(listener: ObservablePropListener<ValueType>): () => boolean;
+    /** Remove the given listener by reference. */
+    removeListener(listener: ObservablePropListener<ValueType>): boolean;
+    destroy(): void;
+    value: ValueType;
+};
+export declare const basicObservablePropShape: import("object-shape-tester").ShapeDefinition<ObservableProp<any>, false>;
+export declare function isObservableProp<ValueType = unknown>(input: unknown): input is ObservableProp<ValueType>;

package/dist/declarative-element/properties/observable-prop/observable-prop.js

@@ -0,0 +1,14 @@
+import { defineShape, isValidShape, unknownShape } from 'object-shape-tester';
+export const basicObservablePropShape = defineShape({
+    addListener() {
+        return () => false;
+    },
+    removeListener() {
+        return false;
+    },
+    destroy() { },
+    value: unknownShape(),
+});
+export function isObservableProp(input) {
+    return isValidShape(input, basicObservablePropShape, { allowExtraKeys: true });
+}

package/dist/declarative-element/properties/observable-prop/setter-observable-prop.d.ts

@@ -0,0 +1,18 @@
+import { referenceEqualityCheck } from '../../../util/equality';
+import { ObservableProp } from './observable-prop';
+/** A simple ObservableProp with a setter. */
+export type SetterObservableProp<ValueType> = ObservableProp<ValueType> & {
+    setValue(newValue: ValueType): void;
+};
+/**
+ * Easy and quick way to create an ObservableProp. Includes a setValue method with equality checking
+ * for easily emitting changes.
+ */
+export declare function createSetterObservableProp<ValueType>(
+/** The value at which the `SetterObservableProp` will start at. */
+initValue: ValueType, 
+/**
+ * The function used to determine if a set value is actually new. Defaults to simple reference
+ * equality.
+ */
+equalityCallback?: typeof referenceEqualityCheck): SetterObservableProp<ValueType>;

package/dist/declarative-element/properties/observable-prop/setter-observable-prop.js

@@ -0,0 +1,42 @@
+import { referenceEqualityCheck } from '../../../util/equality';
+/**
+ * Easy and quick way to create an ObservableProp. Includes a setValue method with equality checking
+ * for easily emitting changes.
+ */
+export function createSetterObservableProp(
+/** The value at which the `SetterObservableProp` will start at. */
+initValue, 
+/**
+ * The function used to determine if a set value is actually new. Defaults to simple reference
+ * equality.
+ */
+equalityCallback = referenceEqualityCheck) {
+    const listeners = new Set();
+    function fireListeners() {
+        listeners.forEach((listener) => listener(observableProperty.value));
+    }
+    function removeListener(listener) {
+        return listeners.delete(listener);
+    }
+    const observableProperty = {
+        value: initValue,
+        setValue(newValue) {
+            if (!equalityCallback(observableProperty.value, newValue)) {
+                observableProperty.value = newValue;
+                fireListeners();
+            }
+        },
+        addListener(listener) {
+            const shouldAddListener = !listeners.has(listener);
+            if (shouldAddListener) {
+                listeners.add(listener);
+            }
+            return () => removeListener(listener);
+        },
+        removeListener,
+        destroy() {
+            listeners.clear();
+        },
+    };
+    return observableProperty;
+}

package/dist/declarative-element/properties/observable-prop/updatable-observable-prop.d.ts

@@ -0,0 +1,40 @@
+import { referenceEqualityCheck } from '../../../util/equality';
+import { ObservableProp } from './observable-prop';
+/** Callback for updating the `UpdatableObservableProp`. */
+export type UpdaterCallback<ValueType, UpdateInputType> = (inputs: UpdateInputType, lastValue: ValueType | undefined) => ValueType;
+/** Function for updating the `UpdatableObservableProp`. */
+export type TriggerUpdateFunction<ValueType, UpdateInputType> = (inputs?: UpdateInputType) => ValueType;
+export type UpdatableObservableProp<ValueType, UpdateInputType> = ObservableProp<ValueType | Awaited<ValueType>> & {
+    /**
+     * Trigger the `UpdatableObservableProp` to update itself. Requires the inputs that the
+     * observable prop's updateCallback requires.
+     */
+    triggerUpdate: TriggerUpdateFunction<ValueType, UpdateInputType>;
+    /** The number of times that the prop has been updated. Mostly only useful for debugging. */
+    readonly updateCount: number;
+    /**
+     * The last value that was resolved. This will be undefined if there has never, so far, been a
+     * resolved value.
+     */
+    latestResolvedValue: ValueType extends Promise<any> ? Awaited<ValueType> | undefined : ValueType;
+};
+/** Setup required for creating an `UpdatableObservableProp`. */
+export type UpdatableObservablePropSetup<ValueType, UpdateInputType> = {
+    /** Initial value for the observable prop. */
+    initInput: UpdateInputType;
+    /** The callback which will be called in order to update the observable prop. */
+    updateCallback: UpdaterCallback<ValueType, UpdateInputType>;
+    /**
+     * The function used to determine if a new value is actually new. Defaults to simple reference
+     * equality.
+     */
+    equalityCallback?: typeof referenceEqualityCheck | undefined;
+};
+/**
+ * An ObservableProp that requires an updater callback on setup. Future updates then call this
+ * updater callback rather than directly setting a value (`SetterObservableProp` merely sets a
+ * value).
+ */
+export declare function createUpdatableObservableProp<ValueType, UpdateInputType = undefined>(
+/** Setup object required for creating the UpdatableObservableProp. */
+setup: UpdatableObservablePropSetup<ValueType, UpdateInputType>): UpdatableObservableProp<ValueType, UpdateInputType>;

package/dist/declarative-element/properties/observable-prop/updatable-observable-prop.js

@@ -0,0 +1,61 @@
+import { referenceEqualityCheck } from '../../../util/equality';
+import { createSetterObservableProp } from './setter-observable-prop';
+/**
+ * An ObservableProp that requires an updater callback on setup. Future updates then call this
+ * updater callback rather than directly setting a value (`SetterObservableProp` merely sets a
+ * value).
+ */
+export function createUpdatableObservableProp(
+/** Setup object required for creating the UpdatableObservableProp. */
+setup) {
+    const areEqual = setup.equalityCallback ?? referenceEqualityCheck;
+    let lastInputs = setup.initInput;
+    let internalUpdateCount = 0;
+    const innerSimpleObservableProp = createSetterObservableProp(undefined, areEqual);
+    function updateValue(...inputs) {
+        internalUpdateCount++;
+        if (inputs.length) {
+            lastInputs = inputs[0];
+        }
+        const newValue = setup.updateCallback(lastInputs, innerSimpleObservableProp.value);
+        if (newValue instanceof Promise) {
+            const wrappedPromise = new Promise(async (resolve, reject) => {
+                try {
+                    const resolvedValue = await newValue;
+                    observableWithUpdater.latestResolvedValue =
+                        resolvedValue;
+                    innerSimpleObservableProp.setValue(resolvedValue);
+                    resolve(resolvedValue);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+            /** Set the promise so consumers know it's loading. */
+            innerSimpleObservableProp.setValue(wrappedPromise);
+            return wrappedPromise;
+        }
+        else {
+            innerSimpleObservableProp.setValue(newValue);
+            observableWithUpdater.latestResolvedValue = newValue;
+            return newValue;
+        }
+    }
+    const observableWithUpdater = Object.assign(innerSimpleObservableProp, {
+        triggerUpdate: updateValue,
+        latestResolvedValue: undefined,
+        updateCount: internalUpdateCount,
+    });
+    Object.defineProperty(observableWithUpdater, 'updateCount', {
+        get() {
+            return internalUpdateCount;
+        },
+    });
+    try {
+        updateValue(setup.initInput);
+    }
+    catch (error) {
+        console.error(error);
+    }
+    return observableWithUpdater;
+}

package/dist/index.d.ts

@@ -23,8 +23,10 @@ export * from './declarative-element/properties/element-events';
 export * from './declarative-element/properties/element-properties';
 export * from './declarative-element/properties/element-vir-state-setup';
 export * from './declarative-element/properties/host-classes';
-export * from './declarative-element/properties/observable-property/create-observable-property';
-export * from './declarative-element/properties/observable-property/observable-property';
+export * from './declarative-element/properties/observable-prop/interval-observable-prop';
+export * from './declarative-element/properties/observable-prop/observable-prop';
+export * from './declarative-element/properties/observable-prop/setter-observable-prop';
+export * from './declarative-element/properties/observable-prop/updatable-observable-prop';
 export * from './declarative-element/properties/per-instance';
 export * from './declarative-element/properties/styles';
 export * from './declarative-element/properties/tag-name';

package/dist/index.js

@@ -22,8 +22,10 @@ export * from './declarative-element/properties/element-events';
 export * from './declarative-element/properties/element-properties';
 export * from './declarative-element/properties/element-vir-state-setup';
 export * from './declarative-element/properties/host-classes';
-export * from './declarative-element/properties/observable-property/create-observable-property';
-export * from './declarative-element/properties/observable-property/observable-property';
+export * from './declarative-element/properties/observable-prop/interval-observable-prop';
+export * from './declarative-element/properties/observable-prop/observable-prop';
+export * from './declarative-element/properties/observable-prop/setter-observable-prop';
+export * from './declarative-element/properties/observable-prop/updatable-observable-prop';
 export * from './declarative-element/properties/per-instance';
 export * from './declarative-element/properties/styles';
 export * from './declarative-element/properties/tag-name';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-vir",
-    "version": "17.0.2",
+    "version": "18.0.0",
     "keywords": [
         "custom",
         "web",
@@ -29,7 +29,7 @@
         "docs": "virmator docs",
         "format": "virmator format",
         "publish": "virmator publish \"npm run compile && npm run test:all\"",
-        "start": "npm install && virmator frontend",
+        "start": "npm run compile && npm install && virmator frontend",
         "test": "virmator test-web",
         "test:all": "concurrently -c auto --kill-others-on-fail --colors --names types,tests,spelling,format,docs \"npm run test:types\" \"npm run test:coverage\" \"npm run test:spelling\" \"npm run test:format\" \"npm run test:docs\"",
         "test:coverage": "virmator test-web coverage",
@@ -40,19 +40,21 @@
         "test:types": "tsc --noEmit"
     },
     "dependencies": {
-        "@augment-vir/common": "^22.0.0",
-        "lit": "^2.8.0",
-        "lit-css-vars": "^3.0.3",
+        "@augment-vir/common": "^22.1.0",
+        "date-vir": "^5.0.0",
+        "lit": "^3.1.0",
+        "lit-css-vars": "^3.0.7",
+        "lit-html": "^3.1.0",
         "object-shape-tester": "^1.0.2",
         "run-time-assertions": "^0.2.1"
     },
     "devDependencies": {
-        "@augment-vir/browser-testing": "^22.0.0",
-        "@augment-vir/node-js": "^22.0.0",
+        "@augment-vir/browser-testing": "^22.1.0",
+        "@augment-vir/node-js": "^22.1.0",
         "@istanbuljs/nyc-config-typescript": "^1.0.2",
         "@open-wc/testing": "^4.0.0",
-        "@types/chai": "^4.3.10",
-        "@types/mocha": "^10.0.4",
+        "@types/chai": "^4.3.11",
+        "@types/mocha": "^10.0.6",
         "@web/dev-server-esbuild": "^1.0.1",
         "@web/test-runner": "^0.18.0",
         "@web/test-runner-commands": "^0.9.0",
@@ -60,34 +62,35 @@
         "@web/test-runner-visual-regression": "^0.9.0",
         "ansi-colors": "^4.1.3",
         "concurrently": "^8.2.2",
-        "cspell": "^8.0.0",
-        "dependency-cruiser": "^15.3.0",
-        "element-book": "^10.1.6",
-        "esbuild": "^0.19.6",
+        "cspell": "^8.1.3",
+        "dependency-cruiser": "^15.5.0",
+        "element-book": "^10.1.9",
+        "element-vir": "file:./",
+        "esbuild": "^0.19.9",
         "istanbul-smart-text-reporter": "^1.1.3",
         "markdown-code-example-inserter": "^0.3.3",
         "mocha-spec-reporter-with-file-names": "^0.0.3",
         "npm-check-updates": "~16.12.3",
         "nyc": "^15.1.0",
-        "prettier": "^3.1.0",
+        "prettier": "^3.1.1",
         "prettier-plugin-interpolated-html-tags": "^1.0.3",
         "prettier-plugin-jsdoc": "^1.1.1",
         "prettier-plugin-multiline-arrays": "^3.0.1",
         "prettier-plugin-organize-imports": "^3.2.4",
-        "prettier-plugin-packagejson": "^2.4.6",
+        "prettier-plugin-packagejson": "^2.4.7",
         "prettier-plugin-sort-json": "^3.1.0",
-        "prettier-plugin-toml": "^1.0.0",
-        "ts-node": "^10.9.1",
-        "type-fest": "^4.8.1",
-        "typedoc": "^0.25.3",
+        "prettier-plugin-toml": "^2.0.1",
+        "ts-node": "^10.9.2",
+        "type-fest": "^4.8.3",
+        "typedoc": "^0.25.4",
         "typescript": "~5.2.2",
-        "virmator": "^11.1.3",
+        "vira": "^2.5.4",
+        "virmator": "^11.1.4",
         "vite": "^4.5.0",
-        "vite-tsconfig-paths": "^4.2.1"
+        "vite-tsconfig-paths": "^4.2.2"
     },
     "overrides": {
-        "lit": "^2.8.0",
-        "@open-wc/scoped-elements": "2.2.3",
-        "@open-wc/testing-helpers": "2.3.0"
+        "lit": "^3.1.0",
+        "element-vir": "*"
     }
 }

package/dist/declarative-element/properties/observable-property/create-observable-property.d.ts

@@ -1,43 +0,0 @@
-import { referenceEqualityCheck } from '../../../util/equality';
-import { ObservableProperty } from './observable-property';
-export type ObservablePropertyWithSetter<ValueType> = ObservableProperty<ValueType> & {
-    setValue(newValue: ValueType): void;
-};
-/**
- * Easy and quick way to create an ObservableProperty. Includes a setValue method with equality
- * checking for easily emitting changes.
- */
-export declare function createObservablePropertyWithSetter<ValueType>(initValue: ValueType, equalityCallback?: typeof referenceEqualityCheck): ObservablePropertyWithSetter<ValueType>;
-export type UpdaterCallback<ValueType, UpdateInputType> = Exclude<UpdateInputType, undefined> extends never ? () => ValueType : (inputs: UpdateInputType) => ValueType;
-export type ObservablePropertyWithUpdaterCallback<ValueType, UpdateInputType> = ObservableProperty<ValueType | Awaited<ValueType>> & {
-    triggerUpdate: UpdaterCallback<ValueType, UpdateInputType>;
-    /**
-     * The last value that was resolved. This will be undefined if there has never, so far, been a
-     * resolved value.
-     */
-    latestResolvedValue: ValueType extends Promise<any> ? Awaited<ValueType> | undefined : ValueType;
-};
-export type ObservablePropertyWithUpdaterSetup<ValueType, UpdateInputType> = {
-    initInput: UpdateInputType;
-    updateCallback: UpdaterCallback<ValueType, UpdateInputType>;
-    equalityCallback?: typeof referenceEqualityCheck | undefined;
-};
-export declare function createObservablePropertyWithUpdater<ValueType, UpdateInputType = undefined>(setup: ObservablePropertyWithUpdaterSetup<ValueType, UpdateInputType>): ObservablePropertyWithUpdaterCallback<ValueType, UpdateInputType>;
-export type ObservablePropertyWithIntervalSetup<ValueType, UpdateInputType> = ObservablePropertyWithUpdaterSetup<ValueType, UpdateInputType> & {
-    /** Interval duration in Milliseconds. */
-    intervalMs: number;
-};
-export type ObservablePropertyWithInterval<ValueType, UpdateInputType> = Omit<ObservablePropertyWithUpdaterCallback<ValueType, UpdateInputType>, 'triggerUpdate'> & {
-    forceUpdate: UpdaterCallback<ValueType, UpdateInputType>;
-    /**
-     * Pauses the update interval, if it isn't already paused. Use .resumeInterval() to start the
-     * interval again. Under the hood, this actually clears the interval entirely.
-     */
-    pauseInterval(): void;
-    /**
-     * Resumes the update interval if it was paused. Under the hood, this creates a new interval
-     * entirely, as .pauseInterval() actually clears it.
-     */
-    resumeInterval(): void;
-};
-export declare function createObservablePropertyWithIntervalUpdate<ValueType, UpdateInputType = undefined>(setup: ObservablePropertyWithIntervalSetup<ValueType, UpdateInputType>): ObservablePropertyWithInterval<ValueType, UpdateInputType>;

package/dist/declarative-element/properties/observable-property/create-observable-property.js

@@ -1,98 +0,0 @@
-import { referenceEqualityCheck } from '../../../util/equality';
-/**
- * Easy and quick way to create an ObservableProperty. Includes a setValue method with equality
- * checking for easily emitting changes.
- */
-export function createObservablePropertyWithSetter(initValue, equalityCallback = referenceEqualityCheck) {
-    const listeners = new Set();
-    function fireListeners() {
-        listeners.forEach((listener) => listener(observableProperty.value));
-    }
-    const observableProperty = {
-        value: initValue,
-        setValue(newValue) {
-            if (!equalityCallback(observableProperty.value, newValue)) {
-                observableProperty.value = newValue;
-                fireListeners();
-            }
-        },
-        addListener(listener) {
-            const shouldAddListener = !listeners.has(listener);
-            if (shouldAddListener) {
-                listeners.add(listener);
-            }
-            return shouldAddListener;
-        },
-        removeListener(listener) {
-            return listeners.delete(listener);
-        },
-    };
-    return observableProperty;
-}
-export function createObservablePropertyWithUpdater(setup) {
-    const areEqual = setup.equalityCallback ?? referenceEqualityCheck;
-    const innerSimpleObservableProperty = createObservablePropertyWithSetter(undefined, areEqual);
-    function updateValue(inputs) {
-        const newValue = setup.updateCallback(inputs);
-        if (newValue instanceof Promise) {
-            const wrappedPromise = new Promise(async (resolve, reject) => {
-                try {
-                    const resolvedValue = await newValue;
-                    observableWithUpdater.latestResolvedValue =
-                        resolvedValue;
-                    innerSimpleObservableProperty.setValue(resolvedValue);
-                    resolve(resolvedValue);
-                }
-                catch (error) {
-                    reject(error);
-                }
-            });
-            /** Set the promise so consumers know it's loading. */
-            innerSimpleObservableProperty.setValue(wrappedPromise);
-            return wrappedPromise;
-        }
-        else {
-            innerSimpleObservableProperty.setValue(newValue);
-            observableWithUpdater.latestResolvedValue =
-                newValue;
-            return newValue;
-        }
-    }
-    const observableWithUpdater = Object.assign(innerSimpleObservableProperty, {
-        triggerUpdate: updateValue,
-        latestResolvedValue: undefined,
-    });
-    updateValue(setup.initInput);
-    return observableWithUpdater;
-}
-export function createObservablePropertyWithIntervalUpdate(setup) {
-    let latestInputs = setup.initInput;
-    const baseObservableProperty = createObservablePropertyWithUpdater(setup);
-    let latestIntervalId = undefined;
-    function updateValue(inputs) {
-        if (inputs) {
-            latestInputs = inputs;
-        }
-        return baseObservableProperty.triggerUpdate(latestInputs);
-    }
-    const shouldRunInterval = !!setup.intervalMs && setup.intervalMs !== Infinity;
-    function resumeInterval() {
-        if (shouldRunInterval && latestIntervalId == undefined) {
-            latestIntervalId = window.setInterval(() => {
-                updateValue();
-            }, setup.intervalMs);
-        }
-    }
-    resumeInterval();
-    const observablePropertyWithInterval = Object.assign(baseObservableProperty, {
-        forceUpdate: updateValue,
-        pauseInterval() {
-            if (latestIntervalId != undefined) {
-                window.clearInterval(latestIntervalId);
-                latestIntervalId = undefined;
-            }
-        },
-        resumeInterval,
-    });
-    return observablePropertyWithInterval;
-}

package/dist/declarative-element/properties/observable-property/observable-property.d.ts

@@ -1,12 +0,0 @@
-import { PropertyInitMapBase } from '../element-properties';
-export type ObservablePropertyListener<T> = (value: T) => void;
-export type ObservablePropertyListenerMap<OriginalPropertyMap extends PropertyInitMapBase> = Partial<Record<keyof OriginalPropertyMap, ObservablePropertyListener<any> | undefined>>;
-export type ObservableProperty<ValueType> = {
-    /** Add the given listener. */
-    addListener(listener: ObservablePropertyListener<ValueType>): boolean;
-    /** Remove the given listener by reference. */
-    removeListener(listener: ObservablePropertyListener<ValueType>): boolean;
-    value: ValueType;
-};
-export declare const basicObservablePropertyShape: import("object-shape-tester").ShapeDefinition<ObservableProperty<any>, false>;
-export declare function isObservableProperty<ValueType = unknown>(input: unknown): input is ObservableProperty<ValueType>;

package/dist/declarative-element/properties/observable-property/observable-property.js

@@ -1,13 +0,0 @@
-import { defineShape, isValidShape, unknownShape } from 'object-shape-tester';
-export const basicObservablePropertyShape = defineShape({
-    addListener() {
-        return false;
-    },
-    removeListener() {
-        return false;
-    },
-    value: unknownShape(),
-});
-export function isObservableProperty(input) {
-    return isValidShape(input, basicObservablePropertyShape, { allowExtraKeys: true });
-}