bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/composites/shell/workspace.py

@@ -0,0 +1,273 @@
+"""A workspace — one sidebar panel + content, filled by one provider.
+
+A `Workspace` owns a single navigation provider (chosen lazily and mutually
+exclusive) mounted into its own sidebar-panel frame and content frame. The shell
+holds one workspace per rail icon (and an implicit default workspace for the
+single-tier case). Selection truth lives in the shell's `NavModel`; the workspace
+reports clicks/refreshes back to the shell, which drives the model.
+
+The workspace exposes the same content API the shell does — `add_page` /
+`list_nav` / `tree_nav` / `@detail` / headers — so a single-tier app and a
+two-tier workspace are authored identically (the spec's degenerate-case
+unification).
+
+The sidebar has three authored shapes: a flat nav list (`add_page`), the same
+list chunked by static `add_header` labels (grouped-static), or a data-bound
+`list_nav` / `tree_nav`. There is no built-in collapsible accordion — a section
+that hides/reveals a sub-list is a content concern; compose `bs.Accordion`
+inside a custom `panel()` if you need one.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from bootstack.widgets._impl.composites.shell.providers import (
+    CustomProvider,
+    ListNavProvider,
+    StaticProvider,
+    TreeNavProvider,
+)
+
+
+class Workspace:
+    """One workspace's provider + sidebar-panel/content frames.
+
+    Args:
+        key: Workspace identifier.
+        sidebar_panel: The frame this workspace's sidebar provider mounts into.
+        content_frame: The frame this workspace's content renders into.
+        nav_accent: Accent token for the active nav item.
+        on_select: Called `(workspace_key, page_key)` when an item is clicked.
+        on_refresh: Called `(workspace_key)` after a data-bound provider rebuilds.
+        on_first_page: Called `(workspace_key, page_key)` when the workspace's
+            first page is added (so the shell can auto-select it).
+        nav_variant: Static-item style variant for the tier (`'nav-pill'`
+            standalone, `'nav-quiet'` under a rail).
+        nav_surface: Surface token the sidebar items sit on.
+    """
+
+    def __init__(
+        self,
+        key: str,
+        sidebar_panel: Any,
+        content_frame: Any,
+        *,
+        nav_accent: str,
+        on_select: Callable[[str, str], None],
+        on_refresh: Callable[[str], None],
+        on_first_page: Callable[[str, str], None],
+        nav_variant: str = "nav-quiet",
+        nav_surface: str = "card",
+        nav_selection: str = "ghost",
+    ) -> None:
+        self._key = key
+        self._sidebar = sidebar_panel
+        self._content = content_frame
+        self._nav_accent = nav_accent
+        self._nav_variant = nav_variant
+        self._nav_surface = nav_surface
+        self._nav_selection = nav_selection
+        self._on_select = on_select
+        self._on_refresh = on_refresh
+        self._on_first_page = on_first_page
+        self._provider: Any = None
+
+    @property
+    def key(self) -> str:
+        """The workspace identifier."""
+        return self._key
+
+    @property
+    def provider(self) -> Any:
+        """The workspace's navigation provider (or `None`)."""
+        return self._provider
+
+    @property
+    def supports_compact(self) -> bool:
+        """Whether this workspace's provider can render icon-only (compact)."""
+        return bool(getattr(self._provider, "supports_compact", False))
+
+    def set_compact(self, compact: bool) -> None:
+        """Render the sidebar icon-only (`compact`) or with labels."""
+        if self._provider is not None and hasattr(self._provider, "set_compact"):
+            self._provider.set_compact(compact)
+
+    # ----- Provider selection (lazy + mutually exclusive) -----
+
+    def _ensure_static(self) -> StaticProvider:
+        if self._provider is None:
+            self._provider = StaticProvider(
+                accent=self._nav_accent, variant=self._nav_variant,
+                surface=self._nav_surface, selection=self._nav_selection,
+            )
+            self._mount_provider()
+        elif not isinstance(self._provider, StaticProvider):
+            raise RuntimeError(
+                "cannot mix add_page() with a data-bound provider in one workspace"
+            )
+        return self._provider
+
+    def _claim_provider(self) -> None:
+        if self._provider is not None:
+            raise RuntimeError("this workspace already has a navigation provider")
+
+    def _mount_provider(self) -> None:
+        self._provider.mount(
+            self._sidebar,
+            self._content,
+            on_select=lambda page_key: self._on_select(self._key, page_key),
+            on_refresh=lambda: self._on_refresh(self._key),
+        )
+
+    # ----- Static content API -----
+
+    def page_nav(self, *, selection: str | None = None) -> StaticProvider:
+        """Establish the static page-list provider; return it for authoring.
+
+        Called when the page nav is declared explicitly (so its options have a
+        home), before any `add_page`. `selection` overrides the selected-item
+        treatment (`'ghost'`/`'solid'`). `'solid'` is the standalone (`nav-pill`)
+        emphasis only — under a rail (`nav-quiet`) a solid fill competes with the
+        rail, so it is forced to the wash.
+        """
+        if selection is not None:
+            self._nav_selection = selection if self._nav_variant == "nav-pill" else "ghost"
+        return self._ensure_static()
+
+    def add_page(self, key: str, *, text: str = "", icon=None, footer: bool = False) -> Any:
+        """Add a nav item and its page; return the page frame."""
+        if not key:
+            raise ValueError("page key must be non-empty")
+        provider = self._ensure_static()
+        if key in provider.keys():
+            raise ValueError(f"duplicate page key: {key!r}")
+        first = not provider.keys()
+        page = provider.add_page(key, text=text, icon=icon, footer=footer)
+        if first:
+            self._on_first_page(self._key, key)
+        return page
+
+    def add_footer_page(self, key: str, *, text: str = "", icon=None) -> Any:
+        """Add a nav item pinned to the sidebar footer and its page."""
+        return self.add_page(key, text=text, icon=icon, footer=True)
+
+    def add_header(self, text: str) -> Any:
+        """Add a plain section-label header (grouped-static)."""
+        return self._ensure_static().add_header(text)
+
+    def add_divider(self) -> Any:
+        """Add a divider to the sidebar."""
+        return self._ensure_static().add_divider()
+
+    # ----- Custom mode -----
+
+    def panel(self) -> Any:
+        """Claim the workspace as a custom panel; return its sidebar container.
+
+        The workspace enters custom mode: no provider cascade, no compaction.
+        Fill the returned container with your own sidebar UI (e.g. a
+        `bs.Accordion`) and drive the content region yourself via `content`.
+        """
+        self._claim_provider()
+        self._provider = CustomProvider()
+        self._mount_provider()
+        return self._provider.container
+
+    @property
+    def content(self) -> Any:
+        """The workspace's content region frame (for hand-driven swapping)."""
+        return self._content
+
+    # ----- Data-bound content API -----
+
+    def list_nav(
+        self,
+        source: Any,
+        *,
+        separator: bool = False,
+        density: str = "default",
+        placeholder: str = "Select an item to view",
+        chevron: bool = False,
+    ) -> Any:
+        """Fill the workspace from a `DataSource` (flat master-detail).
+
+        Records render their `icon`/`title`/`text` in a recycling `ListView`
+        (which inherits the sidebar surface). `separator` draws divider lines
+        between rows (default flush); `density` is `'default'`/`'compact'`
+        (compact suits one-line items, default suits richer two-line items).
+        `placeholder` is the quiet empty-state shown in the content area when the
+        source has no records. `chevron` adds a per-row disclosure chevron (off by
+        default — use it only when a row visibly drills into something).
+        """
+        self._claim_provider()
+        self._provider = ListNavProvider(
+            source, accent=self._nav_accent, separator=separator,
+            density=density, placeholder=placeholder, chevron=chevron,
+        )
+        self._mount_provider()
+        return self._provider
+
+    def tree_nav(
+        self,
+        *,
+        nodes: list | None = None,
+        source: Any = None,
+        parent_field: str = "parent_id",
+        label_field: str = "name",
+        icon_field: str = "icon",
+        density: str = "default",
+        placeholder: str = "Select an item to view",
+    ) -> Any:
+        """Fill the workspace from a hierarchy (tree master-detail).
+
+        `density` is `'default'`/`'compact'`. `placeholder` is the quiet
+        empty-state shown in the content area until a node is picked (a tree
+        opens unselected).
+        """
+        self._claim_provider()
+        self._provider = TreeNavProvider(
+            nodes=nodes,
+            source=source,
+            parent_field=parent_field,
+            label_field=label_field,
+            icon_field=icon_field,
+            accent=self._nav_accent,
+            density=density,
+            placeholder=placeholder,
+        )
+        self._mount_provider()
+        return self._provider
+
+    def detail(self, fn: Callable[[dict], Any]) -> Callable[[dict], Any]:
+        """Register the detail body for a data-bound provider (decorator)."""
+        if self._provider is None or not hasattr(self._provider, "set_detail"):
+            raise RuntimeError("detail() requires a data-bound provider (list_nav/tree_nav)")
+        self._provider.set_detail(fn)
+        if self._provider.keys():
+            self._on_first_page(self._key, self._provider.keys()[0])
+        return fn
+
+    # ----- Provider plumbing -----
+
+    def keys(self) -> tuple[str, ...]:
+        """All selectable page/record keys this workspace exposes."""
+        return self._provider.keys() if self._provider is not None else ()
+
+    def show(self, key: str, data: dict | None = None) -> None:
+        """Render content for `key` (delegates to the provider)."""
+        if self._provider is not None:
+            self._provider.show(key, data=data)
+
+    def select_visual(self, key: str | None) -> None:
+        """Reflect the active `key` in the sidebar selection (delegates)."""
+        if self._provider is not None:
+            self._provider.select_visual(key)
+
+    def close(self) -> None:
+        """Release provider resources (e.g. data-source subscriptions)."""
+        if self._provider is not None and hasattr(self._provider, "close"):
+            try:
+                self._provider.close()
+            except Exception:
+                pass

bootstack/widgets/_impl/composites/sidenav/__init__.py

@@ -0,0 +1,16 @@
+"""Static navigation building blocks shared by the shell's nav panel.
+
+The standalone `SideNav` widget was retired with the AppShell rewrite; what
+remains are the two non-interactive primitives the shell's `NavPanel` composes:
+
+- SideNavHeader: a non-selectable section label
+- SideNavSeparator: a visual divider between groups
+"""
+
+from bootstack.widgets._impl.composites.sidenav.header import SideNavHeader
+from bootstack.widgets._impl.composites.sidenav.separator import SideNavSeparator
+
+__all__ = [
+    'SideNavHeader',
+    'SideNavSeparator',
+]

bootstack/widgets/_impl/composites/sidenav/header.py

@@ -0,0 +1,81 @@
+"""SideNavHeader widget for section labels in navigation menus."""
+
+from typing import Any
+
+from typing_extensions import TypedDict, Unpack
+
+from bootstack.widgets._impl.primitives.frame import Frame
+from bootstack.widgets._impl.primitives.label import Label
+from bootstack.widgets._impl.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 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 — a quiet, non-interactive section
+    marker. Uses the 'label' font token for styling.
+
+    A header is always a plain label; it does not collapse its items (a
+    collapsible sub-list is a content concern — use a `bs.Accordion`).
+    """
+
+    DEFAULT_PADDING = (8, 20, 8, 4)
+    DEFAULT_FONT = 'label'
+    # Muted, not full-strength: a section header is quiet chrome that names a
+    # group — it should recede so the clickable items carry the contrast.
+    DEFAULT_ACCENT = 'muted'
+
+    def __init__(
+        self,
+        master: Master = None,
+        text: str = '',
+        **kwargs: Unpack[SideNavHeaderKwargs]
+    ):
+        """Initialize a SideNavHeader.
+
+        Args:
+            master: Parent widget.
+            text: 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)
+
+        # 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

bootstack/widgets/_impl/composites/sidenav/separator.py

@@ -0,0 +1,44 @@
+"""SideNavSeparator widget for visual grouping in navigation menus."""
+
+from typing import Any
+
+from typing_extensions import TypedDict, Unpack
+
+from bootstack.widgets._impl.primitives.frame import Frame
+from bootstack.widgets._impl.primitives.separator import Separator
+from bootstack.widgets.types import Master
+
+
+class SideNavSeparatorKwargs(TypedDict, total=False):
+    # Frame options
+    padding: Any
+    width: int
+    height: int
+
+
+class SideNavSeparator(Frame):
+    """A visual separator for grouping items in a SideNav.
+
+    SideNavSeparator provides a horizontal line to visually separate
+    groups of navigation items. It is a thin wrapper around the Separator
+    primitive with appropriate padding for navigation contexts.
+
+    """
+
+    DEFAULT_PADDING = (0, 4, 0, 4)
+
+    def __init__(self, master: Master = None, **kwargs: Unpack[SideNavSeparatorKwargs]):
+        """Initialize a SideNavSeparator.
+
+        Args:
+            master: Parent widget.
+            **kwargs: Additional arguments passed to Frame.
+        """
+        # Default padding for visual separation
+        kwargs.setdefault('padding', self.DEFAULT_PADDING)
+
+        super().__init__(master, **kwargs)
+
+        # Create horizontal separator
+        self._separator = Separator(self, orient='horizontal')
+        self._separator.pack(fill='x')

bootstack/widgets/_impl/composites/slider/__init__.py

@@ -0,0 +1,7 @@
+"""bs.Slider and bs.RangeSlider — themed canvas-based slider widgets."""
+from .slider import Slider
+from .rangeslider import RangeSlider
+
+__all__ = [
+    "Slider", "RangeSlider",
+]

bootstack/widgets/_impl/composites/slider/_shared.py

@@ -0,0 +1,195 @@
+"""Shared constants and PIL helpers for Slider and RangeSlider."""
+from __future__ import annotations
+
+from PIL import Image, ImageDraw
+from PIL.ImageTk import PhotoImage
+
+# Focus-ring border thickness. Retired (0): the ring was never wired to an
+# actual keyboard-focus style and its frozen color did not track theme changes,
+# so it only ever showed as a stale 1-2px border. Kept as a named constant so
+# the geometry math (`cross_size + HL * 2`) and the highlight kwargs stay valid.
+HL = 0
+
+HANDLE_SIZE = 22   # handle diameter (px) — matches slider-handle.png at standard DPI
+TRACK_H = 6        # track height (px)
+
+# Value badge geometry
+BADGE_H = 22
+BADGE_PAD_X = 8
+BADGE_GAP = 5       # gap between badge bottom and handle top
+BADGE_FONT_SIZE = 9
+
+# Tick geometry
+TICK_GAP = 4
+MAJOR_TICK_H = 8
+MINOR_TICK_H = 4
+LABEL_GAP = 3
+LABEL_FONT_SIZE = 9
+
+# Keyboard step sizes
+STEP = 1
+STEP_LARGE = 10
+
+# Keyboard focus ring (RangeSlider: a halo around the active handle)
+FOCUS_RING_GAP = 2    # gap between the handle edge and the ring
+FOCUS_RING_W = 2      # ring stroke width
+HALO_PAD = FOCUS_RING_GAP + FOCUS_RING_W   # ring overhang beyond the handle,
+                                           # reserved on every side so it can't clip
+
+
+def _make_focus_ring(diameter: int, color: str, width: int = FOCUS_RING_W) -> PhotoImage:
+    """Render a smooth anti-aliased ring (transparent center) as a PhotoImage —
+    the keyboard focus halo drawn around the active handle.
+
+    Drawn as a filled outer disc with the center punched out (an annulus) at 4x
+    and LANCZOS-downsampled, which anti-aliases far better than a thin outline
+    stroke at the target size.
+    """
+    scale = 4
+    s = diameter * scale
+    margin = scale                       # 1px transparent margin so the outer edge
+                                         # isn't clipped at the image boundary
+    img = Image.new("RGBA", (s, s), (0, 0, 0, 0))
+    d = ImageDraw.Draw(img)
+    d.ellipse([margin, margin, s - 1 - margin, s - 1 - margin], fill=color)
+    inset = margin + width * scale       # ring thickness = width (post-downsample)
+    d.ellipse([inset, inset, s - 1 - inset, s - 1 - inset], fill=(0, 0, 0, 0))
+    return PhotoImage(image=img.resize((diameter, diameter), Image.Resampling.LANCZOS))
+
+
+def _make_badge(width: int, height: int, bg_color: str) -> PhotoImage:
+    """Render an anti-aliased pill badge background as a PhotoImage."""
+    sw, sh = width * 2, height * 2
+    r = sh // 2
+    img = Image.new("RGBA", (sw, sh), (0, 0, 0, 0))
+    d = ImageDraw.Draw(img)
+    d.rounded_rectangle([0, 0, sw - 1, sh - 1], radius=r, fill=bg_color)
+    return PhotoImage(image=img.resize((width, height), Image.Resampling.LANCZOS))
+
+
+def _make_handle(fill_color: str, ring_color: str, border_color: str) -> PhotoImage:
+    """Recolor the slider-handle asset and return a PhotoImage.
+
+    Args:
+        fill_color: Accent color for the handle center (magenta channel).
+        ring_color: Surface color for the outer ring (white channel).
+        border_color: Neutral stroke around the outer edge (black channel).
+    """
+    from bootstack.style.utility import recolor_element_image
+    result = recolor_element_image(
+        'slider_handle',
+        white_color=ring_color,
+        black_color=border_color,
+        magenta_color=fill_color,
+    )
+    return result.image
+
+
+def _make_track(
+    track_w: int,
+    track_h: int,
+    fill_start: int,
+    fill_end: int,
+    trough_color: str,
+    fill_color: str,
+    *,
+    vertical: bool = False,
+) -> PhotoImage | None:
+    """Render a slider track (trough + fill region) as a PhotoImage.
+
+    When `vertical=True` the image is rotated 90° CCW so the fill region
+    appears at the bottom of the returned (tall) image.
+    """
+    if track_w < 1:
+        return None
+    # Render at 2× for crisp anti-aliased edges, then LANCZOS-downsample
+    scale = 2
+    sw, sh = track_w * scale, track_h * scale
+    r = sh // 2
+    img = Image.new("RGBA", (sw, sh), (0, 0, 0, 0))
+    d = ImageDraw.Draw(img)
+    d.rounded_rectangle([0, 0, sw - 1, sh - 1], radius=r, fill=trough_color)
+    fw = (fill_end - fill_start) * scale
+    if fw >= 1:
+        d.rounded_rectangle(
+            [fill_start * scale, 0, min(fill_end * scale, sw) - 1, sh - 1],
+            radius=r, fill=fill_color,
+        )
+    img = img.resize((track_w, track_h), Image.Resampling.LANCZOS)
+    if vertical:
+        img = img.rotate(90, expand=True)
+    return PhotoImage(image=img)
+
+
+def get_widget_bg(widget: object) -> str | None:
+    """Return a widget's rendered background as a `#rrggbb` hex string.
+
+    Tries `cget('background')` first (tk widgets), then falls back to the
+    ttk Style lookup (ttk widgets). Returns `None` when neither works.
+    """
+    if widget is None:
+        return None
+    # tk.Frame, tk.Canvas, etc. — direct option
+    try:
+        raw = widget.cget('background')  # type: ignore[union-attr]
+        if raw:
+            r, g, b = widget.winfo_rgb(raw)  # type: ignore[union-attr]
+            return f"#{r // 256:02x}{g // 256:02x}{b // 256:02x}"
+    except Exception:
+        pass
+    # ttk.Frame and bootstack Frame — resolve via style system
+    try:
+        from tkinter import ttk
+        sname = widget.cget('style') or ''  # type: ignore[union-attr]
+        style = ttk.Style(widget)  # type: ignore[arg-type]
+        bg = style.lookup(sname, 'background') if sname else None
+        if not bg:
+            wclass = widget.winfo_class()  # type: ignore[union-attr]
+            bg = style.lookup(wclass, 'background')
+        if bg:
+            r, g, b = widget.winfo_rgb(bg)  # type: ignore[union-attr]
+            return f"#{r // 256:02x}{g // 256:02x}{b // 256:02x}"
+    except Exception:
+        pass
+    return None
+
+
+def resolve_colors(accent: str, surface: str, bg_override: str | None = None) -> dict[str, str]:
+    """Resolve all slider colors from theme tokens.
+
+    Args:
+        accent: Accent token (e.g., `'primary'`, `'success'`).
+        surface: Surface token (e.g., `'content'`, `'card'`).
+        bg_override: Explicit hex background color (`'#rrggbb'`) to use
+            instead of the theme default. Pass the result of
+            `get_widget_bg(master)` to make the slider blend with its
+            container surface.
+
+    Returns:
+        Dict of resolved hex color strings.
+    """
+    from bootstack.style.style import get_style
+    b = get_style().style_builder
+    bg = bg_override or b.color('background')
+    accent_hex = b.color(accent)
+    border = b.border(bg)
+    # A muted tone with guaranteed ≥4.5 contrast against the slider's own surface.
+    # (NOT `foreground[muted]`, which computes muted *relative to the foreground*
+    # and so lands near the background — faint everywhere, invisible in e.g.
+    # solarized-light. `muted_foreground(bg)` is the same value the public
+    # `'muted'` token resolves to.)
+    muted = b.muted_foreground(bg)
+    return {
+        'bg':              bg,
+        'trough':          border,
+        'fill':            accent_hex,
+        'fill_disabled':   muted,
+        'handle':          accent_hex,
+        'handle_disabled': muted,
+        'ring':            bg,
+        'handle_border':   border,
+        'badge_bg':        b.color('foreground'),
+        'badge_text':      b.on_color(b.color('foreground')),
+        'tick':            muted,
+        'focus':           b.color('foreground'),
+    }