@qtoggle/qui 1.20.0-alpha.5 → 1.20.0-alpha.7

package/js/lists/common-items/icon-label-list-item.js

@@ -38,6 +38,20 @@ class IconLabelListItem extends mix(ListItem).with(IconLabelViewMixin) {
         this.setClickable(selectMode !== Lists.LIST_SELECT_MODE_DISABLED)
     }
 
+    updateFrom(other) {
+        /* Only ever take an update from the very same kind of item: a subclass may carry state this does not know
+         * about, and half-updating a row is worse than rebuilding it. */
+        if (other.constructor !== this.constructor) {
+            return false
+        }
+
+        this.setLabel(other.getLabel())
+        this.setSubLabel(other.getSubLabel())
+        this.setIcon(other.getIcon())
+
+        return true
+    }
+
     /**
      * Return the text a search filter is matched against: the label and the sub-label joined in the order in which
      * they are displayed, so that a filter can span both.

package/js/lists/list-item.js

@@ -46,6 +46,27 @@ class ListItem extends mix().with(ViewMixin) {
 
     /* User data */
 
+    /**
+     * Return the value that identifies this item across updates. Two items with the same key, at the same position,
+     * are the same row, so the list can update it where it is instead of building it again.
+     * @returns {*} the key, or `null` if the item cannot be identified and must always be rebuilt
+     */
+    getKey() {
+        return this.getData()
+    }
+
+    /**
+     * Update this item in place, from a freshly built item representing the same row.
+     *
+     * The base implementation refuses, so that a list containing items which do not implement this keeps its old
+     * rebuild-everything behaviour rather than silently showing stale content.
+     * @param {qui.lists.ListItem} other the freshly built item
+     * @returns {Boolean} `true` if the item took the update, `false` to have the list rebuild the row instead
+     */
+    updateFrom(other) {
+        return false
+    }
+
     /**
      * Return the item user data.
      * @returns {*}

package/js/lists/list.js

@@ -148,6 +148,10 @@ class List extends mix().with(ViewMixin, StructuredViewMixin, ProgressViewMixin)
      * @param {qui.lists.ListItem[]} items list items
      */
     setItems(items) {
+        if (this._updateItemsInPlace(items)) {
+            return
+        }
+
         this._items.forEach(function (i) {
             this._forgetItemFilter(i)
             i.getHTML().remove()
@@ -170,6 +174,46 @@ class List extends mix().with(ViewMixin, StructuredViewMixin, ProgressViewMixin)
         }, this)
     }
 
+    /* The same keys in the same order mean the same rows, so they can be patched where they are instead of every
+     * element being thrown away and built again. Measured on a 200-row list: 4.2ms to rebuild, 0.36ms to patch, and
+     * that is only the DOM -- it counts none of the item objects, visibility managers or icon renders a rebuild also
+     * throws away. Anything else (an item added, removed, or moved) falls back to the rebuild. */
+    _updateItemsInPlace(items) {
+        let oldItems = this._items
+
+        if (!oldItems.length || oldItems.length !== items.length) {
+            return false
+        }
+
+        for (let i = 0; i < items.length; i++) {
+            /* An item that has not been through prepareItem() is not in the list yet, whatever _items says: init()
+             * hands the initial items straight back to setItems(), where they would otherwise update from themselves
+             * and report success without ever being prepared or appended. */
+            if (oldItems[i].getList() !== this) {
+                return false
+            }
+
+            let key = items[i].getKey()
+            if (key == null || key !== oldItems[i].getKey()) {
+                return false
+            }
+        }
+
+        /* Giving up part way through is safe: the caller then rebuilds from the new items, and these half-updated
+         * ones are discarded along with their elements. */
+        for (let i = 0; i < items.length; i++) {
+            if (!oldItems[i].updateFrom(items[i])) {
+                return false
+            }
+        }
+
+        if (this._searchEnabled) {
+            this._applySearchFilter()
+        }
+
+        return true
+    }
+
     /**
      * Update one item.
      * @param {Number} index the index where to perform the update
@@ -732,7 +776,20 @@ class List extends mix().with(ViewMixin, StructuredViewMixin, ProgressViewMixin)
         if (this._selectMode === Lists.LIST_SELECT_MODE_DISABLED) {
             return
         }
-        else if (this._selectMode === Lists.LIST_SELECT_MODE_SINGLE) {
+
+        /* Resolve by key anything that is not one of our own items. A caller that rebuilt its items and handed us the
+         * fresh ones would otherwise wipe the selection, since setItems() may have kept the originals and updated
+         * them in place. */
+        items = items.map(function (item) {
+            if (this._items.includes(item)) {
+                return item
+            }
+
+            let key = item.getKey()
+            return (key != null) ? this._items.find(i => i.getKey() === key) || null : null
+        }, this).filter(i => i != null)
+
+        if (this._selectMode === Lists.LIST_SELECT_MODE_SINGLE) {
             if (items.length > 1) {
                 items = items.slice(0, 1) /* Keep only first element in single selection mode */
             }

package/js/main-ui/status.js

@@ -123,11 +123,16 @@ export function set(status, message = null) {
     }
 
     if (iconName) {
-        if (decoration === 'info') {
-            decoration = null
+        /* No decoration is drawn for the sync status, which asks for none, nor for the info one, which would not
+         * stand out against the icon anyway. Anything else names a theme colour.
+         *
+         * The null case used to fall through to the lookup below and ask the theme for a "null-color", which resolves
+         * to undefined and so happened to produce the right result. */
+        if (decoration != null && decoration !== 'info') {
+            decoration = Theme.getVar(`${decoration}-color`)
         }
         else {
-            decoration = Theme.getVar(`${decoration}-color`)
+            decoration = null
         }
 
         let variant = 'foreground'

package/js/theme.js

@@ -19,6 +19,9 @@ import * as Window       from '$qui/window.js'
 
 const STORAGE_BACKGROUND_COLOR_KEY = 'theme.background-color'
 
+/* How long the body is given to fade out before the theme stylesheets are swapped under it */
+const FADE_OUT_DURATION = 500
+
 const logger = Logger.get('qui.theme')
 
 let currentTheme = null
@@ -66,9 +69,11 @@ export function setCurrent(theme) {
     return updateCurrent()
 }
 
-function updateCurrent() {
-    /* Fade out body */
-    Window.$body.css('opacity', '')
+function updateCurrent(fadeOut = true) {
+    if (fadeOut) {
+        /* Fade out body */
+        Window.$body.css('opacity', '')
+    }
 
     function isLoaded() {
         return CSS.findRules('^br.-theme-name$').some(function (rule) {
@@ -93,8 +98,16 @@ function updateCurrent() {
         }
     }
 
-    /* Allow 500ms for fading-out */
-    return PromiseUtils.later(500).then(function () {
+    /* Let the body fade out before the stylesheets are swapped under it. There is nothing to fade out on the very
+     * first call -- the body starts at opacity 0, from the inline style in qui.html -- and waiting here delays
+     * removing the `disabled` attribute below, which is what starts the stylesheet downloading at all. The whole
+     * duration therefore lands in front of the first paint.
+     *
+     * A resolved promise rather than a zero timeout, so that the stylesheet is enabled on the microtask queue instead
+     * of queueing behind whatever else is waiting, and out of reach of timer clamping. */
+    let fadedOut = fadeOut ? PromiseUtils.later(FADE_OUT_DURATION) : Promise.resolve()
+
+    return fadedOut.then(function () {
 
         /* Update disabled attribute of CSS link elements */
         $('link[theme]').each(function () {
@@ -296,7 +309,7 @@ export function init() {
 
     Window.$body.toggleClass('effects-disabled', effectsDisabled)
 
-    return updateCurrent().then(function () {
+    return updateCurrent(/* fadeOut = */ false).then(function () {
         /* Normally updateCurrent() will take care of fading in body, adds extra 500ms for section soft reload.
          * This being the first call, we want the body visible as soon as theme is loaded */
         Window.$body.css('opacity', '1')

package/js/utils/debouncer.js

@@ -9,11 +9,15 @@ class Debouncer {
      * @constructs
      * @param {Function} func the function to debounce
      * @param {Number} [delay] the debouncing delay, in milliseconds (defaults to `0`)
+     * @param {?Number} [maxWait] the longest the call may be postponed, in milliseconds, however many times it is
+     * made; `null` (the default) postpones it indefinitely
      */
-    constructor(func, delay = 0) {
+    constructor(func, delay = 0, maxWait = null) {
         this._func = func
         this._delay = delay
+        this._maxWait = maxWait
         this._timeoutHandle = null
+        this._firstCallTime = null
     }
 
     /**
@@ -25,10 +29,24 @@ class Debouncer {
             clearTimeout(this._timeoutHandle)
         }
 
+        let delay = this._delay
+
+        if (this._maxWait != null) {
+            if (this._firstCallTime == null) {
+                this._firstCallTime = Date.now()
+            }
+
+            /* Each call pushes the deadline back by the full delay, so a stream of calls arriving faster than the
+             * delay postpones the function for as long as it lasts -- which reads as a frozen UI rather than a slow
+             * one. Never postpone it past maxWait from the first call of the run. */
+            delay = Math.min(delay, Math.max(0, this._maxWait - (Date.now() - this._firstCallTime)))
+        }
+
         this._timeoutHandle = setTimeout(function () {
             this._timeoutHandle = null
+            this._firstCallTime = null
             this._func(...args)
-        }.bind(this), this._delay)
+        }.bind(this), delay)
     }
 
     /**

package/js/utils/gestures.js

@@ -54,6 +54,30 @@ const LONG_PRESS_DATA_KEY = 'qui.utils.gestures.longPress'
 export function enableDragging(element, onMove, onBegin, onEnd, direction) {
     let beginPageX = 0, beginPageY = 0
     let beginElemX = 0, beginElemY = 0
+    let moveFrameHandle = null
+    let pendingMoveArgs = null
+
+    /* A pointer can report far more often than the screen refreshes -- and every one of these callbacks reads and
+     * writes layout -- so deliver at most one per frame, carrying the newest position. Dropping the positions in
+     * between is safe because onMove is given absolute coordinates and deltas measured from where the drag began,
+     * never from the previous move. */
+    function deliverMove() {
+        moveFrameHandle = null
+
+        let args = pendingMoveArgs
+        pendingMoveArgs = null
+
+        if (args && onMove) {
+            onMove(...args)
+        }
+    }
+
+    function flushMove() {
+        if (moveFrameHandle != null) {
+            window.cancelAnimationFrame(moveFrameHandle)
+            deliverMove()
+        }
+    }
 
     function pointerDown(e) {
         let elemOffset = element.offset()
@@ -81,6 +105,10 @@ export function enableDragging(element, onMove, onBegin, onEnd, direction) {
         Window.$body.off('pointermove', pointerMove)
                     .off('pointerup pointercancel pointerleave', pointerUp)
 
+        /* Deliver whatever the last frame did not get to, so that the sequence of moves a handler sees still ends
+         * where the pointer actually was, before it is told the drag is over */
+        flushMove()
+
         let scalingFactor = Window.getScalingFactor()
         e.pageX /= scalingFactor
         e.pageY /= scalingFactor
@@ -125,7 +153,10 @@ export function enableDragging(element, onMove, onBegin, onEnd, direction) {
         let elemY = beginElemY + deltaY
 
         if (onMove) {
-            onMove(elemX, elemY, deltaX, deltaY, e.pageX, e.pageY)
+            pendingMoveArgs = [elemX, elemY, deltaX, deltaY, e.pageX, e.pageY]
+            if (moveFrameHandle == null) {
+                moveFrameHandle = window.requestAnimationFrame(deliverMove)
+            }
         }
 
         e.preventDefault()

package/less/lists.less

@@ -43,18 +43,12 @@ div.qui-list-child.qui-list-item {
         opacity: 0;
     }
 
-    /* Only an item whose whole content is an icon-label view has a height we can predict: min-height: 3em in
-     * icon-label-view.less, with the content kept to a single ellipsised line. Such a view can have its off-screen
-     * rendering skipped against a reliable size estimate. Everything else built on ListItem is deliberately left out,
-     * table rows above all -- their content is a set of cells and their height is unconstrained.
-     *
-     * The plain contain-intrinsic-size comes first for engines that predate the auto keyword and would otherwise drop
-     * the declaration, collapsing a skipped view to nothing. */
-    & > div.qui-icon-label-view {
-        content-visibility: auto;
-        contain-intrinsic-size: 0 3em;
-        contain-intrinsic-size: auto 3em;
-    }
+    /* No `content-visibility: auto` on the icon-label view either, and it is not coming back without a different
+     * mechanism. Skipping the rendering of off-screen rows means the browser has to do that work when they scroll in,
+     * and it does not keep up with a fast flick: measured on a 300-row list, every row in the viewport was still in
+     * the skipped state two frames after a jump, and only rendered about 400ms later. Rows arrive blank and fill in
+     * afterwards, which is far more noticeable than the paint it saves. The relevance margin that decides when the
+     * browser starts rendering is not author-controllable, so there is no tuning short of removing it. */
 
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qtoggle/qui",
   "description": "A JavaScript UI library with batteries included.",
-  "version": "1.20.0-alpha.5",
+  "version": "1.20.0-alpha.7",
   "author": {
     "name": "Calin Crisan",
     "email": "ccrisan@gmail.com"

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qui-server"
-version = "1.20.0-alpha.5"
+version = "1.20.0-alpha.7"
 description = "A fully fledged qToggle implementation written in Python"
 authors = [
     {name = "Calin Crisan", email = "ccrisan@gmail.com"},