6.6 KiB

Raw Blame History

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

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

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

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

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

6.6 KiB Raw Blame History