gitpane 1.0.0__py3-none-any.whl

gitpane/ui/reference/reference_dialog.py

@@ -0,0 +1,417 @@
+"""Delete one captured remote branch on its server, independently of graph navigation."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QRect, QSignalBlocker, Qt, Signal
+from PySide6.QtWidgets import QCheckBox, QDialog, QHBoxLayout, QLayout, QLineEdit, QListWidget, QListWidgetItem, QMessageBox, QPushButton, QScrollArea, QVBoxLayout, QWidget
+from shiboken6 import isValid
+
+from gitpane.config import DELETE_BRANCH_TITLE, LOCAL_PREFIX, SharedText
+from gitpane.history.repository_value import ReferenceKind
+from gitpane.operation.diagnostic import SensitiveTextFilter
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.reference.reference_edit import ReferenceDeletionIntent, occupied_branch_set, remote_branch_destination, remote_delete_candidates
+from gitpane.ui.reference.branch_selector import BranchSelector
+from gitpane.ui.widget.content_growth import ContentGrowthMixin, OpeningFit
+from gitpane.ui.widget.content_measure import ScrolledContentMeasure
+from gitpane.ui.widget.dialog_layout import fit_form
+from gitpane.ui.widget.long_text import WrappingLabel
+from gitpane.ui.widget.wheel_safe_drop_down import UrlSelector
+from gitpane.ui.window_control.dialog_modality import open_window_modal, prepare_message_box
+
+if TYPE_CHECKING:
+    from gitpane.operation.repository_operation import OperationOutcome
+    from gitpane.reference.reference_snapshot import ReferenceSnapshot
+    from gitpane.transport.branch_exchange import PushTarget
+    from gitpane.transport.remote_config import RemoteSnapshot
+
+DELETE_DIALOG_WIDTH = 640
+DELETE_DIALOG_HEIGHT = 360
+# Button that confirms the deletion of a branch that is not fully merged, kept apart from the window title so that each can change alone.
+CONFIRM_BRANCH_DELETION_BUTTON_TEXT = "Delete branch"
+
+
+class DeleteBranchDialogText(Enum):
+    """Texts only the Delete branch window shows, one member per text so a misspelt name is an error."""
+
+    SUCCEEDED = "Succeeded"
+    DELETE_LOCAL_BRANCH = "Delete local branch (if available)"
+    """The check box that also deletes the local branch of the same name.
+
+    Not "local tracking branch": that is Git's word for a local branch that follows a remote one, but it reads like
+    "remote-tracking branch", the remote branch's local copy, which is not what this box deletes.
+    """
+
+
+# Wording of the step statuses that have one in the result list. Any other status is written as its own word, the
+# way Git and the transport name it: that choice is explicit, and a test lists the statuses it covers.
+STEP_WORD_BY_STATUS: dict[OperationStatus, DeleteBranchDialogText | SharedText] = {
+    OperationStatus.SUCCESS: DeleteBranchDialogText.SUCCEEDED,
+    OperationStatus.FAILED: SharedText.FAILED,
+    OperationStatus.REFUSED: SharedText.FAILED,
+    OperationStatus.NOT_STARTED: SharedText.NOT_STARTED,
+    OperationStatus.UNKNOWN: SharedText.OUTCOME_UNKNOWN,
+}
+
+
+def step_word(status: OperationStatus) -> str:
+    """Give the word of a step status in the result list: its wording in the table, or else the status's own word."""
+    text = STEP_WORD_BY_STATUS.get(status)
+    return status.value if text is None else text.value
+
+
+class DeleteBranchDialog(ContentGrowthMixin, QDialog):
+    """Delete one captured remote branch on its server, with an explicit remote choice and optional local tracking branches.
+
+    Local branches and tags have their own Git Extensions windows; this form only deletes a branch of a remote. The
+    window grows when its remote fields or its messages appear, so the list of local branches is never pushed out of
+    sight, and takes back its height when they go, never below the height it opened at or the one the user set.
+    """
+
+    prepare_requested = Signal(object)
+    delete_requested = Signal(object)
+    destination_changed = Signal()
+    retry_requested = Signal()
+
+    def __init__(self, session_id: str, full_ref: str, parent: QWidget | None = None) -> None:
+        """Keep the branch choice visible above permanent deletion and cancel actions."""
+        super().__init__(parent)
+        self.session_id = session_id
+        self.full_ref = full_ref
+        # Read by the reference form controller, which also runs the Delete tag window: this form deletes a remote branch.
+        self.remote_branch = True
+        self.snapshot: ReferenceSnapshot | None = None
+        self.intent: ReferenceDeletionIntent | None = None
+        self.closed = False
+        self.busy = False
+        self.confirmation: QMessageBox | None = None
+        self.remote_snapshot: RemoteSnapshot | None = None
+        self.push_target: PushTarget | None = None
+        self.remote_request: tuple | None = None
+        self.outcome: OperationOutcome | None = None
+        self.retry_operation_id = ""
+        self.retry_remote_success = False
+        self.candidates: tuple[ReferenceDeletionIntent, ...] = ()
+        self.local_intents: tuple[ReferenceDeletionIntent, ...] = ()
+        self.warning_refs: list[str] = []
+        self.text_filter = SensitiveTextFilter()
+        self.return_focus = parent.focusWidget() if parent is not None else None
+        self.setWindowTitle(DELETE_BRANCH_TITLE)
+        self.resize(DELETE_DIALOG_WIDTH, DELETE_DIALOG_HEIGHT)
+        layout = QVBoxLayout(self)
+        layout.setSizeConstraint(QLayout.SizeConstraint.SetNoConstraint)
+        self.scroll_area = QScrollArea()
+        self.scroll_area.setWidgetResizable(True)
+        content = QWidget()
+        self.form = QVBoxLayout(content)
+        self.heading_label = WrappingLabel("Select branches")
+        self.branch_selector = BranchSelector()
+        self.branch_selector.setAccessibleName("Select branches")
+        self.heading_label.setBuddy(self.branch_selector)
+        self.form.addWidget(self.heading_label)
+        self.form.addWidget(self.branch_selector)
+        self.remote_checkbox = QCheckBox("Delete branch(es) from remote repository")
+        self.form.addWidget(self.remote_checkbox)
+        self.local_checkbox = QCheckBox(DeleteBranchDialogText.DELETE_LOCAL_BRANCH.value)
+        self.local_checkbox.setEnabled(False)
+        self.form.addWidget(self.local_checkbox)
+        self.remote_box = QWidget()
+        remote_form = QVBoxLayout(self.remote_box)
+        self.remote_selector = UrlSelector()
+        self.endpoint_selector = UrlSelector()
+        self.destination_edit = QLineEdit()
+        # The remote and the branch on it follow from the remote branch's Fetch mapping; only the endpoint is chosen.
+        self.destination_edit.setReadOnly(True)
+        self.remote_selector.setEnabled(False)
+        for label_text, widget in (("Remote repository", self.remote_selector), ("Remote branch", self.destination_edit), ("Push endpoint", self.endpoint_selector)):
+            label = WrappingLabel(label_text)
+            label.setBuddy(widget)
+            widget.setAccessibleName(label_text)
+            remote_form.addWidget(label)
+            remote_form.addWidget(widget)
+        self.remote_box.hide()
+        self.form.addWidget(self.remote_box)
+        self.candidate_label = WrappingLabel("Local tracking branch(es) candidate to deletion:")
+        self.candidate_list = QListWidget()
+        self.candidate_list.setAccessibleName(self.candidate_label.text())
+        self.candidate_label.setBuddy(self.candidate_list)
+        self.form.addWidget(self.candidate_label)
+        self.form.addWidget(self.candidate_list)
+        self.status_label = WrappingLabel()
+        self.status_label.setTextFormat(Qt.TextFormat.PlainText)
+        self.status_label.setWordWrap(True)
+        self.status_label.setText("Reading references and remote tracking…")
+        self.form.addWidget(self.status_label)
+        self.form.addStretch()
+        self.scroll_area.setWidget(content)
+        # The remote fields shown by the remote deletion box, a failure or the result of each step arrive after the
+        # window opened, and the window follows them both ways by the rule it shares with Clone and Checkout branch, never
+        # below the height it opened at or the one the user set. It opens at its usual height, taller only when its rows
+        # need more, which keeps room for the result.
+        self.install_content_growth(ScrolledContentMeasure(self.scroll_area), OpeningFit.GROW_ONLY, DELETE_DIALOG_HEIGHT)
+        layout.addWidget(self.scroll_area, 1)
+        actions = QHBoxLayout()
+        self.retry_button = QPushButton("Retry failed step")
+        self.retry_button.setAutoDefault(False)
+        self.retry_button.hide()
+        actions.addWidget(self.retry_button)
+        actions.addStretch()
+        self.submit_button = QPushButton("Delete")
+        actions.addWidget(self.submit_button)
+        self.submit_button.setAutoDefault(False)
+        self.submit_button.setEnabled(False)
+        self.cancel_button = QPushButton("Cancel")
+        actions.addWidget(self.cancel_button)
+        layout.addLayout(actions)
+        self.branch_selector.currentIndexChanged.connect(self._branch_changed)
+        self.remote_checkbox.toggled.connect(self._remote_toggled)
+        self.remote_selector.currentIndexChanged.connect(self._remote_changed)
+        self.endpoint_selector.currentIndexChanged.connect(self._destination_changed)
+        self.destination_edit.textChanged.connect(self._destination_changed)
+        self.retry_button.clicked.connect(self.retry_requested.emit)
+        self.submit_button.clicked.connect(self._submit)
+        self.cancel_button.clicked.connect(self.reject)
+        self.finished.connect(self._closed)
+        self.refresh_metrics()
+
+    def refresh_metrics(self, available: QRect | None = None) -> None:
+        """Fit deletion choices while keeping action buttons outside scrolling content."""
+        fit_form(self, available)
+
+    def populate(self, snapshot: ReferenceSnapshot) -> None:
+        """Select the exact clicked ref without choosing a replacement on disappearance.
+
+        A capture arriving after the click or after the result changes nothing: it would build a new intention and
+        offer a deletion that was already asked or done.
+        """
+        if self.closed or self.busy or self.outcome is not None:
+            return
+        self.snapshot = snapshot
+        self.status_label.setText("Reading remote tracking…")
+        with QSignalBlocker(self.branch_selector):
+            self.branch_selector.clear()
+            for reference in sorted(snapshot.references, key=lambda reference: reference.full_name):
+                if reference.kind == ReferenceKind.REMOTES and not reference.symbolic_target and reference.target_oid:
+                    self.branch_selector.addItem(reference.full_name.removeprefix(LOCAL_PREFIX), reference.full_name)
+            self.branch_selector.setCurrentIndex(self.branch_selector.findData(self.full_ref))
+        self.branch_selector.setEnabled(self.branch_selector.count() > 0 and not self.busy and not self.closed)
+        self._update_intent()
+
+    def _update_intent(self) -> None:
+        """Invalidate prior answers whenever the selected branch changes, and offer Delete only with a complete remote destination."""
+        if self.busy or self.closed:
+            return
+        self.intent = None
+        self.full_ref = self.branch_selector.currentData() or ""
+        if self.snapshot is not None and self.full_ref:
+            try:
+                self.intent = ReferenceDeletionIntent.capture(self.snapshot, self.full_ref, session_id=self.session_id)
+            except ValueError as error:
+                self.status_label.setText(str(error))
+        self.remote_request = None
+        if (self.remote_checkbox.isChecked() and self.remote_snapshot is not None and self.remote_selector.currentData()
+                and self.endpoint_selector.currentData() and self.destination_edit.text().startswith(LOCAL_PREFIX) and self.push_target is not None):
+            self.remote_request = (self.remote_snapshot, self.remote_selector.currentData(), self.destination_edit.text(), self.endpoint_selector.currentData(), self.push_target)
+        remote_ready = self.remote_checkbox.isChecked() and self.remote_request is not None
+        self.submit_button.setEnabled(self.intent is not None and remote_ready)
+
+    def populate_remote(self, snapshot: RemoteSnapshot) -> None:
+        """Show real tracking only when it names a unique remote, branch and effective URL, and only before the click."""
+        if self.busy or self.closed or self.outcome is not None:
+            return
+        self.remote_snapshot = snapshot
+        self.status_label.clear()
+        with QSignalBlocker(self.remote_selector):
+            self.remote_selector.clear()
+            for name, entry in sorted(snapshot.entry_by_name.items()):
+                if entry.active and not entry.collision:
+                    self.remote_selector.addItem(self.text_filter.redact(name), name)
+            self.remote_selector.setCurrentIndex(-1)
+        self._branch_changed()
+
+    def _branch_changed(self) -> None:
+        """Derive the remote and its branch from the selected remote branch's Fetch mapping, and list its local candidates."""
+        if self.busy:
+            return
+        self.full_ref = self.branch_selector.currentData() or ""
+        remote_name, destination = "", ""
+        if self.remote_snapshot is not None:
+            try:
+                remote_name, destination = remote_branch_destination(self.remote_snapshot, self.full_ref)
+            except ValueError as error:
+                self.status_label.setText(str(error))
+        with QSignalBlocker(self.remote_selector), QSignalBlocker(self.destination_edit):
+            self.remote_selector.setCurrentIndex(self.remote_selector.findData(remote_name))
+            self.destination_edit.setText(destination if remote_name and destination.startswith(LOCAL_PREFIX) else "")
+        self._remote_changed()
+        self._populate_candidates()
+
+    def _populate_candidates(self) -> None:
+        """Show exact upstream candidates and disable branches occupied by worktrees."""
+        self.candidate_list.clear()
+        self.candidates = ()
+        self.local_checkbox.setChecked(False)
+        if self.snapshot is not None and self.remote_snapshot is not None:
+            try:
+                self.candidates = remote_delete_candidates(self.snapshot, self.remote_snapshot, self.full_ref, self.session_id)
+            except ValueError as error:
+                self.status_label.setText(str(error))
+        protected_ref_set = occupied_branch_set(self.snapshot) if self.snapshot is not None else set()
+        selectable = False
+        for candidate in self.candidates:
+            protected = candidate.full_ref in protected_ref_set
+            item = QListWidgetItem(candidate.full_ref + (" — checked out in a worktree" if protected else ""))
+            item.setData(Qt.ItemDataRole.UserRole, candidate)
+            item.setToolTip(item.text())
+            if protected:
+                item.setFlags(item.flags() & ~Qt.ItemFlag.ItemIsEnabled)
+                item.setCheckState(Qt.CheckState.Unchecked)
+            else:
+                item.setFlags(item.flags() | Qt.ItemFlag.ItemIsUserCheckable)
+                item.setCheckState(Qt.CheckState.Checked)
+                selectable = True
+            self.candidate_list.addItem(item)
+        self.local_checkbox.setEnabled(selectable)
+
+    def selected_candidates(self) -> tuple[ReferenceDeletionIntent, ...]:
+        """Return only explicitly enabled local candidates from the captured form."""
+        candidates: list[ReferenceDeletionIntent] = []
+        if not self.local_checkbox.isChecked():
+            return ()
+        for index in range(self.candidate_list.count()):
+            item = self.candidate_list.item(index)
+            if item.flags() & Qt.ItemFlag.ItemIsEnabled and item.checkState() == Qt.CheckState.Checked:
+                candidates.append(item.data(Qt.ItemDataRole.UserRole))
+        return tuple(candidates)
+
+    def _remote_changed(self) -> None:
+        """Require explicit selection for multiple endpoints instead of invoking native fan-out."""
+        if self.busy:
+            return
+        name = self.remote_selector.currentData()
+        entry = self.remote_snapshot.entry_by_name.get(name) if self.remote_snapshot is not None else None
+        with QSignalBlocker(self.endpoint_selector):
+            self.endpoint_selector.clear()
+            if entry is not None:
+                for endpoint in sorted(set(entry.push_urls)):
+                    self.endpoint_selector.addItem(self.text_filter.redact(endpoint), endpoint)
+            initial_index = 0 if self.endpoint_selector.count() == 1 else -1
+            self.endpoint_selector.setCurrentIndex(initial_index)
+        self._destination_changed()
+
+    def _remote_toggled(self, checked: bool) -> None:
+        """Expose the exact remote destination only after the explicit opt-in."""
+        self.remote_box.setVisible(checked)
+        self._destination_changed()
+
+    def _destination_changed(self) -> None:
+        """Discard captured authentication whenever a destination field changes."""
+        if self.busy:
+            return
+        self.push_target = None
+        self.destination_changed.emit()
+        self._update_intent()
+
+    def set_push_target(self, target: PushTarget | None, cause: str = "") -> None:
+        """Bind the selected endpoint to its current non-secret account configuration."""
+        self.push_target = target
+        if cause:
+            self.status_label.setText(self.text_filter.redact(cause))
+        self._update_intent()
+
+    def _submit(self) -> None:
+        """Check the captured branch before asking only the necessary unmerged question."""
+        if self.intent is None or self.busy or self.closed or not self.submit_button.isEnabled():
+            return
+        self.busy = True
+        self.local_intents = self.selected_candidates()
+        self.warning_refs.clear()
+        self.submit_button.setEnabled(False)
+        self.branch_selector.setEnabled(False)
+        self.remote_checkbox.setEnabled(False)
+        self.remote_box.setEnabled(False)
+        self.local_checkbox.setEnabled(False)
+        self.candidate_list.setEnabled(False)
+        self.retry_button.setEnabled(False)
+        self.prepare_requested.emit(self.intent)
+
+    def prepared(self, merged: bool) -> None:
+        """Use Delete as authorization for merged branches and Cancel as the warning default."""
+        if self.closed or self.intent is None:
+            return
+        if merged:
+            self.delete_requested.emit(self.intent)
+            return
+        branch = (self.warning_refs.pop(0) if self.warning_refs else self.full_ref).removeprefix(LOCAL_PREFIX)
+        current_branch = (self.snapshot.head_ref or "HEAD").removeprefix(LOCAL_PREFIX)
+        question = QMessageBox(QMessageBox.Icon.Warning, DELETE_BRANCH_TITLE, f"Branch '{branch}' is not fully merged into '{current_branch}'. Delete it anyway?",
+                               QMessageBox.StandardButton.NoButton, self)
+        prepare_message_box(question, DELETE_BRANCH_TITLE)
+        question.setTextFormat(Qt.TextFormat.PlainText)
+        delete_button = question.addButton(CONFIRM_BRANCH_DELETION_BUTTON_TEXT, QMessageBox.ButtonRole.AcceptRole)
+        cancel_button = question.addButton("Cancel deletion", QMessageBox.ButtonRole.RejectRole)
+        question.setDefaultButton(cancel_button)
+        question.setEscapeButton(cancel_button)
+        self.confirmation = question
+        captured = self.intent
+
+        def answer() -> None:
+            """Bind the affirmative button to the original intent and invalidate late answers."""
+            self.confirmation = None
+            accepted = question.clickedButton() is delete_button
+            question.deleteLater()
+            if self.closed or self.intent != captured:
+                return
+            if accepted:
+                if self.warning_refs:
+                    self.prepared(False)
+                    return
+                self.intent = replace(captured, unmerged_confirmed=True)
+                self.delete_requested.emit(self.intent)
+            else:
+                self.busy = False
+                self.branch_selector.setEnabled(True)
+                self.remote_checkbox.setEnabled(True)
+                self.remote_box.setEnabled(True)
+                self.local_checkbox.setEnabled(bool(self.candidates))
+                self.candidate_list.setEnabled(True)
+                self._update_intent()
+        question.finished.connect(answer)
+        open_window_modal(question)
+
+    def show_error(self, cause: str) -> None:
+        """Retain the exact failure without permitting stale capture reuse."""
+        self.busy = False
+        self.status_label.setText(self.text_filter.redact(cause))
+        self.branch_selector.setEnabled(False)
+        self.submit_button.setEnabled(False)
+        if self.outcome is not None:
+            self.retry_button.setEnabled(True)
+
+    def show_outcome(self, outcome: OperationOutcome) -> None:
+        """Keep each deletion result visible until the user closes the form."""
+        self.busy = False
+        self.outcome = outcome
+        lines: list[str] = []
+        for step in outcome.steps:
+            lines.append(step.operation + (" " + step.full_ref if step.full_ref else "") + ": " + step_word(step.status) + " — " + step.effect)
+        if outcome.diagnostic is not None:
+            lines.append(outcome.diagnostic.detail)
+        self.status_label.setText("\n".join(lines))
+        self.cancel_button.setText("Close")
+        self.submit_button.setEnabled(False)
+        retryable = outcome.status in (OperationStatus.FAILED, OperationStatus.REFUSED, OperationStatus.PARTIAL) and any(step.status in (OperationStatus.FAILED, OperationStatus.REFUSED, OperationStatus.NOT_STARTED) for step in outcome.steps)
+        self.retry_button.setVisible(retryable)
+        self.retry_button.setEnabled(retryable)
+
+    def _closed(self) -> None:
+        """Invalidate pending reads and questions and restore the launching widget focus."""
+        self.closed = True
+        if self.confirmation is not None:
+            self.confirmation.reject()
+        if self.return_focus is not None and isValid(self.return_focus):
+            self.return_focus.setFocus()

gitpane/ui/reference/reference_feedback.py

@@ -0,0 +1,62 @@
+"""Render bounded operation feedback without owning Git work or interpreting its output."""
+
+from __future__ import annotations
+
+from html import escape
+
+from PySide6.QtCore import QEvent, Qt
+from PySide6.QtGui import QPalette
+from PySide6.QtWidgets import QWidget
+
+from gitpane.config import DARK_BACKGROUND_LIGHTNESS_LIMIT, ERROR_DARK_COLOR, ERROR_LIGHT_COLOR
+from gitpane.operation.diagnostic import SensitiveTextFilter
+from gitpane.ui.widget.long_text import WrappingLabel
+
+
+def format_reference_summary(lines: list[tuple[str, bool]], palette: QPalette) -> str:
+    """Escape filtered observation lines and emphasize only errors against the current theme."""
+    dark = palette.color(QPalette.ColorRole.Window).lightnessF() < DARK_BACKGROUND_LIGHTNESS_LIMIT
+    color = ERROR_DARK_COLOR if dark else ERROR_LIGHT_COLOR
+    text_filter = SensitiveTextFilter()
+    rendered_lines: list[str] = []
+    for text, error in lines:
+        literal = escape(text_filter.redact(text)).replace("\n", "<br>")
+        rendered_lines.append(f'<span style="color: {color}"><b>{literal}</b></span>' if error else literal)
+    return "<br>".join(rendered_lines)
+
+
+class ReferenceSummaryLabel(WrappingLabel):
+    """Keep ordinary messages literal and redraw rich results when the palette changes."""
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        """Retain filtered lines only while an operation summary is visible."""
+        super().__init__(parent=parent)
+        self.summary_lines: list[tuple[str, bool]] = []
+        self.setTextFormat(Qt.TextFormat.PlainText)
+        self.setWordWrap(True)
+        self.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+
+    def setText(self, text: str) -> None:
+        """Display non-summary messages as literal filtered text."""
+        self.summary_lines = []
+        self.setTextFormat(Qt.TextFormat.PlainText)
+        super().setText(SensitiveTextFilter().redact(text))
+
+    def clear(self) -> None:
+        """Forget a previous summary when a new operation begins."""
+        self.setText("")
+
+    def show_summary(self, lines: list[tuple[str, bool]]) -> None:
+        """Retain safe observations for palette updates and text selection."""
+        text_filter = SensitiveTextFilter()
+        self.summary_lines = []
+        for text, error in lines:
+            self.summary_lines.append((text_filter.redact(text), error))
+        self.setTextFormat(Qt.TextFormat.RichText)
+        super().setText(format_reference_summary(self.summary_lines, self.palette()))
+
+    def changeEvent(self, event: QEvent) -> None:
+        """Refresh error contrast after a live theme change."""
+        super().changeEvent(event)
+        if event.type() == QEvent.Type.PaletteChange and self.summary_lines:
+            super().setText(format_reference_summary(self.summary_lines, self.palette()))

gitpane/ui/reference/reference_form.py

@@ -0,0 +1,139 @@
+"""Share the life cycle of the reference windows that reproduce Git Extensions forms."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QDialog, QMessageBox, QPushButton, QWidget
+from shiboken6 import isValid
+
+from gitpane.config import fit_window
+from gitpane.operation.diagnostic import SensitiveTextFilter
+from gitpane.ui.window_control.dialog_modality import open_window_modal, prepare_message_box
+
+if TYPE_CHECKING:
+    from PySide6.QtCore import QRect
+    from PySide6.QtGui import QCloseEvent, QKeyEvent
+
+    from gitpane.reference.reference_edit import BranchDeletionIntent, BranchIntent, CheckoutIntent, ReferenceDeletionIntent, ResetIntent, TagIntent
+    from gitpane.reference.reference_snapshot import ReferenceSnapshot
+    from gitpane.ui.reference.commit_summary import CommitSummary
+
+
+def reference_warning_box(title: str, cause: str, parent: QWidget | None, text_filter: SensitiveTextFilter | None = None) -> QMessageBox:
+    """Build the warning box of a reference form: the form's title, a warning icon, OK, and the cause as plain text with anything sensitive removed.
+
+    Both the error of a form in use and the refusal of a form at its opening are built here, so neither can drop the
+    removal of secrets nor differ in look from the other. A form in use passes its own filter, which keeps the secrets
+    it already met.
+    """
+    redacted = (text_filter or SensitiveTextFilter()).redact(cause)
+    box = QMessageBox(QMessageBox.Icon.Warning, title, redacted, QMessageBox.StandardButton.Ok, parent)
+    prepare_message_box(box, title)
+    box.setTextFormat(Qt.TextFormat.PlainText)
+    return box
+
+
+class ReferenceFormDialog(QDialog):
+    """Base of the reference forms: frozen while Git runs, errors in a message box, Enter on the focused button.
+
+    A subclass builds its body and sets ``submit_button``; the reference form controller owns every Git read and write. While
+    ``busy`` the form cannot be closed, so the captured request stays visible until its operation ends.
+    """
+
+    def __init__(self, session_id: str, parent: QWidget | None = None) -> None:
+        """Start idle, without a capture, and remember which control to give the focus back to on closing."""
+        super().__init__(parent)
+        self.session_id = session_id
+        self.snapshot: ReferenceSnapshot | None = None
+        # Each form freezes its own kind of request; the Delete branch window of local branches freezes a group deletion.
+        self.intent: TagIntent | BranchIntent | CheckoutIntent | ResetIntent | ReferenceDeletionIntent | BranchDeletionIntent | None = None
+        self.busy = False
+        self.closed = False
+        self.completed = False
+        self.return_focus = parent.focusWidget() if parent is not None else None
+        self.error_box: QMessageBox | None = None
+        self.text_filter = SensitiveTextFilter()
+        # Raised each time the form targets another commit, so a late position answer for an older target is ignored.
+        self.position_generation = 0
+        # The Git Extensions commit box of the forms that show one; the reference form controller fills it for each new target.
+        self.commit_summary: CommitSummary | None = None
+        # Height of the forms made of a single row, which Git Extensions lets grow in width only; None lets the height change.
+        self.single_row_height: int | None = None
+        self.submit_button = QPushButton()
+        # The Git Extensions forms have no help button in their title bar, and there is no help to open.
+        self.setWindowFlag(Qt.WindowType.WindowContextHelpButtonHint, False)
+        self.finished.connect(self._closed)
+
+    def show_error(self, cause: str) -> None:
+        """Refuse submission and explain why in a Windows-style warning box, as Git Extensions does.
+
+        The forms have no status area, so the cause goes to a non-blocking message box, and to the submit button's
+        tooltip so it can still be read after the box is closed. A second error updates the box already open instead
+        of stacking another one.
+        """
+        text = self.text_filter.redact(cause)
+        self.submit_button.setEnabled(False)
+        self.submit_button.setToolTip(text)
+        if self.error_box is not None and isValid(self.error_box):
+            self.error_box.setText(text)
+            open_window_modal(self.error_box)
+            return
+        self.error_box = reference_warning_box(self.windowTitle(), cause, self, self.text_filter)
+        open_window_modal(self.error_box)
+
+    def fit_capture_controls(self) -> None:
+        """Size the captions and buttons copied from the form's capture for the current font; forms that have some override it.
+
+        The captures were taken with Segoe UI 9 pt: each control keeps its capture's size where its text fits, and takes
+        the size its text needs with a wider font, so no caption or button text is cut.
+        """
+
+    def refresh_metrics(self, available: QRect | None = None) -> None:
+        """Size the controls copied from the capture, then keep the form on the usable screen area without turning its starting size into a minimum.
+
+        A single-row form gets its fixed height back afterwards: fitting the window rewrites its minimum size, which
+        would otherwise let the height change again. That height is the capture's, or the height its row needs when a
+        larger text size makes the caption, the field or the button taller, so no text is cut.
+        """
+        self.fit_capture_controls()
+        fit_window(self, 0, 0, available)
+        if self.single_row_height is not None:
+            self.setFixedHeight(max(self.single_row_height, self.layout().totalMinimumSize().height()))
+
+    def reject(self) -> None:
+        """Close an idle form; a form whose request is running stays open."""
+        if not self.busy:
+            super().reject()
+
+    def accept(self) -> None:
+        """Ignore acceptance while the native operation still owns the captured request."""
+        if not self.busy:
+            super().accept()
+
+    def closeEvent(self, event: QCloseEvent) -> None:
+        """Ignore the title bar close button while Git is still using the captured choices."""
+        if self.busy:
+            event.ignore()
+            return
+        super().closeEvent(event)
+
+    def keyPressEvent(self, event: QKeyEvent) -> None:
+        """Press the focused button on Enter, as Windows does; anywhere else Enter runs the default submit button."""
+        focused = self.focusWidget()
+        if (event.key() in (Qt.Key.Key_Return, Qt.Key.Key_Enter) and isinstance(focused, QPushButton) and focused is not self.submit_button
+                and self.isAncestorOf(focused)):
+            if focused.isEnabled():
+                focused.click()
+            return
+        super().keyPressEvent(event)
+
+    def _closed(self) -> None:
+        """Invalidate late answers, close a pending error box and give the focus back to the launching control."""
+        self.closed = True
+        self.position_generation += 1
+        if self.error_box is not None and isValid(self.error_box):
+            self.error_box.close()
+        if self.return_focus is not None and isValid(self.return_focus):
+            self.return_focus.setFocus()