Add OptionList widget (#2154)

* Menu skeleton

The vaguest of starts. Near the end of the day and I want to pick this up
later/tomorrow, so making sure it's on the forge before I go AFK.

* Initial design for populating the menu

One of the driving forces in the design here is that a menu option can have
a prompt that is more than one line in height; and different options can
have different height prompts. This has meant that I've had to finally get
to grips with Rich renderable types and related things.

The menu is going to lean heavily on the line API, and aims to be as
efficient as possible when it comes to having a very large menu. Large menus
are a bad idea! Nobody should be using large menus. On the other hand,
people will do it so let's allow for it.

Work in progress commit. Lots more to come.

* Add a reminder about width

* Make mypy and friend happy with OptionLineSpan.__contains__

* Fix typo

* Add a debug message

I'll remove this later, but I'd like to bubble up some debug stuff into my
own test app.

* Get scrolling working

After battling for ages to try and figure out why scrolling just wasn't
working at all, two things turned out to be at play:

1. If `overflow: hidden` you need force=True. Doh!
   - I should know that too as I added force. O_o
2. Even if you do the above, it doesn't work as you'd expect *if* animation
   is turned on. Turning that off made things work.

I've raised #2077 as a reminder to myself that I need to look into '2' some
more. The menus feel very snappy with animation off, but I suspect there
will be a call to allow animation during menu navigation so that'll need
sorting at some point I guess.

* Add support for home and end keys

Which, shockingly, go to the first and last items in the menu.

* Remind myself I need to remove the Debug message

Once I'm done with it.

* Make the MenuOption class a NamedTuple

There's no obvious benefit to it being a full class, but some benefits to it
being a NamedTuple.

* Add a Menu.OptionHighlighted message

* Add a missing argument to a docstring

* Fully type the option line segments list

I forgot to ensure that it was fully typed.

* Add a method for getting an option at a given position

* Better name for the location of the option

* Include the highlighted index in the OptionHighlighted message

* Add home and end to the binding docstring

* Add support for page up/down in a menu

* Rename OptionLineSegments to OptionLine

It's the details for a line of an option that hold the segments, amongst
other things. No point in repeating information here.

* Add support for a Menu.OptionSelected message

* Remove a TODO comment

It's not that it doesn't need doing yet; it's just that I've moved some TODO
stuff to a WIP document.

* Document the enter binding

* Add a reminder to myself about why animate is off

For a menu I feel that animate *should* be off, but if anyone is reading
this bit of code and feels it should be on, this will explain why it isn't.

* Explain OptionLineSpan a wee bit more

* Import Literal from typing_extensions rather than typing

This is needed for older Pythons.

* Move the prompt shapes calculation code into its own method

* Add a property for getting the option count of the menu

* Add a method of adding an option to the menu

* Highlight first option if no highlight and then movement

* Ensure the virtual height is recalculated on addition

* Remove the method for getting a specific option

There's little point in letting the user treat the menu as if it's an array;
they should know what they put into it and anything that happens *on* the
menu will result in a message which will point to the option anyway.

* Add a menu separator

This isn't the complete version of this; aside from the obvious fact that at
the moment it's just treated line an ordinary menu option (which we don't
want), the presence of a separator means the index of options will be thrown
off, from the user's point of view. The point being, a menu with 4 options
and a separator might look like this:

    Option 1
    Option 2
    --------
    Option 3
    Option 4

I think the index of "Option 3" above should likely be 2 (starting from 0,
of course), not 3. This means I need to tweak the internals of the menu code
to take this into account while also keeping things efficient.

That's next up; but I wanted to get the core of this change in first so I
can noodle away and get the best approach to this.

* Finish off support for menu separators

Here I sort of add support for a menu having both content *and* prompts.
Content is anything that goes in the menu and results in lines being
rendered. Prompts are things that the end user actually gets to select from.
A menu option will have a prompt that has one or more lines. A menu
separator isn't an option but takes up one line.

* Add (back) a method for getting a particular option

Now that the menu content and the menu options are different lists, it's
possible to allow this again. While it still follows that menus shouldn't
really be treated like lists, there's no harm in providing this facility.

* Allow styling separators

* Fix how we tell the Rule to have no style

* Add a documentation line for the separator component class

* Apply default styling to the non-special options

* Set the default color to $text

This isn't actually working, but if I set it to an actual colour, it does
work. Need to dig into this more.

* Remove a TODO warning that isn't valid any more

* Have the menu option messages get the option via Menu.option

It did, and still could, pull directly from the _option property but one
step of indirection means that I can be sure anything "external" is going
via the public interface (yes, I know the message isn't really "external"
but it feels correct to treat it as such because it's for public
consumption).

* Make OptionLine just a Line and drop magic numbers for separators

Rather than overload the option index of the option line class with a magic
number to say that something isn't really an option, here I make the class
just about being a line, I keep the option_index but make it optional (no
pun intended); so that if it's `None` that means "this isn't related to a
menu option".

* Drop the assert that non-option content is a separator

I can't see much benefit in doing this in what should be a fairly tight
loop. This code relates to data that's all under the hood so we shouldn't
need to be quite so defensive.

* Remove unused import of Final

* Add a clear method

* Add support for disabled menu options

At the moment this is done in a way that, as the user navigates, the
disabled options *aren't* skipped. I'm still undecided about this. Your
traditional dropdown menus sometimes do that, sometimes don't do that. And
to make things even more interesting this menu can really be used as a
large-data-friendly listbox and I'm not sure we'd want that there.

This may change.

Also, at this point, I'm also working to keep the MenuOption class a
NamedTuple, which means it's read-only (I don't want the user messing with
things outside of the menu), which means there's interface methods for
changing the disabled state that copy the option and change the disabled
state.

Again, I'll see if I carry on liking this or not. So far I'm okay with this.

* Dial in the styles some more

* Rename some methods that use index to say index in the name

I'm going to be adding support for an id for options too, and want the user
to be able to either access an option via index or via ID. This is the first
step to allowing that.

* Remove an unnecessary inherit

Looks like this was a hangover from an early version of the message classes
and I didn't clean up.

* Fix copy/paste-o

Now there is forever evidence as to where I stole my homework from.

* Add support for menu option IDs

The idea here is that they're purely from, and purely for, the developer who
is creating the menu. Internally I don't care about them and don't
personally use them. However, there is without a doubt a good case for
allowing the developer to specify IDs for options so here's optional support
for that.

* Add a method to get a menu option via an ID

* Reduce property access and list access calls

* Have the content-tracker code do a little less work

* Drop the menu option data attribute

It wasn't going to work well, was going to cause a bunch of problems with
typing, and really it's easier to do by the dev by having them inherit from
MenuOption. So let's do that.

* Remove unused imports

* Add a TODO reminder about subclasses menu optons

* Add an initial bit of unit testing

Just the most basic test so far; it's the end of the day but I want to start
here.

* Allow the caller to use None as an alias for MenuSeparator

In doing so, overhaul how I type candidate menu content vs actual menu
content, setting up a couple of type aliases and making it easier to
maintain.

* Rename the parameter for Menu.add to better match other changes

* Swap MenuOption over to being a standard class

It would have been nice to keep it as a named tuple, but I want the
developer to be able to subclass and add their own properties to the
option (think attaching some random data to a menu option). The problem is
you can't subclass a named tuple.

So... standard class it is, with some reasonably defensive work to
discourage the developer from changing the prompt and the ID on the fly.

For obvious reasons I need to let them change the disabled state on the fly,
and this is where things end up being a little iffy. The only way (right
now) the menu will refresh when the disabled state changes is if the
developer does so via one of the methods on Menu. If they go toggling the
state on the option itself and hope that the menu will reflect this... no,
that's not going to happen.

I *could* make it happen by somehow capturing a reference to the parent menu
inside the menu option, but then things get circular and I don't like that.

* Test using None as an alternative to MenuSeparator

* Flesh out the initial menu unit tests

* Add a module docstring to the core menu unit test

* Add some testing for using subclassed menu options

* Add a property for getting an iterator of the options

* Add unit tests for option enabled/disabled

* Rename Menu -> OptionList (and friends)

The great renaming! We sort of had decided this was coming, but kept going
back and forth on if we should, what it should be, etc. Decision made today.
While this is mostly everything you want from a menu, it is foundational
enough that it needs to really be something else so it's a list of options.
Options; in a list. An OptionList.

* Add a test for adding more items to an option list later on

* Remove the debug message

I think I'm at a stage where I don't need to use it any more.

* Start of OptionList movement tests

End of day commit; more to come.

* Update the pyi for the Menu -> OptionList rename

Missed this during the grand rename.

* Tidy up a test

* Export the DuplicateID exception

* Add a test for creating a duplicate ID

* Add some more OptionList movement tests

* Allow scrollbars by default

Until the great renaming, this code was all about being menus, which
normally don't have scrollbars, and so I made a point of not having them on.
Now that this code is more about it being a list of stuff, which can be the
foundation for a menu, we want the bars there by default and any derived
menu widget can turn them off.

So here we go.

This introduces some issues that now need to be addressed. For one thing no
thought has been given to horizontal scrolling in this code (easy enough to
solve).

Also, weirdly though, the vertical scrollbars aren't quite reaching the
bottom when we highlight the last item. Wasn't expecting that, although I'm
sure there's a simple cause for that.

* Remove hover component class

I do want this, but not yet, so don't have it kicking around until I'm
actually doing something with it.

* Add missing items to the component classes docstring.

* Crop the lines that we draw

This in turn adds support for horizontal scrolling. We're not actually going
to support horizontal scrolling; in conversation with Will we've decided
that it will be *only* a vertical scrolling list, so options will be
rendered within the confines of the width.

* Allow for scrollbars by default

* Make scrolling to a non-highlight a nop rather than an error

Being able to call scroll_to_highlight even if nothing is highlighted is
useful; throwing an error when something isn't, isn't helpful. So let's make
that a no-op.

* Make a note that option ID tracking could be changed

* Ensure highlight is pulled into view on resize

It's possible that a resize might cause a highlight to partially, or even
totally, go out of view. This commit ensures that after such an event this
will be handled.

* Save an attribute access

* Microoptimise _refresh_content_tracking some more

* Reintroduce animation

But only if the vertical scrollbar is visible (see #2077 for context).

* Force a refresh when doing a specific add

* Add support for a mouse hover effect

* Highlighted a clicked option (where appropriate)

* Improve the style of a focused highlighted hovered option

* Reduce the number of attribute lookups in the line drawing method

* Simplify the way we handle page up/down at the margins

Rather than wrap around when doing page up/down, have them work as home/end
when at the margins.

* Remove unnecessary import

* Add some more option list movement tests

* Add tests for moving around an empty list

* Remove the debug message (again)

* Test moving when there are items but no highlight

* Ensure the mouse over gets cleared on clear

* Remove mouse hover logging code

It was useful while adding mouse hover support, but it's not needed now.

* Force a refresh of content tracking when doing a clear

* Rename some methods to talk about options

I want to add a `remove` for options, but widgets already have a `remove`.
So I could call it `remove_option` but then that's an imbalance with `add`.
So this renames `add` to `add_option`, and also renames `clear` to
`clear_options`.

* Add support for removing an option

* Add highlight wrapping back

I made some recent changes to highlight validation where more sensible in
the general sense, but broke the wrapping when using cursor keys to move
around. This takes that into account.

* Add tests for removing options

* Reduce the number of attribute lookups for spans

* Swap to watching highlighted to handle movement

I'd started out with an explicit refresh of the highlighted option, while
working on other things, and forgot to swap over to using a watch method.
This commit fixes that.

* Make a mouse-clicked option select that option too

* Add unit tests for option list messages

* Add unit tests for mouse hover events

* Clarify the point of the mouse click test

* Add an option list message test for highlighting a disabled option

* Add tests for interacting with disabled OptionList options

* Typo fixing

Try and make the docstring sound something approaching English.

* Fix the OptionMessage.__init__ docstring

* Add the API documentation for the OptionList

* Update the OptionTest message tests for initial highlight

Having changed things around a little regarding initial highlight, the unit
tests needed updating.

* Start the reference for the OptionList

I feel this needs a bit more work, but this feels like the core of what we
want to be emphasising.

* Add the OptionList to the gallary

* Try some extra pauses in OptionList tests

While the tests are all passing just fine locally, I'm getting the whole
whack-a-mole thing in CI that is mostly down to subtle timing issues. This
is a test to see if these extra pauses let the test apps settle down before
starting the meat of the testing.

* Try pausing in tests without setting a time

* Add snapshot tests for the OptionList examples

* Sort the bindings

* Add a docstring to the default CSS

* Explain that mouse_hovering_over can be None

* Turn mouse_hovering_over into an internal property

There was a reason that I had it as a reactive, at one point, but looking at
the final form of this code I can't see a use for it any more. So bring it
internal and make it cheaper to update.

* Update the CHANGELOG

* Update the mouse hover test after the changes to the tracking variable

* Tweak the descriptions of the hover tests

Now that I've changed this away from being a reactive.

* Tweak the OptionList hover tests some more

* Rename the up/down actions to cursor_up/down

Re: #2154 (comment)

* Don't kick off an idle check if the widget isn't running

Added at Will's suggestion. :-P

* Simplify how we watch the vertical scrollbar status

Re: #2154 (comment)

* Change the hover highlight to $boost

Re: #2154 (comment)

* Add a custom exception for when an option can't be found

Re:
https://github.com/Textualize/textual/pull/2154/files/74a2d079b3053263b39f5620ae5438dc5ef0322c#r1151632957
and https://github.com/Textualize/textual/pull/2154/files/74a2d079b3053263b39f5620ae5438dc5ef0322c#r1151631495

* Update tests for the new option list exceptions

* Remove the options property

We've decided it has little utility given the rest of the interface of the
widget.

Re: #2154 (comment)

* Remove import of iterator

It's no longer required.

* Fix some option list unit tests after removing options property

* Crate Line.segments as a strip

Rather than recreate the strip every time around, just create it as a Strip
to start with. Also, in doing so, add the option meta up front rather than
every time we draw the line.

Re: #2154 (comment)

* Correct a comment typo

* Simplify the Separator docstring

* Docstring wording tweak

* Remove the import of Segment

It's not needed any more

* Flesh out the OptionList reference some more

Things like the component classes, bindings and messages had been left out.

* Update snapshot tests

Nothing of consequence has changed but it looked like the change to how the
lines are originally constructed has resulted in an under-the-hood change to
the data that goes into a snapshot.

* Add a missing word to a docstring

Co-authored-by: Rodrigo Girão Serrão <[email protected]>

* Fix a typo

Co-authored-by: Rodrigo Girão Serrão <[email protected]>

* Fix a typo

Co-authored-by: Rodrigo Girão Serrão <[email protected]>

* Document some raises that were missing

* Turn off animation

---------

Co-authored-by: Rodrigo Girão Serrão <[email protected]>

Author: davep

CHANGELOG.md

@@ -43,6 +43,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Added TEXTUAL_LOG env var which should be a path that Textual will write verbose logs to (textual devtools is generally preferred) https://github.com/Textualize/textual/pull/2148
 - Added textual.logging.TextualHandler logging handler
 - Added Query.set_classes, DOMNode.set_classes, and `classes` setter for Widget https://github.com/Textualize/textual/issues/1081
+- Added `OptionList` https://github.com/Textualize/textual/pull/2154
 
 ## [0.16.0] - 2023-03-22
 

docs/api/option_list.md

@@ -0,0 +1,3 @@
+::: textual.widgets.OptionList
+::: textual.widgets._option_list.Option
+::: textual.widgets._option_list.Separator

docs/examples/widgets/option_list.css

@@ -0,0 +1,10 @@
+Screen {
+    align: center middle;
+}
+
+OptionList {
+    background: $panel;
+    border: round $primary;
+    width: 70%;
+    height: 70%;
+}

docs/examples/widgets/option_list_options.py

@@ -0,0 +1,36 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Footer, Header, OptionList
+from textual.widgets.option_list import Option, Separator
+
+
+class OptionListApp(App[None]):
+    CSS_PATH = "option_list.css"
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield OptionList(
+            Option("Aerilon", id="aer"),
+            Option("Aquaria", id="aqu"),
+            Separator(),
+            Option("Canceron", id="can"),
+            Option("Caprica", id="cap", disabled=True),
+            Separator(),
+            Option("Gemenon", id="gem"),
+            Separator(),
+            Option("Leonis", id="leo"),
+            Option("Libran", id="lib"),
+            Separator(),
+            Option("Picon", id="pic"),
+            Separator(),
+            Option("Sagittaron", id="sag"),
+            Option("Scorpia", id="sco"),
+            Separator(),
+            Option("Tauron", id="tau"),
+            Separator(),
+            Option("Virgon", id="vir"),
+        )
+        yield Footer()
+
+
+if __name__ == "__main__":
+    OptionListApp().run()

docs/examples/widgets/option_list_strings.py

@@ -0,0 +1,28 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Footer, Header, OptionList
+
+
+class OptionListApp(App[None]):
+    CSS_PATH = "option_list.css"
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield OptionList(
+            "Aerilon",
+            "Aquaria",
+            "Canceron",
+            "Caprica",
+            "Gemenon",
+            "Leonis",
+            "Libran",
+            "Picon",
+            "Sagittaron",
+            "Scorpia",
+            "Tauron",
+            "Virgon",
+        )
+        yield Footer()
+
+
+if __name__ == "__main__":
+    OptionListApp().run()

docs/examples/widgets/option_list_tables.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from rich.table import Table
+
+from textual.app import App, ComposeResult
+from textual.widgets import Footer, Header, OptionList
+from textual.widgets.option_list import Option, Separator
+
+COLONIES: tuple[tuple[str, str, str, str], ...] = (
+    ("Aerilon", "Demeter", "1.2 Billion", "Gaoth"),
+    ("Aquaria", "Hermes", "75,000", "None"),
+    ("Canceron", "Hephaestus", "6.7 Billion", "Hades"),
+    ("Caprica", "Apollo", "4.9 Billion", "Caprica City"),
+    ("Gemenon", "Hera", "2.8 Billion", "Oranu"),
+    ("Leonis", "Artemis", "2.6 Billion", "Luminere"),
+    ("Libran", "Athena", "2.1 Billion", "None"),
+    ("Picon", "Poseidon", "1.4 Billion", "Queenstown"),
+    ("Sagittaron", "Zeus", "1.7 Billion", "Tawa"),
+    ("Scorpia", "Dionysus", "450 Million", "Celeste"),
+    ("Tauron", "Ares", "2.5 Billion", "Hypatia"),
+    ("Virgon", "Hestia", "4.3 Billion", "Boskirk"),
+)
+
+
+class OptionListApp(App[None]):
+    CSS_PATH = "option_list.css"
+
+    @staticmethod
+    def colony(name: str, god: str, population: str, capital: str) -> Table:
+        table = Table(title=f"Data for {name}", expand=True)
+        table.add_column("Patron God")
+        table.add_column("Population")
+        table.add_column("Capital City")
+        table.add_row(god, population, capital)
+        return table
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield OptionList(*[self.colony(*row) for row in COLONIES])
+        yield Footer()
+
+
+if __name__ == "__main__":
+    OptionListApp().run()

docs/widget_gallery.md

@@ -138,6 +138,15 @@ Display a markdown document.
 ```{.textual path="docs/examples/widgets/markdown.py"}
 ```
 
+## OptionList
+
+Display a vertical list of options (options may be Rich renderables).
+
+[OptionList reference](./widgets/option_list.md){ .md-button .md-button--primary }
+
+
+```{.textual path="docs/examples/widgets/option_list_options.py"}
+```
 
 ## Placeholder
 

docs/widgets/option_list.md

@@ -0,0 +1,127 @@
+# OptionList
+
+!!! tip "Added in version 0.17.0"
+
+A widget for showing a vertical list of Rich renderable options.
+
+- [x] Focusable
+- [ ] Container
+
+## Examples
+
+### Options as simple strings
+
+An `OptionList` can be constructed with a simple collection of string
+options:
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/option_list_strings.py"}
+    ```
+
+=== "option_list_strings.py"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/option_list_strings.py"
+    ~~~
+
+=== "option_list.css"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/option_list.css"
+    ~~~
+
+### Options as `Option` instances
+
+For finer control over the options, the `Option` class can be used; this
+allows for setting IDs, setting initial disabled state, etc. The `Separator`
+class can be used to add separator lines between options.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/option_list_options.py"}
+    ```
+
+=== "option_list_options.py"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/option_list_options.py"
+    ~~~
+
+=== "option_list.css"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/option_list.css"
+    ~~~
+
+### Options as Rich renderables
+
+Because the prompts for the options can be [Rich
+renderables](https://rich.readthedocs.io/en/latest/protocol.html), this
+means they can be any height you wish. As an example, here is an option list
+comprised of [Rich
+tables](https://rich.readthedocs.io/en/latest/tables.html):
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/option_list_tables.py"}
+    ```
+
+=== "option_list_tables.py"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/option_list_tables.py"
+    ~~~
+
+=== "option_list.css"
+
+    ~~~python
+    --8<-- "docs/examples/widgets/option_list.css"
+    ~~~
+
+## Reactive Attributes
+
+| Name          | Type            | Default | Description                                                               |
+|---------------|-----------------|---------|---------------------------------------------------------------------------|
+| `highlighted` | `int` \| `None` | `None`  | The index of the highlighted option. `None` means nothing is highlighted. |
+
+## Messages
+
+### ::: textual.widgets.OptionList.OptionHighlighted
+
+### ::: textual.widgets.OptionList.OptionSelected
+
+Both of the messages above inherit from this common base, which makes
+available the following properties relating to the `OptionList` and the
+related `Option`:
+
+### Common message properties
+
+Both of the above messages provide the following properties:
+
+#### ::: textual.widgets.OptionList.OptionMessage.option
+#### ::: textual.widgets.OptionList.OptionMessage.option_id
+#### ::: textual.widgets.OptionList.OptionMessage.option_index
+#### ::: textual.widgets.OptionList.OptionMessage.option_list
+
+## Bindings
+
+The option list widget defines the following bindings:
+
+::: textual.widgets.OptionList.BINDINGS
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+
+## Component Classes
+
+The option list provides the following component classes:
+
+::: textual.widgets.OptionList.COMPONENT_CLASSES
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+
+## See Also
+
+* [OptionList][textual.widgets.OptionList] code reference

mkdocs-nav.yml

@@ -137,6 +137,7 @@ nav:
       - "widgets/loading_indicator.md"
       - "widgets/markdown_viewer.md"
       - "widgets/markdown.md"
+      - "widgets/option_list.md"
       - "widgets/placeholder.md"
       - "widgets/radiobutton.md"
       - "widgets/radioset.md"
@@ -174,6 +175,7 @@ nav:
     - "api/markdown.md"
     - "api/message_pump.md"
     - "api/message.md"
+    - "api/option_list.md"
     - "api/pilot.md"
     - "api/placeholder.md"
     - "api/query.md"

src/textual/message_pump.py

@@ -597,7 +597,7 @@ async def _on_message(self, message: Message) -> None:
 
     def check_idle(self) -> None:
         """Prompt the message pump to call idle if the queue is empty."""
-        if self._message_queue.empty():
+        if self._running and self._message_queue.empty():
             self.post_message(messages.Prompt())
 
     async def _post_message(self, message: Message) -> bool: