evc_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 703fa9100249c54f63c8e567d5d8cde7b3908b6777dfb555f2d2e72a949d4daa
+  data.tar.gz: f175e943945bc31a3d4da2be22290e7f843546c0bb6dc0426ad22d1433472fe6
+SHA512:
+  metadata.gz: dcd338b43347af1e971b99d50298d425da85193856f0362a4b7358ad19fbe3b059b5808b6c7ba0bf0f53944244d2bf2a5a7fd8e2283d6d13912f138c683d6b36
+  data.tar.gz: c902814035da4a002d4006df67b07e8e71256084a9bc3585a256d1b14281eb5bee41c4941b0d7956f4c6d87330bf72cfdfb5edef2b03321a94e99c676af2e331

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.1
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 scttymn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,153 @@
+# EvcRails
+
+EvcRails is a Rails gem that introduces a custom .evc template handler, allowing you to define your Rails View Components using a concise, HTML-like PascalCase tag syntax, reminiscent of React or other modern component-based UI frameworks. This gem seamlessly integrates your custom tags with Rails View Components, enabling a more declarative and readable approach to building UIs in Rails.
+
+## Features
+
+PascalCase Component Tags: Define and use your View Components with <MyComponent> or self-closing <MyComponent /> syntax directly in your .evc templates.
+
+Attribute Handling: Pass attributes to your components using standard HTML-like key="value", key='value', or Ruby expressions key={@variable}.
+
+Content Blocks: Components can accept content blocks (<MyComponent>content</MyComponent>) which are passed to the View Component via a block.
+
+Automatic Component Resolution: Automatically appends "Component" to your tag name if it's not already present (e.g., <Button> resolves to ButtonComponent).
+
+Performance Optimized: Includes in-memory caching of compiled templates and memoization of component class lookups for efficient rendering in production.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```
+gem 'evc_rails'
+```
+
+And then execute:
+
+```
+bundle install
+```
+
+Or install it yourself as:
+
+```
+gem install evc_rails
+```
+
+## Usage
+
+1. Create a View Component
+   First, ensure you have a Rails View Component. For example, create app/components/my_component_component.rb:
+
+```ruby
+# app/components/my_component_component.rb
+class MyComponentComponent < ViewComponent::Base
+  def initialize(title:)
+    @title = title
+  end
+
+  def call
+    tag.div(class: "my-component") do
+      concat tag.h2(@title)
+      concat content # This renders the block content
+    end
+  end
+end
+```
+
+And its associated template app/components/my_component_component.html.erb (if you're using separate templates):
+
+```html
+<!-- app/components/my_component_component.html.erb -->
+<div class="my-component">
+  <h2><%= @title %></h2>
+  <%= content %>
+</div>
+```
+
+2. Create an .evc Template
+   Now, create a template file with the .evc extension. For instance, app/views/pages/home.html.evc:
+
+```html
+<!-- app/views/pages/home.html.evc -->
+<h1>Welcome to My App</h1>
+
+<MyComponent title="Hello World">
+  <p>This is some content passed to the component.</p>
+  <button text="Click Me" />
+</MyComponent>
+
+<%# A more concise way to render your DoughnutChartComponent %>
+<DoughnutChart rings="{@progress_data}" />
+
+<%# You can still use standard ERB within .evc files %>
+<p><%= link_to "Go somewhere", some_path %></p>
+```
+
+3. Ensure Components are Autoloaded
+   Make sure your app/components directory is eager-loaded in production. In config/application.rb or an initializer:
+
+```ruby
+# config/application.rb
+config.eager_load_paths << Rails.root.join("app/components")
+```
+
+## How it Works
+
+When Rails processes an .evc template, EvcRails intercepts it and performs the following transformations:
+
+```erb
+<MyComponent title="Hello World">... </MyComponent>
+```
+
+becomes:
+
+```ruby
+<%= render MyComponentComponent.new(title: "Hello World") do %>
+  ... (processed content) ...
+<% end %>
+```
+
+```erb
+<%=<button text="Click Me" />
+```
+
+becomes:
+
+```ruby
+<%= render ButtonComponent.new(text: "Click Me") %>
+```
+
+```erb
+<DoughnutChart rings={@progress_data} />
+```
+
+becomes:
+
+```ruby
+<%= render DoughnutChartComponent.new(rings: @progress_data) %>
+```
+
+`attr={@variable}` becomes `attr: @variable` in the new() call.
+
+The transformed content is then passed to the standard ERB handler for final rendering.
+
+## Configuration
+
+Currently, EvcRails requires no specific configuration. Future versions might include options for:
+
+Customizing the component suffix (e.g., if you don't want "Component" appended).
+
+Defining custom component lookup paths.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [your-gem-repo-link]. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the MIT License
+
+```
+
+```

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/lib/evc_rails/railtie.rb

@@ -0,0 +1,37 @@
+# lib/evc_rails/railtie.rb
+#
+# This file defines a Rails::Railtie, which integrates the evc_rails gem
+# with the Rails framework during its boot process.
+
+require "evc_rails/template_handler"
+require "action_view" # Ensure ActionView is loaded for handler registration
+
+module EvcRails
+  class Railtie < Rails::Railtie
+    # Register MIME type and template handler early in the initialization process
+    initializer "evc_rails.register_template_handler", before: :load_config_initializers do
+      Rails.logger.info "Registering EVC template handler"
+      # Register a unique MIME type for .evc templates
+      Mime::Type.register "text/evc", :evc, %w[text/evc], %w[evc]
+
+      # Register the template handler
+      handler = EvcRails::TemplateHandlers::Evc.new
+      ActionView::Template.register_template_handler(:evc, handler)
+
+      Rails.logger.info "Template handler registered: #{handler.inspect}"
+    end
+
+    # Finalize configuration after Rails initialization
+    config.after_initialize do
+      Rails.logger.info "Configuring EVC template handlers"
+      # Ensure :evc is prioritized in default handlers
+      config.action_view.default_template_handlers ||= []
+      config.action_view.default_template_handlers.prepend(:evc)
+
+      # Verify handler registration (no re-registration)
+      unless ActionView::Template.handler_for_extension(:evc)
+        Rails.logger.warn "EVC template handler not registered; check initialization"
+      end
+    end
+  end
+end

data/lib/evc_rails/template_handler.rb

@@ -0,0 +1,191 @@
+# lib/evc_rails/template_handler.rb
+#
+# This file contains the core logic for the .evc template handler.
+# It's part of the `EvcRails` module to keep it namespaced within the gem.
+# Handles .evc templates, converting PascalCase tags (self-closing <MyComponent attr={value} />
+# or container <MyComponent>content</MyComponent>) into Rails View Component renders.
+# Supports string literals and Ruby expressions as attribute values. The handler is
+# agnostic to specific component APIs, passing content as a block for the component
+# to interpret via yield or custom methods.
+
+module EvcRails
+  module TemplateHandlers
+    class Evc
+      # Regex to match opening or self-closing PascalCase component tags with attributes
+      TAG_REGEX = %r{<([A-Z][a-zA-Z_]*)([^>]*)/?>}
+
+      # Regex to match closing PascalCase component tags
+      CLOSE_TAG_REGEX = %r{</([A-Z][a-zA-Z_]*)>}
+
+      # Regex for attributes: Supports string literals (key="value", key='value')
+      # and Ruby expressions (key={@variable}).
+      # Group 1: Attribute key, Group 2: Double-quoted value, Group 3: Single-quoted value,
+      # Group 4: Ruby expression.
+      ATTRIBUTE_REGEX = /(\w+)=(?:\"([^"]*)\"|'([^']*)'|\{([^}]*)\})/
+
+      # Cache for compiled templates to improve performance.
+      # @cache will store { identifier: { source: original_source, result: compiled_result } }
+      # Note: In a production environment, a more robust cache store (e.g., Rails.cache)
+      # might be preferred for persistence and memory management, especially for large applications.
+      # This simple in-memory cache is effective for a single process.
+      @cache = {}
+
+      def self.clear_cache # Class method to allow clearing cache manually, if needed
+        @cache = {}
+      end
+
+      def call(template, source = nil)
+        identifier = template.identifier
+
+        # Only use cache in non-development environments
+        # Check if cache exists for this template and if the source hasn't changed.
+        # This prevents recompilation of unchanged templates.
+        if !Rails.env.development? && self.class.instance_variable_get(:@cache)[identifier] &&
+           source == self.class.instance_variable_get(:@cache)[identifier][:source]
+          return self.class.instance_variable_get(:@cache)[identifier][:result]
+        end
+
+        # Process the template source into an ERB-compatible string
+        processed_source = process_template(source, template)
+
+        # Get the standard ERB handler and pass the processed source to it
+        erb_handler = ActionView::Template.registered_template_handler(:erb)
+        result = erb_handler.call(template, processed_source)
+
+        # Cache the result for future requests, but only in non-development environments.
+        # In development, templates change frequently, so caching would hinder development flow.
+        unless Rails.env.development?
+          self.class.instance_variable_set(:@cache, self.class.instance_variable_get(:@cache).merge({
+            identifier => { source: source, result: result }
+          }))
+        end
+        result
+      end
+
+      private
+
+      # A memoization cache for resolved component classes within a single template processing.
+      # This prevents repeated `constantize` calls for the same component name within `process_template`.
+      attr_reader :component_class_memo
+
+      def initialize
+        @component_class_memo = {}
+      end
+
+      # Processes the .evc template source, converting custom tags into Rails View Component render calls.
+      # This method is recursive to handle nested components.
+      def process_template(source, template)
+        # Using an array for `parts` and then joining at the end is generally more efficient
+        # for building strings in Ruby than repeated string concatenations (`<<`).
+        parts = []
+        pos = 0
+        stack = [] # Track [component_class_name, render_params_str, start_pos_in_source]
+
+        # Initialize memoization cache for this processing run
+        @component_class_memo = {}
+
+        while pos < source.length
+          # Try to match an opening or self-closing tag
+          if (match = TAG_REGEX.match(source, pos))
+            # Append text before the current tag to the result parts
+            parts << source[pos...match.begin(0)]
+            pos = match.end(0) # Move position past the matched tag
+
+            is_self_closing = match[0].end_with?("/>")
+            tag_name = match[1]
+            attributes_str = match[2].strip
+
+            # Determine the full component class name
+            component_class_name = if tag_name.end_with?("Component")
+                                     tag_name
+                                   else
+                                     "#{tag_name}Component"
+                                   end
+
+            # Validate if the component class exists using memoization.
+            # The component class will only be constantized once per unique class name
+            # within a single template processing call.
+            component_class = @component_class_memo[component_class_name] ||= begin
+              component_class_name.constantize
+            rescue NameError
+              raise ArgumentError, "Component #{component_class_name} not found in template #{template.identifier}"
+            end
+
+            # Parse attributes and format them for the render call
+            params = []
+            attributes_str.scan(ATTRIBUTE_REGEX) do |key, quoted_value, single_quoted_value, ruby_expression|
+              # Basic validation for attribute keys
+              unless key =~ /\A[a-z_][a-z0-9_]*\z/i
+                raise ArgumentError, "Invalid attribute key '#{key}' in template #{template.identifier}"
+              end
+
+              formatted_key = "#{key}:"
+              if ruby_expression
+                # For Ruby expressions, directly embed the expression.
+                params << "#{formatted_key} #{ruby_expression}"
+              elsif quoted_value
+                # For double-quoted string literals, escape double quotes within the value.
+                params << "#{formatted_key} \"#{quoted_value.gsub('"', '\"')}\""
+              elsif single_quoted_value
+                # For single-quoted string literals, escape single quotes within the value
+                # and wrap in double quotes for Ruby string literal syntax.
+                params << "#{formatted_key} \"#{single_quoted_value.gsub("'", "\\'")}\""
+              end
+            end
+
+            render_params_str = params.join(", ")
+
+            if is_self_closing
+              # If it's a self-closing tag, generate a simple render call.
+              parts << "<%= render #{component_class_name}.new(#{render_params_str}) %>"
+            else
+              # If it's an opening tag, push it onto the stack to await its closing tag.
+              stack << [component_class_name, render_params_str, pos]
+            end
+
+          # Try to match a closing tag
+          elsif (match = CLOSE_TAG_REGEX.match(source, pos))
+            # Append text before the closing tag to the result parts
+            parts << source[pos...match.begin(0)]
+            pos = match.end(0) # Move position past the matched tag
+
+            closing_tag_name = match[1]
+
+            # Check for unmatched closing tags
+            if stack.empty?
+              raise ArgumentError, "Unmatched closing tag </#{closing_tag_name}> in template #{template.identifier}"
+            end
+
+            # Pop the corresponding opening tag from the stack
+            component_class_name, render_params_str, start_pos = stack.pop
+
+            # Check for mismatched tags (e.g., <div></p>)
+            if component_class_name != closing_tag_name
+              raise ArgumentError, "Mismatched tags: expected </#{component_class_name}>, got </#{closing_tag_name}> in template #{template.identifier}"
+            end
+
+            # Recursively process the content between the opening and closing tags.
+            # This is where nested components are handled.
+            content = process_template(source[start_pos...match.begin(0)], template)
+
+            # Generate the render call with a block for the content.
+            parts << "<%= render #{component_class_name}.new(#{render_params_str}) do %>#{content}<% end %>"
+
+          else
+            # If no tags are matched, append the rest of the source and break the loop.
+            parts << source[pos..-1]
+            break
+          end
+        end
+
+        # After parsing, if the stack is not empty, it means there are unclosed tags.
+        unless stack.empty?
+          raise ArgumentError, "Unclosed tag <#{stack.last[0]}> in template #{template.identifier}"
+        end
+
+        # Join all the collected parts to form the final ERB string.
+        parts.join("")
+      end
+    end
+  end
+end

data/lib/evc_rails/version.rb

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

data/lib/evc_rails.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "rails"
+require "active_support/lazy_load_hooks"
+require "action_view"
+require_relative "evc_rails/version"
+require_relative "evc_rails/template_handler"
+require_relative "evc_rails/railtie"
+
+module EvcRails
+  class Error < StandardError; end
+end

data/sig/evc_rails.rbs

@@ -0,0 +1,4 @@
+module EvcRails
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: evc_rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- scttymn
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: view_component
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A Rails engine that provides a custom template handler for .evc files,
+  allowing developers to use PascalCase ViewComponent tags (e.g., <MyComponent />)
+  directly in their HTML, similar to JSX.
+email:
+- scotty@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/evc_rails.rb
+- lib/evc_rails/railtie.rb
+- lib/evc_rails/template_handler.rb
+- lib/evc_rails/version.rb
+- sig/evc_rails.rbs
+homepage: https://github.com/scttymn/evc_rails
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/scttymn/evc_rails
+  source_code_uri: https://github.com/scttymn/evc_rails
+  changelog_uri: https://github.com/scttymn/evc_rails/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Enables JSX-like PascalCase component tags in Rails .evc view files.
+test_files: []