feat(portfolios): show aggregate value in the footer

Loading multiple portfolios with ``-p`` previously gave per-portfolio
``Total`` rows but no overall figure, so users splitting their holdings
across work / personal / crypto files had to add the rows up by hand
to answer the obvious "how much do I have right now?" question.

The aggregate sits in the footer just left of ``^palette`` because
that row is the natural status bar for app-wide state -- it doesn't
scroll with the portfolios above it and stays visible no matter how
deep the user scrolls into a portfolio table.  It is computed in the
first portfolio's base currency, with all foreign positions and cash
converted through the same forex map ``portfolio_total`` already
consumes; if any underlying price or rate is missing the label renders
``N/A`` rather than a misleading partial sum.

The label is mounted in single-portfolio mode too (just hidden via a
CSS class) so the footer geometry doesn't shift when the user opens a
second portfolio, and the cached renderable on the Footer subclass
survives Textual's post-``_bindings_ready`` recompose so the value
doesn't flicker back to empty between mount and the first refresh.

Signed-off-by: Igor Opaniuk <igor.opaniuk@gmail.com>

Author: igoropaniuk

src/stonks_cli/app.py

@@ -42,6 +42,7 @@
     Portfolio,
     Position,
     WatchlistItem,
+    combined_portfolio_total,
     portfolio_total,
 )
 from stonks_cli.news_fetcher import NewsFetcher, NewsItem
@@ -408,6 +409,78 @@ def on_click(self) -> None:
         self.post_message(self.Selected(self._index))
 
 
+class _FooterWithTotal(Footer):
+    """``Footer`` subclass that injects a ``Total all portfolios`` label
+    just left of the command-palette indicator.
+
+    Multiple ``dock: right`` widgets in Textual all anchor to the same
+    right edge and overlap, so we can't simply yield a second
+    ``dock: right`` Static after the palette and expect them to stack.
+    Instead we ``dock: right`` the label and offset it leftwards by
+    ``margin-right`` equal to the rendered palette width plus a small
+    gap, putting it visually just to the left of ``^palette``.
+
+    When ``show_total`` is False the label is mounted with the
+    ``-hidden`` class so the DOM is identical between single- and
+    multi-portfolio modes; only its ``display`` flips.
+
+    Footer triggers a ``recompose`` once its ``_bindings_ready`` reactive
+    flips, which wipes any children the previous ``compose`` yielded
+    (including ours).  We cache the most recent renderable on the
+    instance so each recompose re-creates the Static with the value the
+    app last set via :meth:`set_total_renderable`, rather than flashing
+    back to empty between recompose and the next price refresh.
+    """
+
+    # The command-palette FooterKey renders with ``dock: right`` and a
+    # vertical-key border on the left.  Its width is the key glyph + label
+    # padding -- empirically ~12 cells in the default theme.  We clear it
+    # plus a 2-cell gap so the total doesn't visually collide with the
+    # palette border.
+    _PALETTE_GAP = 14
+
+    DEFAULT_CSS = f"""
+    _FooterWithTotal Static#combined-total {{
+        dock: right;
+        width: auto;
+        padding: 0 1;
+        margin-right: {_PALETTE_GAP};
+        color: $accent;
+        text-style: bold;
+    }}
+    _FooterWithTotal Static#combined-total.-hidden {{
+        display: none;
+    }}
+    """
+
+    def __init__(self, *, show_total: bool, **kw: Any) -> None:
+        super().__init__(**kw)
+        self._show_total = show_total
+        self._cached_renderable: Text | str = ""
+
+    def compose(self) -> ComposeResult:
+        yield from super().compose()
+        classes = "" if self._show_total else "-hidden"
+        yield Static(self._cached_renderable, id="combined-total", classes=classes)
+
+    def set_total_renderable(self, renderable: Text | str) -> None:
+        """Update the cached label and the live Static, if mounted.
+
+        Called by the app each time per-portfolio totals are refreshed.
+        Caching on the instance means the next recompose (triggered by
+        ``Footer`` itself when its bindings settle, or later if the key
+        bindings change) re-creates the Static with the latest value.
+        """
+        self._cached_renderable = renderable
+        try:
+            self.query_one("#combined-total", Static).update(renderable)
+        except NoMatches:
+            # Static isn't mounted yet (or was just removed by an
+            # in-flight recompose); the cached value will be picked up
+            # when compose runs again.
+            pass
+
+
 class PortfolioApp(ThreadGuardMixin, App[None]):
     """Full-screen portfolio table with periodic price refresh."""
 
@@ -495,7 +568,14 @@ def compose(self) -> ComposeResult:
         yield Static("", id="status")
         yield Static("", id="error")
         yield NewsFeedWidget(id="news-panel")
-        yield Footer()
+        # The aggregate "Total all portfolios" label only renders when more
+        # than one portfolio is loaded -- in single-portfolio mode it would
+        # just duplicate the per-portfolio Total row.  We always mount it
+        # so the footer layout doesn't shift; visibility is toggled via the
+        # ``-hidden`` class on the Static inside.
+        yield _FooterWithTotal(
+            show_total=len(self.portfolios) > 1,
+        )
 
     def on_mount(self) -> None:
         self._populate_tables()
@@ -971,6 +1051,30 @@ def _populate_tables(self) -> None:
         else:
             for i, portfolio in enumerate(self.portfolios):
                 self._populate_for(i, portfolio)
+            self._update_combined_total()
+
+    def _update_combined_total(self) -> None:
+        """Refresh the aggregate "Total all portfolios" label in the footer.
+
+        Goes through ``_FooterWithTotal.set_total_renderable`` rather than
+        updating the Static directly so the value survives the Footer's
+        post-``_bindings_ready`` recompose -- without the cache, the
+        label would flash to empty between recompose and the next price
+        refresh.
+        """
+        try:
+            footer = self.query_one(_FooterWithTotal)
+        except NoMatches:
+            return
+        total, base = combined_portfolio_total(
+            self.portfolios, self._snap.prices, self._snap.forex_rates
+        )
+        label = Text(f"Total ({base})  ")
+        if total is None:
+            renderable: Text = label.append("N/A", style="bold")
+        else:
+            renderable = label.append(f"{total:,.2f}", style="bold")
+        footer.set_total_renderable(renderable)
 
     def _populate_single(self) -> None:
         try:

src/stonks_cli/models.py

@@ -299,3 +299,39 @@ def portfolio_total(
             return None
         total += cash_pos.amount * rate
     return total
+
+
+def combined_portfolio_total(
+    portfolios: "list[Portfolio]",
+    prices: dict[str, float],
+    forex_rates: dict[str, dict[str, float]],
+) -> tuple[float | None, str]:
+    """Return ``(total, base_currency)`` summed across all *portfolios*.
+
+    The aggregate is computed in the *first* portfolio's ``base_currency`` --
+    every position and cash balance across every portfolio is converted into
+    that currency using ``forex_rates[base]``.  ``base`` is returned alongside
+    the total so callers can render the label without having to look it up
+    themselves.
+
+    Returns ``(None, base)`` when any underlying portfolio's value cannot be
+    computed (missing price or forex rate) so the UI can render "N/A" rather
+    than a misleading partial sum.  Returns ``(None, "USD")`` when the list
+    is empty.
+
+    Args:
+        portfolios: Loaded portfolios to aggregate.
+        prices: Last prices keyed by symbol (shared across all portfolios).
+        forex_rates: Nested forex map ``{base_currency: {position_currency: rate}}``.
+    """
+    if not portfolios:
+        return None, "USD"
+    base = portfolios[0].base_currency
+    rates = forex_rates.get(base, {})
+    total = 0.0
+    for p in portfolios:
+        sub = portfolio_total(p, prices, rates)
+        if sub is None:
+            return None, base
+        total += sub
+    return total, base

tests/test_app.py

@@ -2590,6 +2590,86 @@ async def test_action_chat_no_op_when_already_open(portfolio: Portfolio) -> None
         mock_push.assert_not_called()
 
 
+def _static_content(widget: Static) -> str:
+    """Return the plain-text content currently displayed by a Static widget."""
+    # ``Static`` stores content in a name-mangled ``__content`` attribute.
+    # Going through the name-mangled name is the simplest way to inspect
+    # what was last passed to ``widget.update()`` in tests.
+    content = getattr(widget, "_Static__content", "")
+    return str(content)
+
+
+@pytest.mark.asyncio
+async def test_combined_total_widget_hidden_in_single_portfolio_mode(
+    portfolio: Portfolio,
+) -> None:
+    """The aggregate label is always mounted (so the footer layout stays
+    stable across single-/multi-portfolio modes) but is hidden via the
+    ``-hidden`` class when only one portfolio is loaded -- otherwise it
+    would just duplicate the per-portfolio Total row."""
+    app = PortfolioApp(portfolios=[portfolio], prices={}, forex_rates=USD_RATES)
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        widget = app.query_one("#combined-total", Static)
+        assert "-hidden" in widget.classes
+
+    multi = PortfolioApp(
+        portfolios=[portfolio, Portfolio(name="Second")],
+        prices={},
+        forex_rates=USD_RATES,
+    )
+    async with multi.run_test() as pilot:
+        await pilot.pause()
+        widget = multi.query_one("#combined-total", Static)
+        assert "-hidden" not in widget.classes
+
+
+@pytest.mark.asyncio
+async def test_combined_total_widget_renders_value(portfolio: Portfolio) -> None:
+    """When prices and forex rates are available, the aggregate footer
+    must display the summed value across all portfolios in the first
+    portfolio's base currency."""
+    second = Portfolio(
+        name="Second",
+        positions=[Position(symbol="MSFT", quantity=10, avg_cost=200.0)],
+    )
+    app = PortfolioApp(
+        portfolios=[portfolio, second],
+        prices={"AAPL": 200.0, "NVDA": 150.0, "MSFT": 300.0},
+        forex_rates=USD_RATES,
+    )
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        widget = app.query_one("#combined-total", Static)
+        text = _static_content(widget)
+        # portfolio fixture: AAPL 100 @ 200 + NVDA 200 @ 150 = 50_000;
+        # second: MSFT 10 @ 300 = 3_000; total 53_000
+        assert "Total (USD)" in text
+        assert "53,000.00" in text
+
+
+@pytest.mark.asyncio
+async def test_combined_total_widget_renders_na_on_missing_price(
+    portfolio: Portfolio,
+) -> None:
+    """When any price is missing the aggregate must render ``N/A`` rather
+    than a misleading partial sum."""
+    second = Portfolio(
+        name="Second",
+        positions=[Position(symbol="MISSING", quantity=10, avg_cost=200.0)],
+    )
+    app = PortfolioApp(
+        portfolios=[portfolio, second],
+        prices={"AAPL": 200.0, "NVDA": 150.0},  # MISSING absent
+        forex_rates=USD_RATES,
+    )
+    async with app.run_test() as pilot:
+        await pilot.pause()
+        widget = app.query_one("#combined-total", Static)
+        text = _static_content(widget)
+        assert "N/A" in text
+
+
 @pytest.mark.asyncio
 async def test_history_updated_message_syncs_to_app(portfolio: Portfolio) -> None:
     """HistoryUpdated message from ChatScreen updates app._chat_history."""

tests/test_models.py

@@ -7,6 +7,7 @@
     Portfolio,
     Position,
     WatchlistItem,
+    combined_portfolio_total,
     daily_change_pct,
     portfolio_total,
 )
@@ -344,3 +345,72 @@ def test_forex_conversion(self):
         prices = {"VOW3": 120.0}
         rates = {"EUR": 1.1}  # EUR -> USD
         assert portfolio_total(p, prices, rates) == pytest.approx(5 * 120.0 * 1.1)
+
+
+class TestCombinedPortfolioTotal:
+    def test_empty_list_returns_none_usd(self):
+        total, base = combined_portfolio_total([], {}, {})
+        assert total is None
+        assert base == "USD"
+
+    def test_sums_across_portfolios_same_base(self):
+        p1 = Portfolio(
+            positions=[Position("AAPL", 10, 150.0)],
+            cash=[CashPosition("USD", 500.0)],
+            base_currency="USD",
+        )
+        p2 = Portfolio(
+            positions=[Position("NVDA", 5, 100.0)],
+            base_currency="USD",
+        )
+        prices = {"AAPL": 200.0, "NVDA": 120.0}
+        forex = {"USD": {"USD": 1.0}}
+        total, base = combined_portfolio_total([p1, p2], prices, forex)
+        # p1: 10*200 + 500 = 2500; p2: 5*120 = 600; combined = 3100
+        assert total == pytest.approx(3100.0)
+        assert base == "USD"
+
+    def test_uses_first_portfolio_base_currency(self):
+        # p1 base = EUR, p2 base = USD -- the aggregate is reported in EUR.
+        p1 = Portfolio(
+            positions=[Position("VOW3", 1, 100.0, currency="EUR")],
+            base_currency="EUR",
+        )
+        p2 = Portfolio(
+            positions=[Position("AAPL", 1, 100.0, currency="USD")],
+            base_currency="USD",
+        )
+        prices = {"VOW3": 200.0, "AAPL": 200.0}
+        # rates keyed by aggregate base ("EUR") -> {pos_currency: multiplier}
+        forex = {"EUR": {"EUR": 1.0, "USD": 0.9}}
+        total, base = combined_portfolio_total([p1, p2], prices, forex)
+        # p1 in EUR: 1*200*1.0 = 200; p2 USD->EUR: 1*200*0.9 = 180; total 380
+        assert total == pytest.approx(380.0)
+        assert base == "EUR"
+
+    def test_returns_none_when_any_portfolio_incomplete(self):
+        p1 = Portfolio(positions=[Position("AAPL", 10, 150.0)])
+        p2 = Portfolio(positions=[Position("MISSING", 1, 50.0)])
+        prices = {"AAPL": 200.0}  # MISSING has no price
+        forex = {"USD": {"USD": 1.0}}
+        total, base = combined_portfolio_total([p1, p2], prices, forex)
+        assert total is None
+        assert base == "USD"
+
+    def test_returns_none_when_base_rates_absent(self):
+        # forex_rates has no entry for the first portfolio's base -> the
+        # nested rates dict is empty, so any non-empty portfolio fails.
+        p1 = Portfolio(positions=[Position("AAPL", 10, 150.0)])
+        total, base = combined_portfolio_total([p1], {"AAPL": 200.0}, {})
+        assert total is None
+        assert base == "USD"
+
+    def test_single_portfolio_matches_portfolio_total(self):
+        p = Portfolio(
+            positions=[Position("AAPL", 10, 150.0)],
+            cash=[CashPosition("USD", 500.0)],
+        )
+        prices = {"AAPL": 200.0}
+        forex = {"USD": {"USD": 1.0}}
+        combined, _ = combined_portfolio_total([p], prices, forex)
+        assert combined == pytest.approx(portfolio_total(p, prices, {"USD": 1.0}))