gitpane 1.0.0__py3-none-any.whl

gitpane/ui/reader/commit_panel.py

@@ -0,0 +1,378 @@
+"""Present one commit in a scrolling panel: its exact text, or its explicit loading state."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from enum import Enum
+from html import escape
+from typing import TYPE_CHECKING, Self
+
+from PySide6.QtCore import QEvent, Qt, Signal
+from PySide6.QtGui import QColor, QImage, QPalette, QPixmap, QTextBlockFormat, QTextCursor
+from PySide6.QtWidgets import QApplication, QGridLayout, QLabel, QPushButton, QScrollArea, QSizePolicy, QVBoxLayout, QWidget
+
+from gitpane.config import LAYOUT_SPACING, MESSAGE_LINE_HEIGHT_PERCENT, SPACING_MD, SPACING_XS, SharedText
+from gitpane.history.avatar import AvatarService, author_color, author_initials
+from gitpane.ui.look.avatar_label import AvatarLabel
+from gitpane.ui.look.fixed_font import body_sized_fixed_font
+from gitpane.ui.reader.commit_message import CommitMessage
+from gitpane.ui.widget.commit_date_text import format_commit_time
+from gitpane.ui.widget.plain_label import plain_label
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from PySide6.QtGui import QKeyEvent
+
+    from gitpane.history.repository_value import Commit, CommitLink, CommitRelation
+
+
+class CommitPanelText(Enum):
+    """Texts the commit detail panel shows, one member per text."""
+
+    DETAIL_EMPTY = "Select a commit to view its details."
+    DETAIL_RETRY = "Retry reading"
+    MESSAGE_EMPTY = "Empty message"
+    AUTHOR_UNKNOWN = "Unknown author"
+    AUTHOR = "Author"
+    AUTHOR_DATE = "Author date"
+    COMMITTER_DATE = "Committer date"
+    PARENT_EMPTY = "No parents"
+    CHILD_EMPTY = "No children"
+
+
+class CopiedHash(Enum):
+    """Which form of a commit hash is copied, with the text of its copy control and the message shown once it is copied."""
+
+    FULL = ("full", "Copy full hash", "Full hash copied.")
+    SHORT = ("short", "Copy short hash", "Short hash copied.")
+
+    def __new__(cls, value: str, copy_label: str, copied_message: str) -> Self:
+        """Keep the name of the hash form as the value, and its two texts beside it."""
+        member = object.__new__(cls)
+        member._value_ = value
+        member.copy_label = copy_label
+        member.copied_message = copied_message
+        return member
+
+
+class HashButton(QPushButton):
+    """Make a displayed hash a native, keyboard-activatable copy control."""
+
+    def __init__(self) -> None:
+        """Use the native focus indicator and underline the copied value."""
+        super().__init__()
+        self.setFlat(True)
+        self.setStyleSheet("QPushButton { text-align: left; padding: 0; }")
+        font = self.font()
+        font.setUnderline(True)
+        self.setFont(font)
+        self.setCursor(Qt.CursorShape.PointingHandCursor)
+        self.setSizePolicy(QSizePolicy.Policy.Maximum, QSizePolicy.Policy.Fixed)
+
+    def keyPressEvent(self, event: QKeyEvent) -> None:
+        """Support Enter outside dialogs alongside the native Space activation."""
+        if event.key() in (Qt.Key.Key_Return, Qt.Key.Key_Enter):
+            self.click()
+            event.accept()
+            return
+        super().keyPressEvent(event)
+
+
+class RelativeLabel(QLabel):
+    """Expose an underlined relative link with the same keyboard activation as hashes."""
+
+    def keyPressEvent(self, event: QKeyEvent) -> None:
+        """Activate the sole local target with Enter or Space, retaining native focus."""
+        if event.key() in (Qt.Key.Key_Return, Qt.Key.Key_Enter, Qt.Key.Key_Space):
+            self.linkActivated.emit(str(self.property("oid")))
+            event.accept()
+            return
+        super().keyPressEvent(event)
+
+
+class CommitPanel(QScrollArea):
+    """Keep metadata, copy values and navigation bound to the visible commit."""
+
+    copy_requested = Signal(str, object)
+    navigation_requested = Signal(str)
+    retry_requested = Signal(str)
+
+    def __init__(self, clock: Callable[[], datetime] | None = None) -> None:
+        """Build plain text fields and reserve a stable square for the author image."""
+        super().__init__()
+        self.clock = clock or (lambda: datetime.now().astimezone())
+        self.commit: Commit | None = None
+        self.oid: str | None = None
+        self.avatar_service: AvatarService | None = None
+        self.avatar_identity: object | None = None
+        self.setWidgetResizable(True)
+        content = QWidget()
+        layout = QVBoxLayout(content)
+        layout.setSpacing(LAYOUT_SPACING)
+        layout.setContentsMargins(LAYOUT_SPACING, LAYOUT_SPACING, LAYOUT_SPACING, LAYOUT_SPACING)
+        self.state_label = plain_label("")
+        self.avatar_label = AvatarLabel()
+        self.avatar_label.setTextFormat(Qt.TextFormat.PlainText)
+        self.avatar_label.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.avatar_label.setTextInteractionFlags(Qt.TextInteractionFlag.NoTextInteraction)
+        self.avatar_label.setAccessibleName("Author avatar")
+        self.author_label = plain_label("")
+        self.author_label.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred)
+        self.date_label = plain_label("")
+        self.committer_date_label = plain_label("")
+        self.full_hash_button = HashButton()
+        self.short_hash_button = HashButton()
+        self.full_hash_button.setAccessibleName(CopiedHash.FULL.copy_label)
+        self.short_hash_button.setAccessibleName(CopiedHash.SHORT.copy_label)
+        self.full_hash_button.clicked.connect(lambda: self.copy_requested.emit(self.full_hash_button.text(), CopiedHash.FULL))
+        self.short_hash_button.clicked.connect(lambda: self.copy_requested.emit(self.short_hash_button.text(), CopiedHash.SHORT))
+        self.retry_button = QPushButton(CommitPanelText.DETAIL_RETRY.value)
+        self.retry_button.clicked.connect(lambda: self.retry_requested.emit(self.oid) if self.oid else None)
+        self.message_panel = CommitMessage()
+        self.message_edit = self.message_panel.text_edit
+        self.message_state_label = plain_label("")
+        self.parent_label = plain_label("")
+        self.child_label = plain_label("")
+        self.parent_links: list[QLabel] = []
+        self.child_links: list[QLabel] = []
+        self.relation_content = QWidget()
+        self.relation_layout = QVBoxLayout(self.relation_content)
+        self.relation_layout.setContentsMargins(0, 0, 0, 0)
+        self.relation_layout.setSpacing(LAYOUT_SPACING)
+        self.relation_layout.addWidget(self.parent_label)
+        self.relation_layout.addWidget(self.child_label)
+        layout.addWidget(self.state_label)
+        header_layout = QGridLayout()
+        header_layout.setVerticalSpacing(0)
+        header_layout.setHorizontalSpacing(SPACING_MD)
+        header_layout.setAlignment(Qt.AlignmentFlag.AlignTop)
+        avatar_column, label_column, value_column = range(3)
+        first_row = 0
+        self.metadata_values = [self.author_label, self.date_label, self.committer_date_label, self.full_hash_button, self.short_hash_button]
+        self.metadata_labels: list[QLabel] = []
+        titles = (CommitPanelText.AUTHOR.value, CommitPanelText.AUTHOR_DATE.value, CommitPanelText.COMMITTER_DATE.value, "Full hash", "Short hash")
+        for row, (title, value) in enumerate(zip(titles, self.metadata_values, strict=True)):
+            label = QLabel(title)
+            self.metadata_labels.append(label)
+            header_layout.addWidget(label, row, label_column)
+            header_layout.addWidget(value, row, value_column)
+        header_layout.addWidget(self.avatar_label, first_row, avatar_column, len(self.metadata_values), 1, Qt.AlignmentFlag.AlignTop)
+        header_layout.setColumnStretch(value_column, 1)
+        layout.addLayout(header_layout)
+        layout.addWidget(self.retry_button)
+        layout.addWidget(self.relation_content)
+        layout.addWidget(self.message_state_label)
+        layout.addWidget(self.message_panel, 1)
+        self.setWidget(content)
+        self.refresh_metrics()
+        self.clear_selection()
+
+    def refresh_metrics(self) -> None:
+        """Fit compact metadata rows to system text and size the avatar to their combined height."""
+        body_font = QApplication.font()
+        self.message_edit.setFont(body_font)
+        fixed_font = body_sized_fixed_font()
+        fixed_font.setUnderline(True)
+        for button in (self.full_hash_button, self.short_hash_button):
+            button.setFont(fixed_font)
+        self.apply_link_color()
+        self.avatar_label.setFont(body_font)
+        row_height = max(self.author_label.fontMetrics().height(), self.full_hash_button.fontMetrics().height()) + SPACING_XS
+        for control in (*self.metadata_labels, *self.metadata_values):
+            control.setMinimumHeight(row_height)
+        # Flat copy links use text-height rows; native form-button padding would spread all five lines.
+        for button in (self.full_hash_button, self.short_hash_button):
+            button.setFixedHeight(row_height)
+        row_count = len(self.metadata_values)
+        avatar_side = row_count * row_height
+        if self.avatar_label.width() != avatar_side:
+            self.avatar_label.setFixedSize(avatar_side, avatar_side)
+            self.refresh_avatar()
+
+    def apply_link_color(self) -> None:
+        """Draw the copyable hashes in the link color of the panel's palette, the same whether the window is active or not.
+
+        The color is copied into each hash button, so it is copied again whenever the panel's palette changes: a switch
+        between light and dark changes the link color, and the light blue is hard to read on the dark panel. The active
+        color is taken by name, since the palette's current group follows whether the window is active at that moment.
+        """
+        link_color = self.palette().color(QPalette.ColorGroup.Active, QPalette.ColorRole.Link)
+        for button in (self.full_hash_button, self.short_hash_button):
+            palette = button.palette()
+            palette.setColor(QPalette.ColorRole.ButtonText, link_color)
+            button.setPalette(palette)
+
+    def changeEvent(self, event: QEvent) -> None:
+        """Give the hashes the new link color when the panel's palette changes."""
+        super().changeEvent(event)
+        if event.type() == QEvent.Type.PaletteChange:
+            self.apply_link_color()
+
+    def clear_selection(self) -> None:
+        """Remove every actionable value when no commit is selected."""
+        self.cancel_avatar()
+        self.commit = None
+        self.oid = None
+        self.state_label.show()
+        self.state_label.setText(CommitPanelText.DETAIL_EMPTY.value)
+        self.avatar_label.setAutoFillBackground(False)
+        for label in (self.author_label, self.date_label, self.committer_date_label, self.avatar_label, self.message_state_label, self.parent_label, self.child_label):
+            label.clear()
+        self.parent_label.show()
+        self.child_label.show()
+        for button in (self.full_hash_button, self.short_hash_button):
+            button.setText("")
+            button.setEnabled(False)
+        self.message_edit.clear()
+        self.retry_button.hide()
+        self.clear_relation()
+
+    def clear_relation(self) -> None:
+        """Disable former relative links immediately when the active commit changes."""
+        for link in (*self.parent_links, *self.child_links):
+            self.relation_layout.removeWidget(link)
+            link.setEnabled(False)
+            link.hide()
+            link.deleteLater()
+        self.parent_links.clear()
+        self.child_links.clear()
+
+    def show_relation(self, relation: CommitRelation) -> None:
+        """Show known relatives without confusing a partial index with no children."""
+        if relation.oid != self.oid or self.commit is None:
+            return
+        self.clear_relation()
+        self.parent_label.setText(CommitPanelText.PARENT_EMPTY.value)
+        self.parent_label.setVisible(not relation.parents)
+        self.child_label.setText(CommitPanelText.CHILD_EMPTY.value if relation.children_complete else SharedText.CHILD_LOADING.value)
+        self.child_label.setVisible(not relation.children_complete or not relation.child_links)
+        for relative in relation.parents:
+            self.parent_links.append(self._add_link(relative, "Parent"))
+        for relative in relation.child_links:
+            self.child_links.append(self._add_link(relative, "Child"))
+        previous = self.short_hash_button
+        for link in (*self.parent_links, *self.child_links):
+            QWidget.setTabOrder(previous, link)
+            previous = link
+        QWidget.setTabOrder(previous, self.message_edit)
+
+    def _add_link(self, relative: CommitLink, kind: str) -> QLabel:
+        """Escape Git text inside a controlled local navigation link, never an external URL."""
+        label = RelativeLabel()
+        label.setWordWrap(True)
+        label.setTextFormat(Qt.TextFormat.RichText)
+        label.setTextInteractionFlags(Qt.TextInteractionFlag.LinksAccessibleByMouse | Qt.TextInteractionFlag.LinksAccessibleByKeyboard)
+        label.setOpenExternalLinks(False)
+        label.setFocusPolicy(Qt.FocusPolicy.StrongFocus)
+        text = f"{relative.short_oid or relative.oid} — {relative.subject or 'Empty message'}"
+        label.setText(f'{kind} : <a href="{escape(relative.oid)}">{escape(text)}</a>')
+        label.setAccessibleName(f"{kind} : {text}")
+        label.setProperty("oid", relative.oid)
+        label.linkActivated.connect(lambda _target, oid=relative.oid: self.navigation_requested.emit(oid))
+        if kind == "Parent":
+            self.relation_layout.insertWidget(self.relation_layout.indexOf(self.child_label), label)
+        else:
+            self.relation_layout.addWidget(label)
+        label.show()
+        return label
+
+    def show_loading(self, oid: str, short_oid: str = "") -> None:
+        """Retain only the current known hashes while fresh metadata is read."""
+        self.clear_selection()
+        self.oid = oid
+        self.full_hash_button.setText(oid)
+        self.full_hash_button.setEnabled(bool(oid))
+        self.short_hash_button.setText(short_oid)
+        self.short_hash_button.setEnabled(bool(short_oid))
+        self.state_label.setText(f"Loading commit {short_oid or oid}…")
+        self.child_label.setText(SharedText.CHILD_LOADING.value)
+
+    def show_error(self, oid: str, cause: str) -> None:
+        """Keep the current hash available and offer an explicit retry after failure."""
+        if self.oid != oid:
+            return
+        short_oid = self.short_hash_button.text()
+        self.show_loading(oid, short_oid)
+        self.state_label.setText(f"Details unavailable — {cause}")
+        self.retry_button.show()
+
+    def show_commit(self, commit: Commit) -> None:
+        """Publish all fields together only for the selection currently being read."""
+        if self.oid != commit.oid:
+            return
+        if commit.detail_error:
+            self.show_error(commit.oid, commit.detail_error)
+            return
+        self.commit = commit
+        self.state_label.clear()
+        self.state_label.hide()
+        self.retry_button.hide()
+        self.full_hash_button.setText(commit.oid)
+        self.short_hash_button.setText(commit.short_oid)
+        self.short_hash_button.setEnabled(bool(commit.short_oid))
+        author = commit.author_name or CommitPanelText.AUTHOR_UNKNOWN.value
+        self.author_label.setText(f"{author} <{commit.author_email}>" if commit.author_email else author)
+        self.refresh_avatar()
+        self.message_edit.setPlainText(commit.message)
+        cursor = QTextCursor(self.message_edit.document())
+        cursor.select(QTextCursor.SelectionType.Document)
+        paragraph_format = QTextBlockFormat()
+        paragraph_format.setLineHeight(MESSAGE_LINE_HEIGHT_PERCENT, QTextBlockFormat.LineHeightTypes.ProportionalHeight.value)
+        cursor.mergeBlockFormat(paragraph_format)
+        self.message_state_label.setText("" if commit.message else CommitPanelText.MESSAGE_EMPTY.value)
+        self.message_state_label.setVisible(not commit.message)
+        self.refresh_date()
+
+    def set_avatar_service(self, service: AvatarService) -> None:
+        """Connect the shared photo service while retaining a standalone offline panel."""
+        self.cancel_avatar()
+        if self.avatar_service is not None:
+            self.avatar_service.image_ready.disconnect(self._image_ready)
+        self.avatar_service = service
+        service.image_ready.connect(self._image_ready)
+        self.refresh_avatar()
+
+    def cancel_avatar(self) -> None:
+        """Invalidate the current consumer before selection or window lifetime changes."""
+        identity = self.avatar_identity
+        self.avatar_identity = None
+        if self.avatar_service is not None and identity is not None:
+            self.avatar_service.cancel(identity)
+
+    def refresh_avatar(self, device_pixel_ratio: float | None = None) -> None:
+        """Rebuild the photo identity after author, selection or display density changes."""
+        self.cancel_avatar()
+        if self.commit is None:
+            return
+        palette = self.avatar_label.palette()
+        palette.setColor(QPalette.ColorRole.Window, QColor(author_color(self.commit.author_name, self.commit.author_email)))
+        palette.setColor(QPalette.ColorRole.WindowText, QColor("white"))
+        self.avatar_label.setPalette(palette)
+        self.avatar_label.setAutoFillBackground(True)
+        if self.avatar_label.pixmap().isNull():
+            self.avatar_label.setText(author_initials(self.commit.author_name))
+        self.avatar_label.setAccessibleName(f"Avatar for {self.commit.author_name or 'unknown author'}")
+        if self.avatar_service is None:
+            return
+        ratio = self.devicePixelRatioF() if device_pixel_ratio is None else device_pixel_ratio
+        avatar_side = self.avatar_label.width()
+        self.avatar_identity = (uuid.uuid4().hex, self.oid, self.commit.author_email, avatar_side, ratio)
+        self.avatar_service.request(self.commit.author_email, avatar_side, ratio, self.avatar_identity)
+
+    def _image_ready(self, identity: object, image: QImage) -> None:
+        """Ignore stale author and screen responses without altering surrounding text."""
+        if identity != self.avatar_identity or self.commit is None or image.isNull():
+            return
+        pixmap = QPixmap.fromImage(image)
+        pixmap.setDevicePixelRatio(max(image.width(), image.height()) / self.avatar_label.width())
+        self.avatar_label.setPixmap(pixmap)
+
+    def refresh_date(self) -> None:
+        """Update relative labels without replacing the message or changing its scroll."""
+        if self.commit is None:
+            return
+        now = self.clock()
+        self.date_label.setText(format_commit_time(self.commit, self.commit.author_timestamp, now))
+        self.committer_date_label.setText(format_commit_time(self.commit, self.commit.committer_timestamp, now))