@julianoczkowski/create-trimble-app 2.0.0

package/templates/react/.cursor/rules/modus-navbar-side-navigation-react-short.mdc

@@ -0,0 +1,23 @@
+---
+description: Critical integration patterns for Modus Navbar with Side Navigation in React
+globs: ["**/components/ModusNavbar*.tsx", "**/components/ModusSideNavigation*.tsx", "**/demos/**/page.tsx"]
+alwaysApply: true
+---
+
+# Modus Navbar + Side Navigation - Short
+
+Critical integration patterns for Modus Navbar with Side Navigation in React.
+
+## Key Rules
+
+- **Use ModusNavbar wrapper component** - Never use `ModusWcNavbar` directly
+- **Pass props as native React objects** - Wrapper handles serialization
+- **Sync via ref and state** - Set `expanded` on ref AND track in React state
+- **Position side navigation absolutely** - Use `position: absolute`, `z-index: 999`
+- **Account for collapsed width** - Add `margin-left: 4rem` to panel content
+- **Listen for expandedChange events** - Keep React state in sync with web component
+- **Collapse sub-menus when nav closes** - Reset sub-menu states on collapse
+
+## Reference
+
+For detailed patterns, layout structure, and common pitfalls, fetch the full rule: `modus-navbar-side-navigation-react`

package/templates/react/.cursor/rules/modus-navbar-side-navigation-react.mdc

@@ -0,0 +1,247 @@
+---
+description: Critical integration patterns for Modus Navbar with Side Navigation in React
+globs: ["**/components/ModusNavbar*.tsx", "**/components/ModusSideNavigation*.tsx", "**/demos/**/page.tsx"]
+alwaysApply: false
+---
+
+# Modus Navbar + Side Navigation Integration
+
+Critical patterns for integrating `ModusWcNavbar` with `ModusWcSideNavigation` in React applications.
+
+## Key Rules
+
+- **Use the ModusNavbar wrapper component** - Never use `ModusWcNavbar` directly
+- **Pass props as native React objects** - Wrapper handles serialization
+- **Sync navbar hamburger menu with side navigation** - Use `onMainMenuOpenChange` callback
+- **Position side navigation absolutely** - Required for proper layering
+- **Set explicit z-index** - Ensure side navigation renders above content
+
+---
+
+## DO: Use ModusNavbar Wrapper Component
+
+The `ModusNavbar` wrapper component handles prop serialization and event binding correctly.
+
+```tsx
+// DO: Use the wrapper component
+import ModusNavbar from "../../components/ModusNavbar";
+
+<ModusNavbar
+  userCard={userCard}
+  visibility={{ mainMenu: true, user: true }}
+  onMainMenuOpenChange={handleNavbarMenuOpenChange}
+/>;
+```
+
+## DON'T: Use ModusWcNavbar Directly
+
+Direct usage causes prop serialization issues.
+
+```tsx
+// DON'T: Direct usage won't work properly
+import { ModusWcNavbar } from "@trimble-oss/moduswebcomponents-react";
+
+<ModusWcNavbar
+  user-card={JSON.stringify(userCard)} // Won't work!
+  visibility={JSON.stringify({ mainMenu: true })} // Won't work!
+/>;
+```
+
+---
+
+## DO: Sync Navbar with Side Navigation via Ref
+
+Use a ref to directly set the `expanded` property on the side navigation.
+
+```tsx
+const [navbarMenuExpanded, setNavbarMenuExpanded] = useState(false);
+const sideNavRef = useRef<any>(null);
+
+const handleNavbarMenuOpenChange = useCallback((isOpen: boolean) => {
+  setNavbarMenuExpanded(isOpen);
+
+  // Directly set expanded property on the web component
+  const sideNav = sideNavRef.current;
+  if (sideNav) {
+    sideNav.expanded = isOpen;
+  }
+}, []);
+
+<ModusNavbar
+  onMainMenuOpenChange={handleNavbarMenuOpenChange}
+/>
+
+<ModusWcSideNavigation
+  ref={sideNavRef}
+  expanded={navbarMenuExpanded}
+/>
+```
+
+## DON'T: Rely Only on React State
+
+React state alone won't trigger the web component to expand.
+
+```tsx
+// DON'T: This alone won't work
+const [expanded, setExpanded] = useState(false);
+
+const handleMenuOpen = (isOpen: boolean) => {
+  setExpanded(isOpen); // Web component won't update!
+};
+
+<ModusWcSideNavigation expanded={expanded} />; // May not respond
+```
+
+---
+
+## DO: Position Side Navigation Absolutely with Z-Index
+
+Side navigation uses `position: absolute` internally. Set proper CSS.
+
+```css
+.main-content-row {
+  display: flex;
+  flex: 1;
+  position: relative; /* Creates positioning context */
+  min-height: 500px;
+}
+
+.side-navigation {
+  position: absolute;
+  left: 0;
+  top: 0;
+  height: 100%;
+  z-index: 999; /* Ensure above content */
+}
+
+.panel-content {
+  flex: 1;
+  padding: 1.5rem;
+  margin-left: 4rem; /* Account for collapsed nav width */
+}
+```
+
+## DON'T: Use Relative Positioning
+
+Relative positioning causes the side navigation to be hidden by other content.
+
+```css
+/* DON'T: Side nav will be hidden */
+.side-navigation {
+  position: relative; /* Wrong! */
+}
+```
+
+---
+
+## DO: Listen for expandedChange Events
+
+Keep React state in sync with web component state changes.
+
+```tsx
+useEffect(() => {
+  const sideNav = sideNavRef.current;
+  if (!sideNav) return;
+
+  const handleExpandedChange = (e: Event) => {
+    const customEvent = e as CustomEvent<boolean>;
+    setNavbarMenuExpanded(customEvent.detail);
+  };
+
+  sideNav.addEventListener("expandedChange", handleExpandedChange);
+
+  return () => {
+    sideNav.removeEventListener("expandedChange", handleExpandedChange);
+  };
+}, []);
+```
+
+---
+
+## DO: Use Correct User Card Structure
+
+```tsx
+const userCard = {
+  name: "John Doe",
+  email: "john.doe@example.com",
+  avatarSrc: "", // Optional
+  avatarAlt: "User Avatar", // Optional
+};
+```
+
+---
+
+## DO: Handle Sub-Menu State When Side Nav Collapses
+
+Collapse all sub-menus when the side navigation closes.
+
+```tsx
+const [subMenuStates, setSubMenuStates] = useState<Record<string, boolean>>({
+  charts: false,
+  maps: false,
+});
+
+const collapseAllSubMenus = () => {
+  setSubMenuStates({
+    charts: false,
+    maps: false,
+  });
+};
+
+const handleNavbarMenuOpenChange = useCallback((isOpen: boolean) => {
+  setNavbarMenuExpanded(isOpen);
+
+  if (!isOpen) {
+    collapseAllSubMenus(); // Reset sub-menus when collapsing
+  }
+}, []);
+```
+
+---
+
+## Required Layout Structure
+
+```tsx
+<div className="layout-with-navbar">
+  <ModusNavbar
+    userCard={userCard}
+    visibility={{ mainMenu: true, user: true }}
+    onMainMenuOpenChange={handleNavbarMenuOpenChange}
+  />
+
+  <div className="main-content-row">
+    <ModusWcSideNavigation
+      ref={sideNavRef}
+      expanded={navbarMenuExpanded}
+      collapse-on-click-outside={true}
+      max-width="256px"
+      mode="push"
+      className="side-navigation"
+    >
+      <ModusWcMenu>
+        <ModusWcMenuItem label="Home" value="home">
+          <ModusWcIcon slot="start-icon" name="home" decorative={true} />
+        </ModusWcMenuItem>
+      </ModusWcMenu>
+    </ModusWcSideNavigation>
+
+    <div className="panel-content">{/* Main content here */}</div>
+  </div>
+</div>
+```
+
+---
+
+## Common Pitfalls
+
+1. **Hamburger menu not visible** - Use `ModusNavbar` wrapper, not `ModusWcNavbar` directly
+2. **Side nav expands then immediately collapses** - Bind `expanded` prop to React state and set via ref
+3. **Side nav hidden by content** - Use `position: absolute` and `z-index: 999`
+4. **Events not firing** - Use `addEventListener` for web component custom events
+5. **Props not updating** - Set properties directly on the ref for web components
+
+---
+
+## Reference Implementation
+
+See `/src/demos/side-navigation-demo/page.tsx` for complete working examples.

package/templates/react/.cursor/rules/modus-no-emojis-react-short.mdc

@@ -0,0 +1,23 @@
+---
+description: Strict prohibition of emojis in React + Vite application
+globs: ["**/*.tsx", "**/*.ts", "**/*.md"]
+alwaysApply: true
+---
+
+# Modus No Emojis - Short
+
+Strict prohibition of emojis in React + Vite application.
+
+## Key Rules
+
+- **Never use emojis in code** - No emoji characters in any code files
+- **Never use emojis in components** - No emoji in JSX, content, or UI elements
+- **Never use emojis in content** - No emoji in text, descriptions, or user-facing content
+- **Use Modus icons instead** - Replace emojis with appropriate Modus icons
+- **Use Unicode characters for symbols** - Use proper Unicode symbols when needed
+- **Check all content** - Verify no emojis in comments, strings, or documentation
+- **Use linting to catch violations** - Automated checks for emoji usage
+
+## Reference
+
+For detailed emoji prohibition guidelines, icon replacement patterns, and linting setup, fetch the full rule: `modus-no-emojis-react`

package/templates/react/.cursor/rules/modus-opacity-utilities-react-short.mdc

@@ -0,0 +1,70 @@
+---
+description: Essential opacity utilities for Modus Design System colors in React + Vite
+globs: ["**/*.tsx", "**/*.css"]
+alwaysApply: true
+---
+
+# Modus Opacity Utilities - Short
+
+Essential opacity utilities for Modus Design System colors in React + 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 index.css** - No Tailwind config changes needed
+- **Respects theme switching** - Works in all 6 Modus themes
+- **Use semantic color names** - `foreground`, `primary`, `destructive`, etc.
+
+## Available Utilities
+
+### 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`
+
+### 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
+
+```tsx
+// ❌ This doesn't work with CSS variables
+<div className="text-foreground/80">Text with 80% opacity</div>
+
+// ✅ Use custom opacity utilities
+<div className="text-foreground-80">Text with 80% opacity</div>
+<div className="bg-primary-60">Primary background with 60% opacity</div>
+<div className="border border-destructive-40">Destructive border with 40% opacity</div>
+```
+
+## Common Patterns
+
+```tsx
+// Text hierarchy
+<div className="text-foreground">Main heading (100%)</div>
+<div className="text-foreground-80">Subheading (80%)</div>
+<div className="text-muted-foreground-60">Description (60%)</div>
+
+// Interactive states
+<button className="bg-primary hover:bg-primary-80 transition-colors">
+  Hover with opacity
+</button>
+
+// Overlay effects
+<div className="bg-foreground-20 absolute inset-0 rounded-lg"></div>
+```
+
+## Reference
+
+For detailed implementation patterns, migration guide, and advanced techniques, fetch the full rule: `modus-opacity-utilities-react`

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

@@ -0,0 +1,208 @@
+---
+description: Essential opacity utilities for Modus Design System colors in React + Vite
+globs: ["**/*.tsx", "**/*.css"]
+alwaysApply: false
+---
+
+# Modus Opacity Utilities - React
+
+Essential opacity utilities for Modus Design System colors in React + 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 index.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
+
+```tsx
+// ❌ This doesn't work with CSS variables
+<div className="text-foreground/80">Text with 80% opacity</div>
+
+// ✅ Use custom opacity utilities
+<div className="text-foreground-80">Text with 80% opacity</div>
+<div className="text-primary-60">Primary text with 60% opacity</div>
+<div className="text-muted-foreground-40">Muted text with 40% opacity</div>
+```
+
+### Background Opacity
+
+```tsx
+// ✅ Background opacity utilities
+<div className="bg-primary-80">Primary background with 80% opacity</div>
+<div className="bg-destructive-60">Destructive background with 60% opacity</div>
+<div className="bg-warning-40">Warning background with 40% opacity</div>
+```
+
+### Border Opacity
+
+```tsx
+// ✅ Border opacity utilities
+<div className="border border-primary-80">Primary border with 80% opacity</div>
+<div className="border border-destructive-60">Destructive border with 60% opacity</div>
+<div className="border border-success-40">Success border with 40% opacity</div>
+```
+
+### Combined Usage
+
+```tsx
+// ✅ Mix opacity utilities with other classes
+<div className="p-4 bg-card border border-primary-40 rounded-lg">
+  <div className="text-foreground-80 mb-2">Title with 80% opacity</div>
+  <div className="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
+
+```tsx
+<div className="space-y-2">
+  <div className="text-foreground">Main heading (100%)</div>
+  <div className="text-foreground-80">Subheading (80%)</div>
+  <div className="text-muted-foreground-60">Description (60%)</div>
+  <div className="text-muted-foreground-40">Caption (40%)</div>
+</div>
+```
+
+### Interactive States
+
+```tsx
+<button className="bg-primary hover:bg-primary-80 transition-colors">
+  Hover with opacity
+</button>
+```
+
+### Overlay Effects
+
+```tsx
+<div className="relative">
+  <div className="bg-foreground-20 absolute inset-0 rounded-lg"></div>
+  <div className="relative z-10 p-4">Content with overlay</div>
+</div>
+```
+
+## Browser Support
+
+- **color-mix()** - Supported in all modern browsers (Chrome 111+, Firefox 113+, Safari 16.2+)
+- **Fallback** - Gracefully degrades to full opacity in older browsers
+- **Progressive enhancement** - Works without JavaScript
+
+## Performance
+
+- **CSS-only solution** - No JavaScript overhead
+- **Efficient rendering** - Uses native CSS color-mix() function
+- **Theme-aware** - Automatically updates with theme changes
+- **No runtime calculations** - Pre-computed opacity values
+
+## Migration Guide
+
+### From Tailwind /80 syntax
+
+```tsx
+// ❌ Old (doesn't work with CSS variables)
+<div className="text-foreground/80">Text</div>
+<div className="bg-primary/60">Background</div>
+<div className="border-destructive/40">Border</div>
+
+// ✅ New (works with design system)
+<div className="text-foreground-80">Text</div>
+<div className="bg-primary-60">Background</div>
+<div className="border-destructive-40">Border</div>
+```
+
+### From inline styles
+
+```tsx
+// ❌ Old (not theme-aware)
+<div style={{ color: 'rgba(0, 0, 0, 0.8)' }}>Text</div>
+
+// ✅ New (theme-aware)
+<div className="text-foreground-80">Text</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
+- **Document opacity choices** - Explain why specific opacity levels are used
+
+## Troubleshooting
+
+### Opacity not working
+
+- Check if using custom utilities (`text-foreground-80`) not Tailwind syntax (`text-foreground/80`)
+- Verify CSS custom properties are defined in `index.css`
+- Ensure browser supports `color-mix()` function
+
+### Theme switching issues
+
+- Opacity utilities automatically respect theme changes
+- No additional configuration needed for theme switching
+- Test in both light and dark modes
+
+### Performance concerns
+
+- Opacity utilities are CSS-only and highly performant
+- No JavaScript calculations or runtime overhead
+- Uses native browser color-mix() function
+
+## Reference
+
+This rule provides comprehensive opacity utilities for Modus Design System colors, ensuring consistent and theme-aware opacity effects throughout the React application.

package/templates/react/.cursor/rules/modus-react-best-practices-short.mdc

@@ -0,0 +1,23 @@
+---
+description: Core React best practices for Modus Design System integration
+globs: ["**/*.tsx", "**/*.ts"]
+alwaysApply: true
+---
+
+# Modus React Best Practices - Short
+
+Core React best practices for Modus Design System integration.
+
+## Key Rules
+
+- **Single configurable components** - One component with variants, not multiple specific components
+- **Use design system colors only** - Never use generic Tailwind colors or hardcoded values
+- **Component composition pattern** - Build complex components from smaller, reusable pieces
+- **Event handling with refs** - Use refs and event listeners for Modus Web Components
+- **Theme-aware components** - Use theme context for conditional styling and content
+- **Performance optimization** - Use memoization and lazy loading where appropriate
+- **Vite-specific patterns** - Use environment variables, dynamic imports, and asset imports
+
+## Reference
+
+For detailed component patterns, styling architecture, and advanced React techniques, fetch the full rule: `modus-react-best-practices`