@easemate/web-kit 0.1.0

package/build/decorators/Component.d.ts

@@ -0,0 +1,28 @@
+import { type TemplateResult } from 'lit-html';
+type Constructor<T extends HTMLElement> = new (...args: unknown[]) => T;
+type RenderableElement = HTMLElement & {
+    render?(): TemplateResult | null | undefined;
+    afterRender?(): void;
+    wrapRender?(commit: () => void, context: RenderContext): void;
+    onAttributeChange?(name: string, oldValue: string | null, newValue: string | null): void;
+    requestRender?(): void;
+    renderRoot?: ShadowRoot | HTMLElement;
+};
+type TemplateValue<TElement extends RenderableElement> = TemplateResult | null | undefined | ((this: TElement, host: TElement) => TemplateResult | null | undefined);
+interface ComponentOptions<TElement extends RenderableElement = RenderableElement> {
+    tag: string;
+    template?: TemplateValue<TElement>;
+    styles?: string;
+    styleUrls?: string[];
+    observedAttributes?: string[];
+    shadowMode?: ShadowRootMode;
+    autoSlot?: boolean;
+}
+export interface RenderContext {
+    fragment: DocumentFragment;
+    root: ShadowRoot | HTMLElement;
+}
+export declare const Component: <TElement extends RenderableElement = RenderableElement>(options: ComponentOptions<TElement>) => <TBase extends Constructor<TElement> & {
+    observedAttributes?: string[];
+}>(Base: TBase, _context: ClassDecoratorContext) => TBase;
+export {};

package/build/decorators/Component.js

@@ -0,0 +1,123 @@
+import { html, render } from 'lit-html';
+const styleCache = new Map();
+const normalizeTemplate = (template) => {
+    if (typeof template === 'function') {
+        return template;
+    }
+    if (template && typeof template === 'object' && '_$litTemplate$' in template) {
+        return function () {
+            return template;
+        };
+    }
+    return function () {
+        return null;
+    };
+};
+const fetchStyles = async (urls) => Promise.all(urls.map((url) => {
+    const cached = styleCache.get(url);
+    if (cached) {
+        return cached;
+    }
+    const request = fetch(url)
+        .then((response) => (response.ok ? response.text() : ''))
+        .catch(() => '');
+    styleCache.set(url, request);
+    return request;
+}));
+export const Component = (options) => (Base, _context) => {
+    const { tag, template, styles = '', styleUrls = [], observedAttributes = [], shadowMode = 'open', autoSlot = true } = options;
+    if (!tag) {
+        throw new Error('@Component requires a "tag" option.');
+    }
+    const templateFn = normalizeTemplate(template);
+    class Decorated extends Base {
+        static get observedAttributes() {
+            const parent = 'observedAttributes' in Base && Array.isArray(Base.observedAttributes)
+                ? Base.observedAttributes
+                : [];
+            const own = Array.isArray(observedAttributes) ? observedAttributes : [];
+            return Array.from(new Set([...parent, ...own]));
+        }
+        #shadow;
+        #styles = styles;
+        #styleUrls = [...styleUrls];
+        #renderScheduled = false;
+        constructor(...args) {
+            super(...args);
+            this.#shadow = this.attachShadow({ mode: shadowMode });
+            this.renderRoot = this.#shadow;
+        }
+        get shadow() {
+            return this.renderRoot;
+        }
+        connectedCallback() {
+            Base.prototype.connectedCallback?.call(this);
+            void this.#loadStyles().finally(() => {
+                this.requestRender();
+            });
+        }
+        disconnectedCallback() {
+            Base.prototype.disconnectedCallback?.call(this);
+            this.#renderScheduled = false;
+        }
+        attributeChangedCallback(name, oldValue, newValue) {
+            Base.prototype.attributeChangedCallback?.call(this, name, oldValue, newValue);
+            if (oldValue !== newValue) {
+                this.onAttributeChange?.(name, oldValue, newValue);
+            }
+        }
+        requestRender() {
+            if (this.#renderScheduled) {
+                return;
+            }
+            this.#renderScheduled = true;
+            requestAnimationFrame(() => {
+                this.#renderScheduled = false;
+                this.#render();
+            });
+        }
+        async #loadStyles() {
+            if (!this.#styleUrls.length) {
+                return;
+            }
+            const fetched = await fetchStyles(this.#styleUrls);
+            const inlineStyles = this.#styles ? [this.#styles] : [];
+            this.#styles = [...inlineStyles, ...fetched.filter(Boolean)].join('\n');
+        }
+        #render() {
+            const root = this.#shadow;
+            let templateResult;
+            if (typeof this.render === 'function') {
+                templateResult = this.render();
+            }
+            else {
+                templateResult = templateFn.call(this, this);
+            }
+            const styleTemplate = this.#styles ? html `<style>${this.#styles}</style>` : null;
+            const slotTemplate = autoSlot ? html `<slot></slot>` : null;
+            const completeTemplate = html `
+          ${styleTemplate}
+          ${templateResult ?? null}
+          ${slotTemplate}
+        `;
+            const commit = () => {
+                render(completeTemplate, root);
+                this.afterRender?.();
+            };
+            if (typeof this.wrapRender === 'function') {
+                const fragment = document.createDocumentFragment();
+                const tempDiv = document.createElement('div');
+                render(completeTemplate, tempDiv);
+                fragment.append(...tempDiv.childNodes);
+                this.wrapRender(commit, { fragment, root });
+                return;
+            }
+            commit();
+        }
+    }
+    // SSR safety: only register in browser environments
+    if (typeof customElements !== 'undefined' && !customElements.get(tag)) {
+        customElements.define(tag, Decorated);
+    }
+    return Decorated;
+};

package/build/decorators/Listen.cjs

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Listen = Listen;
+const lifecycleHooks = {
+    connectedCallback: new WeakMap(),
+    disconnectedCallback: new WeakMap()
+};
+const cleanupRegistry = new WeakMap();
+const addLifecycleHook = (instance, hookName, handler) => {
+    const store = lifecycleHooks[hookName];
+    let callbacks = store.get(instance);
+    if (!callbacks) {
+        callbacks = new Set();
+        store.set(instance, callbacks);
+        const original = instance[hookName];
+        instance[hookName] = function (...args) {
+            callbacks?.forEach((callback) => {
+                callback.apply(this);
+            });
+            if (typeof original === 'function') {
+                return original.apply(this, args);
+            }
+            return undefined;
+        };
+    }
+    callbacks.add(handler);
+};
+const registerCleanup = (instance, cleanup) => {
+    let callbacks = cleanupRegistry.get(instance);
+    if (!callbacks) {
+        callbacks = new Set();
+        cleanupRegistry.set(instance, callbacks);
+        addLifecycleHook(instance, 'disconnectedCallback', function () {
+            const registered = cleanupRegistry.get(this);
+            registered?.forEach((fn) => {
+                try {
+                    fn();
+                }
+                catch (error) {
+                    console.error('[Listen] cleanup failed', error);
+                }
+            });
+            cleanupRegistry.delete(this);
+        });
+    }
+    callbacks.add(cleanup);
+};
+const resolveTarget = (host, target) => {
+    if (typeof target === 'function') {
+        return target(host) ?? null;
+    }
+    if (target instanceof EventTarget) {
+        return target;
+    }
+    switch (target) {
+        case 'document':
+            return document;
+        case 'window':
+            return window;
+        case 'light':
+            return host;
+        default:
+            return host.renderRoot ?? host.shadowRoot ?? host;
+    }
+};
+const normalizeOptions = (selectorOrOptions) => {
+    if (typeof selectorOrOptions === 'string') {
+        return { selector: selectorOrOptions };
+    }
+    return selectorOrOptions ?? {};
+};
+const buildOptions = (options) => {
+    return {
+        selector: options.selector ?? null,
+        target: options.target ?? 'shadow',
+        prevent: options.prevent ?? false,
+        stop: options.stop ?? false,
+        stopImmediate: options.stopImmediate ?? false,
+        once: options.once ?? false,
+        passive: options.passive,
+        capture: options.capture ?? false,
+        when: options.when ?? null
+    };
+};
+function Listen(eventName, selectorOrOptions) {
+    if (!eventName) {
+        throw new Error('@Listen requires an event name.');
+    }
+    const listenConfig = buildOptions(normalizeOptions(selectorOrOptions));
+    return (originalMethod, context) => {
+        context.addInitializer(function () {
+            let attached = false;
+            const attach = () => {
+                if (attached) {
+                    return;
+                }
+                const target = resolveTarget(this, listenConfig.target);
+                if (!target || typeof target.addEventListener !== 'function') {
+                    console.warn(`@Listen unable to resolve target for ${String(eventName)}`);
+                    return;
+                }
+                const eventOptions = {
+                    capture: listenConfig.capture,
+                    once: listenConfig.once,
+                    passive: listenConfig.passive !== undefined ? listenConfig.passive : !listenConfig.prevent
+                };
+                const handler = (event) => {
+                    const typedEvent = event;
+                    if (listenConfig.prevent) {
+                        typedEvent.preventDefault();
+                    }
+                    if (listenConfig.stopImmediate) {
+                        typedEvent.stopImmediatePropagation();
+                    }
+                    else if (listenConfig.stop) {
+                        typedEvent.stopPropagation();
+                    }
+                    let matched = null;
+                    if (listenConfig.selector) {
+                        const path = typedEvent.composedPath();
+                        matched =
+                            path.find((node) => node instanceof Element && node.matches(listenConfig.selector)) ?? null;
+                        if (!matched) {
+                            return;
+                        }
+                    }
+                    if (listenConfig.when && !listenConfig.when(typedEvent, matched)) {
+                        return;
+                    }
+                    if (listenConfig.selector) {
+                        void originalMethod.call(this, typedEvent, matched);
+                    }
+                    else {
+                        const targetNode = (typedEvent.target instanceof Element ? typedEvent.target : null);
+                        void originalMethod.call(this, typedEvent, targetNode);
+                    }
+                };
+                target.addEventListener(eventName, handler, eventOptions);
+                attached = true;
+                registerCleanup(this, () => {
+                    target.removeEventListener(eventName, handler, eventOptions);
+                    attached = false;
+                });
+            };
+            // IMPORTANT:
+            // Many components are created inside templates/shadow DOM. At construction time they are often not connected yet,
+            // and patching instance lifecycle callbacks is not reliably invoked by the platform.
+            // Attach the listener ASAP (microtask) so it works for nested components as well.
+            queueMicrotask(attach);
+            // Best-effort attach on connect too (idempotent).
+            addLifecycleHook(this, 'connectedCallback', attach);
+        });
+    };
+}

package/build/decorators/Listen.d.cts

@@ -0,0 +1,18 @@
+type ListenHost = HTMLElement & {
+    renderRoot?: ShadowRoot | DocumentFragment | HTMLElement;
+};
+type ListenTargetResolver<THost extends ListenHost> = 'document' | 'window' | 'shadow' | 'root' | 'light' | EventTarget | ((host: THost) => EventTarget | null | undefined);
+type Predicate<TEvent extends Event, TElement extends Element> = (event: TEvent, matched: TElement | null) => boolean;
+interface ListenOptions<THost extends ListenHost, TElement extends Element, TEvent extends Event> {
+    selector?: string;
+    target?: ListenTargetResolver<THost>;
+    prevent?: boolean;
+    stop?: boolean;
+    stopImmediate?: boolean;
+    once?: boolean;
+    passive?: boolean;
+    capture?: boolean;
+    when?: Predicate<TEvent, TElement>;
+}
+export declare function Listen<THost extends ListenHost, TEvent extends Event = Event, TElement extends Element = Element>(eventName: keyof HTMLElementEventMap | string, selectorOrOptions?: string | ListenOptions<THost, TElement, TEvent>): (originalMethod: (this: THost, event: TEvent, matched?: TElement | null) => unknown, context: ClassMethodDecoratorContext<THost, typeof originalMethod>) => void;
+export {};

package/build/decorators/Listen.d.ts

@@ -0,0 +1,18 @@
+type ListenHost = HTMLElement & {
+    renderRoot?: ShadowRoot | DocumentFragment | HTMLElement;
+};
+type ListenTargetResolver<THost extends ListenHost> = 'document' | 'window' | 'shadow' | 'root' | 'light' | EventTarget | ((host: THost) => EventTarget | null | undefined);
+type Predicate<TEvent extends Event, TElement extends Element> = (event: TEvent, matched: TElement | null) => boolean;
+interface ListenOptions<THost extends ListenHost, TElement extends Element, TEvent extends Event> {
+    selector?: string;
+    target?: ListenTargetResolver<THost>;
+    prevent?: boolean;
+    stop?: boolean;
+    stopImmediate?: boolean;
+    once?: boolean;
+    passive?: boolean;
+    capture?: boolean;
+    when?: Predicate<TEvent, TElement>;
+}
+export declare function Listen<THost extends ListenHost, TEvent extends Event = Event, TElement extends Element = Element>(eventName: keyof HTMLElementEventMap | string, selectorOrOptions?: string | ListenOptions<THost, TElement, TEvent>): (originalMethod: (this: THost, event: TEvent, matched?: TElement | null) => unknown, context: ClassMethodDecoratorContext<THost, typeof originalMethod>) => void;
+export {};

package/build/decorators/Listen.js

@@ -0,0 +1,151 @@
+const lifecycleHooks = {
+    connectedCallback: new WeakMap(),
+    disconnectedCallback: new WeakMap()
+};
+const cleanupRegistry = new WeakMap();
+const addLifecycleHook = (instance, hookName, handler) => {
+    const store = lifecycleHooks[hookName];
+    let callbacks = store.get(instance);
+    if (!callbacks) {
+        callbacks = new Set();
+        store.set(instance, callbacks);
+        const original = instance[hookName];
+        instance[hookName] = function (...args) {
+            callbacks?.forEach((callback) => {
+                callback.apply(this);
+            });
+            if (typeof original === 'function') {
+                return original.apply(this, args);
+            }
+            return undefined;
+        };
+    }
+    callbacks.add(handler);
+};
+const registerCleanup = (instance, cleanup) => {
+    let callbacks = cleanupRegistry.get(instance);
+    if (!callbacks) {
+        callbacks = new Set();
+        cleanupRegistry.set(instance, callbacks);
+        addLifecycleHook(instance, 'disconnectedCallback', function () {
+            const registered = cleanupRegistry.get(this);
+            registered?.forEach((fn) => {
+                try {
+                    fn();
+                }
+                catch (error) {
+                    console.error('[Listen] cleanup failed', error);
+                }
+            });
+            cleanupRegistry.delete(this);
+        });
+    }
+    callbacks.add(cleanup);
+};
+const resolveTarget = (host, target) => {
+    if (typeof target === 'function') {
+        return target(host) ?? null;
+    }
+    if (target instanceof EventTarget) {
+        return target;
+    }
+    switch (target) {
+        case 'document':
+            return document;
+        case 'window':
+            return window;
+        case 'light':
+            return host;
+        default:
+            return host.renderRoot ?? host.shadowRoot ?? host;
+    }
+};
+const normalizeOptions = (selectorOrOptions) => {
+    if (typeof selectorOrOptions === 'string') {
+        return { selector: selectorOrOptions };
+    }
+    return selectorOrOptions ?? {};
+};
+const buildOptions = (options) => {
+    return {
+        selector: options.selector ?? null,
+        target: options.target ?? 'shadow',
+        prevent: options.prevent ?? false,
+        stop: options.stop ?? false,
+        stopImmediate: options.stopImmediate ?? false,
+        once: options.once ?? false,
+        passive: options.passive,
+        capture: options.capture ?? false,
+        when: options.when ?? null
+    };
+};
+export function Listen(eventName, selectorOrOptions) {
+    if (!eventName) {
+        throw new Error('@Listen requires an event name.');
+    }
+    const listenConfig = buildOptions(normalizeOptions(selectorOrOptions));
+    return (originalMethod, context) => {
+        context.addInitializer(function () {
+            let attached = false;
+            const attach = () => {
+                if (attached) {
+                    return;
+                }
+                const target = resolveTarget(this, listenConfig.target);
+                if (!target || typeof target.addEventListener !== 'function') {
+                    console.warn(`@Listen unable to resolve target for ${String(eventName)}`);
+                    return;
+                }
+                const eventOptions = {
+                    capture: listenConfig.capture,
+                    once: listenConfig.once,
+                    passive: listenConfig.passive !== undefined ? listenConfig.passive : !listenConfig.prevent
+                };
+                const handler = (event) => {
+                    const typedEvent = event;
+                    if (listenConfig.prevent) {
+                        typedEvent.preventDefault();
+                    }
+                    if (listenConfig.stopImmediate) {
+                        typedEvent.stopImmediatePropagation();
+                    }
+                    else if (listenConfig.stop) {
+                        typedEvent.stopPropagation();
+                    }
+                    let matched = null;
+                    if (listenConfig.selector) {
+                        const path = typedEvent.composedPath();
+                        matched =
+                            path.find((node) => node instanceof Element && node.matches(listenConfig.selector)) ?? null;
+                        if (!matched) {
+                            return;
+                        }
+                    }
+                    if (listenConfig.when && !listenConfig.when(typedEvent, matched)) {
+                        return;
+                    }
+                    if (listenConfig.selector) {
+                        void originalMethod.call(this, typedEvent, matched);
+                    }
+                    else {
+                        const targetNode = (typedEvent.target instanceof Element ? typedEvent.target : null);
+                        void originalMethod.call(this, typedEvent, targetNode);
+                    }
+                };
+                target.addEventListener(eventName, handler, eventOptions);
+                attached = true;
+                registerCleanup(this, () => {
+                    target.removeEventListener(eventName, handler, eventOptions);
+                    attached = false;
+                });
+            };
+            // IMPORTANT:
+            // Many components are created inside templates/shadow DOM. At construction time they are often not connected yet,
+            // and patching instance lifecycle callbacks is not reliably invoked by the platform.
+            // Attach the listener ASAP (microtask) so it works for nested components as well.
+            queueMicrotask(attach);
+            // Best-effort attach on connect too (idempotent).
+            addLifecycleHook(this, 'connectedCallback', attach);
+        });
+    };
+}

package/build/decorators/OutsideClick.cjs

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestOutsideClickUpdate = void 0;
+exports.OutsideClick = OutsideClick;
+const outside_click_1 = require("~/utils/outside-click");
+const lifecycleApplied = new WeakSet();
+const wrapMethod = (host, name, hook, callHookFirst = false) => {
+    const original = host[name];
+    host[name] = function (...args) {
+        if (callHookFirst) {
+            hook.call(this);
+        }
+        let result;
+        if (typeof original === 'function') {
+            result = original.apply(this, args);
+        }
+        if (!callHookFirst) {
+            hook.call(this);
+        }
+        return result;
+    };
+};
+const ensureLifecycle = (host) => {
+    if (lifecycleApplied.has(host)) {
+        return;
+    }
+    lifecycleApplied.add(host);
+    wrapMethod(host, 'connectedCallback', function () {
+        (0, outside_click_1.updateOutsideClickHandles)(this);
+    });
+    wrapMethod(host, 'afterRender', function () {
+        (0, outside_click_1.updateOutsideClickHandles)(this);
+    });
+    wrapMethod(host, 'disconnectedCallback', function () {
+        (0, outside_click_1.disconnectOutsideClickHandles)(this);
+    }, true);
+};
+function OutsideClick(options = {}) {
+    return (originalMethod, context) => {
+        context.addInitializer(function () {
+            ensureLifecycle(this);
+            const resolve = options.resolve ??
+                ((host) => {
+                    return {
+                        owner: options.owner?.(host),
+                        content: options.content?.(host),
+                        triggers: options.triggers?.(host)
+                    };
+                });
+            const handle = (0, outside_click_1.createOutsideClickHandle)(this, (event) => {
+                originalMethod.call(this, event);
+            }, {
+                resolve,
+                disabled: options.disabled
+            });
+            (0, outside_click_1.registerOutsideClickHandle)(this, handle);
+            if (this.isConnected) {
+                (0, outside_click_1.updateOutsideClickHandles)(this);
+            }
+        });
+    };
+}
+var outside_click_2 = require("~/utils/outside-click");
+Object.defineProperty(exports, "requestOutsideClickUpdate", { enumerable: true, get: function () { return outside_click_2.requestOutsideClickUpdate; } });

package/build/decorators/OutsideClick.d.cts

@@ -0,0 +1,16 @@
+import type { OutsideClickResolution } from '~/utils/outside-click';
+type OutsideClickHost = HTMLElement & {
+    connectedCallback?: (...args: unknown[]) => unknown;
+    disconnectedCallback?: (...args: unknown[]) => unknown;
+    afterRender?: (...args: unknown[]) => unknown;
+};
+interface OutsideClickOptions<THost extends OutsideClickHost> {
+    resolve?: (host: THost) => OutsideClickResolution | null | undefined;
+    owner?: (host: THost) => HTMLElement | null | undefined;
+    content?: (host: THost) => HTMLElement | null | undefined;
+    triggers?: (host: THost) => Array<HTMLElement | null | undefined>;
+    disabled?: (host: THost) => boolean;
+}
+export declare function OutsideClick<THost extends OutsideClickHost, TEvent extends Event = Event>(options?: OutsideClickOptions<THost>): (originalMethod: (this: THost, event: TEvent) => unknown, context: ClassMethodDecoratorContext<THost, typeof originalMethod>) => void;
+export { requestOutsideClickUpdate } from '~/utils/outside-click';
+export type { OutsideClickOptions };

package/build/decorators/OutsideClick.d.ts

@@ -0,0 +1,16 @@
+import type { OutsideClickResolution } from '~/utils/outside-click';
+type OutsideClickHost = HTMLElement & {
+    connectedCallback?: (...args: unknown[]) => unknown;
+    disconnectedCallback?: (...args: unknown[]) => unknown;
+    afterRender?: (...args: unknown[]) => unknown;
+};
+interface OutsideClickOptions<THost extends OutsideClickHost> {
+    resolve?: (host: THost) => OutsideClickResolution | null | undefined;
+    owner?: (host: THost) => HTMLElement | null | undefined;
+    content?: (host: THost) => HTMLElement | null | undefined;
+    triggers?: (host: THost) => Array<HTMLElement | null | undefined>;
+    disabled?: (host: THost) => boolean;
+}
+export declare function OutsideClick<THost extends OutsideClickHost, TEvent extends Event = Event>(options?: OutsideClickOptions<THost>): (originalMethod: (this: THost, event: TEvent) => unknown, context: ClassMethodDecoratorContext<THost, typeof originalMethod>) => void;
+export { requestOutsideClickUpdate } from '~/utils/outside-click';
+export type { OutsideClickOptions };

package/build/decorators/OutsideClick.js

@@ -0,0 +1,59 @@
+import { createOutsideClickHandle, disconnectOutsideClickHandles, registerOutsideClickHandle, updateOutsideClickHandles } from '~/utils/outside-click';
+const lifecycleApplied = new WeakSet();
+const wrapMethod = (host, name, hook, callHookFirst = false) => {
+    const original = host[name];
+    host[name] = function (...args) {
+        if (callHookFirst) {
+            hook.call(this);
+        }
+        let result;
+        if (typeof original === 'function') {
+            result = original.apply(this, args);
+        }
+        if (!callHookFirst) {
+            hook.call(this);
+        }
+        return result;
+    };
+};
+const ensureLifecycle = (host) => {
+    if (lifecycleApplied.has(host)) {
+        return;
+    }
+    lifecycleApplied.add(host);
+    wrapMethod(host, 'connectedCallback', function () {
+        updateOutsideClickHandles(this);
+    });
+    wrapMethod(host, 'afterRender', function () {
+        updateOutsideClickHandles(this);
+    });
+    wrapMethod(host, 'disconnectedCallback', function () {
+        disconnectOutsideClickHandles(this);
+    }, true);
+};
+export function OutsideClick(options = {}) {
+    return (originalMethod, context) => {
+        context.addInitializer(function () {
+            ensureLifecycle(this);
+            const resolve = options.resolve ??
+                ((host) => {
+                    return {
+                        owner: options.owner?.(host),
+                        content: options.content?.(host),
+                        triggers: options.triggers?.(host)
+                    };
+                });
+            const handle = createOutsideClickHandle(this, (event) => {
+                originalMethod.call(this, event);
+            }, {
+                resolve,
+                disabled: options.disabled
+            });
+            registerOutsideClickHandle(this, handle);
+            if (this.isConnected) {
+                updateOutsideClickHandles(this);
+            }
+        });
+    };
+}
+export { requestOutsideClickUpdate } from '~/utils/outside-click';