element-vir 26.11.2 → 26.12.0

package/dist/declarative-element/directives/on-intersect.directive.d.ts

@@ -1,64 +0,0 @@
-import { type MaybePromise } from '@augment-vir/common';
-import { type PartInfo } from '../../lit-exports/all-lit-exports.js';
-/**
- * Callback called by the {@link onIntersect} directive.
- *
- * @category Internal
- */
-export type OnIntersectCallback = (params: {
-    entry: IntersectionObserverEntry;
-    allEntries: IntersectionObserverEntry[];
-    observer: IntersectionObserver;
-    element: Element;
-}) => MaybePromise<void>;
-/**
- * Options used for the {@link onIntersect} directive.
- *
- * @category Internal
- */
-export type OnIntersectOptions = IntersectionObserverInit;
-/**
- * A directive that fires its listener any time the element's configured "intersection" is crossed.
- * This is commonly use for detecting when an element has scrolled into view. This uses the
- * [built-in `IntersectionObserver`
- * API](https://developer.mozilla.org/docs/Web/API/IntersectionObserver/IntersectionObserver), so it
- * is very efficient.
- *
- * @category Directives
- * @example
- *
- * ```ts
- * import {html, defineElement, onIntersect} from 'element-vir';
- *
- * const MyElement = defineElement()({
- *     tagName: 'my-element',
- *     render() {
- *         return html`
- *             <div
- *                 ${onIntersect({threshold: 1}, ({element, entry}) => {
- *                     if (entry.isIntersecting) {
- *                         console.log('is intersecting!');
- *                     } else {
- *                         console.log('is not intersecting');
- *                     }
- *                 })}
- *             >
- *                 Some div
- *             </div>
- *         `;
- *     },
- * });
- * ```
- */
-export declare const onIntersect: (options: IntersectionObserverInit, callback: OnIntersectCallback) => import("lit-html/directive.js").DirectiveResult<{
-    new (partInfo: PartInfo): {
-        element: Element | undefined;
-        options: OnIntersectOptions | undefined;
-        intersectionObserver: undefined | IntersectionObserver;
-        callback: OnIntersectCallback | undefined;
-        fireCallback(entries: IntersectionObserverEntry[], observer: IntersectionObserver): void;
-        update(partInfo: PartInfo, [options, callback,]: [OnIntersectOptions, OnIntersectCallback]): undefined;
-        render(options: OnIntersectOptions, callback: OnIntersectCallback): undefined;
-        get _$isConnected(): boolean;
-    };
-}>;

package/dist/declarative-element/directives/on-intersect.directive.js

@@ -1,89 +0,0 @@
-import { assert, assertWrap, check } from '@augment-vir/assert';
-import { directive, Directive } from '../../lit-exports/all-lit-exports.js';
-import { assertIsElementPartInfo } from './directive-helpers.js';
-const directiveName = 'onIntersect';
-/**
- * A directive that fires its listener any time the element's configured "intersection" is crossed.
- * This is commonly use for detecting when an element has scrolled into view. This uses the
- * [built-in `IntersectionObserver`
- * API](https://developer.mozilla.org/docs/Web/API/IntersectionObserver/IntersectionObserver), so it
- * is very efficient.
- *
- * @category Directives
- * @example
- *
- * ```ts
- * import {html, defineElement, onIntersect} from 'element-vir';
- *
- * const MyElement = defineElement()({
- *     tagName: 'my-element',
- *     render() {
- *         return html`
- *             <div
- *                 ${onIntersect({threshold: 1}, ({element, entry}) => {
- *                     if (entry.isIntersecting) {
- *                         console.log('is intersecting!');
- *                     } else {
- *                         console.log('is not intersecting');
- *                     }
- *                 })}
- *             >
- *                 Some div
- *             </div>
- *         `;
- *     },
- * });
- * ```
- */
-export const onIntersect = directive(class extends Directive {
-    element;
-    options;
-    intersectionObserver;
-    callback;
-    constructor(partInfo) {
-        super(partInfo);
-        assertIsElementPartInfo(partInfo, directiveName);
-    }
-    fireCallback(entries, observer) {
-        assert.isLengthAtLeast(entries, 1);
-        void this.callback?.({
-            element: assertWrap.isDefined(this.element),
-            allEntries: entries,
-            observer,
-            entry: entries[0],
-        });
-    }
-    update(partInfo, [options, callback,]) {
-        assertIsElementPartInfo(partInfo, directiveName);
-        this.callback = callback;
-        let needsObserving = false;
-        const newOptions = options;
-        const oldOptions = this.options;
-        if (!this.intersectionObserver ||
-            !oldOptions ||
-            !check.entriesEqual(newOptions, oldOptions)) {
-            this.options = options;
-            this.intersectionObserver?.disconnect();
-            this.intersectionObserver = new IntersectionObserver((entries, observer) => this.fireCallback(entries, observer), options);
-            needsObserving = true;
-        }
-        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.intersectionObserver.unobserve(oldElement);
-            }
-            needsObserving = true;
-        }
-        if (needsObserving) {
-            this.intersectionObserver.observe(newElement);
-        }
-        return this.render(options, callback);
-    }
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    render(options, callback) {
-        return undefined;
-    }
-});

package/dist/declarative-element/directives/on-resize.directive.d.ts

@@ -1,74 +0,0 @@
-import { type MaybePromise } from '@augment-vir/common';
-import { type PartInfo } from '../../lit-exports/all-lit-exports.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>;
-/**
- * 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 declare const onResize: (callback: OnResizeCallback) => import("lit-html/directive.js").DirectiveResult<{
-    new (partInfo: PartInfo): {
-        element: Element | undefined;
-        readonly resizeObserver: ResizeObserver;
-        callback: OnResizeCallback | undefined;
-        update(partInfo: PartInfo, [callback]: [OnResizeCallback]): undefined;
-        render(callback: OnResizeCallback): undefined;
-        get _$isConnected(): boolean;
-    };
-}>;
-/**
- * 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 declare function attachOnResize(element: Element, callback: OnResizeCallback): {
-    resizeObserver: ResizeObserver;
-    element: Element;
-};

package/dist/declarative-element/directives/on-resize.directive.js

@@ -1,106 +0,0 @@
-import { directive, Directive } from '../../lit-exports/all-lit-exports.js';
-import { assertIsElementPartInfo } from './directive-helpers.js';
-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 {
-    element;
-    resizeObserver = new ResizeObserver((entries) => {
-        if (this.element && this.callback) {
-            handleOnResizeCallback(this.element, this.callback, entries);
-        }
-    });
-    callback;
-    constructor(partInfo) {
-        super(partInfo);
-        assertIsElementPartInfo(partInfo, directiveName);
-    }
-    update(partInfo, [callback]) {
-        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
-    render(callback) {
-        return undefined;
-    }
-});
-function handleOnResizeCallback(element, callback, entries) {
-    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, callback) {
-    const resizeObserver = new ResizeObserver((entries) => {
-        handleOnResizeCallback(element, callback, entries);
-    });
-    resizeObserver.observe(element);
-    return {
-        resizeObserver,
-        element,
-    };
-}

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

@@ -1,45 +0,0 @@
-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 declare 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 declare 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 declare 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 declare function renderAsync<T, FallbackResult>(asyncProp: Pick<AsyncProp<T, any>, 'value'>, fallback: FallbackResult, resolutionRender?: undefined, errorRender?: undefined): FallbackResult | Awaited<T> | string;

package/dist/declarative-element/directives/render-async.directive.js

@@ -1,33 +0,0 @@
-import { check } from '@augment-vir/assert';
-import { extractErrorMessage } from '@augment-vir/common';
-/**
- * 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(asyncProp, 
-/** This value will be rendered if the async prop has not settled yet. */
-fallback, resolutionRender, errorRender) {
-    const asyncPropValue = asyncProp.value;
-    if (asyncPropValue instanceof Error) {
-        const errorResult = errorRender
-            ? errorRender(asyncPropValue)
-            : extractErrorMessage(asyncPropValue);
-        return errorResult;
-    }
-    else if (check.isPromiseLike(asyncPropValue)) {
-        const fallbackResult = fallback;
-        return fallbackResult;
-    }
-    else {
-        const resolutionResult = resolutionRender
-            ? resolutionRender(asyncPropValue)
-            : asyncPropValue;
-        return resolutionResult;
-    }
-}

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

@@ -1,32 +0,0 @@
-/**
- * A directive that, given a condition, chooses between two inputs: `ifTrue` and `ifFalse`. If
- * `ifFalse` is omitted (which is allowed), the false case defaults to `undefined`, which won't get
- * rendered at all inside of an HTML template.
- *
- * @category Directives
- * @example
- *
- * ```ts
- * import {html, defineElement, renderIf} from 'element-vir';
- *
- * const MyElement = defineElement()({
- *     tagName: 'my-element',
- *     render() {
- *         return html`
- *             <div>
- *                 ${renderIf(
- *                     Math.random() > 0.5,
- *                     html`
- *                         True!
- *                     `,
- *                     html`
- *                         False!
- *                     `,
- *                 )}
- *             </div>
- *         `;
- *     },
- * });
- * ```
- */
-export declare function renderIf<TrueCondition = unknown, FalseCondition = undefined>(condition: boolean, ifTrue: TrueCondition, ifFalse?: FalseCondition): TrueCondition | FalseCondition;

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

@@ -1,52 +0,0 @@
-/**
- * Assigns the given id as a test id attribute to the attached element.
- *
- * @category Test
- * @example
- *
- * ```ts
- * import {html, defineElement, testId} from 'element-vir';
- *
- * const MyElement = defineElement()({
- *     tagName: 'my-element',
- *     render() {
- *         return html`
- *             <div ${testId('my-test')}>Some div</div>
- *         `;
- *     },
- * });
- * ```
- */
-export declare const testId: (this: void, attributeValue: string) => import("lit-html/directive.js").DirectiveResult<{
-    new (partInfo: import("lit-html/directive.js").PartInfo): {
-        readonly element: Element;
-        render(attributeValue: string): symbol;
-        get _$isConnected(): boolean;
-        update(_part: import("lit-html").Part, props: Array<unknown>): unknown;
-    };
-}>;
-/**
- * Construct an attribute selector for the given test id.
- *
- * @category Test
- * @example
- *
- * ```ts
- * import {html, selectTestId} from 'element-vir';
- * import {testWeb} from '@augment-vir/test';
- * import {assert} from '@augment-vir/assert';
- *
- * const instance = testWeb.render(html`
- *     <${MyElement}></${MyElement}>
- * `);
- * assert.instanceOf(instance, MyElement);
- * instance.shadowRoot.querySelector(selectTestId('my-test'));
- * ```
- */
-export declare const testIdSelector: (this: void, attributeValue: string) => string;
-/**
- * The test id attribute name.
- *
- * @category Test
- */
-export declare const testIdAttributeName: string;

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

@@ -1 +0,0 @@
-export declare function hasDeclarativeElementParent(input: Element): boolean;

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

@@ -1,17 +0,0 @@
-import { type DeclarativeElementDefinition } from './declarative-element.js';
-/**
- * Asserts that the given input is a declarative element definition.
- *
- * @category Util
- * @see
- * - {@link isDeclarativeElementDefinition}
- */
-export declare function assertDeclarativeElementDefinition(input: unknown, failMessage?: string | undefined): asserts input is DeclarativeElementDefinition;
-/**
- * Checks that the given input is a declarative element definition.
- *
- * @category Util
- * @see
- * - {@link assertDeclarativeElementDefinition}
- */
-export declare function isDeclarativeElementDefinition(input: unknown): input is DeclarativeElementDefinition;

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

@@ -1,15 +0,0 @@
-import { type DeclarativeElement } from './declarative-element.js';
-/**
- * Checks if the input is an instance of a DeclarativeElement, the super class of all custom
- * elements defined with element-vir.
- *
- * @category Util
- */
-export declare function isDeclarativeElement(input: unknown): input is DeclarativeElement;
-/**
- * Checks if the input is an instance of a DeclarativeElement, the super class of all custom
- * elements defined with element-vir.
- *
- * @category Util
- */
-export declare function assertIsDeclarativeElement(input: unknown): asserts input is DeclarativeElement;

package/dist/declarative-element/properties/assign-inputs.d.ts

@@ -1 +0,0 @@
-export declare function assignInputs(element: Element, inputs: object): void;

package/dist/declarative-element/properties/assign-inputs.js

@@ -1,25 +0,0 @@
-import { getObjectTypedKeys } from '@augment-vir/common';
-export function assignInputs(element, inputs) {
-    const instanceState = element.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[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[existingKey] =
-                    undefined;
-            }
-        });
-    }
-}

package/dist/declarative-element/properties/css-vars.d.ts

@@ -1,16 +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/dist/declarative-element/properties/css-vars.js

@@ -1 +0,0 @@
-export {};

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

@@ -1,65 +0,0 @@
-import { type DefinedTypedEvent, type DefineEvent, type TypedEvent } from '../../typed-event/typed-event.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 declare function defineElementEvent<EventDetailGeneric>(): DefineEvent<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 declare function createEventDescriptorMap<TagName extends CustomElementTagName, EventsInitGeneric extends EventsInitMap>(tagName: CustomElementTagName, eventsInit: EventsInitGeneric | undefined): EventDescriptorMap<TagName, EventsInitGeneric>;