bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/composites/expander.py

@@ -0,0 +1,515 @@
+"""Expander widget - a collapsible container with header and content."""
+from __future__ import annotations
+
+from tkinter import Widget, Variable
+from typing_extensions import Unpack
+from typing import Any, Callable, Literal, TYPE_CHECKING, TypedDict
+
+from bootstack.events import ToggleEvent
+from bootstack.widgets._impl.primitives.frame import Frame, FrameKwargs
+from bootstack.widgets._impl.primitives.label import Label
+from bootstack.widgets._impl.composites.compositeframe import CompositeFrame
+from bootstack.widgets._impl.mixins import configure_delegate
+from bootstack.widgets.types import Master
+from bootstack._core.capabilities.signals import normalize_signal
+
+if TYPE_CHECKING:
+    from bootstack.signals import Signal
+
+
+class SelectedEventData(TypedDict):
+    """Payload for `<<Selected>>` events."""
+    value: Any
+    """The expander's configured value."""
+
+
+class Expander(Frame):
+    """A collapsible container with a clickable header and expandable content.
+
+    The Expander displays a header with an optional icon, title, and chevron
+    button. Clicking anywhere on the header toggles the visibility of the
+    content area.
+
+    Expander also supports selection state via `signal`/`variable` and
+    `value`, similar to RadioButton. When clicked, it sets the variable to
+    its value, enabling radio-group-like behavior for navigation.
+
+    """
+
+    def __init__(
+        self,
+        master: Master = None,
+        title: str = "",
+        icon: str | dict = None,
+        expanded: bool = True,
+        collapsible: bool = True,
+        highlight: bool = False,
+        icon_expanded: str | dict = None,
+        icon_collapsed: str | dict = None,
+        icon_position: Literal["before", "after"] = "after",
+        signal: 'Signal[Any]' = None,
+        variable: Variable = None,
+        value: Any = None,
+        **kwargs: Unpack[FrameKwargs]
+    ):
+        """Create an Expander widget.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            title: Header title text.
+            icon: Icon to display in header (left of title).
+            expanded: Initial expansion state. Default is True (expanded).
+            collapsible: Whether the expander can be toggled. Default is True.
+            highlight: If True, header shows 'selected' state when expanded.
+            icon_expanded: Icon spec for expanded state. Default is chevron-up.
+            icon_collapsed: Icon spec for collapsed state. Default is chevron-down.
+            icon_position: Position of chevron relative to title.
+            signal: Reactive Signal for selection state (preferred over variable).
+            variable: Tk variable for selection state (synced with signal).
+                See [tkinter Variables](https://docs.python.org/3/library/tkinter.html#tkinter-variables).
+            value: Value to set on signal/variable when selected.
+            **kwargs: Additional arguments passed to Frame. Use `accent` and `variant`
+                for styling the header and chevron.
+        """
+        self._header_accent = kwargs.pop('accent', None)
+        self._header_variant = kwargs.pop('variant', None)
+        if 'show_border' in kwargs:
+            kwargs.setdefault('padding', 3)  # need 3 pixels to avoid cutting off corners
+        kwargs.setdefault('takefocus', False)  # Outer container shouldn't take focus
+        super().__init__(master, **kwargs)
+
+        self._title = title
+        self._icon = icon
+        self._expanded = expanded
+        self._collapsible = collapsible
+        self._highlight = highlight
+        self._icon_expanded = icon_expanded
+        self._icon_collapsed = icon_collapsed
+        self._icon_position = icon_position
+        self._content_widget = None
+        self._value = value
+        self._compact = False
+
+        # Selection state - signal/variable syncing
+        self._signal: Signal[Any] | None = None
+        self._variable: Variable | None = None
+        self._trace_id: str | None = None
+
+        # Widget references
+        self._icon_label: Label | None = None
+        self._title_label: Label | None = None
+
+        self._build_widget()
+
+        # Set up signal/variable after widget is built
+        # Prefer signal if both provided
+        if signal is not None:
+            self._set_signal_or_variable(signal)
+        elif variable is not None:
+            self._set_signal_or_variable(variable)
+
+    def _set_signal_or_variable(self, value: Any):
+        """Set up signal/variable binding with trace for selection updates."""
+        # Remove old trace if exists
+        if self._variable is not None and self._trace_id is not None:
+            try:
+                self._variable.trace_remove('write', self._trace_id)
+            except Exception:
+                pass
+
+        # Normalize to get both signal and variable
+        binding = normalize_signal(value)
+        if binding is not None:
+            self._signal = binding.signal
+            self._variable = binding.variable
+        else:
+            # Direct variable
+            self._variable = value
+            self._signal = None
+
+        # Add trace to update selection state
+        if self._variable is not None:
+            self._trace_id = self._variable.trace_add('write', self._on_variable_changed)
+            # Initial update
+            self._update_selection_state()
+
+    def _on_variable_changed(self, *args):
+        """Handle variable changes to update selection state."""
+        self._update_selection_state()
+
+    def _update_selection_state(self):
+        """Update visual state based on selection."""
+        # For now, just track state - visual updates can be added later
+        # when a dedicated nav style is created
+        pass
+
+    @property
+    def _current_chevron_icon(self):
+        """Get the appropriate chevron icon for current state."""
+        if self._expanded:
+            return self._icon_expanded or {'name': 'chevron-up', 'size': 16}
+        else:
+            return self._icon_collapsed or {'name': 'chevron-down', 'size': 16}
+
+    def _build_widget(self):
+        """Build the internal widget structure."""
+        accent = self._header_accent
+        variant = self._header_variant
+
+        # Use CompositeFrame for header to enable hover/pressed/focus states
+        self._header_frame = CompositeFrame(
+            self, ttk_class='Expander.TFrame',
+            accent=accent, variant=variant, padding=8, takefocus=True
+        )
+        self._header_frame.pack(fill='x')
+
+        # Icon (optional, before title)
+        if self._icon:
+            self._icon_label = Label(
+                self._header_frame,
+                icon=self._icon,
+                icon_only=True,
+                ttk_class='Expander.TLabel',
+                accent=accent, variant=variant,
+                takefocus=False,
+            )
+            self._header_frame.register_composite(self._icon_label)
+            self._icon_label.pack(side='left', padx=(0, 8))
+
+        # Title label
+        self._title_label = Label(
+            self._header_frame,
+            text=self._title,
+            anchor='w',
+            ttk_class='Expander.TLabel',
+            accent=accent, variant=variant,
+            takefocus=False,
+        )
+        self._header_frame.register_composite(self._title_label)
+
+        # Toggle button (chevron)
+        self._toggle_button = Label(
+            self._header_frame,
+            icon=self._current_chevron_icon,
+            icon_only=True,
+            accent=accent, variant=variant,
+            ttk_class='Expander.TLabel',
+            takefocus=False,
+        )
+        self._header_frame.register_composite(self._toggle_button)
+
+        # Layout based on icon_position
+        if self._icon_position == "before":
+            self._toggle_button.pack(side='left')
+            self._title_label.pack(side='left', fill='x', expand=True)
+        else:
+            self._title_label.pack(side='left', fill='x', expand=True)
+            self._toggle_button.pack(side='right')
+
+        # Hide button if not collapsible
+        if not self._collapsible:
+            self._toggle_button.pack_forget()
+
+        # Content frame
+        self._content_frame = Frame(self)
+        if self._expanded:
+            self._content_frame.pack(fill='both', expand=True)
+
+        # Set initial highlight state
+        if self._highlight and self._expanded:
+            self._header_frame.set_selected(True)
+
+        # Bind header events
+        self._bind_header_events()
+
+    def _bind_header_events(self):
+        """Make entire header clickable and keyboard accessible."""
+        # Always bind for selection, even if not collapsible
+        self._header_frame.bind('<Button-1>', self._on_header_click, add='+')
+        self._title_label.bind('<Button-1>', self._on_header_click, add='+')
+        if self._icon_label:
+            self._icon_label.bind('<Button-1>', self._on_header_click, add='+')
+
+        # Keyboard support
+        self._header_frame.bind('<Return>', self._on_header_click, add='+')
+        self._header_frame.bind('<space>', self._on_header_click, add='+')
+
+    def _on_header_click(self, event=None):
+        """Handle header click - select and optionally toggle."""
+        # Request focus on click
+        self._header_frame.focus_set()
+
+        # Set selection if variable is configured
+        if self._variable is not None and self._value is not None:
+            self._variable.set(self._value)
+            self.event_generate('<<Selected>>', data={'value': self._value})
+
+        # Toggle expansion if collapsible
+        if self._collapsible:
+            self.toggle()
+
+    def toggle(self):
+        """Toggle expanded/collapsed state."""
+        if not self._collapsible:
+            return
+
+        if self._expanded:
+            self.collapse()
+        else:
+            self.expand()
+
+    def expand(self):
+        """Expand the content area."""
+        if self._expanded:
+            return
+
+        self._expanded = True
+        self._content_frame.pack(fill='both', expand=True)
+        # Recolor any widget that missed a theme change while this section was
+        # collapsed (the theme walk skips off-screen widgets; this is the
+        # genuine "now visible" trigger, like PageStack page navigation).
+        def _recolor(p=self._content_frame):
+            from bootstack.style.style import get_style
+            get_style().apply_theme_walk(p, only_stale=True)
+        self.after_idle(_recolor)
+        self._toggle_button.configure(icon=self._current_chevron_icon)
+        if self._highlight:
+            self._header_frame.set_selected(True)
+        self.event_generate('<<Toggle>>', data=ToggleEvent(expanded=True))
+
+    def collapse(self):
+        """Collapse the content area."""
+        if not self._expanded:
+            return
+
+        self._expanded = False
+        self._content_frame.pack_forget()
+        self._toggle_button.configure(icon=self._current_chevron_icon)
+        if self._highlight:
+            self._header_frame.set_selected(False)
+        self.event_generate('<<Toggle>>', data=ToggleEvent(expanded=False))
+
+    def select(self):
+        """Select this expander (set variable to this expander's value)."""
+        if self._variable is not None and self._value is not None:
+            self._variable.set(self._value)
+
+    def add(self, widget: Widget = None, **kwargs: Unpack[FrameKwargs]) -> Widget:
+        """Add content widget, or create and return an empty frame.
+
+        Args:
+            widget: Optional widget to use as content. If None, creates a Frame.
+            **kwargs: When widget is None, these are passed to Frame (e.g., padding).
+
+        Returns:
+            Widget: The content widget (passed or created).
+
+        Raises:
+            ValueError: If content already exists and widget is provided.
+        """
+        # If content exists and no widget passed, return existing (idempotent)
+        if self._content_widget is not None:
+            if widget is not None:
+                raise ValueError("Expander already has content.")
+            return self._content_widget
+
+        if widget is None:
+            widget = Frame(self._content_frame, **kwargs)
+
+        self._content_widget = widget
+        widget.pack(fill='both', expand=True)
+        return widget
+
+    @property
+    def content(self) -> Frame:
+        """Get the content frame (for direct child parenting)."""
+        return self._content_frame
+
+    @property
+    def is_selected(self) -> bool:
+        """Check if this expander is currently selected."""
+        if self._variable is not None and self._value is not None:
+            return self._variable.get() == self._value
+        return False
+
+    def on_toggled(self, callback: Callable[[ToggleEvent], None]) -> str:
+        """Register a callback for `<<Toggle>>` events.
+
+        Args:
+            callback: Receives a `ToggleEvent` payload with attribute
+                `expanded` (bool — True if now open, False if now closed).
+
+        Returns:
+            Bind ID — pass to `off_toggled()` to unsubscribe.
+        """
+        return self.bind('<<Toggle>>', callback, add='+')
+
+    def off_toggled(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<Toggle>>`.
+
+        Args:
+            bind_id: ID returned by `on_toggled()`. If None, removes all.
+        """
+        self.unbind('<<Toggle>>', bind_id)
+
+    def on_selected(self, callback: Callable[[SelectedEventData], None]) -> str:
+        """Register a callback for `<<Selected>>` events.
+
+        Args:
+            callback: Receives a `SelectedEventData` dict with key
+                `value` (the expander's configured value).
+
+        Returns:
+            Bind ID — pass to `off_selected()` to unsubscribe.
+        """
+        return self.bind('<<Selected>>', callback, add='+')
+
+    def off_selected(self, bind_id: str | None = None) -> None:
+        """Unsubscribe from `<<Selected>>`.
+
+        Args:
+            bind_id: ID returned by `on_selected()`. If None, removes all.
+        """
+        self.unbind('<<Selected>>', bind_id)
+
+    @configure_delegate('title')
+    def _delegate_title(self, value=None):
+        """Get or set the title text."""
+        if value is None:
+            return self._title
+        self._title = value
+        self._title_label.configure(text=value)
+        return None
+
+    @configure_delegate('icon')
+    def _delegate_icon(self, value=None):
+        """Get or set the header icon."""
+        if value is None:
+            return self._icon
+        self._icon = value
+        if self._icon_label is not None:
+            self._icon_label.configure(icon=value)
+        elif value is not None:
+            # Create icon label if it doesn't exist
+            self._icon_label = Label(
+                self._header_frame,
+                icon=value,
+                icon_only=True,
+                ttk_class='Expander.TLabel',
+                accent=self._header_accent, variant=self._header_variant,
+                takefocus=False,
+            )
+            self._header_frame.register_composite(self._icon_label)
+            # Insert at beginning of header
+            self._icon_label.pack(side='left', padx=(0, 8), before=self._title_label)
+            self._icon_label.bind('<Button-1>', self._on_header_click, add='+')
+        return None
+
+    @configure_delegate('collapsible')
+    def _delegate_collapsible(self, value=None):
+        """Get or set whether the expander can be toggled."""
+        if value is None:
+            return self._collapsible
+        self._collapsible = value
+        if value:
+            side = 'left' if self._icon_position == 'before' else 'right'
+            self._toggle_button.pack(side=side)
+        else:
+            self._toggle_button.pack_forget()
+        return None
+
+    @configure_delegate('icon_expanded')
+    def _delegate_icon_expanded(self, value=None):
+        """Get or set the expanded state chevron icon."""
+        if value is None:
+            return self._icon_expanded
+        self._icon_expanded = value
+        if self._expanded:
+            self._toggle_button.configure(icon=self._current_chevron_icon)
+        return None
+
+    @configure_delegate('icon_collapsed')
+    def _delegate_icon_collapsed(self, value=None):
+        """Get or set the collapsed state chevron icon."""
+        if value is None:
+            return self._icon_collapsed
+        self._icon_collapsed = value
+        if not self._expanded:
+            self._toggle_button.configure(icon=self._current_chevron_icon)
+        return None
+
+    @configure_delegate('value')
+    def _delegate_value(self, value=None):
+        """Get or set the selection value."""
+        if value is None:
+            return self._value
+        self._value = value
+        return None
+
+    @configure_delegate('compact')
+    def _delegate_compact(self, value=None):
+        """Get or set compact mode (hides title, shows icon only)."""
+        if value is None:
+            return self._compact
+        self._compact = value
+        if value:
+            # Hide title
+            if self._title_label is not None:
+                self._title_label.pack_forget()
+            # Center the icon
+            if self._icon_label is not None:
+                self._icon_label.pack_forget()
+                self._icon_label.pack(expand=True)
+        else:
+            # Restore icon to left-aligned
+            if self._icon_label is not None:
+                self._icon_label.pack_forget()
+                self._icon_label.pack(side='left', padx=(0, 8))
+            # Re-pack title in correct position
+            if self._title_label is not None:
+                if self._icon_position == "before":
+                    self._title_label.pack(side='left', fill='x', expand=True)
+                else:
+                    # Pack after icon (if exists) or at left
+                    if self._icon_label is not None:
+                        self._title_label.pack(side='left', fill='x', expand=True, after=self._icon_label)
+                    else:
+                        self._title_label.pack(side='left', fill='x', expand=True)
+        return None
+
+    @configure_delegate('highlight')
+    def _delegate_highlight(self, value=None):
+        """Get or set highlight mode (shows 'selected' state when expanded)."""
+        if value is None:
+            return self._highlight
+        self._highlight = value
+        # Update the current state based on new highlight value
+        self._header_frame.set_selected(value and self._expanded)
+        return None
+
+    @configure_delegate('expanded')
+    def _delegate_expanded(self, value=None):
+        """Get or set the expansion state."""
+        if value is None:
+            return self._expanded
+        if value:
+            self.expand()
+        else:
+            self.collapse()
+        return None
+
+    @configure_delegate('signal')
+    def _delegate_signal(self, value=None):
+        """Get or set the signal for selection state."""
+        if value is None:
+            return self._signal
+        self._set_signal_or_variable(value)
+        return None
+
+    @configure_delegate('variable')
+    def _delegate_variable(self, value=None):
+        """Get or set the variable for selection state."""
+        if value is None:
+            return self._variable
+        self._set_signal_or_variable(value)
+        return None