bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_core/field_mixin.py

@@ -0,0 +1,353 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Literal, TYPE_CHECKING
+
+from bootstack.errors import BootstackError
+from bootstack.validation import RuleType
+from bootstack.validation.validation_rules import rule_applies_to_kind
+from bootstack.widgets.types import AccentToken
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class FieldAddonMixin:
+    """Mixin that exposes `insert_addon` and `addons` on public field wrappers.
+
+    Requires the inheriting class to have `self._internal` pointing to a
+    `Field`-based composite that implements `insert_addon` / `addons`.
+    """
+
+    #: The kind of value this field holds, used to reject inapplicable
+    #: validation rules at attach time. Text fields keep the default; typed
+    #: field wrappers override it (`'number'`, `'date'`, `'time'`).
+    _VALIDATION_KIND: str = "text"
+
+    _ADDON_TYPES = {
+        "button":  "bootstack.widgets._impl.primitives.button::Button",
+        "label":   "bootstack.widgets._impl.primitives.label::Label",
+        "toggle":  "bootstack.widgets._impl.primitives.checktoggle::CheckToggle",
+    }
+
+    def insert_addon(
+        self,
+        widget: Literal["button", "label", "toggle"],
+        position: Literal["before", "after"],
+        *,
+        name: str | None = None,
+        text: str | None = None,
+        icon: str | None = None,
+        accent: AccentToken | str | None = None,
+        on_click: Callable[[], Any] | None = None,
+        signal: "Signal | None" = None,
+        active_when_readonly: bool = False,
+    ) -> Any:
+        """Insert a small widget inside the field border, before or after the input.
+
+        Use this for affordances such as a clear button, a search icon, a unit
+        suffix label, or an on/off toggle.
+
+        Args:
+            widget: Addon type — `'button'` (clickable), `'label'` (static
+                text or icon), or `'toggle'` (on/off control).
+            position: `'before'` (left of the input) or `'after'` (right).
+            name: Key to retrieve the addon later via `addons`. Auto-generated
+                if omitted.
+            text: Text shown on the addon. Applies to any addon type.
+            icon: Bootstrap Icons name shown on the addon (e.g. `'search'`,
+                `'x-lg'`). An icon-only addon is rendered when `icon` is given
+                without `text`.
+            accent: Accent token for the addon. Prefer an accent for a
+                text-only button.
+            on_click: Called with no arguments when a `'button'` or `'toggle'`
+                addon is activated.
+            signal: Reactive `Signal[bool]` bound to a `'toggle'` addon's
+                on/off state.
+            active_when_readonly: Keep the addon interactive while the field is
+                read-only. Off by default, so addons follow the field's
+                read-only state — appropriate since most act on the value (a
+                clear button, the spin buttons). Set `True` only for a
+                read-only-safe action such as a copy or reveal button; it still
+                dims when the field is fully disabled.
+
+        Returns:
+            The created addon widget instance.
+        """
+        if widget not in self._ADDON_TYPES:
+            raise ValueError(f"widget must be 'button', 'label', or 'toggle'; got {widget!r}")
+        if on_click is not None and widget == "label":
+            raise ValueError("on_click is not valid for a 'label' addon")
+        if signal is not None and widget != "toggle":
+            raise ValueError("signal is only valid for a 'toggle' addon")
+
+        module_path, cls_name = self._ADDON_TYPES[widget].split("::")
+        import importlib
+        cls = getattr(importlib.import_module(module_path), cls_name)
+
+        if name is None:
+            seq = getattr(self, "_addon_seq", 0)
+            self._addon_seq = seq + 1
+            name = f"addon_{seq}"
+
+        addon_kwargs: dict[str, Any] = {}
+        if text is not None:
+            addon_kwargs["text"] = text
+        if icon is not None:
+            addon_kwargs["icon"] = icon
+        if on_click is not None:
+            addon_kwargs["command"] = on_click
+        if signal is not None:
+            addon_kwargs["signal"] = signal
+
+        return self._internal.insert_addon(
+            cls, position, name=name, accent=accent,
+            active_when_readonly=active_when_readonly, **addon_kwargs,
+        )
+
+    def update_addon(
+        self,
+        name: str,
+        *,
+        text: str | None = None,
+        icon: str | None = None,
+        accent: AccentToken | str | None = None,
+        on_click: Callable[[], Any] | None = None,
+    ) -> None:
+        """Reconfigure an existing addon in place.
+
+        Only the options you pass are changed. Use this, for example, to flip a
+        toggle addon's label between two units, or swap a button's icon.
+
+        Args:
+            name: The addon's name (as passed to `insert_addon`).
+            text: New text for the addon.
+            icon: New Bootstrap Icons name for the addon.
+            accent: New accent token for the addon.
+            on_click: New click handler for a `'button'` or `'toggle'` addon.
+
+        Raises:
+            KeyError: If no addon with that name exists.
+        """
+        try:
+            addon = self._internal.addons[name]
+        except KeyError:
+            raise KeyError(f"no addon named {name!r}") from None
+        config: dict[str, Any] = {}
+        if text is not None:
+            config["text"] = text
+        if icon is not None:
+            config["icon"] = icon
+        if accent is not None:
+            config["accent"] = accent
+        if on_click is not None:
+            config["command"] = on_click
+        if config:
+            addon.configure(**config)
+
+    def remove_addon(self, name: str) -> None:
+        """Remove an addon inserted with `insert_addon()`.
+
+        Args:
+            name: The addon's name (as passed to `insert_addon`).
+
+        Raises:
+            KeyError: If no addon with that name exists.
+        """
+        self._internal.remove_addon(name)
+
+    @property
+    def addons(self) -> dict[str, Any]:
+        """Named addon widgets inserted via `insert_addon()`."""
+        return self._internal.addons
+
+    @property
+    def text(self) -> str:
+        """The current display text shown in the field.
+
+        This is the formatted string the user sees, as opposed to `value`, which
+        is the raw parsed datum (e.g. for a `DateField`, `text` is `'Jan 2, 2024'`
+        while `value` is a `date`). Read-only — assign to `value` to change it.
+        """
+        return self._internal.get()
+
+    @property
+    def valid(self) -> "Signal":
+        """Reactive `Signal[bool]` — whether the field currently passes validation.
+
+        Call it to read the current state (`field.valid()`), `subscribe` to
+        react, or bind it. Updated on every validation run — a blur, a keystroke
+        (for key-triggered rules), or a manual `validate()`.
+        """
+        return self._internal._entry._valid_signal
+
+    @property
+    def error(self) -> "Signal":
+        """Reactive `Signal[str]` — the current validation error, `''` when valid.
+
+        Bind it to surface the message anywhere, for example
+        `bs.Label(textsignal=field.error)`.
+        """
+        return self._internal._entry._error_signal
+
+    def add_validation_rule(self, rule_type: RuleType, **kwargs: Any) -> None:
+        """Add a validation rule to the field.
+
+        Rules run automatically on blur or key events depending on the rule
+        type, or manually via `validate()`. Multiple rules can be added;
+        they are evaluated in order and stop at the first failure.
+
+        Rules validate the field's **typed value** — a `custom` rule on a
+        numeric field receives a number, on a date field a `date`. Text rules
+        (`stringLength`, `pattern`, `email`) apply only to text fields; `range`
+        applies only to numeric/date/time fields. Attaching a rule to a field
+        whose value kind it cannot validate raises `BootstackError`.
+
+        Args:
+            rule_type: The kind of validation rule to apply.
+            **kwargs: Rule-specific options:
+
+                - `message` *(all rules)* — override the default error message.
+                - `trigger` *(all rules)* — when to run: `'always'` (key and
+                  blur), `'key'`, `'blur'`, or `'manual'`. Each rule type
+                  has its own sensible default (see the Validation reference).
+                - `min`, `max` *(stringLength)* — minimum/maximum character count.
+                - `min`, `max` *(range)* — lower/upper bound for the typed value
+                  (numbers, or `date`/`time` objects).
+                - `pattern` *(pattern)* — regex string the value must match.
+                - `other_field` *(compare)* — field whose value must match.
+                - `func` *(custom)* — callable `(value) -> bool` receiving the
+                  field's typed value.
+
+        Example::
+
+            field.add_validation_rule("required")
+            field.add_validation_rule("stringLength", min=3, max=50)
+            field.add_validation_rule("email", message="Enter a valid email.")
+            field.add_validation_rule("custom", func=lambda v: v.isdigit())
+
+            age.add_validation_rule("range", min=18, message="Must be 18+.")
+        """
+        if not isinstance(rule_type, str):
+            raise TypeError(
+                f"add_validation_rule() takes a rule-type string (e.g. "
+                f"'stringLength'), not a {type(rule_type).__name__} object. Pass "
+                f"the rule's options as keyword arguments: "
+                f"field.add_validation_rule('stringLength', min=3)."
+            )
+        kind = self._VALIDATION_KIND
+        if not rule_applies_to_kind(rule_type, kind):
+            if kind == "text":
+                hint = "'stringLength' bounds text length."
+            else:
+                hint = f"'range' or 'custom' validates {kind} values."
+            raise BootstackError(
+                f"the {rule_type!r} rule does not apply to a {kind} field "
+                f"({type(self).__name__}). {hint}"
+            )
+        self._internal.add_validation_rule(rule_type, **kwargs)
+
+
+class ValueSignalMixin:
+    """Two-way binds a field's typed `.value` to a public `signal`.
+
+    The signal carries the field's **value** (a number, date, time, …) — not its
+    text. The inheriting wrapper must expose a `value` property (get and set) and
+    an `on_change` event; this mixin keeps the two in sync, seeding the field from
+    the signal and updating the signal when the field commits a new value.
+    """
+
+    value: Any
+    on_change: Callable
+
+    def _bind_value_signal(self, signal: "Signal") -> None:
+        """Establish the two-way binding between `self.value` and `signal`."""
+        self._value_signal = signal
+        self._value_syncing = False
+
+        current = signal()
+        if current is not None:
+            self.value = current
+        else:
+            self._push_to_signal(self.value)
+
+        def _from_signal(v: Any) -> None:
+            if self._value_syncing or v is None:
+                return
+            self._value_syncing = True
+            try:
+                self.value = v
+            finally:
+                self._value_syncing = False
+
+        def _to_signal(_event: Any) -> None:
+            if self._value_syncing:
+                return
+            v = self.value
+            if v is None:
+                return
+            self._value_syncing = True
+            try:
+                self._push_to_signal(v)
+            finally:
+                self._value_syncing = False
+
+        # Hold the subscription id so it can be released on destroy. A Signal
+        # usually outlives the widgets bound to it, so a dangling subscription
+        # would pin a destroyed field (and all it references) in memory.
+        self._value_sub = signal.subscribe(_from_signal)
+        self.on_change(_to_signal)
+        self.on_destroy(lambda _e: self._release_value_signal())
+
+    def _sync_value_set(self, value: Any) -> None:
+        """Push a programmatic `field.value = …` to the bound signal.
+
+        The `on_change`-driven sync only fires on a user commit, so a
+        programmatic value set would otherwise leave the signal stale. Call this
+        from the wrapper's `value` setter. A no-op when no signal is bound, while
+        a signal↔field sync is in flight, or for an empty value.
+        """
+        if getattr(self, "_value_signal", None) is None:
+            return
+        if getattr(self, "_value_syncing", False) or value is None:
+            return
+        self._value_syncing = True
+        try:
+            self._push_to_signal(self.value)
+        finally:
+            self._value_syncing = False
+
+    def _push_to_signal(self, value: Any) -> None:
+        """Write `value` to the bound signal, reconciling numeric types.
+
+        `Signal` is strict about value type (it only widens `int` into a
+        `float`-typed signal). A numeric field can produce either an `int` or a
+        `float`, so reconcile the two here. If the signal's type is genuinely
+        incompatible (for example an `int`-typed signal and a fractional value),
+        leave the signal unchanged rather than raising into the Tk event loop.
+        """
+        signal = self._value_signal
+        target = getattr(signal, "_type", None)
+        if target is not None and type(value) is not target:
+            if target is float and type(value) is int:
+                value = float(value)
+            elif target is int and type(value) is float and value.is_integer():
+                value = int(value)
+        try:
+            signal.set(value)
+        except TypeError:
+            pass
+
+    def _release_value_signal(self) -> None:
+        """Drop the value-signal subscription (called on widget destroy)."""
+        sub = getattr(self, "_value_sub", None)
+        if sub is not None:
+            try:
+                sub.cancel()
+            except Exception:
+                pass
+            self._value_sub = None
+
+    @property
+    def signal(self) -> "Signal | None":
+        """The reactive `Signal` bound to this field's value, or `None`."""
+        return getattr(self, "_value_signal", None)

bootstack/widgets/_core/icon_image_props.py

@@ -0,0 +1,72 @@
+"""Reusable `icon` / `image` property mixins for widgets that accept them.
+
+Widgets in the button family take a widget-level `icon=` (a Bootstrap icon name)
+and/or `image=` (an `Image` handle) at construction. These mixins expose those as
+live, settable properties so they can be changed after construction — `image`
+updates in place (no rebuild, no flicker).
+"""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bootstack.widgets.types import IconSpec
+
+
+class IconProperty:
+    """Adds a live `icon` property to a widget whose internal accepts `icon=`."""
+
+    @property
+    def icon(self) -> "str | IconSpec | None":
+        """The icon shown on the widget, or `None` if none is set.
+
+        A Bootstrap Icons name, or an `IconSpec` mapping (`{'name', 'size',
+        'color'}`) for control over size and color.
+        """
+        return self._internal.configure_style_options("icon")
+
+    @icon.setter
+    def icon(self, value: "str | IconSpec | None") -> None:
+        self._internal.configure(icon=value)
+
+
+class ImageProperty:
+    """Adds a live `image` property to a widget whose internal accepts `image=`."""
+
+    @property
+    def image(self) -> Any:
+        """The displayed image handle, or `None`.
+
+        Assigning an `Image` (from `bootstack.images`) updates the picture in
+        place — no rebuild — which avoids the flicker of recreating the widget.
+        """
+        return getattr(self, "_image_handle", None)
+
+    @image.setter
+    def image(self, value: Any) -> None:
+        from bootstack.widgets._core.image_binding import (
+            _release_theme_binding,
+            bind_image,
+        )
+
+        if value is None:
+            # Drop any theme-following binding from a previous Image, otherwise it
+            # keeps re-applying a now-removed image on theme changes (and pins it).
+            _release_theme_binding(self)
+            self._internal.configure(image="")
+            self._image_handle = None
+            self._image_photo = None
+            return
+        from bootstack.images import Image as _ImageHandle
+
+        if isinstance(value, _ImageHandle):
+            bind_image(self, self._internal, value)
+        else:
+            _release_theme_binding(self)
+            self._internal.configure(image=value)
+            self._image_handle = None
+            self._image_photo = value
+
+
+__all__ = ["IconProperty", "ImageProperty"]

bootstack/widgets/_core/image_binding.py

@@ -0,0 +1,93 @@
+"""Bind a public image handle onto an internal widget.
+
+The `image=` slot on text widgets accepts a public `bootstack.images.Image`
+handle. Because a handle holds no display resource until it is used, this helper
+renders it against the target widget and, when the handle follows the theme (a
+token-colored icon), re-renders it whenever the theme changes — releasing the
+binding when the widget is destroyed.
+"""
+
+from __future__ import annotations
+
+import tkinter as tk
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bootstack.images import Image
+
+
+def bind_image(public_widget, internal_widget, image: "Image") -> None:
+    """Render `image` onto `internal_widget`, following the theme if needed.
+
+    Args:
+        public_widget: The public wrapper; strong references to the handle and
+            its rendered image are stored on it so they are not collected.
+        internal_widget: The underlying widget to display the image on.
+        image: The image handle to render and bind.
+    """
+    # Calling this again on the same widget (a live `image=` update) must not
+    # stack theme bindings — release any prior one first.
+    _release_theme_binding(public_widget)
+
+    photo = image._materialize(internal_widget)
+    internal_widget.configure(image=photo)
+    public_widget._image_handle = image
+    public_widget._image_photo = photo
+
+    if not image._is_theme_following:
+        return
+
+    root = internal_widget.winfo_toplevel()
+
+    def _reapply(_event=None) -> None:
+        try:
+            image._invalidate()
+            new_photo = image._materialize(internal_widget)
+            internal_widget.configure(image=new_photo)
+            public_widget._image_photo = new_photo
+        except tk.TclError:
+            pass
+
+    bind_id = root.bind("<<BsThemeChanged>>", _reapply, add="+")
+    public_widget._image_theme_binding = (root, bind_id)
+
+    def _release(event) -> None:
+        if event.widget is not internal_widget:
+            return
+        _release_theme_binding(public_widget)
+
+    internal_widget.bind("<Destroy>", _release, add="+")
+
+
+def _release_theme_binding(public_widget) -> None:
+    """Unbind a previously installed `<<BsThemeChanged>>` handler, if any."""
+    prev = getattr(public_widget, "_image_theme_binding", None)
+    if prev is None:
+        return
+    root, bind_id = prev
+    try:
+        root.unbind("<<BsThemeChanged>>", bind_id)
+    except tk.TclError:
+        pass
+    public_widget._image_theme_binding = None
+
+
+def resolve_window_icon(icon):
+    """Normalize a window `icon=` argument to `(path, deferred_image)`.
+
+    Exactly one of the returned values is non-`None` (or both are, for `None`
+    input). A `path` can be handed to the window at construction; a deferred
+    image must be rendered and applied after the window's root exists.
+
+    Args:
+        icon: An icon file path, an `Image` handle, or an `AppIcon`.
+    """
+    if icon is None:
+        return None, None
+    from bootstack.images import AppIcon, Image
+
+    if isinstance(icon, AppIcon):
+        return icon._icon_path(), None
+    if isinstance(icon, Image):
+        return None, icon
+    return str(icon), None