modus-angular-integration

Modus Web Components Angular Wrappers

Comprehensive guide for Angular standalone wrapper components that wrap Modus Web Components, focusing on signal-based APIs, TypeScript interfaces, and Tailwind CSS integration.

Table of Contents

1. Overview
2. Wrapper Component Pattern
3. Signal-Based API
4. Component Structure
5. Icon Integration
6. Styling Guidelines
7. Best Practices
   • Type Verification - Critical Rules

---

Overview

What Are These Components?

This application uses Angular standalone wrapper components that wrap Modus Web Components (modus-wc-*). These wrappers:

• Provide Angular-native APIs using signals (input(), output())
• Offer TypeScript type safety with exported interfaces
• Maintain consistency across the application
• Enable future flexibility to swap implementations
• Follow Angular 20+ best practices with modern control flow

Available Wrapper Components

All wrapper components are located in src/app/components/ and exported from src/app/components/index.ts:

import {
  ModusButtonComponent,
  ModusAlertComponent,
  ModusIconComponent,
  ModusTextInputComponent,
  ModusSelectComponent,
  // ... and many more
} from '@/app/components';

Reference: See src/app/components/index.ts for the complete list of available components.

---

Wrapper Component Pattern

Standard Component Structure

All wrapper components follow this consistent pattern:

import { ChangeDetectionStrategy, Component, input, output } from '@angular/core';
import { CommonModule } from '@angular/common';
import { ModusWcButton } from '@trimble-oss/moduswebcomponents-angular';

/**
 * Type definitions for component props
 */
export type ButtonColor = 'primary' | 'secondary' | 'tertiary' | 'warning' | 'danger';
export type ButtonVariant = 'filled' | 'outlined' | 'borderless';
export type ButtonSize = 'xs' | 'sm' | 'md' | 'lg';

/**
 * Props interface (optional but recommended for documentation)
 */
export interface ModusButtonProps {
  color?: ButtonColor;
  variant?: ButtonVariant;
  size?: ButtonSize;
  disabled?: boolean;
  // ... other props
}

@Component({
  selector: 'modus-button', // ← Users invoke with <modus-button>, NOT <modus-wc-button>
  standalone: true,
  imports: [CommonModule, ModusWcButton],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <!-- Inside the wrapper, we use modus-wc-button -->
    <modus-wc-button
      [color]="color()"
      [variant]="variant()"
      [size]="size()"
      [disabled]="disabled()"
      (buttonClick)="handleButtonClick($event)"
    >
      <ng-content></ng-content>
    </modus-wc-button>
  `,
})
export class ModusButtonComponent {
  // Signal-based inputs
  readonly color = input<ButtonColor>('primary');
  readonly variant = input<ButtonVariant>('filled');
  readonly size = input<ButtonSize>('md');
  readonly disabled = input<boolean>(false);

  // Signal-based output
  readonly buttonClick = output<MouseEvent | KeyboardEvent>();

  // Event handler
  handleButtonClick(event: CustomEvent<MouseEvent | KeyboardEvent>): void {
    if (!this.disabled()) {
      this.buttonClick.emit(event.detail);
    }
  }
}