julianoczkowski/create-trimble-app/fix-modus-component-event-issues

Fix Modus Component Event Issues

Debug and fix common event handling problems with Modus web components in SolidJS.

When to Use

Use this skill when:

• Events aren't firing on Modus components
• Components aren't responding to user interactions
• Event handlers aren't being called
• You suspect event listener setup issues

Common Issues and Solutions

Issue 1: Events Not Firing

Symptoms: Click handlers, change handlers, or other events don't fire.

Causes:

1. Missing event listener setup
2. Wrong event name
3. Component ref not set up
4. Handler not passed as prop

Solution:

// ✅ CORRECT: Proper event listener setup (SolidJS)
createEffect(() => {
  const component = componentEl;
  if (!component) return;
  const handleEvent = (event: Event) => {
    props.onEvent?.(event as CustomEvent<EventDetailType>);
  };
  if (props.onEvent) {
    component.addEventListener("eventName", handleEvent);
  }
  return () => {
    if (props.onEvent) {
      component.removeEventListener("eventName", handleEvent);
    }
  };
});

Checklist:

• [ ] Component ref is created: let componentEl: HTMLModusWcComponentElement | undefined
• [ ] Callback ref is used: <modus-wc-component ref={(el) => (componentEl = el)} />
• [ ] Event listener is added in createEffect
• [ ] Event name matches Modus documentation
• [ ] Cleanup function removes listener

Issue 2: Missing Cleanup

Symptoms: Memory leaks, events firing multiple times, component errors after unmount.

Solution:

createEffect(() => {
  const component = componentEl;
  if (!component) return;
  const handleEvent = (event: Event) => {
    props.onEvent?.(event as CustomEvent<EventDetailType>);
  };
  component.addEventListener("eventName", handleEvent);
  // ✅ CRITICAL: Always return cleanup function
  return () => {
    component.removeEventListener("eventName", handleEvent);
  };
});

Issue 3: Wrong Event Names

Symptoms: Events never fire, wrong event type received.

Common Event Names:

Solution: Check Modus documentation for exact event names. They're case-sensitive.

Issue 4: Missing Ref

Symptoms: Cannot read property 'addEventListener' of null, events don't attach.

Solution:

// ✅ CORRECT: Ref setup (SolidJS)
let componentEl: HTMLModusWcComponentElement | undefined;
createEffect(() => {
  const component = componentEl;
  if (!component) return; // ✅ Check before use
  // Set up listeners
});
return (
  <modus-wc-component ref={(el) => (componentEl = el)} /> // ✅ Callback ref
);

Issue 5: Wrong Event Target

Symptoms: Can't access component properties, wrong value extracted.

Solution:

// ✅ CORRECT: Cast to proper element type
const handleInputChange = (event: Event) => {
  const customEvent = event as CustomEvent<InputEvent>;
  const value = (customEvent.target as HTMLModusWcTextInputElement).value;
  props.onInputChange?.(value);
};
// ❌ WRONG: Don't use event.detail for input values
const handleInputChange = (event: Event) => {
  const value = event.detail; // Wrong for input components!
};

Issue 6: Multiple Event Listeners

Symptoms: Events fire multiple times, duplicate handlers.

Solution:

// ✅ CORRECT: Conditional attachment
if (props.onEvent) {
  component.addEventListener("eventName", handleEvent);
}
// ✅ CORRECT: Remove in cleanup
return () => {
  if (props.onEvent) {
    component.removeEventListener("eventName", handleEvent);
  }
};

Debugging Checklist

When events aren't working, check:

1. Ref Setup

• [ ] let ref is declared with correct type
• [ ] Callback ref is passed to web component
• [ ] Ref is checked before use (if (!component) return)

1. Event Listener Setup

• [ ] Listener is added in createEffect
• [ ] Event name matches Modus documentation
• [ ] Handler function is defined
• [ ] Handler is conditionally attached (if prop exists)

1. Cleanup

• [ ] Cleanup function is returned from createEffect
• [ ] Listener is removed in cleanup
• [ ] Same handler reference is used for add/remove

1. Event Handling

• [ ] Event is cast to correct CustomEvent type
• [ ] Value is extracted correctly (target.value vs detail)
• [ ] Handler is called with correct parameters

Quick Fixes

Fix: Events Not Firing

1. Check if ref is set: console.log(componentEl)
2. Verify event name: Check Modus docs
3. Add console.log in handler to verify it's called
4. Check if handler prop is passed

Fix: Events Firing Multiple Times

1. Check if cleanup is removing listeners
2. Verify handler isn't recreated on each render
3. Ensure createEffect dependencies are correct

Fix: Wrong Values

1. Verify event type casting
2. Check if using target.value vs detail
3. For checkboxes, verify value inversion is handled

Related Files

• src/components/ModusCheckbox.tsx - Event handling example
• src/components/ModusDropdownMenu.tsx - Multiple events example
• src/components/ModusNavbar.tsx - Complex event handling