124 lines
4.0 KiB
Markdown
124 lines
4.0 KiB
Markdown
# Design Document
|
|
|
|
## Overview
|
|
|
|
This design establishes consistent detail panel behavior across all entity browsers (shots, assets, tasks) in the VFX Project Management System. The design ensures users have a unified experience when working with detail panels regardless of the entity type.
|
|
|
|
## Architecture
|
|
|
|
The detail panel system uses a consistent state management pattern across all entity browsers:
|
|
|
|
- **Auto-Enable State**: Controls whether panels automatically show on entity selection
|
|
- **Manual Visibility State**: Controls manual panel visibility via keyboard shortcuts
|
|
- **Combined Logic**: Panel shows when either auto-enabled with selection OR manually visible
|
|
|
|
## Components and Interfaces
|
|
|
|
### State Variables (Per Browser)
|
|
```typescript
|
|
// Auto-enable toggle state
|
|
const isDetailPanelEnabled = ref(true)
|
|
|
|
// Manual visibility control
|
|
const isDetailPanelVisible = ref(false)
|
|
|
|
// Selected entity
|
|
const selectedEntity = ref<Entity | null>(null)
|
|
```
|
|
|
|
### Panel Visibility Logic
|
|
```typescript
|
|
// Panel shows when:
|
|
// 1. Auto-enabled AND entity selected, OR
|
|
// 2. Manually shown
|
|
const showPanel = computed(() =>
|
|
selectedEntity.value && (isDetailPanelEnabled.value || isDetailPanelVisible.value)
|
|
)
|
|
```
|
|
|
|
### Keyboard Handler Interface
|
|
```typescript
|
|
interface KeyboardHandler {
|
|
handleKeyDown(event: KeyboardEvent): void
|
|
// Conditions:
|
|
// - 'i' key pressed
|
|
// - Entity selected
|
|
// - No dialogs open
|
|
// - Not typing in input fields
|
|
}
|
|
```
|
|
|
|
## Data Models
|
|
|
|
### Panel State Model
|
|
```typescript
|
|
interface DetailPanelState {
|
|
isEnabled: boolean // Auto-enable toggle
|
|
isVisible: boolean // Manual visibility
|
|
selectedEntity: Entity | null
|
|
}
|
|
```
|
|
|
|
### Entity Selection Model
|
|
```typescript
|
|
interface EntitySelection {
|
|
entity: Entity
|
|
preserveManualState: boolean // Don't reset manual visibility
|
|
}
|
|
```
|
|
|
|
## Correctness Properties
|
|
|
|
*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
|
|
|
|
### Property 1: Manual Panel Persistence
|
|
*For any* entity browser with manually opened detail panel, selecting different entities should keep the panel visible and update content
|
|
**Validates: Requirements 2.1, 2.2, 2.3**
|
|
|
|
### Property 2: Keyboard Toggle Consistency
|
|
*For any* entity browser, pressing 'i' key with selected entity should toggle panel visibility consistently
|
|
**Validates: Requirements 4.1**
|
|
|
|
### Property 3: Auto-Enable Independence
|
|
*For any* combination of auto-enable and manual states, the panel visibility should follow OR logic (show if either condition is true)
|
|
**Validates: Requirements 3.5**
|
|
|
|
### Property 4: Input Field Protection
|
|
*For any* keyboard event while focused on input fields, the 'i' key should not trigger panel toggle
|
|
**Validates: Requirements 4.2**
|
|
|
|
### Property 5: Selection State Preservation
|
|
*For any* entity selection while panel is manually visible, the manual visibility state should be preserved
|
|
**Validates: Requirements 2.1**
|
|
|
|
## Error Handling
|
|
|
|
### Invalid States
|
|
- No entity selected + manual panel visible → Hide panel
|
|
- Dialog open + keyboard shortcut → Ignore shortcut
|
|
- Input field focused + keyboard shortcut → Ignore shortcut
|
|
|
|
### State Recovery
|
|
- Invalid combinations reset to safe defaults
|
|
- Manual state cleared when no entity selected
|
|
- Auto-enable state persists across sessions
|
|
|
|
## Testing Strategy
|
|
|
|
### Unit Testing
|
|
- Test individual state transitions
|
|
- Test keyboard event handling
|
|
- Test panel visibility logic
|
|
- Test edge cases (no selection, dialogs open)
|
|
|
|
### Property-Based Testing
|
|
- Generate random entity selections and verify panel behavior
|
|
- Test keyboard events with various application states
|
|
- Verify state consistency across browser types
|
|
- Test auto-enable/manual state combinations
|
|
|
|
### Integration Testing
|
|
- Test behavior across all entity browsers
|
|
- Test session persistence
|
|
- Test mobile vs desktop behavior
|
|
- Test with real user workflows |