Floating Widget Pattern

This pattern describes global widgets that stay available across pages.

Current Widgets

• Theme widget
• Feedback widget

Both are rendered via WidgetDock in the app shell.

Key Requirements

1. Global availability across authenticated app routes
2. Persistent draft/state across route changes
3. Fixed positioning with safe spacing from actionable page controls
4. Clear open/close affordances

Current Implementation

• Dock component: src/features/widgets/components/WidgetDock.tsx
• Shell placement: src/app/layout/AppShell.tsx
• Theme state persistence: theme context + local storage
• Feedback draft persistence: local storage in feedback widget

Implementation Checklist for New Widgets

• Create feature-local widget component under src/features/widgets/components
• Keep state in a shared provider/context when it must survive navigation
• Add dock entry in WidgetDock
• Validate overlap behavior in desktop and mobile layouts
• Add tests for persistence and submit/cancel behavior

Anti-Patterns

• Widget state tied to a single page component (state resets on navigation)
• Widget positioning that blocks primary form controls on common breakpoints
• Hidden submit errors without in-widget feedback