bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/grid.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import Any
+
+from bootstack.widgets._impl.primitives.gridframe import GridFrame
+from bootstack.widgets._core.container import (
+    PublicContainer, GRID_KEYS, grid_sticky, _reject_legacy_child_kwargs,
+)
+from bootstack.widgets.types import (
+    AccentToken, SurfaceToken, HAlign, VAlign, Padding, AutoFlow,
+)
+
+
+class Grid(PublicContainer):
+    """A container that arranges children in rows and columns.
+
+    Children are auto-placed left-to-right, top-to-bottom by default. Column and
+    row sizes are set with weighted `columns=` / `rows=`; in-cell alignment is
+    controlled with `horizontal_items` and `vertical_items`, overridable per
+    child with `horizontal` / `vertical`.
+
+    Args:
+        columns: Column definitions. An integer creates that many
+            equal-weight columns. A list sets per-column weights or
+            sizes — integers are relative weights, `'auto'` sizes to
+            content, `'Npx'` sets a fixed pixel width (e.g. `'120px'`).
+            Defaults to `None` (single column, sized to content).
+        rows: Row definitions, same format as `columns`. Defaults to
+            `None` (rows added automatically as children are placed).
+        gap: Space in pixels between cells. An integer applies to both
+            axes; a 2-tuple `(col_gap, row_gap)` sets them
+            independently. Defaults to `0`.
+        horizontal_items: Horizontal in-cell alignment of every child —
+            `'stretch'` (fill the cell width), `'left'`, `'center'`, or
+            `'right'`. Override per child with `horizontal`. Defaults to
+            `'stretch'`.
+        vertical_items: Vertical in-cell alignment of every child —
+            `'stretch'` (fill the cell height), `'top'`, `'center'`, or
+            `'bottom'`. Override per child with `vertical`. Defaults to
+            `'stretch'`.
+        auto_flow: Auto-placement direction. Defaults to `'row'`.
+        padding: Space in pixels between the grid 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
+            grid. Use at least `padding=1` to give the border visual
+            clearance. Defaults to `False`.
+        width: Fixed width in pixels. Disables frame propagation —
+            see the note in :class:`Row` for sizing behavior.
+            Defaults to `None`.
+        height: Fixed height in pixels. Disables frame propagation —
+            see the note in :class:`Column` for sizing behavior.
+            Defaults to `None`.
+        parent: Override the context-stack parent widget.
+        **kwargs: Per-child placement options — `row`, `column`,
+            `rowspan`, `columnspan`, `horizontal`, `vertical`,
+            `margin`. See :doc:`/tasks/layout`.
+    """
+
+    def __init__(
+        self,
+        *,
+        parent: Any = None,
+        columns: int | list[int | str] | None = None,
+        rows: int | list[int | str] | None = None,
+        gap: int | tuple[int, int] = 0,
+        horizontal_items: HAlign = "stretch",
+        vertical_items: VAlign = "stretch",
+        auto_flow: AutoFlow = "row",
+        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:
+        self._parent = self._resolve_parent(parent)
+        layout_kw = self._split_layout_kwargs(kwargs)
+
+        frame_kwargs: dict[str, Any] = {
+            "rows": rows,
+            "columns": columns,
+            "gap": gap,
+            "auto_flow": auto_flow,
+        }
+        for k, v in {
+            "padding": padding,
+            "surface": surface,
+        }.items():
+            if v is not None:
+                frame_kwargs[k] = v
+        if show_border:
+            frame_kwargs["show_border"] = True
+        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
+
+        self._horizontal_items = horizontal_items
+        self._vertical_items = vertical_items
+
+        tk_master = self._parent._child_master() if self._parent else None
+        self._internal = GridFrame(tk_master, **frame_kwargs)
+        self._attach_to_parent(layout_kw)
+
+    def _default_layout_method(self) -> str:
+        return "grid"
+
+    def _merge_layout_options(self, child: Any, layout_kw: dict) -> tuple[str, dict]:
+        _reject_legacy_child_kwargs(layout_kw, "Grid")
+        options = {k: v for k, v in layout_kw.items() if k in GRID_KEYS}
+        # Derive the cell sticky from per-child horizontal/vertical, each falling
+        # back to the container default for its axis.
+        h = layout_kw.get("horizontal") or self._horizontal_items
+        v = layout_kw.get("vertical") or self._vertical_items
+        options["sticky"] = grid_sticky(h, v)
+        return ("grid", options)

bootstack/widgets/groupbox.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import tkinter
+from typing import Any
+
+from bootstack.widgets._impl.primitives.labelframe import LabelFrame as _LabelFrame
+from bootstack.widgets._impl.primitives.flexframe import FlexFrame
+from bootstack.widgets._impl.primitives.gridframe import GridFrame
+from bootstack.widgets._core.container import (
+    PublicContainer, GRID_KEYS, place_flex_child, grid_sticky,
+    _reject_legacy_child_kwargs,
+)
+from bootstack.widgets.types import (
+    AccentToken, Padding, LayoutKind, AutoFlow, LocalizeMode,
+)
+
+
+class GroupBox(PublicContainer):
+    """A labeled container that groups related content inside a bordered frame.
+
+    The title is embedded in the top border line, giving the classic fieldset
+    look. Children are laid out according to `layout`.
+
+    Args:
+        title: Text label embedded in the top border line. Defaults to an
+            empty string (border only, no label).
+        layout: Internal layout manager. Defaults to `'column'`.
+        padding: Space in pixels between the border and the content. A single
+            value applies to all sides; `(x, y)` sets the horizontal and
+            vertical amounts. Defaults to `16`.
+        accent: Color intent token applied to the border and title label.
+            When omitted, the border uses the theme's default foreground color.
+        gap: Space in pixels between child widgets. Defaults to `0`.
+        horizontal_items: How children sit on the horizontal axis — edge values
+            `'left'`/`'center'`/`'right'`/`'stretch'`, plus the `'space-*'` modes
+            when horizontal is the stacking axis (`'row'`). Override per child
+            with `horizontal`. Defaults to `'stretch'` in grid mode, `'center'` in a column
+            and `'left'` in a row.
+        vertical_items: How children sit on the vertical axis — edge values
+            `'top'`/`'center'`/`'bottom'`/`'stretch'`, plus the `'space-*'` modes
+            when vertical is the stacking axis (`'column'`). Override per child
+            with `vertical`. Defaults to `'stretch'` in grid mode, `'center'` in a row and `'top'` in a column.
+        grow_items: For `'column'`/`'row'` layout, when `True` every child
+            grows equally to share the main axis. Defaults to `False`.
+        columns: Column definitions for `'grid'` layout. An integer sets
+            the number of equal-weight columns; a list sets per-column
+            weights or sizes — integers are relative weights, `'auto'`
+            sizes to content, `'Npx'` sets a fixed pixel width (e.g.
+            `[1, 2, 'auto', '120px']`).
+        rows: Row definitions for `'grid'` layout, same format as `columns`.
+        auto_flow: Grid auto-placement direction. Defaults to `'row'`.
+        localize: Whether the title is translated through the catalog — `True`,
+            `False`, or `'auto'`. Defaults to the app's `localize_mode`.
+        parent: Override the context-stack parent widget.
+        **kwargs: Layout placement options applied by the parent container —
+            `fill`, `expand`, `anchor`, `margin`, `row`, `column`, `sticky`.
+            See :doc:`/tasks/layout`.
+    """
+
+    def __init__(
+        self,
+        title: str = "",
+        *,
+        layout: LayoutKind = "column",
+        padding: Padding | None = 16,
+        accent: AccentToken | str | None = None,
+        gap: int = 0,
+        horizontal_items: str | None = None,
+        vertical_items: str | None = None,
+        grow_items: bool = False,
+        columns: int | list[int | str] | None = None,
+        rows: int | list[int | str] | None = None,
+        auto_flow: AutoFlow = "row",
+        localize: LocalizeMode | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._parent = self._resolve_parent(parent)
+        self._layout = layout
+        layout_kw = self._split_layout_kwargs(kwargs)
+
+        # One horizontal_items/vertical_items pair serves both modes; the sensible
+        # default differs — grid cells fill (stretch), stacked children sit at the
+        # leading edge (left/top).
+        if horizontal_items is None:
+            horizontal_items = (
+                "stretch" if layout == "grid"
+                else "center" if layout == "column" else "left"
+            )
+        if vertical_items is None:
+            vertical_items = (
+                "stretch" if layout == "grid"
+                else "center" if layout == "row" else "top"
+            )
+
+        tk_master = self._parent._child_master() if self._parent else None
+
+        lf_kwargs: dict[str, Any] = {"text": title, "padding": padding}
+        if accent is not None:
+            lf_kwargs["accent"] = accent
+        if localize is not None:
+            lf_kwargs["localize"] = localize
+
+        self._internal = _LabelFrame(tk_master, **lf_kwargs)
+
+        if layout in ("column", "row"):
+            self._layout_frame = FlexFrame(
+                self._internal,
+                direction="vertical" if layout == "column" else "horizontal",
+                gap=gap,
+                horizontal_items=horizontal_items,
+                vertical_items=vertical_items,
+                grow_items=grow_items,
+            )
+        elif layout == "grid":
+            self._layout_frame = GridFrame(
+                self._internal,
+                columns=columns,
+                rows=rows,
+                gap=gap,
+                auto_flow=auto_flow,
+            )
+        else:
+            raise ValueError(
+                f"GroupBox layout must be 'column', 'row', or 'grid', got {layout!r}"
+            )
+
+        self._horizontal_items = horizontal_items
+        self._vertical_items = vertical_items
+        self._layout_frame.pack(fill="both", expand=True)
+        self._attach_to_parent(layout_kw)
+
+    def _child_master(self) -> tkinter.Misc:
+        return self._layout_frame
+
+    def _default_layout_method(self) -> str:
+        return "grid" if self._layout == "grid" else "flex"
+
+    def guide_layout(self, child: Any, **layout_kw: Any) -> None:
+        if self._layout == "grid":
+            return super().guide_layout(child, **layout_kw)
+        place_flex_child(self._layout_frame, child, layout_kw, "GroupBox")
+
+    def _merge_layout_options(self, child: Any, layout_kw: dict) -> tuple[str, dict]:
+        # Only reached for grid layout (column/row use the flex path above).
+        _reject_legacy_child_kwargs(layout_kw, "GroupBox")
+        options = {k: v for k, v in layout_kw.items() if k in GRID_KEYS}
+        h = layout_kw.get("horizontal") or self._horizontal_items
+        v = layout_kw.get("vertical") or self._vertical_items
+        options["sticky"] = grid_sticky(h, v)
+        return ("grid", options)
+
+    # ----- Properties -----
+
+    @property
+    def title(self) -> str:
+        """The text embedded in the border."""
+        return self._internal.cget("text")
+
+    @title.setter
+    def title(self, value: str) -> None:
+        self._internal.configure(text=value)

bootstack/widgets/label.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+from typing import overload, Any, Callable, Literal, TYPE_CHECKING
+
+from bootstack.widgets._impl.primitives.label import Label as _InternalLabel
+from bootstack.widgets._impl.primitives.badge import Badge as _InternalBadge
+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, SurfaceToken,
+    Anchor, Justify, Relief, CompoundMode, Padding, IconPosition, IconSpec,
+)
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class Label(IconProperty, ImageProperty, PublicWidgetBase):
+    """Static text display with optional icon, semantic styling, and font tokens.
+
+    The display text is the first positional argument. All options are
+    keyword-only.
+
+    Args:
+        text: Text to display.
+        textsignal: Reactive `Signal` bound to the display text. Updates
+            automatically when the signal changes. Combine with
+            `value_format=` to format numeric or date values.
+        value_format: Format applied to the `textsignal` value before display —
+            a named preset (e.g. `'decimal'`, `'currency'`, `'shortDate'`) or a
+            custom pattern (e.g. `'#,##0'`). Requires `textsignal=` and
+            localization enabled. See :ref:`format specs <value-formats>`.
+        image: An `Image` handle (from `bootstack.images`) to display, for custom
+            artwork rather than a Bootstrap Icon name. Also accepts a `get_icon`
+            result. Use `icon_position=` to control placement relative to text.
+        icon: Bootstrap Icons name (e.g. `'house'`, `'gear'`) — 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. Auto-detected when
+            `text` is empty and `icon` is provided.
+        icon_position: Position of the icon or image relative to the text.
+            Only relevant when an icon or image is shown alongside text.
+            Default `'left'`.
+        anchor: Content alignment within the label area. Default `'center'`.
+        justify: Multi-line text alignment.
+        padding: Inner spacing around the text content.
+        width: Width in character units.
+        wrap_width: Maximum pixel width before text wraps. Set to enable
+            multi-line wrapping.
+        font: Semantic font token. Examples: `'body'`, `'heading-lg'`,
+            `'heading-md[bold]'`, `'caption'`, `'code'`, `'body+2[italic]'`.
+        accent: Semantic color applied to the text.
+        surface: Background surface context.
+        localize: Whether the text is 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 a proper noun or identifier untranslated.
+        parent: Explicit parent widget. If omitted, the current context-stack
+            container is used.
+    """
+
+    _internal_class = _InternalLabel
+
+    def __init__(
+        self,
+        text: str = "",
+        *,
+        textsignal: "Signal | None" = None,
+        value_format: str | None = None,
+        image: Any = None,
+        icon: str | IconSpec | None = None,
+        icon_only: bool = False,
+        icon_position: IconPosition = "left",
+        anchor: Anchor | None = None,
+        justify: Justify | None = None,
+        padding: Padding | None = None,
+        width: int | None = None,
+        wrap_width: int | None = None,
+        font: str | None = None,
+        accent: AccentToken | Literal['muted'] | str | None = None,
+        surface: SurfaceToken | str | None = None,
+        localize: bool | Literal['auto'] | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        # `variant` is not a public Label option (Label has only the implicit
+        # 'default'); it rides in via kwargs as the conduit for the Badge
+        # subclass, which sets its own 'square'/'pill' on a Badge ttk class.
+        variant = kwargs.pop("variant", 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
+
+        internal_kwargs: dict[str, Any] = {}
+        if text:
+            internal_kwargs["text"] = text
+        if textsignal is not None:
+            internal_kwargs["textsignal"] = textsignal
+        if value_format is not None:
+            internal_kwargs["value_format"] = value_format
+        deferred_image = None
+        if image is not None:
+            from bootstack.images import Image as _ImageHandle
+
+            if isinstance(image, _ImageHandle):
+                deferred_image = image
+                has_text = bool(text) or textsignal is not None
+                if not has_text or icon_only:
+                    internal_kwargs["icon_only"] = True
+                    internal_kwargs["compound"] = "image"
+                else:
+                    internal_kwargs["compound"] = icon_position
+            else:
+                internal_kwargs["image"] = image
+        if icon is not None:
+            internal_kwargs["icon"] = icon
+            has_text = bool(text) or textsignal is not None
+            if not has_text or icon_only:
+                internal_kwargs["icon_only"] = True
+                internal_kwargs["compound"] = "image"
+            else:
+                internal_kwargs["compound"] = icon_position
+        elif icon_only:
+            internal_kwargs["icon_only"] = True
+        if anchor is not None:
+            internal_kwargs["anchor"] = anchor
+        if justify is not None:
+            internal_kwargs["justify"] = justify
+        if padding is not None:
+            internal_kwargs["padding"] = padding
+        if width is not None:
+            internal_kwargs["width"] = width
+        if wrap_width is not None:
+            internal_kwargs["wraplength"] = wrap_width
+        if font is not None:
+            internal_kwargs["font"] = font
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if variant is not None:
+            internal_kwargs["variant"] = variant
+        if surface is not None:
+            internal_kwargs["surface"] = surface
+        if localize is not None:
+            internal_kwargs["localize"] = localize
+
+        self._internal = self._internal_class(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 displayed text."""
+        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)
+
+    # ----- 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 click events on this label.
+
+        Called with no handler, returns a composable `Stream`. Called with
+        a handler, binds it immediately and returns a `Subscription`. The
+        handler receives the curated `Event` (pointer position, modifier keys).
+
+        Args:
+            handler: Called with the click `Event` when the label is clicked.
+
+        Returns:
+            `Subscription` (with handler) or `Stream` (without handler).
+        """
+        return self.on("click", handler)
+
+
+register_widget_events(Label, {})
+
+
+class Badge(Label):
+    """Compact styled chip for status indicators, counts, and tags.
+
+    A `Badge` is a styled `Label` with a fixed visual shape. It accepts the
+    same kwargs as `Label`, but the icon and image elements are not rendered.
+
+    Args:
+        text: Text to display inside the badge.
+        accent: Color intent token for the badge. Defaults to `'primary'`.
+        variant: Shape variant — `'square'` is a rounded rectangle, `'pill'` is
+            fully rounded. Default `'square'`.
+        **kwargs: Other `Label` options (e.g. `font`, `padding`, `width`) plus
+            layout placement options applied by the parent container. See
+            :doc:`/tasks/layout`.
+    """
+
+    _internal_class = _InternalBadge
+
+    def __init__(
+        self,
+        text: str = "",
+        *,
+        accent: AccentToken | str = "primary",
+        variant: Literal["square", "pill"] = "square",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(text, accent=accent, variant=variant, **kwargs)
+
+
+register_widget_events(Badge, {})