CTriStateChecked Component

Overview

CTriStateChecked is a modern React functional component that provides a tri-state checkbox interface. It cycles through three distinct states: disabled → unchecked → checked. This component has been completely modernized with React hooks and follows current best practices.

🆕 Recent Updates (v1.0.5)

Major Improvements

• ✅ Modern Architecture: Converted from class component to functional component with React hooks
• ✅ Fixed State Management: Eliminated direct state mutations, now uses proper useState() and useEffect()
• ✅ Accurate Event Callbacks: onChange now receives correct current state values instead of stale data
• ✅ PropTypes Validation: Added runtime type checking for all props
• ✅ Better Accessibility: Improved label association and keyboard navigation
• ✅ Modern CSS: Replaced undefined CSS classes with Bootstrap 5 standards
• ✅ Comprehensive Examples: Added working examples and HTML demo

Fixed Issues

• State mutation bugs that could cause React warnings
• Incorrect callback parameters in onChange events
• Missing CSS class definitions
• Inconsistent prop naming conventions

Features

• Tri-State Functionality: Seamlessly cycles through disabled, unchecked, and checked states
• Modern React Architecture: Built with functional components and hooks (useState, useEffect, useRef)
• Runtime Validation: PropTypes for type safety and better debugging
• Event Handling: Provides accurate onChange callbacks with current state values
• Customizable Styling: Supports Bootstrap 5 classes and custom CSS
• Accessible: Proper label association and keyboard navigation support

🚀 Quick Start

Option 1: HTML Demo (Fastest)

Open the included demo file in your browser to see the component in action:

# Simply open this file in any browser
open demo.html
# or double-click the file in your file manager

Option 2: React Development

# Install dependencies
npm install

# Start development server
npm start

# Or run the example specifically
npm run example

Option 3: Build for Production

npm run build

Installation

npm install tri_state_combo_react

Dependencies

• React 16.8+ (for hooks support)
• PropTypes 15.8+ (included as dependency)
• Bootstrap 5+ (optional, for default styling)

📖 Usage Guide

Basic Usage

import React from 'react';
import CTriStateChecked from 'tri_state_combo_react';

const MyComponent = () => {
    const handleChange = (is_enabled, is_checked) => {
        console.log('Enabled:', is_enabled, 'Checked:', is_checked);
        // is_enabled: boolean - whether checkbox is enabled
        // is_checked: boolean - whether checkbox is checked
    };

    return (
        <CTriStateChecked 
            txtLabel="Feature Toggle"
            disabled={false}    // Initial state: enabled
            checked={true}      // Initial state: checked
            onChange={handleChange}
        />
    );
};

Real-World Example

import React, { useState } from 'react';
import CTriStateChecked from 'tri_state_combo_react';

const SettingsPanel = () => {
    const [logs, setLogs] = useState([]);
    
    const logChange = (feature, is_enabled, is_checked) => {
        const message = `${feature}: enabled=${is_enabled}, checked=${is_checked}`;
        setLogs(prev => [...prev, `${new Date().toLocaleTimeString()}: ${message}`]);
    };

    return (
        <div className="container">
            <h4>Application Settings</h4>
            
            <CTriStateChecked 
                txtLabel="Server Communication"
                disabled={false}
                checked={true}
                onChange={(enabled, checked) => logChange('Server Comm', enabled, checked)}
                className="mb-2"
            />
            
            <CTriStateChecked 
                txtLabel="Auto Save Feature"
                disabled={false}
                checked={false}
                onChange={(enabled, checked) => logChange('Auto Save', enabled, checked)}
                className="mb-2"
            />
            
            <CTriStateChecked 
                txtLabel="Debug Mode"
                disabled={true}  // Start disabled
                checked={false}
                onChange={(enabled, checked) => logChange('Debug Mode', enabled, checked)}
                className="mb-2"
            />
            
            {/* Display logs */}
            <div className="mt-3">
                <h5>Event Log:</h5>
                <div style={{ 
                    height: '200px', 
                    overflowY: 'auto', 
                    border: '1px solid #ccc',
                    padding: '10px',
                    fontFamily: 'monospace',
                    fontSize: '12px'
                }}>
                    {logs.map((log, index) => (
                        <div key={index}>{log}</div>
                    ))}
                </div>
            </div>
        </div>
    );
};

Custom Styling

// Override default Bootstrap classes
<CTriStateChecked 
    txtLabel="Custom Styled Component"
    className="my-tri-state custom-class"
    onChange={handleChange}
/>

// CSS for custom styling
.my-tri-state {
    background-color: #f8f9fa;
    padding: 10px;
    border-radius: 5px;
}

.my-tri-state .form-check-input {
    transform: scale(1.2);
}

📋 Props Reference

| Prop Name | Type | Default | Required | Description | |-----------|------|---------|----------|-------------| | txtLabel | string | '' | No | Text displayed next to the checkbox | | disabled | boolean | false | No | Initial disabled state | | checked | boolean | false | No | Initial checked state | | className | string | '' | No | Additional CSS classes | | onChange | function | null | No | Callback for state changes |

onChange Callback

function onChange(is_enabled, is_checked) {
    // is_enabled: boolean - true if checkbox is enabled (states 1 & 2)
    // is_checked: boolean - true if checkbox is checked (state 2 only)
}

🔄 State Cycle

The component cycles through these states when clicked:

1. State 0 - Disabled:

   • checkbox.disabled = true
   • checkbox.checked = false
   • Callback: onChange(false, false)

2. State 1 - Unchecked:

   • checkbox.disabled = false
   • checkbox.checked = false
   • Callback: onChange(true, false)

3. State 2 - Checked:

   • checkbox.disabled = false
   • checkbox.checked = true
   • Callback: onChange(true, true)

🎨 CSS Classes Used

The component uses these Bootstrap 5 classes by default:

• d-flex: Flexbox layout container
• align-items-center: Vertical alignment
• me-2: Right margin for label
• flex-grow-1: Label takes available space
• form-check-input: Bootstrap checkbox styling

🛠 Development

Available Scripts

npm run build      # Build component for distribution
npm run start      # Start React development server
npm run example    # Run the example application
npm run dev        # Development mode with hot reload

Project Structure

tri_state_combo_react/
├── src/
│   ├── index.ts                    # Main export file
│   └── jsc_mctl_tri_state_check.jsx # Component implementation
├── example.js                      # React example application
├── demo.html                       # Static HTML demo
├── package.json                    # Dependencies and scripts
└── README.md                       # This file

🌐 Browser Support

• Chrome 60+
• Firefox 60+
• Safari 12+
• Edge 79+

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📋 Changelog

v1.0.5 (Current)

• Breaking Changes: Component modernized to functional component
• Fixed: State mutation issues that caused React warnings
• Fixed: Incorrect onChange callback parameters
• Added: PropTypes validation for all props
• Added: Comprehensive examples and HTML demo
• Improved: Accessibility and keyboard navigation
• Updated: CSS classes to use Bootstrap 5 standards
• Updated: Documentation with real-world examples

v1.0.0

• Initial release with class component implementation

🔧 Troubleshooting

Common Issues

Q: Component doesn't update when props change A: Ensure you're using React 16.8+ for hooks support. The component now uses useEffect to respond to prop changes.

Q: onChange callback shows wrong values A: This was fixed in v1.0.5. The callback now receives the actual current state instead of previous state.

Q: CSS classes not working A: The component now uses standard Bootstrap 5 classes. Include Bootstrap in your project or provide custom CSS.

Q: TypeScript errors A: The component includes PropTypes for runtime validation. For TypeScript support, create type definitions or use the included .tsx examples.

Getting Help

• Check the demo.html file for visual examples
• Review the example.js file for React implementation
• Open an issue on GitHub for bug reports
• Check the changelog for recent fixes and updates