bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_core/navmodel.py

@@ -0,0 +1,345 @@
+"""Headless navigation state for the application shell.
+
+`NavModel` is the single source of truth for shell navigation: the ordered set
+of workspaces, which workspace is active, the active page *per* workspace
+(persistent memory), the sidebar's `hidden -> compact -> expanded` axis, and the
+detail-dock visibility. It is deliberately **Tk-free and testable headless** —
+controls dispatch into it via the transition methods, and view regions subscribe
+to it via `subscribe()`.
+
+The model encodes two design invariants:
+
+- The sidebar is a single linear axis `hidden -> compact -> expanded`, so an
+  incoherent state such as "hidden but expanded" is unrepresentable.
+- The rail (workspace switcher) renders only when there is more than one
+  workspace, so a single-tier app is the degenerate one-workspace case with no
+  branching in the consumer.
+
+See `development/appshell-navigation-spec.md` for the full design.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Literal
+
+from bootstack._core import NavigationError
+from bootstack.streams import Handle
+
+
+SidebarMode = Literal["hidden", "compact", "expanded"]
+"""The sidebar's position on its single linear visibility/compaction axis."""
+
+ProviderKind = Literal["pages", "list", "tree", "custom"]
+"""Which navigation provider fills a workspace's sidebar panel."""
+
+NavFacet = Literal["workspace", "page", "sidebar", "dock", "structure"]
+"""Which part of the navigation state a `NavChange` describes."""
+
+
+@dataclass
+class WorkspaceState:
+    """A workspace registered in the navigation model.
+
+    A workspace owns one sidebar panel (filled by a single provider) and
+    remembers its own active page. The rail renders one icon per workspace.
+    """
+
+    key: str
+    """Unique identifier for the workspace."""
+    text: str = ""
+    """Rail label / tooltip text."""
+    icon: str | dict | None = None
+    """Rail glyph — an icon name or icon-spec dict."""
+    is_footer: bool = False
+    """Whether the rail icon is pinned to the bottom of the rail."""
+    provider: ProviderKind = "pages"
+    """The provider that fills this workspace's sidebar panel."""
+
+
+@dataclass(frozen=True)
+class NavChange:
+    """A notification emitted to subscribers when the model changes.
+
+    Only the field(s) relevant to `facet` are populated; subscribers filter on
+    `facet` and read the corresponding field (or the model itself).
+    """
+
+    facet: NavFacet
+    """Which part of the state changed."""
+    workspace: str | None = None
+    """The affected workspace key, for `'workspace'`/`'page'`/`'structure'`."""
+    page: str | None = None
+    """The newly active page key, for `'page'`."""
+    sidebar_mode: SidebarMode | None = None
+    """The new sidebar mode, for `'sidebar'`."""
+    dock_visible: bool | None = None
+    """The new dock visibility, for `'dock'`."""
+
+
+class NavModel:
+    """Observable, Tk-free navigation state for the shell.
+
+    Construct empty, register workspaces with `add_workspace()`, then drive
+    selection and visibility through the transition methods. Subscribe with
+    `subscribe()` to react to changes.
+
+    Args:
+        sidebar_mode: Initial sidebar mode. Default `'expanded'`.
+        dock_visible: Initial detail-dock visibility. Default `False`.
+    """
+
+    def __init__(
+        self,
+        *,
+        sidebar_mode: SidebarMode = "expanded",
+        dock_visible: bool = False,
+    ) -> None:
+        self._workspaces: list[WorkspaceState] = []
+        self._index: dict[str, WorkspaceState] = {}
+        self._active_workspace: str | None = None
+        self._active_page: dict[str, str] = {}
+        self._sidebar_mode: SidebarMode = sidebar_mode
+        # The mode to restore when un-hiding; never 'hidden'.
+        self._restore_mode: SidebarMode = (
+            sidebar_mode if sidebar_mode != "hidden" else "expanded"
+        )
+        self._dock_visible: bool = dock_visible
+        self._listeners: list[Callable[[NavChange], None]] = []
+
+    # ----- Read state -----
+
+    @property
+    def workspaces(self) -> tuple[WorkspaceState, ...]:
+        """All workspaces in insertion order (footers included)."""
+        return tuple(self._workspaces)
+
+    @property
+    def active_workspace(self) -> str | None:
+        """Key of the active workspace, or `None` if none is active."""
+        return self._active_workspace
+
+    @property
+    def sidebar_mode(self) -> SidebarMode:
+        """The sidebar's current position on the `hidden/compact/expanded` axis."""
+        return self._sidebar_mode
+
+    @property
+    def sidebar_visible(self) -> bool:
+        """Whether the sidebar is shown (i.e. not `'hidden'`)."""
+        return self._sidebar_mode != "hidden"
+
+    @property
+    def dock_visible(self) -> bool:
+        """Whether the detail/inspector dock is shown."""
+        return self._dock_visible
+
+    @property
+    def rail_visible(self) -> bool:
+        """Whether the workspace rail renders — true with more than one workspace.
+
+        A single-tier app has one workspace, so the rail is hidden; the switcher
+        is therefore optional with no branching in the consumer.
+        """
+        return len(self._workspaces) > 1
+
+    def workspace(self, key: str) -> WorkspaceState:
+        """Return the workspace registered under `key`.
+
+        Raises:
+            NavigationError: If no workspace with that key exists.
+        """
+        if key not in self._index:
+            raise NavigationError(f"No workspace with key {key!r}")
+        return self._index[key]
+
+    def has_workspace(self, key: str) -> bool:
+        """Return whether a workspace is registered under `key`."""
+        return key in self._index
+
+    def active_page(self, workspace: str | None = None) -> str | None:
+        """Return the remembered active page for a workspace.
+
+        Args:
+            workspace: Workspace key; defaults to the active workspace.
+
+        Returns:
+            The remembered page key, or `None` if the workspace has none yet.
+        """
+        ws_key = workspace if workspace is not None else self._active_workspace
+        if ws_key is None:
+            return None
+        return self._active_page.get(ws_key)
+
+    # ----- Transitions -----
+
+    def add_workspace(
+        self,
+        key: str,
+        *,
+        text: str = "",
+        icon: str | dict | None = None,
+        is_footer: bool = False,
+        provider: ProviderKind = "pages",
+    ) -> WorkspaceState:
+        """Register a workspace and return its state.
+
+        The first non-footer workspace added becomes active automatically, so a
+        single-tier app shows content without an explicit `select_workspace()`.
+
+        Args:
+            key: Unique workspace identifier.
+            text: Rail label / tooltip.
+            icon: Rail glyph (icon name or icon-spec dict).
+            is_footer: Pin the rail icon to the rail bottom.
+            provider: Provider kind filling the workspace's sidebar.
+
+        Returns:
+            The created `WorkspaceState`.
+
+        Raises:
+            ValueError: If `key` is empty.
+            NavigationError: If `key` is already registered.
+        """
+        if not key:
+            raise ValueError("workspace key must be non-empty")
+        if key in self._index:
+            raise NavigationError(f"Workspace {key!r} already exists")
+
+        ws = WorkspaceState(
+            key=key, text=text, icon=icon, is_footer=is_footer, provider=provider
+        )
+        self._workspaces.append(ws)
+        self._index[key] = ws
+
+        if self._active_workspace is None and not is_footer:
+            self._active_workspace = key
+
+        self._notify(NavChange(facet="structure", workspace=key))
+        return ws
+
+    def select_workspace(self, key: str) -> None:
+        """Make `key` the active workspace (no effect on sidebar visibility).
+
+        This is the lower-level primitive; `activate_rail()` layers the VS Code
+        rail gesture on top.
+
+        Raises:
+            NavigationError: If no workspace with that key exists.
+        """
+        if key not in self._index:
+            raise NavigationError(f"No workspace with key {key!r}")
+        if key == self._active_workspace:
+            return
+        self._active_workspace = key
+        self._notify(NavChange(facet="workspace", workspace=key))
+
+    def select_page(self, key: str, *, workspace: str | None = None) -> None:
+        """Set the active page for a workspace (its remembered page).
+
+        Args:
+            key: Page key.
+            workspace: Workspace to set it on; defaults to the active workspace.
+
+        Raises:
+            NavigationError: If the target workspace does not exist.
+            ValueError: If there is no active workspace and none is given.
+        """
+        ws_key = workspace if workspace is not None else self._active_workspace
+        if ws_key is None:
+            raise ValueError("no active workspace to select a page on")
+        if ws_key not in self._index:
+            raise NavigationError(f"No workspace with key {ws_key!r}")
+        if self._active_page.get(ws_key) == key:
+            return
+        self._active_page[ws_key] = key
+        self._notify(NavChange(facet="page", workspace=ws_key, page=key))
+
+    def activate_rail(self, key: str) -> None:
+        """Handle a rail icon click — the VS Code workspace-switch gesture.
+
+        Clicking the **active** workspace's icon hides the sidebar (or shows it
+        again if already hidden); clicking a **different** workspace's icon
+        switches to it and shows the sidebar.
+
+        Raises:
+            NavigationError: If no workspace with that key exists.
+        """
+        if key not in self._index:
+            raise NavigationError(f"No workspace with key {key!r}")
+        if key == self._active_workspace:
+            self.toggle_sidebar()
+        else:
+            self.select_workspace(key)
+            self.show_sidebar()
+
+    def set_sidebar_mode(self, mode: SidebarMode) -> None:
+        """Set the sidebar mode directly.
+
+        Setting a non-hidden mode records it as the mode to restore when the
+        sidebar is next un-hidden.
+
+        Args:
+            mode: `'hidden'`, `'compact'`, or `'expanded'`.
+
+        Raises:
+            ValueError: If `mode` is not a valid sidebar mode.
+        """
+        if mode not in ("hidden", "compact", "expanded"):
+            raise ValueError(f"invalid sidebar mode: {mode!r}")
+        if mode == self._sidebar_mode:
+            return
+        if mode == "hidden":
+            self._restore_mode = self._sidebar_mode  # current is non-hidden here
+        else:
+            self._restore_mode = mode
+        self._sidebar_mode = mode
+        self._notify(NavChange(facet="sidebar", sidebar_mode=mode))
+
+    def show_sidebar(self) -> None:
+        """Show the sidebar, restoring the last non-hidden mode."""
+        if self._sidebar_mode == "hidden":
+            self.set_sidebar_mode(self._restore_mode)
+
+    def hide_sidebar(self) -> None:
+        """Hide the sidebar entirely (the visibility axis)."""
+        self.set_sidebar_mode("hidden")
+
+    def toggle_sidebar(self) -> None:
+        """Toggle sidebar visibility — the hamburger / shortcut action."""
+        if self._sidebar_mode == "hidden":
+            self.show_sidebar()
+        else:
+            self.hide_sidebar()
+
+    def toggle_dock(self) -> None:
+        """Toggle the detail/inspector dock visibility (its own axis)."""
+        self._dock_visible = not self._dock_visible
+        self._notify(NavChange(facet="dock", dock_visible=self._dock_visible))
+
+    # ----- Subscription -----
+
+    def subscribe(self, listener: Callable[[NavChange], None]) -> Handle:
+        """Register `listener` for change notifications.
+
+        Args:
+            listener: Called with a `NavChange` on every state transition.
+
+        Returns:
+            A cancellable `Handle` (call `.cancel()`, or use as a context
+            manager) that unsubscribes the listener.
+        """
+        self._listeners.append(listener)
+
+        def unsubscribe() -> None:
+            try:
+                self._listeners.remove(listener)
+            except ValueError:
+                pass
+
+        return Handle(unsubscribe)
+
+    def _notify(self, change: NavChange) -> None:
+        # Iterate a copy so a listener may unsubscribe during dispatch.
+        for listener in list(self._listeners):
+            listener(change)

bootstack/widgets/_core/options.py

@@ -0,0 +1,210 @@
+"""Shared normalization for the selection family's option shape.
+
+`Select`, `SelectButton`, `RadioGroup`, and `ToggleGroup` all accept the same
+`Option` shape (a plain string, a `(text, value)` tuple, or an `OptionDict`).
+This module turns any of those into a canonical `OptionRecord` so every widget
+shares one coercion + validation path.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterable, NamedTuple
+
+from bootstack.widgets.types import Option
+
+
+class OptionRecord(NamedTuple):
+    """A normalized option — what every selection widget consumes internally."""
+
+    text: str
+    """Display label."""
+    value: Any
+    """Stored and emitted value."""
+    extras: dict
+    """Reserved per-option extras (e.g. `icon`, `disabled`); empty for now."""
+
+
+def normalize_option(opt: Option) -> OptionRecord:
+    """Coerce a single `Option` to an `OptionRecord`.
+
+    The dict form is a *data bag*: `text` is required (and `value` defaults to
+    it) UNLESS the dict carries an `icon` and a `value`, in which case `text` may
+    be omitted to request an icon-only option (`text` becomes `''`). `text`/
+    `value` and the recognized `icon`/`disabled` act on rendering; every other
+    key rides along as carried data, retrievable via the widget's `selection`.
+    Unrecognized keys are NOT rejected — the dict route is opt-in, so the caller
+    accepts the risk of a mistyped key.
+
+    Args:
+        opt: A plain string, a `(text, value)` tuple, or an `OptionDict`.
+
+    Returns:
+        The normalized `(text, value, extras)` record.
+
+    Raises:
+        TypeError: If `opt` is not a string, 2-tuple, or dict, or if a dict
+            `text` is not a string.
+        ValueError: If a tuple does not have exactly two items, or a dict has
+            neither a `text` key nor an `icon` + `value` pair.
+    """
+    if isinstance(opt, str):
+        return OptionRecord(opt, opt, {})
+
+    if isinstance(opt, dict):
+        if "text" in opt:
+            text = opt["text"]
+            if not isinstance(text, str):
+                raise TypeError(f"option 'text' must be a string, got {type(text).__name__}: {opt!r}")
+        elif "icon" in opt and "value" in opt:
+            # Icon-only option: the label is omitted on purpose. The widget
+            # renders the glyph alone and infers icon-only from the empty text.
+            text = ""
+        else:
+            raise ValueError(
+                "option dict needs a 'text' key (or 'icon' + 'value' for an "
+                f"icon-only option): {opt!r}"
+            )
+        value = opt["value"] if "value" in opt else text
+        # The bag: every key except text/value, including the reserved
+        # icon/disabled (carried now, interpreted by the widget later).
+        extras = {k: opt[k] for k in opt if k not in ("text", "value")}
+        return OptionRecord(text, value, extras)
+
+    if isinstance(opt, tuple):
+        if len(opt) != 2:
+            raise ValueError(f"option tuple must be (text, value), got {len(opt)} items: {opt!r}")
+        text, value = opt
+        if not isinstance(text, str):
+            raise TypeError(f"option text must be a string, got {type(text).__name__}: {opt!r}")
+        return OptionRecord(text, value, {})
+
+    raise TypeError(
+        f"option must be a str, (text, value) tuple, or dict, got {type(opt).__name__}: {opt!r}"
+    )
+
+
+def normalize_options(opts: Iterable[Option] | None) -> list[OptionRecord]:
+    """Coerce an iterable of `Option` values to a list of `OptionRecord`.
+
+    Args:
+        opts: Options to normalize, or `None` for an empty list.
+    """
+    if not opts:
+        return []
+    return [normalize_option(opt) for opt in opts]
+
+
+def record_to_dict(record: OptionRecord) -> dict:
+    """Render an `OptionRecord` as a public `{'text', 'value', ...extras}` dict."""
+    return {"text": record.text, "value": record.value, **record.extras}
+
+
+def record_field(record: OptionRecord, field: str) -> Any:
+    """Read one field from a record by name, spanning `text`/`value`/extras.
+
+    The record is treated as the flat `{'text', 'value', ...extras}` bag, so a
+    grouping or display selector can name any carried key (including `text` or
+    `value`).
+
+    Args:
+        record: The normalized option record.
+        field: The key to read.
+
+    Returns:
+        The field's value, or `None` when the record does not carry it.
+    """
+    if field == "text":
+        return record.text
+    if field == "value":
+        return record.value
+    return record.extras.get(field)
+
+
+def cluster_records(
+    records: list[OptionRecord], group_by: str | None
+) -> list[tuple[str | None, list[OptionRecord]]]:
+    """Cluster records into groups by a named bag field, for presentation.
+
+    Buckets appear in **first-appearance** order — the order each distinct group
+    value is first seen while walking `records`. Within a bucket the source
+    order is preserved. A record whose `group_by` field is absent, `None`, or
+    blank falls into the ungrouped bucket (keyed `None`), which renders without a
+    header; that bucket too keeps its first-appearance position.
+
+    Grouping is purely presentational: every record is returned exactly once and
+    unchanged, so `value`/`selection`/`options` are unaffected.
+
+    Args:
+        records: The normalized option records, in source order.
+        group_by: The field name to cluster by, or `None` to skip grouping (the
+            whole list is returned as a single ungrouped bucket).
+
+    Returns:
+        An ordered list of `(group_label, records)` pairs. `group_label` is the
+        group's value coerced to a string, or `None` for the ungrouped bucket.
+    """
+    if not group_by:
+        return [(None, list(records))]
+    order: list[str | None] = []
+    buckets: dict[str | None, list[OptionRecord]] = {}
+    for rec in records:
+        raw = record_field(rec, group_by)
+        label = None if raw is None or str(raw) == "" else str(raw)
+        if label not in buckets:
+            buckets[label] = []
+            order.append(label)
+        buckets[label].append(rec)
+    return [(label, buckets[label]) for label in order]
+
+
+def option_display(record: OptionRecord) -> tuple[Any, bool]:
+    """Return the `(icon, disabled)` rendering hints from a record's extras.
+
+    These are the two recognized extra keys that the selection widgets act on:
+    `icon` (an icon spec rendered beside the label, or `None`) and `disabled`
+    (when truthy the option is shown dimmed and is not user-selectable). Every
+    other extra is inert carried data. Each widget maps the pair onto its own
+    primitive (`icon=`/`state='disabled'` for the button-backed widgets).
+
+    Args:
+        record: The normalized option record.
+
+    Returns:
+        A `(icon, disabled)` tuple — `icon` is the spec or `None`; `disabled`
+        is a plain `bool`.
+    """
+    return record.extras.get("icon"), bool(record.extras.get("disabled"))
+
+
+def option_localize(record: OptionRecord) -> Any:
+    """Return a record's per-option `localize` override, or `None` if absent.
+
+    The `localize` key rides in the option's extras (the data bag), like `icon`
+    and `disabled`. When present it overrides the widget's group-level
+    `localize=` for just this option; `None` means defer to the group setting.
+
+    Args:
+        record: The normalized option record.
+
+    Returns:
+        The `localize` override (`True`/`False`/`'auto'`), or `None` when the
+        option does not carry one.
+    """
+    return record.extras.get("localize")
+
+
+def option_is_icon_only(record: OptionRecord) -> bool:
+    """Whether an option should render as icon-only (a glyph with no label).
+
+    Inferred — there is no explicit flag: an option is icon-only when it carries
+    an `icon` and its `text` is blank. This lets a compact toggle/radio group be
+    expressed as `[{'icon': 'list', 'value': 'list'}, ...]` without the caller
+    setting `icon_only` per button.
+
+    Args:
+        record: The normalized option record.
+
+    Returns:
+        `True` when the record has an icon and no (non-whitespace) label.
+    """
+    icon = record.extras.get("icon")
+    return icon is not None and not (record.text or "").strip()

bootstack/widgets/_core/selection_group.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from typing import Any
+
+from bootstack.widgets._core.options import OptionRecord, record_to_dict, option_localize
+
+
+class SelectionGroupMixin:
+    """Shared item-management surface for the option-group widgets.
+
+    Mixed into `RadioGroup` and `ToggleGroup`, which both wrap an internal
+    composite exposing `keys()`, `configure_item()`, and `remove()`. Each class
+    keeps its own `add()` (the option semantics differ) and its own value /
+    change surface; only the value-keyed item operations live here.
+
+    The internal composites store only each option's text and value, so the
+    mixin keeps the normalized records here (the data bag) — keyed by the
+    stringified value, matching the selection variable's coercion — so
+    `selection` can hand back each option's full `{text, value, ...extras}`.
+    """
+
+    _internal: Any
+
+    def _set_option_records(self, records: list[OptionRecord]) -> None:
+        """Seed the option records from a normalized construction list."""
+        self._option_records: dict[str, OptionRecord] = {
+            str(rec.value): rec for rec in records
+        }
+
+    def _add_option_record(self, text: str, value: Any, extras: dict | None = None) -> None:
+        """Register a record for an option added at runtime."""
+        if not hasattr(self, "_option_records"):
+            self._option_records = {}
+        self._option_records[str(value)] = OptionRecord(text, value, extras or {})
+
+    def _record_dict_for(self, value: Any) -> dict | None:
+        """Return the `{text, value, ...extras}` dict for a value, or None."""
+        if value is None or value == "":
+            return None
+        rec = getattr(self, "_option_records", {}).get(str(value))
+        return record_to_dict(rec) if rec is not None else None
+
+    @staticmethod
+    def _option_render(icon: Any, disabled: bool, text: str | None = None) -> tuple[dict, dict]:
+        """Map the `icon`/`disabled` hints to (internal-add kwargs, extras).
+
+        The internal group forwards `icon`/`state` to each button primitive; the
+        extras dict is what `selection` hands back. An icon with a blank `text`
+        is inferred as icon-only (the button shows the glyph alone). Returns a
+        pair so a single call seeds both the rendered button and the carried
+        record.
+        """
+        add_kwargs: dict[str, Any] = {}
+        extras: dict[str, Any] = {}
+        if icon is not None:
+            add_kwargs["icon"] = icon
+            extras["icon"] = icon
+            if not (text or "").strip():
+                add_kwargs["icon_only"] = True
+        if disabled:
+            add_kwargs["state"] = "disabled"
+            extras["disabled"] = True
+        return add_kwargs, extras
+
+    def _resolve_localize(self, record: OptionRecord | None = None, override: Any = None) -> Any:
+        """Resolve the effective `localize` for an option.
+
+        Precedence: an explicit per-item `override` (from `add(localize=)`), then
+        the option's own `localize` key (carried in its data bag), then the
+        widget's group-level `localize=`. `None` at every level means defer to
+        the app's `localize_mode`, so it is not forwarded to the item.
+
+        Args:
+            record: The option's normalized record, when adding from options.
+            override: A per-call `localize` from `add()`.
+
+        Returns:
+            The resolved `localize` mode, or `None` to inherit the app default.
+        """
+        if override is not None:
+            return override
+        if record is not None:
+            item = option_localize(record)
+            if item is not None:
+                return item
+        return getattr(self, "_localize", None)
+
+    def remove(self, value: Any) -> None:
+        """Remove the option identified by `value`.
+
+        Args:
+            value: The value the option was added with.
+
+        Raises:
+            KeyError: If no option with that value exists.
+        """
+        self._internal.remove(value)
+        getattr(self, "_option_records", {}).pop(str(value), None)
+
+    def configure_item(
+        self,
+        value: Any,
+        *,
+        label: str | None = None,
+        disabled: bool | None = None,
+    ) -> None:
+        """Update a single option in place, without rebuilding the group.
+
+        Args:
+            value: The option to update (the value it was added with).
+            label: New display text, when given.
+            disabled: When given, disable (`True`) or re-enable (`False`) just
+                this option. A later group-level `disabled` change resets every
+                option's state, so apply per-option states after it.
+
+        Raises:
+            KeyError: If no option with that value exists.
+        """
+        if label is not None:
+            self._internal.configure_item(value, text=label)
+        if disabled is not None:
+            self._internal.configure_item(value, state="disabled" if disabled else "normal")
+
+    def __len__(self) -> int:
+        """The number of options in the group."""
+        return len(self._internal.keys())
+
+    def __contains__(self, value: Any) -> bool:
+        """Whether an option with the given `value` is in the group."""
+        return value in self._internal.keys()