evc_rails 0.1.4 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e15aa81852a8394bcc2a904cff923f3d5a5f588c618a2c0c6112f33203b0bd2c
-  data.tar.gz: cdd1c962213f4c2a6593a522ac2aee9cc793858f4759c218242169a26fd40ace
+  metadata.gz: 5fa808d0d2dcb0efe2ff7a1807cbfabfb62995594731b066eb718e3aac9e1ee3
+  data.tar.gz: fc944ac269042805ec1bb1c9175a4646ac56ed4a3ac2461c6061c211c831b608
 SHA512:
-  metadata.gz: 91a5a791151b6e2290dc3a20a8e95980a0821bf2526314a3b07724e85dda06f11a6149bfd9d808eb4af9e67da90d80616ddb9fa799d2c61ebc0e908e4cb627ce
-  data.tar.gz: 0bc11c9d4026d5357b5d86089884eff7d30bf82a66823ec164aa3600cbf2ca6774c835c18175a132225acd9204cd95879f76a5698fbc80e355a46ba1ac771e85
+  metadata.gz: 197a8e203c89e35b9a2365b38d40a9c24c042045a9ea654538f9fa5eb860778d7a1312231c921d6a7b9119cc41869ece6240ce5af201a4c94420406a5f02f228
+  data.tar.gz: 0ae04a20540c3ad665ac2b7309e1053bdb200ca6f0a9c439752904ff9400fb6ce45defbe15cc620256a6959dd7b2c2b46489bea45921c1d44b09ea813a86f000

data/README.md

@@ -154,6 +154,32 @@ This maps to:
 
 ### Slot Support
 
+EVC provides a powerful and intuitive way to work with ViewComponent slots. To populate a slot, you use a corresponding `<With...>` tag that matches the **method name** provided by `renders_one` or `renders_many`.
+
+When you use slots, EVC automatically makes the component's instance available in a block variable. By default, this variable is named after the component itself in snake_case (e.g., `<Accordion>` yields an `accordion` variable). This allows you to easily call component methods like `<%= accordion.arrow %>` from within the block. This variable is even available in deeply nested components, and you can provide a custom name to avoid ambiguity when nesting components of the same type.
+
+#### Slot Naming Convention
+
+The key to understanding slot tags in `evc_rails` is that they map directly to the **methods** generated by ViewComponent, not the `renders_...` declaration itself.
+
+For both `renders_one` and `renders_many`, ViewComponent always generates a singular `with_*` method.
+
+- `renders_one :header` provides a `with_header` method. You use `<WithHeader>`.
+- `renders_many :items` provides a singular `with_item` method. You use the singular `<WithItem>` tag for each item you want to render.
+
+This design provides maximum flexibility, allowing you to pass content as a block or make multiple self-closing calls, just like you would in standard ERB.
+
+#### Attributes vs. Slots
+
+There are two ways to pass information to a component:
+
+- **As attributes:** Data passed as attributes on the main component tag (e.g. `<Card title="...">`) is sent to its `initialize` method.
+- **As slot content:** Rich content passed via `<With...>` tags is used to populate the component's named slots.
+
+#### When a Block Variable is Yielded
+
+The contextual variable (e.g., `|card|`) is only yielded if one or more `<With...>` slot tags are present inside the component block. If you render a component like `<Card></Card>` with no slots inside, `evc_rails` is smart enough to render it without the `do |card|` part.
+
 #### Single Slots (`renders_one`)
 
 ```ruby
@@ -166,23 +192,23 @@ end
 
 ```erb
 <Card>
-  <Card::Header>
+  <WithHeader>
     <h1>Welcome</h1>
-  </Card::Header>
-  <Card::Body>
+  </WithHeader>
+  <WithBody>
     <p>This is the body content.</p>
-  </Card::Body>
+  </WithBody>
 </Card>
 ```
 
 Becomes:
 
 ```erb
-<%= render CardComponent.new do |c| %>
-  <% c.header do %>
+<%= render CardComponent.new do |card| %>
+  <% card.with_header do %>
     <h1>Welcome</h1>
   <% end %>
-  <% c.body do %>
+  <% card.with_body do %>
     <p>This is the body content.</p>
   <% end %>
 <% end %>
@@ -199,42 +225,63 @@ end
 
 ```erb
 <List>
-  <List::Item>Item 1</List::Item>
-  <List::Item>Item 2</List::Item>
-  <List::Item>Item 3</List::Item>
+  <% @todo_items.each do |item| %>
+    <WithItem>
+      <span class="<%= item.completed? ? 'line-through' : '' %>">
+        <%= item.title %>
+      </span>
+    </WithItem>
+  <% end %>
 </List>
 ```
 
 Becomes:
 
 ```erb
-<%= render ListComponent.new do |c| %>
-  <% c.item do %>Item 1<% end %>
-  <% c.item do %>Item 2<% end %>
-  <% c.item do %>Item 3<% end %>
+<%= render ListComponent.new do |list| %>
+  <% @todo_items.each do |item| %>
+    <% list.with_item do %>
+      <span class="<%= item.completed? ? 'line-through' : '' %>">
+        <%= item.title %>
+      </span>
+    <% end %>
+  <% end %>
 <% end %>
 ```
 
-### Complex Nesting
+#### Custom Variable Naming with `as`
+
+For clarity or to resolve ambiguity when nesting components of the same type, you can provide a custom variable name with the `as` attribute.
+
+```ruby
+# app/components/card_component.rb
+class CardComponent < ViewComponent::Base
+  renders_one :header
+
+  attr_reader :title
+
+  def initialize(title: "Default Title")
+    @title = title
+  end
+end
+```
 
 ```erb
-<UI::Card>
-  <h2 class="text-2xl font-semibold">Dashboard</h2>
-
-  <UI::Grid cols="3" gap="md">
-    <UI::Card shadow="sm">
-      <p class="text-center">Widget 1</p>
-    </UI::Card>
-    <UI::Card shadow="sm">
-      <p class="text-center">Widget 2</p>
-    </UI::Card>
-    <UI::Card shadow="sm">
-      <p class="text-center">Widget 3</p>
-    </UI::Card>
-  </UI::Grid>
-</UI::Card>
+<Card as="outer_card" title="Outer Card">
+  <WithHeader>
+    <h2><%= outer_card.title %></h2>
+    <Card as="inner_card" title="Inner Card">
+      <WithHeader>
+        <h3><%= inner_card.title %></h3>
+        <p>Outer card title from inner scope: <%= outer_card.title %></p>
+      </WithHeader>
+    </Card>
+  </WithHeader>
+</Card>
 ```
 
+This generates distinct variables, `outer_card` and `inner_card`, allowing you to access the context of each component without collision.
+
 ### Mixed Content
 
 You can mix regular HTML, ERB, and component tags:

data/lib/evc_rails/template_handler.rb

@@ -104,40 +104,35 @@ module EvcRails
             match = next_open
             tag_name = match[1]
             attributes_str = match[2].to_s.strip
+            params, as_variable = parse_attributes(attributes_str, attribute_regex)
+            param_str = params.join(", ")
             is_self_closing = match[0].end_with?("/>")
 
             # Add content before the tag
             result << source[pos...match.begin(0)] if pos < match.begin(0)
 
-            # Determine if this is a slot (e.g., Card::Header inside Card)
-            parent = stack.last
+            # Determine if this is a slot (e.g., WithHeader, WithPost)
+            parent_component = stack.reverse.find { |item| item[4] == :component }
             is_slot = false
             slot_name = nil
-            slot_parent = nil
-            if parent
-              parent_tag = parent[0]
-              if tag_name.start_with?("#{parent_tag}::")
-                is_slot = true
-                slot_name = tag_name.split("::").last.downcase
-                slot_parent = parent_tag
-                # Mark parent as having a slot
-                parent[6] = true
-              end
+
+            if parent_component && tag_name.start_with?("With")
+              is_slot = true
+              # Convert CamelCase slot name to snake_case
+              slot_name = tag_name[4..].gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+              parent_component[6] = true # Mark parent as having a slot
             end
 
             if is_self_closing
               if is_slot
-                params = parse_attributes(attributes_str, attribute_regex)
-                param_str = params.join(", ")
+                parent_variable = parent_component[8]
                 result << if param_str.empty?
-                            "<% c.#{slot_name} do %><% end %>"
+                            "<% #{parent_variable}.with_#{slot_name} do %><% end %>"
                           else
-                            "<% c.#{slot_name}(#{param_str}) do %><% end %>"
+                            "<% #{parent_variable}.with_#{slot_name}(#{param_str}) do %><% end %>"
                           end
               else
                 component_class = "#{tag_name}Component"
-                params = parse_attributes(attributes_str, attribute_regex)
-                param_str = params.join(", ")
                 result << if param_str.empty?
                             "<%= render #{component_class}.new %>"
                           else
@@ -145,35 +140,23 @@ module EvcRails
                           end
               end
             elsif is_slot
-              params = parse_attributes(attributes_str, attribute_regex)
-              param_str = params.join(", ")
-              stack << [tag_name, nil, param_str, result.length, :slot, slot_name, false, match.begin(0)]
+              parent_variable = parent_component[8]
+              stack << [tag_name, nil, param_str, result.length, :slot, slot_name, false, match.begin(0), nil]
               result << if param_str.empty?
-                          "<% c.#{slot_name} do %>"
+                          "<% #{parent_variable}.with_#{slot_name} do %>"
                         else
-                          "<% c.#{slot_name}(#{param_str}) do %>"
+                          "<% #{parent_variable}.with_#{slot_name}(#{param_str}) do %>"
                         end
             else
               component_class = "#{tag_name}Component"
-              params = parse_attributes(attributes_str, attribute_regex)
-              param_str = params.join(", ")
-              # If this is the outermost component, add |c| for slot support only if a slot is used
-              if stack.empty?
-                stack << [tag_name, component_class, param_str, result.length, :component, nil, false, match.begin(0)] # [tag_name, class, params, pos, type, slot_name, slot_used, open_pos]
-                # We'll patch in |c| at close if needed
-                result << if param_str.empty?
-                            "<%= render #{component_class}.new do %>"
-                          else
-                            "<%= render #{component_class}.new(#{param_str}) do %>"
-                          end
-              else
-                stack << [tag_name, component_class, param_str, result.length, :component, nil, false, match.begin(0)]
-                result << if param_str.empty?
-                            "<%= render #{component_class}.new do %>"
-                          else
-                            "<%= render #{component_class}.new(#{param_str}) do %>"
-                          end
-              end
+              variable_name = as_variable || component_variable_name(tag_name)
+              stack << [tag_name, component_class, param_str, result.length, :component, nil, false, match.begin(0),
+                        variable_name]
+              result << if param_str.empty?
+                          "<%= render #{component_class}.new do %>"
+                        else
+                          "<%= render #{component_class}.new(#{param_str}) do %>"
+                        end
             end
 
             pos = match.end(0)
@@ -193,7 +176,7 @@ module EvcRails
             end
 
             # Find the matching opening tag (from the end)
-            matching_index = stack.rindex { |(tag_name, _, _, _, _, _, _, _)| tag_name == closing_tag_name }
+            matching_index = stack.rindex { |(tag_name, *)| tag_name == closing_tag_name }
             if matching_index.nil?
               line = line_number_at_position(source, match.begin(0))
               col = column_number_at_position(source, match.begin(0))
@@ -201,18 +184,30 @@ module EvcRails
             end
 
             # Pop the matching opening tag
-            tag_name, component_class, param_str, start_pos, type, slot_name, slot_used, open_pos = stack.delete_at(matching_index)
+            open_tag_data = stack.delete_at(matching_index)
+            tag_type = open_tag_data[4]
+
+            if tag_type == :component
+              _tag_name, component_class, param_str, start_pos, _type, _slot_name, slot_used, _open_pos, variable_name = open_tag_data
+
+              # Patch in |variable_name| for component if a slot was used
+              if slot_used
+                # More robustly find the end of the `do` block to insert the variable.
+                # This avoids faulty regex matching on complex parameters.
+                relevant_part = result[start_pos..-1]
+                match_for_insertion = /( do)( %>)/.match(relevant_part)
+                if match_for_insertion
+                  # Insert the variable name just before the ` do`
+                  insertion_point = start_pos + match_for_insertion.begin(1)
+                  result.insert(insertion_point, " |#{variable_name}|")
+                end
+              end
 
-            # Patch in |c| for top-level component if a slot was used
-            if type == :component && stack.empty? && slot_used
-              # Find the opening block and insert |c|
-              open_block_regex = /(<%= render #{component_class}\.new(?:\(.*?\))? do)( %>)/
-              result.sub!(open_block_regex) { "#{::Regexp.last_match(1)} |c|#{::Regexp.last_match(2)}" }
+              result << "<% end %>"
+            else # It's a slot
+              result << "<% end %>"
             end
 
-            # Add closing block
-            result << (type == :slot ? "<% end %>" : "<% end %>")
-
             pos = match.end(0)
           else
             # No more tags, add remaining content
@@ -239,7 +234,24 @@ module EvcRails
         erb_string
       end
 
+      def component_variable_name(tag_name)
+        # Simplified version of ActiveSupport's underscore
+        name = tag_name.gsub(/::/, "_")
+        name.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+        name.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+        name.tr!("-", "_")
+        name.downcase!
+        name
+      end
+
       def parse_attributes(attributes_str, attribute_regex = ATTRIBUTE_REGEX)
+        as_variable = nil
+        # Find and remove the `as` attribute, storing its value.
+        attributes_str = attributes_str.gsub(/\bas=(?:"([^"]*)"|'([^']*)')/) do |_match|
+          as_variable = Regexp.last_match(1) || Regexp.last_match(2)
+          ""
+        end.strip
+
         params = []
         attributes_str.scan(attribute_regex) do |key, quoted_value, single_quoted_value, ruby_expression|
           if ruby_expression
@@ -250,7 +262,7 @@ module EvcRails
             params << "#{key}: \"#{single_quoted_value.gsub("'", "\\'")}\""
           end
         end
-        params
+        [params, as_variable]
       end
     end
   end

data/lib/evc_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EvcRails
-  VERSION = "0.1.4"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: evc_rails
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.1
 platform: ruby
 authors:
 - scttymn