view_component_subtemplates 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ceb9e9e6a47b06706f7464baf5f4a2f5754b10b670ae3bf28dfed61ca3068027
-  data.tar.gz: 887ad1b1f30395592da4a3a90c78f22691715864f8e821e985c32cd4f0e1cf9a
+  metadata.gz: acf9c5ce1fdb01c2939e9e5737cfaf2b66a38a9540f8f24eafadf3cb473aaba5
+  data.tar.gz: 78bfcfbc62662ab2d5ac93a7f56a1bf4fcdd410132bf23e356c58b9a503336f9
 SHA512:
-  metadata.gz: d00849719d594843981c36d0bf85a44fa933b31fe1e49034434e92d18a6af377d7e89391e105f623bcff3a1727620f799827775bcf6ace4aa1afb76fe76ee003
-  data.tar.gz: fe2554a34486b1c27e3a452d5b5bc3b9830bba3677f284c5d1a5ae8cef43be5359b44f0cf4f7e01b756fa26d73f7ce9008ac22bfb2e063d623cacff30a6eada5
+  metadata.gz: 85de07486ae8017548b8bcef1168967cecb340bfe3060564f33fc9779b8fef323703b364b38d2bde01814d7f4eecb9295f73fc620531ebf14a529108d6a8c7dd
+  data.tar.gz: 34d0b0f65cac64023cb71eecb06e6001dccb9f1b2144510ea71c21acbaf19cdf13cfaff17a19840ae7be55c09ce52ac3a157810cd11726ce836ab83e0f7800c3

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [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

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/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.2.0"
+  VERSION = "0.3.0"
 end

data/lib/view_component_subtemplates.rb

@@ -37,8 +37,10 @@ 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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - jsolas
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-21 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