@xtia/jel 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# Jel
+## Or, How I Learned To Stop Worrying And Love The DOM
+### TypeScript Edition
+
+Jel is a thin layer over the DOM to simplify element structure creation, manipulation and componentisation with 'vanilla' TS.
+
+See [demo/index.ts](demo/index.ts) for example operation. Compare with [resulting page](https://aleta.codes/jel-ts-demo/).
+
+## `$` basic use:
+
+```bash
+$ npm i @xtia/jel
+```
+
+`$.[tagname](details)` produces an element of `<tagname>`. `details` can be content of various types or a descriptor object.
+
+```ts
+import { $ } from "jel-ts";
+
+body.append($.form([
+    $.h2("Sign in"),
+    $.label("Email"),
+    $.input({ attribs: { name: "email" }}),
+    $.label("Password"),
+    $.input({ attribs: { name: "password", type: "password" }}),
+    $.button("Sign in"),
+    $.a({
+        content: ["Having trouble? ", $.strong("Recover account")],
+        attribs: {
+            href: "/recover-account",
+        }
+    })
+]));
+
+body.append([
+    $.h2("Files"),
+    $.ul(
+        files.map(file => $.li(
+            $.a({
+                content: file.name,
+                attribs: {
+                    href: `/files/${file.name}`,
+                }
+            })
+        ))
+    )
+])
+
+```

package/index.d.ts

@@ -0,0 +1,50 @@
+export type ElementClassSpec = string | Record<string, boolean> | ElementClassSpec[];
+export type DOMContent = number | null | string | Element | JelEntity<object, any> | Text | DOMContent[];
+export type DomEntity<T extends HTMLElement> = JelEntity<ElementAPI<T>, HTMLElementEventMap>;
+type Classes = string | Record<string, boolean> | Classes[];
+type PartFn<Spec, API extends {}, EventDataMap> = (spec?: Partial<Spec & CommonOptions<EventDataMap>>) => JelEntity<API, EventDataMap>;
+type CommonOptions<EventDataMap> = {
+    on?: Partial<{
+        [EventID in keyof EventDataMap]: (data: EventDataMap[EventID]) => void;
+    }>;
+};
+type JelEntity<API extends {}, EventDataMap> = API & {
+    on<E extends keyof EventDataMap>(eventId: E, handler: (this: JelEntity<API, EventDataMap>, data: EventDataMap[E]) => void): void;
+    readonly [componentDataSymbol]: JelComponentData;
+};
+interface ElementDescriptor {
+    classes?: Classes;
+    content?: DOMContent;
+    attribs?: Record<string, string | number | boolean>;
+    on?: Partial<{
+        [E in keyof HTMLElementEventMap]: (event: HTMLElementEventMap[E]) => void;
+    }>;
+    style?: Partial<{
+        [key in keyof CSSStyleDeclaration]: string | number;
+    }> & Record<string, string | number>;
+}
+type DomHelper = ((<T extends keyof HTMLElementTagNameMap>(tagName: T, descriptor: ElementDescriptor) => HTMLElementTagNameMap[T]) & ((selector: string, content?: DOMContent) => DomEntity<any>) & (<T extends HTMLElement>(element: T) => DomEntity<T>) & {
+    [T in keyof HTMLElementTagNameMap]: (descriptor: ElementDescriptor) => DomEntity<HTMLElementTagNameMap[T]>;
+} & {
+    [T in keyof HTMLElementTagNameMap]: (content?: DOMContent) => DomEntity<HTMLElementTagNameMap[T]>;
+});
+type JelComponentData = {
+    dom: DOMContent;
+};
+export declare const $: DomHelper;
+declare const componentDataSymbol: unique symbol;
+type ElementAPI<T extends HTMLElement> = {
+    element: T;
+    content: DOMContent;
+    classes: DOMTokenList;
+    attribs: {
+        [key: string]: string | null;
+    };
+    style: CSSStyleDeclaration;
+    innerHTML: string;
+    qsa(selector: string): DomEntity<any>[];
+    append(...content: DOMContent[]): void;
+    remove(): void;
+};
+export declare function definePart<Spec, API extends object, EventDataMap extends Record<string, any> = {}>(defaultOptions: Spec, init: (spec: Spec, append: (content: DOMContent) => void, trigger: <K extends keyof EventDataMap>(eventId: K, eventData: EventDataMap[K]) => void) => API | void): PartFn<Spec, API, EventDataMap>;
+export {};

package/index.js

@@ -0,0 +1,242 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.$ = void 0;
+exports.definePart = definePart;
+function createElement(tag, descriptor) {
+    if (descriptor === void 0) { descriptor = {}; }
+    if (isContent(descriptor))
+        descriptor = { content: descriptor };
+    var ent = getWrappedElement(document.createElement(tag));
+    var applyClasses = function (classes) {
+        if (Array.isArray(classes))
+            return classes.forEach(function (c) { return applyClasses(c); });
+        if (typeof classes == "string") {
+            classes.trim().split(/\s+/).forEach(function (c) { return ent.classes.add(c); });
+            return;
+        }
+        Object.entries(classes).forEach(function (_a) {
+            var className = _a[0], state = _a[1];
+            if (state)
+                applyClasses(className);
+        });
+    };
+    applyClasses(descriptor.classes || []);
+    if (descriptor.attribs)
+        Object.entries(descriptor.attribs).forEach(function (_a) {
+            var k = _a[0], v = _a[1];
+            if (v === false) {
+                return;
+            }
+            ent.element.setAttribute(k, v === true ? k : v);
+        });
+    var addContent = function (content) {
+        if (Array.isArray(content))
+            return content.forEach(function (c) { return addContent(c); });
+        if (content)
+            ent.append(content);
+    };
+    if (descriptor.content)
+        addContent(descriptor.content);
+    descriptor.style && Object.entries(descriptor.style).forEach(function (_a) {
+        var prop = _a[0], val = _a[1];
+        if (/\-/.test(prop)) {
+            ent.element.style.setProperty(prop, val.toString());
+        }
+        else {
+            ent.element.style[prop] = val;
+        }
+    });
+    descriptor.on && Object.entries(descriptor.on).forEach(function (_a) {
+        var eventName = _a[0], handler = _a[1];
+        return ent.on(eventName, handler);
+    });
+    return ent;
+}
+;
+var isContent = function (value) {
+    return ["string", "number"].includes(typeof value)
+        || value instanceof Element
+        || value instanceof Text
+        || Array.isArray(value)
+        || !value;
+};
+exports.$ = new Proxy(createElement, {
+    apply: function (create, _0, _a) {
+        var _b;
+        var selectorOrTagName = _a[0], contentOrDescriptor = _a[1];
+        if (selectorOrTagName instanceof HTMLElement)
+            return getWrappedElement(selectorOrTagName);
+        var tagName = ((_b = selectorOrTagName.match(/^[^.#]*/)) === null || _b === void 0 ? void 0 : _b[0]) || "";
+        if (!tagName)
+            throw new Error("Invalid tag");
+        var matches = selectorOrTagName.slice(tagName.length).match(/[.#][^.#]+/g);
+        var classes = {};
+        var descriptor = {
+            classes: classes,
+            content: contentOrDescriptor,
+        };
+        matches === null || matches === void 0 ? void 0 : matches.forEach(function (m) {
+            var value = m.slice(1);
+            if (m[0] == ".") {
+                classes[value] = true;
+            }
+            else {
+                descriptor.attribs = { id: value };
+            }
+        });
+        return create(tagName, descriptor);
+    },
+    get: function (create, tagName) {
+        return function (descriptorOrContent) {
+            return create(tagName, descriptorOrContent);
+        };
+    }
+});
+var componentDataSymbol = Symbol("jelComponentData");
+var elementWrapCache = new WeakMap();
+function definePart(defaultOptions, init) {
+    return (function (partialSpec) {
+        var _a, _b;
+        if (partialSpec === void 0) { partialSpec = {}; }
+        var spec = __assign(__assign({}, defaultOptions), partialSpec);
+        var eventHandlers = {};
+        var addEventListener = function (eventId, fn) {
+            if (!eventHandlers[eventId])
+                eventHandlers[eventId] = [];
+            eventHandlers[eventId].push(fn);
+        };
+        if (spec.on)
+            Object.entries(spec.on).forEach(function (_a) {
+                var eventId = _a[0], handler = _a[1];
+                addEventListener(eventId, handler);
+            });
+        var entity;
+        var content = [];
+        var append = function (c) {
+            if (entity)
+                throw new Error("Component root content can only be added during initialisation");
+            content.push(c);
+        };
+        var trigger = function (eventId, data) {
+            var _a;
+            (_a = eventHandlers[eventId]) === null || _a === void 0 ? void 0 : _a.forEach(function (fn) { return fn.call(entity, data); });
+        };
+        var api = init(spec, append, trigger);
+        entity = api ? Object.create(api, (_a = {},
+            _a[componentDataSymbol] = {
+                value: {
+                    dom: content
+                }
+            },
+            _a)) : (_b = {},
+            _b[componentDataSymbol] = {
+                dom: content
+            },
+            _b);
+        return entity;
+    });
+}
+;
+var attribsProxy = {
+    get: function (element, key) {
+        return element.getAttribute(key);
+    },
+    set: function (element, key, value) {
+        element.setAttribute(key, value);
+        return true;
+    }
+};
+function getWrappedElement(element) {
+    var _a;
+    if (!elementWrapCache.has(element)) {
+        var recursiveAppend_1 = function (c) {
+            if (c === undefined)
+                debugger;
+            if (c === null)
+                return;
+            if (Array.isArray(c)) {
+                c.forEach(function (item) { return recursiveAppend_1(item); });
+                return;
+            }
+            if (isJelEntity(c)) {
+                recursiveAppend_1(c[componentDataSymbol].dom);
+                return;
+            }
+            if (typeof c == "number")
+                c = c.toString();
+            element.append(c);
+        };
+        var domEntity_1 = (_a = {},
+            _a[componentDataSymbol] = {
+                dom: element,
+            },
+            Object.defineProperty(_a, "element", {
+                get: function () { return element; },
+                enumerable: false,
+                configurable: true
+            }),
+            _a.on = function (eventId, handler) {
+                element.addEventListener(eventId, function (eventData) {
+                    handler.call(domEntity_1, eventData);
+                });
+            },
+            _a.append = function () {
+                var content = [];
+                for (var _i = 0; _i < arguments.length; _i++) {
+                    content[_i] = arguments[_i];
+                }
+                recursiveAppend_1(content);
+            },
+            _a.remove = function () {
+                element.remove();
+            },
+            _a.classes = element.classList,
+            _a.qsa = function (selector) {
+                return [].slice.call(element.querySelectorAll(selector)).map(function (el) { return getWrappedElement(el); });
+            },
+            Object.defineProperty(_a, "content", {
+                get: function () {
+                    return [].slice.call(element.children).map(function (child) {
+                        if (child instanceof HTMLElement)
+                            return getWrappedElement(child);
+                        return child;
+                    });
+                },
+                set: function (v) {
+                    element.innerHTML = "";
+                    recursiveAppend_1(v);
+                },
+                enumerable: false,
+                configurable: true
+            }),
+            _a.attribs = new Proxy(element, attribsProxy),
+            Object.defineProperty(_a, "innerHTML", {
+                get: function () {
+                    return element.innerHTML;
+                },
+                set: function (v) {
+                    element.innerHTML = v;
+                },
+                enumerable: false,
+                configurable: true
+            }),
+            _a.style = element.style,
+            _a);
+        elementWrapCache.set(element, domEntity_1);
+    }
+    return elementWrapCache.get(element);
+}
+function isJelEntity(content) {
+    return typeof content == "object" && !!content && componentDataSymbol in content;
+}

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@xtia/jel",
+  "version": "0.1.0",
+  "description": "Lightweight DOM wrapper",
+  "main": "index.js",
+  "keywords": [
+    "dom"
+  ],
+  "author": "Aleta Lovelace",
+  "license": "MIT"
+}