bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/mixins/signal_mixin.py

@@ -0,0 +1,272 @@
+"""Signal integration mixins for bootstack widgets.
+
+Provides seamless integration between tkinter Variables and reactive Signals,
+exposing both as properties on widgets that support `textvariable` and `variable`
+options. The mixins maintain bidirectional synchronization between Variables and
+Signals automatically.
+
+These mixins are thin glue layers that delegate to the core signal capability
+module for normalization and binding logic.
+"""
+
+from __future__ import annotations
+
+import tkinter as tk
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+
+from bootstack.core.capabilities.signals import (
+    is_signal,
+    is_variable,
+    normalize_signal,
+    create_signal,
+    infer_default_value_for_widget,
+    query_binding,
+)
+from bootstack.widgets.mixins.configure_mixin import configure_delegate
+
+
+class TextSignalMixin:
+    """Mixin providing `.textvariable` and `.textsignal` properties for text-based widgets.
+
+    For widgets that support the `textvariable` option (Entry, Label, Button, etc.),
+    this mixin exposes both the underlying tk.Variable and a reactive Signal as properties,
+    maintaining bidirectional synchronization between them.
+
+    This mixin delegates normalization and binding logic to the core signals capability.
+
+    Attributes:
+        textvariable (Variable): The underlying tk.Variable (usually StringVar).
+        textsignal (Signal): The reactive Signal wrapper with subscribe/map capabilities.
+    """
+
+    def __init__(self, *args, **kwargs):
+        """Initialize mixin and extract textsignal/textvariable parameters before tkinter sees them."""
+        # Extract textsignal and textvariable before passing kwargs to tkinter
+        textsignal_value = kwargs.pop('textsignal', None)
+        textvariable_value = kwargs.pop('textvariable', None)
+
+        # Call parent __init__
+        super().__init__(*args, **kwargs)
+
+        # Apply textsignal or textvariable after widget construction
+        # Prefer textsignal if both are provided
+        if textsignal_value is not None:
+            self._config_delegate_set('textsignal', textsignal_value)
+        elif textvariable_value is not None:
+            self._config_delegate_set('textvariable', textvariable_value)
+
+    @configure_delegate("textvariable", "textsignal")
+    def _delegate_textsignal(self, value: Any = None):
+        """Handle textvariable and textsignal configuration.
+
+        Args:
+            value: Signal, tk.Variable, or None for query.
+
+        Returns:
+            Current value for query path, None for set path.
+        """
+        # Query path - return stored value
+        if value is None:
+            return query_binding(
+                getattr(self, '_textsignal', None),
+                getattr(self, '_textvariable', None),
+                self._ttk_base,  # type: ignore[misc]
+                self,
+                'textvariable',
+            )
+
+        # Set path - normalize and apply
+        binding = normalize_signal(value, default_value="")
+        if binding is not None:
+            self._textsignal = binding.signal
+            self._textvariable = binding.variable
+            var_to_set = binding.tk_value
+        else:
+            # String (Tcl variable name) or other - pass through
+            var_to_set = value
+            if value:
+                self._textvariable = value
+
+        # Apply via base ttk widget to avoid recursion
+        return self._ttk_base.configure(self, textvariable=var_to_set)  # type: ignore[misc]
+
+    @property
+    def textsignal(self) -> 'Signal[str]':
+        """Get or lazily create the textsignal.
+
+        If no textvariable has been set, creates a new Signal with empty string.
+        If textvariable exists, wraps it in a Signal.
+
+        Returns:
+            The reactive Signal for this widget's text.
+        """
+        if not hasattr(self, '_textsignal'):
+            # Create fresh signal
+            binding = create_signal("")
+            self._textsignal = binding.signal
+            self._textvariable = binding.variable
+            try:
+                self._ttk_base.configure(self, textvariable=binding.tk_value)  # type: ignore[misc]
+            except Exception:
+                pass
+        return self._textsignal
+
+    @textsignal.setter
+    def textsignal(self, value: 'Signal[str]') -> None:
+        """Set the textsignal, extracting and configuring its underlying variable.
+
+        Args:
+            value: Signal to use for this widget's text.
+        """
+        self._delegate_textsignal(value)
+
+    @property
+    def textvariable(self) -> tk.Variable:
+        """Get the underlying tk.Variable.
+
+        If not yet created, accessing this property will trigger lazy creation
+        via the textsignal property.
+
+        Returns:
+            The tk.Variable (usually StringVar) for this widget's text.
+        """
+        if not hasattr(self, '_textvariable'):
+            # Trigger lazy creation via textsignal
+            _ = self.textsignal
+        return self._textvariable
+
+    @textvariable.setter
+    def textvariable(self, value: tk.Variable) -> None:
+        """Set the textvariable, creating a synced Signal automatically.
+
+        Args:
+            value: tk.Variable to use for this widget's text.
+        """
+        self._delegate_textsignal(value)
+
+
+class SignalMixin:
+    """Mixin providing `.variable` and `.signal` properties for value-based widgets.
+
+    For widgets that support the `variable` option (Checkbutton, Radiobutton, Scale, etc.),
+    this mixin exposes both the underlying tk.Variable and a reactive Signal as properties,
+    maintaining bidirectional synchronization between them.
+
+    This mixin delegates normalization and binding logic to the core signals capability.
+
+    Attributes:
+        variable (Variable): The underlying tk.Variable (IntVar, DoubleVar, BooleanVar, etc.).
+        signal (Signal): The reactive Signal wrapper with subscribe/map capabilities.
+    """
+
+    def __init__(self, *args, **kwargs):
+        """Initialize mixin and extract signal/variable parameters before tkinter sees them."""
+        # Extract signal and variable before passing kwargs to tkinter
+        signal_value = kwargs.pop('signal', None)
+        variable_value = kwargs.pop('variable', None)
+
+        # Call parent __init__
+        super().__init__(*args, **kwargs)
+
+        # Apply signal or variable after widget construction
+        # Prefer signal if both are provided
+        if signal_value is not None:
+            self._config_delegate_set('signal', signal_value)
+        elif variable_value is not None:
+            self._config_delegate_set('variable', variable_value)
+
+    @configure_delegate("variable", "signal")
+    def _delegate_signal(self, value: Any = None):
+        """Handle variable and signal configuration.
+
+        Args:
+            value: Signal, tk.Variable, or None for query.
+
+        Returns:
+            Current value for query path, None for set path.
+        """
+        # Query path - return stored value
+        if value is None:
+            return query_binding(
+                getattr(self, '_signal', None),
+                getattr(self, '_variable', None),
+                self._ttk_base,  # type: ignore[misc]
+                self,
+                'variable',
+            )
+
+        # Set path - normalize and apply
+        binding = normalize_signal(value)
+        if binding is not None:
+            self._signal = binding.signal
+            self._variable = binding.variable
+            var_to_set = binding.tk_value
+        else:
+            # String (Tcl variable name) or other - pass through
+            var_to_set = value
+            if value:
+                self._variable = value
+
+        # Apply via base ttk widget to avoid recursion
+        return self._ttk_base.configure(self, variable=var_to_set)  # type: ignore[misc]
+
+    @property
+    def signal(self) -> 'Signal[Any]':
+        """Get or lazily create the signal.
+
+        If no variable has been set, creates a new Signal with appropriate default
+        (False for Checkbutton, 0 for Scale, etc.). If variable exists, wraps it in a Signal.
+
+        Returns:
+            The reactive Signal for this widget's value.
+        """
+        if not hasattr(self, '_signal'):
+            # Infer default value based on widget type
+            default_value = infer_default_value_for_widget(self.winfo_class())
+            binding = create_signal(default_value)
+            self._signal = binding.signal
+            self._variable = binding.variable
+            try:
+                self._ttk_base.configure(self, variable=binding.tk_value)  # type: ignore[misc]
+            except Exception:
+                pass
+        return self._signal
+
+    @signal.setter
+    def signal(self, value: 'Signal[Any]') -> None:
+        """Set the signal, extracting and configuring its underlying variable.
+
+        Args:
+            value: Signal to use for this widget's value.
+        """
+        self._delegate_signal(value)
+
+    @property
+    def variable(self) -> tk.Variable:
+        """Get the underlying tk.Variable.
+
+        If not yet created, accessing this property will trigger lazy creation
+        via the signal property.
+
+        Returns:
+            The tk.Variable (IntVar, BooleanVar, DoubleVar, etc.) for this widget's value.
+        """
+        if not hasattr(self, '_variable'):
+            # Trigger lazy creation via signal
+            _ = self.signal
+        return self._variable
+
+    @variable.setter
+    def variable(self, value: tk.Variable) -> None:
+        """Set the variable, creating a synced Signal automatically.
+
+        Args:
+            value: tk.Variable to use for this widget's value.
+        """
+        self._delegate_signal(value)
+
+
+__all__ = ["TextSignalMixin", "SignalMixin"]

bootstack/widgets/mixins/validation_mixin.py

@@ -0,0 +1,204 @@
+"""Validation mixin for widgets with enhanced event system.
+
+This mixin provides validation functionality using the enhanced event system
+that allows passing data directly through virtual events.
+"""
+
+from __future__ import annotations
+
+from tkinter import TclError
+from tkinter.ttk import Widget
+from typing import Any, Callable, Optional
+
+from bootstack.core.validation import ValidationRule
+from bootstack.core.validation.types import RuleTriggerType, RuleType, ValidationOptions
+
+
+class ValidationMixin(Widget):
+    """Pure-Tkinter validation mixin for bound widgets.
+
+    Provides debounced auto-validation on key/blur with virtual event emission.
+    Event data is accessible via `event.data` in handlers.
+
+    !!! note "Events"
+
+        - `<<Valid>>`: Fired when validation passes.
+          Provides `event.data` with keys: `value`, `is_valid` (True), `message`.
+
+        - `<<Invalid>>`: Fired when validation fails.
+          Provides `event.data` with keys: `value`, `is_valid` (False), `message`.
+
+        - `<<Validate>>`: Fired after any validation.
+          Provides `event.data` with keys: `value`, `is_valid` (bool), `message`.
+    """
+
+    EVENT_VALID = '<<Valid>>'
+    EVENT_INVALID = '<<Invalid>>'
+    EVENT_VALIDATED = '<<Validate>>'
+    SEQ_KEYUP = '<KeyRelease>'
+    SEQ_BLUR = '<FocusOut>'
+
+    def __init__(self, *args, **kwargs):
+        """Initialize validation mixin."""
+        # Validation rules
+        self._rules: list[ValidationRule] = []
+
+        # Debounce tracking
+        self._debounce_ids: dict[str, str] = {}
+
+        # Optional convenience callbacks
+        self._on_invalid_command: Optional[Callable[[dict[str, Any]], None]] = None
+        self._on_valid_command: Optional[Callable[[dict[str, Any]], None]] = None
+        self._on_validated_command: Optional[Callable[[dict[str, Any]], None]] = None
+
+        super().__init__(*args, **kwargs)  # next in MRO must be a Tk/ttk widget
+        self._setup_validation_binds()
+
+    # ---------------- Public API ----------------
+
+    def value(self) -> Any:
+        """Default value accessor; override for non-Entry widgets.
+
+        Returns:
+            Current widget value
+        """
+        if hasattr(self, 'get'):
+            try:
+                return self.get()
+            except AttributeError:
+                return None
+        return None
+
+    def add_validation_rule(self, rule_type: RuleType, **kwargs: ValidationOptions) -> None:
+        """Add a single validation rule.
+
+        Args:
+            rule_type: Type of validation rule (e.g., 'required', 'min_length')
+            **kwargs: Rule-specific options (e.g., min_length=5, message='...')
+        """
+        self._rules.append(ValidationRule(rule_type, **kwargs))
+
+    def add_validation_rules(self, rules: list[ValidationRule]) -> None:
+        """Replace all validation rules.
+
+        Args:
+            rules: List of ValidationRule objects
+        """
+        self._rules = list(rules)
+
+    def validate(self, value: Any, trigger: RuleTriggerType = "manual") -> bool:
+        """Run validation rules against a value.
+
+        Emits `<<Valid>>`, `<<Invalid>>`, and `<<Validate>>` events
+        with data payload containing validation results.
+
+        Args:
+            value: Value to validate
+            trigger: Trigger type ('manual', 'key', 'blur', or 'always')
+
+        Returns:
+            True if validation was performed (regardless of result)
+        """
+        ran_rule = False
+        payload: dict[str, Any] = {"value": value, "is_valid": True, "message": ""}
+
+        for rule in self._rules:
+            if trigger != "manual" and rule.trigger not in ("always", trigger):
+                continue
+
+            ran_rule = True
+            result = rule.validate(value)
+            payload.update(is_valid=result.is_valid, message=result.message)
+
+            if not result.is_valid:
+                # Emit invalid and validated events with data
+                self.event_generate(self.EVENT_INVALID, data=payload)
+                self.event_generate(self.EVENT_VALIDATED, data=payload)
+                return False
+
+        if ran_rule:
+            # Emit valid and validated events with data
+            self.event_generate(self.EVENT_VALID, data=payload)
+            self.event_generate(self.EVENT_VALIDATED, data=payload)
+
+        return ran_rule
+
+    # Optional: ergonomic callback registration
+    def on_invalid(self, func: Callable[[dict[str, Any]], None]) -> None:
+        """Register callback for invalid validation."""
+        self._on_invalid_command = func
+
+    def off_invalid(self, bind_id: str | None = None):
+        """Remove the callback for the <<Invalid>> event"""
+        self.unbind('<<Invalid>>', bind_id)
+
+    def on_valid(self, func: Callable[[dict[str, Any]], None]) -> None:
+        """Register callback for valid validation."""
+        self._on_valid_command = func
+
+    def off_valid(self, bind_id: str | None = None):
+        """Remove the callback for the <<Valid>> event"""
+        self.unbind('<<Valid>>', bind_id)
+
+    def on_validated(self, func: Callable[[dict[str, Any]], None]) -> None:
+        """Register callback for any validation (valid or invalid)."""
+        self._on_validated_command = func
+
+    def off_validated(self, bind_id: str | None = None):
+        """Remove the callback for validated event"""
+        self.unbind('<<Validate>>', bind_id)
+
+    # ---------------- Internals ----------------
+
+    def _get_validation_value(self) -> Any:
+        """Get the current value for validation purposes.
+
+        For entry widgets, this should return the current text being typed,
+        not the committed value. Prefers get() method over value() method.
+        """
+        if hasattr(self, 'get'):
+            try:
+                return self.get()
+            except (AttributeError, TclError):
+                pass
+        return self.value()
+
+    def _setup_validation_binds(self, keyup_delay_ms: int = 50, blur_delay_ms: int = 50) -> None:
+        """Set up automatic validation bindings with debouncing."""
+        # Auto-validate (debounced)
+        self.bind(self.SEQ_KEYUP, lambda e: self._debounced("key", keyup_delay_ms), add=True)
+        self.bind(self.SEQ_BLUR, lambda e: self._debounced("blur", blur_delay_ms), add=True)
+
+        # Wire optional convenience callbacks
+        self.bind(self.EVENT_VALIDATED, self._dispatch_validated, add=True)
+        self.bind(self.EVENT_VALID, self._dispatch_valid, add=True)
+        self.bind(self.EVENT_INVALID, self._dispatch_invalid, add=True)
+
+    def _debounced(self, trigger: RuleTriggerType, ms: int) -> None:
+        """Debounce validation to avoid excessive checks during typing."""
+        key = f"debounce:{trigger}"
+        aid: Optional[str] = self._debounce_ids.get(key)
+        if aid:
+            try:
+                self.after_cancel(aid)
+            except TclError:
+                pass
+        # defer reading value until the timer fires
+        self._debounce_ids[key] = self.after(ms, lambda: self.validate(self._get_validation_value(), trigger))
+
+    # ----- optional dispatchers for on_* convenience -----
+
+    def _dispatch_validated(self, event) -> None:
+        """Dispatch validated event to registered callback."""
+        if self._on_validated_command:
+            self._on_validated_command(event.data)
+
+    def _dispatch_valid(self, event) -> None:
+        """Dispatch valid event to registered callback."""
+        if self._on_valid_command:
+            self._on_valid_command(event.data)
+
+    def _dispatch_invalid(self, event) -> None:
+        """Dispatch invalid event to registered callback."""
+        if self._on_invalid_command:
+            self._on_invalid_command(event.data)

bootstack/widgets/parts/__init__.py

@@ -0,0 +1,11 @@
+"""Widget parts module for composite widgets."""
+
+from bootstack.widgets.parts.textentry_part import TextEntryPart
+from bootstack.widgets.parts.numberentry_part import NumberEntryPart
+from bootstack.widgets.parts.spinnerentry_part import SpinnerEntryPart
+
+__all__ = [
+    'TextEntryPart',
+    'NumberEntryPart',
+    'SpinnerEntryPart',
+]