jsx_rosetta 0.5.1 → 0.6.0

data/lib/jsx_rosetta/backend/phlex.rb

@@ -2,6 +2,7 @@
 
 require_relative "../ast/inflector"
 require_relative "../ir/types"
+require_relative "../pages_routing"
 require_relative "base"
 require_relative "view_component/expression_translator"
 
@@ -69,19 +70,74 @@ module JsxRosetta
       # ViewComponent backend pattern (lib/jsx_rosetta/backend/view_component.rb).
       EventDescriptor = Data.define(:kind, :body)
 
-      def initialize(suffix: nil, namespace: nil)
+      RAILS_VIEW_BASE_CLASS = "Views::Base"
+
+      # Per-tag map of which attribute names carry a URL that the href
+      # rewriter should attempt to rewrite. Most link tags use `href`/`to`;
+      # `<form action="...">` uses `action`. Slice C1 added the `form`
+      # entry — non-GET forms are skipped at format_attributes time
+      # before they reach try_rewrite_href.
+      LINK_TAG_ATTRS = {
+        "a" => %w[href].freeze,
+        "Link" => %w[href to].freeze,
+        "NavLink" => %w[href to].freeze,
+        "RouterLink" => %w[href to].freeze,
+        "form" => %w[action].freeze
+      }.freeze
+      # Matches `router.push("…")` / `router.push('…')` / `router.push(\`…\`)`
+      # in verbatim hook source, capturing the quoted argument (including the
+      # surrounding quote/backtick). A3: only fires for sync hook bodies —
+      # event-handler bodies live in IR::EventHandler / IR::StimulusMethod
+      # sources, not in react_hooks, so they're naturally out of scope.
+      ROUTER_PUSH_PATTERN = /router\.push\(\s*("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`)\s*[,)]/
+
+      # Per-wrapper TODO header text. Each HOC that lowering peeled off the
+      # source (recorded on IR::Component#hoc_wrappers) gets one short line
+      # above the class explaining the Rails analog. Falls back to a
+      # generic line for wrappers not in this map.
+      HOC_WRAPPER_TODO_LINES = {
+        "memo" => "TODO: original component was wrapped in memo(...). React's memo memoizes " \
+                  "by shallow prop equality. Rails analog: fragment caching (`cache @model do …`) " \
+                  "when the view is expensive.",
+        "forwardRef" => "TODO: original component was wrapped in forwardRef(...). The second " \
+                        "arg (`ref`) was dropped — Rails has no view-side ref-forwarding analog; " \
+                        "use Stimulus targets / DOM ids if the host needs a handle.",
+        "observer" => "TODO: original component was wrapped in observer(...) (mobx). React's " \
+                      "observer auto-subscribes to observable state. Rails analog: the controller " \
+                      "loads data and sets @ivars; reactivity moves to Turbo Streams / Hotwire.",
+        "connect" => "TODO: original component was wrapped in connect(...)(X) (redux). Props " \
+                     "injected by mapState/mapDispatch in the source — in Rails, expect those as " \
+                     "controller-passed instance variables instead.",
+        "withRouter" => "TODO: original component was wrapped in withRouter(...) (React Router). " \
+                        "Injected router props (location, history, match) map to Rails: request.path, " \
+                        "redirect_to / form actions, and params.",
+        "withTranslation" => "TODO: original component was wrapped in withTranslation()(X) (i18n). " \
+                             "Injected `t` translator function maps to Rails I18n: `I18n.t(\"…\")` " \
+                             "or the `t` view helper."
+      }.freeze
+
+      def initialize(suffix: nil, namespace: nil, rails_view: nil, route_table: nil)
         super()
         raise ArgumentError, "Phlex backend: pass either suffix: or namespace:, not both" if suffix && namespace
+        if rails_view && (suffix || namespace)
+          raise ArgumentError, "Phlex backend: rails_view: cannot be combined with suffix: or namespace:"
+        end
 
         @suffix = suffix.is_a?(String) ? suffix : (DEFAULT_SUFFIX if suffix == true)
         @namespace = namespace
+        @rails_view = rails_view
+        @href_rewriter = route_table && PagesRouting::HrefRewriter.new(route_table)
       end
 
-      def emit(component)
+      def emit(component, source_filename: nil)
+        @current_component = component
         translator = build_translator(component)
         @stimulus_identifier = component.stimulus_methods.any? ? stimulus_identifier(component) : nil
         @lambda_methods = []
         @lambda_method_counts = {}
+        @event_handler_methods = []
+        @emit_module_prefix = first_emit_for_module_bindings?(component)
+        @source_filename = source_filename
 
         files = [File.new(path: ruby_path(component), contents: clean_output(render_ruby_class(component, translator)))]
         if component.stimulus_methods.any?
@@ -90,7 +146,29 @@ module JsxRosetta
             contents: render_stimulus_controller_js(component)
           )
         end
+        files.concat(lucide_icon_files(component))
         files
+      ensure
+        # Drop the per-emit IR reference so a long-running emitter
+        # instance doesn't pin the entire component tree until the
+        # next emit() call.
+        @current_component = nil
+      end
+
+      # When a source file lowers to multiple sibling components, lower_all
+      # attaches the *same* module_bindings array to every sibling. Emitting
+      # the constants TODO block on each one duplicates 40-line GraphQL
+      # blocks across every emitted .rb file. Track the array identities
+      # we've seen and only emit the prefix the first time.
+      def first_emit_for_module_bindings?(component)
+        return true if component.module_bindings.empty?
+
+        @seen_module_bindings ||= Set.new
+        key = component.module_bindings.object_id
+        return false if @seen_module_bindings.include?(key)
+
+        @seen_module_bindings << key
+        true
       end
 
       def build_translator(component)
@@ -99,10 +177,15 @@ module JsxRosetta
         prop_aliases = component.props.each_with_object({}) do |prop, hash|
           hash[prop.alias_name] = prop.name if prop.alias_name
         end
+        # `imported_names` covers both top-level `import` declarations AND
+        # top-level helper bindings (`function onError(){}`, `const FOO = …`).
+        # They behave identically at the use site — the translator bails out
+        # to `nil` rather than emitting a bare snake_case ref that NameErrors.
         ViewComponent::ExpressionTranslator.new(
           prop_names: prop_names,
           local_binding_names: component.local_binding_names,
-          prop_aliases: prop_aliases
+          prop_aliases: prop_aliases,
+          imported_names: component.module_imports.map(&:name) + component.module_bindings.map(&:name)
         )
       end
 
@@ -151,42 +234,234 @@ module JsxRosetta
       # letter when forming the class name. Pure-PascalCase names pass
       # through unchanged.
       def class_name(component)
+        return rails_view_class_name if @rails_view
+
         base = "#{component.name[0].upcase}#{component.name[1..]}"
-        @suffix ? "#{base}#{@suffix}" : base
+        suffix = effective_suffix_for(base, source_filename: @source_filename)
+        suffix ? "#{base}#{suffix}" : base
+      end
+
+      def rails_view_class_name
+        return rails_layout_class_name if @rails_view.kind == :layout
+
+        namespace_parts = (@rails_view.namespace || []).map { |ns| AST::Inflector.upper_camelize(ns) }
+        controller = AST::Inflector.upper_camelize(@rails_view.controller)
+        action = AST::Inflector.upper_camelize(@rails_view.action)
+        (["Views"] + namespace_parts + [controller, action]).join("::")
+      end
+
+      # Layouts land under Views::Layouts:: regardless of source path —
+      # `_app.tsx` → Views::Layouts::Application. There's only ever one
+      # "controller" for layouts (`layouts`), so the controller segment
+      # is collapsed into the namespace.
+      def rails_layout_class_name
+        action = AST::Inflector.upper_camelize(@rails_view.action)
+        "Views::Layouts::#{action}"
+      end
+
+      def parent_class
+        @rails_view ? RAILS_VIEW_BASE_CLASS : PHLEX_BASE_CLASS
+      end
+
+      # Pick the suffix to append to a class name, applying two rules in
+      # order:
+      #
+      # 1. **Page detection.** Source name ends in `Page` OR the source
+      #    file path contains `/pages/` (Next.js / Nuxt convention) →
+      #    use the literal `Page` suffix, regardless of the configured
+      #    `@suffix`. Lets the gem keep `<HomePage>` / `pages/home.tsx`
+      #    landing as `HomePage` / `home_page.rb` even when the user
+      #    passes `--phlex-suffix=Component` for the rest of the codebase.
+      # 2. **No double-suffix.** When the name already ends with the
+      #    chosen suffix (e.g. source `HomePage` with the `Page` suffix,
+      #    or source `FooComponent` with the `Component` suffix), skip
+      #    the append. Returns nil so callers don't concatenate.
+      #
+      # `source_filename` is the absolute or repo-relative path of the
+      # JSX source; nil when callers translate raw source strings
+      # without filename context (then only the name-based signal fires).
+      def effective_suffix_for(name, source_filename: nil)
+        suffix = page?(name, source_filename) ? "Page" : @suffix
+        return nil unless suffix
+        return nil if name.end_with?(suffix)
+
+        suffix
+      end
+
+      def page?(name, source_filename)
+        return true if name.end_with?("Page")
+        return false unless source_filename
+
+        source_filename.include?("/pages/")
       end
 
       def ruby_path(component)
+        return "#{rails_view_dir}/#{@rails_view.action}.rb" if @rails_view
+
         "#{AST::Inflector.underscore(class_name(component))}.rb"
       end
 
       def stimulus_path(component)
+        return "#{rails_view_dir}/#{@rails_view.action}_controller.js" if @rails_view
+
         "#{AST::Inflector.underscore(class_name(component))}_controller.js"
       end
 
+      def rails_view_dir
+        ((@rails_view.namespace || []) + [@rails_view.controller]).join("/")
+      end
+
       def stimulus_identifier(component)
         AST::Inflector.underscore(component.name).tr("_", "-")
       end
 
       def render_ruby_class(component, translator)
         class_body = render_class_body(component, translator)
-        prefix = render_module_bindings_prefix(component)
+        prefix = "#{render_hoc_wrappers_prefix(component)}" \
+                 "#{render_server_data_source_prefix(component)}" \
+                 "#{render_module_bindings_prefix(component)}"
         wrap_in_namespace("#{prefix}#{class_body}")
       end
 
+      def render_hoc_wrappers_prefix(component)
+        return "" if component.hoc_wrappers.empty?
+
+        lines = component.hoc_wrappers.map do |wrapper|
+          "# #{HOC_WRAPPER_TODO_LINES[wrapper] ||
+               "TODO: original component was wrapped in #{wrapper}(...). " \
+               "Verify the Rails-side equivalent (or absence) and adjust before shipping."}"
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      # When the source file exports `getServerSideProps` /
+      # `getStaticProps`, emit a TODO block above the class with the
+      # body verbatim. The block names the matching Rails controller
+      # action when `@rails_view` is set; otherwise it points at "the
+      # host controller" generically.
+      def render_server_data_source_prefix(component)
+        return "" unless component.server_data_source
+
+        sds = component.server_data_source
+        target = if @rails_view
+                   "#{AST::Inflector.upper_camelize(@rails_view.controller)}Controller##{@rails_view.action}"
+                 else
+                   "the host controller action"
+                 end
+        body_lines = comment_lines(sds.source)
+        lines = [
+          "# TODO: port the original Next.js `#{sds.hook_name}` to #{target}:",
+          "#",
+          *body_lines,
+          "#",
+          "# In Rails: load the data in the controller (set @ivars), and read",
+          "# them in this view via the standard props plumbing."
+        ]
+        "#{lines.join("\n")}\n"
+      end
+
       # Top-level `const`/`let` declarations outside the component
-      # function — captured at lowering time and surfaced here as a TODO
-      # comment block above the class definition. We don't try to
-      # translate the JS; the human reviewer either copies the value as
-      # a Ruby constant or moves it to a Rails initializer.
+      # function — captured at lowering time. Cva-shaped bindings get
+      # emitted as real Ruby constants (FOO_BASE_CLASS, etc.); generic
+      # local bindings still surface as a TODO comment block.
       def render_module_bindings_prefix(component)
         return "" if component.module_bindings.empty?
 
+        groups = component.module_bindings.group_by { |b| binding_group(b) }
+        cva_bindings = groups[:cva] || []
+        module_constants = groups[:module_constant] || []
+        other_bindings = groups[:other] || []
+        sections = []
+        # cva constants are *referenced* by every sibling's class body via
+        # FOO_BASE_CLASS / FOO_VARIANT_CLASSES — they have to land in every
+        # sibling's file or non-first siblings NameError at render. The
+        # non-cva TODO block is informational only, so it suppresses on
+        # later siblings to avoid duplicating 40-line GraphQL blocks.
+        sections << render_cva_constants(cva_bindings) unless cva_bindings.empty?
+        sections << render_module_constants(module_constants) unless module_constants.empty?
+        emit_todo_block = @emit_module_prefix && !other_bindings.empty?
+        sections << render_module_local_bindings_todo(other_bindings) if emit_todo_block
+        sections.compact.join("\n")
+      end
+
+      def binding_group(binding)
+        case binding
+        when IR::CvaBinding then :cva
+        when IR::ModuleConstant then :module_constant
+        else :other
+        end
+      end
+
+      # Emit each literal-shaped module-level const as a real Ruby constant.
+      # Hash and array values are emitted via Ruby's `inspect` and frozen so
+      # accidental mutation surfaces immediately. Scalars (string / number /
+      # bool / nil) skip the `.freeze` since they're already immutable in
+      # Ruby — keeps the output terse for the common `const TITLE = "X"` case.
+      def render_module_constants(constants)
+        lines = constants.map do |constant|
+          literal = constant.value.inspect
+          literal += ".freeze" if constant.value.is_a?(Hash) || constant.value.is_a?(Array) ||
+                                  constant.value.is_a?(String)
+          "#{constant.constant_name} = #{literal}"
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      # Emit one cva binding as a triplet of Ruby constants —
+      # FOO_BASE_CLASS, FOO_VARIANT_CLASSES, FOO_DEFAULT_VARIANTS — that
+      # the call-site interpolation in the class body references.
+      def render_cva_constants(cva_bindings)
+        lines = []
+        cva_bindings.each do |cva|
+          prefix = cva_constant_prefix(cva.name)
+          lines << "#{prefix}_BASE_CLASS = #{cva.base_class.inspect}"
+          lines << "#{prefix}_VARIANT_CLASSES = #{format_variants_literal(cva.variants)}.freeze"
+          unless cva.default_variants.empty?
+            lines << "#{prefix}_DEFAULT_VARIANTS = #{cva.default_variants.inspect}.freeze"
+          end
+          if cva.compound_source
+            lines << "# TODO: compoundVariants from #{cva.name} aren't translated — port by hand:"
+            lines.concat(comment_lines(cva.compound_source))
+          end
+          lines << ""
+        end
+        "#{lines.join("\n").rstrip}\n"
+      end
+
+      # Non-cva module bindings — the original Gap E pre-class TODO block.
+      # Distinct from the body-level `render_local_bindings_todo` further
+      # below in this file.
+      def render_module_local_bindings_todo(bindings)
         lines = ["# TODO: module-level constants — translate to Ruby constants " \
                  "or move to a Rails initializer:"]
-        component.module_bindings.each { |b| lines.concat(comment_lines(b.source)) }
+        bindings.each { |b| lines.concat(comment_lines(b.source)) }
         "#{lines.join("\n")}\n"
       end
 
+      # buttonVariants → BUTTON, alertVariants → ALERT. The degenerate
+      # name `"Variants"` would strip to `""` (a Ruby SyntaxError when
+      # used as a `_BASE_CLASS` prefix) — fall back to the raw name in
+      # that case. Two cva bindings whose names collapse to the same
+      # prefix (`fooVariant` and `fooVariants` → `FOO`) keep both forms
+      # disambiguated by upcasing the unstripped name as the fallback.
+      def cva_constant_prefix(cva_name)
+        stripped = cva_name.sub(/Variants?\z/, "")
+        base = stripped.empty? ? cva_name : stripped
+        AST::Inflector.underscore(base).upcase
+      end
+
+      def format_variants_literal(variants)
+        return "{}" if variants.empty?
+
+        lines = ["{"]
+        variants.each do |axis, options|
+          opts_pairs = options.map { |k, v| "#{k.inspect} => #{v.inspect}" }.join(", ")
+          lines << "  #{axis.inspect} => { #{opts_pairs} },"
+        end
+        lines << "}"
+        lines.join("\n")
+      end
+
       def wrap_in_namespace(body)
         return "# frozen_string_literal: true\n\n#{body}" unless @namespace
 
@@ -213,7 +488,7 @@ module JsxRosetta
         # body is intentionally minimal so it doesn't drift from the source
         # over time; a richer comment belongs in the host repo's review.
         "# #{cls} — generated by jsx_rosetta from JSX. Review before shipping.\n" \
-          "class #{cls} < #{PHLEX_BASE_CLASS}\n#{sections}\nend\n"
+          "class #{cls} < #{parent_class}\n#{sections}\nend\n"
       end
 
       # For data-factory components (`export const createColumns = (args)
@@ -252,12 +527,32 @@ module JsxRosetta
         lambda_methods = (@lambda_methods || []).map do |entry|
           render_lambda_method_definition(entry[:method_name], entry[:lambda], translator)
         end
-        all = render_methods + lambda_methods
+        event_handlers = (@event_handler_methods || []).map do |entry|
+          render_event_handler_method_definition(entry[:method_name], entry[:handler], entry[:attr_name])
+        end
+        all = render_methods + lambda_methods + event_handlers
         return nil if all.empty?
 
         "  private\n\n#{all.join("\n\n")}"
       end
 
+      # Emit one EventHandler as a stub method on the class. The JS body
+      # is preserved verbatim as a TODO comment; the method itself is a
+      # no-op so the file loads and the receiving component sees a real
+      # `Method` object via `method(:name)`. Parameter names snake_case
+      # from JS conventions to Ruby identifiers.
+      def render_event_handler_method_definition(method_name, handler, attr_name)
+        snake_params = handler.params.map { |p| AST::Inflector.underscore(p) }
+        signature = snake_params.empty? ? method_name : "#{method_name}(#{snake_params.join(", ")})"
+        body_lines = comment_lines(handler.body_source).map { |l| "    #{l}" }
+        [
+          "  def #{signature}",
+          "    # TODO: translate the original JSX `#{attr_name}` handler:",
+          *body_lines,
+          "  end"
+        ].join("\n")
+      end
+
       # Emit one RenderMethod as a private method on the class. Params are
       # pushed into the translator scope so identifier references inside
       # the body resolve to method-local arguments.
@@ -317,6 +612,15 @@ module JsxRosetta
       end
 
       def ruby_default_for(prop, translator)
+        # Use the cva defaultVariants entry as the initializer default when
+        # the prop name matches a cva axis and the JSX didn't already
+        # specify its own default. So `variant: 'default'` flows from the
+        # cva binding's defaultVariants, even though the React function
+        # signature took it as an undefaulted prop.
+        if prop.default.nil? && (cva_default = cva_axis_default_for(prop.name))
+          return cva_default.inspect
+        end
+
         return "nil" if prop.default.nil?
 
         case prop.default
@@ -336,41 +640,105 @@ module JsxRosetta
         end
       end
 
+      # Look up `prop_name` (e.g. "variant") across every CvaBinding on the
+      # current component. Returns the cva default value (e.g. "default") or
+      # nil when no cva binding declares that axis with a default.
+      def cva_axis_default_for(prop_name)
+        return nil unless @current_component
+
+        @current_component.module_bindings.each do |b|
+          next unless b.is_a?(IR::CvaBinding)
+          next unless b.default_variants.key?(prop_name)
+
+          return b.default_variants[prop_name]
+        end
+        nil
+      end
+
       def render_view_template(component, translator)
         body = render_template_body(component, translator)
-        prefix = render_template_prefix(component)
+        prefix = render_template_prefix(component, translator)
         body_with_prefix = prefix.empty? ? body : "#{prefix}#{body}"
         "  def view_template\n#{body_with_prefix}\n  end"
       end
 
-      def render_template_prefix(component)
+      def render_template_prefix(component, translator)
         lines = []
-        lines.concat(render_react_hooks_todo(component.react_hooks))
+        lines.concat(render_react_hooks_todo(component.react_hooks, translator))
         lines.concat(render_local_bindings_todo(component.local_bindings))
         return "" if lines.empty?
 
         "#{lines.map { |l| "    #{l}" }.join("\n")}\n"
       end
 
-      def render_react_hooks_todo(hooks)
+      def render_react_hooks_todo(hooks, translator)
         return [] if hooks.empty?
 
         # Preserve the source order of the first occurrence per library so
         # the React block (typical) lands before Apollo/Next.js blocks when
         # all three are present. group_by preserves first-seen order.
-        hooks.group_by(&:library).flat_map { |library, calls| hook_todo_block_lines(library, calls) }
+        hooks.group_by(&:library).flat_map { |library, calls| hook_todo_block_lines(library, calls, translator) }
       end
 
-      def hook_todo_block_lines(library, calls)
+      def hook_todo_block_lines(library, calls, translator)
         header_lines = HOOK_TODO_HEADERS.fetch(library, HOOK_TODO_HEADERS[:react])
         lines = header_lines.map { |line| "# #{line}" }
         calls.each do |call|
+          lines.concat(router_push_hint_lines(call.source, translator))
           lines << "#   operation: #{call.operation}" if call.operation
           lines.concat(comment_lines(call.source))
         end
         lines
       end
 
+      # Scan a hook's verbatim source for `router.push("…")` invocations and
+      # emit a one-line hint per match. With a route table the hint names
+      # the matching URL helper (`redirect_to user_path(@id)`); without one,
+      # it suggests adding the helper. See ROUTER_PUSH_PATTERN for the
+      # accepted shapes and why event-handler bodies are out of scope.
+      def router_push_hint_lines(source, translator)
+        source.scan(ROUTER_PUSH_PATTERN).flat_map do |(arg)|
+          hint = router_push_hint(arg, translator)
+          hint ? ["# #{hint}"] : []
+        end
+      end
+
+      def router_push_hint(arg, translator)
+        if arg.start_with?("`")
+          template_router_push_hint(arg, translator)
+        else
+          path = arg[1..-2]
+          literal_router_push_hint(path)
+        end
+      end
+
+      def literal_router_push_hint(path)
+        helper = @href_rewriter&.rewrite_literal(path)
+        return "→ redirect_to #{helper} (translated from router.push(#{path.inspect}))" if helper
+
+        "→ consider redirect_to <helper> for router.push(#{path.inspect}) (not in route table)"
+      end
+
+      def template_router_push_hint(template_src, translator)
+        segments = PagesRouting::HrefRewriter.parse_template_source(template_src)
+        return "→ consider redirect_to <helper> for router.push(#{template_src})" unless segments
+
+        translated = segments.map { |kind, value| kind == :hole ? translate_hole(value, translator) : [kind, value] }
+        return "→ consider redirect_to <helper> for router.push(#{template_src})" if translated.any?(&:nil?)
+
+        helper = @href_rewriter&.rewrite_template(translated)
+        return "→ redirect_to #{helper} (translated from router.push(#{template_src}))" if helper
+
+        "→ consider redirect_to <helper> for router.push(#{template_src}) (path not in route table)"
+      end
+
+      def translate_hole(js_source, translator)
+        translated = translator.translate(js_source)
+        return nil unless translated && translated.ruby != "nil"
+
+        [:hole, translated.ruby]
+      end
+
       def render_local_bindings_todo(bindings)
         return [] if bindings.empty?
 
@@ -409,6 +777,7 @@ module JsxRosetta
         when IR::Text then render_text(node, indent: indent)
         when IR::Interpolation then render_interpolation(node, translator, indent: indent)
         when IR::Comment then render_comment(node, indent: indent)
+        when IR::LayoutYield then "#{" " * indent}yield"
         end
       end
 
@@ -441,36 +810,81 @@ module JsxRosetta
 
       def render_element(element, translator, indent:)
         todos = []
-        attrs_source = format_attributes(element.attributes, translator, context: :html, todos: todos, indent: indent)
+        attrs_source = format_attributes(element.attributes, translator,
+                                         context: :html, tag: element.tag, todos: todos, indent: indent)
         method_call = "#{element.tag}#{attrs_source}"
+        body = element_body(element, method_call, translator, indent)
+        prepend_attribute_todos(todos, indent, body)
+      end
 
-        body = if VOID_ELEMENTS.include?(element.tag) || element.children.empty?
-                 "#{spaces(indent)}#{method_call}"
-               else
-                 inner = element.children.map { |c| render_ir_node(c, translator, indent: indent + 2) }.join("\n")
-                 "#{spaces(indent)}#{method_call} do\n#{inner}\n#{spaces(indent)}end"
-               end
+      # Decide whether the HTML tag is blockless, yield-only (auto-yield for
+      # self-closing-with-spread), or full do/end (explicit children).
+      def element_body(element, method_call, translator, indent)
+        return "#{spaces(indent)}#{method_call}" if blockless_element?(element)
 
-        prepend_attribute_todos(todos, indent, body)
+        if element.children.empty?
+          # `<tag {...rest} />` — the rest-spread carries React `children`,
+          # but JSX self-closes so there are no explicit IR children. Yield
+          # to the Phlex caller's block so `Component.new { ... }` nesting
+          # actually renders; guard with `block_given?` so callers who pass
+          # no block don't blow up.
+          yield_only_block(method_call, indent)
+        else
+          inner = element.children.map { |c| render_ir_node(c, translator, indent: indent + 2) }.join("\n")
+          "#{spaces(indent)}#{method_call} do\n#{inner}\n#{spaces(indent)}end"
+        end
+      end
+
+      def blockless_element?(element)
+        return true if VOID_ELEMENTS.include?(element.tag)
+
+        element.children.empty? && !spreads_children?(element)
       end
 
       def render_component_invocation(invocation, translator, indent:)
         todos = []
-        kwargs = component_invocation_kwargs(invocation.props, translator, todos: todos, indent: indent)
+        kwargs = component_invocation_kwargs(invocation.props, translator,
+                                             todos: todos, indent: indent, tag: invocation.name)
         class_ref = component_class_reference(invocation.name)
         new_call = kwargs.empty? ? "#{class_ref}.new" : "#{class_ref}.new(#{kwargs})"
+        body = component_invocation_body(invocation, new_call, translator, indent)
+        prepend_attribute_todos(todos, indent, body)
+      end
 
+      def component_invocation_body(invocation, new_call, translator, indent)
         render_prop = invocation.children.find { |c| c.is_a?(IR::RenderProp) }
-        body = if render_prop
-                 render_with_render_prop(new_call, render_prop, translator, indent)
-               elsif invocation.children.empty?
-                 "#{spaces(indent)}render #{new_call}"
-               else
-                 inner = invocation.children.map { |c| render_ir_node(c, translator, indent: indent + 2) }.join("\n")
-                 "#{spaces(indent)}render #{new_call} do\n#{inner}\n#{spaces(indent)}end"
-               end
+        return render_with_render_prop(new_call, render_prop, translator, indent) if render_prop
 
-        prepend_attribute_todos(todos, indent, body)
+        call = "render #{new_call}"
+        return "#{spaces(indent)}#{call}" if blockless_invocation?(invocation)
+
+        if invocation.children.empty?
+          # `<Component {...rest} />` — same idiom as element_body. The
+          # spread carries `children`; yield to the caller's block.
+          yield_only_block(call, indent)
+        else
+          inner = invocation.children.map { |c| render_ir_node(c, translator, indent: indent + 2) }.join("\n")
+          "#{spaces(indent)}#{call} do\n#{inner}\n#{spaces(indent)}end"
+        end
+      end
+
+      def blockless_invocation?(invocation)
+        invocation.children.empty? && !spreads_children?(invocation)
+      end
+
+      def yield_only_block(call, indent)
+        outer = spaces(indent)
+        inner = spaces(indent + 2)
+        "#{outer}#{call} do\n#{inner}yield if block_given?\n#{outer}end"
+      end
+
+      # Does this Element/ComponentInvocation carry a JSX rest-spread
+      # (`{...props}`) that may transport React `children` we can't see in
+      # the IR? Used to decide whether a self-closing JSX tag should still
+      # yield to the Phlex caller's block.
+      def spreads_children?(node)
+        attrs = node.respond_to?(:attributes) ? node.attributes : node.props
+        attrs.any?(IR::SpreadAttribute)
       end
 
       # Emit a render-prop child as a Ruby block on the parent `render` call.
@@ -497,9 +911,14 @@ module JsxRosetta
       # JSX `<Foo>` → `Foo` (default), `FooComponent` (suffix), or just
       # `Foo` again under namespace (Ruby's constant lookup finds the
       # peer class). JSX `<Foo.Bar>` → `Foo::Bar` (plus suffix when set).
+      # `<HomePage>` keeps the `Page` suffix without doubling (no
+      # `HomePageComponent`) — see effective_suffix_for. The path-based
+      # page detection doesn't apply here: an invocation only carries
+      # the JSX tag name, not the target file's path.
       def component_class_reference(jsx_tag)
         segments = jsx_tag.split(".")
-        segments[-1] = "#{segments.last}#{@suffix}" if @suffix
+        suffix = effective_suffix_for(segments.last)
+        segments[-1] = "#{segments.last}#{suffix}" if suffix
         segments.join("::")
       end
 
@@ -508,12 +927,80 @@ module JsxRosetta
       end
 
       def render_conditional(conditional, translator, indent:)
+        if guard_ladder?(conditional, translator)
+          return render_guard_ladder_collapse(conditional, translator, indent: indent)
+        end
+
         lines = []
         emit_conditional_branches(conditional, translator, indent, lines, leading_keyword: "if")
         lines << "#{spaces(indent)}end"
         lines.join("\n")
       end
 
+      # A guard ladder is a chain of `if/elsif` branches whose tests are all
+      # untranslatable AND whose consequents are all "render nothing" (the
+      # lowered form of `return null` in a guard), terminating in a real
+      # else branch. Emitted naively as `if false / elsif false / .../ else
+      # <main>`, the else *always* fires — silently inverting the source
+      # semantic ("render nothing when any guard hits") into "render main
+      # unconditionally." Collapse to a single TODO block + just the else
+      # so the reviewer sees what guards used to gate the render, and the
+      # main render is at least visible without the misleading `if false`s.
+      def guard_ladder?(conditional, translator)
+        branches, else_branch = walk_conditional_chain(conditional)
+        return false unless else_branch
+        return false if branches.empty?
+
+        branches.all? do |b|
+          test_translates_to_untranslatable?(b[:test], translator) && empty_consequent?(b[:consequent])
+        end
+      end
+
+      def render_guard_ladder_collapse(conditional, translator, indent:)
+        branches, else_branch = walk_conditional_chain(conditional)
+        lines = ["#{spaces(indent)}# TODO: #{branches.length} render guard(s) couldn't translate; wire up Rails-side:"]
+        branches.each do |b|
+          compact = b[:test].tr("\n", " ").squeeze(" ")
+          lines << "#{spaces(indent)}#   #{compact}"
+        end
+        lines << render_ir_node(else_branch, translator, indent: indent)
+        lines.join("\n")
+      end
+
+      def walk_conditional_chain(conditional)
+        branches = []
+        node = conditional
+        while node.is_a?(IR::Conditional)
+          branches << { test: node.test.expression, consequent: node.consequent }
+          node = node.alternate
+        end
+        [branches, node]
+      end
+
+      def test_translates_to_untranslatable?(expression, translator)
+        # Use condition-mode translation so bucket-4 hits (hook-tuple
+        # destructures, top-level imports) count as translatable. When a
+        # guard ladder's tests *do* translate under widening, the ladder
+        # collapses to nothing — render_conditional emits the real
+        # `if @ivar / elsif @ivar / else <main>` form, which correctly
+        # short-circuits to render nothing when any guard fires. Only
+        # untranslatable tests (verbatim JS we can't ivar-promote) still
+        # trip the collapse-to-TODO path.
+        translated = translator.translate_condition(expression)
+        translated.nil? || translated.ruby == "nil"
+      end
+
+      # An empty consequent is what `return null` (the JS guard idiom) lowers
+      # to. Detected as either a literal empty Text node or a Fragment whose
+      # children are all empty.
+      def empty_consequent?(node)
+        case node
+        when IR::Text then node.value.to_s.empty?
+        when IR::Fragment then node.children.all? { |c| empty_consequent?(c) }
+        else false
+        end
+      end
+
       # Walk a Conditional and its `alternate` chain, emitting `if` for the
       # first test, `elsif` for each alternate that is itself a Conditional,
       # and a final `else` for a non-Conditional alternate. Flattens the
@@ -522,8 +1009,13 @@ module JsxRosetta
       # this, deeply nested conditional chains explode the file's
       # indentation and trip Style/IfInsideElse + Metrics/BlockNesting.
       def emit_conditional_branches(conditional, translator, indent, lines, leading_keyword:)
-        test_ruby, todo = safe_test_expression(conditional.test.expression, translator, fallback: "false")
-        lines << "#{spaces(indent)}# TODO: translate condition: #{todo}" if todo
+        test_ruby, todo, promoted = safe_test_expression(conditional.test.expression, translator, fallback: "false")
+        if todo
+          lines << "#{spaces(indent)}# TODO: translate condition: #{todo}"
+        elsif promoted && !promoted.empty?
+          lines << "#{spaces(indent)}# TODO: render condition references binding(s) promoted to @ivar — " \
+                   "thread as controller-passed prop(s): #{promoted.join(", ")}"
+        end
         lines << "#{spaces(indent)}#{leading_keyword} #{test_ruby}"
         lines << render_ir_node(conditional.consequent, translator, indent: indent + 2)
 
@@ -565,32 +1057,51 @@ module JsxRosetta
         when IR::ArrayLiteral
           [render_array_literal_value(iterable, translator, todos: []), nil]
         when IR::Interpolation
-          safe_test_expression(iterable.expression, translator, fallback: "[]")
+          safe_iterable_expression(iterable.expression, translator)
         else
           ["[]", iterable.inspect]
         end
       end
 
+      # Iterable variant of safe_test_expression. Uses narrow (non-condition)
+      # translation: a hook-tuple `items` translates to `nil` here rather than
+      # being promoted to `@items`. Rationale: `nil.each` would crash at
+      # render time; `[].each` renders nothing while the accompanying TODO
+      # documents what didn't translate. Render-condition contexts (A1)
+      # take the opposite trade-off because driving `if nil` silently
+      # disables a load-bearing decision.
+      def safe_iterable_expression(expression, translator)
+        translated = translator.translate(expression)
+        return [translated.ruby, nil] if translated && translated.ruby != "nil"
+
+        compact = expression.tr("\n", " ").squeeze(" ")
+        ["[]", compact]
+      end
+
       # Translate an expression intended to drive an `if` or `.each` call.
-      # Returns `[ruby_source, todo_text]`. When the translator can parse
-      # the expression, `todo_text` is nil. When it can't, the caller's
-      # `fallback` (e.g. `"false"` for conditions, `"[]"` for iterables)
-      # is returned along with the original expression so a TODO comment
-      # can be emitted above the call. Without this, JS operators like
-      # `!==`, `===`, optional chaining, and `in` would leak into the
-      # emitted Ruby and produce SyntaxError on load.
+      # Returns `[ruby_source, todo_text, promoted_locals]`:
+      #   - When the translator can parse the expression cleanly, `todo_text`
+      #     is nil. `promoted_locals` carries any bucket-4 names the
+      #     condition-mode translator promoted to `@ivar` — the caller
+      #     surfaces these in a TODO so a reviewer knows which bindings need
+      #     to become controller-passed props.
+      #   - When the translator can't, the caller's `fallback` (`"false"` for
+      #     conditions, `"[]"` for iterables) is returned with the verbatim
+      #     expression in `todo_text` so a TODO comment can be emitted. Without
+      #     this, JS operators like `!==`, `===`, optional chaining, and `in`
+      #     would leak into Ruby and produce SyntaxError on load.
       #
-      # A translated value of `"nil"` is treated as untranslatable: the
-      # translator returns `"nil"` for known-local bindings (so the file
-      # loads as a leaf reference), but driving an `if` with `nil` silently
-      # disables the whole branch. Fall through to the TODO path instead so
-      # the human reviewer sees what needs filling in.
+      # Condition-mode translation (`translate_condition`) is used for both
+      # branches — it widens bucket-4 hits to `@ivar` so `if loading; …`
+      # becomes `if @loading; …` instead of the dead `if false` fallback.
+      # The promoted list separates that path from full-clean translation,
+      # which has nothing to flag.
       def safe_test_expression(expression, translator, fallback:)
-        translated = translator.translate(expression)
-        return [translated.ruby, nil] if translated && translated.ruby != "nil"
+        translated = translator.translate_condition(expression)
+        return [translated.ruby, nil, translated.promoted_locals] if translated && translated.ruby != "nil"
 
         compact = expression.tr("\n", " ").squeeze(" ")
-        [fallback, compact]
+        [fallback, compact, []]
       end
 
       def render_slot(slot, indent:)
@@ -656,22 +1167,31 @@ module JsxRosetta
       # of `h1()`). The `context:` param selects naming convention:
       #   - :html       (HTML element attrs — preserve camelCase for SVG)
       #   - :component  (Ruby method args — snake_case via Inflector.underscore)
-      def format_attributes(attributes, translator, context: :html, todos: [], indent: 0)
+      def format_attributes(attributes, translator, context: :html, tag: nil, todos: [], indent: 0)
         events, others = attributes.partition { |a| a.is_a?(IR::EventBinding) || a.is_a?(IR::StimulusBinding) }
         spreads, plain_attrs = others.partition { |a| a.is_a?(IR::SpreadAttribute) }
 
+        # Per-element form-method check. Set before any attribute renders
+        # so try_rewrite_href can consult it. Scoped per element via a
+        # local backup/restore around the iteration — nested forms are
+        # rare but legal HTML.
+        prev_form_rewritable = @form_action_rewritable
+        @form_action_rewritable = tag == "form" ? form_action_rewritable?(plain_attrs) : false
+
         parts = { sym: [], str: [] }
         plain_attrs.each do |a|
-          append_attribute_part(a, translator, parts, context: context, todos: todos, indent: indent)
+          append_attribute_part(a, translator, parts, context: context, tag: tag, todos: todos, indent: indent)
         end
         parts[:sym] << data_action_entry(events, translator) if events.any?
 
         joined = build_attribute_list(parts, spreads, translator)
         joined.empty? ? "" : "(#{joined})"
+      ensure
+        @form_action_rewritable = prev_form_rewritable
       end
 
-      def append_attribute_part(attribute, translator, parts, context:, todos:, indent: 0)
-        part = phlex_attribute_part(attribute, translator, context: context, todos: todos, indent: indent)
+      def append_attribute_part(attribute, translator, parts, context:, todos:, indent: 0, tag: nil)
+        part = phlex_attribute_part(attribute, translator, context: context, tag: tag, todos: todos, indent: indent)
         return unless part
 
         (part[:string_key] ? parts[:str] : parts[:sym]) << part[:source]
@@ -686,23 +1206,102 @@ module JsxRosetta
 
       # Emit one attribute as either a {string_key: false, source: "id: @x"}
       # (Ruby-kwarg-safe name) or {string_key: true, source: '"xml:lang" => @x'}
-      # (rare; non-identifier name — goes into a **{ ... } splat).
-      def phlex_attribute_part(attribute, translator, context:, todos:, indent: 0)
+      # (rare; non-identifier name — goes into a **{ ... } splat). Returns
+      # nil to signal "drop this attribute entirely" — used when every style
+      # declaration dropped (would emit `style: ''`) or every plain-attribute
+      # value bailed (would emit `attr: nil`); the TODO comment above the
+      # element already describes what was lost.
+      def phlex_attribute_part(attribute, translator, context:, todos:, indent: 0, tag: nil)
         case attribute
+        when IR::CvaCallSite then cva_call_site_attribute_part(attribute, translator)
         when IR::StyleBinding then class_attribute_part(attribute.expression, translator)
         when IR::ClassList then { string_key: false, source: "class: #{class_list_to_ruby_string(attribute, translator)}" }
-        when IR::Style then { string_key: false, source: "style: #{style_to_ruby_string(attribute, translator, todos: todos)}" }
+        when IR::Style then style_attribute_part(attribute, translator, todos: todos)
         when IR::Attribute
-          plain_attribute_part(attribute, translator, context: context, todos: todos, indent: indent)
+          plain_attribute_part(attribute, translator, context: context, tag: tag, todos: todos, indent: indent)
         end
       end
 
+      # Skip the `style:` kwarg entirely when every declaration failed to
+      # translate — `style: ''` is invalid HTML output and pure noise; the
+      # per-declaration TODO comments above the element preserve what was
+      # there.
+      def style_attribute_part(style, translator, todos:)
+        ruby = style_to_ruby_string(style, translator, todos: todos)
+        return nil if empty_style_ruby?(ruby)
+
+        { string_key: false, source: "style: #{ruby}" }
+      end
+
+      def empty_style_ruby?(ruby)
+        ["''", '""'].include?(ruby)
+      end
+
+      # A "dropped" attribute is one where translation failed AND the
+      # fallback was the literal `nil` string. We detect this by watching
+      # whether a TODO was appended during the value computation: a real
+      # `attr={null}` in the source produces `nil` *without* a TODO and
+      # should still emit (preserves intent); a failed translation
+      # produces `nil` *with* a TODO and we drop the kwarg to keep output
+      # clean — the TODO above the element already describes the loss.
+      def dropped_value?(value_ruby, todos_before, todos_after)
+        value_ruby == "nil" && todos_after.length > todos_before
+      end
+
       def class_attribute_part(expression, translator)
         translated = translator.translate(expression)
         ruby = translated ? translated.ruby : expression.inspect
         { string_key: false, source: "class: #{ruby}" }
       end
 
+      # Render an IR::CvaCallSite as the `class:` kwarg. Always produces
+      # a single Ruby string-interpolation literal that references the
+      # backend-emitted constants for the cva binding. The detection
+      # happened at lowering time (in `try_lower_cva_call_site`), so the
+      # node already carries the binding name, axes, and optional
+      # class_arg — no regex over verbatim JS source here.
+      def cva_call_site_attribute_part(node, translator)
+        cva = find_cva_binding(node.binding_name)
+        return { string_key: false, source: "class: nil" } unless cva
+
+        parts = cva_call_site_parts(node, cva, translator)
+        { string_key: false, source: %(class: "#{parts.join(" ")}") }
+      end
+
+      def find_cva_binding(binding_name)
+        @current_component&.module_bindings&.find do |b|
+          b.is_a?(IR::CvaBinding) && b.name == binding_name
+        end
+      end
+
+      def cva_call_site_parts(node, cva, translator)
+        prefix = cva_constant_prefix(cva.name)
+        parts = ["\#{#{prefix}_BASE_CLASS}"]
+        node.axes.each do |pair|
+          next unless cva.variants.key?(pair.axis)
+
+          parts << "\#{#{prefix}_VARIANT_CLASSES[#{pair.axis.inspect}][#{cva_axis_ruby_value(pair)}]}"
+        end
+        parts << "\#{#{cva_class_arg_ruby(node.class_arg, translator)}}" if node.class_arg
+        parts
+      end
+
+      def cva_class_arg_ruby(class_arg, translator)
+        translated = translator.translate(class_arg.expression)
+        return translated.ruby if translated
+
+        "@#{AST::Inflector.underscore(class_arg.expression)}"
+      end
+
+      def cva_axis_ruby_value(pair)
+        case pair.kind
+        when :literal_string then pair.source.inspect
+        when :literal_other then pair.source
+        when :literal_nil then "nil"
+        when :prop_ref then "@#{AST::Inflector.underscore(pair.source)}"
+        end
+      end
+
       # Map a JSX attribute name to its Ruby kwarg form. For HTML element
       # attrs (`context: :html`), only hyphens convert to underscores —
       # camelCase (`viewBox`, `preserveAspectRatio`) preserves verbatim
@@ -712,8 +1311,12 @@ module JsxRosetta
       # follow snake_case convention (`defaultValue` → `default_value`).
       # Names that aren't valid Ruby identifiers after conversion (rare:
       # `xml:lang` and friends) fall back to a quoted string key.
-      def plain_attribute_part(attribute, translator, context:, todos:, indent: 0)
-        value_ruby = attribute_value_to_ruby(attribute.name, attribute.value, translator, todos: todos, indent: indent)
+      def plain_attribute_part(attribute, translator, context:, todos:, indent: 0, tag: nil)
+        todos_before = todos.length
+        value_ruby = attribute_value_to_ruby(attribute.name, attribute.value, translator,
+                                             todos: todos, indent: indent, tag: tag)
+        return nil if dropped_value?(value_ruby, todos_before, todos)
+
         ruby_name = case context
                     when :component then AST::Inflector.underscore(attribute.name)
                     else attribute.name.tr("-", "_")
@@ -725,7 +1328,11 @@ module JsxRosetta
         end
       end
 
-      def attribute_value_to_ruby(name, value, translator, todos:, indent: 0)
+      def attribute_value_to_ruby(name, value, translator, todos:, indent: 0, tag: nil)
+        if (rewrite = try_rewrite_href(name, value, translator, tag: tag))
+          return rewrite
+        end
+
         case value
         when true then "true"
         when String then AST::Inflector.ruby_string_literal(value)
@@ -733,9 +1340,89 @@ module JsxRosetta
         when IR::ObjectLiteral then render_object_literal_value(value, translator, todos: todos, indent: indent)
         when IR::ArrayLiteral then render_array_literal_value(value, translator, todos: todos, indent: indent)
         when IR::Lambda then render_lambda_method_reference(value, translator, attr_name: name)
+        when IR::EventHandler then render_event_handler_method_reference(value, attr_name: name)
+        when IR::ComponentInvocation
+          component_invocation_value(value, translator, todos: todos, attr_name: name)
+        when IR::Element, IR::Fragment
+          # An HTML tag (`title={<span>x</span>}`) or a multi-element
+          # Fragment as an attribute value needs a Phlex execution context
+          # the receiver might not provide. Drop with a TODO rather than
+          # emit a broken kwarg or a speculative method reference.
+          drop_jsx_value_with_todo(name, value, todos: todos)
         end
       end
 
+      # Slice 3: rewrite `href`/`to` on link-shaped tags to a Rails URL
+      # helper call when the literal/template-literal path matches a
+      # route in the scanned table. Returns nil to fall through to the
+      # default emission path. Slice C1 added `<form action>` — see
+      # form_action_rewritable? for the method-attribute check.
+      def try_rewrite_href(name, value, translator, tag:)
+        return nil unless @href_rewriter
+        return nil unless tag
+
+        allowed_attrs = LINK_TAG_ATTRS[tag]
+        return nil unless allowed_attrs&.include?(name)
+        return nil if tag == "form" && !@form_action_rewritable
+
+        case value
+        when String
+          @href_rewriter.rewrite_literal(value)
+        when IR::Interpolation
+          rewrite_interpolation_href(value.expression, translator)
+        end
+      end
+
+      # `<form action="…">` only rewrites for safe (GET) submissions —
+      # slice-1 routes are GET-only, so POST/PUT/DELETE forms must stay
+      # verbatim until the route table supports non-GET routes. Returns
+      # true when no method attr is set (HTML default = GET) or when the
+      # method is a literal GET; false otherwise (including interpolated
+      # / TODO methods where we can't statically prove GET).
+      def form_action_rewritable?(attributes)
+        method_attr = attributes.find { |a| a.is_a?(IR::Attribute) && a.name == "method" }
+        return true unless method_attr
+
+        case method_attr.value
+        when nil, true then true
+        when String then method_attr.value.casecmp("get").zero?
+        else false
+        end
+      end
+
+      def rewrite_interpolation_href(js_source, translator)
+        if (literal = string_literal_path(js_source))
+          return @href_rewriter.rewrite_literal(literal)
+        end
+
+        segments = PagesRouting::HrefRewriter.parse_template_source(js_source)
+        return nil unless segments
+
+        translated = segments.map do |kind, val|
+          next [:literal, val] if kind == :literal
+
+          result = translator.translate(val)
+          return nil unless result && result.ruby != "nil"
+
+          [:hole, result.ruby]
+        end
+        @href_rewriter.rewrite_template(translated)
+      end
+
+      def string_literal_path(js_source)
+        return nil unless js_source.is_a?(String)
+        return nil unless js_source.length >= 2
+
+        first = js_source[0]
+        return nil unless ['"', "'"].include?(first)
+        return nil unless js_source[-1] == first
+
+        body = js_source[1..-2]
+        return nil if body.include?(first) || body.include?("\\")
+
+        body
+      end
+
       # Render an ObjectLiteral as a Ruby hash literal. Identifier-keyed
       # entries become Ruby kwargs (snake_cased to match Ruby convention);
       # non-identifier keys (numeric, hyphenated) fall back to string keys.
@@ -805,8 +1492,13 @@ module JsxRosetta
         when IR::ArrayLiteral
           render_array_literal_value(value, translator, todos: todos, indent: indent, force_inline: force_inline)
         when IR::Lambda then render_lambda_method_reference(value, translator, attr_name: attr_name)
+        when IR::EventHandler then render_event_handler_method_reference(value, attr_name: attr_name)
         when IR::Interpolation then interpolated_attribute_value(attr_name || "<element>", value, translator,
                                                                  todos: todos)
+        when IR::ComponentInvocation
+          component_invocation_value(value, translator, todos: todos, attr_name: attr_name)
+        when IR::Element, IR::Fragment
+          drop_jsx_value_with_todo(attr_name, value, todos: todos)
         when String then AST::Inflector.ruby_string_literal(value)
         when true then "true"
         else
@@ -843,6 +1535,31 @@ module JsxRosetta
         @lambda_method_counts[base] == 1 ? base : "#{base}#{@lambda_method_counts[base]}"
       end
 
+      # Inline arrow event handler on a PascalCase tag — `onClick={() =>
+      # doX()}` on `<Button>`. Extract to a stub method on the class and
+      # reference via `method(:handle_click)` at the kwarg position so the
+      # receiving component has a callable. The body translation is left
+      # to the human reviewer (the JS source is preserved as a TODO
+      # comment inside the method), but the structural wiring is intact.
+      def render_event_handler_method_reference(handler, attr_name:)
+        @event_handler_methods ||= []
+        base = event_handler_method_base(attr_name)
+        method_name = unique_lambda_method_name(base)
+        @event_handler_methods << { handler: handler, method_name: method_name, attr_name: attr_name }
+        "method(:#{method_name})"
+      end
+
+      # Map a JSX attribute name to an idiomatic Ruby handler-method name.
+      # `onClick` → `handle_click` (mirrors React's `handleClick` convention,
+      # snake_cased). Non-event attrs (rare — a callback prop with no `on`
+      # prefix) fall back to `<attr>_handler`.
+      def event_handler_method_base(attr_name)
+        return "anonymous_handler" if attr_name.nil? || attr_name.empty?
+
+        snake = AST::Inflector.underscore(attr_name)
+        snake.start_with?("on_") ? "handle_#{snake.delete_prefix("on_")}" : "#{snake}_handler"
+      end
+
       # Attribute-position interpolation. Three failure modes:
       #   1. Translator returns non-nil, no unresolved identifiers — emit
       #      the Ruby reference directly. Common case.
@@ -859,9 +1576,7 @@ module JsxRosetta
       #      template literals with method calls). Same TODO + nil path.
       def interpolated_attribute_value(name, value, translator, todos:)
         translated = translator.translate(value.expression)
-        if translated && !uppercase_unresolved?(translated.unresolved_identifiers)
-          return translated.ruby
-        end
+        return translated.ruby if translated && !uppercase_unresolved?(translated.unresolved_identifiers)
 
         compact = value.expression.tr("\n", " ").squeeze(" ")
         todos << "attribute #{name.inspect} dropped — couldn't translate: #{compact}"
@@ -872,13 +1587,84 @@ module JsxRosetta
         unresolved_identifiers.any? { |name| name[0] == name[0].upcase }
       end
 
-      def component_invocation_kwargs(props, translator, todos: [], indent: 0)
+      # JSX appearing as an attribute value — typically `icon={<Foo/>}` or
+      # `fallback={<Loading/>}` on antd/MUI components. Emitted as a
+      # component-instance value: `icon: FooComponent.new`. The receiving
+      # Phlex component can render it directly via `render @icon`. Closes
+      # the largest single category of attribute-value drops we were
+      # silently emitting as `attr: nil` + TODO.
+      #
+      # Three child-handling tiers:
+      #   1. No children — `ClassRef.new(kwargs)` on one line.
+      #   2. Children whose rendered Phlex body fits a single line — emit
+      #      as a block: `ClassRef.new(kwargs) { plain "x" }`. The block
+      #      runs in the child component's render context, so HTML helpers
+      #      resolve correctly.
+      #   3. Children that need multiple lines, or any IR::Element /
+      #      IR::Fragment we can't represent inline — fall back to the
+      #      existing TODO drop. Out of MVP scope; expand later if the
+      #      stress numbers warrant it.
+      def component_invocation_value(invocation, translator, todos:, attr_name:)
+        return drop_attribute_with_todo(attr_name, invocation, todos: todos) if invocation_has_render_prop?(invocation)
+
+        kwargs = component_invocation_kwargs(invocation.props, translator, todos: todos, indent: 0)
+        class_ref = component_class_reference(invocation.name)
+        new_call = kwargs.empty? ? "#{class_ref}.new" : "#{class_ref}.new(#{kwargs})"
+
+        return new_call if invocation.children.empty?
+
+        block_body = render_inline_children(invocation.children, translator)
+        return drop_attribute_with_todo(attr_name, invocation, todos: todos) unless block_body
+
+        "#{new_call} { #{block_body} }"
+      end
+
+      def invocation_has_render_prop?(invocation)
+        invocation.children.any?(IR::RenderProp)
+      end
+
+      # Render children to a single-line Phlex block body. Returns nil when
+      # any child needs multiple lines or isn't representable inline — the
+      # caller falls back to the TODO drop.
+      def render_inline_children(children, translator)
+        rendered = children.map { |c| render_ir_node(c, translator, indent: 0) }
+        return nil if rendered.any? { |line| line.include?("\n") }
+
+        joined = rendered.join("; ")
+        joined.length <= LITERAL_INLINE_BUDGET ? joined : nil
+      end
+
+      def drop_attribute_with_todo(attr_name, invocation, todos:)
+        label = attr_name || "<element>"
+        compact = invocation_source_summary(invocation)
+        todos << "attribute #{label.inspect} dropped — couldn't inline JSX value: #{compact}"
+        "nil"
+      end
+
+      def invocation_source_summary(invocation)
+        tag = invocation.name
+        suffix = invocation.children.empty? ? "/" : "...>"
+        "<#{tag}#{suffix}"
+      end
+
+      def drop_jsx_value_with_todo(attr_name, value, todos:)
+        label = attr_name || "<element>"
+        summary = case value
+                  when IR::Element then "<#{value.tag}...>"
+                  when IR::Fragment then "<>...</>"
+                  else "<JSX>"
+                  end
+        todos << "attribute #{label.inspect} dropped — couldn't inline JSX value: #{summary}"
+        "nil"
+      end
+
+      def component_invocation_kwargs(props, translator, todos: [], indent: 0, tag: nil)
         events, others = props.partition { |a| a.is_a?(IR::EventBinding) || a.is_a?(IR::StimulusBinding) }
         spreads, plain_attrs = others.partition { |a| a.is_a?(IR::SpreadAttribute) }
 
         parts = { sym: [], str: [] }
         plain_attrs.each do |a|
-          append_attribute_part(a, translator, parts, context: :component, todos: todos, indent: indent)
+          append_attribute_part(a, translator, parts, context: :component, tag: tag, todos: todos, indent: indent)
         end
         parts[:sym] << data_action_entry(events, translator) if events.any?
 
@@ -995,15 +1781,77 @@ module JsxRosetta
         "#{lines.join("\n")}\n"
       end
 
+      # Stimulus method emission. JSX inline arrow bodies are valid JS already;
+      # for DOM-driven handlers (the common shadcn shape) we just paste the body
+      # verbatim into the method, naming the JS parameter to match the original
+      # arrow's parameter so identifier references in the body still resolve.
+      #
+      # When the body references React-state setters or hooks we can't run in
+      # the browser, fall back to the previous TODO-comment behavior so the
+      # human reviewer ports it by hand.
       def stimulus_method_lines(method)
-        body_lines = method.body_source.strip.split("\n")
-        commented = body_lines.map { |line| "  //   #{line}" }
-        header = ["  // TODO: translate from the original JSX handler:"]
+        lines = []
         if method.name != method.original_name
-          header.unshift("  // NOTE: method renamed from #{method.original_name.inspect} " \
-                         "to avoid collision with an earlier handler")
+          lines << "  // NOTE: method renamed from #{method.original_name.inspect} " \
+                   "to avoid collision with an earlier handler"
+        end
+
+        if safe_to_paste_handler?(method)
+          lines.concat(pasted_handler_lines(method))
+        else
+          lines.concat(todo_handler_lines(method))
         end
-        header + commented + [
+
+        lines
+      end
+
+      # Heuristic for "this JS body is safe to drop into a Stimulus method
+      # verbatim." Bails out when:
+      #   - any arrow param wasn't a plain Identifier (destructured / rest) —
+      #     pasting would reference an undefined local at runtime;
+      #   - the body is the identifier-bound pseudo-comment we synthesize
+      #     when an `onClick={onChange}` reference resolved to no arrow;
+      #   - the body calls a top-level React state setter (`setX(`) or hook
+      #     (`useX(`) — the negative lookbehind on `[.\w]` makes sure DOM
+      #     methods like `e.setAttribute(` / `el.setPointerCapture(` don't
+      #     trip the guard.
+      def safe_to_paste_handler?(method)
+        return false unless method.params.all?
+
+        body = method.body_source
+        return false if body.lstrip.start_with?("//")
+        return false if body =~ /(?<![.\w])set[A-Z]\w*\(/
+        return false if body =~ /(?<![.\w])use[A-Z]\w*\(/
+
+        true
+      end
+
+      # Paste the JS body into the method, using the original arrow's first
+      # parameter name (so the body's references still resolve). Strip the
+      # outer `{ … }` wrapper only when the body was an arrow BlockStatement
+      # (`(e) => { … }`), not an expression-form body like `(e) => ({ x: 1 })`
+      # which Babel hands back as `{ x: 1 }` already — stripping would yield
+      # `x: 1`, a JS label statement (no-op).
+      def pasted_handler_lines(method)
+        param = method.params.first || "event"
+        body = method.body_source.strip
+        body = body[1..-2].strip if method.body_is_block
+        inner_lines = body.split("\n").map { |l| "    #{l.lstrip}" }
+        [
+          "  #{method.name}(#{param}) {",
+          *inner_lines,
+          "  }"
+        ]
+      end
+
+      # Fallback for handlers that aren't safe to paste verbatim — preserve
+      # the original body as a comment and emit an empty method body.
+      def todo_handler_lines(method)
+        body_lines = method.body_source.strip.split("\n")
+        commented = body_lines.map { |line| "  //   #{line}" }
+        [
+          "  // TODO: translate from the original JSX handler:",
+          *commented,
           "  #{method.name}(event) {",
           "    // ...",
           "  }"
@@ -1013,6 +1861,159 @@ module JsxRosetta
       def spaces(count)
         " " * count
       end
+
+      # ----------------------------------------------------------------------
+      # Lucide icon sidecars
+      # ----------------------------------------------------------------------
+      #
+      # When a translated component references `<ChevronRight />` after
+      # `import { ChevronRight } from "lucide-react"`, the consumer ends up
+      # with a `render ChevronRight.new(...)` call against a Ruby class that
+      # doesn't exist. To close that NameError, we emit one Phlex class per
+      # referenced icon as a sidecar file (`chevron_right.rb` etc.) plus a
+      # shared `lucide_icon.rb` base. Each file follows Zeitwerk's
+      # one-constant-per-file convention so it drops straight into
+      # `app/components/` without further configuration.
+
+      def lucide_icon_files(component)
+        usages = referenced_lucide_icons(component)
+        return [] if usages.empty?
+
+        @seen_lucide_icons ||= Set.new
+        files = []
+        unless @seen_lucide_icons.include?(:base)
+          files << File.new(path: "lucide_icon.rb", contents: render_lucide_icon_base_rb)
+          @seen_lucide_icons << :base
+        end
+
+        usages.sort_by { |u| u[:local_name] }.each do |usage|
+          next if @seen_lucide_icons.include?(usage[:local_name])
+
+          path = "#{AST::Inflector.underscore(usage[:local_name])}.rb"
+          files << File.new(
+            path: path,
+            contents: render_lucide_icon_class_rb(usage[:local_name], canonical: usage[:canonical_name])
+          )
+          @seen_lucide_icons << usage[:local_name]
+        end
+        files
+      end
+
+      # Lucide imports used as JSX tags, each carrying both the local
+      # binding (what the emitted file/class is named after) and the
+      # canonical export (used to look up the vendored SVG path data).
+      # The two diverge under aliased imports — `import { ChevronRight as
+      # CR }` should still resolve `ChevronRight`'s SVG while emitting a
+      # `cr.rb` defining `class CR < LucideIcon`. Names not in the
+      # vendored data still emit, but the class falls back to a TODO
+      # `inner_svg` instead of NameError-ing at render.
+      def referenced_lucide_icons(component)
+        lucide_by_local = component.module_imports
+                                   .select { |i| Icons.lucide_source?(i.source) }
+                                   .to_h { |i| [i.name, i.imported_name || i.name] }
+        return [] if lucide_by_local.empty?
+
+        invocations = Set.new
+        collect_component_invocations(component.body, invocations)
+        invocations.intersection(lucide_by_local.keys).map do |local_name|
+          { local_name: local_name, canonical_name: lucide_by_local.fetch(local_name) }
+        end
+      end
+
+      # Walk an IR subtree and collect every ComponentInvocation tag name we
+      # see. Recurses through any field that holds an IR node or array of
+      # nodes. Conservative — visits every container; cost is proportional
+      # to IR size.
+      def collect_component_invocations(node, acc)
+        return if node.nil?
+
+        acc << node.name if node.is_a?(IR::ComponentInvocation)
+        return unless node.respond_to?(:members)
+
+        node.members.each do |field|
+          value = node.public_send(field)
+          if value.is_a?(Array)
+            value.each { |child| collect_component_invocations(child, acc) }
+          elsif value.respond_to?(:members)
+            collect_component_invocations(value, acc)
+          end
+        end
+      end
+
+      def render_lucide_icon_base_rb
+        mod_open, mod_close, indent = lucide_module_wrap
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # Generated by jsx_rosetta. Don't edit by hand — re-translate the source
+          # to refresh. Shared SVG-wrapper base for Lucide icon shims; one subclass
+          # per icon (e.g. ChevronRight, Search) sits alongside this file.
+          #{mod_open}#{indent}class LucideIcon < Phlex::HTML
+          #{indent}  BASE_ATTRS = %{xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"}.freeze
+
+          #{indent}  def initialize(class_name: nil, **)
+          #{indent}    super()
+          #{indent}    @class_name = class_name
+          #{indent}  end
+
+          #{indent}  def view_template
+          #{indent}    cls = @class_name.to_s.empty? ? "" : %{ class="\#{@class_name}"}
+          #{indent}    raw safe("<svg \#{BASE_ATTRS}\#{cls}>\#{inner_svg}</svg>")
+          #{indent}  end
+
+          #{indent}  def inner_svg
+          #{indent}    raise NotImplementedError
+          #{indent}  end
+          #{indent}end
+          #{mod_close}
+        RUBY
+      end
+
+      # `name` is the local binding (the Ruby class name we emit), `canonical`
+      # is the original Lucide export — they diverge under aliased imports.
+      # SVG lookup keys on `canonical`; the class definition keys on `name`.
+      def render_lucide_icon_class_rb(name, canonical: name)
+        inner = Icons.lucide_for(canonical)
+        mod_open, mod_close, indent = lucide_module_wrap
+        body = if inner
+                 "#{indent}  def inner_svg = #{format_svg_string(inner)}"
+               else
+                 "#{indent}  # TODO: #{canonical.inspect} isn't in jsx_rosetta's vendored lucide.json.\n" \
+                   "#{indent}  # Fill in inner_svg with the SVG path data from lucide.dev, or refresh\n" \
+                   "#{indent}  # `lib/jsx_rosetta/icons/lucide.json`.\n" \
+                   "#{indent}  def inner_svg = \"\""
+               end
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # Generated by jsx_rosetta from a "lucide-react" import. Refresh with
+          # a re-translate; don't edit by hand.
+          #{mod_open}#{indent}class #{name} < LucideIcon
+          #{body}
+          #{indent}end
+          #{mod_close}
+        RUBY
+      end
+
+      # Match the namespace wrapping we use for the main component class.
+      # Returns ["module Foo\n", "end\n", "  "] when a namespace is set,
+      # or ["", "", ""] for the top-level case.
+      def lucide_module_wrap
+        return ["", "", ""] unless @namespace
+
+        ["module #{@namespace}\n", "end\n", "  "]
+      end
+
+      # Wrap an SVG inner-markup snippet in a Ruby string literal that
+      # preserves its embedded double quotes. Single-quoted when the markup
+      # contains no single quotes (most cases), otherwise %q delimited.
+      def format_svg_string(svg)
+        if svg.include?("'")
+          %(%q{#{svg}})
+        else
+          "'#{svg}'"
+        end
+      end
     end
   end
 end