bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/composites/textarea/extensions/bracket_matcher.py

@@ -0,0 +1,138 @@
+"""BracketMatcher — highlights matching bracket pairs on cursor move.
+
+Filter-style extension: binds to cursor-movement events and applies a
+highlight tag to the bracket under the cursor and its matching pair.
+Uses a flash-and-restore pattern borrowed from idlelib/parenmatch.py.
+"""
+from __future__ import annotations
+
+import tkinter as tk
+from typing import TYPE_CHECKING
+
+from bootstack.widgets._impl.composites.textarea.filter import EditFilter
+
+if TYPE_CHECKING:
+    from bootstack.widgets._impl.composites.textarea.core import _MultilineCore
+
+_OPENERS = "([{"
+_CLOSERS = ")]}"
+_PAIRS = dict(zip(_OPENERS, _CLOSERS))
+_REVERSE = dict(zip(_CLOSERS, _OPENERS))
+
+_LAYER = "bracket"
+_STYLE = "match"
+_TAG = f"bs::{_LAYER}::{_STYLE}"
+_FLASH_MS = 500     # how long to show the highlight
+
+
+class BracketMatcher(EditFilter):
+    """Highlights matching bracket pairs when the cursor rests on a bracket.
+
+    Install via `core.add_filter(BracketMatcher())`.
+    The highlight tag `bs::bracket::match` is applied to both the bracket
+    under the cursor and its matching partner. It is removed after
+    `_FLASH_MS` milliseconds or on the next cursor move.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._core: _MultilineCore | None = None
+        self._after_id: str | None = None
+
+    def attach(self, core: _MultilineCore) -> None:
+        self._core = core
+        core.define_style(_STYLE, foreground="primary", background="primary[subtle]")
+        core.register_layer(_LAYER, priority=5)
+        core.text.bind("<<CursorMove>>", self._on_cursor_move, add="+")
+        core.text.bind("<KeyRelease>", self._on_cursor_move, add="+")
+        core.text.bind("<ButtonRelease-1>", self._on_cursor_move, add="+")
+
+    def detach(self, core: _MultilineCore) -> None:
+        self._clear()
+        self._core = None
+
+    # ── filter pass-through (BracketMatcher doesn't intercept edits) ──────
+
+    def insert(self, index: str, chars: str, tags=None) -> None:
+        self.delegate.insert(index, chars, tags)
+
+    def delete(self, index1: str, index2: str | None = None) -> None:
+        self.delegate.delete(index1, index2)
+
+    # ── matching logic ────────────────────────────────────────────────────
+
+    def _on_cursor_move(self, _event=None) -> None:
+        self._clear()
+        if self._core is None:
+            return
+        text = self._core.text
+        cursor = text.index("insert")
+        # Check character at cursor and the one before it
+        for idx in (cursor, f"{cursor}-1c"):
+            ch = text.get(idx)
+            if ch in _OPENERS:
+                partner = self._find_close(text, idx, ch)
+                if partner:
+                    self._highlight(idx, partner)
+                return
+            if ch in _CLOSERS:
+                partner = self._find_open(text, idx, ch)
+                if partner:
+                    self._highlight(partner, idx)
+                return
+
+    def _find_close(self, text: tk.Text, start: str, opener: str) -> str | None:
+        closer = _PAIRS[opener]
+        depth = 1
+        idx = text.index(f"{start}+1c")
+        end = text.index("end")
+        while text.compare(idx, "<", end):
+            ch = text.get(idx)
+            if ch == opener:
+                depth += 1
+            elif ch == closer:
+                depth -= 1
+                if depth == 0:
+                    return idx
+            idx = text.index(f"{idx}+1c")
+        return None
+
+    def _find_open(self, text: tk.Text, start: str, closer: str) -> str | None:
+        opener = _REVERSE[closer]
+        depth = 1
+        idx = text.index(f"{start}-1c")
+        while text.compare(idx, ">=", "1.0"):
+            ch = text.get(idx)
+            if ch == closer:
+                depth += 1
+            elif ch == opener:
+                depth -= 1
+                if depth == 0:
+                    return idx
+            if text.compare(idx, "==", "1.0"):
+                break
+            idx = text.index(f"{idx}-1c")
+        return None
+
+    def _highlight(self, a: str, b: str) -> None:
+        if self._core is None:
+            return
+        text = self._core.text
+        for idx in (a, b):
+            text.tag_add(_TAG, idx, f"{idx}+1c")
+        if self._after_id is not None:
+            text.after_cancel(self._after_id)
+        self._after_id = text.after(_FLASH_MS, self._clear)
+
+    def _clear(self) -> None:
+        if self._after_id is not None and self._core is not None:
+            try:
+                self._core.text.after_cancel(self._after_id)
+            except Exception:
+                pass
+            self._after_id = None
+        if self._core is not None:
+            try:
+                self._core.text.tag_remove(_TAG, "1.0", "end")
+            except Exception:
+                pass

bootstack/widgets/_impl/composites/textarea/extensions/indent_guides.py

@@ -0,0 +1,158 @@
+"""IndentGuides — draws subtle guide marks at each indent stop.
+
+Filter-style extension: on each edit (debounced), scans all lines and
+places a single-character background highlight at the last space of each
+tab-stop in the leading whitespace, producing a visual column guide.
+
+Only space-based indentation is supported. Tab-character indentation is
+ignored (guide count will be zero for tab-indented lines).
+"""
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+from bootstack.widgets._impl.composites.textarea.filter import EditFilter
+from bootstack.widgets._impl.composites.textarea.decoration import Position, RangeDecoration
+
+if TYPE_CHECKING:
+    from bootstack.widgets._impl.composites.textarea.core import _MultilineCore
+
+
+_LAYER = "indent"
+_DEBOUNCE_MS = 200
+_STYLE = "guide"
+
+
+class IndentGuides(EditFilter):
+    """Draws subtle vertical guide marks at each indent stop.
+
+    Install via the `show_indent_guides=True` parameter on `CodeEditor`,
+    or manually: `core.add_filter(IndentGuides())`.
+
+    Guide marks are placed on the last space character of each tab-stop
+    group in a line's leading whitespace (e.g. at column 3, 7, 11, ...
+    for `tab_width=4`). Only space-indented lines receive guides.
+
+    Args:
+        tab_width: Spaces per indent level. Should match `SmartIndent`.
+    """
+
+    def __init__(self, tab_width: int = 4) -> None:
+        super().__init__()
+        self._core: _MultilineCore | None = None
+        self._after_id: str | None = None
+        self._tab_width = tab_width
+        self._theme_root: Any = None
+        self._theme_bind_id: str | None = None
+
+    # ── EditFilter protocol ───────────────────────────────────────────────
+
+    def attach(self, core: _MultilineCore) -> None:
+        self._core = core
+        core.register_layer(_LAYER, priority=0)
+        self._apply_guide_style(core)
+        core.text.bind("<<EditorBgChanged>>", self._on_theme_changed, add="+")
+        # Recalibrate guide color after a theme rebuild. Bind <<BsThemeChanged>>
+        # on the root — fired ONCE by bootstack after the full rebuild (correct
+        # colors) — NOT the ttk <<ThemeChanged>>, which fires mid-rebuild.
+        self._theme_root = core.winfo_toplevel()
+        self._theme_bind_id = self._theme_root.bind(
+            "<<BsThemeChanged>>", self._on_theme_changed, add="+"
+        )
+        self._schedule()
+
+    def detach(self, core: _MultilineCore) -> None:
+        self._cancel()
+        if self._theme_bind_id is not None and self._theme_root is not None:
+            try:
+                self._theme_root.unbind("<<BsThemeChanged>>", self._theme_bind_id)
+            except Exception:
+                pass
+            self._theme_bind_id = None
+            self._theme_root = None
+        if self._core is not None:
+            core.clear_decorations(_LAYER)
+        self._core = None
+
+    def insert(self, index: str, chars: str, tags=None) -> None:
+        self.delegate.insert(index, chars, tags)
+        self._schedule()
+
+    def delete(self, index1: str, index2: str | None = None) -> None:
+        self.delegate.delete(index1, index2)
+        self._schedule()
+
+    # ── internal ──────────────────────────────────────────────────────────
+
+    def _apply_guide_style(self, core: _MultilineCore) -> None:
+        try:
+            bg = core.text.cget("background")
+            guide_bg = _subtle_variant(bg)
+        except Exception:
+            guide_bg = "#cccccc"
+        core.define_style(_STYLE, background=guide_bg)
+
+    def _on_theme_changed(self, _event=None) -> None:
+        if self._core is not None:
+            self._apply_guide_style(self._core)
+
+    def _schedule(self) -> None:
+        self._cancel()
+        if self._core is not None:
+            self._after_id = self._core.text.after(_DEBOUNCE_MS, self._update)
+
+    def _cancel(self) -> None:
+        if self._after_id is not None and self._core is not None:
+            try:
+                self._core.text.after_cancel(self._after_id)
+            except Exception:
+                pass
+        self._after_id = None
+
+    def _update(self) -> None:
+        self._after_id = None
+        if self._core is None:
+            return
+        try:
+            text = self._core.value
+        except Exception:
+            return
+
+        decorations = _compute_guides(text, self._tab_width)
+        self._core.set_decorations(_LAYER, decorations)
+
+
+def _compute_guides(text: str, tab_width: int) -> list[RangeDecoration]:
+    """Return guide decorations for every indent stop in `text`."""
+    decorations: list[RangeDecoration] = []
+    for line_num, line in enumerate(text.split("\n"), 1):
+        n = len(line) - len(line.lstrip(" "))
+        for k in range(1, n // tab_width + 1):
+            col = k * tab_width - 1
+            decorations.append(RangeDecoration(
+                Position(line_num, col),
+                Position(line_num, col + 1),
+                _STYLE,
+            ))
+    return decorations
+
+
+def _subtle_variant(hex_color: str) -> str:
+    """Return a slightly darker or lighter shade of `hex_color`."""
+    h = hex_color.lstrip("#")
+    if len(h) < 6:
+        return "#cccccc"
+    try:
+        r, g, b = int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+        luminance = 0.299 * r + 0.587 * g + 0.114 * b
+        if luminance > 128:
+            r2 = max(0, int(r * 0.88))
+            g2 = max(0, int(g * 0.88))
+            b2 = max(0, int(b * 0.88))
+        else:
+            r2 = min(255, r + 28)
+            g2 = min(255, g + 28)
+            b2 = min(255, b + 28)
+        return f"#{r2:02x}{g2:02x}{b2:02x}"
+    except Exception:
+        return "#cccccc"

bootstack/widgets/_impl/composites/textarea/extensions/line_numbers.py

@@ -0,0 +1,138 @@
+"""LineNumbers sidebar — displays line numbers synced with the main text.
+
+Port of idlelib/sidebar.py LineNumbers. Uses a sibling tk.Text widget
+(read-only, no padding, matching font) placed to the left of the main text.
+Width auto-adjusts when the line count crosses a power-of-ten boundary.
+"""
+from __future__ import annotations
+
+import tkinter as tk
+from typing import TYPE_CHECKING
+
+from bootstack.widgets._impl.composites.textarea.sidebar import Sidebar
+
+if TYPE_CHECKING:
+    from bootstack.widgets._impl.composites.textarea.core import _MultilineCore
+
+_PADX = 6    # horizontal padding inside the line-number gutter
+_PADY = 1    # top padding to align with text widget baseline
+
+
+class LineNumbers(Sidebar):
+    """Displays line numbers alongside the text, scroll-synced.
+
+    Add to a `CodeEditor` or `TextArea` core via::
+
+        core.add_sidebar(LineNumbers())
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._widget: tk.Text | None = None
+        self._core: _MultilineCore | None = None
+        self._last_line_count: int = 0
+        self._current_width: int = 1     # digits in the widest line number
+
+    # ── Sidebar protocol ──────────────────────────────────────────────────
+
+    def _build(self, core: _MultilineCore) -> None:
+        self._core = core
+        font = core.text.cget("font") or "TkFixedFont"
+
+        self._widget = tk.Text(
+            core,
+            width=self._current_width,
+            height=core.text.cget("height"),
+            padx=_PADX,
+            pady=_PADY,
+            state=tk.DISABLED,
+            wrap=tk.NONE,
+            font=font,
+            cursor="arrow",
+            takefocus=False,
+            highlightthickness=0,
+            relief=tk.FLAT,
+            borderwidth=0,
+        )
+
+        # Grid in col 0 (left sidebar column), same row as the main text
+        self._widget.grid(row=0, column=0, sticky="ns")
+
+        self._apply_colors()
+        self._update()
+
+    def _destroy(self) -> None:
+        if self._widget is not None:
+            try:
+                self._widget.destroy()
+            except Exception:
+                pass
+            self._widget = None
+
+    def on_scroll(self, first: str, last: str) -> None:
+        """Sync the line-number gutter with the main text scroll position."""
+        if self._widget is not None:
+            self._widget.yview_moveto(first)
+
+    def on_change(self) -> None:
+        """Refresh line numbers after every edit."""
+        self._update()
+
+    def update_font(self) -> None:
+        """Sync the gutter font with the main text font."""
+        if self._widget and self._core:
+            font = self._core.text.cget("font")
+            self._widget.configure(font=font)
+
+    def update_colors(self, event=None) -> None:
+        """Reapply theme colors."""
+        self._apply_colors()
+
+    # ── internals ─────────────────────────────────────────────────────────
+
+    def _update(self) -> None:
+        """Recompute and render the line numbers."""
+        if self._widget is None or self._core is None:
+            return
+
+        line_count = self._line_count()
+        self._adjust_width(line_count)
+
+        numbers = "\n".join(str(i) for i in range(1, line_count + 1))
+
+        self._widget.configure(state=tk.NORMAL)
+        self._widget.delete("1.0", tk.END)
+        self._widget.insert("1.0", numbers)
+        self._widget.configure(state=tk.DISABLED)
+
+        self._last_line_count = line_count
+
+    def _line_count(self) -> int:
+        """Return the number of lines in the main text widget."""
+        if self._core is None:
+            return 1
+        idx = self._core.text.index("end-1c")
+        return int(idx.split(".")[0])
+
+    def _adjust_width(self, line_count: int) -> None:
+        """Expand or contract the gutter when line count crosses a decade."""
+        needed = len(str(line_count))
+        if needed != self._current_width:
+            self._current_width = needed
+            if self._widget:
+                self._widget.configure(width=needed)
+
+    def _apply_colors(self) -> None:
+        """Apply theme-aware foreground/background to the gutter."""
+        if self._widget is None:
+            return
+        try:
+            from bootstack.style.style import get_theme_provider
+            colors = get_theme_provider().colors
+            fg = colors.get("muted", "#888888")
+            bg = colors.get("chrome", "#f0f0f0")
+            self._widget.configure(foreground=fg, background=bg,
+                                   selectbackground=bg, selectforeground=fg,
+                                   inactiveselectbackground=bg)
+        except Exception:
+            pass