@qtoggle/qui 0.0.0

package/js/icons/multi-state-sprites-icon.js

@@ -0,0 +1,362 @@
+
+import $ from '$qui/lib/jquery.module.js'
+
+import * as Theme       from '$qui/theme.js'
+import * as ArrayUtils  from '$qui/utils/array.js'
+import * as Colors      from '$qui/utils/colors.js'
+import * as CSS         from '$qui/utils/css.js'
+import {asap}           from '$qui/utils/misc.js'
+import * as ObjectUtils from '$qui/utils/object.js'
+import * as Window      from '$qui/window.js'
+
+import Icon from './icon.js'
+
+
+/**
+ * @typedef {Object} qui.icons.MultiStateSpritesIcon.StateDetails
+ * @property {Number} offsetX the X offset of the icon in the sprites image
+ * @property {Number} offsetY the Y offset of the icon in the sprites image
+ * @property {String} filter a CSS filter to apply to the icon
+ */
+
+/**
+ * An icon with different settings for various states.
+ *
+ * Defined icon states are `normal`, `active`, `focused` and `selected`.
+ *
+ * @alias qui.icons.MultiStateSpritesIcon
+ * @extends qui.icons.Icon
+ */
+class MultiStateSpritesIcon extends Icon {
+
+    static KNOWN_STATES = ['normal', 'active', 'focused', 'selected']
+
+
+    /**
+     * @constructs
+     * @param {String} url the URL of the image resource
+     * @param {Number} bgWidth the total width of the image resource
+     * @param {Number} bgHeight the total height of the image resource
+     * @param {Number} [size] the size of the icon; defaults to `1`
+     * @param {String} [unit] the CSS unit used for all dimension attributes; defaults to `"rem"`
+     * @param {Object<String,qui.icons.MultiStateSpritesIcon.StateDetails>} [states] a mapping with icon states
+     * @param {Number} [scale] icon scaling factor; defaults to `1`
+     * @param {String} [decoration] icon decoration
+     * @param {...*} args parent class parameters
+     */
+    constructor({
+        url,
+        bgWidth,
+        bgHeight,
+        size = 1,
+        unit = 'rem',
+        states = null,
+        scale = 1,
+        decoration = null,
+        ...args
+    }) {
+        super({...args})
+
+        this._url = url
+        this._bgWidth = bgWidth
+        this._bgHeight = bgHeight
+        this._size = size
+        this._unit = unit
+
+        this._states = states
+        this._scale = scale
+        this._decoration = decoration
+    }
+
+    /**
+     * Tell if the icon has a given state.
+     * @param {String} state
+     * @returns {Boolean}
+     */
+    hasState(state) {
+        return state in this._states
+    }
+
+    toAttributes() {
+        return Object.assign(super.toAttributes(), {
+            url: this._url,
+            bgWidth: this._bgWidth,
+            bgHeight: this._bgHeight,
+            size: this._size,
+            unit: this._unit,
+            states: this._states,
+            scale: this._scale,
+            decoration: this._decoration
+        })
+    }
+
+    _prepareParams() {
+        let m, u, v
+        let size = this._size
+        let bgWidth = String(this._bgWidth)
+        let bgHeight = String(this._bgHeight)
+
+        /* Perform required scaling transformations */
+        if (this._scale !== 1) {
+            size *= this._scale
+
+            m = bgWidth.match(new RegExp('[^\\d]'))
+            if (m) {
+                u = bgWidth.substring(m.index)
+                v = parseInt(bgWidth)
+            }
+            else {
+                u = this._unit
+                v = Number(bgWidth) || 0
+            }
+            bgWidth = v * this._scale + u
+
+            m = bgHeight.match(new RegExp('[^\\d]'))
+            if (m) {
+                u = bgHeight.substring(m.index)
+                v = parseInt(bgHeight)
+            }
+            else {
+                u = this._unit
+                v = Number(bgHeight) || 0
+            }
+
+            bgHeight = v * this._scale + u
+        }
+
+        return {
+            size: size,
+            bgWidth: bgWidth,
+            bgHeight: bgHeight
+        }
+    }
+
+    renderTo(element) {
+        let params = this._prepareParams()
+
+        let size = params.size
+        let bgWidth = params.bgWidth
+        let bgHeight = params.bgHeight
+
+        /* Find and remove existing icon state elements */
+        let existingStateElements = element.children().filter(function () {
+            return this.className.split(' ').some(function (c) {
+                return c.match(new RegExp('^qui-icon-[\\w\\-]+$')) && c !== 'qui-icon-decoration'
+            })
+        })
+
+        let addedToDOM = element.parents('body').length
+        if (addedToDOM) {
+            asap(function () {
+                existingStateElements.addClass('qui-icon-hidden')
+            })
+            Theme.afterTransition(function () {
+                existingStateElements.remove()
+            }, existingStateElements)
+        }
+        else {
+            existingStateElements.remove()
+            existingStateElements = []
+        }
+
+        element.addClass('qui-icon')
+
+        /* Add new icon state elements */
+        let newElements = $()
+        ObjectUtils.forEach(this._states, function (state, details) {
+
+            let offsetX = details.offsetX
+            let offsetY = details.offsetY
+
+            /* Incomplete states don't get an element */
+            if (offsetX == null || offsetY == null) {
+                return
+            }
+
+            let stateDiv = $('<div></div>', {class: `qui-icon-${state}`})
+            /* If no existing elements, display the new element directly, w/o any effect; otherwise start hidden and
+             * do a transition to visible */
+            if (existingStateElements.length) {
+                stateDiv.addClass('qui-icon-hidden')
+            }
+
+            let css = {
+                'background-image': `url("${this._url}")`,
+                'background-position': `${(-offsetX * size)}${this._unit} ${(-offsetY * size)}${this._unit}`
+            }
+            if (bgWidth && bgHeight) {
+                css['background-size'] = `${bgWidth} ${bgHeight}`
+            }
+
+            if (details.filter) {
+                css['filter'] = details.filter
+            }
+
+            stateDiv.css(css)
+
+            element.append(stateDiv)
+            newElements = newElements.add(stateDiv)
+
+        }, this)
+
+        if (existingStateElements.length) {
+            asap(function () {
+                newElements.removeClass('qui-icon-hidden')
+            })
+        }
+
+        let topState = 'normal'
+        this.constructor.KNOWN_STATES.forEach(function (state) {
+            if (state in this._states) {
+                topState = state
+            }
+        }, this)
+
+        element.removeClass(this.constructor.KNOWN_STATES.map(s => `top-${s}`).join(' '))
+        element.addClass(`top-${topState}`)
+
+        /* Decoration */
+
+        let decorationDiv = element.children('div.qui-icon-decoration')
+        if (!decorationDiv.length) {
+            decorationDiv = null
+        }
+
+        if (!decorationDiv && this._decoration) {
+            decorationDiv = $('<div></div>', {class: 'qui-icon-decoration'})
+            element.prepend(decorationDiv)
+        }
+        else if (decorationDiv && !this._decoration) {
+            decorationDiv.remove()
+            decorationDiv = null
+        }
+
+        if (decorationDiv) {
+            let css = {
+                background: this._decoration
+            }
+
+            let bgColor = this._findBgColor(element)
+            let bgRGB = Colors.str2rgba(bgColor)
+            let decoRGB = Colors.str2rgba(this._decoration)
+            if (Colors.contrast(bgRGB, decoRGB) > 1.5) {
+                css['border-color'] = bgColor
+            }
+            else {
+                this._findIconColor(element).then(function (color) {
+                    css['border-color'] = color
+                })
+            }
+
+            decorationDiv.css(css)
+        }
+    }
+
+    _findBgColor(elem) {
+        /* Find the background color behind the icon */
+
+        let e = elem
+        let bgColor = null
+        while (e.length && e[0].tagName && (!bgColor || bgColor === 'rgba(0, 0, 0, 0)' ||
+                                             bgColor === 'transparent')) {
+
+            bgColor = e.css('background-color')
+            e = e.parent()
+        }
+
+        if (!e.length || !e[0].tagName) {
+            /* Icon element not added yet to the DOM, or no element has a background color */
+            bgColor = Theme.getVar('background-color')
+        }
+
+        return bgColor
+    }
+
+    _findIconColor(elem) {
+        /* Find the dominant color of the icon, using a canvas element */
+
+        return new Promise(function (resolve) {
+            let params = this._prepareParams()
+
+            let size = params.size
+            let pxFactor = 1
+            if (this._unit === 'em') {
+                if (Window.$body.has(elem).length) {
+                    pxFactor = CSS.em2px(1, elem)
+                }
+                else {
+                    pxFactor = CSS.em2px(1)
+                }
+            }
+            else if (this._unit === 'rem') {
+                pxFactor = CSS.em2px(1)
+            }
+
+            let normalState = this._states['normal']
+            let offsetX = 0
+            let offsetY = 0
+            if (normalState) {
+                offsetX = normalState.offsetX || 0
+                offsetY = normalState.offsetY || 0
+            }
+
+            offsetX *= size
+            offsetY *= size
+
+            let canvas = document.createElement('canvas')
+            let context = canvas.getContext('2d')
+
+            let width = size * pxFactor
+
+            canvas.width = width
+            canvas.height = width /* Yes, width */
+
+            context.scale(this._scale, this._scale)
+            context.translate(-offsetX * pxFactor, -offsetY * pxFactor)
+
+            let img = new window.Image()
+            img.onload = function () {
+
+                context.drawImage(img, 0, 0)
+                let snapshot = context.getImageData(0, 0, width, width)
+
+                function getColor(x, y) {
+                    let p = (y * width + x)
+                    let r = snapshot.data[4 * p]
+                    let g = snapshot.data[4 * p + 1]
+                    let b = snapshot.data[4 * p + 2]
+
+                    return Colors.rgba2str([r, g, b])
+                }
+
+                let bgColor = getColor(0, 0)
+                let colorDict = {}
+
+                for (let y = 0; y < width; y++) {
+                    for (let x = 0; x < width; x++) {
+                        let color = getColor(x, y)
+                        if (color in colorDict) {
+                            colorDict[color] += 1
+                        }
+                        else {
+                            colorDict[color] = 0
+                        }
+                    }
+                }
+
+                let colorCounters = ArrayUtils.sortKey(Object.entries(colorDict), c => c[1], /* desc = */ true)
+                while (colorCounters[0][0] === bgColor && colorCounters.length > 1) {
+                    colorCounters.shift()
+                }
+
+                resolve(colorCounters[0][0])
+            }
+
+            img.src = this._url
+        }.bind(this))
+    }
+
+}
+
+
+export default MultiStateSpritesIcon

package/js/icons/stock-icon.js

@@ -0,0 +1,219 @@
+
+import {AssertionError} from '$qui/base/errors.js'
+import * as ObjectUtils from '$qui/utils/object.js'
+
+import * as DefaultStock     from './default-stock.js'
+import Icon                  from './icon.js'
+import MultiStateSpritesIcon from './multi-state-sprites-icon.js'
+import * as Stocks           from './stocks.js'
+
+
+/**
+ * An icon defined by stock attributes.
+ * @alias qui.icons.StockIcon
+ * @extends qui.icons.Icon
+ */
+class StockIcon extends Icon {
+
+    /**
+     * @constructs
+     * @param {String} name the icon name (in normal state)
+     * @param {String} [stockName] the name of the stock (defaults to `qui`)
+     * @param {String} [variant] the icon variant (in normal state)
+     * @param {String} [activeName] the icon name in active state
+     * @param {String} [activeVariant] the icon variant in active state
+     * @param {String} [focusedName] the icon name in focused state
+     * @param {String} [focusedVariant] the icon variant in focused state
+     * @param {String} [selectedName] the icon name in selected state
+     * @param {String} [selectedVariant] the icon variant in selected state
+     * @param {Number} [scale] icon scaling factor (defaults to `1`)
+     * @param {String} [decoration] icon decoration
+     * @param {...*} args parent class parameters
+     */
+    constructor({
+        name,
+        stockName = DefaultStock.NAME,
+        variant = null,
+        activeName = null,
+        activeVariant = null,
+        focusedName = null,
+        focusedVariant = null,
+        selectedName = null,
+        selectedVariant = null,
+        scale = 1,
+        decoration = null,
+        ...args
+    }) {
+        super({...args})
+
+        this._name = name
+        this._stockName = stockName
+        this._variant = variant
+        this._activeName = activeName
+        this._activeVariant = activeVariant
+        this._focusedName = focusedName
+        this._focusedVariant = focusedVariant
+        this._selectedName = selectedName
+        this._selectedVariant = selectedVariant
+        this._scale = scale
+        this._decoration = decoration
+
+        /* A variant is specified but no corresponding name */
+        if (this._activeVariant && !this._activeName) {
+            this._activeName = this._name
+        }
+        if (this._focusedVariant && !this._focusedName) {
+            this._focusedName = this._name
+        }
+        if (this._selectedVariant && !this._selectedName) {
+            this._selectedName = this._name
+        }
+
+        /* A name is specified but no corresponding variant */
+        if (this._activeName && !this._activeVariant) {
+            this._activeVariant = this._variant
+        }
+        if (this._focusedName && !this._focusedVariant) {
+            this._focusedVariant = this._variant
+        }
+        if (this._selectedName && !this._selectedVariant) {
+            this._selectedVariant = this._variant
+        }
+    }
+
+    toAttributes() {
+        return Object.assign(super.toAttributes(), {
+            name: this._name,
+            stockName: this._stockName,
+            variant: this._variant,
+            activeName: this._activeName,
+            activeVariant: this._activeVariant,
+            focusedName: this._focusedName,
+            focusedVariant: this._focusedVariant,
+            selectedName: this._selectedName,
+            selectedVariant: this._selectedVariant,
+            scale: this._scale,
+            decoration: this._decoration
+        })
+    }
+
+    /**
+     * Return a dictionary with attributes suitable to build a {@link qui.icons.MultiStateSpritesIcon}.
+     * @returns {?qui.icons.MultiStateSpritesIcon}
+     */
+    toMultiStateSpritesIcon() {
+        let stock = Stocks.get(this._stockName)
+        if (!stock) {
+            return null
+        }
+
+        let attributes = Object.assign(super.toAttributes(), {
+            url: stock.src,
+            bgWidth: stock.width,
+            bgHeight: stock.height,
+            size: stock.size,
+            unit: stock.unit
+        })
+
+        let states = {}
+        let filterVariant
+
+        if (this._name) {
+            filterVariant = stock.parseVariant(this._variant)
+            states['normal'] = {
+                offsetX: stock.names[this._name],
+                offsetY: stock.variants[filterVariant.variant],
+                filter: filterVariant.filter
+            }
+        }
+
+        if (this._activeName) {
+            filterVariant = stock.parseVariant(this._activeVariant)
+            states['active'] = {
+                offsetX: stock.names[this._activeName],
+                offsetY: stock.variants[filterVariant.variant],
+                filter: filterVariant.filter
+            }
+        }
+
+        if (this._focusedName) {
+            filterVariant = stock.parseVariant(this._focusedVariant)
+            states['focused'] = {
+                offsetX: stock.names[this._focusedName],
+                offsetY: stock.variants[filterVariant.variant],
+                filter: filterVariant.filter
+            }
+        }
+
+        if (this._selectedName) {
+            filterVariant = stock.parseVariant(this._selectedVariant)
+            states['selected'] = {
+                offsetX: stock.names[this._selectedName],
+                offsetY: stock.variants[filterVariant.variant],
+                filter: filterVariant.filter
+            }
+        }
+
+        attributes.states = states
+
+        if (this._scale) {
+            attributes.scale = this._scale
+        }
+        if (this._decoration) {
+            attributes.decoration = this._decoration
+        }
+
+        return new MultiStateSpritesIcon(attributes)
+    }
+
+    /**
+     * Return an updated version of the icon by altering some of the attributes.
+     * @param {Object} attributes the attributes to alter
+     * @returns qui.icons.StockIcon
+     */
+    alter(attributes) {
+        return new this.constructor(Object.assign(this.toAttributes(), attributes))
+    }
+
+    /**
+     * Return an updated version of the icon by altering some of the attributes only if they are unset (`null`).
+     *
+     * This method allows creating an icon by providing default attribute values.
+     *
+     * @param {Object} attributes the attributes to alter
+     * @returns qui.icons.StockIcon
+     */
+    alterDefault(attributes) {
+        /* Keep only attributes whose value is currently null */
+        attributes = ObjectUtils.filter(attributes, (key) => (this[`_${key}`] == null))
+
+        return this.alter(attributes)
+    }
+
+    /**
+     * Alter a stock icon that has already been applied to an element, in place.
+     * @param {jQuery} element
+     * @param {Object} attributes the attributes to alter
+     */
+    static alterElement(element, attributes) {
+        let icon = Icon.getFromElement(element)
+        if (!icon) {
+            throw new AssertionError('Attempt to alter element without icon')
+        }
+
+        if (!(icon instanceof StockIcon)) {
+            throw new AssertionError('Attempt to alter an icon that is not StockIcon')
+        }
+
+        icon = icon.alter(attributes)
+        icon.applyTo(element)
+    }
+
+    renderTo(element) {
+        this.toMultiStateSpritesIcon().applyTo(element)
+    }
+
+}
+
+
+export default StockIcon

package/js/icons/stock.js

@@ -0,0 +1,98 @@
+
+import {appendBuildHash} from '$qui/utils/misc.js'
+
+import * as DefaultStock from './default-stock.js'
+
+
+/**
+ * An icon stock.
+ * @alias qui.icons.Stock
+ */
+class Stock {
+
+    /**
+     * @constructs
+     * @param {String} src image source (normally a URL)
+     * @param {String} unit unit of measurement for icon size (e.g. `"em"`, `"rem"`, `"px"`)
+     * @param {Number} size icon size with respect to the `unit` (the icon is assumed to be a square)
+     * @param {Number} width the number of icons in a row present in the source
+     * @param {Number} height the number of icon rows present in the source
+     * @param {Object<String,Number>} names a mapping associating each icon name to its horizontal offset
+     * @param {?Object<String,Number>} [variants] a mapping associating each icon variant to its vertical offset; the
+     * variants of the default stock ({@link qui.icons.defaultstock} are used if not supplied
+     * @param {Object<String,String>} [variantAliases] an optional mapping of aliases to icon variants; the variant
+     * aliases of the default stock ({@link qui.icons.defaultstock} are used if not supplied
+     *
+     */
+    constructor({src, unit, size, width, height, names, variants = null, variantAliases = null}) {
+        src = appendBuildHash(src)
+
+        this.src = src
+        this.unit = unit
+        this.size = size
+        this.width = width
+        this.height = height
+        this.names = names
+        this.variants = variants
+        this.variantAliases = variantAliases
+    }
+
+    /**
+     * Make the stock ready to be used by ensuring all its properties are prepared.
+     */
+    prepare() {
+        /* Copy variants from default stock */
+        let defaultStock = DefaultStock.get()
+
+        if (!this.variants) {
+            this.variants = defaultStock.variants
+        }
+        if (!this.variantAliases) {
+            this.variantAliases = defaultStock.variantAliases
+        }
+    }
+
+    /**
+     * Transform a variant into its corresponding filter and final variant.
+     * @param {String} variant
+     * @returns {{filter: String, variant: String}}
+     */
+    parseVariant(variant) {
+        /* First resolve any alias */
+        let c = 0
+        while (variant in this.variantAliases) {
+            variant = this.variantAliases[variant]
+
+            /* Prevent loops; allow at most 10 levels of aliasing */
+            c++
+            if (c > 10) {
+                break
+            }
+        }
+
+        if (!variant) {
+            return {
+                variant: null,
+                filter: null
+            }
+        }
+
+        let parts = variant.split(' ')
+        if (parts.length > 1) {
+            return {
+                variant: parts[0],
+                filter: parts.slice(1).join(' ')
+            }
+        }
+        else {
+            return {
+                variant: variant,
+                filter: null
+            }
+        }
+    }
+
+}
+
+
+export default Stock