Skip to content

fix(alerts): keep useAlert's show function stable across renders - #1447

Merged
KaiVandivier merged 5 commits into
masterfrom
fix/stable-use-alert-show
Nov 10, 2026
Merged

KaiVandivier merged 5 commits into
masterfrom
fix/stable-use-alert-show

Conversation

@HendrikThePendric

@HendrikThePendric HendrikThePendric commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Key features

  1. show returned by useAlert now has the same identity across renders, even when the hook is called with an inline message function, an inline options object, or no options at all
  2. show always uses the latest message and options
  3. AlertsProvider no longer re-renders every useAlert consumer when an alert is added or removed

Description

useAlert built show with useCallback and listed message and options as dependencies. The common ways of calling the hook pass new values on every render:

  • an inline message or options function: useAlert(({ name }) => `Deleted ${name}`)
  • an inline options object: useAlert('Saved', { success: true })
  • no options at all, because the default {} is a new object on every call

Each of these produced a new show on every render, including both examples in docs/hooks/useAlert.md. A caller that put show in a useCallback or useEffect dependency list then re-ran that callback or effect on every render. In event-visualizer-app this caused a fetch loop: a data-fetching callback depended on show, and an effect depended on that callback. The only workaround was to move both the message function and an empty options object to module scope.

show now reads message and options from a ref, which a layout effect updates after a commit in which they changed. Its useCallback dependencies are now only the alerts context values (add, plugin, parentAlertsAdd, showAlertsInPlugin). This makes show behave like an event handler: its identity is stable and it uses the latest arguments. React 19.2's useEffectEvent does the same thing, but app-runtime supports React ^16.8.6 || ^18, so this uses the ref pattern. hide was already stable and is unchanged.

AlertsProvider also built a new AlertsManagerContext value on every render. Every useAlert consumer therefore re-rendered whenever an alert was added or removed, and that re-render is what turned an unstable show into a fetch loop. The context value is now memoized on alertsManager, parentAlertsAdd and showAlertsInPlugin.

Behaviour change: show no longer changes identity when message or options change. Code that relied on this, for example to re-run an effect when the message changed, will no longer re-run. We don't expect this to affect real usage.


Checklist

  • Have written Documentation
    • docs/hooks/useAlert.md now notes that show and hide are stable and safe to use in dependency lists
  • Has tests coverage
    • show is stable with inline message/options and with no options
    • an earlier show uses the message/options from the latest render
    • function messages and options still get the props passed to show
    • plugin alerts still go to parentAlertsAdd unless showAlertsInPlugin is set
    • a useAlert consumer does not re-render when an alert is shown or hidden

🤖 Generated with Claude Code

`show` listed `message` and `options` as useCallback dependencies, so
inline message functions, inline options objects, or the default `{}`
gave a new `show` on every render. Callers that depended on `show` in
a useCallback or useEffect re-ran every render, which caused a fetch
loop in event-visualizer-app.

`show` now reads the latest `message` and `options` from refs that are
updated in a layout effect, so its identity only depends on the alerts
context values.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
HendrikThePendric added a commit to dhis2/individual-data-visualizer-app that referenced this pull request Nov 5, 2026
This needs dhis2/app-runtime#1447, which keeps useAlert's show function
the same across renders. With older versions, show changes on every
render and the line list would refetch in a loop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@KaiVandivier KaiVandivier left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I invited Claude AI to do a review, and I pulled out these points which I think are worth considering:

Should be fixed before merge

  1. TypeScript error in the new test (useAlert.test.tsx:90). initialProps sets the props type to { success: boolean }, so rerender({ options: { critical: true } }) fails with TS2353. The test only passes because babel-jest strips types and the package tsconfig skips __tests__. Fix: type initialProps as { options: AlertOptions }.

Worth considering

  1. The root cause is in the provider (AlertsProvider.tsx:25). AlertsProvider builds a new context value on every render, so every useAlert consumer re-renders whenever any alert is added or removed. That re-render is what turned an unstable show into a fetch loop. Wrapping the value in useMemo would remove that re-render for all consumers. It could go in this PR or a follow-up.
  2. show still changes identity in plugins (useAlert.ts:56). parentAlertsAdd is still a dependency of show. In app-shell, the PluginLoader creates a new parentAlertsAdd wrapper each time the host sends updated props, so a plugin gets a new show on every host prop change. A plugin that puts show in an effect's dependency list can still loop, which is the event-visualizer bug again. A fix here could be: read add, plugin, parentAlertsAdd and showAlertsInPlugin through the ref too, so show has no dependencies. [Kai: but this is probably better solved in the app-shell]

Nits

  1. The layout effect has no dependency array, so it runs after every render. Adding [message, options] is cheap.
  2. messageRef and optionsRef are always written and read together; one ref holding { message, options } would be simpler.

HendrikThePendric and others added 3 commits November 10, 2026 10:42
initialProps inferred the options type as { success: boolean }, so the
rerender with { critical: true } did not type-check. Jest strips types
and the package tsconfig excludes __tests__, so it went unnoticed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
AlertsProvider built a new AlertsManagerContext value on every render,
so every useAlert consumer re-rendered whenever an alert was added or
removed. Memoize it on the values it is built from.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
They are always written and read together. Also give the layout effect
a dependency array so it only runs when they change.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@HendrikThePendric

Copy link
Copy Markdown
Contributor Author

@KaiVandivier in total the review brought up 5 points, 4 of which I have addressed. I will do a PR in app-platform for the "Worth considering", point 2 suggestion.

@sonarqubecloud

Copy link
Copy Markdown

@KaiVandivier
KaiVandivier merged commit a9a435d into master Nov 10, 2026
16 checks passed
@KaiVandivier
KaiVandivier deleted the fix/stable-use-alert-show branch November 10, 2026 10:13
dhis2-bot added a commit that referenced this pull request Nov 10, 2026
## [3.17.6](v3.17.5...v3.17.6) (2026-11-10)

### Bug Fixes

* **alerts:** keep useAlert's show function stable across renders ([#1447](#1447)) ([a9a435d](a9a435d))
@dhis2-bot

Copy link
Copy Markdown
Contributor

HendrikThePendric added a commit to dhis2/individual-data-visualizer-app that referenced this pull request Nov 10, 2026
This needs dhis2/app-runtime#1447, which keeps useAlert's show function
the same across renders. With older versions, show changes on every
render and the line list would refetch in a loop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
HendrikThePendric added a commit to dhis2/individual-data-visualizer-app that referenced this pull request Nov 10, 2026
* feat: type the line list pager with and without totals

The analytics pager has a page count and total when totals are requested,
and isLastPage otherwise. Paging now always sends the page size, so a
chosen page size is kept when moving to another page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: add the line list row count text

Uses the program's or tracked entity type's plural label when there is
one, and the standard words otherwise.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: request line list totals when the server can count them

The server reports through capability.analyticsTotalCounts in system/info
whether it can count line list rows cheaply. The app adapter already puts
system info in the config, so the plugin reads it without an extra request.

An empty page after the first one keeps the current page instead of
showing an error, since without totals the user can go past the last
page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: add the line list page input

Typing a page and pressing Enter or leaving the field goes to that page.
With totals, a page out of range goes to the nearest valid one. The page
number boxes have a fixed width, so the buttons beside them don't move.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: add the line list page size menu

Rows per page moves out of the bar into a popover behind a button at its
end.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: replace the line list pagination with a custom bar

Previous and next sit at the start of the bar, so they don't move when the
table width changes between pages. The page number can be typed. With
totals, the bar shows the page count and the total number of rows; on a
single page it always shows the row count. Rows per page moves into a menu
at the end of the bar.

The bar is disabled while a page loads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: update translations for the line list pagination bar

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep the line list loader in view when the table is scrolled

The loader was positioned inside the scrolling content, so it scrolled
away with the rows. The sticky header and pager then stayed clickable
while data loaded. The scroll box now renders the loader in a frame
around the scrolling part.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: abort a line list request when a newer one starts

Each analytics request aborts the one before it, and the hook ignores
whatever an aborted request returns, so only the newest page or sort
reaches the table. The hook also reports the page and page size of the
request that is loading.

The browser only stops the aborted request once @dhis2/analytics passes
the signal on (dhis2/analytics#1879).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: keep paging and sorting usable while the line list loads

The pager pages on from the page that is loading, so clicking next
three times goes from page 1 to 4. The loader lets clicks through to
the sort buttons and the pager, and nothing is disabled while loading.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: page through each line list output type with and without totals

Each output type queries its own analytics endpoint, so events,
enrollments and tracked entities each get a paging test without and with
totals. The tests force the analyticsTotalCounts capability through
/api/system/info, so they run whatever analytics database the instance
uses. The enrollment test with totals stays skipped while core answers
that query with E7154.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: alert when a typed line list page has no rows

Without totals the user can type a page past the last one. The table
keeps the page it shows, and an alert says which page was not found and
which page the user is back on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: block the next page button while a page loads without totals

Without totals only a response tells whether the page after it exists,
so rapid clicks on next could run past the last page. Next is marked
aria-disabled instead of disabled while a page loads, so it keeps its
focus and a keyboard user can press it again once the page is there.
With totals the page count is known and next stays usable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: update translations for the empty page alert

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep the line list page size when sorting

Sorting refetched without a page size, so the line list went back to
100 rows a page. A fetch without a page size now uses the last one
requested.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep the line list loader inside the scroll box border

The loader covered the whole scroll box, border and scrollbars included.
It now covers only the visible part of the table, measured from the
scroll container, as it did before it was moved out of the scrolling
content.

The scroll box takes an isFetching flag and renders the loader itself.
The loader is a plain div rather than a Cover, because Cover exists to
catch clicks and this one lets them through.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: name the E2E paging helper after the page it goes to

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: drop line list paging tests that the bar and slot specs cover

The line list spec keeps one test that the response's pager reaches the
bar, and one that the connection status does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test: check the line list requests its data only once

A fetch callback whose identity changes on every render would make the
plugin refetch after each response.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor: pass the empty page alert message to useAlert inline

This needs dhis2/app-runtime#1447, which keeps useAlert's show function
the same across renders. With older versions, show changes on every
render and the line list would refetch in a loop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor: rename PageRequest to RequestedPage

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(deps): bump @dhis2/analytics to v29.9.0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(deps): bump @dhis2/app-runtime to v3.17.6

Brings the aborted FetchError for aborted requests (#1446) and a stable
useAlert show function (#1447). Also dedupes the lockfile, so the app
shell and @dhis2/ui use the same app-runtime as the app.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants