# Phase 2: UnifiedAssignmentModal Extraction

Status: ✅ Complete
Date: 2025-11-10
Effort: ~2 hours
Files Created: 6
Lines of Code: ~600

🎯 Objective

Extract generic assignment components from the refactored SquadManagement to create reusable UI patterns for all M:N assignment scenarios in TurnFix.

📊 Summary

Created a generic three-column assignment UI system that can be reused across: - ✅ Squads ← Participants (original use case) - 🔄 Groups ← Participants (next: Phase 4) - 🔄 Teams ← Participants - 🔄 Judges ← Disciplines - 🔄 Coaches ← Athletes - 🔄 EventParticipants ← Competitions

📁 File Structure

client/src/components/assignment/
├── index.ts                              # Public API exports
├── UnifiedAssignmentModal.tsx            # Main orchestration component (140 lines)
├── UnifiedAssignmentModal.types.ts       # TypeScript definitions (175 lines)
├── MasterList.tsx                        # Column 1: Master items (105 lines)
├── AvailableList.tsx                     # Column 2: Available items (130 lines)
└── DetailPane.tsx                        # Column 3: Detail view (50 lines)

Total: 6 files, ~600 lines

🏗️ Architecture

Three-Column Layout Pattern

┌──────────────┬──────────────┬──────────────┐
│ Column 1     │ Column 2     │ Column 3     │
│ Master List  │ Available    │ Detail Pane  │
│              │ Items        │              │
│ ┌─────────┐  │ ┌─────────┐  │ ┌──────────┐ │
│ │ Squad A │◄─┼─│ John D. │  │ │ Squad A  │ │
│ ├─────────┤  │ ├─────────┤  │ │          │ │
│ │ Squad B │  │ │ Mary S. │  │ │ Members: │ │
│ ├─────────┤  │ ├─────────┤  │ │ • John   │ │
│ │ Squad C │  │ │ Tom H.  │  │ │ • Sarah  │ │
│ └─────────┘  │ └─────────┘  │ └──────────┘ │
└──────────────┴──────────────┴──────────────┘
    Select        Assign →      View/Unassign

Generic Type System

// Base interfaces for all assignment types
BaseMasterItem   → Squad, Group, Team, Judge, Coach
BaseAvailableItem → Participant, Athlete, Discipline
BaseAssignment   → SquadParticipant, GroupMember, etc.

// Configuration pattern
AssignmentConfig<TMaster, TAvailable> {
  entityNames: { master, available, masterPlural, availablePlural }
  getMasterMetadata: (item) => { itemCount, subtitle, tags, isVirtual }
  getAvailableMetadata: (item) => { subtitle, tags: [{ label, color, isHighlighted }] }
  onAssign, onUnassign, onCreateMaster, onDeleteMaster, onExportPDF
  features: { allowCreate, allowDelete, allowExport, showFilters, ... }
}

🔧 Component Details

1. UnifiedAssignmentModal.tsx (Main Component)

Purpose: Orchestrate the three-column layout with generic configuration

Key Features: - ✅ Generic type parameters <TMaster, TAvailable, TAssignment> - ✅ Configuration-driven UI (no hardcoded entity names) - ✅ Optional filtering support - ✅ Conditional feature flags (create, delete, export) - ✅ Loading state management

Usage Pattern: 

<UnifiedAssignmentModal
  masterItems={squads}
  availableItems={participants}
  assignments={squadAssignments}
  config={{
    entityNames: { master: "Squad", available: "Participant", ... },
    getMasterMetadata: (squad) => ({ itemCount: squad.participantCount, ... }),
    onAssign: assignParticipantToSquad,
    onUnassign: removeParticipantFromSquad,
    features: { allowCreate: true, allowDelete: true, ... }
  }}
/>

2. MasterList.tsx (Column 1)

Purpose: Display master entities (Squads, Groups, Teams, etc.)

Features: - ✅ Selectable items with highlight state - ✅ Virtual entity badge (orange border + badge) - ✅ Item count display - ✅ Tag/badge support (competitions, roles, etc.) - ✅ Delete button (optional) - ✅ Metadata-driven rendering

Metadata Structure: 

{
  itemCount: number;         // "5 Participants"
  subtitle?: string;         // Optional description
  tags?: Array<{             // Competition badges, etc.
    label: string;
    color?: string;
  }>;
  isVirtual?: boolean;       // Show virtual badge
}

3. AvailableList.tsx (Column 2)

Purpose: Display available items for assignment

Features: - ✅ Assign button (arrow icon) when master selected - ✅ Tag highlighting (for competition filtering) - ✅ Virtual assignment info box - ✅ Scrollable list (max-height: 600px) - ✅ Flexible naming (firstname + lastname OR displayName OR name) - ✅ Tag-based filtering support

Metadata Structure: 

{
  subtitle?: string;              // "Club ABC • male • 15 years"
  tags?: Array<{
    label: string;
    color?: string;
    isHighlighted?: boolean;      // Blue highlight for filtered items
  }>;
}

4. DetailPane.tsx (Column 3)

Purpose: Show selected master item's details

Features: - ✅ Empty state (no selection) - ✅ Custom render function support - ✅ Generic entity name display

Custom Rendering: 

renderContent: (squad) => (
  <>
    <Participants list={squad.participants} onRemove={handleRemove} />
    <Competitions list={squad.competitions} onClick={handleClick} />
  </>
)

🎨 UI Design Patterns

Visual Hierarchy

Color Coding: - 🔵 Blue: Selected master, highlighted tags (primary action) - 🟠 Orange: Virtual entities, warnings - 🔴 Red: Delete actions - ⚪ Gray: Default state, inactive items

Borders: - Thick blue border: Selected master item - Orange left border: Virtual entities - Blue double border + shadow: Highlighted available items (filtered)

Responsive Design

  • Desktop (lg+): Three-column grid
  • Mobile: Stacked single-column layout
  • Scrollable areas: max-height constraints with overflow-y-auto

🔄 Reusability Pattern

Step 1: Define Your Types

// For Squad Management
interface Squad extends BaseMasterItem {
  participantCount: number;
  competitions: Array<{ id: number; name: string; number: string }>;
  participants: Participant[];
}

interface Participant extends BaseAvailableItem {
  firstname: string;
  lastname: string;
  club: string;
  gender: string;
  birthYear: number;
  competitions: Array<{ id: number; name: string; number: string }>;
}

interface SquadAssignment extends BaseAssignment {
  squadId: number;
  participantId: number;
}

Step 2: Create Configuration

const squadConfig: AssignmentConfig<Squad, Participant> = {
  entityNames: {
    master: "Squad",
    available: "Participant",
    masterPlural: "Squads",
    availablePlural: "Participants"
  },

  getMasterMetadata: (squad) => ({
    itemCount: squad.participantCount,
    subtitle: `${squad.participantCount} participants`,
    tags: squad.competitions.map(c => ({
      label: `${c.name} (Nr. ${c.number})`,
      color: 'bg-gray-100 text-gray-700'
    })),
    isVirtual: squad.isVirtual
  }),

  getAvailableMetadata: (participant) => ({
    subtitle: `${participant.club} • ${participant.gender} • ${age} years`,
    tags: participant.competitions.map(c => ({
      label: `${c.name} (Nr. ${c.number})`,
      color: 'bg-blue-100 text-blue-800',
      isHighlighted: c.id === selectedCompetitionId
    }))
  }),

  onAssign: assignParticipantToSquad,
  onUnassign: removeParticipantFromSquad,
  onCreateMaster: () => setShowCreateModal(true),
  onDeleteMaster: deleteSquad,

  features: {
    allowCreate: true,
    allowDelete: true,
    allowExport: true,
    showFilters: true,
    showSearch: true,
    supportsVirtual: true
  }
};

Step 3: Use the Component

<UnifiedAssignmentModal
  masterItems={squads}
  availableItems={participants}
  assignments={squadAssignments}
  config={squadConfig}
  isLoading={isLoading}
  eventId={eventId}
/>

✅ Benefits

  1. Code Reuse: Write once, use for 6 different assignment UIs
  2. Consistency: Same UX across all assignment scenarios
  3. Maintainability: Fix bugs in one place, all UIs benefit
  4. Type Safety: Full TypeScript support with generics
  5. Flexibility: Configuration-driven, not hardcoded
  6. Testability: Easier to unit test generic components
  7. Documentation: Self-documenting through types

📊 Metrics

Before (Monolithic): - SquadManagement: 1070 lines - Groups: ~800 lines (estimate) - Teams: ~700 lines (estimate) - Judges: ~600 lines (estimate) - Coaches: ~500 lines (estimate) - EventParticipants: ~1900 lines - Total: ~5,570 lines

After (Unified Components): - Generic components: ~600 lines - Squad configuration: ~150 lines (estimate) - Group configuration: ~120 lines (estimate) - Team configuration: ~100 lines (estimate) - Judge configuration: ~80 lines (estimate) - Coach configuration: ~80 lines (estimate) - EventParticipant configuration: ~180 lines (estimate) - Total: ~1,310 lines

Reduction: ~76% less code (5,570 → 1,310 lines)

🧪 Testing Checklist

Phase 3 will validate these patterns by migrating SquadManagement to use UnifiedAssignmentModal:

  • Squad selection works
  • Participant assignment works
  • Participant unassignment works
  • Virtual squad support works
  • Competition filtering works
  • Create squad modal works
  • Delete squad works
  • PDF export works
  • Empty states display correctly
  • Mobile responsive layout works

🚀 Next Steps

Phase 3: Migrate SquadManagement to use UnifiedAssignmentModal - Replace old three-column components - Wire up configuration - Validate all functionality preserved - Document migration pattern

Phase 4: Groups proof of concept - Create Group types (extend base types) - Create group configuration - Test with real group assignment scenario - Document lessons learned

Phase 5: Migrate remaining 4 pages - Teams - Judges - Coaches - EventParticipants

📝 Notes

Virtual Entity Support

The system natively supports virtual entities (items that can be assigned multiple times): - Visual indicator: Orange left border + badge - Storage hint: Shows where virtual data is stored (e.g., int_riegen_virtual) - Info box: Explains virtual assignment behavior

Tag Highlighting

Tags can be highlighted to show filtering context: - isHighlighted: true → Blue background with ring - Used for competition filtering in SquadManagement - Reusable for any filtering scenario

Flexible Naming

Components support multiple naming conventions: - displayName (highest priority) - firstname + lastname (people) - name (entities) - id (fallback)

This allows reuse across different entity types without modification.

Phase 2 Complete! ✅
Ready for Phase 3: Migration validation.