feat(ui): draw pane frames, page keys and a scroll thumb

tests/test_frame.py

@@ -0,0 +1,81 @@
+"""The BBS frames: grey edges, corners fading white → grey → cyan."""
+
+from __future__ import annotations
+
+from rich.text import Text
+
+from beefy_player.widgets import frame
+
+
+def styles_of(line: Text) -> list[tuple[str, str]]:
+    return [
+        (line.plain[span.start : span.end], str(span.style)) for span in line.spans
+    ]
+
+
+def test_only_the_top_right_corner_fades_on_the_top_edge() -> None:
+    spans = styles_of(frame.top(30))
+    assert spans[0] == ("╭", "bright_black")  # plain grey corner
+    # the fade runs into the top-right corner: cyan, bright cyan, light grey
+    assert [style for _text, style in spans[-5:-1]] == [
+        "bright_black",
+        "cyan",
+        "bright_cyan",
+        "white",
+    ]
+    assert spans[-1] == ("╮", "bold bright_white")
+
+
+def test_only_the_bottom_left_corner_fades_on_the_bottom_edge() -> None:
+    spans = styles_of(frame.bottom(30))
+    assert spans[0] == ("╰", "bold bright_white")
+    assert [style for _text, style in spans[1:4]] == ["white", "bright_cyan", "cyan"]
+    assert spans[-1] == ("╯", "bright_black")  # plain grey corner
+
+
+def test_the_sides_glow_towards_their_own_corner_only() -> None:
+    # left column fades up from the bottom-left corner
+    assert [frame.side_style(row, 10, "left") for row in range(10)] == [
+        "bright_black",
+        "bright_black",
+        "bright_black",
+        "bright_black",
+        "bright_black",
+        "bright_black",
+        "bright_black",
+        "cyan",
+        "bright_cyan",
+        "white",
+    ]
+    # right column fades down from the top-right corner
+    assert [frame.side_style(row, 10, "right") for row in range(10)] == [
+        "white",
+        "bright_cyan",
+        "cyan",
+        "bright_black",
+        "bright_black",
+        "bright_black",
+        "bright_black",
+        "bright_black",
+        "bright_black",
+        "bright_black",
+    ]
+
+
+def test_the_title_sits_after_the_left_fade() -> None:
+    line = frame.top(30, "STATIONS")
+    assert line.plain.startswith("╭─ STATIONS ─")
+    assert "STATIONS" in line.plain
+    # a pane too narrow for the title drops it rather than truncating
+    assert "STATIONS" not in frame.top(10, "STATIONS").plain
+
+
+def test_wrap_frames_the_content_on_every_row() -> None:
+    content = [Text("hello"), Text("world")]
+    group = frame.wrap(content, 20, 6, "PANE")
+    lines = [line.plain for line in group.renderables]
+    assert len(lines) == 6
+    assert lines[0].startswith("╭") and lines[-1].startswith("╰")
+    assert all(len(line) == 20 for line in lines)
+    assert all(line.startswith("│") and line.endswith("│") for line in lines[1:-1])
+    assert lines[1].startswith("│hello")