@studiometa/js-toolkit 1.7.2 → 2.0.0-alpha.10

package/Base/index.d.ts

@@ -0,0 +1,217 @@
+/**
+ * @typedef {typeof Base} BaseConstructor
+ * @typedef {(Base) => Promise<BaseConstructor | { default: BaseConstructor }>} BaseAsyncConstructor
+ * @typedef {OptionsManager & { [name:string]: any }} BaseOptions
+ * @typedef {{ [name:string]: HTMLElement | HTMLElement[] }} BaseRefs
+ * @typedef {{ [nameOrSelector:string]: Base[] | Promise<Base>[] }} BaseChildren
+ * @typedef {{ [nameOrSelector:string]: BaseConstructor | BaseAsyncConstructor }} BaseConfigComponents
+ * @typedef {import('./managers/OptionsManager').OptionsSchema} BaseConfigOptions
+ * @typedef {import('./managers/ServicesManager.js').ServiceName} ServiceName
+ */
+/**
+ * @typedef {Object} BaseConfig
+ * @property {String} name
+ * @property {Boolean} [debug]
+ * @property {Boolean} [log]
+ * @property {String[]} [refs]
+ * @property {BaseConfigComponents} [components]
+ * @property {BaseConfigOptions} [options]
+ */
+/**
+ * Base class.
+ */
+export default class Base {
+    /**
+     * This is a Base instance.
+     * @type {Boolean}
+     * @readonly
+     */
+    static readonly $isBase: boolean;
+    /**
+     * @type {BaseConfig}
+     */
+    static config: BaseConfig;
+    /**
+     * Factory method to generate multiple instance of the class.
+     *
+     * @param  {String}      nameOrSelector The selector on which to mount each instance.
+     * @return {Array<Base>}                A list of the created instance.
+     */
+    static $factory(nameOrSelector: string): Array<Base>;
+    /**
+     * Class constructor where all the magic takes place.
+     *
+     * @param {HTMLElement} element The component's root element dd.
+     */
+    constructor(element: HTMLElement);
+    /**
+     * The instance parent.
+     * @type {Base}
+     */
+    $parent: Base;
+    /**
+     * The instance id.
+     * @type {string}
+     */
+    $id: string;
+    /**
+     * The root element.
+     * @type {HTMLElement}
+     */
+    $el: HTMLElement;
+    /**
+     * The state of the component.
+     * @type {Boolean}
+     */
+    $isMounted: boolean;
+    /**
+     * Get the root instance of the app.
+     * @return {Base}
+     */
+    get $root(): Base;
+    /**
+     * Merge configuration with the parents' configurations.
+     *
+     * @return {BaseConfig}
+     * @private
+     */
+    private get __config();
+    /**
+     * @type {ServicesManager}
+     * @private
+     */
+    private __services;
+    /**
+     * @type {ServicesManager}
+     */
+    get $services(): ServicesManager;
+    /**
+     * @type {RefsManager}
+     * @private
+     */
+    private __refs;
+    /**
+     * @return {RefsManager}
+     */
+    get $refs(): RefsManager;
+    /**
+     * @type {BaseOptions}
+     * @private
+     */
+    private __options;
+    /**
+     * @return {BaseOptions}
+     */
+    get $options(): BaseOptions;
+    /**
+     * @type {ChildrenManager}
+     * @private
+     */
+    private __children;
+    /**
+     * @return {ChildrenManager}
+     */
+    get $children(): ChildrenManager;
+    /**
+     * @type {EventsManager}
+     * @private
+     */
+    private __events;
+    /**
+     * Small helper to log stuff.
+     *
+     * @return {(...args: any) => void}
+     */
+    get $log(): (...args: any) => void;
+    /**
+     * Small helper to debug information.
+     *
+     * @return {(...args:any) => void}
+     */
+    get __debug(): (...args: any) => void;
+    /**
+     * Trigger the `mounted` callback.
+     * @return {this}
+     */
+    $mount(): this;
+    /**
+     * Update the instance children.
+     * @return {this}
+     */
+    $update(): this;
+    /**
+     * Trigger the `destroyed` callback.
+     * @return {this}
+     */
+    $destroy(): this;
+    /**
+     * Terminate a child instance when it is not needed anymore.
+     * @return {void}
+     */
+    $terminate(): void;
+    /**
+     * Bind a listener function to an event.
+     *
+     * @param  {string} event
+     *   Name of the event.
+     * @param  {EventListenerOrEventListenerObject} listener
+     *   Function to be called.
+     * @param {boolean|AddEventListenerOptions} [options]
+     *   Options for the `removeEventListener` method.
+     * @return {() => void}
+     *   A function to unbind the listener.
+     */
+    $on(event: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): () => void;
+    /**
+     * Unbind a listener function from an event.
+     *
+     * @param {string} event
+     *   Name of the event.
+     * @param {EventListenerOrEventListenerObject} listener
+     *   Function to be removed.
+     * @param {boolean|EventListenerOptions} [options]
+     *   Options for the `removeEventListener` method.
+     *
+     * @return {void}
+     */
+    $off(event: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    /**
+     * Emits an event.
+     *
+     * @param  {string} event
+     *   Name of the event.
+     * @param  {any[]}        args  The arguments to apply to the functions bound to this event.
+     * @return {void}
+     */
+    $emit(event: string, ...args: any[]): void;
+}
+export type BaseConstructor = typeof Base;
+export type BaseAsyncConstructor = (Base: any) => Promise<BaseConstructor | {
+    default: BaseConstructor;
+}>;
+export type BaseOptions = OptionsManager & {
+    [name: string]: any;
+};
+export type BaseRefs = {
+    [name: string]: HTMLElement | HTMLElement[];
+};
+export type BaseChildren = {
+    [nameOrSelector: string]: Base[] | Promise<Base>[];
+};
+export type BaseConfigComponents = {
+    [nameOrSelector: string]: typeof Base | BaseAsyncConstructor;
+};
+export type BaseConfigOptions = import('./managers/OptionsManager').OptionsSchema;
+export type ServiceName = import('./managers/ServicesManager.js').ServiceName;
+export type BaseConfig = {
+    name: string;
+    debug?: boolean;
+    log?: boolean;
+    refs?: string[];
+    components?: BaseConfigComponents;
+    options?: BaseConfigOptions;
+};
+import ServicesManager from "./managers/ServicesManager.js";
+import RefsManager from "./managers/RefsManager.js";
+import ChildrenManager from "./managers/ChildrenManager.js";
+import OptionsManager from "./managers/OptionsManager.js";

package/Base/index.js

@@ -0,0 +1,237 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+
+function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); if (enumerableOnly) { symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; }); } keys.push.apply(keys, symbols); } return keys; }
+
+function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i] != null ? arguments[i] : {}; if (i % 2) { ownKeys(Object(source), true).forEach(function (key) { _defineProperty(target, key, source[key]); }); } else if (Object.getOwnPropertyDescriptors) { Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)); } else { ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } } return target; }
+
+import { callMethod, getComponentElements } from './utils.js';
+import ChildrenManager from './managers/ChildrenManager.js';
+import RefsManager from './managers/RefsManager.js';
+import ServicesManager from './managers/ServicesManager.js';
+import EventsManager from './managers/EventsManager.js';
+import OptionsManager from './managers/OptionsManager.js';
+var id = 0;
+
+function noop() {}
+
+export default class Base {
+  get $root() {
+    if (!this.$parent) {
+      return this;
+    }
+
+    var parent = this.$parent;
+    var root = this.$parent;
+
+    while (parent) {
+      if (!parent.$parent) {
+        root = parent;
+      }
+
+      parent = parent.$parent;
+    }
+
+    return root;
+  }
+
+  get __config() {
+    var proto = Object.getPrototypeOf(this);
+    var {
+      config
+    } = proto.constructor;
+
+    while (proto.constructor.config && proto.constructor.$isBase) {
+      config = _objectSpread(_objectSpread({}, proto.constructor.config), config);
+
+      if (proto.constructor.config.options) {
+        config.options = _objectSpread(_objectSpread({}, proto.constructor.config.options), config.options);
+      }
+
+      proto = Object.getPrototypeOf(proto);
+    }
+
+    return config;
+  }
+
+  get $services() {
+    var services = this.__services;
+    this.$emit('get:services', services);
+    return services;
+  }
+
+  get $refs() {
+    var refs = this.__refs;
+    this.$emit('get:refs', refs);
+    return refs;
+  }
+
+  get $options() {
+    var options = this.__options;
+    this.$emit('get:options', options);
+    return options;
+  }
+
+  get $children() {
+    var children = this.__children;
+    this.$emit('get:children', children);
+    return children;
+  }
+
+  get $log() {
+    return this.__options.log ? window.console.log.bind(window, "[".concat(this.__config.name, "]")) : noop;
+  }
+
+  get __debug() {
+    return this.__options.debug && typeof window.__DEV__ !== 'undefined' && window.__DEV__ ? window.console.log.bind(window, "[debug] [".concat(this.$id, "]")) : noop;
+  }
+
+  constructor(element) {
+    _defineProperty(this, "$parent", null);
+
+    _defineProperty(this, "$id", void 0);
+
+    _defineProperty(this, "$el", void 0);
+
+    _defineProperty(this, "$isMounted", false);
+
+    _defineProperty(this, "__services", void 0);
+
+    _defineProperty(this, "__refs", void 0);
+
+    _defineProperty(this, "__options", void 0);
+
+    _defineProperty(this, "__children", void 0);
+
+    _defineProperty(this, "__events", void 0);
+
+    if (!element) {
+      throw new Error('The root element must be defined.');
+    }
+
+    var {
+      __config
+    } = this;
+
+    if (!__config) {
+      throw new Error('The `config` static property must be defined.');
+    }
+
+    if (!__config.name) {
+      throw new Error('The `config.name` property is required.');
+    }
+
+    this.$id = "".concat(__config.name, "-").concat(id);
+    id += 1;
+    this.$el = element;
+
+    if (!('__base__' in this.$el)) {
+      Object.defineProperty(this.$el, '__base__', {
+        get: () => this,
+        configurable: true
+      });
+    }
+
+    this.__options = new OptionsManager(element, __config.options || {}, __config);
+    this.__services = new ServicesManager(this);
+    this.__events = new EventsManager(element, this);
+    this.__children = new ChildrenManager(this, element, __config.components || {}, this.__events);
+    this.__refs = new RefsManager(this, element, __config.refs || [], this.__events);
+
+    this.__debug('constructor', this);
+
+    return this;
+  }
+
+  $mount() {
+    this.__debug('$mount');
+
+    this.$children.registerAll();
+    this.$refs.registerAll();
+
+    this.__events.bindRootElement();
+
+    this.$services.enableAll();
+    this.$children.mountAll();
+    callMethod(this, 'mounted');
+    this.$isMounted = true;
+    return this;
+  }
+
+  $update() {
+    this.__debug('$update');
+
+    this.$refs.unregisterAll();
+    this.$services.disableAll();
+    this.$children.registerAll();
+    this.$refs.registerAll();
+    this.$services.enableAll();
+    this.$children.updateAll();
+    callMethod(this, 'updated');
+    return this;
+  }
+
+  $destroy() {
+    this.__debug('$destroy');
+
+    this.__events.unbindRootElement();
+
+    this.$refs.unregisterAll();
+    this.$services.disableAll();
+    this.$children.destroyAll();
+    callMethod(this, 'destroyed');
+    this.$isMounted = false;
+    return this;
+  }
+
+  $terminate() {
+    this.__debug('$terminate');
+
+    this.$destroy();
+    callMethod(this, 'terminated');
+    Object.defineProperty(this.$el, '__base__', {
+      value: 'terminated',
+      configurable: false,
+      writable: false
+    });
+  }
+
+  static $factory(nameOrSelector) {
+    if (!nameOrSelector) {
+      throw new Error('The $factory method requires a component’s name or selector to be specified.');
+    }
+
+    return getComponentElements(nameOrSelector).map(el => new this(el).$mount());
+  }
+
+  $on(event, listener, options) {
+    this.__debug('$on', event, listener, options);
+
+    this.$el.addEventListener(event, listener, options);
+    return () => {
+      this.$off(event, listener, options);
+    };
+  }
+
+  $off(event, listener, options) {
+    this.__debug('$off', event, listener);
+
+    this.$el.removeEventListener(event, listener, options);
+  }
+
+  $emit(event) {
+    for (var _len = arguments.length, args = new Array(_len > 1 ? _len - 1 : 0), _key = 1; _key < _len; _key++) {
+      args[_key - 1] = arguments[_key];
+    }
+
+    this.__debug('$emit', event, args);
+
+    this.$el.dispatchEvent(new CustomEvent(event, {
+      detail: args
+    }));
+  }
+
+}
+
+_defineProperty(Base, "$isBase", true);
+
+_defineProperty(Base, "config", void 0);

package/Base/managers/ChildrenManager.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @typedef {import('../index.js').default} Base
+ * @typedef {import('../index.js').BaseConstructor} BaseConstructor
+ * @typedef {import('../index.js').BaseAsyncConstructor} BaseAsyncConstructor
+ * @typedef {import('../index.js').BaseConfigComponents} BaseConfigComponents
+ * @typedef {import('./EventsManager.js').default} EventsManager
+ */
+/**
+ * Children manager.
+ */
+export default class ChildrenManager {
+    /**
+     * Class constructor.
+     * @param {Base} base
+     *   The component's instance.
+     * @param {HTMLElement} element
+     *   The component's root element
+     * @param {BaseConfigComponents} components
+     *   The children components' classes
+     * @param {EventsManager} eventsManager
+     */
+    constructor(base: Base, element: HTMLElement, components: BaseConfigComponents, eventsManager: EventsManager);
+    /**
+     * @type {Base}
+     * @private
+     */
+    private __base;
+    /**
+     * @type {HTMLElement}
+     * @private
+     */
+    private __element;
+    /**
+     * @type {BaseConfigComponents}
+     * @private
+     */
+    private __components;
+    /**
+     * @type {EventsManager}
+     * @private
+     */
+    private __eventsManager;
+    /**
+     * @return {string[]}
+     */
+    get registeredNames(): string[];
+    /**
+     * Register instances of all children components.
+     */
+    registerAll(): void;
+    /**
+     * Register instance of a child component.
+     *
+     * @param {string} name
+     *   The name of the child component.
+     * @param {BaseConstructor|BaseAsyncConstructor} component
+     *   A Base class or a Promise for async components.
+     * @private
+     */
+    private __register;
+    /**
+     * Get a child component's instance.
+     *
+     * @param {HTMLElement & { __base__?: Base | 'terminated' }} el
+     *   The root element of the child component.
+     * @param {BaseConstructor|BaseAsyncConstructor} ComponentClass
+     *   A Base class or a Promise for async components.
+     * @param {string} name
+     *   The name of the child component.
+     * @return {Base|Promise|'terminated'}
+     *   A Base instance or a Promise resolving to a Base instance.
+     * @private
+     */
+    private __getChild;
+    /**
+     * Mount all child component instances.
+     */
+    mountAll(): void;
+    /**
+     * Update all child component instances.
+     */
+    updateAll(): void;
+    /**
+     * Destroy all child component instances.
+     */
+    destroyAll(): void;
+    /**
+     * Execute the given hook for all children instances.
+     *
+     * @param {'$mount'|'$update'|'$destroy'} hook The hook to execute.
+     * @private
+     */
+    private __triggerHookForAll;
+    /**
+     * Execute the given hook for the given instance.
+     *
+     * @param {'$mount'|'$update'|'$destroy'} hook The hook to trigger.
+     * @param {Base} instance The target instance.
+     * @param {string} name The name of the component.
+     * @private
+     */
+    private __triggerHook;
+}
+export type Base = import('../index.js').default;
+export type BaseConstructor = import('../index.js').BaseConstructor;
+export type BaseAsyncConstructor = import('../index.js').BaseAsyncConstructor;
+export type BaseConfigComponents = import('../index.js').BaseConfigComponents;
+export type EventsManager = import('./EventsManager.js').default;

package/Base/managers/ChildrenManager.js

@@ -0,0 +1,124 @@
+import _defineProperty from "@babel/runtime/helpers/defineProperty";
+import { getComponentElements } from '../utils.js';
+export default class ChildrenManager {
+  get registeredNames() {
+    return Object.keys(this).filter(key => !key.startsWith('__'));
+  }
+
+  constructor(base, element, components, eventsManager) {
+    _defineProperty(this, "__base", void 0);
+
+    _defineProperty(this, "__element", void 0);
+
+    _defineProperty(this, "__components", void 0);
+
+    _defineProperty(this, "__eventsManager", void 0);
+
+    Object.defineProperties(this, {
+      __base: {
+        enumerable: false,
+        writable: false,
+        value: base
+      },
+      __element: {
+        enumerable: false,
+        writable: false,
+        value: element
+      },
+      __components: {
+        enumerable: false,
+        writable: false,
+        value: components
+      },
+      __eventsManager: {
+        enumerable: false,
+        writable: false,
+        value: eventsManager
+      }
+    });
+  }
+
+  registerAll() {
+    Object.entries(this.__components).forEach(_ref => {
+      var [name, component] = _ref;
+      return this.__register(name, component);
+    });
+  }
+
+  __register(name, component) {
+    Object.defineProperty(this, name, {
+      enumerable: true,
+      configurable: true,
+      get: () => {
+        var elements = getComponentElements(name, this.__element);
+
+        if (elements.length === 0) {
+          return [];
+        }
+
+        return elements.map(element => this.__getChild(element, component, name)).filter(instance => instance !== 'terminated');
+      }
+    });
+  }
+
+  __getChild(el, ComponentClass, name) {
+    if (el.__base__) {
+      return el.__base__;
+    }
+
+    if ('$isBase' in ComponentClass) {
+      var child = new ComponentClass(el);
+      Object.defineProperty(child, '$parent', {
+        get: () => this.__base
+      });
+      return child;
+    }
+
+    return ComponentClass(this.__base).then(module => {
+      var _module$default;
+
+      return this.__getChild(el, (_module$default = module.default) !== null && _module$default !== void 0 ? _module$default : module, name);
+    });
+  }
+
+  mountAll() {
+    this.__triggerHookForAll('$mount');
+  }
+
+  updateAll() {
+    this.__triggerHookForAll('$update');
+  }
+
+  destroyAll() {
+    this.__triggerHookForAll('$destroy');
+  }
+
+  __triggerHookForAll(hook) {
+    this.registeredNames.forEach(name => {
+      this[name].forEach(instance => {
+        if (instance instanceof Promise) {
+          instance.then(resolvedInstance => this.__triggerHook(hook, resolvedInstance, name));
+        } else {
+          this.__triggerHook(hook, instance, name);
+        }
+      });
+    });
+  }
+
+  __triggerHook(hook, instance, name) {
+    if (hook === '$update' && !instance.$isMounted) {
+      hook = '$mount';
+    }
+
+    if (hook === '$update' || hook === '$destroy') {
+      this.__eventsManager.unbindChild(name, instance);
+    }
+
+    if (hook === '$update' || hook === '$mount') {
+      this.__eventsManager.bindChild(name, instance);
+    }
+
+    instance[hook]();
+  }
+
+}