create-modus-wrapper-component

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

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}
    />
  );
}