bootstack 0.1.0a14__tar.gz → 0.1.0a16__tar.gz

{bootstack-0.1.0a14/src/bootstack.egg-info → bootstack-0.1.0a16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bootstack
-Version: 0.1.0a14
+Version: 0.1.0a16
 Summary: From idea to a shipped desktop app, fast — a declarative, reactive, batteries-included Python UI framework with 60+ widgets, semantic theming, and built-in packaging.
 Author-email: Israel Dryer <israel.dryer@gmail.com>
 License-Expression: MIT
@@ -223,7 +223,7 @@ app.run()
 
 ## Features
 
-- **Application scaffolding** — `App` for blank windows, `AppShell` for toolbar + sidebar + page-stack apps, `Workbench` for two-tier workspace apps, undecorated windows with custom chrome
+- **Application scaffolding** — `App` for blank windows, `AppShell` for toolbar + sidebar + page-stack apps, `Workbench` for two-tier workspace apps, `Splash` for a startup intro screen, undecorated windows with custom chrome
 - **60+ themed widgets** — primitives plus higher-level composites (DataTable, Tree, ListView, Calendar, DateField, Form, Gauge, ToggleGroup, PageStack, Carousel, Tooltip, and more)
 - **Dialogs and messages** — `alert()` / `confirm()` / `ask_*()` prompts and `FormDialog` / `FontDialog` / `FilterDialog`, plus non-blocking `toast()`, `Notification`, and `Snackbar` surfaces
 - **Layout containers** — `Column`, `Row`, `Grid`, and `Spacer` for declarative layouts; `Card`, `GroupBox`, `ScrollView`, `SplitView`, `Accordion`, `Divider`
@@ -248,7 +248,7 @@ app.run()
 | **Data Display** | Label, Badge, ListView, Tree, DataTable, ProgressBar, Gauge |
 | **Media** | Avatar, Picture, Gallery, Carousel |
 | **Layout** | Column, Row, Grid, Spacer, Card, GroupBox, SplitView, ScrollView, Accordion, Divider |
-| **Navigation** | AppShell, Workbench, Window, StatusBar, Tabs, PageStack |
+| **Navigation** | AppShell, Workbench, Window, Splash, StatusBar, Tabs, PageStack |
 | **Dialogs** | `alert()`, `confirm()`, `ask_*()` prompts, FormDialog, FontDialog, FilterDialog |
 | **Overlays** | `toast()`, Notification, Snackbar, Tooltip |
 | **Forms** | Form, with field-level validation |

{bootstack-0.1.0a14 → bootstack-0.1.0a16}/README.md

@@ -173,7 +173,7 @@ app.run()
 
 ## Features
 
-- **Application scaffolding** — `App` for blank windows, `AppShell` for toolbar + sidebar + page-stack apps, `Workbench` for two-tier workspace apps, undecorated windows with custom chrome
+- **Application scaffolding** — `App` for blank windows, `AppShell` for toolbar + sidebar + page-stack apps, `Workbench` for two-tier workspace apps, `Splash` for a startup intro screen, undecorated windows with custom chrome
 - **60+ themed widgets** — primitives plus higher-level composites (DataTable, Tree, ListView, Calendar, DateField, Form, Gauge, ToggleGroup, PageStack, Carousel, Tooltip, and more)
 - **Dialogs and messages** — `alert()` / `confirm()` / `ask_*()` prompts and `FormDialog` / `FontDialog` / `FilterDialog`, plus non-blocking `toast()`, `Notification`, and `Snackbar` surfaces
 - **Layout containers** — `Column`, `Row`, `Grid`, and `Spacer` for declarative layouts; `Card`, `GroupBox`, `ScrollView`, `SplitView`, `Accordion`, `Divider`
@@ -198,7 +198,7 @@ app.run()
 | **Data Display** | Label, Badge, ListView, Tree, DataTable, ProgressBar, Gauge |
 | **Media** | Avatar, Picture, Gallery, Carousel |
 | **Layout** | Column, Row, Grid, Spacer, Card, GroupBox, SplitView, ScrollView, Accordion, Divider |
-| **Navigation** | AppShell, Workbench, Window, StatusBar, Tabs, PageStack |
+| **Navigation** | AppShell, Workbench, Window, Splash, StatusBar, Tabs, PageStack |
 | **Dialogs** | `alert()`, `confirm()`, `ask_*()` prompts, FormDialog, FontDialog, FilterDialog |
 | **Overlays** | `toast()`, Notification, Snackbar, Tooltip |
 | **Forms** | Form, with field-level validation |

{bootstack-0.1.0a14 → bootstack-0.1.0a16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "bootstack"
-version = "0.1.0a14"
+version = "0.1.0a16"
 description = "From idea to a shipped desktop app, fast — a declarative, reactive, batteries-included Python UI framework with 60+ widgets, semantic theming, and built-in packaging."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -109,7 +109,7 @@ where = ["src"]
 ]
 
 [tool.bumpversion]
-current_version = "0.1.0a14"
+current_version = "0.1.0a16"
 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.0a14 → bootstack-0.1.0a16}/src/bootstack/__init__.py

@@ -60,6 +60,7 @@ from bootstack.dialogs import (
 from bootstack.widgets.app import App
 from bootstack.widgets.appshell import AppShell, Workbench
 from bootstack.widgets.window import Window
+from bootstack.widgets.splash import Splash
 
 # ── Public widget layer ───────────────────────────────────────────────────────
 from bootstack.widgets.stacks import Row, Column, Spacer
@@ -130,7 +131,7 @@ __all__ = [
     "ask_date_range", "ask_item", "ask_color", "ask_font", "ask_filter",
     "ask_save_file", "ask_open_file", "ask_open_files", "ask_directory",
     # Application & windows
-    "App", "AppShell", "Workbench", "Window",
+    "App", "AppShell", "Workbench", "Window", "Splash",
     # Layout
     "Row", "Column", "Spacer", "Grid", "Card", "GroupBox", "Divider", "ScrollView",
     "SplitView", "SplitPane", "Accordion", "AccordionSection",

{bootstack-0.1.0a14 → bootstack-0.1.0a16}/src/bootstack/_runtime/app.py

@@ -630,6 +630,10 @@ class App(BaseWindow, WidgetCapabilitiesMixin, tkinter.Tk):
         if self._on_close_kwarg is not None:
             self.add_close_handler(self._on_close_kwarg)
 
+        # A registered intro splash (bs.Splash), or None. Set by the splash on
+        # construction; read at reveal time to defer the app's own appearance.
+        self._splash: Any = None
+
     def mainloop(self, n=0) -> None:
         """Start the application event loop
 
@@ -639,7 +643,13 @@ class App(BaseWindow, WidgetCapabilitiesMixin, tkinter.Tk):
         """
         if self._center_on_screen:
             self.place_window_center()
-        self.show()
+        splash = getattr(self, "_splash", None)
+        if splash is not None and splash.is_showing:
+            # An intro splash is up — defer the app's reveal until it dismisses,
+            # then reveal via this callback (see Splash._notify_app_ready).
+            splash._notify_app_ready(self.show)
+        else:
+            self.show()
         super().mainloop(n=n)
 
     def _do_close(self) -> None:
@@ -694,10 +704,12 @@ class App(BaseWindow, WidgetCapabilitiesMixin, tkinter.Tk):
                 from bootstack.style.typography import Typography
                 from bootstack._core.images import _ImageService
                 from bootstack._runtime.visual_focus import reset_visual_focus_root
+                from bootstack.signals.signal import reset_realized_signals
                 reset_style()
                 Typography.reset()
                 _ImageService.clear_cache()
                 reset_visual_focus_root()
+                reset_realized_signals()
                 gc.collect()
             except Exception:
                 pass

{bootstack-0.1.0a14 → bootstack-0.1.0a16}/src/bootstack/_runtime/toplevel.py

@@ -62,7 +62,13 @@ class Toplevel(BaseWindow, WidgetCapabilitiesMixin, tkinter.Toplevel):
             resizable: Whether the user may resize the window as (x, y).
             transient: Mark this window as transient for the given master.
             overrideredirect: If True, instruct the window manager to ignore this window.
-            windowtype: On X11, request a specific window manager type via `-type`.
+            windowtype: Request a native window type, resolved per platform from a
+                single switch. Values: `'splash'`, `'tooltip'`, `'dock'`, `'utility'`.
+                On X11 it sets `-type`; on macOS it maps to a `MacWindowStyle`; on
+                Windows the chromeless types (`'splash'`/`'tooltip'`/`'dock'`) resolve
+                to override-redirect (borderless, no taskbar button) and `'utility'`
+                resolves to a tool window. The caller does not also need to pass
+                `overrideredirect=True` to get a chromeless window on Windows.
             topmost: If True, keep this window above others (`-topmost`).
             toolwindow: On Windows, request a toolwindow style (`-toolwindow`).
             alpha: On Windows, the window alpha transparency (0.0–1.0) via `-alpha`.
@@ -124,6 +130,20 @@ class Toplevel(BaseWindow, WidgetCapabilitiesMixin, tkinter.Toplevel):
                 except tkinter.TclError:
                     pass
 
+        # Windows has no native window-type attribute, so translate windowtype
+        # to the matching primitive: the chromeless types resolve to
+        # override-redirect (borderless + no taskbar/Alt-Tab button), and
+        # 'utility' resolves to a tool window (minimal chrome). One switch then
+        # yields the right native window on all three platforms. (On Aqua the
+        # overrideredirect call is a no-op — MacWindowStyle handled it above.)
+        _effective_overrideredirect = overrideredirect
+        _effective_toolwindow = toolwindow
+        if windowtype is not None and self.winsys == "win32":
+            if windowtype in ("splash", "tooltip", "dock"):
+                _effective_overrideredirect = True
+            elif windowtype == "utility":
+                _effective_toolwindow = True
+
         # Setup icon (use default bootstack icon if no icon provided)
         self._setup_icon(icon, default_icon_enabled=True)
 
@@ -169,7 +189,7 @@ class Toplevel(BaseWindow, WidgetCapabilitiesMixin, tkinter.Toplevel):
             maxsize=maxsize,
             resizable=resizable,
             transient=_resolved_transient,
-            overrideredirect=overrideredirect,
+            overrideredirect=_effective_overrideredirect,
             alpha=alpha,
             window_style=window_style,
             center_on_parent=_center_parent,
@@ -188,7 +208,7 @@ class Toplevel(BaseWindow, WidgetCapabilitiesMixin, tkinter.Toplevel):
         if topmost:
             self.attributes("-topmost", 1)
 
-        if toolwindow and self.winsys == "win32":
+        if _effective_toolwindow and self.winsys == "win32":
             self.attributes("-toolwindow", 1)
 
         # Register on_close handler

{bootstack-0.1.0a14 → bootstack-0.1.0a16}/src/bootstack/_runtime/utility.py

@@ -247,6 +247,27 @@ def scale_padding_floor(base: int) -> int:
     return max(base, round(base * _ScalingState.get_ui_scale()))
 
 
+def scale_icon_size(base: int) -> int:
+    """Scale a logical icon size to physical pixels for the current DPI.
+
+    Icons are authored at logical (96-DPI) sizes. On a higher-DPI display the
+    surrounding fonts and layout scale up via Tk scaling, so an icon rendered at
+    its literal logical size lands too small for its container and gets resampled
+    by the display, reading as soft (#267). Rendering at the physical size makes
+    the glyph land 1:1 in the scaled layout, so it stays crisp.
+
+    Floors at `base` (mirrors `scale_padding_floor`) so an uninitialized scale
+    state or a sub-baseline display never renders an icon smaller than requested.
+
+    Args:
+        base: The logical icon size in pixels at standard (96-DPI) scaling.
+
+    Returns:
+        The DPI-scaled size, at least `base`.
+    """
+    return max(base, round(base * _ScalingState.get_ui_scale()))
+
+
 def scale_size(widget=None, size=None):
     """Scale the size based on the scaling factor of tkinter.
     This is used most frequently to adjust the assets for

{bootstack-0.1.0a14 → bootstack-0.1.0a16}/src/bootstack/events/__init__.py

@@ -32,9 +32,13 @@ from bootstack.events._payloads import (
     RangeSliderEvent,
     RowEvent,
     RowsEvent,
+    SashMoveEvent,
+    ScrollEvent,
     SelectionEvent,
     SliderCommitEvent,
     SliderEvent,
+    SplashDismissEvent,
+    SplashDismissReason,
     TabActivateEvent,
     TabChangeEvent,
     TabCloseEvent,
@@ -97,4 +101,11 @@ __all__ = [
     # Payloads — data source
     "DataChangeEvent",
     "ChangeKind",
+    # Payloads — split view
+    "SashMoveEvent",
+    # Payloads — scroll view
+    "ScrollEvent",
+    # Payloads — splash
+    "SplashDismissEvent",
+    "SplashDismissReason",
 ]

{bootstack-0.1.0a14 → bootstack-0.1.0a16}/src/bootstack/events/_payloads.py

@@ -487,3 +487,53 @@ class DataChangeEvent:
     record: Mapping[str, Any] | None = None
     """The affected record (or the applied updates) where cheaply available on
     `insert`/`update`; `None` otherwise."""
+
+
+# ---------------------------------------------------------------------------
+# SplitView
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class SashMoveEvent:
+    """Fires when a `SplitView` sash is released after being dragged."""
+
+    index: int = 0
+    """Zero-based index of the sash that moved."""
+
+    position: int = 0
+    """New pixel position of the sash in pixels from the leading edge."""
+
+
+# ---------------------------------------------------------------------------
+# ScrollView
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ScrollEvent:
+    """Fires when a `ScrollView`'s viewport position changes."""
+
+    y: float = 0.0
+    """Vertical scroll position — 0.0 (top) to 1.0 (bottom)."""
+
+    x: float = 0.0
+    """Horizontal scroll position — 0.0 (left) to 1.0 (right)."""
+
+
+# ---------------------------------------------------------------------------
+# Splash
+# ---------------------------------------------------------------------------
+
+SplashDismissReason = Literal["ready", "timer", "manual", "skip"]
+"""Why a splash screen dismissed — `'ready'` (the app finished building),
+`'timer'` (its timed duration elapsed), `'manual'` (an explicit `dismiss()`),
+or `'skip'` (the user clicked or pressed Escape)."""
+
+
+@dataclass(frozen=True, slots=True)
+class SplashDismissEvent:
+    """Fires when a splash screen begins dismissing."""
+
+    reason: SplashDismissReason = "ready"
+    """Why the splash dismissed."""

{bootstack-0.1.0a14 → bootstack-0.1.0a16}/src/bootstack/images.py

@@ -37,6 +37,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from bootstack._core.images import _ImageService
+from bootstack._runtime.utility import scale_icon_size
 
 if TYPE_CHECKING:
     from PIL.Image import Image as _PILImage
@@ -248,7 +249,7 @@ class Image:
             # every scroll doesn't re-render the glyph each time; dropped by
             # _invalidate() on a theme change so token colors re-render.
             if self._icon_pil is None:
-                size = self._icon.size
+                size = scale_icon_size(self._icon.size)
                 size = size if size % 2 == 0 else size + 1
                 self._icon_pil = _ImageService._render_icon(
                     self._icon.name, size, self._resolve_icon_color()
@@ -285,7 +286,7 @@ class Image:
             return self._photo
         if self._icon is not None:
             color = self._resolve_icon_color()
-            photo = _ImageService.get_icon(self._icon.name, self._icon.size, color)
+            photo = _ImageService.get_icon(self._icon.name, scale_icon_size(self._icon.size), color)
         elif self._path is not None:
             photo = _ImageService.open(self._path)
         elif self._data is not None:

bootstack-0.1.0a16/src/bootstack/signals/README.md

@@ -0,0 +1,98 @@
+Signals for bootstack
+=====================
+
+Lightweight reactive state. A ``Signal[T]`` holds a value, notifies subscribers
+when it changes, and can be bound two-way to widgets. It is backed by a Tk
+variable, but that variable is created lazily, so the Tk surface never leaks
+into the public API.
+
+> The user-facing guide is ``docs/reference/signals.rst`` (teaching) and the
+> API Reference page for ``bootstack.signals`` (lookup). This README covers the
+> package internals; keep it in sync with ``signal.py``.
+
+Architecture
+- ``Signal[T]`` (public): the reactive cell — ``signal()`` to read, ``set()`` to
+  write, ``subscribe()`` to observe, ``map()`` to derive.
+- Lazy Tk-var realization: ``Signal(...)`` creates **no** Tk variable at
+  construction, so a signal can be created at module level (before any ``App``).
+  The backing variable is realized on first bind/escape-hatch access against the
+  running interpreter, and re-realized cleanly across ``App`` lifecycles.
+- Object mode: values that are not Tk-native (anything other than
+  ``bool``/``int``/``float``/``str``/``set`` — e.g. a ``date`` or a dataclass)
+  are held as the authoritative Python object; the Tk variable is used only as a
+  change-notification bus. Native values are stored in the Tk variable directly.
+- ``_SignalTrace`` (internal): manages the Tcl variable trace
+  (``trace_add``/``trace_remove``).
+
+Key behaviors
+- Read / write: ``signal()`` returns the current value; ``signal.set(v)`` updates
+  it. A ``set()`` to an equal value is a no-op (no notification).
+- Subscriptions: ``subscribe(callback, *, immediate=False)`` returns a
+  ``streams.Handle``; call ``handle.cancel()`` to unsubscribe. ``immediate=True``
+  fires the callback once with the current value at subscribe time.
+- Derived signals: ``map(transform)`` returns a new signal that follows this one.
+  A weak reference keeps the parent from holding the derived signal alive.
+- Robustness: the last value is cached and returned even if the backing variable
+  has been dropped (e.g. between ``App`` lifecycles).
+- Escape hatch: ``Signal.from_variable(tk_var)`` wraps an existing Tk variable,
+  and ``signal.var`` exposes the backing variable. These are the only Tk-aware
+  paths; everything else stays Tk-free.
+
+Usage
+1) Quick start (works at module level — no ``App`` required)
+```python
+from bootstack.signals import Signal
+
+count = Signal(0)
+print(count())        # -> 0
+count.set(1)
+print(count())        # -> 1
+```
+
+2) Two-way binding to a widget
+```python
+import bootstack as bs
+
+with bs.App() as app:
+    name = bs.Signal("")
+    bs.TextField(textsignal=name)          # edits flow into the signal
+    bs.Label(textsignal=name.map(lambda v: f"Hello, {v}!"))  # derived display
+app.run()
+```
+
+3) Subscribing and unsubscribing
+```python
+import bootstack as bs
+
+with bs.App() as app:
+    flag = bs.Signal(False)
+
+    def on_flag(value):
+        print("flag:", value)
+
+    handle = flag.subscribe(on_flag, immediate=True)  # prints: flag: False
+    flag.set(True)                                     # prints: flag: True
+    handle.cancel()                                    # stop observing
+app.run()
+```
+
+4) Typed (object-mode) values
+```python
+from datetime import date
+import bootstack as bs
+
+with bs.App():
+    due = bs.Signal(date.today())
+    bs.DateField(signal=due)        # binds the typed value
+    print(type(due()))              # -> <class 'datetime.date'> (not str)
+```
+
+Import path
+- ``import bootstack as bs; bs.Signal``
+- ``from bootstack.signals import Signal``
+
+Notes
+- The UI toolkit is not thread-safe. Marshal cross-thread updates onto the UI
+  via the framework's scheduling, not by touching the signal from a worker
+  thread.
+- Keep subscriber callbacks fast; offload long-running work.