@brandup/ui 1.0.44 → 2.0.2

package/dist/mjs/dom/tag.js

@@ -0,0 +1,203 @@
+import { UIElement } from '../element.js';
+import { Binding } from './bind.js';
+import { BindingEach, appendBindingEach } from './bind-each.js';
+import { effect } from '../reactive/effect.js';
+import { autoDisposeBinding } from './binding-cleanup.js';
+import helpers from './helpers.js';
+
+/** Returns `true` when `value` should be treated as options (or absent options), `false` when it is the first child. */
+const isOptionsArg = (value) => {
+    if (value === null || value === undefined)
+        return true;
+    if (typeof value !== "object")
+        return false; // string, number, boolean, function → child
+    if (Array.isArray(value))
+        return false; // array → children
+    if (value instanceof Element || value instanceof UIElement || value instanceof Binding || value instanceof BindingEach || value instanceof Promise)
+        return false;
+    return true; // plain object → ElementOptions
+};
+/**
+ * Creates an HTML element, optionally applying options and appending children.
+ *
+ * The second argument is **options** when it is `null` or a plain {@link ElementOptions} object.
+ * It is treated as the **first child** for any {@link TagFirstChild} value — strings, numbers,
+ * elements, bindings, arrays, etc. — so `tag("div", "hello")` appends "hello" as HTML text,
+ * and `tag("ul", bindEach(...))` works without a leading `null`.
+ * To apply a CSS class use `{ class: "name" }` in options.
+ */
+function tag(tagName, optionsOrChild, ...rest) {
+    const elem = document.createElement(tagName);
+    if (isOptionsArg(optionsOrChild)) {
+        applyOptions(elem, optionsOrChild);
+        appendChild(elem, rest);
+    }
+    else {
+        appendChild(elem, optionsOrChild !== undefined ? [optionsOrChild, ...rest] : rest);
+    }
+    return elem;
+}
+/**
+ * Applies element options to an existing element. A string or array is treated as a {@link CssClass}; otherwise each {@link ElementOptions} key is applied (`id`, `styles`, `class`, `command`, `dataset`, `events`, or a plain attribute). `undefined` values are skipped.
+ * @param elem Target element to mutate.
+ * @param options Options object, {@link CssClass} shorthand, or `null`/`undefined` for none.
+ */
+const applyOptions = (elem, options) => {
+    if (!options)
+        return;
+    if (typeof options === "string" || Array.isArray(options))
+        helpers.addCssClass(elem, options);
+    else {
+        for (const key in options) {
+            const value = options[key];
+            if (value === undefined)
+                continue;
+            switch (key) {
+                case "id":
+                    elem.id = value;
+                    break;
+                case "styles": {
+                    if (value) {
+                        for (const sKey in value)
+                            elem.style[sKey] = value[sKey];
+                    }
+                    break;
+                }
+                case "class": {
+                    helpers.addCssClass(elem, value);
+                    break;
+                }
+                case "command": {
+                    elem.dataset["command"] = value;
+                    break;
+                }
+                case "dataset": {
+                    if (value) {
+                        for (const dataName in value)
+                            elem.dataset[dataName] = value[dataName];
+                    }
+                    break;
+                }
+                case "events": {
+                    if (value) {
+                        for (const eventName in value)
+                            elem.addEventListener(eventName, value[eventName]);
+                    }
+                    break;
+                }
+                default: {
+                    if (value === null)
+                        elem.setAttribute(key, "");
+                    else if (typeof value === "object")
+                        elem.setAttribute(key, JSON.stringify(value));
+                    else
+                        elem.setAttribute(key, String(value));
+                    break;
+                }
+            }
+        }
+    }
+};
+/**
+ * Appends one or more children to a container, recursively resolving arrays, promises and factory functions. Elements are appended as-is; a {@link UIElement} appends its bound element (or defers until `setElement` binds one); a reactive {@link Binding} renders and live-updates in place; strings/numbers/booleans are inserted as HTML; `null`/`undefined` are ignored.
+ * @param container Element to append the children to.
+ * @param children Child or children to append. See {@link TagChildrenLike}.
+ * @throws Error When a child resolves to an unsupported type.
+ */
+const appendChild = (container, children) => {
+    if (children === null || children === undefined)
+        return;
+    if (children instanceof Array)
+        children.forEach(child => appendChild(container, child));
+    else if (children instanceof Element)
+        container.append(children);
+    else if (children instanceof UIElement) {
+        if (children.element)
+            container.append(children.element);
+        else {
+            // reserve the position now; replace the placeholder once setElement
+            // binds the element (after _onRenderElement), keeping child order
+            const placeholder = document.createComment("");
+            container.append(placeholder);
+            children.once("rendered", () => {
+                if (children.element)
+                    placeholder.replaceWith(children.element);
+            });
+        }
+    }
+    else if (children instanceof Binding)
+        appendBinding(container, children);
+    else if (children instanceof BindingEach)
+        appendBindingEach(container, children);
+    else if (children instanceof Promise)
+        children.then((child) => appendChild(container, child));
+    else {
+        const typeName = typeof children;
+        let html;
+        switch (typeName) {
+            case "string":
+                html = children;
+                break;
+            case "number":
+            case "boolean":
+                html = children.toString();
+                break;
+            case "function":
+                const child = children(container);
+                appendChild(container, child);
+                return;
+            default:
+                throw new Error(`Not support child type of ${typeName}.`);
+        }
+        container.insertAdjacentHTML("beforeend", html);
+    }
+};
+/**
+ * Renders a reactive {@link Binding} child and keeps it up to date: a reactive
+ * effect re-evaluates the binding and updates the DOM in place — reusing a text
+ * node for text values and swapping the node when an element/UIElement is returned.
+ */
+const appendBinding = (container, binding) => {
+    let current = document.createTextNode("");
+    let textNode = current;
+    container.append(current);
+    const eff = effect(() => {
+        const value = binding.compute();
+        if (value instanceof Element || value instanceof UIElement) {
+            const next = (value instanceof UIElement ? value.element : value) ?? document.createComment("");
+            current.replaceWith(next);
+            current = next;
+            textNode = null;
+            // deferred UIElement: its element is bound later — swap the placeholder
+            // for the real element once setElement raises "rendered"
+            if (value instanceof UIElement && !value.element) {
+                const placeholder = next;
+                value.once("rendered", () => {
+                    // skip if the binding has since re-rendered to a different node
+                    if (value.element && current === placeholder) {
+                        placeholder.replaceWith(value.element);
+                        current = value.element;
+                    }
+                });
+            }
+        }
+        else {
+            // null/undefined/false render as empty text
+            const text = (value === null || value === undefined || value === false) ? "" : String(value);
+            if (textNode && textNode === current) {
+                textNode.textContent = text;
+            }
+            else {
+                const next = document.createTextNode(text);
+                current.replaceWith(next);
+                current = next;
+                textNode = next;
+            }
+        }
+    });
+    // stop the effect when the rendered node leaves the document
+    autoDisposeBinding(container, () => current, eff);
+};
+
+export { appendChild, applyOptions, tag };
+//# sourceMappingURL=tag.js.map

package/dist/mjs/dom/tag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag.js","sources":["../../../../source/dom/tag.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}

package/dist/mjs/element.js

@@ -0,0 +1,260 @@
+import { EventEmitter } from './events.js';
+import { effectScope } from './reactive/effect.js';
+import { trackAutoDestroy, destroyUIElementsWithin, untrackAutoDestroy, disposeBindingsWithin } from './dom/binding-cleanup.js';
+import constants from './constants.js';
+
+/**
+ * Wraps an `HTMLElement` and binds business logic, commands and events to it.
+ *
+ * The optional `TEvents` event map is merged with {@link UIElementEvents}, so subclasses
+ * can declare their own typed events in addition to the built-in `command`/`destroy`.
+ */
+class UIElement extends EventEmitter {
+    __element;
+    __events;
+    __commands;
+    __destroyed;
+    // Element members
+    /** The bound DOM element, or `undefined` until `setElement` is called. */
+    get element() { return this.__element; }
+    /**
+     * Bind a DOM element to this instance and run render logic. Can be called only once.
+     * @param elem Element to bind; throws if already bound or owned by another `UIElement`.
+     */
+    setElement(elem) {
+        if (!elem)
+            throw new Error("Not set value elem.");
+        if (this.__element || UIElement.hasElement(elem))
+            throw new Error("UIElement already defined");
+        this.__element = elem;
+        elem[constants.ElemPropertyName] = this;
+        elem.dataset[constants.ElemAttributeName] = this.typeName;
+        trackAutoDestroy(elem, () => this.destroy());
+        this._onRenderElement(elem);
+        this.__raise("rendered", this);
+    }
+    // static members
+    /**
+     * Whether the given element is already bound to a `UIElement`.
+     * @param elem Element to test.
+     */
+    static hasElement(elem) {
+        return !!elem.dataset[constants.ElemAttributeName];
+    }
+    // Command members
+    /**
+     * Register a handler for a command declared in markup via the `data-command` attribute.
+     * @param name Command name (case-insensitive); throws if already registered.
+     * @param execute Handler run when the command fires; may return a `Promise` for async commands.
+     * @param canExecute Optional predicate gating whether the command may run.
+     * @returns This instance for chaining.
+     */
+    registerCommand(name, execute, canExecute) {
+        if (this.__destroyed)
+            return this;
+        const commands = this.__commands || (this.__commands = {});
+        const normalizedName = name.toLowerCase();
+        if (normalizedName in commands)
+            throw new Error(`Command "${name}" already registered.`);
+        commands[normalizedName] = {
+            name: name,
+            execute,
+            canExecute
+        };
+        return this;
+    }
+    /**
+     * Whether a command with the given name is registered.
+     * @param name Command name (case-insensitive).
+     */
+    hasCommand(name) {
+        return !!this.__commands && name.toLowerCase() in this.__commands;
+    }
+    /**
+     * Execute a registered command against a target element.
+     * @internal
+     */
+    __execCommand(name, target) {
+        if (this.__destroyed || !this.__element)
+            throw new Error("UIElement is destroyed or has no element.");
+        const key = name.toLowerCase();
+        const command = this.__commands?.[key];
+        if (!command)
+            throw new Error(`Command "${name}" is not registered.`);
+        const context = {
+            target,
+            uiElem: this
+        };
+        if (command.isExecuting)
+            return { status: "already", context };
+        command.isExecuting = true;
+        // keep isExecuting cleanup inside finally so a throw in the
+        // guards/trigger/execute can never leave the command stuck.
+        let isAsync = false;
+        try {
+            if (!this._onCanExecCommand(name, target))
+                return { status: "disallow", context };
+            if (command.canExecute && !command.canExecute(context))
+                return { status: "disallow", context };
+            this.__raise("command", { element: this, name: command.name });
+            const commandResult = command.execute(context);
+            if (commandResult instanceof Promise) {
+                isAsync = true;
+                target.classList.add(constants.CommandExecutingCssClassName);
+                commandResult
+                    // command owns its errors; log so failures aren't silent, and avoid unhandled rejection
+                    .catch((reason) => console.error(`Command "${command.name}" failed.`, reason))
+                    .finally(() => {
+                    target.classList.remove(constants.CommandExecutingCssClassName);
+                    delete command.isExecuting;
+                });
+            }
+            return { status: "success", context };
+        }
+        finally {
+            if (!isAsync)
+                delete command.isExecuting;
+        }
+    }
+    /**
+     * Hook invoked when an element is bound via `setElement`. Override to render or wire up the element.
+     * @param _elem The newly bound element.
+     */
+    /** Trigger a built-in event. Typed by {@link UIElementEvents}; bypasses the generic trigger overload internally. */
+    __raise(name, ...args) {
+        this.trigger(name, ...args);
+    }
+    _onRenderElement(_elem) { }
+    /**
+     * Hook deciding whether a command may execute. Override to add element-wide gating.
+     * @param _name Command name being executed.
+     * @param _elem Target element of the command.
+     * @returns `true` to allow execution (default), `false` to disallow.
+     */
+    _onCanExecCommand(_name, _elem) {
+        return true;
+    }
+    /**
+     * Create an {@link EffectScope} whose reactive effects are stopped automatically when
+     * this element is destroyed. Use it to scope `bind`/`effect` to the element's lifetime.
+     */
+    effectScope() {
+        const scope = effectScope();
+        this.on("destroy", () => scope.stop());
+        return scope;
+    }
+    /** Returns the `typeName` of this element. */
+    toString() { return this.typeName; }
+    /** Destroy the element: trigger the `destroy` event, release events/commands and detach from the DOM element. */
+    destroy() {
+        if (this.__destroyed)
+            return;
+        this.__destroyed = true;
+        this.__raise("destroy", this);
+        super.stopEvents();
+        const elem = this.__element;
+        if (elem) {
+            destroyUIElementsWithin(elem); // cascade to nested UIElements, deepest first
+            untrackAutoDestroy(elem);
+            disposeBindingsWithin(elem);
+            delete elem.dataset[constants.ElemAttributeName];
+            delete elem[constants.ElemPropertyName];
+        }
+        delete this.__element;
+        delete this.__events;
+        delete this.__commands;
+    }
+}
+/**
+ * A {@link UIElement} whose DOM element is bound in the constructor, so its `element`
+ * is always defined (typed `HTMLElement`, never `undefined`). Subclasses pass their
+ * `typeName` and the element to `super`.
+ *
+ * Use {@link UIElement} directly when the element is bound later (e.g. an application
+ * that binds its element on run).
+ */
+class UIElementBound extends UIElement {
+    __typeName;
+    /** @param typeName Unique type name of this element. @param elem Element to bind. */
+    constructor(typeName, elem) {
+        super();
+        this.__typeName = typeName; // set before setElement (no field-initializer race)
+        this.setElement(elem);
+    }
+    get typeName() { return this.__typeName; }
+    /** The bound DOM element; always defined since it is set in the constructor. */
+    get element() { return super.element; }
+}
+const findUiElementByCommand = (elem, commandName) => {
+    let current = elem;
+    while (current) {
+        if (current.dataset[constants.ElemAttributeName]) {
+            const uiElem = current[constants.ElemPropertyName];
+            if (uiElem.hasCommand(commandName))
+                return uiElem;
+        }
+        current = current.parentElement;
+    }
+    return null;
+};
+const commandClickHandler = (e) => {
+    // walk up from the clicked element to the nearest ancestor declaring a command
+    let commandElem = e.target;
+    while (commandElem && !commandElem.dataset[constants.CommandAttributeName])
+        commandElem = commandElem.parentElement;
+    if (!commandElem)
+        return;
+    const commandName = commandElem.dataset[constants.CommandAttributeName];
+    if (!commandName)
+        throw new Error("Command data attribute does not have a value.");
+    const uiElem = findUiElementByCommand(commandElem, commandName);
+    // A click on a data-command element is owned by the library: prevent the element's
+    // default action (e.g. <a> navigation) and stop the click chain — UNLESS the command
+    // completed successfully and asked to stay transparent. This runs in `finally`, so a
+    // throwing command can never skip preventDefault and let the page navigate/reload.
+    let transparent = false;
+    try {
+        if (uiElem) {
+            const result = uiElem.__execCommand(commandName, commandElem);
+            transparent = result.status === "success" && !!result.context.transparent;
+        }
+        else
+            console.warn(`Not find handler for command "${commandName}".`);
+    }
+    catch (reason) {
+        console.error(`Command "${commandName}" failed.`, reason);
+    }
+    finally {
+        if (!transparent) {
+            e.preventDefault();
+            e.stopPropagation();
+            e.stopImmediatePropagation();
+        }
+    }
+};
+let __commandsInited = false;
+/**
+ * Register the global click handler that dispatches {@link UIElement} commands declared in
+ * markup via `data-command`. Call once during application startup. Idempotent and a no-op in
+ * a non-DOM environment. {@link Application.run} (in `@brandup/ui-app`) calls this automatically;
+ * call it yourself only when using `UIElement` commands without an `Application`.
+ *
+ * Making this explicit (instead of a side effect on import) lets bundlers tree-shake the
+ * command system away for consumers that don't use it.
+ */
+function initUICommands() {
+    if (__commandsInited || typeof window === "undefined")
+        return;
+    __commandsInited = true;
+    window.addEventListener("click", commandClickHandler);
+}
+/** Remove the global command click handler registered by {@link initUICommands} (e.g. on HMR disposal or teardown). */
+function destroyUI() {
+    if (!__commandsInited || typeof window === "undefined")
+        return;
+    __commandsInited = false;
+    window.removeEventListener("click", commandClickHandler);
+}
+
+export { UIElement, UIElementBound, destroyUI, initUICommands };
+//# sourceMappingURL=element.js.map

package/dist/mjs/element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.js","sources":["../../../source/element.ts"],"sourcesContent":[null],"names":["UICONSTANTS","createEffectScope"],"mappings":"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"}