@julianoczkowski/create-trimble-app 2.0.0

package/templates/react/.cursor/skills/create-modus-wrapper-component/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: create-modus-wrapper-component
+description: Scaffold a new Modus wrapper component following established patterns with proper TypeScript interfaces, event handling, and cleanup
+---
+
+# Create Modus Wrapper Component
+
+Scaffold a new Modus wrapper component following established patterns from the codebase.
+
+## When to Use
+
+Use this skill when:
+- Creating a new wrapper component for a Modus web component
+- You need to integrate a Modus component that doesn't have a wrapper yet
+- You want to ensure proper event handling and TypeScript types
+
+## Pattern Overview
+
+All Modus wrapper components follow this structure:
+
+1. **Import the web component** from `@trimble-oss/moduswebcomponents-react`
+2. **Define TypeScript props interface** with JSDoc comments
+3. **Use `useRef`** for component reference
+4. **Use `useEffect`** for event listeners with proper cleanup
+5. **Forward props** to the web component with conditional spreading
+6. **Handle events** via event listeners, not React props
+
+## Reference Examples
+
+- **Simple wrapper**: `src/components/ModusButton.tsx` - No event listeners needed
+- **With event listeners**: `src/components/ModusCheckbox.tsx` - Shows event handling pattern
+- **With dropdown**: `src/components/ModusDropdownMenu.tsx` - Shows menu event handling
+
+## Implementation Template
+
+```tsx
+import { useEffect, useRef } from "react";
+import { ModusWc[ComponentName] } from "@trimble-oss/moduswebcomponents-react";
+import type { ReactNode } from "react";
+
+/**
+ * Props for the Modus[ComponentName] component.
+ */
+export interface Modus[ComponentName]Props {
+  /** Description of prop */
+  propName?: string;
+  
+  /** A callback function to handle events. */
+  onEventName?: (event: CustomEvent<EventDetailType>) => void;
+  
+  /** A custom CSS class to apply to the component. */
+  customClass?: string;
+  
+  /** The ARIA label for accessibility. */
+  "aria-label"?: string;
+}
+
+/**
+ * Renders a Modus [component name] component.
+ *
+ * @example
+ * // Basic usage
+ * <Modus[ComponentName] propName="value" />
+ *
+ * @example
+ * // With event handler
+ * <Modus[ComponentName]
+ *   propName="value"
+ *   onEventName={(event) => console.log(event.detail)}
+ * />
+ *
+ * @param {Modus[ComponentName]Props} props - The component props.
+ * @returns {JSX.Element} The rendered component.
+ * @see {@link https://modus.trimble.com/components/[component]} - Modus documentation
+ */
+export default function Modus[ComponentName]({
+  propName,
+  onEventName,
+  customClass,
+  "aria-label": ariaLabel,
+}: Modus[ComponentName]Props) {
+  const componentRef = useRef<HTMLModusWc[ComponentName]Element>(null);
+
+  // Set up event listeners if needed
+  useEffect(() => {
+    const component = componentRef.current;
+    if (!component) return;
+
+    const handleEventName = (event: Event) => {
+      onEventName?.(event as CustomEvent<EventDetailType>);
+    };
+
+    if (onEventName) {
+      component.addEventListener("eventName", handleEventName);
+    }
+
+    return () => {
+      if (onEventName) {
+        component.removeEventListener("eventName", handleEventName);
+      }
+    };
+  }, [onEventName]);
+
+  return (
+    <ModusWc[ComponentName]
+      ref={componentRef}
+      prop-name={propName}
+      custom-class={customClass}
+      aria-label={ariaLabel}
+    />
+  );
+}
+```
+
+## Key Patterns
+
+### 1. Conditional Prop Spreading
+
+For optional props that shouldn't be passed when undefined:
+
+```tsx
+// ✅ CORRECT: Conditional spreading
+<ModusWcComponent
+  {...(color && { color })}
+  {...(variant && { variant })}
+  size={size} // Required prop, always pass
+/>
+
+// ❌ WRONG: Passing undefined
+<ModusWcComponent
+  color={color} // May be undefined
+  variant={variant} // May be undefined
+/>
+```
+
+Reference: `src/components/ModusButton.tsx:229-230`
+
+### 2. Event Listener Setup
+
+Always use `useEffect` with cleanup:
+
+```tsx
+useEffect(() => {
+  const component = componentRef.current;
+  if (!component) return;
+
+  const handleEvent = (event: Event) => {
+    onEvent?.(event as CustomEvent<EventDetailType>);
+  };
+
+  if (onEvent) {
+    component.addEventListener("eventName", handleEvent);
+  }
+
+  return () => {
+    if (onEvent) {
+      component.removeEventListener("eventName", handleEvent);
+    }
+  };
+}, [onEvent]);
+```
+
+Reference: `src/components/ModusCheckbox.tsx:91-150`
+
+### 3. TypeScript Types
+
+Use proper types for web component elements:
+
+```tsx
+// ✅ CORRECT: Proper element type
+const componentRef = useRef<HTMLModusWcButtonElement>(null);
+const componentRef = useRef<HTMLModusWcCheckboxElement>(null);
+const componentRef = useRef<HTMLModusWcDropdownMenuElement>(null);
+
+// Pattern: HTMLModusWc[ComponentName]Element
+```
+
+### 4. Prop Naming
+
+Web components use kebab-case for props:
+
+```tsx
+// React prop: customClass
+// Web component prop: custom-class
+<ModusWcComponent custom-class={customClass} />
+
+// React prop: modalId
+// Web component prop: modal-id
+<ModusWcModal modal-id={modalId} />
+```
+
+### 5. Event Handler Types
+
+Always type event handlers properly:
+
+```tsx
+// ✅ CORRECT: Typed event handler
+onEventName?: (event: CustomEvent<{ value: string }>) => void;
+
+// In handler:
+const handleEvent = (event: Event) => {
+  onEventName?.(event as CustomEvent<{ value: string }>);
+};
+```
+
+## Common Event Names
+
+Modus components use these common event names:
+
+- `inputChange` - For input value changes
+- `inputFocus` - For focus events
+- `inputBlur` - For blur events
+- `buttonClick` - For button clicks
+- `itemSelect` - For menu/dropdown item selection
+- `menuVisibilityChange` - For dropdown menu visibility
+- `expandedChange` - For accordion/collapse state
+
+Check the Modus documentation for component-specific events.
+
+## Accessibility
+
+Always include:
+
+- `aria-label` prop for icon-only or non-text components
+- Proper ARIA attributes passed to web component
+- Keyboard navigation support (usually handled by web component)
+
+## Testing Checklist
+
+- [ ] Component renders without errors
+- [ ] Props are forwarded correctly to web component
+- [ ] Event listeners are set up and cleaned up properly
+- [ ] TypeScript types are correct
+- [ ] Accessibility attributes are included
+- [ ] Conditional props don't pass undefined values
+
+## Common Mistakes to Avoid
+
+1. **Missing cleanup**: Always return cleanup function from `useEffect`
+2. **Wrong event names**: Check Modus docs for exact event names
+3. **Passing undefined**: Use conditional spreading for optional props
+4. **Wrong prop names**: Web components use kebab-case, React uses camelCase
+5. **Missing null checks**: Always check `componentRef.current` before use
+
+## Next Steps
+
+After creating the wrapper:
+
+1. Export it from `src/components/index.ts` (if exists)
+2. Create a demo page in `src/demos/[component]-demo/page.tsx`
+3. Add to component reference documentation
+4. Test all props and events

package/templates/react/.cursor/skills/fix-modus-component-event-issues/SKILL.md

@@ -0,0 +1,345 @@
+---
+name: fix-modus-component-event-issues
+description: Debug and fix common event handling problems with Modus web components
+---
+
+# Fix Modus Component Event Issues
+
+Debug and fix common event handling problems with Modus web components.
+
+## 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**:
+
+```tsx
+// ✅ CORRECT: Proper event listener setup
+useEffect(() => {
+  const component = componentRef.current;
+  if (!component) return;
+
+  const handleEvent = (event: Event) => {
+    onEvent?.(event as CustomEvent<EventDetailType>);
+  };
+
+  if (onEvent) {
+    component.addEventListener("eventName", handleEvent);
+  }
+
+  return () => {
+    if (onEvent) {
+      component.removeEventListener("eventName", handleEvent);
+    }
+  };
+}, [onEvent]); // ✅ Include handler in dependencies
+```
+
+**Checklist**:
+- [ ] Component ref is created: `const componentRef = useRef<HTMLModusWcComponentElement>(null)`
+- [ ] Ref is passed to web component: `<ModusWcComponent ref={componentRef} />`
+- [ ] Event listener is added in `useEffect`
+- [ ] Event name matches Modus documentation
+- [ ] Handler is included in dependency array
+- [ ] Cleanup function removes listener
+
+### Issue 2: Missing Cleanup
+
+**Symptoms**: Memory leaks, events firing multiple times, component errors after unmount.
+
+**Solution**:
+
+```tsx
+useEffect(() => {
+  const component = componentRef.current;
+  if (!component) return;
+
+  const handleEvent = (event: Event) => {
+    onEvent?.(event as CustomEvent<EventDetailType>);
+  };
+
+  component.addEventListener("eventName", handleEvent);
+
+  // ✅ CRITICAL: Always return cleanup function
+  return () => {
+    component.removeEventListener("eventName", handleEvent);
+  };
+}, [onEvent]);
+```
+
+### Issue 3: Wrong Event Names
+
+**Symptoms**: Events never fire, wrong event type received.
+
+**Common Event Names**:
+
+| Component | Event Name | Detail Type |
+|-----------|------------|-------------|
+| Checkbox | `inputChange` | `InputEvent` |
+| TextInput | `inputChange` | `InputEvent` |
+| DropdownMenu | `itemSelect` | `{ value: string }` |
+| DropdownMenu | `menuVisibilityChange` | `{ isVisible: boolean }` |
+| Navbar | `searchClick` | `MouseEvent \| KeyboardEvent` |
+| Accordion | `expandedChange` | `{ expanded: boolean; index: number }` |
+
+**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**:
+
+```tsx
+// ✅ CORRECT: Ref setup
+const componentRef = useRef<HTMLModusWcComponentElement>(null);
+
+useEffect(() => {
+  const component = componentRef.current;
+  if (!component) return; // ✅ Check before use
+  
+  // Set up listeners
+}, []);
+
+return (
+  <ModusWcComponent ref={componentRef} /> // ✅ Pass ref
+);
+```
+
+### Issue 5: Handler Not in Dependencies
+
+**Symptoms**: Stale closures, handlers use old values.
+
+**Solution**:
+
+```tsx
+useEffect(() => {
+  const component = componentRef.current;
+  if (!component) return;
+
+  const handleEvent = (event: Event) => {
+    onEvent?.(event as CustomEvent<EventDetailType>);
+  };
+
+  if (onEvent) {
+    component.addEventListener("eventName", handleEvent);
+  }
+
+  return () => {
+    if (onEvent) {
+      component.removeEventListener("eventName", handleEvent);
+    }
+  };
+}, [onEvent]); // ✅ Include handler in dependencies
+```
+
+### Issue 6: Wrong Event Target
+
+**Symptoms**: Can't access component properties, wrong value extracted.
+
+**Solution**:
+
+```tsx
+// ✅ CORRECT: Cast to proper element type
+const handleInputChange = (event: Event) => {
+  const customEvent = event as CustomEvent<InputEvent>;
+  const value = (customEvent.target as HTMLModusWcTextInputElement).value;
+  onInputChange?.(value);
+};
+
+// ❌ WRONG: Don't use event.detail for input values
+const handleInputChange = (event: Event) => {
+  const value = event.detail; // Wrong for input components!
+};
+```
+
+### Issue 7: Multiple Event Listeners
+
+**Symptoms**: Events fire multiple times, duplicate handlers.
+
+**Solution**:
+
+```tsx
+// ✅ CORRECT: Conditional attachment
+if (onEvent) {
+  component.addEventListener("eventName", handleEvent);
+}
+
+// ✅ CORRECT: Remove in cleanup
+return () => {
+  if (onEvent) {
+    component.removeEventListener("eventName", handleEvent);
+  }
+};
+```
+
+## Debugging Checklist
+
+When events aren't working, check:
+
+1. **Ref Setup**
+   - [ ] `useRef` is created with correct type
+   - [ ] Ref is passed to web component
+   - [ ] Ref is checked before use (`if (!component) return`)
+
+2. **Event Listener Setup**
+   - [ ] Listener is added in `useEffect`
+   - [ ] Event name matches Modus documentation
+   - [ ] Handler function is defined
+   - [ ] Handler is conditionally attached (if prop exists)
+
+3. **Cleanup**
+   - [ ] Cleanup function is returned from `useEffect`
+   - [ ] Listener is removed in cleanup
+   - [ ] Same handler reference is used for add/remove
+
+4. **Dependencies**
+   - [ ] Handler props are in dependency array
+   - [ ] No missing dependencies causing stale closures
+
+5. **Event Handling**
+   - [ ] Event is cast to correct `CustomEvent` type
+   - [ ] Value is extracted correctly (`target.value` vs `detail`)
+   - [ ] Handler is called with correct parameters
+
+## Debugging Tools
+
+### Console Logging
+
+```tsx
+useEffect(() => {
+  const component = componentRef.current;
+  if (!component) {
+    console.error("Component ref is null");
+    return;
+  }
+
+  console.log("Setting up event listener for:", component);
+
+  const handleEvent = (event: Event) => {
+    console.log("Event fired:", event);
+    console.log("Event type:", event.type);
+    console.log("Event target:", event.target);
+    onEvent?.(event as CustomEvent<EventDetailType>);
+  };
+
+  component.addEventListener("eventName", handleEvent);
+  console.log("Event listener attached");
+
+  return () => {
+    console.log("Cleaning up event listener");
+    component.removeEventListener("eventName", handleEvent);
+  };
+}, [onEvent]);
+```
+
+### React DevTools
+
+- Check if component ref is set
+- Verify component is mounted
+- Check if handlers are defined
+
+### Browser DevTools
+
+- Check Event Listeners panel for attached listeners
+- Verify event names match
+- Check for errors in console
+
+## Common Patterns to Verify
+
+### Pattern 1: Basic Event Setup
+
+```tsx
+// ✅ Verify this pattern
+const componentRef = useRef<HTMLModusWcComponentElement>(null);
+
+useEffect(() => {
+  const component = componentRef.current;
+  if (!component) return;
+
+  const handleEvent = (event: Event) => {
+    onEvent?.(event as CustomEvent<EventDetailType>);
+  };
+
+  if (onEvent) {
+    component.addEventListener("eventName", handleEvent);
+  }
+
+  return () => {
+    if (onEvent) {
+      component.removeEventListener("eventName", handleEvent);
+    }
+  };
+}, [onEvent]);
+
+return <ModusWcComponent ref={componentRef} />;
+```
+
+### Pattern 2: Multiple Events
+
+```tsx
+// ✅ Verify all events are set up
+useEffect(() => {
+  const component = componentRef.current;
+  if (!component) return;
+
+  const handleEvent1 = (event: Event) => {
+    onEvent1?.(event as CustomEvent<Type1>);
+  };
+  const handleEvent2 = (event: Event) => {
+    onEvent2?.(event as CustomEvent<Type2>);
+  };
+
+  if (onEvent1) component.addEventListener("event1", handleEvent1);
+  if (onEvent2) component.addEventListener("event2", handleEvent2);
+
+  return () => {
+    if (onEvent1) component.removeEventListener("event1", handleEvent1);
+    if (onEvent2) component.removeEventListener("event2", handleEvent2);
+  };
+}, [onEvent1, onEvent2]); // ✅ All handlers in dependencies
+```
+
+## Quick Fixes
+
+### Fix: Events Not Firing
+
+1. Check if ref is set: `console.log(componentRef.current)`
+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. Check dependency array includes handler
+
+### 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
+- `.cursor/rules/modus-react-integration.mdc` - Integration patterns