gitpane 1.0.0__py3-none-any.whl

gitpane/ui/reference/commit_summary.py

@@ -0,0 +1,339 @@
+"""Present a compact, read-only summary of a captured revision."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, QPoint, QRect, Qt
+from PySide6.QtGui import QColor, QPainter, QPalette
+from PySide6.QtWidgets import QApplication, QGridLayout, QGroupBox, QLabel, QStyle, QStyleOptionGroupBox
+
+from gitpane.history.history_parse import COMMIT_TIME_UNAVAILABLE_CAUSE
+from gitpane.history.repository_value import ReferenceKind
+from gitpane.ui.look.theme_color import is_dark_palette, theme_line_color
+from gitpane.ui.look.theme_palette import WINDOWS_CONTROL_LIGHT_COLOR
+from gitpane.ui.widget.commit_date_text import DATE_UNAVAILABLE_TEXT, format_commit_date
+from gitpane.ui.widget.dialog_layout import CAPTION_TO_FIELD_MIN_SPACE
+from gitpane.ui.widget.long_text import ElidedLabel, WrappingLabel
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from PySide6.QtGui import QPaintEvent
+
+    from gitpane.history.repository_value import Commit
+    from gitpane.reference.reference_snapshot import ReferenceSnapshot
+
+REVISION_PREFIX_LENGTH = 7
+# Git Extensions writes eight hexadecimal digits in its commit box.
+GIT_EXTENSIONS_REVISION_PREFIX_LENGTH = 8
+LOADING_COMMIT_TEXT = "Loading commit metadata…"
+NOT_AVAILABLE_TEXT = "n/a"
+# Qt centres a label one pixel lower in a 21 px row than Windows Forms does; a one-pixel bottom margin lifts it.
+GIT_EXTENSIONS_TEXT_LIFT = 1
+# Git Extensions colors, in a light theme: frame line and empty reference band sampled from its Cherry pick commit
+# capture, branch band LightSalmon (also sampled), tag band LightSteelBlue as its source code sets it.
+FRAME_LIGHT_COLOR = "#dcdcdc"
+BRANCH_BAND_LIGHT_COLOR = "#ffa07a"
+TAG_BAND_LIGHT_COLOR = "#b0c4de"
+EMPTY_REFERENCE_BAND_LIGHT_COLOR = WINDOWS_CONTROL_LIGHT_COLOR
+# Dark counterparts of the salmon and steel blue bands: same hues, dark enough for light text (contrast above 7:1).
+BRANCH_BAND_DARK_COLOR = "#6e3524"
+TAG_BAND_DARK_COLOR = "#34465e"
+# Space kept free on each side of the short hash where it interrupts the frame line.
+TITLE_LINE_GAP = 1
+# Git Extensions starts the short hash 9 px after the frame corner, leaving a short piece of line on its left.
+TITLE_INDENT = 9
+# Its digits sit slightly above the line's middle; Qt centres them slightly below, hence this small lift.
+TITLE_TEXT_RAISE = 2
+# Inside the Git Extensions commit box (measured on its capture, from the frame's left, right and bottom edges and from
+# the frame line): subject 18 px under the line and 15 px in, 13 px of space before the metadata rows, rows 21 px high
+# except the last one (31 px), captions 17 px in, values 102 px in, bands ending 13 px before the right edge, 10 px of
+# space under the last row.
+GIT_EXTENSIONS_CONTENT_LEFT = 15
+GIT_EXTENSIONS_CONTENT_TOP_BELOW_LINE = 18
+GIT_EXTENSIONS_CONTENT_RIGHT = 13
+GIT_EXTENSIONS_CONTENT_BOTTOM = 10
+GIT_EXTENSIONS_SUBJECT_TO_METADATA_SPACE = 13
+GIT_EXTENSIONS_METADATA_ROW_HEIGHT = 21
+GIT_EXTENSIONS_LAST_ROW_HEIGHT = 31
+# The Git Extensions v6.0 windows (Create branch, Reset branch) give their last row the height of the others, so their
+# frame is 141 px high instead of the 151 px of Revert and Cherry-pick.
+GIT_EXTENSIONS_COMPACT_LAST_ROW_HEIGHT = GIT_EXTENSIONS_METADATA_ROW_HEIGHT
+GIT_EXTENSIONS_CAPTION_INDENT = 2
+GIT_EXTENSIONS_CAPTION_COLUMN_WIDTH = 87
+# The colored band starts this far left of the value text.
+VALUE_BAND_LEAD = 2
+
+
+class GitExtensionsGroupBox(QGroupBox):
+    """Group frame drawn like the Git Extensions ones: a thin grey rectangle whose caption interrupts its top line.
+
+    The caption starts a few pixels after the frame's corner, leaving a short piece of line on its left. The frame is
+    painted here rather than through a style sheet: a style sheet on the frame would also restyle every child and
+    change the native metrics the layout was measured with, while painting only replaces the frame drawing.
+    """
+
+    def frame_color(self) -> QColor:
+        """Use the captured frame grey in a light theme and the theme's line grey in a dark one.
+
+        The dark grey is worked out from the application palette at paint time, like every other line of the window, so
+        the frame shows on the dark body and follows a theme change.
+        """
+        if is_dark_palette(self.palette()):
+            return theme_line_color(QApplication.palette())
+        return QColor(FRAME_LIGHT_COLOR)
+
+    def title_rectangle(self) -> QRect:
+        """Return where the caption is written: at the style's caption height, moved off the corner."""
+        option = QStyleOptionGroupBox()
+        self.initStyleOption(option)
+        style_rectangle = self.style().subControlRect(QStyle.ComplexControl.CC_GroupBox, option, QStyle.SubControl.SC_GroupBoxLabel, self)
+        return QRect(TITLE_INDENT, style_rectangle.top(), self.fontMetrics().horizontalAdvance(self.title()), style_rectangle.height())
+
+    def frame_rectangle(self) -> QRect:
+        """Return the painted frame: from the line crossing the caption down to the bottom edge."""
+        return QRect(QPoint(0, self.title_rectangle().center().y()), QPoint(self.width() - 1, self.height() - 1))
+
+    def paintEvent(self, event: QPaintEvent) -> None:
+        """Draw the frame, clear its line behind the caption and write the caption across it."""
+        title_rect = self.title_rectangle()
+        frame = self.frame_rectangle()
+        painter = QPainter(self)
+        painter.setPen(self.frame_color())
+        painter.drawRect(QRect(frame.left(), frame.top(), frame.width() - 1, frame.height() - 1))
+        painter.fillRect(title_rect.adjusted(-TITLE_LINE_GAP, 0, TITLE_LINE_GAP, 0), self.palette().color(QPalette.ColorRole.Window))
+        painter.setPen(self.palette().color(QPalette.ColorRole.WindowText))
+        painter.drawText(title_rect.translated(0, -TITLE_TEXT_RAISE), Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignVCenter, self.title())
+        painter.end()
+
+
+class CommitSummary(GitExtensionsGroupBox):
+    """Keep a revision's subject and essential metadata aligned in a small form.
+
+    With ``git_extensions_look`` the frame reproduces the Git Extensions commit box: the short hash is written across
+    the frame's top line, and the Branch(es) and Tag(s) values sit on colored bands. Other forms keep the native frame.
+    ``last_row_height`` sets the height of the Tag(s) row of that look, and ``single_line`` cuts long values with an
+    ellipsis instead of wrapping them, so the box never grows the window. ``clock`` gives the current time the relative
+    commit date is written against; it is injected so that date can be reproduced, as the window gallery needs, and
+    reads the system time when absent.
+    """
+
+    def __init__(self, target_oid: str, *, git_extensions_look: bool = False, last_row_height: int = GIT_EXTENSIONS_LAST_ROW_HEIGHT,
+                 single_line: bool = False, clock: Callable[[], datetime] | None = None) -> None:
+        """Retain the complete target while using a short hash as the frame caption."""
+        super().__init__(target_oid[:REVISION_PREFIX_LENGTH])
+        self.target_oid = target_oid
+        self.clock = clock or (lambda: datetime.now(UTC))
+        self.git_extensions_look = git_extensions_look
+        self.last_row_height = last_row_height
+        self.single_line = single_line
+        self.has_branch = False
+        self.has_tag = False
+        self.setToolTip(target_oid)
+        self.setAccessibleName("Target revision " + target_oid)
+        self.grid = QGridLayout(self)
+        self.subject_label = self._label(LOADING_COMMIT_TEXT, bold=True)
+        self.author_label = self._label(NOT_AVAILABLE_TEXT, bold=True)
+        self.date_label = self._label(NOT_AVAILABLE_TEXT)
+        self.branch_label = self._label(NOT_AVAILABLE_TEXT)
+        self.tag_label = self._label(NOT_AVAILABLE_TEXT)
+        subject_row, spacing_row = 0, 1
+        # The Git Extensions look keeps an empty row between the subject and the metadata instead of the grid spacing.
+        first_metadata_row = spacing_row + 1 if git_extensions_look else spacing_row
+        caption_column, value_column, column_count = 0, 1, 2
+        self.grid.addWidget(self.subject_label, subject_row, caption_column, 1, column_count)
+        self.caption_labels: list[QLabel] = []
+        # Git Extensions centres each caption on its value row; the native form keeps it on the value's first line.
+        caption_alignment = Qt.AlignmentFlag(0) if git_extensions_look else Qt.AlignmentFlag.AlignTop
+        for row, (caption, label) in enumerate((("Author:", self.author_label), ("Commit date:", self.date_label),
+                                               ("Branch(es):", self.branch_label), ("Tag(s):", self.tag_label)), start=first_metadata_row):
+            caption_label = QLabel(caption)
+            self.caption_labels.append(caption_label)
+            self.grid.addWidget(caption_label, row, caption_column, alignment=caption_alignment)
+            label.setAccessibleName(caption.removesuffix(":"))
+            self.grid.addWidget(label, row, value_column)
+        self.grid.setColumnStretch(value_column, 1)
+        if git_extensions_look:
+            self._use_git_extensions_metrics(spacing_row, first_metadata_row)
+
+    def _use_git_extensions_metrics(self, spacing_row: int, first_metadata_row: int) -> None:
+        """Space the subject, captions and values like the Git Extensions commit box instead of the native form."""
+        self.grid.setHorizontalSpacing(0)
+        self.grid.setVerticalSpacing(0)
+        self.grid.setRowMinimumHeight(spacing_row, GIT_EXTENSIONS_SUBJECT_TO_METADATA_SPACE)
+        metadata_row_count = len(self.caption_labels)
+        last_metadata_row = first_metadata_row + metadata_row_count - 1
+        for row in range(first_metadata_row, last_metadata_row):
+            self.grid.setRowMinimumHeight(row, GIT_EXTENSIONS_METADATA_ROW_HEIGHT)
+        self.grid.setRowMinimumHeight(last_metadata_row, self.last_row_height)
+        caption_column = 0
+        self.grid.setColumnMinimumWidth(caption_column, GIT_EXTENSIONS_CAPTION_COLUMN_WIDTH)
+        for caption_label in self.caption_labels:
+            caption_label.setIndent(GIT_EXTENSIONS_CAPTION_INDENT)
+            # The right margin is the space every captured caption keeps before its value: the column is the capture's
+            # width, or wider when a larger system text needs it, and then still leaves that space ("Commit date:" at
+            # 14 pt under macOS touched its value).
+            caption_label.setContentsMargins(0, 0, CAPTION_TO_FIELD_MIN_SPACE, GIT_EXTENSIONS_TEXT_LIFT)
+        for value_label in (self.author_label, self.date_label, self.branch_label, self.tag_label):
+            value_label.setContentsMargins(0, 0, 0, GIT_EXTENSIONS_TEXT_LIFT)
+        self.setTitle(self._short_hash(self.target_oid))
+        self._place_git_extensions_content()
+
+    def _short_hash(self, oid: str) -> str:
+        """Return the frame caption for a commit: eight digits in the Git Extensions look, seven otherwise."""
+        return oid[:GIT_EXTENSIONS_REVISION_PREFIX_LENGTH if self.git_extensions_look else REVISION_PREFIX_LENGTH]
+
+    def _place_git_extensions_content(self) -> None:
+        """Set the grid margins so the content sits at the measured distances from the painted frame.
+
+        The group box reserves its own margins for the native title and frame, and recomputes them whenever the style
+        or font changes; the grid margins are the measured distances minus that reservation.
+        """
+        reserved = self.contentsMargins()
+        line_top = self.title_rectangle().center().y()
+        self.grid.setContentsMargins(max(0, GIT_EXTENSIONS_CONTENT_LEFT - reserved.left()), max(0, line_top + GIT_EXTENSIONS_CONTENT_TOP_BELOW_LINE - reserved.top()),
+                                     max(0, GIT_EXTENSIONS_CONTENT_RIGHT - reserved.right()), max(0, GIT_EXTENSIONS_CONTENT_BOTTOM - reserved.bottom()))
+
+    def changeEvent(self, event: QEvent) -> None:
+        """Keep the Git Extensions spacing when a new style or font changes the group box's own margins."""
+        super().changeEvent(event)
+        # The group box sends style and font changes while it is still being built, before the look is known.
+        if not getattr(self, "git_extensions_look", False) or not hasattr(self, "caption_labels"):
+            return
+        if event.type() in (QEvent.Type.StyleChange, QEvent.Type.FontChange):
+            self._place_git_extensions_content()
+
+    def _label(self, text: str, *, bold: bool = False) -> QLabel:
+        """Build a value label: one line cut with an ellipsis, or literal Git text able to wrap without widening the form."""
+        if self.single_line:
+            label = ElidedLabel(text)
+        else:
+            label = WrappingLabel(text)
+            label.setWordWrap(True)
+        font = label.font()
+        font.setBold(bold)
+        label.setFont(font)
+        return label
+
+    def retarget(self, target_oid: str) -> None:
+        """Show another commit: its short hash in the frame and pending values until its details and references arrive.
+
+        An answer still expected for the previous commit is ignored afterwards, since it no longer matches the target.
+        """
+        if target_oid == self.target_oid:
+            return
+        self.target_oid = target_oid
+        self.setToolTip(target_oid)
+        self.setAccessibleName("Target revision " + target_oid)
+        self.setTitle(self._short_hash(target_oid))
+        self.subject_label.setText(LOADING_COMMIT_TEXT)
+        for label in (self.author_label, self.date_label, self.branch_label, self.tag_label):
+            label.setText(NOT_AVAILABLE_TEXT)
+        self._show_reference_presence(has_branch=False, has_tag=False)
+
+    def show_commit(self, fields: tuple[str, ...]) -> None:
+        """Show only the subject, author and real commit date of the captured target."""
+        oid, author, _author_date, _committer, commit_date, message = fields
+        if oid != self.target_oid:
+            return
+        timestamp = None
+        if commit_date:
+            try:
+                timestamp = int(datetime.fromisoformat(commit_date).timestamp())
+            except (ValueError, OverflowError, OSError):
+                timestamp = None
+        self._show_values(message, author, timestamp, commit_date)
+
+    def show_loaded_commit(self, commit: Commit) -> None:
+        """Show the subject, author and commit date of a commit the history graph already holds, without Git."""
+        if commit.oid != self.target_oid:
+            return
+        if commit.time_unavailable:
+            self._show_values(commit.message, commit.author_name, None, COMMIT_TIME_UNAVAILABLE_CAUSE)
+            return
+        commit_date = datetime.fromtimestamp(commit.committer_timestamp, UTC).isoformat()
+        self._show_values(commit.message, commit.author_name, commit.committer_timestamp, commit_date)
+
+    def _show_values(self, message: str, author: str, timestamp: int | None, commit_date: str) -> None:
+        """Write the subject line, the author and the commit date the way the history graph writes dates.
+
+        Wrapping labels also carry the whole message and the exact date as tooltips; one-line labels keep their
+        tooltip for the whole text of a value they had to cut.
+        """
+        subject, _, _body = message.partition("\n")
+        self.subject_label.setText(subject or NOT_AVAILABLE_TEXT)
+        self.author_label.setText(author or NOT_AVAILABLE_TEXT)
+        if not commit_date:
+            self.date_label.setText(NOT_AVAILABLE_TEXT)
+        elif timestamp is None:
+            self.date_label.setText(DATE_UNAVAILABLE_TEXT)
+        else:
+            self.date_label.setText(format_commit_date(timestamp, self.clock()))
+        if self.single_line:
+            return
+        self.subject_label.setToolTip(message)
+        self.date_label.setToolTip(commit_date)
+
+    def show_references(self, snapshot: ReferenceSnapshot) -> None:
+        """List real branches and tags at the revision, excluding redundant symbolic aliases."""
+        branches: list[str] = []
+        tags: list[str] = []
+        for reference in sorted(snapshot.references, key=lambda reference: reference.full_name):
+            if reference.target_oid != self.target_oid or reference.symbolic_target:
+                continue
+            name = reference.full_name.removeprefix(reference.kind.prefix)
+            if reference.kind == ReferenceKind.TAGS:
+                tags.append(name)
+            elif reference.kind in (ReferenceKind.HEADS, ReferenceKind.REMOTES):
+                branches.append(name)
+        self.branch_label.setText(", ".join(branches) or NOT_AVAILABLE_TEXT)
+        self.tag_label.setText(", ".join(tags) or NOT_AVAILABLE_TEXT)
+        self._show_reference_presence(has_branch=bool(branches), has_tag=bool(tags))
+
+    def _show_reference_presence(self, *, has_branch: bool, has_tag: bool) -> None:
+        """Remember which bands are filled and, in the Git Extensions look, write present references in bold."""
+        self.has_branch = has_branch
+        self.has_tag = has_tag
+        if not self.git_extensions_look:
+            return
+        # Git Extensions writes a present branch or tag in bold on its colored band.
+        for label, present in ((self.branch_label, self.has_branch), (self.tag_label, self.has_tag)):
+            font = label.font()
+            font.setBold(present)
+            label.setFont(font)
+        self.update()
+
+    def branch_band_color(self, present: bool) -> QColor:
+        """Return the Branch(es) band color: salmon when the commit carries a branch, the control grey otherwise."""
+        if not present:
+            return self._empty_band_color()
+        return QColor(BRANCH_BAND_DARK_COLOR if is_dark_palette(self.palette()) else BRANCH_BAND_LIGHT_COLOR)
+
+    def tag_band_color(self, present: bool) -> QColor:
+        """Return the Tag(s) band color: steel blue when the commit carries a tag, the control grey otherwise."""
+        if not present:
+            return self._empty_band_color()
+        return QColor(TAG_BAND_DARK_COLOR if is_dark_palette(self.palette()) else TAG_BAND_LIGHT_COLOR)
+
+    def _empty_band_color(self) -> QColor:
+        """Use the captured control grey in a light theme and the palette's control color in a dark one."""
+        if is_dark_palette(self.palette()):
+            return self.palette().color(QPalette.ColorRole.Button)
+        return QColor(EMPTY_REFERENCE_BAND_LIGHT_COLOR)
+
+    def paintEvent(self, event: QPaintEvent) -> None:
+        """Draw the Git Extensions frame and reference bands, or the native frame when that look is off."""
+        if not self.git_extensions_look:
+            QGroupBox.paintEvent(self, event)
+            return
+        super().paintEvent(event)
+        painter = QPainter(self)
+        # Each band also covers half of the row spacing above and below its value, so consecutive bands touch like
+        # the Git Extensions rows, and it starts a little left of the text so the value does not touch its edge.
+        row_spacing = max(0, self.grid.verticalSpacing())
+        space_above, space_below = row_spacing // 2, row_spacing - row_spacing // 2
+        for label, color in ((self.branch_label, self.branch_band_color(self.has_branch)), (self.tag_label, self.tag_band_color(self.has_tag))):
+            value = label.geometry()
+            painter.fillRect(QRect(QPoint(value.left() - VALUE_BAND_LEAD, value.top() - space_above), QPoint(value.right(), value.bottom() + space_below)), color)