@qtoggle/qui 0.0.0

package/js/base/base.js

@@ -0,0 +1,47 @@
+/**
+ * @namespace qui.base
+ */
+
+
+/**
+ * Make an imported module globally accessible via `window`.
+ *
+ * This function is intended to be used with dynamic imports, such as:
+ *
+ *     import('$qui/path/to/module.js').then(globalize('qui.path.to.module'))
+ *
+ * When imported module has default export, the last element in `path` is used to represent it:
+ *
+ *     import('$qui/path/to/class.js').then(globalize('qui.path.to.Class'))
+ *
+ * @alias qui.base.globalize
+ * @param {String} path dotted path
+ * @returns {Function} a function that handles dynamic import call promise result
+ */
+export function globalize(path) {
+    return function (module) {
+        let parts = path.split('.')
+        let obj = window
+        let defName = null
+
+        /* When module has default export, last element of path is used as default name */
+        if ('default' in module) {
+            defName = parts[parts.length - 1]
+            parts = parts.slice(0, -1)
+        }
+
+        parts.forEach(function (part) {
+            if (!(part in obj)) {
+                obj[part] = {}
+            }
+
+            obj = obj[part]
+        })
+
+        Object.entries(module).forEach(([key, value]) => (obj[key] = value))
+        if (defName) {
+            obj[defName] = obj['default']
+            delete obj['default']
+        }
+    }
+}

package/js/base/condition-variable.js

@@ -0,0 +1,92 @@
+
+import {AssertionError} from '$qui/base/errors.js'
+
+
+/**
+ * An asynchronous implementation of condition variables based on promises. Due to the fact that promises cannot be
+ * easily extended, this class actually wraps a promise.
+ * @alias qui.base.ConditionVariable
+ * @extends Promise
+ */
+class ConditionVariable {
+
+    /**
+     * @constructs
+     */
+    constructor() {
+        this._resolve = null
+        this._reject = null
+
+        this._promise = new Promise(function (resolve, reject) {
+
+            this._resolve = resolve
+            this._reject = reject
+
+        }.bind(this))
+
+        this._fulfilled = false
+        this._cancelled = false
+    }
+
+    /**
+     * Fulfill the condition, notifying everybody that waits on this condition.
+     * @param {*} [arg] an optional fulfill argument
+     */
+    fulfill(arg) {
+        if (this._fulfilled || this._cancelled) {
+            throw new AssertionError('Condition variable already settled')
+        }
+
+        this._fulfilled = true
+        this._resolve(arg)
+    }
+
+    /**
+     * Cancel the condition, notifying everybody that waits on this condition.
+     * @param {*} [error] an optional error argument
+     */
+    cancel(error) {
+        if (this._fulfilled || this._cancelled) {
+            throw new AssertionError('Condition variable already settled')
+        }
+
+        this._cancelled = true
+        this._reject(error)
+    }
+
+    /**
+     * Tell if the condition is fulfilled or not.
+     * @returns {Boolean}
+     */
+    isFulfilled() {
+        return this._fulfilled
+    }
+
+    /**
+     * Tell if the condition is cancelled or not.
+     * @returns {Boolean}
+     */
+    isCancelled() {
+        return this._cancelled
+    }
+
+    /**
+     * Tell if the condition is settled (fulfilled or cancelled) or not.
+     * @returns {Boolean}
+     */
+    isSettled() {
+        return this._fulfilled || this._cancelled
+    }
+
+    then(f, r) {
+        return this._promise.then(f, r)
+    }
+
+    catch(r) {
+        return this._promise.catch(r)
+    }
+
+}
+
+
+export default ConditionVariable

package/js/base/errors.js

@@ -0,0 +1,36 @@
+/**
+ * @namespace qui.base.errors
+ */
+
+/**
+ * An error class used when assertions fail.
+ * @alias qui.base.errors.AssertionError
+ * @extends Error
+ */
+export class AssertionError extends Error {
+}
+
+/**
+ * An error class used when an operation times out.
+ * @alias qui.base.errors.TimeoutError
+ * @extends Error
+ */
+export class TimeoutError extends Error {
+}
+
+/**
+ * An error class thrown from methods or functions that are not implemented.
+ * @alias qui.base.errors.NotImplementedError
+ * @extends Error
+ */
+export class NotImplementedError extends Error {
+}
+
+/**
+ * An error class used to indicate an operation that has been cancelled. Exceptions of this type are usually ignored and
+ * not treated as errors.
+ * @alias qui.base.errors.CancelledError
+ * @extends Error
+ */
+export class CancelledError extends Error {
+}

package/js/base/i18n.js

@@ -0,0 +1,20 @@
+/**
+ * @namespace qui.base.i18n
+ */
+
+/**
+ * Translate a message.
+ * @alias qui.base.i18n.gettext
+ * @param {String} msg the message to translate
+ * @returns {String} the translated message or the original message, if no translation found
+ */
+export function gettext(msg) {
+    if (window._jsTranslations) {
+        let transMsg = window._jsTranslations[msg]
+        if (transMsg != null) {
+            return transMsg
+        }
+    }
+
+    return msg
+}

package/js/base/mixwith.js

@@ -0,0 +1,135 @@
+/**
+ * Utilities for writing mixins. Copied and adapted from Justin Fagnani's work:
+ * {@link https://github.com/justinfagnani/mixwith.js}.
+ *
+ * @namespace qui.base.mixwith
+ */
+
+const _appliedMixin = '__mixwith_appliedMixin'
+const _wrappedMixin = '__mixwith_wrappedMixin'
+
+
+/**
+ * A function that, when called with (applied to) a superclass, generates a new class inherited indirectly from the
+ * superclass and directly from an intermediate mixin dynamic class, offering extra functionality, specific to the
+ * mixin.
+ *
+ * @callback qui.base.mixwith.MixinFunction
+ * @param {typeof Object} superclass class to which the mixin will be applied
+ * @param rootclass
+ * @param mixin
+ */
+
+
+function apply(superclass, rootclass, mixin) {
+    let application = mixin(superclass, rootclass)
+    application.prototype[_appliedMixin] = unwrap(mixin)
+
+    return application
+}
+
+function isApplicationOf(proto, mixin) {
+    return Object.prototype.hasOwnProperty.call(proto, _appliedMixin) && proto[_appliedMixin] === unwrap(mixin)
+}
+
+function hasMixin(o, mixin) {
+    while (o != null) {
+        if (isApplicationOf(o, mixin)) {
+            return true
+        }
+
+        o = Object.getPrototypeOf(o)
+    }
+
+    return false
+}
+
+function wrap(mixin, wrapper) {
+    Object.setPrototypeOf(wrapper, mixin)
+    if (!mixin[_wrappedMixin]) {
+        mixin[_wrappedMixin] = mixin
+    }
+
+    return wrapper
+}
+
+function unwrap(wrapper) {
+    return wrapper[_wrappedMixin] || wrapper
+}
+
+function HasInstance(mixin) {
+    if (Symbol && Symbol.hasInstance) {
+        Object.defineProperty(mixin, Symbol.hasInstance, {
+            value(o) {
+                return hasMixin(o, mixin)
+            }
+        })
+    }
+
+    return mixin
+}
+
+function BareMixin(mixin) {
+    return wrap(mixin, (s, r) => apply(s, r, mixin))
+}
+
+
+/**
+ * A helper class capable of applying one or more mixins to a superclass.
+ * @alias qui.base.mixwith.MixinBuilder
+ */
+export class MixinBuilder {
+
+    /**
+     * @constructs
+     * @param {typeof Object} superclass
+     */
+    constructor(superclass) {
+        this.superclass = superclass || Object
+    }
+
+    /**
+     * @param {...qui.base.mixwith.MixinFunction} mixins mixins to apply to the superclass
+     * @returns {*} a new class derived from the superclass, with all `mixins` applied
+     */
+    with(...mixins) {
+        return mixins.reduce((c, m) => m(c, /* rootclass = */ this.superclass), this.superclass)
+    }
+
+}
+
+
+/**
+ * Prepare a mixin function.
+ * @alias qui.base.mixwith.Mixin
+ * @param {qui.base.mixwith.MixinFunction} mixin the mixin function
+ * @returns {qui.base.mixwith.MixinFunction} the prepared mixin function
+ */
+export function Mixin(mixin) {
+    return HasInstance(BareMixin(mixin))
+}
+
+
+/**
+ * Apply a list of mixins to a superclass.
+ *
+ * ```
+ * class X extends mix(Object).with(A, B, C) {}
+ * ```
+ *
+ * The mixins are applied in order to the superclass, so the prototype chain
+ * will be: X->C'->B'->A'->Object.
+ *
+ * This is purely a convenience function. The above example is equivalent to:
+ *
+ * ```
+ * class X extends C(B(A(Object))) {}
+ * ```
+ *
+ * @alias qui.base.mixwith.mix
+ * @param {typeof Object} [superclass]
+ * @returns {MixinBuilder}
+ */
+export function mix(superclass = Object) {
+    return new MixinBuilder(superclass)
+}

package/js/base/require-js-compat.js

@@ -0,0 +1,78 @@
+/*
+ * A layer of compatibility between modules based on `define()`/`require()` and ES6 modules.
+ */
+
+let definedModules = {}
+
+const ALIASES = {
+    jquery: ['jQuery']
+}
+
+
+function findCallerModuleName() {
+    /* Use stack trace to find the name of the first JS file, which is expected to be the module */
+    let error = new Error()
+    let names = error.stack.match(new RegExp('[A-Za-z0-9_.-]+\\.js', 'g'))
+    if (!names) {
+        return
+    }
+
+    /* The name of the module is the name of the script file without the extension */
+    let name = names[names.length - 1]
+    name = name.split('.').slice(0, -1).join('.')
+
+    return name
+}
+
+window.define = function (...args) {
+    let name = null
+    let depNames = []
+    let factory
+
+    if (args.length < 1) {
+        return
+    }
+    else if (args.length < 2) {
+        [factory] = args
+    }
+    else if (args.length < 3) {
+        [depNames, factory] = args
+    }
+    else {
+        [name, depNames, factory] = args
+    }
+
+    /* For anonymous modules, we need to look for the name of the module script */
+    if (!name) {
+        name = findCallerModuleName()
+    }
+
+    let deps = depNames.map(depName => window[depName])
+    let module
+    if (typeof factory === 'function') {
+        module = factory.apply(null, deps)
+    }
+    else {
+        module = factory
+    }
+
+    if (name) {
+        window[name] = definedModules[name] = module
+    }
+
+    /* Also register module under its aliases */
+    (ALIASES[name] || []).forEach(function (alias) {
+        window[alias] = module
+    })
+}
+
+window.define.amd = true
+
+
+/**
+ * Cleanup workarounds set up for providing `define()`/`require()` compatibility.
+ */
+export function cleanup() {
+    Object.keys(definedModules).forEach(name => delete window[name])
+    delete window['define']
+}

package/js/base/signal.js

@@ -0,0 +1,91 @@
+/**
+ * A signal handler.
+ * @callback qui.base.Signal.SignalHandler
+ */
+
+/**
+ * A signal.
+ * @alias qui.base.Signal
+ */
+class Signal {
+
+    /**
+     * @constructs
+     * @param {Object} [object] an optional object that owns and emits the signal
+     */
+    constructor(object = null) {
+        this._object = object
+        this._handlers = []
+    }
+
+    /**
+     * Add a handler to the signal. This function doesn't check for duplicates, so if a handler is bound more than once
+     * to the same signal, it will be called multiple times when the signal is emitted.
+     * @param {qui.base.Signal.SignalHandler} handler the handler function to add
+     * @param {Boolean} [once] optionally set this to `true` to call the handler only once, the first time the signal is
+     * emitted, and then disconnect the handler from the signal
+     * @returns {qui.base.Signal} this signal
+     */
+    connect(handler, once = false) {
+        this._handlers.push({handler: handler, once: once})
+
+        return this
+    }
+
+    /**
+     * Remove a handler from the signal.
+     * @param {qui.base.Signal.SignalHandler} [handler] the handler function to disconnect
+     * @returns {qui.base.Signal} this signal
+     */
+    disconnect(handler) {
+        this._handlers = this._handlers.filter(e => e.handler !== handler)
+
+        return this
+    }
+
+    /**
+     * Remove all handlers from the signal.
+     * @returns {qui.base.Signal} this signal
+     */
+    disconnectAll() {
+        this._handlers = []
+
+        return this
+    }
+
+    /**
+     * Emit the signal. All the handler functions will be called in the order of binding, until one of them returns
+     * `false`.
+     *
+     * Any additional arguments to this function will be passed to the handlers.
+     *
+     * The handler functions are called with `this` set to the owner object of the signal.
+     *
+     * @params {...*} args arguments to be passed to the handlers
+     * @returns {*} the value returned by the last called handler
+     */
+    emit(...args) {
+        // eslint-disable-next-line no-undef-init
+        let result = undefined
+
+        this._handlers.some(function ({handler, once}) {
+
+            if (once) {
+                this.disconnect(handler)
+            }
+
+            result = handler.apply(this._object, args)
+            if (result === false) {
+                /* Returning false from a handler will stop the signal from being handled any further */
+                return true
+            }
+
+        }, this)
+
+        return result
+    }
+
+}
+
+
+export default Signal

package/js/base/singleton.js

@@ -0,0 +1,66 @@
+
+import {Mixin} from '$qui/base/mixwith.js'
+
+
+/** @lends qui.base.SingletonMixin */
+const SingletonMixin = Mixin((superclass = Object) => {
+
+    /**
+     * A mixin that helps implementing the singleton pattern.
+     * @alias qui.base.SingletonMixin
+     * @mixin
+     */
+    class SingletonMixin extends superclass {
+
+        static _instance = null
+        static _args = null
+
+
+        /**
+         * @constructs
+         * @param {...*} args parent class parameters
+         */
+        constructor(...args) {
+            super(...args)
+        }
+
+        /**
+         * Prepare the class for instantiation, establishing the constructor arguments.
+         *
+         * Any arguments passed to this method will be passed to the constructor, when creating the singleton.
+         *
+         * @param {...*} args arguments to be passed to the constructor
+         */
+        static setup(...args) {
+            this._args = args
+            this._instance = null
+        }
+
+        /**
+         * Return the singleton instance. Instantiates the class on first call.
+         * @returns {Object} the instance
+         */
+        static getInstance() {
+            if (this._instance) {
+                return this._instance
+            }
+
+            /* Make sure setup() has been called */
+            if (this._args == null) {
+                this.setup()
+            }
+
+            // eslint-disable-next-line new-parens
+            this._instance = new (this.bind.apply(this, this._args))
+
+            return this._instance
+        }
+
+    }
+
+    return SingletonMixin
+
+})
+
+
+export default SingletonMixin

package/js/base/timer.js

@@ -0,0 +1,126 @@
+
+import {AssertionError} from '$qui/base/errors.js'
+
+
+/**
+ * A convenience class that makes it easy to work with timeouts.
+ * @alias qui.base.Timer
+ */
+class Timer {
+
+    /**
+     * @constructs
+     * @param {Number} [defaultTimeout] a default timeout, in milliseconds
+     * @param {Function} [onTimeout] an optional timeout callback
+     * @param {Boolean} [repeat] set to `true` to automatically restart timer on timeout
+     */
+    constructor(defaultTimeout = null, onTimeout = null, repeat = false) {
+        this._defaultTimeout = defaultTimeout
+        this._onTimeout = onTimeout
+        this._repeat = repeat
+
+        this._cancelled = false
+        this._startedTime = null
+        this._timeoutHandle = null
+    }
+
+    /**
+     * Start the timer.
+     * @param {Number} [timeout] a timeout, in milliseconds, that overrides the timer's `defaultTimeout`
+     */
+    start(timeout = null) {
+        if (this._timeoutHandle) {
+            throw new AssertionError('Timer already started')
+        }
+
+        if (timeout == null) {
+            timeout = this._defaultTimeout
+        }
+
+        if (timeout == null) {
+            throw new AssertionError('Cannot start timer without timeout')
+        }
+
+        this._cancelled = false
+        this._startedTime = new Date().getTime()
+
+        this._timeoutHandle = setTimeout(function () {
+            this._timeoutHandle = null
+            if (this._repeat) {
+                this.start(timeout)
+            }
+            if (this._onTimeout) {
+                this._onTimeout()
+            }
+        }.bind(this), timeout)
+    }
+
+    /**
+     * Cancel the timer.
+     */
+    cancel() {
+        if (!this._timeoutHandle) {
+            throw new AssertionError('Timer not started')
+        }
+        if (this._cancelled) {
+            throw new AssertionError('Timer already cancelled')
+        }
+
+        clearTimeout(this._timeoutHandle)
+        this._timeoutHandle = null
+        this._cancelled = true
+        this._startedTime = null
+    }
+
+    /**
+     * Start the timer if it's not currently running. Otherwise cancel and start it over.
+     * @param {Number} [timeout] a timeout, in milliseconds, that overrides the timer's `defaultTimeout`
+     */
+    restart(timeout = null) {
+        if (this.isRunning()) {
+            this.cancel()
+        }
+
+        this.start(timeout)
+    }
+
+    /**
+     * Tell if the timer is currently running.
+     * @returns {Boolean}
+     */
+    isRunning() {
+        return !!this._timeoutHandle
+    }
+
+    /**
+     * Tell if the timer has been cancelled.
+     * @returns {Boolean}
+     */
+    isCancelled() {
+        return this._cancelled
+    }
+
+    /**
+     * Tell if the timer has fired.
+     * @returns {Boolean}
+     */
+    isFired() {
+        return !this._timeoutHandle && !!this._startedTime
+    }
+
+    /**
+     * Tell the remaining time, in milliseconds.
+     * @returns {Number}
+     */
+    getRemainingTime() {
+        if (this.isRunning()) {
+            throw new AssertionError('Timer not started')
+        }
+
+        return new Date().getTime() - this._startedTime
+    }
+
+}
+
+
+export default Timer