bootstack 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,312 @@
+"""PygmentsHighlighter — syntax highlighting via Pygments.
+
+Implements a debounced full-document retokenize strategy: on each
+insert/delete, schedules a retokenize after 150 ms. Tokens are mapped
+to `RangeDecoration` objects and applied via the decoration layer system.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pygments import lex
+from pygments.lexers import get_lexer_by_name, TextLexer
+from pygments.styles import get_style_by_name
+from pygments.token import Token
+from pygments.util import ClassNotFound
+
+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 = "syntax"
+_DEBOUNCE_MS = 150
+
+# Token family → bootstack style name.  More-specific entries must come
+# before their parents so that the parent-walk hits the right name first.
+_TOKEN_TO_STYLE: dict = {
+    Token.String.Doc: "string_doc",
+    Token.String: "string",
+    Token.Keyword: "keyword",
+    Token.Comment: "comment",
+    Token.Number: "number",
+    Token.Operator: "operator",
+    Token.Name.Builtin: "name_builtin",
+    Token.Name.Function: "name_function",
+    Token.Name.Class: "name_class",
+    Token.Name.Decorator: "name_decorator",
+    Token.Name.Exception: "name_exception",
+    Token.Name.Namespace: "name_namespace",
+    Token.Name.Tag: "name_tag",           # JSON keys, HTML/XML tags
+    Token.Name.Attribute: "name_attribute",  # HTML/XML attributes
+    Token.Punctuation: "punctuation",
+    Token.Error: "error",
+}
+
+# Reverse map: style name → canonical token (used for color extraction)
+_STYLE_TO_TOKEN: dict = {v: k for k, v in _TOKEN_TO_STYLE.items()}
+
+
+def _find_style(ttype) -> str | None:
+    """Walk up the Pygments token hierarchy to find the nearest style name."""
+    t = ttype
+    while t is not None:
+        if t in _TOKEN_TO_STYLE:
+            return _TOKEN_TO_STYLE[t]
+        t = t.parent
+    return None
+
+
+def _extract_colors(style_cls) -> dict[str, str]:
+    """Return `{style_name: '#RRGGBB'}` for all style names that have a color."""
+    colors: dict[str, str] = {}
+    for name, token in _STYLE_TO_TOKEN.items():
+        info = style_cls.style_for_token(token)
+        color = info.get("color")
+        if color:
+            colors[name] = f"#{color}"
+    return colors
+
+
+def _contrast_color(hex_color: str) -> str:
+    """Return black or white for maximum contrast against `hex_color`."""
+    h = hex_color.lstrip("#")
+    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
+        return "#000000" if luminance > 128 else "#ffffff"
+    except Exception:
+        return "#000000"
+
+
+class PygmentsHighlighter(EditFilter):
+    """Syntax highlighting via Pygments.
+
+    Install via the `language=` parameter on `CodeEditor`, or manually:
+
+        core.add_filter(PygmentsHighlighter("python"))
+
+    Uses a debounced full-document retokenize: 150 ms after the last edit the
+    full text is re-lexed, tokens are converted to `RangeDecoration` objects,
+    and applied via `core.set_decorations()`.
+
+    Args:
+        language: Pygments lexer name (e.g. `'python'`, `'sql'`,
+            `'javascript'`). Unknown names fall back to plain text.
+        pygments_style: Pygments style name, or `'auto'` to track the
+            bootstack theme. When `'auto'`, `light_style` and `dark_style`
+            determine the actual Pygments style used.
+        light_style: Pygments style used in auto mode when the active
+            bootstack theme is light. Default `'default'`.
+        dark_style: Pygments style used in auto mode when the active
+            bootstack theme is dark. Default `'monokai'`.
+    """
+
+    def __init__(
+        self,
+        language: str,
+        pygments_style: str = "default",
+        light_style: str = "default",
+        dark_style: str = "monokai",
+    ) -> None:
+        super().__init__()
+        self._core: _MultilineCore | None = None
+        self._after_id: str | None = None
+        self._theme_bind_id: str | None = None
+        self._theme_root = None
+
+        self._auto = pygments_style == "auto"
+        self._light_style = light_style
+        self._dark_style = dark_style
+
+        try:
+            self._lexer = get_lexer_by_name(language, stripall=False, stripnl=False)
+        except ClassNotFound:
+            self._lexer = TextLexer()
+
+        # Load initial style — auto resolves after attach when the theme is known.
+        initial = self._resolve_auto_name() if self._auto else pygments_style
+        self._load_style(initial)
+
+        # Saved originals — restored on detach.
+        self._orig_bg: str | None = None
+        self._orig_fg: str | None = None
+        self._orig_ibg: str | None = None
+
+    # ── EditFilter protocol ───────────────────────────────────────────────
+
+    def attach(self, core: _MultilineCore) -> None:
+        self._core = core
+
+        # Resolve auto style now that we can query the theme provider.
+        if self._auto:
+            self._load_style(self._resolve_auto_name())
+
+        core.register_layer(_LAYER, priority=1)
+        for sname, color in self._style_colors.items():
+            core.define_style(sname, foreground=color)
+
+        # Save current text-widget colors before overriding them.
+        self._orig_bg = core.text.cget("background")
+        self._orig_fg = core.text.cget("foreground")
+        self._orig_ibg = core.text.cget("insertbackground")
+        self._apply_widget_colors(core)
+
+        # Bind to <<BsThemeChanged>> on the root — fired by bootstack after full
+        # rebuild so colors and mode are already accurate when the handler runs.
+        self._theme_root = core.winfo_toplevel()
+        self._theme_bind_id = self._theme_root.bind(
+            "<<BsThemeChanged>>", self._on_framework_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._restore_widget_colors(core)
+        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_widget_colors(self, core: _MultilineCore, notify: bool = True) -> None:
+        kw: dict = {"background": self._style_bg}
+        if self._style_fg:
+            kw["foreground"] = self._style_fg
+        kw["insertbackground"] = self._style_fg or _contrast_color(self._style_bg)
+        try:
+            core.text.configure(**kw)
+            if notify:
+                # Notify extensions that the editor background changed so they
+                # can re-calibrate colors.  Only fire on deliberate style
+                # application (attach / set_language), not on every theme
+                # rebuild — extensions already react to <<BsThemeChanged>>
+                # directly and cascading it causes unnecessary repaints.
+                core.text.event_generate("<<EditorBgChanged>>", when="tail")
+        except Exception:
+            pass
+
+    def _restore_widget_colors(self, core: _MultilineCore) -> None:
+        kw: dict = {}
+        if self._orig_bg is not None:
+            kw["background"] = self._orig_bg
+        if self._orig_fg is not None:
+            kw["foreground"] = self._orig_fg
+        if self._orig_ibg is not None:
+            kw["insertbackground"] = self._orig_ibg
+        if kw:
+            try:
+                core.text.configure(**kw)
+            except Exception:
+                pass
+
+    def _resolve_auto_name(self) -> str:
+        """Return the appropriate Pygments style name for the current theme mode."""
+        try:
+            from bootstack.style.style import get_theme_provider
+            mode = get_theme_provider().mode
+        except Exception:
+            mode = "light"
+        return self._dark_style if mode == "dark" else self._light_style
+
+    def _load_style(self, style_name: str) -> None:
+        """Load a Pygments style, updating all color state."""
+        try:
+            style_cls = get_style_by_name(style_name)
+        except ClassNotFound:
+            style_cls = get_style_by_name("default")
+        self._style_colors = _extract_colors(style_cls)
+        self._active_styles: frozenset[str] = frozenset(self._style_colors)
+        self._style_bg: str = style_cls.background_color
+        raw_fg = (
+            style_cls.style_for_token(Token.Text).get("color")
+            or style_cls.style_for_token(Token).get("color")
+        )
+        self._style_fg: str | None = f"#{raw_fg}" if raw_fg else None
+
+    def _on_framework_theme_changed(self, event=None) -> None:
+        """Called via <<BsThemeChanged>> after _rebuild_all_styles() completes."""
+        if self._core is None:
+            return
+        if self._auto:
+            mode = (event.data or {}).get("mode") if event else None
+            resolved = self._dark_style if mode == "dark" else self._resolve_auto_name()
+            self._load_style(resolved)
+            for sname, color in self._style_colors.items():
+                self._core.define_style(sname, foreground=color)
+        self._apply_widget_colors(self._core, notify=True)
+        self._schedule()
+
+    def _schedule(self) -> None:
+        self._cancel()
+        if self._core is not None:
+            self._after_id = self._core.text.after(_DEBOUNCE_MS, self._retokenize)
+
+    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 _retokenize(self) -> None:
+        self._after_id = None
+        if self._core is None:
+            return
+        try:
+            text = self._core.value
+        except Exception:
+            return
+
+        if not text:
+            self._core.clear_decorations(_LAYER)
+            return
+
+        decorations: list[RangeDecoration] = []
+        line, col = 1, 0
+        active = self._active_styles
+
+        for ttype, value in lex(text, self._lexer):
+            if value:
+                style = _find_style(ttype)
+                if style is not None and style in active:
+                    if "\n" in value:
+                        vlines = value.split("\n")
+                        end_line = line + len(vlines) - 1
+                        end_col = len(vlines[-1])
+                    else:
+                        end_line = line
+                        end_col = col + len(value)
+                    decorations.append(RangeDecoration(
+                        Position(line, col),
+                        Position(end_line, end_col),
+                        style,
+                    ))
+
+                # Advance position regardless of whether we added a decoration.
+                if "\n" in value:
+                    vlines = value.split("\n")
+                    line += len(vlines) - 1
+                    col = len(vlines[-1])
+                else:
+                    col += len(value)
+
+        self._core.set_decorations(_LAYER, decorations)

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

@@ -0,0 +1,177 @@
+"""SmartIndent — auto-indent on Enter and Tab-to-spaces conversion.
+
+Filter-style extension: intercepts Return and Tab key events to provide
+editor-grade indentation. Does not intercept insert/delete in the chain
+(key bindings are used instead to avoid interfering with clipboard ops).
+"""
+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
+
+
+class SmartIndent(EditFilter):
+    """Provides auto-indent on Return, Tab-to-spaces, and block indent/dedent.
+
+    On `<Return>`:
+        Inserts a newline followed by the same leading whitespace as the
+        current line, so the cursor lands at the same indent level.
+
+    On `<Tab>` with a selection:
+        Indents every selected line by one tab stop.
+
+    On `<Tab>` with no selection (when `insert_spaces=True`):
+        Inserts spaces to the next tab stop instead of a literal tab character.
+
+    On `<Shift-Tab>`:
+        Dedents every selected line (or the current line) by one tab stop.
+
+    Install via `core.add_filter(SmartIndent())`.
+    """
+
+    def __init__(self, tab_width: int = 4, insert_spaces: bool = True) -> None:
+        super().__init__()
+        self._tab_width = tab_width
+        self._insert_spaces = insert_spaces
+        self._core: _MultilineCore | None = None
+
+    def attach(self, core: _MultilineCore) -> None:
+        self._core = core
+        core.text.bind("<Return>", self._on_return, add="+")
+        core.text.bind("<Tab>", self._on_tab, add="+")
+        core.text.bind("<Shift-Tab>", self._on_shift_tab, add="+")
+        core.text.bind("<ISO_Left_Tab>", self._on_shift_tab, add="+")  # Linux/X11
+
+    def detach(self, core: _MultilineCore) -> None:
+        self._core = None
+
+    # ── filter pass-through ───────────────────────────────────────────────
+
+    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)
+
+    # ── public block operations ───────────────────────────────────────────
+
+    def indent(self) -> None:
+        """Indent selected lines by one tab stop, or insert at cursor."""
+        if self._core is None:
+            return
+        tw = self._core.text
+        ranges = tw.tag_ranges("sel")
+        if ranges:
+            self._indent_block(tw, ranges)
+        else:
+            col = int(tw.index("insert").split(".")[1])
+            spaces = self._tab_width - (col % self._tab_width)
+            tw.insert("insert", " " * spaces if self._insert_spaces else "\t")
+
+    def dedent(self) -> None:
+        """Dedent selected lines (or current line) by one tab stop."""
+        if self._core is None:
+            return
+        self._dedent_block(self._core.text, self._core.text.tag_ranges("sel"))
+
+    # ── key handlers ─────────────────────────────────────────────────────
+
+    def _on_return(self, _event: tk.Event) -> str:
+        """Insert a newline with matching indentation."""
+        if self._core is None:
+            return ""
+        text = self._core.text
+        cursor = text.index("insert")
+        line_start = text.index(f"{cursor} linestart")
+        line_text = text.get(line_start, cursor)
+        indent = _leading_whitespace(line_text)
+        # Use the undo block API so auto-indent is one undo step with the newline
+        self._core.undo_block_start()
+        text.insert("insert", f"\n{indent}")
+        self._core.undo_block_stop()
+        return "break"     # prevent default Return handling
+
+    def _on_tab(self, _event: tk.Event) -> str | None:
+        """Indent selection, or insert spaces / fall through for a literal tab."""
+        if self._core is None:
+            return None
+        tw = self._core.text
+        ranges = tw.tag_ranges("sel")
+        if ranges:
+            self._indent_block(tw, ranges)
+            return "break"
+        if self._insert_spaces:
+            col = int(tw.index("insert").split(".")[1])
+            spaces = self._tab_width - (col % self._tab_width)
+            tw.insert("insert", " " * spaces)
+            return "break"
+        # insert_spaces=False, no selection: let native Tab insert \t
+        return None
+
+    def _on_shift_tab(self, _event: tk.Event) -> str:
+        """Dedent selection or current line."""
+        if self._core is None:
+            return "break"
+        self._dedent_block(self._core.text, self._core.text.tag_ranges("sel"))
+        return "break"
+
+    # ── helpers ───────────────────────────────────────────────────────────
+
+    def _indent_block(self, tw: tk.Text, ranges: tuple) -> None:
+        start_line, end_line = _sel_line_range(ranges)
+        indent = " " * self._tab_width if self._insert_spaces else "\t"
+        self._core.undo_block_start()
+        try:
+            for ln in range(start_line, end_line + 1):
+                if tw.get(f"{ln}.0", f"{ln}.end"):  # skip blank lines
+                    tw.insert(f"{ln}.0", indent)
+        finally:
+            self._core.undo_block_stop()
+        tw.tag_add("sel", f"{start_line}.0", f"{end_line}.end")
+
+    def _dedent_block(self, tw: tk.Text, ranges: tuple) -> None:
+        if ranges:
+            start_line, end_line = _sel_line_range(ranges)
+        else:
+            start_line = end_line = int(tw.index("insert").split(".")[0])
+        self._core.undo_block_start()
+        try:
+            for ln in range(start_line, end_line + 1):
+                line_text = tw.get(f"{ln}.0", f"{ln}.end")
+                if self._insert_spaces:
+                    n = min(self._tab_width, len(line_text) - len(line_text.lstrip(" ")))
+                    if n:
+                        tw.delete(f"{ln}.0", f"{ln}.{n}")
+                else:
+                    if line_text.startswith("\t"):
+                        tw.delete(f"{ln}.0", f"{ln}.1")
+        finally:
+            self._core.undo_block_stop()
+        if ranges:
+            tw.tag_add("sel", f"{start_line}.0", f"{end_line}.end")
+
+
+def _leading_whitespace(line: str) -> str:
+    """Return the leading whitespace characters of *line*."""
+    return line[: len(line) - len(line.lstrip())]
+
+
+def _sel_line_range(ranges: tuple) -> tuple[int, int]:
+    """Return (start_line, end_line) from a tag_ranges("sel") result.
+
+    If the selection ends exactly at column 0 of the last line (i.e. the user
+    selected to the very start of a line without including any content), that
+    trailing line is excluded so we don't indent/dedent a line the user didn't
+    intend to touch.
+    """
+    start_str, end_str = str(ranges[0]), str(ranges[1])
+    start_line = int(start_str.split(".")[0])
+    end_line = int(end_str.split(".")[0])
+    if end_str.split(".")[1] == "0" and end_line > start_line:
+        end_line -= 1
+    return start_line, end_line

bootstack/widgets/_impl/composites/textarea/filter.py

@@ -0,0 +1,171 @@
+"""EditFilter base class and FilterChain.
+
+Adaptation of IDLE's Delegator/Percolator pattern
+(idlelib/delegator.py + idlelib/percolator.py).
+
+WidgetRedirector intercepts every insert/delete at the Tk command level —
+including keyboard input from Tk's default text bindings — and routes them
+through the Python filter chain. The bottom of the chain calls the original
+Tk command via OriginalCommand objects returned by redirector.register(),
+which are clean Python callables, not raw Tcl strings.
+"""
+from __future__ import annotations
+
+import tkinter as tk
+from idlelib.redirector import WidgetRedirector
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bootstack.widgets._impl.composites.textarea.core import _MultilineCore
+
+
+# NOTE(editfilter-public-api): EditFilter was demoted from the top-level public
+# namespace during the API Reference restructure (Stage 4). It is a Tk-coupled
+# extension hook — subclasses work in raw Tk text indices, tags, and the Tk Text
+# API — which contradicts the framework's "Tkinter is invisible" premise, and it
+# ships no narrative docs. CodeEditor still accepts user filters via
+# `extensions=`/`install()`, so it stays importable for power users, but it is no
+# longer presented as compose surface. TODO: decide whether CodeEditor should have
+# a real, documented, de-Tkinter-ed extension/plugin API (one that hides Tk text
+# indices behind framework-level edit events) and, if so, design that as the public
+# face — re-promoting only once it no longer leaks Tk. See memory
+# project_editfilter_public_api.
+class EditFilter:
+    """Sits in the mutation chain between user code and the Tk Text widget.
+
+    Subclass and override `insert` and/or `delete` to intercept edits.
+    Always forward to `self.delegate.insert` / `self.delegate.delete`
+    unless you intend to suppress the edit.
+
+    Attribute reads (`self.get(...)`, `self.tag_add(...)`, etc.) forward
+    automatically to the next delegate via `__getattr__`, so a filter
+    behaves like the Text widget itself when reading state.
+    """
+
+    def __init__(self) -> None:
+        self.delegate: EditFilter | _BottomFilter | None = None
+        self._cache: set[str] = set()
+
+    def __getattr__(self, name: str):
+        if name.startswith('_') or self.delegate is None:
+            raise AttributeError(name)
+        attr = getattr(self.delegate, name)
+        setattr(self, name, attr)
+        self._cache.add(name)
+        return attr
+
+    def _reset_cache(self) -> None:
+        for k in self._cache:
+            try:
+                delattr(self, k)
+            except AttributeError:
+                pass
+        self._cache.clear()
+
+    def _set_delegate(self, d: EditFilter | _BottomFilter | None) -> None:
+        self._reset_cache()
+        self.delegate = d
+
+    def insert(self, index: str, chars: str, tags=None) -> None:
+        """Forward an insert to the next delegate."""
+        self.delegate.insert(index, chars, tags)
+
+    def delete(self, index1: str, index2: str | None = None) -> None:
+        """Forward a delete to the next delegate."""
+        self.delegate.delete(index1, index2)
+
+    def attach(self, core: _MultilineCore) -> None:
+        """Called when this filter is added to a core's chain."""
+
+    def detach(self, core: _MultilineCore) -> None:
+        """Called when this filter is removed from a core's chain."""
+
+
+class _BottomFilter:
+    """Terminal filter — calls the original Tk Text command via OriginalCommand.
+
+    WidgetRedirector.register() returns an OriginalCommand callable for each
+    intercepted operation. Calling it routes directly to the renamed Tcl proc
+    (e.g. `.!text_orig insert ...`) without going back through the chain.
+    """
+
+    def __init__(self, orig_insert, orig_delete, text: tk.Text) -> None:
+        self._orig_insert = orig_insert   # OriginalCommand returned by register()
+        self._orig_delete = orig_delete   # OriginalCommand returned by register()
+        self._text = text
+
+    def __getattr__(self, name: str):
+        return getattr(self._text, name)
+
+    def insert(self, index: str, chars: str, tags=None) -> None:
+        if tags:
+            self._orig_insert(index, chars, tags)
+        else:
+            self._orig_insert(index, chars)
+
+    def delete(self, index1: str, index2: str | None = None) -> None:
+        if index2 is not None:
+            self._orig_delete(index1, index2)
+        else:
+            self._orig_delete(index1)
+
+    def _set_delegate(self, d) -> None:
+        pass
+
+
+class FilterChain:
+    """Owns the ordered chain of EditFilters.
+
+    Uses WidgetRedirector so that every insert/delete on the Text widget —
+    including those triggered by Tk's default key bindings — flows through
+    the chain before reaching the underlying Tk Text widget.
+    """
+
+    def __init__(self, text: tk.Text) -> None:
+        self._text = text
+        self._redirector = WidgetRedirector(text)
+        self._filters: list[EditFilter] = []
+
+        # Register our handlers; register() returns OriginalCommand callables
+        orig_insert = self._redirector.register('insert', self._chain_insert)
+        orig_delete = self._redirector.register('delete', self._chain_delete)
+
+        self._bottom = _BottomFilter(orig_insert, orig_delete, text)
+        self._top: EditFilter | _BottomFilter = self._bottom
+
+    def _chain_insert(self, index: str, chars: str, tags=None) -> None:
+        self._top.insert(index, chars, tags)
+
+    def _chain_delete(self, index1: str, index2: str | None = None) -> None:
+        self._top.delete(index1, index2)
+
+    def add(self, f: EditFilter) -> None:
+        """Prepend a filter to the top of the chain."""
+        f._set_delegate(self._top)
+        self._top = f
+        self._filters.insert(0, f)
+
+    def remove(self, f: EditFilter) -> None:
+        """Remove a filter from the chain."""
+        if f not in self._filters:
+            return
+        idx = self._filters.index(f)
+        above = self._filters[idx - 1] if idx > 0 else None
+        below = self._filters[idx + 1] if idx < len(self._filters) - 1 else self._bottom
+
+        if above is None:
+            self._top = below
+        else:
+            above._set_delegate(below)
+
+        f._set_delegate(None)
+        self._filters.pop(idx)
+
+    def destroy(self) -> None:
+        """Uninstall the redirector."""
+        try:
+            self._redirector.unregister('insert')
+            self._redirector.unregister('delete')
+            self._redirector.close()
+        except Exception:
+            pass