ranger-compiler 3.5.0 → 3.5.2

package/dist/lib/evg/EvgHost.rgr

@@ -0,0 +1,451 @@
+; SPDX-License-Identifier: MIT
+; ==============================================================================
+; EvgHost.rgr — the viewport every native host puts around an EVG app.
+; ==============================================================================
+;
+; PLAN_WEB_LOADING.md S8. A UIKit view, an Android View and a browser page all
+; do the same job around a Ranger app: hold the window's size and the part of
+; it the system covers, convert a window point to a page point, turn a touch
+; into a press that a drag can cancel, time a fling against the host's real
+; clock, carry the keyboard's text in and the display list out.
+;
+; That was written three times. This is it once, against `EvgApp` — the
+; conversation rather than any one application — so an app that extends
+; `EvgApp` gets iOS, Android and the browser by declaring a subclass, and a
+; rule fixed here is fixed on every platform at once.
+;
+; WHAT A SUBCLASS ADDS is only what is genuinely its own: how its app is
+; loaded, and anything it answers that no other app would be asked. It puts
+; its app in `app`, loads it, and calls `began` with the window.
+;
+; Units are the host's business and not this file's. iOS hands it points,
+; Android density-independent pixels, a browser CSS pixels, and each scales
+; its own canvas; what crosses is one coordinate system per platform and the
+; same arithmetic.
+;
+; Everything here is checked on Node — `check_rt_ios.rgr` and
+; `check_rt_android.rgr` drive it through RealTrainer's subclass, 42 and 40
+; assertions — so a Mac and an emulator are needed only for the Swift and the
+; Kotlin on top.
+
+Import "EvgApp.rgr"
+Import "EvgViewport.rgr"
+
+class EvgHost {
+
+    ; The application, as the conversation rather than as itself: a subclass
+    ; puts its own app here and this class never learns which one it is.
+    def app:EvgApp (new EvgApp)
+    def started:boolean false
+
+    ; The window, the safe area and where the page sits inside them — all of
+    ; it in `EvgViewport`, which the dashboard's host owns one of too. This
+    ; one is in mode 0: the page IS the window, so the scale is one, the pan
+    ; is zero and a pinch has nothing to do.
+    def vp:EvgViewport (new EvgViewport)
+
+    ; The last point a finger was seen at, in page pixels. A press is two
+    ; events -- down marks the control, up activates it -- and the demo's
+    ; `press` takes the id, so the id has to survive between them. A drag
+    ; that scrolls cancels the press, as it does under a finger in the
+    ; browser.
+    def lastPageX:double 0.0
+    def lastPageY:double 0.0
+    def pressedId:string ""
+    def dragged:double 0.0
+    ; The clock a pan is timed against. A pan callback carries no timestamp of
+    ; its own here, so `tick` advances this and a pan measures itself against
+    ; the frame it arrived in — several pans inside one frame share that
+    ; frame's time, which is what `EVGFling.track` is written to expect.
+    def nowMs:double 0.0
+    def lastPanMs:double 0.0
+    ; A finger that landed on the scrollbar's thumb drags the thumb, not the
+    ; page, until it lifts. `barY` follows it in page units.
+    def barDrag:boolean false
+    def barY:double 0.0
+
+    Constructor () {
+    }
+
+    ; --- lifecycle ------------------------------------------------------------
+
+    ; The window and the five texts the browser page embeds: the stylesheet,
+    ; the session's COMPACT, the two state machines and the reference seed.
+    ; An empty machine or seed is left unloaded rather than parsed, so a
+    ; bundle that lacks one still opens the page.
+
+
+    ; WHAT EVERY `start` DOES, whatever the app it started. A subclass loads
+    ; its own app — one takes a stylesheet and a seed, another takes a file —
+    ; and then calls this: the window is taken, the page is laid out for it,
+    ; and the host is open for business.
+    ; `coarse` is a finger rather than a mouse, as the host reports it: the
+    ; stylesheet's `(pointer: coarse)` block gives the targets their size. A
+    ; phone says true and means it; a browser asks a media query and may mean
+    ; either, which is why this is a parameter and not an assumption.
+    fn began:void (w:double h:double coarse:boolean) {
+        vp.resize(w h)
+        app.setPointerCoarse(coarse)
+        started = true
+        this.fitPage()
+    }
+
+    ; A rotation, Split View, Stage Manager, the keyboard. The page keeps every
+    ; bit of its state; only its size changes, and the layout answers for it.
+    fn resize:void (w:double h:double) {
+        vp.resize(w h)
+        this.fitPage()
+    }
+
+    fn setSafeArea:void (top:double bottom:double left:double right:double) {
+        vp.setSafeArea(top bottom left right)
+        this.fitPage()
+    }
+
+    ; --- the viewport ---------------------------------------------------------
+
+    fn usableWidth:double () {
+        return (vp.usableWidth())
+    }
+
+    fn usableHeight:double () {
+        return (vp.usableHeight())
+    }
+
+    ; The page is the usable window, exactly: no scale, no offset but the
+    ; safe area's. The demo lays itself out at that size.
+    fn fitPage:void () {
+        if (started == false) {
+            return
+        }
+        app.setPageSize((this.usableWidth()) (this.usableHeight()))
+    }
+
+    ; What the host translates the context by before it paints, and what it
+    ; scales by — one, always. The names are the dashboard port's, so the two
+    ; hosts read alike.
+    fn scale:double () {
+        return (vp.scale())
+    }
+
+    fn zoom:double () {
+        return (vp.zoom())
+    }
+
+    fn offsetX:double () {
+        return (vp.offsetX())
+    }
+
+    fn offsetY:double () {
+        return (vp.offsetY())
+    }
+
+    fn pageWidth:double () {
+        return (app.widthPx())
+    }
+
+    fn pageHeight:double () {
+        return (app.heightPx())
+    }
+
+    ; A window point to a page pixel, and whether it lands on the page at all.
+    fn toPageX:double (x:double) {
+        return (vp.toPageX(x))
+    }
+
+    fn toPageY:double (y:double) {
+        return (vp.toPageY(y))
+    }
+
+    fn onPage:boolean (x:double y:double) {
+        def px:double (this.toPageX(x))
+        def py:double (this.toPageY(y))
+        if ((px < 0.0) || (py < 0.0)) {
+            return false
+        }
+        if (px > (this.usableWidth())) {
+            return false
+        }
+        if (py > (this.usableHeight())) {
+            return false
+        }
+        return true
+    }
+
+    ; No zoom on a page that is already the window's size: a pinch changes
+    ; nothing and says so, and a double tap has nothing to reset.
+    ; A pinch and a double tap go to the viewport, which answers false in
+    ; mode 0 — a page that IS the window has nothing to zoom out of. A host
+    ; that later puts this class in mode 1 gets both for nothing.
+    fn pinch:boolean (factor:double focusX:double focusY:double) {
+        def moved:boolean (vp.pinch(factor focusX focusY))
+        if moved {
+            this.fitPage()
+            app.rebuild()
+        }
+        return moved
+    }
+
+    fn resetZoom:boolean () {
+        def moved:boolean (vp.resetZoom())
+        if moved {
+            this.fitPage()
+            app.rebuild()
+        }
+        return moved
+    }
+
+    ; A drag scrolls the document, as a finger does in the browser: the
+    ; content follows the finger. Past a few points of travel the press under
+    ; the finger is a drag and not a tap, and the mark comes off.
+    fn canPan:boolean () {
+        return started
+    }
+
+    ; The same drag, from a host that has its own timestamps.
+    ;
+    ; `panBy` measures how long a move took from `nowMs`, which `tick`
+    ; advances — a touch callback on a phone carries no timestamp, so the
+    ; frame it arrived in is the best clock there is. A browser's pointer
+    ; event carries one, and a host that has a real interval should not have
+    ; to throw it away and use the frame's instead.
+    fn panAt:boolean (dx:double dy:double dtMs:double) {
+        nowMs = (nowMs + dtMs)
+        return (this.panBy(dx dy))
+    }
+
+    fn panBy:boolean (dx:double dy:double) {
+        if (started == false) {
+            return false
+        }
+        dragged = (dragged + (dy * dy) + (dx * dx))
+        if ((dragged > 36.0) && ((strlen pressedId) > 0)) {
+            pressedId = ""
+            app.setPressed("")
+        }
+        ; HOW LONG the move took as well as how far, because that is what
+        ; decides where the lift throws the page. Without it a swipe on the
+        ; phone stopped the instant the finger left, which no other iOS
+        ; scroll does.
+        def dt:double (nowMs - lastPanMs)
+        lastPanMs = nowMs
+        if barDrag {
+            barY = (barY + dy)
+            return (app.scrollbarDrag(barY))
+        }
+        return (app.scrollDrag((0.0 - dy) dt))
+    }
+
+    ; --- the frame ------------------------------------------------------------
+
+    fn frame:EVGDisplayList () {
+        return (app.display())
+    }
+
+    ; The clock. `dtMs` is the REAL milliseconds since the last frame, which is
+    ; what makes a dropped frame shorten an animation rather than stretch it.
+    ; The host clamps a long gap; this answers whether anything moved.
+    fn tick:boolean (dtMs:double) {
+        if (started == false) {
+            return false
+        }
+        nowMs = (nowMs + dtMs)
+        ; `app.tick` carries the momentum forward as well as the clock — see
+        ; `RealTrainerDemo.scrollDrag` — so a glide needs nothing from the
+        ; host beyond the frames it is already asking for.
+        return (app.tick(dtMs))
+    }
+
+    ; --- input ----------------------------------------------------------------
+
+    fn hitAt:string (x:double y:double) {
+        if ((this.onPage(x y)) == false) {
+            return ""
+        }
+        return (app.hitId((this.toPageX(x)) (this.toPageY(y))))
+    }
+
+    ; A finger lands: mark whatever is under it as pressed, and remember the id
+    ; so the release can activate the same control even if the finger moved a
+    ; little first.
+    fn pressAt:boolean (x:double y:double) {
+        lastPageX = (this.toPageX(x))
+        lastPageY = (this.toPageY(y))
+        dragged = 0.0
+        ; A finger down catches the page where it is, the way it does
+        ; everywhere else on the phone.
+        app.scrollHalt()
+        lastPanMs = nowMs
+        if (app.scrollbarGrab(lastPageX lastPageY)) {
+            barDrag = true
+            barY = lastPageY
+            pressedId = ""
+            return true
+        }
+        def id:string (this.hitAt(x y))
+        pressedId = id
+        app.setPressed(id)
+        return ((strlen id) > 0)
+    }
+
+    ; The finger lifts. The control under it is activated -- the demo decides
+    ; what that means -- and the pressed mark comes off either way. A field
+    ; takes the focus, so the host knows to raise the keyboard.
+    fn releasePress:boolean () {
+        if barDrag {
+            barDrag = false
+            app.scrollbarRelease()
+            return true
+        }
+        ; The finger left. If it was moving, the page carries on — the app
+        ; decides from the speed it tracked whether that was a throw or a
+        ; stop, and `tick` does the rest.
+        def threw:boolean (app.scrollRelease())
+        def id:string pressedId
+        pressedId = ""
+        app.setPressed("")
+        if threw {
+            return true
+        }
+        if ((strlen id) == 0) {
+            return true
+        }
+        if (app.hasField(id)) {
+            if ((app.focusedField()) != id) {
+                app.setFocus(id)
+                app.rebuild()
+            }
+            return true
+        }
+        if ((strlen (app.focusedField())) > 0) {
+            app.setFocus("")
+            app.rebuild()
+        }
+        return (app.press(id))
+    }
+
+    fn cancelPress:boolean () {
+        if barDrag {
+            barDrag = false
+            app.scrollbarRelease()
+            return true
+        }
+        def threw:boolean (app.scrollRelease())
+        if ((strlen pressedId) == 0) {
+            return threw
+        }
+        pressedId = ""
+        app.setPressed("")
+        return true
+    }
+
+    ; A pointer that is not pressing: a trackpad on an iPad, or the Simulator's
+    ; mouse. Answers whether the hover actually changed, so a host does not
+    ; repaint on every move.
+    fn hoverAt:boolean (x:double y:double) {
+        def barChanged:boolean (app.scrollbarHover((this.toPageX(x)) (this.toPageY(y))))
+        if (app.overScrollbar()) {
+            if ((strlen (app.hoveredId())) > 0) {
+                app.setHover("")
+                return true
+            }
+            return barChanged
+        }
+        def id:string (this.hitAt(x y))
+        if (id == (app.hoveredId())) {
+            return barChanged
+        }
+        app.setHover(id)
+        return true
+    }
+
+    fn clearHover:boolean () {
+        if ((strlen (app.hoveredId())) == 0) {
+            return false
+        }
+        app.setHover("")
+        return true
+    }
+
+    ; --- the keyboard ---------------------------------------------------------
+
+    ; The field that has the focus, or nothing — the host raises the keyboard
+    ; while there is one and lowers it when there is none.
+    fn focusedField:string () {
+        return (app.focusedField())
+    }
+
+    ; What the keyboard typed, into the focused field.
+    fn typeText:boolean (text:string) {
+        if ((strlen (app.focusedField())) == 0) {
+            return false
+        }
+        return (app.typeText(text))
+    }
+
+    ; A named key — "Backspace", "Enter", "ArrowLeft"... — as the browser
+    ; names them.
+    fn key:boolean (name:string shift:boolean ctrl:boolean) {
+        return (app.keyWith(name shift ctrl))
+    }
+
+    ; The focused field's text, for a host that mirrors it into a native
+    ; field of its own.
+    fn fieldStateJson:string () {
+        def tid:string (app.focusedField())
+        if ((strlen tid) == 0) {
+            return "{}"
+        }
+        return (app.fieldStateJson(tid))
+    }
+
+    fn blur:boolean () {
+        if ((strlen (app.focusedField())) == 0) {
+            return false
+        }
+        app.setFocus("")
+        app.rebuild()
+        return true
+    }
+
+    ; --- what the app is doing ------------------------------------------------
+
+    fn sceneName:string () {
+        return (app.sceneName())
+    }
+
+    ; A route, as the browser's `?route=` opens one: `/calendar/cal-train`,
+    ; `/new-calendar`, `/summary/yearsheet`.
+    fn openRoute:boolean (route:string) {
+        return (app.openRoute(route))
+    }
+
+    fn styleErrorCount:int () {
+        return (app.styleErrorCount())
+    }
+
+    fn styleErrorAt:string (i:int) {
+        return (app.styleErrorAt(i))
+    }
+
+    ; --- the names the Android host learned first --------------------------
+    ;
+    ; The Kotlin side asks for `panX` and `panY` where the Swift side asks for
+    ; `offsetX` and `offsetY`. They are the same number — where in the window
+    ; the page's top left corner sits — and the two ports simply named it
+    ; twice. Both names answer here rather than either host being edited to
+    ; suit the merge.
+    fn panX:double () {
+        return (this.offsetX())
+    }
+
+    fn panY:double () {
+        return (this.offsetY())
+    }
+
+    ; No `main` here, deliberately. This facade is a LIBRARY: an app's entry
+    ; point is the hand-written host — `ios/main.swift` calling
+    ; `UIApplicationMain`, an Android `Activity` — and a static method named
+    ; `main`, with or without a call at the bottom, would make the compiler
+    ; emit a program that runs on load, which is not what a library is.
+}

package/dist/lib/evg/EvgTest.rgr

@@ -0,0 +1,91 @@
+; SPDX-License-Identifier: MIT
+
+; ==============================================================================
+; EvgTest — the small assertion harness the EVG suites under lib/ use.
+; ==============================================================================
+; The same shape as the gallery's RgTest: each check prints "  PASS <name>" /
+; "  FAIL <name>", and summary() prints a grep-able "ALL PASS" (or
+; "SOME FAILED") plus a "passed=X failed=Y" line. It lives here so that
+; nothing under lib/evg imports gallery/ — lib is MIT and the gallery is not.
+; ==============================================================================
+
+class EvgTest {
+    def passed:int 0
+    def failed:int 0
+    def suite:string ""
+
+    sfn forSuite:EvgTest (name:string) {
+        def t:EvgTest (new EvgTest)
+        t.suite = name
+        print ("### " + name)
+        return t
+    }
+
+    fn ok:void (name:string cond:boolean) {
+        if cond {
+            this.passed = (this.passed + 1)
+            print ("  PASS " + name)
+        } {
+            this.failed = (this.failed + 1)
+            print ("  FAIL " + name)
+        }
+    }
+
+    fn no:void (name:string cond:boolean) {
+        this.ok(name (cond == false))
+    }
+
+    fn eqInt:void (name:string got:int want:int) {
+        if (got == want) {
+            this.passed = (this.passed + 1)
+            print ("  PASS " + name)
+        } {
+            this.failed = (this.failed + 1)
+            print ("  FAIL " + name + " got=" + (to_string got) + " want=" + (to_string want))
+        }
+    }
+
+    fn eqStr:void (name:string got:string want:string) {
+        if (got == want) {
+            this.passed = (this.passed + 1)
+            print ("  PASS " + name)
+        } {
+            this.failed = (this.failed + 1)
+            print ("  FAIL " + name + " got=" + got + " want=" + want)
+        }
+    }
+
+    fn eqBool:void (name:string got:boolean want:boolean) {
+        if (got == want) {
+            this.passed = (this.passed + 1)
+            print ("  PASS " + name)
+        } {
+            this.failed = (this.failed + 1)
+            print ("  FAIL " + name)
+        }
+    }
+
+    fn near:void (name:string got:double want:double) {
+        def d:double (got - want)
+        if (d < 0.0) {
+            d = (0.0 - d)
+        }
+        if (d < 0.000001) {
+            this.passed = (this.passed + 1)
+            print ("  PASS " + name)
+        } {
+            this.failed = (this.failed + 1)
+            print ("  FAIL " + name + " got=" + (to_string got) + " want=" + (to_string want))
+        }
+    }
+
+    fn summary:void () {
+        print "== summary =="
+        print ("passed=" + (to_string this.passed) + " failed=" + (to_string this.failed))
+        if (this.failed == 0) {
+            print "ALL PASS"
+        } {
+            print "SOME FAILED"
+        }
+    }
+}