@julianoczkowski/create-trimble-app 2.0.0

package/templates/angular/.cursor/rules/modus-angular-opacity-utilities.mdc

@@ -0,0 +1,160 @@
+---
+description: Essential opacity utilities for Modus Design System colors in Angular + Vite
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: false
+---
+
+# Modus Opacity Utilities - Angular
+
+Essential opacity utilities for Modus Design System colors in Angular + Vite.
+
+## Key Rules
+
+- **Use custom opacity utilities, not Tailwind /80 syntax** - `text-foreground-80` not `text-foreground/80`
+- **CSS variables don't work with Tailwind opacity modifiers** - Tailwind needs actual color values
+- **Use color-mix() for opacity variants** - Modern CSS function for proper opacity calculation
+- **All utilities defined in styles.css** - No Tailwind config changes needed
+- **Respects theme switching** - Works in all 6 Modus themes
+- **Use semantic color names** - `foreground`, `primary`, `destructive`, etc.
+
+## Available Opacity Levels
+
+- **80%** - `text-foreground-80`, `bg-primary-80`, `border-destructive-80`
+- **60%** - `text-foreground-60`, `bg-primary-60`, `border-destructive-60`
+- **40%** - `text-foreground-40`, `bg-primary-40`, `border-destructive-40`
+- **20%** - `text-foreground-20`, `bg-primary-20`, `border-destructive-20`
+
+## Available Colors
+
+- **foreground** - `text-foreground-80`, `bg-foreground-80`, `border-foreground-80`
+- **muted-foreground** - `text-muted-foreground-80`, `bg-muted-foreground-80`
+- **primary** - `text-primary-80`, `bg-primary-80`, `border-primary-80`
+- **secondary** - `text-secondary-80`, `bg-secondary-80`
+- **destructive** - `text-destructive-80`, `bg-destructive-80`, `border-destructive-80`
+- **warning** - `text-warning-80`, `bg-warning-80`, `border-warning-80`
+- **success** - `text-success-80`, `bg-success-80`, `border-success-80`
+
+## Usage Examples
+
+### Text Opacity
+
+```html
+<!-- WRONG: Tailwind syntax doesn't work with CSS variables -->
+<div class="text-foreground/80">Text with 80% opacity</div>
+
+<!-- CORRECT: Use custom opacity utilities -->
+<div class="text-foreground-80">Text with 80% opacity</div>
+<div class="text-primary-60">Primary text with 60% opacity</div>
+<div class="text-muted-foreground-40">Muted text with 40% opacity</div>
+```
+
+### Background Opacity
+
+```html
+<!-- CORRECT: Background opacity utilities -->
+<div class="bg-primary-80">Primary background with 80% opacity</div>
+<div class="bg-destructive-60">Destructive background with 60% opacity</div>
+<div class="bg-warning-40">Warning background with 40% opacity</div>
+```
+
+### Border Opacity
+
+```html
+<!-- CORRECT: Border opacity utilities -->
+<div class="border border-primary-80">Primary border with 80% opacity</div>
+<div class="border border-destructive-60">Destructive border with 60% opacity</div>
+<div class="border border-success-40">Success border with 40% opacity</div>
+```
+
+### Combined Usage
+
+```html
+<!-- CORRECT: Mix opacity utilities with other classes -->
+<div class="p-4 bg-card border border-primary-40 rounded-lg">
+  <div class="text-foreground-80 mb-2">Title with 80% opacity</div>
+  <div class="text-muted-foreground-60">Description with 60% opacity</div>
+</div>
+```
+
+## Implementation Details
+
+### CSS Custom Properties
+
+```css
+/* Opacity variants for design system colors */
+--foreground-80: color-mix(in srgb, var(--foreground) 80%, transparent);
+--foreground-60: color-mix(in srgb, var(--foreground) 60%, transparent);
+--foreground-40: color-mix(in srgb, var(--foreground) 40%, transparent);
+--foreground-20: color-mix(in srgb, var(--foreground) 20%, transparent);
+```
+
+### Tailwind Utilities
+
+```css
+.text-foreground-80 {
+  color: var(--foreground-80);
+}
+.text-foreground-60 {
+  color: var(--foreground-60);
+}
+.text-foreground-40 {
+  color: var(--foreground-40);
+}
+.text-foreground-20 {
+  color: var(--foreground-20);
+}
+```
+
+## Common Patterns
+
+### Subtle Text Hierarchy
+
+```html
+<div class="space-y-2">
+  <div class="text-foreground">Main heading (100%)</div>
+  <div class="text-foreground-80">Subheading (80%)</div>
+  <div class="text-muted-foreground-60">Description (60%)</div>
+  <div class="text-muted-foreground-40">Caption (40%)</div>
+</div>
+```
+
+### Interactive States
+
+```html
+<modus-button class="bg-primary hover:bg-primary-80 transition-colors">
+  Hover with opacity
+</modus-button>
+```
+
+### Overlay Effects
+
+```html
+<div class="relative">
+  <div class="bg-foreground-20 absolute inset-0 rounded-lg"></div>
+  <div class="relative z-10 p-4">Content with overlay</div>
+</div>
+```
+
+## Migration Guide
+
+### From Tailwind /80 syntax
+
+```html
+<!-- WRONG: Old (doesn't work with CSS variables) -->
+<div class="text-foreground/80">Text</div>
+<div class="bg-primary/60">Background</div>
+<div class="border-destructive/40">Border</div>
+
+<!-- CORRECT: New (works with design system) -->
+<div class="text-foreground-80">Text</div>
+<div class="bg-primary-60">Background</div>
+<div class="border-destructive-40">Border</div>
+```
+
+## Best Practices
+
+- **Use semantic colors** - `foreground`, `primary`, `destructive` instead of generic colors
+- **Maintain contrast ratios** - Ensure accessibility with opacity levels
+- **Test in all themes** - Verify opacity works in light and dark modes
+- **Use consistent opacity levels** - Stick to 80%, 60%, 40%, 20% for consistency
+- **Combine with other utilities** - Mix with spacing, sizing, and layout classes

package/templates/angular/.cursor/rules/modus-angular-select-vs-dropdown-menu-short.mdc

@@ -0,0 +1,51 @@
+---
+description: ModusSelect vs ModusDropdownMenu reliability comparison in Angular
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: true
+---
+
+# Modus Select vs Dropdown Menu - Short
+
+Use ModusDropdownMenu instead of ModusSelect for reliable event handling.
+
+## Key Rules
+
+- **Use ModusDropdownMenu, not ModusSelect** - ModusSelect has unreliable event handling in some scenarios
+- **Reliable itemSelect events** - ModusDropdownMenu provides consistent event handling
+- **Proper state management** - Use Angular signals to track selected values and visibility
+- **Programmatic control** - Use `menuVisible` property for control
+- **Event handling patterns** - Handle `itemSelect` events for selection changes
+
+## Correct Pattern
+
+```typescript
+@Component({
+  template: `
+    <modus-dropdown-menu
+      [menuVisible]="isOpen()"
+      (itemSelect)="handleItemSelect($event)"
+      (menuVisibleChange)="isOpen.set($event)"
+    >
+      <modus-button slot="trigger" (buttonClick)="toggleDropdown()">
+        {{ selectedLabel() || 'Select an option' }}
+      </modus-button>
+      @for (item of menuItems(); track item.value) {
+        <modus-menu-item [value]="item.value">{{ item.label }}</modus-menu-item>
+      }
+    </modus-dropdown-menu>
+  `,
+})
+export class DropdownComponent {
+  readonly selectedValue = signal<string>('');
+  readonly isOpen = signal(false);
+
+  handleItemSelect(event: CustomEvent<{ value: string }>): void {
+    this.selectedValue.set(event.detail.value);
+    this.isOpen.set(false);
+  }
+}
+```
+
+## Reference
+
+For detailed component comparison and advanced usage, fetch the full rule: `modus-angular-select-vs-dropdown-menu`

package/templates/angular/.cursor/rules/modus-angular-select-vs-dropdown-menu.mdc

@@ -0,0 +1,83 @@
+---
+description: ModusSelect vs ModusDropdownMenu reliability comparison in Angular
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: false
+---
+
+# ModusSelect vs ModusDropdownMenu in Angular
+
+## CRITICAL: ModusSelect Reliability Issues
+
+**Problem**: `ModusSelect` component has unreliable event handling in some scenarios, especially with Chrome DevTools automation and testing.
+
+**Solution**: Use `ModusDropdownMenu` with `itemSelect` events, which are more reliable and consistent.
+
+## Correct Pattern: Use ModusDropdownMenu
+
+```typescript
+// CORRECT: ModusDropdownMenu with reliable events
+@Component({
+  template: `
+    <modus-dropdown-menu
+      [menuVisible]="isOpen()"
+      (itemSelect)="handleItemSelect($event)"
+      (menuVisibleChange)="isOpen.set($event)"
+    >
+      <modus-button
+        slot="trigger"
+        variant="outlined"
+        (buttonClick)="toggleDropdown()"
+      >
+        {{ selectedLabel() || 'Select an option' }}
+        <i class="modus-icons ml-2">{{ isOpen() ? 'caret_up' : 'caret_down' }}</i>
+      </modus-button>
+
+      @for (item of menuItems(); track item.value) {
+        <modus-menu-item
+          [value]="item.value"
+          [class.bg-primary-20]="selectedValue() === item.value"
+        >
+          {{ item.label }}
+        </modus-menu-item>
+      }
+    </modus-dropdown-menu>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ReliableDropdownComponent {
+  readonly selectedValue = signal<string>('');
+  readonly isOpen = signal(false);
+
+  readonly menuItems = signal([
+    { label: 'Option 1', value: 'option1' },
+    { label: 'Option 2', value: 'option2' },
+    { label: 'Option 3', value: 'option3' },
+  ]);
+
+  readonly selectedLabel = computed(() => {
+    const item = this.menuItems().find(i => i.value === this.selectedValue());
+    return item?.label ?? '';
+  });
+
+  handleItemSelect(event: CustomEvent<{ value: string }>): void {
+    const value = event.detail.value;
+    this.selectedValue.set(value);
+    this.isOpen.set(false);
+  }
+
+  toggleDropdown(): void {
+    this.isOpen.update(open => !open);
+  }
+}
+```
+
+## Key Takeaways
+
+1. **Prefer ModusDropdownMenu**: Use `ModusDropdownMenu` for reliable event handling
+2. **Reliable Events**: `itemSelect` events are more reliable than `inputChange` events
+3. **Programmatic Control**: Use `menuVisible` property for programmatic control
+4. **Event Handling**: Use proper event handling patterns with signals
+
+---
+
+**Remember: ModusSelect may have unreliable event handling in some scenarios. Prefer ModusDropdownMenu with itemSelect events for reliable dropdown functionality.**

package/templates/angular/.cursor/rules/modus-angular-semantic-html-short.mdc

@@ -0,0 +1,36 @@
+---
+description: Semantic HTML usage guidelines for Angular + Vite with Modus
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: true
+---
+
+# Modus Semantic HTML - Short
+
+Use div elements exclusively to avoid Tailwind CSS conflicts.
+
+## Key Rules
+
+- **Use div elements only** - All content must use `<div>` elements
+- **No semantic HTML elements** - Never use `h1`, `p`, `section`, `header`, `footer`, `nav`, `main`, `aside`, `article`, `span`
+- **Use Tailwind classes for styling** - Apply typography and layout with Tailwind classes
+- **Icon exception** - Only `<i>` elements allowed for Modus icons
+- **Consistent structure** - Maintain consistent div-based component structure
+
+## Correct Patterns
+
+```html
+<!-- CORRECT: Div elements with Tailwind classes -->
+<div class="text-4xl font-bold">Title</div>
+<div class="text-base">Paragraph text</div>
+<div class="bg-background">Header content</div>
+<div class="bg-muted">Footer content</div>
+
+<!-- WRONG: Semantic HTML elements -->
+<h1 class="text-4xl font-bold">Title</h1>
+<p class="text-base">Paragraph text</p>
+<header class="bg-background">Header content</header>
+```
+
+## Reference
+
+For detailed HTML patterns and accessibility guidelines, fetch the full rule: `modus-angular-semantic-html`

package/templates/angular/.cursor/rules/modus-angular-semantic-html.mdc

@@ -0,0 +1,81 @@
+---
+description: Semantic HTML usage guidelines for Angular + Vite with Modus
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: false
+---
+
+# Semantic HTML Usage in Angular + Vite
+
+## CRITICAL: Use Div Elements Only
+
+**MANDATORY**: This Angular + Vite application uses **div elements exclusively** for all content (except `<i>` for icons) to avoid conflicts with Tailwind CSS default browser styles.
+
+**Rule**: Use `div` elements with Tailwind classes instead of semantic HTML elements.
+
+## FORBIDDEN: Semantic HTML Elements
+
+```html
+<!-- WRONG: Semantic HTML elements -->
+<h1 class="text-4xl font-bold">Title</h1>
+<p class="text-base">Paragraph text</p>
+<section class="mb-8 p-4">Content section</section>
+<header class="bg-background">Header content</header>
+<footer class="bg-muted">Footer content</footer>
+<nav class="flex space-x-4">Navigation</nav>
+<span class="text-sm">Inline text</span>
+```
+
+## CORRECT: Div Elements with Tailwind
+
+```html
+<!-- CORRECT: Div elements with Tailwind classes -->
+<div class="text-4xl font-bold">Title</div>
+<div class="text-base">Paragraph text</div>
+<div class="mb-8 p-4">Content section</div>
+<div class="bg-background">Header content</div>
+<div class="bg-muted">Footer content</div>
+<div class="flex space-x-4">Navigation</div>
+<div class="text-sm">Inline text</div>
+```
+
+## Component Patterns
+
+### Page Layout with Divs
+
+```typescript
+@Component({
+  selector: 'page-layout',
+  template: `
+    <div class="min-h-screen flex flex-col">
+      <div class="bg-background border-b border-default">
+        <div class="container mx-auto px-4 py-4">
+          <div class="text-2xl font-bold text-foreground">App Title</div>
+        </div>
+      </div>
+
+      <div class="flex-1">
+        <ng-content />
+      </div>
+
+      <div class="bg-muted border-t border-default">
+        <div class="container mx-auto px-4 py-4">
+          <div class="text-sm text-foreground-60">Footer content</div>
+        </div>
+      </div>
+    </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class PageLayoutComponent {}
+```
+
+## Semantic HTML Compliance Checklist
+
+- [ ] **No Semantic Elements**: No `h1`, `h2`, `p`, `section`, `header`, `footer`, `nav`, `main`, `aside`, `article`, `span`
+- [ ] **Div Elements Only**: All content uses `div` elements
+- [ ] **Icon Exception**: Only `<i>` elements allowed for icons
+- [ ] **Tailwind Styling**: All styling through Tailwind classes
+
+---
+
+**Remember: This Angular + Vite application uses div elements exclusively for all content (except `<i>` for icons) to avoid conflicts with Tailwind CSS default browser styles.**

package/templates/angular/.cursor/rules/modus-angular-side-navigation-usage-short.mdc

@@ -0,0 +1,50 @@
+---
+description: Integration patterns for Modus Navbar with Side Navigation in Angular
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: true
+---
+
+# Modus Side Navigation Usage - Short
+
+Critical integration patterns for Modus Navbar with Side Navigation in Angular.
+
+## Key Rules
+
+- **Use Angular wrapper components** - Use `modus-navbar` and `modus-side-navigation`, not raw web components
+- **Pass props as native objects** - Angular handles binding automatically
+- **Listen for mainMenuOpenChange events** - Use DOM event listeners on container
+- **Position side navigation absolutely** - Required for proper layering
+- **Set explicit z-index** - Ensure side navigation renders above content
+- **Account for collapsed width** - Add margin-left to panel content
+
+## Required CSS
+
+```css
+.side-navigation {
+  position: absolute;
+  left: 0;
+  top: 0;
+  height: 100%;
+  z-index: 999;
+}
+
+.panel-content {
+  margin-left: 4rem;
+}
+```
+
+## Event Integration
+
+```typescript
+ngAfterViewInit(): void {
+  const container = this.elementRef.nativeElement.querySelector('.layout-with-navbar');
+  container.addEventListener('mainMenuOpenChange', (event: any) => {
+    const sideNav = container.querySelector('modus-wc-side-navigation');
+    if (sideNav) sideNav.expanded = event.detail;
+  });
+}
+```
+
+## Reference
+
+For detailed layout patterns and common pitfalls, fetch the full rule: `modus-angular-side-navigation-usage`

package/templates/angular/.cursor/rules/modus-angular-side-navigation-usage.mdc

@@ -0,0 +1,136 @@
+---
+description: Integration patterns for Modus Navbar with Side Navigation in Angular
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: false
+---
+
+# Modus Navbar + Side Navigation Integration (Angular)
+
+Critical patterns for integrating `modus-navbar` with `modus-side-navigation` in Angular applications.
+
+## Key Rules
+
+- **Use Angular wrapper components** - Use `modus-navbar` and `modus-side-navigation`, not raw web components
+- **Pass props as native objects** - Angular handles binding automatically
+- **Listen for mainMenuOpenChange events** - Use DOM event listeners on container
+- **Position side navigation absolutely** - Required for proper layering
+- **Set explicit z-index** - Ensure side navigation renders above content
+
+## DO: Use Angular Wrapper Components
+
+```html
+<!-- DO: Use Angular wrapper components -->
+<modus-navbar [userCard]="userCardInfo()" [visibility]="{ mainMenu: true, user: true }" />
+
+<modus-side-navigation
+  [expanded]="false"
+  [collapseOnClickOutside]="true"
+  [maxWidth]="'256px'"
+  mode="push"
+  [targetContent]="'#panel-content'"
+/>
+```
+
+## DO: Setup Event Listeners in ngAfterViewInit
+
+```typescript
+export class SideNavigationDemoComponent implements AfterViewInit {
+  readonly navbarMenuExpanded = signal<boolean>(false);
+
+  constructor(private elementRef: ElementRef) {}
+
+  ngAfterViewInit(): void {
+    this.setupNavbarSideNavigationIntegration();
+  }
+
+  private setupNavbarSideNavigationIntegration(): void {
+    const container = this.elementRef.nativeElement.querySelector('.layout-with-navbar');
+
+    container.addEventListener('mainMenuOpenChange', (event: any) => {
+      const sideNav = container.querySelector('modus-wc-side-navigation');
+
+      if (sideNav) {
+        sideNav.expanded = event.detail;
+        this.navbarMenuExpanded.set(event.detail);
+      }
+    });
+
+    const sideNav = container.querySelector('modus-wc-side-navigation');
+    sideNav?.addEventListener('expandedChange', (event: any) => {
+      this.navbarMenuExpanded.set(event.detail);
+    });
+  }
+}
+```
+
+## DO: Position Side Navigation Absolutely with Z-Index
+
+```css
+.layout-with-navbar {
+  box-shadow: rgba(36, 35, 45, 0.3) 1px 0 4px;
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+.layout-with-navbar .main-content-row {
+  display: flex;
+  flex: 1;
+  overflow: hidden;
+  position: relative;
+  min-height: 500px;
+}
+
+.layout-with-navbar .side-navigation,
+.layout-with-navbar modus-side-navigation {
+  position: absolute;
+  left: 0;
+  top: 0;
+  height: 100%;
+  z-index: 999;
+}
+
+.layout-with-navbar .panel-content {
+  flex: 1;
+  padding: 1.5rem;
+  overflow: auto;
+  margin-left: 4rem;
+}
+```
+
+## Required Layout Structure
+
+```html
+<div class="layout-with-navbar h-[600px] flex flex-col" data-example="basic">
+  <modus-navbar [userCard]="userCardInfo()" [visibility]="{ mainMenu: true, user: true }" />
+
+  <div class="main-content-row flex flex-1 overflow-hidden">
+    <modus-side-navigation
+      [expanded]="false"
+      [collapseOnClickOutside]="true"
+      [maxWidth]="'256px'"
+      mode="push"
+      [targetContent]="'#panel-content'"
+      class="side-navigation h-full"
+    >
+      <modus-menu size="lg">
+        <modus-menu-item label="Home" value="home" [selected]="true">
+          <modus-icon slot="start-icon" name="home" [decorative]="true"></modus-icon>
+        </modus-menu-item>
+      </modus-menu>
+    </modus-side-navigation>
+
+    <div id="panel-content" class="panel-content flex-1 p-6">
+      <!-- Main content here -->
+    </div>
+  </div>
+</div>
+```
+
+## Common Pitfalls
+
+1. **Hamburger menu not visible** - Ensure `visibility.mainMenu: true` is set on navbar
+2. **Side nav expands then immediately collapses** - Set `expanded` property directly on web component ref
+3. **Side nav hidden by content** - Use `position: absolute` and `z-index: 999` in global CSS
+4. **Events not firing** - Use `addEventListener` on container, not Angular event binding
+5. **State not updating** - Set properties directly on the `modus-wc-side-navigation` element

package/templates/angular/.cursor/rules/modus-angular-table-usage-short.mdc

@@ -0,0 +1,52 @@
+---
+description: Modus Table component usage patterns for Angular
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: true
+---
+
+# Modus Table Usage - Short
+
+Essential patterns for Modus Table component in Angular.
+
+## Key Rules
+
+- **Use custom editors for editable cells** - Set `editor: 'custom'` with `customEditorRenderer`
+- **Use design system CSS variables** - `--border`, `--background`, `--foreground` in editors
+- **Handle keyboard events** - Enter to commit, Escape to cancel
+- **Use immutable updates with signals** - For proper change detection
+- **Import types from Modus** - `ITableColumn` from `@trimble-oss/moduswebcomponents`
+
+## Basic Usage
+
+```typescript
+const columns: ITableColumn[] = [
+  { id: 'name', header: 'Name', accessor: 'name', width: '40%' },
+  { id: 'role', header: 'Role', accessor: 'role' },
+];
+```
+
+```html
+<modus-table
+  [columns]="columns"
+  [data]="data"
+  density="comfortable"
+  [zebra]="true"
+  [hover]="true"
+/>
+```
+
+## Editable Cells
+
+```typescript
+{
+  id: 'task',
+  header: 'Task',
+  accessor: 'task',
+  editor: 'custom',
+  customEditorRenderer: (value, onCommit) => createTextEditor(value, onCommit),
+}
+```
+
+## Reference
+
+For detailed table patterns and custom editors, fetch the full rule: `modus-angular-table-usage`