Cursor rule

1---
2description: 
3globs: app/views/**,app/javascript/**,app/components/**/*.js
4alwaysApply: false
5---
6Use this rule to learn how to write ERB views, partials, and Stimulus controllers should be incorporated into them.
7 
8- **Component vs. Partial Decision Making**
9  - **Use ViewComponents when:**
10    - Element has complex logic or styling patterns
11    - Element will be reused across multiple views/contexts
12    - Element needs structured styling with variants/sizes (like buttons, badges)
13    - Element requires interactive behavior or Stimulus controllers
14    - Element has configurable slots or complex APIs
15    - Element needs accessibility features or ARIA support
16  
17  - **Use Partials when:**
18    - Element is primarily static HTML with minimal logic
19    - Element is used in only one or few specific contexts
20    - Element is simple template content (like CTAs, static sections)
21    - Element doesn't need variants, sizes, or complex configuration
22    - Element is more about content organization than reusable functionality
23 
24- **Prefer components over partials**
25  - If there is a component available for the use case in app/components, use it
26  - If there is no component, look for a partial
27  - If there is no partial, decide between component or partial based on the criteria above
28 
29- **Examples of Component vs. Partial Usage**
30```erb
31  <%# Component: Complex, reusable with variants and interactivity %>
32  <%= render DialogComponent.new(variant: :drawer) do |dialog| %>
33    <% dialog.with_header(title: "Account Settings") %>
34    <% dialog.with_body { "Dialog content here" } %>
35  <% end %>
36  
37  <%# Component: Interactive with complex styling options %>
38  <%= render ButtonComponent.new(text: "Save Changes", variant: "primary", confirm: "Are you sure?") %>
39  
40  <%# Component: Reusable with variants %>
41  <%= render FilledIconComponent.new(icon: "credit-card", variant: :surface) %>
42  
43  <%# Partial: Static template content %>
44  <%= render "shared/logo" %>
45  
46  <%# Partial: Simple, context-specific content with basic styling %>
47  <%= render "shared/trend_change", trend: @account.trend, comparison_label: "vs last month" %>
48  
49  <%# Partial: Simple divider/utility %>
50  <%= render "shared/ruler", classes: "my-4" %>
51  
52  <%# Partial: Simple form utility %>
53  <%= render "shared/form_errors", model: @account %>
54```
55 
56- **Keep domain logic out of the views**
57```erb
58    <%# BAD!!! %>
59 
60    <%# This belongs in the component file, not the template file! %>
61    <% button_classes = { class: "bg-blue-500 hover:bg-blue-600" } %>
62 
63    <%= tag.button class: button_classes do %>
64      Save Account
65    <% end %>
66 
67    <%# GOOD! %>
68 
69    <%= tag.button class: computed_button_classes do %>
70      Save Account
71    <% end %>
72```
73 
74- **Stimulus Integration in Views**
75  - Always use the **declarative approach** when integrating Stimulus controllers
76  - The ERB template should declare what happens, the Stimulus controller should respond
77  - Refer to [stimulus_conventions.mdc](mdc:.cursor/rules/stimulus_conventions.mdc) to learn how to incorporate them into 
78 
79  GOOD Stimulus controller integration into views:
80 
81```erb
82  <!-- Declarative - HTML declares what happens -->
83 
84  <div data-controller="toggle">
85    <button data-action="click->toggle#toggle" data-toggle-target="button">Show</button>
86    <div data-toggle-target="content" class="hidden">Hello World!</div>
87  </div>
88```
89 
90- **Stimulus Controller Placement Guidelines**
91  - **Component controllers** (in `app/components/`) should only be used within their component templates
92  - **Global controllers** (in `app/javascript/controllers/`) can be used across any view
93  - Pass data from Rails to Stimulus using `data-*-value` attributes, not inline JavaScript
94  - Use Stimulus targets to reference DOM elements, not manual `getElementById` calls
95 
96- **Naming Conventions**
97  - **Components**: Use `ComponentName` suffix (e.g., `ButtonComponent`, `DialogComponent`, `FilledIconComponent`)
98  - **Partials**: Use underscore prefix (e.g., `_trend_change.html.erb`, `_form_errors.html.erb`, `_sync_indicator.html.erb`)
99  - **Shared partials**: Place in `app/views/shared/` directory for reusable content
100  - **Context-specific partials**: Place in relevant controller view directory (e.g., `accounts/_account_sidebar_tabs.html.erb`)
101 
102