utils/gatelock/gatelock/corner_strip.py

# Copyright (c) 2026 Krzysztof Rudnicki
"""A small always-on-top strip in the top-right corner of the primary output.

For the time a gate is *stood down but not done*: the lock is not up, yet the
user still owes something (a morning session to finish, solves to submit).
Without it the screen just clears and the lock returns out of nowhere.

Top-right because the centre is where the user's actual work sits and the
bottom-right is where desktop notifications land. Lifted from leetcode-guard's
study strip so every gate shows the same thing in the same place.

The strip never grabs input and never re-asserts a grab; its tick only
refreshes the text and re-lifts the window. ``supply`` returning ``None`` is
the one way it ends on its own, so the owner decides when the debt is gone.
"""

from __future__ import annotations

from dataclasses import dataclass
import logging
import tkinter as tk
from typing import TYPE_CHECKING, Final

if TYPE_CHECKING:
    from collections.abc import Callable, Sequence

    from gatelock._config import LockConfig
    from gatelock._output_types import OutputRect, OutputScan

_logger: Final = logging.getLogger(__name__)

_TOPMOST_ON: Final = 1
CORNER_STRIP_WIDTH_PX: Final = 420
CORNER_STRIP_TICK_MS: Final = 1_000


@dataclass(frozen=True)
class StripContent:
    """What the strip says: one bold title and a few plain lines."""

    title: str
    lines: tuple[str, ...]


def corner_rect(scan: OutputScan) -> OutputRect | None:
    """The rectangle to sit on: the primary live output, else the first live.

    The whole X screen spans every monitor on a multi-head desk and would park
    the strip on the far one, so it is always one output's rectangle.
    """
    live = scan.live
    for output in live:
        if output.primary:
            return output.rect
    return live[0].rect if live else None


def corner_geometry(rect: OutputRect, *, width: int, height: int, inset: int) -> str:
    """Tk geometry for a ``width`` x ``height`` window in ``rect``'s top-right."""
    x = rect.x + rect.width - width - inset
    y = rect.y + inset
    return f"{width}x{height}+{x}+{y}"


class CornerStrip:
    """Handle on a built strip: refresh it, tick it, tear it down."""

    def __init__(
        self,
        window: tk.Toplevel,
        title_label: tk.Label,
        line_labels: Sequence[tk.Label],
        *,
        tick_ms: int = CORNER_STRIP_TICK_MS,
    ) -> None:
        """Wrap an already-built strip window."""
        self.window = window
        self._title = title_label
        self._lines = tuple(line_labels)
        self._tick_ms = tick_ms
        self._job: str | None = None
        self._destroyed = False

    @property
    def closed(self) -> bool:
        """Whether the strip is gone (destroyed, or broke on a refresh)."""
        return self._destroyed

    def show(self, content: StripContent) -> None:
        """Write ``content`` and re-lift; lines past the content are blanked."""
        if self._destroyed:
            return
        try:
            self._title.configure(text=content.title)
            for index, label in enumerate(self._lines):
                text = content.lines[index] if index < len(content.lines) else ""
                label.configure(text=text)
            self.window.lift()
        except tk.TclError:
            # A fullscreen window over us is cosmetic; an exception escaping a
            # Tk callback is not. Stop ticking and say so.
            _logger.warning("the corner strip could not refresh", exc_info=True)
            self._destroyed = True

    def schedule(
        self,
        supply: Callable[[], StripContent | None],
        *,
        on_close: Callable[[], None],
    ) -> None:
        """Tick: show ``supply()`` until it returns None, then close."""
        if self._destroyed:
            return

        def run() -> None:
            content = supply()
            if content is None:
                self.destroy()
                on_close()
                return
            self.show(content)
            if not self._destroyed:
                self._job = self.window.after(self._tick_ms, run)

        self._job = self.window.after(self._tick_ms, run)

    def destroy(self) -> None:
        """Cancel the tick and tear the window down. Idempotent."""
        if self._destroyed:
            return
        self._destroyed = True
        try:
            if self._job is not None:
                self.window.after_cancel(self._job)
            self.window.destroy()
        except tk.TclError:
            _logger.warning("the corner strip could not be destroyed", exc_info=True)


def build_corner_strip(
    root: tk.Misc,
    config: LockConfig,
    content: StripContent,
    *,
    rect: OutputRect,
    max_lines: int = 3,
) -> CornerStrip:
    """Create the strip in ``rect``'s top-right corner, showing ``content``.

    ``max_lines`` labels are built up front so later content can grow into
    them without re-layout; the height is whatever those labels ask for.
    """
    width = CORNER_STRIP_WIDTH_PX
    window = tk.Toplevel(root)
    # Override-redirect must be set while withdrawn or the geometry is ignored.
    window.withdraw()
    window.overrideredirect(boolean=True)
    window.configure(bg=config.palette.field_bg)
    wrap = width - 2 * config.space("md")

    title = tk.Label(
        window,
        text=content.title,
        font=config.font("label", bold=True),
        fg=config.palette.fg,
        bg=config.palette.field_bg,
        wraplength=wrap,
    )
    title.pack(pady=(config.space("sm"), 0), padx=config.space("md"))
    lines = []
    for index in range(max_lines):
        label = tk.Label(
            window,
            text=content.lines[index] if index < len(content.lines) else "",
            font=config.font("body" if index == 0 else "caption"),
            fg=config.palette.accent if index == 0 else config.palette.muted,
            bg=config.palette.field_bg,
            wraplength=wrap,
            justify="left",
        )
        label.pack(padx=config.space("md"))
        lines.append(label)
    if lines:
        lines[-1].pack_configure(pady=(0, config.space("sm")))

    window.update_idletasks()
    height = int(window.winfo_reqheight())
    window.geometry(
        corner_geometry(rect, width=width, height=height, inset=config.space("md"))
    )
    window.deiconify()
    window.lift()
    # A hint most window managers honour even for override-redirect windows.
    window.attributes("-topmost", _TOPMOST_ON)
    return CornerStrip(window, title, lines)