Skip to content

tui: keep key bindings discoverable in narrow terminals #79

Description

@abhiksark

Motivation

Keyboard actions continue to work in a narrow terminal, but the footer hides several essential bindings. A keyboard-only learner cannot discover topic navigation, documentation, or quit keys from the visible interface.

Current evidence

A 40 by 15 Textual pilot on dev at e1d4dae37234b75124bd6a53f06734296ebbbdee completed the full keyboard flow, but the track footer visibly stopped after F3:

visible: F1 Hint, F2 Reset, F3 List
clipped: F4 Topics, F5 Docs, Escape Quit, Ctrl+Q Quit

F4, F5, and Escape still executed correctly, so this is a responsive discoverability defect rather than broken key handling.

Exact scope

Provide a compact or otherwise accessible binding presentation when the footer cannot fit the normal labels. Keep the existing keys and actions unchanged.

Acceptance checklist

  • A 40-column track screen exposes a discoverable route to F4, F5, and quit actions.
  • Topic picker and documentation screens retain discoverable close or quit actions at the same size.
  • The normal-width footer retains its current useful labels.
  • Existing F1 through F5, Escape, and Ctrl+Q behavior is unchanged.
  • A Textual pilot or snapshot test covers the narrow presentation.
  • Keyboard-only navigation still completes the picker, track, docs, and exit flow.

Explicit exclusions

Do not change key assignments, remove footer help at normal widths, redesign the main three-pane layout, or add mouse-only controls.

Likely files

  • pythonlings/screens/track.py
  • pythonlings/screens/topic_picker.py
  • pythonlings/screens/docs.py
  • pythonlings/pythonlings.tcss
  • tests/tui/test_app_pilot.py

Verification

python -m pytest tests/tui -q
python -m pytest -q
pythonlings --root tests/fixtures/passing_curriculum verify

Exercise the complete keyboard flow at 40 by 15 and at a normal terminal size.

Sprint coordination

See Discussion #37 and tracker #52. This issue is intentionally unassigned. A coordination comment is welcome, but it does not reserve the issue. The first pull request that satisfies every acceptance criterion and verification requirement is considered for merge.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: tuiTextual terminal user interfacebugSomething isn't workingdev sprintPythonlings Community Dev Sprint August 2026good first issueGood for newcomershelp wantedExtra attention is neededsize: SSmall, focused contribution

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions