element-vir 26.11.2 → 26.12.0

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

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

@@ -0,0 +1,127 @@
+/* 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/{dist/index.d.ts → src/index.ts}

@@ -1,4 +1,5 @@
 export * from 'observavir';
+
 export * from './declarative-element/custom-tag-name.js';
 export * from './declarative-element/declarative-element-init.js';
 export * from './declarative-element/declarative-element.js';
@@ -39,4 +40,5 @@ export * from './template-transforms/vir-html/vir-html.js';
 export * from './typed-event/typed-event.js';
 export * from './util/increment.js';
 export * from './util/lit-template.js';
+export * from './util/map-async-value.js';
 export * from './util/type.js';

package/{dist/lit-exports/base-lit-exports.js → src/lit-exports/base-lit-exports.ts}

@@ -1,4 +1,13 @@
-export { LitElement, noChange, nothing, svg, unsafeCSS } from 'lit';
+export {LitElement, noChange, nothing, svg, unsafeCSS} from 'lit';
+export type {
+    CSSResult,
+    CSSResultGroup,
+    CompiledTemplate,
+    CompiledTemplateResult,
+    HTMLTemplateResult,
+    SVGTemplateResult,
+    TemplateResult,
+} from 'lit';
 export * from 'lit/async-directive.js';
 export * from 'lit/decorators.js';
 export * from 'lit/directive-helpers.js';

package/{dist/lit-exports/lit-repeat-fix.d.ts → src/lit-exports/lit-repeat-fix.ts}

@@ -1,9 +1,12 @@
-export type { KeyFn } from 'lit/directives/repeat.js';
-export type { RepeatDirective };
-import { type Directive, type PartInfo } from 'lit-html/directive.js';
-import { type KeyFn } from 'lit-html/directives/repeat.js';
-import { type ChildPart, type noChange } from 'lit-html/lit-html.js';
-import { type HtmlInterpolation } from '../template-transforms/vir-html/html-interpolation.js';
+export type {KeyFn} from 'lit/directives/repeat.js';
+export type {RepeatDirective};
+
+import {type Directive, type PartInfo} from 'lit-html/directive.js';
+import {type KeyFn} from 'lit-html/directives/repeat.js';
+import {type ChildPart, type noChange} from 'lit-html/lit-html.js';
+import {repeat as repeatImport} from 'lit/directives/repeat.js';
+import {type HtmlInterpolation} from '../template-transforms/vir-html/html-interpolation.js';
+
 /**
  * A modified class type for the built-in lit `repeat` directive which works for element-vir
  * declarative elements.
@@ -15,16 +18,32 @@ declare class RepeatDirective extends Directive {
     constructor(partInfo: PartInfo);
     private _getValuesAndKeys;
     /** Renders the repeated templates. */
-    render<T>(items: Iterable<T>, template: ItemTemplate<T>): Array<HtmlInterpolation>;
+    public render<T>(items: Iterable<T>, template: ItemTemplate<T>): Array<HtmlInterpolation>;
     /** Renders the repeated templates. */
-    render<T>(items: Iterable<T>, keyFn: KeyFn<T> | ItemTemplate<T>, template: ItemTemplate<T>): Array<HtmlInterpolation>;
+    public render<T>(
+        items: Iterable<T>,
+        keyFn: KeyFn<T> | ItemTemplate<T>,
+        template: ItemTemplate<T>,
+    ): Array<HtmlInterpolation>;
+
     /** Updates the repeated templates. */
-    update<T>(containerPart: ChildPart, [items, keyFnOrTemplate, template,]: [
-        Iterable<T>,
-        (KeyFn<T> | ItemTemplate<T>),
-        ItemTemplate<T>
-    ]): HtmlInterpolation[] | typeof noChange;
+    public update<T>(
+        containerPart: ChildPart,
+        [
+            items,
+            keyFnOrTemplate,
+            template,
+        ]: [
+            Iterable<T>,
+            (
+                | KeyFn<T>
+                | ItemTemplate<T>
+            ),
+            ItemTemplate<T>,
+        ],
+    ): HtmlInterpolation[] | typeof noChange;
 }
+
 /**
  * A modified `ItemTemplate` type for the built-in lit `repeat` directive which works for
  * element-vir declarative elements.
@@ -32,6 +51,7 @@ declare class RepeatDirective extends Directive {
  * @category Internal
  */
 export type ItemTemplate<T> = (item: T, index: number) => HtmlInterpolation;
+
 /**
  * A modified `RepeatDirectiveFn` type for the built-in lit `repeat` directive which works for
  * element-vir declarative elements.
@@ -39,10 +59,19 @@ export type ItemTemplate<T> = (item: T, index: number) => HtmlInterpolation;
  * @category Internal
  */
 export interface RepeatDirectiveFn {
-    <T>(items: Iterable<T>, keyFnOrTemplate: KeyFn<T> | ItemTemplate<T>, template?: ItemTemplate<T>): HtmlInterpolation[];
+    <T>(
+        items: Iterable<T>,
+        keyFnOrTemplate: KeyFn<T> | ItemTemplate<T>,
+        template?: ItemTemplate<T>,
+    ): HtmlInterpolation[];
     <T>(items: Iterable<T>, template: ItemTemplate<T>): HtmlInterpolation[];
-    <T>(items: Iterable<T>, keyFn: KeyFn<T> | ItemTemplate<T>, template: ItemTemplate<T>): HtmlInterpolation[];
+    <T>(
+        items: Iterable<T>,
+        keyFn: KeyFn<T> | ItemTemplate<T>,
+        template: ItemTemplate<T>,
+    ): HtmlInterpolation[];
 }
+
 /**
  * A directive that repeats a series of values (usually `TemplateResults`) generated from an
  * iterable, and updates those items efficiently when the iterable changes based on user-provided
@@ -78,4 +107,4 @@ export interface RepeatDirectiveFn {
  * If no `keyFn` is provided, this directive will perform similar to mapping items to values, and
  * DOM will be reused against potentially different items.
  */
-export declare const repeat: RepeatDirectiveFn;
+export const repeat = repeatImport as RepeatDirectiveFn;

package/{dist/readme-examples/my-app.element.js → src/readme-examples/my-app.element.ts}

@@ -1,10 +1,11 @@
-import { defineElement } from 'element-vir';
-import { html } from '../index.js';
-import { MySimple } from './my-simple.element.js';
+import {defineElement} from 'element-vir';
+import {html} from '../index.js';
+import {MySimple} from './my-simple.element.js';
+
 export const MyApp = defineElement()({
     tagName: 'my-app',
     render() {
-        return html `
+        return html`
             <h1>My App</h1>
             <${MySimple}></${MySimple}>
         `;

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

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

package/{dist/readme-examples/my-custom-define.js → src/readme-examples/my-custom-define.ts}

@@ -1,15 +1,20 @@
-import { wrapDefineElement } from '../index.js';
-export const defineVirElement = wrapDefineElement();
+import {wrapDefineElement} from '../index.js';
+
+export type VirTagName = `vir-${string}`;
+
+export const defineVirElement = wrapDefineElement<VirTagName>();
+
 // add an optional assert callback
-export const defineVerifiedVirElement = wrapDefineElement({
+export const defineVerifiedVirElement = wrapDefineElement<VirTagName>({
     assertInputs: (inputs) => {
         if (!inputs.tagName.startsWith('vir-')) {
             throw new Error(`all custom elements must start with "vir-"`);
         }
     },
 });
+
 // add an optional transform callback
-export const defineTransformedVirElement = wrapDefineElement({
+export const defineTransformedVirElement = wrapDefineElement<VirTagName>({
     transformInputs: (inputs) => {
         return {
             ...inputs,

package/{dist/readme-examples/my-simple.element.js → src/readme-examples/my-simple.element.ts}

@@ -1,9 +1,10 @@
-import { defineElement } from 'element-vir';
-import { html } from '../index.js';
+import {defineElement} from 'element-vir';
+import {html} from '../index.js';
+
 export const MySimple = defineElement()({
     tagName: 'my-simple',
     render() {
-        return html `
+        return html`
             <span>Hello there!</span>
         `;
     },

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

@@ -0,0 +1,16 @@
+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/{dist/readme-examples/my-with-async-prop.element.js → src/readme-examples/my-with-async-prop.element.ts}

@@ -1,46 +1,54 @@
-import { asyncProp, defineElement, html, listen, renderAsync } from '../index.js';
-async function loadSomething(endpoint) {
+import {asyncProp, defineElement, html, listen, renderAsync} from '../index.js';
+
+type EndpointData = number[];
+
+async function loadSomething(endpoint: string): Promise<EndpointData> {
     // load something from the network
-    const data = await (await fetch([
-        '',
-        'api',
-        endpoint,
-    ].join('/'))).json();
+    const data = await (
+        await fetch(
+            [
+                '',
+                'api',
+                endpoint,
+            ].join('/'),
+        )
+    ).json();
     return data;
 }
-export const MyWithAsyncProp = defineElement()({
+
+export const MyWithAsyncProp = defineElement<{endpoint: string}>()({
     tagName: 'my-with-async-prop',
     state() {
         return {
             data: asyncProp({
-                async updateCallback({ endpoint }) {
+                async updateCallback({endpoint}: {endpoint: string}) {
                     return loadSomething(endpoint);
                 },
             }),
             hi: '',
         };
     },
-    render({ inputs, state }) {
+    render({inputs, state}) {
         /**
          * This causes the a promise which automatically updates the state.data prop once the
          * promise resolves. It only creates a new promise if the first input, the trigger, value
          * changes from previous calls.
          */
         state.data.update(inputs);
-        return html `
+        return html`
             Here's the data:
             <br />
             ${renderAsync(state.data, 'Loading...', (loadedData) => {
-            return html `
+                return html`
                     Got the data: ${loadedData}
                 `;
-        })}
+            })}
             <br />
             <button
                 ${listen('click', () => {
-            /** You can force asyncProp to update by calling forceUpdate. */
-            state.data.forceUpdate(inputs);
-        })}
+                    /** You can force asyncProp to update by calling forceUpdate. */
+                    state.data.forceUpdate(inputs);
+                })}
             >
                 Refresh
             </button>

package/{dist/readme-examples/my-with-cleanup-callback.element.js → src/readme-examples/my-with-cleanup-callback.element.ts}

@@ -1,5 +1,6 @@
-import { defineElement } from 'element-vir';
-import { html } from '../index.js';
+import {defineElement} from 'element-vir';
+import {html} from '../index.js';
+
 export const MyWithAssignmentCleanupCallback = defineElement()({
     tagName: 'my-with-cleanup-callback',
     state() {
@@ -8,11 +9,11 @@ export const MyWithAssignmentCleanupCallback = defineElement()({
         };
     },
     render() {
-        return html `
+        return html`
             <h1>My App</h1>
         `;
     },
-    cleanup({ state }) {
+    cleanup({state}) {
         window.clearInterval(state.intervalId);
     },
 });

package/{dist/readme-examples/my-with-css-vars.element.js → src/readme-examples/my-with-css-vars.element.ts}

@@ -1,12 +1,13 @@
-import { defineElement } from 'element-vir';
-import { css, html } from '../index.js';
+import {defineElement} from 'element-vir';
+import {css, html} from '../index.js';
+
 export const MyWithCssVars = defineElement()({
     tagName: 'my-with-css-vars',
     cssVars: {
         /** The value assigned here ('blue') becomes the fallback value for this CSS var. */
         'my-with-css-vars-my-var': 'blue',
     },
-    styles: ({ cssVars }) => css `
+    styles: ({cssVars}) => css`
         :host {
             /*
                 Set CSS vars (or reference the name directly) via the ".name" property
@@ -20,6 +21,6 @@ export const MyWithCssVars = defineElement()({
         }
     `,
     render() {
-        return html ``;
+        return html``;
     },
 });

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

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