@julianoczkowski/create-trimble-app 2.0.0

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

@@ -0,0 +1,222 @@
+---
+description: 6 Modus themes with proper switching and persistence in Angular + Vite
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: false
+---
+
+# Modus Themes Implementation in Angular + Vite
+
+## Theme System Overview
+
+This Angular + Vite application supports **6 Modus themes** with proper theme switching, persistence, and service-based management.
+
+**Available Themes**: 4 Modus themes + 2 Connect themes
+
+- `modus-classic-light` / `modus-classic-dark`
+- `modus-modern-light` / `modus-modern-dark`
+- `connect-light` / `connect-dark`
+
+## Theme Architecture
+
+### ThemeService Implementation
+
+```typescript
+import { Injectable, signal, computed } from '@angular/core';
+
+export type Theme =
+  | 'modus-classic-light'
+  | 'modus-classic-dark'
+  | 'modus-modern-light'
+  | 'modus-modern-dark'
+  | 'connect-light'
+  | 'connect-dark';
+
+const VALID_THEMES: Theme[] = [
+  'modus-classic-light',
+  'modus-classic-dark',
+  'modus-modern-light',
+  'modus-modern-dark',
+  'connect-light',
+  'connect-dark',
+];
+
+@Injectable({ providedIn: 'root' })
+export class ThemeService {
+  private readonly themeSignal = signal<Theme>('modus-classic-light');
+
+  readonly currentTheme = this.themeSignal.asReadonly();
+  readonly isDark = computed(() => this.themeSignal().includes('dark'));
+  readonly isModern = computed(() => this.themeSignal().includes('modern'));
+
+  constructor() {
+    this.loadThemeFromStorage();
+  }
+
+  private loadThemeFromStorage(): void {
+    if (typeof window !== 'undefined') {
+      try {
+        const savedTheme = window.localStorage.getItem('preferred-theme') as Theme | null;
+        if (savedTheme && VALID_THEMES.includes(savedTheme)) {
+          this.setTheme(savedTheme);
+        }
+      } catch (error) {
+        console.warn('Unable to read stored theme preference:', error);
+      }
+    }
+  }
+
+  setTheme(theme: Theme): void {
+    this.themeSignal.set(theme);
+    
+    // Apply theme to document
+    document.documentElement.setAttribute('data-theme', theme);
+    
+    // Persist to localStorage
+    try {
+      window.localStorage.setItem('preferred-theme', theme);
+    } catch (error) {
+      console.warn('Unable to persist theme preference:', error);
+    }
+  }
+}
+```
+
+## Theme Usage Patterns
+
+### Theme-Aware Components
+
+```typescript
+@Component({
+  template: `
+    <div class="bg-background text-foreground transition-colors duration-200">
+      <div class="text-foreground">Current theme: {{ themeService.currentTheme() }}</div>
+      <div class="text-muted-foreground">
+        Mode: {{ themeService.isDark() ? 'Dark' : 'Light' }}
+      </div>
+      <div class="text-muted-foreground">
+        Style: {{ themeService.isModern() ? 'Modern' : 'Classic' }}
+      </div>
+    </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ThemedComponent {
+  readonly themeService = inject(ThemeService);
+}
+```
+
+### Conditional Theming
+
+```typescript
+@Component({
+  template: `
+    <div class="bg-background text-foreground p-4 rounded border-default">
+      <div class="text-lg font-semibold">{{ themeSpecificContent() }}</div>
+    </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ConditionalThemedComponent {
+  private themeService = inject(ThemeService);
+  
+  readonly themeSpecificContent = computed(() => {
+    switch (this.themeService.currentTheme()) {
+      case 'modus-classic-light': return 'Classic Light Theme';
+      case 'modus-classic-dark': return 'Classic Dark Theme';
+      case 'modus-modern-light': return 'Modern Light Theme';
+      case 'modus-modern-dark': return 'Modern Dark Theme';
+      case 'connect-light': return 'Connect Light Theme';
+      case 'connect-dark': return 'Connect Dark Theme';
+      default: return 'Default Theme';
+    }
+  });
+}
+```
+
+### Theme Switching Component
+
+```typescript
+@Component({
+  template: `
+    <div class="space-y-2">
+      <div class="text-sm font-medium text-foreground">Theme</div>
+      <modus-dropdown-menu
+        [menuVisible]="isOpen()"
+        (itemSelect)="handleItemSelect($event)"
+        (menuVisibleChange)="isOpen.set($event)"
+      >
+        <modus-button slot="trigger" variant="outlined" (buttonClick)="isOpen.update(o => !o)">
+          {{ selectedLabel() }}
+        </modus-button>
+        @for (theme of themes; track theme.value) {
+          <modus-menu-item 
+            [value]="theme.value"
+            [class.bg-primary-20]="currentTheme() === theme.value"
+          >
+            {{ theme.label }}
+          </modus-menu-item>
+        }
+      </modus-dropdown-menu>
+    </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ThemeSwitcherComponent {
+  private themeService = inject(ThemeService);
+  
+  readonly isOpen = signal(false);
+  readonly currentTheme = this.themeService.currentTheme;
+  
+  readonly themes = [
+    { value: 'modus-classic-light', label: 'Classic Light' },
+    { value: 'modus-classic-dark', label: 'Classic Dark' },
+    { value: 'modus-modern-light', label: 'Modern Light' },
+    { value: 'modus-modern-dark', label: 'Modern Dark' },
+    { value: 'connect-light', label: 'Connect Light' },
+    { value: 'connect-dark', label: 'Connect Dark' },
+  ];
+  
+  readonly selectedLabel = computed(() => {
+    const theme = this.themes.find(t => t.value === this.currentTheme());
+    return theme?.label || 'Select Theme';
+  });
+  
+  handleItemSelect(event: CustomEvent<{ value: string }>): void {
+    this.themeService.setTheme(event.detail.value as Theme);
+    this.isOpen.set(false);
+  }
+}
+```
+
+## Common Anti-Patterns
+
+### Don't Use Custom Theme Attributes
+
+```typescript
+// WRONG: Using custom theme attributes
+document.documentElement.setAttribute('data-mode', isDark ? 'dark' : 'light');
+document.documentElement.classList.add(isDark ? 'dark' : 'light');
+
+// CORRECT: Use only official data-theme attribute
+document.documentElement.setAttribute('data-theme', theme);
+```
+
+### Don't Use Invalid Theme Values
+
+```typescript
+// WRONG: Invalid theme values
+this.themeService.setTheme('invalid-theme');
+this.themeService.setTheme('modus-light');
+
+// CORRECT: Valid theme values
+this.themeService.setTheme('modus-classic-light');
+this.themeService.setTheme('connect-dark');
+```
+
+## Key Takeaways
+
+1. **Use ThemeService**: Always use `ThemeService` for theme access via `inject()`
+2. **Official Theme Application**: Use only `data-theme` attribute (no custom attributes)
+3. **Valid Themes**: Only use the 6 valid theme values
+4. **Persistence**: Themes are automatically persisted to localStorage
+5. **Testing**: Test all themes to ensure proper functionality

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

@@ -0,0 +1,52 @@
+---
+description: Correct implementation pattern for Modus Utility Panel in Angular
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: true
+---
+
+# Modus Utility Panel Usage - Short
+
+Critical implementation patterns for Modus Utility Panel.
+
+## Key Rules
+
+- **Always use `className="fixed-utility-panel"`** - Required for overlay panels
+- **Place panel at END of template** - Outside content containers
+- **Don't use overflow-hidden** - On parent elements
+- **Don't nest panel in relative containers** - Causes layout issues
+- **Control state from your buttons** - Not from `panelToggle` events
+- **Panel should be sibling of content** - Not a child
+
+## Correct Pattern
+
+```typescript
+@Component({
+  template: `
+    <div class="p-6">
+      <modus-button (buttonClick)="expanded.set(!expanded())">
+        {{ expanded() ? 'Close' : 'Open' }} Panel
+      </modus-button>
+    </div>
+
+    <modus-utility-panel
+      [expanded]="expanded()"
+      className="fixed-utility-panel"
+      position="right"
+      panelWidth="312px"
+    >
+      <div slot="header">Panel Title</div>
+      <div>Panel content</div>
+      <div slot="footer">
+        <modus-button (buttonClick)="expanded.set(false)">Close</modus-button>
+      </div>
+    </modus-utility-panel>
+  `,
+})
+export class PanelComponent {
+  readonly expanded = signal<boolean>(false);
+}
+```
+
+## Reference
+
+For detailed panel patterns and props, fetch the full rule: `modus-angular-utility-panel-usage`

package/templates/angular/.cursor/rules/modus-angular-utility-panel-usage.mdc

@@ -0,0 +1,130 @@
+---
+description: Correct implementation pattern for Modus Utility Panel in Angular
+globs: ["**/*.ts", "**/*.html", "**/*.scss", "**/*.css"]
+alwaysApply: false
+---
+
+## Correct Implementation Pattern Utility Panel
+
+### Demo Page Structure
+
+```typescript
+@Component({
+  selector: 'app-utility-panel-demo',
+  template: `
+    <!-- Main page content -->
+    <div class="p-6">
+      <modus-button (buttonClick)="togglePanel()">
+        {{ expanded() ? 'Close' : 'Open' }} Panel
+      </modus-button>
+
+      <div class="mt-4 bg-card p-4">Main workspace content here</div>
+    </div>
+
+    <!-- Panel OUTSIDE the content flow, at the end of the template -->
+    <modus-utility-panel
+      [expanded]="expanded()"
+      className="fixed-utility-panel"
+      position="right"
+      panelWidth="312px"
+      ariaLabel="Settings panel"
+    >
+      <div slot="header">
+        <div class="flex items-center justify-between w-full">
+          <div class="text-xl font-bold">Panel Title</div>
+          <modus-button
+            size="sm"
+            variant="borderless"
+            icon="close"
+            iconPosition="only"
+            ariaLabel="Close panel"
+            (buttonClick)="closePanel()"
+          />
+        </div>
+      </div>
+
+      <div class="space-y-4">
+        <!-- Panel body content -->
+      </div>
+
+      <div slot="footer" class="flex gap-2 justify-end">
+        <modus-button color="secondary" (buttonClick)="closePanel()"> Cancel </modus-button>
+        <modus-button color="primary" (buttonClick)="save()"> Save </modus-button>
+      </div>
+    </modus-utility-panel>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UtilityPanelDemoComponent {
+  readonly expanded = signal<boolean>(false);
+
+  togglePanel(): void {
+    this.expanded.set(!this.expanded());
+  }
+
+  closePanel(): void {
+    this.expanded.set(false);
+  }
+
+  save(): void {
+    // Save logic
+    this.closePanel();
+  }
+}
+```
+
+## What NOT to Do
+
+### Don't Nest Panel Inside Relative Containers
+
+```html
+<!-- WRONG: Causes layout issues -->
+<div class="relative">
+  <modus-utility-panel [expanded]="expanded()"> ... </modus-utility-panel>
+</div>
+```
+
+### Don't Forget the fixed-utility-panel className
+
+```html
+<!-- WRONG: Panel won't be full height or properly positioned -->
+<modus-utility-panel [expanded]="expanded()">
+
+<!-- CORRECT: Fixed positioning for overlay behavior -->
+<modus-utility-panel [expanded]="expanded()" className="fixed-utility-panel">
+```
+
+### Don't Place Panel in Middle of Template
+
+```html
+<!-- CORRECT: Panel at the END of the template -->
+<div class="header">...</div>
+<div class="content">...</div>
+<div class="footer">...</div>
+
+<modus-utility-panel [expanded]="expanded()" className="fixed-utility-panel"> </modus-utility-panel>
+```
+
+## Props Reference
+
+| Prop            | Type                | Default     | Description                              |
+| --------------- | ------------------- | ----------- | ---------------------------------------- |
+| `expanded`      | `boolean`           | `false`     | Controls panel visibility                |
+| `position`      | `'left' \| 'right'` | `'right'`   | Panel slide-in direction                 |
+| `panelWidth`    | `string`            | `undefined` | Panel width (e.g., '312px', '24rem')     |
+| `className`     | `string`            | `undefined` | CSS class applied to host element        |
+| `ariaLabel`     | `string`            | `undefined` | Accessibility label                      |
+| `pushContent`   | `boolean`           | `false`     | Push main content instead of overlay     |
+
+## Key Takeaways
+
+1. **Always use `className="fixed-utility-panel"`** for overlay panels
+2. **Place the panel at the END of the template**, outside content containers
+3. **Don't use `overflow-hidden`** on parent elements
+4. **Don't nest the panel** inside relative or positioned containers
+5. **Control state from your own buttons**, not from `panelToggle` events
+6. **Panel should be a sibling** of the main content, not a child
+
+---
+
+**Remember**: The utility panel is designed as a fixed overlay that slides in from the edge of the viewport. It must be positioned outside the normal document flow to work correctly.