Tab-stop support when spaces used for indent

src/textual/widgets/_text_area.py

@@ -213,7 +213,7 @@ class TextArea(ScrollView, can_focus=True):
     Changing this value will immediately re-render the `TextArea`."""
 
     indent_width: Reactive[int] = reactive(4)
-    """The width of tabs or the number of spaces to insert on pressing the `tab` key.
+    """The width of tabs or the multiple of spaces to align to on pressing the `tab` key.
 
     If the document currently open contains tabs that are currently visible on screen,
     altering this value will immediately change the display width of the visible tabs.
@@ -916,7 +916,7 @@ async def _on_key(self, event: events.Key) -> None:
         """Handle key presses which correspond to document inserts."""
         key = event.key
         insert_values = {
-            "tab": " " * self.indent_width if self.indent_type == "spaces" else "\t",
+            "tab": " " * self._find_columns_to_next_tab_stop(),
             "enter": "\n",
         }
         self._restart_blink()
@@ -930,6 +930,27 @@ async def _on_key(self, event: events.Key) -> None:
             start, end = self.selection
             self.replace(insert, start, end, maintain_selection_offset=False)
 
+    def _find_columns_to_next_tab_stop(self) -> int:
+        """Get the location of the next tab stop after the cursors position on the current line.
+
+        If the cursor is already at a tab stop, this returns the *next* tab stop location.
+
+        Returns:
+            The number of cells to the next tab stop from the current cursor column.
+        """
+        cursor_row, cursor_column = self.cursor_location
+        line_text = self.document[cursor_row]
+        indent_width = self.indent_width
+        if not line_text:
+            return indent_width
+
+        width_before_cursor = self.get_column_width(cursor_row, cursor_column)
+        spaces_to_insert = indent_width - (
+            (indent_width + width_before_cursor) % indent_width
+        )
+
+        return spaces_to_insert
+
     def get_target_document_location(self, event: MouseEvent) -> Location:
         """Given a MouseEvent, return the row and column offset of the event in document-space.
 

tests/text_area/test_edit_via_bindings.py

@@ -50,6 +50,35 @@ async def test_single_keypress_enter():
         assert text_area.text == "\n" + TEXT
 
 
+@pytest.mark.parametrize(
+    "content,cursor_column,cursor_destination",
+    [
+        ("", 0, 4),
+        ("x", 0, 4),
+        ("x", 1, 4),
+        ("xxx", 3, 4),
+        ("xxxx", 4, 8),
+        ("xxxxx", 5, 8),
+        ("xxxxxx", 6, 8),
+        ("💩", 1, 3),
+        ("💩💩", 2, 6),
+    ],
+)
+async def test_tab_with_spaces_goes_to_tab_stop(
+    content, cursor_column, cursor_destination
+):
+    app = TextAreaApp()
+    async with app.run_test() as pilot:
+        text_area = app.query_one(TextArea)
+        text_area.indent_width = 4
+        text_area.load_text(content)
+        text_area.cursor_location = (0, cursor_column)
+
+        await pilot.press("tab")
+
+        assert text_area.cursor_location[1] == cursor_destination
+
+
 async def test_delete_left():
     app = TextAreaApp()
     async with app.run_test() as pilot: