PLAN.md §12 noted "Native dialogs (file pickers, notifications) — where
do they live?" as an open question with the bias "QML side via Qt".
That bias was never written up; without the doc, a Symfony developer
new to Qt would reasonably reach for "POST /api/show-dialog" or roll
a custom QML "FileDialog" using Window + ListView. Both are wrong.
The doc:
- States the boundary plainly (native UI = QML side, never PHP) plus
the architectural reason (PHP's process can't reach the user's
window manager; Qt's can and already wraps every platform's
native API).
- Walks through Qt.labs.platform.FileDialog / MessageDialog /
SystemTrayIcon / StandardPaths with copy-pasteable examples so
apps don't need to discover Qt.labs the hard way.
- Explains the trigger-vs-effect split: user-initiated confirmations
open from the QML handler that fired the action; server-side
events route through Mercure and let QML decide how to surface
them (toast / dialog / tray notification).
Anti-pattern callouts: don't dispatch dialogs from Doctrine listeners,
don't add HTTP endpoints whose only job is to trigger UI side-effects,
don't roll a custom QML file browser.
Notifications caveat: Qt.labs.platform.SystemTrayIcon::showMessage
covers the common case but routes through the tray. Richer
notifications (action buttons, replies) need platform-specific code
and are deferred — flagged in-doc.
PLAN.md §13 also mentioned "ship a small Q_INVOKABLE helper for the
common cases". Skipped: every common case Qt.labs.platform already
covers, and a wrapper would just shadow upstream's API. If a future
need surfaces a real gap (XDG portal notifications without tray,
say), that's the time to add framework-side code; the doc will
point at it.
No code changes; doc-only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
