Fix/wait-element-sth

[CSWinnall]

Overview

This PR introduces three major enhancements to KTL: a new waitElement utility for robust DOM waiting, improvements to the _hsv (hideShowView) keyword, and a comprehensive refactoring of the checkbox system with new callback capabilities.

---

1. New waitElement Function

Features

• Modern Promise-based API for waiting on DOM elements
• Multiple selector support - wait for any of several selectors
• Flexible timeout configuration - set custom timeouts or use defaults
• Configurable error handling - choose between silent fail, warning, or error
• Outcome reporting - returns which selector was found (if multiple provided)
• Retry logic - configurable scan speed for performance tuning

Usage Examples

// Simple wait with default timeout (5 seconds)
await ktl.core.waitElement('#myElement');

// Wait for multiple possible selectors
const result = await ktl.core.waitElement(['#option1', '#option2'], { timeout: 10000 });
console.log('Found:', result.selector); // Shows which one was found

// Custom error handling
await ktl.core.waitElement('.required', { 
    outcome: ktl.const.WAIT_SEL_LOG_ERROR,
    timeout: 3000 
});

// Silent fail for optional elements
const found = await ktl.core.waitElement('.optional', { outcome: ktl.const.WAIT_SEL_IGNORE });

Benefits

• Cleaner async/await syntax vs callback-based waitSelector
• Better error context and debugging
• More flexible for modern JavaScript patterns
• Easier to compose with other async operations

---

3. Checkbox System Refactoring & Enhancements

Major Changes

Consolidated API

• Removed internal _addCheckboxesToTableInternal function
• Enhanced addCheckboxesToTable to be the single public function
• Accepts both legacy boolean parameter AND modern options object
• Backward compatible with all existing code

New Callback System

1. onRowChange callback - fires when individual checkboxes are clicked

   • Parameters: (viewId, checkbox, row, checkedRows)
   • Provides the clicked checkbox element
   • Provides the parent row element
   • Provides array of ALL currently checked rows

2. Enhanced onMasterChange callback - now includes checked rows

   • Parameters: (viewId, isChecked, checkedRows)
   • Provides all affected rows (all rows when checked, empty array when unchecked)

Shift-Click Support

• Range selection - click one checkbox, shift+click another to select/deselect range
• Works seamlessly with callback system
• Integrated across all checkbox implementations

Usage Examples

// Legacy style (still works)
ktl.views.addCheckboxesToTable('view_123', true);

// Modern style with callbacks
ktl.views.addCheckboxesToTable('view_123', {
    addMasterCheckbox: true,
    addColumnCheckboxes: true,
    isBulkOps: true,
    onMasterChange: (viewId, isChecked, checkedRows) => {
        console.log('Master checkbox toggled:', isChecked);
        console.log('Total rows:', checkedRows.length);
        // Process all rows at once
    },
    onRowChange: (viewId, checkbox, row, checkedRows) => {
        console.log('Row toggled:', row.id);
        console.log('Total checked:', checkedRows.length);
        // React to individual selections
        // checkedRows gives you full context of current state
    }
});

Bug Fixes

• Fixed duplicate condition check for ktlColumnCheckbox (line 27916)
• Improved class name consistency across checkbox types

Technical Improvements

• Pure vanilla JavaScript - no jQuery in new checkbox creation code
• Unified class naming - ktlMasterCheckbox, ktlRowCheckbox, ktlColumnCheckbox, ktlBulkOpsCheckbox
• Backward compatibility - maintains legacy class names (masterSelector, bulkEditCb)
• Better code organization - single function handles all checkbox scenarios
• Comprehensive documentation - JSDoc with examples for all options

---

Testing Checklist

• waitElement with single selector
• waitElement with multiple selectors
• waitElement timeout behavior
• waitElement error handling modes
• _hsv keyword hide/show toggling
• Legacy addCheckboxesToTable(viewId, true) still works
• New options-based addCheckboxesToTable works
• onRowChange callback fires correctly
• onMasterChange callback receives checked rows
• Shift-click range selection works
• Bulk operations checkboxes work with callbacks
• Backward compatibility maintained

---

Migration Notes

No breaking changes - all existing code continues to work. New features are opt-in through the options parameter.

To use new callbacks:

// Before (still works)
ktl.views.addCheckboxesToTable('view_123');

// After (opt-in to new features)
ktl.views.addCheckboxesToTable('view_123', {
    onRowChange: (viewId, checkbox, row, checkedRows) => {
        // Your logic here
    }
});