LinkDesk/.kiro/specs/asset-browser-table-refactor/design.md

# Asset Browser Table Refactor Design Document

## Overview

This design refactors the Asset Browser table implementation to use TanStack Table, matching the architecture and behavior of the Shot Data Table. The refactor will improve performance, consistency, and maintainability while preserving all existing functionality.

## Architecture

### Current Architecture
- **AssetBrowser.vue**: Monolithic component with custom table implementation
- Manual table rendering using shadcn-vue Table components
- Custom row selection and sorting logic
- Direct DOM manipulation for some interactions

### Target Architecture
- **AssetBrowser.vue**: Container component managing state and data
- **AssetsDataTable.vue**: Dedicated table component using TanStack Table
- **columns.ts**: Column definitions with proper typing and behavior
- Composable-based state management for table interactions

## Components and Interfaces

### New Components

#### AssetsDataTable.vue
```typescript
interface Props {
  columns: ColumnDef<Asset>[]
  data: Asset[]
  sorting: SortingState
  columnVisibility: VisibilityState
  allTaskTypes: string[]
}

interface Emits {
  'update:sorting': [sorting: SortingState]
  'update:columnVisibility': [visibility: VisibilityState]
  'update:rowSelection': [selection: Record<string, boolean>]
  'row-click': [asset: Asset, event: MouseEvent]
  'selection-cleared': []
}
```

#### columns.ts
```typescript
interface AssetColumnMeta {
  projectId: number
  categories: Array<{ value: string; label: string; icon: any }>
  onEdit: (asset: Asset) => void
  onDelete: (asset: Asset) => void
  onViewTasks: (asset: Asset) => void
  onTaskStatusUpdated: (assetId: number, taskType: string, newStatus: TaskStatus) => void
  onBulkTaskStatusChange?: (taskType: string, status: TaskStatus) => void
  getSelectedCount?: () => number
  getAllStatusOptions?: () => Array<{ id: string; name: string; color?: string; is_system?: boolean }>
}

export const createAssetColumns = (
  allTaskTypes: string[],
  meta: AssetColumnMeta
): ColumnDef<Asset>[] => { ... }
```

### Modified Components

#### AssetBrowser.vue Changes
- Remove custom table implementation
- Add TanStack Table state management
- Integrate AssetsDataTable component
- Maintain existing filtering and search logic
- Preserve detail panel integration

## Data Models

### TanStack Table State
```typescript
// Table state management
const sorting = ref<SortingState>([])
const columnVisibility = ref<VisibilityState>({})
const rowSelection = ref<Record<string, boolean>>({})

// Column visibility defaults
const defaultColumnVisibility = {
  name: true,
  category: true,
  status: true,
  thumbnail: false,
  modeling: true,
  surfacing: true,
  rigging: true,
  description: true,
  updatedAt: true
}
```

### Asset Column Structure
```typescript
// Standard columns
- select: Checkbox column for row selection
- thumbnail: Asset thumbnail display
- name: Asset name with category icon
- category: Asset category badge
- status: Asset status badge
- description: Asset description text
- updatedAt: Last updated timestamp

// Dynamic task columns (based on project configuration)
- modeling: Editable task status
- surfacing: Editable task status  
- rigging: Editable task status (conditional)
- [customTaskType]: Dynamic custom task columns

// Actions column
- actions: Dropdown menu with edit/delete/view tasks
```

## 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: Table Behavior Consistency
*For any* table interaction (row selection, column sorting, bulk operations, dropdown actions), the asset table should behave identically to the shot table implementation
**Validates: Requirements 1.2, 1.3, 1.4, 2.4, 4.2**

### Property 2: Required Column Presence
*For any* asset table rendering, all required asset-specific columns (name, category, status, task statuses, description, updated date) should be present and functional
**Validates: Requirements 3.1**

### Property 3: Column Visibility Persistence
*For any* column visibility change, the settings should be persisted to session storage and restored correctly on component mount
**Validates: Requirements 2.5, 5.1**

### Property 4: Bulk Operations Completeness
*For any* bulk operation scenario (multiple selection, status changes, UI feedback), the system should handle all states correctly including empty selection, optimistic updates, and completion messages
**Validates: Requirements 4.1, 4.3, 4.4, 4.5**

### Property 5: Feature Preservation Round Trip
*For any* existing asset browser feature (task status editing, thumbnails, filtering, detail panel, view modes), the functionality should work identically before and after the refactor
**Validates: Requirements 3.2, 3.3, 3.4, 3.5, 5.2, 5.3, 5.4**

## Error Handling

### Table Rendering Errors
- Graceful fallback to loading state if column creation fails
- Error boundaries around table component to prevent crashes
- Validation of column definitions before rendering

### Selection State Errors
- Clear invalid selections on data changes
- Handle edge cases in range selection (empty data, filtered results)
- Prevent selection of non-existent rows

### Bulk Operation Errors
- Show error messages for failed bulk operations
- Revert optimistic updates on API failures
- Disable bulk controls during operations

## Testing Strategy

### Unit Tests
- Column definition creation with various task type configurations
- Row selection logic with different modifier key combinations
- Column visibility state management and persistence
- Bulk operation state transitions

### Property-Based Tests
- **Property 1**: Table behavior consistency across different interaction patterns and datasets
- **Property 2**: Required column presence verification across different project configurations
- **Property 3**: Column visibility persistence round-trip testing with various visibility states
- **Property 4**: Bulk operations completeness testing across different selection scenarios
- **Property 5**: Feature preservation verification through before/after comparison testing

### Integration Tests
- Asset table integration with detail panel
- Filter and search integration with new table structure
- Task status editing integration with backend services
- Bulk operations integration with API endpoints

The testing approach will use **fast-check** for property-based testing, with each property test configured to run a minimum of 100 iterations to ensure comprehensive coverage of edge cases and state combinations.