termcore 0.2.0__py3-none-any.whl

termcore/tui/custom_widgets/custom_data_table.py

@@ -0,0 +1,247 @@
+"""
+Extension of Textual's DataTable with support for flexible column resizing.
+
+This module defines `CustomDataTable`, a subclass of Textual's `DataTable`
+with additional capabilities for handling dynamic resizing of table columns
+based on available space.
+
+The primary enhancement is the introduction of *flexible columns* - a list of
+column keys that automatically adjust their widths when the table is resized.
+This allows developers to create responsive and adaptive data tables where
+certain columns expand or contract depending on the widget size, while others
+remain fixed.
+
+The class overrides the `on_resize` method to calculate the total available
+width and distribute it proportionally among the flexible columns. It also
+provides helper methods for determining fixed column widths and adjusting
+layout accordingly.
+
+This is particularly useful for applications with tabular data in dynamic
+layouts or where users resize windows and expect columns to adapt gracefully.
+"""
+from typing import Any, TypeVar
+
+from textual.coordinate import Coordinate
+from textual.message import Message
+from textual.widget import Widget
+from textual.widgets import DataTable
+from textual.widgets._data_table import Column, ColumnKey
+
+__all__ = [
+    "CustomDataTable",
+]
+
+_CellType = TypeVar("_CellType")
+
+
+class CustomDataTable(DataTable[_CellType]):
+    """
+    A DataTable with columns that stretch to fill the available width.
+
+    Attributes
+    ----------
+    MIN_FLEX_COL_WIDTH : int
+        Minimum width for flexible columns.
+    flexible_columns : list[ColumnKey]
+        List of column keys that should be flexible in width
+        (will be adjusted according to window width).
+    """
+
+    MIN_FLEX_COL_WIDTH = 5
+    flexible_columns: list[ColumnKey]
+
+
+    class Mounted(Message):
+        """Posted once the table has been mounted and can be filled."""
+
+        def __init__(self, sender: Widget) -> None:
+            """Records which widget was mounted."""
+            super().__init__()
+            self.sender = sender
+
+
+    def __init__(self, **kwargs: Any) -> None:  # noqa: ANN401
+        """
+        Initializes the table with an empty set of flexible columns.
+
+        The arguments are whatever `DataTable` takes, which is what Any
+        says here; naming them would mean restating fifteen parameters
+        and re-stating them again on every Textual release.
+        """
+        super().__init__(**kwargs)
+
+        # Per instance: as a class attribute every table in the process
+        # shared one list and inherited the columns of all the others.
+        self.flexible_columns = []
+
+
+    def on_mount(self) -> None:
+        """
+        Handles the mount event of the DataTable.
+
+        This method is called when the DataTable is mounted in the application.
+        It posts a Mounted message to notify that the DataTable is ready.
+        This is useful for initializing any additional functionality that
+        depends on the DataTable being fully mounted.
+
+        Examples
+        --------
+        >>> @on(CustomDataTable.Mounted)
+        >>> async def on_table_mounted(self, event: CustomDataTable.Mounted):
+        ...     # Add columns and rows to the table
+        ...     pass
+        """
+        self.post_message(self.Mounted(self))
+
+    def on_resize(self) -> None:
+        """
+        Handles the resize event of the DataTable.
+
+        Adjusts the widths of the flexible columns based on the new size of
+        the table.
+        """
+        scrollbar_width = 2 if self.show_vertical_scrollbar else 0
+        table_width = self.size.width - len(self.columns) * 2 - scrollbar_width
+        fixed_widths = self.get_fixed_column_widths()
+        self.adjust_flexible_columns(table_width, fixed_widths)
+        self.refresh()
+
+    def get_fixed_column_widths(self) -> int:
+        """
+        Returns the total width of all fixed-width columns in the table.
+
+        This is used to calculate the available width for flexible columns.
+
+        Returns
+        -------
+        int
+            The total width of all fixed-width columns.
+        """
+        fixed_widths = 0
+
+        for column_key in self.columns:
+            column: Column = self.columns[column_key]
+
+            if column_key not in self.flexible_columns:
+                fixed_widths += column.width
+
+        return fixed_widths
+
+    def adjust_flexible_columns(self, table_width: int, fixed_width: int) \
+    -> None:
+        """
+        Adjusts the flexible columns to the width the table has.
+
+        Parameters
+        ----------
+        table_width : int
+            The total width of the table.
+        fixed_width : int
+            The total width of all fixed-width columns.
+        """
+        for column_key in self.columns:
+            column: Column = self.columns[column_key]
+
+            if column_key in self.flexible_columns:
+                column.auto_width = False
+                column.width = int(
+                    (table_width - fixed_width) / len(self.flexible_columns)
+                )
+
+                # Don't allow column width to be less than MIN_FLEX_COL_WIDTH
+                column.width = max(column.width, self.MIN_FLEX_COL_WIDTH)
+
+        self.update_virtual_size()
+
+    def update_virtual_size(self) -> None:
+        """
+        Updates the virtual size from the current column widths.
+
+        This is what makes the horizontal scrollbar appear only when it is
+        actually needed.
+
+        The effect of this method is that the DataTable has the correct width
+        (no hidden column at the right side "compensating" the reduced widths
+        of the flexible columns) and that the horizontal scrollbar only appears
+        when the total width of all columns exceeds the visible width of
+        the DataTable widget.
+
+        The actual total width of all columns including separators is
+        calculated by the following formula:
+
+        ```
+        total_width = sum(column_widths) + (num_columns * 2 - 2)
+        ```
+
+        Notes
+        -----
+        Explanation:
+
+            - Each column has 2 pixels of spacing (padding/border)
+            - With n columns, there are (n-1) separators between columns
+            - The first column has left padding and the last has right padding
+            - This results in: `2 * (n-1) + 2 = 2n - 2 + 2 = 2n` pixels total
+            - However, empirically it's necessary to subtract 2 pixels to
+              account for the table's own border/padding, giving: `2n - 2`
+
+            Example with 4 columns: `4 * 2 - 2 = 6` pixels for separators
+        """
+        # Calculate total width of all columns including separators
+        total_column_width = sum(col.width for col in self.columns.values())
+        total_width_with_separators = total_column_width \
+                                      + (len(self.columns) * 2 - 2)
+
+        # Update virtual size of the DataTable to reflect new width
+        self.virtual_size = self.virtual_size._replace(
+            width=total_width_with_separators
+        )
+
+    def update_scrollbar_visibility(self) -> None:
+        """
+        Shows or hides the horizontal scrollbar based on the content width.
+
+        .. deprecated::
+            This method is no longer needed.
+
+        Scrollbar visibility is now automatically managed by the
+        `update_virtual_size()` method, which correctly sets the virtual
+        size of the table. The horizontal scrollbar will only appear when
+        the content width exceeds the table width.
+
+        Notes
+        -----
+        TODO: Remove this method in future versions.
+        """
+        total_content_width = sum(col.width for col in self.columns.values())
+
+        self.styles.scrollbar_size_horizontal = (
+            None if total_content_width > self.size.width else 0
+        )
+
+    def select_first_row(self) -> None:
+        """Selects the first row and posts a RowHighlighted event."""
+        if self.row_count == 0:
+            return
+
+        # Set cursor to first row
+        self.cursor_coordinate = Coordinate(0, 0)
+        self.move_cursor(row=0, column=0)  # Same as above, just to be sure
+
+        # Manually post RowHighlighted event
+        row_key, _ = self.coordinate_to_cell_key(self.cursor_coordinate)
+        self.post_message(
+            DataTable.RowHighlighted(self, self.cursor_row, row_key)
+        )
+
+    def delete_selected_row(self) -> None:
+        """Deletes the currently selected row from the table."""
+        if self.row_count > 0:
+            row_key, _ = self.coordinate_to_cell_key(self.cursor_coordinate)
+            self.remove_row(row_key)
+
+    # def get_current_id(self) -> int:
+    #     Returns the ID of the currently selected topic.
+
+    #     Returns:
+    #         int: The ID of the currently selected topic.
+

termcore/tui/custom_widgets/custom_selection.py

@@ -0,0 +1,80 @@
+"""A Textual SelectionList that shows check marks instead of X marks."""
+
+from typing import TypeVar
+
+from rich.segment import Segment
+from textual.strip import Strip
+from textual.widgets import SelectionList
+from textual.widgets._toggle_button import ToggleButton
+
+__all__ = [
+    "CustomSelectionList",
+]
+
+_SelectionType = TypeVar("_SelectionType")
+
+
+class CustomSelectionList(SelectionList[_SelectionType]):
+    """
+    A Textual SelectionList whose items show a check mark when selected.
+
+    If unselected, they show an empty box - instead of the default
+    behavior of showing an "X".
+
+    Attributes
+    ----------
+    CUSTOM_BUTTON_INNER : str
+        The character to display when an item is selected.
+    """
+
+    CUSTOM_BUTTON_INNER = "✔"
+
+
+    def render_line(self, y: int) -> Strip:
+        """
+        Renders one line, with check marks instead of X marks.
+
+        Parameters
+        ----------
+        y : int
+            The line number to render.
+
+        Returns
+        -------
+        Strip
+            A Strip representing the rendered line.
+        """
+        # Get the default rendered line from the parent class (SelectionList)
+        rendered_line: Strip = super().render_line(y)
+
+        # rendered_line contains the segments for the line including the
+        # check box representation. This segment needs to be modified to
+        # replace the default "X" with a custom check mark when selected.
+        # Since rendered_line is immutable, a new list of segments is created.
+        segments: list[Segment] = []
+
+        # Loop through each segment in the rendered line
+        for segment in rendered_line:
+            # Check if the segment text matches the default button inner
+            # (= the one that must be modified)
+            if segment.text == ToggleButton.BUTTON_INNER:
+                # Check if segment is selected
+                _, scroll_y = self.scroll_offset
+                selection_index = scroll_y + y
+                selection = self.get_option_at_index(selection_index)
+                if selection.value in self._selected:
+                    segment_text = self.CUSTOM_BUTTON_INNER
+                else:
+                    segment_text = " "
+
+                # Create a new segment with the custom check mark and same style
+                segment_style = segment.style
+                new_segment = Segment(segment_text, segment_style)
+                segments.append(new_segment)
+            else:
+                # Not the segment containing the check box -> keep segment as is
+                segments.append(segment)
+
+        return Strip([
+            *segments
+        ])

termcore/tui/custom_widgets/multiline_footer.py

@@ -0,0 +1,240 @@
+"""
+MultiLineFooter - a multi-line footer extending Textual's built-in Footer.
+
+Two modes:
+
+  1. auto_wrap=True   → Bindings automatically wrap when the row is full.
+  2. auto_wrap=False  → Bindings are explicitly assigned to rows via `row_map`.
+
+Usage:
+    # Auto-wrap (default)
+    yield MultiLineFooter()
+
+    # Manual row assignment
+    yield MultiLineFooter(
+        auto_wrap=False,
+        row_map={
+            "quit": 0,
+            "save": 0,
+            "toggle_dark": 1,
+            "help": 1,
+        },
+    )
+
+The `row_map` maps binding actions to row numbers (0-based).
+Unassigned bindings fall into the last defined row.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import cast, override
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.containers import HorizontalGroup
+from textual.reactive import reactive
+from textual.widgets._footer import Footer, FooterKey
+
+__all__ = [
+    "FooterRow",
+    "MultiLineFooter",
+]
+
+
+class FooterRow(HorizontalGroup):
+    """Horizontal row containing FooterKey widgets."""
+
+    DEFAULT_CSS: str = """
+    FooterRow {
+        width: 1fr;
+        height: 1;
+        layout: horizontal;
+        background: $footer-background;
+    }
+    """
+
+
+class MultiLineFooter(Footer):
+    """
+    Multi-line footer with auto-wrap or manual row assignment.
+
+    Inherits from Textual's built-in Footer and overrides the layout to support
+    multiple rows.
+
+    Attributes
+    ----------
+    auto_wrap : bool, default True
+        If True, bindings wrap automatically based on terminal width.
+    row_map : dict[str, int] or None, optional
+        Dict mapping action names to row numbers (0-based).
+        Only relevant when ``auto_wrap=False``.
+    max_rows : int, default 0
+        Maximum number of rows for auto-wrap. 0 means unlimited.
+    show_command_palette : bool, default True
+        Show the command palette binding.
+    compact : bool, default False
+        Use compact styling with less whitespace.
+    """
+
+    DEFAULT_CSS: str = """
+    MultiLineFooter {
+        height: auto;
+        layout: vertical;
+        scrollbar-size: 0 0;
+    }
+    """
+
+    auto_wrap: reactive[bool] = reactive(default=True)
+    max_rows: reactive[int] = reactive(0)
+    _bindings_ready: bool
+
+    def __init__(  # noqa: PLR0913 - mirrors Textual's Widget signature
+        self,
+        *,
+        auto_wrap: bool = True,
+        row_map: dict[str, int] | None = None,
+        max_rows: int = 0,
+        show_command_palette: bool = True,
+        compact: bool = False,
+        name: str | None = None,
+        id: str | None = None,  # noqa: A002 - Textual's parameter name
+        classes: str | None = None,
+    ) -> None:
+        super().__init__(
+            name=name,
+            id=id,
+            classes=classes,
+            show_command_palette=show_command_palette,
+            compact=compact,
+        )
+        self._row_map: dict[str, int] = row_map or {}
+        self.set_reactive(MultiLineFooter.auto_wrap, auto_wrap)
+        self.set_reactive(MultiLineFooter.max_rows, max_rows)
+
+    @staticmethod
+    def _estimate_key_width(key_display: str, description: str) -> int:
+        """Estimates the width of a FooterKey in columns (including padding)."""
+        w = 1 + len(key_display) + 1   # key padding
+        if description:
+            w += len(description) + 1  # description + right padding
+        return w
+
+    def _collect_bindings(self) -> list[tuple[Binding, bool, str]]:
+        """Collects active visible bindings, excluding the command palette."""
+        active = self.screen.active_bindings
+        app = cast("App[object]", self.app)
+        palette_key = (
+            app.COMMAND_PALETTE_BINDING
+            if self.show_command_palette and app.ENABLE_COMMAND_PALETTE
+            else None
+        )
+        return [
+            (binding, enabled, tooltip)
+            for key_str, (_node, binding, enabled, tooltip) in active.items()
+            if binding.show and key_str != palette_key
+        ]
+
+    def _get_palette_binding(self) -> tuple[Binding, bool, str] | None:
+        """Returns the command palette binding tuple or None."""
+        app = cast("App[object]", self.app)
+        if not (self.show_command_palette and app.ENABLE_COMMAND_PALETTE):
+            return None
+        try:
+            _node, binding, enabled, tooltip = self.screen.active_bindings[
+                app.COMMAND_PALETTE_BINDING
+            ]
+        except KeyError:
+            return None
+        return binding, enabled, tooltip
+
+    def _build_rows_auto(
+        self, bindings: list[tuple[Binding, bool, str]]
+    ) -> list[list[tuple[Binding, bool, str]]]:
+        """Distributes bindings across rows based on available width."""
+        available = self.size.width or 80
+        rows: list[list[tuple[Binding, bool, str]]] = [[]]
+        current_width = 0
+
+        app = cast("App[object]", self.app)
+        for binding, enabled, tooltip in bindings:
+            key_display = app.get_key_display(binding)
+            w = self._estimate_key_width(key_display, binding.description) + 1
+            if current_width + w > available and rows[-1]:
+                if self.max_rows > 0 and len(rows) >= self.max_rows:
+                    rows[-1].append((binding, enabled, tooltip))
+                    current_width += w
+                    continue
+                rows.append([])
+                current_width = 0
+            rows[-1].append((binding, enabled, tooltip))
+            current_width += w
+
+        return rows
+
+    def _build_rows_manual(
+        self, bindings: list[tuple[Binding, bool, str]]
+    ) -> list[list[tuple[Binding, bool, str]]]:
+        """Distributes bindings across rows using the row_map."""
+        grouped: defaultdict[int, list[tuple[Binding, bool, str]]] = \
+            defaultdict(list)
+        fallback_row = max(self._row_map.values(), default=0)
+
+        for binding, enabled, tooltip in bindings:
+            grouped[self._row_map.get(binding.action, fallback_row)].append(
+                (binding, enabled, tooltip)
+            )
+        if not grouped:
+            return []
+        return [grouped[i] for i in sorted(grouped.keys())]
+
+    @override
+    def compose(self) -> ComposeResult:
+        if not self._bindings_ready:
+            return
+
+        app = cast("App[object]", self.app)
+        bindings = self._collect_bindings()
+        rows = (
+            self._build_rows_auto(bindings)
+            if self.auto_wrap
+            else self._build_rows_manual(bindings)
+        )
+        palette = self._get_palette_binding()
+
+        for row_idx, row_bindings in enumerate(rows):
+            with FooterRow():
+                for binding, enabled, tooltip in row_bindings:
+                    yield FooterKey(
+                        binding.key,
+                        app.get_key_display(binding),
+                        binding.description,
+                        binding.action,
+                        disabled=not enabled,
+                        tooltip=tooltip or binding.description,
+                    ).data_bind(compact=Footer.compact)
+                # Place the command palette in the first row
+                # if row_idx == 0 and palette:
+                # Place the command palette in the last row
+                if row_idx == len(rows) - 1 and palette:
+                    b, en, tt = palette
+                    yield FooterKey(
+                        b.key,
+                        app.get_key_display(b),
+                        b.description,
+                        b.action,
+                        disabled=not en,
+                        tooltip=tt or b.description,
+                        classes="-command-palette",
+                    )
+
+    @override
+    def on_mount(self) -> None:
+        super().on_mount()
+        # Trigger initial render (needed when the footer is mounted late)
+        self._bindings_ready = True
+        _ = self.call_after_refresh(self.recompose)
+
+    def on_resize(self) -> None:
+        """Re-wraps on terminal resize (auto-wrap mode only)."""
+        if self.auto_wrap and self._bindings_ready:
+            _ = self.call_after_refresh(self.recompose)

termcore/tui/question_screen.py

@@ -0,0 +1,107 @@
+"""
+A modal screen that asks a yes/no question and returns the answer.
+
+The screen displays a customizable question and two buttons labeled "Yes"
+and "No". It uses Textual's event system to handle user interactions and
+returns `True` or `False` accordingly. The button colors can be configured using
+the `ButtonColor` enum, allowing visual emphasis (e.g., marking "Yes" as
+destructive in red or "No" as a safe action in blue).
+
+The screen can be dismissed using the escape key or by clicking a button. It is
+ideal for confirmation dialogs, safety prompts or binary decision points within
+an application UI.
+"""
+from enum import Enum
+from typing import ClassVar
+
+from textual import on
+from textual.app import ComposeResult
+from textual.binding import BindingType
+from textual.containers import Grid
+from textual.screen import ModalScreen
+from textual.widgets import Button, Label
+
+__all__ = [
+    "ButtonColor",
+    "QuestionScreen",
+]
+
+
+class ButtonColor(Enum):
+    """Enum for button colors."""
+
+    DEFAULT = "default"
+    PRIMARY = "primary"
+    ERROR = "error"
+    SUCCESS = "success"
+    WARNING = "warning"
+
+
+class QuestionScreen(ModalScreen[bool]):
+    """A screen that asks a question and returns a boolean answer."""
+
+    yes_button_color: ButtonColor
+    no_button_color: ButtonColor
+    BINDINGS: ClassVar[list[BindingType]] = [
+        ("escape", "close_modal", "Close"),
+    ]
+    CSS = """
+        QuestionScreen {
+            align: center middle;
+        }
+
+        QuestionScreen #dialog {
+            grid-size: 2;
+            grid-gutter: 1 2;
+            grid-rows: 1fr 3;
+            padding: 0 1;
+            width: 60;
+            height: 11;
+            border: thick $background 80%;
+            background: $surface;
+        }
+
+        QuestionScreen #question {
+            column-span: 2;
+            height: 1fr;
+            width: 1fr;
+            content-align: center middle;
+        }
+
+        QuestionScreen Button {
+            width: 100%;
+        }
+    """
+
+
+    def __init__(self, question: str,
+                 yes_button_color: ButtonColor = ButtonColor.ERROR,
+                 no_button_color: ButtonColor = ButtonColor.PRIMARY) -> None:
+        """Initialize the QuestionScreen with a question."""
+        self.question = question
+        self.yes_button_color = yes_button_color
+        self.no_button_color = no_button_color
+        super().__init__()
+
+    def compose(self) -> ComposeResult:
+        """Compose the screen layout."""
+        yield Grid(
+            Label(self.question, id="question"),
+            Button("Yes", variant=self.yes_button_color.value, id="yes"),
+            Button("No", variant=self.no_button_color.value, id="no"),
+            id="dialog",
+        )
+
+    def action_close_modal(self) -> None:
+        """Closes the modal popup."""
+        self.dismiss(result=False)
+
+    @on(Button.Pressed, "#yes")
+    def handle_yes(self) -> None:
+        """Handle the "Yes" button press."""
+        self.dismiss(result=True)
+
+    @on(Button.Pressed, "#no")
+    def handle_no(self) -> None:
+        """Handle the "No" button press."""
+        self.dismiss(result=False)