@djangocfg/layouts 2.1.36 → 2.1.37

package/src/snippets/PWA/@refactoring2/REMAINING-ISSUES.md

@@ -0,0 +1,557 @@
+# Remaining Issues After P0 Refactoring
+
+**Date**: December 2025
+**Status**: Post-P0 Analysis
+
+## Summary
+
+Total remaining issues: **10**
+
+| Priority | Count | Status |
+|----------|-------|--------|
+| **P1** (High) | 3 | ⚠️ Should fix before next release |
+| **P2** (Medium) | 4 | ⏳ Can fix incrementally |
+| **P3** (Low) | 3 | 💡 Nice to have |
+
+---
+
+## P1: High Priority Issues
+
+Must be addressed before next production release.
+
+### P1-1: Security Vulnerability in config.ts
+
+**Location**: `config.ts:10-11`
+
+**Issue**: Frontend package exposes server-side secrets
+
+```typescript
+// ❌ SECURITY ISSUE
+export const VAPID_PRIVATE_KEY = process.env.VAPID_PRIVATE_KEY || '';
+export const VAPID_MAILTO = process.env.VAPID_MAILTO || '';
+```
+
+**Problem**:
+- Private VAPID key should NEVER be in frontend code
+- Even if accessed via env var, bundlers may include it
+- This is a **critical security vulnerability**
+
+**Impact**: 🔴 Critical
+- Attackers can send unauthorized push notifications
+- Private key compromise requires regeneration
+- All existing subscriptions would need re-subscription
+
+**Effort**: Low (5 minutes)
+
+**Fix**: Remove these lines entirely from frontend package
+
+```typescript
+// ✅ FIXED - Only expose public key
+export const DEFAULT_VAPID_PUBLIC_KEY = process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY || '';
+// Note: VAPID_PRIVATE_KEY should only exist in backend/API routes
+```
+
+**See**: [RECOMMENDATIONS.md#fix-security-vulnerability](./RECOMMENDATIONS.md#fix-security-vulnerability)
+
+---
+
+### P1-2: Inconsistent Error Logging
+
+**Locations**:
+- `components/PushPrompt.tsx:106`
+- `components/A2HSHint.tsx:150`
+- `context/PushContext.tsx:114`
+
+**Issue**: 3 files still use `console.error` instead of `pwaLogger.error`
+
+**Code Examples**:
+
+```typescript
+// ❌ PushPrompt.tsx:106
+console.error('[PushPrompt] Enable failed:', error);
+
+// ❌ A2HSHint.tsx:150
+console.error('[A2HSHint] Install error:', error);
+
+// ❌ PushContext.tsx:114
+console.error('Failed to send push:', error);
+```
+
+**Problem**:
+- Inconsistent with P0 refactoring (logger.ts)
+- No debug mode control for these errors
+- Breaks the conditional logging pattern
+
+**Impact**: 🟡 Medium
+- Console spam in production (errors only)
+- Inconsistent DX
+- Harder to debug with mixed logging patterns
+
+**Effort**: Low (10 minutes)
+
+**Fix**: Replace all with `pwaLogger.error()`
+
+```typescript
+// ✅ FIXED
+import { pwaLogger } from '../utils/logger';
+
+pwaLogger.error('[PushPrompt] Enable failed:', error);
+```
+
+**Note**: `pwaLogger.error()` always logs (even in production), so behavior stays the same but now consistent.
+
+**See**: [RECOMMENDATIONS.md#fix-inconsistent-logging](./RECOMMENDATIONS.md#fix-inconsistent-logging)
+
+---
+
+### P1-3: Duplicated localStorage Keys
+
+**Locations**:
+- `components/A2HSHint.tsx:27`
+- `components/PushPrompt.tsx:18`
+
+**Issue**: Similar localStorage key patterns duplicated across files
+
+**Code**:
+
+```typescript
+// A2HSHint.tsx:27
+const DISMISSED_KEY = 'cmdop-a2hs-dismissed';
+
+// PushPrompt.tsx:18
+const DISMISSED_KEY = 'pwa-push-dismissed';
+```
+
+**Problem**:
+- DRY violation (Don't Repeat Yourself)
+- If we want to change key prefix, must update in 2+ places
+- Potential key collision if not careful
+
+**Impact**: 🟡 Medium
+- Maintenance overhead
+- Risk of inconsistent key naming
+- Harder to clear all PWA data
+
+**Effort**: Low (15 minutes)
+
+**Fix**: Centralize in `utils/localStorage.ts`
+
+```typescript
+// utils/localStorage.ts
+export const STORAGE_KEYS = {
+  // ... existing keys ...
+  A2HS_DISMISSED: 'pwa_a2hs_dismissed_at',
+  PUSH_DISMISSED: 'pwa_push_dismissed_at',
+} as const;
+```
+
+**See**: [RECOMMENDATIONS.md#centralize-localstorage-keys](./RECOMMENDATIONS.md#centralize-localstorage-keys)
+
+---
+
+## P2: Medium Priority Issues
+
+Can be addressed incrementally over next few sprints.
+
+### P2-1: Unused EngagementMetrics Code
+
+**Location**: `utils/localStorage.ts:132-205`
+
+**Issue**: Fully implemented engagement tracking but never used
+
+**Code**: ~74 lines of dead code
+
+```typescript
+// utils/localStorage.ts - All unused
+export function getEngagementMetrics(): EngagementMetrics { ... }
+export function saveEngagementMetrics(metrics: EngagementMetrics): void { ... }
+export function trackAction(): void { ... }
+export function trackTimeSpent(ms: number): void { ... }
+export function updateVisit(): void { ... }
+```
+
+**Problem**:
+- Dead code increases bundle size
+- Confusing for developers (is it used?)
+- Maintenance burden
+
+**Impact**: 🟡 Medium
+- ~2-3 KB bundle size (after minification)
+- Developer confusion
+- Potential bugs if someone starts using it without testing
+
+**Effort**: Low (choose option below)
+
+**Options**:
+
+**Option A**: Remove it entirely
+```typescript
+// Remove lines 132-205 from localStorage.ts
+// Remove EngagementMetrics from types/components.ts
+```
+
+**Option B**: Actually use it
+```typescript
+// Add to InstallContext.tsx
+const { actions, timeSpent } = useEngagement();
+
+// Show install prompt based on engagement
+if (actions > 10 && timeSpent > 60000) {
+  // User is engaged, show install prompt
+}
+```
+
+**Recommendation**: Remove unless there's a plan to use it within 2 sprints
+
+**See**: [RECOMMENDATIONS.md#handle-unused-engagement-metrics](./RECOMMENDATIONS.md#handle-unused-engagement-metrics)
+
+---
+
+### P2-2: Context Composition Complexity
+
+**Location**: `context/InstallContext.tsx:81-84`
+
+**Issue**: Conditional context wrapping makes composition hard to follow
+
+**Code**:
+
+```typescript
+// Wrap with PushProvider if configured
+if (config.pushNotifications) {
+  content = <PushProvider {...config.pushNotifications}>{content}</PushProvider>;
+}
+```
+
+**Problem**:
+- Magic wrapping based on config
+- Hard to understand composition tree
+- Difficult to test in isolation
+
+**Impact**: 🟡 Medium
+- Developer confusion
+- Harder to test
+- Implicit dependencies
+
+**Effort**: Medium (30 minutes)
+
+**Fix**: Make composition explicit
+
+```typescript
+// ✅ Explicit composition (recommended)
+export function PwaProvider({ children, ...config }: PwaConfig & { children: React.ReactNode }) {
+  if (config.enabled === false) return <>{children}</>;
+
+  // Build context tree explicitly
+  return (
+    <InstallProvider {...config}>
+      <ConditionalPushProvider enabled={!!config.pushNotifications} {...config.pushNotifications}>
+        {children}
+      </ConditionalPushProvider>
+    </InstallProvider>
+  );
+}
+```
+
+**See**: [RECOMMENDATIONS.md#simplify-context-composition](./RECOMMENDATIONS.md#simplify-context-composition)
+
+---
+
+### P2-3: No Server-Side Push Subscription Persistence
+
+**Location**: `hooks/usePushNotifications.ts:117-123`
+
+**Issue**: Push subscriptions only saved client-side
+
+**Code**:
+
+```typescript
+// Send subscription to server
+if (options.subscribeEndpoint) {
+  await fetch(options.subscribeEndpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(subscription),
+  });
+}
+```
+
+**Problem**:
+- No error handling for server failure
+- No confirmation that server saved it
+- No way to sync subscriptions across devices
+- No unsubscribe endpoint
+
+**Impact**: 🟡 Medium
+- Silent failures possible
+- Can't manage subscriptions on backend
+- Can't send targeted push notifications
+
+**Effort**: Medium (1-2 hours)
+
+**Fix**: Add proper server-side persistence
+
+```typescript
+// Backend API route needed
+POST /api/push/subscribe
+DELETE /api/push/unsubscribe
+GET /api/push/subscription
+
+// Frontend changes
+const response = await fetch(options.subscribeEndpoint, ...);
+if (!response.ok) {
+  throw new Error('Server failed to save subscription');
+}
+const { success, subscriptionId } = await response.json();
+```
+
+**See**: [RECOMMENDATIONS.md#add-server-side-persistence](./RECOMMENDATIONS.md#add-server-side-persistence)
+
+---
+
+### P2-4: Limited Error Recovery for Push Subscriptions
+
+**Location**: `hooks/usePushNotifications.ts:133-146`
+
+**Issue**: Push subscription errors have no recovery mechanism
+
+**Code**:
+
+```typescript
+} catch (error: any) {
+  pwaLogger.error('[usePushNotifications] Subscribe failed:', error);
+
+  // Diagnostic logging but no recovery
+  if (error.name === 'AbortError' || error.message?.includes('push service error')) {
+    pwaLogger.error('[usePushNotifications] Push service blocked. Possible causes:');
+    // ... more error logs
+  }
+
+  return false; // Just fail, no retry
+}
+```
+
+**Problem**:
+- No retry logic for transient failures
+- No user-facing error messages
+- No recovery suggestions
+
+**Impact**: 🟡 Medium
+- Poor UX for temporary network issues
+- Users confused why it failed
+- No way to retry without page refresh
+
+**Effort**: Medium (1 hour)
+
+**Fix**: Add retry logic + user feedback
+
+```typescript
+// Add retry with exponential backoff
+const subscribe = async (retries = 3): Promise<boolean> => {
+  for (let i = 0; i < retries; i++) {
+    try {
+      // ... subscription logic
+      return true;
+    } catch (error) {
+      if (i === retries - 1) {
+        // Last attempt failed - show user error
+        onError?.(getErrorMessage(error));
+        return false;
+      }
+      // Wait before retry (exponential backoff)
+      await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
+    }
+  }
+  return false;
+};
+```
+
+**See**: [RECOMMENDATIONS.md#improve-error-recovery](./RECOMMENDATIONS.md#improve-error-recovery)
+
+---
+
+## P3: Nice to Have
+
+Low priority improvements that would enhance quality but aren't blocking.
+
+### P3-1: No Tests
+
+**Location**: Entire `src/snippets/PWA/` directory
+
+**Issue**: Zero unit tests, zero integration tests
+
+**Problem**:
+- Can't verify correctness
+- Regressions possible
+- Refactoring risky
+
+**Impact**: 🟢 Low (for now)
+- No issues currently
+- But future changes risky
+
+**Effort**: High (4-8 hours for full coverage)
+
+**Fix**: Add tests incrementally
+
+```typescript
+// utils/platform.test.ts
+describe('isStandalone', () => {
+  it('returns false when window is undefined', () => {
+    expect(isStandalone()).toBe(false);
+  });
+
+  it('checks matchMedia for standalone display mode', () => {
+    // ... test implementation
+  });
+});
+```
+
+**Priority**: Start with utils (pure functions), then hooks, then components
+
+**See**: [RECOMMENDATIONS.md#add-testing](./RECOMMENDATIONS.md#add-testing)
+
+---
+
+### P3-2: Limited Accessibility
+
+**Location**:
+- `components/A2HSHint.tsx`
+- `components/PushPrompt.tsx`
+- `components/IOSGuideModal.tsx`
+
+**Issue**: Missing some ARIA labels and keyboard navigation
+
+**Examples**:
+- Close buttons have aria-label ✅
+- But modals don't trap focus ❌
+- No keyboard shortcut to dismiss ❌
+- No screen reader announcements ❌
+
+**Impact**: 🟢 Low
+- Works with screen readers (basic)
+- But not optimal
+
+**Effort**: Medium (2-3 hours)
+
+**Fix**: Enhance accessibility
+
+```typescript
+// Add focus trap
+import { useFocusTrap } from '@djangocfg/ui-nextjs/hooks';
+
+export function IOSGuideModal({ open, onDismiss }: Props) {
+  const focusTrapRef = useFocusTrap<HTMLDivElement>(open);
+
+  return (
+    <Dialog open={open} onOpenChange={onDismiss}>
+      <DialogContent ref={focusTrapRef} role="alertdialog" aria-describedby="ios-guide-description">
+        {/* Add keyboard listener */}
+        <div onKeyDown={(e) => e.key === 'Escape' && onDismiss()}>
+          {/* content */}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
+**See**: [RECOMMENDATIONS.md#improve-accessibility](./RECOMMENDATIONS.md#improve-accessibility)
+
+---
+
+### P3-3: TypeScript Not in Strict Mode
+
+**Location**: `tsconfig.json` (parent)
+
+**Issue**: TypeScript strict mode not enabled
+
+**Examples**:
+```typescript
+// These would be caught in strict mode
+const value: any = something; // any should be avoided
+element?.addEventListener('click', handler); // handler type unclear
+```
+
+**Impact**: 🟢 Low
+- Current code works fine
+- But future changes could introduce bugs
+
+**Effort**: Medium (2-4 hours to fix all errors)
+
+**Fix**: Enable strict mode incrementally
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictPropertyInitialization": true
+  }
+}
+```
+
+Then fix all resulting type errors.
+
+**See**: [RECOMMENDATIONS.md#enable-typescript-strict-mode](./RECOMMENDATIONS.md#enable-typescript-strict-mode)
+
+---
+
+## Issue Summary by File
+
+| File | P1 Issues | P2 Issues | P3 Issues | Total |
+|------|-----------|-----------|-----------|-------|
+| config.ts | 1 | 0 | 0 | 1 |
+| PushPrompt.tsx | 1 | 0 | 1 | 2 |
+| A2HSHint.tsx | 1 | 0 | 1 | 2 |
+| PushContext.tsx | 1 | 1 | 0 | 2 |
+| InstallContext.tsx | 0 | 1 | 0 | 1 |
+| usePushNotifications.ts | 0 | 1 | 0 | 1 |
+| localStorage.ts | 1 | 1 | 0 | 2 |
+| IOSGuide components | 0 | 0 | 1 | 1 |
+| Testing/TS Config | 0 | 0 | 2 | 2 |
+
+---
+
+## Recommended Fix Order
+
+### Sprint 1 (P1 Issues - ~30 minutes total)
+
+1. Fix security vulnerability (config.ts) - **5 min**
+2. Replace console.error with pwaLogger (3 files) - **10 min**
+3. Centralize localStorage keys - **15 min**
+
+**Impact**: Eliminates all P1 issues
+
+### Sprint 2 (P2 High-Value Issues - ~2 hours)
+
+4. Remove unused EngagementMetrics OR implement usage - **30 min**
+5. Add server-side push subscription persistence - **1.5 hours**
+
+**Impact**: Reduces bundle size, enables proper push management
+
+### Sprint 3 (P2 Polish - ~1.5 hours)
+
+6. Simplify context composition - **30 min**
+7. Improve error recovery for push subscriptions - **1 hour**
+
+**Impact**: Better DX and UX
+
+### Sprint 4+ (P3 - Ongoing)
+
+8. Add tests (incrementally)
+9. Improve accessibility
+10. Enable TypeScript strict mode
+
+**Impact**: Long-term quality improvements
+
+---
+
+## Conclusion
+
+**Critical**: Only 3 P1 issues, all fixable in ~30 minutes
+**Important**: 4 P2 issues, addressable over 2-3 sprints
+**Optional**: 3 P3 issues for long-term quality
+
+**Next Steps**: See [RECOMMENDATIONS.md](./RECOMMENDATIONS.md) for detailed fixes with code examples.