@julianoczkowski/create-trimble-app 2.0.0

package/templates/angular/.cursor/rules/modus-angular-20.mdc

@@ -0,0 +1,82 @@
+---
+description: Angular 20 best practices and coding standards with signals, standalone components, and modern patterns
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: true
+---
+
+# Angular 20 Best Practices
+
+This project adheres to modern Angular best practices, emphasizing maintainability, performance, accessibility, and scalability.
+
+## TypeScript Best Practices
+
+* **Strict Type Checking:** Always enable and adhere to strict type checking.
+* **Prefer Type Inference:** Allow TypeScript to infer types when they are obvious from the context.
+* **Avoid `any`:** Do not use the `any` type unless absolutely necessary. Prefer `unknown` when a type is uncertain.
+
+## Angular Best Practices
+
+* **Standalone Components:** Always use standalone components, directives, and pipes. Avoid using `NgModules` for new features.
+* **Implicit Standalone:** Do not explicitly set `standalone: true` inside the `@Component`, `@Directive` and `@Pipe` decorators, as it is implied by default.
+* **Signals for State Management:** Utilize Angular Signals for reactive state management within components and services.
+* **Lazy Loading:** Implement lazy loading for feature routes to improve initial load times.
+* **NgOptimizedImage:** Use `NgOptimizedImage` for all static images to automatically optimize image loading and performance.
+* **Host bindings:** Do NOT use the `@HostBinding` and `@HostListener` decorators. Put host bindings inside the `host` object of the `@Component` or `@Directive` decorator instead.
+
+## Components
+
+* **Single Responsibility:** Keep components small, focused, and responsible for a single piece of functionality.
+* **`input()` and `output()` Functions:** Prefer `input()` and `output()` functions over the `@Input()` and `@Output()` decorators:
+    ```typescript
+    import { input, output } from '@angular/core';
+
+    userId = input<string>('');
+    userSelected = output<string>();
+    ```
+* **`computed()` for Derived State:** Use the `computed()` function from `@angular/core` for derived state based on signals.
+* **`ChangeDetectionStrategy.OnPush`:** Always set `changeDetection: ChangeDetectionStrategy.OnPush` in the `@Component` decorator.
+* **Inline Templates:** Prefer inline templates (template: `...`) for small components. For larger templates, use external HTML files.
+* **Reactive Forms:** Prefer Reactive forms over Template-driven forms for complex forms.
+* **No `ngClass` / `NgClass`:** Do not use the `ngClass` directive. Instead, use native `class` bindings:
+    ```html
+    <section [class.active]="isActive"></section>
+    <section [class]="{'active': isActive}"></section>
+    ```
+* **No `ngStyle` / `NgStyle`:** Do not use the `ngStyle` directive. Instead, use native `style` bindings:
+    ```html
+    <section [style.font-size.px]="fontSize"></section>
+    ```
+
+## State Management
+
+* **Signals for Local State:** Use signals for managing local component state.
+* **`computed()` for Derived State:** Leverage `computed()` for any state that can be derived from other signals.
+* **Pure and Predictable Transformations:** Ensure state transformations are pure functions (no side effects) and predictable.
+* **Signal value updates:** Do NOT use `mutate` on signals, use `update` or `set` instead.
+
+## Templates
+
+* **Simple Templates:** Keep templates as simple as possible, avoiding complex logic directly in the template.
+* **Native Control Flow:** Use the new built-in control flow syntax (`@if`, `@for`, `@switch`) instead of the older structural directives (`*ngIf`, `*ngFor`, `*ngSwitch`):
+    ```html
+    @if (isVisible) {
+      <section>Content</section>
+    }
+    @for (item of items; track item.id) {
+      <section>{{ item }}</section>
+    }
+    ```
+* **Async Pipe:** Use the `async` pipe to handle observables in templates.
+
+## Services
+
+* **Single Responsibility:** Design services around a single, well-defined responsibility.
+* **`providedIn: 'root'`:** Use the `providedIn: 'root'` option when declaring injectable services to ensure they are singletons and tree-shakable.
+* **`inject()` Function:** Prefer the `inject()` function over constructor injection:
+    ```typescript
+    import { inject } from '@angular/core';
+
+    export class MyComponent {
+      private myService = inject(MyService);
+    }
+    ```

package/templates/angular/.cursor/rules/modus-angular-accordion-state-management-short.mdc

@@ -0,0 +1,45 @@
+---
+description: State management patterns for Modus accordion components in Angular
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: true
+---
+
+# Modus Accordion State Management - Short
+
+Essential state management patterns for Modus Accordion components in Angular.
+
+## Key Rules
+
+- **Let Modus components manage their own state** - Don't try to control accordion state from Angular
+- **Use `expanded` for initial state only** - Set initial state, then let component handle changes
+- **Use `(expandedChange)` for tracking** - Monitor state changes without controlling them
+- **Use ViewChild for programmatic control** - Access component methods when needed
+- **Avoid real-time synchronization** - Don't sync Angular state with accordion state
+- **Don't use signals to control accordion** - Creates state loops and conflicts
+
+## Correct Patterns
+
+```typescript
+// CORRECT: Let Modus manage state
+@Component({
+  template: `
+    <modus-accordion>
+      <modus-collapse collapse-id="item1" [expanded]="true">
+        <div slot="content">Content</div>
+      </modus-collapse>
+    </modus-accordion>
+  `,
+})
+
+// CORRECT: ViewChild for programmatic control
+readonly collapseRef = viewChild<ElementRef>('collapseRef');
+
+openAccordion(): void {
+  const collapse = this.collapseRef()?.nativeElement;
+  if (collapse) collapse.expanded = true;
+}
+```
+
+## Reference
+
+For detailed state management patterns and advanced accordion usage, fetch the full rule: `modus-angular-accordion-state-management`

package/templates/angular/.cursor/rules/modus-angular-accordion-state-management.mdc

@@ -0,0 +1,322 @@
+---
+description: State management patterns for Modus accordion components in Angular
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: false
+---
+
+# Modus Accordion State Management in Angular
+
+## IMPORTANT: Accordion State Management Guidelines
+
+**Key Principle**: Modus Web Components (`modus-wc-accordion`, `modus-wc-collapse`) are designed to manage their own state, but they DO support controlled state when needed.
+
+**Best Practice**: Use the `expanded` attribute on `modus-wc-collapse` components for initial state or programmatic control, but avoid trying to synchronize Angular state with Modus state in real-time.
+
+## Common Anti-Patterns
+
+### Real-time State Synchronization
+
+```typescript
+// WRONG: Trying to sync Angular state with Modus state in real-time
+@Component({
+  template: `
+    <modus-accordion
+      (expandedChange)="onExpandedChange($event)"
+    >
+      <modus-collapse
+        [expanded]="isExpanded()"  <!-- Creates state loop -->
+      >
+        <div slot="content">Content</div>
+      </modus-collapse>
+    </modus-accordion>
+  `,
+})
+export class AccordionComponent {
+  readonly isExpanded = signal(false);
+
+  onExpandedChange(event: CustomEvent): void {
+    this.isExpanded.set(event.detail.expanded); // Creates conflicts
+  }
+}
+```
+
+### Complex State Synchronization
+
+```typescript
+// WRONG: Complex state synchronization that can cause loops
+@Component({
+  template: `
+    @for (item of items(); track item.id) {
+      <modus-accordion
+        (expandedChange)="toggleAccordion(item.id)"  <!-- Creates loops -->
+      >
+        <modus-collapse
+          [expanded]="accordionStates()[item.id]"  <!-- Causes conflicts -->
+        >
+          <div slot="content">Content for {{ item.id }}</div>
+        </modus-collapse>
+      </modus-accordion>
+    }
+  `,
+})
+export class MyComponent {
+  readonly items = signal([{ id: 'item1' }, { id: 'item2' }]);
+  readonly accordionStates = signal<Record<string, boolean>>({
+    item1: false,
+    item2: true,
+  });
+
+  toggleAccordion(id: string): void {
+    this.accordionStates.update(states => ({
+      ...states,
+      [id]: !states[id],
+    }));
+  }
+}
+```
+
+## Correct Patterns
+
+### Let Modus Components Manage Their Own State
+
+```typescript
+// CORRECT: Let Modus accordion manage its own state
+@Component({
+  template: `
+    <modus-accordion>
+      <modus-collapse
+        collapse-id="item1"
+        [options]="{
+          title: 'Item One',
+          description: 'First accordion item',
+          icon: 'star'
+        }"
+      >
+        <div slot="content">Content for item one.</div>
+      </modus-collapse>
+    </modus-accordion>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AccordionComponent {}
+```
+
+### Initial State Control (Recommended)
+
+```typescript
+// CORRECT: Set initial state without real-time synchronization
+@Component({
+  template: `
+    <modus-accordion>
+      <modus-collapse
+        collapse-id="item1"
+        [expanded]="true"  <!-- CORRECT: Initial state is fine -->
+        [options]="{
+          title: 'Initially Open',
+          description: 'This item starts expanded'
+        }"
+      >
+        <div slot="content">Content for item one.</div>
+      </modus-collapse>
+    </modus-accordion>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AccordionComponent {}
+```
+
+### Listen to Events for Tracking (Not Control)
+
+```typescript
+// CORRECT: Listen to events for tracking, don't control state
+@Component({
+  template: `
+    <modus-accordion (expandedChange)="handleAccordionChange($event)">
+      <modus-collapse
+        collapse-id="item1"
+        [options]="{
+          title: 'Item One',
+          description: 'First accordion item'
+        }"
+      >
+        <div slot="content">Content for item one.</div>
+      </modus-collapse>
+    </modus-accordion>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AccordionComponent {
+  readonly trackingData = signal({
+    accordionOpened: false,
+    openCount: 0,
+  });
+
+  handleAccordionChange(event: CustomEvent<{ expanded: boolean; index: number }>): void {
+    const { expanded, index } = event.detail;
+
+    // CORRECT: Use for tracking/analytics, not state control
+    this.trackingData.update(data => ({
+      accordionOpened: expanded,
+      openCount: expanded ? data.openCount + 1 : data.openCount,
+    }));
+
+    // CORRECT: Log for analytics
+    console.log(`Accordion item ${index} is now ${expanded ? 'open' : 'closed'}`);
+  }
+}
+```
+
+### Programmatic Control When Needed
+
+```typescript
+// CORRECT: Use ViewChild for programmatic control
+@Component({
+  template: `
+    <div class="space-x-2">
+      <modus-button (buttonClick)="openAccordion()">Open Accordion</modus-button>
+      <modus-button (buttonClick)="closeAccordion()">Close Accordion</modus-button>
+    </div>
+
+    <modus-accordion>
+      <modus-collapse
+        #collapseRef
+        collapse-id="item1"
+        [options]="{
+          title: 'Controllable Item',
+          description: 'This can be controlled programmatically'
+        }"
+      >
+        <div slot="content">Content for controllable item.</div>
+      </modus-collapse>
+    </modus-accordion>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class AccordionComponent {
+  readonly collapseRef = viewChild<ElementRef>('collapseRef');
+
+  openAccordion(): void {
+    const collapse = this.collapseRef()?.nativeElement;
+    if (collapse) {
+      collapse.expanded = true;
+    }
+  }
+
+  closeAccordion(): void {
+    const collapse = this.collapseRef()?.nativeElement;
+    if (collapse) {
+      collapse.expanded = false;
+    }
+  }
+}
+```
+
+## Best Practices
+
+### State Management Strategy
+
+1. **Let Modus Components Own Their State**
+
+   - Don't try to control `expanded` from Angular signals
+   - Use events to track state changes
+   - Use ViewChild for programmatic control when needed
+
+2. **Event-Driven Architecture**
+
+   ```typescript
+   // CORRECT: Event-driven approach
+   @Component({
+     template: `
+       <modus-accordion (expandedChange)="handleAccordionChange($event)">
+         <div slot="header">Header</div>
+         <div slot="body">Body</div>
+       </modus-accordion>
+     `,
+   })
+   export class MyComponent {
+     handleAccordionChange(event: CustomEvent): void {
+       // Handle the event for tracking, analytics, or side effects
+       // Don't try to control the accordion state
+       console.log('Accordion expanded:', event.detail);
+     }
+   }
+   ```
+
+3. **Use ViewChild for Programmatic Control**
+
+   ```typescript
+   // CORRECT: ViewChild-based control
+   readonly accordionRef = viewChild<ElementRef>('accordionRef');
+
+   toggleAccordion(): void {
+     const accordion = this.accordionRef()?.nativeElement;
+     if (accordion) {
+       accordion.expanded = !accordion.expanded;
+     }
+   }
+   ```
+
+### Multiple Accordions Pattern
+
+```typescript
+// CORRECT: Multiple accordions with independent state
+@Component({
+  template: `
+    <div class="space-x-2">
+      <modus-button (buttonClick)="openAllAccordions()">Open All</modus-button>
+      <modus-button (buttonClick)="closeAllAccordions()">Close All</modus-button>
+    </div>
+
+    @for (item of accordionData(); track item.id; let i = $index) {
+      <modus-accordion>
+        <modus-collapse
+          #accordionRefs
+          [collapse-id]="item.id"
+          [options]="{ title: item.title }"
+        >
+          <div slot="content">{{ item.content }}</div>
+        </modus-collapse>
+      </modus-accordion>
+    }
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class MultipleAccordionsComponent {
+  readonly accordionData = signal([
+    { id: 'acc1', title: 'Accordion 1', content: 'Content 1' },
+    { id: 'acc2', title: 'Accordion 2', content: 'Content 2' },
+    { id: 'acc3', title: 'Accordion 3', content: 'Content 3' },
+  ]);
+
+  readonly accordionRefs = viewChildren<ElementRef>('accordionRefs');
+
+  openAllAccordions(): void {
+    this.accordionRefs().forEach(ref => {
+      if (ref.nativeElement) {
+        ref.nativeElement.expanded = true;
+      }
+    });
+  }
+
+  closeAllAccordions(): void {
+    this.accordionRefs().forEach(ref => {
+      if (ref.nativeElement) {
+        ref.nativeElement.expanded = false;
+      }
+    });
+  }
+}
+```
+
+## Key Takeaways
+
+1. **Initial State is Fine**: Setting `[expanded]="true"` for initial state is perfectly acceptable
+2. **Avoid Real-time Sync**: Don't try to synchronize Angular state with Modus state in real-time
+3. **Use Events for Tracking**: Listen to `(expandedChange)` for analytics and side effects
+4. **Use ViewChild for Control**: When you need programmatic control, use ViewChild on `modus-collapse`
+5. **Trust the Component**: Modus Web Components handle their own state changes after initial render
+6. **Proper Structure**: Use `modus-accordion` with `modus-collapse` components and `options` for headers
+
+---
+
+**Remember: Modus accordion components support controlled initial state but avoid real-time synchronization. Use `expanded` for initial state, `(expandedChange)` for tracking, and ViewChild for programmatic control. This approach prevents conflicts and ensures reliable behavior.**