jsx_rosetta 0.3.0 → 0.4.0

data/lib/jsx_rosetta/backend/rails_view.rb

@@ -18,7 +18,9 @@ module JsxRosetta
       def emit(component)
         prop_names = component.props.map(&:name)
         prop_names << component.rest_prop_name if component.rest_prop_name
-        translator = ExpressionTranslator.new(prop_names: prop_names)
+        translator = ExpressionTranslator.new(
+          prop_names: prop_names, local_binding_names: component.local_binding_names
+        )
 
         @stimulus_identifier = component.stimulus_methods.any? ? stimulus_identifier(component) : nil
 

data/lib/jsx_rosetta/backend/view_component/expression_translator.rb

@@ -18,6 +18,10 @@ module JsxRosetta
       #     to the bare snake_case identifier.
       #   * Names in `prop_names` translate to a `@snake_case` instance
       #     variable.
+      #   * Names in `local_binding_names` (consts/destructures captured at
+      #     lowering time but not modeled in IR) translate to a `nil`
+      #     placeholder with an inline `# TODO: local 'name'` marker — the
+      #     file still loads, but the reviewer sees what to fill in.
       #   * Anything else translates to the bare snake_case identifier and
       #     is recorded as unresolved.
       #
@@ -35,8 +39,9 @@ module JsxRosetta
 
         Result = Data.define(:ruby, :unresolved_identifiers)
 
-        def initialize(prop_names:)
+        def initialize(prop_names:, local_binding_names: [])
           @prop_names = prop_names.to_set
+          @local_binding_names = local_binding_names.to_set
           @local_stack = []
         end
 
@@ -77,12 +82,27 @@ module JsxRosetta
           @local_stack.any? { |scope| scope.include?(name) }
         end
 
-        def translate_identifier(name, unresolved)
+        def translate_identifier(name, unresolved, member_chain_root: false)
           snake = AST::Inflector.underscore(name)
           if in_local_scope?(name)
             snake
           elsif @prop_names.include?(name)
             "@#{snake}"
+          elsif @local_binding_names.include?(name)
+            # We know this binding exists locally (destructure, hook tuple)
+            # but can't model its value. As a leaf identifier, return `nil`
+            # so the file loads (a bare snake_case ref would NameError).
+            # As a member-chain root, `nil.member` would NoMethodError at
+            # render time — worse. Fall back to the snake_case bare ref
+            # and let it surface as a NameError (caller adds an unresolved
+            # marker), which is at least debuggable. The TODO marker for
+            # the binding source already lives in the comment block.
+            if member_chain_root
+              unresolved << name
+              snake
+            else
+              "nil"
+            end
           else
             unresolved << name
             snake
@@ -90,7 +110,7 @@ module JsxRosetta
         end
 
         def translate_member_chain(root, rest, unresolved)
-          translated_root = translate_identifier(root, unresolved)
+          translated_root = translate_identifier(root, unresolved, member_chain_root: true)
           # Underscore each chain segment so JS camelCase identifiers map to
           # Ruby snake_case (`post.coverImage` → `post.cover_image`).
           ruby_rest = rest.gsub(/\.([a-zA-Z_$][a-zA-Z_$0-9]*)/) do
@@ -103,16 +123,38 @@ module JsxRosetta
           return nil if content.include?("\\`")
           return nil if content.scan("${").size != content.scan(TEMPLATE_INTERPOLATION).size
 
-          ruby_content = content.gsub(TEMPLATE_INTERPOLATION) do |_match|
-            captured = ::Regexp.last_match(1)
-            translated = if (m = MEMBER_CHAIN.match(captured))
-                           translate_member_chain(m[:root], m[:rest], unresolved)
-                         else
-                           translate_identifier(captured, unresolved)
-                         end
-            "\#{#{translated}}"
+          parts = []
+          last_pos = 0
+          content.to_enum(:scan, TEMPLATE_INTERPOLATION).each do
+            match = ::Regexp.last_match
+            literal = content[last_pos...match.begin(0)]
+            parts << escape_ruby_string_literal(literal) unless literal.empty?
+            parts << "\#{#{translate_template_interpolation(match[1], unresolved)}}"
+            last_pos = match.end(0)
           end
-          %("#{ruby_content}")
+          trailing = content[last_pos..]
+          parts << escape_ruby_string_literal(trailing) unless trailing.empty?
+          %("#{parts.join}")
+        end
+
+        # Split into literal vs. interpolation segments so `"` and `\` in
+        # the literal parts can be escaped without touching the
+        # interpolation expressions (which are already valid Ruby).
+        def translate_template_interpolation(captured, unresolved)
+          if (m = MEMBER_CHAIN.match(captured))
+            translate_member_chain(m[:root], m[:rest], unresolved)
+          else
+            translate_identifier(captured, unresolved)
+          end
+        end
+
+        # Escape backslashes and double quotes so the literal portions of a
+        # translated template literal don't accidentally terminate the
+        # surrounding Ruby string. Newlines stay literal — Ruby double-quoted
+        # strings allow them, and template literals are typically used for
+        # short interpolated phrases anyway.
+        def escape_ruby_string_literal(text)
+          text.gsub("\\", "\\\\").gsub('"', '\\"')
         end
       end
     end

data/lib/jsx_rosetta/backend/view_component.rb

@@ -28,6 +28,12 @@ module JsxRosetta
       DEFAULT_SLOT_NAME = "children"
       VOID_ELEMENTS = %w[area base br col embed hr img input link meta param source track wbr].freeze
 
+      # Structured intermediate for tag_builder_data_action — avoids the
+      # fragile "parse what you just rendered" pattern. :literal is a raw
+      # action token like `"click->foo#bar"`; :ruby is a Ruby expression
+      # whose value is the action string (e.g. `event.handler.expression`).
+      EventDescriptor = Data.define(:kind, :body)
+
       # JSX component names that have a direct Rails view-helper analog.
       # Override per-instance via `ViewComponent.new(helpers: {...})`, or
       # disable by passing `helpers: false`.
@@ -53,7 +59,9 @@ module JsxRosetta
       def emit(component)
         prop_names = component.props.map(&:name)
         prop_names << component.rest_prop_name if component.rest_prop_name
-        translator = ExpressionTranslator.new(prop_names: prop_names)
+        translator = ExpressionTranslator.new(
+          prop_names: prop_names, local_binding_names: component.local_binding_names
+        )
 
         base_name = "#{AST::Inflector.underscore(component.name)}_component"
         @stimulus_identifier = component.stimulus_methods.any? ? stimulus_identifier(component) : nil
@@ -101,7 +109,12 @@ module JsxRosetta
       def stimulus_method_lines(method)
         body_lines = method.body_source.strip.split("\n")
         commented = body_lines.map { |line| "  //   #{line}" }
-        ["  // TODO: translate from the original JSX handler:"] + commented + [
+        header = ["  // TODO: translate from the original JSX handler:"]
+        if method.name != method.original_name
+          header.unshift("  // NOTE: method renamed from #{method.original_name.inspect} " \
+                         "to avoid collision with an earlier handler")
+        end
+        header + commented + [
           "  #{method.name}(event) {",
           "    // ...",
           "  }"
@@ -118,16 +131,41 @@ module JsxRosetta
         props = initializable_props(component)
         rest_name = component.rest_prop_name
 
-        if props.empty? && rest_name.nil?
-          <<~RUBY
-            # frozen_string_literal: true
+        body = if props.empty? && rest_name.nil?
+                 <<~RUBY
+                   # frozen_string_literal: true
 
-            class #{component.name}Component < ::ViewComponent::Base
-            end
-          RUBY
-        else
-          render_ruby_class_with_props(component, props, rest_name, translator)
-        end
+                   class #{component.name}Component < ::ViewComponent::Base
+                   end
+                 RUBY
+               else
+                 render_ruby_class_with_props(component, props, rest_name, translator)
+               end
+
+        prefix = render_module_bindings_prefix(component)
+        prefix.empty? ? body : insert_module_bindings_prefix(body, prefix)
+      end
+
+      def render_module_bindings_prefix(component)
+        return "" if component.module_bindings.empty?
+
+        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)) }
+        "#{lines.join("\n")}\n"
+      end
+
+      # The class body already starts with the magic comment — splice the
+      # module-bindings prefix in between so it lands above the class.
+      def insert_module_bindings_prefix(body, prefix)
+        magic = "# frozen_string_literal: true\n\n"
+        return "#{prefix}#{body}" unless body.start_with?(magic)
+
+        "#{magic}#{prefix}#{body[magic.length..]}"
+      end
+
+      def comment_lines(source)
+        source.split("\n").map { |line| "#   #{line}" }
       end
 
       def render_ruby_class_with_props(component, props, rest_name, translator)
@@ -160,8 +198,41 @@ module JsxRosetta
       def ruby_default_for(prop, translator)
         return "nil" if prop.default.nil?
 
-        translated = translator.translate(prop.default.expression)
-        translated ? translated.ruby : "nil # TODO: translate #{prop.default.expression.inspect}"
+        case prop.default
+        when IR::Interpolation
+          translated = translator.translate(prop.default.expression)
+          translated ? translated.ruby : "nil"
+        when IR::ObjectLiteral then render_object_literal_default(prop.default, translator)
+        when IR::ArrayLiteral then render_array_literal_default(prop.default, translator)
+        else "nil"
+        end
+      end
+
+      def render_object_literal_default(object_literal, translator)
+        pairs = object_literal.properties.map do |(key, value)|
+          snake = AST::Inflector.underscore(key)
+          key_str = snake.match?(/\A[a-z_][a-z0-9_]*\z/i) ? "#{snake}:" : "#{key.inspect} =>"
+          "#{key_str} #{render_default_inline_value(value, translator)}"
+        end
+        "{ #{pairs.join(", ")} }"
+      end
+
+      def render_array_literal_default(array_literal, translator)
+        parts = array_literal.elements.map { |el| el.nil? ? "nil" : render_default_inline_value(el, translator) }
+        "[#{parts.join(", ")}]"
+      end
+
+      def render_default_inline_value(value, translator)
+        case value
+        when IR::ObjectLiteral then render_object_literal_default(value, translator)
+        when IR::ArrayLiteral then render_array_literal_default(value, translator)
+        when IR::Interpolation
+          translated = translator.translate(value.expression)
+          translated ? translated.ruby : "nil"
+        when String then value.inspect
+        when true then "true"
+        else "nil"
+        end
       end
 
       def render_erb_template(component, translator)
@@ -211,6 +282,7 @@ module JsxRosetta
         when IR::Fragment then render_fragment(node, translator, indent: indent)
         when IR::Conditional then render_conditional(node, translator, indent: indent)
         when IR::Loop then render_loop(node, translator, indent: indent)
+        when IR::RenderProp then render_orphan_render_prop(node, translator, indent: indent)
         when IR::Slot then render_slot(node, indent: indent)
         when IR::Text then "#{spaces(indent)}#{node.value}"
         when IR::Interpolation then "#{spaces(indent)}#{interpolation_to_erb(node, translator)}"
@@ -218,8 +290,14 @@ module JsxRosetta
         end
       end
 
+      def render_orphan_render_prop(render_prop, translator, indent:)
+        translator.with_locals(render_prop.params) do
+          render_ir_node(render_prop.body, translator, indent: indent)
+        end
+      end
+
       def render_loop(loop_node, translator, indent:)
-        iterable_ruby = render_test_expression(loop_node.iterable, translator)
+        iterable_ruby = render_loop_iterable(loop_node.iterable, translator)
         js_bindings = [loop_node.item_binding, loop_node.index_binding].compact
         ruby_bindings = js_bindings.map { |name| AST::Inflector.underscore(name) }
         binding_str = "|#{ruby_bindings.join(", ")}|"
@@ -235,6 +313,14 @@ module JsxRosetta
         ].join("\n")
       end
 
+      def render_loop_iterable(iterable, translator)
+        case iterable
+        when IR::ArrayLiteral then render_array_literal_default(iterable, translator)
+        when IR::Interpolation then render_test_expression(iterable, translator)
+        else "[]"
+        end
+      end
+
       def render_element(element, translator, indent:)
         return render_element_with_tag_builder(element, translator, indent: indent) if needs_tag_builder?(element)
 
@@ -312,13 +398,11 @@ module JsxRosetta
 
       def tag_builder_data_action(events, translator)
         descriptors = events.map { |event| tag_builder_event_descriptor(event, translator) }
-        all_literal = descriptors.all? { |d| d.start_with?('"') && d.end_with?('"') }
-        joined = if descriptors.size == 1
-                   descriptors.first
-                 elsif all_literal
-                   %("#{descriptors.map { |d| d[1..-2] }.join(" ")}")
+        joined = case descriptors
+                 in [single]
+                   render_single_event_descriptor(single)
                  else
-                   %("#{descriptors.map { |d| literal_to_interpolated(d) }.join(" ")}")
+                   %("#{descriptors.map { |d| descriptor_in_string(d) }.join(" ")}")
                  end
         %("data-action" => #{joined})
       end
@@ -327,23 +411,34 @@ module JsxRosetta
         case event
         when IR::EventBinding
           translated = translator.translate(event.handler.expression)
-          translated ? translated.ruby : event.handler.expression.inspect
+          if translated
+            EventDescriptor.new(:ruby, translated.ruby)
+          else
+            EventDescriptor.new(:ruby, event.handler.expression.inspect)
+          end
         when IR::StimulusBinding
-          %("#{event.event}->#{@stimulus_identifier}##{event.method_name}")
+          EventDescriptor.new(:literal, "#{event.event}->#{@stimulus_identifier}##{event.method_name}")
         end
       end
 
-      def literal_to_interpolated(descriptor)
-        if descriptor.start_with?('"') && descriptor.end_with?('"')
-          descriptor[1..-2]
-        else
-          "\#{#{descriptor}}"
-        end
+      def render_single_event_descriptor(descriptor)
+        descriptor.kind == :literal ? %("#{descriptor.body}") : descriptor.body
       end
 
+      # Render a descriptor inline inside a Ruby string literal: literals
+      # are spliced verbatim, ruby expressions become `#{...}`.
+      def descriptor_in_string(descriptor)
+        descriptor.kind == :literal ? descriptor.body : "\#{#{descriptor.body}}"
+      end
+
+      # Wrap the spread expression in `(… || {})` so a nil-valued prop
+      # default doesn't raise at render time. `<div {...maybeNil}>` →
+      # `**(@maybe_nil || {})`. Cheap to emit unconditionally; the
+      # `|| {}` shortcuts on non-nil values.
       def tag_builder_spread(expression, translator)
         translated = translator.translate(expression)
-        translated ? translated.ruby : expression
+        ruby = translated ? translated.ruby : expression
+        "(#{ruby} || {})"
       end
 
       def render_component_invocation(invocation, translator, indent:)
@@ -354,7 +449,10 @@ module JsxRosetta
         class_name = component_class_name(invocation.name)
         new_call = kwargs.empty? ? "#{class_name}.new" : "#{class_name}.new(#{kwargs})"
 
-        if invocation.children.empty?
+        render_prop = invocation.children.find { |c| c.is_a?(IR::RenderProp) }
+        if render_prop
+          render_component_with_render_prop(new_call, render_prop, translator, indent)
+        elsif invocation.children.empty?
           "#{spaces(indent)}<%= render #{new_call} %>"
         else
           inner = invocation.children.map { |child| render_ir_node(child, translator, indent: indent + 2) }.join("\n")
@@ -362,6 +460,15 @@ module JsxRosetta
         end
       end
 
+      def render_component_with_render_prop(new_call, render_prop, translator, indent)
+        snake_params = render_prop.params.map { |p| AST::Inflector.underscore(p) }
+        param_str = snake_params.empty? ? "" : " |#{snake_params.join(", ")}|"
+        inner = translator.with_locals(render_prop.params) do
+          render_ir_node(render_prop.body, translator, indent: indent + 2)
+        end
+        "#{spaces(indent)}<%= render #{new_call} do#{param_str} %>\n#{inner}\n#{spaces(indent)}<% end %>"
+      end
+
       # JSX `<Foo.Bar>` → Ruby `Foo::BarComponent`. Plain `<Card>` stays as
       # `CardComponent`. Each member-expression segment joins with `::`,
       # and `Component` suffixes the leaf so the result is a constant path
@@ -455,52 +562,53 @@ module JsxRosetta
       end
 
       def render_style(style, translator)
-        rendered = style.declarations.map { |decl| render_style_declaration(decl, translator) }.join(" ")
+        rendered = style.declarations.map { |decl| style_declaration(decl, translator, format: :erb) }.join(" ")
         %(style="#{rendered}")
       end
 
-      def render_style_declaration(decl, translator)
+      def render_class_list_attribute(class_list, translator)
+        parts = class_list.segments.map { |seg| class_segment(seg, translator, format: :erb) }
+        %(class="#{parts.join(" ")}")
+      end
+
+      def class_list_to_ruby_string(class_list, translator)
+        parts = class_list.segments.map { |seg| class_segment(seg, translator, format: :ruby_string) }
+        %("#{parts.join(" ")}")
+      end
+
+      # Render one IR::Style declaration in either ERB-template form
+      # (`color: <%= @c %>;`) or Ruby-string-interpolation form
+      # (`color: #{@c};`).
+      def style_declaration(decl, translator, format:)
         value = case decl.value
                 when String then decl.value
-                when IR::Interpolation
-                  translated = translator.translate(decl.value.expression)
-                  "<%= #{translated&.ruby || decl.value.expression} %>"
+                when IR::Interpolation then interpolation_value(decl.value.expression, translator, format: format)
                 end
         "#{decl.property}: #{value};"
       end
 
-      def render_class_list_attribute(class_list, translator)
-        parts = class_list.segments.map { |seg| class_segment_for_html(seg, translator) }
-        %(class="#{parts.join(" ")}")
-      end
-
-      def class_segment_for_html(segment, translator)
+      # Render one ClassList segment in either ERB-template form or Ruby
+      # string-interpolation form.
+      def class_segment(segment, translator, format:)
         case segment
         when String then segment
-        when IR::Interpolation
-          translated = translator.translate(segment.expression)
-          "<%= #{translated&.ruby || segment.expression} %>"
-        when IR::ConditionalSegment
-          cond_translated = translator.translate(segment.condition.expression)
-          cond_ruby = cond_translated&.ruby || segment.condition.expression
-          "<%= #{cond_ruby} ? #{segment.class_name.inspect} : '' %>"
+        when IR::Interpolation then interpolation_value(segment.expression, translator, format: format)
+        when IR::ConditionalSegment then conditional_class_segment(segment, translator, format: format)
         end
       end
 
-      def class_list_to_ruby_string(class_list, translator)
-        parts = class_list.segments.map { |seg| class_segment_for_ruby(seg, translator) }
-        %("#{parts.join(" ")}")
+      def interpolation_value(expression, translator, format:)
+        translated = translator.translate(expression)
+        ruby = translated&.ruby || expression
+        format == :erb ? "<%= #{ruby} %>" : "\#{#{ruby}}"
       end
 
-      def class_segment_for_ruby(segment, translator)
-        case segment
-        when String then segment
-        when IR::Interpolation
-          translated = translator.translate(segment.expression)
-          "\#{#{translated&.ruby || segment.expression}}"
-        when IR::ConditionalSegment
-          cond_translated = translator.translate(segment.condition.expression)
-          cond_ruby = cond_translated&.ruby || segment.condition.expression
+      def conditional_class_segment(segment, translator, format:)
+        cond_translated = translator.translate(segment.condition.expression)
+        cond_ruby = cond_translated&.ruby || segment.condition.expression
+        if format == :erb
+          "<%= #{cond_ruby} ? #{segment.class_name.inspect} : '' %>"
+        else
           %(\#{#{cond_ruby} ? #{segment.class_name.inspect} : ""})
         end
       end
@@ -598,15 +706,7 @@ module JsxRosetta
       end
 
       def style_to_ruby_string(style, translator)
-        parts = style.declarations.map do |decl|
-          value = case decl.value
-                  when String then decl.value
-                  when IR::Interpolation
-                    translated = translator.translate(decl.value.expression)
-                    "\#{#{translated&.ruby || decl.value.expression}}"
-                  end
-          "#{decl.property}: #{value};"
-        end
+        parts = style.declarations.map { |decl| style_declaration(decl, translator, format: :ruby_string) }
         %("#{parts.join(" ")}")
       end
 

data/lib/jsx_rosetta/backend.rb

@@ -4,6 +4,7 @@ require_relative "backend/base"
 require_relative "backend/view_component"
 require_relative "backend/view_component/expression_translator"
 require_relative "backend/rails_view"
+require_relative "backend/phlex"
 require_relative "backend/routes_script"
 
 module JsxRosetta

data/lib/jsx_rosetta/cli.rb

@@ -63,16 +63,40 @@ module JsxRosetta
 
       out_dir = options[:out] || "."
       typescript = options[:tsx] || input_path.end_with?(".tsx")
-      backend = options[:as] == "view" ? :rails_view : :view_component
+      backend = backend_for_as(options[:as])
+      backend_options = backend_options_for(backend, options)
 
       source = File.read(input_path)
       files = JsxRosetta.translate(
         source,
         backend: backend,
+        backend_options: backend_options,
         typescript: typescript,
         source_filename: input_path
       )
 
+      write_emitted_files(files, out_dir)
+      EXIT_OK
+    rescue ParseError, IR::Lowering::LoweringError, ArgumentError => e
+      @stderr.puts "jsx_rosetta translate: #{e.message}"
+      EXIT_FAILURE
+    end
+
+    def backend_for_as(value)
+      case value
+      when "view" then :rails_view
+      when "phlex" then :phlex
+      else :view_component
+      end
+    end
+
+    def backend_options_for(backend, options)
+      return {} unless backend == :phlex
+
+      { suffix: options[:phlex_suffix], namespace: options[:phlex_namespace] }.compact
+    end
+
+    def write_emitted_files(files, out_dir)
       FileUtils.mkdir_p(out_dir)
       files.each do |file|
         target = File.join(out_dir, file.path)
@@ -80,10 +104,6 @@ module JsxRosetta
         File.write(target, file.contents)
         @stdout.puts "wrote #{target}"
       end
-      EXIT_OK
-    rescue ParseError, IR::Lowering::LoweringError => e
-      @stderr.puts "jsx_rosetta translate: #{e.message}"
-      EXIT_FAILURE
     end
 
     def run_routes
@@ -142,6 +162,10 @@ module JsxRosetta
         when "--tsx", "--typescript" then options[:tsx] = true
         when "--as" then options[:as] = @argv.shift
         when /\A--as=(.+)\z/ then options[:as] = ::Regexp.last_match(1)
+        when "--phlex-suffix" then options[:phlex_suffix] = @argv.shift
+        when /\A--phlex-suffix=(.*)\z/ then options[:phlex_suffix] = ::Regexp.last_match(1)
+        when "--phlex-namespace" then options[:phlex_namespace] = @argv.shift
+        when /\A--phlex-namespace=(.+)\z/ then options[:phlex_namespace] = ::Regexp.last_match(1)
         else positional << arg
         end
       end
@@ -166,6 +190,10 @@ module JsxRosetta
                                      Pass --as=view to emit a Rails view template (`<snake>.html.erb`)
                                      instead of a ViewComponent class + sidecar template — appropriate
                                      for pages tied to a route.
+                                     Pass --as=phlex to emit a single-file Phlex 2.x view class
+                                     (`<snake>.rb`) instead of a ViewComponent. Configure the class
+                                     name with --phlex-suffix=Component or --phlex-namespace=Components
+                                     (mutually exclusive; default is bare class name).
           routes FILE [-o OUT.rb]    Parse <Route path=... element={<X/>} /> patterns from FILE
                                      and emit a reviewable Ruby script that calls `rails generate
                                      controller` and prints suggested config/routes.rb additions.