# Braindump

This is a combination of a thinking-out-loud document and a TODO list.
It is not a document of record. You should not expect to derive value
from reading it

tl;dr what if ... a web browser, but tabs were more like emacs buffers?

## objects/data types

buffer
  Buffer.find ;; by name, title, url
  Buffer.by_name (maybe?)

  buffer has-a webview but it is not shown by default. Later we may
  add some kind of webview reuse so that invisible and old buffers
  don't need to have a webview until needed.

  I seem to be using "buffer" and "tab" mostly synonymously

frame
  Frame.the-frame
  frame.set-buffer (buffer)
  frame.get-buffer => buffer
  frame.commander - text entry widget
  frame.actions - container of toolbar buttons

  in future we may be able to split a frame into multiple windows
  which show different buffers

location (url)
document
document element(?)
webview
lua's standard types

-----

a consideration we haven't touched on yet: in emacs, not all buffers
are files - e.g. the buffer list, or the process list, or the magit
status buffer - there is a well-used affordance for elisp to put
semi-persistent interactable content onscreen - do we need such a
thing here or is it ok to say "just call gtk" to command authors

----

when input widget is active for a parameter, show the completions
flowbox

while typing, use the typed input to get a completions list.  each
completion is an acceptable value: convert to a gtk widget by calling
(to-label value) and add to flowbox.


if the value is a table
  if :to-label key present, use it as-is
  else Gtk.Label { :label value.value }
else (assume it's a string)
  Gtk.Label { :label value }

on RET, check there is a completion value whose stringification
matches the input string. Hide the flowbox

to activate a rendered completion, the callback needs to perform the
same action as RET would on the chosen value

is there a role for TAB?

- in the shell it activates completion or  shows options: we don't need that if we're updating them automatically

- we could use it to cycle through the available completions: switch
focus from entry to step through the completions then RET activates


-----

# TODO

* [done] show loading progress
* [done] show url when the commander is inactive
* [done] visit-location url defaults to current
* [done] ESC to cancel interactive command
* [done] C-g to cancel key sequence

* custom rendering for completions (e.g. buffer thumbnails)
* less ugly default completions rendering
* buffer name is often going to be useless. find buffers by url/title
   still need some 1:1 mapping between the buffer object and
   a text-representable form of same
* click in commander widget activates visit-location
* in general, can we bind commands to widget events?
* display unbound key error
* autocomplete command name
* command to create new buffer
* keyboard navigation of completions

----

I think we're misusing the commander to show url and error messages
and key prompts. It's OK to have that part of the screen be multipurpose
but philosophically those things are not related to the command system.

- hide commander when inactive and replace it with echo area
- move it to bottom?

commander can't hide itself, it needs to ask its parent to hide it
