ranger-compiler 3.5.0 → 3.5.2

package/dist/lib/evg/EVGHitTest.rgr

@@ -0,0 +1,208 @@
+; SPDX-License-Identifier: MIT
+
+; ==============================================================================
+; EVGHitTest — what is under the pointer, in the order things are painted
+; ==============================================================================
+;
+; A hit test that walks the tree answers with whatever the tree reaches first.
+; That is the wrong answer the moment anything floats: a menu panel is drawn
+; over the trigger beside it, and a click inside the panel has to reach the
+; panel, not the trigger it happens to cover.
+;
+; So this does not walk the tree. It builds the SAME order the display list
+; paints in — the normal tree, then the overlay surfaces in the order they were
+; reached — and scans it backwards. Topmost wins because topmost is literally
+; last, and there is one rule instead of two that can drift apart.
+;
+; Note what this is NOT. It answers "which element is under this point", i.e.
+; the paint question. Where the resulting event then GOES is the tree's
+; business: a click on a menu row is handled by the menu that owns the row, and
+; ownership never moved, because an overlay surface never left the tree.
+; ==============================================================================
+
+Import "EVGElement.rgr"
+
+class EVGHitTest {
+    ; The paint order of the last call. A field rather than a return value
+    ; threaded through the recursion: the walk defers surfaces as it meets them
+    ; and comes back to them afterwards, which is exactly what `deferred` is.
+    def order:[EVGElement]
+    def deferred:[EVGElement]
+
+    Constructor () {
+    }
+
+    ; Depth-first, minus the surfaces: those are put aside and painted after
+    ; the whole normal tree.
+    fn collect:void (el:EVGElement) {
+        ; `display: none` cannot be hit, nor anything under it.
+        if (el.isHidden()) {
+            return
+        }
+        el.settleShift()
+        push order el
+        def i:int 0
+        while (i < (array_length el.children)) {
+            def kid:EVGElement (itemAt el.children i)
+            if kid.isOverlay {
+                push deferred kid
+            } {
+                this.collect(kid)
+            }
+            i = (i + 1)
+        }
+    }
+
+    ; Back to front. A surface reached INSIDE a surface is appended while this
+    ; loop is running, so a submenu lands after the menu that opened it — the
+    ; stack falls out of the walk and nothing carries a z-index.
+    fn paintOrder:[EVGElement] (root:EVGElement) {
+        clear order
+        clear deferred
+        this.collect(root)
+        def i:int 0
+        while (i < (array_length deferred)) {
+            this.collect((itemAt deferred i))
+            i = (i + 1)
+        }
+        return order
+    }
+
+    sfn containsPoint:boolean (el:EVGElement px:double py:double) {
+        if (px < el.calculatedX) {
+            return false
+        }
+        if (py < el.calculatedY) {
+            return false
+        }
+        if (px > (el.calculatedX + el.calculatedWidth)) {
+            return false
+        }
+        if (py > (el.calculatedY + el.calculatedHeight)) {
+            return false
+        }
+        return true
+    }
+
+    ; The same walk, minus what the point cannot see.
+    ;
+    ; A clipping box the point is OUTSIDE takes its whole subtree with it. That
+    ; is not an optimisation: without it, a row scrolled out of a viewport is
+    ; still sitting under the pointer at its unclipped position — invisible and
+    ; clickable at once, which is the worst of the two. The paint order and the
+    ; hit order have to agree about what is on the screen, and the display list
+    ; stops drawing at exactly this boundary.
+    ;
+    ; The point is needed to do it, which is why this is a second walk rather
+    ; than a rule inside `collect`: `paintOrder` answers "what is drawn, in
+    ; order" and has no point to test against.
+    fn collectAt:void (el:EVGElement px:double py:double) {
+        if (el.clipsContent()) {
+            if ((EVGHitTest.containsPoint(el px py)) == false) {
+                return
+            }
+        }
+        ; Nor can the point be in a subtree whose paint bounds — the union
+        ; of every box beneath it, written by the layout and moved with it —
+        ; do not hold it. This is the same test the display list culls with,
+        ; and it is what keeps a pointer move over a long document from
+        ; visiting every element in it: the rows are tested at their roots
+        ; and the ones the point is not over are never entered. A subtree
+        ; drawn somewhere its boxes do not say is never pruned.
+        if ((el.paintUnbounded == false) && ((el.isHidden()) == false)) {
+            if (px < el.paintLeft) { return }
+            if (py < el.paintTop) { return }
+            if (px > el.paintRight) { return }
+            if (py > el.paintBottom) { return }
+        }
+        el.settleShift()
+        push order el
+        def i:int 0
+        while (i < (array_length el.children)) {
+            def kid:EVGElement (itemAt el.children i)
+            if kid.isOverlay {
+                push deferred kid
+            } {
+                this.collectAt(kid px py)
+            }
+            i = (i + 1)
+        }
+    }
+
+    ; A surface is deferred here exactly as it is in `paintOrder`, so an
+    ; overlay opened from inside a scroll box is still reachable after the box
+    ; has clipped everything else — which is the whole point of deferring it.
+    fn paintOrderAt:[EVGElement] (root:EVGElement px:double py:double) {
+        clear order
+        clear deferred
+        this.collectAt(root px py)
+        def i:int 0
+        while (i < (array_length deferred)) {
+            this.collectAt((itemAt deferred i) px py)
+            i = (i + 1)
+        }
+        return order
+    }
+
+    ; The id of the topmost element under the point that HAS one.
+    ;
+    ; Unnamed elements are passed over rather than answered with "": a label
+    ; inside a row is drawn last and would otherwise swallow every click on the
+    ; row that owns it. Giving a thing an id is how this file is told the thing
+    ; is a target — the same convention `UiHost` uses with test ids.
+    fn idAt:string (root:EVGElement px:double py:double) {
+        def list:[EVGElement] (this.paintOrderAt(root px py))
+        def i:int ((array_length list) - 1)
+        while (i >= 0) {
+            def el:EVGElement (itemAt list i)
+            if ((strlen el.id) > 0) {
+                if (EVGHitTest.containsPoint(el px py)) {
+                    return el.id
+                }
+            }
+            i = (i - 1)
+        }
+        return ""
+    }
+
+    ; What the pointer should look like here.
+    ;
+    ; The topmost element under the point, whatever its id — unlike `idAt` this
+    ; does NOT skip the unnamed ones, because a label inside a title bar is
+    ; exactly the thing the pointer is usually over and it has no id of its
+    ; own. It does not need one: `cursor` inherits, so by the time the layout
+    ; is done the label is carrying its bar's answer.
+    ;
+    ; Empty means nobody said, and the caller decides what that means.
+    fn cursorAt:string (root:EVGElement px:double py:double) {
+        def list:[EVGElement] (this.paintOrderAt(root px py))
+        def i:int ((array_length list) - 1)
+        while (i >= 0) {
+            def el:EVGElement (itemAt list i)
+            if ((strlen el.cursor) > 0) {
+                if (EVGHitTest.containsPoint(el px py)) {
+                    return el.cursor
+                }
+            }
+            i = (i - 1)
+        }
+        return ""
+    }
+
+    ; Same scan, for a caller that wants the class list — a hover highlight asks
+    ; "is this a row?" and does not care which row.
+    fn classAt:string (root:EVGElement px:double py:double) {
+        def list:[EVGElement] (this.paintOrderAt(root px py))
+        def i:int ((array_length list) - 1)
+        while (i >= 0) {
+            def el:EVGElement (itemAt list i)
+            if ((strlen el.id) > 0) {
+                if (EVGHitTest.containsPoint(el px py)) {
+                    return el.className
+                }
+            }
+            i = (i - 1)
+        }
+        return ""
+    }
+}

package/dist/lib/evg/EVGHoles.rgr

@@ -0,0 +1,294 @@
+; SPDX-License-Identifier: MIT
+
+; =============================================================================
+; EVGHoles / EVGDress — a `{key}` in a document, and what fills it in a design
+; =============================================================================
+;
+; A document that drives an app writes a control's state as a HOLE:
+;
+;   class-name="ui-switch ui-switch-state-{wifi}"
+;
+; At run time a machine fills it from its context, and the class becomes
+; `ui-switch-state-checked`, which is what the stylesheet paints. That is the
+; app runtime's job and it lives with the app runtime.
+;
+; At DESIGN time there is no machine, and until now the hole was left exactly
+; as written — so `ui-switch-state-{wifi}` matched no rule, the track got no
+; colour and the switch was invisible on the very screen somebody was drawing.
+; The workaround people found was to hand-write base paint into the document's
+; stylesheet so the unmatched state would not matter. That is a second copy of
+; every control's look, kept in step by hand, and it is what this file exists
+; to make unnecessary.
+;
+; The document already knows what each control is showing: `checked` is on the
+; node, and it is the same value `evg_app init` reads to write the machine's
+; opening context. So a design can fill its own holes from itself, and the
+; picture a designer sees is the picture the app boots with.
+;
+; It fills by ADDING, never by replacing:
+;
+;   ui-switch-track-state-{wifi}
+;   ui-switch-track-state-{wifi} ui-switch-track-state-checked
+;
+; The hole stays in the class list, which matters for three reasons. Nothing
+; downstream can mistake a dressed design for a bound app. `EVGMeasure` can
+; still tell a control that is bound from one whose state is a fixed word —
+; the `frozen` check reads exactly that. And the document on disk is never
+; touched: this dresses a tree in memory, on its way to a layout.
+;
+; The app runtime does NOT call this. A machine's value and the document's
+; value disagree the moment anything is pressed, and two state classes on one
+; element would then paint whichever the sheet happened to reach last.
+; =============================================================================
+
+Import "EVGElement.rgr"
+
+class EVGHoles {
+    ; --- THE TWO SHAPES OF A HOLE ---------------------------------------------
+    ;
+    ;   {wifi}              the key's value, whatever it is
+    ;   {cinematic=4k30}    "checked" when the key IS that value, else "unchecked"
+    ;
+    ; The second exists because one thing a screen does constantly has no
+    ; expression in the first: CHOOSING ONE OF SEVERAL. A list of six
+    ; resolutions with a tick against the chosen one is not six switches —
+    ; it is one value, asked six different questions. Encoded with plain
+    ; holes it becomes a key per row that something has to keep consistent,
+    ; and the thing that has to is a person, who will get it wrong.
+    ;
+    ; Asking the question in the hole keeps the fact in one place. The answer
+    ; is a STATE WORD rather than a boolean because that is the vocabulary
+    ; every control in this engine already paints with, so a tick needs two
+    ; rules in the sheet — `.check-state-checked`, `.check-state-unchecked` —
+    ; and those two serve every row of every group in the app.
+    ;
+    ; A key with a `=` in it is not addressable, which is the price and is
+    ; cheap: `=` is not in any key anybody writes.
+    sfn keyOf:string (name:string) {
+        def cut:int (indexOf name "=")
+        if (cut < 0) {
+            return name
+        }
+        return (substring name 0 cut)
+    }
+
+    ; "" when the hole asks for the value rather than testing it.
+    sfn wantOf:string (name:string) {
+        def cut:int (indexOf name "=")
+        if (cut < 0) {
+            return ""
+        }
+        return (substring name (cut + 1) (strlen name))
+    }
+
+    sfn asksEquals:boolean (name:string) {
+        return ((indexOf name "=") >= 0)
+    }
+
+    ; The `{name}` syntax, defined once. `EvgAppRules.fillText` fills the same
+    ; holes from a machine's context; it differs only in where the value comes
+    ; from, and it scans with this.
+    ;
+    ; A `{key=value}` reports `key`: the name a machine has to hold is the
+    ; key, and the value is the question being asked about it.
+    sfn scan:void (text:string out:[string]) {
+        def n:int (strlen text)
+        def i@(mutable):int 0
+        while (i < n) {
+            if ((charAt text i) == 123) {
+                def j@(mutable):int (i + 1)
+                def close@(mutable):int (0 - 1)
+                while (j < n) {
+                    if ((charAt text j) == 125) {
+                        if (close < 0) {
+                            close = j
+                        }
+                    }
+                    j = (j + 1)
+                }
+                if (close < 0) {
+                    i = n
+                } {
+                    def name:string (substring text (i + 1) close)
+                    def key:string (EVGHoles.keyOf(name))
+                    if ((strlen key) > 0) {
+                        if ((EVGHoles.mentions(out key)) == false) {
+                            push out key
+                        }
+                    }
+                    i = (close + 1)
+                }
+            } {
+                i = (i + 1)
+            }
+        }
+    }
+
+    ; Every hole in `text` replaced by one word. A design has a single answer
+    ; for a control — what it is showing — so it does not need a per-key
+    ; lookup, and an unclosed `{` is left alone rather than swallowing the
+    ; rest of the string.
+    sfn fillWith:string (text:string word:string) {
+        def out@(mutable):string ""
+        def i@(mutable):int 0
+        def n:int (strlen text)
+        while (i < n) {
+            def c:int (charAt text i)
+            if (c == 123) {
+                def close@(mutable):int (0 - 1)
+                def j@(mutable):int (i + 1)
+                while (j < n) {
+                    if ((charAt text j) == 125) {
+                        if (close < 0) {
+                            close = j
+                        }
+                    }
+                    j = (j + 1)
+                }
+                if (close < 0) {
+                    out = (out + (substring text i (i + 1)))
+                    i = (i + 1)
+                } {
+                    out = (out + word)
+                    i = (close + 1)
+                }
+            } {
+                out = (out + (substring text i (i + 1)))
+                i = (i + 1)
+            }
+        }
+        return out
+    }
+
+    sfn hasHole:boolean (text:string) {
+        return ((indexOf text "{") >= 0)
+    }
+
+    sfn mentions:boolean (list:[string] want:string) {
+        def i:int 0
+        while (i < (array_length list)) {
+            if ((itemAt list i) == want) {
+                return true
+            }
+            i = (i + 1)
+        }
+        return false
+    }
+}
+
+class EVGDress {
+    ; Fill a design's own state holes, in place, on a tree that is on its way
+    ; to a layout. Safe to call twice: a class that is already there is not
+    ; added again.
+    sfn dress:void (root:EVGElement) {
+        EVGDress.walk(root "")
+    }
+
+    ; The state word flows DOWN. A track and a thumb carry the same hole as the
+    ; switch above them and say nothing themselves about what they are showing,
+    ; because the control is the thing that has a state — so the nearest
+    ; ancestor with a role is what answers for them.
+    sfn walk:void (el:EVGElement word:string) {
+        def here:string word
+        if ((strlen el.role) > 0) {
+            def own:string (EVGDress.wordFor(el))
+            if ((strlen own) > 0) {
+                here = own
+            }
+        }
+        if ((strlen here) > 0) {
+            if ((strlen el.className) > 0) {
+                el.className = (EVGDress.dressed(el.className here))
+            }
+        }
+        def i:int 0
+        while (i < (array_length el.children)) {
+            EVGDress.walk((itemAt el.children i) here)
+            i = (i + 1)
+        }
+    }
+
+    ; What this control is showing, as the word a state class is spelled with.
+    ; A control that says nothing is showing `unchecked`: that is what a
+    ; machine written by `evg_app init` opens with, so it is what a design of
+    ; it should look like rather than a hole.
+    sfn wordFor:string (el:EVGElement) {
+        if (el.a11yChecked == 2) {
+            return "checked"
+        }
+        if (el.a11yChecked == 3) {
+            return "indeterminate"
+        }
+        if (el.a11yChecked == 1) {
+            return "unchecked"
+        }
+        if (EVGDress.isStateful(el.role)) {
+            return "unchecked"
+        }
+        return ""
+    }
+
+    sfn isStateful:boolean (role:string) {
+        if (role == "switch") {
+            return true
+        }
+        if (role == "checkbox") {
+            return true
+        }
+        if (role == "radio") {
+            return true
+        }
+        return false
+    }
+
+    ; Each holed class token gets a filled copy beside it. The hole itself
+    ; stays: see the header — this is the difference between a design that
+    ; paints and a design that has quietly become an app.
+    sfn dressed:string (className:string word:string) {
+        if ((EVGHoles.hasHole(className)) == false) {
+            return className
+        }
+        def out@(mutable):string className
+        def n:int (strlen className)
+        def at@(mutable):int 0
+        while (at < n) {
+            def rest:string (substring className at n)
+            def sp:int (indexOf rest " ")
+            def end@(mutable):int n
+            if (sp >= 0) {
+                end = (at + sp)
+            }
+            def tok:string (substring className at end)
+            if (EVGHoles.hasHole(tok)) {
+                def filled:string (EVGHoles.fillWith(tok word))
+                if (filled != tok) {
+                    if ((EVGDress.carries(out filled)) == false) {
+                        out = ((out + " ") + filled)
+                    }
+                }
+            }
+            at = (end + 1)
+        }
+        return out
+    }
+
+    ; Is `want` already one of the space-separated tokens of `className`?
+    ; `indexOf` would say yes to `ui-switch` inside `ui-switch-track`.
+    sfn carries:boolean (className:string want:string) {
+        def n:int (strlen className)
+        def at@(mutable):int 0
+        while (at < n) {
+            def rest:string (substring className at n)
+            def sp:int (indexOf rest " ")
+            def end@(mutable):int n
+            if (sp >= 0) {
+                end = (at + sp)
+            }
+            if ((substring className at end) == want) {
+                return true
+            }
+            at = (end + 1)
+        }
+        return false
+    }
+}