Add help screen to studio (#461)

feat: add help screen

Author: kayjan

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Search: Search by name/names to allow regex match.
 - Studio: Enhance search to be by name, regex, or attribute query.
 - Studio: Refactor actions to implement base class.
+- Studio: Add help screen.
 - Test: Test for studio.
 ### Fixed:
 - Query: Query method for inequality to cover cases where attribute is not present.

bigtree/tree/studio/app.py

@@ -58,8 +58,7 @@
 
 import bigtree.tree.studio.actions as actions
 import bigtree.tree.studio.utils as studio_utils
-from bigtree.tree.studio.details import Details
-from bigtree.tree.studio.prompt import Prompt
+from bigtree.tree.studio.screens import Details, Help, Prompt
 from bigtree.tree.tree import Tree as BTTree
 from bigtree.utils import exceptions
 
@@ -116,25 +115,7 @@ class Studio(App):  # type: ignore[misc]
         padding: 1;
     }
     """
-
-    BINDINGS = [
-        # space: Expand
-        # single click: view attribute
-        # double click: Expand
-        ("a", "add_node", "Add Child"),
-        ("A", "add_sibling", "Add Sibling"),
-        ("d", "delete_node", "Delete"),
-        ("r", "rename_node", "Rename"),
-        ("t", "edit_attr", "Edit Attribute"),
-        ("/", "search", "Search"),
-        ("n", "next_match", "Next"),
-        ("N", "prev_match", "Prev"),
-        ("e", "toggle_expand", "Expand"),
-        ("E", "expand_all", "Expand All"),
-        ("z", "collapse_all", "Collapse All"),
-        ("S", "save_as", "Save As"),
-        ("q", "quit", "Quit"),
-    ]
+    BINDINGS = studio_utils.BINDINGS
 
     def __init__(self, tree: BTTree, depth: int = 2):
         super().__init__()
@@ -302,6 +283,9 @@ def _save_as(self, value: Optional[str]) -> None:
             f"Saved to {value}", title="Save Successful", severity="information"
         )
 
+    def action_help(self) -> None:
+        self.push_screen(Help())
+
 
 def run_app_cli() -> None:
     parser = argparse.ArgumentParser()

bigtree/tree/studio/screens/__init__.py

@@ -0,0 +1,9 @@
+from .details import Details  # noqa
+from .help import Help  # noqa
+from .prompt import Prompt  # noqa
+
+__all__ = [
+    "Details",
+    "Help",
+    "Prompt",
+]

bigtree/tree/studio/details.py bigtree/tree/studio/screens/details.pybigtree/tree/studio/details.py renamed to bigtree/tree/studio/screens/details.py

@@ -0,0 +1,76 @@
+import bigtree.tree.studio.utils as studio_utils
+
+try:
+    from textual.app import ComposeResult
+    from textual.containers import Vertical
+    from textual.screen import ModalScreen
+    from textual.widgets import Input, Label, Static
+
+except ImportError:  # pragma: no cover
+    from unittest.mock import MagicMock
+
+    ComposeResult = MagicMock()
+    Vertical = MagicMock()
+    Static = Input = Label = MagicMock()
+    ModalScreen = MagicMock()
+
+
+class Help(ModalScreen[str]):  # type: ignore[misc]
+
+    CSS = """
+    Help {
+        align: center middle;
+        background: $background 50%
+    }
+
+    Vertical {
+        width: 72;
+        height: auto;
+        padding: 1 2;
+        background: $surface;
+        border: round $primary;
+    }
+
+    .title {
+        text-style: bold;
+        content-align: center middle;
+        margin-bottom: 1;
+    }
+
+    .section {
+        text-style: bold;
+        color: $accent;
+        margin-top: 1;
+    }
+
+    .footer {
+        margin-top: 1;
+        color: $text-muted;
+        content-align: center middle;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Vertical(
+            Label("Keyboard Shortcuts", classes="title"),
+            *self._build_help(),
+            Static("[dim]Press Esc to close[/]", classes="footer"),
+        )
+
+    @staticmethod
+    def _build_help() -> list[Static]:
+        widgets = []
+
+        for section, bindings in studio_utils.HELP.items():
+            widgets.append(Static(f"[b]{section}[/]", classes="section"))
+
+            lines = []
+            for key, *description in bindings:
+                lines.append(f"[cyan]{key:<22}[/] {description[-1]}")
+            widgets.append(Static("\n".join(lines)))
+        return widgets
+
+    def on_key(self, event: Input.Submitted) -> None:
+        if event.key in ("escape", "question_mark"):
+            event.stop()
+            self.dismiss(None)

bigtree/tree/studio/screens/help.py

@@ -26,6 +26,49 @@
 ]
 
 
+# Shortcut, key binding function, footer description, help description
+HELP: dict[str, list[tuple[str, ...]]] = {
+    "Navigation": [
+        ("↑ / ↓", "Move selection"),
+        ("Enter / Click", "View node attributes"),
+        ("Space / Double Click", "Expand or collapse node"),
+    ],
+    "Editing": [
+        ("a", "add_node", "Add Child", "Add child node"),
+        ("A", "add_sibling", "Add Sibling", "Add sibling node"),
+        ("r", "rename_node", "Rename", "Rename selected node"),
+        ("d", "delete_node", "Delete", "Delete selected node"),
+        ("t", "edit_attr", "Edit Attributes", "Edit attributes"),
+    ],
+    "Search": [
+        ("/", "search", "Search", "Search"),
+        ("n", "next_match", "Next", "Next search result"),
+        ("N", "prev_match", "Prev", "Previous search result"),
+    ],
+    "View": [
+        ("e", "toggle_expand", "Expand", "Toggle expand"),
+        ("E", "expand_all", "Expand All", "Expand all"),
+        ("z", "collapse_all", "Collapse All", "Collapse all"),
+    ],
+    "File": [
+        ("S", "save_as", "Save As", "Save As"),
+        ("q", "quit", "Quit", "Quit Studio"),
+    ],
+}
+
+BINDINGS = [
+    # enter / single click: View attribute
+    # space / double click: Expand or collapse
+    *(
+        (item[0], item[1], item[2])
+        for section, items in HELP.items()
+        if section in ["Editing", "Search", "View", "File"]
+        for item in items
+    ),
+    ("?", "help", "Help"),
+]
+
+
 SEARCH_EXAMPLES = """[b]Examples[/]
 [cyan]alice[/]                                    Exact name
 [cyan]name:^ali.*[/]                              Regex name

bigtree/tree/studio/prompt.py bigtree/tree/studio/screens/prompt.pybigtree/tree/studio/prompt.py renamed to bigtree/tree/studio/screens/prompt.py

@@ -149,9 +149,8 @@ omit = [
   "*/tests/*",
   "*/workflows/*",
   "bigtree/tree/construct/render.py",
+  "bigtree/tree/studio/screens/*",
   "bigtree/tree/studio/app.py",
-  "bigtree/tree/studio/details.py",
-  "bigtree/tree/studio/prompt.py",
 ]
 
 [tool.coverage.report]