Code clarity

[ToddG]

WHAT
I'm not yet a gleam expert. But even with decades of software experience, I'm having trouble following the code in internal.gleam... here are some functions in particular:

QUESTIONS

1. How does this work? Why do you pass in a pos?

shore/src/shore/internal.gleam

Line 478 in 3accb64

fn do_list_focusable(

fn do_list_focusable(
  pos: Pos,
  children: List(Node(msg)),
  acc: List(Focused(msg)),
) -> List(Focused(msg)) {

2. This method is too long for me to decipher what it does

https://github.com/bgwdotdev/shore/blob/3accb647c98ebca04d7472ffa7abc6a377887224/src/shore/internal.gleam#L230C1-L233C49

fn shore_loop(
  state: State(model, msg),
  event: Event(msg),
) -> actor.Next(State(model, msg), Event(msg)) {

[bgwdotdev]

How does this work?

Generally, it just walks through the tree of nodes to create a flat list of all nodes that can be focused

Why do you pass in a pos?

This is used as part of calculating the cursor position of focused input field.

Currently, because the size of an input box can be a responsive value such as a Percentage (say 50%), we have to pass in absolute width of the containing element (the whole screen, or a Box). say that box is 10 characters wide, and we're 50% of it, so the input box itself is 5 characters wide.

We need this to figure out where the cursor can be during focus, (you may have an input string of 20 characters long, but the field itself can only display 5 of those at a time) if that makes sense?

This method is too long for me to decipher what it does

Yeah, don't worry, At this point I'm struggling to follow my own code here, this loop expanded a lot since I originally wrote it, it's in desperate need of a refactor ^^; The code complexity rating on it is waay too high haha. It should likely be broken out into a few different functions to separately handle things like focus, key inputs, events and such.

Definitely on my list to refactor

[bgwdotdev]

For more detail on the shore_loop bit:

first, i suggest ignoring the KeyInput event and reading the rest, I believe these are all pretty simple hopefully (cmd, redraw, resize and exit)

Once we get to the KeyPress event, is where a lot starts happening.

first we load the UI, as we'll need to walk it to check events and focus and such.

focus

then we check the current focus state, to decide how to deal with inputs

no focus

if we DONT have a node focused, we check if we've pressed a key focus shortcut (like pressing S in the dev example takes you to the Search field) and if so, we focus that field

then we check if you've pressed a keybind for an event, such as pressing I or D to increment/decrement the counter in the example. we run update to execute that message if so.

existing focus

if we DO have a node focused, instead we need to take a different set of actions depending on the key pressed

first we reload the focus, this is incase the last event changed the ui, as it may have removed the node we were focusing from from the screen, such as pressing enter to complete a login form or something.

if the item of focus is still present, we can then proceed to handle the event based on the focus type

is input

if it's an input, then this means handling input events, so first we check if you've pressed the enter key to submit the field

else we pass the key pressed through to the event, which typically means passing the letter you pressed through to the ui.input's event: fn(String) -> msg handler.

is button

if it's a button

we can check if the submit key bind was pressed and if so, trigger it's event, else just continue on

framework keybinds

after checking the above focus related stages, we can then check if one of the framework keybinds was pressed

in these scenarios, we typically need move the focus, either moving it forward (press tab) or backwards (shift tab), or clearing it entirely (escape)

redraw

finally we just redraw

[bgwdotdev]

Hopefully, this might clarify things some what. If you have any questions or anything, don' hesitate to let me know :)

[ToddG]

Thank you for the clarification. That helps. I'm not a UX dev, I'm a BE dev, so take my opinion with a grain of salt... but I would implement this differently, like so:

Instead of a bunch of hard coded checking of state to see what do to, I'd create a focus stack and bubble the events from the leaf to the root:

Example:
0. app consists of two panes, a button and a textbox

┌──application───────────────────────────────────────────────────────────────────┐
│                                                                                │
│                                                                                │
│                                                                                │
│     ┌──pane1────────────────────────┐    ┌────pane2───────────────────────┐    │
│     │                               │    │                                │    │
│     │                               │    │                                │    │
│     │    ┌─textbox───────────┐      │    │                                │    │
│     │    │                   │      │    │                                │    │
│     │    │                   │      │    │                                │    │
│     │    └───────────────────┘      │    │                                │    │
│     │    ┌─button────────────┐      │    │                                │    │
│     │    │                   │      │    │                                │    │
│     │    │                   │      │    │                                │    │
│     │    │                   │      │    │                                │    │
│     │    │                   │      │    │                                │    │
│     │    │                   │      │    │                                │    │
│     │    │                   │      │    │                                │    │
│     │    │                   │      │    │                                │    │
│     │    │                   │      │    │                                │    │
│     │    └───────────────────┘      │    │                                │    │
│     │                               │    │                                │    │
│     │                               │    │                                │    │
│     └───────────────────────────────┘    └────────────────────────────────┘    │
│                                                                                │
└────────────────────────────────────────────────────────────────────────────────┘

1. user starts app, loads the root key_bindings which contains CTRL-X -> exit(), TAB->focus_next(), SHIFT-TAB->focus_prev(), etc.

focus_stack = [
#(root, root_keybindings) //  --> head of list has focus
] 

2. user presses tab and focus enters pane1, so the pane1 keybindings are placed on top of the stack

focus_stack = [
#(pane1, pane1_keybindings)   //  --> head of list has focus
#(root, root_keybindings),
]

3. user presses tab and focus enters the textbox

focus_stack = [
#(textbox, textbox_keybindings)   //  --> head of list has focus
#(pane1, pane1_keybindings)  
#(root, root_keybindings),
]

Now when a user types a keystroke, the textbox_keybindings will capture any of the standard ascii input and fill in the text. But if input is not recognized and captured, then it bubbles out of the textbox and back up (or down, however you think of it) the stack until it is recognized and captured.

4. user presses TAB and exits the textbox. the TAB isn't caught by the textbox, and is eventually caught by the root, which then navigates focus to the next item, the BUTTON. The textbox is popped off the focus stack and the button is pushed on:

focus_stack = [
#(button, button_keybindings)   //  --> head of list has focus
#(pane1, pane1_keybindings)  
#(root, root_keybindings),
]

I think this is how a lot of UI libraries work.

[ToddG]

Also, fwiw, the current textbox can get into a bad state and there's no way to exit out of it. Happened to me at least once. Had to terminate the app to get out.

[bgwdotdev]

Hey :) thanks for the comments!

I'd create a focus stack and bubble the events from the leaf to the root

I'm generally familiar with event bubbling from other things so yeah, understand the concept there as you've explained it :)

While I'm not against it, I'm hesitant about the approach as maintaining a "stack" which we push and pop onto feels a little stateful and imperative compared to the current approach of executing the event in the currently focused item, or walking the ui for the first matching event.

I'd be curious to what you envision this change would bring/enable?

Instead of a bunch of hard coded checking of state to see what do to

I'd be curious further to your thoughts with maybe a small excerpt/example, I think generally we only care about one bit of state, which is if we've got an existing focused item or not, and then we essentially execute some (very messy) rules -- but it may be i'm just looking at it wrong, so keen to hear your perspective in a little more detail ^^!

Also, fwiw, the current textbox can get into a bad state and there's no way to exit out of it. Happened to me at least once. Had to terminate the app to get out.

Oh really? I've not experienced this so far, but definitely possible I've missed something! -- one thing I would double check is you didn't accidentally press ctrl+s, which will "lock up" the terminal?

--

super keen to hear your thoughts :) love your enthusiasm and interest!

[ToddG]

Cool, I'll see if I can cobble up some code later this week to show what I'm thinking.