I'm not totally happy with calling it popup behavior. In X speak this is not a popup.

Fair enough. I want some name that hints it doesn't include panels.

I'm open to suggestions.

Stupid question: the popups are transient to the panel? If yes we can fix in layer. A panel transient should be in panel layer and thus above the windows without any client side tricks.

The default state works fine without tricks.

There's a magic button on the system tray/calendar with a little icon of a pin. When clicked this window should remain on top even when focus goes to somewhere else. This is unlike a normal popup.

Currently this is done via QWindow::setFlags(Qt::WindowStaysOnTopHint) which on the wayland QPA goes nowhere.

Somehow we need to negotiate whether we're in that mode or the normal mode.

Stays on top is wrong. The window needs to be in the dock layer, not in the above layer. With keep above other keep above windows can still go on top of it.

It's one of the many cases where Plasma is not really correct. Many such features where implemented without consulting KWin devs. IMHO it should be a transient to the panel and inherit the parent's layer.

There's an extra twist.
You can put the digital-clock on the desktop. You can then open the popup, and then pin it so that it's above windows.
Being transient to the desktop won't help there.

You are right that I could keep it always on top rather than only when the pin is set and that does allow some other options.
I'll do a bit more investigation rather than just going for a direct X port.

That's an evil twist. Idea: make the windows panels with windows go below?