@woosh/meep-engine 3.58.0 → 3.60.0

package/src/view/elements/progress/segmented/playground/index.html

@@ -0,0 +1,78 @@
+<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <title>meep — segmented resource bar</title>
+    <link rel="stylesheet" href="../segmented-resource-bar.css">
+    <style>
+        :root {
+            color-scheme: dark;
+        }
+
+        html, body {
+            margin: 0;
+            background: #2a2f36;
+            color: #d6dae0;
+            font: 12px/1.5 ui-monospace, Consolas, monospace;
+        }
+
+        main {
+            padding: 16px;
+        }
+
+        h2 {
+            font-size: 12px;
+            font-weight: normal;
+            color: #8b939f;
+            margin: 18px 0 8px;
+        }
+
+        .row {
+            display: flex;
+            align-items: center;
+            gap: 12px;
+            margin: 6px 0;
+        }
+
+        .row > .label {
+            width: 110px;
+            text-align: right;
+        }
+
+        .ui-segmented-resource-bar-view {
+            width: 258px;
+        }
+
+        /* the bar starts on a fractional CSS pixel, as it does inside a scaled or flowed HUD */
+        .offset {
+            margin-left: 0.37px;
+        }
+
+        .mode-cells {
+            --segmented-bar-height: 10px;
+        }
+
+        button {
+            font: inherit;
+        }
+    </style>
+</head>
+<body>
+<main>
+    <h2>health: tiers 25 / 100 / 500 / 1000, a shield stacked after the health</h2>
+    <div id="health"></div>
+
+    <h2>ammo: cells, grouped in fives and ungrouped</h2>
+    <div id="ammo"></div>
+
+    <h2>controls</h2>
+    <div class="row">
+        <button id="damage">damage 22%</button>
+        <button id="heal">heal to full</button>
+        <button id="fire">fire one</button>
+        <button id="reload">reload</button>
+    </div>
+</main>
+<script type="module" src="./main.js"></script>
+</body>
+</html>

package/src/view/elements/progress/segmented/playground/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/src/view/elements/progress/segmented/playground/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../../../src/view/elements/progress/segmented/playground/main.js"],"names":[],"mappings":""}

package/src/view/elements/progress/segmented/playground/main.js

@@ -0,0 +1,173 @@
+import Vector1 from "../../../../../core/geom/Vector1.js";
+import { SegmentedResourceBarView } from "../SegmentedResourceBarView.js";
+import { SegmentTier } from "../SegmentTier.js";
+
+/**
+ * An example health ladder, as a game would pass it; the class names reuse the default stylesheet's tiers
+ * @type {SegmentTier[]}
+ */
+const HEALTH_TIERS = [
+    SegmentTier.from(25, 'segment-tier-minor', 1, 5),
+    SegmentTier.from(100, 'segment-tier-major', 1, 3),
+    SegmentTier.from(500, 'segment-tier-super', 2, 0),
+    SegmentTier.from(1000, 'segment-tier-super', 2, 0),
+];
+
+/**
+ * @type {{view:SegmentedResourceBarView, values:Vector1[], max:Vector1}[]}
+ */
+const health_bars = [];
+
+/**
+ * @type {{view:SegmentedResourceBarView, rounds:Vector1, count:number}[]}
+ */
+const ammo_bars = [];
+
+/**
+ * @param {HTMLElement} parent
+ * @param {string} label
+ * @param {SegmentedResourceBarView} view
+ * @param {boolean} offset
+ */
+function add_row(parent, label, view, offset) {
+    const row = document.createElement('div');
+    row.className = 'row';
+
+    const el_label = document.createElement('span');
+    el_label.className = 'label';
+    el_label.textContent = label;
+
+    row.appendChild(el_label);
+
+    if (offset) {
+        view.addClass('offset');
+    }
+
+    row.appendChild(view.el);
+    parent.appendChild(row);
+
+    view.link();
+}
+
+const el_health = document.getElementById('health');
+
+for (const max_value of [60, 300, 606, 1500]) {
+    for (const offset of [false, true]) {
+        const max = new Vector1(max_value);
+        const health = new Vector1(max_value * 0.7);
+        const shield = new Vector1(max_value * 0.12);
+
+        const view = new SegmentedResourceBarView({ values: [health, shield], max, tiers: HEALTH_TIERS });
+
+        add_row(el_health, `${max_value}${offset ? ' +0.37px' : ''}`, view, offset);
+
+        health_bars.push({ view, values: [health, shield], max });
+    }
+}
+
+const el_ammo = document.getElementById('ammo');
+
+for (const count of [12, 17, 33]) {
+    for (const group of [5, 0]) {
+        const rounds = new Vector1(count - 3);
+
+        const view = new SegmentedResourceBarView({
+            values: [rounds],
+            max: new Vector1(count),
+            cells: { count, group }
+        });
+
+        add_row(el_ammo, `${count} / g${group}`, view, group === 0);
+
+        ammo_bars.push({ view, rounds, count });
+    }
+}
+
+document.getElementById('damage').addEventListener('click', () => {
+    for (const { values, max } of health_bars) {
+        let damage = max.getValue() * 0.22;
+
+        // the shield takes it first
+        for (let i = values.length - 1; i >= 0 && damage > 0; i--) {
+            const taken = Math.min(damage, values[i].getValue());
+
+            values[i].set(values[i].getValue() - taken);
+            damage -= taken;
+        }
+    }
+});
+
+document.getElementById('heal').addEventListener('click', () => {
+    for (const { values, max } of health_bars) {
+        values[0].set(max.getValue() * 0.88);
+        values[1].set(max.getValue() * 0.12);
+    }
+});
+
+document.getElementById('fire').addEventListener('click', () => {
+    for (const { rounds } of ammo_bars) {
+        rounds.set(Math.max(0, Math.ceil(rounds.getValue()) - 1));
+    }
+});
+
+let reload_frame = 0;
+
+document.getElementById('reload').addEventListener('click', () => {
+    cancelAnimationFrame(reload_frame);
+
+    // one round every 120 ms, each cell filling as its round goes in
+    const step = () => {
+        let done = true;
+
+        for (const { rounds, count } of ammo_bars) {
+            const next = Math.min(count, rounds.getValue() + 16 / 120);
+
+            rounds.set(next);
+
+            if (next < count) {
+                done = false;
+            }
+        }
+
+        if (!done) {
+            reload_frame = requestAnimationFrame(step);
+        }
+    };
+
+    reload_frame = requestAnimationFrame(step);
+});
+
+/**
+ * For a driver: every notch and cell edge in device pixels, and whether it is whole. Chrome keeps layout in
+ * 1/64 CSS pixel steps, so an edge placed at 0.8 CSS px reads back as 0.796875; anything within one such step of
+ * a whole device pixel paints on it.
+ * @returns {{dpr:number, checked:number, worst:number, off_grid:string[]}}
+ */
+globalThis.segmented_bar_pixel_report = function () {
+    const dpr = devicePixelRatio;
+
+    const tolerance = dpr / 64;
+
+    const off_grid = [];
+    let checked = 0;
+    let worst = 0;
+
+    for (const el of document.querySelectorAll('.notch, .cell')) {
+        const r = el.getBoundingClientRect();
+
+        for (const [name, v] of [['left', r.left], ['right', r.right]]) {
+            const device = v * dpr;
+
+            const miss = Math.abs(device - Math.round(device));
+
+            checked++;
+            worst = Math.max(worst, miss);
+
+            if (miss > tolerance) {
+                off_grid.push(`${el.className} ${name} ${device.toFixed(4)}`);
+            }
+        }
+    }
+
+    return { dpr, checked, worst, off_grid };
+};

package/src/view/elements/progress/segmented/segment_cell_layout.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @typedef {Object} SegmentCellLayout
+ * @property {number} bar_width_device the bar's width in whole device pixels; the last cell ends here
+ * @property {number} gap_device gap between two cells of one group, device pixels
+ * @property {number} group_gap_device gap between two groups, device pixels: 3 in-group gaps
+ * @property {number[]} cell_x_device each cell's left edge, device pixels from the bar's left edge
+ * @property {number[]} cell_width_device each cell's width, device pixels
+ */
+/**
+ * Lays out `count` separate cells across a bar on whole device pixels.
+ *
+ * Every in-group gap is the same `max(1, round(dpr))` device pixels and every between-group gap exactly three of
+ * those. What the gaps leave is shared among the cells, the remainder spread evenly (Bresenham), so no cell is
+ * more than one device pixel wider than another and the last cell ends exactly at `floor(width_px * dpr)`.
+ *
+ * Needs at least one device pixel per cell after the gaps. A bar narrower than that gets zero-width cells and
+ * its last cell does not reach the edge: draw that many rounds as notches instead, or ungroup them.
+ *
+ * @param {number} width_px the bar's width, CSS pixels
+ * @param {number} count number of cells
+ * @param {number} group cells per group, 0 for no grouping
+ * @param {number} dpr device pixel ratio
+ * @returns {SegmentCellLayout}
+ */
+export function segment_cell_layout(width_px: number, count: number, group: number, dpr: number): SegmentCellLayout;
+export type SegmentCellLayout = {
+    /**
+     * the bar's width in whole device pixels; the last cell ends here
+     */
+    bar_width_device: number;
+    /**
+     * gap between two cells of one group, device pixels
+     */
+    gap_device: number;
+    /**
+     * gap between two groups, device pixels: 3 in-group gaps
+     */
+    group_gap_device: number;
+    /**
+     * each cell's left edge, device pixels from the bar's left edge
+     */
+    cell_x_device: number[];
+    /**
+     * each cell's width, device pixels
+     */
+    cell_width_device: number[];
+};
+//# sourceMappingURL=segment_cell_layout.d.ts.map

package/src/view/elements/progress/segmented/segment_cell_layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment_cell_layout.d.ts","sourceRoot":"","sources":["../../../../../../src/view/elements/progress/segmented/segment_cell_layout.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,8CANW,MAAM,SACN,MAAM,SACN,MAAM,OACN,MAAM,GACJ,iBAAiB,CAiD7B;;;;;sBAtEa,MAAM;;;;gBACN,MAAM;;;;sBACN,MAAM;;;;mBACN,MAAM,EAAE;;;;uBACR,MAAM,EAAE"}

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

@@ -0,0 +1,75 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * @typedef {Object} SegmentCellLayout
+ * @property {number} bar_width_device the bar's width in whole device pixels; the last cell ends here
+ * @property {number} gap_device gap between two cells of one group, device pixels
+ * @property {number} group_gap_device gap between two groups, device pixels: 3 in-group gaps
+ * @property {number[]} cell_x_device each cell's left edge, device pixels from the bar's left edge
+ * @property {number[]} cell_width_device each cell's width, device pixels
+ */
+
+/**
+ * Lays out `count` separate cells across a bar on whole device pixels.
+ *
+ * Every in-group gap is the same `max(1, round(dpr))` device pixels and every between-group gap exactly three of
+ * those. What the gaps leave is shared among the cells, the remainder spread evenly (Bresenham), so no cell is
+ * more than one device pixel wider than another and the last cell ends exactly at `floor(width_px * dpr)`.
+ *
+ * Needs at least one device pixel per cell after the gaps. A bar narrower than that gets zero-width cells and
+ * its last cell does not reach the edge: draw that many rounds as notches instead, or ungroup them.
+ *
+ * @param {number} width_px the bar's width, CSS pixels
+ * @param {number} count number of cells
+ * @param {number} group cells per group, 0 for no grouping
+ * @param {number} dpr device pixel ratio
+ * @returns {SegmentCellLayout}
+ */
+export function segment_cell_layout(width_px, count, group, dpr) {
+    assert.isNumber(width_px, 'width_px');
+    assert.isNonNegativeInteger(count, 'count');
+    assert.isNonNegativeInteger(group, 'group');
+    assert.isNumber(dpr, 'dpr');
+
+    const bar_width_device = Math.floor(width_px * dpr);
+
+    const gap_device = Math.max(1, Math.round(dpr));
+    const group_gap_device = gap_device * 3;
+
+    const group_count = group > 0 ? Math.ceil(count / group) : 1;
+    const group_gaps = count > 0 ? group_count - 1 : 0;
+    const cell_gaps = count > 0 ? count - 1 - group_gaps : 0;
+
+    const cells_device = bar_width_device - cell_gaps * gap_device - group_gaps * group_gap_device;
+
+    const base = count > 0 ? Math.max(0, Math.floor(cells_device / count)) : 0;
+    const remainder = count > 0 ? Math.max(0, cells_device - base * count) : 0;
+
+    const cell_x_device = new Array(count);
+    const cell_width_device = new Array(count);
+
+    let x = 0;
+
+    for (let i = 0; i < count; i++) {
+        if (i > 0) {
+            x += (group > 0 && i % group === 0) ? group_gap_device : gap_device;
+        }
+
+        // Bresenham: cell i takes one of the remainder's pixels whenever the running share crosses a whole one
+        const extra = Math.floor((i + 1) * remainder / count) - Math.floor(i * remainder / count);
+        const w = base + extra;
+
+        cell_x_device[i] = x;
+        cell_width_device[i] = w;
+
+        x += w;
+    }
+
+    return {
+        bar_width_device,
+        gap_device,
+        group_gap_device,
+        cell_x_device,
+        cell_width_device
+    };
+}

package/src/view/elements/progress/segmented/segment_notch_place.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Places one notch on whole device pixels.
+ *
+ * The notch is centred on its fraction of the bar, measured in device pixels of the bar's rounded device width,
+ * and is `width_px` CSS pixels wide scaled by the whole part of the pixel ratio, so a 1 px notch is 1 device pixel
+ * at DPR 1.25 and 2 at DPR 1.5 or 2 — never a smear across two. When the bar's own left edge falls between device
+ * pixels the notch is shifted back onto the grid, so `(rect_left + left) * dpr` and `width * dpr` are integers.
+ *
+ * @param {number[]|Float64Array} result receives [left, width], in CSS pixels relative to the bar's left edge
+ * @param {number} result_offset
+ * @param {number} fraction where the notch sits, value / max
+ * @param {number} width_px notch width in CSS pixels, before the pixel-ratio scale
+ * @param {number} rect_left the bar's left edge on the page, CSS pixels (getBoundingClientRect().left)
+ * @param {number} rect_width the bar's width, CSS pixels
+ * @param {number} dpr device pixel ratio
+ */
+export function segment_notch_place(result: number[] | Float64Array, result_offset: number, fraction: number, width_px: number, rect_left: number, rect_width: number, dpr: number): void;
+//# sourceMappingURL=segment_notch_place.d.ts.map

package/src/view/elements/progress/segmented/segment_notch_place.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment_notch_place.d.ts","sourceRoot":"","sources":["../../../../../../src/view/elements/progress/segmented/segment_notch_place.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,4CARW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,YACN,MAAM,YACN,MAAM,aACN,MAAM,cACN,MAAM,OACN,MAAM,QAahB"}

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

@@ -0,0 +1,28 @@
+/**
+ * Places one notch on whole device pixels.
+ *
+ * The notch is centred on its fraction of the bar, measured in device pixels of the bar's rounded device width,
+ * and is `width_px` CSS pixels wide scaled by the whole part of the pixel ratio, so a 1 px notch is 1 device pixel
+ * at DPR 1.25 and 2 at DPR 1.5 or 2 — never a smear across two. When the bar's own left edge falls between device
+ * pixels the notch is shifted back onto the grid, so `(rect_left + left) * dpr` and `width * dpr` are integers.
+ *
+ * @param {number[]|Float64Array} result receives [left, width], in CSS pixels relative to the bar's left edge
+ * @param {number} result_offset
+ * @param {number} fraction where the notch sits, value / max
+ * @param {number} width_px notch width in CSS pixels, before the pixel-ratio scale
+ * @param {number} rect_left the bar's left edge on the page, CSS pixels (getBoundingClientRect().left)
+ * @param {number} rect_width the bar's width, CSS pixels
+ * @param {number} dpr device pixel ratio
+ */
+export function segment_notch_place(result, result_offset, fraction, width_px, rect_left, rect_width, dpr) {
+    const bar_width_device = Math.round(rect_width * dpr);
+    const notch_width_device = width_px * Math.max(1, Math.round(dpr));
+
+    const x_device = Math.round(fraction * bar_width_device) - Math.floor(notch_width_device / 2);
+
+    const origin_device = rect_left * dpr;
+    const origin_shift = (Math.round(origin_device) - origin_device) / dpr;
+
+    result[result_offset] = x_device / dpr + origin_shift;
+    result[result_offset + 1] = notch_width_device / dpr;
+}

package/src/view/elements/progress/segmented/segment_tick_positions.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Which notches a bar of the given max and width draws, and the tier of each.
+ *
+ * A notch at value `v` belongs to the coarsest tier whose unit divides `v`, so a tier marks the same amount on
+ * every bar. A tier whose on-screen spacing (`width_px * unit / max`) is under its `min_spacing_px` is dropped,
+ * and so is every tier finer than it: dropping goes finest first and the coarser tiers stay. A tier is also
+ * dropped when its notches would leave no pixel of bar between them (spacing under `width_px + 1`), which is
+ * what bounds the notch count by the bar's width whatever the tiers ask for.
+ *
+ * Notches sit strictly inside the bar: none at 0, none at max.
+ *
+ * @param {number} max the bar's full amount
+ * @param {number} width_px the bar's width in CSS pixels
+ * @param {{unit:number, width_px:number, min_spacing_px:number}[]} tiers finest first, units strictly ascending
+ * @returns {SegmentTick[]} ascending by value
+ */
+export function segment_tick_positions(max: number, width_px: number, tiers: {
+    unit: number;
+    width_px: number;
+    min_spacing_px: number;
+}[]): SegmentTick[];
+export type SegmentTick = {
+    /**
+     * where the notch sits, in the bar's own units
+     */
+    value: number;
+    /**
+     * index into the tier list of the tier that marks it
+     */
+    tier: number;
+};
+//# sourceMappingURL=segment_tick_positions.d.ts.map

package/src/view/elements/progress/segmented/segment_tick_positions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segment_tick_positions.d.ts","sourceRoot":"","sources":["../../../../../../src/view/elements/progress/segmented/segment_tick_positions.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;GAeG;AACH,4CALW,MAAM,YACN,MAAM,SACN;IAAC,IAAI,EAAC,MAAM,CAAC;IAAC,QAAQ,EAAC,MAAM,CAAC;IAAC,cAAc,EAAC,MAAM,CAAA;CAAC,EAAE,GACrD,WAAW,EAAE,CA+DzB;;;;;WAlGa,MAAM;;;;UACN,MAAM"}

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

@@ -0,0 +1,103 @@
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * @typedef {Object} SegmentTick
+ * @property {number} value where the notch sits, in the bar's own units
+ * @property {number} tier index into the tier list of the tier that marks it
+ */
+
+/**
+ * Relative tolerance for "unit divides value", so a fractional unit (0.1) still divides its own multiples
+ * @type {number}
+ */
+const DIVIDES_TOLERANCE = 1e-9;
+
+/**
+ * @param {number} value
+ * @param {number} unit
+ * @returns {boolean}
+ */
+function unit_divides(value, unit) {
+    const q = value / unit;
+
+    return Math.abs(q - Math.round(q)) <= DIVIDES_TOLERANCE * q;
+}
+
+/**
+ * Which notches a bar of the given max and width draws, and the tier of each.
+ *
+ * A notch at value `v` belongs to the coarsest tier whose unit divides `v`, so a tier marks the same amount on
+ * every bar. A tier whose on-screen spacing (`width_px * unit / max`) is under its `min_spacing_px` is dropped,
+ * and so is every tier finer than it: dropping goes finest first and the coarser tiers stay. A tier is also
+ * dropped when its notches would leave no pixel of bar between them (spacing under `width_px + 1`), which is
+ * what bounds the notch count by the bar's width whatever the tiers ask for.
+ *
+ * Notches sit strictly inside the bar: none at 0, none at max.
+ *
+ * @param {number} max the bar's full amount
+ * @param {number} width_px the bar's width in CSS pixels
+ * @param {{unit:number, width_px:number, min_spacing_px:number}[]} tiers finest first, units strictly ascending
+ * @returns {SegmentTick[]} ascending by value
+ */
+export function segment_tick_positions(max, width_px, tiers) {
+    assert.isNumber(max, 'max');
+    assert.isNumber(width_px, 'width_px');
+    assert.isArray(tiers, 'tiers');
+
+    /**
+     * @type {SegmentTick[]}
+     */
+    const result = [];
+
+    if (!(max > 0) || !(width_px > 0) || !Number.isFinite(max)) {
+        return result;
+    }
+
+    const tier_count = tiers.length;
+
+    for (let i = 1; i < tier_count; i++) {
+        assert.greaterThan(tiers[i].unit, tiers[i - 1].unit, 'tier units must be strictly ascending');
+    }
+
+    // finest tier that is kept; everything coarser is kept with it
+    let first_kept = tier_count;
+
+    for (let i = 0; i < tier_count; i++) {
+        const tier = tiers[i];
+
+        assert.greaterThan(tier.unit, 0, 'tier.unit');
+
+        const spacing = width_px * tier.unit / max;
+        const min_spacing = Math.max(tier.min_spacing_px, tier.width_px + 1);
+
+        if (spacing >= min_spacing) {
+            first_kept = i;
+            break;
+        }
+    }
+
+    for (let i = first_kept; i < tier_count; i++) {
+        const unit = tiers[i].unit;
+
+        for (let k = 1; k * unit < max; k++) {
+            const value = k * unit;
+
+            let claimed_by_coarser = false;
+
+            for (let j = i + 1; j < tier_count; j++) {
+                if (unit_divides(value, tiers[j].unit)) {
+                    claimed_by_coarser = true;
+                    break;
+                }
+            }
+
+            if (!claimed_by_coarser) {
+                result.push({ value, tier: i });
+            }
+        }
+    }
+
+    result.sort((a, b) => a.value - b.value);
+
+    return result;
+}