feat: Implement all 7 phases

docs/moderation/ARCHITECTURE.md

@@ -0,0 +1,34 @@
+# Moderation Queue Architecture
+
+## Overview
+
+The moderation queue system is a comprehensive content review platform that enables moderators to review, approve, and reject user-submitted content including park/ride submissions, photo uploads, and user reviews.
+
+## System Architecture
+
+### Core Components
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    ModerationQueue (Root)                    │
+│  - Entry point for moderation interface                     │
+│  - Manages UI state (modals, dialogs)                       │
+│  - Delegates business logic to hooks                         │
+└────────────┬────────────────────────────────────────────────┘
+             │
+             ├─► useModerationQueueManager (Orchestrator)
+             │   └─► Combines multiple sub-hooks
+             │       ├─► useModerationFilters (Filtering)
+             │       ├─► usePagination (Page management)
+             │       ├─► useModerationQueue (Lock management)
+             │       ├─► useModerationActions (Action handlers)
+             │       ├─► useEntityCache (Entity name resolution)
+             │       └─► useProfileCache (User profile caching)
+             │
+             ├─► QueueFilters (Filter controls)
+             ├─► QueueStats (Statistics display)
+             ├─► LockStatusDisplay (Current lock info)
+             │
+             └─► QueueItem (Individual submission renderer)
+                 └─► Wrapped in ModerationErrorBoundary
+                     └─► Prevents individual failures from crashing queue

docs/moderation/COMPONENTS.md

@@ -0,0 +1,524 @@
+# Moderation Queue Components
+
+## Component Reference
+
+### ModerationQueue (Root Component)
+
+**Location:** `src/components/moderation/ModerationQueue.tsx`
+
+**Purpose:** Root component for moderation interface. Orchestrates all sub-components and manages UI state.
+
+**Props:**
+```typescript
+interface ModerationQueueProps {
+  optimisticallyUpdateStats?: (delta: Partial<{
+    pendingSubmissions: number;
+    openReports: number;
+    flaggedContent: number;
+  }>) => void;
+}
+```
+
+**Ref API:**
+```typescript
+interface ModerationQueueRef {
+  refresh: () => void;
+}
+```
+
+**Usage:**
+```tsx
+import { useRef } from 'react';
+import { ModerationQueue } from '@/components/moderation/ModerationQueue';
+
+function AdminPanel() {
+  const queueRef = useRef<ModerationQueueRef>(null);
+  
+  return (
+    <div>
+      <button onClick={() => queueRef.current?.refresh()}>
+        Refresh Queue
+      </button>
+      <ModerationQueue ref={queueRef} />
+    </div>
+  );
+}
+```
+
+---
+
+### ModerationErrorBoundary
+
+**Location:** `src/components/error/ModerationErrorBoundary.tsx`
+
+**Purpose:** Catches React render errors in queue items, preventing full queue crashes.
+
+**Props:**
+```typescript
+interface ModerationErrorBoundaryProps {
+  children: ReactNode;
+  submissionId?: string;
+  fallback?: ReactNode;
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+```
+
+**Features:**
+- Automatic error logging
+- User-friendly error UI
+- Retry functionality
+- Copy error details button
+- Development-mode stack traces
+
+**Usage:**
+```tsx
+<ModerationErrorBoundary submissionId={item.id}>
+  <QueueItem item={item} {...props} />
+</ModerationErrorBoundary>
+```
+
+**Custom Fallback:**
+```tsx
+<ModerationErrorBoundary
+  submissionId={item.id}
+  fallback={<div>Custom error message</div>}
+  onError={(error, info) => {
+    // Send to monitoring service
+    trackError(error, info);
+  }}
+>
+  <QueueItem item={item} {...props} />
+</ModerationErrorBoundary>
+```
+
+---
+
+### QueueItem
+
+**Location:** `src/components/moderation/QueueItem.tsx`
+
+**Purpose:** Renders individual submission in queue with all interaction controls.
+
+**Props:**
+```typescript
+interface QueueItemProps {
+  item: ModerationItem;
+  isMobile: boolean;
+  actionLoading: string | null;
+  isLockedByMe: boolean;
+  isLockedByOther: boolean;
+  lockStatus: LockStatus;
+  currentLockSubmissionId?: string;
+  notes: Record<string, string>;
+  isAdmin: boolean;
+  isSuperuser: boolean;
+  queueIsLoading: boolean;
+  onNoteChange: (id: string, value: string) => void;
+  onApprove: (item: ModerationItem, action: 'approved' | 'rejected', notes?: string) => void;
+  onResetToPending: (item: ModerationItem) => void;
+  onRetryFailed: (item: ModerationItem) => void;
+  onOpenPhotos: (photos: PhotoForDisplay[], index: number) => void;
+  onOpenReviewManager: (submissionId: string) => void;
+  onOpenItemEditor: (submissionId: string) => void;
+  onClaimSubmission: (submissionId: string) => void;
+  onDeleteSubmission: (item: ModerationItem) => void;
+  onInteractionFocus: (id: string) => void;
+  onInteractionBlur: (id: string) => void;
+}
+```
+
+**Key Features:**
+- Displays submission type, status, timestamps
+- User profile with avatar
+- Validation summary (errors, warnings)
+- Lock status indicators
+- Moderator edit badges
+- Action buttons (approve, reject, claim)
+- Responsive mobile/desktop layouts
+
+**Accessibility:**
+- Keyboard navigation support
+- ARIA labels on interactive elements
+- Focus management
+- Screen reader compatible
+
+---
+
+### QueueFilters
+
+**Location:** `src/components/moderation/QueueFilters.tsx`
+
+**Purpose:** Filter and sort controls for moderation queue.
+
+**Props:**
+```typescript
+interface QueueFiltersProps {
+  activeEntityFilter: EntityFilter;
+  activeStatusFilter: StatusFilter;
+  sortConfig: SortConfig;
+  isMobile: boolean;
+  isLoading?: boolean;
+  onEntityFilterChange: (filter: EntityFilter) => void;
+  onStatusFilterChange: (filter: StatusFilter) => void;
+  onSortChange: (config: SortConfig) => void;
+  onClearFilters: () => void;
+  showClearButton: boolean;
+}
+```
+
+**Features:**
+- Entity type filter (all, reviews, submissions, photos)
+- Status filter (pending, approved, rejected, etc.)
+- Sort controls (date, type, status)
+- Clear filters button
+- Fully accessible (ARIA labels, keyboard navigation)
+
+**Usage:**
+```tsx
+<QueueFilters
+  activeEntityFilter={filters.entityFilter}
+  activeStatusFilter={filters.statusFilter}
+  sortConfig={filters.sortConfig}
+  isMobile={isMobile}
+  onEntityFilterChange={filters.setEntityFilter}
+  onStatusFilterChange={filters.setStatusFilter}
+  onSortChange={filters.setSortConfig}
+  onClearFilters={filters.clearFilters}
+  showClearButton={filters.hasActiveFilters}
+/>
+```
+
+---
+
+### ValidationSummary
+
+**Location:** `src/components/moderation/ValidationSummary.tsx`
+
+**Purpose:** Displays validation results for submission items.
+
+**Props:**
+```typescript
+interface ValidationSummaryProps {
+  item: {
+    item_type: string;
+    item_data: SubmissionItemData;
+    id?: string;
+  };
+  onValidationChange?: (result: ValidationResult) => void;
+  compact?: boolean;
+  validationKey?: number;
+}
+```
+
+**View Modes:**
+
+**Compact (for queue items):**
+- Status badges (Valid, Errors, Warnings)
+- Always-visible error details (no hover needed)
+- Minimal space usage
+
+**Detailed (for review manager):**
+- Expandable validation details
+- Full error, warning, and suggestion lists
+- Re-validate button
+
+**Usage:**
+```tsx
+{/* Compact view in queue */}
+<ValidationSummary
+  item={{
+    item_type: 'park',
+    item_data: parkData,
+    id: itemId
+  }}
+  compact={true}
+  onValidationChange={(result) => {
+    if (result.blockingErrors.length > 0) {
+      setCanApprove(false);
+    }
+  }}
+/>
+
+{/* Detailed view in editor */}
+<ValidationSummary
+  item={{
+    item_type: 'ride',
+    item_data: rideData
+  }}
+  compact={false}
+/>
+```
+
+---
+
+## Hooks Reference
+
+### useModerationQueueManager
+
+**Location:** `src/hooks/moderation/useModerationQueueManager.ts`
+
+**Purpose:** Orchestrator hook combining all moderation queue logic.
+
+**Usage:**
+```typescript
+const queueManager = useModerationQueueManager({
+  user,
+  isAdmin: isAdmin(),
+  isSuperuser: isSuperuser(),
+  toast,
+  settings: {
+    refreshMode: 'auto',
+    pollInterval: 30000,
+    refreshStrategy: 'merge',
+    preserveInteraction: true,
+    useRealtimeQueue: true,
+  },
+});
+
+// Access sub-hooks
+queueManager.filters.setEntityFilter('reviews');
+queueManager.pagination.setCurrentPage(2);
+queueManager.queue.claimSubmission(itemId);
+
+// Perform actions
+await queueManager.performAction(item, 'approved', 'Looks good!');
+await queueManager.deleteSubmission(item);
+```
+
+---
+
+### useModerationQueue
+
+**Location:** `src/hooks/useModerationQueue.ts`
+
+**Purpose:** Lock management and queue statistics.
+
+**Features:**
+- Claim/release submission locks
+- Lock expiry countdown
+- Lock status checking
+- Queue statistics
+
+**Usage:**
+```typescript
+const queue = useModerationQueue({
+  onLockStateChange: () => {
+    console.log('Lock state changed');
+  }
+});
+
+// Claim submission
+await queue.claimSubmission('submission-123');
+
+// Extend lock (adds 15 minutes)
+await queue.extendLock();
+
+// Release lock
+await queue.releaseLock('submission-123');
+
+// Check lock status
+const timeRemaining = queue.getTimeRemaining();
+const progress = queue.getLockProgress();
+```
+
+---
+
+## Testing Components
+
+### Unit Testing Example
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import { ModerationErrorBoundary } from '@/components/error/ModerationErrorBoundary';
+
+describe('ModerationErrorBoundary', () => {
+  it('catches errors and shows fallback UI', () => {
+    const ThrowError = () => {
+      throw new Error('Test error');
+    };
+    
+    render(
+      <ModerationErrorBoundary submissionId="test-123">
+        <ThrowError />
+      </ModerationErrorBoundary>
+    );
+    
+    expect(screen.getByText(/queue item error/i)).toBeInTheDocument();
+    expect(screen.getByText(/test error/i)).toBeInTheDocument();
+  });
+  
+  it('shows retry button', () => {
+    const ThrowError = () => {
+      throw new Error('Test error');
+    };
+    
+    render(
+      <ModerationErrorBoundary>
+        <ThrowError />
+      </ModerationErrorBoundary>
+    );
+    
+    expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument();
+  });
+});
+```
+
+### Integration Testing Example
+
+```typescript
+import { renderHook, act } from '@testing-library/react';
+import { useModerationQueueManager } from '@/hooks/moderation/useModerationQueueManager';
+
+describe('useModerationQueueManager', () => {
+  it('filters items correctly', async () => {
+    const { result } = renderHook(() => useModerationQueueManager(config));
+    
+    act(() => {
+      result.current.filters.setEntityFilter('reviews');
+    });
+    
+    await waitFor(() => {
+      expect(result.current.items.every(item => item.type === 'review')).toBe(true);
+    });
+  });
+});
+```
+
+---
+
+## Accessibility Guidelines
+
+### Keyboard Navigation
+
+**Queue Filters:**
+- `Tab`: Navigate between filter controls
+- `Enter`/`Space`: Open dropdown
+- `Arrow keys`: Navigate dropdown options
+- `Escape`: Close dropdown
+
+**Queue Items:**
+- `Tab`: Navigate between interactive elements
+- `Enter`/`Space`: Activate buttons
+- `Escape`: Close expanded sections
+
+### Screen Reader Support
+
+All components include:
+- Semantic HTML (`<button>`, `<label>`, `<select>`)
+- ARIA labels for icon-only buttons
+- ARIA live regions for dynamic updates
+- Proper heading hierarchy
+
+### Focus Management
+
+- Focus trapped in modals
+- Focus returned to trigger on close
+- Skip links for keyboard users
+- Visible focus indicators
+
+---
+
+## Styling Guidelines
+
+### Semantic Tokens
+
+Use design system tokens instead of hardcoded colors:
+
+```tsx
+// ❌ DON'T
+<div className="text-white bg-blue-500">
+
+// ✅ DO
+<div className="text-foreground bg-primary">
+```
+
+### Responsive Design
+
+All components support mobile/desktop layouts:
+
+```tsx
+<div className={`${isMobile ? 'flex-col' : 'flex-row'}`}>
+```
+
+### Dark Mode
+
+All components automatically adapt to light/dark mode using CSS variables.
+
+---
+
+## Performance Considerations
+
+### Memoization
+
+```tsx
+// QueueItem is memoized
+export const QueueItem = memo(({ item, ...props }) => {
+  // Component will only re-render if props change
+});
+```
+
+### Lazy Loading
+
+Large components can be lazy-loaded:
+
+```tsx
+const SubmissionReviewManager = lazy(() => 
+  import('./SubmissionReviewManager')
+);
+```
+
+### Debouncing
+
+Filters use debounced updates to reduce query load:
+
+```tsx
+const filters = useModerationFilters({
+  debounceDelay: 300, // Wait 300ms before applying filter
+});
+```
+
+---
+
+## Troubleshooting
+
+### Error Boundary Not Catching Errors
+
+**Issue:** Error boundary doesn't catch async errors or event handler errors.
+
+**Solution:** Error boundaries only catch errors during rendering, lifecycle methods, and constructors. For async errors:
+
+```tsx
+try {
+  await performAction();
+} catch (error) {
+  handleError(error); // Manual error handling
+}
+```
+
+### Lock Timer Memory Leak
+
+**Issue:** Lock timer continues after component unmount.
+
+**Solution:** Already fixed in Phase 4. Timer now checks `isMounted` flag and cleans up properly.
+
+### Validation Summary Not Updating
+
+**Issue:** Validation summary shows stale data after edits.
+
+**Solution:** Pass `validationKey` prop to force re-validation:
+
+```tsx
+<ValidationSummary
+  item={item}
+  validationKey={editCount} // Increment on each edit
+/>
+```
+
+---
+
+## References
+
+- Architecture: `docs/moderation/ARCHITECTURE.md`
+- Submission Patterns: `docs/moderation/SUBMISSION_PATTERNS.md`
+- Type Definitions: `src/types/moderation.ts`
+- Hooks: `src/hooks/moderation/`

docs/moderation/SUBMISSION_PATTERNS.md

@@ -0,0 +1,261 @@
+# Submission Patterns & Guidelines
+
+## Overview
+
+This document outlines the patterns and best practices for working with submissions in the moderation queue system.
+
+## Submission Types
+
+### 1. Content Submissions (`content_submissions`)
+
+**When to use:**
+- Creating or updating parks, rides, companies, ride models
+- Multi-item submissions with dependencies
+- Submissions requiring moderator review before going live
+
+**Data Flow:**
+```
+User Form → validateEntityData() → createSubmission() 
+  → content_submissions table 
+  → submission_items table (with dependencies)
+  → Moderation Queue
+  → Approval → process-selective-approval edge function
+  → Live entities created
+```
+
+**Example:**
+```typescript
+// Creating a park with operator dependency
+const { success } = await createParkSubmission({
+  name: "Cedar Point",
+  park_type: "theme_park",
+  operator_id: "new_operator_123", // References another item in same submission
+});
+```
+
+### 2. Photo Submissions (`photo_submissions`)
+
+**When to use:**
+- User uploading photos to existing entities
+- Photos require moderation but entity already exists
+
+**Data Flow:**
+```
+UppyPhotoSubmissionUpload 
+  → Cloudflare Direct Upload
+  → photo_submissions + photo_submission_items tables
+  → Moderation Queue
+  → Approval → Photos linked to entity
+```
+
+**Key Requirements:**
+- Must be linked to parent `content_submissions` for queue integration
+- Caption and title sanitized (plain text only, no HTML)
+- Maximum 10 photos per submission
+
+### 3. Reviews (`reviews`)
+
+**When to use:**
+- User reviewing a park or ride
+- Rating with optional text content
+
+**Data Flow:**
+```
+ReviewForm 
+  → reviews table + content_submissions (NEW)
+  → Moderation Queue
+  → Approval → Review goes live
+```
+
+**Sanitization:**
+- All review content is plain text (HTML stripped)
+- Maximum 5000 characters
+- Rating validation (0.5-5.0 scale)
+
+## When to Use Each Table
+
+### Use `content_submissions` when:
+✅ Creating new entities (parks, rides, companies)
+✅ Updating existing entities
+✅ Submissions have multi-item dependencies
+✅ Need moderator review before data goes live
+
+### Use Specialized Tables when:
+✅ **Photos**: Entity exists, just adding media (`photo_submissions`)
+✅ **Reviews**: User feedback on existing entity (`reviews` + `content_submissions`)
+✅ **Technical Specs**: Belongs to specific entity (`ride_technical_specifications`)
+
+## Validation Requirements
+
+### All Submissions Must:
+1. Pass Zod schema validation (`entityValidationSchemas.ts`)
+2. Have proper slug generation (unique, URL-safe)
+3. Include source URLs when applicable
+4. Pass duplicate detection checks
+
+### Entity-Specific Requirements:
+
+**Parks:**
+- Valid `park_type` enum
+- Valid location data (country required)
+- Opening date format validation
+
+**Rides:**
+- Must reference valid `park_id`
+- Valid `ride_type` enum
+- Opening date validation
+
+**Companies:**
+- Valid `company_type` enum
+- Country code validation
+- Founded year range check
+
+## Dependency Resolution
+
+### Dependency Types:
+1. **Same-submission dependencies**: New park references new operator (both in queue)
+2. **Existing entity dependencies**: New ride references existing park
+3. **Multi-level dependencies**: Ride → Park → Operator → Owner (4 levels)
+
+### Resolution Order:
+Dependencies are resolved using topological sorting:
+```
+1. Load all items in submission
+2. Build dependency graph
+3. Sort topologically (parents before children)
+4. Process in order
+```
+
+**Example:**
+```
+Submission contains:
+- Item A: Operator (no dependencies)
+- Item B: Park (depends on A)
+- Item C: Ride (depends on B)
+
+Processing order: A → B → C
+```
+
+## Best Practices
+
+### DO:
+✅ Use existing entities when possible (avoid duplicates)
+✅ Provide source URLs for verifiability
+✅ Write clear submission notes for moderators
+✅ Validate data on client-side before submission
+✅ Use type guards when working with `SubmissionItemData`
+
+### DON'T:
+❌ Store JSON blobs in SQL columns
+❌ Skip validation to "speed up" submissions
+❌ Create dependencies to non-existent entities
+❌ Submit without source verification
+❌ Bypass moderation queue (security risk)
+
+## Adding New Submission Types
+
+### Steps:
+1. Create type definition in `src/types/moderation.ts`
+2. Add type guard to `src/lib/moderation/typeGuards.ts`
+3. Create validation schema in `src/lib/entityValidationSchemas.ts`
+4. Add submission helper in `src/lib/entitySubmissionHelpers.ts`
+5. Update `useModerationQueueManager` query to fetch new type
+6. Create renderer component (optional, for complex UI)
+7. Add tests for new type
+
+### Example: Adding "Event" Submission Type
+
+```typescript
+// 1. Type definition (moderation.ts)
+export interface EventItemData {
+  event_id?: string;
+  name: string;
+  park_id: string;
+  start_date: string;
+  end_date: string;
+}
+
+export type SubmissionItemData = 
+  | ParkItemData 
+  | RideItemData
+  | EventItemData; // Add here
+
+// 2. Type guard (typeGuards.ts)
+export function isEventItemData(data: SubmissionItemData): data is EventItemData {
+  return 'start_date' in data && 'end_date' in data;
+}
+
+// 3. Validation (entityValidationSchemas.ts)
+const eventSchema = z.object({
+  name: z.string().min(1).max(200),
+  park_id: z.string().uuid(),
+  start_date: z.string().datetime(),
+  end_date: z.string().datetime(),
+});
+
+// 4. Submission helper (entitySubmissionHelpers.ts)
+export async function createEventSubmission(eventData: EventFormData) {
+  // Validation, submission creation logic
+}
+
+// 5. Update queue query to include events
+// (already handles all content_submissions)
+
+// 6. Optional: Create EventSubmissionDisplay component
+// 7. Add tests
+```
+
+## Migration Checklist
+
+When migrating legacy code to this pattern:
+- [ ] Remove direct database writes (use submission helpers)
+- [ ] Add validation schemas
+- [ ] Update to use `SubmissionItemData` types
+- [ ] Add type guards where needed
+- [ ] Test dependency resolution
+- [ ] Verify sanitization is applied
+- [ ] Update documentation
+
+## Security Considerations
+
+### Input Validation:
+- **Server-side validation** is mandatory (Zod schemas)
+- **Client-side validation** for UX only
+- **Never trust user input** - always validate and sanitize
+
+### Sanitization:
+- HTML stripped from user text (use `rehype-sanitize`)
+- URLs validated and optionally stripped
+- File uploads validated (type, size, count)
+- SQL injection prevented (Supabase parameterized queries)
+
+### Access Control:
+- Only moderators can approve/reject
+- Users can only submit, not self-approve
+- RLS policies enforce row-level security
+- Lock system prevents concurrent modifications
+
+## Troubleshooting
+
+### Common Issues:
+
+**"Dependency not found"**
+→ Check if parent entity exists in database or in same submission
+
+**"Validation failed"**
+→ Check Zod schema, ensure all required fields present
+
+**"Duplicate slug"**
+→ Slug generation collided, system will auto-increment
+
+**"Lock expired"**
+→ Moderator must re-claim submission to continue
+
+**"Permission denied"**
+→ Check user role (must be moderator/admin)
+
+## References
+
+- See `ARCHITECTURE.md` for system design
+- See `COMPONENTS.md` for UI component usage
+- See `../IMPLEMENTATION_COMPLETE.md` for recent changes