ranger-compiler 3.5.1 → 3.5.2

package/dist/lib/evg/EVGFlexWrapTest.rgr

@@ -0,0 +1,246 @@
+; SPDX-License-Identifier: MIT
+
+; ==============================================================================
+; EVGFlexWrapTest — a row must not wrap because of its own arithmetic
+; ==============================================================================
+;
+; The case, which is the commonest two-column layout there is:
+;
+;   .body { display: flex; gap: 24px }        ; wrap allowed — the default here
+;   .side { width: 240px }
+;   .main { flex: 1 }
+;
+; `.main`'s width is computed BY THE LAYOUT out of the same line it is then
+; measured against: take the inner width, subtract the sidebar and the gap, and
+; the remainder is `.main`. Adding those three back up is not guaranteed to
+; return the number they were subtracted from — in binary floating point
+; `(a - b - c) + b + c` can land one ulp above `a` — and the wrap test then
+; reads the row as too wide for itself and puts `.main` on a second line.
+;
+; It is not a rare case. Before the tolerance went into `EVGLayout`, the page in
+; `lib/evg/web/responsive` wrapped at 127 of the 680 integer window widths
+; between 821 and 1500, scattered rather than in a band: dragging the window
+; edge dropped the content below the sidebar and pulled it back up a pixel
+; later, over and over. That is what this file is here to stop coming back.
+;
+; --- WHAT IS ACTUALLY ASSERTED ------------------------------------------------
+;
+; Three things, in the order that matters:
+;
+;   1. Across a fine sweep of widths — including fractional ones, because a
+;      device pixel ratio and a `vw` padding both produce them — the two boxes
+;      stay on the same line. One width would prove nothing; the defect was
+;      that SOME widths failed.
+;   2. A row that genuinely does not fit still wraps. A tolerance that stops
+;      every wrap would pass test 1 and be worse than the bug.
+;   3. `flex-wrap: nowrap` still means nowrap.
+; ==============================================================================
+
+Import "EVGElement.rgr"
+Import "EVGUnit.rgr"
+Import "EVGLayout.rgr"
+Import "EVGStyleSheet.rgr"
+
+class FlexWrapCheck {
+    def passed:int 0
+    def failed:int 0
+
+    Constructor () {
+    }
+
+    fn ok:void (name:string cond:boolean) {
+        if cond {
+            passed = (passed + 1)
+            print ("  PASS " + name)
+        } {
+            failed = (failed + 1)
+            print ("  FAIL " + name)
+        }
+    }
+
+    ; A page with `4vw` side padding — the padding matters, because it is what
+    ; makes the inner width fractional and therefore makes the sum that has to
+    ; come back out exact.
+    fn build:EVGElement (sideWidth:string mainFlex:string wrap:string) {
+        def page (EVGElement.createDiv())
+        page.className = "page"
+        page.setAttribute("display" "flex")
+        page.setAttribute("flex-direction" "column")
+        page.setAttribute("padding-left" "4vw")
+        page.setAttribute("padding-right" "4vw")
+
+        def body (EVGElement.createDiv())
+        body.className = "body"
+        body.setAttribute("display" "flex")
+        body.setAttribute("flex-direction" "row")
+        body.setAttribute("gap" "24px")
+        if ((strlen wrap) > 0) {
+            body.setAttribute("flex-wrap" wrap)
+        }
+
+        def side (EVGElement.createDiv())
+        side.className = "side"
+        side.setAttribute("width" sideWidth)
+        side.setAttribute("height" "300px")
+
+        def main (EVGElement.createDiv())
+        main.className = "main"
+        main.setAttribute("flex" mainFlex)
+        main.setAttribute("height" "300px")
+
+        body.addChild(side)
+        body.addChild(main)
+        page.addChild(body)
+        return page
+    }
+
+    fn childAt:EVGElement (root:EVGElement a:int b:int) {
+        def outer:EVGElement (root.getChild(a))
+        return (outer.getChild(b))
+    }
+
+    ; True when the two children of `.body` sit on one line.
+    fn sameRow:boolean (root:EVGElement) {
+        def side:EVGElement (this.childAt(root 0 0))
+        def main:EVGElement (this.childAt(root 0 1))
+        def dy:double (main.calculatedY - side.calculatedY)
+        if (dy < 0.0) {
+            dy = (0.0 - dy)
+        }
+        return (dy < 1.0)
+    }
+
+    fn layoutAt:EVGElement (root:EVGElement w:double) {
+        def lay (new EVGLayout())
+        lay.setPageSize(w 900.0)
+        lay.layout(root)
+        return root
+    }
+
+    fn run:void () {
+        print "EVGFlexWrapTest"
+
+        ; --- 1. the sweep -----------------------------------------------------
+        ;
+        ; 0.25px steps so fractional widths are covered too. Every failure is
+        ; named — a count alone would not say whether the tolerance is slightly
+        ; short or missing entirely.
+        def wrapped:int 0
+        def shown:int 0
+        def w:double 400.0
+        while (w <= 1800.0) {
+            def root:EVGElement (this.build("240px" "1" ""))
+            this.layoutAt(root w)
+            if ((this.sameRow(root)) == false) {
+                wrapped = (wrapped + 1)
+                if (shown < 8) {
+                    shown = (shown + 1)
+                    print ("       wrapped at width " + (to_string w))
+                }
+            }
+            w = (w + 0.25)
+        }
+        this.ok("a 240px sidebar and a flex:1 panel stay on one line at every width"
+            (wrapped == 0))
+
+        ; The same, with the sidebar in a unit that does not divide evenly.
+        def wrapped2:int 0
+        def w2:double 400.0
+        while (w2 <= 1200.0) {
+            def root2:EVGElement (this.build("33.3333%" "1" ""))
+            this.layoutAt(root2 w2)
+            if ((this.sameRow(root2)) == false) {
+                wrapped2 = (wrapped2 + 1)
+            }
+            w2 = (w2 + 0.25)
+        }
+        this.ok("a percentage sidebar and a flex:1 panel stay on one line"
+            (wrapped2 == 0))
+
+        ; --- 2. a row that really does not fit still wraps ---------------------
+        ;
+        ; Two fixed children whose declared widths exceed the line by whole
+        ; pixels. Nothing here is a rounding artifact, so the wrap must happen.
+        def big (EVGElement.createDiv())
+        big.className = "page"
+        big.setAttribute("display" "flex")
+        def row (EVGElement.createDiv())
+        row.setAttribute("display" "flex")
+        row.setAttribute("flex-direction" "row")
+        def a (EVGElement.createDiv())
+        a.setAttribute("width" "400px")
+        a.setAttribute("height" "50px")
+        def b (EVGElement.createDiv())
+        b.setAttribute("width" "400px")
+        b.setAttribute("height" "50px")
+        row.addChild(a)
+        row.addChild(b)
+        big.addChild(row)
+        def lay2 (new EVGLayout())
+        lay2.setPageSize(600.0 900.0)
+        lay2.layout(big)
+        this.ok("two 400px boxes on a 600px line still wrap"
+            ((b.calculatedY - a.calculatedY) > 1.0))
+
+        ; And one that misses by a single whole pixel, which is the smallest
+        ; overflow that is a layout rather than an artifact.
+        def big2 (EVGElement.createDiv())
+        big2.setAttribute("display" "flex")
+        def row2 (EVGElement.createDiv())
+        row2.setAttribute("display" "flex")
+        row2.setAttribute("flex-direction" "row")
+        def c (EVGElement.createDiv())
+        c.setAttribute("width" "300px")
+        c.setAttribute("height" "50px")
+        def d (EVGElement.createDiv())
+        d.setAttribute("width" "301px")
+        d.setAttribute("height" "50px")
+        row2.addChild(c)
+        row2.addChild(d)
+        big2.addChild(row2)
+        def lay3 (new EVGLayout())
+        lay3.setPageSize(600.0 900.0)
+        lay3.layout(big2)
+        this.ok("300px + 301px on a 600px line wraps"
+            ((d.calculatedY - c.calculatedY) > 1.0))
+
+        ; --- 3. nowrap still means nowrap --------------------------------------
+        def nw (EVGElement.createDiv())
+        nw.setAttribute("display" "flex")
+        def row3 (EVGElement.createDiv())
+        row3.setAttribute("display" "flex")
+        row3.setAttribute("flex-direction" "row")
+        row3.setAttribute("flex-wrap" "nowrap")
+        def e (EVGElement.createDiv())
+        e.setAttribute("width" "400px")
+        e.setAttribute("height" "50px")
+        def f (EVGElement.createDiv())
+        f.setAttribute("width" "400px")
+        f.setAttribute("height" "50px")
+        row3.addChild(e)
+        row3.addChild(f)
+        nw.addChild(row3)
+        def lay4 (new EVGLayout())
+        lay4.setPageSize(600.0 900.0)
+        lay4.layout(nw)
+        def dy4:double (f.calculatedY - e.calculatedY)
+        if (dy4 < 0.0) {
+            dy4 = (0.0 - dy4)
+        }
+        this.ok("flex-wrap: nowrap keeps two overflowing boxes on one line"
+            (dy4 < 1.0))
+
+        print ""
+        print ((("Passed: " + (to_string passed)) + "  Failed: ") + (to_string failed))
+        if (failed > 0) {
+            print "FAILED"
+        } {
+            print "OK"
+        }
+    }
+
+    sfn m@(main):void () {
+        def c (new FlexWrapCheck())
+        c.run()
+    }
+}

package/dist/lib/evg/EVGFling.rgr

@@ -0,0 +1,244 @@
+; SPDX-License-Identifier: MIT
+
+; ==============================================================================
+; EVGFling — a finger that leaves the glass moving is still scrolling
+; ==============================================================================
+;
+; A drag that stops when the finger lifts is the difference between a page that
+; feels like a phone and one that feels like a spreadsheet. What a phone does
+; is simple and worth stating exactly, because every part of it is a decision:
+;
+;   THE SPEED IS MEASURED OVER A WINDOW, not from the last two points. The last
+;   sample before a lift is very often a slow one — a finger decelerates on the
+;   glass in the few milliseconds before it leaves — and a fling taken from it
+;   is a fling that barely moves. So the last few samples inside `windowMs` are
+;   summed and the speed is the total distance over the total time.
+;
+;   IT DECAYS IN PROPORTION TO ITSELF, which makes the distance travelled
+;   exactly proportional to the speed of the throw: a swipe twice as fast goes
+;   twice as far. That is the property being asked for, and it falls out of
+;   the decay rather than being a rule on top of it — the total is
+;   `velocity / friction`, and at the default that is four hundred times the
+;   speed in pixels per millisecond, so a firm 3 px/ms flick carries about
+;   1200 pixels, a page and a half of a phone.
+;
+;   The step is `v - v*friction*dt` and not `v * decay^dt`, because Ranger has
+;   no `pow` and does not need one here: over a frame `friction*dt` is between
+;   0.02 and 0.08, where the two agree to a tenth of a percent. The factor is
+;   clamped so a very long frame — a tab coming back to the foreground — stops
+;   the page rather than throwing it backwards.
+;
+;   IT IS DRIVEN BY THE REAL FRAME TIME. `step(dtMs)` asks for a distance, so a
+;   dropped frame moves further rather than slowing the page down; nothing here
+;   assumes sixty of anything.
+;
+; It scrolls nothing itself. `step` returns a distance and the caller decides
+; what it means, which is what lets the same object serve a browser's wheel
+; handler, a UIPanGestureRecognizer and a headless check.
+; ==============================================================================
+
+class EVGFling {
+    ; The samples still inside the window: how far, and over how long.
+    def dys:[double]
+    def dts:[double]
+    ; What the page is doing now, in pixels per millisecond. Zero is stopped.
+    def velocity:double 0.0
+
+    ; --- the numbers, and why they are these numbers --------------------------
+    ;
+    ; The fraction of the speed lost per millisecond. Higher stops sooner.
+    ;
+    ; 0.002 is a total distance of five hundred times the speed in pixels per
+    ; millisecond, and a glide of about two seconds. In the sizes a phone
+    ; actually produces: an idle drag of 0.5 px/ms carries 250 pixels, a
+    ; normal swipe of 2 carries a thousand — more than a screen — and a hard
+    ; flick of 4 carries two thousand, which is two and a half screens of a
+    ; 390x844 phone. Those are the numbers `web/scroll-check.mjs` holds it to.
+    def frictionPerMs:double 0.002
+    ; Below this a lift is a stop and not a throw — a third of a pixel a frame
+    ; at sixty of them, which is under the smallest movement anyone sees.
+    def minVelocity:double 0.05
+    ; A single sample cannot make the page faster than this. A finger that
+    ; jumps — a lost frame, a warped timestamp, a synthetic event — would
+    ; otherwise launch the document into next week.
+    def maxVelocity:double 8.0
+    ; How far back the speed is measured. Long enough to average out one bad
+    ; sample, short enough that a finger that paused before lifting is read as
+    ; having stopped, which is exactly what it did.
+    def windowMs:double 90.0
+
+    Constructor () {
+    }
+
+    ; How quickly a throw runs out. Higher is shorter; `distanceFor` says
+    ; what a given value means in pixels.
+    fn setFriction:void (perMs:double) {
+        frictionPerMs = perMs
+    }
+
+    ; One sample of a drag: how far it moved and how long that took. Sign is
+    ; the caller's — whatever `scroll by this much` means to it.
+    fn track:void (dy:double dtMs:double) {
+        ; TWO MOVES INSIDE ONE TICK OF THE CALLER'S CLOCK. A host whose only
+        ; clock is the frame — the iOS one, whose pan callbacks arrive between
+        ; frames — reports the second move of a frame as having taken no time.
+        ; Dropping it would lose most of a fast swipe, which is the swipe that
+        ; matters, so it is folded into the sample already there: the
+        ; distances add and the time stays the frame's, which is what happened.
+        if (dtMs <= 0.0) {
+            def n:int (array_length dys)
+            if (n > 0) {
+                dys = (this.withAdded(dys (n - 1) dy))
+            }
+            return
+        }
+        ; A gap longer than the window is a new gesture as far as speed is
+        ; concerned: whatever was moving before it is not moving now.
+        if (dtMs > windowMs) {
+            this.clearSamples()
+        }
+        push dys dy
+        push dts dtMs
+        this.trim()
+    }
+
+    ; `dys` with `dy` added to the entry at `i`. A list is rebuilt rather than
+    ; written into because Ranger has no indexed assignment on one, and the
+    ; list is at most a handful of samples long.
+    fn withAdded:[double] (src:[double] i:int dy:double) {
+        def out:[double]
+        def k:int 0
+        while (k < (array_length src)) {
+            def v:double (itemAt src k)
+            if (k == i) {
+                v = (v + dy)
+            }
+            push out v
+            k = (k + 1)
+        }
+        return out
+    }
+
+    fn clearSamples:void () {
+        def a:[double]
+        dys = a
+        def b:[double]
+        dts = b
+    }
+
+    ; Drop whatever has fallen out of the window, oldest first, but always keep
+    ; the last sample: a single slow one is still the best answer there is.
+    fn trim:void () {
+        def total:double (this.windowTotalTime())
+        while ((array_length dts) > 1) {
+            def oldest:double (itemAt dts 0)
+            if ((total - oldest) < windowMs) {
+                return
+            }
+            total = (total - oldest)
+            def ky:[double]
+            def kt:[double]
+            def i:int 1
+            while (i < (array_length dts)) {
+                push ky (itemAt dys i)
+                push kt (itemAt dts i)
+                i = (i + 1)
+            }
+            dys = ky
+            dts = kt
+        }
+    }
+
+    fn windowTotalTime:double () {
+        def t:double 0.0
+        def i:int 0
+        while (i < (array_length dts)) {
+            t = (t + (itemAt dts i))
+            i = (i + 1)
+        }
+        return t
+    }
+
+    fn windowTotalDistance:double () {
+        def d:double 0.0
+        def i:int 0
+        while (i < (array_length dys)) {
+            d = (d + (itemAt dys i))
+            i = (i + 1)
+        }
+        return d
+    }
+
+    ; The speed of the drag as it stands, over the window. Public because a
+    ; host that wants to decide for itself whether a gesture was a throw can
+    ; ask, and because it is the one number worth seeing in a test.
+    fn trackedVelocity:double () {
+        def t:double (this.windowTotalTime())
+        if (t <= 0.0) {
+            return 0.0
+        }
+        def v:double ((this.windowTotalDistance()) / t)
+        if (v > maxVelocity) {
+            return maxVelocity
+        }
+        if (v < (0.0 - maxVelocity)) {
+            return (0.0 - maxVelocity)
+        }
+        return v
+    }
+
+    ; The finger left. Returns whether that started a fling — a lift below
+    ; `minVelocity` is a stop, and says so.
+    fn release:boolean () {
+        def v:double (this.trackedVelocity())
+        this.clearSamples()
+        if ((fabs v) < minVelocity) {
+            velocity = 0.0
+            return false
+        }
+        velocity = v
+        return true
+    }
+
+    ; Stop dead. A finger going down catches the page where it is, the way it
+    ; does on a phone, and a wheel event takes it over.
+    fn halt:void () {
+        velocity = 0.0
+        this.clearSamples()
+    }
+
+    fn running:boolean () {
+        return (velocity != 0.0)
+    }
+
+    ; How far to scroll for this frame, and the speed left afterwards. Zero
+    ; when there is no fling, so a caller can ask on every frame.
+    fn step:double (dtMs:double) {
+        if (velocity == 0.0) {
+            return 0.0
+        }
+        if (dtMs <= 0.0) {
+            return 0.0
+        }
+        def d:double (velocity * dtMs)
+        def keep:double (1.0 - (frictionPerMs * dtMs))
+        if (keep < 0.0) {
+            keep = 0.0
+        }
+        velocity = (velocity * keep)
+        if ((fabs velocity) < minVelocity) {
+            velocity = 0.0
+        }
+        return d
+    }
+
+    ; What a throw at this speed would cover in total, if nothing stopped it.
+    ; The integral of the decay, and the reason "twice as fast goes twice as
+    ; far" is a fact about this class rather than a hope: it is linear in `v`.
+    fn distanceFor:double (v:double) {
+        if (frictionPerMs <= 0.0) {
+            return 0.0
+        }
+        return (v / frictionPerMs)
+    }
+}