Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Fix: Load the sidebar counters from the shell and roll them up to the section

Damian Legawiec4d54e29f8566
diff --git a/docs/developer/core-concepts/reporting.mdx b/docs/developer/core-concepts/reporting.mdx
index 3fabff95aa..e2a57e67ae 100644
--- a/docs/developer/core-concepts/reporting.mdx
+++ b/docs/developer/core-concepts/reporting.mdx
@@ -191,6 +191,12 @@ the sidebar renders it without knowing which counters exist:
{ "key": "open_returns", "label": "Open returns", "value": 3, "nav": "returns" }
```
+A parent nav entry sums its own counter and its children's, because the
+sidebar only shows the children of the section you are in — a count nobody
+sees until they have already navigated there tells them nothing. Orders
+carries the total of what is waiting to ship plus the open returns, exchanges
+and claims; expanding the section breaks it down.
+
Three things follow from counters living in the registry:
- **Labels come from the server**, the same way metric labels do, so a
@@ -205,8 +211,10 @@ Three things follow from counters living in the registry:
counted carries no link.
Core ships seven: orders to fulfill, payments to collect, open returns, open
-exchanges, open claims, low stock variants and out of stock variants. The
-three post-sale ones badge their sidebar entries. The low stock counter reads the
+exchanges, open claims, low stock variants and out of stock variants. Orders
+to fulfill and the three post-sale counters badge the sidebar; payments to
+collect deliberately does not, since a badge that is lit on almost every store
+stops carrying information. The low stock counter reads the
store's `low_stock_threshold` preference (default five units; zero turns it
off), which merchants set under store settings → Inventory.
diff --git a/docs/plans/6.0-analytics-semantic-layer.md b/docs/plans/6.0-analytics-semantic-layer.md
index 48ced30dfb..a58d3e22fa 100644
--- a/docs/plans/6.0-analytics-semantic-layer.md
+++ b/docs/plans/6.0-analytics-semantic-layer.md
@@ -194,7 +194,7 @@ does not send us the data. That is now the only recorded gap.
### Decision 15 — Operations counters are registry members; the low stock threshold is a store preference (2026-09-10)
-The home screen's Operations card was the last hand-rolled number surface: five counts as private methods on a serializer in the API gem, five matching icon-plus-filter rows hardcoded in the dashboard, one permission (`read_dashboard`) covering all of them, and a `low_stock_threshold` request parameter the dashboard never sent. **Counters now join `Spree.reporting`** as a fourth member type beside metrics, dimensions and bases: `registry.counter :name, count: ->(store, channel:) { … }, subject:, key_scope:, link:, description:`. They are not compiled into the query (no range, no currency, no base — a counter is the state of the store at this instant), so the registry only stores the lambda; `Spree::Reporting::Counters` evaluates them for one store and channel, filtered by the same `member_allowed?` predicate the schema and the query apply, now shared through `Admin::ReportingAuthorization`. `GET /dashboard/counters` returns `{ channel_id, counters: [{ key, label, description, value, link, nav }] }` and the dashboard renders whatever arrives, keeping only an icon map with a fallback. **One request serves the home card and every sidebar badge:** the three post-sale badges each used to spend a list request with `limit: 1` purely to read a total off the pagination meta, and the returns badge counted `received` while the counter did not — two definitions of the same number. Counters now carry the nav entry they badge, so the sidebar reads the shared response and an extension's counter badges its own entry with no dashboard release. Labels resolve through `reporting.counters.<key>` in the locale the way metric labels do. **The link is declared beside the count** so the list a merchant lands on shows exactly the rows counted — the previous out-of-stock link pointed at a products filter the server silently dropped. **`low_stock_threshold` is a `Spree::Store` preference** (integer, default 5, 0 = off), edited under Settings → Store → Inventory and named in the counter's own description; neither reference platform has a per-variant threshold, and Shopify's inventory report bands by days of supply rather than a count, so store-level is the grain. Not `Spree.operations` (reserved) and not a second namespace — the plan's own line that "state metrics join the registry" is the design.
+The home screen's Operations card was the last hand-rolled number surface: five counts as private methods on a serializer in the API gem, five matching icon-plus-filter rows hardcoded in the dashboard, one permission (`read_dashboard`) covering all of them, and a `low_stock_threshold` request parameter the dashboard never sent. **Counters now join `Spree.reporting`** as a fourth member type beside metrics, dimensions and bases: `registry.counter :name, count: ->(store, channel:) { … }, subject:, key_scope:, link:, description:`. They are not compiled into the query (no range, no currency, no base — a counter is the state of the store at this instant), so the registry only stores the lambda; `Spree::Reporting::Counters` evaluates them for one store and channel, filtered by the same `member_allowed?` predicate the schema and the query apply, now shared through `Admin::ReportingAuthorization`. `GET /dashboard/counters` returns `{ channel_id, counters: [{ key, label, description, value, link, nav }] }` and the dashboard renders whatever arrives, keeping only an icon map with a fallback. **One request serves the home card and every sidebar badge:** the three post-sale badges each used to spend a list request with `limit: 1` purely to read a total off the pagination meta, and the returns badge counted `received` while the counter did not — two definitions of the same number. Counters now carry the nav entry they badge, so the sidebar reads the shared response and an extension's counter badges its own entry with no dashboard release. **The shell loads them, not the badges:** the sidebar mounts only the children of the section being viewed, so a badge-driven request left every page outside Orders with no counts at all (a defect the three replaced badges shared), and a parent entry sums its own counter with its children's so the total survives a collapsed submenu. Labels resolve through `reporting.counters.<key>` in the locale the way metric labels do. **The link is declared beside the count** so the list a merchant lands on shows exactly the rows counted — the previous out-of-stock link pointed at a products filter the server silently dropped. **`low_stock_threshold` is a `Spree::Store` preference** (integer, default 5, 0 = off), edited under Settings → Store → Inventory and named in the counter's own description; neither reference platform has a per-variant threshold, and Shopify's inventory report bands by days of supply rather than a count, so store-level is the grain. Not `Spree.operations` (reserved) and not a second namespace — the plan's own line that "state metrics join the registry" is the design.
## Design Details
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 165ec47e6c..7454a7fd81 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -4,7 +4,7 @@
**Decision:** Counters are a fourth member type on `Spree.reporting` (`registry.counter`), evaluated by `Spree::Reporting::Counters` rather than compiled into the query — a counter has no range, currency or base. Each declares `subject` + `key_scope` like every other member and is filtered by the shared `Admin::ReportingAuthorization#member_allowed?`; the endpoint returns `{ key, label, description, value, link }` per counter and the dashboard renders whatever arrives. The link is declared beside the count so the list opened shows exactly the rows counted; a counter with no honest list (the stock ones, until the Inventory page) carries none. `low_stock_threshold` is a `Spree::Store` preference (default 5, 0 = off) surfaced in store settings. `Spree.operations` stays reserved; the registry name `Spree.reporting` is unchanged.
-**Amended 2026-09-11:** the endpoint is `dashboard/counters`, not `dashboard/operations` — the payload was already named after what it holds, and the developer preview needs no bridge. The three post-sale sidebar badges fold into it: each used to issue its own list request with `limit: 1` to read a total off the pagination meta, so the shell spent three round trips counting three things, and the returns badge counted `received` while `open_returns` did not. Counters now carry the `nav` entry they badge, `open_exchanges` and `open_claims` join the vocabulary, `open_returns` adopts the badge's wider definition, and the sidebar and home card share one query.
+**Amended 2026-09-11:** the endpoint is `dashboard/counters`, not `dashboard/operations` — the payload was already named after what it holds, and the developer preview needs no bridge. The three post-sale sidebar badges fold into it: each used to issue its own list request with `limit: 1` to read a total off the pagination meta, so the shell spent three round trips counting three things, and the returns badge counted `received` while `open_returns` did not. Counters now carry the `nav` entry they badge, `open_exchanges` and `open_claims` join the vocabulary, `open_returns` adopts the badge's wider definition, and the sidebar and home card share one query. The shell issues that query rather than any badge — the sidebar mounts only the children of the section being viewed, so the old badge-driven fetch produced no counts anywhere outside Orders — and a parent nav entry sums its own counter with its children's so the total is visible while the submenu is collapsed. `orders_to_fulfill` badges Orders as an inbox-unread count; `payments_to_collect` deliberately carries no `nav`, since a badge lit on nearly every store stops informing.
**Consequences:** An extension registers a counter with a locale label and it appears on every merchant's home screen — and, with `nav`, in the sidebar — with the right permission gating and no dashboard change. A limited role sees a shorter list, not a refused card. New point-in-time numbers for the home screen are registrations — never serializer methods or client-side derivations. See `6.0-analytics-semantic-layer.md` Decision 15.
diff --git a/packages/dashboard/src/components/spree/nav-counter-badge.tsx b/packages/dashboard/src/components/spree/nav-counter-badge.tsx
index 37137d082b..928298c8c9 100644
--- a/packages/dashboard/src/components/spree/nav-counter-badge.tsx
+++ b/packages/dashboard/src/components/spree/nav-counter-badge.tsx
@@ -4,17 +4,21 @@ import { useDashboardCounters } from '../../hooks/use-dashboard-counters'
/**
* How many records under a nav entry still need the merchant to do something.
*
- * The count comes from the counters endpoint, which every badge and the home
- * screen's card share as one request — the sidebar used to spend a list
- * request per badge just to read a total off the pagination meta. Which nav
- * entry a counter badges is the counter's own `nav` field, so an extension
- * registering a counter badges its nav entry without a dashboard release.
+ * A parent entry passes its own key plus its children's, so the count stays
+ * visible while the submenu is collapsed — the sidebar only mounts children of
+ * the section you are in, and a number nobody can see until they have already
+ * navigated there is not worth having. Expanding the section then breaks the
+ * same total down across the children.
+ *
+ * Which entry a counter badges is the counter's own `nav` field, so an
+ * extension registering a counter badges its nav entry without a dashboard
+ * release. The count itself comes from the shared counters request.
*/
-export function navCounterBadge(navKey: string) {
+export function navCounterBadge(...navKeys: string[]) {
return function NavCounterBadge() {
const { data } = useDashboardCounters()
const total = (data?.counters ?? [])
- .filter((counter) => counter.nav === navKey)
+ .filter((counter) => counter.nav && navKeys.includes(counter.nav))
.reduce((sum, counter) => sum + counter.value, 0)
if (total === 0) return null
diff --git a/packages/dashboard/src/nav/default.ts b/packages/dashboard/src/nav/default.ts
index 3c8cf17c0d..75d6d19188 100644
--- a/packages/dashboard/src/nav/default.ts
+++ b/packages/dashboard/src/nav/default.ts
@@ -47,6 +47,9 @@ nav.add({
icon: InboxIcon,
subject: Subject.Order,
position: 200,
+ // The section's own work plus its children's, so the total survives the
+ // submenu being collapsed on every page outside Orders.
+ badge: navCounterBadge('orders', 'returns', 'exchanges', 'claims'),
children: [
{
key: 'orders.drafts',
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId.tsx
index 2d2803d217..f8dcb10d6e 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId.tsx
@@ -16,6 +16,7 @@ import { createFileRoute, Outlet, useRouterState } from '@tanstack/react-router'
import { useState } from 'react'
import { CommandPalette } from '../../components/spree/command-palette/command-palette'
import { ProfileDialog } from '../../components/spree/profile-dialog'
+import { useDashboardCounters } from '../../hooks/use-dashboard-counters'
import { getAvailableUiLocales } from '../../i18n-setup'
// Derived once from the shipped locale bundles — stable for the app lifetime.
@@ -62,6 +63,11 @@ function StoreLayout() {
*/
function StoreShell({ inSettings }: { inSettings: boolean }) {
useAutoCollapseSidebar(inSettings)
+ // Loaded by the shell rather than by whichever badge happens to be on screen:
+ // the sidebar only mounts the children of the section you are in, so leaving
+ // the request to a badge means no counts at all on every other page. One
+ // query key, so the badges and the home screen's card share this one request.
+ useDashboardCounters()
// The profile is edited in a dialog rather than a page, so the shell owns its
// open state — the trigger sits in the TopBar's user menu, which is mounted
// here and stays put across route changes.
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/dashboard_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/dashboard_controller_spec.rb
index 1f17f94ee3..710c1e4a4f 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/dashboard_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/dashboard_controller_spec.rb
@@ -22,7 +22,7 @@ RSpec.describe Spree::Api::V3::Admin::DashboardController, type: :controller do
)
fulfill = json_response['counters'].first
- expect(fulfill).to include('label' => 'Orders to fulfill', 'value' => 0, 'nav' => nil)
+ expect(fulfill).to include('label' => 'Orders to fulfill', 'value' => 0, 'nav' => 'orders')
expect(fulfill['link']).to eq(
'resource' => 'orders',
'filters' => [{ 'field' => 'fulfillment_status', 'operator' => 'eq', 'value' => 'unfulfilled' }]
diff --git a/spree/core/lib/spree/reporting/default_vocabulary.rb b/spree/core/lib/spree/reporting/default_vocabulary.rb
index 9754a2f70d..d0ea4c6d33 100644
--- a/spree/core/lib/spree/reporting/default_vocabulary.rb
+++ b/spree/core/lib/spree/reporting/default_vocabulary.rb
@@ -420,7 +420,7 @@ module Spree
# "at or below n on hand" (docs/plans/6.0-inventory-operations.md).
counter :orders_to_fulfill,
- subject: -> { Spree::Order }, key_scope: 'read_orders',
+ subject: -> { Spree::Order }, key_scope: 'read_orders', nav: 'orders',
count: ->(store, channel:) { PLACED_ORDERS.call(store, channel).ready_to_ship.count },
link: { resource: 'orders',
filters: [{ field: 'fulfillment_status', operator: 'eq', value: 'unfulfilled' }] }
diff --git a/spree/core/spec/lib/spree/reporting/counters_spec.rb b/spree/core/spec/lib/spree/reporting/counters_spec.rb
index f4dbc48642..1ca54af63f 100644
--- a/spree/core/spec/lib/spree/reporting/counters_spec.rb
+++ b/spree/core/spec/lib/spree/reporting/counters_spec.rb
@@ -14,7 +14,7 @@ RSpec.describe Spree::Reporting::Counters do
%w[orders_to_fulfill payments_to_collect open_returns open_exchanges open_claims low_stock_items out_of_stock_items]
)
expect(results['orders_to_fulfill'].label).to eq('Orders to fulfill')
- expect(results['orders_to_fulfill'].nav).to be_nil
+ expect(results['orders_to_fulfill'].nav).to eq('orders')
expect(results['orders_to_fulfill'].link).to eq(
'resource' => 'orders',
'filters' => [{ 'field' => 'fulfillment_status', 'operator' => 'eq', 'value' => 'unfulfilled' }]
@@ -87,6 +87,10 @@ RSpec.describe Spree::Reporting::Counters do
expect(evaluate['open_exchanges'].nav).to eq('exchanges')
expect(evaluate['open_claims'].nav).to eq('claims')
end
+
+ it 'leaves money owed off the sidebar, where a near-permanent badge would stop informing' do
+ expect(evaluate['payments_to_collect'].nav).to be_nil
+ end
end
context 'with stock levels' do