gitpane 1.0.0__py3-none-any.whl

gitpane/ui/reference/delete_tag_dialog.py

@@ -0,0 +1,394 @@
+"""Reproduce the Git Extensions "Delete tag" window: a tag list, Delete, an optional deletion on one remote."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QMargins, QRect, QSignalBlocker, QSize, Qt, Signal
+from PySide6.QtWidgets import QCheckBox, QComboBox, QHBoxLayout, QLabel, QPushButton, QVBoxLayout, QWidget
+
+from gitpane.config import DELETE_BUTTON_TEXT, SharedText
+from gitpane.history.repository_value import ReferenceKind
+from gitpane.operation.operation_status import OperationStatus
+from gitpane.reference.reference_edit import DEFAULT_PUSH_REMOTE_NAME, DELETE_LOCAL_TAG_OPERATION, DELETE_REMOTE_TAG_OPERATION, ReferenceDeletionIntent
+from gitpane.reference.reference_snapshot import short_reference_name
+from gitpane.text.typed_text import typed_value
+from gitpane.ui.look.theme_look import follow_theme
+from gitpane.ui.look.windows_control_look import apply_windows_button_look, apply_windows_combo_look
+from gitpane.ui.reference.reference_feedback import ReferenceSummaryLabel
+from gitpane.ui.reference.reference_form import ReferenceFormDialog
+from gitpane.ui.widget.content_growth import ContentGrowthMixin, OpeningFit
+from gitpane.ui.widget.content_measure import LayoutContentMeasure
+from gitpane.ui.widget.dialog_layout import fit_caption_column, fit_capture_control, install_plain_form_palette
+from gitpane.ui.widget.scrolled_text import ScrolledText
+
+if TYPE_CHECKING:
+    from gitpane.operation.repository_operation import OperationOutcome
+    from gitpane.reference.reference_snapshot import ReferenceSnapshot
+    from gitpane.transport.remote_config import RemoteSnapshot
+
+DELETE_TAG_TITLE = "Delete tag"
+SELECT_TAG_CAPTION = "Select tag"
+LOCAL_DELETION_TEXT = "This will delete the selected tag from the (local) repository."
+REMOTE_DELETION_CAPTION = "Delete tag also from the following remote(s):"
+REMOTE_LIST_NAME = "Remote"
+RETRY_BUTTON_TEXT = "Retry failed step"
+NO_TAG_CAUSE = "No tags are available"
+LOCAL_DESTINATION = "Local"
+# Refusals of a remote deletion, written before anything is deleted, locally or on a server.
+SEVERAL_PUSH_ADDRESSES_CAUSE = "Remote '{0}' has several push addresses. GitPane deletes a tag on one server only; the tag was not deleted."
+NO_PUSH_ADDRESS_CAUSE = "Remote '{0}' has no push address; the tag was not deleted."
+UNUSABLE_REMOTE_CAUSE = "Remote '{0}' is not configured unambiguously; the tag was not deleted."
+NO_REMOTE_CAUSE = "Select the remote to delete the tag from"
+REMOTE_READ_FAILED_CAUSE = "The remote configuration could not be read: {0}"
+
+
+class DeleteTagDialogText(Enum):
+    """Texts only the Delete tag window shows, one member per text so a misspelt name is an error."""
+
+    DELETED = "deleted"
+
+
+# Wording of the step statuses that have one in the result summary. 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_SUMMARY_BY_STATUS: dict[OperationStatus, DeleteTagDialogText | SharedText] = {
+    OperationStatus.SUCCESS: DeleteTagDialogText.DELETED,
+    OperationStatus.UNKNOWN: SharedText.OUTCOME_UNKNOWN,
+}
+
+
+def step_summary_word(status: OperationStatus) -> str:
+    """Give the word of a step status in the result summary: its wording in the table, or else the status's own word."""
+    text = STEP_SUMMARY_BY_STATUS.get(status)
+    return status.value if text is None else text.value
+
+
+RETRYABLE_OUTCOME_STATUS_SET = frozenset((OperationStatus.FAILED, OperationStatus.REFUSED, OperationStatus.PARTIAL))
+RETRYABLE_STEP_STATUS_SET = frozenset((OperationStatus.FAILED, OperationStatus.REFUSED, OperationStatus.NOT_STARTED))
+# Client area of the Git Extensions capture, 454 x 171 inside the window borders and title bar.
+DELETE_TAG_CAPTURE_CLIENT_SIZE = QSize(454, 171)
+# Height of the capture's bottom row, a Help link and its explanation; GitPane has no help, so the window loses that row.
+HELP_ROW_HEIGHT = 25
+DELETE_TAG_CLIENT_SIZE = QSize(DELETE_TAG_CAPTURE_CLIENT_SIZE.width(), DELETE_TAG_CAPTURE_CLIENT_SIZE.height() - HELP_ROW_HEIGHT)
+# Measured on the capture in client pixels at 100 %, visible borders included: "Select tag" ink from x 10, y 18; tag list
+# (126, 12, 237, 23); Delete button (370, 11, 73, 23), right of the list rather than in a button band; local text ink
+# from x 10, y 55; check box square (10, 83, 13, 13) with its text from x 29; remote list (10, 106, 270, 23).
+DELETE_TAG_CAPTION_LEFT = 10
+TAG_COMBO_RECT = QRect(126, 12, 237, 23)
+DELETE_BUTTON_RECT = QRect(370, 11, 73, 23)
+REMOTE_COMBO_RECT = QRect(10, 106, 270, 23)
+# Width of the caption, from its left edge to the tag list; a wider caption text widens it.
+SELECT_TAG_CAPTION_WIDTH = TAG_COMBO_RECT.left() - DELETE_TAG_CAPTION_LEFT
+# The window's own margins: the captions, the Delete button's top and right edges and the remote list's bottom set them.
+DELETE_TAG_MARGINS = QMargins(DELETE_TAG_CAPTION_LEFT, DELETE_BUTTON_RECT.top(), DELETE_TAG_CLIENT_SIZE.width() - DELETE_BUTTON_RECT.right() - 1,
+                              DELETE_TAG_CLIENT_SIZE.height() - REMOTE_COMBO_RECT.bottom() - 1)
+# The tag list sits 1 px lower than the Delete button in the capture.
+TAG_COMBO_DROP = TAG_COMBO_RECT.top() - DELETE_BUTTON_RECT.top()
+TAG_COMBO_TO_BUTTON_SPACE = DELETE_BUTTON_RECT.left() - TAG_COMBO_RECT.right() - 1
+# Vertical spaces between the rows, fitted so that Qt's text, square and list land where the capture has them in the
+# Fusion style: the local text's ink on y 55, the check box square on y 83 and the remote list on y 106.
+FIRST_ROW_TO_LOCAL_TEXT_SPACE = 16
+LOCAL_TEXT_TO_CHECK_BOX_SPACE = 13
+CHECK_BOX_TO_REMOTE_COMBO_SPACE = 5
+# Space between the remote list and the result summary shown after a failed step.
+REMOTE_COMBO_TO_SUMMARY_SPACE = 8
+
+
+class DeleteTagDialog(ContentGrowthMixin, ReferenceFormDialog):
+    """Delete one tag locally, and optionally on one remote, like the Git Extensions Delete tag window.
+
+    The window only freezes a request. The reference form controller reads the remote configuration the first time the check box is
+    checked, turns the chosen remote into its single push address, runs Git and answers with ``show_outcome`` or
+    ``show_error``. The reference form controller, which runs the deletion, reads these attributes: ``intent`` (the tag deletion), ``remote_request``
+    (remote configuration, remote name, tag, push address and push target, or None for a local deletion),
+    ``remote_snapshot`` (the remote configuration read for this window), ``outcome`` (the last result),
+    ``retry_operation_id`` and ``retry_remote_success`` (set while retrying), ``remote_branch`` (always False: this
+    window deletes a tag) and ``local_intents`` (always empty: a tag has no local tracking branch to delete with it).
+    """
+
+    delete_requested = Signal(object)
+    remote_requested = Signal()
+    retry_requested = Signal()
+
+    def __init__(self, session_id: str, parent: QWidget | None = None) -> None:
+        """Build the rows of the capture without its help row, with the remote list disabled until the check box is checked."""
+        super().__init__(session_id, parent)
+        self.intent: ReferenceDeletionIntent | None = None
+        self.setWindowTitle(DELETE_TAG_TITLE)
+        self.full_ref = ""
+        self.remote_snapshot: RemoteSnapshot | None = None
+        self.remote_request: tuple | None = None
+        # Set once the remote configuration was asked for, so unchecking and checking again does not read it twice.
+        self.remote_read_requested = False
+        self.outcome: OperationOutcome | None = None
+        self.retry_operation_id = ""
+        self.retry_remote_success = False
+        self.remote_branch = False
+        self.local_intents: tuple[ReferenceDeletionIntent, ...] = ()
+        install_plain_form_palette(self)
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(DELETE_TAG_MARGINS)
+        layout.setSpacing(0)
+        self.caption_label = QLabel(SELECT_TAG_CAPTION)
+        self.tag_combo = QComboBox()
+        # The capture shows the tag name selected in a list one can type into; typed names are matched against the list.
+        self.tag_combo.setEditable(True)
+        self.tag_combo.setInsertPolicy(QComboBox.InsertPolicy.NoInsert)
+        self.tag_combo.setAccessibleName(SELECT_TAG_CAPTION)
+        self.caption_label.setBuddy(self.tag_combo)
+        tag_column = QVBoxLayout()
+        tag_column.setContentsMargins(0, TAG_COMBO_DROP, 0, 0)
+        tag_column.setSpacing(0)
+        tag_column.addWidget(self.tag_combo)
+        self.submit_button.setText(DELETE_BUTTON_TEXT)
+        self.submit_button.setEnabled(False)
+        first_row = QHBoxLayout()
+        first_row.setContentsMargins(0, 0, 0, 0)
+        first_row.setSpacing(0)
+        first_row.addWidget(self.caption_label, 0, Qt.AlignmentFlag.AlignVCenter)
+        first_row.addLayout(tag_column, 1)
+        first_row.addSpacing(TAG_COMBO_TO_BUTTON_SPACE)
+        first_row.addWidget(self.submit_button, 0, Qt.AlignmentFlag.AlignTop)
+        layout.addLayout(first_row)
+        layout.addSpacing(FIRST_ROW_TO_LOCAL_TEXT_SPACE)
+        self.local_label = QLabel(LOCAL_DELETION_TEXT)
+        layout.addWidget(self.local_label)
+        layout.addSpacing(LOCAL_TEXT_TO_CHECK_BOX_SPACE)
+        self.remote_checkbox = QCheckBox(REMOTE_DELETION_CAPTION)
+        layout.addWidget(self.remote_checkbox)
+        layout.addSpacing(CHECK_BOX_TO_REMOTE_COMBO_SPACE)
+        self.remote_combo = QComboBox()
+        self.remote_combo.setAccessibleName(REMOTE_LIST_NAME)
+        self.remote_combo.setFixedWidth(REMOTE_COMBO_RECT.width())
+        self.remote_combo.setEnabled(False)
+        layout.addWidget(self.remote_combo, 0, Qt.AlignmentFlag.AlignLeft)
+        # Shown only after a result that did not delete everything: each destination's result, then Retry failed step.
+        self.summary_space = QWidget()
+        self.summary_space.setFixedHeight(REMOTE_COMBO_TO_SUMMARY_SPACE)
+        self.summary_space.hide()
+        layout.addWidget(self.summary_space)
+        self.status_label = ReferenceSummaryLabel()
+        # A server's refusal can be longer than the screen: the summary scrolls past the window's growth cap, so Retry
+        # failed step under it stays inside the window.
+        self.status_area = ScrolledText(self.status_label)
+        self.status_area.hide()
+        layout.addWidget(self.status_area)
+        self.retry_button = QPushButton(RETRY_BUTTON_TEXT)
+        self.retry_button.setAutoDefault(False)
+        self.retry_button.hide()
+        layout.addWidget(self.retry_button, 0, Qt.AlignmentFlag.AlignLeft)
+        layout.addStretch(1)
+        self.apply_theme_look()
+        follow_theme(self, self.apply_theme_look)
+        # Enter runs Delete from anywhere in the form. The role is set only once the button belongs to the dialog, so Qt
+        # records it as the dialog's main default. There is no Cancel button: Escape and the title bar close the window.
+        self.submit_button.setDefault(True)
+        self.submit_button.clicked.connect(self._submit)
+        self.retry_button.clicked.connect(self.retry_requested.emit)
+        self.tag_combo.currentIndexChanged.connect(self._update_intent)
+        self.tag_combo.editTextChanged.connect(self._update_intent)
+        self.remote_checkbox.toggled.connect(self._remote_toggled)
+        self.remote_combo.currentIndexChanged.connect(self._update_intent)
+        self.resize(DELETE_TAG_CLIENT_SIZE)
+        self.refresh_metrics()
+        self.install_content_growth(LayoutContentMeasure(self), OpeningFit.GROW_ONLY, self.height())
+        self.tag_combo.setFocus()
+
+    def apply_theme_look(self) -> None:
+        """Lay the light or dark look of the tag list, Delete, the remote list and Retry failed step, decided on the application palette.
+
+        Called by the constructor and again at each switch. The remote list and Retry are built with the form, hidden or
+        disabled until needed, so they always carry the look of the current appearance. Git Extensions draws the remote
+        list like a field one can type into (a light grey border while disabled); GitPane keeps it a plain choice among
+        the configured remotes, so no typed name can reach the deletion. Only style sheets and palettes change: the
+        tag, the remote choice and any result shown stay as they are.
+        """
+        apply_windows_combo_look(self.tag_combo, editable=True)
+        apply_windows_button_look(self.submit_button)
+        apply_windows_combo_look(self.remote_combo, editable=True)
+        apply_windows_button_look(self.retry_button)
+
+    def fit_capture_controls(self) -> None:
+        """Give the caption and the Delete button the capture's sizes, or more when their text needs it; a wider caption moves the list right."""
+        fit_caption_column((self.caption_label,), SELECT_TAG_CAPTION_WIDTH)
+        fit_capture_control(self.submit_button, DELETE_BUTTON_RECT.size())
+
+    def populate(self, snapshot: ReferenceSnapshot, full_ref: str) -> None:
+        """Offer the tags and remotes of the references the window was opened on, the clicked tag selected.
+
+        No Git process is needed: the remote names come from the same capture. A capture arriving after the click or
+        after a result changes nothing, so it never replaces a deletion already asked or done.
+        """
+        if self.closed or self.busy or self.completed or self.outcome is not None:
+            return
+        self.snapshot = snapshot
+        self.full_ref = full_ref
+        with QSignalBlocker(self.tag_combo), QSignalBlocker(self.remote_combo):
+            self.tag_combo.clear()
+            for reference in sorted(snapshot.references, key=lambda reference: reference.full_name):
+                if reference.kind == ReferenceKind.TAGS and reference.target_oid and not reference.symbolic_target:
+                    self.tag_combo.addItem(short_reference_name(reference.full_name), reference.full_name)
+            self.tag_combo.setCurrentIndex(self.tag_combo.findData(full_ref))
+            self.remote_combo.clear()
+            for remote_name in sorted(snapshot.remote_names):
+                self.remote_combo.addItem(remote_name, remote_name)
+            default_index = self.remote_combo.findData(DEFAULT_PUSH_REMOTE_NAME)
+            first_index = 0
+            self.remote_combo.setCurrentIndex(default_index if default_index >= 0 else first_index if self.remote_combo.count() else -1)
+        self.tag_combo.lineEdit().selectAll()
+        self.tag_combo.setFocus()
+        self._update_intent()
+        if not self.tag_combo.count():
+            self.submit_button.setToolTip(NO_TAG_CAUSE)
+
+    def selected_ref(self) -> str:
+        """Return the full name of the tag written in the list, or an empty text when it names no offered tag.
+
+        The typed name is taken without the blanks around it; the list keeps what was typed.
+        """
+        index = self.tag_combo.findText(typed_value(self.tag_combo.currentText()), Qt.MatchFlag.MatchExactly | Qt.MatchFlag.MatchCaseSensitive)
+        if index < 0:
+            return ""
+        return self.tag_combo.itemData(index) or ""
+
+    def _update_intent(self) -> None:
+        """Freeze the selected tag into a deletion request, and offer Delete once any remote choice can be checked."""
+        if self.busy or self.closed or self.completed:
+            return
+        self.intent = None
+        self.remote_request = None
+        self.full_ref = self.selected_ref()
+        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:
+                self.intent = None
+        remote_ready = not self.remote_checkbox.isChecked() or self.remote_snapshot is not None
+        self.submit_button.setToolTip("")
+        self.submit_button.setEnabled(self.intent is not None and remote_ready)
+
+    def _remote_toggled(self, checked: bool) -> None:
+        """Offer the remote list only while the check box is checked, and ask for the remote configuration the first time."""
+        self.remote_combo.setEnabled(checked and not self.busy and not self.completed)
+        if checked and not self.remote_read_requested:
+            self.remote_read_requested = True
+            self.remote_requested.emit()
+        self._update_intent()
+
+    def populate_remote(self, remote_snapshot: RemoteSnapshot) -> None:
+        """Keep the remote configuration read for this window, the one a remote deletion is checked against."""
+        if self.closed or self.busy or self.completed or self.outcome is not None:
+            return
+        self.remote_snapshot = remote_snapshot
+        self._update_intent()
+
+    def show_remote_error(self, cause: str) -> None:
+        """Explain why the remote configuration could not be read and uncheck the remote option, so checking it reads again."""
+        if self.closed or self.busy or self.completed:
+            return
+        self.remote_read_requested = False
+        with QSignalBlocker(self.remote_checkbox):
+            self.remote_checkbox.setChecked(False)
+        self.remote_combo.setEnabled(False)
+        self._update_intent()
+        self.show_error(REMOTE_READ_FAILED_CAUSE.format(cause))
+
+    def _submit(self) -> None:
+        """Freeze the form and hand its request to the reference form controller once."""
+        if self.closed or self.busy or self.completed or self.intent is None or not self.submit_button.isEnabled():
+            return
+        self.busy = True
+        self._set_controls_enabled(False)
+        self.delete_requested.emit(self.intent)
+
+    def show_error(self, cause: str) -> None:
+        """Refuse or explain a failure: in a message box before any result, under the results after one.
+
+        Before any result nothing was deleted, so the form is given back for another choice. After a result, a retry
+        that could not be prepared keeps the results already obtained and adds its cause below them.
+        """
+        self.busy = False
+        if self.outcome is None:
+            if not self.completed:
+                self._set_controls_enabled(True)
+            super().show_error(cause)
+            return
+        self._show_summary(self.outcome, [(cause, True)])
+
+    def show_outcome(self, outcome: OperationOutcome) -> None:
+        """Close once every requested destination was deleted; otherwise keep the form with each destination's result.
+
+        After a failed step the results and, when the failed step can be tried again, Retry failed step appear under the
+        remote list. The window follows them both ways by the common growth rule: it grows to show them, and gives back
+        the height of the lines that leave when a shorter text replaces them, never below its opening height.
+        """
+        self.busy = False
+        self.outcome = outcome
+        if outcome.status == OperationStatus.SUCCESS and self._requested_operation_set() <= self._successful_operation_set(outcome):
+            self.accept()
+            return
+        self.completed = True
+        self._set_controls_enabled(False)
+        self._show_summary(outcome, [])
+
+    def _requested_operation_set(self) -> set[str]:
+        """Name the deletion steps this request asked for: always the local one, the remote one when a remote was chosen."""
+        operation_set = {DELETE_LOCAL_TAG_OPERATION}
+        if self.remote_request is not None:
+            operation_set.add(DELETE_REMOTE_TAG_OPERATION)
+        return operation_set
+
+    def _successful_operation_set(self, outcome: OperationOutcome) -> set[str]:
+        """Name the deletion steps the result reports as done."""
+        operation_set: set[str] = set()
+        for step in outcome.steps:
+            if step.status == OperationStatus.SUCCESS:
+                operation_set.add(step.operation)
+        return operation_set
+
+    def _remote_name(self) -> str:
+        """Name the chosen remote as the summary writes it, or a generic word for a local deletion."""
+        if self.remote_request is None:
+            return REMOTE_LIST_NAME
+        _remote_snapshot, remote_name, _destination, _endpoint, _push_target = self.remote_request
+        return remote_name
+
+    def _show_summary(self, outcome: OperationOutcome, extra_lines: list[tuple[str, bool]]) -> None:
+        """Write one line per destination, its diagnostic and any extra cause, and offer Retry only for a failed step that can be retried."""
+        remote_name = self._remote_name()
+        destination_by_operation = {DELETE_LOCAL_TAG_OPERATION: LOCAL_DESTINATION, DELETE_REMOTE_TAG_OPERATION: remote_name}
+        summary_lines: list[tuple[str, bool]] = []
+        observed_operation_set: set[str] = set()
+        diagnostic_detail_set: set[str] = set()
+        for step in outcome.steps:
+            observed_operation_set.add(step.operation)
+            destination = destination_by_operation.get(step.operation, step.operation)
+            failed = step.status != OperationStatus.SUCCESS
+            summary_lines.append((destination + ": " + step_summary_word(step.status) + " — " + step.effect, failed))
+            if step.diagnostic is not None:
+                summary_lines.append((destination + ": " + step.diagnostic.detail, failed))
+                diagnostic_detail_set.add(step.diagnostic.detail)
+        if outcome.diagnostic is not None and outcome.diagnostic.detail not in diagnostic_detail_set:
+            summary_lines.append(("Operation: " + outcome.diagnostic.detail, outcome.status != OperationStatus.SUCCESS))
+        for operation in (DELETE_LOCAL_TAG_OPERATION, DELETE_REMOTE_TAG_OPERATION):
+            if operation in self._requested_operation_set() and operation not in observed_operation_set:
+                summary_lines.append((destination_by_operation[operation] + ": Awaiting result", False))
+        summary_lines.extend(extra_lines)
+        self.status_label.show_summary(summary_lines)
+        # A remote step whose outcome is unknown may have deleted the tag on the server: it is never retried blindly.
+        remote_unknown = any(step.operation == DELETE_REMOTE_TAG_OPERATION and step.status == OperationStatus.UNKNOWN for step in outcome.steps)
+        retryable = (outcome.status in RETRYABLE_OUTCOME_STATUS_SET and not remote_unknown
+                     and any(step.status in RETRYABLE_STEP_STATUS_SET for step in outcome.steps))
+        self.summary_space.show()
+        self.status_area.show()
+        self.retry_button.setVisible(retryable)
+        self.retry_button.setEnabled(retryable)
+
+    def _set_controls_enabled(self, enabled: bool) -> None:
+        """Enable or disable the choices of the form together; the remote list only ever while the check box is checked."""
+        self.tag_combo.setEnabled(enabled)
+        self.remote_checkbox.setEnabled(enabled)
+        self.remote_combo.setEnabled(enabled and self.remote_checkbox.isChecked())
+        if not enabled:
+            self.submit_button.setEnabled(False)

gitpane/ui/reference/form_opening.py

@@ -0,0 +1,53 @@
+"""End the opening of a reference form one of three ways: shown once its check accepts it, refused with its warning alone, or closed unseen.
+
+A reference form opens on the references its repository window last read, and GitPane checks them again before the
+form can do anything. When that check refuses (the branches changed since, the read failed, the window was refreshed
+meanwhile), a form shown at once would only sit greyed behind its warning, and the user would have to close both. The
+form therefore stays hidden until its check answers: accepted, it is shown filled; refused, it is closed unseen and the
+refusal opens alone, under the form's title, over the window the form belongs to. A form whose check ends otherwise
+(its filling failed, it stopped being current) is closed unseen without a warning. A form closed unseen is deleted,
+since nobody can reopen it. A refusal that comes later, once the form is in use, stays in the form.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QDialog
+
+from gitpane.ui.reference.reference_form import reference_warning_box
+from gitpane.ui.window_control.dialog_modality import open_window_modal
+
+if TYPE_CHECKING:
+    from PySide6.QtWidgets import QWidget
+
+
+def reveal_form(dialog: QDialog) -> None:
+    """Show a form its opening check accepted, blocking its repository window like any reference form; a form already shown is left as it is."""
+    if dialog.isVisible():
+        return
+    open_window_modal(dialog)
+
+
+def close_unseen_form(dialog: QDialog) -> None:
+    """Close a form that was never shown, so its registry and its late answers let it go and the next click opens a new one, then delete it.
+
+    The form is deleted at the next turn of the event loop rather than left hidden in its window until that window
+    closes: nobody can show it again, and each new click makes a new form.
+    """
+    dialog.done(QDialog.DialogCode.Rejected)
+    dialog.deleteLater()
+
+
+def refuse_form_opening(dialog: QDialog, cause: str) -> None:
+    """Close a form its opening check refused without ever showing it, and show the refusal alone over its repository window.
+
+    The warning keeps the form's title, so the user knows which action was refused, and the text the form would have
+    shown, with anything sensitive removed. Closing the warning leaves nothing else open.
+    """
+    window: QWidget | None = dialog.parentWidget()
+    box = reference_warning_box(dialog.windowTitle(), cause, window)
+    box.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
+    close_unseen_form(dialog)
+    open_window_modal(box)