fix(app): refresh button silently no-op'd due to queryKey mismatch (#779)

[alfredo1996]

Summary

Per-widget manual refresh button silently no-op'd. The dashboard-container.tsx onRefresh handler invalidated TanStack Query with a 4-element key (["widget-query", connectionId, query, params]), but useWidgetQuery caches under a 5-element key (["widget-query", connectionId, query, mergedParams, staleTime]). The 3rd position differs (widget.params raw template ≠ mergedParams resolved at hook call time) so the prefix match failed and no refetch fired.

Fix: truncate the invalidation prefix to 3 elements (stop at query). TanStack Query's prefix matching catches all variants regardless of params/staleTime — and params/staleTime are computed at hook call time and not reproducible from widget alone.

Original implementation reference

The same fix shipped on release/2.1 as commit 25617a55 (bundled with #778). This PR ports the #779 portion only, against current dev. See that commit for the original diagnostic notes.

Re-implementation context

Part of the v2.1 — Re-implementation on dev milestone (cascade strategy abandoned 2026-05-16; see #787 for full context).

Test plan

• Unit: 2 new tests in dashboard-container-refresh.test.tsx
  • asserts invalidate-prefix matches the cached key shape
  • asserts invalidation scopes to the clicked widget's connection + query (other widgets untouched)
• npm -w app run test -- dashboard-container — 7/7 pass
• CI verifies full suite (local has a stale-deps zod-4 mismatch unrelated to this fix)
• E2E auto-refresh.spec.ts + widget-states.spec.ts refresh-button tests pass in CI

Closes #779

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved widget refresh button functionality with optimized cache key handling, ensuring the refresh button correctly targets only the selected widget without inadvertently affecting data from other widgets

• Tests

  • Added comprehensive regression test suite for widget refresh functionality, verifying proper cache invalidation behavior and correct scoping per widget

[coderabbitai]

Walkthrough

This PR fixes a TanStack Query cache invalidation bug in the dashboard widget refresh feature. The widget refresh button now invalidates cached entries using a shorter query key prefix ["widget-query", connectionId, query] instead of including variable fields like mergedParams and staleTime, enabling reliable prefix-based matching. Regression tests verify the fix prevents stale cache entries from blocking refreshes and enforces per-widget scoping.

Changes

Widget Refresh Query Key Invalidation Fix

Layer / File(s)	Summary
Invalidation key prefix fix and documentation app/src/components/dashboard-container.tsx	queryClient.invalidateQueries now uses a 3-element prefix key ["widget-query", connectionId, query] instead of including widget.params and staleTime. Inline comments explain the full cache key structure and why shorter prefixes prevent refresh no-ops when params/staleTime vary across cache slots.
Test infrastructure, mocks, and fixtures app/src/components/__tests__/dashboard-container-refresh.test.tsx	Regression test suite with detailed comments describing the original bug. Comprehensive mocks for dashboard components, widgets, parameters, and query utilities. Helper functions construct DashboardWidget and DashboardPage fixtures with grid layout.
Cache invalidation and scoping test cases app/src/components/__tests__/dashboard-container-refresh.test.tsx	Two regression tests: (1) verify that refresh button invalidation uses a prefix key matching cached widget-query entries, confirming they are marked invalidated; (2) verify that refreshing one widget does not invalidate other widgets' cached entries with different connectionId or query values.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• alfredo1996/neoboard#779: This PR addresses the widget refresh cache key prefix issue; the related issue argues whether refresh should use refetchQueries vs. invalidateQueries—both concern the same refresh call behavior in DashboardContainer.

Possibly related PRs

• alfredo1996/neoboard#519: Both PRs target the per-widget manual refresh behavior; this PR fixes the TanStack Query invalidation key prefix, while the related PR adds E2E validation that refresh triggers the expected /api/query refetch.

Suggested labels

bug, pkg:app, area:dashboard, testing

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the core fix: the refresh button was silently failing due to a queryKey prefix mismatch, which directly aligns with the primary change of truncating the invalidation key from 4 to 3 elements.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/issue-779-refresh-button-key

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

app/src/components/__tests__/dashboard-container-refresh.test.tsx (1)

96-137: ⚡ Quick win

Skip the Next.js module mocks in this test — the component doesn't use next/navigation or next/dynamic.

The DashboardContainer component (under test) doesn't import or use Next.js navigation or dynamic imports. Adding these mocks would be unnecessary boilerplate without functional benefit. Standard practice is to mock dependencies that the component or test actually needs; transitive mocking of unused modules adds clutter.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@app/src/components/__tests__/dashboard-container-refresh.test.tsx` around
lines 96 - 137, Remove the unnecessary Next.js mocks from the test (specifically
any vi.mock calls for "next/navigation" and "next/dynamic") since
DashboardContainer doesn't import or use those modules; keep only the mocks
actually used by this test (e.g., CardContainer, interpolateTitle,
buildExportData, widget-utils, widget-actions, parameter-store,
format-parameter-value, resolve-cache-options and the shouldShowRefreshButton
override) so the test file only stubs the real dependencies referenced by the
DashboardContainer component.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@app/src/components/__tests__/dashboard-container-refresh.test.tsx`:
- Around line 96-137: Remove the unnecessary Next.js mocks from the test
(specifically any vi.mock calls for "next/navigation" and "next/dynamic") since
DashboardContainer doesn't import or use those modules; keep only the mocks
actually used by this test (e.g., CardContainer, interpolateTitle,
buildExportData, widget-utils, widget-actions, parameter-store,
format-parameter-value, resolve-cache-options and the shouldShowRefreshButton
override) so the test file only stubs the real dependencies referenced by the
DashboardContainer component.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 59e9c42b-e94b-4319-afec-da4f878fccc6

📥 Commits

Reviewing files that changed from the base of the PR and between eaca140 and a0b6185.

📒 Files selected for processing (2)

• app/src/components/__tests__/dashboard-container-refresh.test.tsx
• app/src/components/dashboard-container.tsx

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[alfredo1996]

Obsolete: the refresh-button queryKey fix is already on the new dev tip via the cascade work that landed on release/2.0. The force-push of chore/release-2.0-preflight to dev (#789) included it. Closing without merge.