@brandup/ui 1.0.44 → 2.0.2

package/dist/cjs/element.js

@@ -0,0 +1,265 @@
+'use strict';
+
+var events = require('./events.js');
+var effect = require('./reactive/effect.js');
+var bindingCleanup = require('./dom/binding-cleanup.js');
+var constants = require('./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 events.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.default.ElemPropertyName] = this;
+        elem.dataset[constants.default.ElemAttributeName] = this.typeName;
+        bindingCleanup.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.default.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.default.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.default.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 = effect.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) {
+            bindingCleanup.destroyUIElementsWithin(elem); // cascade to nested UIElements, deepest first
+            bindingCleanup.untrackAutoDestroy(elem);
+            bindingCleanup.disposeBindingsWithin(elem);
+            delete elem.dataset[constants.default.ElemAttributeName];
+            delete elem[constants.default.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.default.ElemAttributeName]) {
+            const uiElem = current[constants.default.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.default.CommandAttributeName])
+        commandElem = commandElem.parentElement;
+    if (!commandElem)
+        return;
+    const commandName = commandElem.dataset[constants.default.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);
+}
+
+exports.UIElement = UIElement;
+exports.UIElementBound = UIElementBound;
+exports.destroyUI = destroyUI;
+exports.initUICommands = initUICommands;
+//# sourceMappingURL=element.js.map

package/dist/cjs/element.js.map

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

package/dist/cjs/events.js

@@ -0,0 +1,204 @@
+'use strict';
+
+let ListenCounter = 1;
+/**
+ * Minimal event emitter with support for one-off listeners and cross-emitter listening.
+ *
+ * The optional `TEvents` type parameter is an event map (`{ eventName: (args) => void }`)
+ * that gives subclasses strongly-typed event names, callback signatures and `trigger` arguments.
+ * When omitted it defaults to a loose map, so untyped usage keeps working.
+ */
+class EventEmitter {
+    _events;
+    _listenId;
+    _listeningTo;
+    on(eventName, callback, context) {
+        const events = this._getOrCreateEvents(eventName);
+        events.push({ callback, context: context || undefined, ctx: context || this });
+        return this;
+    }
+    once(eventName, callback, context) {
+        const wrapper = (...args) => {
+            this.off(eventName, wrapper, context);
+            callback.apply(context || this, args);
+        };
+        return this.on(eventName, wrapper, context);
+    }
+    off(eventName, callback, context) {
+        if (!eventName && !callback && !context)
+            throw new Error("Require off arguments.");
+        const events = this._events;
+        if (!events)
+            return this;
+        callback = callback || undefined;
+        context = context || undefined;
+        const eventNames = eventName ? [eventName.toLowerCase()] : Object.keys(events);
+        for (let i = 0; i < eventNames.length; i++) {
+            const name = eventNames[i];
+            const currentCallbacks = events[name];
+            if (!currentCallbacks)
+                continue;
+            // reset callback list
+            const newCallbacks = events[name] = [];
+            if (callback || context) {
+                currentCallbacks.forEach(c => {
+                    const callbackMatch = !callback || c.callback === callback;
+                    const contextMatch = !context || c.context === context;
+                    if (callbackMatch && contextMatch)
+                        return;
+                    newCallbacks.push(c);
+                });
+            }
+            if (!newCallbacks.length)
+                delete events[name];
+        }
+        return this;
+    }
+    /**
+     * Listen to an event on another emitter, tracking the subscription so it can be released via `stopListening`.
+     * @param source Emitter to subscribe to.
+     * @param eventName Event name to listen for.
+     * @param callback Handler invoked when the event is triggered.
+     */
+    listenTo(source, eventName, callback) {
+        this._addListeningTo(source, eventName, callback, callback);
+        source.on(eventName, callback, this);
+        return this;
+    }
+    /**
+     * Listen once to an event on another emitter; the subscription is tracked and auto-removed after it fires.
+     * @param source Emitter to subscribe to.
+     * @param eventName Event name to listen for.
+     * @param callback Handler invoked once when the event is triggered.
+     */
+    listenToOnce(source, eventName, callback) {
+        // Use our own one-shot wrapper instead of source.once so that, when it fires,
+        // we can drop this exact subscription from BOTH sides — the source and our
+        // own _listeningTo registry — keeping the two in sync (no dangling tracking).
+        const wrapper = (...args) => {
+            source.off(eventName, wrapper, this);
+            this._removeListeningSubscription(source, eventName, wrapper);
+            callback.apply(this, args);
+        };
+        this._addListeningTo(source, eventName, wrapper, callback);
+        source.on(eventName, wrapper, this);
+        return this;
+    }
+    /**
+     * Release subscriptions previously established with `listenTo`/`listenToOnce`.
+     * Omitted arguments broaden the match (e.g. no `source` releases all tracked emitters).
+     * @param source Limit to a specific emitter, or omit for all.
+     * @param eventName Limit to a specific event, or omit for all.
+     * @param callback Limit to a specific handler, or omit for all.
+     */
+    stopListening(source, eventName, callback) {
+        if (!this._listeningTo)
+            return this;
+        // A source we never listened to has no tracked subscriptions — nothing to do.
+        const listenings = source
+            ? (source._listenId && this._listeningTo[source._listenId] ? [this._listeningTo[source._listenId]] : [])
+            : Object.values(this._listeningTo);
+        const targetEvent = eventName ? eventName.toLowerCase() : undefined;
+        listenings.forEach(listening => {
+            // snapshot: the loop splices listening.subscriptions
+            listening.subscriptions.slice().forEach(sub => {
+                if (targetEvent && sub.eventName !== targetEvent)
+                    return;
+                // match the user-supplied callback against both the registered
+                // callback and the original (so a listenToOnce can be stopped by
+                // the callback the caller passed, not the internal wrapper)
+                if (callback && sub.callback !== callback && sub.origin !== callback)
+                    return;
+                listening.emitter.off(sub.eventName, sub.callback, this);
+                const index = listening.subscriptions.indexOf(sub);
+                if (index >= 0)
+                    listening.subscriptions.splice(index, 1);
+            });
+            if (!listening.subscriptions.length && listening.emitter._listenId)
+                delete this._listeningTo[listening.emitter._listenId];
+        });
+        if (!this._listeningTo || Object.keys(this._listeningTo).length === 0)
+            delete this._listeningTo;
+        return this;
+    }
+    _addListeningTo(source, eventName, callback, origin) {
+        const listeningTo = this._listeningTo || (this._listeningTo = {});
+        const listenId = source._listenId || (source._listenId = `l${ListenCounter++}`);
+        const listenTo = listeningTo[listenId] || (listeningTo[listenId] = { emitter: source, subscriptions: [] });
+        // one entry per subscription (not per event name) so each can be removed
+        // independently — e.g. a listenToOnce dropping itself without disturbing
+        // a co-registered persistent listenTo on the same source+event.
+        listenTo.subscriptions.push({ eventName: eventName.toLowerCase(), callback, origin });
+    }
+    /** Remove a single tracked subscription (matched by event + registered callback). @internal */
+    _removeListeningSubscription(source, eventName, callback) {
+        const listenId = source._listenId;
+        if (!this._listeningTo || !listenId)
+            return;
+        const listening = this._listeningTo[listenId];
+        if (!listening)
+            return;
+        eventName = eventName.toLowerCase();
+        const index = listening.subscriptions.findIndex(s => s.eventName === eventName && s.callback === callback);
+        if (index >= 0)
+            listening.subscriptions.splice(index, 1);
+        if (!listening.subscriptions.length)
+            delete this._listeningTo[listenId];
+        if (Object.keys(this._listeningTo).length === 0)
+            delete this._listeningTo;
+    }
+    stopAllListeners() {
+        if (!this._events)
+            return;
+        Object.values(this._events).forEach(callbacks => {
+            callbacks.forEach(callback => {
+                if (callback.context instanceof EventEmitter)
+                    callback.context.stopListening(this);
+            });
+        });
+        delete this._events;
+    }
+    trigger(eventName, ...args) {
+        eventName = eventName.toLowerCase();
+        if (eventName === "all")
+            throw new Error('Not allow trigger all event.');
+        if (!this._events)
+            return this;
+        const events = this._getEvents(eventName);
+        const allEvents = this._getEvents("all");
+        this._triggerEvent(events, ...args);
+        this._triggerEvent(allEvents, ...args);
+        return this;
+    }
+    _triggerEvent(events, ...args) {
+        if (!events || !events.length)
+            return;
+        // snapshot so callbacks added/removed during dispatch don't affect this trigger
+        const snapshot = events.slice();
+        for (let i = 0; i < snapshot.length; i++) {
+            const event = snapshot[i];
+            event.callback.apply(event.ctx, args);
+        }
+    }
+    _getOrCreateEvents(eventName) {
+        eventName = eventName.toLowerCase();
+        const events = this._events || (this._events = {});
+        return events[eventName] || (events[eventName] = []);
+    }
+    _getEvents(eventName) {
+        if (!eventName)
+            return;
+        const events = this._events;
+        if (!events)
+            return;
+        return events[eventName];
+    }
+    /** Release every subscription: both events this emitter listens to and listeners registered on it. */
+    stopEvents() {
+        this.stopListening();
+        this.stopAllListeners();
+    }
+}
+
+exports.EventEmitter = EventEmitter;
+//# sourceMappingURL=events.js.map

package/dist/cjs/events.js.map

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

package/dist/cjs/ext.js

@@ -0,0 +1,20 @@
+'use strict';
+
+let __inited = false;
+/**
+ * Install the `HTMLElement.prototype.ui(factory)` convenience binder. Opt-in (no longer a
+ * side effect on import) so bundlers can tree-shake it away for consumers that don't use it.
+ * Idempotent and a no-op in a non-DOM environment.
+ */
+function enableElementExtensions() {
+    if (__inited || typeof HTMLElement === "undefined")
+        return;
+    __inited = true;
+    HTMLElement.prototype.ui = function (factory) {
+        factory(this);
+        return this;
+    };
+}
+
+exports.enableElementExtensions = enableElementExtensions;
+//# sourceMappingURL=ext.js.map

package/dist/cjs/ext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ext.js","sources":["../../../source/ext.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAiBA,IAAI,QAAQ,GAAG,KAAK;AAEpB;;;;AAIG;SACa,uBAAuB,GAAA;AACtC,IAAA,IAAI,QAAQ,IAAI,OAAO,WAAW,KAAK,WAAW;QACjD;IACD,QAAQ,GAAG,IAAI;AAEf,IAAA,WAAW,CAAC,SAAS,CAAC,EAAE,GAAG,UAAU,OAAyC,EAAA;QAC7E,OAAO,CAAC,IAAI,CAAC;AACb,QAAA,OAAO,IAAI;AACZ,IAAA,CAAC;AACF;;;;"}