inventory/docs/validate-table-changes.md

Current Issues to Address

4. Validation isn't happening beyond checking if a cell is required or not - needs to respect rules in import.tsx
   • Red cell outline if cell is required and it's empty
   • Red outline + alert circle icon with tooltip if cell is NOT empty and isn't valid
5. Description column needs to have an expanded view of some sort, maybe a popover to allow for easier editing
   • Don't distort table to make it happen
6. The template select cell is expanding, needs to be fixed size and truncate
7. When you enter a value in 2+ cells before validation finishes, contents from all edited cells get erased when validation finishes
8. Import dialog state not fully reset when closing? (validate data step appears scrolled to the middle of the table where I left it)
9. UPC column doesn't need to show loading state when Item Number is being processed, only show on item number column
10. Copy down needs to show a loading state on the cells that it will copy to
11. Shipping restrictions/tax category should default to ID 0 if we didn't get it elsewhere

Do NOT change or edit

• Anything related to AI validation
• Anything about how templates or UPC validation work (only focus on specific issues described above)
• Anything outside of the ValidationStepNew folder

Issues already fixed - do not work on these

✅FIXED 1. The red row background should go away when all cells in the row are valid and all required cells are populated ✅FIXED 2. Columns alignment with header is slightly off, gets worse the further right you go ✅FIXED 3. The copy down button is in the way of the validation error icon and the select open trigger - all three need to be in unique locations ✅FIXED 6. Need to ensure all cell's contents don't overflow the input (truncate). COO does this currently, probably more ✅FIXED 13. Header row should be sticky (both up/down and left/right) ✅FIXED 14. Need a way to scroll around table if user doesn't have mouse wheel for left/right

---

Validation Step Components Overview

Core Components

ValidationContainer

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/components/ValidationContainer.tsx

• Main wrapper component for the validation step
• Manages global state and coordinates between subcomponents
• Handles navigation events (next, back)
• Manages template application and validation state
• Coordinates UPC validation and product line loading
• Manages row selection and filtering
• Contains cache management for UPC validation results
• Maintains item number references separate from main data

ValidationTable

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/components/ValidationTable.tsx

• Handles data display and column configuration
• Uses TanStack Table for core functionality
• Features:
  • Sticky header (both vertical and horizontal) - currently doesn't work properly
  • Row selection with checkboxes
  • Template selection column
  • Dynamic column widths based on field types - specified in import.tsx component
  • Copy down functionality for cell values
  • Error highlighting for rows and cells
  • Loading states for cells being validated

ValidationCell

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/components/ValidationCell.tsx

• Base cell component that renders different cell types based on field configuration
• Handles error display with tooltips
• Manages copy down button visibility
• Supports loading states during validation
• Cell Types:
  1. InputCell: For single-value text input
  2. SelectCell: For dropdown selection
  3. MultiInputCell: For multiple value inputs
  4. Template selection cells with SearchableTemplateSelect component

SearchableTemplateSelect

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/components/SearchableTemplateSelect.tsx

• Advanced template selection component with search functionality
• Features:
  • Real-time search filtering of templates
  • Customizable display text for templates
  • Support for default brand selection
  • Accessible popover interface
  • Keyboard navigation support
  • Custom styling through className props
  • Scroll event handling for nested scrollable areas

TemplateManager

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/components/TemplateManager.tsx

• Comprehensive template management interface
• Features:
  • Template selection with search functionality
  • Save template dialog with name and type inputs
  • Batch template application to selected rows
  • Template count tracking
  • Toast notifications for user feedback
  • Dialog-based interface for template operations

AiValidationDialogs

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/components/AiValidationDialogs.tsx

• Manages AI-assisted validation dialogs and interactions

SaveTemplateDialog

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/components/SaveTemplateDialog.tsx

• Dialog component for saving new templates

Cell Components

InputCell

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/components/cells/InputCell.tsx

• Handles single value text input
• Features:
  • Inline/edit mode switching
  • Multiline support
  • Price formatting
  • Error state display
  • Loading state during validation
  • Width constraints
  • Automated cleanPriceFields processing for "$" formatting

SelectCell

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/components/cells/SelectCell.tsx

• Handles dropdown selection
• Features:
  • Searchable dropdown
  • Custom option rendering
  • Error state display
  • Loading state during validation
  • Width constraints
  • Disabled state support
  • Deferred search query handling for performance

MultiInputCell

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/components/cells/MultiInputCell.tsx

• Handles multiple value inputs
• Features:
  • Comma-separated input support
  • Multi-select dropdown for predefined options
  • Custom separators
  • Badge display for selected count
  • Truncation for long values
  • Width constraints
  • Price formatting support
  • Internal state management to avoid excessive re-renders

Validation System

useValidation Hook

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/hooks/useValidation.tsx

• Provides core validation logic
• Validates at multiple levels:
  1. Field-level validation (required, regex, unique)
  2. Row-level validation (supplier, company fields)
  3. Table-level validation
  4. Custom validation hooks support
• Error object structure includes message, level, and source properties
• Handles debounced validation updates to avoid UI freezing

useAiValidation Hook

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/hooks/useAiValidation.tsx

• Manages AI-assisted validation logic and state
• Features:
  • Tracks detailed changes per product
  • Manages validation progress with estimated completion time
  • Handles warnings and change suggestions
  • Supports diff generation for changes
  • Progress tracking with step indicators
  • Prompt management for AI interactions
  • Timer management for long-running operations

useTemplates Hook

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/hooks/useTemplates.tsx

• Comprehensive template management system
• Features:
  • Template CRUD operations
  • Template application logic
  • Default value handling
  • Template search and filtering
  • Batch template operations
  • Template validation

useUpcValidation Hook

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/hooks/useUpcValidation.tsx

• Dedicated UPC validation management
• Features:
  • UPC format validation
  • Supplier data validation
  • Cache management for validation results
  • Batch processing of UPC validations
  • Item number generation logic
  • Loading state management

useFilters Hook

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/hooks/useFilters.tsx

• Advanced filtering system for table data
• Features:
  • Multiple filter criteria support
  • Dynamic filter updates
  • Filter persistence
  • Filter combination logic
  • Performance optimized filtering

useValidationState Hook

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/hooks/useValidationState.tsx

• Manages global validation state
• Handles:
  • Data updates
  • Template management
  • Error tracking using Map objects
  • Row selection
  • Filtering
  • UPC validation with caching to prevent duplicate API calls
  • Product line loading
  • Batch processing of updates
  • Default value application for tax_cat and ship_restrictions (defaulting to "0")
  • Price field auto-formatting to remove "$" symbols

Utility Files

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/utils/validationUtils.ts

• Core validation utility functions
• Includes:
  • Field validation logic
  • Error message formatting
  • Validation rule processing
  • Type checking utilities

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/utils/errorUtils.ts

• Error handling and formatting utilities
• Includes:
  • Error object creation
  • Error message formatting
  • Error source tracking
  • Error level management

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/utils/dataMutations.ts

• Data transformation and mutation utilities
• Includes:
  • Row data updates
  • Batch data processing
  • Data structure conversions
  • Change tracking

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/utils/validation-helper.js

• Helper functions for validation
• Includes:
  • Common validation patterns
  • Validation state management
  • Validation result processing

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/utils/upcValidation.ts

• UPC-specific validation utilities
• Includes:
  • UPC format checking
  • Checksum validation
  • Supplier data matching
  • Cache management

Types

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/types.ts

• Core type definitions for the validation step

Validation Types

1. Required field validation
2. Regex pattern validation
3. Unique value validation
4. Custom field validation
5. Row-level validation
6. Table-level validation

State Management

useValidationState Hook

inventory/src/lib/react-spreadsheet-import/src/steps/ValidationStepNew/hooks/useValidationState.tsx

• Manages global validation state
• Handles:
  • Data updates
  • Template management
  • Error tracking using Map objects
  • Row selection
  • Filtering
  • UPC validation with caching to prevent duplicate API calls
  • Product line loading
  • Batch processing of updates
  • Default value application for tax_cat and ship_restrictions (defaulting to "0")
  • Price field auto-formatting to remove "$" symbols

UPC Validation System

UPC Processing

• Validates UPCs against supplier data
• Cache system for UPC validation results
• Batch processing of UPC validation requests
• Auto-generation of item numbers based on UPC
• Special loading states for UPC/item number fields
• Separate state tracking to avoid unnecessary data structure updates

Template System

Template Management

• Supports saving and loading templates
• Template application to single/multiple rows
• Default template values
• Template search and filtering

Performance Optimizations

1. Memoized components to prevent unnecessary renders
2. Virtualized table for large datasets
3. Deferred value updates for search inputs
4. Efficient error state management
5. Optimized cell update handling