bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/composites/accordion.py

@@ -0,0 +1,381 @@
+"""Accordion widget - a container of mutually exclusive expanders."""
+from __future__ import annotations
+
+from typing_extensions import Unpack
+from typing import Any, Callable, TYPE_CHECKING
+
+from bootstack.events import AccordionChangeEvent
+from bootstack.widgets._impl.primitives.frame import Frame, FrameKwargs
+from bootstack.widgets._impl.primitives.separator import Separator
+from bootstack.widgets._impl.composites.expander import Expander
+from bootstack.widgets._impl.mixins import configure_delegate
+from bootstack.widgets.types import Master
+
+if TYPE_CHECKING:
+    pass
+
+
+class Accordion(Frame):
+    """A container of Expander widgets with optional mutual exclusion.
+
+    The Accordion manages a group of Expanders, optionally enforcing that only
+    one can be expanded at a time. When `allow_multiple=False`, expanding one
+    section automatically collapses the others. When `allow_collapse_all=False`,
+    at least one section must remain open.
+    """
+
+    def __init__(
+        self,
+        master: Master = None,
+        *,
+        allow_multiple: bool = False,
+        allow_collapse_all: bool = True,
+        show_separators: bool = False,
+        accent: str = None,
+        variant: str = None,
+        **kwargs: Unpack[FrameKwargs]
+    ):
+        """Create an Accordion widget.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            allow_multiple: If True, multiple sections can be open at once.
+                If False (default), only one section can be open at a time.
+            allow_collapse_all: If True (default), all sections can be collapsed.
+                If False, at least one section must remain open.
+            show_separators: If True, show separators between expanders.
+            accent: Accent token for the expanders (e.g., 'success', 'primary').
+            variant: Variant for the expanders (e.g., 'solid', 'default').
+            **kwargs: Additional arguments passed to Frame.
+        """
+
+        if 'show_border' in kwargs:
+            kwargs.setdefault('padding', 1)  # required to avoid clipping corners
+
+        super().__init__(master, **kwargs)
+
+        self._allow_multiple = allow_multiple
+        self._allow_collapse_all = allow_collapse_all
+        self._show_separators = show_separators
+        self._accent = accent
+        self._variant = variant
+        self._expanders: dict[str, Expander] = {}
+        self._expander_order: list[str] = []
+        self._separator_widgets: list[Separator] = []
+        self._updating = False  # Prevent recursive updates
+        self._counter = 0  # For auto-generating keys
+
+    def add(
+        self,
+        expander: Expander = None,
+        *,
+        key: str = None,
+        title: str = "",
+        icon: str | dict = None,
+        expanded: bool = None,
+        **kwargs
+    ) -> Expander:
+        """Add an expander to the accordion.
+
+        Args:
+            expander: Existing Expander to add. If None, creates one.
+            key: Unique identifier for the expander. Auto-generated if not provided.
+            title: Title for the expander header (when creating new).
+            icon: Icon for the expander header (when creating new).
+            expanded: Initial expansion state. If None, first expander
+                is expanded when allow_collapse_all=False, otherwise collapsed.
+            **kwargs: When expander is None, passed to Expander constructor.
+
+        Returns:
+            Expander: The added or created Expander widget.
+
+        Raises:
+            ValueError: If an expander with the same key already exists.
+        """
+        # Auto-generate key if not provided
+        if key is None:
+            key = f"expander_{self._counter}"
+            self._counter += 1
+
+        if key in self._expanders:
+            raise ValueError(f"An expander with the key '{key}' already exists.")
+
+        # Add separator before this expander (if not the first)
+        if self._show_separators and len(self._expanders) > 0:
+            sep = Separator(self, orient='horizontal')
+            sep.pack(fill='x')
+            self._separator_widgets.append(sep)
+
+        # Create expander if not provided
+        if expander is None:
+            # Determine initial expanded state
+            if expanded is None:
+                # If not collapsible and this is the first, expand it
+                if not self._allow_collapse_all and len(self._expanders) == 0:
+                    expanded = True
+                else:
+                    expanded = False
+
+            # Get accent/variant from kwargs or use accordion defaults
+            accent = self._accent or kwargs.pop('accent', None)
+            variant = self._variant or kwargs.pop('variant', None)
+
+            expander = Expander(
+                self,
+                title=title,
+                icon=icon,
+                expanded=expanded,
+                highlight=True,
+                accent=accent,
+                variant=variant,
+                **kwargs
+            )
+        else:
+            # Configure existing expander
+            expander.configure(highlight=False)
+            if expanded is not None:
+                if expanded:
+                    expander.expand()
+                else:
+                    expander.collapse()
+
+        expander.pack(fill='x')
+        self._expanders[key] = expander
+        self._expander_order.append(key)
+
+        # Bind to toggle events
+        expander.on_toggled(lambda e, exp=expander: self._on_expander_toggle(exp, e))
+
+        return expander
+
+    def remove(self, key: str) -> None:
+        """Remove an expander from the accordion.
+
+        Args:
+            key: The key of the expander to remove.
+
+        Raises:
+            KeyError: If no expander with the given key exists.
+
+        Note:
+            The expander widget is destroyed. If allow_collapse_all=False and
+            removing would leave no expanders, or would remove the only
+            open expander, another expander will be expanded automatically.
+        """
+        if key not in self._expanders:
+            raise KeyError(f"No expander with key '{key}'")
+
+        expander = self._expanders[key]
+        index = self._expander_order.index(key)
+        was_expanded = expander['expanded']
+
+        # Remove associated separator
+        if self._show_separators and self._separator_widgets:
+            if index > 0:
+                # Remove the separator before this expander
+                sep_index = index - 1
+            elif len(self._expanders) > 1:
+                # Removing first expander - remove the separator after it
+                sep_index = 0
+            else:
+                sep_index = None
+
+            if sep_index is not None and sep_index < len(self._separator_widgets):
+                sep = self._separator_widgets.pop(sep_index)
+                sep.destroy()
+
+        # Remove expander from dict/list and destroy
+        del self._expanders[key]
+        self._expander_order.remove(key)
+        expander.destroy()
+
+        # Handle allow_collapse_all=False constraint
+        if not self._allow_collapse_all and was_expanded and self._expanders:
+            # The removed expander was open - need to open another
+            expander_list = [self._expanders[k] for k in self._expander_order]
+            any_open = any(exp['expanded'] for exp in expander_list)
+            if not any_open:
+                expander_list[0].expand()
+
+        # Fire change event
+        if self._expanders:
+            expander_list = [self._expanders[k] for k in self._expander_order]
+            self.event_generate('<<AccordionChange>>', data=AccordionChangeEvent(
+                expanded=tuple(exp for exp in expander_list if exp['expanded'])
+            ))
+
+    def _on_expander_toggle(self, expander: Expander, event):
+        """Handle expander toggle events."""
+        if self._updating:
+            return
+
+        self._updating = True
+        try:
+            is_expanded = event.data.expanded
+            expander_list = [self._expanders[k] for k in self._expander_order]
+
+            if is_expanded:
+                # Expander was just opened
+                if not self._allow_multiple:
+                    # Collapse all others
+                    for exp in expander_list:
+                        if exp is not expander and exp['expanded']:
+                            exp.collapse()
+            else:
+                # Expander was just closed
+                if not self._allow_collapse_all:
+                    # Check if any are still open
+                    any_open = any(exp['expanded'] for exp in expander_list)
+                    if not any_open:
+                        # Re-open this one - can't collapse all
+                        expander.expand()
+                        return
+
+            # Fire change event
+            self.event_generate('<<AccordionChange>>', data=AccordionChangeEvent(
+                expanded=tuple(exp for exp in expander_list if exp['expanded'])
+            ))
+        finally:
+            self._updating = False
+
+    def item(self, key: str) -> Expander:
+        """Get an expander by its key.
+
+        Args:
+            key: The key of the expander to retrieve.
+
+        Returns:
+            The Expander instance.
+
+        Raises:
+            KeyError: If no expander with the given key exists.
+        """
+        if key not in self._expanders:
+            raise KeyError(f"No expander with key '{key}'")
+        return self._expanders[key]
+
+    def items(self, expanded: bool | None = None) -> tuple[Expander, ...]:
+        """Get expander widgets in insertion order, optionally filtered by state.
+
+        Args:
+            expanded: If `True`, return only expanded expanders. If `False`,
+                return only collapsed expanders. If `None` (default), return all.
+
+        Returns:
+            A tuple of matching Expander instances.
+        """
+        expanders = (self._expanders[key] for key in self._expander_order)
+        if expanded is None:
+            return tuple(expanders)
+        return tuple(e for e in expanders if bool(e['expanded']) == expanded)
+
+    def keys(self) -> tuple[str, ...]:
+        """Get all expander keys in order.
+
+        Returns:
+            A tuple of all expander keys in the order they were added.
+        """
+        return tuple(self._expander_order)
+
+    def configure_item(self, key: str, option: str = None, **kwargs: Any):
+        """Configure a specific expander by its key.
+
+        Args:
+            key: The key of the expander to configure.
+            option: If provided, return the value of this option.
+            **kwargs: Configuration options to apply to the expander.
+
+        Returns:
+            If option is provided, returns the value of that option.
+        """
+        expander = self.item(key)
+        if option is not None:
+            return expander.cget(option)
+        expander.configure(**kwargs)
+
+    def expand(self, key: str):
+        """Expand the expander with the given key.
+
+        Args:
+            key: Key of the expander to expand.
+        """
+        if key in self._expanders:
+            self._expanders[key].expand()
+
+    def collapse(self, key: str):
+        """Collapse the expander with the given key.
+
+        Args:
+            key: Key of the expander to collapse.
+
+        Note:
+            If allow_collapse_all=False and this is the only open expander,
+            this call will be ignored.
+        """
+        if key in self._expanders:
+            exp = self._expanders[key]
+            if not self._allow_collapse_all:
+                # Check if this is the only open one
+                expander_list = [self._expanders[k] for k in self._expander_order]
+                open_count = sum(1 for e in expander_list if e['expanded'])
+                if open_count <= 1 and exp['expanded']:
+                    return  # Can't collapse the last one
+            exp.collapse()
+
+    def expand_all(self):
+        """Expand all expanders (only effective when allow_multiple=True)."""
+        if not self._allow_multiple:
+            return
+        for exp in self._expanders.values():
+            exp.expand()
+
+    def collapse_all(self):
+        """Collapse all expanders (only effective when allow_collapse_all=True)."""
+        if not self._allow_collapse_all:
+            return
+        for exp in self._expanders.values():
+            exp.collapse()
+
+    @configure_delegate('allow_multiple')
+    def _delegate_allow_multiple(self, value=None):
+        """Get or set whether multiple sections can be open at once."""
+        if value is None:
+            return self._allow_multiple
+        self._allow_multiple = value
+        return None
+
+    @configure_delegate('allow_collapse_all')
+    def _delegate_allow_collapse_all(self, value=None):
+        """Get or set whether all sections can be collapsed."""
+        if value is None:
+            return self._allow_collapse_all
+        self._allow_collapse_all = value
+        return None
+
+    @configure_delegate('show_separators')
+    def _delegate_show_separators(self, value=None):
+        """Get or set whether separators are shown between sections."""
+        if value is None:
+            return self._show_separators
+        self._show_separators = value
+        return None
+
+    def on_accordion_changed(self, callback: Callable[[AccordionChangeEvent], None]) -> str:
+        """Register a callback for `<<AccordionChange>>` events.
+
+        Args:
+            callback: Receives an `AccordionChangeEvent` payload with attribute
+                `expanded` (list of currently open Expanders).
+
+        Returns:
+            Bind ID — pass to `off_accordion_changed()` to unsubscribe.
+        """
+        return self.bind('<<AccordionChange>>', callback, add='+')
+
+    def off_accordion_changed(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<AccordionChange>>`.
+
+        Args:
+            bind_id: ID returned by `on_accordion_changed()`. If None, removes all.
+        """
+        self.unbind('<<AccordionChange>>', bind_id)

bootstack/widgets/_impl/composites/avatar.py

@@ -0,0 +1,191 @@
+"""Internal Avatar composite — a small identity badge.
+
+Shows either an image (cover-fit, clipped to the avatar shape) or initials on a
+filled tile. Canvas-backed: the image path reuses the shared `_image_fit`
+helpers, and initials are drawn as Tk canvas text (so they use the framework's
+fonts cross-platform — PIL has no bundled text font). The public
+`bootstack.Avatar` wrapper drives this.
+"""
+
+from __future__ import annotations
+
+from tkinter import Canvas, TclError
+from typing import Any, Literal
+
+from PIL import Image as PILImage, ImageDraw
+from PIL.Image import Resampling
+from PIL.ImageTk import PhotoImage
+
+from bootstack.style.style import get_style
+from bootstack.widgets._impl.composites._image_fit import fit_image, resolve_pil, round_corners
+from bootstack.widgets._impl.primitives.frame import Frame
+from bootstack.widgets.types import Master
+
+Shape = Literal["circle", "rounded", "square"]
+
+
+def _initials_from(name: str | None, initials: str | None) -> str:
+    """Resolve the initials to show: explicit override, else derived from `name`."""
+    if initials:
+        return initials.strip()[:2].upper()
+    if name:
+        parts = [p for p in name.split() if p]
+        if not parts:
+            return ""
+        if len(parts) == 1:
+            return parts[0][:2].upper()
+        return (parts[0][0] + parts[-1][0]).upper()
+    return ""
+
+
+class Avatar(Frame):
+    """Canvas-backed avatar — an image or initials on a filled tile."""
+
+    def __init__(
+        self,
+        master: Master = None,
+        *,
+        source: Any = None,
+        name: str | None = None,
+        initials: str | None = None,
+        size: int = 40,
+        shape: Shape = "circle",
+        background: str = "primary",
+        foreground: str = "white",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(master, **kwargs)
+
+        self._size = max(8, int(size))
+        self._shape: Shape = shape
+        self._background = background
+        self._foreground = foreground
+        self._source = source
+        self._name = name
+        self._initials = initials
+        self._photo: PhotoImage | None = None   # strong ref (Tk GC)
+
+        self._canvas = Canvas(self, width=self._size, height=self._size,
+                              highlightthickness=0, bd=0,
+                              background=self._surface_color())
+        self._canvas.pack()
+        self._canvas.bind("<Button-1>", self._forward_click)
+
+        self._render()
+
+    # ----- helpers -----------------------------------------------------------
+
+    def _surface_color(self) -> str:
+        token = getattr(self, "_surface", None) or "background"
+        b = get_style().style_builder
+        try:
+            return b.color(token)
+        except Exception:
+            return b.color("background")
+
+    def _color(self, token: str) -> str:
+        try:
+            return get_style().style_builder.color(token)
+        except Exception:
+            return token
+
+    def _radius(self) -> int:
+        if self._shape == "circle":
+            return self._size // 2
+        if self._shape == "rounded":
+            return max(1, int(self._size * 0.25))
+        return 0
+
+    # ----- rendering ---------------------------------------------------------
+
+    def _render(self) -> None:
+        self._canvas.delete("all")
+        pil = resolve_pil(self._source) if self._source is not None else None
+        if pil is not None:
+            self._render_image(pil)
+        else:
+            self._render_initials()
+
+    def _render_image(self, pil: PILImage.Image) -> None:
+        composed = fit_image(pil.convert("RGBA"), self._size, self._size, "cover")
+        radius = self._radius()
+        if radius > 0:
+            composed = round_corners(composed, radius)
+        self._photo = PhotoImage(composed)
+        self._canvas.create_image(self._size // 2, self._size // 2,
+                                  image=self._photo, anchor="center")
+
+    def _render_initials(self) -> None:
+        # Filled tile (antialiased) in the background color, clipped to the shape.
+        ss = 4
+        s = self._size
+        big = PILImage.new("RGBA", (s * ss, s * ss), (0, 0, 0, 0))
+        fill = _hex_or_name_to_rgba(self._color(self._background))
+        ImageDraw.Draw(big).rounded_rectangle(
+            [0, 0, s * ss - 1, s * ss - 1], radius=self._radius() * ss, fill=fill
+        )
+        self._photo = PhotoImage(big.resize((s, s), Resampling.LANCZOS))
+        self._canvas.create_image(s // 2, s // 2, image=self._photo, anchor="center")
+
+        text = _initials_from(self._name, self._initials)
+        if text:
+            font_size = max(8, int(s * 0.4))
+            self._canvas.create_text(
+                s // 2, s // 2, text=text, fill=self._text_color(),
+                font=(self._ui_family(), font_size, "bold"), anchor="center",
+            )
+
+    def _text_color(self) -> str:
+        """The resolved foreground color, validated as a Tk color (else white)."""
+        color = self._color(self._foreground)
+        try:
+            self._canvas.winfo_rgb(color)   # authoritative Tk color parse
+            return color
+        except TclError:
+            return "#ffffff"
+
+    @staticmethod
+    def _ui_family() -> str:
+        """The framework's configured UI font family.
+
+        bootstack overrides `TkDefaultFont` to its body font, so reading its
+        actual family gives the app's UI font for the initials text.
+        """
+        from tkinter import font as tkfont
+
+        try:
+            return tkfont.nametofont("TkDefaultFont").actual("family")
+        except Exception:
+            return ""
+
+    def _bs_apply_theme(self, _event=None) -> None:
+        try:
+            self._canvas.configure(background=self._surface_color())
+        except TclError:
+            return
+        self._render()
+
+    def _forward_click(self, event) -> None:
+        self.event_generate("<<AvatarClick>>", x=event.x, y=event.y)
+
+    # ----- live updates ------------------------------------------------------
+
+    def set_source(self, source: Any) -> None:
+        self._source = source
+        self._render()
+
+    def set_text(self, *, name: str | None = None, initials: str | None = None) -> None:
+        self._name = name
+        self._initials = initials
+        self._render()
+
+
+def _hex_or_name_to_rgba(color: str) -> tuple[int, int, int, int]:
+    """Parse a resolved color (hex or name) to an opaque RGBA tuple for PIL fill."""
+    from PIL import ImageColor
+
+    try:
+        r, g, b = ImageColor.getrgb(color)[:3]
+        return (r, g, b, 255)
+    except (ValueError, TypeError):
+        return (108, 117, 125, 255)   # neutral gray fallback