richardfogaca opened a new pull request, #37459:
URL: https://github.com/apache/superset/pull/37459
### SUMMARY
This PR implements a comprehensive real-time dashboard auto-refresh feature
with an enhanced user experience. The main goals are to provide clear visual
feedback about refresh status, prevent UI flickering during refreshes, and give
users control over the refresh behavior.
#### Key Features
**1. Auto-Refresh Status Indicator**
- A colored dot in the dashboard header indicates the current refresh state:
- **Green (Success)**: Dashboard refreshed successfully on schedule
- **Blue (Idle/Fetching)**: Waiting for first refresh or currently
fetching data
- **Yellow (Delayed)**: Refresh taking longer than expected OR 1
consecutive error
- **Red (Error)**: 2+ consecutive errors
- **White (Paused)**: Auto-refresh is paused (manually or by tab
visibility)
- Hovering over the indicator shows a tooltip with detailed status
information including last refresh time, configured interval, and error counts
**2. Pause/Resume Controls**
- Users can manually pause and resume auto-refresh via a play/pause button
next to the status indicator
- When resuming, charts are immediately refreshed before the timer restarts
- The pause state is independent of tab visibility pause
**3. Tab Visibility Auto-Pause (Opt-in)**
- Optional feature to automatically pause auto-refresh when the browser tab
becomes inactive
- When the user returns to the tab, data is immediately fetched and the
timer restarts
- Respects manual pause state - returning to tab won't auto-resume if
manually paused
- Implemented using the Page Visibility API via `useTabVisibility` hook
**4. Flickering Prevention**
Multiple improvements to ensure smooth visual updates during auto-refresh:
- **Loading spinner suppression**: Charts maintain their previous data
display during refresh instead of showing loading spinners
- **FiltersBadge preservation**: Filter indicators remain visible during
refresh cycles
- **Stable series ordering**: Added secondary sort by name to prevent legend
reordering flicker in ECharts
- **Tree chart animation control**: Disabled expand/collapse animations
during refresh
- **Status dot debouncing**: Smooth color transitions with CSS and state
debouncing
**5. Timer Race Condition Fix**
- Added sequence guard mechanism to prevent stale refresh cycles from
re-arming timers with old intervals
- Each refresh cycle captures a sequence ID; old cycles bail out if the
sequence no longer matches
- This prevents the bug where changing intervals while a refresh is
in-flight would cause the old interval to persist
**6. Configuration Changes**
- Dropped the 5-second preset from auto-refresh options (too aggressive for
most use cases)
- Allowed custom intervals as low as 1 second for real-time use cases
- Added validation for minimum refresh intervals with configurable
server-side limits
#### Architecture
**New Files:**
- `dashboard/types/autoRefresh.ts` - Type definitions (`AutoRefreshStatus`
enum, `AutoRefreshState` interface) and state defaults
- `dashboard/actions/autoRefresh.ts` - Redux actions for refresh state
management (status, pause, errors, etc.)
- `dashboard/contexts/AutoRefreshContext.tsx` - React context for
propagating refresh state to charts (enables spinner suppression)
- `dashboard/hooks/useRealTimeDashboard.ts` - Main hook for accessing and
managing refresh state with Redux selectors
- `dashboard/hooks/useTabVisibility.ts` - Hook for tracking browser tab
visibility via Page Visibility API
- `dashboard/hooks/useAutoRefreshTabPause.ts` - Hook that orchestrates
tab-based pause/resume behavior
- `dashboard/hooks/useCurrentTime.ts` - Real-time clock hook for tooltip
time displays
- `dashboard/components/AutoRefreshStatus/` - Status indicator components
(dot, tooltip content)
- `dashboard/components/AutoRefreshIndicator/` - Unified indicator with
status dot and pause button
- `dashboard/components/AutoRefreshControls/` - Standalone pause/resume and
refresh buttons
- `dashboard/components/RefreshButton/` - Manual refresh button component
- `dashboard/components/RefreshFrequency/` - Shared refresh frequency select
component with validation
**Modified Files:**
- `dashboard/reducers/dashboardState.js` - Added auto-refresh state handling
with error threshold logic
- `dashboard/components/Header/index.tsx` - Converted from JSX, integrated
auto-refresh orchestration with sequence guard
- `dashboard/containers/DashboardPage.tsx` - Wrapped dashboard in
`AutoRefreshProvider`
- `components/Chart/ChartRenderer.jsx` - Added `suppressLoadingSpinner` prop
for auto-refresh cycles
- `dashboard/components/FiltersBadge/index.tsx` - Added auto-refresh
awareness to preserve filter indicators
- `dashboard/components/gridComponents/Chart.jsx` - Integrated
`useIsAutoRefreshing` context hook
- `dashboard/components/gridComponents/Tab.jsx` - Added lazy-load refresh
handling with `isLazyLoad` flag
- `dashboard/components/PropertiesModal/index.tsx` - Integrated refresh
settings section
- `dashboard/components/RefreshIntervalModal.tsx` - Added
pause-on-inactive-tab checkbox
### BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF
**Before:** Auto-refresh showed toast notifications on each refresh cycle,
charts flickered with loading spinners, no status indicator, no pause control.
**After:**
- Clean status indicator dot with informative tooltip showing last refresh
time, interval, and status
- Pause/play controls for manual control of auto-refresh
- Smooth refresh without flickering or loading spinners during auto-refresh
cycles
- Optional tab visibility pause with immediate refresh on return
<img width="681" height="194" alt="Screenshot 2026-01-26 at 20 56 03"
src="https://github.com/user-attachments/assets/54d5ce80-1c5f-49db-a66c-9c64e30e31c2";
/>
<img width="279" height="132" alt="Screenshot 2026-01-26 at 20 56 18"
src="https://github.com/user-attachments/assets/29126fb3-2941-43e0-8c35-24aca701d235";
/>
<img width="394" height="539" alt="Screenshot 2026-01-26 at 21 18 30"
src="https://github.com/user-attachments/assets/ff1a8924-645c-417e-8b6e-133e80e35830";
/>
### TESTING INSTRUCTIONS
1. **Basic Auto-Refresh Status:**
- Open a dashboard and set an auto-refresh interval (e.g., 10 seconds)
- Observe the status indicator dot appears next to the refresh controls
- Watch the dot turn blue during fetch, then green on success
- Hover over the indicator to see tooltip with last refresh time and
interval
2. **Pause/Resume:**
- With auto-refresh enabled, click the pause button
- Observe the dot turns white (paused state)
- Click play to resume - charts should refresh immediately
- Verify the timer restarts after resuming
3. **Tab Visibility Pause:**
- Enable the "Pause on inactive tab" option in refresh settings
- Switch to another browser tab for longer than the refresh interval
- Return to the dashboard tab
- Verify data refreshes immediately and timer restarts
4. **Interval Change While Refreshing:**
- Set a short refresh interval (e.g., 10 seconds)
- During an active refresh cycle, open settings and change to 30 seconds
- Verify the dashboard now refreshes at 30-second intervals (not the old
10s)
5. **Flickering Prevention:**
- Set a short refresh interval (e.g., 10 seconds)
- Observe that charts don't show loading spinners during auto-refresh
- Verify filter badges remain visible during refresh
- Check that chart legends don't flicker or reorder
6. **Error Handling:**
- Simulate network issues or chart errors
- Verify the status dot turns yellow on first error, red on 2+ errors
- Verify tooltip shows error information and count
7. **Lazy-Loaded Tabs:**
- Create a dashboard with multiple tabs
- Enable auto-refresh and switch between tabs
- Verify lazy-loaded tabs refresh correctly without triggering full
dashboard refresh state
### ADDITIONAL INFORMATION
- [x] Has associated issue:
- [ ] Required feature flags:
- [x] Changes UI
- [ ] Includes DB Migration (follow approval process in
[SIP-59](https://github.com/apache/superset/issues/13351))
- [ ] Migration is atomic, supports rollback & is backwards-compatible
- [ ] Confirm DB migration upgrade and downgrade tested
- [ ] Runtime estimates and downtime expectations provided
- [x] Introduces new feature or API
- [ ] Removes existing feature or API
#### Test Coverage
- Unit tests for all new hooks (`useRealTimeDashboard`, `useTabVisibility`,
`useAutoRefreshTabPause`, `useCurrentTime`)
- Unit tests for auto-refresh reducer actions and state transitions
- Unit tests for UI components (`AutoRefreshStatus`, `StatusIndicatorDot`,
`StatusTooltipContent`, `AutoRefreshControls`)
- Unit tests for `RefreshFrequencySelect` validation functions
- Integration tests for FiltersBadge auto-refresh behavior
- Updated Header component tests for auto-refresh orchestration
- Tests for lazy-load tab refresh behavior
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
