bootstack 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,495 @@
+"""_MultilineCore — shared internal engine for TextArea and CodeEditor.
+
+Owns the tk.Text widget, filter chain, scrollbar wiring, and the
+sidebar/decoration registries used by CodeEditor extensions.
+"""
+from __future__ import annotations
+
+import tkinter as tk
+from typing import Callable, Literal
+
+from bootstack.events import TextModifiedEvent
+from bootstack.widgets._impl.primitives.scrollbar import Scrollbar
+from bootstack.widgets._impl.composites.textarea.filter import EditFilter, FilterChain
+from bootstack.widgets._impl.composites.textarea.change import ChangeNotifier
+from bootstack.widgets._impl.composites.textarea.undo import UndoManager
+from bootstack.widgets._impl.composites.textarea.style_registry import StyleRegistry
+from bootstack.widgets._impl.composites.textarea.diff import DecorationDiff
+from bootstack.widgets._impl.composites.textarea.decoration import (
+    LineDecoration, Position, RangeDecoration,
+)
+from bootstack.widgets.types import Master
+
+
+ScrollbarMode = Literal["vertical", "both", "none", "auto"]
+
+
+class _MultilineCore(tk.Frame):
+    """Internal engine shared by TextArea and CodeEditor.
+
+    Not part of the public API. Use TextArea or CodeEditor instead.
+
+    Wraps a tk.Text widget with:
+    - A FilterChain routing all inserts/deletes through registered filters.
+    - Built-in ChangeNotifier (fires <<Change>>) and UndoManager.
+    - Scrollbar wiring with auto/always/none/both modes.
+    - value/textsignal reactive binding.
+    """
+
+    def __init__(
+        self,
+        master: Master = None,
+        value: str = "",
+        wrap: bool = True,
+        height: int = 4,
+        scrollbars: ScrollbarMode = "auto",
+        font: str = "body",
+        read_only: bool = False,
+        **text_kwargs,
+    ) -> None:
+        super().__init__(master, highlightthickness=0, borderwidth=0)
+
+        self._scrollbar_mode = scrollbars
+        self._read_only = read_only
+        self._signal = None
+        self._signal_trace_id = None
+
+        # Detect windowing system for mousewheel handling
+        self.winsys: str = self.tk.call("tk", "windowingsystem")
+
+        # ── text widget ───────────────────────────────────────────────────
+        # undo=False: we manage the undo stack ourselves via UndoManager
+        # (character-class grouping for word-level undo, matching IDLE).
+        wrap_mode = tk.WORD if wrap else tk.NONE
+        self.text = tk.Text(
+            self,
+            wrap=wrap_mode,
+            height=height,
+            font=font,
+            undo=False,
+            borderwidth=0,
+            highlightthickness=0,
+            **text_kwargs,
+        )
+
+        # ── scrollbars ────────────────────────────────────────────────────
+        self._vscroll = Scrollbar(self, orient="vertical", command=self.text.yview)
+        self._hscroll = Scrollbar(self, orient="horizontal", command=self.text.xview)
+
+        self.text.configure(yscrollcommand=self._on_yscroll)
+        if not wrap:
+            self.text.configure(xscrollcommand=self._on_xscroll)
+
+        # ── layout ────────────────────────────────────────────────────────
+        # col 0: left sidebars (auto-sized, initially empty)
+        # col 1: text (fills available space)
+        # col 2: vertical scrollbar
+        self._sidebars: list = []         # list of attached Sidebar instances
+        self._text_col = 1                # text widget column (shifts right if needed)
+        self.grid_rowconfigure(0, weight=1)
+        self.grid_columnconfigure(0, weight=0)   # sidebar column
+        self.grid_columnconfigure(1, weight=1)   # text column
+        self.text.grid(row=0, column=1, sticky="nsew")
+
+        self._update_scrollbar_layout()
+
+        # ── filter chain ──────────────────────────────────────────────────
+        self._chain = FilterChain(self.text)
+
+        self._undo_manager = UndoManager()
+        self._change_notifier = ChangeNotifier()
+
+        self._install_filter(self._undo_manager)
+        self._install_filter(self._change_notifier)
+
+        # ── style registry + decoration diff ─────────────────────────────
+        self._style_registry = StyleRegistry(self)
+        self._decoration_diff = DecorationDiff(self, self._style_registry)
+
+        # ── mousewheel ────────────────────────────────────────────────────
+        self._scroll_tag = f"_mcore_{id(self)}"
+        self._setup_mousewheel()
+
+        # ── initial value ─────────────────────────────────────────────────
+        if value:
+            self.text.insert("1.0", value)
+            self._undo_manager.reset_undo()   # clear history after seeding
+
+        if read_only:
+            self.text.configure(state=tk.DISABLED)
+
+        # Keyboard undo/redo: drive our UndoManager from Tk's platform-aware
+        # <<Undo>>/<<Redo>> virtual events rather than hardcoding keys, so the
+        # native per-OS shortcut applies (Ctrl+Z / Ctrl+Y on Windows & Linux,
+        # Cmd+Z / Cmd+Shift+Z on macOS). undo=False means Tk's own handlers for
+        # these events no-op; the widget-level binding runs first and "break"
+        # suppresses the (empty) class handler.
+        self.text.bind("<<Undo>>", lambda e: (self._undo_manager.undo(), "break")[1], add="+")
+        self.text.bind("<<Redo>>", lambda e: (self._undo_manager.redo(), "break")[1], add="+")
+
+        # <<Modified>> still fires from Tk's edit_modified flag (independent
+        # of the undo stack) — enrich with is_dirty payload.
+        self.text.bind("<<Modified>>", self._on_tk_modified, add="+")
+
+        self.bind("<Destroy>", self._on_destroy, add="+")
+
+    # ── filter management ─────────────────────────────────────────────────
+
+    def _install_filter(self, f: EditFilter) -> None:
+        self._chain.add(f)
+        f.attach(self)
+
+    def add_filter(self, f: EditFilter) -> None:
+        """Install a custom filter at the top of the chain."""
+        self._install_filter(f)
+
+    def remove_filter(self, f: EditFilter) -> None:
+        """Remove a custom filter from the chain."""
+        f.detach(self)
+        self._chain.remove(f)
+
+    # ── sidebar management ────────────────────────────────────────────────
+
+    def add_sidebar(self, sidebar, side: str = "left") -> None:
+        """Attach a sidebar widget to this core.
+
+        Args:
+            sidebar: A `Sidebar` instance.
+            side: `"left"` (default) — only left sidebars are supported
+                in the current layout.
+        """
+        self._sidebars.append(sidebar)
+        sidebar.attach(self, side=side)
+
+    def remove_sidebar(self, sidebar) -> None:
+        """Detach a sidebar widget from this core.
+
+        Args:
+            sidebar: The `Sidebar` instance to remove.
+        """
+        if sidebar in self._sidebars:
+            self._sidebars.remove(sidebar)
+            sidebar.detach(self)
+
+    # ── scrollbars ────────────────────────────────────────────────────────
+
+    def _on_yscroll(self, first: str, last: str) -> None:
+        self._vscroll.set(first, last)
+        for sb in self._sidebars:
+            sb.on_scroll(first, last)
+        if self._scrollbar_mode == "auto":
+            vscroll_col = self._text_col + 1
+            if float(first) <= 0.0 and float(last) >= 1.0:
+                self._vscroll.grid_remove()
+            else:
+                self._vscroll.grid(row=0, column=vscroll_col, sticky="ns")
+
+    def _on_xscroll(self, first: str, last: str) -> None:
+        self._hscroll.set(first, last)
+        if self._scrollbar_mode == "auto":
+            if float(first) <= 0.0 and float(last) >= 1.0:
+                self._hscroll.grid_remove()
+            else:
+                self._hscroll.grid(row=1, column=self._text_col, sticky="ew")
+
+    def _update_scrollbar_layout(self) -> None:
+        mode = self._scrollbar_mode
+        vscroll_col = self._text_col + 1
+        if mode in ("vertical", "both", "auto"):
+            self._vscroll.grid(row=0, column=vscroll_col, sticky="ns")
+        else:
+            self._vscroll.grid_remove()
+
+        if mode == "both":
+            self._hscroll.grid(row=1, column=self._text_col, sticky="ew")
+        else:
+            self._hscroll.grid_remove()
+
+        if mode == "auto":
+            self._vscroll.grid_remove()
+            self._hscroll.grid_remove()
+
+    # ── mousewheel ────────────────────────────────────────────────────────
+
+    def _setup_mousewheel(self) -> None:
+        if self.winsys == "x11":
+            self.bind_class(self._scroll_tag, "<Button-4>", self._on_wheel)
+            self.bind_class(self._scroll_tag, "<Button-5>", self._on_wheel)
+        else:
+            self.bind_class(self._scroll_tag, "<MouseWheel>", self._on_wheel)
+        tags = list(self.text.bindtags())
+        if self._scroll_tag not in tags:
+            tags.insert(1, self._scroll_tag)
+            self.text.bindtags(tuple(tags))
+
+    def _on_wheel(self, event: tk.Event) -> None:
+        if self.winsys == "win32":
+            delta = -int(event.delta / 120)
+        elif self.winsys == "aqua":
+            delta = -event.delta
+        elif event.num == 4:
+            delta = -1
+        else:
+            delta = 1
+        self.text.yview_scroll(delta, "units")
+
+    # ── value / signal ────────────────────────────────────────────────────
+
+    @property
+    def value(self) -> str:
+        """Full text content (trailing newline stripped)."""
+        return self.text.get("1.0", "end-1c")
+
+    @value.setter
+    def value(self, text: str) -> None:
+        was_disabled = self._read_only
+        if was_disabled:
+            self.text.configure(state=tk.NORMAL)
+        self.text.delete("1.0", tk.END)
+        if text:
+            self.text.insert("1.0", text)
+        if was_disabled:
+            self.text.configure(state=tk.DISABLED)
+
+    @property
+    def read_only(self) -> bool:
+        """Whether the text is visible but not editable."""
+        return self._read_only
+
+    @read_only.setter
+    def read_only(self, value: bool) -> None:
+        # Keep the flag and the widget state in lockstep: the value/insert
+        # setters consult `_read_only` to know whether to lift the disabled
+        # state for a programmatic write.
+        self._read_only = bool(value)
+        self.text.configure(state=tk.DISABLED if self._read_only else tk.NORMAL)
+
+    def insert(self, index: str, text: str) -> None:
+        """Insert text at `index`, applying even when read-only.
+
+        Read-only blocks *user* edits, not programmatic ones, so this lifts the
+        disabled state for the write and restores it (matching the value setter).
+        """
+        was_disabled = self._read_only
+        if was_disabled:
+            self.text.configure(state=tk.NORMAL)
+        self.text.insert(index, text)
+        if was_disabled:
+            self.text.configure(state=tk.DISABLED)
+
+    def bind_signal(self, signal) -> None:
+        """Bind a Signal[str] — updates the text when the signal changes."""
+        if self._signal is not None:
+            self._unbind_signal()
+        self._signal = signal
+        self._signal_trace_id = signal.subscribe(self._on_signal_change)
+        # Set initial value from signal
+        v = signal()
+        if v is not None:
+            self.value = str(v)
+
+    def _unbind_signal(self) -> None:
+        if self._signal is not None and self._signal_trace_id is not None:
+            try:
+                self._signal_trace_id.cancel()
+            except Exception:
+                pass
+        self._signal = None
+        self._signal_trace_id = None
+
+    def _on_signal_change(self, new_value) -> None:
+        if new_value is not None:
+            self.value = str(new_value)
+
+    # ── dirty tracking ────────────────────────────────────────────────────
+
+    @property
+    def is_dirty(self) -> bool:
+        """True if the content has changed since last save."""
+        return self._undo_manager.is_dirty
+
+    def mark_saved(self) -> None:
+        """Mark current state as the clean baseline."""
+        self._undo_manager.mark_saved()
+
+    # ── undo / redo ───────────────────────────────────────────────────────
+
+    def undo(self) -> None:
+        """Undo the last edit."""
+        self._undo_manager.undo()
+
+    def redo(self) -> None:
+        """Redo the last undone edit."""
+        self._undo_manager.redo()
+
+    def undo_block_start(self) -> None:
+        """Begin a compound undo block."""
+        self._undo_manager.undo_block_start()
+
+    def undo_block_stop(self) -> None:
+        """End a compound undo block."""
+        self._undo_manager.undo_block_stop()
+
+    # ── decoration / style API ────────────────────────────────────────────
+
+    def register_layer(self, name: str, priority: int = 0) -> None:
+        """Register a decoration layer.
+
+        Args:
+            name: Layer identifier. Used to namespace Tk tags.
+            priority: Tag raise order — higher priority layers render on top.
+        """
+        self._decoration_diff.register_layer(name, priority)
+
+    def define_style(self, name: str, **attrs) -> None:
+        """Define a named text style for use in decorations.
+
+        Args:
+            name: Style identifier referenced in decoration objects.
+            **attrs: Style attributes — `foreground`, `background`,
+                `font`, `underline`, `spacing1`, `spacing3`.
+                Values may be theme tokens (e.g. `'primary'`) or literal
+                Tk color/font strings.
+        """
+        self._style_registry.define_style(name, **attrs)
+
+    def set_decorations(self, layer: str, decorations) -> None:
+        """Apply a decoration set to *layer*, diffing against the previous set.
+
+        Args:
+            layer: The decoration layer to update.
+            decorations: Sequence of `RangeDecoration` or `LineDecoration`.
+        """
+        self._decoration_diff.set_decorations(layer, decorations)
+
+    def clear_decorations(self, layer: str) -> None:
+        """Remove all decorations from *layer*.
+
+        Args:
+            layer: The layer to clear.
+        """
+        self._decoration_diff.clear_layer(layer)
+
+    # ── internal Tk event enrichment ─────────────────────────────────────
+
+    def _on_tk_modified(self, _event=None) -> None:
+        self.text.event_generate(
+            "<<TextModified>>",
+            data=TextModifiedEvent(is_dirty=self.is_dirty),
+            when="tail",
+        )
+
+    # ── event subscription ────────────────────────────────────────────────
+
+    def on_change(self, callback: Callable) -> str:
+        """Register a callback for `<<Change>>` events.
+
+        Args:
+            callback: Receives the Tk event. `event.data` contains
+                `{"op": "insert"|"delete", "index": str}`.
+
+        Returns:
+            Bind ID — pass to `off_change()` to unsubscribe.
+        """
+        return self.text.bind("<<Change>>", callback, add="+")
+
+    def off_change(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<Change>>`.
+
+        Args:
+            bind_id: ID returned by `on_change()`. If None, removes all.
+        """
+        self.text.unbind("<<Change>>", bind_id)
+
+    def on_modified(self, callback: Callable) -> str:
+        """Register a callback for `<<TextModified>>` events.
+
+        Fires when the dirty state changes. `event.is_dirty`
+        reflects the new state.
+
+        Args:
+            callback: Receives the Tk event with `event.data = {"is_dirty": bool}`.
+
+        Returns:
+            Bind ID — pass to `off_modified()` to unsubscribe.
+        """
+        return self.text.bind("<<TextModified>>", callback, add="+")
+
+    def off_modified(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<TextModified>>`.
+
+        Args:
+            bind_id: ID returned by `on_modified()`. If None, removes all.
+        """
+        self.text.unbind("<<TextModified>>", bind_id)
+
+    def on_undo(self, callback: Callable) -> str:
+        """Register a callback for `<<TextUndo>>` events.
+
+        Fires after an undo completes. `event.data.text` is the
+        text content after the undo.
+
+        Args:
+            callback: Receives the Tk event with `event.data = {"value": str}`.
+
+        Returns:
+            Bind ID — pass to `off_undo()` to unsubscribe.
+        """
+        return self.text.bind("<<TextUndo>>", callback, add="+")
+
+    def off_undo(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<TextUndo>>`.
+
+        Args:
+            bind_id: ID returned by `on_undo()`. If None, removes all.
+        """
+        self.text.unbind("<<TextUndo>>", bind_id)
+
+    def on_redo(self, callback: Callable) -> str:
+        """Register a callback for `<<TextRedo>>` events.
+
+        Fires after a redo completes. `event.data.text` is the
+        text content after the redo.
+
+        Args:
+            callback: Receives the Tk event with `event.data = {"value": str}`.
+
+        Returns:
+            Bind ID — pass to `off_redo()` to unsubscribe.
+        """
+        return self.text.bind("<<TextRedo>>", callback, add="+")
+
+    def off_redo(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<TextRedo>>`.
+
+        Args:
+            bind_id: ID returned by `on_redo()`. If None, removes all.
+        """
+        self.text.unbind("<<TextRedo>>", bind_id)
+
+    # ── convenience: forward common Text API to self ──────────────────────
+
+    def bind(self, sequence=None, func=None, add=None):
+        return self.text.bind(sequence, func, add)
+
+    def unbind(self, sequence, funcid=None):
+        return self.text.unbind(sequence, funcid)
+
+    def focus_set(self):
+        self.text.focus_set()
+
+    # ── cleanup ───────────────────────────────────────────────────────────
+
+    def _on_destroy(self, event: tk.Event) -> None:
+        if event.widget is not self:
+            return
+        self._unbind_signal()
+        self._chain.destroy()
+        try:
+            if self.winsys == "x11":
+                self.unbind_class(self._scroll_tag, "<Button-4>")
+                self.unbind_class(self._scroll_tag, "<Button-5>")
+            else:
+                self.unbind_class(self._scroll_tag, "<MouseWheel>")
+        except Exception:
+            pass

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

@@ -0,0 +1,42 @@
+"""Decoration types for the TextArea/CodeEditor decoration system."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Any
+import tkinter as tk
+
+
+@dataclass(frozen=True)
+class Position:
+    """A line/column position in the text (1-indexed line, 0-indexed column)."""
+    line: int
+    col: int
+
+    def to_tk(self) -> str:
+        """Convert to a Tk text index string (e.g. `'3.7'`)."""
+        return f"{self.line}.{self.col}"
+
+
+@dataclass(frozen=True)
+class RangeDecoration:
+    """A styled range from *start* to *end*."""
+    start: Position
+    end: Position
+    style: str
+    meta: dict | None = None
+
+
+@dataclass(frozen=True)
+class LineDecoration:
+    """A style applied to an entire line."""
+    line: int
+    style: str
+    meta: dict | None = None
+
+
+@dataclass(frozen=True)
+class WidgetDecoration:
+    """A widget embedded at a position (e.g. inline diagnostic icon)."""
+    at: Position
+    widget_factory: Callable[[tk.Misc], tk.Widget]
+    meta: dict | None = None

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

@@ -0,0 +1,127 @@
+"""Decoration-set diff engine.
+
+Per-layer state stored as a dict keyed by (start_tk, end_tk, style).
+Diff is a dict comparison: O(|symmetric difference|) Tk tag calls.
+"""
+from __future__ import annotations
+
+import tkinter as tk
+from typing import Sequence, TYPE_CHECKING
+
+from bootstack.widgets._impl.composites.textarea.decoration import (
+    LineDecoration, RangeDecoration,
+)
+
+if TYPE_CHECKING:
+    from bootstack.widgets._impl.composites.textarea.core import _MultilineCore
+    from bootstack.widgets._impl.composites.textarea.style_registry import StyleRegistry
+
+# Key: (start_tk_index, end_tk_index, style_name)
+_LayerState = dict[tuple[str, str, str], dict | None]
+
+
+class DecorationDiff:
+    """Applies decoration sets to a Text widget using a diff-based approach.
+
+    Maintains per-layer state so that only changed decorations cause Tk
+    tag_add / tag_remove calls. For a 200-decoration viewport with one
+    edited token, this is ~2 Tk calls instead of clearing and rebuilding.
+    """
+
+    def __init__(self, core: _MultilineCore, style_registry: StyleRegistry) -> None:
+        self._core = core
+        self._text = core.text
+        self._styles = style_registry
+        # layer -> current decoration state
+        self._layers: dict[str, _LayerState] = {}
+        # layer -> priority (lower = below)
+        self._priorities: dict[str, int] = {}
+
+    def register_layer(self, name: str, priority: int = 0) -> None:
+        """Register a decoration layer.
+
+        Args:
+            name: Layer identifier (used in style tag names).
+            priority: Tag raise order — higher priority layers appear on top.
+        """
+        if name not in self._layers:
+            self._layers[name] = {}
+            self._priorities[name] = priority
+
+    def set_decorations(
+        self,
+        layer: str,
+        decorations: Sequence[RangeDecoration | LineDecoration],
+    ) -> None:
+        """Apply a new decoration set to *layer*, diffing against the previous set.
+
+        Args:
+            layer: The layer to update.
+            decorations: New complete set of decorations for this layer.
+        """
+        if layer not in self._layers:
+            self.register_layer(layer)
+
+        new_state = _build_state(decorations)
+        old_state = self._layers[layer]
+
+        old_keys = set(old_state.keys())
+        new_keys = set(new_state.keys())
+
+        removed = old_keys - new_keys
+        added = new_keys - old_keys
+
+        for start, end, style in removed:
+            tag = self._styles.tag_name(layer, style)
+            try:
+                self._text.tag_remove(tag, start, end)
+            except tk.TclError:
+                pass
+
+        for start, end, style in added:
+            tag = self._styles.tag_name(layer, style)
+            if not self._styles.is_configured(layer, style):
+                self._styles.configure_tag(layer, style)
+            try:
+                self._text.tag_add(tag, start, end)
+            except tk.TclError:
+                pass
+
+        self._layers[layer] = new_state
+        self._raise_layers()
+
+    def clear_layer(self, layer: str) -> None:
+        """Remove all decorations from *layer*."""
+        self.set_decorations(layer, [])
+
+    def _raise_layers(self) -> None:
+        """Enforce layer priority order via tag_raise."""
+        ordered = sorted(self._priorities.items(), key=lambda x: x[1])
+        for layer, _ in ordered:
+            state = self._layers.get(layer, {})
+            seen_tags: set[str] = set()
+            for _, _, style in state:
+                tag = self._styles.tag_name(layer, style)
+                if tag not in seen_tags:
+                    seen_tags.add(tag)
+                    try:
+                        self._text.tag_raise(tag)
+                    except tk.TclError:
+                        pass
+
+
+def _build_state(
+    decorations: Sequence[RangeDecoration | LineDecoration],
+) -> _LayerState:
+    """Convert a list of decorations to the internal dict-key format."""
+    state: _LayerState = {}
+    for dec in decorations:
+        if isinstance(dec, RangeDecoration):
+            key = (dec.start.to_tk(), dec.end.to_tk(), dec.style)
+            state[key] = dec.meta
+        elif isinstance(dec, LineDecoration):
+            start = f"{dec.line}.0"
+            end = f"{dec.line}.end"
+            key = (start, end, dec.style)
+            state[key] = dec.meta
+    return state

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

@@ -0,0 +1 @@
+"""Built-in TextArea/CodeEditor extensions."""