element-vir 26.11.2 → 26.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "element-vir",
-    "version": "26.11.2",
+    "version": "26.12.0",
     "keywords": [
         "custom",
         "web",
@@ -27,9 +27,9 @@
     },
     "sideEffects": false,
     "type": "module",
-    "main": "dist/index.js",
-    "module": "dist/index.js",
-    "types": "dist/index.d.ts",
+    "main": "src/index.ts",
+    "module": "src/index.ts",
+    "types": "src/index.ts",
     "scripts": {
         "build": "npm run docs",
         "compile": "virmator compile",
@@ -39,19 +39,19 @@
         "test:docs": "virmator docs check"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.50.4",
-        "@augment-vir/common": "^31.50.4",
+        "@augment-vir/assert": "^31.54.3",
+        "@augment-vir/common": "^31.54.3",
         "date-vir": "^8.0.0",
         "lit": "^3.3.1",
         "lit-css-vars": "^3.0.11",
         "lit-html": "^3.3.1",
-        "object-shape-tester": "^6.9.3",
+        "object-shape-tester": "^6.10.0",
         "observavir": "^2.2.0",
         "typed-event-target": "^4.1.0"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.50.4",
-        "@augment-vir/web": "^31.50.4",
+        "@augment-vir/test": "^31.54.3",
+        "@augment-vir/web": "^31.54.3",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",
@@ -60,10 +60,10 @@
         "html-spec-tags": "^2.2.3",
         "istanbul-smart-text-reporter": "^1.1.5",
         "markdown-code-example-inserter": "^3.0.3",
-        "type-fest": "^5.2.0",
-        "typedoc": "^0.28.14",
+        "type-fest": "^5.3.1",
+        "typedoc": "^0.28.15",
         "typescript": "5.9.3",
-        "vite": "^7.2.2",
+        "vite": "^7.2.7",
         "vite-tsconfig-paths": "^5.1.4"
     },
     "engines": {

package/src/declarative-element/declarative-element-init.ts

@@ -0,0 +1,115 @@
+import {type CSSResult} from '../lit-exports/base-lit-exports.js';
+import {type CustomElementTagName} from './custom-tag-name.js';
+import {type DeclarativeElementDefinitionOptions} from './definition-options.js';
+import {type CssVarsInitMap} from './properties/css-vars.js';
+import {type EventsInitMap} from './properties/element-events.js';
+import {type PropertyInitMapBase} from './properties/element-properties.js';
+import {type HostClassesInitMap} from './properties/host-classes.js';
+import {type BaseStringName} from './properties/string-names.js';
+import {type StylesCallback} from './properties/styles.js';
+import {type InitCallback, type RenderCallback, type RenderParams} from './render-callback.js';
+
+/**
+ * Initialization for an element-vir declarative element. This defines all the pieces required for
+ * rendering the element.
+ *
+ * @category Internal
+ */
+export type DeclarativeElementInit<
+    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>,
+> = {
+    /**
+     * HTML tag name. This should not be used directly, as interpolating it with the html tagged
+     * template from this package is preferred.
+     */
+    tagName: TagName;
+    /** Static styles. These should not and cannot change. */
+    styles?: CSSResult | StylesCallback<TagName, HostClassKeys, CssVarKeys> | undefined;
+    /** Events that the element can dispatch. (These can be thought of as "outputs".) */
+    events?: EventsInit | undefined;
+    slotNames?: SlotNames | undefined;
+    testIds?: TestIds | undefined;
+    /**
+     * HTML host classes. Values can be callbacks to determine when a host class should be defined,
+     * based on current instance state or inputs, or just false to indicate that the host class will
+     * only be manually set.
+     */
+    hostClasses?: HostClassesInitMap<TagName, HostClassKeys, Inputs, State> | undefined;
+    /**
+     * CSS Vars for the component. Keys of this object should be kebab-case and start with the
+     * element's tag name.
+     *
+     * Values of this object represent the default fallback value for the given CSS var. These are
+     * then passed to the styles property, which must be a callback to take advantage of these.
+     */
+    cssVars?: CssVarsInitMap<TagName, CssVarKeys>;
+    /**
+     * Make sure to define this at the top of your element init object or TypeScript will fail to
+     * infer the element's state type.
+     *
+     * Setup the element's initial state. This is only called once per element instance, before the
+     * first render. The return type of this method becomes the element's state type.
+     */
+    state?: (
+        params: Omit<
+            RenderParams<
+                TagName,
+                Inputs,
+                any,
+                EventsInit,
+                HostClassKeys,
+                CssVarKeys,
+                SlotNames,
+                TestIds
+            >,
+            'state' | 'updateState'
+        >,
+    ) => Extract<keyof State, keyof HTMLElement> extends never
+        ? Extract<keyof State, keyof Inputs> extends never
+            ? State
+            : `ERROR: Cannot define an element state property that clashes with input properties: ${Extract<keyof State, keyof Inputs> extends string | number | bigint | boolean | null | undefined ? Extract<keyof State, keyof Inputs> : ''}`
+        : `ERROR: Cannot define an element state property that clashes with native HTMLElement properties: ${Extract<keyof State, keyof HTMLElement>}`;
+    /** Called as part of the first render call, before the first render call. */
+    init?:
+        | InitCallback<
+              TagName,
+              Inputs,
+              State,
+              EventsInit,
+              HostClassKeys,
+              CssVarKeys,
+              SlotNames,
+              TestIds
+          >
+        | undefined;
+    render: RenderCallback<
+        TagName,
+        Inputs,
+        State,
+        EventsInit,
+        HostClassKeys,
+        CssVarKeys,
+        SlotNames,
+        TestIds
+    >;
+    cleanup?:
+        | InitCallback<
+              TagName,
+              Inputs,
+              State,
+              EventsInit,
+              HostClassKeys,
+              CssVarKeys,
+              SlotNames,
+              TestIds
+          >
+        | undefined;
+    options?: Partial<DeclarativeElementDefinitionOptions> | undefined;
+};

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

@@ -0,0 +1,372 @@
+import {type SetRequiredAndNotNull} from '@augment-vir/common';
+import {type EmptyObject, type IsAny, type IsEmptyObject} from 'type-fest';
+import {LitElement, type CSSResult} from '../lit-exports/base-lit-exports.js';
+import {type MinimalDefinitionWithInputs} from '../template-transforms/minimal-element-definition.js';
+import {type CustomElementTagName} from './custom-tag-name.js';
+import {type DeclarativeElementInit} from './declarative-element-init.js';
+import {type DeclarativeElementDefinitionOptions} from './definition-options.js';
+import {type CssVars} from './properties/css-vars.js';
+import {type EventDescriptorMap, type EventsInitMap} from './properties/element-events.js';
+import {type PropertyInitMapBase} from './properties/element-properties.js';
+import {type HostClassNamesMap} from './properties/host-classes.js';
+import {type ObservableListenerMap} from './properties/property-proxy.js';
+import {type BaseStringName, type StringNameMap} from './properties/string-names.js';
+import {
+    type RenderCallback,
+    type RenderParams,
+    type UpdateStateCallback,
+} from './render-callback.js';
+
+/**
+ * The `host` type for a declarative element. This references a declarative element instance's
+ * top-level HTML element and always contains a shadow root (wherein the element is rendered).
+ *
+ * @category Internal
+ */
+export type DeclarativeElementHost<
+    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,
+> = SetRequiredAndNotNull<
+    Omit<
+        DeclarativeElement<
+            TagName,
+            Inputs,
+            State,
+            EventsInit,
+            HostClassKeys,
+            CssVarKeys,
+            SlotNames,
+            TestIds
+        >,
+        Exclude<
+            keyof StaticDeclarativeElementProperties<any, any, any, any, any, any, any, any>,
+            keyof HTMLElement
+        >
+    >,
+    'shadowRoot'
+>;
+
+/**
+ * The full definition for a declarative element.
+ *
+ * @category Internal
+ */
+export type DeclarativeElementDefinition<
+    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,
+> = (new () => DeclarativeElementHost<
+    TagName,
+    Inputs,
+    State,
+    EventsInit,
+    HostClassKeys,
+    CssVarKeys,
+    SlotNames,
+    TestIds
+>) &
+    StaticDeclarativeElementProperties<
+        TagName,
+        Inputs,
+        State,
+        EventsInit,
+        HostClassKeys,
+        CssVarKeys,
+        SlotNames,
+        TestIds
+    > & {
+        InstanceType: DeclarativeElementHost<
+            TagName,
+            Inputs,
+            State,
+            EventsInit,
+            HostClassKeys,
+            CssVarKeys,
+            SlotNames,
+            TestIds
+        >;
+    };
+
+/**
+ * Abstract class base for all declarative elements.
+ *
+ * @category Internal
+ */
+export abstract class DeclarativeElement<
+    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,
+> extends LitElement {
+    /**
+     * Assign inputs to an element instantiation. Use only on the opening tag.
+     *
+     * @example
+     *
+     * ```ts
+     * import {html} from 'element-vir';
+     *
+     * const myTemplate = html`
+     *     <${MyElement.assign({input1: 'a', input2: 'b'})}></${MyElement}>
+     * `;
+     * ```
+     */
+    public static readonly assign: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['assign'];
+    public static readonly assignedInputs: PropertyInitMapBase | undefined;
+    public static readonly tagName: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['tagName'];
+    public static override readonly styles: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['styles'];
+    public static readonly render: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['render'];
+    public static readonly InputsType: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['InputsType'];
+    public static readonly StateType: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['StateType'];
+    public static readonly UpdateStateType: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['UpdateStateType'];
+    public static readonly events: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['events'];
+    public static readonly init: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['init'];
+    public static readonly elementOptions: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['elementOptions'];
+    public static readonly hostClasses: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['hostClasses'];
+    public static readonly cssVars: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['cssVars'];
+    public static readonly slotNames: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['slotNames'];
+    public static readonly testIds: StaticDeclarativeElementProperties<
+        CustomElementTagName,
+        PropertyInitMapBase,
+        PropertyInitMapBase,
+        EventsInitMap,
+        BaseStringName<CustomElementTagName>,
+        BaseStringName<CustomElementTagName>,
+        ReadonlyArray<string>,
+        ReadonlyArray<string>
+    >['testIds'];
+
+    public abstract _lastRenderError: Error | undefined;
+    public abstract _internalRenderCount: number;
+    public abstract _lastRenderedProps: Readonly<
+        Pick<RenderParams<any, Inputs, State, any, any, any, any, any>, 'inputs' | 'state'>
+    >;
+    /**
+     * Calls all destroy methods on all state properties, if they exist. This is automatically
+     * called whenever the element is detached.
+     */
+    public abstract destroy(): void;
+    public abstract override render(): unknown;
+    public abstract readonly instanceState: State;
+    public abstract readonly observablePropertyListenerMap: ObservableListenerMap<State & Inputs>;
+    public abstract readonly instanceInputs: Inputs;
+    /**
+     * Used to assign inputs to the given element. This can be externally called as an API for
+     * setting inputs on an element reference, though this is discouraged. Inputs should typically
+     * be called using the `.assign()` method on an element definition inside of an HTML template.
+     */
+    public abstract assignInputs(
+        inputs: EmptyObject extends Required<Inputs> ? never : Partial<Inputs>,
+    ): void;
+    /** The element definition for this element instance. */
+    public abstract readonly definition: DeclarativeElementDefinition<
+        TagName,
+        Inputs,
+        State,
+        EventsInit,
+        HostClassKeys,
+        CssVarKeys,
+        SlotNames,
+        TestIds
+    >;
+}
+
+/**
+ * The assign inputs method of a declarative element.
+ *
+ * @category Internal
+ */
+export type AssignMethod<TagName extends CustomElementTagName, Inputs extends PropertyInitMapBase> =
+    IsAny<Inputs> extends true
+        ? any
+        : IsEmptyObject<Required<Inputs>> extends true
+          ? (inputsObject: never) => never
+          : (
+                inputsObject: IsEmptyObject<Required<Inputs>> extends true ? never : Inputs,
+            ) => MinimalDefinitionWithInputs<TagName>;
+
+/**
+ * All static properties on a declarative element. These all come from the element's definition.
+ *
+ * @category Internal
+ */
+export type StaticDeclarativeElementProperties<
+    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>,
+> = {
+    /** Assign inputs to an element directly on its interpolated tag. */
+    readonly assign: AssignMethod<TagName, Inputs>;
+    assignedInputs: Inputs | undefined;
+
+    /** Pass through the render callback for direct unit testability */
+    readonly render: RenderCallback<
+        TagName,
+        Inputs,
+        State,
+        EventsInit,
+        HostClassKeys,
+        CssVarKeys,
+        SlotNames,
+        TestIds
+    >;
+    readonly events: EventDescriptorMap<TagName, EventsInit>;
+    readonly slotNames: Readonly<StringNameMap<TagName, 'slot', SlotNames>>;
+    readonly testIds: Readonly<StringNameMap<TagName, 'test-id', TestIds>>;
+    readonly init: DeclarativeElementInit<
+        TagName,
+        Inputs,
+        State,
+        EventsInit,
+        HostClassKeys,
+        CssVarKeys,
+        SlotNames,
+        TestIds
+    >;
+    readonly elementOptions: DeclarativeElementDefinitionOptions;
+    readonly InputsType: Inputs;
+    readonly StateType: Readonly<State>;
+    readonly UpdateStateType: UpdateStateCallback<State>;
+    readonly hostClasses: HostClassNamesMap<string, HostClassKeys>;
+    readonly cssVars: CssVars<TagName, CssVarKeys>;
+
+    readonly tagName: TagName;
+    readonly styles: CSSResult;
+};