bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/composites/toast.py

@@ -0,0 +1,390 @@
+
+from bootstack._runtime.toplevel import Toplevel
+from typing import Any, Callable, Sequence
+
+from typing_extensions import TypedDict, Unpack
+
+from bootstack._runtime.window_utilities import WindowPositioning
+
+
+class IconSpec(TypedDict, total=False):
+    """Icon configuration for toast."""
+    name: str
+    size: int | None
+    color: str | None
+
+
+from bootstack.widgets._impl.primitives.frame import Frame as _Frame
+from bootstack.widgets._impl.primitives.label import Label as _Label
+from bootstack.widgets._impl.primitives.button import Button as _Button
+
+class ToastConfig(TypedDict, total=False):
+    """Configuration options for Toast widget."""
+    title: str | None
+    icon: str | IconSpec | None
+    message: str | None
+    memo: str | None
+    duration: int | None
+    buttons: Sequence[dict[str, Any]] | None
+    show_close_button: bool
+    accent: str | None
+    position: str | None
+    alert: bool
+    on_dismissed: Callable[[Any], Any] | None
+
+
+class Toast:
+    """A notification toast widget that displays temporary messages.
+
+    Toast notifications appear in a small window, typically in the corner of the screen,
+    and can display a title, message, icon, buttons, and optional metadata. They can be
+    configured to auto-dismiss after a duration or remain visible until manually closed.
+    """
+
+    def __init__(
+            self,
+            *,
+            title: str | None = None,
+            icon: str | IconSpec | None = None,
+            message: str | None = None,
+            memo: str | None = None,
+            duration: int | None = None,
+            buttons: Sequence[dict[str, Any]] | None = None,
+            show_close_button: bool = True,
+            accent: str | None = None,
+            position: str | None = None,
+            alert: bool = False,
+            on_dismissed: Callable[[Any], Any] | None = None,
+            place: Callable[[Any], None] | None = None,
+    ) -> None:
+        """Initialize a Toast notification.
+
+        Args:
+            title: Title text. Displayed with a larger font when no message is
+                provided; otherwise appears as the header with message below.
+            icon: Icon name string or `IconSpec` dict with `name`, `size`, and
+                `color` keys.
+            message: Main message text. Displayed in header when no title; shown
+                below the title separator when both are provided.
+            memo: Small metadata text in the header (e.g., "5 mins ago"). Muted styling.
+            duration: Auto-dismiss delay in milliseconds. If None, stays until closed.
+            buttons: Sequence of button option dicts. Each dict accepts any bootstack
+                Button kwargs. Button press triggers `on_dismissed` before closing.
+            show_close_button: Whether to show the close (×) button. Default True.
+            accent: Accent token for the container (e.g., 'primary', 'danger'). If
+                None, uses the default background.
+            position: Tkinter geometry string (e.g., '-25-75'). If None, uses
+                platform defaults (bottom-right on Windows/macOS, top-right on X11).
+            alert: If True, plays a system bell when shown.
+            on_dismissed: Callback invoked on dismiss. Receives the button options
+                dict when dismissed via a button, or None otherwise.
+        """
+        self._config_keys = {'title', 'icon', 'message', 'memo', 'duration', 'buttons', 'show_close_button',
+                             'accent', 'position', 'alert', 'on_dismissed'}
+
+        # initialized configuration
+        self._title = title
+        self._icon = icon
+        self._message = message
+        self._memo = memo
+        self._duration = duration
+        self._buttons = buttons
+        self._show_close_button = show_close_button
+        self._accent = accent
+        self._position = position
+        self._alert = alert
+        self._on_dismissed = on_dismissed
+        # Optional positioning hook: a callable given the built (off-screen,
+        # measured) Toplevel that sets its final geometry. Lets a facade own
+        # corner/window placement and stacking; bypasses the default logic.
+        self._place = place
+
+        # top level widget
+        self._toplevel: Toplevel | None = None
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Set a configuration option using dictionary syntax."""
+        self.configure(**{key: value})
+
+    def __getitem__(self, key: str) -> Any:
+        """Get a configuration option using dictionary syntax."""
+        return self.cget(key)
+
+    def _handle_on_dismissed(self, data: Any = None) -> None:
+        """Invoke the on_dismissed callback if configured."""
+        if self._on_dismissed:
+            self._on_dismissed(data)
+
+    def configure(
+            self,
+            option: str | None = None,
+            **kwargs: Unpack[ToastConfig]
+    ) -> tuple[str, str, str, None, Any] | None:
+        """Configure toast options.
+
+        Args:
+            option: If provided, returns the configuration for this option.
+            **kwargs: Configuration options to set.
+
+        Returns:
+            Configuration tuple if option provided, otherwise None.
+        """
+        if option is not None:
+            if option in self._config_keys:
+                attr = f"_{option}"
+                value = getattr(self, attr)
+                # returns in the expected tkinter.configure format
+                return option, option, option.capitalize(), None, value
+            else:
+                raise AttributeError(f"'{option}' is not a valid option")
+
+        if kwargs:
+            for key, value in kwargs.items():
+                if key in self._config_keys:
+                    attr = f"_{key}"
+                    setattr(self, attr, value)
+                else:
+                    raise AttributeError(f"'{key}' is not a valid option")
+        return None
+
+    def cget(self, option: str) -> Any:
+        """Get the value of a configuration option.
+
+        Args:
+            option: The configuration option name.
+
+        Returns:
+            The value of the configuration option.
+        """
+        if option in self._config_keys:
+            attr = f"_{option}"
+            return getattr(self, attr)
+        else:
+            raise AttributeError(f"'{option}' is not a valid option")
+
+    def show(self, merge: bool = True, **options: Unpack[ToastConfig]) -> None:
+        """Display the toast.
+
+        If options are provided, they are merged with the existing toast configuration. If you do not want this
+        behavior, set the merge flag to False, or create a new toast instance.
+
+        Args:
+            merge: If True, merge options with existing configuration. If False, clear existing options first.
+            **options: Configuration options to set before showing.
+        """
+        if not merge:
+            self._clear_options()
+
+        self.configure(**options)
+        self._build_toast()
+        if self._toplevel:
+            self._toplevel.deiconify()
+
+    def _clear_options(self) -> None:
+        """Clear all configuration options to their default values."""
+        self._title = None
+        self._icon = None
+        self._message = None
+        self._memo = None
+        self._duration = None
+        self._buttons = None
+        self._show_close_button = True
+        self._accent = None
+        self._position = None
+        self._alert = False
+        self._on_dismissed = None
+
+    def hide(self) -> None:
+        """Hide the toast and trigger the on_dismissed callback."""
+        if self._toplevel:
+            self._toplevel.destroy()
+        self._handle_on_dismissed(None)
+
+    def destroy(self) -> None:
+        """Destroy the toast widget and cleanup resources."""
+        if hasattr(self, '_toplevel') and self._toplevel:
+            self._toplevel.destroy()
+        self._toplevel = None
+
+    def _build_toast(self) -> None:
+                # ----- Configuration Options -------
+
+        has_title = self._title is not None
+        has_title_and_message = has_title and self._message is not None
+        resolved_title_font = "label" if has_title else "body"
+        subtle_accent = f"{self._accent}[subtle]" if self._accent else None
+        # Text uses the accent's *emphasis* shade — a dark, readable, accent-
+        # tinted color (matching Bootstrap's text-emphasis), not the bright base
+        # accent, which is low-contrast and harsh as text on the subtle wash.
+        # No accent -> None, so the label falls back to the on-surface foreground.
+        text_accent = f"{self._accent}_emphasis" if self._accent else None
+        # Icon is opt-in (no forced default): a toast is its message, optionally
+        # preceded by an icon. Frameworks don't agree on a default, so render one
+        # only when asked.
+        icon_spec = None
+        if self._icon:
+            icon_spec = self._icon if isinstance(self._icon, dict) else {"name": self._icon, "size": 20}
+
+        # ------ Toplevel setup ------
+
+        # bootstack.Toplevel applies MacWindowStyle 'help none' on Aqua
+        # via windowtype='tooltip', so toasts render chromeless on Mac
+        # (overrideredirect alone is silently skipped on Aqua per the
+        # project's BaseWindow guard). Win/Linux keep the overrideredirect
+        # path. Topmost + alpha are passed as kwargs so the Toplevel sets
+        # them at the right moment in its setup pipeline.
+        top = Toplevel(
+            overrideredirect=True,
+            topmost=True,
+            alpha=0.97,
+            windowtype='tooltip',
+        )
+        top.minsize(400, 30)
+
+        # ------ Toast Layout ------
+
+        # The container carries the subtle accent wash; the border stays neutral
+        # (no accent) so the card has a quiet edge rather than a bright outline.
+        container = _Frame(top, padding=4, show_border=True,
+                           surface=subtle_accent or 'overlay')
+        container.pack(fill='both', expand=True)
+
+        # Tight gap below the title so it reads as one unit with the message;
+        # the breathing room lives on the outside (container padding + message
+        # bottom). A lone title (no message) keeps a balanced bottom instead.
+        header_bottom = 8 if not has_title_and_message else 2
+        header = _Frame(container, padding=(8, 8, 8, header_bottom))
+        header.pack(side='top', fill='x')
+
+        # icon — the emphasis shade, like the text, so it stays legible on the
+        # subtle wash (the bright base accent — e.g. warning's yellow — washes
+        # out against its own pale tint).
+        if icon_spec:
+            _Label(header, icon=icon_spec, accent=text_accent).pack(side='left', padx=(0, 8))
+
+        # title — emphasis (dark, readable accent-tinted) text
+        _Label(
+            header,
+            text=self._title if has_title else self._message,
+            font=resolved_title_font,
+            wraplength=380,
+            justify='left',
+            accent=text_accent,
+        ).pack(side='left', fill='x')
+
+        # close — a clickable x icon, not a Button: a compact button still floors
+        # ~12px above the title row and would inflate the header. A Label icon
+        # matches the title/icon height, so the row stays content-sized.
+        if self._show_close_button:
+            close = _Label(header, icon={"name": "x-lg", "size": 14}, accent="secondary")
+            close.configure(cursor="hand2")
+            close.bind("<Button-1>", lambda _e: self.hide())
+            close.pack(side='right', padx=(4, 0))
+
+        # memo — muted metadata (no extra vertical padding; the header owns it)
+        if self._memo:
+            _Label(
+                header,
+                text=self._memo,
+                font="caption",
+                accent="secondary",
+            ).pack(side='right', padx=(0, 4 if self._show_close_button else 12))
+
+        # message — emphasis text
+        if has_title_and_message:
+            _Label(
+                container,
+                text=self._message,
+                wraplength=400,
+                justify='left',
+                accent=text_accent,
+            ).pack(side='top', fill='x', pady=(0, 8), padx=8)
+
+        # buttons
+        if self._buttons:
+            def execute_command(options: dict[str, Any], fn: Callable[[], None] | None = None) -> Callable[[], None]:
+                def inner() -> None:
+                    if fn:
+                        fn()
+                    self._handle_on_dismissed(options)
+                    top.destroy()
+
+                return inner
+
+            button_frame = _Frame(container)
+            button_frame.pack(side='top', anchor='e', padx=4, pady=(0, 4))
+
+            for i, button_options in enumerate(self._buttons):
+                func = button_options.get('command', None)
+                button_opts = {k: v for k, v in button_options.items() if k != 'command'}
+                _Button(
+                    button_frame,
+                    **button_opts,
+                    command=execute_command(button_options, func)
+                ).grid(column=i, row=0, padx=(4 if i > 0 else 0, 0))
+
+        # ------ Positioning -------
+
+        # Deiconify off-screen first so the geometry manager runs a full
+        # layout pass on a mapped window. winfo_height() returns 1 on a
+        # withdrawn window, causing the toast to be placed with ~0 height
+        # and therefore positioned flush against the screen edge.
+        top.deiconify()
+        top.geometry(
+            f"+{top.winfo_screenwidth() * 2}+{top.winfo_screenheight() * 2}"
+        )
+        top.update_idletasks()
+
+        # A facade-supplied placement hook owns corner/window positioning and
+        # stacking; it runs while the window is still off-screen, so there is no
+        # reposition flash.
+        if self._place is not None:
+            self._place(top)
+        # Apply positioning using WindowPositioning utilities
+        elif self._position:
+            # Support legacy geometry strings (e.g., "-25-75")
+            if self._position.startswith(('+', '-')):
+                # Legacy geometry string - use directly
+                top.geometry(self._position)
+            else:
+                # New positioning - assume it's a corner specification
+                # (future enhancement: could support more complex positioning)
+                top.geometry(self._position)
+        else:
+            # Default positioning based on platform
+            winsys = top.tk.call('tk', 'windowingsystem')
+            if winsys in ['win32', 'aqua']:
+                # Bottom-right corner
+                WindowPositioning.position_anchored(
+                    window=top,
+                    anchor_to="screen",
+                    parent=None,
+                    anchor_point="se",
+                    window_point="se",
+                    offset=(-25, -75),
+                    auto_flip=False,
+                    ensure_visible=True
+                )
+            else:
+                # Top-right corner for X11
+                WindowPositioning.position_anchored(
+                    window=top,
+                    anchor_to="screen",
+                    parent=None,
+                    anchor_point="ne",
+                    window_point="ne",
+                    offset=(-25, 25),
+                    auto_flip=False,
+                    ensure_visible=True
+                )
+
+        # ------ Other setup -------
+
+        if self._duration:
+            top.after(self._duration, self.hide)
+
+        if self._alert:
+            top.bell()
+
+        self._toplevel = top
+

bootstack/widgets/_impl/composites/toast_stack.py

@@ -0,0 +1,156 @@
+"""Positioning and stacking for the toast family.
+
+The public `toast()` / `Notification` / `Snackbar` facades share one process-wide
+manager that owns *where* a transient window lands and how several of them stack:
+
+- **Corner stacks** (toast, notification) float in a corner of the monitor the
+  app window currently sits on, newest nearest the corner, older ones offset
+  away. The stack re-flows when any member dismisses.
+- **Snackbar** anchors to the app window's own bottom edge, aligned left,
+  center, or right. Only one snackbar shows at a time; a new one replaces it.
+
+Geometry is computed by hand (no reliance on the engine's default placement) and
+applied through the engine's `place=` hook, so positioning happens while the
+window is still off-screen — no reposition flash.
+"""
+from __future__ import annotations
+
+import tkinter
+from typing import Literal
+
+from bootstack._runtime.app import get_default_root
+from bootstack._runtime.window_utilities import WindowPositioning
+
+Corner = Literal["top-left", "top-right", "bottom-left", "bottom-right"]
+Align = Literal["left", "center", "right"]
+
+CORNERS: tuple[Corner, ...] = ("top-left", "top-right", "bottom-left", "bottom-right")
+
+_MARGIN = 24  # px gap from the monitor / window edge
+_GAP = 12     # px gap between stacked windows
+
+
+def _alive(top: tkinter.Toplevel) -> bool:
+    """Whether a toast Toplevel still exists."""
+    try:
+        return bool(top.winfo_exists())
+    except tkinter.TclError:
+        return False
+
+
+def _monitor_rect() -> tuple[int, int, int, int]:
+    """`(x, y, w, h)` usable work area of the monitor the app window is on.
+
+    On macOS this is the visible frame (menu bar + Dock excluded) so a corner
+    toast never lands under the Dock; elsewhere it is the full monitor bounds.
+    Falls back to the full screen, then a fixed default.
+    """
+    root = get_default_root()
+    if root is not None:
+        try:
+            root.update_idletasks()
+            cx = root.winfo_rootx() + root.winfo_width() // 2
+            cy = root.winfo_rooty() + root.winfo_height() // 2
+            rect = WindowPositioning._get_monitor_at_point(cx, cy)
+            if rect is None:
+                rect = (0, 0, root.winfo_screenwidth(), root.winfo_screenheight())
+            return WindowPositioning.get_work_area(root, rect)
+        except tkinter.TclError:
+            pass
+    return (0, 0, 1920, 1080)
+
+
+class _ToastManager:
+    """Process-wide owner of corner stacks and the single active snackbar."""
+
+    def __init__(self) -> None:
+        self._corners: dict[Corner, list[tkinter.Toplevel]] = {c: [] for c in CORNERS}
+        self._snackbar: tkinter.Toplevel | None = None
+
+    # ----- corner stacks (toast / notification) --------------------------
+
+    def corner_placer(self, corner: Corner):
+        """Return a `place(top)` hook that slots `top` into `corner`'s stack."""
+        def _place(top: tkinter.Toplevel) -> None:
+            self._corners[corner].insert(0, top)  # newest nearest the corner
+            self._reflow(corner)
+        return _place
+
+    def remove(self, corner: Corner, top: tkinter.Toplevel) -> None:
+        """Drop `top` from its stack (on dismiss) and re-flow the rest."""
+        stack = self._corners.get(corner)
+        if stack is None:
+            return
+        self._corners[corner] = [t for t in stack if t is not top]
+        self._reflow(corner)
+
+    def _reflow(self, corner: Corner) -> None:
+        """Re-position every live window in a corner stack, in order."""
+        mx, my, mw, mh = _monitor_rect()
+        at_top = "top" in corner
+        at_right = "right" in corner
+        offset = _MARGIN
+        live: list[tkinter.Toplevel] = []
+        for top in self._corners[corner]:
+            if not _alive(top):
+                continue
+            live.append(top)
+            try:
+                top.update_idletasks()
+                w, h = top.winfo_width(), top.winfo_height()
+                x = (mx + mw - w - _MARGIN) if at_right else (mx + _MARGIN)
+                y = (my + offset) if at_top else (my + mh - h - offset)
+                top.geometry(f"+{int(x)}+{int(y)}")
+                offset += h + _GAP
+            except tkinter.TclError:
+                pass
+        self._corners[corner] = live
+
+    # ----- snackbar (single, app-window bottom edge) ---------------------
+
+    def snackbar_placer(self, align: Align):
+        """Return a `place(top)` hook that anchors `top` to the window bottom."""
+        def _place(top: tkinter.Toplevel) -> None:
+            if self._snackbar is not None and _alive(self._snackbar) and self._snackbar is not top:
+                try:
+                    self._snackbar.destroy()
+                except tkinter.TclError:
+                    pass
+            self._snackbar = top
+            self._position_snackbar(top, align)
+        return _place
+
+    def clear_snackbar(self, top: tkinter.Toplevel) -> None:
+        """Forget the active snackbar if it is `top` (on dismiss)."""
+        if self._snackbar is top:
+            self._snackbar = None
+
+    def _position_snackbar(self, top: tkinter.Toplevel, align: Align) -> None:
+        root = get_default_root()
+        if root is None:
+            return
+        try:
+            root.update_idletasks()
+            top.update_idletasks()
+            rx, ry = root.winfo_rootx(), root.winfo_rooty()
+            rw, rh = root.winfo_width(), root.winfo_height()
+            w, h = top.winfo_width(), top.winfo_height()
+            y = ry + rh - h - _MARGIN
+            if align == "left":
+                x = rx + _MARGIN
+            elif align == "right":
+                x = rx + rw - w - _MARGIN
+            else:  # center
+                x = rx + (rw - w) // 2
+            top.geometry(f"+{int(x)}+{int(y)}")
+        except tkinter.TclError:
+            pass
+
+
+# One manager for the whole process — toasts are app-global.
+_manager = _ToastManager()
+
+
+def get_toast_manager() -> _ToastManager:
+    """Return the process-wide toast manager."""
+    return _manager