bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/stacks.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+from typing import Any
+
+from bootstack.widgets._impl.primitives.frame import Frame
+from bootstack.widgets._impl.primitives.flexframe import FlexFrame
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.container import FlexContainer
+from bootstack.widgets.types import (
+    AccentToken, SurfaceToken, HAlign, VAlign, HArrange, VArrange, Padding,
+)
+
+
+class _FlexBase(FlexContainer):
+    _direction: str  # set by subclass
+
+    def __init__(
+        self,
+        *,
+        parent: Any = None,
+        horizontal_items: str = "left",
+        vertical_items: str = "top",
+        grow_items: bool = False,
+        weights: list[int] | None = None,
+        gap: int = 0,
+        padding: Padding | None = None,
+        surface: SurfaceToken | AccentToken | str | None = None,
+        show_border: bool = False,
+        width: int | None = None,
+        height: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        # Shared implementation for Row/Column. Each subclass declares its own
+        # __init__ so Sphinx renders the (axis-specific) params and value types
+        # per class.
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+
+        frame_kwargs: dict[str, Any] = {
+            "direction": self._direction,
+            "horizontal_items": horizontal_items,
+            "vertical_items": vertical_items,
+            "grow_items": grow_items,
+            "weights": weights,
+            "gap": gap,
+        }
+        if padding is not None:
+            frame_kwargs["padding"] = padding
+        if surface is not None:
+            frame_kwargs["surface"] = surface
+        if show_border:
+            frame_kwargs["show_border"] = show_border
+        if width is not None:
+            frame_kwargs["width"] = width
+        if height is not None:
+            frame_kwargs["height"] = height
+        if width is not None or height is not None:
+            frame_kwargs["propagate"] = False
+
+        tk_master = self._parent._child_master() if self._parent else None
+        self._internal = FlexFrame(tk_master, **frame_kwargs)
+        self._attach_to_parent(layout_kw)
+
+
+class Row(_FlexBase):
+    """Lays out children left to right along the horizontal axis.
+
+    Children flow in order. Position them on each screen axis: `horizontal_items`
+    *arranges the group* along the row (`'left'`/`'center'`/`'right'` or a
+    `'space-*'` mode), `vertical_items` *aligns* them up and down
+    (`'top'`/`'center'`/`'bottom'`/`'stretch'`), and `grow` / `weights` let
+    children share the available width. Drop a `Spacer` between children to push a
+    group aside without nesting.
+
+    Example::
+
+        with bs.Row(gap=8, vertical_items="center"):
+            bs.Label("Name:")
+            bs.TextField(grow=1)
+
+    Args:
+        horizontal_items: How the whole group of children is arranged along the
+            row — `'left'`, `'center'`, `'right'`, or the `'space-*'` modes. Has
+            no effect once any child grows. Defaults to `'left'`.
+        vertical_items: Vertical alignment of children — `'top'`, `'center'`,
+            `'bottom'`, or `'stretch'` (fill the row's height). Override per child
+            with `vertical`. Defaults to `'center'`.
+        grow_items: When `True`, every child grows equally to fill the row.
+            Defaults to `False`.
+        weights: Explicit per-child width weights (e.g. `[1, 2, 1]`) — shorthand
+            for setting `grow` on each child positionally. Overrides `grow_items`
+            and per-child `grow`. Defaults to `None`.
+        gap: Spacing in pixels between adjacent children. Defaults to `0`.
+        padding: Space in pixels between the row border and its content. Defaults
+            to `None` (no padding).
+        surface: Background token. Accepts a surface token, an accent token, or
+            any token with modifiers (e.g. `'primary[subtle]'`). Defaults to
+            `None` (inherits from parent surface).
+        show_border: When `True`, draws a 1 px border around the row frame.
+            Defaults to `False`.
+        width: Fixed width in pixels. Disables frame propagation so children
+            cannot resize the container. Defaults to `None` (size from children).
+        height: Fixed height in pixels. Disables frame propagation so children
+            cannot resize the container. Defaults to `None` (size from children).
+        parent: Override the context-stack parent widget.
+        **kwargs: Per-child placement options — `grow` (`bool | int`: `grow=True`
+            fills the leftover width with weight 1, `grow=N` takes N shares),
+            `vertical` (this child's vertical alignment: `'top'`/`'center'`/
+            `'bottom'`/`'stretch'`), `margin`, `index`. See :doc:`/tasks/layout`.
+    """
+    _direction = "horizontal"
+
+    def __init__(
+        self,
+        *,
+        parent: Any = None,
+        horizontal_items: HArrange = "left",
+        vertical_items: VAlign = "center",
+        grow_items: bool = False,
+        weights: list[int] | None = None,
+        gap: int = 0,
+        padding: Padding | None = None,
+        surface: SurfaceToken | AccentToken | str | None = None,
+        show_border: bool = False,
+        width: int | None = None,
+        height: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            parent=parent, horizontal_items=horizontal_items,
+            vertical_items=vertical_items, grow_items=grow_items, weights=weights,
+            gap=gap, padding=padding, surface=surface, show_border=show_border,
+            width=width, height=height, **kwargs,
+        )
+
+
+class Column(_FlexBase):
+    """Lays out children top to bottom along the vertical axis.
+
+    Children flow in order. Position them on each screen axis: `vertical_items`
+    *arranges the group* down the column (`'top'`/`'center'`/`'bottom'` or a
+    `'space-*'` mode), `horizontal_items` *aligns* them left and right
+    (`'left'`/`'center'`/`'right'`/`'stretch'`), and `grow` / `weights` let
+    children share the available height. Use `horizontal_items='stretch'` for a
+    full-width form column.
+
+    Example::
+
+        with bs.Column(gap=12, horizontal_items="stretch", padding=16):
+            bs.Label("Title", font="heading-md")
+            bs.TextField()
+            bs.Button("Submit", accent="primary")
+
+    Args:
+        horizontal_items: Horizontal alignment of children — `'left'`,
+            `'center'`, `'right'`, or `'stretch'` (fill the column's width).
+            Override per child with `horizontal`. Defaults to `'center'`.
+        vertical_items: How the whole group of children is arranged down the
+            column — `'top'`, `'center'`, `'bottom'`, or the `'space-*'` modes.
+            Has no effect once any child grows. Defaults to `'top'`.
+        grow_items: When `True`, every child grows equally to fill the column.
+            Defaults to `False`.
+        weights: Explicit per-child height weights (e.g. `[1, 2, 1]`) — shorthand
+            for setting `grow` on each child positionally. Overrides `grow_items`
+            and per-child `grow`. Defaults to `None`.
+        gap: Spacing in pixels between adjacent children. Defaults to `0`.
+        padding: Space in pixels between the column border and its content.
+            Defaults to `None` (no padding).
+        surface: Background token. Accepts a surface token, an accent token, or
+            any token with modifiers (e.g. `'primary[subtle]'`). Defaults to
+            `None` (inherits from parent surface).
+        show_border: When `True`, draws a 1 px border around the column frame.
+            Defaults to `False`.
+        width: Fixed width in pixels. Disables frame propagation so children
+            cannot resize the container. Defaults to `None` (size from children).
+        height: Fixed height in pixels. Disables frame propagation so children
+            cannot resize the container. Defaults to `None` (size from children).
+        parent: Override the context-stack parent widget.
+        **kwargs: Per-child placement options — `grow` (`bool | int`: `grow=True`
+            fills the leftover height with weight 1, `grow=N` takes N shares),
+            `horizontal` (this child's horizontal alignment: `'left'`/`'center'`/
+            `'right'`/`'stretch'`), `margin`, `index`. See :doc:`/tasks/layout`.
+    """
+    _direction = "vertical"
+
+    def __init__(
+        self,
+        *,
+        parent: Any = None,
+        horizontal_items: HAlign = "center",
+        vertical_items: VArrange = "top",
+        grow_items: bool = False,
+        weights: list[int] | None = None,
+        gap: int = 0,
+        padding: Padding | None = None,
+        surface: SurfaceToken | AccentToken | str | None = None,
+        show_border: bool = False,
+        width: int | None = None,
+        height: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            parent=parent, horizontal_items=horizontal_items,
+            vertical_items=vertical_items, grow_items=grow_items, weights=weights,
+            gap=gap, padding=padding, surface=surface, show_border=show_border,
+            width=width, height=height, **kwargs,
+        )
+
+
+class Spacer(PublicWidgetBase):
+    """A composable break that pushes neighbors apart in a Row or Column.
+
+    Flexible by default — it absorbs the available stacking-axis space, so items
+    before it cluster at the start and items after it at the end. `Spacer(size=N)`
+    is instead a fixed N-pixel gap, and `Spacer(weight=N)` shares slack with
+    other spacers in proportion to their weights.
+
+    Unlike `horizontal_items`/`vertical_items` (which arrange the *whole* group),
+    a `Spacer` is a local break at one point — use it for clustered toolbars and
+    footers without nesting::
+
+        with bs.Row(gap=4):
+            bs.Button("New"); bs.Button("Open")
+            bs.Spacer()
+            bs.Button("Settings")
+
+    Args:
+        size: Fixed size in pixels. When set, the spacer is a rigid gap rather
+            than flexible slack. Defaults to `None` (flexible).
+        weight: Relative share of the leftover space when flexible. Ignored when
+            `size` is set. Defaults to `1`.
+        parent: Override the context-stack parent widget.
+    """
+
+    _is_spacer = True
+
+    def __init__(
+        self,
+        *,
+        size: int | None = None,
+        weight: int = 1,
+        parent: Any = None,
+    ) -> None:
+        self._parent = self._resolve_parent(parent)
+        self._spacer_size = size
+        self._spacer_weight = 0 if size is not None else weight
+        tk_master = self._parent._child_master() if self._parent else None
+        self._internal = Frame(tk_master, width=1, height=1)
+        self._attach_to_parent({})

bootstack/widgets/statusbar.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from bootstack.widgets._impl.composites.toolbar import Toolbar as _InternalToolbar
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets.types import SurfaceToken, WidgetDensity
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class StatusBar(PublicWidgetBase):
+    """A horizontal status band of passive segments — counts, sync state, a ready
+    message.
+
+    Intended for *passive* status (whether static or bound to a `Signal` for live
+    updates). Interactive controls (buttons, a search box) belong on a
+    :class:`Toolbar <bootstack.Toolbar>` by convention; nothing enforces it,
+    but the status bar reads best as a quiet display strip. Segments add
+    left-to-right; an `add_spacer()` (or `side='right'`) pushes the following
+    segments to the right cluster.
+
+    Use it standalone — `bs.StatusBar(horizontal="stretch")` spans the bottom of
+    any `App`/`Window` (place it last and let the content above `grow`) — or read
+    `shell.statusbar` for the one built
+    into an :class:`AppShell <bootstack.AppShell>`. Add widgets by class with
+    `add_widget()`, or create custom widgets with `parent=statusbar` (they add to
+    the left cluster automatically).
+
+    Args:
+        surface: Background surface token. Defaults to the theme's `'chrome'`
+            surface (a quiet band, distinct from the content area).
+        density: Size of the band's segments. Default `'compact'`.
+        padding: Inner padding in pixels — an int or a `(horizontal, vertical)`
+            tuple. Defaults to a thin compact padding.
+        parent: Override the context-stack parent.
+        **kwargs: Layout placement options applied by the parent container —
+            `fill`, `side`, `expand`, `anchor`, `margin`. See :doc:`/tasks/layout`.
+    """
+
+    _auto_place = True
+
+    def __init__(
+        self,
+        *,
+        surface: SurfaceToken | str | None = "chrome",
+        density: WidgetDensity = "compact",
+        padding: int | tuple[int, int] | None = None,
+        parent: Any = None,
+        _toolbar: Any = None,
+        _show: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._has_right_spacer = False
+        if _toolbar is not None:
+            # Shell adoption: wrap the AppShell's pre-built status band. `_show`
+            # reveals the (content-driven) band on the first segment added.
+            self._internal = _toolbar
+            self._parent = None
+            self._show = _show or (lambda: None)
+            return
+
+        # Standalone: build our own bar (the Toolbar pattern).
+        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] = {"density": density, "draggable": False}
+        if surface is not None:
+            internal_kwargs["surface"] = surface
+        if padding is not None:
+            internal_kwargs["padding"] = padding
+        internal_kwargs.update(kwargs)
+        self._internal = _InternalToolbar(tk_master, **internal_kwargs)
+        self._attach_to_parent(layout_kw)
+        # Standalone bars are placed/shown by the caller — nothing to reveal.
+        self._show = lambda: None
+
+    # ----- Container protocol (so `parent=statusbar` works) -----
+
+    def _child_master(self) -> Any:
+        return self._internal.content
+
+    def guide_layout(self, child: Any, **layout_kw: Any) -> None:
+        # A widget created with `parent=statusbar` adds to the left cluster.
+        self._internal.add_widget(child._internal)
+        self._show()
+
+    @property
+    def content(self) -> Any:
+        """The band's content frame — parent custom widgets here."""
+        return self._internal.content
+
+    # ----- Segments -----
+
+    def _ensure_right(self) -> None:
+        if not self._has_right_spacer:
+            self._internal.add_spacer()
+            self._has_right_spacer = True
+
+    def add_widget(
+        self, widget_cls: Any, *, side: Literal["left", "right"] = "left", **kwargs: Any
+    ) -> Any:
+        """Build a widget on the left or right cluster from its class.
+
+        Pass a widget **class** — the bar builds it, applying its own `density`
+        and `surface` (for any the class accepts) so the widget matches the band,
+        and forwarding `kwargs` to the constructor:
+
+            status.add_widget(bs.ThemeToggle, side="right")
+            status.add_widget(bs.ProgressBar, value=65)
+
+        To add a widget you have already built yourself, parent it onto the bar
+        directly (it lands in the left cluster):
+
+            bs.MyCustomWidget(parent=status)
+
+        Args:
+            widget_cls: The widget class to build on the band.
+            side: `'left'` (default) or `'right'` (after the spacer).
+            **kwargs: Constructor arguments for the widget.
+
+        Returns:
+            The new widget instance.
+        """
+        if side == "right":
+            self._ensure_right()
+        self._apply_bar_defaults(widget_cls, kwargs)
+        return widget_cls(parent=self, **kwargs)
+
+    def _apply_bar_defaults(self, widget_cls: type, kwargs: dict[str, Any]) -> None:
+        """Default `density`/`surface` from the band onto a class being built, but
+        only for parameters the widget actually accepts (and not if the caller
+        already passed them)."""
+        import inspect
+
+        try:
+            params = inspect.signature(widget_cls).parameters
+        except (TypeError, ValueError):
+            return
+        if "density" in params:
+            kwargs.setdefault("density", self._internal.density)
+        if "surface" in params:
+            kwargs.setdefault("surface", self._internal._surface)
+
+    def add_text(
+        self,
+        text: str = "",
+        *,
+        textsignal: "Signal | None" = None,
+        side: Literal["left", "right"] = "left",
+        icon: str | None = None,
+        font: str | None = None,
+    ) -> None:
+        """Add a text (and optional icon) segment to a cluster.
+
+        Pass `textsignal` to make the segment **reactive** — a `Signal` whose
+        value drives the text and updates it live as the signal changes (e.g. a
+        running count or sync state). `text` seeds a static segment instead.
+
+        Args:
+            text: The static label text (ignored when `textsignal` is given).
+            textsignal: A reactive `Signal[str]` bound to the segment's text.
+            side: `'left'` (default) or `'right'` (after the spacer).
+            icon: Optional icon name displayed beside the text.
+            font: Optional font token, e.g. `'caption'`.
+        """
+        if side == "right":
+            self._ensure_right()
+        kwargs: dict[str, Any] = {"icon": icon, "font": font}
+        if textsignal is not None:
+            kwargs["textsignal"] = textsignal
+        self._internal.add_label(text, **kwargs)
+        self._show()
+
+    def add_spacer(self) -> None:
+        """Add a flexible spacer that pushes following items to the right."""
+        self._internal.add_spacer()
+        self._has_right_spacer = True
+        self._show()
+
+    def clear(self) -> None:
+        """Remove all status segments."""
+        for child in list(self._internal.content.winfo_children()):
+            try:
+                child.destroy()
+            except Exception:
+                pass
+        self._has_right_spacer = False