ranger-compiler 3.5.1 → 3.5.2

package/dist/lib/evg/EVGFocus.rgr

@@ -0,0 +1,400 @@
+; SPDX-License-Identifier: MIT
+
+; =============================================================================
+; EVGFocus — the keyboard, for a renderer that has none
+; =============================================================================
+; A drawn UI has no tab stops. The browser gives them to a page of elements for
+; free; a canvas is one element, and everything inside it is a rectangle the
+; GPU painted. So every EVG app so far has either had no keyboard at all or
+; hand-written one for the single widget that needed it — which is why the
+; arrows do nothing on a screen full of buttons.
+;
+; This is that, once, for every renderer: the elements that say they are
+; focusable, in an order, with a rule for what an arrow key means.
+;
+;   Tab / Shift+Tab     the next and previous in TREE ORDER, wrapping. That is
+;                       the order the page was written in, which is the order
+;                       the a11y mirror publishes and the order a browser
+;                       would use.
+;
+;   the four arrows     SPATIAL. Tree order is wrong for a grid: the thing
+;                       under a button is not the thing after it. So an arrow
+;                       looks at the boxes — where the focus is now, and which
+;                       focusable box lies in that direction — and takes the
+;                       nearest one, measured along the direction moved and
+;                       penalised for drifting sideways.
+;
+;   Home / End          the first and the last.
+;
+; AND A MODAL TRAPS IT. A dialog that has to be closed must not be a dialog
+; the keyboard can walk out of — Tab past its last button and the ring is on
+; the page behind it, over controls the person cannot see the point of and
+; cannot get back from except by walking all the way round.
+;
+; The trap is not something a host remembers to switch on. It is already in
+; the tree: a dialog says `a11yModal`, which is `aria-modal` and what the
+; accessibility mirror reads to hide the page behind it, so the keyboard reads
+; the same declaration. While one is up, the walk starts at that dialog and
+; the page under it does not exist as far as the keys are concerned — and when
+; it closes, the tree stops saying so and the whole page comes back.
+;
+; The INNERMOST one, which here means the last in tree order: overlays are
+; appended, so a review sheet opened over an add sheet is the one after it,
+; and it is the one that traps.
+;
+; A focusable element is one that says `a11yFocusable` and is not
+; `a11yDisabled` or `a11yHidden`, and has a box with area. A control with no
+; id cannot be focused, because an id is what the host presses.
+;
+; NOTHING HERE DRAWS. `EVGDisplayList.setFocus` puts a ring around whatever id
+; this settles on, so a renderer gets the ring for the same reason it gets a
+; border: it is in the list.
+;
+; The spatial rule, stated once because it is the whole design:
+;
+;     A candidate counts only if its CENTRE is past the current box's edge in
+;     the direction moved. Its cost is the distance along that direction plus
+;     twice the overlap-free gap across it. So a button directly below wins
+;     over one further down, and one directly below wins over one beside it —
+;     which is what "down" means to a person looking at the screen.
+; =============================================================================
+
+Import "EVGElement.rgr"
+
+class EVGFocus {
+    ; The focusable ids, in tree order, and their boxes.
+    def ids:[string]
+    def xs:[double]
+    def ys:[double]
+    def ws:[double]
+    def hs:[double]
+    ; What has the focus, or "" for nothing.
+    def focusId@(mutable):string ""
+    ; WHETHER TO DRAW IT. The focus moves on a click as well as on a key —
+    ; otherwise Tab after a click carries on from somewhere else on the screen
+    ; — but a ring round every button somebody points at is not what a focus
+    ; ring is for. The rule is the browsers': shown when a key put it there,
+    ; not when the pointer did. `ringId` is what a renderer asks.
+    def ringVisible@(mutable):boolean false
+    ; The dialog the walk is confined to, when the tree declares one.
+    def trapEl@(mutable+optional):EVGElement
+    def trapped@(mutable):boolean false
+
+    Constructor () {
+    }
+
+    ; --- what can be focused ---------------------------------------------------
+
+    fn scan:void (root:EVGElement) {
+        clear ids
+        clear xs
+        clear ys
+        clear ws
+        clear hs
+        trapped = false
+        def none@(optional):EVGElement
+        trapEl = none
+        this.findModal(root)
+        if trapped {
+            this.walk((unwrap trapEl))
+            return
+        }
+        this.walk(root)
+    }
+
+    ; The last modal in tree order that is on the screen — see the note at the
+    ; top. Pre-order and overwriting, so a dialog nested inside another wins
+    ; over the one holding it, and a later sibling wins over an earlier one.
+    fn findModal:void (el:EVGElement) {
+        if el.a11yHidden {
+            return
+        }
+        if (el.display == "none") {
+            return
+        }
+        if el.a11yModal {
+            trapEl = el
+            trapped = true
+        }
+        def i:int 0
+        def n:int (el.getChildCount())
+        while (i < n) {
+            this.findModal((el.getChild(i)))
+            i = (i + 1)
+        }
+    }
+
+    ; The id of the dialog the keys are trapped in, or "" when they are not.
+    ; A dialog with no id still traps — the walk is confined to the element,
+    ; not to its name — so this answers "" for one, which is why a caller that
+    ; wants to know IF there is a trap asks `isTrapped`.
+    fn trapId:string () {
+        if (trapped == false) {
+            return ""
+        }
+        def el:EVGElement (unwrap trapEl)
+        return el.id
+    }
+
+    fn isTrapped:boolean () {
+        return trapped
+    }
+
+    fn walk:void (el:EVGElement) {
+        if el.a11yHidden {
+            return
+        }
+        if (el.display == "none") {
+            return
+        }
+        if (EVGFocus.takes(el)) {
+            push ids el.id
+            push xs el.calculatedX
+            push ys el.calculatedY
+            push ws el.calculatedWidth
+            push hs el.calculatedHeight
+        }
+        def i:int 0
+        def n:int (el.getChildCount())
+        while (i < n) {
+            this.walk((el.getChild(i)))
+            i = (i + 1)
+        }
+    }
+
+    ; An element with no id cannot be focused: the host acts on ids, and a
+    ; focus nobody can press is a focus that goes nowhere.
+    sfn takes:boolean (el:EVGElement) {
+        if (el.a11yFocusable == false) {
+            return false
+        }
+        if el.a11yDisabled {
+            return false
+        }
+        if ((strlen el.id) == 0) {
+            return false
+        }
+        if (el.calculatedWidth <= 0.0) {
+            return false
+        }
+        return (el.calculatedHeight > 0.0)
+    }
+
+    fn count:int () {
+        return (array_length ids)
+    }
+
+    fn idAt:string (i:int) {
+        if (i < 0) {
+            return ""
+        }
+        if (i >= (array_length ids)) {
+            return ""
+        }
+        return (itemAt ids i)
+    }
+
+    fn indexOfId:int (id:string) {
+        def i:int 0
+        def n:int (array_length ids)
+        while (i < n) {
+            if ((itemAt ids i) == id) {
+                return i
+            }
+            i = (i + 1)
+        }
+        return (0 - 1)
+    }
+
+    ; --- moving ----------------------------------------------------------------
+
+    ; Tree order, wrapping. With nothing focused, Tab starts at the first and
+    ; Shift+Tab at the last — the same as a browser entering a page from
+    ; either end.
+    fn step:string (back:boolean) {
+        def n:int (array_length ids)
+        if (n == 0) {
+            return ""
+        }
+        def at:int (this.indexOfId(focusId))
+        if (at < 0) {
+            if back {
+                return (this.idAt((n - 1)))
+            }
+            return (this.idAt(0))
+        }
+        def next@(mutable):int (at + 1)
+        if back {
+            next = (at - 1)
+        }
+        if (next >= n) {
+            next = 0
+        }
+        if (next < 0) {
+            next = (n - 1)
+        }
+        return (this.idAt(next))
+    }
+
+    ; The spatial rule stated at the top. `dx`/`dy` is the direction: one of
+    ; (0,-1) (0,1) (-1,0) (1,0).
+    fn towards:string (dx:double dy:double) {
+        def n:int (array_length ids)
+        if (n == 0) {
+            return ""
+        }
+        def at:int (this.indexOfId(focusId))
+        if (at < 0) {
+            ; Nowhere yet: an arrow enters at the first, like Tab.
+            return (this.idAt(0))
+        }
+        def cx:double ((itemAt xs at) + ((itemAt ws at) / 2.0))
+        def cy:double ((itemAt ys at) + ((itemAt hs at) / 2.0))
+        def best@(mutable):string ""
+        def bestCost@(mutable):double 0.0
+        def i:int 0
+        while (i < n) {
+            if (i != at) {
+                def ox:double ((itemAt xs i) + ((itemAt ws i) / 2.0))
+                def oy:double ((itemAt ys i) + ((itemAt hs i) / 2.0))
+                def along:double (((ox - cx) * dx) + ((oy - cy) * dy))
+                ; Strictly past the centre in the direction moved. Half a
+                ; pixel, so a row of buttons whose centres are one rounding
+                ; apart does not count as "below" itself.
+                if (along > 0.5) {
+                    ; Across is the other axis, which for (0,±1) is x and for
+                    ; (±1,0) is y.
+                    def across@(mutable):double ((ox - cx) * dy)
+                    if (dy == 0.0) {
+                        across = (oy - cy)
+                    } {
+                        across = (ox - cx)
+                    }
+                    if (across < 0.0) {
+                        across = (0.0 - across)
+                    }
+                    def cost:double (along + (across * 2.0))
+                    if ((strlen best) == 0) {
+                        best = (itemAt ids i)
+                        bestCost = cost
+                    } {
+                        if (cost < bestCost) {
+                            best = (itemAt ids i)
+                            bestCost = cost
+                        }
+                    }
+                }
+            }
+            i = (i + 1)
+        }
+        return best
+    }
+
+    ; --- the key ---------------------------------------------------------------
+
+    ; One key against a tree. Answers the id the focus moved to, or "" when
+    ; the key is not one of these or there is nowhere to go — a host that gets
+    ; "" must let the key through, because refusing a key you did nothing with
+    ; is how a page stops scrolling.
+    ;
+    ; `scan` runs here so a caller never has to remember to: the tree it is
+    ; given is the tree as it is now, and a focus that survived a rebuild is
+    ; found by id rather than by position.
+    fn key:string (root:EVGElement k:string shift:boolean) {
+        this.scan(root)
+        def to@(mutable):string ""
+        if (k == "Tab") {
+            to = (this.step(shift))
+        }
+        if (k == "ArrowDown") {
+            to = (this.towards(0.0 1.0))
+        }
+        if (k == "ArrowUp") {
+            to = (this.towards(0.0 (0.0 - 1.0)))
+        }
+        if (k == "ArrowRight") {
+            to = (this.towards(1.0 0.0))
+        }
+        if (k == "ArrowLeft") {
+            to = (this.towards((0.0 - 1.0) 0.0))
+        }
+        if (k == "Home") {
+            to = (this.idAt(0))
+        }
+        if (k == "End") {
+            to = (this.idAt(((array_length ids) - 1)))
+        }
+        if ((strlen to) == 0) {
+            return ""
+        }
+        focusId = to
+        ringVisible = true
+        return to
+    }
+
+    ; Put the focus somewhere by hand — a press, or a screen that opens with
+    ; something already chosen. An id nothing focusable carries is refused
+    ; rather than remembered, so the ring cannot point at nothing.
+    fn place:boolean (root:EVGElement id:string) {
+        if ((strlen id) == 0) {
+            focusId = ""
+            ringVisible = false
+            return true
+        }
+        this.scan(root)
+        if ((this.indexOfId(id)) < 0) {
+            return false
+        }
+        focusId = id
+        ringVisible = true
+        return true
+    }
+
+    ; The same, from a POINTER: the focus moves so the keys carry on from what
+    ; was just clicked, and nothing is drawn, because the person can see where
+    ; they clicked.
+    fn pointAt:boolean (root:EVGElement id:string) {
+        if ((this.place(root id)) == false) {
+            return false
+        }
+        ringVisible = false
+        return true
+    }
+
+    ; SHOW IT AGAIN. A press is the pointer's by default — `pointAt` puts the
+    ; ring away — and a press the KEYBOARD made is not: Enter on a focused
+    ; button activates it and leaves the ring where it was, in every browser
+    ; there is. The caller that knows a key did it says so with this.
+    fn show:void () {
+        if ((strlen focusId) > 0) {
+            ringVisible = true
+        }
+    }
+
+    ; Where to draw the ring, or "" for nowhere.
+    fn ringId:string () {
+        if (ringVisible == false) {
+            return ""
+        }
+        return focusId
+    }
+
+    fn clear:void () {
+        focusId = ""
+        ringVisible = false
+    }
+
+    ; The focus after a rebuild: it is kept if the id is still focusable, and
+    ; dropped if it is not — a ring around an element that has gone is worse
+    ; than no ring.
+    fn settle:void (root:EVGElement) {
+        if ((strlen focusId) == 0) {
+            return
+        }
+        this.scan(root)
+        if ((this.indexOfId(focusId)) < 0) {
+            focusId = ""
+            ringVisible = false
+        }
+    }
+}