Professor-Chen/cursor-byok

Floating UI

Verwenden Sie @floating-ui/dom für jedes interaktive Element, das relativ zu einem Trigger positioniert wird. Berechnen Sie Koordinaten nicht manuell und verlassen Sie sich nicht auf CSS-Abstandsoffsets für Dropdowns, Popover, Menüs, Combobox-Listen oder Tooltips.

Erforderliche Struktur

• Rendern Sie Overlays mit createPortal(..., document.body), damit Layout- und Stacking-Kontexte sie nicht abschneiden.
• Positionieren Sie mit computePosition innerhalb von autoUpdate; räumen Sie die von autoUpdate zurückgegebene Funktion auf, wenn das Overlay geschlossen oder ausgehängt wird.
• Gehen Sie von der nächstgelegenen vorhandenen Steuerung in apps/desktop/src/components/ui aus. Übernehmen Sie deren placement-, offset-, flip-, shift- und size-Middleware, es sei denn, die Interaktion erfordert eine bewusste Abweichung.
• Speichern Sie die berechneten left, top, width und verfügbare Höhe im React-Status. Wenden Sie den Status auf das Portal-Root-Element an; mutieren Sie Elementstile nicht direkt.
• Verwenden Sie size, wenn die Referenzbreite oder die Viewport-Höhe das Overlay einschränkt. Listen, die wachsen können, müssen components/virtual/VirtualList.tsx verwenden; halten Sie feste Kopf- und Fußzeilen außerhalb des virtuellen Viewports.

Interaktionsinvarianten

• Halten Sie den offenen/fokussierten Rand des Triggers sichtbar, während der Fokus innerhalb eines portalierten Overlays liegt.
• Schließen Sie bei Mausinteraktion außerhalb und Escape und geben Sie den Fokus dann an den Trigger zurück.
• Überprüfungen auf Klick außerhalb müssen sowohl den Trigger als auch das Overlay einschließen. Ein verschachteltes portaliertes Overlay muss sein Pointer-Ereignis stoppen, bevor es den Outside-Click-Listener des Eltern-Overlays erreicht, sodass die Interaktion mit einem Kindmenü niemals das Elternmenü schließt.
• Stellen Sie den Trigger-Status mit aria-expanded, aria-controls und dem entsprechenden aria-haspopup dar; versehen Sie das Overlay mit der passenden menu-, listbox-, dialog- oder tooltip-Semantik.
• Überprüfen Sie die Positionierung an allen Viewport-Rändern, Klicks auf verschachtelte Overlays, Tastaturverwerfung, virtuelles Scrollen und Verhalten bei fixierten Fußzeilen.