bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/form.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Mapping, Sequence, overload
+
+from bootstack.constants import DEFAULT_MIN_COL_WIDTH
+from bootstack.widgets._impl.composites.form import Form as _InternalForm
+from bootstack.widgets._impl.composites.form import (
+    FormItem, FieldItem, GroupItem, TabsItem, TabItem,
+)
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.streams import Stream
+from bootstack.events import Subscription
+from bootstack.signals import Signal
+from bootstack.widgets.types import AccentToken
+
+if TYPE_CHECKING:
+    from bootstack.dialogs import DialogButton
+
+
+class Form(PublicWidgetBase):
+    """Data-entry form built from data or explicit field definitions.
+
+    Args:
+        data: Initial data dict. Keys become field names; types are inferred
+            when `items` is not provided.
+        items: Explicit form layout as `FieldItem`/`GroupItem`/`TabsItem`
+            instances or equivalent dicts.
+        col_count: Number of top-level columns. Default `1`.
+        min_col_width: Minimum column width in pixels.
+        on_data_change: Callback invoked with the updated data dict on each
+            field change. Equivalent to calling `on_data_change()` after
+            construction.
+        width: Fixed form width in pixels.
+        height: Fixed form height in pixels.
+        accent: Accent token for the form container.
+        buttons: Footer buttons — strings, `DialogButton` instances, or dicts.
+        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,
+        *,
+        data: dict[str, Any] | None = None,
+        items: Sequence[FormItem | Mapping[str, Any]] | None = None,
+        col_count: int = 1,
+        min_col_width: int = DEFAULT_MIN_COL_WIDTH,
+        on_data_change: Callable[[dict[str, Any]], Any] | None = None,
+        width: int | None = None,
+        height: int | None = None,
+        accent: AccentToken | str | None = None,
+        buttons: Sequence[str | DialogButton | dict[str, Any]] | 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] = {"col_count": col_count, "min_col_width": min_col_width}
+        if data is not None:
+            kw["data"] = data
+        if items is not None:
+            kw["items"] = items
+        if on_data_change is not None:
+            kw["on_data_change"] = on_data_change
+        if width is not None:
+            kw["width"] = width
+        if height is not None:
+            kw["height"] = height
+        if accent is not None:
+            kw["accent"] = accent
+        if buttons is not None:
+            kw["buttons"] = buttons
+
+        self._internal = _InternalForm(tk_master, **kw)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Value API -----
+
+    @property
+    def value(self) -> dict[str, Any]:
+        """All field values as a dictionary."""
+        return self._internal.value
+
+    @value.setter
+    def value(self, values: Mapping[str, Any]) -> None:
+        self._internal.value = values
+
+    @property
+    def data(self) -> dict[str, Any]:
+        """Current form data dict."""
+        return self._internal.data
+
+    @property
+    def result(self) -> Any:
+        """Value set by button commands. None until a button is pressed."""
+        return self._internal.result
+
+    def get(self) -> dict[str, Any]:
+        """Return all field values as a dictionary."""
+        return self._internal.get()
+
+    def set(self, values: Mapping[str, Any]) -> None:
+        """Set multiple field values from a dictionary."""
+        self._internal.set(values)
+
+    def validate(self) -> bool:
+        """Run validation rules; returns True if all fields pass."""
+        return self._internal.validate()
+
+    @property
+    def valid(self) -> Signal:
+        """Reactive `Signal[bool]` — `True` when every field passes validation.
+
+        AND-ed over the fields' own `valid` signals and recomputed whenever any
+        field's validity changes, so a submit button can react to it directly::
+
+            form = bs.Form(items=[...])
+            submit = bs.Button("Save", on_click=save)
+
+            def gate(ok):
+                submit.disabled = not ok
+
+            form.valid.subscribe(gate)
+
+        A field is valid until proven otherwise, so this reads `True` before any
+        rule has run — call `validate()` to force a full pass (for example, to
+        gate the submit button's initial state).
+        """
+        return self._internal.valid
+
+    @property
+    def errors(self) -> dict[str, str]:
+        """Current validation errors keyed by field key; empty when all valid.
+
+        Read live from the fields' `error` signals, so it always reflects the
+        latest validation run.
+        """
+        return self._internal.errors
+
+    # ----- Field access -----
+
+    def field(self, key: str) -> Any:
+        """Return the Field widget for the given key."""
+        return self._internal.field(key)
+
+    def fields(self) -> tuple:
+        """Return all field widgets in insertion order."""
+        return self._internal.fields()
+
+    def keys(self) -> tuple[str, ...]:
+        """Return all field keys in insertion order."""
+        return self._internal.keys()
+
+    def get_field_value(self, key: str) -> Any:
+        """Return the current value of the named field."""
+        return self._internal.get_field_value(key)
+
+    def set_field_value(self, key: str, value: Any) -> None:
+        """Set the value of the named field."""
+        self._internal.set_field_value(key, value)
+
+    # ----- Signal access -----
+
+    def field_signal(self, key: str) -> Any:
+        """Return the Signal for the named field value."""
+        return self._internal.field_signal(key)
+
+    def field_textsignal(self, key: str) -> Any:
+        """Return the text Signal for the named field."""
+        return self._internal.field_textsignal(key)
+
+    # ----- Events -----
+
+    @overload
+    def on_data_change(self) -> Stream: ...
+    @overload
+    def on_data_change(self, handler: Callable[[dict[str, Any]], Any]) -> Subscription: ...
+    def on_data_change(self, handler: Callable[[dict[str, Any]], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired whenever any field value changes.
+
+        The handler receives the current form data as a dict. Called with no
+        handler, returns a composable `Stream`.
+
+        Args:
+            handler: Called with the updated data dict on each field change.
+
+        Returns:
+            `Subscription` (with handler) or `Stream` (without handler).
+        """
+        if handler is None:
+            return self.on("data_change")
+        return self.on("data_change", lambda _e: handler(self.value))
+
+
+register_widget_events(Form, {"data_change": "<<BsDataChange>>"})

bootstack/widgets/gallery.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+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.gallery import Gallery as _InternalGallery
+from bootstack.widgets.types import AccentToken, SelectionMode, SurfaceToken, ScrollbarVariant
+
+if TYPE_CHECKING:
+    from bootstack.data.types import DataSourceProtocol
+
+ImageFit = Literal["contain", "cover", "fill", "none", "scale-down"]
+
+
+class Gallery(PublicWidgetBase):
+    """A scrollable, selectable grid of image thumbnails.
+
+    `Gallery` displays a collection of image records as a reflowing grid of
+    thumbnails, recycling tiles so it stays efficient for large collections. It
+    is record-native — populate it with `items=` (a list of dicts) or a
+    `data_source=`, and read the chosen tile(s) back through `selection`, the
+    same model `ListView`, `DataTable`, and `Tree` share.
+
+    Each record names the image to show through `image_field` (an `Image`, a file
+    path, or a PIL image) and, optionally, a caption through `caption_field`.
+    Other keys ride along in the record bag and are returned by `selection` and
+    events.
+
+    Args:
+        items: Initial list of record dicts.
+        data_source: A data source for database- or API-backed data. Any object
+            implementing the data-source protocol is accepted.
+        image_field: Record key holding the image to display in each tile — an
+            `Image` handle, a file path, or a PIL image. Default `'image'`.
+        caption_field: Record key for the caption shown under each thumbnail.
+            Default `None` (no captions).
+        columns: Number of columns, or `'auto'` (default) to reflow the grid to
+            fit the available width as it resizes.
+        tile_size: Thumbnail size as `(width, height)` in pixels. Default
+            `(160, 160)`.
+        fit: How each image is scaled into its tile — `'contain'`, `'cover'`
+            (default), `'fill'`, `'none'`, or `'scale-down'`. See `Picture`.
+        corner_radius: Rounded-corner radius for thumbnails, in pixels. Default
+            `0`.
+        gap: Spacing between tiles in pixels. Default `8`.
+        selection_mode: Tile selection behavior — `'single'`, `'multi'`, or
+            `'none'` (default). Selected tiles show an accent highlight ring.
+        scrollbar_variant: Scrollbar style — `'thin'` (default) for a slim bar,
+            or `'default'` for the standard rounded bar.
+        rows: Number of tile rows used to derive the gallery's minimum height
+            when it sits in a container that doesn't impose one (a scroll view,
+            an auto-fit window). Default `2`. `fill`/`expand` still grow the grid
+            past this floor and reflow more rows in.
+        accent: Color intent token for the selection ring. Defaults to the
+            theme's primary color.
+        surface: Background surface token shown behind the tiles.
+        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,
+        *,
+        items: list[dict] | None = None,
+        data_source: "DataSourceProtocol | None" = None,
+        image_field: str = "image",
+        caption_field: str | None = None,
+        columns: "int | Literal['auto']" = "auto",
+        tile_size: tuple[int, int] = (160, 160),
+        fit: ImageFit = "cover",
+        corner_radius: int = 0,
+        gap: int = 8,
+        selection_mode: SelectionMode = "none",
+        scrollbar_variant: ScrollbarVariant = "thin",
+        rows: int = 2,
+        accent: AccentToken | str | None = None,
+        surface: SurfaceToken | str | None = None,
+        parent: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        self._parent = self._resolve_parent(parent)
+        self._selection_mode = selection_mode
+        layout_kw = self._split_layout_kwargs(kwargs)
+        tk_master = self._parent._child_master() if self._parent else None
+
+        internal_kwargs: dict[str, Any] = {
+            "image_field": image_field,
+            "caption_field": caption_field,
+            "columns": columns,
+            "tile_size": tile_size,
+            "fit": fit,
+            "corner_radius": corner_radius,
+            "gap": gap,
+            "selection_mode": selection_mode,
+            "scrollbar_variant": scrollbar_variant,
+            "rows": rows,
+        }
+        if items is not None:
+            internal_kwargs["items"] = items
+        if data_source is not None:
+            internal_kwargs["datasource"] = data_source
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if surface is not None:
+            internal_kwargs["surface"] = surface
+
+        self._internal = _InternalGallery(tk_master, **internal_kwargs)
+        self._internal.pack_propagate(False)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Selection -----
+
+    @property
+    def selection(self) -> dict | list[dict] | None:
+        """The selected record(s) — the data bag.
+
+        In `'single'` mode, the selected record `dict` (or `None`). In `'multi'`
+        mode, a `list` of record dicts (empty when nothing is selected). Each
+        record carries its non-displayed fields too. Read-only.
+        """
+        rows = self._internal.get_selected()
+        if self._selection_mode == "multi":
+            return rows
+        return rows[0] if rows else None
+
+    def select_items(self, record_ids: list) -> None:
+        """Select tiles by record `id`.
+
+        In `'single'` mode this replaces the current selection; in `'multi'`
+        mode the items are added to it.
+
+        Args:
+            record_ids: Record ids of the tiles to select.
+        """
+        self._internal.select_items(record_ids)
+
+    def deselect_items(self, record_ids: list) -> None:
+        """Remove the given tiles from the selection by record `id`.
+
+        Args:
+            record_ids: Record ids to deselect.
+        """
+        self._internal.deselect_items(record_ids)
+
+    def select_all(self) -> None:
+        """Select all tiles. Only effective when `selection_mode='multi'`."""
+        self._internal.select_all()
+
+    def clear_selection(self) -> None:
+        """Deselect all tiles."""
+        self._internal.clear_selection()
+
+    # ----- Scrolling -----
+
+    def scroll_to_top(self) -> None:
+        """Scroll to the first tile."""
+        self._internal.scroll_to_top()
+
+    def scroll_to_bottom(self) -> None:
+        """Scroll to the last tile."""
+        self._internal.scroll_to_bottom()
+
+    def reload(self) -> None:
+        """Reload from the data source and refresh the grid."""
+        self._internal.reload()
+
+    # ----- Properties -----
+
+    @property
+    def data_source(self) -> "DataSourceProtocol":
+        """The underlying data source instance."""
+        return self._internal.get_datasource()
+
+    # ----- Events -----
+
+    @overload
+    def on_item_click(self) -> Stream: ...
+    @overload
+    def on_item_click(self, handler: Callable[[dict[str, Any]], Any]) -> Subscription: ...
+    def on_item_click(
+        self, handler: Callable[[dict[str, Any]], Any] | None = None
+    ) -> Stream | Subscription:
+        """Fired when a tile is clicked.
+
+        Args:
+            handler: Called with the record `dict` — read fields with
+                `e["field"]`. 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("item_click", handler)
+
+    @overload
+    def on_item_activate(self) -> Stream: ...
+    @overload
+    def on_item_activate(self, handler: Callable[[dict[str, Any]], Any]) -> Subscription: ...
+    def on_item_activate(
+        self, handler: Callable[[dict[str, Any]], Any] | None = None
+    ) -> Stream | Subscription:
+        """Fired when a tile is activated (double-clicked).
+
+        The natural hook for opening a full-size viewer or detail page for the
+        chosen record.
+
+        Args:
+            handler: Called with the record `dict`. 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("item_activate", handler)
+
+    @overload
+    def on_select(self) -> Stream: ...
+    @overload
+    def on_select(self, handler: Callable[[Event], Any]) -> Subscription: ...
+    def on_select(
+        self, handler: Callable[[Event], Any] | None = None
+    ) -> Stream | Subscription:
+        """Fired when the selection changes.
+
+        Args:
+            handler: Called with the curated :class:`~bootstack.events.Event`;
+                read `selection` for the current selection. 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("select", handler)
+
+
+_GALLERY_EVENTS: dict[str, str] = {
+    "item_click": "<<ItemClick>>",
+    "item_activate": "<<ItemActivate>>",
+    "select": "<<SelectionChange>>",
+}
+
+register_widget_events(Gallery, _GALLERY_EVENTS)

bootstack/widgets/gauge.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from typing import Literal, overload, Any, Callable
+
+from bootstack.widgets._impl.composites.meter import Meter as _InternalMeter
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.events import register_widget_events
+from bootstack.events import SliderEvent, Subscription
+from bootstack.streams import Stream
+from bootstack.widgets.types import AccentToken, Event, SurfaceToken
+
+
+class Gauge(PublicWidgetBase):
+    """A circular gauge for displaying a value within a range.
+
+    Renders a circular arc gauge with an optional center text display. Supports
+    full-circle and semicircle layouts, solid and segmented arcs, and an
+    interactive drag mode for value input.
+
+    Args:
+        value: Initial value. Defaults to `0`.
+        min_value: Minimum of the range. Defaults to `0`.
+        max_value: Maximum of the range. Defaults to `100`.
+        subtitle: Secondary label displayed below the value text.
+        value_prefix: Text prepended to the displayed value (e.g. `'$'`).
+        value_suffix: Text appended to the displayed value (e.g. `'%'`).
+        value_template: Python format string applied to the value (e.g.
+            `'{:.0f}'`, `'{:.1f}'`). Pair with `value_prefix`/`value_suffix` for
+            units. Default `'{:.0f}'` (integer display). For locale-aware
+            formatting, format the value yourself and pass it via `value=`.
+        size: Diameter of the gauge in pixels. Defaults to `200`.
+        thickness: Width of the arc stroke in pixels. Defaults to `10`.
+        variant: Shape variant. `'full'` (default) draws a complete 360° ring;
+            `'semi'` draws a half-circle arc along the bottom.
+        segment_width: Width of each dash segment for a dashed arc style.
+            `0` (default) draws a solid arc.
+        interactive: If `True`, the user can click or drag the arc to change
+            the value. Defaults to `False`.
+        step: Value increment per drag step in interactive mode. Defaults to `1`.
+        show_text: If `False`, hides the center value text. Defaults to `True`.
+        accent: Color intent token for the arc. Defaults to the theme's default
+            color.
+        surface: Surface token for the gauge background, so it matches the
+            container it sits on (e.g. `'card'` inside a `Card`). Defaults to the
+            window background.
+        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,
+        value: int | float = 0,
+        *,
+        min_value: int | float = 0,
+        max_value: int | float = 100,
+        subtitle: str | None = None,
+        value_prefix: str | None = None,
+        value_suffix: str | None = None,
+        value_template: str = "{:.0f}",
+        size: int = 200,
+        thickness: int = 10,
+        variant: Literal["full", "semi"] = "full",
+        segment_width: int = 0,
+        interactive: bool = False,
+        step: int | float = 1,
+        show_text: bool = True,
+        accent: AccentToken | str | None = None,
+        surface: SurfaceToken | str | 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
+
+        internal_kwargs: dict[str, Any] = {
+            "value": value,
+            "minvalue": min_value,
+            "maxvalue": max_value,
+            "value_format": value_template,
+            "size": size,
+            "thickness": thickness,
+            "meter_type": variant,
+            "segment_width": segment_width,
+            "interactive": interactive,
+            "step_size": step,
+            "show_text": show_text,
+        }
+        if subtitle is not None:
+            internal_kwargs["subtitle"] = subtitle
+        if value_prefix is not None:
+            internal_kwargs["value_prefix"] = value_prefix
+        if value_suffix is not None:
+            internal_kwargs["value_suffix"] = value_suffix
+        if accent is not None:
+            internal_kwargs["accent"] = accent
+        if surface is not None:
+            internal_kwargs["surface"] = surface
+
+        self._internal = _InternalMeter(tk_master, **internal_kwargs)
+        self._attach_to_parent(layout_kw)
+
+    # ----- Properties -----
+
+    @property
+    def value(self) -> int | float:
+        """The current gauge value."""
+        return self._internal.value
+
+    @value.setter
+    def value(self, v: int | float) -> None:
+        self._internal.value = v
+
+    @property
+    def subtitle(self) -> str:
+        """The secondary label shown below the value text."""
+        return self._internal.subtitle
+
+    @subtitle.setter
+    def subtitle(self, v: str) -> None:
+        self._internal.subtitle = v
+
+    @property
+    def min_value(self) -> int | float:
+        """The low end of the range. Assigning to it rescales the gauge live."""
+        return self._internal.cget("minvalue")
+
+    @min_value.setter
+    def min_value(self, v: int | float) -> None:
+        self._internal.configure(minvalue=v)
+
+    @property
+    def max_value(self) -> int | float:
+        """The high end of the range. Assigning to it rescales the gauge live."""
+        return self._internal.cget("maxvalue")
+
+    @max_value.setter
+    def max_value(self, v: int | float) -> None:
+        self._internal.configure(maxvalue=v)
+
+    # ----- Event shorthands -----
+
+    @overload
+    def on_change(self) -> Stream: ...
+    @overload
+    def on_change(self, handler: Callable[[SliderEvent], Any]) -> Subscription: ...
+    def on_change(self, handler: Callable[[SliderEvent], Any] | None = None) -> Stream | Subscription:
+        """Register a callback fired when the gauge value changes.
+
+        Args:
+            handler: Called with a :class:`~bootstack.events.SliderEvent`. 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)
+
+
+_GAUGE_EVENTS: dict[str, str] = {
+    "change": "<<Change>>",
+}
+
+register_widget_events(Gauge, _GAUGE_EVENTS)