bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/avatar.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable, Literal, overload, TYPE_CHECKING
+
+from bootstack.events import Event, Subscription
+from bootstack.streams import Stream
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.widgets._impl.composites.avatar import Avatar as _InternalAvatar
+from bootstack.widgets.types import AccentToken
+
+if TYPE_CHECKING:
+    from bootstack.images import Image
+
+AvatarShape = Literal["circle", "rounded", "square"]
+
+
+class Avatar(PublicWidgetBase):
+    """A small identity badge — a picture or initials on a filled tile.
+
+    Shows `image` cover-fit and clipped to the avatar shape; when no image is
+    given (or one fails to load), it falls back to initials on a `background`
+    tile. Initials come from `initials` if given, otherwise from `name` (the
+    first letters of the first and last words).
+
+    Args:
+        image: The picture to show — an `Image` handle, a file path, or a PIL
+            image. Omit to show initials instead.
+        name: A name to derive initials from, e.g. `'Ada Lovelace'` → `'AL'`.
+            Used when `image` is absent and `initials` is not given.
+        initials: Explicit initials (1–2 characters), overriding `name`.
+        size: The avatar's edge length in pixels (it is square). Default `40`.
+        shape: `'circle'` (default), `'rounded'`, or `'square'`.
+        background: Tile color behind initials (and the fallback when an image
+            can't load) — a theme color token or a hex string. Default
+            `'primary'`.
+        foreground: Initials text color — a theme color token or hex string.
+            Default `'white'`.
+        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`.
+    """
+
+    def __init__(
+        self,
+        image: "Image | str | Path | None" = None,
+        *,
+        name: str | None = None,
+        initials: str | None = None,
+        size: int = 40,
+        shape: AvatarShape = "circle",
+        background: AccentToken | str = "primary",
+        foreground: str = "white",
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+        tk_master = self._parent._child_master() if self._parent else None
+
+        self._source = self._coerce_image(image)
+        self._internal = _InternalAvatar(
+            tk_master, source=self._source, name=name, initials=initials,
+            size=size, shape=shape, background=background, foreground=foreground,
+        )
+        self._attach_to_parent(layout_kw)
+
+    @staticmethod
+    def _coerce_image(image: "Image | str | Path | None") -> Any:
+        if image is None:
+            return None
+        from bootstack.images import Image as _ImageHandle
+
+        if isinstance(image, _ImageHandle):
+            return image
+        if isinstance(image, (str, Path)):
+            return _ImageHandle.open(image)
+        try:
+            from PIL.Image import Image as _PILImage
+
+            if isinstance(image, _PILImage):
+                return _ImageHandle.from_pil(image)
+        except Exception:
+            pass
+        raise TypeError(
+            "Avatar image must be an Image handle, a file path, or a PIL image; "
+            f"got {type(image).__name__}"
+        )
+
+    # ----- Properties -----
+
+    @property
+    def image(self) -> "Image | None":
+        """The displayed image handle, or `None` when showing initials.
+
+        Assign an `Image`, a file path, or `None` to change what is shown.
+        """
+        return self._source
+
+    @image.setter
+    def image(self, value: "Image | str | Path | None") -> None:
+        self._source = self._coerce_image(value)
+        self._internal.set_source(self._source)
+
+    def set_initials(self, *, name: str | None = None, initials: str | None = None) -> None:
+        """Update the initials shown (when no image is set).
+
+        Args:
+            name: A name to derive initials from.
+            initials: Explicit initials, overriding `name`.
+        """
+        self._internal.set_text(name=name, initials=initials)
+
+    # ----- Events -----
+
+    @overload
+    def on_click(self) -> Stream: ...
+    @overload
+    def on_click(self, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on_click(
+        self, handler: Callable[[Event], Any] | None = None
+    ) -> Stream | Subscription:
+        """Register a callback for clicks on the avatar.
+
+        The handler receives a curated :class:`~bootstack.events.Event`.
+
+        Args:
+            handler: Called with the click `Event`. Omit to get a composable
+                :class:`~bootstack.streams.Stream`.
+
+        Returns:
+            A cancellable :class:`~bootstack.events.Subscription` when a handler
+            is given, otherwise a :class:`~bootstack.streams.Stream`.
+        """
+        return self.on("click", handler)
+
+
+register_widget_events(Avatar, {"click": "<<AvatarClick>>"})

bootstack/widgets/boolean_controls.py

@@ -0,0 +1,455 @@
+from __future__ import annotations
+
+from typing import overload, Any, Callable, TYPE_CHECKING
+
+from bootstack.widgets._impl.primitives.checkbutton import CheckButton as _InternalCheckButton
+from bootstack.widgets._impl.primitives.switch import Switch as _InternalSwitch
+from bootstack.widgets._impl.primitives.checktoggle import CheckToggle as _InternalCheckToggle
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.events import Subscription, ChangeEvent
+from bootstack.streams import Stream
+from bootstack.widgets.types import AccentToken, Event, WidgetDensity, ButtonVariant, LocalizeMode
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+_BOOLEAN_EVENTS: dict[str, str] = {
+    "change":   "<<Change>>",
+    "check":    "<<ToggleOn>>",
+    "uncheck":  "<<ToggleOff>>",
+}
+
+
+class _BooleanControlBase(PublicWidgetBase):
+    """Shared base for Checkbox, Switch, and ToggleButton."""
+
+    _internal_class: type  # set by subclass
+
+    def __init__(
+        self,
+        label: str = "",
+        *,
+        signal: "Signal | None" = None,
+        value: Any = None,
+        checked_value: Any = True,
+        unchecked_value: Any = False,
+        on_change: Callable[[], Any] | None = None,
+        disabled: bool = False,
+        accent: AccentToken | str | None = None,
+        localize: LocalizeMode | None = None,
+        _tristate: bool = False,
+        _internal_options: dict[str, Any] | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+        if kwargs:
+            raise TypeError(
+                f"{type(self).__name__}() got unexpected keyword argument(s): "
+                f"{', '.join(sorted(kwargs))}"
+            )
+        self._checked_value = checked_value
+        self._unchecked_value = unchecked_value
+        self._tristate = _tristate
+
+        tk_master = self._parent._child_master() if self._parent else None
+
+        # Ctor on_change callback — stored so the command wrapper can call it.
+        _ctor_callback = on_change
+
+        internal_kwargs: dict[str, Any] = {}
+        if label:
+            internal_kwargs["text"] = label
+        if signal is not None:
+            internal_kwargs["signal"] = signal
+        if checked_value is not True:
+            internal_kwargs["onvalue"] = checked_value
+        if unchecked_value is not False:
+            internal_kwargs["offvalue"] = unchecked_value
+        if disabled:
+            internal_kwargs["state"] = "disabled"
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if localize is not None:
+            internal_kwargs["localize"] = localize
+        # Per-subclass styling options (icons, variant, density, …) — only the
+        # ones a given control actually supports are passed in by the subclass.
+        if _internal_options:
+            internal_kwargs.update(_internal_options)
+
+        self._internal = self._internal_class(tk_master, **internal_kwargs)
+
+        # Seed initial value when no signal was passed.
+        # tristate=False: default to unchecked_value so the box never shows the
+        # indeterminate dash unexpectedly. tristate=True: leave unseeded so the
+        # initial state is None (indeterminate) unless value= was explicitly given.
+        if signal is None:
+            if value is not None:
+                self._internal.set(value)
+            elif not _tristate:
+                self._internal.set(unchecked_value)
+
+        # Track the previous value so on_change can report it. The control may be
+        # tristate (checked / unchecked / indeterminate), so prev cannot be derived
+        # from the new value alone — and the command fires after Tk updates the var.
+        self._prev_value = self._internal.get()
+
+        # Wire command → virtual events so on_change() / on_check() subscriptions work.
+        def _command():
+            v = self._internal.get()
+            prev, self._prev_value = self._prev_value, v
+            self._internal.event_generate(
+                "<<Change>>", data=ChangeEvent(value=v, prev_value=prev)
+            )
+            if v == self._checked_value:
+                self._internal.event_generate("<<ToggleOn>>")
+            else:
+                self._internal.event_generate("<<ToggleOff>>")
+            if _ctor_callback is not None:
+                _ctor_callback()
+
+        self._internal.configure(command=_command)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Properties -----
+
+    @property
+    def value(self) -> Any:
+        """The current value.
+
+        Returns `checked_value` when checked, `unchecked_value` when
+        unchecked, or `None` when in the indeterminate state (only possible
+        when `tristate=True`).
+        """
+        v = self._internal.get()
+        if v == self._checked_value:
+            return self._checked_value
+        if v == self._unchecked_value:
+            return self._unchecked_value
+        return None
+
+    @value.setter
+    def value(self, v: Any) -> None:
+        self._internal.set(v)
+
+    @property
+    def checked(self) -> bool:
+        """Whether the control is in the checked/on state."""
+        return self._internal.get() == self._checked_value
+
+    @checked.setter
+    def checked(self, v: bool) -> None:
+        self._internal.set(self._checked_value if v else self._internal.cget("offvalue"))
+
+    @property
+    def signal(self) -> "Signal | None":
+        """The reactive `Signal` linked to this control, or `None`."""
+        return getattr(self._internal, 'signal', None)
+
+    @property
+    def disabled(self) -> bool:
+        """Whether the control is non-interactive."""
+        return str(self._internal.cget("state")) == "disabled"
+
+    @disabled.setter
+    def disabled(self, v: bool) -> None:
+        self._internal.configure(state="disabled" if v else "normal")
+
+    # ----- Methods -----
+
+    def toggle(self) -> None:
+        """Toggle the control's state programmatically."""
+        self._internal.invoke()
+
+    # ----- 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 whenever the value changes.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.ChangeEvent`
+                carrying the new `value` and the `prev_value` (useful for
+                tristate controls). 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_check(self) -> Stream: ...
+    @overload
+    def on_check(self, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on_check(self, handler: Callable[[Event], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when the control becomes checked/selected.
+
+        Args:
+            handler: Called with the :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("check", handler)
+
+    @overload
+    def on_uncheck(self) -> Stream: ...
+    @overload
+    def on_uncheck(self, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on_uncheck(self, handler: Callable[[Event], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when the control becomes unchecked/deselected.
+
+        Args:
+            handler: Called with the :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("uncheck", handler)
+
+
+class Checkbox(_BooleanControlBase):
+    """A labeled checkbox — checked or unchecked.
+
+    The label is the first positional argument. All options are keyword-only.
+
+    Args:
+        label: Label text displayed beside the checkbox.
+        signal: Reactive `Signal` controlling the checked state. When
+            provided, `value=` is ignored — seed the Signal directly.
+        value: Initial value. Ignored when `signal=` is passed.
+        checked_value: Value representing the checked state. Defaults to
+            `True`.
+        unchecked_value: Value representing the unchecked state. Defaults
+            to `False`.
+        tristate: If `True`, enables a third indeterminate state. When
+            indeterminate the box shows a dash indicator and `value`
+            returns `None`. If no `value=` or `signal=` is provided,
+            the checkbox starts in the indeterminate state. Defaults to
+            `False`.
+        on_change: Shorthand callback fired on every toggle. Equivalent to
+            `checkbox.on_change(fn)`.
+        on_icon: Bootstrap Icons name shown when the checkbox is checked.
+            Pair with `off_icon=` to display different icons per state,
+            e.g. `on_icon="check-circle-fill", off_icon="circle"`.
+        off_icon: Bootstrap Icons name shown when the checkbox is unchecked.
+        icon_only: If `True`, hides the label text and shows only the icon.
+            Combine with `on_icon=`/`off_icon=` and
+            `show_indicator=False` for fully icon-driven checkboxes.
+        show_indicator: If `False`, hides the checkbox box indicator.
+            Useful when `on_icon=`/`off_icon=` serve as the visual cue.
+        disabled: If `True`, widget is non-interactive and dimmed.
+            Defaults to `False`.
+        accent: Accent token applied to the box and check mark.
+        parent: Explicit parent widget. If omitted, the current
+            context-stack container is used.
+        **kwargs: Layout placement options applied by the parent container —
+            `fill`, `expand`, `anchor`, `margin`, `row`, `column`, `sticky`.
+            See :doc:`/tasks/layout`.
+    """
+    _internal_class = _InternalCheckButton
+
+    def __init__(
+        self,
+        label: str = "",
+        *,
+        signal: "Signal | None" = None,
+        value: Any = None,
+        checked_value: Any = True,
+        unchecked_value: Any = False,
+        tristate: bool = False,
+        on_change: Callable[[], Any] | None = None,
+        on_icon: str | None = None,
+        off_icon: str | None = None,
+        icon_only: bool = False,
+        show_indicator: bool = True,
+        disabled: bool = False,
+        accent: AccentToken | str | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        options: dict[str, Any] = {}
+        if on_icon is not None:
+            options["on_icon"] = on_icon
+        if off_icon is not None:
+            options["off_icon"] = off_icon
+        if icon_only:
+            options["icon_only"] = True
+        if not show_indicator:
+            options["show_indicator"] = False
+        super().__init__(
+            label,
+            signal=signal,
+            value=value,
+            checked_value=checked_value,
+            unchecked_value=unchecked_value,
+            _tristate=tristate,
+            on_change=on_change,
+            disabled=disabled,
+            accent=accent,
+            _internal_options=options,
+            parent=parent,
+            **kwargs,
+        )
+
+
+class Switch(_BooleanControlBase):
+    """A toggle switch — on or off.
+
+    Renders as a sliding track-and-thumb control. Use in place of a checkbox
+    when the action takes effect immediately (e.g. enable/disable a setting).
+
+    Args:
+        label: Label text displayed beside the switch.
+        signal: Reactive `Signal` controlling the on/off state. When
+            provided, `value=` is ignored — seed the Signal directly.
+        value: Initial value. Ignored when `signal=` is passed.
+        checked_value: Value representing the on state. Defaults to
+            `True`.
+        unchecked_value: Value representing the off state. Defaults to
+            `False`.
+        on_change: Shorthand callback fired on every toggle. Equivalent to
+            `switch.on_change(fn)`.
+        disabled: If `True`, widget is non-interactive and dimmed.
+            Defaults to `False`.
+        accent: Accent token applied to the track when on.
+        parent: Explicit parent widget. If omitted, the current
+            context-stack container is used.
+        **kwargs: Layout placement options applied by the parent container —
+            `fill`, `expand`, `anchor`, `margin`, `row`, `column`, `sticky`.
+            See :doc:`/tasks/layout`.
+    """
+    _internal_class = _InternalSwitch
+
+    def __init__(
+        self,
+        label: str = "",
+        *,
+        signal: "Signal | None" = None,
+        value: Any = None,
+        checked_value: Any = True,
+        unchecked_value: Any = False,
+        on_change: Callable[[], Any] | None = None,
+        disabled: bool = False,
+        accent: AccentToken | str | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            label,
+            signal=signal,
+            value=value,
+            checked_value=checked_value,
+            unchecked_value=unchecked_value,
+            on_change=on_change,
+            disabled=disabled,
+            accent=accent,
+            parent=parent,
+            **kwargs,
+        )
+
+
+class ToggleButton(_BooleanControlBase):
+    """A button that stays pressed when active — toolbar-style toggle.
+
+    Renders as a depressed button rather than a checkbox or switch. Commonly
+    used in toolbars and button groups to represent a persistent on/off state.
+
+    Args:
+        text: Button text.
+        signal: Reactive `Signal` controlling the pressed state. When
+            provided, `value=` is ignored — seed the Signal directly.
+        value: Initial value. Ignored when `signal=` is passed.
+        checked_value: Value representing the pressed/active state. Defaults
+            to `True`.
+        unchecked_value: Value representing the unpressed/inactive state.
+            Defaults to `False`.
+        on_change: Shorthand callback fired on every toggle. Equivalent to
+            `btn.on_change(fn)`.
+        icon: Bootstrap Icons name shown in both states — the fallback for
+            `on_icon`/`off_icon` when those are not given. Pass `on_icon`/
+            `off_icon` to override the icon per state.
+        on_icon: Bootstrap Icons name shown when the button is active/pressed.
+            Use alone to swap icon on activation, or pair with `off_icon=`
+            to show different icons per state,
+            e.g. `on_icon="star-fill", off_icon="star"`. Falls back to `icon`.
+        off_icon: Bootstrap Icons name shown when the button is inactive.
+            Can be used alone or paired with `on_icon=`. Falls back to `icon`.
+        icon_only: If `True`, shows only the icon with no label text.
+            Requires `icon=`, `on_icon=`, or `off_icon=` to be set.
+        disabled: If `True`, widget is non-interactive and dimmed.
+            Defaults to `False`.
+        accent: Accent token applied to the button when active.
+        variant: Button style variant. Default `'solid'`.
+        density: Padding density.
+        parent: Explicit parent widget. If omitted, the current
+            context-stack container is used.
+        **kwargs: Layout placement options applied by the parent container —
+            `fill`, `expand`, `anchor`, `margin`, `row`, `column`, `sticky`.
+            See :doc:`/tasks/layout`.
+    """
+    _internal_class = _InternalCheckToggle
+
+    def __init__(
+        self,
+        text: str = "",
+        *,
+        signal: "Signal | None" = None,
+        value: Any = None,
+        checked_value: Any = True,
+        unchecked_value: Any = False,
+        on_change: Callable[[], Any] | None = None,
+        icon: str | None = None,
+        on_icon: str | None = None,
+        off_icon: str | None = None,
+        icon_only: bool = False,
+        disabled: bool = False,
+        accent: AccentToken | str | None = None,
+        variant: ButtonVariant = "default",
+        density: WidgetDensity | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        options: dict[str, Any] = {}
+        # `icon` is the fallback for both states; on_icon/off_icon override it.
+        resolved_on = on_icon if on_icon is not None else icon
+        resolved_off = off_icon if off_icon is not None else icon
+        if resolved_on is not None:
+            options["on_icon"] = resolved_on
+        if resolved_off is not None:
+            options["off_icon"] = resolved_off
+        if icon_only:
+            options["icon_only"] = True
+        if variant is not None:
+            options["variant"] = variant
+        if density is not None:
+            options["density"] = density
+        super().__init__(
+            text,
+            signal=signal,
+            value=value,
+            checked_value=checked_value,
+            unchecked_value=unchecked_value,
+            on_change=on_change,
+            disabled=disabled,
+            accent=accent,
+            _internal_options=options,
+            parent=parent,
+            **kwargs,
+        )
+
+
+register_widget_events(Checkbox, _BOOLEAN_EVENTS)
+register_widget_events(Switch, _BOOLEAN_EVENTS)
+register_widget_events(ToggleButton, _BOOLEAN_EVENTS)