@julianoczkowski/create-trimble-app 2.0.0

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

@@ -0,0 +1,445 @@
+---
+description: Essential state management patterns for Modus Accordion components in React
+globs: ["**/components/ModusAccordion*.tsx", "**/demos/**/page.tsx"]
+alwaysApply: false
+---
+
+# Modus Accordion State Management in React
+
+## 🚨 **IMPORTANT: Accordion State Management Guidelines**
+
+**Key Principle**: Modus Web Components (`ModusWcAccordion`, `ModusWcCollapse`) are designed to manage their own state, but they DO support controlled state when needed.
+
+**Best Practice**: Use the `expanded` attribute on `ModusWcCollapse` components for initial state or programmatic control, but avoid trying to synchronize React state with Modus state in real-time.
+
+## ❌ **Common Anti-Patterns**
+
+### ❌ **Real-time State Synchronization**
+
+```tsx
+// ❌ WRONG: Trying to sync React state with Modus state in real-time
+function AccordionComponent() {
+  const [isExpanded, setIsExpanded] = useState(false);
+
+  return (
+    <ModusWcAccordion
+      onExpandedChange={(e) => setIsExpanded(e.detail.expanded)} // ❌ Creates state loop
+    >
+      <ModusWcCollapse expanded={isExpanded}>
+        {" "}
+        {/* ❌ This causes conflicts */}
+        <div slot="content">Content</div>
+      </ModusWcCollapse>
+    </ModusWcAccordion>
+  );
+}
+```
+
+### ❌ **Complex State Synchronization**
+
+```tsx
+// ❌ WRONG: Complex state synchronization that can cause loops
+function MyComponent() {
+  const [accordionStates, setAccordionStates] = useState({
+    accordion1: false,
+    accordion2: true,
+    accordion3: false,
+  });
+
+  const toggleAccordion = (id: string) => {
+    setAccordionStates((prev) => ({
+      ...prev,
+      [id]: !prev[id],
+    }));
+  };
+
+  return (
+    <div>
+      {Object.entries(accordionStates).map(([id, isExpanded]) => (
+        <ModusWcAccordion
+          key={id}
+          onExpandedChange={() => toggleAccordion(id)} // ❌ Creates state loops
+        >
+          <ModusWcCollapse expanded={isExpanded}>
+            {" "}
+            {/* ❌ This can cause conflicts */}
+            <div slot="content">Content for {id}</div>
+          </ModusWcCollapse>
+        </ModusWcAccordion>
+      ))}
+    </div>
+  );
+}
+```
+
+## ✅ **Correct Patterns**
+
+### ✅ **Let Modus Components Manage Their Own State**
+
+```tsx
+// ✅ CORRECT: Let Modus accordion manage its own state
+function AccordionComponent() {
+  return (
+    <ModusWcAccordion>
+      <ModusWcCollapse
+        collapse-id="item1"
+        options={{
+          title: "Item One",
+          description: "First accordion item",
+          icon: "star",
+        }}
+      >
+        <div slot="content">Content for item one.</div>
+      </ModusWcCollapse>
+    </ModusWcAccordion>
+  );
+}
+```
+
+### ✅ **Initial State Control (Recommended)**
+
+```tsx
+// ✅ CORRECT: Set initial state without real-time synchronization
+function AccordionComponent() {
+  return (
+    <ModusWcAccordion>
+      <ModusWcCollapse
+        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>
+      </ModusWcCollapse>
+    </ModusWcAccordion>
+  );
+}
+```
+
+### ✅ **Listen to Events for Tracking (Not Control)**
+
+```tsx
+// ✅ CORRECT: Listen to events for tracking, don't control state
+function AccordionComponent() {
+  const [trackingData, setTrackingData] = useState({
+    accordionOpened: false,
+    openCount: 0,
+  });
+
+  const handleAccordionChange = (
+    event: CustomEvent<{ expanded: boolean; index: number }>
+  ) => {
+    const { expanded, index } = event.detail;
+
+    // ✅ CORRECT: Use for tracking/analytics, not state control
+    setTrackingData((prev) => ({
+      accordionOpened: expanded,
+      openCount: expanded ? prev.openCount + 1 : prev.openCount,
+    }));
+
+    // ✅ CORRECT: Log for analytics
+    console.log(
+      `Accordion item ${index} is now ${expanded ? "open" : "closed"}`
+    );
+  };
+
+  return (
+    <ModusWcAccordion onExpandedChange={handleAccordionChange}>
+      <ModusWcCollapse
+        collapse-id="item1"
+        options={{
+          title: "Item One",
+          description: "First accordion item",
+        }}
+      >
+        <div slot="content">Content for item one.</div>
+      </ModusWcCollapse>
+    </ModusWcAccordion>
+  );
+}
+```
+
+### ✅ **Programmatic Control When Needed**
+
+```tsx
+// ✅ CORRECT: Use refs for programmatic control
+function AccordionComponent() {
+  const collapseRef = useRef<ModusWcCollapse>(null);
+
+  const openAccordion = () => {
+    // ✅ CORRECT: Use ref to control collapse programmatically
+    if (collapseRef.current) {
+      collapseRef.current.expanded = true;
+    }
+  };
+
+  const closeAccordion = () => {
+    // ✅ CORRECT: Use ref to control collapse programmatically
+    if (collapseRef.current) {
+      collapseRef.current.expanded = false;
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={openAccordion}>Open Accordion</button>
+      <button onClick={closeAccordion}>Close Accordion</button>
+
+      <ModusWcAccordion>
+        <ModusWcCollapse
+          ref={collapseRef}
+          collapse-id="item1"
+          options={{
+            title: "Controllable Item",
+            description: "This can be controlled programmatically",
+          }}
+        >
+          <div slot="content">Content for controllable item.</div>
+        </ModusWcCollapse>
+      </ModusWcAccordion>
+    </div>
+  );
+}
+```
+
+## 🎯 **Best Practices**
+
+### ✅ **State Management Strategy**
+
+1. **Let Modus Components Own Their State**
+
+   - Don't try to control `expanded` from React
+   - Use events to track state changes
+   - Use refs for programmatic control when needed
+
+2. **Event-Driven Architecture**
+
+   ```tsx
+   // ✅ CORRECT: Event-driven approach
+   function MyComponent() {
+     const handleAccordionChange = (event: CustomEvent) => {
+       // Handle the event for tracking, analytics, or side effects
+       // Don't try to control the accordion state
+       console.log("Accordion expanded:", event.detail);
+     };
+
+     return (
+       <ModusWcAccordion onExpandedChange={handleAccordionChange}>
+         <div slot="header">Header</div>
+         <div slot="body">Body</div>
+       </ModusWcAccordion>
+     );
+   }
+   ```
+
+3. **Use Refs for Programmatic Control**
+
+   ```tsx
+   // ✅ CORRECT: Ref-based control
+   const accordionRef = useRef<ModusWcAccordion>(null);
+
+   const toggleAccordion = () => {
+     if (accordionRef.current) {
+       accordionRef.current.expanded = !accordionRef.current.expanded;
+     }
+   };
+   ```
+
+### ✅ **Multiple Accordions Pattern**
+
+```tsx
+// ✅ CORRECT: Multiple accordions with independent state
+function MultipleAccordions() {
+  const accordionRefs = useRef<(ModusWcAccordion | null)[]>([]);
+
+  const openAllAccordions = () => {
+    accordionRefs.current.forEach((ref) => {
+      if (ref) ref.expanded = true;
+    });
+  };
+
+  const closeAllAccordions = () => {
+    accordionRefs.current.forEach((ref) => {
+      if (ref) ref.expanded = false;
+    });
+  };
+
+  return (
+    <div>
+      <button onClick={openAllAccordions}>Open All</button>
+      <button onClick={closeAllAccordions}>Close All</button>
+
+      {accordionData.map((item, index) => (
+        <ModusWcAccordion
+          key={item.id}
+          ref={(el) => (accordionRefs.current[index] = el)}
+        >
+          <div slot="header">{item.title}</div>
+          <div slot="body">{item.content}</div>
+        </ModusWcAccordion>
+      ))}
+    </div>
+  );
+}
+```
+
+## 🔧 **Advanced Patterns**
+
+### ✅ **Accordion with External State Tracking**
+
+```tsx
+// ✅ CORRECT: Track accordion state without controlling it
+function AccordionWithTracking() {
+  const [accordionStates, setAccordionStates] = useState<
+    Record<string, boolean>
+  >({});
+
+  const handleAccordionChange = (id: string) => (event: CustomEvent) => {
+    const isExpanded = event.detail;
+
+    // ✅ CORRECT: Track state for analytics/UI updates
+    setAccordionStates((prev) => ({
+      ...prev,
+      [id]: isExpanded,
+    }));
+
+    // ✅ CORRECT: Use for conditional rendering or analytics
+    if (isExpanded) {
+      console.log(`Accordion ${id} opened`);
+    }
+  };
+
+  return (
+    <div>
+      {accordionData.map((item) => (
+        <ModusWcAccordion
+          key={item.id}
+          onExpandedChange={handleAccordionChange(item.id)}
+        >
+          <div slot="header">
+            {item.title}
+            {accordionStates[item.id] && <span> (Open)</span>}
+          </div>
+          <div slot="body">{item.content}</div>
+        </ModusWcAccordion>
+      ))}
+    </div>
+  );
+}
+```
+
+### ✅ **Accordion with Conditional Content**
+
+```tsx
+// ✅ CORRECT: Use events to show/hide related content
+function AccordionWithConditionalContent() {
+  const [activeAccordion, setActiveAccordion] = useState<string | null>(null);
+
+  const handleAccordionChange = (id: string) => (event: CustomEvent) => {
+    const isExpanded = event.detail;
+    setActiveAccordion(isExpanded ? id : null);
+  };
+
+  return (
+    <div>
+      {accordionData.map((item) => (
+        <div key={item.id}>
+          <ModusWcAccordion onExpandedChange={handleAccordionChange(item.id)}>
+            <div slot="header">{item.title}</div>
+            <div slot="body">{item.content}</div>
+          </ModusWcAccordion>
+
+          {/* ✅ CORRECT: Show additional content based on accordion state */}
+          {activeAccordion === item.id && (
+            <div className="mt-4 p-4 bg-muted rounded">
+              Additional content for {item.title}
+            </div>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## 🚫 **What NOT to Do**
+
+### ❌ **Don't Control State from React**
+
+```tsx
+// ❌ WRONG: Don't do this
+const [isExpanded, setIsExpanded] = useState(false);
+
+<ModusWcAccordion
+  expanded={isExpanded}  // ❌ This causes conflicts
+  onExpandedChange={(e) => setIsExpanded(e.detail)}  // ❌ Creates loops
+>
+```
+
+### ❌ **Don't Use React State for Accordion Logic**
+
+```tsx
+// ❌ WRONG: Don't manage accordion state in React
+const [accordionState, setAccordionState] = useState({
+  accordion1: false,
+  accordion2: true,
+});
+```
+
+### ❌ **Don't Try to Sync React and Modus State**
+
+```tsx
+// ❌ WRONG: Don't try to sync states
+useEffect(() => {
+  // This will cause infinite loops
+  if (reactState !== modusState) {
+    setReactState(modusState);
+  }
+}, [reactState, modusState]);
+```
+
+## 🎯 **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 React state with Modus state in real-time
+3. **Use Events for Tracking**: Listen to `onExpandedChange` for analytics and side effects
+4. **Use Refs for Control**: When you need programmatic control, use refs on `ModusWcCollapse`
+5. **Trust the Component**: Modus Web Components handle their own state changes after initial render
+6. **Proper Structure**: Use `ModusWcAccordion` with `ModusWcCollapse` components and `options` for headers
+
+## 🔍 **Testing Accordion State**
+
+```tsx
+// ✅ CORRECT: Test accordion behavior
+function TestAccordion() {
+  const accordionRef = useRef<ModusWcAccordion>(null);
+
+  const testAccordion = () => {
+    if (accordionRef.current) {
+      // Test opening
+      accordionRef.current.expanded = true;
+
+      setTimeout(() => {
+        // Test closing
+        accordionRef.current!.expanded = false;
+      }, 1000);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={testAccordion}>Test Accordion</button>
+      <ModusWcAccordion ref={accordionRef}>
+        <div slot="header">Test Header</div>
+        <div slot="body">Test Body</div>
+      </ModusWcAccordion>
+    </div>
+  );
+}
+```
+
+---
+
+**Remember: Modus accordion components support controlled initial state but avoid real-time synchronization. Use `expanded` for initial state, `onExpandedChange` for tracking, and refs for programmatic control. This approach prevents conflicts and ensures reliable behavior.**

package/templates/react/.cursor/rules/modus-button-group-usage-react-short.mdc

@@ -0,0 +1,23 @@
+---
+description: Critical pattern for ModusButton inside ModusButtonGroup
+globs: ["**/components/ModusButton*.tsx", "**/demos/**/page.tsx"]
+alwaysApply: true
+---
+
+# Modus Button Group Usage - Short
+
+Critical pattern to avoid styling conflicts in button groups.
+
+## Key Rules
+
+- **No defaults for variant/color in ModusButton** - Defaults override button group settings
+- **Use conditional prop spreading** - `{...(variant && { variant })}` to only pass when defined
+- **Group controls styling** - ModusButtonGroup applies variant/color to all child buttons
+- **Don't set variant/color on buttons inside groups** - Let the group control them
+- **Explicitly set props for standalone buttons** - When not in a group, set variant and color
+- **Group uses setAttribute after load** - DOM manipulation requires no conflicting React props
+- **Test all three variants** - Outlined, filled, and borderless should look distinct
+
+## Reference
+
+For detailed patterns, web component internals, and testing checklist, fetch the full rule: `modus-button-group-usage-react`

package/templates/react/.cursor/rules/modus-button-group-usage-react.mdc

@@ -0,0 +1,117 @@
+---
+description: Critical pattern for ModusButton inside ModusButtonGroup
+globs: ["**/components/ModusButton*.tsx", "**/demos/**/page.tsx"]
+alwaysApply: false
+---
+
+# Modus Button Group Usage
+
+Critical patterns for using ModusButton components inside ModusButtonGroup.
+
+## The Problem
+
+When `ModusButton` has default values for `variant` and `color`, these explicit values **override** the `ModusButtonGroup`'s settings. This causes all buttons to look the same regardless of the group's variant prop.
+
+## Root Cause
+
+The `modus-wc-button-group` web component uses `setAttribute()` to apply its `variant` and `color` to child buttons **after** they load. If React buttons have explicit defaults, they override the group's settings.
+
+## Correct Pattern
+
+### ModusButton Component
+
+Do NOT set defaults for `variant` or `color` in the ModusButton wrapper:
+
+```tsx
+// CORRECT - No defaults, allows inheritance from button group
+export default function ModusButton({
+  color, // undefined by default
+  variant, // undefined by default
+  size = "md",
+  // ...other props
+}: ModusButtonProps) {
+  return (
+    <ModusWcButton
+      {...(color && { color })} // Only pass if defined
+      {...(variant && { variant })} // Only pass if defined
+      size={size}
+      // ...other props
+    >
+      {children}
+    </ModusWcButton>
+  );
+}
+```
+
+```tsx
+// WRONG - Defaults override button group settings
+export default function ModusButton({
+  color = "primary", // BAD: Will override group's color
+  variant = "filled", // BAD: Will override group's variant
+  // ...
+}: ModusButtonProps) {
+  // ...
+}
+```
+
+### Using ModusButton Standalone
+
+When using `ModusButton` outside a button group, explicitly set the props you need:
+
+```tsx
+// Standalone button - explicitly set variant and color
+<ModusButton variant="filled" color="primary">
+  Click Me
+</ModusButton>
+```
+
+### Using ModusButton in a Button Group
+
+When inside a `ModusButtonGroup`, do NOT set variant/color on individual buttons:
+
+```tsx
+// CORRECT - Group controls all button styling
+<ModusButtonGroup variant="outlined" color="primary">
+  <ModusButton>Button 1</ModusButton>
+  <ModusButton>Button 2</ModusButton>
+  <ModusButton>Button 3</ModusButton>
+</ModusButtonGroup>
+
+// WRONG - Individual button props override group settings
+<ModusButtonGroup variant="outlined" color="primary">
+  <ModusButton variant="filled">Button 1</ModusButton>  // BAD
+  <ModusButton color="danger">Button 2</ModusButton>    // BAD
+</ModusButtonGroup>
+```
+
+## How ModusButtonGroup Works
+
+The web component applies styling to children via DOM manipulation:
+
+```typescript
+// Inside modus-wc-button-group.tsx
+private syncButtonStates(): void {
+  this.buttonElements = this.el.querySelectorAll('modus-wc-button');
+  this.setButtonAttribute('variant', this.variant);
+  this.setButtonAttribute('color', this.color || null);
+  this.setButtonAttribute('disabled', this.disabled ? 'true' : null);
+}
+```
+
+This only works if child buttons don't have explicit values that override the setAttribute calls.
+
+## Quick Reference
+
+| Context                        | variant                | color                  | Notes                            |
+| ------------------------------ | ---------------------- | ---------------------- | -------------------------------- |
+| Standalone button              | Set explicitly         | Set explicitly         | Button controls its own style    |
+| Inside button group            | Do NOT set             | Do NOT set             | Group controls all button styles |
+| Mixed (some grouped, some not) | Set only on standalone | Set only on standalone | Follow context rules             |
+
+## Testing Checklist
+
+- [ ] Outlined variant shows bordered buttons with transparent background
+- [ ] Filled variant shows solid colored buttons
+- [ ] Borderless variant shows text-only buttons without borders
+- [ ] Color prop applies consistently to all buttons in group
+- [ ] Individual buttons don't override group styling

package/templates/react/.cursor/rules/modus-checkbox-value-inversion-react-short.mdc

@@ -0,0 +1,23 @@
+---
+description: Critical bug fix for ModusWcCheckbox value property inversion
+globs: ["**/components/ModusCheckbox*.tsx", "**/demos/**/page.tsx"]
+alwaysApply: true
+---
+
+# Modus Checkbox Value Inversion - Short
+
+Critical bug fix for ModusWcCheckbox value property inversion.
+
+## Key Rules
+
+- **Always invert checkbox value property** - `const actualChecked = !value` from `inputChange` event
+- **Use wrapper components** - Create React wrapper to handle inversion automatically
+- **Never trust the raw value** - The `value` property is inverted (false when checked, true when unchecked)
+- **Handle in event handlers** - Invert value in `onInputChange` event handler
+- **Use utility functions** - Create helper functions for value inversion
+- **Test thoroughly** - Verify checkbox behavior matches expected state
+- **Document the bug** - Make team aware of this critical issue
+
+## Reference
+
+For detailed bug explanation, wrapper component patterns, and utility functions, fetch the full rule: `modus-checkbox-value-inversion-react`