bootstack 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,217 @@
+"""UndoManager filter — word-level undo via character-class grouping.
+
+Adaptation of IDLE's UndoDelegator (idlelib/undo.py). Key differences:
+- Renamed UndoManager / _Command for clarity.
+- Character-class merging gives word-level undo without needing Tk's
+  built-in undo stack (undo=False on the Text widget).
+- Canonical line.col indices recorded before forwarding so undo positions
+  stay correct after the cursor moves.
+- Adjacency check uses line/col arithmetic rather than Tk mark resolution.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from bootstack.events import InputEvent
+from bootstack.widgets._impl.composites.textarea.filter import EditFilter
+
+if TYPE_CHECKING:
+    from bootstack.widgets._impl.composites.textarea.core import _MultilineCore
+
+# Character classes for merging adjacent typed characters into one undo step
+_ALPHANUMERIC = frozenset(
+    'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_'
+)
+
+
+def _char_class(ch: str) -> str:
+    if ch in _ALPHANUMERIC:
+        return 'alphanum'
+    if ch == '\n':
+        return 'newline'
+    return 'punct'
+
+
+class _Command:
+    """One reversible edit operation."""
+
+    def __init__(self, op: str, index: str, chars: str, tags=None) -> None:
+        self.op = op        # 'insert' or 'delete'
+        self.index = index  # canonical line.col (e.g. "1.5")
+        self.chars = chars
+        self.tags = tags
+
+    def do(self, core: _MultilineCore) -> None:
+        """Re-apply this operation (used by redo)."""
+        if self.op == 'insert':
+            core.text.insert(self.index, self.chars, self.tags or ())
+        else:
+            end = core.text.index(f'{self.index} +{len(self.chars)}c')
+            core.text.delete(self.index, end)
+
+    def undo(self, core: _MultilineCore) -> None:
+        """Reverse this operation."""
+        if self.op == 'insert':
+            end = core.text.index(f'{self.index} +{len(self.chars)}c')
+            core.text.delete(self.index, end)
+        else:
+            core.text.insert(self.index, self.chars, self.tags or ())
+
+    def merge(self, other: '_Command') -> bool:
+        """Try to merge *other* into this command (in-place). Returns True if merged.
+
+        Two single-character inserts merge when they are:
+        - Both inserts
+        - Adjacent (other starts where self ends, same row)
+        - Same character class
+        - Neither contains a newline (newlines always start a new block)
+        """
+        if self.op != 'insert' or other.op != 'insert':
+            return False
+        if len(other.chars) != 1 or '\n' in other.chars:
+            return False
+        if not self.chars or '\n' in self.chars:
+            return False
+        if _char_class(self.chars[-1]) != _char_class(other.chars[0]):
+            return False
+        # Adjacency: other must start exactly where self ends (same row)
+        try:
+            row1, col1 = map(int, self.index.split('.'))
+            row2, col2 = map(int, other.index.split('.'))
+            if row1 == row2 and col1 + len(self.chars) == col2:
+                self.chars += other.chars
+                return True
+        except (ValueError, AttributeError):
+            pass
+        return False
+
+
+class UndoManager(EditFilter):
+    """Undo/redo filter with character-class word-level grouping.
+
+    Intercepts every insert/delete, records canonical operations, and groups
+    consecutive same-class single-character inserts into one undo block.
+    Provides `undo()`, `redo()`, `undo_block_start()`,
+    `undo_block_stop()`, and `reset_undo()` via the owning core.
+    """
+
+    MAX_UNDO = 1000
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._stack: list[list[_Command]] = []
+        self._redo_stack: list[list[_Command]] = []
+        self._current_block: list[_Command] | None = None
+        self._block_depth: int = 0
+        self._saved_index: int = 0   # stack length at last save
+        self._core: _MultilineCore | None = None
+        self._undoing: bool = False
+
+    # ── lifecycle ──────────────────────────────────────────────────────────
+
+    def attach(self, core: _MultilineCore) -> None:
+        self._core = core
+
+    def detach(self, core: _MultilineCore) -> None:
+        self._core = None
+
+    # ── filter chain ───────────────────────────────────────────────────────
+
+    def insert(self, index: str, chars: str, tags=None) -> None:
+        if not self._undoing:
+            canonical = self.index(index)
+            self.delegate.insert(index, chars, tags)
+            self._record(_Command('insert', canonical, chars, tags))
+        else:
+            self.delegate.insert(index, chars, tags)
+
+    def delete(self, index1: str, index2: str | None = None) -> None:
+        if not self._undoing:
+            canonical = self.index(index1)
+            end = index2 if index2 else self.index(f'{index1} +1c')
+            chars = self.get(canonical, end)
+            self.delegate.delete(index1, index2)
+            self._record(_Command('delete', canonical, chars))
+        else:
+            self.delegate.delete(index1, index2)
+
+    # ── recording ─────────────────────────────────────────────────────────
+
+    def _record(self, cmd: _Command) -> None:
+        self._redo_stack.clear()
+        if self._current_block is not None:
+            self._current_block.append(cmd)
+            return
+        # Try to merge with the last single-command block
+        if self._stack and len(self._stack[-1]) == 1:
+            if self._stack[-1][0].merge(cmd):
+                return
+        self._stack.append([cmd])
+        if len(self._stack) > self.MAX_UNDO:
+            self._stack.pop(0)
+            if self._saved_index > 0:
+                self._saved_index -= 1
+
+    # ── public API ────────────────────────────────────────────────────────
+
+    def undo_block_start(self) -> None:
+        """Begin a compound undo block. Nested calls are safe."""
+        if self._block_depth == 0:
+            self._current_block = []
+        self._block_depth += 1
+
+    def undo_block_stop(self) -> None:
+        """End a compound undo block. Commits when depth reaches zero."""
+        self._block_depth -= 1
+        if self._block_depth == 0 and self._current_block is not None:
+            if self._current_block:
+                self._stack.append(self._current_block)
+            self._current_block = None
+
+    def undo(self) -> None:
+        """Undo the last edit group."""
+        if not self._stack or self._core is None:
+            return
+        block = self._stack.pop()
+        self._redo_stack.append(block)
+        self._undoing = True
+        try:
+            for cmd in reversed(block):
+                cmd.undo(self._core)
+        finally:
+            self._undoing = False
+        self._core.text.event_generate(
+            '<<TextUndo>>', data=InputEvent(text=self._core.value), when='tail'
+        )
+
+    def redo(self) -> None:
+        """Redo the last undone edit group."""
+        if not self._redo_stack or self._core is None:
+            return
+        block = self._redo_stack.pop()
+        self._stack.append(block)
+        self._undoing = True
+        try:
+            for cmd in block:
+                cmd.do(self._core)
+        finally:
+            self._undoing = False
+        self._core.text.event_generate(
+            '<<TextRedo>>', data=InputEvent(text=self._core.value), when='tail'
+        )
+
+    def reset_undo(self) -> None:
+        """Clear undo/redo history and mark current state as saved."""
+        self._stack.clear()
+        self._redo_stack.clear()
+        self._redo_stack.clear()
+        self._saved_index = 0
+
+    def mark_saved(self) -> None:
+        """Mark the current stack depth as the saved baseline."""
+        self._saved_index = len(self._stack)
+
+    @property
+    def is_dirty(self) -> bool:
+        """True if the stack depth differs from the saved baseline."""
+        return len(self._stack) != self._saved_index

bootstack/widgets/_impl/composites/textentry.py

@@ -0,0 +1,57 @@
+from typing import Any
+
+from typing_extensions import Unpack
+
+from bootstack.widgets._impl.composites.field import Field, FieldOptions
+from bootstack.widgets.types import Master
+
+
+class TextEntry(Field):
+    """A text entry field widget with label, validation, and formatting support.
+
+    TextEntry is a composite widget that combines a label, text entry input, and
+    message area into a single component. It provides internationalization-aware
+    text input with deferred parsing, validation support, and visual feedback.
+
+    The widget separates user input (display text) from the committed/parsed value,
+    only parsing and formatting when the user commits via `<FocusOut>` or `<Return>`.
+    """
+
+    def __init__(
+            self, master: Master = None, value: Any = None, label: str = None, message: str = None,
+            **kwargs: Unpack[FieldOptions]):
+        """Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial value to display. Default is None.
+            label: Optional label text to display above the entry field.
+                If required=True, an asterisk (*) is automatically appended.
+            message: Optional message text to display below the entry field.
+                This is replaced by validation error messages when validation fails.
+
+        Other Parameters:
+            accent: Accent token for the focus ring and active border.
+            density: Widget density — 'default' or 'compact'.
+            state: Initial widget state — 'normal', 'disabled', or 'readonly'.
+            allow_blank: Allow empty input. Default is True.
+            cursor: Cursor style when hovering.
+            value_format: ICU format pattern for parsing/formatting.
+            exportselection: Export selection to clipboard.
+            font: Font for text display.
+            foreground: Text color.
+            initial_focus: If True, widget receives focus on creation.
+            justify: Text alignment ('left', 'center', 'right').
+            show_message: If True, displays message area. Defaults to False,
+                but auto-enables when `message=` or `required=True` is set.
+            padding: Padding around entry widget.
+            show: Character to mask input (e.g., '*' for passwords).
+            takefocus: If True, widget accepts Tab focus.
+            textvariable: Tkinter Variable to link with text.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            textsignal: Signal object for reactive updates.
+            width: Width in characters.
+            required: If True, field cannot be empty. Adds 'required'
+                validation rule and appends '*' to label.
+            xscrollcommand: Callback for horizontal scrolling.
+        """
+        super().__init__(master, value=value, label=label, message=message, **kwargs)
+

bootstack/widgets/_impl/composites/timeentry.py

@@ -0,0 +1,176 @@
+"""Time entry field widget with dropdown list of time intervals.
+
+Provides a specialized entry field for time input with a searchable dropdown
+list of time values at specified intervals.
+"""
+
+from __future__ import annotations
+
+import datetime
+from bootstack.i18n.intl_format import DateFormatSpec
+
+from typing_extensions import Unpack
+
+from bootstack._runtime.app import get_app_settings
+from bootstack.i18n import IntlFormatter
+from bootstack.widgets._impl.composites.field import FieldOptions
+from bootstack.widgets._impl.composites.selectbox import SelectBox
+from bootstack.widgets.types import Master
+
+
+class TimeEntry(SelectBox):
+    """Time entry field with dropdown list of time intervals.
+
+    TimeEntry extends SelectBox to provide specialized time input with
+    locale-aware formatting and a searchable dropdown of time intervals.
+    The widget supports various time format presets and custom time patterns.
+    """
+
+    def __init__(
+            self,
+            master: Master = None,
+            value: datetime.time | str = None,
+            value_format: DateFormatSpec = 'shortTime',
+            interval: int = 30,
+            min_time: datetime.time | str = None,
+            max_time: datetime.time | str = None,
+            label: str = None,
+            message: str = None,
+            **kwargs: Unpack[FieldOptions]
+    ):
+        """Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial time value to display. Can be a time object or string.
+                Empty by default.
+            value_format: Time format pattern for parsing and displaying times.
+                Default is "shortTime" (e.g., "3:30 PM"). Common formats:
+                "shortTime" (3:30 PM), "longTime" (3:30:45 PM PST),
+                "mediumTime" (3:30:45 PM), "HH:mm" (15:30), "h:mm a" (3:30 PM).
+            interval: Time interval in minutes for dropdown items (e.g., 15, 30, 60).
+                Default is 30 minutes.
+            min_time: Minimum time value for the dropdown list. Can be a time object
+                or string (e.g., "09:00" or "9:00 AM"). Default is midnight (00:00).
+            max_time: Maximum time value for the dropdown list. Can be a time object
+                or string (e.g., "17:00" or "5:00 PM"). Default is 11:59 PM (23:59).
+            label: Optional label text to display above the entry field.
+                If required=True, an asterisk (*) is automatically appended.
+            message: Optional message text to display below the entry field.
+                Used for hints or help text. Replaced by validation errors when
+                validation fails.
+
+        Other Parameters:
+            locale: Locale identifier for time formatting (e.g., 'en_US').
+            required: If True, field cannot be empty.
+            accent: Accent token for the focus ring and active border.
+            allow_blank: Allow empty input.
+            width: Width in characters.
+            textvariable: Tkinter Variable to link with text.
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            textsignal: Signal object for reactive updates.
+        """
+        self._interval = interval
+        self._value_format = value_format
+        self._locale = kwargs.get('locale') or get_app_settings().locale
+
+        # Parse and store time range
+        self._min_time = self._parse_time(min_time) if min_time else datetime.time(0, 0)
+        self._max_time = self._parse_time(max_time) if max_time else datetime.time(23, 59)
+
+        # An empty field stays empty — consistent with the other field widgets,
+        # so `required=` meaningfully demands input (was: defaulted to the current
+        # time, which silently pre-filled and defeated `required`). Pass an
+        # explicit `value=` to seed a starting time.
+        if value is None or value == "":
+            formatted_value = ""
+        else:
+            # Normalize value to a time object using our own parser (avoids
+            # dateparser mis-reading "08:30" as "August 30"), then format it with
+            # the same IntlFormatter used to build items so the strings compare
+            # equal.
+            formatter = IntlFormatter(locale=self._locale)
+            time_val = self._parse_time(value) if isinstance(value, str) else value
+            formatted_value = formatter.format(time_val, value_format)
+
+        # Generate time intervals for dropdown
+        items = self._generate_time_intervals()
+
+        # Initialize SelectBox with time-specific configuration
+        super().__init__(
+            master=master,
+            value=formatted_value,
+            value_format=value_format,
+            items=items,
+            allow_custom_values=True,
+            enable_search=True,
+            dropdown_button_icon='clock',
+            message=message,
+            label=label,
+            **kwargs
+        )
+
+    def _parse_time(self, time_value: datetime.time | str) -> datetime.time:
+        """Parse time value from various input formats.
+
+        Args:
+            time_value: Time value as time object or string
+
+        Returns:
+            Parsed time object, or midnight (00:00) if parsing fails
+        """
+        if isinstance(time_value, datetime.time):
+            return time_value
+
+        if isinstance(time_value, str):
+            # Try 24-hour format (HH:MM)
+            try:
+                dt = datetime.datetime.strptime(time_value, '%H:%M')
+                return dt.time()
+            except ValueError:
+                pass
+
+            # Try 12-hour format (h:MM AM/PM)
+            try:
+                dt = datetime.datetime.strptime(time_value, '%I:%M %p')
+                return dt.time()
+            except ValueError:
+                pass
+
+        # Fallback to midnight
+        return datetime.time(0, 0)
+
+    def _generate_time_intervals(self) -> list[str]:
+        """Generate list of formatted time strings at specified intervals.
+
+        Creates a list of time values from min_time to max_time at the specified
+        interval, formatted according to value_format. Uses IntlFormatter for
+        consistent locale-aware formatting with Field.
+
+        Returns:
+            List of formatted time strings
+        """
+        times = []
+        formatter = IntlFormatter(locale=self._locale)
+
+        # Convert time objects to datetime for iteration
+        current = datetime.datetime.combine(datetime.date.today(), self._min_time)
+        end = datetime.datetime.combine(datetime.date.today(), self._max_time)
+
+        # Handle midnight crossing (e.g., min_time=22:00, max_time=02:00)
+        if end < current:
+            end += datetime.timedelta(days=1)
+
+        # Generate intervals
+        while current <= end:
+            # Format using IntlFormatter (consistent with TextEntryPart)
+            # Note: Pass datetime (not time) as IntlFormatter expects it for Babel
+            try:
+                formatted_time = formatter.format(current, self._value_format)
+            except:
+                # Fallback to 24-hour format if formatting fails
+                formatted_time = current.strftime('%H:%M')
+
+            times.append(formatted_time)
+            current += datetime.timedelta(minutes=self._interval)
+
+        return times
+