diff --git a/.claude/rules/08-frontend-guide.md b/.claude/rules/08-frontend-guide.md index e60fef893..69d0e21d7 100644 --- a/.claude/rules/08-frontend-guide.md +++ b/.claude/rules/08-frontend-guide.md @@ -53,15 +53,26 @@ src/ │ ├── TelegramLoginButton.tsx # OAuth login integration │ ├── ProtectedRoute.tsx # Auth-gated routes │ ├── PublicRoute.tsx # Guest-only routes -│ └── ConnectionIndicator.tsx # Status indicators +│ ├── ConnectionIndicator.tsx # Status indicators +│ └── settings/ # Settings modal system +│ ├── SettingsModal.tsx # Main container with routing +│ ├── SettingsLayout.tsx # Modal wrapper with portal +│ ├── SettingsHome.tsx # Main menu with profile +│ ├── panels/ConnectionsPanel.tsx # Connection management +│ ├── components/ # Menu items, header, back button +│ └── hooks/ # Navigation and animation hooks └── utils/ # Utilities and config ├── config.ts # Environment variables └── desktopDeepLinkListener.ts # Deep link handling ``` ### Recent Architecture Changes +- **Settings Modal System**: Complete URL-based modal system with clean white design + - Modal routes: `/settings`, `/settings/connections` overlaying existing content + - Component structure: SettingsModal, SettingsLayout, ConnectionsPanel, hooks + - Redux integration: auth, user, telegram state for profile and connection management - **HashRouter**: Switched from BrowserRouter for better desktop app compatibility -- **153 TypeScript files**: Comprehensive component library +- **165+ TypeScript files**: Comprehensive component library with settings modal system - **Provider chain**: Redux → PersistGate → Socket → Telegram → HashRouter → Routes - **MCP Integration**: 99 Telegram tools for AI-driven interactions - **Deep Link Auth**: Web-to-desktop handoff using `outsourced://` scheme diff --git a/.claude/rules/15-settings-modal-system.md b/.claude/rules/15-settings-modal-system.md new file mode 100644 index 000000000..451d37380 --- /dev/null +++ b/.claude/rules/15-settings-modal-system.md @@ -0,0 +1,237 @@ +# Settings Modal System - URL-Based Modal Architecture + +## Overview + +Complete settings modal system with clean white design that overlays on existing content. Features URL-based routing, Redux integration, and reusable component architecture for system settings management. + +## Architecture + +### Modal Infrastructure + +**Location**: `src/components/settings/` + +The settings modal system uses a clean architectural pattern: + +``` +SettingsModal.tsx # Route-based modal container +├── SettingsLayout.tsx # createPortal modal wrapper with backdrop +├── SettingsHome.tsx # Main menu with user profile +├── panels/ +│ └── ConnectionsPanel.tsx # Connection management interface +├── components/ +│ ├── SettingsHeader.tsx # User profile section +│ ├── SettingsMenuItem.tsx # Individual menu items +│ ├── SettingsBackButton.tsx # Back navigation +│ └── SettingsPanelLayout.tsx # Panel wrapper +└── hooks/ + ├── useSettingsNavigation.ts # URL routing logic + └── useSettingsAnimation.ts # Animation state +``` + +### URL Routing Pattern + +``` +/settings # Main settings menu +/settings/connections # Connection management +/settings/messaging # Future: messaging settings +/settings/privacy # Future: privacy settings +/settings/profile # Future: profile settings +/settings/advanced # Future: advanced settings +/settings/billing # Future: billing settings +``` + +## Design Specifications + +### Modal Container +- **Width**: 520px (desktop), responsive on mobile +- **Background**: Pure white (#FFFFFF) - contrasts with app's glass morphism +- **Border-radius**: 16px +- **Shadow**: `0 20px 25px -5px rgba(0, 0, 0, 0.1)` +- **Backdrop**: Black 50% opacity with 8px blur +- **Position**: Fixed center with flexbox + +### User Profile Section +- **Avatar**: 56px circular with border and shadow +- **Typography**: 18px semibold name, 14px gray email +- **Background**: Subtle gradient from white to gray-50 +- **Integration**: Redux user state for name and email display + +### Menu Items +- **Height**: 52px with proper touch targets +- **Hover**: bg-gray-50 with smooth transitions +- **Icons**: 20px with consistent spacing +- **Chevron**: 16px with translateX(2px) hover animation +- **Typography**: 15px medium weight for clarity + +### Animation System +- **Entry**: 200ms ease-out modal slide up +- **Panel transitions**: 250ms slide from right +- **Micro-interactions**: 150ms hover effects +- **Exit**: 150ms ease-in with backdrop fade + +## Component Usage + +### Basic Modal Implementation + +```tsx +// Trigger settings modal (from any component) +import { useNavigate } from 'react-router-dom'; + +const navigate = useNavigate(); +const openSettings = () => navigate('/settings'); +const openConnections = () => navigate('/settings/connections'); +``` + +### Settings Navigation Hook + +```tsx +import { useSettingsNavigation } from '../hooks/useSettingsNavigation'; + +const { + currentRoute, + navigateTo, + navigateBack, + closeModal +} = useSettingsNavigation(); + +// Navigate to connections +navigateTo('connections'); + +// Go back or close +navigateBack(); // or closeModal(); +``` + +### Redux Integration + +```tsx +// User profile data +const { user } = useAppSelector((state) => state.user); +const displayName = user?.username || user?.firstName || 'User'; + +// Connection status +const { isAuthenticated } = useAppSelector((state) => state.telegram); + +// Logout functionality +const dispatch = useAppDispatch(); +const handleLogout = () => { + dispatch(clearToken()); + navigate('/'); +}; +``` + +## Connection Management + +### Status Display +- **Connected**: Green badge with proper status +- **Offline**: Gray badge for disconnected services +- **Coming Soon**: Disabled state for future integrations + +### Integration Points +- **Telegram**: Uses existing `TelegramConnectionModal` for setup +- **Redux State**: Real-time status from telegram slice +- **Component Reuse**: Leverages `connectOptions` from onboarding + +### Connection Actions +```tsx +// Connect new service +const handleConnect = (serviceId: string) => { + if (serviceId === 'telegram') { + setTelegramModalOpen(true); + } + // Future: other service connection flows +}; + +// Disconnect service +const handleDisconnect = (serviceId: string) => { + // Service-specific disconnection logic +}; +``` + +## Mobile Responsiveness + +### Breakpoint Behavior +- **Mobile (<640px)**: Full-screen modal with slight margins +- **Tablet (640-1024px)**: Scaled modal with backdrop +- **Desktop (>1024px)**: Fixed 520px width + +### Touch Interactions +- **Minimum target size**: 48px for accessibility +- **Swipe gestures**: Down-to-close support +- **Safe areas**: iOS notch and navigation accommodation + +## Accessibility Features + +### Focus Management +- Trap focus within modal during interaction +- Return focus to trigger element on close +- Keyboard navigation between menu items + +### ARIA Labels +- `role="dialog"` with proper modal attributes +- `aria-labelledby` for modal title +- Screen reader friendly navigation + +### Keyboard Support +- **Escape key**: Close modal and return to previous page +- **Arrow keys**: Navigate between menu items +- **Enter/Space**: Activate menu items +- **Tab**: Focus trap within modal + +## Integration Patterns + +### Existing Component Reuse +- **Connection Options**: Reuses `connectOptions` array from `ConnectStep.tsx` +- **Modal Pattern**: Follows `TelegramConnectionModal.tsx` pattern +- **Redux Patterns**: Uses existing slice patterns and selectors + +### State Management +- **No new Redux state**: Leverages existing auth, user, telegram slices +- **URL state**: Modal state driven by route parameters +- **Component state**: Local state for animations and temporary UI state + +### Future Extensibility +- **Panel Structure**: Easy to add new settings panels +- **Menu Items**: Simple configuration for new settings categories +- **Service Integration**: Pattern established for new connection types + +## Performance Considerations + +### Code Splitting +- Settings panels lazy-loaded when accessed +- Modal infrastructure loaded on first settings access +- Minimal impact on initial app bundle size + +### Animation Performance +- Hardware-accelerated CSS transforms +- Proper will-change declarations for animations +- Debounced interactions for smooth experience + +### Memory Management +- Proper cleanup of event listeners and timers +- Component unmounting handled correctly +- Redux subscriptions managed efficiently + +## Development Guidelines + +### Adding New Settings Panels +1. Create panel component in `src/components/settings/panels/` +2. Add route in `SettingsModal.tsx` switch statement +3. Add menu item in `SettingsHome.tsx` menu array +4. Follow `ConnectionsPanel.tsx` pattern for consistency + +### Styling Conventions +- Use existing Tailwind classes where possible +- Follow clean white design (not glass morphism) +- Maintain 52px height for interactive elements +- Use consistent spacing and typography scales + +### Testing Patterns +- Test modal open/close functionality +- Verify URL navigation between panels +- Test Redux state integration +- Ensure mobile responsive behavior +- Validate accessibility requirements + +--- + +*This settings modal system provides a robust, extensible foundation for app configuration while maintaining the sophisticated design standards of the crypto community platform.* \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 294fd5c5c..b95fd4301 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -146,6 +146,12 @@ Production defaults are in `src/utils/config.ts`. Key updates from recent commits: ### Major Additions +- **Settings Modal System** (`60054d8`): Complete URL-based settings modal with clean white design + - Modal infrastructure with backdrop blur and center positioning + - User profile integration with Redux state management + - Connection management panel reusing onboarding components + - URL routing for `/settings` and `/settings/connections` paths + - Mobile responsive design with accessibility features - **Type Casting Helpers**: Added for Telegram MTProto API (`5a0425c`) - **Onboarding Refactor**: Updated connection logic and steps (`bd1d240`) - **MCP Tools Enhancement**: Improved type safety and consistency across Telegram tools (`d0e1191`, `86cc53a`) @@ -153,19 +159,30 @@ Key updates from recent commits: - **Big Integer Support**: Consistent handling across all Telegram MCP tools (`0abed4d`) ### Design System Updates +- **Settings Modal UI**: Clean 520px white modal contrasting with glass morphism theme +- **Animations**: 200ms entry animations, 250ms panel transitions, chevron hover effects - **Lottie Animations**: Integrated into onboarding flow (`334673e`) - **Connection Components**: Added Telegram and Gmail connection indicators - **Routing**: Switched to HashRouter for better desktop app compatibility - **Theme**: Implemented sophisticated color system with premium crypto aesthetic ### Component Structure -- **153 TypeScript files** across `src/` directory +- **165+ TypeScript files** across `src/` directory (added settings modal system) +- **Settings Modal System**: Complete modal infrastructure in `src/components/settings/` + - SettingsModal.tsx - Main container with URL routing + - SettingsLayout.tsx - Modal wrapper with createPortal + - SettingsHome.tsx - Main menu with profile and navigation + - ConnectionsPanel.tsx - Connection management with status indicators + - Hooks: useSettingsNavigation.ts, useSettingsAnimation.ts - **Onboarding Flow**: Multi-step process with privacy, analytics, and connection steps - **Authentication**: Web-to-desktop handoff using `outsourced://` scheme - **Connection Management**: Telegram MTProto and Socket.io integration ## Key Patterns +- **Modal System**: Settings modal uses `createPortal` pattern with URL-based routing. Clean white design (not glass morphism) for system settings. Navigate with `/settings` and `/settings/connections` paths. +- **Component Reuse**: Connection management reuses `connectOptions` array and components from onboarding flow. Maintains consistent UX patterns across features. +- **Redux Integration**: Settings modal integrates with existing slices - auth for logout, user for profile display, telegram for connection status. No new state management needed. - **Node polyfills**: Vite config (`vite.config.ts`) polyfills `buffer`, `process`, `util`, `os`, `crypto`, `stream` for the `telegram` npm package which requires Node APIs. - **Telegram IDs**: Use `big-integer` library, not native JS numbers (Telegram IDs exceed `Number.MAX_SAFE_INTEGER`). - **MCP tool files**: Each tool in `src/lib/mcp/telegram/tools/` exports a handler conforming to `TelegramMCPToolHandler` interface. Tool names are typed in `src/lib/mcp/telegram/types.ts`.