view_component_subtemplates 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7f722cb0d9a6fcd6224817d0e22c98eac0e958fbc4e97fd40b756522aebe462
-  data.tar.gz: 23e07e652f582ed9827adb0ae6100c76587c9fd115346a5fe843f8cf0e8c881c
+  metadata.gz: acf9c5ce1fdb01c2939e9e5737cfaf2b66a38a9540f8f24eafadf3cb473aaba5
+  data.tar.gz: 78bfcfbc62662ab2d5ac93a7f56a1bf4fcdd410132bf23e356c58b9a503336f9
 SHA512:
-  metadata.gz: ac11be7bea5d9ecca0f28b03606a9044a75b3492f3e877bf0e73e97809e66e74d180bb595b314005e43176171889c4314fe60514e8a6ba63691261e04064922a
-  data.tar.gz: 88786270c38e3637cfbb5dc45ab0c4f44da14a06ed0c7a92f1d814f7bd09c2551739227172329fd02d035ddae1a834ffb3767c7afa14a16bd81a546d61ab7a48
+  metadata.gz: 85de07486ae8017548b8bcef1168967cecb340bfe3060564f33fc9779b8fef323703b364b38d2bde01814d7f4eecb9295f73fc620531ebf14a529108d6a8c7dd
+  data.tar.gz: 34d0b0f65cac64023cb71eecb06e6001dccb9f1b2144510ea71c21acbaf19cdf13cfaff17a19840ae7be55c09ce52ac3a157810cd11726ce836ab83e0f7800c3

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-12
+
+### Added
+- `render_subtemplate_in(view_context, name)` to render a single subtemplate on its own, from outside the component (e.g. a controller responding with just a fragment), without rendering the main template. It is the subtemplate-level counterpart of ViewComponent's `render_in`. The subtemplate must not declare locals (per-render data is passed through the component's constructor); rendering a subtemplate with locals, or one that is not defined, raises a clear error.
+
+## [0.2.0] - 2026-01-21
+
+### Added
+- Automatic subtemplate processing for ancestor components
+- Support for multi-level inheritance (grandparent → parent → child)
+
+### Fixed
+- Inheritance issue where child components miss parent's `call_*` methods
+
 ## [0.1.1] - 2026-01-13
 
 ### Changed

data/README.md

@@ -107,6 +107,47 @@ app/components/
 <%= render TableComponent.new(users: @users, title: "User List") %>
 ```
 
+## Rendering a subtemplate on its own
+
+Sometimes you need to render just one subtemplate, outside the component's main
+template. A common case is a controller action that responds to an AJAX request
+with only an updated fragment.
+
+Call `render_subtemplate_in` on a component instance, passing the current view
+context. The subtemplate **must not declare locals**: any per-render data is
+passed through the component's constructor, so the call site stays free of an
+untyped `**locals` boundary.
+
+```ruby
+class UsersController < ApplicationController
+  def row
+    component = RowComponent.new(user: User.find(params[:id]), highlight: false)
+
+    render html: component.render_subtemplate_in(view_context, :row), layout: false
+  end
+end
+```
+
+```erb
+<%# app/components/row_component/row.html.erb -- no `locals:` line %>
+<tr class="<%= 'highlighted' if @highlight %>"><td><%= @user.name %></td></tr>
+```
+
+`render_subtemplate_in(view_context, name)` renders the named subtemplate and
+returns its HTML as an html_safe string, without rendering the component's main
+template. It is the subtemplate-level counterpart of ViewComponent's `render_in`:
+`render_in(view_context)` is the external entry point for the main template
+(internally `call`), and `render_subtemplate_in` is the external entry point for
+a single subtemplate (internally `call_<name>`).
+
+`render_subtemplate_in` raises a clear error if the named subtemplate does not
+exist, or if it declares locals (pass that data through the component's
+constructor instead).
+
+**The no-locals rule applies only to standalone rendering.** Inside a component's
+templates, `call_<name>` keeps taking locals exactly as shown in the Quick Start;
+`render_subtemplate_in` is the only path that requires a no-locals subtemplate.
+
 ## Requirements
 
 - Ruby >= 3.1.0

data/lib/view_component_subtemplates/compiler_extension.rb

@@ -1,14 +1,24 @@
 # frozen_string_literal: true
 
-# compiler_extension.rb
 module ViewComponentSubtemplates
+  # Extends ViewComponent's compilation process to handle subtemplates.
   module CompilerExtension
-    # Processes a component class to compile its sub-templates.
-    # Called from the after_compile hook.
+    # Compiles all subtemplates for a component into call_* methods.
+    # Skips processing if already done for this component.
+    #
+    # @param component_class [Class] the component class to process
+    # @return [void]
     def self.process_component(component_class)
+      return if component_class.instance_variable_get(:@__subtemplates_processed)
+
       gather_sub_templates_for(component_class).each(&:compile_to_component)
+      component_class.instance_variable_set(:@__subtemplates_processed, true)
     end
 
+    # Discovers subtemplate files in the component's subdirectory.
+    #
+    # @param component_class [Class] the component class
+    # @return [Array<SubTemplate>] array of subtemplate objects
     def self.gather_sub_templates_for(component_class)
       component_subdir = ViewComponentSubtemplates.component_subdir_for(component_class)
       return [] unless Dir.exist?(component_subdir)
@@ -17,12 +27,8 @@ module ViewComponentSubtemplates
 
       Dir.glob(File.join(component_subdir, "*")).filter_map do |file_path|
         next unless File.file?(file_path)
+        next unless template_extensions.include?(File.extname(file_path)[1..])
 
-        file_extension = File.extname(file_path)[1..] # Remove the leading dot
-        next unless template_extensions.include?(file_extension)
-
-        # Correctly extract template name by removing the first extension found.
-        # e.g. "header.html.erb" -> "header"
         template_name = File.basename(file_path).split(".").first
 
         SubTemplate.new(

data/lib/view_component_subtemplates/standalone_renderer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ViewComponentSubtemplates
+  # Renders one subtemplate on its own (no main template), e.g. to serve a fragment
+  # from a controller. The subtemplate-level counterpart of `render_in`.
+  # Requires a no-locals subtemplate: per-render data goes through the constructor.
+  module StandaloneRenderer
+    # @param view_context [ActionView::Base] inside a controller, this is `view_context`.
+    # @param name [Symbol, String] subtemplate name, without the `call_` prefix.
+    # @return [String] the subtemplate's HTML (html_safe).
+    def render_subtemplate_in(view_context, name)
+      self.class.__vc_compile(raise_errors: true)
+      ensure_renderable_subtemplate!(name)
+
+      # Set up the view context the helper guards require. `__vc_original_view_context`
+      # makes `helpers` reuse it instead of building a new one (keep both).
+      @view_context = view_context
+      self.__vc_original_view_context = view_context
+
+      public_send("call_#{name}")
+    end
+
+    private
+
+    def ensure_renderable_subtemplate!(name)
+      call_method = "call_#{name}"
+      unless respond_to?(call_method)
+        raise ViewComponentSubtemplates::Error,
+              "Subtemplate `#{name}` is not defined on #{self.class}. " \
+              "Available subtemplates: #{available_subtemplates.join(", ").presence || "(none)"}."
+      end
+
+      return if method(call_method).parameters.empty?
+
+      raise ViewComponentSubtemplates::Error,
+            "Subtemplate `#{name}` declares locals; standalone rendering requires a subtemplate " \
+            "without locals. Pass per-render data through the component's constructor instead."
+    end
+
+    def available_subtemplates
+      methods.grep(/\Acall_(.+)\z/) { Regexp.last_match(1) }
+    end
+  end
+end

data/lib/view_component_subtemplates/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ViewComponentSubtemplates
-  VERSION = "0.1.1"
+  VERSION = "0.3.0"
 end

data/lib/view_component_subtemplates.rb

@@ -26,15 +26,21 @@ module ViewComponentSubtemplates
   module AfterCompileHook
     def after_compile
       super
-      ViewComponentSubtemplates::CompilerExtension.process_component(self)
+
+      # Process subtemplates for all ancestors (top to bottom) and self
+      ancestors.select { |a| a.is_a?(Class) && a < ViewComponent::Base }
+               .reverse
+               .each { |ancestor| ViewComponentSubtemplates::CompilerExtension.process_component(ancestor) }
     end
   end
 end
 
 # Load SubTemplate after the module is fully configured
 require_relative "view_component_subtemplates/sub_template"
+require_relative "view_component_subtemplates/standalone_renderer"
 
 # Hook into ViewComponent when it loads (lazy loading for faster boot in development)
 ActiveSupport.on_load(:view_component) do
   ViewComponent::Base.singleton_class.prepend(ViewComponentSubtemplates::AfterCompileHook)
+  ViewComponent::Base.include(ViewComponentSubtemplates::StandaloneRenderer)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: view_component_subtemplates
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - jsolas
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-14 00:00:00.000000000 Z
+date: 2026-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -53,6 +53,7 @@ files:
 - Rakefile
 - lib/view_component_subtemplates.rb
 - lib/view_component_subtemplates/compiler_extension.rb
+- lib/view_component_subtemplates/standalone_renderer.rb
 - lib/view_component_subtemplates/sub_template.rb
 - lib/view_component_subtemplates/version.rb
 homepage: https://github.com/bukhr/view_component_subtemplates