jsx_rosetta 0.3.0 → 0.4.0

data/lib/jsx_rosetta/ir/lowering.rb

@@ -1,29 +1,30 @@
 # frozen_string_literal: true
 
 require_relative "types"
+require_relative "module_shape_classifier"
 
 module JsxRosetta
   module IR
     # Lowers a parsed AST::File into an IR::Component tree.
     #
-    # Phase 2 scope:
-    #   - Single function-declaration component per file.
-    #   - JSX elements with lowercase tags lower to IR::Element; others to
-    #     IR::ComponentInvocation.
-    #   - className attributes lower to IR::StyleBinding; everything else
-    #     to IR::Attribute (event handlers like onClick are passed through
-    #     as Attribute for now and will be re-lowered to EventBinding in
-    #     a later phase).
-    #   - JS expressions are preserved as opaque source text via
-    #     IR::Interpolation. No JS-to-Ruby translation.
-    #   - Pure-whitespace JSXText between elements is dropped (matches
-    #     JSX runtime behavior); other text is preserved verbatim.
+    # Responsibilities:
+    #   - Component discovery — find function/arrow declarations whose
+    #     name and body shape qualify as a function component.
+    #   - Module-shape classification — when no component is found,
+    #     produce a triage-friendly error message via SHAPE_MESSAGES.
+    #   - Function-body lowering — turn return-bearing block statements,
+    #     if-chains, switch/try statements, and bare expression returns
+    #     into IR values (Conditional, Interpolation, Text, etc.).
+    #   - JSX-node lowering — turn JSXElement / JSXFragment / JSXText /
+    #     JSXExpressionContainer trees into IR::Element / Fragment /
+    #     ComponentInvocation / Conditional / Loop / etc.
+    #   - Pattern recognition — `cn()` / `clsx()` className helpers,
+    #     `items.map(...)` loops, `cond ? <A/> : <B/>` polymorphic tags,
+    #     React-hook calls, and onX={...} handlers promotable to
+    #     Stimulus methods.
     #
-    # Phase 4a additions:
-    #   - {children} where `children` is a prop lowers to IR::Slot.
-    #   - {cond && X}, {cond ? X : null}, and {cond ? X : Y} lower to
-    #     IR::Conditional. Other LogicalExpression operators (||, ??) are
-    #     left as opaque interpolations.
+    # Anything outside these patterns is preserved verbatim as a TODO
+    # so the human reviewer sees the original JS at the right spot.
     class Lowering
       # A failure during AST → IR lowering. Carries optional line/column
       # information when the failure can be tied to an AST node.
@@ -66,9 +67,7 @@ module JsxRosetta
         useReducer useImperativeHandle useLayoutEffect useDebugValue
       ].freeze
 
-      EXPORT_TYPES = %w[ExportNamedDeclaration ExportDefaultDeclaration].freeze
       JSX_NODE_TYPES = %w[JSXElement JSXFragment JSXText JSXExpressionContainer].freeze
-      HOC_NAMES = %w[memo forwardRef lazy observer].freeze
 
       # Pre-lowering AST scan: maps a node type to a callable returning the
       # AST nodes that contribute return values. Used by body_returns_jsx?.
@@ -106,8 +105,10 @@ module JsxRosetta
         @prop_names = []
         @local_jsx = {}
         @local_bindings = []
+        @local_binding_names = []
         @local_arrows = {}
         @local_polymorphic_tags = {}
+        @local_destructures = {}
         @stimulus_methods = []
         @stimulus_seen_names = {}
         @react_hooks = []
@@ -118,148 +119,79 @@ module JsxRosetta
         raise no_component_error(file.program) if candidates.empty?
 
         name, function = candidates.first
-        lower_component(name, function)
+        module_bindings = capture_module_bindings(file.program, candidates)
+        attach_module_bindings(lower_component(name, function), module_bindings)
       end
 
       def lower_all_components(file)
         candidates = find_component_functions(file.program)
         raise no_component_error(file.program) if candidates.empty?
 
-        candidates.map { |name, function| lower_component(name, function) }
-      end
-
-      private
-
-      def lowering_error(message, node: nil)
-        LoweringError.new(message, node: node, source: @source)
-      end
-
-      def no_component_error(program)
-        shape = classify_module_shape(program)
-        message = SHAPE_MESSAGES[shape]
-        suffix = message ? " — #{message}" : ""
-        lowering_error("no component function found in module#{suffix}")
-      end
-
-      # Heuristic classifier that labels a module whose top-level shape isn't
-      # a function component. Used only for the error message — does not
-      # affect what does or doesn't translate. Order matters: more specific
-      # shapes are checked first.
-      def classify_module_shape(program)
-        ast_shape = classify_ast_shape(program)
-        return ast_shape if ast_shape
-
-        classify_by_export_names(top_level_export_names(program), program)
-      end
-
-      def classify_ast_shape(program)
-        return :class_component if program.body.any? { |stmt| class_component?(stmt) }
-        return :hoc_wrapped if program.body.any? { |stmt| hoc_wrapped_export?(stmt) }
-        return :columns_data if program.body.any? { |stmt| array_literal_export?(stmt) }
-
-        nil
-      end
-
-      def classify_by_export_names(names, program)
-        export_label = classify_by_export_pattern(names)
-        return export_label if export_label
-
-        classify_non_export_module(program)
-      end
-
-      def classify_by_export_pattern(names)
-        any_hooks = names.any? { |n| hook_name?(n) }
-        any_helpers = names.any? { |n| /\A[a-z]/.match?(n) && !hook_name?(n) }
-        return :mixed_exports if any_hooks && any_helpers
-        return :hooks_only if any_hooks
-        return :utils_only if any_helpers
-
-        nil
-      end
-
-      # No function-shaped exports. Distinguish:
-      #   - side-effect-only (top-level calls like `LicenseManager.set(...)`)
-      #   - types-only       (TS types/interfaces and constants)
-      #   - unknown          (nothing top-level to look at)
-      def classify_non_export_module(program)
-        return :side_effects_only if program.body.any? { |s| side_effect_statement?(s) }
-        return :types_only if top_level_has_anything?(program)
-
-        :unknown
-      end
-
-      def side_effect_statement?(stmt)
-        stmt.is_a?(AST::Node) && stmt.type == "ExpressionStatement"
+        module_bindings = capture_module_bindings(file.program, candidates)
+        candidates.map do |name, function|
+          attach_module_bindings(lower_component(name, function), module_bindings)
+        end
       end
 
-      def hook_name?(name)
-        name.start_with?("use") && name.length > 3 && name[3] == name[3].upcase
+      # Walk the program body for top-level `const`/`let` declarations that
+      # aren't component declarations. Capture each as a LocalBinding so
+      # backends can emit them as Ruby constants (or as a TODO comment for
+      # non-literal initializers) before the class definition. Without
+      # this, `const FOO = 400; function X() { return <p>{FOO}</p> }` would
+      # silently drop the FOO declaration and emit an unbacked `foo`
+      # reference inside the view template.
+      def capture_module_bindings(program, candidates)
+        component_names = candidates.to_set(&:first)
+        bindings = []
+        program.body.each do |stmt|
+          walk_module_binding(stmt, component_names, bindings)
+        end
+        bindings
       end
 
-      def class_component?(stmt)
-        decl = EXPORT_TYPES.include?(stmt.type) ? stmt[:declaration] : stmt
-        decl.is_a?(AST::Node) && decl.type == "ClassDeclaration"
+      def walk_module_binding(stmt, component_names, bindings)
+        case stmt.type
+        when "VariableDeclaration"
+          stmt[:declarations].each { |d| record_module_binding(stmt, d, component_names, bindings) }
+        when "ExportNamedDeclaration"
+          decl = stmt[:declaration]
+          walk_module_binding(decl, component_names, bindings) if decl.is_a?(AST::Node)
+        end
       end
 
-      # Recognize `export const X = React.memo(...)` (export wrapper) or a
-      # top-level `const X = lazy(() => ...)` followed by `export default X`
-      # — a VariableDeclaration whose init is a CallExpression to a known HOC.
-      def hoc_wrapped_export?(stmt)
-        decl = EXPORT_TYPES.include?(stmt.type) ? stmt[:declaration] : stmt
-        return false unless decl.is_a?(AST::Node) && decl.type == "VariableDeclaration"
+      def record_module_binding(stmt, declarator, component_names, bindings)
+        init = declarator[:init]
+        return unless init.is_a?(AST::Node)
 
-        decl[:declarations].any? do |d|
-          init = d[:init]
-          init.is_a?(AST::Node) && init.type == "CallExpression" && hoc_callee?(init[:callee])
-        end
-      end
+        # Component declarators (`const Foo = () => ...`) are handled by
+        # the component pipeline; skip them here so the source doesn't
+        # show up twice.
+        return if %w[ArrowFunctionExpression FunctionExpression].include?(init.type) &&
+                  component_names.include?(declarator[:id]&.[](:name))
 
-      def hoc_callee?(callee)
-        return false unless callee.is_a?(AST::Node)
+        name = declarator[:id]&.[](:name)
+        return unless name
 
-        case callee.type
-        when "Identifier" then HOC_NAMES.include?(callee[:name])
-        when "MemberExpression"
-          property = callee[:property]
-          property.is_a?(AST::Node) && property.type == "Identifier" && HOC_NAMES.include?(property[:name])
-        else false
-        end
+        bindings << LocalBinding.new(name: name, source: source_of(stmt).strip)
       end
 
-      def array_literal_export?(stmt)
-        return false unless EXPORT_TYPES.include?(stmt.type)
+      def attach_module_bindings(component, module_bindings)
+        return component if module_bindings.empty?
 
-        decl = stmt[:declaration]
-        return true if decl.is_a?(AST::Node) && decl.type == "ArrayExpression"
-        return false unless decl.is_a?(AST::Node) && decl.type == "VariableDeclaration"
-
-        decl[:declarations].any? { |d| d[:init].is_a?(AST::Node) && d[:init].type == "ArrayExpression" }
+        component.with(module_bindings: module_bindings)
       end
 
-      # Does the program have any top-level non-import statements? Used to
-      # distinguish "types-only / empty module" from "mixed exports."
-      def top_level_has_anything?(program)
-        program.body.any? do |stmt|
-          stmt.is_a?(AST::Node) && stmt.type != "ImportDeclaration"
-        end
-      end
+      private
 
-      def top_level_export_names(program)
-        program.body.flat_map { |stmt| extract_top_level_names(stmt) }.compact
+      def lowering_error(message, node: nil)
+        LoweringError.new(message, node: node, source: @source)
       end
 
-      def extract_top_level_names(stmt)
-        case stmt.type
-        when "FunctionDeclaration"
-          [stmt[:id]&.[](:name)]
-        when "VariableDeclaration"
-          stmt[:declarations].map { |d| d[:id].is_a?(AST::Node) && d[:id].type == "Identifier" ? d[:id][:name] : nil }
-        when "ExportNamedDeclaration", "ExportDefaultDeclaration"
-          decl = stmt[:declaration]
-          decl.is_a?(AST::Node) ? extract_top_level_names(decl) : []
-        else
-          []
-        end
+      def no_component_error(program)
+        shape = ModuleShapeClassifier.classify(program)
+        message = SHAPE_MESSAGES[shape]
+        suffix = message ? " — #{message}" : ""
+        lowering_error("no component function found in module#{suffix}")
       end
 
       def find_component_functions(program)
@@ -287,6 +219,10 @@ module JsxRosetta
         first == first.upcase && first != first.downcase
       end
 
+      def hook_name?(name)
+        name.start_with?("use") && name.length > 3 && name[3] == name[3].upcase
+      end
+
       # Pre-lowering AST scan: does any return path in this body produce a
       # JSX value? Used only as a heuristic for component_function?, so a
       # false positive is a translation attempt that may TODO out, while
@@ -347,8 +283,10 @@ module JsxRosetta
         props, rest_prop_name = lower_params(function[:params])
         @prop_names = props.map(&:name)
         @local_bindings = []
+        @local_binding_names = []
         @local_arrows = {}
         @local_polymorphic_tags = {}
+        @local_destructures = {}
         @stimulus_methods = []
         @stimulus_seen_names = {}
         @react_hooks = []
@@ -361,6 +299,8 @@ module JsxRosetta
           body: body,
           rest_prop_name: rest_prop_name,
           local_bindings: @local_bindings,
+          local_binding_names: @local_binding_names.uniq,
+          module_bindings: [],
           stimulus_methods: @stimulus_methods,
           react_hooks: @react_hooks
         )
@@ -401,7 +341,12 @@ module JsxRosetta
         key = property[:key]
         prop_name = key.type == "StringLiteral" ? key[:value] : key[:name]
         value = property[:value]
-        default = (Interpolation.new(expression: source_of(value[:right])) if value.type == "AssignmentPattern")
+        # Route prop default expressions through the recursive value
+        # lowering so object/array literals translate cleanly, instead of
+        # producing an opaque Interpolation that the backend would emit as
+        # `nil # TODO: ...`. The trailing `#` comment inside a method
+        # parameter list swallows the closing `)` and breaks Ruby syntax.
+        default = (lower_value_expression(value[:right]) if value.type == "AssignmentPattern")
         Prop.new(name: prop_name, default: default)
       end
 
@@ -454,7 +399,7 @@ module JsxRosetta
       # around the base value as outer Conditionals. Returns nil when no shape
       # matches; caller raises.
       def lower_block_returns(statements)
-        return_idx = statements.index { |s| s.is_a?(AST::Node) && s.type == "ReturnStatement" }
+        return_idx = statements.index { |s| AST::Node.matches?(s, "ReturnStatement") }
 
         if return_idx
           return_arg = statements[return_idx][:argument]
@@ -492,20 +437,22 @@ module JsxRosetta
       # behavior of dropping unrepresentable preceding statements rather
       # than failing the whole component.
       def wrap_return_guards(preceding, base_value)
-        preceding.reverse.each do |stmt|
-          next unless stmt.is_a?(AST::Node) && stmt.type == "IfStatement"
-          next if stmt[:alternate]
+        preceding.reverse.reduce(base_value) do |acc, stmt|
+          next acc unless guard_if_statement?(stmt)
 
           branch_value = lower_return_branch(stmt[:consequent])
-          next unless branch_value
+          next acc unless branch_value
 
-          base_value = Conditional.new(
+          Conditional.new(
             test: Interpolation.new(expression: source_of(stmt[:test])),
             consequent: branch_value,
-            alternate: base_value
+            alternate: acc
           )
         end
-        base_value
+      end
+
+      def guard_if_statement?(stmt)
+        AST::Node.matches?(stmt, "IfStatement") && stmt[:alternate].nil?
       end
 
       def lower_if_return_chain(if_stmt)
@@ -547,7 +494,7 @@ module JsxRosetta
 
       def collect_nested_local_bindings(stmts)
         stmts.each do |stmt|
-          next unless stmt.is_a?(AST::Node) && stmt.type == "VariableDeclaration"
+          next unless AST::Node.matches?(stmt, "VariableDeclaration")
 
           seen = {}
           stmt[:declarations].each { |declarator| classify_local_binding(stmt, declarator, seen) }
@@ -625,10 +572,10 @@ module JsxRosetta
       #   case A: if (X) return Y; return Z;  (guard prefix + return)
       # Trailing `break` statements are ignored.
       def lower_switch_case_consequent(stmts)
-        filtered = stmts.reject { |s| s.is_a?(AST::Node) && s.type == "BreakStatement" }
+        filtered = stmts.reject { |s| AST::Node.matches?(s, "BreakStatement") }
         return nil if filtered.empty?
 
-        if filtered.size == 1 && filtered.first.is_a?(AST::Node) && filtered.first.type == "BlockStatement"
+        if filtered.size == 1 && AST::Node.matches?(filtered.first, "BlockStatement")
           return lower_switch_case_consequent(filtered.first[:body])
         end
 
@@ -650,6 +597,7 @@ module JsxRosetta
         @local_jsx = {}
         @local_arrows = {}
         @local_polymorphic_tags = {}
+        @local_destructures = {}
         seen_other_stmts = {}
 
         statements.each do |stmt|
@@ -666,12 +614,27 @@ module JsxRosetta
         init = declarator[:init]
         return unless init.is_a?(AST::Node)
 
-        if hook_call?(init)
-          @react_hooks << ReactHookCall.new(hook: init[:callee][:name], source: source_of(stmt).strip)
+        is_hook = hook_call?(init)
+        @react_hooks << ReactHookCall.new(hook: init[:callee][:name], source: source_of(stmt).strip) if is_hook
+
+        id_node = declarator[:id]
+        if destructure_pattern?(id_node)
+          # Capture destructured names so the ExpressionTranslator recognizes
+          # them as known-local bindings and emits a `nil` placeholder
+          # instead of a bare unresolved reference (which NameErrors at
+          # render time). Hook destructures (`const [open, setOpen] = useState(0)`)
+          # contribute names but not a separate LocalBinding TODO — the
+          # hook's source already shows the binding to the reviewer.
+          # Also track member-expression destructures (Gap J) so
+          # `const { Content } = Layout` lets `<Content/>` resolve to
+          # `Layout::Content`.
+          record_destructured_names(stmt, declarator, init: init, seen: seen, is_hook: is_hook)
           return
         end
 
-        name = declarator[:id]&.[](:name)
+        return if is_hook
+
+        name = id_node&.[](:name)
         return unless name
 
         case init.type
@@ -687,19 +650,83 @@ module JsxRosetta
         end
       end
 
+      def destructure_pattern?(node)
+        AST::Node.matches?(node, "ArrayPattern", "ObjectPattern")
+      end
+
+      def record_destructured_names(stmt, declarator, init:, seen:, is_hook:)
+        pattern = declarator[:id]
+        names = destructured_names_of(pattern)
+        return if names.empty?
+
+        # Member-expression-style destructuring (Gap J): `const { Content } = Layout`
+        # binds `Content` to `Layout.Content`. Record those so JSX use sites
+        # resolve to the right component.
+        track_member_destructures(pattern, init) if AST::Node.matches?(init, "Identifier")
+
+        @local_binding_names.concat(names)
+        return if is_hook
+
+        seen[stmt.start_pos] ||= source_of(stmt).strip
+        names.each { |name| @local_bindings << LocalBinding.new(name: name, source: seen[stmt.start_pos]) }
+      end
+
+      # Return the flat list of Identifier names bound by a destructuring
+      # pattern. Nested patterns recurse. RestElement / aliased properties
+      # are included; defaults (AssignmentPattern) are followed to their
+      # left-hand identifier.
+      def destructured_names_of(pattern)
+        return [] unless pattern.is_a?(AST::Node)
+
+        case pattern.type
+        when "Identifier" then [pattern[:name]]
+        when "ArrayPattern"
+          pattern[:elements].flat_map { |element| element ? destructured_names_of(element) : [] }
+        when "ObjectPattern"
+          pattern[:properties].flat_map { |prop| destructured_names_from_property(prop) }
+        when "RestElement"
+          destructured_names_of(pattern[:argument])
+        when "AssignmentPattern"
+          destructured_names_of(pattern[:left])
+        else
+          []
+        end
+      end
+
+      def destructured_names_from_property(prop)
+        case prop.type
+        when "ObjectProperty" then destructured_names_of(prop[:value])
+        when "RestElement" then destructured_names_of(prop[:argument])
+        else []
+        end
+      end
+
+      def track_member_destructures(pattern, source_identifier)
+        return unless AST::Node.matches?(pattern, "ObjectPattern")
+
+        source_name = source_identifier[:name]
+        pattern[:properties].each do |prop|
+          next unless prop.type == "ObjectProperty"
+
+          value = prop[:value]
+          next unless AST::Node.matches?(value, "Identifier")
+
+          @local_destructures[value[:name]] = source_name
+        end
+      end
+
       def detect_bare_hook_call(stmt)
-        expr = stmt[:expression]
-        return unless expr.is_a?(AST::Node) && expr.type == "CallExpression"
-        return unless hook_call?(expr)
+        expr = stmt.child(:expression)
+        return unless expr&.of_type?("CallExpression") && hook_call?(expr)
 
         @react_hooks << ReactHookCall.new(hook: expr[:callee][:name], source: source_of(stmt).strip)
       end
 
       def hook_call?(call_expression)
-        return false unless call_expression.type == "CallExpression"
+        return false unless call_expression.of_type?("CallExpression")
 
-        callee = call_expression[:callee]
-        callee.is_a?(AST::Node) && callee.type == "Identifier" && REACT_HOOKS.include?(callee[:name])
+        callee = call_expression.child(:callee)
+        callee&.of_type?("Identifier") && REACT_HOOKS.include?(callee[:name])
       end
 
       # Recognize the asChild-style polymorphic tag pattern:
@@ -727,6 +754,7 @@ module JsxRosetta
       def record_local_other_binding(stmt, name, seen)
         seen[stmt.start_pos] ||= source_of(stmt).strip
         @local_bindings << LocalBinding.new(name: name, source: seen[stmt.start_pos])
+        @local_binding_names << name
       end
 
       def lower_jsx(node)
@@ -742,7 +770,7 @@ module JsxRosetta
 
       def lower_jsx_element(element)
         tag = element.tag_name
-        attributes = element.opening_element.attributes.filter_map { |attr| lower_attribute(attr) }
+        attributes = element.opening_element.attributes.filter_map { |attr| lower_attribute(attr, tag: tag) }
         # `key` is a React-only reconciliation hint; never emit it to the DOM
         # or to ViewComponent invocations.
         attributes = attributes.reject { |attr| attr.is_a?(Attribute) && attr.name == "key" }
@@ -750,6 +778,10 @@ module JsxRosetta
 
         if (poly = @local_polymorphic_tags[tag])
           lower_polymorphic_tag_use(poly, attributes, children)
+        elsif (parent = @local_destructures[tag])
+          # Gap J: `const { Content } = Layout; <Content/>` should resolve
+          # to `Layout::Content`, not a bare `ContentComponent`.
+          ComponentInvocation.new(name: "#{parent}.#{tag}", props: attributes, children: children)
         elsif html_element?(tag)
           Element.new(tag: tag, attributes: attributes, children: children)
         else
@@ -834,11 +866,30 @@ module JsxRosetta
         when "ConditionalExpression" then lower_ternary_expression(expression)
         when "Identifier" then lower_identifier_expression(expression)
         when "CallExpression" then lower_call_expression(expression)
+        when "ArrowFunctionExpression", "FunctionExpression" then lower_render_prop(expression)
         else
           Interpolation.new(expression: source_of(expression))
         end
       end
 
+      # Recognize the render-prop / function-as-children pattern:
+      #   <Form.List>{(fields, helpers) => <div>{fields}</div>}</Form.List>
+      # Returns nil (caller falls back to verbatim interpolation) when the
+      # arrow has zero or too many params, or when the body doesn't lower
+      # cleanly to a JSX child.
+      def lower_render_prop(arrow)
+        params = arrow[:params]
+        return Interpolation.new(expression: source_of(arrow)) if params.size > 4
+        unless params.all? { |p| AST::Node.matches?(p, "Identifier") }
+          return Interpolation.new(expression: source_of(arrow))
+        end
+
+        body = lower_arrow_body(arrow[:body])
+        return Interpolation.new(expression: source_of(arrow)) unless body
+
+        RenderProp.new(params: params.map { |p| p[:name] }, body: body)
+      end
+
       def lower_jsx_comment(empty_expression)
         comments = empty_expression.raw["innerComments"]
         return nil if comments.nil? || comments.empty?
@@ -851,32 +902,50 @@ module JsxRosetta
         loop_node || Interpolation.new(expression: source_of(expression))
       end
 
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def try_lower_map_loop(call_expression)
-        callee = call_expression[:callee]
-        return nil unless callee.is_a?(AST::Node) && callee.type == "MemberExpression"
-        return nil unless callee[:property].is_a?(AST::Node) && callee[:property][:name] == "map"
+        callee = call_expression.child(:callee)
+        return nil unless callee&.of_type?("MemberExpression")
 
-        args = call_expression[:arguments]
-        return nil if args.size != 1
-        return nil unless args.first.type == "ArrowFunctionExpression"
+        property = callee.child(:property)
+        return nil unless property && property[:name] == "map"
 
-        arrow = args.first
-        params = arrow[:params]
-        return nil if params.empty? || params.size > 2
-        return nil unless params.all? { |p| p.is_a?(AST::Node) && p.type == "Identifier" }
+        arrow = map_loop_arrow(call_expression[:arguments])
+        return nil unless arrow
 
+        params = arrow[:params]
         body = lower_arrow_body(arrow[:body])
         return nil unless body
 
         Loop.new(
-          iterable: Interpolation.new(expression: source_of(callee[:object])),
+          iterable: lower_loop_iterable(callee[:object]),
           item_binding: params[0][:name],
           index_binding: params[1] && params[1][:name],
           body: body
         )
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      # Recognize ArrayExpression/ObjectExpression iterables so a literal-
+      # rooted `.map(...)` doesn't bail at translation time. Falls back to
+      # the verbatim Interpolation for everything else.
+      def lower_loop_iterable(object)
+        case object.type
+        when "ArrayExpression" then lower_array_literal(object)
+        else Interpolation.new(expression: source_of(object))
+        end
+      end
+
+      def map_loop_arrow(args)
+        return nil if args.size != 1
+
+        arrow = args.first
+        return nil unless AST::Node.matches?(arrow, "ArrowFunctionExpression")
+
+        params = arrow[:params]
+        return nil if params.empty? || params.size > 2
+        return nil unless params.all? { |p| AST::Node.matches?(p, "Identifier") }
+
+        arrow
+      end
 
       def lower_arrow_body(body)
         case body.type
@@ -939,21 +1008,27 @@ module JsxRosetta
         end
       end
 
-      def lower_attribute(attr)
+      def lower_attribute(attr, tag:)
         case attr
         when AST::JSXAttribute
-          lower_jsx_attribute(attr)
+          lower_jsx_attribute(attr, tag: tag)
         when AST::JSXSpreadAttribute
           SpreadAttribute.new(expression: source_of(attr.argument))
         end
       end
 
-      def lower_jsx_attribute(attr)
+      # When the JSX tag is a component (PascalCase or member-expression),
+      # `on*` props are NOT DOM events — they're callback props the receiving
+      # Ruby component decides how to handle. Stimulus action descriptors
+      # only fire on real DOM events, so promoting them would generate
+      # never-firing `data-action="change->foo#h"` markup. Pass through as
+      # a regular component-prop kwarg instead.
+      def lower_jsx_attribute(attr, tag:)
         name = attr.attribute_name
 
         return lower_class_name(attr.value) if name == "className"
         return lower_style_attribute_or_fallback(attr.value) if name == "style"
-        if event_attribute?(name) && attr.value.is_a?(AST::JSXExpressionContainer)
+        if event_attribute?(name) && attr.value.is_a?(AST::JSXExpressionContainer) && html_element?(tag)
           return lower_event_attribute(name, attr.value)
         end
 
@@ -968,7 +1043,7 @@ module JsxRosetta
         return nil unless value.is_a?(AST::JSXExpressionContainer)
 
         expression = value.expression
-        return nil unless expression.is_a?(AST::Node) && expression.type == "ObjectExpression"
+        return nil unless AST::Node.matches?(expression, "ObjectExpression")
 
         declarations = expression[:properties].map { |prop| lower_style_property(prop) }
         return nil if declarations.any?(&:nil?)
@@ -1014,10 +1089,10 @@ module JsxRosetta
       end
 
       def try_lower_class_helper(expression)
-        return nil unless expression.is_a?(AST::Node) && expression.type == "CallExpression"
+        return nil unless AST::Node.matches?(expression, "CallExpression")
 
-        callee = expression[:callee]
-        return nil unless callee.is_a?(AST::Node) && callee.type == "Identifier"
+        callee = expression.child(:callee)
+        return nil unless callee&.of_type?("Identifier")
         return nil unless %w[cn clsx classnames].include?(callee[:name])
 
         segments = expression[:arguments].flat_map { |arg| lower_class_helper_arg(arg) }
@@ -1069,26 +1144,49 @@ module JsxRosetta
         )
       end
 
+      # Promote a JSX event-handler attribute (`onClick={...}`, `onChange={...}`)
+      # to a Stimulus method binding. Three input shapes are recognized:
+      #   - inline arrow / function expression (`onClick={() => doX()}`)
+      #     → method body is the arrow's body source.
+      #   - identifier referring to a local arrow binding
+      #     (`const h = () => doX(); onClick={h}`) → method body is the
+      #     bound arrow's body. The local arrow is consumed.
+      #   - identifier referring to a prop or external (`onClick={onChange}`)
+      #     → synthesizes a method whose body documents the original
+      #     reference. Without this branch, prop-handler bindings used to
+      #     fall through to an EventBinding that rendered as a broken
+      #     `data-action` (a Ruby reference, not a Stimulus action descriptor).
       def try_promote_to_stimulus(attr_name, event, expression)
-        arrow_node, name_hint = stimulus_arrow_for(expression)
-        return nil unless arrow_node
+        case expression.type
+        when "ArrowFunctionExpression", "FunctionExpression"
+          promote_arrow_to_stimulus(attr_name, event, expression, name_hint: nil)
+        when "Identifier"
+          promote_identifier_event(attr_name, event, expression[:name])
+        end
+      end
 
-        method_name = stimulus_method_name(name_hint || default_stimulus_method_name(attr_name))
+      def promote_arrow_to_stimulus(attr_name, event, arrow_node, name_hint:)
+        base = name_hint || default_stimulus_method_name(attr_name)
+        method_name = stimulus_method_name(base)
         body_source = source_of(arrow_node[:body])
-        @stimulus_methods << StimulusMethod.new(name: method_name, body_source: body_source)
+        @stimulus_methods << StimulusMethod.new(
+          name: method_name, body_source: body_source, original_name: base
+        )
         @local_arrows.delete(name_hint) if name_hint
-
         StimulusBinding.new(event: event, method_name: method_name)
       end
 
-      def stimulus_arrow_for(expression)
-        case expression.type
-        when "ArrowFunctionExpression", "FunctionExpression"
-          [expression, nil]
-        when "Identifier"
-          arrow = @local_arrows[expression[:name]]
-          arrow ? [arrow, expression[:name]] : nil
+      def promote_identifier_event(attr_name, event, identifier_name)
+        if (arrow = @local_arrows[identifier_name])
+          return promote_arrow_to_stimulus(attr_name, event, arrow, name_hint: identifier_name)
         end
+
+        method_name = stimulus_method_name(identifier_name)
+        body_source = "// originally bound to: #{identifier_name}"
+        @stimulus_methods << StimulusMethod.new(
+          name: method_name, body_source: body_source, original_name: identifier_name
+        )
+        StimulusBinding.new(event: event, method_name: method_name)
       end
 
       def default_stimulus_method_name(attr_name)
@@ -1108,12 +1206,86 @@ module JsxRosetta
         when nil
           true
         when AST::JSXExpressionContainer
-          Interpolation.new(expression: source_of(value.expression))
+          lower_value_expression(value.expression)
         else
           value.raw["value"]
         end
       end
 
+      # Recursively lower an arbitrary JS expression into structured IR
+      # when possible: ObjectExpression → ObjectLiteral, ArrayExpression
+      # → ArrayLiteral, ArrowFunctionExpression / FunctionExpression →
+      # Lambda. Everything else falls back to the verbatim Interpolation
+      # so simpler ExpressionTranslator paths still get a crack at it.
+      def lower_value_expression(expression)
+        case expression.type
+        when "ObjectExpression" then lower_object_literal(expression)
+        when "ArrayExpression" then lower_array_literal(expression)
+        when "ArrowFunctionExpression", "FunctionExpression" then lower_value_lambda(expression)
+        else
+          Interpolation.new(expression: source_of(expression))
+        end
+      end
+
+      def lower_object_literal(object_expression)
+        properties = []
+        object_expression[:properties].each do |prop|
+          # Spreads inside object literals, computed keys, getters/setters,
+          # methods — fall back to a verbatim Interpolation since we can't
+          # represent them as a simple key-value pair.
+          return Interpolation.new(expression: source_of(object_expression)) unless prop.type == "ObjectProperty"
+          return Interpolation.new(expression: source_of(object_expression)) if prop.raw["computed"]
+
+          key_name = object_property_key_name(prop[:key])
+          return Interpolation.new(expression: source_of(object_expression)) if key_name.nil?
+
+          properties << [key_name, lower_value_expression(prop[:value])]
+        end
+        ObjectLiteral.new(properties: properties)
+      end
+
+      def object_property_key_name(key_node)
+        case key_node.type
+        when "Identifier" then key_node[:name]
+        when "StringLiteral" then key_node[:value]
+        when "NumericLiteral" then key_node[:value].to_s
+        end
+      end
+
+      def lower_array_literal(array_expression)
+        elements = array_expression[:elements].map do |el|
+          next nil if el.nil? # `[1, , 3]` holes — Ruby has no equivalent
+
+          lower_value_expression(el)
+        end
+        ArrayLiteral.new(elements: elements)
+      end
+
+      def lower_value_lambda(arrow)
+        params = arrow[:params]
+        return Interpolation.new(expression: source_of(arrow)) if params.size > 4
+        unless params.all? { |p| AST::Node.matches?(p, "Identifier") }
+          return Interpolation.new(expression: source_of(arrow))
+        end
+
+        body = lower_lambda_body(arrow[:body])
+        return Interpolation.new(expression: source_of(arrow)) unless body
+
+        Lambda.new(params: params.map { |p| p[:name] }, body: body)
+      end
+
+      def lower_lambda_body(body)
+        return lower_jsx(body) if %w[JSXElement JSXFragment].include?(body.type)
+
+        return unless body.type == "BlockStatement"
+
+        return_stmt = body[:body].find { |s| s.type == "ReturnStatement" }
+        return nil unless return_stmt && return_stmt[:argument]
+
+        arg = return_stmt[:argument]
+        %w[JSXElement JSXFragment].include?(arg.type) ? lower_jsx(arg) : nil
+      end
+
       def style_binding_expression(value)
         case value
         when nil then "true"