bootstack 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,558 @@
+"""Navigation providers — what fills a workspace's sidebar panel.
+
+A provider owns one workspace's sidebar UI *and* its content-rendering strategy,
+behind a small contract: populate the sidebar, report selections via an
+`on_select` callback, and render content for the active key. The shell hosts one
+provider per workspace, routes selections through `NavModel`, and asks the active
+provider to show content. This is the seam that lets static (`add_page`) and the
+data-bound providers (`list_nav`/`tree_nav`, later) be interchangeable.
+
+`StaticProvider` is the first concrete provider: authored items, each with its
+own authored page (N items -> N independent bodies), rendered through a
+`PageStack`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Protocol, runtime_checkable
+
+from bootstack.widgets._impl.primitives.frame import Frame
+from bootstack.widgets._impl.composites.pagestack import PageStack
+from bootstack.widgets._impl.composites.shell.content_host import ContentHost
+from bootstack.widgets._impl.composites.shell.nav_panel import NavPanel
+
+
+@runtime_checkable
+class NavProvider(Protocol):
+    """The contract a workspace's sidebar provider fulfills.
+
+    A provider populates the sidebar and renders content; selection truth lives
+    in the shell's `NavModel`, so the provider only *reports* clicks (via the
+    `on_select` callback given to `mount`) and *reflects* the active key (via
+    `select_visual` / `show`).
+    """
+
+    supports_compact: bool
+    """Whether the sidebar may render icon-only (compact).
+
+    True only for the static provider, whose items carry authored icons. A
+    data-bound list (`list_nav`) or hierarchy (`tree_nav`) cannot meaningfully
+    compact, so theirs is False — they are hidden or shown, never icon-only.
+    Compaction is also gated by the host to the standalone case (no rail).
+    """
+
+    def mount(
+        self,
+        sidebar: Frame,
+        content: Frame,
+        *,
+        on_select: Callable[[str], None],
+        on_refresh: Callable[[], None] | None = None,
+    ) -> None:
+        """Build the sidebar UI in `sidebar` and prepare the `content` region.
+
+        `on_refresh` (optional) is invoked after the provider rebuilds its items
+        from a changed source, so the host can reconcile the active selection.
+        """
+        ...
+
+    def set_compact(self, compact: bool) -> None:
+        """Render the sidebar icon-only (`compact`) or with labels.
+
+        A no-op for providers where `supports_compact` is False.
+        """
+        ...
+
+    def show(self, key: str, data: dict | None = None) -> None:
+        """Render content for the selected `key`."""
+        ...
+
+    def select_visual(self, key: str | None) -> None:
+        """Reflect the active `key` in the sidebar's selection visual."""
+        ...
+
+    def keys(self) -> tuple[str, ...]:
+        """All selectable keys this provider exposes."""
+        ...
+
+
+class StaticProvider:
+    """Static provider — authored items, each with its own authored page.
+
+    Args:
+        accent: Accent token for the active nav item.
+    """
+
+    supports_compact = True
+
+    def __init__(self, *, accent: str | None = None, variant: str = "nav-quiet",
+                 surface: str = "card", selection: str = "ghost") -> None:
+        self._accent = accent
+        self._variant = variant
+        self._surface = surface
+        self._selection = selection
+        self._nav: NavPanel | None = None
+        self._pages: PageStack | None = None
+        self._keys: list[str] = []
+
+    def mount(
+        self,
+        sidebar: Frame,
+        content: Frame,
+        *,
+        on_select: Callable[[str], None],
+        on_refresh: Callable[[], None] | None = None,
+    ) -> None:
+        # Static authoring never refreshes from a source; on_refresh is ignored.
+        self._nav = NavPanel(
+            sidebar, on_select=on_select, accent=self._accent,
+            variant=self._variant, surface=self._surface, selection=self._selection,
+        )
+        self._nav.pack(fill="both", expand=True)
+        self._pages = PageStack(content)
+        self._pages.pack(fill="both", expand=True)
+
+    # ----- Authoring -----
+
+    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."""
+        page = self._pages.add(key)
+        if footer:
+            self._nav.add_footer_item(key, text=text, icon=icon)
+        else:
+            self._nav.add_item(key, text=text, icon=icon)
+        self._keys.append(key)
+        return page
+
+    def add_header(self, text: str) -> Any:
+        """Add a plain section-label header."""
+        return self._nav.add_header(text)
+
+    def add_divider(self) -> Any:
+        """Add a divider."""
+        return self._nav.add_divider()
+
+    # ----- Provider contract -----
+
+    def set_compact(self, compact: bool) -> None:
+        self._nav.set_compact(compact)
+
+    def show(self, key: str, data: dict | None = None) -> None:
+        self._pages.navigate(key, data=data)
+
+    def select_visual(self, key: str | None) -> None:
+        self._nav.select(key)
+
+    def keys(self) -> tuple[str, ...]:
+        return tuple(self._keys)
+
+    # ----- Accessors -----
+
+    @property
+    def nav(self) -> NavPanel:
+        """The sidebar navigation panel."""
+        return self._nav
+
+    @property
+    def pages(self) -> PageStack:
+        """The content page deck."""
+        return self._pages
+
+
+class ListNavProvider:
+    """Flat, data-bound provider — a `DataSource` drives a sidebar `ListView`.
+
+    Each record becomes a single-select row (keyed by record id); selecting one
+    re-renders a single `@detail` body parameterized by that record — the public
+    record dict (the universal `.selection` shape). Rows render the record's
+    `text`/`icon`; the recycling `ListView` follows the source live and inherits
+    the sidebar surface (no surface plumbing needed).
+
+    Args:
+        source: A `DataSourceProtocol` supplying records (with `text`/`icon`).
+        accent: Accent token (the selection control follows it; the row
+            selection itself is a neutral wash by default).
+        separator: Draw separator lines between rows. Default False (flush).
+        chevron: Show a right-pointing chevron on each row. Off by default — a
+            disclosure affordance worth adding only when the row visibly drills
+            into something.
+    """
+
+    # A label-less data list is a poor nav, so list_nav is hidden-or-shown,
+    # never icon-only (spec Revision 2 / R1).
+    supports_compact = False
+
+    def __init__(
+        self,
+        source: Any,
+        *,
+        accent: str | None = None,
+        separator: bool = False,
+        density: str = "default",
+        placeholder: str = "Select an item to view",
+        chevron: bool = False,
+    ) -> None:
+        self._source = source
+        self._accent = accent
+        self._separator = separator
+        self._density = density
+        self._placeholder = placeholder
+        self._chevron = chevron
+        self._listview: Any = None
+        self._host: ContentHost | None = None
+        self._sidebar_host: ContentHost | None = None
+        self._detail: Callable[[dict], Any] | None = None
+        self._selected: str | None = None
+        self._cache: dict[str, dict] = {}
+        self._on_select: Callable[[str], None] | None = None
+        self._on_refresh: Callable[[], None] | None = None
+        self._sub: Any = None
+        self._src_sub: Any = None
+
+    def mount(
+        self,
+        sidebar: Frame,
+        content: Frame,
+        *,
+        on_select: Callable[[str], None],
+        on_refresh: Callable[[], None] | None = None,
+    ) -> None:
+        from bootstack.widgets.listview import ListView
+
+        self._on_select = on_select
+        self._on_refresh = on_refresh
+        self._host = ContentHost(content)
+        self._sidebar_host = ContentHost(sidebar)
+        self._listview = ListView(
+            parent=self._sidebar_host,
+            data_source=self._source,
+            selection_mode="single",
+            show_separators=self._separator,
+            show_scrollbar=False,   # mousewheel scrolls; no always-on bar in a nav
+            show_chevron=self._chevron,  # opt-in disclosure affordance
+            density=self._density,
+            accent=self._accent,
+            # When a nav accent is set, the row selection tints to it (else neutral).
+            accent_selection=bool(self._accent),
+            fill="both",
+            expand=True,
+        )
+        self._cache = self._read()
+        self._sub = self._listview.on_select(self._on_listview_select)
+        # The ListView refreshes its own rows from the source; we observe too, to
+        # re-render the open detail when the selected record changes in place and
+        # to let the host reconcile selection on add/remove.
+        self._src_sub = self._source.on_change(self._on_source_change)
+        # An empty source has no first record to auto-select, so the content area
+        # would be blank — show a quiet placeholder until rows arrive.
+        if not self._cache:
+            self._render_placeholder()
+
+    def _render_placeholder(self) -> None:
+        """Render a centered, muted empty-state in the content region."""
+        from bootstack.widgets._impl.primitives.label import Label
+
+        self._host.clear()
+        Label(self._host._internal, text=self._placeholder, accent="muted").pack(expand=True)
+
+    def set_detail(self, fn: Callable[[dict], Any]) -> None:
+        """Register the parameterized detail body builder."""
+        self._detail = fn
+
+    def _read(self) -> dict[str, dict]:
+        """Read all current public records keyed by id, in source order."""
+        src = self._source
+        out: dict[str, dict] = {}
+        for raw in src.page_slice(0, src.count):
+            rec = src._public_record(raw)
+            out[str(rec.get("id"))] = rec
+        return out
+
+    def _on_listview_select(self, _event: Any = None) -> None:
+        sel = self._listview.selection
+        if not sel:
+            return
+        self._selected = str(sel.get("id"))
+        self._on_select(self._selected)
+
+    def _on_source_change(self, _event: Any = None) -> None:
+        """React to a source change (the ListView refreshes its own rows).
+
+        Re-render the open detail if the selected record changed in place, and
+        let the host reconcile the active selection (e.g. the selected record was
+        removed).
+        """
+        new = self._read()
+        key = self._selected
+        changed = (
+            key is not None and key in new and key in self._cache
+            and new[key] != self._cache[key]
+        )
+        emptied = bool(self._cache) and not new
+        self._cache = new
+        if changed:
+            self.show(key)
+        elif emptied:
+            # The list drained to nothing — replace the stale detail with the
+            # placeholder (the host won't reconcile to a new selection).
+            self._selected = None
+            self._render_placeholder()
+        if self._on_refresh is not None:
+            self._on_refresh()
+
+    def close(self) -> None:
+        """Cancel the selection + source subscriptions."""
+        for sub in (self._sub, self._src_sub):
+            if sub is not None:
+                try:
+                    sub.cancel()
+                except Exception:
+                    pass
+        self._sub = self._src_sub = None
+
+    # ----- Provider contract -----
+
+    def set_compact(self, compact: bool) -> None:
+        # list_nav never compacts (supports_compact is False); see R1.
+        pass
+
+    def show(self, key: str, data: dict | None = None) -> None:
+        record = self._cache.get(key)
+        if self._detail is not None and record is not None:
+            self._host.clear()
+            with self._host:
+                self._detail(record)
+        else:
+            self._render_placeholder()
+
+    def select_visual(self, key: str | None) -> None:
+        self._selected = key
+        if key is None:
+            self._listview.clear_selection()
+            return
+        record = self._cache.get(key)
+        if record is not None:
+            self._listview.select_items([record.get("id")])
+
+    def keys(self) -> tuple[str, ...]:
+        return tuple(self._read().keys())
+
+    # ----- Accessors -----
+
+    @property
+    def nav(self) -> Any:
+        """The sidebar list widget (the `ListView`)."""
+        return self._listview
+
+    @property
+    def listview(self) -> Any:
+        """The sidebar `ListView`."""
+        return self._listview
+
+
+class TreeNavProvider:
+    """Hierarchical, data-bound provider — a `Tree` drives the sidebar.
+
+    Nodes may be declared inline (`nodes=`) or projected from a flat
+    adjacency-list `source` (`source=`/`parent_field=`). Selecting a node
+    re-renders one `@detail` body with the node normalized to a record dict
+    (`text` from the node label, `icon`, the node id, plus the node's data bag) —
+    the same universal `.selection` shape `list_nav` uses (spec decision #10).
+
+    Hierarchy is incompatible with the icon-rail (a branch cannot render as one
+    glyph), so this provider does not support compaction.
+    """
+
+    supports_compact = False
+
+    def __init__(
+        self,
+        *,
+        nodes: list | None = None,
+        source: Any = None,
+        parent_field: str = "parent_id",
+        label_field: str = "name",
+        icon_field: str = "icon",
+        accent: str | None = None,
+        density: str = "default",
+        placeholder: str = "Select an item to view",
+    ) -> None:
+        self._nodes = nodes
+        self._source = source
+        self._parent_field = parent_field
+        self._label_field = label_field
+        self._icon_field = icon_field
+        self._accent = accent
+        self._density = density
+        self._placeholder = placeholder
+        self._tree: Any = None
+        self._host: ContentHost | None = None
+        self._sidebar_host: ContentHost | None = None
+        self._detail: Callable[[dict], Any] | None = None
+        self._on_select: Callable[[str], None] | None = None
+        self._nodes_by_key: dict[str, Any] = {}
+        self._sub: Any = None
+
+    def mount(
+        self,
+        sidebar: Frame,
+        content: Frame,
+        *,
+        on_select: Callable[[str], None],
+        on_refresh: Callable[[], None] | None = None,
+    ) -> None:
+        from bootstack.widgets.tree import Tree
+
+        self._on_select = on_select
+        self._host = ContentHost(content)
+        self._sidebar_host = ContentHost(sidebar)
+
+        tree_kwargs: dict[str, Any] = {
+            "parent": self._sidebar_host,
+            "selection_mode": "single",
+            "show_scrollbar": False,
+            "density": self._density,
+            "accent": self._accent,
+            # When a nav accent is set, the row selection tints to it (else neutral).
+            "accent_selection": bool(self._accent),
+            "fill": "both",
+            "expand": True,
+        }
+        if self._source is not None:
+            tree_kwargs.update(
+                data_source=self._source,
+                parent_field=self._parent_field,
+                label_field=self._label_field,
+                icon_field=self._icon_field,
+            )
+        elif self._nodes is not None:
+            tree_kwargs["nodes"] = self._nodes
+        self._tree = Tree(**tree_kwargs)
+        self._sub = self._tree.on_select(self._on_tree_select)
+        # A tree opens with nothing selected, so the content area would be blank.
+        # Show a quiet placeholder until the first node is picked.
+        self._render_placeholder()
+
+    def _render_placeholder(self) -> None:
+        """Render a centered, muted empty-state in the content region."""
+        from bootstack.widgets._impl.primitives.label import Label
+
+        self._host.clear()
+        Label(self._host._internal, text=self._placeholder, accent="muted").pack(expand=True)
+
+    def set_detail(self, fn: Callable[[dict], Any]) -> None:
+        """Register the parameterized detail body builder."""
+        self._detail = fn
+
+    # ----- Selection plumbing (node identity -> string key) -----
+
+    def _key_for(self, node: Any) -> str:
+        key = str(id(node))
+        self._nodes_by_key[key] = node
+        return key
+
+    def _record(self, node: Any, key: str) -> dict:
+        rec = dict(getattr(node, "data", {}) or {})
+        rec["text"] = node.label
+        rec["icon"] = node.icon
+        rec["id"] = key
+        return rec
+
+    def _on_tree_select(self, _event: Any) -> None:
+        node = self._tree.selection
+        if node is None:
+            return
+        self._on_select(self._key_for(node))
+
+    # ----- Provider contract -----
+
+    def set_compact(self, compact: bool) -> None:
+        # A hierarchy cannot render as icons; tree_nav never compacts (see R1).
+        pass
+
+    def show(self, key: str, data: dict | None = None) -> None:
+        node = self._nodes_by_key.get(key)
+        if self._detail is not None and node is not None:
+            self._host.clear()
+            with self._host:
+                self._detail(self._record(node, key))
+        else:
+            self._render_placeholder()
+
+    def select_visual(self, key: str | None) -> None:
+        node = self._nodes_by_key.get(key) if key is not None else None
+        if node is not None:
+            self._tree.select(node)
+
+    def keys(self) -> tuple[str, ...]:
+        # Trees register keys lazily as nodes are selected (nodes may be created
+        # on expand). Empty until the first selection — so the shell never
+        # auto-selects a tree (a tree opens with nothing selected).
+        return tuple(self._nodes_by_key)
+
+    def close(self) -> None:
+        """Cancel the tree selection subscription."""
+        if self._sub is not None:
+            try:
+                self._sub.cancel()
+            except Exception:
+                pass
+            self._sub = None
+
+    # ----- Accessors -----
+
+    @property
+    def tree(self) -> Any:
+        """The sidebar `Tree` widget."""
+        return self._tree
+
+
+class CustomProvider:
+    """Escape-hatch provider — a blank sidebar container the user fills.
+
+    There is no cascade and no per-page memory: the workspace hands back the
+    sidebar container (via `panel`) and its content region (via `Workspace.content`)
+    and the user drives content-switching themselves. A custom panel cannot
+    collapse to icons (its content is arbitrary), so `supports_compact` is False —
+    it only hides.
+    """
+
+    supports_compact = False
+
+    def __init__(self) -> None:
+        self._container: Frame | None = None
+        self._content: Frame | None = None
+
+    def mount(
+        self,
+        sidebar: Frame,
+        content: Frame,
+        *,
+        on_select: Callable[[str], None],
+        on_refresh: Callable[[], None] | None = None,
+    ) -> None:
+        # No selection model: on_select/on_refresh are unused.
+        self._container = Frame(sidebar)
+        self._container.pack(fill="both", expand=True)
+        self._content = content
+
+    # ----- Provider contract (mostly inert) -----
+
+    def set_compact(self, compact: bool) -> None:
+        pass
+
+    def show(self, key: str, data: dict | None = None) -> None:
+        pass
+
+    def select_visual(self, key: str | None) -> None:
+        pass
+
+    def keys(self) -> tuple[str, ...]:
+        return ()
+
+    # ----- Accessors -----
+
+    @property
+    def container(self) -> Frame:
+        """The blank sidebar container to fill."""
+        return self._container

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

@@ -0,0 +1,117 @@
+"""The workspace rail — the tier-1 icon switcher.
+
+A vertical strip of icon-only items, one per workspace, with a pinned footer
+(for global workspaces like Settings). The rail is a single-select **radio
+group**: every item is a `RadioToggle` sharing one `Signal`, so single-select is
+the radio machinery itself — no hand-rolled selection state.
+
+The items use the `rail` Toolbutton style variant (the VS Code activity-bar
+treatment: muted glyph -> full-strength glyph + accent indicator bar on the
+chrome surface). Selection truth still lives in the shell's `NavModel`; the rail
+reports clicks and reflects the active workspace by setting its shared signal.
+
+The VS Code gesture (click the active icon -> hide the sidebar) needs *every*
+click — including a re-click on the already-selected item, which a radio does not
+report as a change — so each item also has a direct click binding that routes to
+the shell.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from bootstack.signals import Signal
+from bootstack.widgets._impl.primitives.frame import Frame
+from bootstack.widgets._impl.primitives.radiotoggle import RadioToggle
+
+
+class Rail(Frame):
+    """A single-select icon rail of workspaces (a radio-toggle group).
+
+    Args:
+        master: Parent widget (the rail region).
+        on_select: Called with a workspace key when its icon is clicked.
+        accent: Accent token for the active item.
+    """
+
+    # Rail glyphs read as standalone, categorical marks — distinctly larger than
+    # the inline sidebar icons. Decision #13's rail_icon_size.
+    DEFAULT_ICON_SIZE = 28
+
+    def __init__(
+        self,
+        master,
+        *,
+        on_select: Callable[[str], None],
+        accent: str | None = None,
+        icon_size: int | None = None,
+        labels: bool = False,
+        surface: str = "chrome",
+    ) -> None:
+        super().__init__(master, surface=surface)
+        self._on_select = on_select
+        self._accent = accent
+        self._surface = surface
+        self._labels = labels
+        self._icon_size = icon_size if icon_size is not None else self.DEFAULT_ICON_SIZE
+        # Shared selection signal: the value is the active workspace key, so the
+        # matching RadioToggle renders selected (radio single-select). A Signal is
+        # typed by its initial value, so use an empty-string sentinel for "none"
+        # (no workspace key is empty) rather than None.
+        self._signal: Signal = Signal("")
+        self._items: dict[str, RadioToggle] = {}
+
+        self._footer = Frame(self, surface=surface)
+        self._footer.pack(side="bottom", fill="x")
+        self._main = Frame(self, surface=surface)
+        self._main.pack(side="top", fill="both", expand=True)
+
+    def add_workspace(self, key: str, *, icon=None, text: str = "", footer: bool = False) -> RadioToggle:
+        """Add a workspace icon to the rail (or its footer)."""
+        if key in self._items:
+            raise ValueError(f"duplicate rail key: {key!r}")
+        parent = self._footer if footer else self._main
+        # Labeled rail: a small caption under the icon (compound='top'); otherwise
+        # icon-only (relies on tooltips for discoverability — a future add).
+        toggle_kwargs: dict = dict(
+            value=key,
+            signal=self._signal,
+            icon=self._icon_spec(icon),
+            accent=self._accent,
+            variant="rail",
+            surface=self._surface,
+        )
+        if self._labels:
+            toggle_kwargs.update(text=text, compound="top", style_options={"labeled": True})
+        else:
+            toggle_kwargs.update(icon_only=True)
+        item = RadioToggle(parent, **toggle_kwargs)
+        item.pack(fill="x")
+        # Catch ALL clicks (including a re-click on the active item) so the shell
+        # can run the VS Code gesture; the radio itself only reports changes.
+        item.bind("<Button-1>", lambda _e, k=key: self._on_select(k), add="+")
+        self._items[key] = item
+        return item
+
+    def _icon_spec(self, icon):
+        """Normalize an icon name/spec to carry the rail icon size."""
+        if icon is None:
+            return None
+        if isinstance(icon, dict):
+            spec = dict(icon)
+            spec.setdefault("size", self._icon_size)
+            return spec
+        return {"name": icon, "size": self._icon_size}
+
+    def select(self, key: str | None) -> None:
+        """Set the visual selection to `key` (or clear with `None`)."""
+        self._signal.set(key if key is not None else "")
+
+    @property
+    def selected(self) -> str | None:
+        """The selected workspace key, or `None`."""
+        return self._signal() or None
+
+    def keys(self) -> tuple[str, ...]:
+        """All workspace keys in insertion order."""
+        return tuple(self._items)