bootstack 0.1.5__tar.gz → 0.1.7__tar.gz

{bootstack-0.1.5/src/bootstack.egg-info → bootstack-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bootstack
-Version: 0.1.5
+Version: 0.1.7
 Summary: Build desktop GUI apps in pure Python and ship them as a standalone executable — built on Tk, no Tkinter boilerplate.
 Author-email: Israel Dryer <israel.dryer@gmail.com>
 License-Expression: MIT
@@ -66,10 +66,9 @@ Dynamic: license-file
 
 ### Desktop apps in pure Python — Tk underneath, none of the boilerplate.
 
-bootstack is built on Tk, so the install is light, there's no Qt license, and
-your app ships as a small standalone executable. But you'll never write a
-`StringVar` or call `.pack()` — the API is its own. 60+ widgets, reactive state,
-and a CLI that scaffolds and packages the whole thing.
+bootstack is built on Tk, so the install is light and your app ships as a small standalone executable. But you'll never
+write a `StringVar` or call `.pack()` — the API is its own. 60+ widgets, reactive state, and a CLI that scaffolds and
+packages the whole thing.
 
 <p align="center">
 <picture>

{bootstack-0.1.5 → bootstack-0.1.7}/README.md

@@ -13,10 +13,9 @@
 
 ### Desktop apps in pure Python — Tk underneath, none of the boilerplate.
 
-bootstack is built on Tk, so the install is light, there's no Qt license, and
-your app ships as a small standalone executable. But you'll never write a
-`StringVar` or call `.pack()` — the API is its own. 60+ widgets, reactive state,
-and a CLI that scaffolds and packages the whole thing.
+bootstack is built on Tk, so the install is light and your app ships as a small standalone executable. But you'll never
+write a `StringVar` or call `.pack()` — the API is its own. 60+ widgets, reactive state, and a CLI that scaffolds and
+packages the whole thing.
 
 <p align="center">
 <picture>

{bootstack-0.1.5 → bootstack-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bootstack"
-version = "0.1.5"
+version = "0.1.7"
 description = "Build desktop GUI apps in pure Python and ship them as a standalone executable — built on Tk, no Tkinter boilerplate."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -114,7 +114,7 @@ where = ["src"]
 ]
 
 [tool.bumpversion]
-current_version = "0.1.5"
+current_version = "0.1.7"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)((?P<pre>a|b|rc)(?P<pre_n>\\d+))?"
 serialize = [
     "{major}.{minor}.{patch}{pre}{pre_n}",

bootstack-0.1.7/src/bootstack/_runtime/wheel.py

@@ -0,0 +1,152 @@
+"""Scroll-gesture normalization across Tk 8.6 and Tk 9.
+
+Tk 9 changed the scroll-event contract in two ways that break code written
+against Tk 8.6:
+
+* A precise-delta device — every Apple trackpad, Magic Mouse and Magic
+  Trackpad — now fires `<TouchpadScroll>` and **never** `<MouseWheel>`.
+  Binding only `<MouseWheel>` leaves those devices completely dead.
+* Wheel deltas are normalized to multiples of 120 on every windowing
+  system. On Aqua a notch used to report 1; it now reports 120.
+
+On X11, `<Button-4>`/`<Button-5>` are no longer delivered to scripts at
+all — Tk translates them to `<MouseWheel>` internally.
+
+This module hides all of that behind one vocabulary. Callers ask for the
+sequences to bind, then convert an incoming event to either wheel
+*notches* or precise *pixels*.
+
+Sign convention (matching Tk's own bindings): a positive value means the
+wheel rolled away from the user, i.e. the view should move toward the
+*start* of the content. Callers therefore negate to get a scroll amount.
+"""
+
+from __future__ import annotations
+
+import tkinter as tk
+
+TOUCHPAD_SCROLL = "<TouchpadScroll>"
+"""Sequence for precise-delta scroll gestures. Tk 8.7+ only."""
+
+_WHEEL_UNITS = 120.0
+"""Delta reported for one wheel notch on a normalized (Tk 8.7+) build."""
+
+_TOUCHPAD_TK = 8.7
+"""First Tk release generating `<TouchpadScroll>` and normalized deltas."""
+
+
+def _windowingsystem(widget: tk.Misc) -> str:
+    try:
+        return str(widget.tk.call("tk", "windowingsystem")).lower()
+    except Exception:
+        return ""
+
+
+def has_touchpad_scroll() -> bool:
+    """Whether the running Tk generates `<TouchpadScroll>` events."""
+    return tk.TkVersion >= _TOUCHPAD_TK
+
+
+def uses_x11_buttons(widget: tk.Misc) -> bool:
+    """Whether wheel input arrives as `<Button-4>`/`<Button-5>` here.
+
+    True only on legacy X11 builds. Tk 8.7+ translates those buttons to
+    `<MouseWheel>` and stops delivering them to scripts.
+    """
+    return not has_touchpad_scroll() and _windowingsystem(widget) == "x11"
+
+
+def wheel_sequences(widget: tk.Misc, *, shift: bool = False) -> tuple[str, ...]:
+    """Event sequences carrying wheel notches for `widget`.
+
+    Args:
+        widget: Any widget; used to resolve the windowing system.
+        shift: Request the horizontal (Shift-modified) sequences.
+    """
+    if uses_x11_buttons(widget):
+        if shift:
+            return ("<Shift-Button-4>", "<Shift-Button-5>")
+        return ("<Button-4>", "<Button-5>")
+    return ("<Shift-MouseWheel>",) if shift else ("<MouseWheel>",)
+
+
+def wheel_notches(widget: tk.Misc, event: tk.Event) -> float:
+    """Signed notch count for a wheel event.
+
+    Returns a positive value when the wheel rolled away from the user.
+    One physical notch is 1.0 on every platform and Tk version.
+    """
+    num = getattr(event, "num", None)
+    if num in (4, 6):
+        return 1.0
+    if num in (5, 7):
+        return -1.0
+
+    try:
+        delta = float(event.delta)
+    except (AttributeError, TypeError, ValueError):
+        return 0.0
+    if not delta:
+        return 0.0
+
+    # Tk 8.6 on Aqua reported one notch as 1; everything else uses 120.
+    if not has_touchpad_scroll() and _windowingsystem(widget) == "aqua":
+        return delta
+    return delta / _WHEEL_UNITS
+
+
+def precise_deltas(event: tk.Event) -> tuple[int, int]:
+    """Unpack a `<TouchpadScroll>` event into `(dx, dy)` pixels.
+
+    Tk packs both axes into the delta field as two signed 16-bit values.
+    This mirrors Tcl's `::tk::PreciseScrollDeltas`.
+    """
+    try:
+        packed = int(event.delta)
+    except (AttributeError, TypeError, ValueError):
+        return (0, 0)
+    dx = packed >> 16
+    low = packed & 0xFFFF
+    dy = low if low < 0x8000 else low - 0x10000
+    return (dx, dy)
+
+
+def scale_num(widget: tk.Misc, value: float) -> int:
+    """Scale a pixel amount for display density, like `::tk::ScaleNum`."""
+    try:
+        scaling = float(widget.tk.call("tk", "scaling"))
+    except Exception:
+        scaling = 1.0
+    return round(value * scaling * 0.75)
+
+
+class PixelAccumulator:
+    """Converts precise pixel deltas into whole discrete scroll steps.
+
+    A touchpad reports small deltas roughly sixty times a second. Widgets
+    that scroll by rows or canvas units cannot act on each one, so the
+    fractional remainder is carried forward until it adds up to a step.
+    """
+
+    __slots__ = ("_x", "_y")
+
+    def __init__(self) -> None:
+        self._x = 0.0
+        self._y = 0.0
+
+    def add(self, dx: float, dy: float, step_x: float, step_y: float) -> tuple[int, int]:
+        """Add a delta and return the whole `(x, y)` steps it completes."""
+        step_x = step_x if step_x and step_x > 0 else 1.0
+        step_y = step_y if step_y and step_y > 0 else 1.0
+        self._x += dx
+        self._y += dy
+        out_x = int(self._x / step_x)
+        out_y = int(self._y / step_y)
+        self._x -= out_x * step_x
+        self._y -= out_y * step_y
+        return (out_x, out_y)
+
+    def reset(self) -> None:
+        """Drop any carried remainder."""
+        self._x = 0.0
+        self._y = 0.0

{bootstack-0.1.5 → bootstack-0.1.7}/src/bootstack/i18n/intl_format.py

@@ -12,6 +12,7 @@ import locale
 import re
 import warnings
 from dataclasses import dataclass
+from decimal import Decimal
 from datetime import date, datetime, time
 from typing import Any, Literal, Mapping, Optional, TypedDict, Union, cast
 
@@ -148,7 +149,10 @@ SUFFIXES_EN = (
     Suffix(1_000, "K"),
 )
 _SUFFIX_TO_FACTOR = {"K": 1_000, "M": 1_000_000, "B": 1_000_000_000, "T": 1_000_000_000_000}
-_NUMBERISH = (int, float)
+# Values formatted as numbers. `Decimal` is passed to Babel as-is rather than
+# coerced: Babel formats it natively, and going through `float` would round
+# away the precision a caller chose `Decimal` to keep.
+_NUMBERISH = (int, float, Decimal)
 
 
 def _locale_to_languages(loc: str) -> list[str]:
@@ -208,7 +212,7 @@ class IntlFormatter:
         if value is None:
             return ""
         if isinstance(value, _NUMBERISH):
-            return self._format_number(float(value), spec)
+            return self._format_number(value if isinstance(value, Decimal) else float(value), spec)
         if isinstance(value, datetime):
             return self._format_datetime(value, spec)
         if isinstance(value, date):
@@ -238,7 +242,7 @@ class IntlFormatter:
         return self._parse_temporal(s, spec)
 
     # ---------- Numbers ----------
-    def _format_number(self, x: float, spec: LooseSpec) -> str:
+    def _format_number(self, x: float | Decimal, spec: LooseSpec) -> str:
         opt = self._normalize_number_spec(spec)
 
         if opt["type"] == "custom":

{bootstack-0.1.5 → bootstack-0.1.7}/src/bootstack/validation/validation_rules.py

@@ -33,6 +33,16 @@ def rule_applies_to_kind(rule_type: str, kind: str) -> bool:
     return True
 
 
+def _is_empty(value: object) -> bool:
+    """Whether a field holds nothing, for rules that only shape a value.
+
+    Matches the emptiness test `range` uses: `None` or the empty string. A
+    whitespace-only entry is real input — `stringLength` should still measure
+    it — so only `required` treats blank text as absent.
+    """
+    return value is None or value == ""
+
+
 def _as_text(value: object) -> str:
     """Coerce a value to text for the string rules.
 
@@ -104,7 +114,15 @@ class ValidationRule:
             # Everything else is valid (non-empty string, number, date, etc.)
             return ValidationResult(True, "")
 
-        elif self.type == "email":
+        # A rule other than `required` describes what a value must look like,
+        # not that one must be present. An untouched optional field has nothing
+        # to check, so it passes — otherwise leaving it blank would block a
+        # submit with no way forward. Use `required` for presence, the same
+        # contract `range` states below.
+        if self.type in TEXT_RULES and _is_empty(value):
+            return ValidationResult(True, "")
+
+        if self.type == "email":
             if not re.match(r"[^@]+@[^@]+\.[^@]+", _as_text(value)):
                 return ValidationResult(False, msg)
         elif self.type == "stringLength":
@@ -119,7 +137,7 @@ class ValidationRule:
         elif self.type == "range":
             # Bounds on an ordered value (number/date/time). An empty field is
             # not out of range — use 'required' for presence.
-            if value is None or value == "":
+            if _is_empty(value):
                 return ValidationResult(True)
             lo = self.params.get("min")
             hi = self.params.get("max")

{bootstack-0.1.5 → bootstack-0.1.7}/src/bootstack/widgets/_core/base.py

@@ -355,6 +355,7 @@ class PublicWidgetBase:
                 options.update(_flex_child_opts(self, kwargs))
             master.add_child(self._internal, options, index=index)
             placement.options = options
+            self._recolor_on_attach()
             return
 
         if kwargs:
@@ -376,6 +377,29 @@ class PublicWidgetBase:
             options.update({k: v for k, v in kwargs.items() if k in PLACE_KEYS})
             self._internal.place(in_=master, **options)
         placement.options = options
+        self._recolor_on_attach()
+
+    def _recolor_on_attach(self) -> None:
+        """Recolor after a theme change that arrived while detached.
+
+        The theme walk skips off-screen widgets, so a widget detached across a
+        theme change comes back carrying the old palette. Attaching is the
+        genuine "now visible" trigger, matching PageStack navigation and
+        Expander expansion. Deferred to idle so the widget is mapped first.
+        """
+        widget = self._internal
+
+        def _recolor() -> None:
+            from bootstack.style.style import get_style
+            try:
+                get_style().apply_theme_walk(widget, only_stale=True)
+            except tkinter.TclError:
+                pass  # destroyed between attach and the idle callback
+
+        try:
+            widget.after_idle(_recolor)
+        except tkinter.TclError:
+            pass
 
     @overload
     def on_destroy(self) -> "Stream": ...

bootstack-0.1.7/src/bootstack/widgets/_core/kwargs.py

@@ -0,0 +1,85 @@
+"""Merging a caller's options dict over framework-built keyword arguments.
+
+Several widgets accept a bag of options aimed at a widget they build for you —
+`Form`'s `editor_options`, `MenuButton`'s `menu_options`, the keyword
+passthrough on `ButtonGroup.add` / `RadioGroup.add` / `Toolbar.add_widget`.
+Those bags name the built widget's own public keyword arguments, so a caller
+may name a parameter the framework also fills.
+
+Splatting both into one call raises `TypeError: got multiple values for
+keyword argument`, which names an internal class the caller never wrote.
+`merge_kwargs` gives that meeting point one rule instead:
+
+- The caller's options WIN over the framework's defaults. Naming a parameter
+  the framework also fills is how you override it.
+- A short list of keys is structural — the widget cannot do its job if they
+  are replaced (it would be parented elsewhere, or lose the command that emits
+  its events). Supplying one raises `BootstackError` naming the API you called
+  and what to use instead.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from bootstack.errors import BootstackError
+
+
+def reject_reserved(
+    user: Mapping[str, Any] | None,
+    reserved: Mapping[str, str] | None,
+    context: str,
+) -> None:
+    """Raise if the caller set a key the framework owns.
+
+    Args:
+        user: The caller's options. `None` is treated as empty.
+        reserved: Structural keys the caller may not set, mapped to the
+            guidance shown when they try.
+        context: The API the caller invoked, e.g. `'ButtonGroup.add()'`.
+
+    Raises:
+        BootstackError: If `user` contains a key listed in `reserved`.
+    """
+    if not user or not reserved:
+        return
+    for key in user:
+        if key in reserved:
+            raise BootstackError(f"{context} does not accept {key}= — {reserved[key]}")
+
+
+def merge_kwargs(
+    defaults: Mapping[str, Any],
+    user: Mapping[str, Any] | None,
+    *,
+    reserved: Mapping[str, str] | None = None,
+    context: str = "this call",
+) -> dict[str, Any]:
+    """Merge a caller's options over framework-built keyword arguments.
+
+    Args:
+        defaults: Keyword arguments the framework derived for the call. Any
+            key also present in `user` is overridden.
+        reserved: Structural keys the caller may not set, mapped to the
+            guidance shown when they try.
+        context: The API the caller invoked, used in the error message.
+        user: The caller's options. `None` is treated as empty.
+
+    Returns:
+        The merged keyword arguments.
+
+    Raises:
+        BootstackError: If `user` contains a key listed in `reserved`.
+    """
+    merged = dict(defaults)
+    if not user:
+        return merged
+    reject_reserved(user, reserved, context)
+    merged.update(user)
+    return merged
+
+
+# Structural keys a bar's widget-options passthrough may not set — a toolbar or
+# status bar places every widget it builds.
+RESERVED_BAR_KWARGS = {
+    'parent': 'the bar places the widgets it builds.',
+}

{bootstack-0.1.5 → bootstack-0.1.7}/src/bootstack/widgets/_core/selection_group.py

@@ -4,6 +4,13 @@ from typing import Any
 
 from bootstack.widgets._core.options import OptionRecord, record_to_dict, option_localize
 
+# Structural keys a per-option kwargs passthrough may not set — the group owns
+# each option's identity and tracks its own selection.
+RESERVED_OPTION_KWARGS = {
+    'text': 'set the caption with the label argument.',
+    'variable': 'the group tracks its own selection.',
+}
+
 
 class SelectionGroupMixin:
     """Shared item-management surface for the option-group widgets.

{bootstack-0.1.5 → bootstack-0.1.7}/src/bootstack/widgets/_impl/_parts/numberentry_part.py

@@ -6,10 +6,14 @@ wheel support.
 """
 
 
+from bootstack._runtime import wheel
 from bootstack.events import ChangeEvent
 from bootstack.widgets._impl.mixins.configure_mixin import configure_delegate
 from bootstack.widgets._impl._parts.textentry_part import TextEntryPart
 
+_TOUCHPAD_STEP_PX = 40
+"""Trackpad travel, in pixels, that advances a stepper by one increment."""
+
 
 class NumberEntryPart(TextEntryPart):
     """Numeric entry widget with stepping and bounds validation.
@@ -111,12 +115,13 @@ class NumberEntryPart(TextEntryPart):
         self.bind('<Up>', self._handle_up_key, add=True)
         self.bind('<Down>', self._handle_down_key, add=True)
 
-        # Bind mouse wheel (Windows/macOS)
-        self.bind('<MouseWheel>', self._handle_mouse_wheel, add=True)
-
-        # Bind mouse wheel (Linux/X11)
-        self.bind('<Button-4>', self._handle_wheel_up, add=True)
-        self.bind('<Button-5>', self._handle_wheel_down, add=True)
+        # Bind wheel stepping. A wheel arrives as <MouseWheel> everywhere
+        # except legacy X11; a trackpad fires <TouchpadScroll> on Tk 8.7+.
+        for seq in wheel.wheel_sequences(self):
+            self.bind(seq, self._handle_mouse_wheel, add=True)
+        if wheel.has_touchpad_scroll():
+            self._touchpad = wheel.PixelAccumulator()
+            self.bind(wheel.TOUCHPAD_SCROLL, self._handle_touchpad_scroll, add=True)
 
         # Listen for increment/decrement events to invoke step
         self.bind('<<Increment>>', self._handle_increment_event, add=True)
@@ -137,33 +142,28 @@ class NumberEntryPart(TextEntryPart):
         return 'break'  # Prevent default behavior
 
     def _handle_mouse_wheel(self, event):
-        """Handle mouse wheel on Windows/macOS."""
+        """Handle a wheel notch by stepping the value once."""
         if not self._is_interactive():
             return 'break'
-        try:
-            delta = int(event.delta)
-        except (AttributeError, ValueError):
-            delta = 0
-
-        if delta != 0:
-            if delta > 0:
-                self.event_generate('<<Increment>>', data={'value': self._value})
-            else:
-                self.event_generate('<<Decrement>>', data={'value': self._value})
+        notches = wheel.wheel_notches(self, event)
+        if notches:
+            name = '<<Increment>>' if notches > 0 else '<<Decrement>>'
+            self.event_generate(name, data={'value': self._value})
         return 'break'
 
-    def _handle_wheel_up(self, event):
-        """Handle mouse wheel up on Linux/X11."""
-        if not self._is_interactive():
-            return 'break'
-        self.event_generate('<<Increment>>', data={'value': self._value})
-        return 'break'
+    def _handle_touchpad_scroll(self, event):
+        """Step once per `_TOUCHPAD_STEP_PX` of trackpad travel.
 
-    def _handle_wheel_down(self, event):
-        """Handle mouse wheel down on Linux/X11."""
+        A trackpad reports around sixty events a second; stepping on each
+        one would run the value away from the user.
+        """
         if not self._is_interactive():
             return 'break'
-        self.event_generate('<<Decrement>>', data={'value': self._value})
+        _dx, dy = wheel.precise_deltas(event)
+        _sx, steps = self._touchpad.add(0, dy, 1, _TOUCHPAD_STEP_PX)
+        name = '<<Increment>>' if steps > 0 else '<<Decrement>>'
+        for _ in range(abs(steps)):
+            self.event_generate(name, data={'value': self._value})
         return 'break'
 
     def _handle_increment_event(self, event):
@@ -272,9 +272,10 @@ class NumberEntryPart(TextEntryPart):
         A plain numeric field parses to a string when no display format is set,
         so coerce it the same way the public value does — validation rules and a
         `custom` func receive a real `int`/`float` (or `None` for empty/invalid
-        input), never the display string.
+        input), never the display string. A visible placeholder is not input,
+        so it reads as empty here — same rule as the text field this overrides.
         """
-        text = self.get()
+        text = '' if self._showing_placeholder else self.get()
         try:
             raw = self._parse_or_none(text)
         except Exception:

{bootstack-0.1.5 → bootstack-0.1.7}/src/bootstack/widgets/_impl/_parts/textentry_part.py

@@ -288,11 +288,17 @@ class TextEntryPart(ValidationMixin, Entry):
         last-committed value. This keeps a manual `validate()`, the automatic
         blur/key validation, and a form-level validate in agreement on the same
         live, typed input.
+
+        A visible placeholder is not input. It is inserted into the entry to
+        render it, so reading the raw text would hand the placeholder string to
+        the rules and `required` would pass on an untouched field — the field
+        reads as empty here, exactly as it does through `value`.
         """
+        text = "" if self._showing_placeholder else self.get()
         try:
-            return self._parse_or_none(self.get())
+            return self._parse_or_none(text)
         except Exception:
-            return self.get()
+            return text
 
     def text(self, value=None):
         """Get or set the raw display text without committing.

{bootstack-0.1.5 → bootstack-0.1.7}/src/bootstack/widgets/_impl/composites/dropdownbutton.py

@@ -7,8 +7,18 @@ from typing_extensions import Unpack
 from bootstack.widgets._impl.composites.contextmenu import ContextMenu, ContextMenuItem, ContextMenuItemResult
 from bootstack.widgets._impl.primitives._menubutton import MenuButton
 from bootstack.widgets._impl.mixins import configure_delegate
+from bootstack.widgets._core.kwargs import merge_kwargs
 from bootstack.widgets.types import Master, StyledKwargs, CompoundMode, WidgetState, WidgetDensity
 
+# Structural keys a menu_options bag may not set — the button owns the menu's
+# contents and the callback that emits its selection events.
+_RESERVED_MENU_OPTIONS = {
+    'items': 'pass the menu items to the button itself.',
+    'command': "use the button's on_select event.",
+    'trigger': 'the button opens its own menu when clicked.',
+    'target': 'the menu belongs to the button that opens it.',
+}
+
 if TYPE_CHECKING:
     from bootstack.signals import Signal
 
@@ -122,10 +132,13 @@ class DropdownButton(MenuButton):
             "offset": (offset_x, 0),
             "density": density,
         }
-        options.update(self._popdown_options)
         # DropdownButton manages its own activation (left-click, Return/
         # KP_Enter via show_menu), so opt out of ContextMenu's auto-trigger.
-        cm = ContextMenu(self, target=self, items=self._items, trigger=None, command=self._command, **options)
+        options["trigger"] = None
+        options = merge_kwargs(options, self._popdown_options,
+                               reserved=_RESERVED_MENU_OPTIONS,
+                               context='MenuButton menu_options')
+        cm = ContextMenu(self, target=self, items=self._items, command=self._command, **options)
         return cm
 
     @property

{bootstack-0.1.5 → bootstack-0.1.7}/src/bootstack/widgets/_impl/composites/field.py

@@ -273,8 +273,13 @@ class Field(EntryMixin, Frame):
         self._entry.value(value)
 
     def get(self) -> str:
-        """Return the raw text from the underlying entry widget."""
-        return self._entry.get()
+        """Return the display text from the underlying entry widget.
+
+        Reads the entry's own text rather than its raw contents, so a field
+        showing only its placeholder reports an empty string — `text` and
+        `value` are a pair and must agree on whether the field is empty.
+        """
+        return self._entry.text()
 
     @property
     def entry_widget(self) -> EntryWidget: