@julianoczkowski/create-trimble-app 2.0.0

package/templates/react/.cursor/rules/modus-react-master.mdc

@@ -0,0 +1,160 @@
+---
+description: Master rule providing overview and references to all Modus React rules
+globs: ["**/*.tsx", "**/*.ts", "**/*.css"]
+alwaysApply: true
+---
+
+# Modus React Rules - Master Reference
+
+This master rule provides an overview of all available rules and serves as an entry point for understanding the Modus React development patterns.
+
+## Rule Structure
+
+This project uses a **short/full rule pattern**:
+
+- **Short Rules** (`*-short.mdc`): Always applied, concise summaries
+- **Full Rules** (`*.mdc`): Apply intelligently, detailed patterns
+
+See `README.md` in this directory for complete rule documentation.
+
+## Essential Rules (Always Applied)
+
+These short rules are always included in chat context:
+
+### Design System
+- `modus-color-usage-react-short.mdc` - Color system usage
+- `modus-icons-react-short.mdc` - Icon usage patterns
+- `modus-semantic-html-react-short.mdc` - HTML element usage
+- `border-usage-guidelines-short.mdc` - Border utilities
+- `modus-opacity-utilities-react-short.mdc` - Opacity utilities
+- `modus-tailwind-usage-react-short.mdc` - Tailwind integration
+- `modus-themes-react-short.mdc` - Theme implementation
+
+### Component Patterns
+- `modus-button-group-usage-react-short.mdc` - Button group patterns
+- `modus-checkbox-value-inversion-react-short.mdc` - Checkbox bug handling
+- `modus-modal-implementation-react-short.mdc` - Modal patterns
+- `modus-accordion-state-management-react-short.mdc` - Accordion state
+- `modus-select-vs-dropdown-menu-react-short.mdc` - Dropdown patterns
+- `modus-navbar-side-navigation-react-short.mdc` - Navigation integration
+
+### React Integration
+- `modus-react-integration-short.mdc` - React + Modus integration
+- `modus-react-best-practices-short.mdc` - React best practices
+- `modus-react-key-warnings-short.mdc` - React key prop patterns
+
+### Workflow
+- `development-workflow-react-short.mdc` - Linting and quality checks
+- `chrome-devtools-testing-react-short.mdc` - Browser testing
+- `implementation-guides-react-short.mdc` - Feature development guides
+- `modus-no-emojis-react-short.mdc` - Emoji prohibition
+
+## Detailed Rules (Apply Intelligently)
+
+For detailed patterns, examples, and advanced techniques, reference these full rules:
+
+### Component-Specific Details
+- `modus-button-group-usage-react.mdc` - Complete button group patterns
+- `modus-checkbox-value-inversion-react.mdc` - Checkbox bug details
+- `modus-modal-implementation-react.mdc` - Complete modal implementation
+- `modus-accordion-state-management-react.mdc` - Accordion state management
+- `modus-select-vs-dropdown-menu-react.mdc` - Dropdown comparison
+- `modus-navbar-side-navigation-react.mdc` - Navigation integration details
+
+### Design System Details
+- `modus-color-usage-react.mdc` - Complete color system guide
+- `modus-icons-react.mdc` - Complete icon usage guide
+- `modus-semantic-html-react.mdc` - HTML patterns guide
+- `border-usage-guidelines.mdc` - Complete border utilities guide
+- `modus-opacity-utilities-react.mdc` - Complete opacity utilities guide
+- `modus-tailwind-usage-react.mdc` - Complete Tailwind integration guide
+- `modus-themes-react.mdc` - Complete theme implementation guide
+
+### Integration & Best Practices
+- `modus-react-integration.mdc` - Complete React integration guide
+- `modus-react-best-practices.mdc` - Complete best practices guide
+- `modus-react-key-warnings.mdc` - Complete key prop patterns guide
+- `modus-react-essentials.mdc` - Comprehensive essentials (consolidates multiple topics)
+
+### Workflow & Testing
+- `development-workflow-react.mdc` - Complete workflow guide
+- `chrome-devtools-testing-react.mdc` - Complete testing guide
+- `implementation-guides-react.mdc` - Complete implementation guide structure
+
+### UX Foundations
+- `ux/ux-ui-foundations.mdc` - UI/UX foundations with Modus 2 + Tailwind
+- `ux/gestalt-laws-detailed.mdc` - Gestalt Laws implementation guide
+
+## Reference Files
+
+- `modus-icon-names.mdc` - Complete list of valid Modus icon names
+- `modus-components-reference.mdc` - Component reference guide
+
+## Quick Start Guide
+
+### Working with Components
+
+1. Check component-specific short rule (always applied)
+2. For details, reference full rule: `@modus-[component]-react`
+3. See component reference: `@modus-components-reference`
+
+### Working with Design System
+
+1. Short rules provide essential patterns (always applied)
+2. For details, reference full rule: `@modus-[topic]-react`
+3. For icon names: `@modus-icon-names`
+
+### Common Patterns
+
+**Colors**: Always use design system colors (`bg-background`, `text-foreground`, etc.)
+- Reference: `@modus-color-usage-react`
+
+**Icons**: Use Modus icons exclusively (`<i className="modus-icons">icon-name</i>`)
+- Reference: `@modus-icons-react`
+- Names: `@modus-icon-names`
+
+**Components**: Use wrapper components, not web components directly
+- Reference: `@modus-react-integration`
+
+**State Management**: Let Modus components manage their own state
+- Reference: Component-specific rules
+
+## Rule Application
+
+Rules are applied automatically based on:
+
+1. **Always Apply**: Short rules with `alwaysApply: true`
+2. **File Patterns**: Rules activate when working with matching files (`globs`)
+3. **Context Matching**: Agent applies rules based on description relevance
+4. **Manual Reference**: Use `@rule-name` to explicitly reference a rule
+
+## Best Practices
+
+When working with Modus React:
+
+1. **Follow Short Rules**: Essential patterns are always available
+2. **Reference Full Rules**: Use `@rule-name` for detailed guidance
+3. **Check Component Reference**: See `@modus-components-reference` for component details
+4. **Verify Icon Names**: Check `@modus-icon-names` before using icons
+5. **Run Linting**: Use `npm run lint:all` before committing
+
+## Getting Help
+
+- **Rule Documentation**: See `README.md` in this directory
+- **Project Guide**: See `CLAUDE.md` in project root
+- **Component Reference**: `@modus-components-reference`
+- **Icon Names**: `@modus-icon-names`
+
+## Rule Maintenance
+
+When adding or updating rules:
+
+1. Create/update short rule with `alwaysApply: true`
+2. Create/update full rule with `alwaysApply: false`
+3. Ensure descriptions match between short and full
+4. Add appropriate `globs:` patterns
+5. Update `README.md` with new rule entry
+
+---
+
+**Note**: This master rule is always applied to provide rule overview. For specific guidance, reference the appropriate detailed rule using `@rule-name` syntax.

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

@@ -0,0 +1,23 @@
+---
+description: Use ModusDropdownMenu instead of ModusSelect for reliable event handling
+globs: ["**/components/ModusSelect*.tsx", "**/components/ModusDropdownMenu*.tsx", "**/demos/**/page.tsx"]
+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 React
+- **Reliable itemSelect events** - ModusDropdownMenu provides consistent event handling
+- **Proper state management** - Use React state to track selected values and visibility
+- **Programmatic control** - Use refs to control dropdown visibility
+- **Event handling patterns** - Handle `itemSelect` events for selection changes
+- **Test thoroughly** - Verify dropdown behavior and event handling
+- **Use established patterns** - Follow ModusDropdownMenu component patterns
+
+## Reference
+
+For detailed component comparison, implementation patterns, and advanced usage, fetch the full rule: `modus-select-vs-dropdown-menu-react`

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

@@ -0,0 +1,442 @@
+---
+description: Use ModusDropdownMenu instead of ModusSelect for reliable event handling
+globs: ["**/components/ModusSelect*.tsx", "**/components/ModusDropdownMenu*.tsx", "**/demos/**/page.tsx"]
+alwaysApply: false
+---
+
+# ModusSelect vs ModusDropdownMenu in React
+
+## 🚨 **CRITICAL: ModusSelect Reliability Issues**
+
+**Problem**: `ModusSelect` component has unreliable event handling in React applications, especially with Chrome DevTools automation and testing.
+
+**Root Cause**: `ModusSelect` events are inconsistent and may not fire reliably in React environments.
+
+**Solution**: Use `ModusDropdownMenu` with `itemSelect` events, which are more reliable and consistent.
+
+## ❌ **Common Anti-Patterns**
+
+### ❌ **Using ModusSelect (Unreliable)**
+
+```tsx
+// ❌ WRONG: ModusSelect with unreliable events
+function UnreliableSelect() {
+  const [selectedValue, setSelectedValue] = useState("");
+
+  const options = [
+    { label: "Option 1", value: "option1" },
+    { label: "Option 2", value: "option2" },
+    { label: "Option 3", value: "option3" },
+  ];
+
+  const handleInputChange = (event: CustomEvent<InputEvent>) => {
+    // ❌ This event may not fire reliably in React
+    console.log("Select changed:", event.target.value);
+    setSelectedValue(event.target.value);
+  };
+
+  return (
+    <ModusSelect
+      options={options}
+      value={selectedValue}
+      onInputChange={handleInputChange} // ❌ Unreliable event
+      label="Select an option"
+    />
+  );
+}
+```
+
+### ❌ **Direct Event Handling**
+
+```tsx
+// ❌ WRONG: Direct event handling
+function DirectEventHandling() {
+  const options = [
+    { label: "Option 1", value: "1" },
+    { label: "Option 2", value: "2" },
+  ];
+
+  const handleInputChange = (event: CustomEvent<InputEvent>) => {
+    // ❌ This may not work consistently in React
+    const value = event.target.value;
+    console.log("Selected:", value);
+  };
+
+  return <ModusSelect options={options} onInputChange={handleInputChange} />;
+}
+```
+
+## ✅ **Correct Patterns**
+
+### ✅ **Use ModusDropdownMenu (Reliable)**
+
+```tsx
+// ✅ CORRECT: ModusDropdownMenu with reliable events
+function ReliableDropdown() {
+  const [selectedValue, setSelectedValue] = useState("");
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<HTMLModusWcDropdownMenuElement>(null);
+
+  const handleItemSelect = (event: CustomEvent<{ value: string }>) => {
+    // ✅ CORRECT: Reliable itemSelect event
+    const value = event.detail.value;
+    console.log("Item selected:", value);
+    setSelectedValue(value);
+    setIsOpen(false);
+  };
+
+  const toggleDropdown = () => {
+    if (dropdownRef.current) {
+      dropdownRef.current.menuVisible = !isOpen;
+      setIsOpen(!isOpen);
+    }
+  };
+
+  const menuItems = [
+    { label: "Option 1", value: "option1" },
+    { label: "Option 2", value: "option2" },
+    { label: "Option 3", value: "option3" },
+  ];
+
+  return (
+    <ModusDropdownMenu
+      ref={dropdownRef}
+      menuVisible={isOpen}
+      onItemSelect={handleItemSelect}
+      buttonContent={
+        <ModusWcButton onClick={toggleDropdown}>
+          {selectedValue || "Select an option"}
+        </ModusWcButton>
+      }
+      menuItems={menuItems}
+    />
+  );
+}
+```
+
+### ✅ **Reusable Dropdown Hook**
+
+```tsx
+// ✅ CORRECT: Reusable dropdown hook
+function useDropdown() {
+  const [selectedValue, setSelectedValue] = useState("");
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<HTMLModusWcDropdownMenuElement>(null);
+
+  const handleItemSelect = (event: CustomEvent<{ value: string }>) => {
+    const value = event.detail.value;
+    setSelectedValue(value);
+    setIsOpen(false);
+  };
+
+  const toggleDropdown = () => {
+    if (dropdownRef.current) {
+      dropdownRef.current.menuVisible = !isOpen;
+      setIsOpen(!isOpen);
+    }
+  };
+
+  const closeDropdown = () => {
+    if (dropdownRef.current) {
+      dropdownRef.current.menuVisible = false;
+      setIsOpen(false);
+    }
+  };
+
+  return {
+    selectedValue,
+    isOpen,
+    dropdownRef,
+    handleItemSelect,
+    toggleDropdown,
+    closeDropdown,
+  };
+}
+
+// ✅ CORRECT: Use the hook
+function DropdownComponent() {
+  const {
+    selectedValue,
+    isOpen,
+    dropdownRef,
+    handleItemSelect,
+    toggleDropdown,
+  } = useDropdown();
+
+  const menuItems = [
+    { label: "Option 1", value: "option1" },
+    { label: "Option 2", value: "option2" },
+    { label: "Option 3", value: "option3" },
+  ];
+
+  return (
+    <ModusDropdownMenu
+      ref={dropdownRef}
+      menuVisible={isOpen}
+      onItemSelect={handleItemSelect}
+      buttonContent={
+        <ModusWcButton onClick={toggleDropdown}>
+          {selectedValue || "Select an option"}
+        </ModusWcButton>
+      }
+      menuItems={menuItems}
+    />
+  );
+}
+```
+
+## 🎯 **Advanced Patterns**
+
+### ✅ **Dropdown with Search**
+
+```tsx
+// ✅ CORRECT: Dropdown with search functionality
+function SearchableDropdown() {
+  const [selectedValue, setSelectedValue] = useState("");
+  const [searchTerm, setSearchTerm] = useState("");
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<ModusWcDropdownMenu>(null);
+
+  const options = [
+    { value: "apple", label: "Apple" },
+    { value: "banana", label: "Banana" },
+    { value: "cherry", label: "Cherry" },
+    { value: "date", label: "Date" },
+    { value: "elderberry", label: "Elderberry" },
+  ];
+
+  const filteredOptions = options.filter((option) =>
+    option.label.toLowerCase().includes(searchTerm.toLowerCase())
+  );
+
+  const handleItemSelect = (event: CustomEvent) => {
+    const value = event.detail;
+    setSelectedValue(value);
+    setIsOpen(false);
+    setSearchTerm("");
+  };
+
+  const toggleDropdown = () => {
+    if (dropdownRef.current) {
+      const dropdown = dropdownRef.current.querySelector(
+        "modus-dropdown-menu"
+      ) as any;
+      if (dropdown) {
+        if (isOpen) {
+          dropdown.close();
+        } else {
+          dropdown.open();
+        }
+        setIsOpen(!isOpen);
+      }
+    }
+  };
+
+  return (
+    <div className="space-y-2">
+      <ModusWcButton onClick={toggleDropdown}>
+        {selectedValue || "Select an option"}
+      </ModusWcButton>
+
+      <ModusWcDropdownMenu ref={dropdownRef} onItemSelect={handleItemSelect}>
+        <div className="p-2">
+          <input
+            type="text"
+            placeholder="Search options..."
+            value={searchTerm}
+            onChange={(e) => setSearchTerm(e.target.value)}
+            className="w-full px-3 py-2 border border-input rounded bg-input text-foreground"
+          />
+        </div>
+
+        {filteredOptions.map((option) => (
+          <ModusWcDropdownMenuItem key={option.value} value={option.value}>
+            {option.label}
+          </ModusWcDropdownMenuItem>
+        ))}
+      </ModusWcDropdownMenu>
+    </div>
+  );
+}
+```
+
+### ✅ **Multi-Select Dropdown**
+
+```tsx
+// ✅ CORRECT: Multi-select dropdown
+function MultiSelectDropdown() {
+  const [selectedValues, setSelectedValues] = useState<string[]>([]);
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<ModusWcDropdownMenu>(null);
+
+  const options = [
+    { value: "option1", label: "Option 1" },
+    { value: "option2", label: "Option 2" },
+    { value: "option3", label: "Option 3" },
+    { value: "option4", label: "Option 4" },
+  ];
+
+  const handleItemSelect = (event: CustomEvent) => {
+    const value = event.detail;
+    setSelectedValues((prev) => {
+      if (prev.includes(value)) {
+        return prev.filter((v) => v !== value);
+      } else {
+        return [...prev, value];
+      }
+    });
+  };
+
+  const toggleDropdown = () => {
+    if (dropdownRef.current) {
+      const dropdown = dropdownRef.current.querySelector(
+        "modus-dropdown-menu"
+      ) as any;
+      if (dropdown) {
+        if (isOpen) {
+          dropdown.close();
+        } else {
+          dropdown.open();
+        }
+        setIsOpen(!isOpen);
+      }
+    }
+  };
+
+  return (
+    <div className="space-y-2">
+      <ModusWcButton onClick={toggleDropdown}>
+        {selectedValues.length > 0
+          ? `${selectedValues.length} selected`
+          : "Select options"}
+      </ModusWcButton>
+
+      <ModusWcDropdownMenu ref={dropdownRef} onItemSelect={handleItemSelect}>
+        {options.map((option) => (
+          <ModusWcDropdownMenuItem
+            key={option.value}
+            value={option.value}
+            className={
+              selectedValues.includes(option.value)
+                ? "bg-primary text-primary-foreground"
+                : ""
+            }
+          >
+            {option.label}
+          </ModusWcDropdownMenuItem>
+        ))}
+      </ModusWcDropdownMenu>
+    </div>
+  );
+}
+```
+
+## 🔧 **Testing Patterns**
+
+### ✅ **Test Dropdown Reliability**
+
+```tsx
+// ✅ CORRECT: Test dropdown reliability
+function DropdownTest() {
+  const [testResults, setTestResults] = useState<string[]>([]);
+  const dropdownRef = useRef<ModusWcDropdownMenu>(null);
+
+  const testDropdown = () => {
+    if (dropdownRef.current) {
+      const dropdown = dropdownRef.current.querySelector(
+        "modus-dropdown-menu"
+      ) as any;
+      if (dropdown) {
+        dropdown.open();
+        setTestResults((prev) => [...prev, "Dropdown opened"]);
+
+        setTimeout(() => {
+          dropdown.close();
+          setTestResults((prev) => [...prev, "Dropdown closed"]);
+        }, 1000);
+      }
+    }
+  };
+
+  const handleItemSelect = (event: CustomEvent) => {
+    const value = event.detail;
+    setTestResults((prev) => [...prev, `Item selected: ${value}`]);
+  };
+
+  return (
+    <div className="space-y-4">
+      <ModusWcButton onClick={testDropdown}>Test Dropdown</ModusWcButton>
+
+      <ModusWcDropdownMenu ref={dropdownRef} onItemSelect={handleItemSelect}>
+        <ModusWcDropdownMenuItem value="test1">
+          Test Option 1
+        </ModusWcDropdownMenuItem>
+        <ModusWcDropdownMenuItem value="test2">
+          Test Option 2
+        </ModusWcDropdownMenuItem>
+      </ModusWcDropdownMenu>
+
+      <div>
+        <h3>Test Results:</h3>
+        {testResults.map((result, index) => (
+          <div key={index}>{result}</div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## 🚫 **What NOT to Do**
+
+### ❌ **Don't Use ModusSelect**
+
+```tsx
+// ❌ WRONG: Don't use ModusSelect
+const options = [{ label: "Option 1", value: "1" }];
+<ModusSelect options={options} onInputChange={handleChange} />;
+```
+
+### ❌ **Don't Rely on ModusSelect Events**
+
+```tsx
+// ❌ WRONG: Don't rely on ModusSelect events
+const handleInputChange = (event: CustomEvent<InputEvent>) => {
+  // This may not fire reliably in React
+  setValue(event.target.value);
+};
+```
+
+### ❌ **Don't Mix Select and Dropdown**
+
+```tsx
+// ❌ WRONG: Don't mix select and dropdown
+<div>
+  <ModusSelect options={options} onInputChange={handleSelect} />
+  {/* ❌ Unreliable */}
+
+  <ModusDropdownMenu menuItems={menuItems} onItemSelect={handleDropdown} />
+  {/* ✅ Reliable */}
+</div>
+```
+
+## 🎯 **Key Takeaways**
+
+1. **Use ModusDropdownMenu**: Always use `ModusDropdownMenu` instead of `ModusSelect`
+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 refs
+5. **Testing**: Test dropdown functionality thoroughly
+
+## 🔍 **Dropdown Implementation Checklist**
+
+- [ ] ✅ **Use ModusDropdownMenu**: Never use ModusSelect
+- [ ] ✅ **Event Handling**: Use itemSelect events for reliability
+- [ ] ✅ **Programmatic Control**: Use menuVisible property for control
+- [ ] ✅ **State Management**: Proper state management with React
+- [ ] ✅ **Testing**: Test dropdown functionality and events
+- [ ] ✅ **Accessibility**: Ensure proper accessibility with dropdown
+
+---
+
+**Remember: ModusSelect has unreliable event handling in React applications. Always use ModusDropdownMenu with itemSelect events for reliable dropdown functionality. Use menuVisible property for programmatic control and proper event handling patterns.**

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

@@ -0,0 +1,23 @@
+---
+description: Use div elements exclusively to avoid Tailwind CSS conflicts
+globs: ["**/*.tsx"]
+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
+- **Accessibility with divs** - Ensure proper accessibility with div elements
+- **Test rendering** - Verify components render correctly in all themes
+
+## Reference
+
+For detailed HTML patterns, accessibility guidelines, and advanced div usage, fetch the full rule: `modus-semantic-html-react`