@lordfokas/yrframe 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 LordFokas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,2 @@
+# yrframe
+A Typescript class-based WebComponents library using Material Design

package/dist/Component.js

@@ -0,0 +1,74 @@
+import { ComponentEvents } from "./ComponentEvents.js";
+import { ComponentFactory } from "./ComponentFactory.js";
+const evt = Symbol('evt');
+export class Component extends HTMLElement {
+    /** Attribute Event Qualifier chars. Attributes starting with this are special. */
+    static AEQ = 'yr:';
+    [evt];
+    events() {
+        return this[evt];
+    }
+    constructor(props, defaults) {
+        super();
+        this[evt] = new ComponentEvents(this);
+        const all = {};
+        // Assign all defaults to object and overwrite with existing values in provided props
+        if (defaults)
+            Object.assign(all, defaults);
+        if (props)
+            Object.assign(all, props);
+        const attrs = {};
+        for (const [k, v] of Object.entries(all)) {
+            if (!k.startsWith(Component.AEQ)) {
+                attrs[k] = v;
+            }
+        }
+        ComponentFactory.setAttributesAndEvents(this, attrs);
+    }
+    /** Remove all children nodes. */
+    clearChildren() {
+        this.innerHTML = "";
+    }
+    isDisabled() {
+        return this.hasAttribute("disabled");
+    }
+    /** HTML5 Custom Element lifecycle callback (remove from page) */
+    disconnectedCallback() {
+        this[evt].disconnect();
+    }
+    /** HTML5 Custom Element lifecycle callback (add to page) */
+    connectedCallback() {
+        this[evt].connect();
+        this.redraw();
+    }
+    /** Draw this component's internals. Should return only children nodes. */
+    render() { return null; }
+    /** Redraw this component. Works by deleting all children, calling render() and appending the results. */
+    redraw() {
+        const child = this.render();
+        this.clearChildren();
+        if (child) {
+            if (Array.isArray(child)) {
+                ComponentFactory.appendChildren(this, child);
+            }
+            else {
+                ComponentFactory.appendChildren(this, [child]);
+            }
+        }
+        this.inject();
+    }
+    /** Called after redraw() to do special manipulation of children nodes. */
+    inject() { }
+    /** Get this component's real width in pixels. */
+    width() {
+        return parseFloat(getComputedStyle(this, null).width.replace("px", ""));
+    }
+    /** Get this component's real height in pixels. */
+    height() {
+        return parseFloat(getComputedStyle(this, null).height.replace("px", ""));
+    }
+    /** Shortcut to register this component with a given tag name */
+    static register(tag) {
+        window.customElements.define(tag, this);
+    }
+}

package/dist/ComponentEvents.js

@@ -0,0 +1,165 @@
+import { EventBus, EventListener } from '@lordfokas/event-bus';
+class PersistentListener extends EventListener {
+    type;
+    constructor(type, callback, nice) {
+        super(callback, nice);
+        this.type = type;
+    }
+}
+/**
+ * Event manager for component special functions.
+ * A developer isn't meant to directly interface with this class,
+ * except by calling Component.events()
+ */
+export class ComponentEvents {
+    listeners = [];
+    sources = {};
+    triggers = {};
+    component;
+    owner;
+    constructor(component) {
+        this.component = component;
+        this.owner = component.constructor.name;
+    }
+    /** Called by the component when entering DOM */
+    connect() {
+        this.listeners.forEach(l => EventBus.GLOBAL.subscribe(l.type, l));
+    }
+    /** Called by the component when leaving DOM */
+    disconnect() {
+        this.listeners.forEach(l => EventBus.GLOBAL.unsubscribe(l));
+    }
+    /** Set up and attach a listener, given a configuration  */
+    createListener(target, name, handler) {
+        const [type, path, nice] = target;
+        this.listeners.push(new PersistentListener(type, event => {
+            handler.call(this.component, event.traverse(...path), event);
+        }, nice).named(name, this.owner));
+    }
+    /** Enforce mandatory targets and skip missing optional ones. */
+    skip(target, name, kind, optional) {
+        if (!target) {
+            if (optional)
+                return true;
+            else
+                throw new Error(`Missing config for mandatory ${kind} '${name}' at '${this.owner}'`);
+        }
+        return false;
+    }
+    /** Attach a generic listener for an event. */
+    attachListener(target, handler, name, kind, optional) {
+        if (this.skip(target, name, kind, optional))
+            return;
+        this.createListener(target, name, handler);
+    }
+    attachGeneric(target, handler, name, optional) {
+        this.attachListener(target, handler, "generic listener", optional);
+    }
+    attachConsumer(target, handler, name, optional) {
+        this.attachListener(target, handler, "consumer", optional);
+    }
+    /** Attach a listener that enriches the target event with data from this component. */
+    attachSupplier(target, source, name, optional) {
+        if (this.skip(target, name, "supplier", optional))
+            return;
+        const [type, path, nice] = target;
+        this.listeners.push(new PersistentListener(type, event => {
+            const path = target[1];
+            const data = source.call(this);
+            if (path.length == 0)
+                event.with(data);
+            else if (path.length == 1)
+                event.with({ [path[0]]: data });
+            else if (path.length > 1)
+                throw new Error("Unsupported path length > 1 for suppliers");
+        }, nice).named(name, this.owner));
+    }
+    /**
+     * Attach a listener that removes data from an event if a predicate passes.
+     * If the target configuration has no path, the whole event is stopped instead.
+     */
+    attachRemover(target, predicate, name, optional) {
+        if (this.skip(target, name, "remover", optional))
+            return;
+        const [type, path, nice] = target;
+        this.listeners.push(new PersistentListener(type, event => {
+            const path = target[1];
+            if (!predicate.call(this))
+                return;
+            if (path.length == 0)
+                event.stop(`Halted by '${name}' at '${this.owner}'`);
+            else if (path.length == 1)
+                delete event[path[0]];
+            else if (path.length > 1)
+                throw new Error("Unsupported path length > 1 for removers");
+        }, nice).named(name, this.owner));
+    }
+    /** Attach a listener that disables a component based on a boolean event field. */
+    attachDisabler(target, source, name, optional) {
+        if (this.skip(target, name, "disabler", optional))
+            return;
+        this.createListener(target, name, (value, _) => {
+            if (typeof value !== "boolean")
+                return;
+            const element = source.call(this);
+            if (value) {
+                element.setAttribute("disabled", "");
+            }
+            else {
+                element.removeAttribute("disabled");
+            }
+        });
+    }
+    /** Create a function that will fire an event and process data from it. */
+    attachSource(target, name, optional) {
+        if (this.skip(target, name, "source", optional))
+            return;
+        const [type, path] = target;
+        this.sources[name] = (callback) => {
+            new type().publish().then(event => {
+                callback.call(this.component, event.traverse(...path), event);
+            });
+        };
+    }
+    /** Create a fake source function that supplies a static or local value. */
+    attachStatic(value, source, name, optional) {
+        if (value === undefined) {
+            if (optional)
+                return;
+            else
+                throw new Error(`Missing config for mandatory static '${name}' at '${this.owner}'`);
+        }
+        this.sources[name] = (callback) => {
+            callback.call(this.component, source.call(this.component), undefined);
+        };
+    }
+    /** Fire a source function and process the returned data. */
+    seek(name, callback) {
+        if (!this.sources[name])
+            callback.call(this.component, undefined, undefined);
+        else
+            this.sources[name].call(callback);
+    }
+    /** Create a function that will fire an event to export data. */
+    attachTrigger(target, name, optional) {
+        if (this.skip(target, name, "trigger", optional))
+            return;
+        const [type, path] = target;
+        this.triggers[name] = (data, parent) => {
+            const event = new type();
+            if (parent)
+                event.parent(parent);
+            if (path.length == 0)
+                event.with(data);
+            if (path.length == 1)
+                event.with({ [path[0]]: data });
+            if (path.length > 1)
+                throw new Error("Unsupported path length > 1 for triggers");
+            event.publish();
+        };
+    }
+    /** Fire a trigger function with the given data. */
+    fire(name, data = {}, parent) {
+        this.triggers[name].call(this.component, data, parent);
+    }
+}

package/dist/ComponentFactory.js

@@ -0,0 +1,75 @@
+import { Facade } from "./Facade.js";
+/**
+ * JSX / TSX component factory.
+ * Should not be invoked manually, is used by TSC when building the project.
+ */
+export class ComponentFactory {
+    static make(tag, props, ...children) {
+        if (tag === Array)
+            return children; // Allow returning multiple elements from render()
+        // Initialize Element
+        let element;
+        if (typeof tag === 'function') { // Construct class based components
+            if (tag.prototype instanceof Facade) {
+                element = new tag(props ?? {}).content();
+            }
+            else {
+                element = new tag(props ?? {});
+            }
+        }
+        else { // Construct vanilla HTML tag
+            element = document.createElement(tag);
+            this.setAttributesAndEvents(element, props);
+        }
+        // Append children if any
+        if (children && children.length > 0) {
+            this.appendChildren(element, children);
+        }
+        return element;
+    }
+    /** Apply vanilla HTML attributes and event callback functions. There is no component level logic here. */
+    static setAttributesAndEvents(element, props) {
+        if (props)
+            for (const key in props) {
+                const value = props[key];
+                if (value === undefined)
+                    continue; // Skip empty prop
+                if (typeof value === "function") { // Set vanilla HTML event callback function
+                    element[key] = value;
+                }
+                else {
+                    element.setAttribute(key, value);
+                }
+            }
+    }
+    /** Logic for appending children to a parent element according to the possible returns of render() */
+    static appendChildren(element, children) {
+        for (const child of children) {
+            // Allow returning null from render() when there is nothing to do
+            if (child === null)
+                continue;
+            // Disallow returning undefined to prevent mistakes being ignored. No-ops must explicitely return null.
+            if (child === undefined)
+                throw new Error("An element's child cannot be undefined");
+            if (Array.isArray(child)) { // Allow returning multiple elements from render()
+                this.appendChildren(element, child);
+            }
+            else {
+                element.append(child);
+            }
+        }
+    }
+}
+/**
+ * ## Here be Shenanigans
+ * In the event your TSC refuses to find ComponentFactory.make
+ * and insists on using React.createElement, fear not:
+ *
+ * Just `import { FakeReact as React }` and call it a day.
+ *
+ * At least until you can be arsed to figure it out...
+ * `¯\_(ツ)_/¯`
+ */
+export class FakeReact {
+    static createElement = ComponentFactory.make;
+}

package/dist/Facade.js

@@ -0,0 +1,51 @@
+import { ComponentEvents } from "./ComponentEvents.js";
+import { ComponentFactory } from "./ComponentFactory.js";
+const evt = Symbol('evt');
+/**
+ * Fake component that constructs and returns another component instead.
+ * Used for aliasing and adapting components from other libraries.
+ */
+export class Facade {
+    static AEQ = 'yr:'; // TODO: centralize these
+    node;
+    isCustom;
+    events() {
+        return this.node[evt];
+    }
+    constructor(tag, props, defaults) {
+        const node = this.node = document.createElement(tag);
+        const events = node[evt] = new ComponentEvents(node);
+        this.isCustom = tag.includes('-');
+        // Attach to existing lifecycle callbacks.
+        if (this.isCustom) {
+            const { connectedCallback, disconnectedCallback } = node;
+            node.connectedCallback = () => {
+                events.connect();
+                return connectedCallback?.call(node);
+            };
+            node.disconnectedCallback = () => {
+                events.disconnect();
+                return disconnectedCallback?.call(node);
+            };
+        }
+        else { // TODO: rethink this, there's clearly use cases for it.
+            throw new Error(`Facade for native element '${tag}' cannot hook to lifecycle calls.`);
+        }
+        const all = {};
+        // Assign all defaults to object and overwrite with existing values in provided props
+        if (defaults)
+            Object.assign(all, defaults);
+        if (props)
+            Object.assign(all, props);
+        const attrs = {};
+        for (const [k, v] of Object.entries(all)) {
+            if (!k.startsWith(Facade.AEQ)) {
+                attrs[k] = v;
+            }
+        }
+        ComponentFactory.setAttributesAndEvents(node, attrs);
+    }
+    content() {
+        return this.node;
+    }
+}

package/dist/utils.js

@@ -0,0 +1,3 @@
+export function has($) {
+    return $ !== undefined;
+}

package/dist/yrframe.js

@@ -0,0 +1,3 @@
+export { Component } from './Component.js';
+export { ComponentEvents } from './ComponentEvents.js';
+export { ComponentFactory, FakeReact } from './ComponentFactory.js';

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@lordfokas/yrframe",
+  "version": "0.1.0",
+  "description": "A Typescript class-based WebComponents library using Material Design.",
+  "main": "dist/yrframe.js",
+  "scripts": {
+    "prebuild": "rm -rf ./dist",
+    "build": "tsc -p ./tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "material",
+    "design",
+    "components",
+    "typescript"
+  ],
+  "author": "LordFokas",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "@lordfokas/event-bus": "^1.0.1"
+  }
+}