refactor(popper)!: migrate to @floating-ui/react-dom (BREAKING)

[HendrikThePendric]

Implements N/A — follow-up to #1750

Stacked on #1750. Targets feat/add-react-19-support; will retarget master automatically when #1750 merges.

---

Description

Migrates the floating-UI engine from popper.js v2 (in maintenance) to @floating-ui/react-dom. Internal code now uses Floating UI's idiomatic API throughout. Breaking — major version bump.

• Drops @popperjs/core and react-popper from all @dhis2-ui/* packages. (Note: @popperjs/core may still appear in yarn.lock because @dhis2/cli-app-scripts transitively pulls in an older bundled version of @dhis2/ui via @dhis2/app-shell. That's a devDependency chain we don't control from this PR.)
• @dhis2-ui/popper, @dhis2-ui/popover, @dhis2-ui/tooltip, @dhis2-ui/calendar, @dhis2-ui/selector-bar now depend on @floating-ui/react-dom.
• Internal modifiers (preventOverflow, flip, custom resizeObserver, custom hideArrowWhenDisplaced) ported to Floating UI middleware (shift, flip, autoUpdate, custom hideArrowWhenDisplaced).
• New usePopper hook (replacing the previous react-popper.usePopper re-export). Wraps useFloating with dhis2's positioning defaults (base middleware, RTL-aware placement, autoUpdate). Use it directly when you need access to middlewareData or want to compose your own DOM structure.
• placement="auto" / "auto-start" / "auto-end" continue to work. Floating UI doesn't accept these as placement values — when usePopper sees an auto placement, it swaps the base flip middleware for autoPlacement (which would otherwise conflict with flip, per FUI docs). shift stays unchanged in both paths since it operates after the placement is settled.

Drive-by note: components/select/i18n/en.pot picks up a missing {{count}} selected extraction. The string was already used in multi-select/input.js but never made it into the .pot file. Unrelated to the FUI migration — picked up by yarn build:api running the i18n extraction tooling. Worth keeping rather than reverting.

---

Breaking changes

• <Popper modifiers={…}> renamed to <Popper middleware={…}>. Accepts Floating UI middleware functions (offset(), flip(), etc.) instead of popper.js modifier config objects.
• <Popper onFirstUpdate={…}> dropped. Use ref forwarding for DOM access (<Popper ref={…}>), or use usePopper directly and read isPositioned for one-shot side effects.
• <Popper> and <Popover> no longer accept observePopperResize / observeReferenceResize. Floating UI's autoUpdate is always-on with all of its defaults (ancestor scroll, ancestor resize, element resize, layout shift). We are intentionally not exposing an escape hatch: the old props were popper.js-flavored, and exposing Floating UI's option shape now would couple our public API to FUI's internals. If a consumer reports a real need to opt out, we'll add a prop then.
• usePopper is no longer a re-export of react-popper's hook. It's now a dhis2-flavored wrapper around Floating UI's useFloating — same defaults as <Popper>. The signature and return shape are different from the previous usePopper.
• getBaseModifiers renamed to getBaseMiddleware and signature changed: now takes no arguments and returns an array of Floating UI middleware. Already applied automatically by usePopper and <Popper>; the export is for consumers using useFloating from @floating-ui/react-dom directly.

---

Migration guide

modifiers → middleware

The modifiers prop has been renamed and now accepts Floating UI middleware functions instead of popper.js modifier config objects.

- <Popper modifiers={[
-     { name: 'offset', options: { offset: [0, 8] } },
-     { name: 'flip', options: { altBoundary: true } },
- ]}>
+ import { offset, flip } from '@floating-ui/react-dom'
+ <Popper middleware={[offset(8), flip({ altBoundary: true })]}>

If you authored custom modifiers using popper.js's mutate-state API (fn: ({ state }) => { state.attributes.foo = … }), you'll need to port them to Floating UI's data-return API (fn: ({ rects, x, y }) => ({ data: { … } })). See the Floating UI middleware docs.

onFirstUpdate → ref forwarding, or usePopper + isPositioned

For DOM access:

- <Popper onFirstUpdate={(instance) => {
-     popperRef.current = instance?.elements?.popper
- }}>
+ <Popper ref={popperRef}>

For one-shot side effects after first positioning, use usePopper:

- <Popper onFirstUpdate={() => triggerAnimation()}>...</Popper>
+ const { refs, floatingStyles, isPositioned } = usePopper({ reference, placement, middleware })
+ useEffect(() => {
+     if (isPositioned) triggerAnimation()
+ }, [isPositioned])
+ return <div ref={refs.setFloating} style={floatingStyles}>...</div>

observePopperResize / observeReferenceResize removed

These have been dropped — autoUpdate is now always on.

- <Popper observePopperResize observeReferenceResize>
+ <Popper>

usePopper API changed

usePopper was previously a re-export of react-popper's hook. It's now a dhis2 hook wrapping Floating UI's useFloating. The API is different:

- import { usePopper } from '@dhis2-ui/popper'
- const { styles, attributes } = usePopper(referenceElement, popperElement, options)
- return <div ref={setPopperEl} style={styles.popper} {...attributes.popper}>...</div>

+ import { usePopper } from '@dhis2-ui/popper'
+ const { refs, floatingStyles, middlewareData } = usePopper({
+     reference,
+     placement,
+     middleware: [offset(8), hide()],
+ })
+ return <div ref={refs.setFloating} style={floatingStyles}>...</div>

Key differences:

• Options object instead of positional args
• Returns refs.setFloating (a ref setter) instead of needing you to call useState for the popper element
• Returns floatingStyles (apply directly) instead of styles.popper
• Returns middlewareData for reading hide/arrow/size/etc. data
• autoUpdate is always on

If you want Floating UI's useFloating directly without our defaults, import it from @floating-ui/react-dom.

getBaseModifiers → getBaseMiddleware

Renamed and signature simplified. No longer takes options (autoUpdate is always-on).

- import { getBaseModifiers } from '@dhis2-ui/popper'
- const modifiers = getBaseModifiers({ observePopperResize, observeReferenceResize })
+ import { getBaseMiddleware } from '@dhis2-ui/popper'
+ const middleware = getBaseMiddleware()

Both usePopper and <Popper> apply this automatically. The export is useful only if you're calling useFloating from @floating-ui/react-dom directly and want to match Popper's positioning defaults.

Reading middleware data (new capability)

Middleware that produces data (e.g. hide(), arrow(), size()) was previously not consumable from the Popper component. Use the new usePopper hook:

import { usePopper } from '@dhis2-ui/popper'
import { hide } from '@floating-ui/react-dom'

const MyPopper = ({ reference, children }) => {
    const { refs, floatingStyles, middlewareData } = usePopper({
        reference,
        middleware: [hide()],
    })
    return (
        <div
            ref={refs.setFloating}
            style={{
                ...floatingStyles,
                visibility: middlewareData.hide?.referenceHidden
                    ? 'hidden'
                    : undefined,
            }}
        >
            {children}
        </div>
    )
}

See the Popper / Custom Middleware With Hook story for a worked example.

---

Checklist

• API docs are regenerated
• Tests were updated
• Storybook demos were updated

---

🤖 Generated with Claude Code

[dhis2-bot]

🚀 Deployed on https://pr-1751--dhis2-ui.netlify.app

[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

[HendrikThePendric]

This work will be batched together with some other work that introduces breaking changes, namely the calendar component