Story 3.1: Basic Group Creation and Selection

docs/stories/3.1.story.md

@@ -0,0 +1,234 @@
+---
+id: "3.1"
+title: "Basic Group Creation and Selection"
+type: "Feature"
+priority: "High"
+status: "Draft"
+assigned_agent: "dev"
+epic_id: "3"
+sprint_id: ""
+created_date: "2025-01-20"
+updated_date: "2025-01-20"
+estimated_effort: "L"
+dependencies: ["Complete undo/redo system (Epic 2)"]
+tags: ["grouping", "selection", "context-menu", "keyboard-shortcuts", "multi-select"]
+
+user_type: "End User"
+component_area: "Node Grouping System"
+technical_complexity: "Medium"
+business_value: "High"
+---
+
+# Story 3.1: Basic Group Creation and Selection
+
+## Story Description
+
+**As a** user, **I want** to select multiple nodes and create a group, **so that** I can organize related functionality into manageable containers.
+
+### Context
+This story begins Epic 3 - Core Node Grouping System, building on the complete undo/redo infrastructure from Epic 2. This establishes the fundamental grouping capability that allows users to organize complex graphs into logical containers. This is the foundation for all future grouping features including visual representation, pin generation, and persistence.
+
+### Background
+The node selection system already exists and supports multi-selection via Ctrl+Click and selectedItems(). The command pattern infrastructure from Epic 2 provides the foundation for undoable group operations. This story extends the existing selection and context menu systems to add group creation functionality.
+
+## Acceptance Criteria
+
+### AC1: Multi-select nodes using Ctrl+Click and drag-rectangle selection
+**Given** multiple nodes exist in the graph  
+**When** user holds Ctrl and clicks nodes or uses drag-rectangle selection  
+**Then** multiple nodes are selected and visually highlighted
+
+### AC2: Right-click context menu "Group Selected" option on valid selections  
+**Given** multiple nodes are selected  
+**When** user right-clicks on selection  
+**Then** context menu shows "Group Selected" option when valid selection exists
+
+### AC3: Keyboard shortcut Ctrl+G for grouping selected nodes
+**Given** multiple nodes are selected  
+**When** user presses Ctrl+G  
+**Then** group creation dialog appears for selected nodes
+
+### AC4: Group creation validation preventing invalid selections (isolated nodes, etc.)
+**Given** user attempts to group nodes  
+**When** selection contains invalid combinations  
+**Then** validation prevents grouping and shows appropriate error message
+
+### AC5: Automatic group naming with user override option in creation dialog
+**Given** user creates a group  
+**When** group creation dialog appears  
+**Then** default name is generated with option for user to customize
+
+## Tasks / Subtasks
+
+### Implementation Tasks
+- [ ] **Task 1**: Extend existing context menu system for group operations (AC: 2)
+  - [ ] Subtask 1.1: Add "Group Selected" option to NodeEditorView.show_context_menu()
+  - [ ] Subtask 1.2: Implement group validation logic for context menu enabling
+  - [ ] Subtask 1.3: Connect context menu action to group creation workflow
+  - [ ] Subtask 1.4: Add proper icon and styling for group menu option
+
+- [ ] **Task 2**: Implement keyboard shortcut system (AC: 3)
+  - [ ] Subtask 2.1: Add Ctrl+G handling to NodeGraph.keyPressEvent()
+  - [ ] Subtask 2.2: Integrate with existing keyboard shortcut patterns
+  - [ ] Subtask 2.3: Ensure proper event propagation and handling
+  - [ ] Subtask 2.4: Add shortcut documentation and tooltips
+
+- [ ] **Task 3**: Create Group class and basic data model (AC: 1, 4, 5)
+  - [ ] Subtask 3.1: Design Group class inheriting from QGraphicsItem
+  - [ ] Subtask 3.2: Implement group data structure with member nodes tracking
+  - [ ] Subtask 3.3: Add serialization/deserialization for group persistence
+  - [ ] Subtask 3.4: Integrate with existing node identification system (UUID)
+
+- [ ] **Task 4**: Implement group creation validation (AC: 4)
+  - [ ] Subtask 4.1: Create validation rules for groupable selections
+  - [ ] Subtask 4.2: Check for minimum node count and connectivity requirements
+  - [ ] Subtask 4.3: Validate node types and prevent invalid combinations
+  - [ ] Subtask 4.4: Implement user-friendly error messaging
+
+- [ ] **Task 5**: Create Group Creation Dialog (AC: 5)
+  - [ ] Subtask 5.1: Design GroupCreationDialog class inheriting from QDialog
+  - [ ] Subtask 5.2: Implement automatic name generation based on selected nodes
+  - [ ] Subtask 5.3: Add user input validation and name override functionality
+  - [ ] Subtask 5.4: Integrate with existing dialog patterns and styling
+
+- [ ] **Task 6**: Implement CreateGroupCommand for undo/redo (AC: 1-5)
+  - [ ] Subtask 6.1: Create CreateGroupCommand following established command pattern
+  - [ ] Subtask 6.2: Implement proper state preservation for undo operations
+  - [ ] Subtask 6.3: Handle group creation, node membership, and state transitions
+  - [ ] Subtask 6.4: Integrate with existing command history system
+
+### Testing Tasks
+- [ ] **Task 7**: Create unit tests for group functionality (AC: 1, 4, 5)
+  - [ ] Test Group class creation and data management
+  - [ ] Test group validation logic with various node combinations
+  - [ ] Test automatic naming generation and customization
+  - [ ] Test serialization and persistence of group data
+
+- [ ] **Task 8**: Create integration tests for UI interactions (AC: 2, 3)
+  - [ ] Test context menu integration and option enabling/disabling
+  - [ ] Test keyboard shortcut handling and event propagation
+  - [ ] Test dialog workflow and user input validation
+  - [ ] Test command pattern integration and undo/redo functionality
+
+- [ ] **Task 9**: Add user workflow tests (AC: 1-5)
+  - [ ] Test complete group creation workflow from selection to completion
+  - [ ] Test error handling and user feedback for invalid selections
+  - [ ] Test integration with existing selection and clipboard systems
+  - [ ] Test undo/redo behavior for group operations
+
+### Documentation Tasks
+- [ ] **Task 10**: Update user documentation
+  - [ ] Document group creation workflow and keyboard shortcuts
+  - [ ] Add group creation tutorial and best practices
+  - [ ] Update UI documentation for new context menu options
+
+## Dev Notes
+
+### Previous Story Insights
+Key learnings from Epic 2 (Undo/Redo System):
+- Command pattern integration works smoothly with existing infrastructure
+- PySide6 signal/slot connections require careful setup and proper disconnection
+- Real-time UI updates need proper event handling and state synchronization
+- Context menu patterns are established in NodeEditorView.show_context_menu()
+- Testing GUI components requires careful mocking and QTest framework consideration
+[Source: docs/stories/2.4.story.md#previous-story-insights]
+
+### Technical Implementation Details
+
+#### Existing Selection Infrastructure
+- **Selection System**: NodeGraph.selectedItems() provides multi-selection capability
+- **Copy System**: copy_selected() method shows pattern for working with selected nodes
+- **Key Handling**: keyPressEvent() in NodeGraph handles Ctrl+Z/Y shortcuts, pattern for Ctrl+G
+- **Context Menu**: NodeEditorView.show_context_menu() provides right-click menu framework
+[Source: src/core/node_graph.py lines 161-195, 105-159; src/ui/editor/node_editor_view.py lines 54-83]
+
+#### Command System Integration Points
+- **Command History**: CommandHistory class in `src/commands/command_history.py` manages undoable operations
+- **NodeGraph Integration**: NodeGraph.command_history provides access to command operations
+- **Existing Commands**: DeleteNodeCommand, CompositeCommand patterns established
+- **State Methods**: execute_command(), undo_last_command(), redo_last_command() available
+[Source: src/commands/command_history.py, src/core/node_graph.py lines 54-91]
+
+#### File Locations & Structure
+- **Main Graph**: `src/core/node_graph.py` - Add group creation and management methods
+- **View System**: `src/ui/editor/node_editor_view.py` - Extend context menu for group options
+- **New Group Class**: `src/core/group.py` - Create new group data model and QGraphicsItem
+- **New Dialog**: `src/ui/dialogs/group_creation_dialog.py` - Create group configuration dialog
+- **New Command**: `src/commands/create_group_command.py` - Implement undoable group creation
+- **Test Files**: `tests/test_group_system.py` (new), extend existing command tests
+[Source: docs/architecture/source-tree.md#user-interface, docs/architecture/source-tree.md#core-application-files]
+
+#### Data Models and Integration
+- **Node Objects**: Node class with UUID-based identification system
+- **Selection Access**: selectedItems() returns list of QGraphicsItem objects for processing
+- **UUID System**: Existing node.uuid pattern for unique identification
+- **Serialization**: Existing node.serialize() pattern for data persistence
+[Source: src/core/node.py, src/core/node_graph.py lines 161-195]
+
+#### Context Menu Architecture Patterns
+- **Menu Creation**: QMenu and QAction patterns established in show_context_menu()
+- **Action Enabling**: Dynamic enabling/disabling based on selection state
+- **Icon Integration**: Font Awesome icon creation via create_fa_icon() function
+- **Signal Connections**: Action triggered signals connected to methods
+[Source: src/ui/editor/node_editor_view.py lines 54-83, src/ui/utils/ui_utils.py]
+
+#### Dialog Architecture Patterns
+- **Base Pattern**: Inherit from QDialog (established pattern in project)
+- **Existing Examples**: SettingsDialog, EnvironmentManagerDialog, GraphPropertiesDialog, UndoHistoryDialog
+- **Layout**: Use QVBoxLayout and QHBoxLayout for responsive design
+- **Integration**: Parent to main window for proper modal behavior
+- **Resource Management**: Proper Qt object parenting for automatic cleanup
+[Source: docs/architecture/coding-standards.md#widget-structure, docs/architecture/source-tree.md#user-interface]
+
+#### Group Data Structure Requirements
+- **Member Tracking**: List of member node UUIDs for group membership
+- **Metadata**: Group name, description, creation timestamp
+- **State Management**: Expanded/collapsed state, position, size
+- **Serialization**: JSON-compatible format for file persistence
+- **Validation**: Rules for valid group compositions and member types
+
+#### Performance Considerations
+- **Selection Performance**: Existing selectedItems() optimized for large graphs
+- **Memory Usage**: Group metadata lightweight, references not copies of nodes
+- **Response Time**: Group creation must remain under 100ms for responsiveness (NFR1)
+- **Large Selections**: Efficient handling of 50+ node selections
+[Source: docs/prd.md#non-functional-requirements]
+
+#### Technical Constraints
+- **Windows Platform**: Use Windows-compatible commands and paths, no Unicode characters
+- **PySide6 Framework**: Follow established Qt patterns and QGraphicsItem architecture
+- **Existing Patterns**: Leverage established command pattern and UUID systems
+- **Error Handling**: Graceful handling of invalid selections with user feedback
+[Source: docs/architecture/coding-standards.md#prohibited-practices, CLAUDE.md]
+
+### Testing
+
+#### Test File Locations
+- **Unit Tests**: `tests/test_group_system.py` (new) - Group class and validation logic
+- **Integration Tests**: Extend existing `tests/test_command_system.py` for group commands
+- **UI Tests**: `tests/test_group_ui_integration.py` (new) - Context menu and dialog testing
+- **Test Naming**: Follow `test_{behavior}_when_{condition}` pattern
+[Source: docs/architecture/coding-standards.md#testing-standards]
+
+#### Testing Framework and Patterns
+- **Framework**: Python unittest (established pattern in project)
+- **Test Runner**: Custom PySide6 GUI test runner for interactive testing
+- **Timeout**: All tests must complete within 10 seconds maximum
+- **Coverage**: Focus on group creation logic, selection validation, and command integration
+[Source: docs/architecture/tech-stack.md#testing-framework, CLAUDE.md#testing]
+
+#### Specific Testing Requirements
+- Test group creation with various node selection combinations
+- Test validation logic for invalid selections and edge cases
+- Test context menu integration and proper enabling/disabling
+- Test keyboard shortcut handling and event propagation
+- Test dialog workflow, input validation, and user feedback
+- Test command pattern integration and undo/redo functionality
+- Test group data serialization and persistence
+- Test integration with existing selection and clipboard systems
+
+## Change Log
+
+| Date       | Version | Description                 | Author    |
+| ---------- | ------- | --------------------------- | --------- |
+| 2025-01-20 | 1.0     | Initial story creation based on PRD Epic 3 | Bob (SM) |

package.json

@@ -0,0 +1 @@
+{}