@julianoczkowski/create-trimble-app 2.0.0

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

@@ -0,0 +1,508 @@
+---
+description: Core React best practices for Modus Design System integration
+globs: ["**/*.tsx", "**/*.ts"]
+alwaysApply: false
+---
+
+# Modus React Best Practices for Vite + SWC
+
+## 🏗️ **Component Architecture**
+
+### ✅ **Single Configurable Component Pattern**
+
+**CRITICAL**: Create **one configurable component** instead of multiple specific components.
+
+```tsx
+// ✅ CORRECT: Single configurable component
+function ModusButton({
+  variant = "primary",
+  size = "md",
+  disabled = false,
+  children,
+  ...props
+}: ModusButtonProps) {
+  const baseClasses =
+    "inline-flex items-center justify-center font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50";
+
+  const variantClasses = {
+    primary: "bg-primary text-primary-foreground hover:bg-primary/90",
+    secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/90",
+    destructive:
+      "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+    outline:
+      "border border-border bg-background hover:bg-muted hover:text-muted-foreground",
+    ghost: "hover:bg-muted hover:text-muted-foreground",
+    link: "text-primary underline-offset-4 hover:underline",
+  };
+
+  const sizeClasses = {
+    sm: "h-9 px-3 text-sm",
+    md: "h-10 px-4 py-2",
+    lg: "h-11 px-8",
+    icon: "h-10 w-10",
+  };
+
+  return (
+    <ModusWcButton
+      className={`${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]}`}
+      disabled={disabled}
+      {...props}
+    >
+      {children}
+    </ModusWcButton>
+  );
+}
+
+// ❌ WRONG: Multiple specific components
+function PrimaryButton({ children, ...props }) {
+  /* ... */
+}
+function SecondaryButton({ children, ...props }) {
+  /* ... */
+}
+function DestructiveButton({ children, ...props }) {
+  /* ... */
+}
+```
+
+### ✅ **Component Composition Pattern**
+
+```tsx
+// ✅ CORRECT: Component composition
+function Card({ children, className, ...props }: CardProps) {
+  return (
+    <div
+      className={`bg-card text-card-foreground border border-border rounded-lg ${className}`}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+function CardHeader({ children, className, ...props }: CardHeaderProps) {
+  return (
+    <div className={`flex flex-col space-y-1.5 p-6 ${className}`} {...props}>
+      {children}
+    </div>
+  );
+}
+
+function CardTitle({ children, className, ...props }: CardTitleProps) {
+  return (
+    <div
+      className={`text-2xl font-semibold leading-none tracking-tight ${className}`}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+function CardContent({ children, className, ...props }: CardContentProps) {
+  return (
+    <div className={`p-6 pt-0 ${className}`} {...props}>
+      {children}
+    </div>
+  );
+}
+
+// Usage
+<Card>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <div>Card content</div>
+  </CardContent>
+</Card>;
+```
+
+## 🎨 **Styling Architecture**
+
+### ✅ **Design System Integration**
+
+```tsx
+// ✅ CORRECT: Design system color usage
+function ThemedComponent() {
+  return (
+    <div className="bg-background text-foreground">
+      <div className="bg-card text-card-foreground border border-border rounded-lg p-4">
+        <div className="text-primary">Primary text</div>
+        <div className="text-secondary">Secondary text</div>
+        <div className="text-muted-foreground">Muted text</div>
+      </div>
+    </div>
+  );
+}
+
+// ❌ WRONG: Generic Tailwind colors
+<div className="bg-blue-500 text-white border-gray-300">Generic colors</div>;
+```
+
+### ✅ **Responsive Design Patterns**
+
+```tsx
+// ✅ CORRECT: Responsive design with design system
+function ResponsiveComponent() {
+  return (
+    <div
+      className="
+      grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4
+      p-4 md:p-6 lg:p-8
+      bg-background text-foreground
+    "
+    >
+      <div className="bg-card text-card-foreground border border-border rounded-lg p-4">
+        <div className="text-lg font-semibold mb-2">Card Title</div>
+        <div className="text-sm text-muted-foreground">Card description</div>
+      </div>
+    </div>
+  );
+}
+```
+
+### ✅ **Interactive States**
+
+```tsx
+// ✅ CORRECT: Interactive states with design system
+function InteractiveComponent() {
+  return (
+    <div
+      className="
+      bg-card text-card-foreground border border-border rounded-lg p-4
+      hover:bg-card/80 hover:shadow-lg
+      focus:ring-2 focus:ring-ring focus:ring-offset-2
+      active:bg-card/90
+      transition-all duration-200
+      cursor-pointer
+    "
+    >
+      Interactive content
+    </div>
+  );
+}
+```
+
+## 🎯 **Modus Web Components Integration**
+
+### ✅ **Event Handling Patterns**
+
+```tsx
+// ✅ CORRECT: Event handling with refs
+function ModusComponent() {
+  const componentRef = useRef<ModusWcButton>(null);
+
+  useEffect(() => {
+    const component = componentRef.current;
+    if (!component) return;
+
+    const handleClick = (event: CustomEvent) => {
+      console.log("Button clicked:", event.detail);
+    };
+
+    component.addEventListener("click", handleClick);
+
+    return () => {
+      component.removeEventListener("click", handleClick);
+    };
+  }, []);
+
+  return <ModusWcButton ref={componentRef}>Click me</ModusWcButton>;
+}
+```
+
+### ✅ **State Management Patterns**
+
+```tsx
+// ✅ CORRECT: State management with Modus components
+function StatefulComponent() {
+  const [isOpen, setIsOpen] = useState(false);
+  const modalRef = useRef<ModusWcModal>(null);
+
+  const openModal = () => {
+    if (modalRef.current) {
+      const dialog = modalRef.current.querySelector(
+        "dialog"
+      ) as HTMLDialogElement;
+      if (dialog) {
+        dialog.showModal();
+        setIsOpen(true);
+      }
+    }
+  };
+
+  const closeModal = () => {
+    if (modalRef.current) {
+      const dialog = modalRef.current.querySelector(
+        "dialog"
+      ) as HTMLDialogElement;
+      if (dialog) {
+        dialog.close();
+        setIsOpen(false);
+      }
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={openModal}>Open Modal</button>
+      <ModusWcModal ref={modalRef}>
+        <div slot="header">Modal Title</div>
+        <div slot="body">Modal content</div>
+        <div slot="footer">
+          <button onClick={closeModal}>Close</button>
+        </div>
+      </ModusWcModal>
+    </div>
+  );
+}
+```
+
+## 🚀 **Vite + React Specific Patterns**
+
+### ✅ **Environment Variables**
+
+```tsx
+// ✅ CORRECT: Environment variables in Vite
+function ApiComponent() {
+  const apiUrl = import.meta.env.VITE_API_URL;
+  const isDevelopment = import.meta.env.DEV;
+
+  return (
+    <div>
+      <div>API URL: {apiUrl}</div>
+      <div>Environment: {isDevelopment ? "Development" : "Production"}</div>
+    </div>
+  );
+}
+```
+
+### ✅ **Dynamic Imports**
+
+```tsx
+// ✅ CORRECT: Dynamic imports for code splitting
+const LazyComponent = lazy(() => import("./LazyComponent"));
+
+function App() {
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <LazyComponent />
+    </Suspense>
+  );
+}
+```
+
+### ✅ **Asset Imports**
+
+```tsx
+// ✅ CORRECT: Asset imports in Vite
+import logoUrl from "./assets/logo.svg";
+import heroImage from "./assets/hero.jpg";
+
+function Header() {
+  return (
+    <div className="flex items-center space-x-4">
+      <img src={logoUrl} alt="Logo" className="h-8 w-8" />
+      <div className="text-xl font-bold text-foreground">App Title</div>
+    </div>
+  );
+}
+```
+
+## 🎨 **Theme Integration**
+
+### ✅ **Theme-Aware Components**
+
+```tsx
+// ✅ CORRECT: Theme-aware component
+function ThemedComponent() {
+  const { theme, isDark, isModern } = useTheme();
+
+  return (
+    <div
+      className={`
+      bg-background text-foreground
+      ${isDark ? "border-border" : "border-border"}
+      transition-colors duration-200
+    `}
+    >
+      <div className="text-foreground">Current theme: {theme}</div>
+      <div className="text-muted-foreground">
+        Mode: {isDark ? "Dark" : "Light"}
+      </div>
+      <div className="text-muted-foreground">
+        Style: {isModern ? "Modern" : "Classic"}
+      </div>
+    </div>
+  );
+}
+```
+
+### ✅ **Conditional Theming**
+
+```tsx
+// ✅ CORRECT: Conditional theming
+function ConditionalThemedComponent() {
+  const { theme } = useTheme();
+
+  const getThemeSpecificContent = () => {
+    switch (theme) {
+      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";
+    }
+  };
+
+  return (
+    <div className="bg-background text-foreground p-4 rounded border border-border">
+      <div className="text-lg font-semibold">{getThemeSpecificContent()}</div>
+    </div>
+  );
+}
+```
+
+## 🔧 **Performance Optimization**
+
+### ✅ **Memoization Patterns**
+
+```tsx
+// ✅ CORRECT: Memoization for expensive components
+const ExpensiveComponent = memo(function ExpensiveComponent({
+  data,
+}: {
+  data: any[];
+}) {
+  const processedData = useMemo(() => {
+    return data.map((item) => ({
+      ...item,
+      processed: item.value * 2,
+    }));
+  }, [data]);
+
+  return (
+    <div className="space-y-2">
+      {processedData.map((item, index) => (
+        <div key={index} className="bg-card text-card-foreground p-2 rounded">
+          {item.processed}
+        </div>
+      ))}
+    </div>
+  );
+});
+```
+
+### ✅ **Lazy Loading Patterns**
+
+```tsx
+// ✅ CORRECT: Lazy loading with Suspense
+const LazyPage = lazy(() => import("./LazyPage"));
+
+function App() {
+  return (
+    <Router>
+      <Routes>
+        <Route
+          path="/lazy"
+          element={
+            <Suspense
+              fallback={
+                <div className="flex items-center justify-center min-h-screen">
+                  <div className="text-foreground">Loading...</div>
+                </div>
+              }
+            >
+              <LazyPage />
+            </Suspense>
+          }
+        />
+      </Routes>
+    </Router>
+  );
+}
+```
+
+## 🚫 **Common Anti-Patterns**
+
+### ❌ **Don't Create Multiple Specific Components**
+
+```tsx
+// ❌ WRONG: Multiple specific components
+function PrimaryButton() {
+  /* ... */
+}
+function SecondaryButton() {
+  /* ... */
+}
+function DestructiveButton() {
+  /* ... */
+}
+
+// ✅ CORRECT: Single configurable component
+function Button({ variant, ...props }) {
+  /* ... */
+}
+```
+
+### ❌ **Don't Use Generic Tailwind Colors**
+
+```tsx
+// ❌ WRONG: Generic Tailwind colors
+<div className="bg-blue-500 text-white border-gray-300">
+  Generic colors
+</div>
+
+// ✅ CORRECT: Design system colors
+<div className="bg-primary text-primary-foreground border-border">
+  Design system colors
+</div>
+```
+
+### ❌ **Don't Mix Color Systems**
+
+```tsx
+// ❌ WRONG: Mixing color systems
+<div className="bg-background text-blue-500 border-red-300">
+  Mixed color systems
+</div>
+
+// ✅ CORRECT: Consistent design system
+<div className="bg-background text-foreground border-border">
+  Consistent design system
+</div>
+```
+
+## 🎯 **Key Takeaways**
+
+1. **Single Configurable Components**: Create one configurable component instead of multiple specific ones
+2. **Design System Colors**: Always use design system colors, never generic Tailwind colors
+3. **Event Handling**: Use refs and event listeners for Modus Web Components
+4. **Theme Integration**: Use theme context for conditional styling and content
+5. **Performance**: Use memoization and lazy loading for optimization
+6. **Vite Patterns**: Use Vite-specific patterns for environment variables and assets
+
+## 🔍 **Best Practices Checklist**
+
+- [ ] ✅ **Single Configurable Components**: One component with variants, not multiple specific components
+- [ ] ✅ **Design System Colors**: Using design system colors exclusively
+- [ ] ✅ **Event Handling**: Proper event handling with refs and listeners
+- [ ] ✅ **Theme Integration**: Theme-aware components with conditional styling
+- [ ] ✅ **Performance**: Memoization and lazy loading where appropriate
+- [ ] ✅ **Vite Patterns**: Using Vite-specific patterns for environment and assets
+- [ ] ✅ **Accessibility**: Proper accessibility with div elements and ARIA attributes
+- [ ] ✅ **Consistency**: Consistent patterns across all components
+
+---
+
+**Remember: This React + Vite application follows a single configurable component pattern with design system integration. Always use design system colors, proper event handling with refs, and theme-aware components. Never use generic Tailwind colors or create multiple specific components.**