@woosh/meep-engine 3.59.0 → 3.60.1

package/src/view/elements/progress/segmented/SegmentedResourceBarView.js

@@ -5,27 +5,91 @@ import { clamp01 } from "../../../../core/math/clamp01.js";
 import ListView from "../../../common/ListView.js";
 import { DomSizeObserver } from "../../../util/DomSizeObserver.js";
 import View from "../../../View.js";
-import { CanvasView } from "../../CanvasView.js";
 import EmptyView from "../../EmptyView.js";
-import { RESOURCE_BAR_SEGMENTS } from "./RESOURCE_BAR_SEGMENTS.js";
+import { GhostTrail } from "./GhostTrail.js";
+import { SEGMENT_TIERS_DEFAULT } from "./SEGMENT_TIERS_DEFAULT.js";
+import { segment_cell_layout } from "./segment_cell_layout.js";
+import { segment_notch_place } from "./segment_notch_place.js";
+import { segment_tick_positions } from "./segment_tick_positions.js";
+
+/**
+ * A width change smaller than this, in CSS pixels, does not rebuild the notches
+ * @type {number}
+ */
+const REBUILD_WIDTH_THRESHOLD_PX = 0.5;
+
+/**
+ * Cell fills within this of a whole cell count as whole, so 7 of 30 rounds is 7 full cells and not 7 and a sliver
+ * @type {number}
+ */
+const CELL_FILL_TOLERANCE = 1e-9;
+
+const CELL_STATE_EMPTY = 0;
+const CELL_STATE_PARTIAL = 1;
+const CELL_STATE_FILLED = 2;
+
+const CELL_STATE_CLASS = ['cell empty', 'cell partial', 'cell filled'];
+
+/**
+ * @param {number} x
+ * @returns {number}
+ */
+function snap_whole(x) {
+    const r = Math.round(x);
+
+    return Math.abs(x - r) <= CELL_FILL_TOLERANCE ? r : x;
+}
 
+/**
+ * Resource bar in the style of a MOBA health bar: the values fill it end to end, notches mark fixed amounts, and
+ * a ghost behind the fill trails a drop so the loss stays readable for a moment.
+ *
+ * Two modes:
+ * - notches (default): a continuous fill, with a notch at every multiple of each {@link SegmentTier}'s unit;
+ * - cells (`cells` given): `count` separate cells with exact, identical gaps, for counting rounds and the like.
+ *
+ * Notches and cells sit on whole device pixels at any pixel ratio and under a CSS scale. Colours, notch heights
+ * and the ghost are styled by `segmented-resource-bar.css` through `--segmented-bar-*` custom properties.
+ */
 export class SegmentedResourceBarView extends View {
     /**
      *
      * @param {Object} options
-     * @param {(Vector1|ObservedInteger)[]} options.values
+     * @param {(Vector1|ObservedInteger)[]} options.values stacked end to end, value 0 first; their total is clamped to max
      * @param {Vector1|ObservedInteger|ReactiveExpression} [options.max=1]
      * @param {string[]} [options.classList]
+     * @param {{unit:number, class_name:string, width_px:number, min_spacing_px:number}[]} [options.tiers] notch tiers, finest first; see {@link SegmentTier}
+     * @param {{count:number, group:number}|null} [options.cells] draw `count` cells instead of notches, in groups of `group` (0 for none)
+     * @param {number} [options.ghost_delay_ms=100] how long the ghost holds after a drop; see {@link GhostTrail}
+     * @param {number} [options.ghost_duration_min_ms=300] how long the ghost takes to close the smallest loss
+     * @param {number} [options.ghost_duration_max_ms=800] how long it takes to close a loss of the whole bar; both
+     *  durations are 0 under prefers-reduced-motion, so the ghost holds, then snaps
      */
     constructor({
                     values,
                     max = Vector1.one,
-                    classList = []
+                    classList = [],
+                    tiers = SEGMENT_TIERS_DEFAULT,
+                    cells = null,
+                    ghost_delay_ms = 100,
+                    ghost_duration_min_ms = 300,
+                    ghost_duration_max_ms = 800
                 }) {
         super();
 
         assert.isArray(values, 'values');
         assert.defined(max, 'max');
+        assert.isArray(tiers, 'tiers');
+        assert.isFinite(ghost_delay_ms, 'ghost_delay_ms');
+        assert.greaterThanOrEqual(ghost_delay_ms, 0, 'ghost_delay_ms must not be negative');
+        assert.isFinite(ghost_duration_max_ms, 'ghost_duration_max_ms');
+        assert.greaterThanOrEqual(ghost_duration_min_ms, 0, 'ghost_duration_min_ms must not be negative');
+        assert.greaterThanOrEqual(ghost_duration_max_ms, ghost_duration_min_ms, 'ghost_duration_max_ms must not be under ghost_duration_min_ms');
+
+        if (cells !== null) {
+            assert.isNonNegativeInteger(cells.count, 'cells.count');
+            assert.isNonNegativeInteger(cells.group, 'cells.group');
+        }
 
         /**
          *
@@ -41,6 +105,75 @@ export class SegmentedResourceBarView extends View {
          */
         this.__value_max = max;
 
+        /**
+         * @type {{unit:number, class_name:string, width_px:number, min_spacing_px:number}[]}
+         * @private
+         */
+        this.__tiers = tiers;
+
+        /**
+         * @type {{count:number, group:number}|null}
+         * @private
+         */
+        this.__cells = cells;
+
+        /**
+         * @type {GhostTrail}
+         * @private
+         */
+        this.__ghost = new GhostTrail();
+        this.__ghost.delay_ms = ghost_delay_ms;
+
+        /**
+         * @type {number}
+         * @private
+         */
+        this.__ghost_duration_min_ms = ghost_duration_min_ms;
+
+        /**
+         * @type {number}
+         * @private
+         */
+        this.__ghost_duration_max_ms = ghost_duration_max_ms;
+
+        /**
+         * Total fill as a fraction of max, as last drawn
+         * @type {number}
+         * @private
+         */
+        this.__total_fraction = 0;
+
+        /**
+         * @type {MediaQueryList|null}
+         * @private
+         */
+        this.__reduced_motion = typeof matchMedia === 'function' ? matchMedia('(prefers-reduced-motion: reduce)') : null;
+
+        /**
+         * Watches for the device pixel ratio moving off the one the layout was built for
+         * @type {MediaQueryList|null}
+         * @private
+         */
+        this.__dpr_query = null;
+
+        this.__handle_dpr_change = this.__handle_dpr_change.bind(this);
+
+        this.__frame_pending = false;
+        this.__frame_id = 0;
+        this.__animate_ghost = this.__animate_ghost.bind(this);
+
+        // what the layout was last built for, so it is rebuilt only when one of them moves
+        this.__built_max = NaN;
+        this.__built_width = NaN;
+        this.__built_ratio = NaN;
+        this.__built_origin_phase = NaN;
+
+        /**
+         * scratch for {@link segment_notch_place}
+         * @type {Float64Array}
+         * @private
+         */
+        this.__place = new Float64Array(2);
 
         /**
          *
@@ -52,31 +185,93 @@ export class SegmentedResourceBarView extends View {
         this.el = document.createElement('div');
 
         this.addClass('ui-segmented-resource-bar-view');
+        this.addClass(cells === null ? 'mode-notches' : 'mode-cells');
 
         this.addClasses(classList);
 
+        // build structure; the ghost goes first so the fills paint over it
 
-        // build structure
-        this.__v__fill = new EmptyView({ classList: ['fill-container'] });
-        this.addChild(this.__v__fill);
+        /**
+         * @type {HTMLElement}
+         * @private
+         */
+        this.__el_ghost = document.createElement('div');
+        this.__el_ghost.className = 'ghost';
 
+        /**
+         * @type {HTMLElement[]}
+         * @private
+         */
         this.__value_fills = [];
 
-        for (let i = 0; i < this.__values_current.length; i++) {
-            const v_value = new EmptyView({ classList: ['fill', `value-${i}`] });
+        /**
+         * @type {HTMLElement[]}
+         * @private
+         */
+        this.__notch_elements = [];
 
-            this.__v__fill.addChild(v_value);
-            this.__value_fills[i] = v_value;
-        }
+        /**
+         * @type {HTMLElement[]}
+         * @private
+         */
+        this.__cell_elements = [];
+        this.__cell_fill_elements = [];
+        this.__cell_ghost_elements = [];
+        this.__cell_states = new Uint8Array(cells === null ? 0 : cells.count);
+
+        // what each cell's fill and ghost were last drawn at, so an animation frame writes only the cells that moved
+        this.__cell_fill_drawn = new Float64Array(cells === null ? 0 : cells.count);
+        this.__cell_ghost_drawn = new Float64Array(cells === null ? 0 : cells.count);
+
+        if (cells === null) {
+            this.el.appendChild(this.__el_ghost);
+
+            const el_fill_container = document.createElement('div');
+            el_fill_container.className = 'fill-container';
+
+            for (let i = 0; i < values.length; i++) {
+                const el_fill = document.createElement('div');
+                el_fill.className = `fill value-${i}`;
+
+                el_fill_container.appendChild(el_fill);
+                this.__value_fills[i] = el_fill;
+            }
+
+            this.el.appendChild(el_fill_container);
+
+            /**
+             * The notches' own box; what they are positioned in and what is measured to place them
+             * @type {HTMLElement}
+             * @private
+             */
+            this.__el_layout = document.createElement('div');
+            this.__el_layout.className = 'notches';
+        } else {
+            this.__el_layout = document.createElement('div');
+            this.__el_layout.className = 'cells';
+
+            for (let i = 0; i < cells.count; i++) {
+                const el_cell = document.createElement('div');
+                el_cell.className = CELL_STATE_CLASS[CELL_STATE_EMPTY];
 
-        this.__v__ghost = new EmptyView({ classList: ['ghost'] });
-        this.addChild(this.__v__ghost);
+                const el_cell_ghost = document.createElement('div');
+                el_cell_ghost.className = 'cell-ghost';
 
+                const el_cell_fill = document.createElement('div');
+                el_cell_fill.className = 'cell-fill';
 
-        this.__v_segments = new CanvasView();
-        this.__v_segments.addClass('notch-overlay');
+                el_cell.appendChild(el_cell_ghost);
+                el_cell.appendChild(el_cell_fill);
 
-        this.addChild(this.__v_segments);
+                this.__el_layout.appendChild(el_cell);
+
+                this.__cell_elements[i] = el_cell;
+                this.__cell_ghost_elements[i] = el_cell_ghost;
+                this.__cell_fill_elements[i] = el_cell_fill;
+            }
+        }
+
+        this.el.appendChild(this.__el_layout);
 
 
         /**
@@ -131,15 +326,15 @@ export class SegmentedResourceBarView extends View {
         this.bindSignal(this.__value_max.onChanged, this.handleMaxChange, this);
 
         /**
-         * We need an observer in order to know when we need to resize the canvas element that holds marks
+         * Tells us when the bar's width moves, so the notches or cells can be placed again
          * @type {DomSizeObserver}
          * @private
          */
         this.__sizeObserver = new DomSizeObserver();
 
-        this.__sizeObserver.attach(this.el);
+        this.__sizeObserver.attach(this.__el_layout);
 
-        this.__sizeObserver.dimensions.size.onChanged.add(this.__updateSize, this);
+        this.__sizeObserver.dimensions.size.onChanged.add(this.updateSegments, this);
     }
 
     link() {
@@ -147,10 +342,10 @@ export class SegmentedResourceBarView extends View {
             return;
         }
 
-
         super.link();
 
         this.__sizeObserver.start();
+        this.__watch_device_pixel_ratio();
         this.update();
     }
 
@@ -161,22 +356,22 @@ export class SegmentedResourceBarView extends View {
 
         this.__sizeObserver.stop();
 
+        if (this.__dpr_query !== null) {
+            this.__dpr_query.removeEventListener('change', this.__handle_dpr_change);
+            this.__dpr_query = null;
+        }
+
+        if (this.__frame_pending) {
+            cancelAnimationFrame(this.__frame_id);
+            this.__frame_pending = false;
+        }
+
         super.unlink();
     }
 
     update() {
-        this.updateFill();
-        this.updateSegments();
-    }
-
-    __updateSize() {
-
-        if (this.__sizeObserver.dimensions.size.distanceSqrTo(this.__v_segments.size) < 0.5) {
-            // change too small, ignore
-            return;
-        }
-
         this.updateSegments();
+        this.updateFill();
     }
 
     handleMaxChange() {
@@ -184,130 +379,276 @@ export class SegmentedResourceBarView extends View {
         this.updateFill();
     }
 
+    /**
+     * Place the notches or cells again, if the max, the bar's width (by {@link REBUILD_WIDTH_THRESHOLD_PX} or more),
+     * its pixel ratio or the device-pixel phase of its left edge has moved since they were last placed.
+     */
     updateSegments() {
+        const el = this.__el_layout;
+
         /**
-         *
-         * @type {Vector2}
+         * width as laid out, before any transform on an ancestor
+         * @type {number}
          */
-        const size = this.__sizeObserver.dimensions.size;
+        const layout_width = el.offsetWidth;
 
+        if (!(layout_width > 0)) {
+            // not laid out (detached, display:none); nothing to place against
+            return;
+        }
 
-        this.__v_segments.size.copy(size);
+        const rect = el.getBoundingClientRect();
 
-        const vSegments = this.__v_segments;
+        const dpr = typeof devicePixelRatio === 'number' && devicePixelRatio > 0 ? devicePixelRatio : 1;
 
-        vSegments.clear();
+        // a CSS scale on an ancestor shows each CSS pixel of the bar as `scale` page pixels
+        const scale = rect.width / layout_width;
 
-        /**
-         *
-         * @type {CanvasRenderingContext2D}
-         */
-        const ctx = vSegments.context2d;
+        // device pixels per CSS pixel of the bar
+        const ratio = dpr * scale;
 
-        const maxValue = this.__value_max.getValue();
+        const origin_device = rect.left * dpr;
+        const origin_phase = origin_device - Math.round(origin_device);
 
-        // figure out what segments to use
-        let major_segment_index = 0;
+        const max = this.__value_max.getValue();
 
-        const max_segment_index = RESOURCE_BAR_SEGMENTS.length - 1;
-        for (let i = max_segment_index; i >= 0; i--) {
-            const segmentDefinition = RESOURCE_BAR_SEGMENTS[i];
+        if (
+            max === this.__built_max
+            && Math.abs(layout_width - this.__built_width) < REBUILD_WIDTH_THRESHOLD_PX
+            && ratio === this.__built_ratio
+            && origin_phase === this.__built_origin_phase
+        ) {
+            return;
+        }
 
-            if (segmentDefinition.value <= maxValue && (i >= max_segment_index || RESOURCE_BAR_SEGMENTS[i + 1].value > maxValue)) {
-                //we found major segment
-                major_segment_index = i;
-            }
+        this.__built_max = max;
+        this.__built_width = layout_width;
+        this.__built_ratio = ratio;
+        this.__built_origin_phase = origin_phase;
+
+        // the bar's left edge in its own CSS pixels, such that left * ratio lands where the page puts it
+        const local_left = origin_device / ratio;
 
+        if (this.__cells === null) {
+            this.__place_notches(max, layout_width, local_left, ratio);
+        } else {
+            this.__place_cells(layout_width, local_left, ratio);
         }
+    }
 
-        const major_spec = RESOURCE_BAR_SEGMENTS[major_segment_index];
-        const minor_spec = RESOURCE_BAR_SEGMENTS[major_segment_index - 1];
+    /**
+     * @param {number} max
+     * @param {number} width
+     * @param {number} left
+     * @param {number} ratio
+     * @private
+     */
+    __place_notches(max, width, left, ratio) {
+        const tiers = this.__tiers;
+        const ticks = segment_tick_positions(max, width, tiers);
 
+        const tick_count = ticks.length;
+        const elements = this.__notch_elements;
+        const container = this.__el_layout;
 
-        const majorSegmentValue = major_spec.value;
+        while (elements.length < tick_count) {
+            const el = document.createElement('div');
 
-        if (minor_spec === undefined) {
-            //no minor spec, only paint major
+            container.appendChild(el);
+            elements.push(el);
+        }
 
-            /**
-             *
-             * @type {number}
-             */
-            const stepCount = maxValue / majorSegmentValue;
+        while (elements.length > tick_count) {
+            container.removeChild(elements.pop());
+        }
 
-            const segmentWidth = size.x / stepCount;
+        const place = this.__place;
 
+        for (let i = 0; i < tick_count; i++) {
+            const tick = ticks[i];
+            const tier = tiers[tick.tier];
 
-            for (let i = 1; i < stepCount; i++) {
+            segment_notch_place(place, 0, tick.value / max, tier.width_px, left, width, ratio);
 
-                const x = i * segmentWidth;
+            const el = elements[i];
 
-                // major notch
+            el.className = `notch ${tier.class_name}`;
 
-                major_spec.draw(ctx, x, size.y);
+            const style = el.style;
 
-            }
+            style.left = `${place[0]}px`;
+            style.width = `${place[1]}px`;
+        }
+    }
 
-        } else {
+    /**
+     * @param {number} width
+     * @param {number} left
+     * @param {number} ratio
+     * @private
+     */
+    __place_cells(width, left, ratio) {
+        const cells = this.__cells;
 
-            const minorSegmentValue = minor_spec.value;
+        const layout = segment_cell_layout(width, cells.count, cells.group, ratio);
 
-            const majorMultiplier = majorSegmentValue / minorSegmentValue;
+        const origin_device = left * ratio;
+        const origin_shift_device = Math.round(origin_device) - origin_device;
 
-            /**
-             *
-             * @type {number}
-             */
-            const stepCount = maxValue / minorSegmentValue;
+        const cell_x = layout.cell_x_device;
+        const cell_width = layout.cell_width_device;
+        const elements = this.__cell_elements;
 
-            const minorSegmentWidth = size.x / stepCount;
+        for (let i = 0; i < cells.count; i++) {
+            const style = elements[i].style;
 
-            const displayMinor = minorSegmentWidth >= 2;
+            style.left = `${(cell_x[i] + origin_shift_device) / ratio}px`;
+            style.width = `${cell_width[i] / ratio}px`;
+        }
+    }
 
-            for (let i = 1; i < stepCount; i++) {
+    updateFill() {
+        const m = this.__value_max.getValue();
 
-                const x = i * minorSegmentWidth;
+        const values = this.__values_current;
+        const value_count = values.length;
 
-                if (i % majorMultiplier === 0) {
-                    // major notch
+        const fills = this.__value_fills;
+        const draw_fills = fills.length > 0;
 
-                    major_spec.draw(ctx, x, size.y);
+        let total = 0;
 
-                } else if (displayMinor) {
-                    // minor notch
+        for (let i = 0; i < value_count; i++) {
+            const value = Math.max(0, values[i].getValue());
 
-                    minor_spec.draw(ctx, x, size.y);
+            const f0 = m > 0 ? clamp01(total / m) : 0;
 
-                }
+            total += value;
+
+            const f1 = m > 0 ? clamp01(total / m) : 0;
 
+            if (draw_fills) {
+                const style = fills[i].style;
+
+                style.left = `${f0 * 100}%`;
+                style.width = `${(f1 - f0) * 100}%`;
             }
         }
+
+        const total_fraction = m > 0 ? clamp01(total / m) : 0;
+
+        this.__total_fraction = total_fraction;
+
+        const now = performance.now();
+
+        const ghost = this.__ghost;
+
+        const reduced_motion = this.__reduced_motion !== null && this.__reduced_motion.matches;
+
+        ghost.duration_min_ms = reduced_motion ? 0 : this.__ghost_duration_min_ms;
+        ghost.duration_max_ms = reduced_motion ? 0 : this.__ghost_duration_max_ms;
+        ghost.set(total_fraction, now);
+
+        this.__draw(now);
+    }
+
+    /**
+     * Draw the cells (in cell mode) and the ghost as they stand at `time_ms`, and keep animating until the ghost settles
+     * @param {number} time_ms
+     * @private
+     */
+    __draw(time_ms) {
+        const ghost_fraction = this.__ghost.sample(time_ms);
+
+        if (this.__cells === null) {
+            this.__el_ghost.style.width = `${ghost_fraction * 100}%`;
+        } else {
+            this.__draw_cells(this.__total_fraction, ghost_fraction);
+        }
+
+        if (!this.__ghost.is_settled(time_ms) && this.isLinked && !this.__frame_pending) {
+            this.__frame_pending = true;
+            this.__frame_id = requestAnimationFrame(this.__animate_ghost);
+        }
     }
 
-    updateFill() {
-        const m = this.__value_max.getValue();
+    /**
+     * @param {number} total_fraction
+     * @param {number} ghost_fraction
+     * @private
+     */
+    __draw_cells(total_fraction, ghost_fraction) {
+        const count = this.__cells.count;
 
-        let total_current = 0;
+        const fill_cells = snap_whole(total_fraction * count);
+        const ghost_cells = snap_whole(ghost_fraction * count);
 
-        for (let i = 0; i < this.__values_current.length; i++) {
-            const v = this.__values_current[i];
+        const states = this.__cell_states;
+
+        for (let i = 0; i < count; i++) {
+            const fill = clamp01(fill_cells - i);
+            const ghost = clamp01(ghost_cells - i);
+
+            const state = fill >= 1 ? CELL_STATE_FILLED : (fill > 0 ? CELL_STATE_PARTIAL : CELL_STATE_EMPTY);
+
+            if (states[i] !== state) {
+                states[i] = state;
+                this.__cell_elements[i].className = CELL_STATE_CLASS[state];
+            }
+
+            if (this.__cell_fill_drawn[i] !== fill) {
+                this.__cell_fill_drawn[i] = fill;
+                this.__cell_fill_elements[i].style.width = `${fill * 100}%`;
+            }
 
-            const value = v.getValue();
+            if (this.__cell_ghost_drawn[i] !== ghost) {
+                this.__cell_ghost_drawn[i] = ghost;
+                this.__cell_ghost_elements[i].style.width = `${ghost * 100}%`;
+            }
+        }
+    }
 
-            total_current += value;
+    /**
+     * @private
+     */
+    __animate_ghost() {
+        this.__frame_pending = false;
 
-            const v_fraction = clamp01(v / m);
+        if (!this.isLinked) {
+            return;
+        }
 
-            const fill_view = this.__value_fills[i];
+        this.__draw(performance.now());
+    }
 
-            fill_view.el.style.width = `${v_fraction * 100}%`;
+    /**
+     * Arm a one-shot watch on the current device pixel ratio; it fires when the window moves to another screen or the
+     * page is zoomed, neither of which resizes the bar in CSS pixels
+     * @private
+     */
+    __watch_device_pixel_ratio() {
+        if (typeof matchMedia !== 'function' || typeof devicePixelRatio !== 'number') {
+            return;
         }
 
+        const query = matchMedia(`(resolution: ${devicePixelRatio}dppx)`);
+
+        query.addEventListener('change', this.__handle_dpr_change, { once: true });
 
-        const f = clamp01(total_current / m);
+        this.__dpr_query = query;
+    }
+
+    /**
+     * @private
+     */
+    __handle_dpr_change() {
+        this.__dpr_query = null;
 
-        const width = `${f * 100}%`;
+        if (!this.isLinked) {
+            return;
+        }
 
-        this.__v__ghost.el.style.width = width;
+        this.updateSegments();
+        this.__watch_device_pixel_ratio();
     }
 }