bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/composites/numericentry.py

@@ -0,0 +1,183 @@
+"""Numeric entry field widget with spin buttons.
+
+Provides a specialized entry field for numeric input with increment/decrement
+buttons and keyboard/mouse wheel support.
+"""
+
+from typing import Any
+from tkinter import TclError
+from typing_extensions import Unpack
+
+from bootstack.widgets.primitives.button import Button
+from bootstack.widgets.composites.field import Field, FieldOptions
+from bootstack.widgets.mixins import configure_delegate
+from bootstack.widgets.types import Master
+
+
+class NumericEntry(Field):
+    """A numeric entry field widget with increment/decrement spin buttons.
+
+    Extends Field to provide numeric input with spin buttons, bounds validation,
+    keyboard stepping (Up/Down arrows), mouse wheel support, and optional wrapping.
+
+    !!! note "Events"
+
+        - `<<Increment>>`: Fired when increment is requested (before step occurs).
+        - `<<Decrement>>`: Fired when decrement is requested (before step occurs).
+        - `<<Change>>`: Fired when value changes after commit.
+        - `<<Input>>`: Fired on each keystroke.
+        - `<<Valid>>`: Fired when validation passes.
+        - `<<Invalid>>`: Fired when validation fails.
+
+    Attributes:
+        entry_widget (NumberEntryPart): The underlying entry widget.
+        label_widget (Label): The label widget.
+        message_widget (Label): The message label widget.
+        addons (dict[str, Widget]): Dictionary of inserted addon widgets by name.
+        variable (Variable): Tkinter Variable linked to entry text.
+        signal (Signal): Signal object for reactive updates.
+    """
+
+    def __init__(
+            self,
+            master: Master = None,
+            value: int | float = 0,
+            label: str = None,
+            message: str = None,
+            show_spin_buttons: bool = True,
+            minvalue: int | float | None = None,
+            maxvalue: int | float | None = None,
+            increment: int | float = 1,
+            **kwargs: Unpack[FieldOptions]
+    ):
+        """Initialize a NumericEntry widget.
+
+        Creates a numeric entry field with optional label, validation, bounds
+        constraints, and increment/decrement spin buttons. The widget supports
+        keyboard stepping (Up/Down arrows), mouse wheel interaction, and optional
+        value wrapping at boundaries.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            value (int | float): Initial numeric value to display.
+            label (str): Optional label text to display above the entry field.
+                If `required=True`, an asterisk (*) is automatically appended.
+            message (str): Optional message text to display below the entry field.
+                Used for hints or help text. Replaced by validation errors when
+                validation fails.
+            show_spin_buttons (bool): If True, displays increment/decrement buttons
+                (plus and minus icons) to the right of the entry.
+            minvalue (int | float): Minimum allowed value (inclusive). Values below
+                this will be clamped or wrapped depending on the wrap setting.
+            maxvalue (int | float): Maximum allowed value (inclusive). Values above
+                this will be clamped or wrapped depending on the wrap setting.
+            increment (int | float): Step size for increment/decrement operations.
+
+        Other Parameters:
+            wrap (bool): If True, values wrap around at min/max boundaries.
+            value_format (str): Number format specification for IntlFormatter.
+                Examples: `'decimal'`, `'percent'`, `'currency'`, `'#,##0.00'`.
+            locale (str): Locale identifier for number formatting (e.g., `'en_US'`).
+            required (bool): If True, field cannot be empty.
+            accent (str): Accent token for the focus ring and active border.
+            bootstyle (str): DEPRECATED - Use `accent` instead.
+            allow_blank (bool): If True, empty input is allowed (sets value to None).
+            cursor (str): Cursor style when hovering.
+            exportselection (bool): Export selection to clipboard.
+            font (str): Font for text display.
+            foreground (str): Text color.
+            initial_focus (bool): If True, widget receives focus on creation.
+            justify (str): Text alignment (`'left'`, `'center'`, `'right'`).
+            show_message (bool): If True, displays message area.
+            padding (int | tuple): Padding around entry widget.
+            takefocus (bool): If True, widget accepts Tab focus.
+            textvariable (Variable): Tkinter Variable to link with text.
+            textsignal (Signal): Signal object for reactive updates.
+            width (int): Width in characters.
+            xscrollcommand (Callable): Callback for horizontal scrolling.
+        """
+        super().__init__(
+            master, value=value, label=label, message=message, minvalue=minvalue, maxvalue=maxvalue, kind="numeric",
+            increment=increment, **kwargs)
+
+        self._show_spin_buttons = show_spin_buttons
+
+        # passthrough methods
+        self.on_increment = self.entry_widget.on_increment
+        self.off_increment = self.entry_widget.off_increment
+        self.on_decrement = self.entry_widget.on_decrement
+        self.off_decrement = self.entry_widget.off_decrement
+        self.step = self.entry_widget.step
+
+        # pack info
+        self._increment_pack_info = {}
+        self._decrement_pack_info = {}
+
+        # buttons
+        self.insert_addon(
+            Button, position="after", name="decrement", icon="dash", command=self.decrement, icon_only=True)
+        self.insert_addon(
+            Button, position="after", name="increment", icon="plus", command=self.increment, icon_only=True)
+        self._delegate_show_spin_buttons(show_spin_buttons)
+
+        self.entry_widget.bind('<<StateChanged>>', self._on_entry_state_changed, add=True)
+        self._update_spin_button_states()
+
+    @property
+    def increment_widget(self):
+        """Get the increment spin button widget."""
+        return self.addons['increment']
+
+    @property
+    def decrement_widget(self):
+        """Get the decrement spin button widget."""
+        return self.addons['decrement']
+
+    def increment(self):
+        """Increment the numeric value by one step."""
+        if not self._entry_is_interactive():
+            return
+        self.entry_widget.event_generate("<<Increment>>")
+
+    def decrement(self):
+        """Decrement the numeric value by one step."""
+        if not self._entry_is_interactive():
+            return
+        self.entry_widget.event_generate("<<Decrement>>")
+
+    def _entry_is_interactive(self) -> bool:
+        """Return True if the entry widget is not disabled or readonly."""
+        state = self.entry_widget.state()
+        return 'disabled' not in state and 'readonly' not in state
+
+    def _on_entry_state_changed(self, _: Any = None):
+        """Sync spin buttons whenever the entry state mutates."""
+        self._update_spin_button_states()
+
+    def _update_spin_button_states(self):
+        """Enable or disable spin buttons based on entry interactivity."""
+        state_value = 'disabled' if not self._entry_is_interactive() else '!disabled'
+        for control in (self.increment_widget, self.decrement_widget):
+            try:
+                control.configure(state=state_value)
+            except TclError:
+                pass
+
+    @configure_delegate('show_spin_buttons')
+    def _delegate_show_spin_buttons(self, value: bool = None):
+        """Get or set the visibility of spin buttons."""
+        if value is None:
+            return self._show_spin_buttons
+        else:
+            self._show_spin_buttons = value
+            if value:
+                if not self.increment_widget.winfo_ismapped():
+                    self.increment_widget.pack(**self._increment_pack_info)
+                if not self.decrement_widget.winfo_ismapped():
+                    self.decrement_widget.pack(**self._decrement_pack_info)
+            else:
+                self._increment_pack_info = self.increment_widget.pack_info()
+                self._decrement_pack_info = self.decrement_widget.pack_info()
+                self.increment_widget.pack_forget()
+                self.decrement_widget.pack_forget()
+        return None

bootstack/widgets/composites/pagestack.py

@@ -0,0 +1,330 @@
+import tkinter
+from collections.abc import ValuesView
+from typing import Any, Callable
+
+from typing_extensions import TypedDict, Unpack
+
+from bootstack.widgets.primitives import Frame
+from bootstack.widgets.types import Master
+from bootstack.core import NavigationError
+
+
+class PageOptions(TypedDict, total=False):
+    padding: Any
+    width: int
+    height: int
+    style: str
+    cursor: str
+    show_border: bool
+    accent: str
+    variant: str
+    surface: str
+    style_options: dict[str, Any]
+
+
+class PageStackKwargs(TypedDict, total=False):
+    takefocus: bool
+    width: int
+    height: int
+    padding: Any
+
+
+class PageStack(Frame):
+    """A navigation container widget for managing multiple pages with history support.
+
+    PageStack provides a stack-based navigation system where only one page is
+    visible at a time. It maintains a navigation history, allowing users to move
+    backward and forward through pages similar to a web browser.
+
+    !!! note "Events"
+
+        - `<<PageUnmount>>`: Triggered when the current page is hidden.
+        - `<<PageWillMount>>`: Triggered before a new page is displayed.
+        - `<<PageMount>>`: Triggered after a new page is displayed.
+        - `<<PageChange>>`: Triggered after page navigation completes.
+
+        All events provide `event.data` with keys: `page`, `prev_page`, `prev_data`,
+        `nav` ('push', 'back', 'forward'), `index`, `length`, `can_back`,
+        `can_forward`.
+    """
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[PageStackKwargs]):
+        """Initialize a new PageStack instance.
+
+        Creates an empty PageStack with no pages and no navigation history.
+        The widget inherits from Frame and supports all standard Frame
+        configuration options.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+
+        Other Parameters:
+            takefocus (bool): If True, the widget can receive keyboard focus.
+            width (int): Width of the PageStack in pixels.
+            height (int): Height of the PageStack in pixels.
+            padding (int | tuple): Padding around the PageStack (can be a single value
+                or tuple of (left, top, right, bottom)).
+
+        Note:
+            Pages must be added using add() before navigation can occur.
+            The PageStack starts with an empty history and no current page.
+        """
+        super().__init__(master, **kwargs)
+        self._pages: dict[str, tkinter.Widget] = {}
+        self._current: str | None = None
+        self._history: list[tuple[str, dict]] = []
+        self._index: int = -1
+
+    def add(self, key: str, page: tkinter.Widget = None, **kwargs) -> tkinter.Widget:
+        """Add a page to the stack, optionally creating a Frame.
+
+        Args:
+            key (str): Unique identifier for the page (required for navigation).
+            page (Widget | None): The widget to add. If None, creates a Frame.
+            **kwargs: When page is None, these are passed to Frame (e.g., padding, color, variant).
+
+        Returns:
+            Widget: The page widget (passed or created Frame).
+
+        Raises:
+            NavigationError: If a page with the given key already exists.
+            ValueError: If key is an empty string.
+        """
+        if not key:
+            raise ValueError("Page key cannot be an empty string")
+        if key in self._pages:
+            raise NavigationError(f"Page {key} already exists")
+
+        if page is None:
+            page = Frame(self, **kwargs)
+
+        self._pages[key] = page
+        page.pack(fill='both', expand=True)
+        page.pack_forget()
+        return page
+
+    def remove(self, key: str) -> None:
+        """Remove a page from the stack and destroy its widget.
+
+        Args:
+            key: The identifier of the page to remove
+
+        Note:
+            If the removed page is currently displayed, the current page
+            will be set to None without navigating to another page.
+        """
+        if key in self._pages:
+            page = self._pages.pop(key)
+            page.destroy()
+        if self._current == key:
+            self._current = None
+
+    def navigate(
+            self,
+            key: str,
+            data: dict | None = None,
+            replace: bool = False,
+            _nav: str = 'push',
+            _prev: tuple[str, dict] | None = None
+    ) -> None:
+        """Navigate to the page with the given key.
+
+        This method handles page transitions, manages navigation history,
+        and triggers lifecycle events (`<<PageUnmount>>`, `<<PageWillMount>>`,
+        `<<PageMount>>`, `<<PageChange>>`).
+
+        Args:
+            key: The identifier of the page to navigate to
+            data: Optional data to pass to the page and include in event payloads
+            replace: If True, replace the current history entry instead of adding a new one
+            _nav: Internal parameter indicating navigation type ('push', 'back', 'forward')
+            _prev: Internal parameter for preserving previous page state
+
+        Raises:
+            NavigationError: If the page with the given key does not exist
+            ValueError: If key is an empty string
+
+        Note:
+            Event payloads include: page, prev_page, prev_data, nav, index,
+            length, can_back, and can_forward.
+        """
+        if not key:
+            raise ValueError("Page key cannot be an empty string")
+        if key not in self._pages:
+            raise NavigationError(f"Page {key} does not exist")
+
+        # Normalize data to empty dict if None
+        if data is None:
+            data = {}
+
+        # Snapshot "previous" BEFORE mutating history
+        if _prev is None:
+            prev_key = self._current
+            prev_data = self._history[self._index][1] if self._index >= 0 else {}
+        else:
+            prev_key, prev_data = _prev
+
+        # Mutate history
+        if replace and 0 <= self._index < len(self._history):
+            self._history[self._index] = (key, data)
+        else:
+            if self._index < len(self._history) - 1:
+                self._history = self._history[:self._index + 1]
+            self._history.append((key, data))
+            self._index += 1
+
+        # Unmount previous page
+        if self._current is not None:
+            self._pages[self._current].event_generate('<<PageUnmount>>', when="tail")
+            self._pages[self._current].pack_forget()
+
+        # Normalized payload (self-contained snapshot)
+        payload = dict(data)
+        payload.update(
+            {
+                "page": key,
+                "prev_page": prev_key,
+                "prev_data": prev_data,
+                "nav": _nav,
+                "index": self._index,
+                "length": len(self._history),
+                "can_back": self._index > 0,
+                "can_forward": self._index < len(self._history) - 1,
+            }
+        )
+
+        # Mount and notify
+        page = self._pages[key]
+        page.event_generate('<<PageWillMount>>', data=payload, when="tail")
+        page.pack(fill='both', expand=True)
+        self._current = key
+        self.event_generate('<<PageMount>>', data=payload, when="tail")
+        self.event_generate('<<PageChange>>', data=payload, when="tail")
+
+    def back(self) -> None:
+        """Navigate to the previous page in the navigation history.
+
+        This method moves backward in the history stack if possible.
+        Does nothing if already at the first page.
+        """
+        if self._index > 0:
+            # Snapshot BEFORE changing index
+            prev = (self._current, self._history[self._index][1] if self._index >= 0 else {})
+            self._index -= 1
+            key, data = self._history[self._index]
+            # use replace=True to avoid pushing a new entry
+            # pass _prev to preserve the correct 'previous' snapshot
+            self.navigate(key, data=data, replace=True, _nav='back', _prev=prev)
+
+    def forward(self) -> None:
+        """Navigate to the next page in the navigation history.
+
+        This method moves forward in the history stack if possible.
+        Does nothing if already at the most recent page.
+        """
+        if self._index < len(self._history) - 1:
+            prev = (self._current, self._history[self._index][1] if self._index >= 0 else {})
+            self._index += 1
+            key, data = self._history[self._index]
+            self.navigate(key, data=data, replace=True, _nav='forward', _prev=prev)
+
+    def can_back(self) -> bool:
+        """Check if backward navigation is possible.
+
+        Returns:
+            True if there is a previous page in the history to navigate back to,
+            False otherwise.
+        """
+        return self._index > 0
+
+    def can_forward(self) -> bool:
+        """Check if forward navigation is possible.
+
+        Returns:
+            True if there is a next page in the history to navigate forward to,
+            False otherwise.
+        """
+        return self._index < len(self._history) - 1
+
+    def current(self) -> tuple[str, dict] | None:
+        """Return the current page key and its navigation data.
+
+        Returns:
+            A tuple of (page_key, data_dict) if a page is currently displayed,
+            None if no page is currently displayed.
+        """
+        if self._current is None:
+            return None
+        return self._current, (self._history[self._index][1] if self._index >= 0 else {})
+
+    def item(self, key: str) -> tkinter.Widget:
+        """Get a page by its key.
+
+        Args:
+            key: The identifier of the page to retrieve.
+
+        Returns:
+            The page widget.
+
+        Raises:
+            KeyError: If no page with the given key exists.
+            ValueError: If key is an empty string.
+        """
+        if not key:
+            raise ValueError("Page key cannot be an empty string")
+        if key not in self._pages:
+            raise KeyError(f"No page with key '{key}'")
+        return self._pages[key]
+
+    def items(self) -> tuple[tkinter.Widget, ...]:
+        """Get all page widgets in the stack.
+
+        Returns:
+            A tuple of all page widgets managed by this PageStack.
+        """
+        return tuple(self._pages.values())
+
+    def keys(self) -> tuple[str, ...]:
+        """Get all page keys.
+
+        Returns:
+            A tuple of all page keys in the stack.
+        """
+        return tuple(self._pages.keys())
+
+    def configure_item(self, key: str, option: Any = None, **kwargs: Any) -> Any:
+        """Query or configure the page configuration.
+
+        Args:
+            key: The identifier of the page to configure.
+            option: Optional configuration option to query.
+            **kwargs: Configuration options to set on the page widget.
+
+        Returns:
+            If option is provided, returns the value of that option.
+            Otherwise returns the result of configure() if kwargs are provided.
+
+        Raises:
+            KeyError: If no page with the given key exists.
+            ValueError: If key is an empty string.
+        """
+        if not key:
+            raise ValueError("Page key cannot be an empty string")
+        if key not in self._pages:
+            raise KeyError(f"No page with key '{key}'")
+        if option is not None:
+            return self._pages[key].cget(option)
+        else:
+            return self._pages[key].configure(**kwargs)
+
+    def on_page_changed(self, callback: Callable) -> str:
+        """Bind to `<<PageChange>>`. Callback receives `event.data` with navigation info.
+
+        Returns:
+            Binding identifier for use with off_page_changed().
+        """
+        return self.bind('<<PageChange>>', callback, add="+")
+
+    def off_page_changed(self, bind_id: str | None = None) -> None:
+        """Unbind from `<<PageChange>>`."""
+        self.unbind("<<PageChange>>", bind_id)

bootstack/widgets/composites/passwordentry.py

@@ -0,0 +1,149 @@
+"""Password entry field widget with visibility toggle.
+
+Provides a specialized text entry field for password input with masked characters
+and an optional visibility toggle button.
+"""
+
+from bootstack.widgets.primitives.button import Button
+from bootstack.widgets.composites.field import Field, FieldOptions
+from bootstack.widgets.mixins.configure_mixin import configure_delegate
+from bootstack.widgets.types import Master
+from typing_extensions import Unpack
+
+
+class PasswordEntry(Field):
+    """A password entry field widget with masked input and visibility toggle.
+
+    PasswordEntry extends the Field widget to provide password-specific functionality,
+    including character masking and a toggle button to temporarily reveal the password.
+    The widget automatically inserts a visibility toggle button (eye icon) that shows
+    the password while pressed and hides it when released.
+
+    !!! note "Events"
+
+        - `<<Input>>`: Triggered on each keystroke.
+        - `<<Change>>`: Triggered when value changes after commit.
+        - `<<Valid>>`: Triggered when validation passes.
+        - `<<Invalid>>`: Triggered when validation fails.
+        - `<<Validate>>`: Triggered after any validation.
+
+    Attributes:
+        entry_widget (TextEntryPart): The underlying text entry widget.
+        label_widget (Label): The label widget above the entry.
+        message_widget (Label): The message label widget below the entry.
+        addons (dict[str, Widget]): Dictionary of inserted addon widgets by name.
+        variable (Variable): Tkinter Variable linked to entry text.
+        signal (Signal): Signal object for reactive updates.
+    """
+
+    def __init__(
+            self,
+            master: Master = None,
+            value: str = None,
+            label: str = None,
+            message: str = None,
+            show_visibility_toggle: bool = True,
+            **kwargs: Unpack[FieldOptions]):
+        """Initialize a PasswordEntry widget.
+
+        Creates a password entry field with character masking and an optional
+        visibility toggle button. The widget automatically masks input characters
+        (default: '•') and provides a button to temporarily reveal the password
+        while pressed.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial password value to display (masked). 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.
+                Used for hints or help text. Replaced by validation errors when
+                validation fails.
+            show_visibility_toggle: If True, displays the visibility toggle button
+                (eye icon) that reveals the password while pressed. Default is True.
+                Can be changed at runtime via `configure(show_visibility_toggle=...)`.
+
+        Other Parameters:
+            show (str): Character to mask password input. Default is '•'.
+            required (bool): If True, field cannot be empty.
+            accent (str): Accent token for the focus ring and active border.
+            bootstyle (str): DEPRECATED - Use `accent` instead.
+            allow_blank (bool): Allow empty input.
+            cursor (str): Cursor style when hovering.
+            font (str): Font for text display.
+            foreground (str): Text color.
+            initial_focus (bool): If True, widget receives focus on creation.
+            justify (str): Text alignment.
+            show_message (bool): If True, displays message area.
+            padding (str): Padding around entry widget.
+            takefocus (bool): If True, widget accepts Tab focus.
+            textvariable (Variable): Tkinter Variable to link with text.
+            textsignal (Signal): Signal object for reactive updates.
+            width (int): Width in characters.
+
+        Note:
+            The visibility toggle button uses a press-and-hold interaction.
+            The password is only visible while the button is actively pressed,
+            providing a secure way to verify input without leaving it exposed.
+        """
+        # set default mask if not provided
+        self._show_indicator = kwargs.get('show', '•')
+        kwargs.setdefault('show', self._show_indicator)
+        super().__init__(master, value=value, label=label, message=message, **kwargs)
+
+        # configuration
+        self._show_visibility_toggle = show_visibility_toggle
+        self._show_visibility_pack = {}
+
+        self.insert_addon(
+            Button,
+            position="after",
+            name="visibility",
+            icon={"name": "eye", "state": [("pressed", "eye-slash")]},
+            compound="image",
+            icon_only=True
+        )
+        addon = self.addons['visibility']
+        addon.bind('<ButtonPress>', self._show_password, add=True)
+        addon.bind('<ButtonRelease>', self._hide_password, add=True)
+
+        # Apply initial visibility setting
+        if not show_visibility_toggle:
+            self._apply_visibility_toggle(False)
+
+    @property
+    def _visibility_toggle(self):
+        """Get the visibility toggle button widget."""
+        return self.addons['visibility']
+
+    def _show_password(self, _):
+        """Reveal the password by removing character masking."""
+        self.entry_widget['show'] = ''
+
+    def _hide_password(self, _):
+        """Hide the password by restoring character masking."""
+        self.entry_widget['show'] = self._show_indicator
+
+    # ------ Configuration Delegates ------
+
+    @configure_delegate('show_visibility_toggle')
+    def _delegate_show_visibility_toggle(self, value=None):
+        if value is None:
+            return self._show_visibility_toggle
+        else:
+            self._apply_visibility_toggle(value)
+        return None
+
+    def _apply_visibility_toggle(self, value: bool):
+        """Show or hide the visibility toggle button.
+
+        Args:
+            value: If True, show the toggle button. If False, hide it.
+        """
+        self._show_visibility_toggle = value
+        if value and not self._visibility_toggle.winfo_ismapped():
+            self._visibility_toggle.pack(**self._show_visibility_pack)
+        elif not value and self._visibility_toggle.winfo_ismapped():
+            self._show_visibility_pack = self._visibility_toggle.pack_info()
+            self._visibility_toggle.pack_forget()
+