@xtia/jel 0.4.5 → 0.5.0

package/README.md

@@ -1,9 +1,9 @@
 # Jel
 ### Or, How I Learned To Stop Worrying And Love The DOM
 
-Jel is a thin layer over the DOM to simplify element structure creation, manipulation and componentisation with 'vanilla' TS.
+Jel is a thin layer over the DOM to simplify element structure creation, manipulation and componentisation with 'vanilla' TS/JS.
 
-See [demo/index.ts](https://github.com/tiadrop/jel-ts/blob/main/demo/index.ts) for example operation. Compare with [resulting page](https://aleta.codes/jel-ts-demo/).
+See [demo/index.ts](https://github.com/tiadrop/jel-ts/blob/main/demo/index.ts) for reusable components. Compare with [resulting page](https://aleta.codes/jel-ts-demo/).
 
 ## `$` Basic Use:
 
@@ -47,7 +47,7 @@ body.append([
 
 ## `DOMContent`
 
-Content can be string, Text, HTMLElement, JelEntity or arbitrarily nested array of content. Typing as DOMContent where possible enables flexibility.
+Content can be string, Text, HTMLElement, JelEntity or arbitrarily nested array of content. Typing as DOMContent carries that flexibility to your own interfaces.
 
 ```ts
 function showDialogue(content: DOMContent) => {
@@ -124,4 +124,17 @@ If you need an element with just a class, id and/or content you can use `tag#id.
 
 ```ts
 showDialogue(["Hello ", $("span.green", "world")]);
-```
+```
+
+## Event composition
+
+Event emitters can be chained:
+
+```ts
+element.events.mousemove
+	.takeUntil(body.events.mousedown.filter(e => e.button === 1))
+	.map(ev => [ev.offsetX, ev.offsetY])
+	.apply(([x, y]) => console.log("mouse @ ", x, y));
+```
+
+For RxJS users, events can be observed with `fromEvent(element.events, "mousemove")`.

package/index.d.ts

@@ -1,108 +1,4 @@
-export type ElementClassDescriptor = string | Record<string, boolean> | ElementClassDescriptor[];
-export type DOMContent = number | null | string | Element | JelEntity<object> | Text | DOMContent[];
-export type DomEntity<T extends HTMLElement> = JelEntity<ElementAPI<T>>;
-type PartConstructor<Spec, API extends object | void, EventDataMap> = (spec: Spec & EventSpec<EventDataMap>) => JelEntity<EventHost<API, EventDataMap>>;
-type EventSpec<EventDataMap> = EventDataMap extends object ? {
-    on?: {
-        [EventID in keyof EventDataMap]+?: (data: EventDataMap[EventID]) => void;
-    };
-} : {};
-type JelEntity<API extends object | void> = (API extends void ? {} : API) & {
-    readonly [entityDataSymbol]: JelEntityData;
-};
-type CSSValue = string | number | null | HexCodeContainer;
-type HexCodeContainer = {
-    hexCode: string;
-    toString(): string;
-};
-type StylesDescriptor = {
-    [K in keyof CSSStyleDeclaration as [
-        K,
-        CSSStyleDeclaration[K]
-    ] extends [string, string] ? K : never]+?: CSSValue;
-};
-type StyleAccessor = StylesDescriptor & ((styles: StylesDescriptor) => void) & ((property: keyof StylesDescriptor, value: CSSValue) => void);
-type ContentlessTag = "area" | "br" | "hr" | "iframe" | "input" | "textarea" | "img" | "canvas" | "link" | "meta";
-type TagWithHref = "a" | "link";
-type TagWithSrc = "img" | "script" | "iframe" | "video" | "audio";
-type TagWithValue = "input" | "textarea";
-type ContentlessElement = HTMLElementTagNameMap[ContentlessTag];
-type ElementDescriptor<Tag extends string> = {
-    classes?: ElementClassDescriptor;
-    attribs?: Record<string, string | number | boolean>;
-    on?: {
-        [E in keyof HTMLElementEventMap]+?: (event: HTMLElementEventMap[E]) => void;
-    };
-    style?: StylesDescriptor;
-    cssVariables?: Record<string, CSSValue>;
-} & (Tag extends TagWithValue ? {
-    value?: string | number;
-} : {}) & (Tag extends ContentlessTag ? {} : {
-    content?: DOMContent;
-}) & (Tag extends TagWithSrc ? {
-    src?: string;
-} : {}) & (Tag extends TagWithHref ? {
-    href?: string;
-} : {}) & (Tag extends "canvas" ? {
-    width: number;
-    height: number;
-} : {});
-type ElementAPI<T extends HTMLElement> = EventHost<{
-    readonly element: T;
-    classes: DOMTokenList;
-    attribs: {
-        [key: string]: string | null;
-    };
-    style: StyleAccessor;
-    setCSSVariable(table: Record<string, CSSValue>): void;
-    setCSSVariable(variableName: string, value: CSSValue): void;
-    qsa(selector: string): (Element | DomEntity<HTMLElement>)[];
-    remove(): void;
-    getRect(): DOMRect;
-    focus(): void;
-    blur(): void;
-} & (T extends ContentlessElement ? {} : {
-    append(...content: DOMContent[]): void;
-    innerHTML: string;
-    content: DOMContent;
-}) & (T extends HTMLElementTagNameMap[TagWithValue] ? {
-    value: string;
-    select(): void;
-} : {}) & (T extends HTMLCanvasElement ? {
-    width: number;
-    height: number;
-    getContext: HTMLCanvasElement["getContext"];
-} : {}) & (T extends HTMLElementTagNameMap[TagWithSrc] ? {
-    src: string;
-} : {}) & (T extends HTMLElementTagNameMap[TagWithHref] ? {
-    href: string;
-} : {}) & (T extends HTMLMediaElement ? {
-    play(): void;
-    pause(): void;
-    currentTime: number;
-    readonly paused: boolean;
-} : {}), HTMLElementEventMap>;
-type DomHelper = ((<T extends keyof HTMLElementTagNameMap>(tagName: T, descriptor: ElementDescriptor<T>) => DomEntity<HTMLElementTagNameMap[T]>) & (<T extends keyof HTMLElementTagNameMap>(selector: `${T}#${string}`, content?: T extends ContentlessTag ? void : DOMContent) => DomEntity<HTMLElementTagNameMap[T]>) & (<T extends keyof HTMLElementTagNameMap>(selector: `${T}.${string}`, content?: T extends ContentlessTag ? void : DOMContent) => DomEntity<HTMLElementTagNameMap[T]>) & (<T extends keyof HTMLElementTagNameMap>(selector: T, content?: T extends ContentlessTag ? void : DOMContent) => DomEntity<HTMLElementTagNameMap[T]>) & (<T extends HTMLElement>(element: T) => DomEntity<T>) & {
-    [T in keyof HTMLElementTagNameMap]: (descriptor: ElementDescriptor<T>) => DomEntity<HTMLElementTagNameMap[T]>;
-} & {
-    [T in keyof HTMLElementTagNameMap]: T extends ContentlessTag ? () => DomEntity<HTMLElementTagNameMap[T]> : (content?: DOMContent) => DomEntity<HTMLElementTagNameMap[T]>;
-});
-type JelEntityData = {
-    dom: DOMContent;
-};
-type OptionalKeys<T> = {
-    [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
-}[keyof T];
-type Optionals<T> = {
-    [K in OptionalKeys<T>]-?: Exclude<T[K], undefined>;
-};
-type ForbidKey<K extends string | symbol> = Record<string | symbol, any> & Partial<Record<K, never>>;
-type EventHost<API extends object | void, EventDataMap> = (API extends object ? API : {}) & {
-    on<E extends keyof EventDataMap>(eventId: E, handler: (this: JelEntity<EventHost<API, EventDataMap>>, data: EventDataMap[E]) => void): void;
-};
-export declare const $: DomHelper;
-declare const entityDataSymbol: unique symbol;
-export declare function createEntity<API extends object>(content: DOMContent, api: API extends DOMContent ? never : API): JelEntity<API>;
-export declare function createEntity(content: DOMContent): JelEntity<void>;
-export declare function definePart<Spec extends ForbidKey<"on">, API extends ForbidKey<"on"> | void = void, EventDataMap extends Record<string, any> = {}>(defaultOptions: Optionals<Spec>, init: (spec: Required<Spec>, append: (...content: DOMContent[]) => void, trigger: <K extends keyof EventDataMap>(eventId: K, eventData: EventDataMap[K]) => void) => API): PartConstructor<Spec, API, EventDataMap>;
-export {};
+export { DomEntity, ElementClassDescriptor, ElementDescriptor, DOMContent, DomHelper, StyleAccessor, JelEntity } from "./internal/types";
+export { $ } from "./internal/element";
+export { createEntity } from "./internal/util";
+export { createEventSource } from "./internal/emitter";

package/index.js

@@ -1,308 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.$ = void 0;
-exports.createEntity = createEntity;
-exports.definePart = definePart;
-const styleProxy = {
-    get(getStyle, prop) {
-        return getStyle()[prop];
-    },
-    set(getStyle, prop, value) {
-        getStyle()[prop] = value;
-        return true;
-    },
-    apply(getStyle, _, [stylesOrProp, value]) {
-        const style = getStyle();
-        if (typeof stylesOrProp == "object") {
-            Object.entries(stylesOrProp).forEach(([prop, val]) => style[prop] = val);
-            return;
-        }
-        style[stylesOrProp] = value;
-    },
-    deleteProperty(getStyle, prop) {
-        getStyle()[prop] = null;
-        return true;
-    }
-};
-function createElement(tag, descriptor = {}) {
-    if (isContent(descriptor))
-        return createElement(tag, {
-            content: descriptor,
-        });
-    const domElement = document.createElement(tag);
-    const ent = getWrappedElement(domElement);
-    const applyClasses = (classes) => {
-        if (Array.isArray(classes)) {
-            return classes.forEach(c => applyClasses(c));
-        }
-        if (typeof classes == "string") {
-            classes.trim().split(/\s+/).forEach(c => ent.classes.add(c));
-            return;
-        }
-        Object.entries(classes).forEach(([className, state]) => {
-            if (state)
-                applyClasses(className);
-        });
-    };
-    applyClasses(descriptor.classes || []);
-    ["value", "src", "href", "width", "height"].forEach(prop => {
-        if (descriptor[prop] !== undefined)
-            domElement.setAttribute(prop, descriptor[prop]);
-    });
-    // attribs.value / attribs.src / attribs.href override descriptor.*
-    if (descriptor.attribs) {
-        Object.entries(descriptor.attribs).forEach(([k, v]) => {
-            if (v === false) {
-                return;
-            }
-            domElement.setAttribute(k, v === true ? k : v);
-        });
-    }
-    if (descriptor.content !== undefined)
-        recursiveAppend(domElement, descriptor.content);
-    if (descriptor.style) {
-        ent.style(descriptor.style);
-    }
-    if (descriptor.cssVariables) {
-        ent.setCSSVariable(descriptor.cssVariables);
-    }
-    if (descriptor.on) {
-        Object.entries(descriptor.on).forEach(([eventName, handler]) => ent.on(eventName, handler));
-    }
-    return ent;
-}
-;
-exports.$ = new Proxy(createElement, {
-    apply(create, _, [selectorOrTagName, contentOrDescriptor]) {
-        var _a;
-        if (selectorOrTagName instanceof HTMLElement)
-            return getWrappedElement(selectorOrTagName);
-        const tagName = ((_a = selectorOrTagName.match(/^[^.#]*/)) === null || _a === void 0 ? void 0 : _a[0]) || "";
-        if (!tagName)
-            throw new Error("Invalid tag");
-        const matches = selectorOrTagName.slice(tagName.length).match(/[.#][^.#]+/g);
-        const classes = {};
-        const descriptor = {
-            classes,
-            content: contentOrDescriptor,
-        };
-        matches === null || matches === void 0 ? void 0 : matches.forEach((m) => {
-            const value = m.slice(1);
-            if (m[0] == ".") {
-                classes[value] = true;
-            }
-            else {
-                descriptor.attribs = { id: value };
-            }
-        });
-        return create(tagName, descriptor);
-    },
-    get(create, tagName) {
-        return (descriptorOrContent) => {
-            return create(tagName, descriptorOrContent);
-        };
-    }
-});
-const entityDataSymbol = Symbol("jelComponentData");
-const elementWrapCache = new WeakMap();
-const attribsProxy = {
-    get: (element, key) => {
-        return element.getAttribute(key);
-    },
-    set: (element, key, value) => {
-        element.setAttribute(key, value);
-        return true;
-    },
-    has: (element, key) => {
-        return element.hasAttribute(key);
-    },
-    ownKeys: (element) => {
-        return element.getAttributeNames();
-    },
-};
-const recursiveAppend = (parent, c) => {
-    if (c === null)
-        return;
-    if (Array.isArray(c)) {
-        c.forEach(item => recursiveAppend(parent, item));
-        return;
-    }
-    if (isJelEntity(c)) {
-        recursiveAppend(parent, c[entityDataSymbol].dom);
-        return;
-    }
-    if (typeof c == "number")
-        c = c.toString();
-    parent.append(c);
-};
-function getWrappedElement(element) {
-    if (!elementWrapCache.has(element)) {
-        const setCSSVariable = (k, v) => {
-            if (v === null) {
-                element.style.removeProperty("--" + k);
-            }
-            else {
-                element.style.setProperty("--" + k, v);
-            }
-        };
-        const domEntity = {
-            [entityDataSymbol]: {
-                dom: element,
-            },
-            get element() { return element; },
-            on(eventId, handler) {
-                element.addEventListener(eventId, eventData => {
-                    handler.call(domEntity, eventData);
-                });
-            },
-            append(...content) {
-                recursiveAppend(element, content);
-            },
-            remove: () => element.remove(),
-            setCSSVariable(variableNameOrTable, value) {
-                if (typeof variableNameOrTable == "object") {
-                    Object.entries(variableNameOrTable).forEach(([k, v]) => setCSSVariable(k, v));
-                    return;
-                }
-                setCSSVariable(variableNameOrTable, value);
-            },
-            qsa(selector) {
-                const results = [];
-                element.querySelectorAll(selector).forEach((el) => results.push(el instanceof HTMLElement ? getWrappedElement(el) : el));
-                return results;
-            },
-            getRect: () => element.getBoundingClientRect(),
-            focus: () => element.focus(),
-            blur: () => element.blur(),
-            select: () => element.select(),
-            play: () => element.play(),
-            pause: () => element.pause(),
-            getContext(mode, options) {
-                return element.getContext(mode, options);
-            },
-            get content() {
-                return [].slice.call(element.children).map((child) => {
-                    if (child instanceof HTMLElement)
-                        return getWrappedElement(child);
-                    return child;
-                });
-            },
-            set content(v) {
-                element.innerHTML = "";
-                recursiveAppend(element, v);
-            },
-            attribs: new Proxy(element, attribsProxy),
-            get innerHTML() {
-                return element.innerHTML;
-            },
-            set innerHTML(v) {
-                element.innerHTML = v;
-            },
-            get value() {
-                return element.value;
-            },
-            set value(v) {
-                element.value = v;
-            },
-            get href() {
-                return element.href;
-            },
-            set href(v) {
-                element.href = v;
-            },
-            get src() {
-                return element.src;
-            },
-            set src(v) {
-                element.src = v;
-            },
-            get width() {
-                return element.width;
-            },
-            set width(v) {
-                element.width = v;
-            },
-            get height() {
-                return element.height;
-            },
-            set height(v) {
-                element.height = v;
-            },
-            get currentTime() {
-                return element.currentTime;
-            },
-            set currentTime(v) {
-                element.currentTime = v;
-            },
-            get paused() {
-                return element.paused;
-            },
-            style: new Proxy(() => element.style, styleProxy),
-            classes: element.classList,
-        };
-        elementWrapCache.set(element, domEntity);
-    }
-    return elementWrapCache.get(element);
-}
-const isContent = (value) => {
-    if (value === undefined)
-        return false;
-    return typeof value == "string"
-        || typeof value == "number"
-        || !value
-        || value instanceof Element
-        || value instanceof Text
-        || entityDataSymbol in value
-        || Array.isArray(value);
-};
-function isJelEntity(content) {
-    return typeof content == "object" && !!content && entityDataSymbol in content;
-}
-function createEntity(content, api) {
-    if (isContent(api)) {
-        throw new TypeError("API object is already valid content");
-    }
-    return Object.create(api !== null && api !== void 0 ? api : {}, {
-        [entityDataSymbol]: {
-            value: {
-                dom: content
-            }
-        },
-    });
-}
-;
-function definePart(defaultOptions, init) {
-    return ((spec) => {
-        var _a;
-        const fullSpec = Object.assign(Object.assign({}, defaultOptions), spec);
-        const eventHandlers = {};
-        const addEventListener = (eventId, fn) => {
-            if (!eventHandlers[eventId])
-                eventHandlers[eventId] = [];
-            eventHandlers[eventId].push(fn);
-        };
-        if (fullSpec.on)
-            Object.entries(fullSpec.on).forEach(([eventId, handler]) => {
-                addEventListener(eventId, handler);
-            });
-        let entity;
-        const content = [];
-        const append = (...c) => {
-            if (entity)
-                throw new Error("Component root content can only be added during initialisation");
-            content.push(...c);
-        };
-        const trigger = (eventId, data) => {
-            var _a;
-            (_a = eventHandlers[eventId]) === null || _a === void 0 ? void 0 : _a.forEach(fn => fn.call(entity, data));
-        };
-        const api = (_a = init(fullSpec, append, trigger)) !== null && _a !== void 0 ? _a : {};
-        entity = createEntity(content, Object.create(api, {
-            on: {
-                value: addEventListener,
-            }
-        }));
-        return entity;
-    });
-}
-;
+export { $ } from "./internal/element";
+export { createEntity } from "./internal/util";
+export { createEventSource } from "./internal/emitter";

package/internal/element.d.ts

@@ -0,0 +1,2 @@
+import { DomHelper } from "./types";
+export declare const $: DomHelper;

package/internal/element.js

@@ -0,0 +1,220 @@
+import { attribsProxy, eventsProxy, styleProxy } from "./proxy";
+import { entityDataSymbol, isContent, isJelEntity } from "./util";
+const elementWrapCache = new WeakMap();
+const recursiveAppend = (parent, c) => {
+    if (c === null)
+        return;
+    if (Array.isArray(c)) {
+        c.forEach(item => recursiveAppend(parent, item));
+        return;
+    }
+    if (isJelEntity(c)) {
+        recursiveAppend(parent, c[entityDataSymbol].dom);
+        return;
+    }
+    if (typeof c == "number")
+        c = c.toString();
+    parent.append(c);
+};
+function createElement(tag, descriptor = {}) {
+    if (isContent(descriptor))
+        return createElement(tag, {
+            content: descriptor,
+        });
+    const domElement = document.createElement(tag);
+    const ent = getWrappedElement(domElement);
+    const applyClasses = (classes) => {
+        if (Array.isArray(classes)) {
+            return classes.forEach(c => applyClasses(c));
+        }
+        if (typeof classes == "string") {
+            classes.trim().split(/\s+/).forEach(c => ent.classes.add(c));
+            return;
+        }
+        if (classes === undefined)
+            return;
+        Object.entries(classes).forEach(([className, state]) => {
+            if (state)
+                applyClasses(className);
+        });
+    };
+    applyClasses(descriptor.classes || []);
+    ["value", "src", "href", "width", "height", "type", "name"].forEach(prop => {
+        if (descriptor[prop] !== undefined)
+            domElement.setAttribute(prop, descriptor[prop]);
+    });
+    // attribs.value / attribs.src / attribs.href override descriptor.*
+    if (descriptor.attribs) {
+        Object.entries(descriptor.attribs).forEach(([k, v]) => {
+            if (v === false) {
+                return;
+            }
+            domElement.setAttribute(k, v === true ? k : v);
+        });
+    }
+    if (descriptor.content !== undefined)
+        recursiveAppend(domElement, descriptor.content);
+    if (descriptor.style) {
+        ent.style(descriptor.style);
+    }
+    if (descriptor.cssVariables) {
+        ent.setCSSVariable(descriptor.cssVariables);
+    }
+    if (descriptor.on) {
+        Object.entries(descriptor.on).forEach(([eventName, handler]) => ent.events[eventName].apply(handler));
+    }
+    return ent;
+}
+;
+export const $ = new Proxy(createElement, {
+    apply(create, _, [selectorOrTagName, contentOrDescriptor]) {
+        var _a;
+        if (selectorOrTagName instanceof HTMLElement)
+            return getWrappedElement(selectorOrTagName);
+        const tagName = ((_a = selectorOrTagName.match(/^[^.#]*/)) === null || _a === void 0 ? void 0 : _a[0]) || "";
+        if (!tagName)
+            throw new Error("Invalid tag");
+        const matches = selectorOrTagName.slice(tagName.length).match(/[.#][^.#]+/g);
+        const classes = {};
+        const descriptor = {
+            classes,
+            content: contentOrDescriptor,
+        };
+        matches === null || matches === void 0 ? void 0 : matches.forEach((m) => {
+            const value = m.slice(1);
+            if (m[0] == ".") {
+                classes[value] = true;
+            }
+            else {
+                descriptor.attribs = { id: value };
+            }
+        });
+        return create(tagName, descriptor);
+    },
+    get(create, tagName) {
+        return (descriptorOrContent) => {
+            return create(tagName, descriptorOrContent);
+        };
+    }
+});
+function getWrappedElement(element) {
+    if (!elementWrapCache.has(element)) {
+        const setCSSVariable = (k, v) => {
+            if (v === null) {
+                element.style.removeProperty("--" + k);
+            }
+            else {
+                element.style.setProperty("--" + k, v);
+            }
+        };
+        const domEntity = {
+            [entityDataSymbol]: {
+                dom: element,
+            },
+            get element() { return element; },
+            on(eventId, handler) {
+                element.addEventListener(eventId, eventData => {
+                    handler.call(domEntity, eventData);
+                });
+            },
+            append(...content) {
+                recursiveAppend(element, content);
+            },
+            remove: () => element.remove(),
+            setCSSVariable(variableNameOrTable, value) {
+                if (typeof variableNameOrTable == "object") {
+                    Object.entries(variableNameOrTable).forEach(([k, v]) => setCSSVariable(k, v));
+                    return;
+                }
+                setCSSVariable(variableNameOrTable, value);
+            },
+            qsa(selector) {
+                const results = [];
+                element.querySelectorAll(selector).forEach((el) => results.push(el instanceof HTMLElement ? getWrappedElement(el) : el));
+                return results;
+            },
+            getRect: () => element.getBoundingClientRect(),
+            focus: () => element.focus(),
+            blur: () => element.blur(),
+            select: () => element.select(),
+            play: () => element.play(),
+            pause: () => element.pause(),
+            getContext(mode, options) {
+                return element.getContext(mode, options);
+            },
+            get content() {
+                return [].slice.call(element.children).map((child) => {
+                    if (child instanceof HTMLElement)
+                        return getWrappedElement(child);
+                    return child;
+                });
+            },
+            set content(v) {
+                element.innerHTML = "";
+                recursiveAppend(element, v);
+            },
+            attribs: new Proxy(element, attribsProxy),
+            get innerHTML() {
+                return element.innerHTML;
+            },
+            set innerHTML(v) {
+                element.innerHTML = v;
+            },
+            get value() {
+                return element.value;
+            },
+            set value(v) {
+                element.value = v;
+            },
+            get href() {
+                return element.href;
+            },
+            set href(v) {
+                element.href = v;
+            },
+            get src() {
+                return element.src;
+            },
+            set src(v) {
+                element.src = v;
+            },
+            get width() {
+                return element.width;
+            },
+            set width(v) {
+                element.width = v;
+            },
+            get height() {
+                return element.height;
+            },
+            set height(v) {
+                element.height = v;
+            },
+            get currentTime() {
+                return element.currentTime;
+            },
+            set currentTime(v) {
+                element.currentTime = v;
+            },
+            get paused() {
+                return element.paused;
+            },
+            get name() {
+                return element.getAttribute("name");
+            },
+            set name(v) {
+                if (v === null) {
+                    element.removeAttribute("name");
+                }
+                else {
+                    element.setAttribute("name", v);
+                }
+            },
+            style: new Proxy(() => element.style, styleProxy),
+            classes: element.classList,
+            events: new Proxy(element, eventsProxy)
+        };
+        elementWrapCache.set(element, domEntity);
+    }
+    return elementWrapCache.get(element);
+}

package/internal/emitter.d.ts

@@ -0,0 +1,123 @@
+type Handler<T> = (value: T) => void;
+export type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
+export type UnsubscribeFunc = () => void;
+export declare class Emitter<T> {
+    protected onListen: ListenFunc<T>;
+    protected constructor(onListen: ListenFunc<T>);
+    protected transform<R = T>(handler: (value: T, emit: (value: R) => void) => void): (fn: (v: R) => void) => UnsubscribeFunc;
+    /**
+     * Compatibility alias for `apply()` - registers a function to receive emitted values
+     * @param handler
+     * @returns A function to deregister the handler
+     */
+    listen(handler: Handler<T>): UnsubscribeFunc;
+    /**
+     * Registers a function to receive emitted values
+     * @param handler
+     * @returns A function to deregister the handler
+     */
+    apply(handler: Handler<T>): UnsubscribeFunc;
+    /**
+     * Creates a chainable emitter that applies arbitrary transformation to values emitted by its parent
+     * @param mapFunc
+     * @returns Listenable: emits transformed values
+     */
+    map<R>(mapFunc: (value: T) => R): Emitter<R>;
+    /**
+     * Creates a chainable emitter that selectively forwards emissions along the chain
+     * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
+     * @returns Listenable: emits values that pass the filter
+     */
+    filter(check: (value: T) => boolean): Emitter<T>;
+    /**
+     * Creates a chainable emitter that discards emitted values that are the same as the last value emitted by the new emitter
+     * @param compare Optional function that takes the previous and next values and returns true if they should be considered equal
+     *
+     * If no `compare` function is provided, values will be compared via `===`
+     * @returns Listenable: emits non-repeating values
+     */
+    dedupe(compare?: (a: T, b: T) => boolean): Emitter<T>;
+    /**
+     * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
+     *
+     * The callback `cb` is called exactly once per parent emission, regardless of how many listeners are attached to the returned emitter.
+     * All listeners attached to the returned emitter receive the same values as the parent emitter.
+     *
+     * *Note*, the side effect `cb` is only invoked when there is at least one listener attached to the returned emitter
+     *
+     * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
+     * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
+     */
+    tap(cb: Handler<T>): Emitter<T>;
+    /**
+     * Immediately passes this emitter to a callback and returns this emitter
+     *
+     * Allows branching without breaking a composition chain
+     *
+     * @example
+     * ```ts
+     * range
+     *   .tween("0%", "100%")
+     *   .fork(branch => branch
+     *       .map(s => `Loading: ${s}`)
+     *       .apply(s => document.title = s)
+     *   )
+     *   .apply(v => progressBar.style.width = v);
+     * ```
+     * @param cb
+     */
+    fork(cb: (branch: this) => void): this;
+}
+export declare class EventEmitter<T> extends Emitter<T> {
+    constructor(listen: ListenFunc<T>);
+    debounce(ms: number): EventEmitter<T>;
+    throttle(ms: number): EventEmitter<T>;
+    batch(ms: number): Emitter<T[]>;
+    filter(check: (value: T) => boolean): EventEmitter<T>;
+    once(): EventEmitter<T>;
+    scan<S>(updater: (state: S, value: T) => S, initial: S): EventEmitter<S>;
+    buffer(count: number): EventEmitter<T[]>;
+    take(limit: number): EventEmitter<T>;
+    tap(cb: Handler<T>): EventEmitter<T>;
+    takeUntil(notifier: Emitter<any>): Emitter<T>;
+}
+/**
+ * Creates a linked Emitter and emit() pair
+ * @example
+ * ```ts
+ * function createForm(options: { onsubmit?: (data: FormData) => void }) {
+ *   const submitEvents = createEventSource(options.onsubmit);
+ *   const form = $.form({
+ *     on: {
+ *       submit: (e) => {
+ *         e.preventDefault();
+ *         const data = new FormData(e.target);
+ *         submitEvents.emit(data); // emit when form is submitted
+ *       }
+ *     }
+ *   });
+ *
+ *   return createEntity(form, {
+ *     events: {
+ *       submit: submitEvents.emitter
+ *     }
+ *   })
+ * }
+ *
+ * const form = createForm({
+ *   onsubmit: (data) => handleSubmission(data)
+ * });
+ * ```
+ *
+ * @param initialHandler Optional listener automatically applied to the resulting Emitter
+ * @returns
+ */
+export declare function createEventSource<T>(initialHandler?: Handler<T>): {
+    emit: (value: T) => void;
+    emitter: EventEmitter<T>;
+};
+export declare function createListenable<T>(onAddFirst?: () => void, onRemoveLast?: () => void): {
+    listen: (fn: (v: T) => void) => UnsubscribeFunc;
+    emit: (value: T) => void;
+};
+export {};

package/internal/emitter.js

@@ -0,0 +1,279 @@
+export class Emitter {
+    constructor(onListen) {
+        this.onListen = onListen;
+    }
+    transform(handler) {
+        let parentUnsubscribe = null;
+        const parentListen = this.onListen;
+        const { emit, listen } = createListenable(() => parentUnsubscribe = parentListen(value => {
+            handler(value, emit);
+        }), () => {
+            parentUnsubscribe();
+            parentUnsubscribe = null;
+        });
+        return listen;
+    }
+    /**
+     * Compatibility alias for `apply()` - registers a function to receive emitted values
+     * @param handler
+     * @returns A function to deregister the handler
+     */
+    listen(handler) {
+        return this.onListen(handler);
+    }
+    /**
+     * Registers a function to receive emitted values
+     * @param handler
+     * @returns A function to deregister the handler
+     */
+    apply(handler) {
+        return this.onListen(handler);
+    }
+    /**
+     * Creates a chainable emitter that applies arbitrary transformation to values emitted by its parent
+     * @param mapFunc
+     * @returns Listenable: emits transformed values
+     */
+    map(mapFunc) {
+        const listen = this.transform((value, emit) => emit(mapFunc(value)));
+        return new Emitter(listen);
+    }
+    /**
+     * Creates a chainable emitter that selectively forwards emissions along the chain
+     * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
+     * @returns Listenable: emits values that pass the filter
+     */
+    filter(check) {
+        const listen = this.transform((value, emit) => check(value) && emit(value));
+        return new Emitter(listen);
+    }
+    /**
+     * Creates a chainable emitter that discards emitted values that are the same as the last value emitted by the new emitter
+     * @param compare Optional function that takes the previous and next values and returns true if they should be considered equal
+     *
+     * If no `compare` function is provided, values will be compared via `===`
+     * @returns Listenable: emits non-repeating values
+     */
+    dedupe(compare) {
+        let previous = null;
+        const listen = this.transform((value, emit) => {
+            if (!previous || (compare
+                ? !compare(previous.value, value)
+                : (previous.value !== value))) {
+                emit(value);
+                previous = { value };
+            }
+        });
+        return new Emitter(listen);
+    }
+    /**
+     * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
+     *
+     * The callback `cb` is called exactly once per parent emission, regardless of how many listeners are attached to the returned emitter.
+     * All listeners attached to the returned emitter receive the same values as the parent emitter.
+     *
+     * *Note*, the side effect `cb` is only invoked when there is at least one listener attached to the returned emitter
+     *
+     * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
+     * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
+     */
+    tap(cb) {
+        const listen = this.transform((value, emit) => {
+            cb(value);
+            emit(value);
+        });
+        return new Emitter(listen);
+    }
+    /**
+     * Immediately passes this emitter to a callback and returns this emitter
+     *
+     * Allows branching without breaking a composition chain
+     *
+     * @example
+     * ```ts
+     * range
+     *   .tween("0%", "100%")
+     *   .fork(branch => branch
+     *       .map(s => `Loading: ${s}`)
+     *       .apply(s => document.title = s)
+     *   )
+     *   .apply(v => progressBar.style.width = v);
+     * ```
+     * @param cb
+     */
+    fork(cb) {
+        cb(this);
+        return this;
+    }
+}
+export class EventEmitter extends Emitter {
+    constructor(listen) {
+        super(listen);
+    }
+    debounce(ms) {
+        let reset = null;
+        const listen = this.transform((value, emit) => {
+            reset === null || reset === void 0 ? void 0 : reset();
+            const timeout = setTimeout(() => {
+                reset = null;
+                emit(value);
+            }, ms);
+            reset = () => {
+                reset = null;
+                clearTimeout(timeout);
+            };
+        });
+        return new EventEmitter(listen);
+    }
+    throttle(ms) {
+        let lastTime = 0;
+        const listen = this.transform((value, emit) => {
+            const now = Date.now();
+            if (now < lastTime + ms) {
+                lastTime = now;
+                emit(value);
+            }
+        });
+        return new EventEmitter(listen);
+    }
+    batch(ms) {
+        let items = [];
+        let active = false;
+        const listen = this.transform((value, emit) => {
+            items.push(value);
+            if (!active) {
+                active = true;
+                setTimeout(() => {
+                    emit(items);
+                    items = [];
+                    active = false;
+                }, ms);
+            }
+        });
+        return new EventEmitter(listen);
+    }
+    filter(check) {
+        const listen = this.transform((value, emit) => check(value) && emit(value));
+        return new EventEmitter(listen);
+    }
+    once() {
+        const { emit, listen } = createListenable();
+        const unsub = this.apply(v => {
+            unsub();
+            emit(v);
+        });
+        return new EventEmitter(listen);
+    }
+    scan(updater, initial) {
+        let state = initial;
+        const listen = this.transform((value, emit) => {
+            state = updater(state, value);
+            emit(state);
+        });
+        return new EventEmitter(listen);
+    }
+    buffer(count) {
+        let buffer = [];
+        const listen = this.transform((value, emit) => {
+            buffer.push(value);
+            if (buffer.length >= count) {
+                emit(buffer);
+                buffer = [];
+            }
+        });
+        return new EventEmitter(listen);
+    }
+    take(limit) {
+        const { emit, listen } = createListenable();
+        let count = 0;
+        const unsub = this.apply(v => {
+            if (count < limit) {
+                emit(v);
+                count++;
+                if (count >= limit) {
+                    unsub();
+                }
+            }
+        });
+        return new EventEmitter(listen);
+    }
+    tap(cb) {
+        const listen = this.transform((value, emit) => {
+            cb(value);
+            emit(value);
+        });
+        return new EventEmitter(listen);
+    }
+    takeUntil(notifier) {
+        const { emit, listen } = createListenable();
+        const unsub = this.apply(v => {
+            emit(v);
+        });
+        const unsubNotifier = notifier.apply(() => {
+            unsub();
+            unsubNotifier();
+        });
+        return new Emitter(listen);
+    }
+}
+/**
+ * Creates a linked Emitter and emit() pair
+ * @example
+ * ```ts
+ * function createForm(options: { onsubmit?: (data: FormData) => void }) {
+ *   const submitEvents = createEventSource(options.onsubmit);
+ *   const form = $.form({
+ *     on: {
+ *       submit: (e) => {
+ *         e.preventDefault();
+ *         const data = new FormData(e.target);
+ *         submitEvents.emit(data); // emit when form is submitted
+ *       }
+ *     }
+ *   });
+ *
+ *   return createEntity(form, {
+ *     events: {
+ *       submit: submitEvents.emitter
+ *     }
+ *   })
+ * }
+ *
+ * const form = createForm({
+ *   onsubmit: (data) => handleSubmission(data)
+ * });
+ * ```
+ *
+ * @param initialHandler Optional listener automatically applied to the resulting Emitter
+ * @returns
+ */
+export function createEventSource(initialHandler) {
+    const { emit, listen } = createListenable();
+    if (initialHandler)
+        listen(initialHandler);
+    return {
+        emit,
+        emitter: new EventEmitter(listen)
+    };
+}
+export function createListenable(onAddFirst, onRemoveLast) {
+    const handlers = [];
+    const addListener = (fn) => {
+        const unique = { fn };
+        handlers.push(unique);
+        if (onAddFirst && handlers.length == 1)
+            onAddFirst();
+        return () => {
+            const idx = handlers.indexOf(unique);
+            if (idx === -1)
+                throw new Error("Handler already unsubscribed");
+            handlers.splice(idx, 1);
+            if (onRemoveLast && handlers.length == 0)
+                onRemoveLast();
+        };
+    };
+    return {
+        listen: addListener,
+        emit: (value) => handlers.forEach(h => h.fn(value)),
+    };
+}

package/internal/proxy.d.ts

@@ -0,0 +1,3 @@
+export declare const styleProxy: ProxyHandler<() => CSSStyleDeclaration>;
+export declare const attribsProxy: ProxyHandler<HTMLElement>;
+export declare const eventsProxy: ProxyHandler<HTMLElement>;

package/internal/proxy.js

@@ -0,0 +1,55 @@
+import { EventEmitter } from "./emitter";
+export const styleProxy = {
+    get(getStyle, prop) {
+        return getStyle()[prop];
+    },
+    set(getStyle, prop, value) {
+        getStyle()[prop] = value;
+        return true;
+    },
+    apply(getStyle, _, [stylesOrProp, value]) {
+        const style = getStyle();
+        if (typeof stylesOrProp == "object") {
+            Object.entries(stylesOrProp).forEach(([prop, val]) => style[prop] = val);
+            return;
+        }
+        style[stylesOrProp] = value;
+    },
+    deleteProperty(getStyle, prop) {
+        getStyle()[prop] = null;
+        return true;
+    }
+};
+export const attribsProxy = {
+    get: (element, key) => {
+        return element.getAttribute(key);
+    },
+    set: (element, key, value) => {
+        element.setAttribute(key, value);
+        return true;
+    },
+    has: (element, key) => {
+        return element.hasAttribute(key);
+    },
+    ownKeys: (element) => {
+        return element.getAttributeNames();
+    },
+};
+export const eventsProxy = {
+    get: (element, key) => {
+        if (key == "addEventListener") {
+            return (name, handler) => element.addEventListener(name, handler);
+        }
+        if (key == "removeEventListener") {
+            return (name, handler) => element.removeEventListener(name, handler);
+        }
+        const listen = (handler) => {
+            const wrappedHandler = (event) => handler(event);
+            element.addEventListener(key, wrappedHandler);
+            return () => {
+                element.removeEventListener(key, wrappedHandler);
+            };
+        };
+        return new EventEmitter(listen);
+    }
+};

package/internal/types.d.ts

@@ -0,0 +1,126 @@
+import { EventEmitter } from "./emitter";
+import { entityDataSymbol } from "./util";
+export type ElementClassDescriptor = string | Record<string, boolean | undefined> | undefined | ElementClassDescriptor[];
+export type DOMContent = number | null | string | Element | JelEntity<object> | Text | DOMContent[];
+export type DomEntity<T extends HTMLElement> = JelEntity<ElementAPI<T>>;
+type CSSValue = string | number | null | HexCodeContainer;
+type HexCodeContainer = {
+    hexCode: string;
+    toString(): string;
+};
+export type StylesDescriptor = {
+    [K in keyof CSSStyleDeclaration as [
+        K,
+        CSSStyleDeclaration[K]
+    ] extends [string, string] ? K : never]+?: CSSValue;
+};
+export type StyleAccessor = StylesDescriptor & ((styles: StylesDescriptor) => void) & ((property: keyof StylesDescriptor, value: CSSValue) => void);
+type ContentlessTag = "area" | "br" | "hr" | "iframe" | "input" | "textarea" | "img" | "canvas" | "link" | "meta" | "source" | "embed" | "track" | "base";
+type TagWithHref = "a" | "link" | "base";
+type TagWithSrc = "img" | "script" | "iframe" | "video" | "audio" | "embed" | "source" | "track";
+type TagWithValue = "input" | "textarea";
+type TagWithWidthHeight = "canvas" | "img" | "embed" | "iframe" | "video";
+type TagWithType = "input" | "source" | "button";
+type TagWithName = 'input' | 'textarea' | 'select' | 'form';
+type ContentlessElement = HTMLElementTagNameMap[ContentlessTag];
+export type ElementDescriptor<Tag extends string> = {
+    classes?: ElementClassDescriptor;
+    attribs?: Record<string, string | number | boolean>;
+    on?: {
+        [E in keyof HTMLElementEventMap]+?: (event: HTMLElementEventMap[E]) => void;
+    };
+    style?: StylesDescriptor;
+    cssVariables?: Record<string, CSSValue>;
+} & (Tag extends TagWithValue ? {
+    value?: string | number;
+} : {}) & (Tag extends ContentlessTag ? {} : {
+    content?: DOMContent;
+}) & (Tag extends TagWithSrc ? {
+    src?: string;
+} : {}) & (Tag extends TagWithHref ? {
+    href?: string;
+} : {}) & (Tag extends TagWithWidthHeight ? {
+    width?: number;
+    height?: number;
+} : {}) & (Tag extends TagWithType ? {
+    type?: string;
+} : {}) & (Tag extends TagWithName ? {
+    name?: string;
+} : {});
+type ElementAPI<T extends HTMLElement> = {
+    readonly element: T;
+    readonly classes: DOMTokenList;
+    readonly attribs: {
+        [key: string]: string | null;
+    };
+    readonly events: EventsAccessor;
+    readonly style: StyleAccessor;
+    setCSSVariable(variableName: string, value: CSSValue): void;
+    setCSSVariable(table: Record<string, CSSValue>): void;
+    qsa(selector: string): (Element | DomEntity<HTMLElement>)[];
+    remove(): void;
+    getRect(): DOMRect;
+    focus(): void;
+    blur(): void;
+    on<E extends keyof HTMLElementEventMap>(eventId: E, handler: (this: ElementAPI<T>, data: HTMLElementEventMap[E]) => void): void;
+} & (T extends ContentlessElement ? {} : {
+    append(...content: DOMContent[]): void;
+    innerHTML: string;
+    content: DOMContent;
+}) & (T extends HTMLElementTagNameMap[TagWithValue] ? {
+    value: string;
+    select(): void;
+} : {}) & (T extends HTMLCanvasElement ? {
+    width: number;
+    height: number;
+    getContext: HTMLCanvasElement["getContext"];
+} : {}) & (T extends HTMLElementTagNameMap[TagWithSrc] ? {
+    src: string;
+} : {}) & (T extends HTMLElementTagNameMap[TagWithHref] ? {
+    href: string;
+} : {}) & (T extends HTMLMediaElement ? {
+    play(): void;
+    pause(): void;
+    currentTime: number;
+    readonly paused: boolean;
+} : {}) & (T extends HTMLElementTagNameMap[TagWithName] ? {
+    name: string | null;
+} : {});
+export type DomHelper = ((
+/**
+ * Creates an element of the specified tag
+ */
+<T extends keyof HTMLElementTagNameMap>(tagName: T, descriptor: ElementDescriptor<T>) => DomEntity<HTMLElementTagNameMap[T]>) & (
+/**
+ * Creates an element of the specified tag
+ */
+<T extends keyof HTMLElementTagNameMap>(tagName: T) => DomEntity<HTMLElementTagNameMap[T]>) & (
+/**
+ * Creates an element with ID and classes as specified by a selector-like string
+ */
+<T extends keyof HTMLElementTagNameMap>(selector: `${T}#${string}`, content?: T extends ContentlessTag ? void : DOMContent) => DomEntity<HTMLElementTagNameMap[T]>) & (
+/**
+ * Creates an element with ID and classes as specified by a selector-like string
+ */
+<T extends keyof HTMLElementTagNameMap>(selector: `${T}.${string}`, content?: T extends ContentlessTag ? void : DOMContent) => DomEntity<HTMLElementTagNameMap[T]>) & (
+/**
+ * Wraps an existing element as a DomEntity
+ */
+<T extends HTMLElement>(element: T) => DomEntity<T>) & {
+    [T in keyof HTMLElementTagNameMap]: (descriptor: ElementDescriptor<T>) => DomEntity<HTMLElementTagNameMap[T]>;
+} & {
+    [T in keyof HTMLElementTagNameMap]: T extends ContentlessTag ? () => DomEntity<HTMLElementTagNameMap[T]> : (content?: DOMContent) => DomEntity<HTMLElementTagNameMap[T]>;
+});
+type JelEntityData = {
+    dom: DOMContent;
+};
+export type JelEntity<API extends object | void> = (API extends void ? {} : API) & {
+    readonly [entityDataSymbol]: JelEntityData;
+};
+export type EventsAccessor = {
+    [K in keyof HTMLElementEventMap]: EventEmitter<HTMLElementEventMap[K]>;
+} & {
+    addEventListener<K extends keyof HTMLElementEventMap>(eventName: K, listener: (event: HTMLElementEventMap[K]) => void): void;
+    removeEventListener<K extends keyof HTMLElementEventMap>(eventName: K, listener: (event: HTMLElementEventMap[K]) => void): void;
+};
+export {};

package/internal/types.js

@@ -0,0 +1 @@
+import { entityDataSymbol } from "./util";

package/internal/util.d.ts

@@ -0,0 +1,11 @@
+import { DOMContent, ElementDescriptor, JelEntity } from "./types";
+export declare const entityDataSymbol: unique symbol;
+export declare const isContent: (value: DOMContent | ElementDescriptor<string> | undefined) => value is DOMContent;
+export declare function isJelEntity(content: DOMContent): content is JelEntity<object>;
+/**
+ * Wraps an object such that it can be appended as DOM content while retaining its original API
+ * @param content
+ * @param api
+ */
+export declare function createEntity<API extends object>(content: DOMContent, api: API extends DOMContent ? never : API): JelEntity<API>;
+export declare function createEntity(content: DOMContent): JelEntity<void>;

package/internal/util.js

@@ -0,0 +1,28 @@
+export const entityDataSymbol = Symbol("jelComponentData");
+export const isContent = (value) => {
+    if (value === undefined)
+        return false;
+    return typeof value == "string"
+        || typeof value == "number"
+        || !value
+        || value instanceof Element
+        || value instanceof Text
+        || entityDataSymbol in value
+        || (Array.isArray(value) && value.every(isContent));
+};
+export function isJelEntity(content) {
+    return typeof content == "object" && !!content && entityDataSymbol in content;
+}
+export function createEntity(content, api) {
+    if (isContent(api)) {
+        throw new TypeError("API object is already valid content");
+    }
+    return Object.create(api !== null && api !== void 0 ? api : {}, {
+        [entityDataSymbol]: {
+            value: {
+                dom: content
+            }
+        },
+    });
+}
+;

package/package.json

@@ -1,12 +1,21 @@
 {
   "name": "@xtia/jel",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "repository": {
     "url": "https://github.com/tiadrop/jel-ts",
     "type": "github"
   },
+  "sideEffects": false,
+  "types": "./index.d.ts",
+  "main": "./index.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./internal/*": null
+  },
   "description": "Lightweight DOM manipulation and componentisation",
-  "main": "index.js",
   "keywords": [
     "dom"
   ],