element-vir 26.12.0 → 26.12.1

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

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

package/src/declarative-element/render-callback.ts

@@ -1,196 +0,0 @@
-import {getObjectTypedKeys, type SetRequiredAndNotNull} from '@augment-vir/common';
-import {type HtmlInterpolation} from '../template-transforms/vir-html/html-interpolation.js';
-import {type TypedEvent} from '../typed-event/typed-event.js';
-import {type CustomElementTagName} from './custom-tag-name.js';
-import {type DeclarativeElement, type DeclarativeElementHost} from './declarative-element.js';
-import {type CssVars} from './properties/css-vars.js';
-import {
-    type EventDescriptorMap,
-    type EventInitMapEventDetailExtractor,
-    type EventsInitMap,
-} from './properties/element-events.js';
-import {type PropertyInitMapBase} from './properties/element-properties.js';
-import {type BaseStringName, type StringNameMap} from './properties/string-names.js';
-
-/**
- * Type for the `render` element definition method.
- *
- * @category Internal
- */
-export type RenderCallback<
-    TagName extends CustomElementTagName = any,
-    Inputs extends PropertyInitMapBase = any,
-    State extends PropertyInitMapBase = any,
-    EventsInit extends EventsInitMap = any,
-    HostClassKeys extends BaseStringName<TagName> = any,
-    CssVarKeys extends BaseStringName<TagName> = any,
-    SlotNames extends ReadonlyArray<string> = any,
-    TestIds extends ReadonlyArray<string> = any,
-> = (
-    params: RenderParams<
-        TagName,
-        Inputs,
-        State,
-        EventsInit,
-        HostClassKeys,
-        CssVarKeys,
-        SlotNames,
-        TestIds
-    >,
-) => HtmlInterpolation;
-
-/**
- * Type for the `init` and `cleanup` element definition methods.
- *
- * @category Internal
- */
-export type InitCallback<
-    TagName extends CustomElementTagName,
-    Inputs extends PropertyInitMapBase,
-    State extends PropertyInitMapBase,
-    EventsInit extends EventsInitMap,
-    HostClassKeys extends BaseStringName<TagName>,
-    CssVarKeys extends BaseStringName<TagName>,
-    SlotNames extends ReadonlyArray<string>,
-    TestIds extends ReadonlyArray<string>,
-> = (
-    params: RenderParams<
-        TagName,
-        Inputs,
-        State,
-        EventsInit,
-        HostClassKeys,
-        CssVarKeys,
-        SlotNames,
-        TestIds
-    >,
-) => undefined | void;
-
-/**
- * Type for the `updateState` render parameter.
- *
- * @category Internal
- */
-export type UpdateStateCallback<State extends PropertyInitMapBase> = (
-    newState: Partial<State>,
-) => void;
-
-/**
- * The full parameters object passed to `render`, `init`, and `cleanup` element definition methods.
- *
- * @category Internal
- */
-export type RenderParams<
-    TagName extends CustomElementTagName,
-    Inputs extends PropertyInitMapBase,
-    State extends PropertyInitMapBase,
-    EventsInit extends EventsInitMap,
-    HostClassKeys extends BaseStringName<TagName>,
-    CssVarKeys extends BaseStringName<TagName>,
-    SlotNames extends ReadonlyArray<string>,
-    TestIds extends ReadonlyArray<string>,
-> = {
-    state: Readonly<State>;
-    cssVars: Readonly<CssVars<TagName, CssVarKeys>>;
-    updateState: UpdateStateCallback<State>;
-    events: EventDescriptorMap<TagName, EventsInit>;
-    host: DeclarativeElementHost<
-        TagName,
-        Inputs,
-        State,
-        EventsInit,
-        HostClassKeys,
-        CssVarKeys,
-        SlotNames,
-        TestIds
-    >;
-    slotNames: Readonly<StringNameMap<TagName, 'slot', SlotNames>>;
-    testIds: Readonly<StringNameMap<TagName, 'test-id', TestIds>>;
-    /** Dispatch an event from the current element. */
-    dispatch: <EventTypeName extends keyof EventsInit>(
-        event:
-            | TypedEvent<
-                  EventTypeName extends string ? EventTypeName : never,
-                  EventInitMapEventDetailExtractor<EventTypeName, EventsInit>
-              >
-            | Event,
-    ) => boolean;
-    inputs: Readonly<Inputs>;
-};
-
-/**
- * This is used to create the parameters passed to the `render`, `init`, and `cleanup` element
- * definition methods whenever they are called.
- *
- * @category Internal
- */
-export function createRenderParams<
-    TagName extends CustomElementTagName,
-    Inputs extends PropertyInitMapBase,
-    State extends PropertyInitMapBase,
-    EventsInit extends EventsInitMap,
-    HostClassKeys extends BaseStringName<TagName>,
-    CssVarKeys extends BaseStringName<TagName>,
-    SlotNames extends ReadonlyArray<string>,
-    TestIds extends ReadonlyArray<string>,
->({
-    element,
-    eventsMap,
-    cssVars,
-    slotNamesMap,
-    testIdsMap,
-}: {
-    element: DeclarativeElement<
-        TagName,
-        Inputs,
-        State,
-        EventsInit,
-        HostClassKeys,
-        CssVarKeys,
-        SlotNames,
-        TestIds
-    >;
-    eventsMap: EventDescriptorMap<TagName, EventsInit>;
-    cssVars: Readonly<CssVars<TagName, CssVarKeys>>;
-    slotNamesMap: Readonly<StringNameMap<TagName, 'slot', SlotNames>>;
-    testIdsMap: Readonly<StringNameMap<TagName, 'test-id', TestIds>>;
-}): RenderParams<
-    TagName,
-    Inputs,
-    State,
-    EventsInit,
-    HostClassKeys,
-    CssVarKeys,
-    SlotNames,
-    TestIds
-> {
-    function updateState(newStatePartial: Parameters<UpdateStateCallback<State>>[0]) {
-        getObjectTypedKeys(newStatePartial).forEach((stateKey) => {
-            const newValue = newStatePartial[stateKey] as State[typeof stateKey];
-
-            element.instanceState[stateKey] = newValue;
-        });
-    }
-
-    const renderParams: RenderParams<
-        TagName,
-        Inputs,
-        State,
-        EventsInit,
-        HostClassKeys,
-        CssVarKeys,
-        SlotNames,
-        TestIds
-    > = {
-        cssVars,
-        slotNames: slotNamesMap,
-        testIds: testIdsMap,
-        dispatch: (event) => element.dispatchEvent(event),
-        events: eventsMap,
-        host: element as SetRequiredAndNotNull<typeof element, 'shadowRoot'>,
-        inputs: element.instanceInputs,
-        state: element.instanceState,
-        updateState,
-    };
-    return renderParams;
-}

package/src/declarative-element/wrap-define-element.ts

@@ -1,127 +0,0 @@
-/* eslint-disable @typescript-eslint/no-empty-object-type */
-
-import {type PartialWithNullable} from '@augment-vir/common';
-import {type CustomElementTagName} from './custom-tag-name.js';
-import {type DeclarativeElementInit} from './declarative-element-init.js';
-import {type DeclarativeElementInputErrorParams, defineElement} from './define-element.js';
-import {type EventsInitMap} from './properties/element-events.js';
-import {type PropertyInitMapBase} from './properties/element-properties.js';
-import {type BaseStringName} from './properties/string-names.js';
-
-/**
- * Options for {@link wrapDefineElement}.
- *
- * @category Internal
- */
-export type WrapDefineElementOptions<
-    TagNameRequirement extends CustomElementTagName = CustomElementTagName,
-    InputsRequirement extends PropertyInitMapBase = {},
-    StateRequirement extends PropertyInitMapBase = {},
-    EventsInitRequirement extends EventsInitMap = {},
-> = PartialWithNullable<{
-    /**
-     * An optional callback which asserts that an element definition init object given to the
-     * wrapped element definition functions is valid.
-     */
-    assertInputs: (
-        inputInit: DeclarativeElementInit<
-            TagNameRequirement,
-            InputsRequirement,
-            StateRequirement,
-            EventsInitRequirement,
-            BaseStringName<TagNameRequirement>,
-            BaseStringName<TagNameRequirement>,
-            ReadonlyArray<string>,
-            ReadonlyArray<string>
-        >,
-    ) => void;
-    /**
-     * An optional callback which transforms a element definition init object given to the wrapped
-     * element definition.
-     */
-    transformInputs: (
-        inputInit: DeclarativeElementInit<
-            TagNameRequirement,
-            InputsRequirement,
-            StateRequirement,
-            EventsInitRequirement,
-            BaseStringName<TagNameRequirement>,
-            BaseStringName<TagNameRequirement>,
-            ReadonlyArray<string>,
-            ReadonlyArray<string>
-        >,
-    ) => DeclarativeElementInit<
-        TagNameRequirement,
-        InputsRequirement,
-        StateRequirement,
-        EventsInitRequirement,
-        BaseStringName<TagNameRequirement>,
-        BaseStringName<TagNameRequirement>,
-        ReadonlyArray<string>,
-        ReadonlyArray<string>
-    >;
-}>;
-
-/**
- * Wraps {@link defineElement} in a superset of requirements. For example:
- *
- * - You could create element definition functions that require all elements to start with a common
- *   prefix, like `vir-`.
- * - You could create element definition functions that require all elements to have _at least_ a
- *   specified set of input properties.
- * - Etc.
- *
- * @category Element Definition
- */
-export function wrapDefineElement<
-    TagNameRequirement extends CustomElementTagName = CustomElementTagName,
-    InputsRequirement extends PropertyInitMapBase = {},
-    StateRequirement extends PropertyInitMapBase = {},
-    EventsInitRequirement extends EventsInitMap = {},
->(options?: WrapDefineElementOptions | undefined) {
-    const {assertInputs, transformInputs}: WrapDefineElementOptions = {
-        assertInputs: options?.assertInputs ?? (() => {}),
-        transformInputs: options?.transformInputs ?? ((inputs: any) => inputs),
-    };
-
-    return <Inputs extends InputsRequirement>(
-        ...errorParams: DeclarativeElementInputErrorParams<Inputs>
-    ) => {
-        return <
-            const TagName extends TagNameRequirement,
-            State extends StateRequirement,
-            EventsInit extends EventsInitRequirement,
-            const HostClassKeys extends BaseStringName<TagName> = `${TagName}-`,
-            const CssVarKeys extends BaseStringName<TagName> = `${TagName}-`,
-            const SlotNames extends ReadonlyArray<string> = Readonly<[]>,
-            const TestIds extends ReadonlyArray<string> = Readonly<[]>,
-        >(
-            inputs: DeclarativeElementInit<
-                TagName,
-                Inputs,
-                State,
-                EventsInit,
-                HostClassKeys,
-                CssVarKeys,
-                SlotNames,
-                TestIds
-            >,
-        ) => {
-            assertInputs(inputs as DeclarativeElementInit<any, any, any, any, any, any, any, any>);
-            return defineElement<Inputs>(...errorParams)(
-                transformInputs(
-                    inputs as DeclarativeElementInit<any, any, any, any, any, any, any, any>,
-                ) as unknown as DeclarativeElementInit<
-                    TagName,
-                    Inputs,
-                    State,
-                    EventsInit,
-                    HostClassKeys,
-                    CssVarKeys,
-                    SlotNames,
-                    TestIds
-                >,
-            );
-        };
-    };
-}

package/src/readme-examples/my-custom-action.event.ts

@@ -1,3 +0,0 @@
-import {defineTypedEvent} from '../index.js';
-
-export const MyCustomActionEvent = defineTypedEvent<number>()('my-custom-action');

package/src/readme-examples/my-with-assignment.element.ts

@@ -1,16 +0,0 @@
-import {defineElement} from 'element-vir';
-import {html} from '../index.js';
-import {MyWithInputs} from './my-with-inputs.element.js';
-
-export const MyWithAssignment = defineElement()({
-    tagName: 'my-with-assignment',
-    render() {
-        return html`
-            <h1>My App</h1>
-            <${MyWithInputs.assign({
-                email: 'user@example.com',
-                username: 'user',
-            })}></${MyWithInputs}>
-        `;
-    },
-});

package/src/readme-examples/my-with-custom-events.element.ts

@@ -1,23 +0,0 @@
-import {randomInteger} from '@augment-vir/common';
-import {defineElement} from 'element-vir';
-import {html, listen} from '../index.js';
-import {MyCustomActionEvent} from './my-custom-action.event.js';
-
-export const MyWithCustomEvents = defineElement()({
-    tagName: 'my-with-custom-events',
-    render({dispatch}) {
-        return html`
-            <div
-                ${listen(MyCustomActionEvent, (event) => {
-                    console.info(`Got a number! ${event.detail}`);
-                })}
-            >
-                <div
-                    ${listen('click', () => {
-                        dispatch(new MyCustomActionEvent(randomInteger({min: 0, max: 1_000_000})));
-                    })}
-                ></div>
-            </div>
-        `;
-    },
-});

package/src/readme-examples/my-with-events.element.ts

@@ -1,23 +0,0 @@
-import {randomInteger} from '@augment-vir/common';
-import {defineElement} from 'element-vir';
-import {defineElementEvent, html, listen} from '../index.js';
-
-export const MyWithEvents = defineElement()({
-    tagName: 'my-with-events',
-    events: {
-        logoutClick: defineElementEvent<void>(),
-        randomNumber: defineElementEvent<number>(),
-    },
-    render({dispatch, events}) {
-        return html`
-            <button ${listen('click', () => dispatch(new events.logoutClick()))}>log out</button>
-            <button
-                ${listen('click', () =>
-                    dispatch(new events.randomNumber(randomInteger({min: 0, max: 1_000_000}))),
-                )}
-            >
-                generate random number
-            </button>
-        `;
-    },
-});

package/src/readme-examples/my-with-inputs.element.ts

@@ -1,13 +0,0 @@
-import {defineElement, html} from '../index.js';
-
-export const MyWithInputs = defineElement<{
-    username: string;
-    email: string;
-}>()({
-    tagName: 'my-with-inputs',
-    render({inputs}) {
-        return html`
-            <span>Hello there ${inputs.username}!</span>
-        `;
-    },
-});

package/src/readme-examples/my-with-on-resize.element.ts

@@ -1,19 +0,0 @@
-import {defineElement} from 'element-vir';
-import {html, onResize} from '../index.js';
-
-export const MyWithOnResize = defineElement()({
-    tagName: 'my-with-on-resize',
-    render() {
-        return html`
-            <span
-                ${onResize((entry) => {
-                    // this will track resizing of this span
-                    // the entry parameter contains target and contentRect properties
-                    console.info(entry);
-                })}
-            >
-                Hello there!
-            </span>
-        `;
-    },
-});

package/src/readme-examples/my-with-render-if.element.ts

@@ -1,15 +0,0 @@
-import {defineElement, html, renderIf} from '../index.js';
-
-export const MyWithRenderIf = defineElement<{shouldRender: boolean}>()({
-    tagName: 'my-with-render-if',
-    render({inputs}) {
-        return html`
-            ${renderIf(
-                inputs.shouldRender,
-                html`
-                    I'm conditionally rendered!
-                `,
-            )}
-        `;
-    },
-});

package/src/readme-examples/require-declarative-element.ts

@@ -1,3 +0,0 @@
-import {requireAllCustomElementsToBeDeclarativeElements} from '../index.js';
-
-requireAllCustomElementsToBeDeclarativeElements();