bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/timefield.py

@@ -0,0 +1,340 @@
+from __future__ import annotations
+
+import datetime
+import tkinter
+from typing import overload, Any, Callable, TYPE_CHECKING
+
+from bootstack.widgets._impl.composites.timeentry import TimeEntry as _InternalTimeEntry
+from bootstack.widgets._core.base import PublicWidgetBase, adapt_handler
+from bootstack.widgets._core.events import resolve_event, register_widget_events
+from bootstack.widgets._core.field_mixin import FieldAddonMixin, ValueSignalMixin
+from bootstack.events import ChangeEvent, Subscription, ValidationEvent
+from bootstack.streams import Stream
+from bootstack.widgets.textfield import _INNER_ENTRY_SEQUENCES
+from bootstack.widgets.types import AccentToken, Event, WidgetDensity
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+_TIME_FIELD_EVENTS: dict[str, str] = {
+    "change":   "<<Change>>",
+    "validate": "<<Validate>>",
+    "valid":    "<<Valid>>",
+    "invalid":  "<<Invalid>>",
+    "submit":   "<Return>",
+    "focus":    "<FocusIn>",
+    "blur":     "<FocusOut>",
+}
+
+
+class TimeField(ValueSignalMixin, FieldAddonMixin, PublicWidgetBase):
+    """A time-input field with a searchable dropdown of time intervals.
+
+    Displays a formatted time value and shows a dropdown list of times at
+    the specified `interval`. The user can type a custom time or pick from
+    the list.
+
+    Args:
+        value: Initial time value — a `datetime.time` object or a time
+            string (e.g. `'14:30'` or `'2:30 PM'`). Empty by default; pass a
+            value to seed a starting time.
+        value_format: Format applied to the displayed time — a named preset
+            (e.g. `'shortTime'`, `'longTime'`) or a custom pattern (e.g.
+            `'HH:mm'`, `'h:mm a'`). Default `'shortTime'`. See
+            :ref:`format specs <value-formats>`.
+        interval: Minute interval for dropdown entries. Default `30`.
+        min_time: Earliest time shown in the dropdown.
+        max_time: Latest time shown in the dropdown.
+        label: Label displayed above the field.
+        message: Hint text displayed below the field.
+        signal: Reactive `Signal` two-way bound to the field's `time` value (not
+            its text). When given, it seeds the initial value. This is the usual
+            way to bind a time field.
+        required: If `True`, field cannot be left empty.
+        disabled: If `True`, field is non-interactive.
+        read_only: If `True`, free-text entry is blocked; user must pick
+            from the dropdown.
+        width: Width in character cells.
+        accent: Accent color applied to the focus ring. Default `'primary'`.
+        density: Widget density.
+        parent: Override the context-stack parent.
+        **kwargs: Layout placement options applied by the parent container —
+            `fill`, `expand`, `anchor`, `margin`, `row`, `column`, `sticky`.
+            See :doc:`/tasks/layout`.
+    """
+
+    _VALIDATION_KIND = "time"
+
+    def __init__(
+        self,
+        value: datetime.time | str | None = None,
+        *,
+        signal: "Signal | None" = None,
+        value_format: str = "shortTime",
+        interval: int = 30,
+        min_time: datetime.time | str | None = None,
+        max_time: datetime.time | str | None = None,
+        label: str | None = None,
+        message: str | None = None,
+        required: bool = False,
+        disabled: bool = False,
+        read_only: bool = False,
+        width: int | None = None,
+        accent: AccentToken | str | None = None,
+        density: WidgetDensity | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+        if "textsignal" in kwargs:
+            raise TypeError(
+                "TimeField does not accept 'textsignal=' — a time field binds its "
+                "time value. Use signal= with a time-typed Signal "
+                "(e.g. Signal(time(9, 0)))."
+            )
+        tk_master = self._parent._child_master() if self._parent else None
+
+        internal_kwargs: dict[str, Any] = {
+            "value_format": value_format,
+            "interval": interval,
+        }
+        if value is not None:
+            internal_kwargs["value"] = value
+        if min_time is not None:
+            internal_kwargs["min_time"] = min_time
+        if max_time is not None:
+            internal_kwargs["max_time"] = max_time
+        if label is not None:
+            internal_kwargs["label"] = label
+        if message is not None:
+            internal_kwargs["message"] = message
+        if required:
+            internal_kwargs["required"] = True
+        if disabled:
+            internal_kwargs["state"] = "disabled"
+        elif read_only:
+            internal_kwargs["state"] = "readonly"
+        if width is not None:
+            internal_kwargs["width"] = width
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if density is not None:
+            internal_kwargs["density"] = density
+
+        self._internal = _InternalTimeEntry(tk_master, **internal_kwargs)
+        self._attach_to_parent(layout_kw)
+
+        if signal is not None:
+            self._bind_value_signal(signal)
+
+    # ----- Event routing -----
+
+    def _entry_widget(self) -> tkinter.Misc:
+        return self._internal._entry
+
+    @overload
+    def on(self, event: str) -> Stream: ...
+    @overload
+    def on(self, event: str, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on(self, event: str, handler: Callable[[Event], Any] | None = None) -> Stream | Subscription:
+        """Register a callback for an event by name.
+
+        A generic, string-keyed escape hatch — prefer the typed `on_*`
+        shorthands (e.g. `on_change`), which carry the precise payload type.
+        Called with no handler, returns a composable `Stream`; with a handler,
+        binds it and returns a `Subscription`.
+
+        Args:
+            event: Event name (for example `'change'` or `'focus'`).
+            handler: Called with the event payload. Omit to get a composable
+                :class:`~bootstack.streams.Stream` instead.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a handler
+            is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        sequence = resolve_event(self, str(event))
+        widget = self._entry_widget() if sequence in _INNER_ENTRY_SEQUENCES else self._internal
+        if handler is None:
+            from bootstack.streams import Stream as _Stream
+            def _source(h):
+                _w = self._entry_widget() if sequence in _INNER_ENTRY_SEQUENCES else self._internal
+                _bid = _w.bind(sequence, adapt_handler(h), add="+")
+                return Subscription(_w, sequence, _bid)
+            return _Stream(self._internal, _source=_source)
+        bind_id = widget.bind(sequence, adapt_handler(handler), add="+")
+        return Subscription(widget, sequence, bind_id)
+
+    # ----- Properties -----
+
+    @property
+    def value(self) -> "datetime.time | None":
+        """Current time value, or `None` if the field is empty."""
+        return self._internal.value
+
+    @value.setter
+    def value(self, v: "datetime.time | str | None") -> None:
+        self._internal.value = v
+        self._sync_value_set(self._internal.value)
+
+    @property
+    def disabled(self) -> bool:
+        """Whether the field is disabled (non-interactive and greyed out)."""
+        return self._internal._entry.instate(("disabled",))
+
+    @disabled.setter
+    def disabled(self, v: bool) -> None:
+        self._internal.configure(state="disabled" if v else "normal")
+
+    @property
+    def read_only(self) -> bool:
+        """Whether the field is read-only (selectable but not editable)."""
+        return self._internal._entry.instate(("readonly",))
+
+    @read_only.setter
+    def read_only(self, v: bool) -> None:
+        self._internal.configure(state="readonly" if v else "normal")
+
+    # ----- Methods -----
+
+    def validate(self) -> bool:
+        """Run validation rules against the current value.
+
+        Returns:
+            `True` if all rules pass, `False` otherwise.
+        """
+        entry = self._internal._entry
+        return entry.validate(entry._get_validation_value(), trigger="manual")
+
+    def focus(self) -> None:
+        """Give keyboard focus to this field."""
+        self._entry_widget().focus_set()
+
+    def clear(self) -> None:
+        """Clear the field, setting the value to `None`."""
+        self._internal.value = None
+
+    # ----- Event shorthands -----
+
+    @overload
+    def on_change(self) -> Stream: ...
+    @overload
+    def on_change(self, handler: Callable[[ChangeEvent], Any]) -> Subscription: ...
+    def on_change(self, handler: Callable[[ChangeEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when the time value changes.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.ChangeEvent`. Omit to
+                get a composable :class:`~bootstack.streams.Stream` instead.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a
+            handler is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("change", handler)
+
+    @overload
+    def on_submit(self) -> Stream: ...
+    @overload
+    def on_submit(self, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on_submit(self, handler: Callable[[Event], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when the user presses Return to confirm input.
+
+        Args:
+            handler: Called with an :class:`~bootstack.events.Event`. Omit to
+                get a composable :class:`~bootstack.streams.Stream` instead.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a
+            handler is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("submit", handler)
+
+    @overload
+    def on_valid(self) -> Stream: ...
+    @overload
+    def on_valid(self, handler: Callable[[ValidationEvent], Any]) -> Subscription: ...
+    def on_valid(self, handler: Callable[[ValidationEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when validation passes.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.ValidationEvent`. Omit to
+                get a composable :class:`~bootstack.streams.Stream` instead.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a
+            handler is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("valid", handler)
+
+    @overload
+    def on_invalid(self) -> Stream: ...
+    @overload
+    def on_invalid(self, handler: Callable[[ValidationEvent], Any]) -> Subscription: ...
+    def on_invalid(self, handler: Callable[[ValidationEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when validation fails.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.ValidationEvent`. Omit to
+                get a composable :class:`~bootstack.streams.Stream` instead.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a
+            handler is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("invalid", handler)
+
+    @overload
+    def on_validate(self) -> Stream: ...
+    @overload
+    def on_validate(self, handler: Callable[[ValidationEvent], Any]) -> Subscription: ...
+    def on_validate(self, handler: Callable[[ValidationEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when a validation check runs.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.ValidationEvent`. Omit to
+                get a composable :class:`~bootstack.streams.Stream` instead.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a
+            handler is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("validate", handler)
+
+    @overload
+    def on_focus(self) -> Stream: ...
+    @overload
+    def on_focus(self, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on_focus(self, handler: Callable[[Event], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when the field gains keyboard focus.
+
+        Args:
+            handler: Called with an :class:`~bootstack.events.Event`. Omit to
+                get a composable :class:`~bootstack.streams.Stream` instead.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a
+            handler is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("focus", handler)
+
+    @overload
+    def on_blur(self) -> Stream: ...
+    @overload
+    def on_blur(self, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on_blur(self, handler: Callable[[Event], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when the field loses keyboard focus.
+
+        Args:
+            handler: Called with an :class:`~bootstack.events.Event`. Omit to
+                get a composable :class:`~bootstack.streams.Stream` instead.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a
+            handler is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("blur", handler)
+
+
+register_widget_events(TimeField, _TIME_FIELD_EVENTS)

bootstack/widgets/toast.py

@@ -0,0 +1,314 @@
+"""Transient message surfaces: toast, notification, and snackbar.
+
+Three opinionated, single-purpose facades over the shared internal toast engine:
+
+- `toast()` — a passive, auto-dismissing message that floats in a screen corner
+  and stacks. Fire-and-forget.
+- `Notification` — a persistent corner message with a close button; the user
+  decides when it goes away. Stacks alongside toasts.
+- `Snackbar` / `snackbar()` — a transient message bound to the app window's
+  bottom edge with an optional single action (e.g. *Undo*). Only one shows at a
+  time; a new one replaces it.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from bootstack.widgets._impl.composites.toast import Toast as _InternalToast
+from bootstack.widgets._impl.composites.toast_stack import get_toast_manager
+from bootstack.widgets.types import AccentToken, Icon, ToastCorner, SnackbarAlign
+
+_TOAST_DEFAULT_DURATION = 4000
+_SNACKBAR_DEFAULT_DURATION = 5000
+
+
+def _windowing_system() -> str:
+    """The active Tk windowing system (`'win32'`, `'aqua'`, or `'x11'`)."""
+    from bootstack._runtime.app import get_default_root
+
+    root = get_default_root()
+    if root is not None:
+        try:
+            return root.tk.call("tk", "windowingsystem")
+        except Exception:
+            pass
+    return "win32"
+
+
+def _resolve_corner(corner: ToastCorner | None, *, persistent: bool) -> ToastCorner:
+    """Resolve the default corner for a toast or notification.
+
+    Notifications default to the top-right everywhere. Passive toasts default to
+    the bottom-right on Windows and macOS, and the top-right on Linux (X11),
+    matching each platform's native notification placement.
+    """
+    if corner is not None:
+        return corner
+    if persistent:
+        return "top-right"
+    return "bottom-right" if _windowing_system() in ("win32", "aqua") else "top-right"
+
+
+# ---------------------------------------------------------------------------
+# toast() — passive, auto-dismiss, stacks in a screen corner
+# ---------------------------------------------------------------------------
+
+def toast(
+    message: str,
+    *,
+    title: str | None = None,
+    corner: ToastCorner | None = None,
+    duration: int = _TOAST_DEFAULT_DURATION,
+    accent: AccentToken | str | None = None,
+    icon: Icon | None = None,
+    on_dismiss: Callable[[], Any] | None = None,
+) -> None:
+    """Show a passive toast that dismisses itself, and return immediately.
+
+    A toast is the lightest notification — "the app telling you something" with
+    no demand for a response. It floats in a corner of the monitor the app
+    window is on, stacks below any toasts already there, and fades after
+    `duration`. For a message the user must dismiss, use `Notification`; for one
+    tied to the window with an action, use `Snackbar`.
+
+    Args:
+        message: Body text of the toast.
+        title: Optional header shown above the message.
+        corner: Screen corner to anchor to — `'top-left'`, `'top-right'`,
+            `'bottom-left'`, or `'bottom-right'`. Defaults to the bottom-right
+            (top-right on Linux).
+        duration: Time on screen in milliseconds before it auto-dismisses.
+            Defaults to `4000`.
+        accent: Semantic color accent (e.g. `'success'`, `'danger'`). Defaults
+            to a neutral surface.
+        icon: Optional Bootstrap Icons name (e.g. `'check-circle'`) or an icon
+            spec dict with `name`, `size`, and `color`, shown before the message.
+            No icon is shown unless given.
+        on_dismiss: Called with no arguments when the toast dismisses.
+    """
+    manager = get_toast_manager()
+    resolved = _resolve_corner(corner, persistent=False)
+
+    engine = _InternalToast(
+        title=title,
+        message=message,
+        icon=icon,
+        accent=accent,
+        duration=duration,
+        show_close_button=False,
+        place=manager.corner_placer(resolved),
+    )
+
+    def _on_dismissed(_data: Any) -> None:
+        manager.remove(resolved, engine._toplevel)
+        if on_dismiss is not None:
+            on_dismiss()
+
+    engine.configure(on_dismissed=_on_dismissed)
+    engine.show()
+
+
+# ---------------------------------------------------------------------------
+# Notification — persistent, close button, stacks in a screen corner
+# ---------------------------------------------------------------------------
+
+class Notification:
+    """A persistent corner message the user closes themselves.
+
+    Like a toast, a notification floats in a screen corner and stacks — but it
+    does not auto-dismiss. It carries a close button and stays until the user
+    closes it or your code calls `dismiss()`. Use it for information that should
+    persist (a finished background job, an available update) rather than flash
+    by. Build it, then call `show()`.
+
+    Notifications are message-only — for a response, use a `Snackbar` action or
+    a dialog.
+
+    Args:
+        title: Header text — the notification's headline.
+        message: Body text shown below the title.
+        detail: Small muted metadata shown in the header (e.g. `'just now'`).
+        corner: Screen corner to anchor to — `'top-left'`, `'top-right'`,
+            `'bottom-left'`, or `'bottom-right'`. Defaults to the top-right.
+        accent: Semantic color accent. Defaults to a neutral surface.
+        icon: Optional Bootstrap Icons name or an icon spec dict, shown before
+            the title. No icon is shown unless given.
+        on_dismiss: Called with no arguments when the notification closes.
+    """
+
+    def __init__(
+        self,
+        title: str | None = None,
+        *,
+        message: str | None = None,
+        detail: str | None = None,
+        corner: ToastCorner | None = None,
+        accent: AccentToken | str | None = None,
+        icon: Icon | None = None,
+        on_dismiss: Callable[[], Any] | None = None,
+    ) -> None:
+        self._title = title
+        self._message = message
+        self._detail = detail
+        self._corner = corner
+        self._accent = accent
+        self._icon = icon
+        self._on_dismiss = on_dismiss
+        self._engine: _InternalToast | None = None
+
+    def show(self) -> "Notification":
+        """Display the notification. Returns `self` for chaining."""
+        manager = get_toast_manager()
+        resolved = _resolve_corner(self._corner, persistent=True)
+
+        engine = _InternalToast(
+            title=self._title,
+            message=self._message,
+            memo=self._detail,
+            icon=self._icon,
+            accent=self._accent,
+            duration=None,
+            show_close_button=True,
+            place=manager.corner_placer(resolved),
+        )
+
+        def _on_dismissed(_data: Any) -> None:
+            manager.remove(resolved, engine._toplevel)
+            if self._on_dismiss is not None:
+                self._on_dismiss()
+
+        engine.configure(on_dismissed=_on_dismissed)
+        self._engine = engine
+        engine.show()
+        return self
+
+    def dismiss(self) -> None:
+        """Close the notification immediately."""
+        if self._engine is not None:
+            self._engine.hide()
+
+
+# ---------------------------------------------------------------------------
+# Snackbar — transient, one action, anchored to the window bottom edge
+# ---------------------------------------------------------------------------
+
+class Snackbar:
+    """A transient message at the app window's bottom edge with one action.
+
+    A snackbar belongs to the app, not the screen: it slides up from the bottom
+    of the window and moves with it. It is for brief, in-context feedback that
+    may offer a single response — the classic *"Message archived. [Undo]"*. Only
+    one snackbar shows at a time; showing another replaces it. Build it, then
+    call `show()`.
+
+    Args:
+        message: Body text of the snackbar.
+        action: Label for the optional action button (e.g. `'Undo'`). Omit for
+            a message with no action.
+        on_action: Called with no arguments when the action button is pressed.
+            The snackbar dismisses afterward.
+        align: Horizontal placement along the window's bottom edge — `'left'`,
+            `'center'`, or `'right'`. Defaults to `'center'`.
+        duration: Time on screen in milliseconds before it auto-dismisses.
+            Defaults to `5000`.
+        accent: Semantic color accent for the action button (the surface stays
+            neutral — severity coloring belongs to `toast`/`Notification`).
+            Defaults to `'primary'`. No effect without an `action`.
+        on_dismiss: Called with no arguments when the snackbar dismisses (whether
+            by timeout, the action, or `dismiss()`).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        action: str | None = None,
+        on_action: Callable[[], Any] | None = None,
+        align: SnackbarAlign = "center",
+        duration: int = _SNACKBAR_DEFAULT_DURATION,
+        accent: AccentToken | str | None = None,
+        on_dismiss: Callable[[], Any] | None = None,
+    ) -> None:
+        self._message = message
+        self._action = action
+        self._on_action = on_action
+        self._align = align
+        self._duration = duration
+        self._accent = accent
+        self._on_dismiss = on_dismiss
+        self._engine: _InternalToast | None = None
+
+    def show(self) -> "Snackbar":
+        """Display the snackbar, replacing any current one. Returns `self`."""
+        manager = get_toast_manager()
+
+        buttons = None
+        if self._action is not None:
+            buttons = [{
+                "text": self._action,
+                "command": self._on_action,
+                "variant": "ghost",
+                "accent": self._accent or "primary",
+            }]
+
+        # Neutral surface (no accent) and no icon — a snackbar is in-app action
+        # feedback, not a severity message. The accent rides only on the action.
+        engine = _InternalToast(
+            message=self._message,
+            duration=self._duration,
+            show_close_button=False,
+            buttons=buttons,
+            place=manager.snackbar_placer(self._align),
+        )
+
+        def _on_dismissed(_data: Any) -> None:
+            manager.clear_snackbar(engine._toplevel)
+            if self._on_dismiss is not None:
+                self._on_dismiss()
+
+        engine.configure(on_dismissed=_on_dismissed)
+        self._engine = engine
+        engine.show()
+        return self
+
+    def dismiss(self) -> None:
+        """Dismiss the snackbar immediately."""
+        if self._engine is not None:
+            self._engine.hide()
+
+
+def snackbar(
+    message: str,
+    *,
+    action: str | None = None,
+    on_action: Callable[[], Any] | None = None,
+    align: SnackbarAlign = "center",
+    duration: int = _SNACKBAR_DEFAULT_DURATION,
+    accent: AccentToken | str | None = None,
+    on_dismiss: Callable[[], Any] | None = None,
+) -> None:
+    """Show a snackbar at the window's bottom edge, and return immediately.
+
+    The one-line form of `Snackbar` — see it for the full description. Use the
+    class when you need a handle to `dismiss()` early.
+
+    Args:
+        message: Body text of the snackbar.
+        action: Label for the optional action button (e.g. `'Undo'`).
+        on_action: Called with no arguments when the action is pressed.
+        align: Bottom-edge alignment — `'left'`, `'center'`, or `'right'`.
+            Defaults to `'center'`.
+        duration: Time on screen in milliseconds. Defaults to `5000`.
+        accent: Semantic color accent for the action button (the surface stays
+            neutral). No effect without an `action`.
+        on_dismiss: Called with no arguments when the snackbar dismisses.
+    """
+    Snackbar(
+        message,
+        action=action,
+        on_action=on_action,
+        align=align,
+        duration=duration,
+        accent=accent,
+        on_dismiss=on_dismiss,
+    ).show()