bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/button.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+
+from typing import Any, Callable, TYPE_CHECKING, overload
+
+from bootstack.widgets._impl.primitives.button import Button as _InternalButton
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.widgets._core.icon_image_props import IconProperty, ImageProperty
+from bootstack.events import Event, Subscription
+from bootstack.streams import Stream
+from bootstack.widgets.types import AccentToken, WidgetDensity, IconPosition, ButtonVariant, IconSpec, LocalizeMode, SurfaceToken
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class Button(IconProperty, ImageProperty, PublicWidgetBase):
+    """A clickable action trigger.
+
+    The button text is the first positional argument. All styling and
+    behavior options are keyword-only.
+
+    Args:
+        text: Text displayed on the button.
+        on_click: Called with no arguments when the button is clicked.
+            Equivalent to subscribing to the `'click'` event.
+        accent: Color intent token. Defaults to the theme's default button color.
+        variant: Visual weight token. Default `'solid'`.
+        icon: Bootstrap Icons name (e.g. `'save'`, `'trash'`) — see the full
+            catalog at https://icons.getbootstrap.com — or an `IconSpec` mapping
+            (`{'name', 'size', 'color'}`) for control over size and color.
+        icon_only: If `True`, show only the icon with no text. Inferred
+            automatically when `icon=` is set and no text is provided. Set
+            meaningful `text` anyway for accessibility.
+        icon_position: Position of the icon or image relative to the text.
+            Default `'left'`.
+        image: An `Image` handle (from `bootstack.images`) to display on the
+            button, for custom artwork rather than a Bootstrap Icon name. Also
+            accepts a `get_icon` result.
+        width: Button width in character units. Useful for making a row of
+            buttons uniform width (e.g. `width=10`).
+        textsignal: Reactive `Signal[str]` bound to the button text. Updates
+            automatically when the signal changes.
+        surface: The background the button is placed on — `'content'`, `'card'`,
+            `'card_raised'`, `'chrome'`, or `'overlay'`. Set it so a
+            `ghost`/`outline` button looks right on a non-default container (e.g.
+            a toolbar sets `'chrome'` on the buttons it builds). A build-time
+            setting, not a live property. Defaults to the theme's content
+            surface.
+        density: Padding density.
+        disabled: If `True`, the button is non-interactive and visually dimmed.
+        localize: Whether the text is translated through the catalog — `True`,
+            `False`, or `'auto'`. Defaults to the app's `localize_mode`. Set
+            `False` to keep a proper noun or identifier untranslated.
+        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`.
+    """
+
+    def __init__(
+        self,
+        text: str = "",
+        *,
+        on_click: Callable[[], Any] | None = None,
+        accent: AccentToken | str | None = None,
+        variant: ButtonVariant = "default",
+        icon: str | IconSpec | None = None,
+        icon_only: bool = False,
+        icon_position: IconPosition = "left",
+        image: Any = None,
+        width: int | None = None,
+        textsignal: "Signal[str] | None" = None,
+        surface: SurfaceToken | str | None = None,
+        density: WidgetDensity | None = None,
+        disabled: bool = False,
+        localize: LocalizeMode | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._reject_signal_text(text)
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+        tk_master = self._parent._child_master() if self._parent else None
+
+        if icon is not None and not text:
+            icon_only = True
+
+        # The internal command is always our dispatcher so that a click —
+        # whether by mouse, keyboard (Space/Return), or click()/invoke() — runs
+        # the on_click= callback AND emits <<Click>> for on_click() subscribers,
+        # consistently and only when the button is enabled (ttk gates the
+        # command on state, unlike a raw <Button-1> binding).
+        self._on_click_cmd = on_click
+
+        internal_kwargs: dict[str, Any] = {"text": text, "command": self._dispatch_click}
+        if not icon_only:
+            internal_kwargs["compound"] = icon_position
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if variant is not None:
+            internal_kwargs["variant"] = variant
+        if icon is not None:
+            internal_kwargs["icon"] = icon
+        if icon_only:
+            internal_kwargs["icon_only"] = True
+        deferred_image = None
+        if image is not None:
+            from bootstack.images import Image as _ImageHandle
+
+            if isinstance(image, _ImageHandle):
+                deferred_image = image
+            else:
+                internal_kwargs["image"] = image
+        if width is not None:
+            internal_kwargs["width"] = width
+        if textsignal is not None:
+            internal_kwargs["textsignal"] = textsignal
+        if surface is not None:
+            internal_kwargs["surface"] = surface
+        if density is not None:
+            internal_kwargs["density"] = density
+        if disabled:
+            internal_kwargs["state"] = "disabled"
+        if localize is not None:
+            internal_kwargs["localize"] = localize
+
+        self._internal = _InternalButton(tk_master, **internal_kwargs)
+        if deferred_image is not None:
+            from bootstack.widgets._core.image_binding import bind_image
+
+            bind_image(self, self._internal, deferred_image)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Properties -----
+
+    @property
+    def text(self) -> str:
+        """The button's text."""
+        # cget('text') reliably reflects a bound textvariable too (ttk keeps the
+        # option synced from the variable), so this is the live value either way.
+        return str(self._internal.cget("text"))
+
+    @text.setter
+    def text(self, value: str) -> None:
+        # When a textsignal/textvariable owns the text, ttk ignores the `text`
+        # option — write through the variable instead (which also keeps the
+        # bound signal in sync). Falls back to the option when unbound.
+        textvar = getattr(self._internal, "_textvariable", None)
+        if textvar is not None:
+            textvar.set(value)
+        else:
+            self._internal.configure(text=value)
+
+    @property
+    def disabled(self) -> bool:
+        """Whether the button is non-interactive."""
+        return str(self._internal.cget("state")) == "disabled"
+
+    @disabled.setter
+    def disabled(self, value: bool) -> None:
+        self._internal.configure(state="disabled" if value else "normal")
+
+    # ----- Methods -----
+
+    def click(self) -> None:
+        """Programmatically activate the button.
+
+        Runs the same path as a real click: the `on_click=` callback and any
+        `on_click()` handlers both fire. Does nothing while the button is
+        disabled.
+        """
+        self._internal.invoke()
+
+    def _dispatch_click(self) -> None:
+        """ttk command target — runs on every activation, never while disabled.
+
+        Fires on mouse release over the button, keyboard Space/Return, and
+        `click()`/`invoke()`. Runs the constructor `on_click=` callback, then
+        emits `<<Click>>` so `on_click()` subscribers see the same activation.
+        """
+        if self._on_click_cmd is not None:
+            self._on_click_cmd()
+        # `when='now'` delivers to subscribers synchronously, so a click()/invoke()
+        # notifies handlers before it returns (matches the on_click= callback).
+        self._internal.event_generate("<<Click>>", when="now")
+
+    # ----- 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 button click events.
+
+        Called with no handler, returns a composable `Stream`. Called with a
+        handler, binds it immediately and returns a `Subscription`.
+
+        Fires on activation — a mouse release over the button, a keyboard
+        Space/Return while focused, or :meth:`click`/`invoke` — and never while
+        the button is disabled, matching the `on_click=` constructor argument.
+        For a simple no-argument action prefer that constructor argument; use
+        this method (or its `Stream`) to compose the click event.
+
+        Args:
+            handler: Called with the click :class:`~bootstack.events.Event`.
+                The event marks the activation; because keyboard and
+                programmatic activations carry no pointer, treat position and
+                modifier fields as unset. Omit the handler 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)
+
+
+# "click" resolves to the <<Click>> virtual event emitted by the command
+# dispatcher (see _dispatch_click) rather than the global <Button-1> mapping, so
+# both the handler and Stream forms fire on activation and honor disabled state.
+register_widget_events(Button, {"click": "<<Click>>"})

bootstack/widgets/buttongroup.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Literal, overload
+
+from bootstack.widgets._impl.composites.buttongroup import ButtonGroup as _InternalButtonGroup
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.events import ButtonGroupClickEvent, Subscription
+from bootstack.streams import Stream
+from bootstack.widgets.types import AccentToken, Event, WidgetDensity, Orient, IconPosition, ButtonVariant
+
+_BUTTONGROUP_EVENTS: dict[str, str] = {
+    "click": "<<BsButtonGroupClick>>",
+}
+
+
+class ButtonGroup(PublicWidgetBase):
+    """A row (or column) of visually-connected buttons sharing accent and variant.
+
+    Buttons are added via `add()` or `add_all()`. The group propagates
+    `accent`, `variant`, and `density` to every member automatically.
+    Listen for any button press with `on_click()`, which receives the key
+    of the clicked button.
+
+    Args:
+        orient: Layout orientation. Default `'horizontal'`.
+        accent: Accent token applied to all buttons.
+        variant: Style variant. Default `'solid'`.
+        density: Widget density. Default `'default'`.
+        disabled: If `True`, all buttons are non-interactive.
+        localize: Whether button labels are translated through the catalog —
+            `True`, `False`, or `'auto'` (translate when a translation is
+            registered, otherwise show the literal). Defaults to the app's
+            `localize_mode`. Set `False` to keep proper nouns untranslated;
+            override a single button with `add(..., localize=...)`.
+        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,
+        orient: Orient = "horizontal",
+        *,
+        accent: AccentToken | str | None = None,
+        variant: ButtonVariant = "default",
+        density: WidgetDensity = "default",
+        disabled: bool = False,
+        localize: bool | Literal['auto'] | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._localize = localize
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+        tk_master = self._parent._child_master() if self._parent else None
+
+        internal_kwargs: dict[str, Any] = {
+            "orient": orient,
+            "variant": variant,
+            "density": density,
+        }
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if disabled:
+            internal_kwargs["state"] = "disabled"
+
+        self._internal = _InternalButtonGroup(tk_master, **internal_kwargs)
+        self._key_counter = 0
+        self._attach_to_parent(layout_kw)
+
+    # ----- Item management -----
+
+    def add(
+        self,
+        label: str = "",
+        *,
+        key: str | None = None,
+        icon: str | None = None,
+        icon_position: IconPosition = "left",
+        disabled: bool = False,
+        localize: bool | Literal['auto'] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Add a button to the group.
+
+        Args:
+            label: Button label text.
+            key: Unique string key. Auto-generated if omitted.
+            icon: Bootstrap Icons name (e.g. `'save'`, `'trash'`).
+            icon_position: Position of the icon relative to the label. Ignored
+                when `icon_only` is inferred or explicitly set. Default `'left'`.
+            disabled: If `True`, this button starts disabled.
+            localize: Translation mode for this button's label, overriding the
+                group's `localize=`. Defaults to the group setting.
+
+        Returns:
+            The key assigned to this button.
+        """
+        if key is None:
+            key = f"widget_{self._key_counter}"
+            self._key_counter += 1
+
+        icon_only = icon is not None and not label
+
+        btn_kwargs: dict[str, Any] = {}
+        if icon is not None:
+            btn_kwargs["icon"] = icon
+        if icon_only:
+            btn_kwargs["icon_only"] = True
+        elif icon is not None:
+            btn_kwargs["compound"] = icon_position
+        if disabled:
+            btn_kwargs["state"] = "disabled"
+        item_localize = localize if localize is not None else self._localize
+        if item_localize is not None:
+            btn_kwargs["localize"] = item_localize
+        btn_kwargs.update(kwargs)
+
+        _key = key
+        _group = self
+
+        def _command() -> None:
+            btn = _group._internal.item(_key)
+            _group.emit("click", data=ButtonGroupClickEvent(
+                key=_key,
+                text=str(btn.cget("text") or ""),
+                icon=btn.configure_style_options("icon"),
+            ))
+
+        self._internal.add(label or None, key=key, command=_command, **btn_kwargs)
+        return key
+
+    def add_all(self, items: list) -> list[str]:
+        """Add multiple buttons at once.
+
+        Each item is either a label string or a dict of keyword arguments
+        accepted by `add()`.
+
+        Args:
+            items: List of labels or dicts. A plain string is treated as
+                the button label with no other options.
+
+        Returns:
+            List of keys assigned to each button, in insertion order.
+        """
+        return [self.add(**item) if isinstance(item, dict) else self.add(item) for item in items]
+
+    def remove(self, key: str) -> None:
+        """Remove the button identified by `key`.
+
+        Args:
+            key: Key returned by `add()`.
+        """
+        self._internal.remove(key)
+
+    def update_item(self, key: str, **kwargs: Any) -> None:
+        """Reconfigure a button after creation.
+
+        Args:
+            key: Key returned by `add()`.
+            **kwargs: Options forwarded to the button's `configure()`.
+        """
+        self._internal.configure_item(key, **kwargs)
+
+    def query_item(self, key: str, option: str) -> Any:
+        """Return the current value of a configuration option for a button.
+
+        Args:
+            key: Key returned by `add()`.
+            option: Option name to query (e.g. `'text'`, `'state'`).
+        """
+        return self._internal.configure_item(key, option)
+
+    # ----- Queries -----
+
+    def item(self, key: str) -> Any:
+        """Return the button item object for `key`.
+
+        Args:
+            key: Key returned by `add()`.
+        """
+        return self._internal.item(key)
+
+    @property
+    def items(self) -> tuple[Any, ...]:
+        """All button items in insertion order."""
+        return self._internal.items()
+
+    @property
+    def keys(self) -> tuple[str, ...]:
+        """Keys of all buttons in insertion order."""
+        return self._internal.keys()
+
+    def __len__(self) -> int:
+        """Number of buttons in the group."""
+        return len(self._internal)
+
+    def __contains__(self, key: object) -> bool:
+        """True if a button with the given key exists in the group."""
+        return key in self._internal
+
+    # ----- Properties -----
+
+    @property
+    def disabled(self) -> bool:
+        """Whether all buttons are non-interactive."""
+        return str(self._internal.cget("state")) == "disabled"
+
+    @disabled.setter
+    def disabled(self, value: bool) -> None:
+        self._internal.configure(state="disabled" if value else "normal")
+
+    # ----- Events -----
+
+    @overload
+    def on_click(self) -> Stream: ...
+    @overload
+    def on_click(self, handler: Callable[[ButtonGroupClickEvent], Any]) -> Subscription: ...
+    def on_click(self, handler: Callable[[ButtonGroupClickEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when any button in the group is clicked.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.ButtonGroupClickEvent`
+                (`key`, `text`, `icon` of the clicked button). 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`.
+        """
+        if handler is None:
+            return self.on("click")
+
+        return self.on("click", handler)
+
+
+register_widget_events(ButtonGroup, _BUTTONGROUP_EVENTS)

bootstack/widgets/calendar.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+from typing import overload, Any, Callable, Iterable, Literal
+
+from bootstack.widgets._impl.composites.calendar import Calendar as _InternalCalendar
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.events import DateSelectEvent, Subscription
+from bootstack.streams import Stream
+from bootstack.widgets.types import AccentToken, Event, Padding
+
+
+class Calendar(PublicWidgetBase):
+    """An inline calendar for single-date or date-range selection.
+
+    Always visible — not a popup. Displays one month in `'single'` mode and
+    two months side-by-side in `'range'` mode.
+
+    Dates can be passed as `datetime.date` objects, `datetime.datetime`
+    objects, or ISO strings (`"2026-05-31"`).
+
+    Args:
+        value: Initially selected date (single mode only).
+        start_date: Initially selected range start date (range mode).
+        end_date: Initially selected range end date (range mode).
+        disabled_dates: Dates that cannot be selected. Displayed with a
+            strikethrough style.
+        selection_mode: `'single'` (default) for one date; `'range'`
+            for a start–end span.
+        min_date: Earliest selectable date. Earlier dates are disabled
+            and month navigation is blocked before this point.
+        max_date: Latest selectable date. Later dates are disabled
+            and month navigation is blocked past this point.
+        show_outside_days: Show days from adjacent months in the grid.
+            Defaults to `True` in single mode and `False` in range mode.
+        show_week_numbers: Display ISO 8601 week numbers in the leftmost
+            column. Defaults to `False`.
+        first_weekday: First day of the week as an integer (0=Monday,
+            6=Sunday). If omitted, the locale default is used.
+        accent: Accent token applied to selected dates and highlights.
+            Defaults to `'primary'`.
+        padding: Space in pixels around the calendar grid.
+        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`.
+    """
+
+    def __init__(
+        self,
+        *,
+        value: date | datetime | str | None = None,
+        start_date: date | datetime | str | None = None,
+        end_date: date | datetime | str | None = None,
+        disabled_dates: Iterable[date | datetime | str] | None = None,
+        selection_mode: Literal["single", "range"] = "single",
+        max_date: date | datetime | str | None = None,
+        min_date: date | datetime | str | None = None,
+        show_outside_days: bool | None = None,
+        show_week_numbers: bool = False,
+        first_weekday: int | None = None,
+        accent: AccentToken | str | None = None,
+        padding: Padding | None = None,
+        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
+
+        kw: dict[str, Any] = {"selection_mode": selection_mode, "show_week_numbers": show_week_numbers}
+        if value is not None:
+            kw["value"] = value
+        if start_date is not None:
+            kw["start_date"] = start_date
+        if end_date is not None:
+            kw["end_date"] = end_date
+        if disabled_dates is not None:
+            kw["disabled_dates"] = disabled_dates
+        if max_date is not None:
+            kw["max_date"] = max_date
+        if min_date is not None:
+            kw["min_date"] = min_date
+        if show_outside_days is not None:
+            kw["show_outside_days"] = show_outside_days
+        if first_weekday is not None:
+            kw["first_weekday"] = first_weekday
+        if accent is not None:
+            kw["accent"] = accent
+        if padding is not None:
+            kw["padding"] = padding
+
+        self._internal = _InternalCalendar(tk_master, **kw)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Value API -----
+
+    @property
+    def value(self) -> date | None:
+        """The currently selected date."""
+        return self._internal.value
+
+    @value.setter
+    def value(self, val: date | datetime | str | None) -> None:
+        self._internal.value = val
+
+    def get(self) -> date | None:
+        """Return the currently selected date."""
+        return self._internal.get()
+
+    def set(self, value: date | datetime | str | None) -> None:
+        """Set the selected date without emitting `<<DateSelect>>`."""
+        self._internal.set(value)
+
+    # ----- Range API -----
+
+    @property
+    def range(self) -> tuple[date | None, date | None]:
+        """The selected date range as (start, end)."""
+        return self._internal.range
+
+    @range.setter
+    def range(self, val: Any) -> None:
+        self._internal.range = val
+
+    def get_range(self) -> tuple[date | None, date | None]:
+        """Return the selected date range."""
+        return self._internal.get_range()
+
+    def set_range(
+        self,
+        start: date | datetime | str | None,
+        end: date | datetime | str | None = None,
+    ) -> None:
+        """Set the selected date range without emitting `<<DateSelect>>`."""
+        self._internal.set_range(start, end)
+
+    # ----- Date constraints (live) -----
+
+    @property
+    def min_date(self) -> date | None:
+        """Earliest selectable date. Assigning updates the calendar immediately; `None` clears the bound."""
+        return self._internal._min_date
+
+    @min_date.setter
+    def min_date(self, value: date | datetime | str | None) -> None:
+        self._internal.set_min_date(value)
+
+    @property
+    def max_date(self) -> date | None:
+        """Latest selectable date. Assigning updates the calendar immediately; `None` clears the bound."""
+        return self._internal._max_date
+
+    @max_date.setter
+    def max_date(self, value: date | datetime | str | None) -> None:
+        self._internal.set_max_date(value)
+
+    @property
+    def disabled_dates(self) -> tuple[date, ...]:
+        """The non-selectable dates. Assigning a new iterable updates the calendar immediately."""
+        return tuple(sorted(self._internal._disabled_dates))
+
+    @disabled_dates.setter
+    def disabled_dates(self, value: Iterable[date | datetime | str] | None) -> None:
+        self._internal.set_disabled_dates(value)
+
+    # ----- Events -----
+
+    @overload
+    def on_select(self) -> Stream: ...
+    @overload
+    def on_select(self, handler: Callable[[DateSelectEvent], Any]) -> Subscription: ...
+    def on_select(self, handler: Callable[[DateSelectEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when a date or range is selected.
+
+        In single mode the handler fires on every date click. In range mode
+        it fires after each click — check `calendar.range` to see whether
+        a complete range has been set (`end` is `None` while the second
+        date is still pending).
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.DateSelectEvent`.
+                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("<<DateSelect>>", handler)
+
+
+register_widget_events(Calendar, {})