handle-modus-checkbox-value-bug

Handle Modus Checkbox Value Bug

Apply the critical value inversion workaround for ModusWcCheckbox components.

Critical Bug

The ModusWcCheckbox web component has a value inversion bug where the value property returns the opposite of the actual checked state:

• When checkbox is checked: target.value returns false
• When checkbox is unchecked: target.value returns true

This is the opposite of what developers expect.

When to Use

Use this skill when:

• Implementing checkbox functionality with ModusCheckbox
• Fixing checkbox-related bugs
• Handling checkbox value changes
• Creating forms with checkboxes

Reference Implementation

See src/components/ModusCheckbox.tsx:116-130 for the complete workaround implementation.

The Fix

Always invert the value when reading from checkbox events:

const handleValueChange = (event: Event) => {
  const customEvent = event as CustomEvent<InputEvent>;
  
  // 🚨 CRITICAL: Handle the value inversion bug
  const rawValue = (customEvent.target as HTMLModusWcCheckboxElement).value;
  const actualValue = !rawValue; // ✅ CORRECT: Invert the value
  
  // Use actualValue for your logic
  setChecked(actualValue);
};

Complete Pattern

import { useEffect, useRef } from "react";
import { ModusWcCheckbox } from "@trimble-oss/moduswebcomponents-react";

export default function ModusCheckbox({
  value = false,
  onValueChange,
}: {
  value?: boolean;
  onValueChange?: (event: CustomEvent<boolean>) => void;
}) {
  const checkboxRef = useRef<HTMLModusWcCheckboxElement>(null);

  useEffect(() => {
    const checkbox = checkboxRef.current;
    if (!checkbox) return;

    const handleValueChange = (event: Event) => {
      const customEvent = event as CustomEvent<InputEvent>;
      
      // 🚨 CRITICAL BUG WORKAROUND: The ModusWcCheckbox component has a value
      // inversion bug where the `value` property returns the opposite of the
      // actual checked state. This function corrects this by inverting the
      // raw value before passing it to the parent component.
      const rawValue = (customEvent.target as HTMLModusWcCheckboxElement).value;
      const actualValue = !rawValue; // ✅ CORRECT: Invert the value

      // Create a new event with the corrected value
      const correctedEvent = new CustomEvent("valueChange", {
        detail: actualValue,
        bubbles: true,
        cancelable: true,
      });

      onValueChange?.(correctedEvent);
    };

    if (onValueChange) {
      checkbox.addEventListener("inputChange", handleValueChange);
    }

    return () => {
      if (onValueChange) {
        checkbox.removeEventListener("inputChange", handleValueChange);
      }
    };
  }, [onValueChange]);

  return (
    <ModusWcCheckbox
      ref={checkboxRef}
      value={value}
    />
  );
}