4.0 KiB

Raw Permalink Blame History

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)

// 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

// 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

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

interface DetailPanelState {
  isEnabled: boolean      // Auto-enable toggle
  isVisible: boolean      // Manual visibility
  selectedEntity: Entity | null
}

Entity Selection Model

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

4.0 KiB Raw Permalink Blame History