bootstack 0.1.0a1__py3-none-any.whl

bootstack/widgets/composites/sidenav/group.py

@@ -0,0 +1,485 @@
+"""SideNavGroup widget for grouping navigation items."""
+
+from __future__ import annotations
+
+from tkinter import TclError, Variable
+from typing import Any, TYPE_CHECKING
+
+from typing_extensions import TypedDict, Unpack
+
+from bootstack.widgets.primitives.frame import Frame
+from bootstack.widgets.primitives.gridframe import GridFrame
+from bootstack.widgets.primitives.label import Label
+from bootstack.widgets.composites.compositeframe import CompositeFrame
+from bootstack.widgets.composites.contextmenu import ContextMenu
+from bootstack.widgets.mixins import configure_delegate
+from bootstack.widgets.types import Master
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+    from bootstack.widgets.composites.sidenav.item import SideNavItem
+
+
+class SideNavGroupKwargs(TypedDict, total=False):
+    key: str
+    text: str
+    icon: Any
+    signal: Any
+    variable: Variable
+    is_expanded: bool
+    accent: str
+    # Frame options
+    padding: Any
+    width: int
+    height: int
+
+
+class SideNavGroup(Frame):
+    """A collapsible group of navigation items.
+
+    SideNavGroup provides a container for related navigation items.
+    In expanded mode, it behaves like an Expander with a chevron toggle.
+    In compact mode, clicking the group shows a popup flyout to the right
+    containing the group's items.
+
+    Uses a single CompositeFrame container with separate icon, text, and
+    chevron labels. In compact mode, text and chevron are hidden and the
+    icon is centered.
+
+    The group shows as selected if any of its child items are currently selected.
+
+    !!! note "Events"
+        - `<<GroupExpanding>>`: Fired before the group expands.
+          `event.data = {'key': str}`
+        - `<<GroupCollapsed>>`: Fired after the group collapses.
+          `event.data = {'key': str}`
+
+    Example:
+        ```python
+        # Groups are created via SideNav.add_group()
+        nav.add_group('files', text='Files', icon='folder')
+        nav.add_item('local', text='Local', icon='hdd', group='files')
+        nav.add_item('cloud', text='Cloud', icon='cloud', group='files')
+        ```
+    """
+
+    # Default padding values (same as SideNavItem)
+    DEFAULT_PADDING_X = 12
+    DEFAULT_PADDING_Y = 6
+    DEFAULT_ICON_GAP = 10
+    COMPACT_PADDING_X = 6
+    COMPACT_PADDING_Y = 6
+
+    def __init__(
+        self,
+        master: Master = None,
+        key: str = '',
+        text: str = '',
+        icon: str | dict = None,
+        signal: 'Signal[Any]' = None,
+        variable: Variable = None,
+        is_expanded: bool = False,
+        **kwargs: Unpack[SideNavGroupKwargs]
+    ):
+        """Initialize a SideNavGroup.
+
+        Args:
+            master (Master | None): Parent widget.
+            key (str): Unique identifier for this group.
+            text (str): Display text for the group.
+            icon (str | dict | None): Icon name or configuration dict.
+            signal (Signal | None): Reactive signal for selection state.
+            variable (Variable | None): Shared variable for selection tracking.
+            is_expanded (bool): Initial expansion state. Default False.
+            **kwargs: Additional arguments passed to Frame.
+        """
+        if not key:
+            raise ValueError("SideNavGroup requires a non-empty 'key'")
+
+        # Extract styling kwargs before super().__init__
+        # Must set these AFTER super().__init__ because TTKWrapperBase also sets _accent
+        saved_accent = kwargs.pop('accent', 'primary')
+
+        super().__init__(master, **kwargs)
+
+        # Set after super() to avoid being overwritten by TTKWrapperBase
+        self._accent = saved_accent
+
+        self._key = key
+        self._text = text
+        self._icon = icon
+        self._signal = signal
+        self._variable = variable
+        self._is_expanded = is_expanded
+
+        # Track child items (managed by SideNav)
+        self._items: dict[str, 'SideNavItem'] = {}
+        self._item_order: list[str] = []
+
+        # Compact mode state
+        self._compact = False
+
+        # Widget references
+        self._container: CompositeFrame | None = None
+        self._icon_label: Label | None = None
+        self._text_label: Label | None = None
+        self._chevron_label: Label | None = None
+        self._content_frame: Frame | None = None
+        self._popup: ContextMenu | None = None
+
+        # Selection state is now managed centrally by SideNav
+        # for better performance (only affected items are updated)
+        self._trace_id: str | None = None
+
+        # Build internal structure
+        self._build_widget()
+
+    def _build_widget(self):
+        """Build the internal widget structure.
+
+        Uses CompositeFrame with NavigationButton styles for the header.
+        Child labels are registered for automatic state coordination.
+        """
+        # Container using NavigationButton.TFrame for selection indicator
+        self._container = CompositeFrame(
+            self,
+            ttk_class='NavigationButton.TFrame',
+            accent=self._accent,
+            padding=(self.DEFAULT_PADDING_X, self.DEFAULT_PADDING_Y,
+                     self.DEFAULT_PADDING_X, self.DEFAULT_PADDING_Y),
+            takefocus=True,
+        )
+        self._container.pack(fill='x')
+
+        # Icon label
+        if self._icon:
+            self._icon_label = Label(
+                self._container,
+                icon=self._icon,
+                icon_only=True,
+                ttk_class='NavigationButton.TLabel',
+                accent=self._accent,
+                takefocus=False,
+            )
+            self._container.register_composite(self._icon_label)
+
+        # Text label
+        self._text_label = Label(
+            self._container,
+            text=self._text,
+            anchor='w',
+            ttk_class='NavigationButton.TLabel',
+            accent=self._accent,
+            takefocus=False,
+        )
+        self._container.register_composite(self._text_label)
+
+        # Chevron for expand/collapse indicator
+        self._chevron_label = Label(
+            self._container,
+            icon=self._get_chevron_icon(),
+            icon_only=True,
+            ttk_class='NavigationButton.TLabel',
+            accent=self._accent,
+            takefocus=False,
+        )
+        self._container.register_composite(self._chevron_label)
+
+        # Apply initial layout
+        self._apply_layout()
+
+        # Bind click events
+        self._bind_events()
+
+        # Content frame for child items
+        self._content_frame = GridFrame(
+            self,
+            columns=1,
+            gap=(0, 0),
+            sticky_items='ew',
+        )
+        if self._is_expanded:
+            self._content_frame.pack(fill='both', expand=True)
+
+        # Set initial selection state
+        self._update_selection_state()
+
+    def _apply_layout(self):
+        """Apply the current layout based on compact mode."""
+        # Clear current layout
+        if self._icon_label:
+            self._icon_label.pack_forget()
+        self._text_label.pack_forget()
+        self._chevron_label.pack_forget()
+
+        if self._compact:
+            # Compact mode: tighter padding, icon centered
+            px = self.COMPACT_PADDING_X
+            py = self.COMPACT_PADDING_Y
+            self._container.configure(padding=(px, py, px, py))
+            if self._icon_label:
+                self._icon_label.pack(expand=True)
+        else:
+            # Expanded mode: restore default padding, icon + text + chevron
+            self._container.configure(
+                padding=(self.DEFAULT_PADDING_X, self.DEFAULT_PADDING_Y,
+                         self.DEFAULT_PADDING_X, self.DEFAULT_PADDING_Y)
+            )
+            if self._icon_label:
+                self._icon_label.pack(side='left', padx=(0, self.DEFAULT_ICON_GAP))
+            self._text_label.pack(side='left', fill='x', expand=True)
+            self._chevron_label.pack(side='right')
+
+    def _bind_events(self):
+        """Bind click and keyboard events.
+
+        Binds click to container and all child widgets since Tkinter
+        doesn't bubble events from children to parents.
+        """
+        self._container.bind('<Button-1>', self._on_header_click, add='+')
+        if self._icon_label:
+            self._icon_label.bind('<Button-1>', self._on_header_click, add='+')
+        self._text_label.bind('<Button-1>', self._on_header_click, add='+')
+        self._chevron_label.bind('<Button-1>', self._on_header_click, add='+')
+
+        # Keyboard support on focusable container
+        self._container.bind('<Return>', self._on_header_click, add='+')
+        self._container.bind('<space>', self._on_header_click, add='+')
+
+    def _get_chevron_icon(self) -> dict:
+        """Get the appropriate chevron icon for current state."""
+        if self._is_expanded:
+            return {'name': 'chevron-up', 'size': 16}
+        else:
+            return {'name': 'chevron-down', 'size': 16}
+
+    def _on_header_click(self, event=None):
+        """Handle header click - toggle expand/collapse or show popup."""
+        self._container.focus_set()
+
+        if self._compact:
+            # In compact mode, show popup
+            self._show_popup()
+        else:
+            # In expanded mode, toggle expand/collapse
+            self.toggle()
+
+    def _update_selection_state(self):
+        """Update visual state based on whether any child is selected."""
+        is_any_selected = self._is_any_child_selected()
+        self._container.set_selected(is_any_selected)
+
+    def set_child_selected(self, has_selected_child: bool) -> None:
+        """Directly set whether a child is selected.
+
+        This is called by SideNav for efficient selection updates,
+        avoiding the need to iterate through children.
+
+        Args:
+            has_selected_child: True if any child item is selected.
+        """
+        self._container.set_selected(has_selected_child)
+
+    def _is_any_child_selected(self) -> bool:
+        """Check if any child item is currently selected."""
+        if not self._variable:
+            return False
+        current = self._variable.get()
+        return current in self._items
+
+    def _show_popup(self):
+        """Show the popup flyout with group items using ContextMenu."""
+        # Always destroy existing popup and create fresh one
+        # (ContextMenu handles click-outside-to-close automatically)
+        self._hide_popup()
+
+        # Create ContextMenu positioned to the right of the container.
+        # SideNav opens this popup via its own click flow, so opt out of
+        # ContextMenu's auto right-click trigger.
+        self._popup = ContextMenu(
+            self,
+            target=self._container,
+            anchor='nw',
+            attach='ne',
+            offset=(4, 0),
+            minwidth=180,
+            trigger=None,
+        )
+
+        # Add items as commands
+        for key in self._item_order:
+            item = self._items[key]
+            item_key = key  # Capture for closure
+            self._popup.add_command(
+                text=item.cget('text'),
+                icon=item.cget('icon'),
+                command=lambda k=item_key: self._on_popup_item_click(k),
+            )
+
+        # Show the popup
+        self._popup.show()
+
+    def _on_popup_item_click(self, key: str):
+        """Handle click on a popup menu item."""
+        if key in self._items:
+            # Set selection
+            if self._variable:
+                self._variable.set(key)
+            # Fire item invoked event
+            self._items[key].event_generate('<<ItemInvoked>>', data={'key': key})
+
+    def _hide_popup(self):
+        """Hide and destroy the popup."""
+        if self._popup:
+            try:
+                self._popup.destroy()
+            except TclError:
+                pass
+            self._popup = None
+
+    # --- Public API ---
+
+    def set_compact(self, compact: bool) -> None:
+        """Set compact mode.
+
+        In compact mode, only the icon is shown and clicking opens a popup
+        with the group's items.
+
+        Args:
+            compact (bool): True for compact mode, False for full display.
+        """
+        if self._compact == compact:
+            return
+
+        self._compact = compact
+        self._hide_popup()
+        self._apply_layout()
+
+        if compact:
+            # Hide content in compact mode
+            self._content_frame.pack_forget()
+        else:
+            # Restore content if expanded
+            if self._is_expanded:
+                self._content_frame.pack(fill='both', expand=True)
+
+        self._update_selection_state()
+
+    def expand(self) -> None:
+        """Expand to show items (expanded mode only)."""
+        if self._compact or self._is_expanded:
+            return
+
+        self._is_expanded = True
+        self._content_frame.pack(fill='both', expand=True)
+        self._chevron_label.configure(icon=self._get_chevron_icon())
+        self.event_generate('<<GroupExpanding>>', data={'key': self._key})
+
+    def collapse(self) -> None:
+        """Collapse to hide items (expanded mode only)."""
+        if self._compact or not self._is_expanded:
+            return
+
+        self._is_expanded = False
+        self._content_frame.pack_forget()
+        self._chevron_label.configure(icon=self._get_chevron_icon())
+        self.event_generate('<<GroupCollapsed>>', data={'key': self._key})
+
+    def toggle(self) -> None:
+        """Toggle expansion state (expanded mode only)."""
+        if self._compact:
+            return
+
+        if self._is_expanded:
+            self.collapse()
+        else:
+            self.expand()
+
+    # --- Internal: Item management (called by SideNav) ---
+
+    def _add_item(self, item: 'SideNavItem') -> None:
+        """Add an item to this group (internal use by SideNav)."""
+        self._items[item.key] = item
+        self._item_order.append(item.key)
+
+    def _remove_item(self, key: str) -> None:
+        """Remove an item from this group (internal use by SideNav)."""
+        if key in self._items:
+            del self._items[key]
+            self._item_order.remove(key)
+
+    # --- Properties ---
+
+    @property
+    def key(self) -> str:
+        """Get the group's unique key."""
+        return self._key
+
+    @property
+    def content_frame(self) -> Frame:
+        """Get the content frame for adding items."""
+        return self._content_frame
+
+    @property
+    def is_expanded(self) -> bool:
+        """Check if group is currently expanded."""
+        return self._is_expanded
+
+    @property
+    def has_items(self) -> bool:
+        """Check if this group has any items."""
+        return len(self._items) > 0
+
+    @property
+    def items(self) -> list['SideNavItem']:
+        """Get all items in order."""
+        return [self._items[key] for key in self._item_order]
+
+    @property
+    def is_any_selected(self) -> bool:
+        """Check if any child item is selected."""
+        return self._is_any_child_selected()
+
+    # --- Configuration Delegates ---
+
+    @configure_delegate('text')
+    def _delegate_text(self, value: str = None):
+        """Configure the group text."""
+        if value is None:
+            return self._text
+        self._text = value
+        if self._text_label:
+            self._text_label.configure(text=value)
+        return None
+
+    @configure_delegate('icon')
+    def _delegate_icon(self, value: str | dict = None):
+        """Configure the group 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._container,
+                icon=value,
+                icon_only=True,
+                ttk_class='NavigationButton.TLabel',
+                accent=self._accent,
+                takefocus=False,
+            )
+            self._container.register_composite(self._icon_label)
+            self._icon_label.bind('<Button-1>', self._on_header_click, add='+')
+            # Re-apply layout
+            self._apply_layout()
+        return None
+
+    # --- Cleanup ---
+
+    def destroy(self):
+        """Clean up resources."""
+        self._hide_popup()
+        super().destroy()

bootstack/widgets/composites/sidenav/header.py

@@ -0,0 +1,83 @@
+"""SideNavHeader widget for section labels in navigation menus."""
+
+from typing import Any
+
+from typing_extensions import TypedDict, Unpack
+
+from bootstack.widgets.primitives.frame import Frame
+from bootstack.widgets.primitives.label import Label
+from bootstack.widgets.mixins import configure_delegate
+from bootstack.widgets.types import Master
+
+
+class SideNavHeaderKwargs(TypedDict, total=False):
+    text: str
+    # Frame options
+    padding: Any
+    width: int
+    height: int
+
+
+class SideNavHeader(Frame):
+    """A non-selectable section header for grouping navigation items.
+
+    SideNavHeader provides a text label to identify groups of related
+    navigation items. Unlike SideNavItem, headers are not selectable
+    and serve only as visual labels. Uses the 'label' font token for styling.
+
+    Example:
+        ```python
+        nav.add_item('home', text='Home', icon='house')
+        nav.add_header('Favorites')  # Creates SideNavHeader
+        nav.add_item('photos', text='Photos', icon='image')
+        nav.add_item('music', text='Music', icon='music-note')
+        ```
+    """
+
+    DEFAULT_PADDING = (8, 20, 8, 4)
+    DEFAULT_FONT = 'label'
+    DEFAULT_ACCENT = 'secondary'
+
+    def __init__(
+        self,
+        master: Master = None,
+        text: str = '',
+        **kwargs: Unpack[SideNavHeaderKwargs]
+    ):
+        """Initialize a SideNavHeader.
+
+        Args:
+            master (Master | None): Parent widget.
+            text (str): The header text to display.
+            **kwargs: Additional arguments passed to Frame.
+        """
+        self._text = text
+
+        # Default padding: more top margin for visual separation between sections
+        kwargs.setdefault('padding', self.DEFAULT_PADDING)
+
+        super().__init__(master, **kwargs)
+
+        # Create header label with 'label' font (smaller, bold) and secondary accent
+        self._text_label = Label(
+            self,
+            text=text,
+            font=self.DEFAULT_FONT,
+            accent=self.DEFAULT_ACCENT,
+            anchor='w',
+        )
+        self._text_label.pack(fill='x')
+
+    @property
+    def text(self) -> str:
+        """Get the header text."""
+        return self._text
+
+    @configure_delegate('text')
+    def _delegate_text(self, value: str = None):
+        """Configure the header text."""
+        if value is None:
+            return self._text
+        self._text = value
+        self._text_label.configure(text=value)
+        return None