@converse/skeletor 0.0.8 → 0.0.9

package/src/element.js

@@ -1,45 +1,62 @@
-import extend from "lodash-es/extend.js";
-import isElement from "lodash-es/isElement.js";
-import isFunction from "lodash-es/isFunction.js";
-import pick from "lodash-es/pick.js";
-import result from "lodash-es/result.js";
-import uniqueId from "lodash-es/uniqueId.js";
-import { Events } from './events.js';
-import { inherits, NotImplementedError } from './helpers.js';
-import { render } from 'lit-html';
-
 
-const paddedLt = /^\s*</;
-
-// Caches a local reference to `Element.prototype` for faster access.
-const ElementProto = (typeof Element !== 'undefined' && Element.prototype) || {};
+/**
+ * @typedef {import('lit-html').TemplateResult} TemplateResult
+ */
+import uniqueId from 'lodash-es/uniqueId.js';
+import { render } from 'lit-html';
+import EventEmitter from './eventemitter.js';
 
 // Cached regex to split keys for `delegate`.
 const delegateEventSplitter = /^(\S+)\s*(.*)$/;
 
-// List of view options to be set as properties.
-const viewOptions = ['model', 'collection', 'events'];
+class ElementView extends EventEmitter(HTMLElement) {
+
+  /**
+   * @typedef {import('./model.js').Model} Model
+   * @typedef {import('./collection.js').Collection} Collection
+   * @typedef {Record.<string, any>} Options
+   *
+   * @callback EventCallback
+   * @param {any} event
+   * @param {Model} model
+   * @param {Collection} collection
+   * @param {Options} [options]
+   */
+
+  set events (events) {
+    this._declarativeEvents = events;
+  }
 
+  get events() {
+    return this._declarativeEvents;
+  }
 
-export class ElementView extends HTMLElement {
+  /**
+   * @param {Options} options
+   */
+  constructor(options={}) {
+    super();
 
-  events = {}
+    // Will be assigned to from Events
+    this.stopListening = null;
 
-  constructor(options) {
-    super();
     // Creating a View creates its initial element outside of the DOM,
     // if an existing element is not provided...
     this.cid = uniqueId('view');
+    this._declarativeEvents = {};
     this._domEvents = [];
-    extend(this, pick(options, viewOptions));
+
+    const { model, collection, events } = options;
+
+    Object.assign(this, { model: model, collection, events });
   }
 
-  createRenderRoot () {
+  createRenderRoot() {
     // Render without the shadow DOM
     return this;
   }
 
-  connectedCallback () {
+  connectedCallback() {
     if (!this._initialized) {
       this.preinitialize.apply(this, arguments);
       this.initialize.apply(this, arguments);
@@ -48,43 +65,61 @@ export class ElementView extends HTMLElement {
     this.delegateEvents();
   }
 
-  disconnectedCallback () {
+  disconnectedCallback() {
     this.undelegateEvents();
-    this.stopListening();
-  }
-
-  // preinitialize is an empty function by default. You can override it with a function
-  // or object.  preinitialize will run before any instantiation logic is run in the View
-  preinitialize () {  // eslint-disable-line class-methods-use-this
+    this.stopListening?.();
   }
 
-  // Initialize is an empty function by default. Override it with your own
-  // initialization logic.
-  initialize() {}  // eslint-disable-line class-methods-use-this
-
-  // **render** is the core function that your view should override, in order
-  // to populate its element (`this.el`), with the appropriate HTML. The
-  // convention is for **render** to always return `this`.
+  /**
+   * preinitialize is an empty function by default. You can override it with a function
+   * or object.  preinitialize will run before any instantiation logic is run in the View
+   * eslint-disable-next-line class-methods-use-this
+   */
+  preinitialize() {}
+
+  /**
+   * Initialize is an empty function by default. Override it with your own
+   * initialization logic.
+   */
+  initialize() {}
+
+  beforeRender() {}
+  afterRender() {}
+
+  /**
+   * **render** is the core function that your view should override, in order
+   * to populate its element (`this.el`), with the appropriate HTML. The
+   * convention is for **render** to always return `this`.
+   */
   render() {
-    isFunction(this.beforeRender) && this.beforeRender();
-    isFunction(this.toHTML) && render(this.toHTML(), this);
-    isFunction(this.afterRender) && this.afterRender();
+    this.beforeRender();
+    render(this.toHTML(), this);
+    this.afterRender();
     return this;
   }
 
-  // Set callbacks, where `this.events` is a hash of
-  //
-  // *{"event selector": "callback"}*
-  //
-  //     {
-  //       'mousedown .title':  'edit',
-  //       'click .button':     'save',
-  //       'click .open':       function(e) { ... }
-  //     }
-  //
-  // pairs. Callbacks will be bound to the view, with `this` set properly.
-  // Uses event delegation for efficiency.
-  // Omitting the selector binds the event to `this.el`.
+  /**
+   * @returns {string|TemplateResult}
+   */
+  toHTML() {
+    return '';
+  }
+
+  /**
+   * Set callbacks, where `this.events` is a hash of
+   *
+   * *{"event selector": "callback"}*
+   *
+   *     {
+   *       'mousedown .title':  'edit',
+   *       'click .button':     'save',
+   *       'click .open':       function(e) { ... }
+   *     }
+   *
+   * pairs. Callbacks will be bound to the view, with `this` set properly.
+   * Uses event delegation for efficiency.
+   * Omitting the selector binds the event to `this.el`.
+   */
   delegateEvents() {
     if (!this.events) {
       return this;
@@ -92,7 +127,7 @@ export class ElementView extends HTMLElement {
     this.undelegateEvents();
     for (const key in this.events) {
       let method = this.events[key];
-      if (!isFunction(method)) method = this[method];
+      if (typeof method !== 'function') method = this[method];
       if (!method) continue;
       const match = key.match(delegateEventSplitter);
       this.delegate(match[1], match[2], method.bind(this));
@@ -100,15 +135,21 @@ export class ElementView extends HTMLElement {
     return this;
   }
 
-  // Make a event delegation handler for the given `eventName` and `selector`
-  // and attach it to `this.el`.
-  // If selector is empty, the listener will be bound to `this.el`. If not, a
-  // new handler that will recursively traverse up the event target's DOM
-  // hierarchy looking for a node that matches the selector. If one is found,
-  // the event's `delegateTarget` property is set to it and the return the
-  // result of calling bound `listener` with the parameters given to the
-  // handler.
+  /**
+   * Make a event delegation handler for the given `eventName` and `selector`
+   * and attach it to `this.el`.
+   * If selector is empty, the listener will be bound to `this.el`. If not, a
+   * new handler that will recursively traverse up the event target's DOM
+   * hierarchy looking for a node that matches the selector. If one is found,
+   * the event's `delegateTarget` property is set to it and the return the
+   * result of calling bound `listener` with the parameters given to the
+   * handler.
+   * @param {string} eventName
+   * @param {string} selector
+   * @param {(ev: Event) => any} listener
+   */
   delegate(eventName, selector, listener) {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
     const root = this;
     if (!root) {
       return this;
@@ -123,29 +164,33 @@ export class ElementView extends HTMLElement {
       for (let i = 0, len = els.length; i < len; i++) {
         const item = els[i];
         item.addEventListener(eventName, listener, false);
-        this._domEvents.push({el: item, eventName: eventName, handler: listener});
+        this._domEvents.push({ el: item, eventName: eventName, handler: listener });
       }
       return listener;
     }
 
-    const handler = selector ? function (e) {
-      let node = e.target || e.srcElement;
-      for (; node && node != root; node = node.parentNode) {
-        if (node.matches(selector)) {
-          e.delegateTarget = node;
-          listener(e);
+    const handler = selector
+      ? function (e) {
+          let node = e.target || e.srcElement;
+          for (; node && node != root; node = node.parentNode) {
+            if (node.matches(selector)) {
+              e.delegateTarget = node;
+              listener(e);
+            }
+          }
         }
-      }
-    } : listener;
+      : listener;
 
     this.addEventListener(eventName, handler, false);
-    this._domEvents.push({el: this, eventName: eventName, handler: handler, listener: listener, selector: selector});
+    this._domEvents.push({ el: this, eventName: eventName, handler: handler, listener: listener, selector: selector });
     return this;
   }
 
-  // Clears all callbacks previously bound to the view by `delegateEvents`.
-  // You usually don't need to use this, but may wish to if you have multiple
-  // Backbone views attached to the same DOM element.
+  /**
+   * Clears all callbacks previously bound to the view by `delegateEvents`.
+   * You usually don't need to use this, but may wish to if you have multiple
+   * Backbone views attached to the same DOM element.
+   */
   undelegateEvents() {
     if (this) {
       for (let i = 0, len = this._domEvents.length; i < len; i++) {
@@ -157,8 +202,13 @@ export class ElementView extends HTMLElement {
     return this;
   }
 
-  // A finer-grained `undelegateEvents` for removing a single delegated event.
-  // `selector` and `listener` are both optional.
+  /**
+   * A finer-grained `undelegateEvents` for removing a single delegated event.
+   * `selector` and `listener` are both optional.
+   * @param {string} eventName
+   * @param {string} selector
+   * @param {(ev: Event) => any} listener
+   */
   undelegate(eventName, selector, listener) {
     if (typeof selector === 'function') {
       listener = selector;
@@ -169,9 +219,10 @@ export class ElementView extends HTMLElement {
       let i = handlers.length;
       while (i--) {
         const item = handlers[i];
-        const match = item.eventName === eventName &&
-            (listener ? item.listener === listener : true) &&
-            (selector ? item.selector === selector : true);
+        const match =
+          item.eventName === eventName &&
+          (listener ? item.listener === listener : true) &&
+          (selector ? item.selector === selector : true);
 
         if (!match) {
           continue;
@@ -184,5 +235,4 @@ export class ElementView extends HTMLElement {
   }
 }
 
-// Set up all inheritable **View** properties and methods.
-Object.assign(ElementView.prototype, Events);
+export default ElementView;

package/src/eventemitter.js

@@ -0,0 +1,187 @@
+/**
+ * @copyright 2010-2019 Jeremy Ashkenas and DocumentCloud
+ * @copyright 2023 JC Brand
+ */
+import isEmpty from 'lodash-es/isEmpty.js';
+import keys from 'lodash-es/keys.js';
+import uniqueId from 'lodash-es/uniqueId.js';
+import Listening from './listening.js';
+import { eventsApi, onApi, offApi, onceMap, tryCatchOn, triggerApi } from './utils/events.js';
+
+// A private global variable to share between listeners and listenees.
+let _listening;
+
+/**
+ * @function
+ * @template {new(...args: any[]) => {}} ClassConstructor
+ * @param {ClassConstructor} Base
+ */
+export function EventEmitter(Base) {
+  return class EventEmitter extends Base {
+    /**
+     * @typedef {import('./model.js').Model} Model
+     * @typedef {import('./collection.js').Collection} Collection
+     * @typedef {Record.<string, any>} Options
+     *
+     * @callback EventCallback
+     * @param {any} event
+     * @param {Model} model
+     * @param {Collection} collection
+     * @param {Options} [options]
+     */
+
+    /**
+     * Bind an event to a `callback` function. Passing `"all"` will bind
+     * the callback to all events fired.
+     * @param {string} name
+     * @param {EventCallback} callback
+     * @param {any} context
+     * @return {EventEmitter}
+     */
+    on(name, callback, context) {
+      this._events = eventsApi(onApi, this._events || {}, name, callback, {
+        context: context,
+        ctx: this,
+        listening: _listening,
+      });
+
+      if (_listening) {
+        const listeners = this._listeners || (this._listeners = {});
+        listeners[_listening.id] = _listening;
+        // Allow the listening to use a counter, instead of tracking
+        // callbacks for library interop
+        _listening.interop = false;
+      }
+
+      return this;
+    }
+
+    /**
+     * Inversion-of-control versions of `on`. Tell *this* object to listen to
+     * an event in another object... keeping track of what it's listening to
+     * for easier unbinding later.
+     * @param {any} obj
+     * @param {string} name
+     * @param {EventCallback} [callback]
+     * @return {EventEmitter}
+     */
+    listenTo(obj, name, callback) {
+      if (!obj) return this;
+      const id = obj._listenId || (obj._listenId = uniqueId('l'));
+      const listeningTo = this._listeningTo || (this._listeningTo = {});
+      let listening = (_listening = listeningTo[id]);
+
+      // This object is not listening to any other events on `obj` yet.
+      // Setup the necessary references to track the listening callbacks.
+      if (!listening) {
+        this._listenId || (this._listenId = uniqueId('l'));
+        listening = _listening = listeningTo[id] = new Listening(this, obj);
+      }
+
+      // Bind callbacks on obj.
+      const error = tryCatchOn(obj, name, callback, this);
+      _listening = undefined;
+
+      if (error) throw error;
+      // If the target obj is not Backbone.Events, track events manually.
+      if (listening.interop) listening.start(name, callback, this, _listening);
+
+      return this;
+    }
+
+    /**
+     * Remove one or many callbacks. If `context` is null, removes all
+     * callbacks with that function. If `callback` is null, removes all
+     * callbacks for the event. If `name` is null, removes all bound
+     * callbacks for all events.
+     * @param {string} name
+     * @param {EventCallback} callback
+     * @param {any} [context]
+     * @return {EventEmitter}
+     */
+    off(name, callback, context) {
+      if (!this._events) return this;
+      this._events = eventsApi(offApi, this._events, name, callback, {
+        context: context,
+        listeners: this._listeners,
+      });
+
+      return this;
+    }
+
+    /**
+     * Tell this object to stop listening to either specific events ... or
+     * to every object it's currently listening to.
+     * @param {any} [obj]
+     * @param {string} [name]
+     * @param {EventCallback} [callback]
+     * @return {EventEmitter}
+     */
+    stopListening(obj, name, callback) {
+      const listeningTo = this._listeningTo;
+      if (!listeningTo) return this;
+
+      const ids = obj ? [obj._listenId] : keys(listeningTo);
+      for (let i = 0; i < ids.length; i++) {
+        const listening = listeningTo[ids[i]];
+
+        // If listening doesn't exist, this object is not currently
+        // listening to obj. Break out early.
+        if (!listening) break;
+
+        listening.obj.off(name, callback, this);
+        if (listening.interop) listening.stop(name, callback);
+      }
+      if (isEmpty(listeningTo)) this._listeningTo = undefined;
+
+      return this;
+    }
+
+    /**
+     * Bind an event to only be triggered a single time. After the first time
+     * the callback is invoked, its listener will be removed. If multiple events
+     * are passed in using the space-separated syntax, the handler will fire
+     * once for each event, not once for a combination of all events.
+     * @param {string} name
+     * @param {EventCallback} callback
+     * @param {any} context
+     * @return {EventEmitter}
+     */
+    once(name, callback, context) {
+      // Map the event into a `{event: once}` object.
+      const events = eventsApi(onceMap, {}, name, callback, this.off.bind(this));
+      if (typeof name === 'string' && (context === null || context === undefined)) callback = undefined;
+      return this.on(events, callback, context);
+    }
+
+    /**
+     * Inversion-of-control versions of `once`.
+     * @param {any} obj
+     * @param {string} name
+     * @param {EventCallback} [callback]
+     * @return {EventEmitter}
+     */
+    listenToOnce(obj, name, callback) {
+      // Map the event into a `{event: once}` object.
+      const events = eventsApi(onceMap, {}, name, callback, this.stopListening.bind(this, obj));
+      return this.listenTo(obj, events);
+    }
+
+    /**
+     * Trigger one or many events, firing all bound callbacks. Callbacks are
+     * passed the same arguments as `trigger` is, apart from the event name
+     * (unless you're listening on `"all"`, which will cause your callback to
+     * receive the true name of the event as the first argument).
+     * @param {string} name
+     * @return {EventEmitter}
+     */
+    trigger(name, ...args) {
+      if (!this._events) return this;
+
+      eventsApi(triggerApi, this._events, name, undefined, args);
+      return this;
+    }
+  };
+}
+
+export default EventEmitter;