Expressive Stateful list api (putting ideas down for later discussion)

[TG-Techie]

Idea

Add a way to have TG-Gui make a list of widgets for each item in some source data in a list "automagically".
The idea is that as some StatefulList object is modified some VList container will be informed and update a visual presentation of the represented data accordingly.

Timeline

Obviously, this is quite a way out as the current GUI is only suited to static layouts where the dynamic bits are pre-define. However once scrolling and some cross-platform functionality has been added this kind of feature would be fantastic!

General Proposed Syntax

@singleinstance
class ContactsPanel(View):
    contacts = StatefulList(
        [ContactModel(**card_dict) for card_dict in get_data.from_json(file_on_disk)]
    )

    body = Vsplit(ContactPreview(contact) for contact in contacts)

First off, this specific code would be syntactic sugar for making a VList that is passed some object and links it to the contacts list. Basically, it would be misusing the python generator protocol to make this code more expressive. A de-sugared version may look something like this:

    body = Vsplit(StatefulListExpansion(ContactPreview, contacts))

Where StatefulListExpansion (or something like it) is a go-between that interprets changes in contacts and does things to the VSplit.

Specific Proposed Syntax

I think there are two good options for the sytac:

    body = Vsplit(ContactPreview(contact) for contact in contacts)
or
    body = Vsplit(ContactPreview.foreach(contact) for contact in contacts)

IMO the first option makes more sense, though it would require that ContactPreview subclasses some specific base class (let's say ModleView) that understands how to transform a model into a specific widget for it. However, I think this a requirement as theVList or StatefulListExpansion will need access to either the model's ids and/or the ModleView's id so it can figure out what to remove from the visual list of widgets.

Possible implementation

In the below syntax, ModleView would have some mechanism (probably in its __new__ constructor) that would be able to take a partially inited StatefulListExpansion and tell it what class it should make.

here are the possible steps that would happen in chronological order:

1. The body = Vsplit(ContactPreview(contact) for contact in contacts) line runs
2. A generator is created by python which calls contacts.__iter__()
3. contacts.__iter__() returns a paritally inted StatefulListExpansion (called "the expansion") in a tuple , (StatefulListExpansion(source=contacts, type=TBDFLAG),)
4. the VSplit (called "body" ) is constructed and passed the newly created generator
   a. body sees it was passed a generator and fetches the first item from the generator and keeps it
   b. on generator fetch, the expansion is passed to the ContactPreview.__new__ method witch finishes initing the expansion by passing it the ContactPreview class,
   c. the generator returns the execute ContactPreview(contact) expression on fetch end
   d. body verifies the generator contained only that item
   e. body checks and then links with the expansion via some protocol
5. the standard widget building procedure continues for VList

later

The Expansion protocol will need to fleshed out but that is a separate discussion. This is just documenting the idea of how to make the VList over a stateful list clear to write and read for TG-Gui users

Some "Full" Pseudo Code

As an example here is what the ContactPreview and ContactModel might look like:

# in some other file
@identifiable  # has _id_ attr
class ContactModel:
    def __init__(self, *, firstname, lastname, number, nickname=None):
        ...

    def subline(self):
        return self.nickname if self.nickname is not None else self.number


# in some other file
@identifiable_proxy # as it mirrors the id of its Model
class ContactPreview(ModelView):

    @property
    def body(self, model, or_soemthing?):
        return VStack(
            Label(f"{model.firstname} {model.lastname}", font=font.heading),
            Label(model.subline(), font=font.subheading),
        )

@singleinstance
class ContactsPanel(View):
    contacts = StatefulList(
        [ContactModel(**card_dict) for card_dict in get_data.from_json(file_on_disk)]
    )

    body = Vsplit(ContactPreview<?>(contact) for contact in contacts)