element-vir 23.4.2 → 25.0.0

package/dist/declarative-element/directives/is-resolved.directive.d.ts

@@ -1,110 +0,0 @@
-import { AsyncProp, AsyncValue } from './async-prop.js';
-/**
- * Checks and type guards that the given async value is resolved, meaning that it is no longer a
- * promise. It may be an error though. This must be passed an {@link AsyncProp}'s `.value` property,
- * not the async prop itself.
- *
- * @category Async
- * @example
- *
- * ```ts
- * import {waitValue, extractErrorMessage} from '@augment-vir/common';
- * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
- *
- * const MyElement = defineElementNoInputs({
- *     tagName: 'my-element',
- *     stateInitStatic: {
- *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
- *     },
- *     render({state}) {
- *         if (isAsyncError(state.myProp.value)) {
- *             return html`
- *                 Error: ${extractErrorMessage(state.myProp.value)}
- *             `;
- *         } else if (isResolved(state.myProp.value)) {
- *             return html`
- *                 Done!
- *             `;
- *         } else {
- *             return html`
- *                 Still waiting...
- *             `;
- *         }
- *     },
- * });
- * ```
- */
-export declare function isResolved<Value extends AsyncValue<any>>(asyncValue: Value extends AsyncProp<any, any> ? 'Error: pass AsyncProp.value, not AsyncProp itself.' : Value): asyncValue is Exclude<typeof asyncValue, Promise<any>>;
-/**
- * Checks and type guards that the given async value is an error, meaning that the async prop's
- * promise was rejected. This must be passed an {@link AsyncProp}'s `.value` property, not the async
- * prop itself.
- *
- * @category Async
- * @example
- *
- * ```ts
- * import {waitValue, extractErrorMessage} from '@augment-vir/common';
- * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
- *
- * const MyElement = defineElementNoInputs({
- *     tagName: 'my-element',
- *     stateInitStatic: {
- *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
- *     },
- *     render({state}) {
- *         if (isAsyncError(state.myProp.value)) {
- *             return html`
- *                 Error: ${extractErrorMessage(state.myProp.value)}
- *             `;
- *         } else if (isResolved(state.myProp.value)) {
- *             return html`
- *                 Done!
- *             `;
- *         } else {
- *             return html`
- *                 Still waiting...
- *             `;
- *         }
- *     },
- * });
- * ```
- */
-export declare function isAsyncError<Value extends AsyncValue<any>>(asyncValue: Value extends AsyncProp<any, any> ? 'Error: pass AsyncProp.value, not AsyncProp itself.' : Value): asyncValue is Extract<typeof asyncValue, Error>;
-/**
- * Same as {@link isResolved} but instead of a returning a boolean, it returns either the resolved
- * value or `undefined`.
- *
- * @category Async
- * @example
- *
- * ```ts
- * import {waitValue, extractErrorMessage} from '@augment-vir/common';
- * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
- *
- * const MyElement = defineElementNoInputs({
- *     tagName: 'my-element',
- *     stateInitStatic: {
- *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
- *     },
- *     render({state}) {
- *         const resolvedValue = resolvedOrUndefined(state.myProp.value);
- *
- *         if (!resolvedValue) {
- *             return html`
- *                 Still waiting...
- *             `;
- *         } else if (isAsyncError(resolvedValue)) {
- *             return html`
- *                 Error: ${extractErrorMessage(state.myProp.value)}
- *             `;
- *         }
- *
- *         return html`
- *             Value: ${resolvedValue}
- *         `;
- *     },
- * });
- * ```
- */
-export declare function resolvedOrUndefined<Value extends AsyncValue<any>>(asyncValue: Value extends AsyncProp<any, any> ? 'Error: pass AsyncProp.value, not AsyncProp itself.' : Value): Exclude<typeof asyncValue, Promise<any>> | undefined;

package/dist/declarative-element/directives/is-resolved.directive.js

@@ -1,127 +0,0 @@
-import { AsyncProp } from './async-prop.js';
-/**
- * Checks and type guards that the given async value is resolved, meaning that it is no longer a
- * promise. It may be an error though. This must be passed an {@link AsyncProp}'s `.value` property,
- * not the async prop itself.
- *
- * @category Async
- * @example
- *
- * ```ts
- * import {waitValue, extractErrorMessage} from '@augment-vir/common';
- * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
- *
- * const MyElement = defineElementNoInputs({
- *     tagName: 'my-element',
- *     stateInitStatic: {
- *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
- *     },
- *     render({state}) {
- *         if (isAsyncError(state.myProp.value)) {
- *             return html`
- *                 Error: ${extractErrorMessage(state.myProp.value)}
- *             `;
- *         } else if (isResolved(state.myProp.value)) {
- *             return html`
- *                 Done!
- *             `;
- *         } else {
- *             return html`
- *                 Still waiting...
- *             `;
- *         }
- *     },
- * });
- * ```
- */
-export function isResolved(asyncValue) {
-    if (asyncValue instanceof AsyncProp) {
-        throw new TypeError('Pass AsyncProp.value, not AsyncProp itself.');
-    }
-    return !(asyncValue instanceof Promise);
-}
-/**
- * Checks and type guards that the given async value is an error, meaning that the async prop's
- * promise was rejected. This must be passed an {@link AsyncProp}'s `.value` property, not the async
- * prop itself.
- *
- * @category Async
- * @example
- *
- * ```ts
- * import {waitValue, extractErrorMessage} from '@augment-vir/common';
- * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
- *
- * const MyElement = defineElementNoInputs({
- *     tagName: 'my-element',
- *     stateInitStatic: {
- *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
- *     },
- *     render({state}) {
- *         if (isAsyncError(state.myProp.value)) {
- *             return html`
- *                 Error: ${extractErrorMessage(state.myProp.value)}
- *             `;
- *         } else if (isResolved(state.myProp.value)) {
- *             return html`
- *                 Done!
- *             `;
- *         } else {
- *             return html`
- *                 Still waiting...
- *             `;
- *         }
- *     },
- * });
- * ```
- */
-export function isAsyncError(asyncValue) {
-    if (asyncValue instanceof AsyncProp) {
-        throw new TypeError('Pass AsyncProp.value, not AsyncProp itself.');
-    }
-    return asyncValue instanceof Error;
-}
-/**
- * Same as {@link isResolved} but instead of a returning a boolean, it returns either the resolved
- * value or `undefined`.
- *
- * @category Async
- * @example
- *
- * ```ts
- * import {waitValue, extractErrorMessage} from '@augment-vir/common';
- * import {isResolved, html, defineElementNoInputs, asyncProp} from 'element-vir';
- *
- * const MyElement = defineElementNoInputs({
- *     tagName: 'my-element',
- *     stateInitStatic: {
- *         myProp: asyncProp({defaultValue: waitValue({seconds: 10}, 'value')}),
- *     },
- *     render({state}) {
- *         const resolvedValue = resolvedOrUndefined(state.myProp.value);
- *
- *         if (!resolvedValue) {
- *             return html`
- *                 Still waiting...
- *             `;
- *         } else if (isAsyncError(resolvedValue)) {
- *             return html`
- *                 Error: ${extractErrorMessage(state.myProp.value)}
- *             `;
- *         }
- *
- *         return html`
- *             Value: ${resolvedValue}
- *         `;
- *     },
- * });
- * ```
- */
-export function resolvedOrUndefined(asyncValue) {
-    if (isResolved(asyncValue)) {
-        return asyncValue;
-    }
-    else {
-        return undefined;
-    }
-}

package/dist/declarative-element/properties/element-vir-state-setup.d.ts

@@ -1,54 +0,0 @@
-import { PropertyInitMapBase } from './element-properties.js';
-/**
- * Use this key with a function value on any object set in `stateInitStatic` to, rather than using
- * the object itself, call the function during each element's initialization and use the output of
- * that function rather than the object itself.
- *
- * See `perInstance` for an example usage.
- *
- * @category Util
- */
-export declare const stateSetupKey: unique symbol;
-/**
- * The type for an object that uses {@link stateSetupKey}.
- *
- * @category Internal
- */
-export type ElementVirStateSetup<InnerValue> = {
-    [key in typeof stateSetupKey]: () => InnerValue;
-};
-/**
- * Check if the given value is a value {@link ElementVirStateSetup} implementation.
- *
- * @category Internal
- */
-export declare function isElementVirStateSetup<T = unknown>(input: unknown): input is ElementVirStateSetup<T>;
-/**
- * If the type parameter is an instance of {@link ElementVirStateSetup}, this unwraps that instance
- * to its type parameter. Otherwise, the original type parameter is used.
- *
- * @category Internal
- */
-export type UnwrapElementVirStateSetup<T> = T extends ElementVirStateSetup<infer U> ? U : T;
-/**
- * Allow wrapped state setup objects.
- *
- * @category Internal
- */
-export type MaybeElementVirStateSetup<T> = UnwrapElementVirStateSetup<T> | ElementVirStateSetup<UnwrapElementVirStateSetup<T>>;
-/**
- * Unwraps all {@link ElementVirStateSetup} properties in the given state init object type parameter.
- *
- * @category Internal
- */
-export type FlattenElementVirStateSetup<StateInit extends PropertyInitMapBase> = {
-    [Prop in keyof StateInit]: Extract<StateInit[Prop], ElementVirStateSetup<any>> extends never ? StateInit[Prop] : Extract<StateInit[Prop], ElementVirStateSetup<any>> extends ElementVirStateSetup<infer InnerValue> ? InnerValue | Exclude<StateInit[Prop], ElementVirStateSetup<any>> : StateInit[Prop];
-};
-/**
- * Allows setting stat with {@link ElementVirStateSetup} properties.
- *
- * @category Internal
- */
-export type AllowElementVirStateSetup<OriginalObject extends PropertyInitMapBase> = {
-    [Prop in keyof OriginalObject]: MaybeElementVirStateSetup<OriginalObject[Prop]>;
-};

package/dist/declarative-element/properties/element-vir-state-setup.js

@@ -1,22 +0,0 @@
-import { check } from '@augment-vir/assert';
-/**
- * Use this key with a function value on any object set in `stateInitStatic` to, rather than using
- * the object itself, call the function during each element's initialization and use the output of
- * that function rather than the object itself.
- *
- * See `perInstance` for an example usage.
- *
- * @category Util
- */
-export const stateSetupKey = Symbol('element-vir-state-setup');
-/**
- * Check if the given value is a value {@link ElementVirStateSetup} implementation.
- *
- * @category Internal
- */
-export function isElementVirStateSetup(input) {
-    if (!check.isObject(input)) {
-        return false;
-    }
-    return stateSetupKey in input && check.isFunction(input[stateSetupKey]);
-}

package/dist/declarative-element/properties/per-instance.d.ts

@@ -1,26 +0,0 @@
-/**
- * For use within `stateInitStatic`: use this as the value of a state prop to call the given
- * callback on each element's creation rather than creating a static state init value.
- *
- * @category Directives
- * @example
- *
- * ```ts
- * import {waitValue, extractErrorMessage} from '@augment-vir/common';
- * import {isResolved, html, defineElementNoInputs, perInstance} from 'element-vir';
- *
- * const MyElement = defineElementNoInputs({
- *     tagName: 'my-element',
- *     stateInitStatic: {
- *         // each instance of `MyElement` will have a different `randomValue`
- *         randomValue: perInstance(() => Math.random()),
- *     },
- *     render({state}) {
- *         return html`
- *             Value: ${state.randomValue}
- *         `;
- *     },
- * });
- * ```
- */
-export declare function perInstance<T>(creationCallback: () => T): T;

package/dist/declarative-element/properties/per-instance.js

@@ -1,32 +0,0 @@
-import { stateSetupKey } from './element-vir-state-setup.js';
-/**
- * For use within `stateInitStatic`: use this as the value of a state prop to call the given
- * callback on each element's creation rather than creating a static state init value.
- *
- * @category Directives
- * @example
- *
- * ```ts
- * import {waitValue, extractErrorMessage} from '@augment-vir/common';
- * import {isResolved, html, defineElementNoInputs, perInstance} from 'element-vir';
- *
- * const MyElement = defineElementNoInputs({
- *     tagName: 'my-element',
- *     stateInitStatic: {
- *         // each instance of `MyElement` will have a different `randomValue`
- *         randomValue: perInstance(() => Math.random()),
- *     },
- *     render({state}) {
- *         return html`
- *             Value: ${state.randomValue}
- *         `;
- *     },
- * });
- * ```
- */
-export function perInstance(creationCallback) {
-    const stateSetup = {
-        [stateSetupKey]: creationCallback,
-    };
-    return stateSetup;
-}