Add typing to widgets and gui

[vallode]

This PR aims to add type support to widgets.lua and gui.lua and as a consequence extend the typing of a few other files as well (namely some globals and class.lua).

There are some conventions being established here, feel free to critique anything and everything for the sake of establishing a good foundation.

When defining new classes we should follow this rough pattern for a good experience:

---@class moduleName.ClassNameAttrs: moduleName.ParentClassAttrs
---@field foo integer This is never nil
---@field bar? integer This can be nil

---@class moduleName.ClassNameInitTable: moduleName.ClassNameAttrs
---@field foo integer This needs to be provided during init
-- This also inherits all attributes from ClassNameAttrs but they are optional.

---@class moduleName.ClassName: moduleName.ParentClass, moduleName.ClassNameAttrs
---@field super moduleName.ParentClass
---@field ATTRS moduleName.ClassNameAttrs|fun(attributes: moduleName.ClassNameAttrs)
---@overload fun(init_table: moduleName.ClassNameInitTable): self
ClassName = defclass(ClassName, Widget)

There are a few caveats:

• defclass(ClassName) plays weird with LuaLS and self parameters in the module file will have to be manually cast as the class, i.e:

---@param self moduleName.ClassName
---@param init_table moduleName.ClassNameInitTable
function ClassName:init(init_table) end```
- `subviews` indexing has no autocomplete or type support so subviews accessed need to be cast manually, i.e
```lua
---@type widgets.List
local list = self.subviews.list

[vallode]

pre-commit.ci autofix

[vallode]

@myk002 gui.lua is probably ready for a first pass to start setting in stone some of the conventions we might use in the future. Namespacing is one issue dfhack.gui.Painter vs gui.Painter. As well as where to keep things like dfhack.color and dfhack.pen, inline whereever fits or maybe a more generic types.lua file also works. I'll let you look over it before I continue further with typing all the methods in gui and widgets.

[myk002]

looks like a great start! class names look good to me

[myk002]

is this attached to anything? or does it get combined into defclass below?

[vallode]

This overload is attached to the class itself, it's mostly boilerplate.

[myk002]

I think this is more commonly an integer, though a string character also works (iirc)

[vallode]

I think this is probably a candidate for an alias/class like dfhack.pen or dfhack.truthy.

[myk002]

specifically, a function that takes no params and returns no value

[myk002]

these three are internal; do they need to be declared here?

[myk002]

colors or Pens

[myk002]

scroll_keys is a map from keybinding strings to either an integer or a string

[vallode]

@myk002 getting closer to completion, feel free to ignore widgets.lua below TextButton I ran out of steam a bit. Also feel free to leave this for a day or two before I get it closer to being 100% done. Cheers!

[vallode]

pre-commit.ci autofix

[myk002]

empty strings are truthy. only nil and false is falsey

if you really want to be complete, you can add userdata to this list

[myk002]

tab? table<T>

[vallode]

As mentioned on Discord, I think this doesn't work. Full example would be something like:

---@generic T
---@param tab? table<T>
---@param idx integer
---@return T
local function map_opttab(tab,idx)
    if tab then
        return tab[idx]
    else
        return idx
    end
end

---@type string[]
local foo
local bar = map_opttab(foo, 0)

Where bar remains unknown

[myk002]

T|integer

[myk002]

this can also be a list of text tokens, like Label