textual-widgets 0.32.1__py3-none-any.whl

textual_widgets/__init__.py

@@ -0,0 +1,110 @@
+"""Wiederverwendbare Textual-Widgets."""
+
+__version__ = "0.32.1"
+__author__ = "Michael Blaess"
+
+from textual_widgets.about_screen import AboutScreen, Quote, load_quotes
+from textual_widgets.clearable_input import ClearableInput
+from textual_widgets.clickable_links import ClickableLinksMixin
+from textual_widgets.context_menu import ContextMenuItem, ContextMenuScreen
+from textual_widgets.crash_guard import CrashGuard, ErrorScreen
+from textual_widgets.date_picker import CalendarGrid, DatePicker, DatePickerScreen
+from textual_widgets.disclaimer_screen import (
+    DISCLAIMER_VERSION,
+    DisclaimerScreen,
+    DisclaimerStore,
+    disclaimer_text,
+)
+from textual_widgets.hamburger_menu import HamburgerItem, HamburgerMenu
+from textual_widgets.http_status_screen import HttpStatusScreen
+from textual_widgets.info_header import InfoAction, InfoHeader, InfoItem
+from textual_widgets.keymap import (
+    COMMON_FUNCTION_KEYS,
+    PROTECTED_ACTIONS,
+    VIM_NAVIGATION,
+    KeyBinding,
+    KeymapProblem,
+    KeymapStyle,
+    ResolvedKeymap,
+    default_style_for_platform,
+    find_collisions,
+    function_key_number,
+    parse_overrides,
+    resolve_keymap,
+    sort_for_footer,
+    vim_navigation_bindings,
+)
+from textual_widgets.log_panel import LogMessage, LogPanel, LogRouter
+from textual_widgets.search_history_dropdown import (
+    SearchHistoryDropdown,
+    SearchInputWithHistory,
+)
+from textual_widgets.settings_screen import BaseSettingsScreen
+from textual_widgets.splitter import HorizontalSplitter, VerticalSplitter
+from textual_widgets.status_bar import StatusBar, StatusItem
+from textual_widgets.terminal_image import (
+    TerminalImage,
+    als_halbbloecke,
+    erkenne_protokoll,
+    vorab_initialisieren,
+)
+from textual_widgets.terminal_title import reset_terminal_title, set_terminal_title
+from textual_widgets.text_input_screen import TextInputScreen
+from textual_widgets.url_input_screen import UrlInputScreen
+
+__all__ = [
+    "AboutScreen",
+    "BaseSettingsScreen",
+    "CalendarGrid",
+    "ClearableInput",
+    "ClickableLinksMixin",
+    "ContextMenuItem",
+    "ContextMenuScreen",
+    "CrashGuard",
+    "COMMON_FUNCTION_KEYS",
+    "DatePicker",
+    "DISCLAIMER_VERSION",
+    "DatePickerScreen",
+    "DisclaimerScreen",
+    "DisclaimerStore",
+    "disclaimer_text",
+    "ErrorScreen",
+    "HamburgerItem",
+    "HamburgerMenu",
+    "HorizontalSplitter",
+    "HttpStatusScreen",
+    "InfoAction",
+    "InfoHeader",
+    "InfoItem",
+    "KeyBinding",
+    "KeymapProblem",
+    "KeymapStyle",
+    "LogMessage",
+    "LogPanel",
+    "LogRouter",
+    "Quote",
+    "PROTECTED_ACTIONS",
+    "ResolvedKeymap",
+    "SearchHistoryDropdown",
+    "SearchInputWithHistory",
+    "StatusBar",
+    "StatusItem",
+    "TerminalImage",
+    "VIM_NAVIGATION",
+    "als_halbbloecke",
+    "erkenne_protokoll",
+    "vorab_initialisieren",
+    "TextInputScreen",
+    "UrlInputScreen",
+    "VerticalSplitter",
+    "load_quotes",
+    "default_style_for_platform",
+    "find_collisions",
+    "reset_terminal_title",
+    "parse_overrides",
+    "function_key_number",
+    "resolve_keymap",
+    "sort_for_footer",
+    "vim_navigation_bindings",
+    "set_terminal_title",
+]

textual_widgets/about_screen.py

@@ -0,0 +1,346 @@
+"""Standardisierter About-Dialog fuer Textual-Apps.
+
+Public API:
+    - `Quote` — Dataclass fuer ein Zitat (text, author).
+    - `load_quotes(lang)` — laedt den mitgelieferten Zitatpool (de/en).
+    - `AboutScreen` — ModalScreen mit einheitlichem Aufbau:
+
+        Headline
+        version - Autor - Release-Datum
+        Beschreibung
+        --- (Trenner, passt sich automatisch der Dialogbreite an)
+        Zitat
+        URL (optional, anklickbar)
+        ESC = Close
+
+Usage:
+    from textual_widgets import AboutScreen
+
+    def action_show_about(self) -> None:
+        self.push_screen(AboutScreen(
+            app_name="my-tool",
+            version=__version__,
+            author=__author__,
+            release=__year__,
+            description="Beschreibung.\\nZweite Zeile.",
+            lang="de",
+        ))
+
+Das Zitat wird bei jedem Oeffnen zufaellig aus dem Pool gewaehlt. Apps koennen
+mit `quote=` ein festes Zitat oder mit `quotes=` eine eigene Liste vorgeben.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+from dataclasses import dataclass
+from importlib import resources
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Center, VerticalScroll
+from textual.events import Click
+from textual.screen import ModalScreen
+from textual.widgets import Button, Rule, Static
+
+# Default-Beschriftung des Schliessen-Buttons pro Sprache.
+_FOOTER_TEXT = {
+    "de": "Schließen (ESC)",
+    "en": "Close (ESC)",
+}
+
+# Breiten-Schranken des Dialogs (Inhaltsbreite + Border + Padding).
+_MIN_WIDTH = 44
+_MAX_WIDTH = 92
+
+
+@dataclass(frozen=True)
+class Quote:
+    """Ein Zitat mit Urheber.
+
+    Attributes:
+        text:
+            Der Zitattext. Darf Zeilenumbrueche enthalten.
+        author:
+            Name des Urhebers (z.B. "Emily Dickinson").
+    """
+
+    text: str
+    author: str
+
+
+def load_quotes(lang: str = "en") -> list[Quote]:
+    """Laedt den mitgelieferten Zitatpool fuer eine Sprache.
+
+    Args:
+        lang:
+            Sprachkuerzel ('de' oder 'en'). Bei unbekannter Sprache wird
+            der englische Pool zurueckgegeben.
+
+    Returns:
+        Liste der Zitate. Leer, wenn die quotes.json fehlt oder unlesbar ist.
+    """
+    try:
+        raw = (resources.files("textual_widgets") / "quotes" / "quotes.json").read_text(encoding="utf-8")
+        data = json.loads(raw)
+    except Exception:
+        return []
+
+    pool = data.get(lang) or data.get("en") or []
+    return [
+        Quote(text=str(entry["text"]), author=str(entry["author"]))
+        for entry in pool
+        if "text" in entry and "author" in entry
+    ]
+
+
+class AboutScreen(ModalScreen[None]):
+    """Standardisierter About-Dialog als ModalScreen.
+
+    Schliessen ueber ESC oder Klick ausserhalb des Dialogs. Die Dialogbreite
+    wird beim Mount aus der laengsten Inhaltszeile berechnet, sodass der
+    Trenner exakt buendig sitzt und kein Whitespace entsteht.
+    """
+
+    DEFAULT_CSS = """
+    AboutScreen {
+        align: center middle;
+    }
+
+    AboutScreen > VerticalScroll {
+        height: auto;
+        max-height: 90%;
+        background: $surface;
+        border: thick $accent;
+        padding: 1 2;
+    }
+
+    AboutScreen #about-title {
+        width: 1fr;
+        height: 3;
+        content-align: center middle;
+        text-style: bold;
+        background: $accent;
+        color: auto;
+        margin-bottom: 1;
+    }
+
+    AboutScreen #about-meta {
+        width: 1fr;
+        text-align: center;
+        margin-bottom: 1;
+    }
+
+    AboutScreen #about-description {
+        width: 1fr;
+    }
+
+    /* Rule fuellt mit width: 1fr exakt die (explizit gesetzte) Dialogbreite */
+    AboutScreen Rule {
+        width: 1fr;
+        color: $text-muted;
+        margin: 1 0;
+    }
+
+    AboutScreen #about-quote {
+        width: 1fr;
+    }
+
+    AboutScreen #about-url, AboutScreen #about-homepage-url {
+        width: 1fr;
+        content-align: center middle;
+        color: $accent;
+        margin-top: 1;
+    }
+
+    /* Homepage steht direkt unter der Repo-URL - kein doppeltes margin. */
+    AboutScreen #about-homepage-url {
+        margin-top: 0;
+    }
+
+    AboutScreen #about-footer {
+        width: 1fr;
+        height: auto;
+        margin-top: 1;
+    }
+    """
+
+    BINDINGS = [
+        Binding("escape", "close", "ESC"),
+    ]
+
+    def __init__(
+        self,
+        *,
+        app_name: str,
+        version: str,
+        author: str,
+        release: str,
+        description: str,
+        lang: str = "en",
+        license: str | None = None,
+        quote: Quote | None = None,
+        quotes: list[Quote] | None = None,
+        url: str | None = None,
+        homepage_url: str | None = "https://www.michaelblaess.de/",
+        footer: str | None = None,
+    ) -> None:
+        """Erstellt den About-Dialog.
+
+        Args:
+            app_name:
+                Name der Anwendung (Headline-Balken).
+            version:
+                Versionsnummer ohne fuehrendes 'v' (z.B. "1.2.0"). Der Dialog
+                stellt das 'v' selbst voran.
+            author:
+                Name des Autors.
+            release:
+                Release-Datum oder -Jahr (z.B. "2026").
+            description:
+                Beschreibungstext. Darf Zeilenumbrueche enthalten.
+            lang:
+                Sprachkuerzel ('de' oder 'en') fuer Footer und Zitatpool.
+            license:
+                Optionale Lizenzangabe (z.B. "Apache 2.0"). Wird als letztes
+                Element an die Meta-Zeile angehaengt.
+            quote:
+                Optionales festes Zitat. Wenn gesetzt, wird kein zufaelliges
+                Zitat aus dem Pool gewaehlt.
+            quotes:
+                Optionale eigene Zitatliste. Wird statt des mitgelieferten
+                Pools verwendet (zufaellige Auswahl).
+            url:
+                Optionale Projekt-/Repo-URL. Wird unter dem Zitat als
+                anklickbarer Link angezeigt (Klick oeffnet im Browser).
+            homepage_url:
+                Optionale zweite URL (Autor/Homepage), die direkt unter
+                ``url`` als anklickbarer Link erscheint. Default zeigt auf
+                die Homepage des Autors; mit ``None`` ausblenden.
+            footer:
+                Optionaler Footer-Text. Default ist das sprachabhaengige
+                "ESC = Schliessen" / "ESC = Close".
+        """
+        super().__init__()
+        self._app_name = app_name
+        self._version = version.lstrip("v")
+        self._author = author
+        self._release = release
+        self._description = description.rstrip("\n")
+        self._license = license
+        self._url = url
+        self._homepage_url = homepage_url
+        self._lang = lang if lang in _FOOTER_TEXT else "en"
+        self._footer = footer if footer is not None else _FOOTER_TEXT[self._lang]
+
+        # Zitat bestimmen: explizit > eigene Liste > mitgelieferter Pool
+        if quote is not None:
+            self._quote: Quote | None = quote
+        else:
+            pool = quotes if quotes else load_quotes(self._lang)
+            self._quote = random.choice(pool) if pool else None
+
+    def compose(self) -> ComposeResult:
+        """Erstellt das Modal-Layout."""
+        with VerticalScroll(id="about-dialog"):
+            yield Static(self._app_name, id="about-title")
+            yield Static(self._build_meta(), id="about-meta")
+            yield Static(self._description, id="about-description")
+            if self._quote is not None:
+                yield Rule(line_style="solid")
+                yield Static(self._build_quote(self._quote), id="about-quote")
+            if self._url:
+                # Klickbar ohne CTRL + Hover-Highlight via Textual-Action-Markup.
+                yield Static(
+                    f"[@click=screen.open_about_url('repo')][underline]{self._url}[/underline][/]",
+                    id="about-url",
+                    markup=True,
+                )
+            if self._homepage_url:
+                yield Static(
+                    f"[@click=screen.open_about_url('homepage')][underline]{self._homepage_url}[/underline][/]",
+                    id="about-homepage-url",
+                    markup=True,
+                )
+            with Center(id="about-footer"):
+                yield Button(self._footer, variant="primary", id="about-close")
+
+    def on_mount(self) -> None:
+        """Setzt die Dialogbreite anhand der laengsten Inhaltszeile.
+
+        Ohne explizite Breite blaeht ein `width: 1fr`-Kind (Rule) den
+        `width: auto`-Container bis zur Bildschirmbreite auf.
+        """
+        self.query_one("#about-dialog").styles.width = self._dialog_width()
+
+    def _build_meta(self) -> Text:
+        """Baut die Meta-Zeile 'version - Autor - Release - Lizenz'."""
+        text = Text()
+        text.append(f"v{self._version}", style="bold")
+        text.append("   ·   ", style="dim")
+        text.append(self._author, style="bold")
+        text.append("   ·   ", style="dim")
+        text.append(self._release, style="bold")
+        if self._license:
+            text.append("   ·   ", style="dim")
+            text.append(self._license, style="bold")
+        return text
+
+    @staticmethod
+    def _build_quote(quote: Quote) -> Text:
+        """Baut das Zitat samt Urheber als Rich Text."""
+        text = Text()
+        text.append(quote.text, style="italic")
+        text.append("\n\n")
+        text.append(f"- {quote.author}", style="bold")
+        return text
+
+    def action_open_about_url(self, target: str = "repo") -> None:
+        """Oeffnet die zur AboutScreen gehoerige URL im Browser.
+
+        Args:
+            target:
+                ``"repo"`` fuer die Projekt-/Repo-URL (Default),
+                ``"homepage"`` fuer die Autor-Homepage.
+        """
+        import contextlib
+        import webbrowser
+
+        url = self._homepage_url if target == "homepage" else self._url
+        if not url:
+            return
+        with contextlib.suppress(Exception):
+            webbrowser.open(url)
+
+    def _dialog_width(self) -> int:
+        """Berechnet die Dialogbreite aus der laengsten Inhaltszeile."""
+        lines: list[str] = [self._app_name, self._build_meta().plain]
+        lines += self._description.split("\n")
+        if self._quote is not None:
+            lines += self._quote.text.split("\n")
+            lines.append(f"- {self._quote.author}")
+        if self._url:
+            lines.append(self._url)
+        if self._homepage_url:
+            lines.append(self._homepage_url)
+        lines.append(self._footer)
+
+        content = max((len(line) for line in lines), default=0)
+        # + 2 Border (thick) + 4 Container-Padding (padding: 1 2)
+        return max(_MIN_WIDTH, min(_MAX_WIDTH, content + 6))
+
+    def on_click(self, event: Click) -> None:
+        """Klick ausserhalb des Dialogs schliesst ihn."""
+        widget, _ = self.get_widget_at(event.screen_x, event.screen_y)
+        if widget is self:
+            self.dismiss(None)
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        """Schliesst den Dialog beim Klick auf den Schliessen-Button."""
+        self.dismiss(None)
+
+    def action_close(self) -> None:
+        """Schliesst den Dialog (ESC)."""
+        self.dismiss(None)

textual_widgets/clearable_input.py

@@ -0,0 +1,136 @@
+"""Eingabefeld mit einem Knopf zum Leeren.
+
+Textuals ``Input`` hat dafuer nichts - es kennt nur die Methode ``clear()``.
+Wer den Knopf will, baut ihn sonst in jeder Anwendung neu daneben.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from textual import on
+from textual.app import ComposeResult
+from textual.containers import Horizontal
+from textual.message import Message
+from textual.widgets import Button, Input
+
+SYMBOL = "X"
+"""Vorgabe-Zeichen auf dem Knopf.
+
+Bewusst ein lateinisches X: das Multiplikationszeichen sieht schoener aus,
+ist aber mehrdeutig (ruff RUF001) und in manchen Schriften zwei Zellen breit.
+"""
+
+
+class ClearableInput(Horizontal):
+    """Ein ``Input`` mit Leeren-Knopf daneben.
+
+    Der Knopf leert das Feld selbst und setzt den Fokus zurueck - wer mehr
+    braucht, faengt ``ClearableInput.Cleared`` ab.
+    """
+
+    DEFAULT_CSS = """
+    ClearableInput {
+        height: auto;
+    }
+    ClearableInput > Input {
+        width: 1fr;
+    }
+    ClearableInput > Button {
+        width: 5;
+        min-width: 5;
+    }
+    """
+
+    class Cleared(Message):
+        """Das Feld wurde ueber den Knopf geleert."""
+
+        def __init__(self, eingabe: ClearableInput) -> None:
+            super().__init__()
+            self.eingabe = eingabe
+
+        @property
+        def control(self) -> ClearableInput:
+            return self.eingabe
+
+    def __init__(
+        self,
+        *,
+        placeholder: str = "",
+        value: str = "",
+        symbol: str = SYMBOL,
+        tooltip: str = "",
+        input_id: str = "clearable-input",
+        button_id: str = "clearable-clear",
+        **kwargs: Any,
+    ) -> None:
+        """Legt Feld und Knopf an.
+
+        Args:
+            placeholder: Platzhaltertext des Eingabefelds.
+            value: Anfangswert.
+            symbol: Beschriftung des Knopfs, etwa ``"X"`` oder ``"⌫"``.
+            tooltip: Hinweis am Knopf.
+            input_id: ID des inneren ``Input``.
+            button_id: ID des Knopfs.
+        """
+        super().__init__(**kwargs)
+        self._placeholder = placeholder
+        self._value = value
+        self._symbol = symbol
+        self._tooltip = tooltip
+        self._input_id = input_id
+        self._button_id = button_id
+
+    def compose(self) -> ComposeResult:
+        yield Input(placeholder=self._placeholder, value=self._value, id=self._input_id)
+        knopf = Button(self._symbol, id=self._button_id)
+        # Der Knopf soll den Fokus nicht aus dem Feld ziehen.
+        knopf.can_focus = False
+        if self._tooltip:
+            knopf.tooltip = self._tooltip
+        yield knopf
+
+    # -- oeffentlich ----------------------------------------------------
+
+    @property
+    def input(self) -> Input:
+        """Das innere Eingabefeld."""
+        return self.query_one(f"#{self._input_id}", Input)
+
+    @property
+    def value(self) -> str:
+        return self.input.value
+
+    @value.setter
+    def value(self, text: str) -> None:
+        self.input.value = text
+
+    @property
+    def disabled_input(self) -> bool:
+        """Ob Feld und Knopf gesperrt sind."""
+        return bool(self.input.disabled)
+
+    def set_disabled(self, gesperrt: bool) -> None:
+        """Sperrt oder entsperrt Feld und Knopf gemeinsam."""
+        self.input.disabled = gesperrt
+        self.query_one(f"#{self._button_id}", Button).disabled = gesperrt
+
+    def clear(self) -> None:
+        """Leert das Feld, ohne eine Nachricht zu senden."""
+        self.input.value = ""
+
+    def focus_input(self) -> None:
+        """Setzt den Fokus ins Feld."""
+        self.input.focus()
+
+    # -- intern ---------------------------------------------------------
+
+    @on(Button.Pressed)
+    def _geleert(self, ereignis: Button.Pressed) -> None:
+        if ereignis.button.id != self._button_id:
+            return
+        ereignis.stop()
+        self.clear()
+        self.focus_input()
+        self.post_message(self.Cleared(self))

textual_widgets/clickable_links.py

@@ -0,0 +1,117 @@
+"""Clickable-Links-Mixin fuer Textual-Apps.
+
+Standardisiert klickbare Links in jeder Textual-App: rohe URLs in Rich-Text
+werden zu Textual-Action-Markup-Schnipseln umgeschrieben, das Textual ohne
+CTRL-Klick aufnimmt und beim Maus-Hover automatisch hervorhebt.
+
+Verwendung:
+
+    class MyApp(ClickableLinksMixin, App):
+        ...
+
+    # Irgendwo im Code
+    self._log.write(self.linkify_urls("Sitemap geschrieben: https://example.com"))
+    self._panel.update(self.link_markup("Dokumentation", "https://docs.example.com"))
+
+Beide Methoden produzieren ein Markup-Snippet vom Format
+``[@click=app.open_link({id})]label[/]``. Beim Klick (oder Enter waehrend
+Hover) ruft Textual ``action_open_link(id)`` auf, das die Mixin bereitstellt:
+http(s)-URLs gehen ueber ``webbrowser.open``, lokale Pfade ueber das jeweilige
+Standard-OS-Kommando.
+
+Sonderzeichen in URLs/Pfaden sind unkritisch, weil die Targets in einer
+internen Registry liegen und das Markup nur die ID enthaelt.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import platform
+import re
+import subprocess
+import webbrowser
+from typing import Any
+
+# http(s)-URL — vermeidet die Re-Linkifizierung von URLs, die bereits in einem
+# ``[link …]``- oder ``[@click=…]``-Markup-Block stecken.
+_URL_RE = re.compile(r"(?<!=)(?<!\])(?<!\")(https?://[^\s\[\]<>\"']+)")
+
+
+class ClickableLinksMixin:
+    """Mixin: registriert Klick-Ziele und oeffnet sie auf Klick.
+
+    Verbraucht eine kleine integer-Counter-State, registriert URLs/Pfade
+    on demand und stellt die Aktion bereit, die Textual beim Klick aufruft.
+    """
+
+    _link_registry: dict[int, str]
+    _link_counter: int
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._link_registry = {}
+        self._link_counter = 0
+
+    def link_markup(self, text: str, target: str) -> str:
+        """Erzeugt Textual-Action-Markup fuer einen klickbaren Link.
+
+        Args:
+            text:
+                Sichtbarer Linktext.
+            target:
+                URL (``http://`` / ``https://``) oder lokaler Dateipfad.
+
+        Returns:
+            Markup-Snippet, das in beliebigen Rich-Text-Kontexten verwendet
+            werden kann. Bei leerem ``target`` wird ``text`` unveraendert
+            zurueckgegeben.
+        """
+        if not target:
+            return text
+        self._link_counter += 1
+        link_id = self._link_counter
+        self._link_registry[link_id] = target
+        return f"[@click=app.open_link({link_id})]{text}[/]"
+
+    def linkify_urls(self, message: str) -> str:
+        """Rewrites jede rohe ``http(s)``-URL in ``message`` zu klickbarem Markup.
+
+        URLs, die bereits in einem ``[link …]``- oder ``[@click=…]``-Markup
+        stecken, werden in Ruhe gelassen.
+
+        Args:
+            message:
+                Beliebige Rich-Text-Nachricht.
+
+        Returns:
+            Die Nachricht mit allen rohen URLs als klickbarem Markup.
+        """
+        return _URL_RE.sub(lambda m: self.link_markup(m.group(1), m.group(1)), message)
+
+    def action_open_link(self, link_id: str) -> None:
+        """Oeffnet das zur ID registrierte URL/Datei-Ziel im OS-Standard-Programm.
+
+        Args:
+            link_id:
+                Die in ``link_markup`` vergebene ID — Textual reicht sie als
+                String aus dem Markup durch.
+        """
+        try:
+            key = int(link_id)
+        except (TypeError, ValueError):
+            return
+        target = self._link_registry.get(key, "")
+        if not target:
+            return
+        if target.startswith(("http://", "https://")):
+            with contextlib.suppress(Exception):
+                webbrowser.open(target)
+            return
+        with contextlib.suppress(Exception):
+            if platform.system() == "Windows":
+                os.startfile(target)  # type: ignore[attr-defined]
+            elif platform.system() == "Darwin":
+                subprocess.Popen(["open", target])
+            else:
+                subprocess.Popen(["xdg-open", target])