Widget collapsible

docs/examples/widgets/collapsible.py

@@ -0,0 +1,47 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Collapsible, Footer, Label, Markdown
+
+LETO = """
+# Duke Leto I Atreides
+
+Head of House Atreides.
+"""
+
+JESSICA = """
+# Lady Jessica
+
+Bene Gesserit and concubine of Leto, and mother of Paul and Alia.
+"""
+
+PAUL = """
+# Paul Atreides
+
+Son of Leto and Jessica.
+"""
+
+
+class CollapsibleApp(App):
+    """An example of colllapsible container."""
+
+    BINDINGS = [
+        ("c", "collapse_or_expand(True)", "Collapse All"),
+        ("e", "collapse_or_expand(False)", "Expand All"),
+    ]
+
+    def compose(self) -> ComposeResult:
+        """Compose app with collapsible containers."""
+        yield Footer()
+        with Collapsible(collapsed=False, title="Leto"):
+            yield Label(LETO)
+        yield Collapsible(Markdown(JESSICA), collapsed=False, title="Jessica")
+        with Collapsible(collapsed=True, title="Paul"):
+            yield Markdown(PAUL)
+
+    def action_collapse_or_expand(self, collapse: bool) -> None:
+        for child in self.walk_children(Collapsible):
+            child.collapsed = collapse
+
+
+if __name__ == "__main__":
+    app = CollapsibleApp()
+    app.run()

docs/widgets/collapsible.md

     ``` 
 === "Output" 
     ```{.textual path="docs/examples/widgets/button.py"} 
     ``` 
 === "button.py" 
     ```python 
     --8<-- "docs/examples/widgets/button.py" 
     ``` 
 === "button.css" 
     ```sass 
     --8<-- "docs/examples/widgets/button.css" 
     ``` 
@@ -0,0 +1,100 @@
+# Collapsible
+
+<!-- !!! tip "Added in version .." -->
+
+Collapsible contents with title.
+
+- [x] Container
+
+This widget wraps other widgets as `Contents` and control the visibility.
+
+## Composing
+
+There are two ways to wrap other widgets.
+You can pass them as positional arguments to the [Collapsible][textual.widgets.Collapsible] constructor:
+
+```python
+def compose(self) -> ComposeResult:
+    yield Collapsible(Label("Verbose sentence to show by default."))
+
+```
+
+Alternatively you can compose other widgets under the context manager:
+
+```python
+def compose(self) -> ComposeResult:
+    with Collapsible():
+        yield Label("Verbose sentence to show by default.")
+
+```
+
+## Title
+
+`Collapsible` can have a custom title instead of "Toggle" by `title` argument of the constructor:
+
+```python
+def compose(self) -> ComposeResult:
+    with Collapsible(title="An interesting story."):
+        yield Label("Interesting but verbose story.")
+
+```
+
+## Collapse/Expand Symbols
+
+`Collapsible` can have different symbol(label)s for each expanded/collapsed status.
+
+```python
+def compose(self) -> ComposeResult:
+    with Collapsible(title="", collapsed_symbol="► Show more", expanded_symbol="▼ Close"):
+        yield Label("Many words.")
+
+```
+
+## Collapse/Expand
+
+If can set the initial status of `collapsed` by `collapsed` argument of the constructor:
+
+```python
+def compose(self) -> ComposeResult:
+    with Collapsible(title="Contents 1", collapsed=False):
+        yield Label("Short sentence to show by default.")
+
+    with Collapsible(title="Contents 2", collapsed=True):  # Default is True
+        yield Label("Verbose unecessary sentence to show by default.")
+```
+
+## Example
+
+The following example contains three `Collapsible`s.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/collapsible.py"}
+    ```
+
+=== "collapsible.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/collapsible.py"
+    ```
+
+## Reactive attributes
+
+| Name        | Type   | Default | Description                                                    |
+| ----------- | ------ | ------- | -------------------------------------------------------------- |
+| `collapsed` | `bool` | `True`  | Invisibility of `Contents`. Set it `False` to show `Contents`. |
+
+## Messages
+
+- [Collapsible.Summary.Toggle][Collapsible.Summary.Toggle]
+
+## See also
+
+<!-- TODO: Add Accordion widgets later -->
+
+---
+
+
+::: textual.widgets.Collapsible
+    options:
+      heading_level: 2

src/textual/widgets/__init__.py

@@ -12,6 +12,7 @@
     from ..widget import Widget
     from ._button import Button
     from ._checkbox import Checkbox
+    from ._collapsible import Collapsible
     from ._content_switcher import ContentSwitcher
     from ._data_table import DataTable
     from ._directory_tree import DirectoryTree
@@ -41,7 +42,6 @@
     from ._tree import Tree
     from ._welcome import Welcome
 
-
 __all__ = [
     "Button",
     "Checkbox",
@@ -76,6 +76,7 @@
     "Tooltip",
     "Tree",
     "Welcome",
+    "Collapsible",
 ]
 
 _WIDGETS_LAZY_LOADING_CACHE: dict[str, type[Widget]] = {}

src/textual/widgets/__init__.pyi

@@ -1,6 +1,7 @@
 # This stub file must re-export every classes exposed in the __init__.py's `__all__` list:
 from ._button import Button as Button
 from ._checkbox import Checkbox as Checkbox
+from ._collapsible import Collapsible as Collapsible
 from ._content_switcher import ContentSwitcher as ContentSwitcher
 from ._data_table import DataTable as DataTable
 from ._directory_tree import DirectoryTree as DirectoryTree

src/textual/widgets/_collapsible.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from textual.widget import Widget
+
+from .. import events, on
+from ..app import ComposeResult
+from ..containers import Container, Horizontal
+from ..message import Message
+from ..reactive import reactive
+from ..widget import Widget
+from ._label import Label
+
+__all__ = ["Collapsible"]
+
+
+class Collapsible(Widget):
+    """A collapsible container."""
+
+    collapsed = reactive(True)
+
+    DEFAULT_CSS = """
+    Collapsible {
+        width: 100%;
+        height: auto;
+    }
+    """
+
+    class Title(Horizontal):
+        DEFAULT_CSS = """
+        Title {
+            width: 100%;
+            height: auto;
+        }
+
+        Title:hover {
+            background: grey;
+        }
+
+        Title .label {
+            padding: 0 0 0 1;
+        }
+
+        Title #collapsed-symbol {
+            display:none;
+        }
+
+        Title.-collapsed #expanded-symbol {
+            display:none;
+        }
+
+        Title.-collapsed #collapsed-symbol {
+            display:block;
+        }
+        """
+
+        def __init__(
+            self,
+            *,
+            label: str,
+            collapsed_symbol: str,
+            expanded_symbol: str,
+            name: str | None = None,
+            id: str | None = None,
+            classes: str | None = None,
+            disabled: bool = False,
+        ) -> None:
+            super().__init__(name=name, id=id, classes=classes, disabled=disabled)
+            self.collapsed_symbol = collapsed_symbol
+            self.expanded_symbol = expanded_symbol
+            self.label = label
+
+        class Toggle(Message):
+            """Request toggle."""
+
+        async def _on_click(self, event: events.Click) -> None:
+            """Inform ancestor we want to toggle."""
+            self.post_message(self.Toggle())
+
+        def compose(self) -> ComposeResult:
+            """Compose right/down arrow and label."""
+            yield Label(self.expanded_symbol, classes="label", id="expanded-symbol")
+            yield Label(self.collapsed_symbol, classes="label", id="collapsed-symbol")
+            yield Label(self.label, classes="label")
+
+    class Contents(Container):
+        DEFAULT_CSS = """
+        Contents {
+            width: 100%;
+            height: auto;
+            padding: 0 0 0 3;
+        }
+
+        Contents.-collapsed {
+            display: none;
+        }
+        """
+
+    def __init__(
+        self,
+        *children: Widget,
+        title: str = "Toggle",
+        collapsed: bool = True,
+        collapsed_symbol: str = "►",
+        expanded_symbol: str = "▼",
+        name: str | None = None,
+        id: str | None = None,
+        classes: str | None = None,
+        disabled: bool = False,
+    ) -> None:
+        """Initialize a Collapsible widget.
+
+        Args:
+            *children: Contents that will be collapsed/expanded.
+            title: Title of the collapsed/expanded contents.
+            collapsed: Default status of the contents.
+            collapsed_symbol: Collapsed symbol before the title.
+            expanded_symbol: Expanded symbol before the title.
+            name: The name of the collapsible.
+            id: The ID of the collapsible in the DOM.
+            classes: The CSS classes of the collapsible.
+            disabled: Whether the collapsible is disabled or not.
+        """
+        self._title = self.Title(
+            label=title,
+            collapsed_symbol=collapsed_symbol,
+            expanded_symbol=expanded_symbol,
+        )
+        self._contents_list: list[Widget] = list(children)
+        super().__init__(name=name, id=id, classes=classes, disabled=disabled)
+        self.collapsed = collapsed
+
+    @on(Title.Toggle)
+    def _update_collapsed(self) -> None:
+        self.collapsed = not self.collapsed
+
+    def watch_collapsed(self) -> None:
+        for child in self._nodes:
+            child.set_class(self.collapsed, "-collapsed")
+
+    def compose(self) -> ComposeResult:
+        yield from (
+            child.set_class(self.collapsed, "-collapsed")
+            for child in (
+                self._title,
+                self.Contents(*self._contents_list),
+            )
+        )
+
+    def compose_add_child(self, widget: Widget) -> None:
+        """When using the context manager compose syntax, we want to attach nodes to the contents.
+
+        Args:
+            widget: A Widget to add.
+        """
+        self._contents_list.append(widget)