zettcode-tui 0.4.0__py3-none-any.whl

zettcode/tui/widgets/dialog.py

@@ -0,0 +1,165 @@
+"""A framed modal body with a row of selectable actions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from ..core.events import KeyEvent
+from ..core.geometry import Constraints, Rect, Size
+from ..core.host import Host
+from ..core.widget import Widget
+from ..layout import Border, Slot, VBox
+from ..render import Canvas, Style
+from ..render.text import display_width
+
+
+@dataclass(frozen=True, slots=True)
+class DialogAction:
+    """One button in a dialog.
+
+    Attributes:
+        label: Text drawn on the button.
+        run: Called when the action is activated; ``None`` renders a button that
+            cannot be committed.
+    """
+
+    label: str
+    run: Callable[[], None] | None = None
+
+
+class _ActionRow(Widget):
+    """Internal row that paints the dialog buttons."""
+
+    def __init__(self, dialog: Dialog) -> None:
+        """Bind the row to the dialog that owns the actions."""
+        super().__init__()
+        self.dialog = dialog
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Claim a minimal cell; the parent box supplies the real width."""
+        return constraints.constrain(Size(1, 1))
+
+    def render(self, canvas: Canvas) -> None:
+        """Paint the actions along the last row of the assigned rectangle."""
+        if self.rect.empty:
+            return
+        theme = self.theme
+        y = self.rect.y + self.rect.height - 1
+        x = self.rect.x
+        for index, action in enumerate(self.dialog.actions):
+            if x >= self.rect.x + self.rect.width:
+                break
+            label = f" {action.label} "
+            selected = index == self.dialog.action_index
+            style = (
+                Style(foreground=theme.surface, background=theme.accent, bold=True)
+                if selected
+                else Style(foreground=theme.muted)
+            )
+            canvas.draw_text(x, y, label, style, max_width=self.rect.x + self.rect.width - x)
+            x += display_width(label) + 1
+
+
+class Dialog(Widget):
+    """A bordered body plus actions, meant to live on a modal screen.
+
+    Shape::
+
+        +-- Run this command? --------+  <- frame, title embedded in the top edge
+        |rm -rf build/                |  <- body, takes the flexible rows
+        |                             |
+        | Run   Always   Abort        |  <- actions on the last row, one highlighted
+        +-----------------------------+
+
+    The frame uses box-drawing glyphs and clears its own rectangle before
+    drawing, so a dialog over another screen is opaque. Left and Right move the
+    highlight, Enter runs it, Escape cancels when ``on_cancel`` is given.
+    """
+
+    def __init__(
+        self,
+        body: Widget | None = None,
+        *,
+        title: str = "",
+        actions: Sequence[DialogAction] = (),
+        on_cancel: Callable[[], None] | None = None,
+    ) -> None:
+        """Wrap the body and the action row in a border, with or without a body.
+
+        Args:
+            body: Content above the buttons; ``None`` leaves a dialog of pure
+                actions, which is still laid out with the same frame.
+            title: Drawn into the top border when the dialog is wide enough.
+            actions: Buttons in focus order; the first one starts highlighted.
+            on_cancel: Called on Escape when one is provided.
+        """
+        super().__init__()
+        self.body = body
+        self.actions = tuple(actions)
+        self.action_index = 0
+        self.on_cancel = on_cancel
+        row = _ActionRow(self)
+        inner = VBox([Slot(body, flex=1), Slot(row, size=1)]) if body is not None else VBox([Slot(row, flex=1)])
+        self.frame = Border(inner, title=title)
+
+    @property
+    def focusable(self) -> bool:
+        """Take focus so the arrow keys and Enter drive the actions."""
+        return True
+
+    @property
+    def children(self) -> tuple[Widget, ...]:
+        """Expose the bordered frame."""
+        return (self.frame,)
+
+    @property
+    def current_action(self) -> DialogAction | None:
+        """Return the highlighted action, or None when there are no actions."""
+        if 0 <= self.action_index < len(self.actions):
+            return self.actions[self.action_index]
+        return None
+
+    def activate(self) -> bool:
+        """Run the selected action, if it has a handler."""
+        action = self.current_action
+        if action is None or action.run is None:
+            return False
+        action.run()
+        return True
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Measure the frame, which measures the body in turn."""
+        return self.frame.measure(constraints)
+
+    def layout(self, rect: Rect) -> None:
+        """Give the frame the whole assigned rectangle."""
+        super().layout(rect)
+        self.frame.layout(rect)
+
+    def render(self, canvas: Canvas) -> None:
+        """Paint the frame and everything inside it."""
+        self.frame.render(canvas)
+
+    def handle(self, event, host: Host) -> bool:
+        """Move between actions, run one, or cancel the dialog."""
+        if not isinstance(event, KeyEvent) or host.focused_widget() is not self:
+            return False
+        match event.key:
+            case "left" | "backtab":
+                self._move(-1)
+            case "right" | "tab":
+                self._move(1)
+            case "enter":
+                return self.activate()
+            case "escape" if self.on_cancel is not None:
+                self.on_cancel()
+                return True
+            case _:
+                return False
+        return True
+
+    def _move(self, amount: int) -> None:
+        """Move the highlight, wrapping at both ends."""
+        if self.actions:
+            self.action_index = (self.action_index + amount) % len(self.actions)

zettcode/tui/widgets/diff.py

@@ -0,0 +1,236 @@
+"""Unified diff parsing with word-level emphasis."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, replace
+from difflib import SequenceMatcher
+from difflib import unified_diff as _unified_diff
+
+from ..core.geometry import Constraints, Size
+from ..core.widget import Widget
+from ..render import Canvas, Style
+from ..render.text import display_width
+
+HUNK = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+TOKEN = re.compile(r"\w+|\s+|[^\w\s]")
+META_PREFIXES = ("diff ", "index ", "--- ", "+++ ", "\\ No newline", "old mode", "new mode", "similarity index")
+
+
+@dataclass(frozen=True, slots=True)
+class DiffSegment:
+    """One run of a diff line, marked when it is what actually changed."""
+
+    text: str
+    emphasis: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class DiffLine:
+    """One rendered diff row in unified-diff order."""
+
+    kind: str
+    text: str
+    segments: tuple[DiffSegment, ...] = ()
+    old_number: int | None = None
+    new_number: int | None = None
+
+
+def word_diff(old: str, new: str) -> tuple[tuple[DiffSegment, ...], tuple[DiffSegment, ...]]:
+    """Return both sides tokenized, marking the tokens that differ.
+
+    Args:
+        old: Text of the removed line.
+        new: Text of the added line it is paired with.
+    """
+    old_tokens = TOKEN.findall(old)
+    new_tokens = TOKEN.findall(new)
+    matcher = SequenceMatcher(None, old_tokens, new_tokens, autojunk=False)
+    old_segments: list[DiffSegment] = []
+    new_segments: list[DiffSegment] = []
+    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+        changed = tag != "equal"
+        old_segments.append(DiffSegment("".join(old_tokens[i1:i2]), changed))
+        new_segments.append(DiffSegment("".join(new_tokens[j1:j2]), changed))
+    return _merge(old_segments), _merge(new_segments)
+
+
+def parse_unified(text: str) -> list[DiffLine]:
+    """Parse unified-diff text, pairing removals with additions by position."""
+    lines: list[DiffLine] = []
+    removals: list[DiffLine] = []
+    additions: list[DiffLine] = []
+    old_number: int | None = None
+    new_number: int | None = None
+
+    def flush() -> None:
+        """Pair buffered removals with additions, then emit both blocks."""
+        nonlocal removals, additions
+        if not removals and not additions:
+            return
+        for index in range(min(len(removals), len(additions))):
+            old_segments, new_segments = word_diff(removals[index].text, additions[index].text)
+            removals[index] = replace(removals[index], segments=old_segments)
+            additions[index] = replace(additions[index], segments=new_segments)
+        for line in removals:
+            lines.append(line if line.segments else replace(line, segments=(DiffSegment(line.text, True),)))
+        for line in additions:
+            lines.append(line if line.segments else replace(line, segments=(DiffSegment(line.text, True),)))
+        removals, additions = [], []
+
+    for raw in text.splitlines():
+        if raw.startswith(META_PREFIXES):
+            flush()
+            lines.append(DiffLine("meta", raw))
+            continue
+        hunk = HUNK.match(raw)
+        if hunk:
+            flush()
+            old_number = int(hunk.group(1))
+            new_number = int(hunk.group(3))
+            lines.append(DiffLine("hunk", raw))
+            continue
+        if raw.startswith("+"):
+            additions.append(DiffLine("add", raw[1:], new_number=new_number))
+            new_number = None if new_number is None else new_number + 1
+            continue
+        if raw.startswith("-"):
+            removals.append(DiffLine("remove", raw[1:], old_number=old_number))
+            old_number = None if old_number is None else old_number + 1
+            continue
+        flush()
+        content = raw[1:] if raw.startswith(" ") else raw
+        lines.append(DiffLine("context", content, old_number=old_number, new_number=new_number))
+        old_number = None if old_number is None else old_number + 1
+        new_number = None if new_number is None else new_number + 1
+    flush()
+    return lines
+
+
+def build_unified(
+    old: str,
+    new: str,
+    *,
+    fromfile: str = "a",
+    tofile: str = "b",
+    context: int = 3,
+) -> list[DiffLine]:
+    """Diff two texts and return parsed diff rows.
+
+    Args:
+        old: Original text; trailing newlines are ignored.
+        new: Replacement text.
+        fromfile: Label of the original side in the ``---`` header line.
+        tofile: Label of the replacement side in the ``+++`` header line.
+        context: Unchanged lines kept around each hunk.
+    """
+    # difflib appends its own terminator to header lines, so the terminator has
+    # to be suppressed before joining: a stray blank line would otherwise parse
+    # as a context row and shift every following line number.
+    text = "\n".join(_unified_diff(old.splitlines(), new.splitlines(), fromfile, tofile, n=context, lineterm=""))
+    return parse_unified(text)
+
+
+class DiffView(Widget):
+    """Paint unified-diff rows with a gutter and word-level emphasis.
+
+    Shape::
+
+                 --- a
+                 +++ b
+                 @@ -1,5 +1,2 @@          <- hunk headers, dim
+          1    1  def total(items):      <- old and new line numbers
+          2       -    value = 0          <- removed
+               2  +    return sum(...)    <- added
+
+    The gutter is reserved only when the diff carries line numbers. Removed and
+    added lines are paired by position, and only the tokens that actually differ
+    get the selection colour, which is what makes a one-word change readable.
+    """
+
+    def __init__(self, lines: tuple[DiffLine, ...] | list[DiffLine] = ()) -> None:
+        """Store the diff rows; the widget itself only paints them.
+
+        Args:
+            lines: Rows in unified-diff order, as ``parse_unified`` returns them.
+        """
+        super().__init__()
+        self.lines = tuple(lines)
+
+    @classmethod
+    def from_text(cls, text: str) -> DiffView:
+        """Build a view from unified-diff text."""
+        return cls(parse_unified(text))
+
+    @classmethod
+    def between(cls, old: str, new: str, *, context: int = 3) -> DiffView:
+        """Diff two texts with difflib and wrap the result.
+
+        Args:
+            old: Original text; trailing newlines are ignored.
+            new: Replacement text.
+            context: Unchanged lines kept around each hunk.
+        """
+        return cls(build_unified(old, new, context=context))
+
+    @property
+    def gutter(self) -> int:
+        """Reserve line numbers only when the diff actually carries them."""
+        if any(line.old_number is not None or line.new_number is not None for line in self.lines):
+            return 11
+        return 0
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Ask for the widest row plus the gutter and the sign column."""
+        widest = max((display_width(line.text) + self.gutter + 1 for line in self.lines), default=0)
+        return constraints.constrain(Size(widest, len(self.lines)))
+
+    def render(self, canvas: Canvas) -> None:
+        """Paint each row with its line numbers, sign, and emphasised segments."""
+        if self.rect.empty:
+            return
+        theme = self.theme
+        styles = {
+            "add": Style(foreground=theme.accent, bold=True),
+            "remove": Style(foreground=theme.error, bold=True),
+            "hunk": Style(foreground=theme.accent_bright, dim=True),
+            "meta": Style(foreground=theme.muted, dim=True),
+            "context": Style(foreground=theme.subtle),
+        }
+        gutter = self.gutter
+        limit = self.rect.x + self.rect.width
+        for row, line in enumerate(self.lines[: self.rect.height]):
+            y = self.rect.y + row
+            x = self.rect.x
+            style = styles.get(line.kind, styles["context"])
+            if gutter:
+                old = "" if line.old_number is None else str(line.old_number)
+                new = "" if line.new_number is None else str(line.new_number)
+                x += canvas.draw_text(
+                    x,
+                    y,
+                    f"{old:>4} {new:>4} ",
+                    Style(foreground=theme.muted, dim=True),
+                    max_width=gutter,
+                )
+            sign = {"add": "+", "remove": "-", "context": " "}.get(line.kind, " ")
+            x += canvas.draw_text(x, y, sign, style, max_width=max(0, limit - x))
+            segments = line.segments or (DiffSegment(line.text),)
+            for segment in segments:
+                if x >= limit:
+                    break
+                segment_style = replace(style, background=theme.selection, bold=True) if segment.emphasis else style
+                x += canvas.draw_text(x, y, segment.text, segment_style, max_width=limit - x)
+
+
+def _merge(segments: list[DiffSegment]) -> tuple[DiffSegment, ...]:
+    """Join adjacent runs that share an emphasis flag."""
+    merged: list[DiffSegment] = []
+    for segment in segments:
+        if not segment.text:
+            continue
+        if merged and merged[-1].emphasis == segment.emphasis:
+            merged[-1] = DiffSegment(merged[-1].text + segment.text, segment.emphasis)
+        else:
+            merged.append(segment)
+    return tuple(merged)

zettcode/tui/widgets/list.py

@@ -0,0 +1,293 @@
+"""Selectable list with keyboard navigation and a scrolling window."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+
+from zettcode.tui import MARKER
+
+from ..core.events import KeyEvent, MouseAction, MouseEvent
+from ..core.geometry import Constraints, Size
+from ..core.host import Host
+from ..core.theme import Theme
+from ..core.widget import Widget
+from ..render import Canvas, Style, truncate
+from ..render.text import display_width
+
+#: Text and the colour to draw it in; ``None`` leaves the colour the row would have had.
+Part = tuple[str, str | None]
+
+#: Pieces of a line in the active theme's colours, which only the theme can say.
+Parts = Callable[[Theme], Sequence[Part]]
+
+
+def draw_parts(canvas: Canvas, x: int, y: int, parts: Sequence[Part], style: Style, *, max_width: int) -> int:
+    """Draw coloured pieces one after another and return the columns used.
+
+    Args:
+        canvas: Where to paint.
+        x: Column of the first piece.
+        y: Row.
+        parts: Text and foreground colour of each piece, in order; a ``None`` colour keeps ``style``'s.
+        style: Everything but the foreground: background, weight.
+        max_width: Column budget for all the pieces together; the one that does not fit is cut, the rest dropped.
+    """
+    used = 0
+    for text, colour in parts:
+        room = max_width - used
+        if room <= 0:
+            break
+        piece = style if colour is None else Style(foreground=colour, background=style.background, bold=style.bold)
+        used += canvas.draw_text(x + used, y, truncate(text, room), piece, max_width=room)
+    return used
+
+
+@dataclass(frozen=True, slots=True)
+class ListItem:
+    """One row of a ListView.
+
+    Attributes:
+        value: Opaque payload handed back to the callbacks.
+        label: Left-hand text of the row.
+        description: Secondary text drawn after the label when space allows.
+        disabled: Skipped by navigation and refused by ``activate``.
+        parts: The same description in colours. It must read as ``description`` when its pieces are joined, which
+            is what sizes the column; ``None`` draws ``description`` in the muted colour.
+    """
+
+    value: object = None
+    label: str = ""
+    description: str = ""
+    disabled: bool = False
+    parts: Parts | None = field(default=None, compare=False)
+
+
+class ListView(Widget):
+    """Show rows and let one of them be selected.
+
+    The window is an absolute row index so the list never rebuilds itself, and
+    the selection is always kept inside the visible window.
+
+    Shape::
+
+        > alpha  first                    <- selected: marker, bold, selection band
+          beta   second                   <- descriptions share one column
+          gamma                           <- disabled: dim, no marker, refuses Enter
+          delta  fourth
+
+    Only ``rect.height`` rows are drawn, starting at ``top``; the marker is part
+    of the label (U+25B8 selected, two spaces otherwise) and the muted
+    description keeps the row's background so the selection band stays
+    continuous. Descriptions start in one column, the width of the widest label
+    plus a gap, measured in cells so a CJK label counts double; when the row is
+    too narrow for that column the description falls back to sitting one cell
+    after its own label, and a label with a description is truncated to the
+    column so the two can never collide.
+    """
+
+    MARKERS = (f"{MARKER} ", "  ")
+    #: Cells the marker column occupies, and the gap before the description column.
+    MARKER_WIDTH = 2
+    COLUMN_GAP = 2
+
+    def __init__(
+        self,
+        items: Sequence[ListItem] = (),
+        *,
+        on_select: Callable[[ListItem], None] | None = None,
+        on_highlight: Callable[[ListItem], None] | None = None,
+        wrap: bool = True,
+        band: bool = False,
+    ) -> None:
+        """Configure the rows, the callbacks, and whether the selection wraps.
+
+        Args:
+            items: Initial rows; ``set_items`` replaces them wholesale.
+            on_select: Called with the row when Enter or ``activate`` commits it.
+            on_highlight: Called only when the selection actually moves, which
+                makes it safe to use for previewing the highlighted row.
+            wrap: Wrap from the last row to the first and back.
+            band: Fill the entire highlighted row, not just the label.
+        """
+        super().__init__()
+        self._items = tuple(items)
+        self.on_select = on_select
+        self.on_highlight = on_highlight
+        self.wrap = wrap
+        self.band = band
+        self.selected = 0 if self._items else -1
+        self.top = 0
+
+    @property
+    def focusable(self) -> bool:
+        """Let Tab land on the list so the arrow keys work without a click."""
+        return True
+
+    @property
+    def items(self) -> tuple[ListItem, ...]:
+        """Return the rows currently shown."""
+        return self._items
+
+    def set_items(self, items: Sequence[ListItem]) -> None:
+        """Replace the rows and reset the selection to the top."""
+        self._items = tuple(items)
+        self.selected = 0 if self._items else -1
+        self.top = 0
+
+    @property
+    def current(self) -> ListItem | None:
+        """Return the selected row, or None when the list is empty."""
+        if 0 <= self.selected < len(self._items):
+            return self._items[self.selected]
+        return None
+
+    def select(self, index: int, *, notify: bool = True) -> None:
+        """Move the selection to a row, skipping disabled entries.
+
+        Args:
+            index: Target row, clamped to the list; a disabled row is refused.
+            notify: Call ``on_highlight`` when the row actually changes. Pass
+                False for programmatic resets that should stay silent.
+        """
+        if not self._items:
+            self.selected = -1
+            return
+        index = min(max(0, index), len(self._items) - 1)
+        if self._items[index].disabled:
+            return
+        changed = index != self.selected
+        self.selected = index
+        if changed and notify and self.on_highlight is not None:
+            self.on_highlight(self._items[index])
+
+    def move(self, amount: int) -> None:
+        """Move the selection, wrapping when configured to."""
+        if not self._items:
+            return
+        count = len(self._items)
+        index = self.selected + amount
+        if self.wrap:
+            index %= count
+        else:
+            index = min(max(0, index), count - 1)
+        step = 1 if amount >= 0 else -1
+        for offset in range(count):
+            candidate = (index + offset * step) % count
+            if not self._items[candidate].disabled:
+                self.select(candidate)
+                return
+
+    def activate(self) -> bool:
+        """Fire the select callback for the current row."""
+        item = self.current
+        if item is None or item.disabled or self.on_select is None:
+            return False
+        self.on_select(item)
+        return True
+
+    def measure(self, constraints: Constraints) -> Size:
+        """Ask for the label column, the gap, the widest description, and a row each."""
+        column = max((display_width(item.label) for item in self._items), default=0)
+        description = max((display_width(item.description) for item in self._items), default=0)
+        width = self.MARKER_WIDTH + column
+        if description:
+            width += self.COLUMN_GAP + description
+        return constraints.constrain(Size(width, len(self._items)))
+
+    def render(self, canvas: Canvas) -> None:
+        """Scroll the selection into view, then paint the visible rows."""
+        if not self._items or self.rect.height <= 0:
+            return
+        self._ensure_visible()
+        theme = self.theme
+        # One column for every label, so descriptions line up down the list
+        # instead of starting wherever each label happens to end.
+        column = max((display_width(item.label) for item in self._items), default=0)
+        for row in range(self.rect.height):
+            index = self.top + row
+            if index >= len(self._items):
+                break
+            item = self._items[index]
+            selected = index == self.selected
+            marker = self.MARKERS[0] if selected else self.MARKERS[1]
+            if item.disabled:
+                style = Style(foreground=theme.muted, dim=True)
+            elif selected:
+                style = Style(foreground=theme.text, background=theme.selection, bold=True)
+            else:
+                style = Style(foreground=theme.text, background=theme.surface_alt if self.band else None)
+            if selected and self.band:
+                canvas.fill(self.rect.x, self.rect.y + row, self.rect.width, 1, style)
+            aligned = self.MARKER_WIDTH + column + self.COLUMN_GAP
+            room = self.rect.width - aligned
+            # Without room for a second column, the description falls back to
+            # one space after the label, as it did before the column existed.
+            inline = display_width(marker + item.label) + 1
+            start = aligned if room > 3 else inline
+            limit = self.rect.width if not item.description else max(0, start - 1)
+            label = truncate(marker + item.label, limit)
+            canvas.draw_text(self.rect.x, self.rect.y + row, label, style, max_width=self.rect.width)
+            if item.description:
+                # Columns, not code points: a label of CJK characters is twice
+                # as wide as it is long, and counting its length would pull the
+                # description left by one column per wide glyph.
+                room = self.rect.width - start
+                if room > 3:
+                    quiet = Style(foreground=theme.muted, background=style.background)
+                    if item.parts is None or item.disabled:
+                        canvas.draw_text(
+                            self.rect.x + start,
+                            self.rect.y + row,
+                            truncate(item.description, room),
+                            quiet,
+                            max_width=room,
+                        )
+                    else:
+                        draw_parts(
+                            canvas,
+                            self.rect.x + start,
+                            self.rect.y + row,
+                            item.parts(theme),
+                            Style(background=style.background, bold=False),
+                            max_width=room,
+                        )
+
+    def handle(self, event, host: Host) -> bool:
+        """Select the clicked row, or move with the arrow and page keys."""
+        if isinstance(event, MouseEvent) and self.rect.contains(event.x, event.y):
+            if event.action is MouseAction.DOWN:
+                self.select(self.top + event.y - self.rect.y)
+                host.focus(self)
+                return True
+            return False
+        if not isinstance(event, KeyEvent) or host.focused_widget() is not self:
+            return False
+        page = max(1, self.rect.height - 1)
+        match event.key:
+            case "up":
+                self.move(-1)
+            case "down":
+                self.move(1)
+            case "page_up":
+                self.move(-page)
+            case "page_down":
+                self.move(page)
+            case "home":
+                self.select(0)
+            case "end":
+                self.select(len(self._items) - 1)
+            case "enter":
+                return self.activate()
+            case _:
+                return False
+        return True
+
+    def _ensure_visible(self) -> None:
+        """Scroll the window so the selected row stays on screen."""
+        height = max(1, self.rect.height)
+        if self.selected < self.top:
+            self.top = self.selected
+        elif self.selected >= self.top + height:
+            self.top = self.selected - height + 1
+        self.top = min(max(0, self.top), max(0, len(self._items) - height))