@qtoggle/qui 1.20.0-alpha.4 → 1.20.0-alpha.6

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/global-glass.less

@@ -9,8 +9,8 @@ div.qui-global-glass {
     left: 0;
     right: 0;
     bottom: 0;
+    /* backdrop-filter is set once below and never changes, so listing it here only ever cost a property to watch */
     transition: opacity @transition-duration ease,
-                backdrop-filter @transition-duration linear,
                 margin-top @transition-duration linear;
     opacity: 0;
     display: flex;

package/less/lists.less

@@ -29,10 +29,15 @@ div.qui-list-child {
 
 div.qui-list-child.qui-list-item {
 
-    /* Nothing inside an item is ever painted outside of it, since div.qui-list-child above already clips with
-     * overflow: hidden. Containment is therefore visually inert here, but it lets the engine scope layout and style
-     * invalidation to the single row that changed, instead of the whole list, and skip painting off-screen rows. */
-    contain: layout style paint;
+    /* No `contain` here, deliberately. Layout or paint containment makes each row an independent unit for pixel
+     * snapping, and the separator below is a 0.0625em border -- one device pixel at the default font size, but a
+     * fractional one as soon as the page is zoomed or the root font size is not 16px. Snapped per row rather than
+     * across the list, some of those borders round away to nothing and the separator simply vanishes for a few rows.
+     * Reproduced at a 53.6px row pitch: 7 of 10 separators drawn with containment, 10 of 10 without. `contain: paint`
+     * alone and `contain: layout style` alone each do it; only `contain: style` is safe, and that buys nothing.
+     *
+     * The off-screen saving is not lost: content-visibility on the icon-label view below implies containment on that
+     * element, which carries no border of its own. */
 
     &.hidden {
         opacity: 0;

package/less/main-ui.less

@@ -24,11 +24,13 @@ div.qui-main-container-glass {
     right: 0;
     bottom: 0;
     left: 0;
-    transition: backdrop-filter @transition-duration linear;
-}
+    opacity: 0;
 
-div.qui-main-container-glass.visible {
+    /* The filter is constant and only the opacity of the filtered layer is animated. Transitioning backdrop-filter
+     * itself gives the compositor a different filter to apply on every frame, across the whole viewport, and nothing
+     * it can cache. There is no cost while hidden: VisibilityManager sets display: none once the fade has finished. */
     backdrop-filter: @modal-background-filter;
+    transition: opacity @transition-duration linear;
 
     /* Workaround for Firefox that doesn't support backdrop-filter property */
     @supports (-moz-appearance:none) {
@@ -36,6 +38,10 @@ div.qui-main-container-glass.visible {
     }
 }
 
+div.qui-main-container-glass.visible {
+    opacity: 1;
+}
+
 div.qui-pages-container {
     height: 100%;
 }

package/less/pages/page.less

@@ -27,10 +27,36 @@ div.qui-page.visible {
     z-index: 1;
 }
 
-body.small-screen > div.qui-main-container > div.qui-pages-container > div.qui-page.visible,
-body.small-screen > div.qui-global-glass > div.qui-global-glass-container > div.qui-page.visible {
+/* On a small screen a page is always exactly as wide as its container, so translateX(100%) lands in the very same
+ * place as left: 100% -- but on the compositor, instead of relayouting and repainting both page subtrees on every
+ * frame of the slide.
+ *
+ * The resting state is deliberately `transform: none` and not `translateX(0)`: any transform other than `none` makes
+ * the page a containing block for its `position: fixed` descendants, which would unpin the form button bar (see
+ * forms/form.less). Interpolating out of `none` animates perfectly well, and while a page is actually sliding, its
+ * button bar travelling with it is what one wants anyway.
+ *
+ * The desktop column layout deliberately stays on `left`/`width`: there a page is narrower than its container, so
+ * translateX(100%) would not carry it clear of the viewport, and the slide distance would have to be computed per
+ * page against its own width. */
+body.small-screen > div.qui-main-container > div.qui-pages-container > div.qui-page,
+body.small-screen > div.qui-global-glass > div.qui-global-glass-container > div.qui-page {
     width: 100% !important;
     left: 0 !important;
+    transform: translateX(100%);
+    transition: opacity @transition-duration ease-out,
+                transform @transition-duration ease;
+
+    &.attached {
+        transform: translateX(-100%);
+    }
+
+    /* Popups fade in place; they never slide */
+    &.popup,
+    &.visible {
+        transform: none;
+    }
+
 }
 
 div.qui-page.current {

package/less/widgets/check-button.less

@@ -20,7 +20,7 @@ div.qui-check-button {
     transition+: background @transition-duration ease,
                  color @transition-duration ease,
                  opacity @transition-duration ease,
-                 border @transition-duration ease;
+                 border-color @transition-duration ease;
     .qui-focusable-widget();
 
     &:FOCUS {

package/less/widgets/common-buttons.less

@@ -4,11 +4,14 @@
 @import (reference) "common";
 
 
+/* border-color, not the border shorthand: the width and style of these borders are set once and never animate, so
+ * naming the colour keeps the fade while leaving border-width and border-style -- the two that would cost layout --
+ * out of the transition entirely. */
 .qui-base-button {
     transition: background @transition-duration ease,
                 color @transition-duration ease,
                 opacity @transition-duration ease,
-                border @transition-duration ease;
+                border-color @transition-duration ease;
     box-sizing: border-box;
     cursor: pointer;
     .noselect;
@@ -73,7 +76,7 @@
     transition+: background @transition-duration ease,
                  color @transition-duration ease,
                  opacity @transition-duration ease,
-                 border @transition-duration ease;
+                 border-color @transition-duration ease;
     .qui-focusable-widget();
 
     &:FOCUS {

package/package.json

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

package/pyproject.toml

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