@qtoggle/qui 0.0.0

package/js/utils/date.js

@@ -0,0 +1,300 @@
+/**
+ * @namespace qui.utils.date
+ */
+
+/* eslint-disable no-multi-spaces */
+
+import {gettext} from '$qui/base/i18n.js'
+
+
+const MONTH_NAMES = [
+    {longName: 'January',   shortName: 'Jan', longNameTrans: gettext('January'),   shortNameTrans: gettext('Jan')},
+    {longName: 'February',  shortName: 'Feb', longNameTrans: gettext('February'),  shortNameTrans: gettext('Feb')},
+    {longName: 'March',     shortName: 'Mar', longNameTrans: gettext('March'),     shortNameTrans: gettext('Mar')},
+    {longName: 'April',     shortName: 'Apr', longNameTrans: gettext('April'),     shortNameTrans: gettext('Apr')},
+    {longName: 'May',       shortName: 'May', longNameTrans: gettext('May'),       shortNameTrans: gettext('May')},
+    {longName: 'June',      shortName: 'Jun', longNameTrans: gettext('June'),      shortNameTrans: gettext('Jun')},
+    {longName: 'July',      shortName: 'Jul', longNameTrans: gettext('July'),      shortNameTrans: gettext('Jul')},
+    {longName: 'August',    shortName: 'Aug', longNameTrans: gettext('August'),    shortNameTrans: gettext('Aug')},
+    {longName: 'September', shortName: 'Sep', longNameTrans: gettext('September'), shortNameTrans: gettext('Sep')},
+    {longName: 'October',   shortName: 'Oct', longNameTrans: gettext('October'),   shortNameTrans: gettext('Oct')},
+    {longName: 'November',  shortName: 'Nov', longNameTrans: gettext('November'),  shortNameTrans: gettext('Nov')},
+    {longName: 'December',  shortName: 'Dec', longNameTrans: gettext('December'),  shortNameTrans: gettext('Dec')}
+]
+
+const WEEK_DAY_NAMES = [
+    {longName: 'Sunday',    shortName: 'Sun', longNameTrans: gettext('Sunday'),    shortNameTrans: gettext('Sun')},
+    {longName: 'Monday',    shortName: 'Mon', longNameTrans: gettext('Monday'),    shortNameTrans: gettext('Mon')},
+    {longName: 'Tuesday',   shortName: 'Tue', longNameTrans: gettext('Tuesday'),   shortNameTrans: gettext('Tue')},
+    {longName: 'Wednesday', shortName: 'Wed', longNameTrans: gettext('Wednesday'), shortNameTrans: gettext('Wed')},
+    {longName: 'Thursday',  shortName: 'Thu', longNameTrans: gettext('Thursday'),  shortNameTrans: gettext('Thu')},
+    {longName: 'Friday',    shortName: 'Fri', longNameTrans: gettext('Friday'),    shortNameTrans: gettext('Fri')},
+    {longName: 'Saturday',  shortName: 'Sat', longNameTrans: gettext('Saturday'),  shortNameTrans: gettext('Sat')}
+]
+
+const MILLISECONDS_IN_MINUTE = 60 * 1000
+const MILLISECONDS_IN_HOUR = 60 * MILLISECONDS_IN_MINUTE
+const MILLISECONDS_IN_DAY = 24 * MILLISECONDS_IN_HOUR
+
+
+/**
+ * Transform a date into a string, according to the given format. Recognized placeholders:
+ *  * `"%a"` - short week day name (e.g. `"Mon"`)
+ *  * `"%A"` - long week day name (e.g. `"Monday"`)
+ *  * `"%w"` - day of week, from `"0"` (Sunday) to `"6"` (Saturday),
+ *  * `"%u"` - day of week, from `"1"` (Monday) to `"7"` (Sunday),
+ *  * `"%d"` - zero padded day of month, from `"00"` to `"31'`
+ *  * `"%b"` - short month name (e.g. `"Apr"`)
+ *  * `"%B"` - long month name (e.g. `"April"`)
+ *  * `"%m"` - zero padded month number, from `"01"` to `"12"`
+ *  * `"%y"` - zero padded short year (e.g. `"97"` or `"03"`)
+ *  * `"%Y"` - zero padded long year (e.g. `"1997"` or `"2003"`)
+ *  * `"%H"` - zero padded hour, from `"00"` to `"23"`
+ *  * `"%I"` - zero padded hour, from `"00"` to `"11"`
+ *  * `"%p"` - `"am"` or `"pm"`
+ *  * `"%M"` - zero padded minutes, from `"00"` to `"59"`
+ *  * `"%S"` - zero padded seconds, from `"00"` to `"59"`
+ *  * `"%f"` - zero padded milliseconds, from `"000"` to `"999"`
+ *
+ * Use a `-` character in front of a format specifier to remove zero padding (e.g. "%-d"`).
+ *
+ * @alias qui.utils.date.formatPercent
+ * @param {Date} date the date to format
+ * @param {String} format the format to be used
+ * @param {Boolean} [trans] whether to translate week day and month names; defaults to `true`
+ * @returns {String} the formatted date
+ */
+export function formatPercent(date, format, trans = true) {
+    if (!date || isNaN(date.getTime())) {
+        return ''
+    }
+
+    let weekDay = date.getDay()
+    let monthDay = date.getDate()
+    let month = date.getMonth()
+    let year = date.getFullYear()
+    let hours = date.getHours()
+    let minutes = date.getMinutes()
+    let seconds = date.getSeconds()
+    let milliseconds = date.getMilliseconds()
+
+    let hours12
+    if (hours === 0) {
+        hours12 = 12
+    }
+    else if (hours < 13) {
+        hours12 = hours
+    }
+    else { /* Hours between 13 and 23 */
+        hours12 = hours % 12
+    }
+
+    let ampm = hours < 12 ? 'AM' : 'PM'
+    let weekDayName = WEEK_DAY_NAMES[weekDay]
+    let weekDayNameShort = trans ? weekDayName.shortNameTrans : weekDayName.shortName
+    let weekDayNameLong = trans ? weekDayName.longNameTrans : weekDayName.longName
+    let monthName = MONTH_NAMES[month]
+    let monthNameShort = trans ? monthName.shortNameTrans : monthName.shortName
+    let monthNameLong = trans ? monthName.longNameTrans : monthName.longName
+
+    let result = ''
+    let percent = false
+    let noLeading = false
+    for (let i = 0; i < format.length; i++) {
+        let c = format.charAt(i)
+        if (percent) {
+            if (c === '-') {
+                noLeading = true
+            }
+            else {
+                switch (c) {
+                    case 'a':
+                        result += weekDayNameShort
+                        break
+
+                    case 'A':
+                        result += weekDayNameLong
+                        break
+
+                    case 'w':
+                        result += weekDay.toString()
+                        break
+
+                    case 'u':
+                        result += (weekDay || 7).toString()
+                        break
+
+                    case 'd':
+                        result += monthDay.toString().padStart(noLeading ? 0 : 2, '0')
+                        break
+
+                    case 'b':
+                        result += monthNameShort
+                        break
+
+                    case 'B':
+                        result += monthNameLong
+                        break
+
+                    case 'm':
+                        result += (month + 1).toString().padStart(noLeading ? 0 : 2, '0')
+                        break
+
+                    case 'y':
+                        result += (year % 100).toString().padStart(noLeading ? 0 : 2, '0')
+                        break
+
+                    case 'Y':
+                        result += year.toString().padStart(noLeading ? 0 : 4, '0')
+                        break
+
+                    case 'H':
+                        result += hours.toString().padStart(noLeading ? 0 : 2, '0')
+                        break
+
+                    case 'I':
+                        result += hours12.toString().padStart(noLeading ? 0 : 2, '0')
+                        break
+
+                    case 'p':
+                        result += ampm
+                        break
+
+                    case 'M':
+                        result += minutes.toString().padStart(noLeading ? 0 : 2, '0')
+                        break
+
+                    case 'S':
+                        result += seconds.toString().padStart(noLeading ? 0 : 2, '0')
+                        break
+
+                    case 'f':
+                        result += milliseconds.toString().padStart(noLeading ? 0 : 3, '0')
+                        break
+
+                    case '%':
+                        result += '%'
+                        break
+                }
+
+                noLeading = false
+                percent = false
+            }
+        }
+        else if (c === '%') {
+            percent = true
+        }
+        else {
+            result += c
+        }
+    }
+
+    return result
+}
+
+/**
+ * Transform a time duration into a string, according to the given format. Recognized placeholders:
+ *  * `"%d"` - number of days
+ *  * `"%H"` - number of hours, from `"00"` to `"23"`
+ *  * `"%M"` - number of minutes, from `"00"` to `"59"`
+ *  * `"%S"` - number of seconds, from `"00"` to `"59"`
+ *  * `"%f"` - number of milliseconds, from `"000"` to `"999"`
+ *
+ * Use a `-` character in front of a format specifier to remove zero padding (e.g. "%-H"`).
+ *
+ * @alias qui.utils.date.formatDurationPercent
+ * @param {Number} duration duration, in milliseconds
+ * @param {String} format the format to be used
+ * @returns {String} the formatted duration
+ */
+export function formatDurationPercent(duration, format) {
+    let negative = false
+    if (duration < 0) {
+        duration = -duration
+        negative = true
+    }
+
+    let days = Math.floor(duration / MILLISECONDS_IN_DAY)
+    duration = duration % MILLISECONDS_IN_DAY
+
+    let hours = Math.floor(duration / MILLISECONDS_IN_HOUR)
+    duration = duration % MILLISECONDS_IN_HOUR
+
+    let minutes = Math.floor(duration / MILLISECONDS_IN_MINUTE)
+    duration = duration % MILLISECONDS_IN_MINUTE
+
+    let seconds = Math.floor(duration / 1000)
+    let milliseconds = duration % 1000
+
+    let result = ''
+    let percent = false
+    let noLeading = false
+    for (let i = 0; i < format.length; i++) {
+        let c = format.charAt(i)
+        if (percent) {
+            if (c === '-') {
+                noLeading = true
+            }
+            else {
+                switch (c) {
+                    case 'd':
+                        result += days.toString()
+                        break
+
+                    case 'H':
+                        result += hours.toString().padStart(noLeading ? 0 : 2, '0')
+                        break
+
+                    case 'M':
+                        result += minutes.toString().padStart(noLeading ? 0 : 2, '0')
+                        break
+
+                    case 'S':
+                        result += seconds.toString().padStart(noLeading ? 0 : 2, '0')
+                        break
+
+                    case 'f':
+                        result += milliseconds.toString().padStart(noLeading ? 0 : 3, '0')
+                        break
+
+                    case '%':
+                        result += '%'
+                        break
+                }
+
+                noLeading = false
+                percent = false
+            }
+        }
+        else if (c === '%') {
+            percent = true
+        }
+        else {
+            result += c
+        }
+    }
+
+    if (negative) {
+        result = `-${result}`
+    }
+
+    return result
+}
+
+/**
+ * Transform a given date object into its UTC equivalent.
+ * @alias qui.utils.date.toUTC
+ * @param {Date} date
+ * @returns {Date}
+ */
+export function toUTC(date) {
+    return new Date(
+        date.getUTCFullYear(),
+        date.getUTCMonth(),
+        date.getUTCDate(),
+        date.getUTCHours(),
+        date.getUTCMinutes(),
+        date.getUTCSeconds(),
+        date.getUTCMilliseconds()
+    )
+}

package/js/utils/files.js

@@ -0,0 +1,27 @@
+/**
+ * @namespace qui.utils.files
+ */
+
+
+/**
+ * Trigger a browser download of a client-side generated file.
+ * @alias qui.utils.files.clientSideDownload
+ * @param {String} filename
+ * @param {String} contentType
+ * @param {String|Uint8Array|ArrayBuffer} content
+ */
+export function clientSideDownload(filename, contentType, content) {
+    if (content instanceof ArrayBuffer) {
+        content = new Uint8Array(content)
+    }
+    if (content instanceof Uint8Array) {
+        content = new TextDecoder('utf-8').decode(content)
+    }
+
+    let blob = new window.Blob([content], {type: contentType})
+    let dataURL = URL.createObjectURL(blob)
+    let a = document.createElement('a')
+    a.href = dataURL
+    a.setAttribute('download', filename)
+    a.click()
+}

package/js/utils/gestures.js

@@ -0,0 +1,165 @@
+/**
+ * @namespace qui.utils.gestures
+ */
+
+import * as Window from '$qui/window.js'
+
+
+/**
+ * Drag Move Callback Function.
+ * @callback qui.utils.gestures.DragMoveCallback
+ * @param {Number} elemX the new element x coordinate, relative to page
+ * @param {Number} elemY the new element y coordinate, relative to page
+ * @param {Number} deltaX the x coordinate variation, relative to initial drag point
+ * @param {Number} deltaY the y coordinate variation, relative to initial drag point
+ * @param {Number} pageX the x coordinate, relative to page
+ * @param {Number} pageY the y coordinate, relative to page
+ */
+
+/**
+ * Drag Begin Callback Function.
+ * @callback qui.utils.gestures.DragBeginCallback
+ * @param {Number} elemX the initial element x coordinate, relative to page
+ * @param {Number} elemY the initial element y coordinate, relative to page
+ * @param {Number} pageX the x coordinate, relative to page
+ * @param {Number} pageY the y coordinate, relative to page
+ * @returns {Boolean} `false` to prevent dragging
+ */
+
+/**
+ * Drag End Callback Function.
+ * @callback qui.utils.gestures.DragEndCallback
+ * @param {Number} elemX the final element x coordinate, relative to page
+ * @param {Number} elemY the final element y coordinate, relative to page
+ * @param {Number} deltaX the final x coordinate variation, relative to initial drag point
+ * @param {Number} deltaY the final y coordinate variation, relative to initial drag point
+ * @param {Number} pageX the x coordinate inside, relative to page
+ * @param {Number} pageY the y coordinate inside, relative to page
+ */
+
+/**
+ * Setup an HTML element for dragging.
+ * @alias qui.utils.gestures.enableDragging
+ * @param {jQuery} element the dragged element
+ * @param {qui.utils.gestures.DragMoveCallback} onMove
+ * @param {qui.utils.gestures.DragBeginCallback} onBegin
+ * @param {qui.utils.gestures.DragEndCallback} onEnd
+ * @param {?String} [direction] indicates dragging direction: `"x"`, `"y"` or `null` for both; defaults to `null`
+ */
+export function enableDragging(element, onMove, onBegin, onEnd, direction) {
+    let beginPageX = 0, beginPageY = 0
+    let beginElemX = 0, beginElemY = 0
+
+    function pointerDown(e) {
+        let elemOffset = element.offset()
+        beginElemX = elemOffset.left
+        beginElemY = elemOffset.top
+
+        let scalingFactor = Window.getScalingFactor()
+        e.pageX /= scalingFactor
+        e.pageY /= scalingFactor
+
+        beginPageX = e.pageX
+        beginPageY = e.pageY
+
+        if (onBegin) {
+            if (onBegin(beginElemX, beginElemY, e.pageX, e.pageY) === false) {
+                return
+            }
+        }
+
+        Window.$body.on('pointermove', pointerMove)
+                    .on('pointerup pointercancel pointerleave', pointerUp)
+    }
+
+    function pointerUp(e) {
+        Window.$body.off('pointermove', pointerMove)
+                    .off('pointerup pointercancel pointerleave', pointerUp)
+
+        let scalingFactor = Window.getScalingFactor()
+        e.pageX /= scalingFactor
+        e.pageY /= scalingFactor
+
+        if (direction === 'x') { /* Constrain moving to horizontal axis */
+            e.pageY = beginPageY
+        }
+        if (direction === 'y') { /* Constrain moving to vertical axis */
+            e.pageX = beginPageX
+        }
+
+        let deltaX = e.pageX - beginPageX
+        let deltaY = e.pageY - beginPageY
+
+        let elemX = beginElemX + deltaX
+        let elemY = beginElemY + deltaY
+
+        beginPageX = beginPageY = 0
+        beginElemX = beginElemY = 0
+
+        if (onEnd) {
+            onEnd(elemX, elemY, deltaX, deltaY, e.pageX, e.pageY)
+        }
+    }
+
+    function pointerMove(e) {
+        let scalingFactor = Window.getScalingFactor()
+        e.pageX /= scalingFactor
+        e.pageY /= scalingFactor
+
+        if (direction === 'x') { /* Constrain moving to horizontal axis */
+            e.pageY = beginPageY
+        }
+        if (direction === 'y') { /* Constrain moving to vertical axis */
+            e.pageX = beginPageX
+        }
+
+        let deltaX = e.pageX - beginPageX
+        let deltaY = e.pageY - beginPageY
+
+        let elemX = beginElemX + deltaX
+        let elemY = beginElemY + deltaY
+
+        if (onMove) {
+            onMove(elemX, elemY, deltaX, deltaY, e.pageX, e.pageY)
+        }
+
+        e.preventDefault()
+    }
+
+    element.data('qui.utils.gestures.dragging', {
+        pointerDown: pointerDown,
+        pointerUp: pointerUp,
+        pointerMove: pointerMove
+    })
+
+    let touchAction = 'none'
+    if (direction === 'x') {
+        touchAction = 'pan-y'
+    }
+    else if (direction === 'y') {
+        touchAction = 'pan-x'
+    }
+
+    element.css('touch-action', touchAction)
+    element.attr('touch-action', touchAction) /* Required for pep.js (on iOS) */
+    element.on('pointerdown', pointerDown)
+}
+
+/**
+ * Disable previously configured dragging support on an HTML element.
+ * @alias qui.utils.gestures.disableDragging
+ * @param {jQuery} element the dragged element
+ */
+export function disableDragging(element) {
+    let draggingData = element.data('qui.utils.gestures.dragging')
+    if (!draggingData) {
+        return
+    }
+
+    Window.$body.off('pointermove', draggingData.pointerMove)
+                .off('pointerup pointercancel pointerleave', draggingData.pointerUp)
+
+    element.css('touch-action', '')
+    element.attr('touch-action', '') /* Required for pep.js (on iOS) */
+    element.off('pointerdown', draggingData.pointerDown)
+}

package/js/utils/html.js

@@ -0,0 +1,76 @@
+/**
+ * @namespace qui.utils.html
+ */
+
+import $ from '$qui/lib/jquery.module.js'
+
+
+const HTML_ENTITIES = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+    '/': '&#x2F;',
+    '`': '&#x60;',
+    '=': '&#x3D;'
+}
+
+const HTML_CHARS_TO_ESCAPE_RE = new RegExp('[&<>"\'`=/]', 'g')
+
+
+/**
+ * Remove any HTML tags from a string, keeping only plain text.
+ * @alias qui.utils.html.plainText
+ * @param {String} s
+ * @returns {String}
+ */
+export function plainText(s) {
+    let span = document.createElement('span')
+    span.innerHTML = s
+
+    return span.innerText
+}
+
+/**
+ * Escape HTML content, using HTML entities.
+ * @alias qui.utils.html.escape
+ * @param {String} s
+ * @returns {String}
+ */
+export function escape(s) {
+    return s.replace(HTML_CHARS_TO_ESCAPE_RE, function (s) {
+        return HTML_ENTITIES[s]
+    })
+}
+
+/**
+ * Replace percent-formatted placeholders in a string with given values. Compared to
+ * {@link qui.utils.string.formatPercent}, this function works with `jQuery` elements instead of primitive values.
+ * @alias qui.utils.html.formatPercent
+ * @param {String} text the text template with placeholders given as `"%(name)s"`
+ * @param {String} wrapElement the HTML element type to use to wrap the result (e.g. `"span"`)
+ * @param {Object<String,jQuery>} values the values used to replace the placeholders
+ * @returns {jQuery}
+ */
+export function formatPercent(text, wrapElement, values) {
+    let result = $(`<${wrapElement}></${wrapElement}>`)
+
+    let re = /%\(([a-zA-Z0-9_-]+)\)s/
+    let match
+    while ((match = re.exec(text))) {
+        let firstPart = text.substring(0, match.index)
+        text = text.substring(match.index + match[0].length)
+        let name = match[1]
+        let value = values[name]
+
+        result.append(firstPart)
+        result.append(value || match[0])
+    }
+
+    if (text.length) {
+        result.append(text)
+    }
+
+    return result
+}

package/js/utils/misc.js

@@ -0,0 +1,81 @@
+/**
+ * @namespace qui.utils.misc
+ */
+
+import Config           from '$qui/config.js'
+import * as ObjectUtils from '$qui/utils/object.js'
+
+import URL from './url.js'
+
+
+/**
+ * Run a function as soon as possible, in the next main loop iteration.
+ * @alias qui.utils.misc.asap
+ * @param {Function} func function to run
+ * @returns {Number} a timeout handle
+ */
+export function asap(func) {
+    return setTimeout(function () {
+        func()
+    }, 20)
+}
+
+/**
+ * Ensure that a URL has a query argument named `h`, representing the build hash.
+ * @alias qui.utils.misc.appendBuildHash
+ * @param {String} strURL
+ * @returns {String}
+ */
+export function appendBuildHash(strURL) {
+    let url = URL.parse(strURL)
+    if (!Config.buildHash) {
+        return url.toString()
+    }
+
+    url = url.alter({query: ObjectUtils.combine(url.query, {h: Config.buildHash})})
+    return url.toString()
+}
+
+/**
+ * Tell if argument is a function and not a class.
+ * @param {*} f
+ * @returns {Boolean}
+ */
+export function isFunction(f) {
+    if (typeof f !== 'function') {
+        return false
+    }
+
+    let s
+    try {
+        s = Function.prototype.toString.call(f)
+    }
+    catch {
+        /* Definitely not a function */
+        return false
+    }
+
+    return !/^class\s/.test(s)
+}
+
+/**
+ * Tell if argument is a class.
+ * @param {*} c
+ * @returns {Boolean}
+ */
+export function isClass(c) {
+    if (typeof c !== 'function') {
+        return false
+    }
+
+    let s
+    try {
+        s = Function.prototype.toString.call(c)
+    }
+    catch {
+        /* Definitely not a class */
+        return false
+    }
+
+    return /^class\s/.test(s)
+}