jsx_rosetta 0.4.0 → 0.5.1

data/lib/jsx_rosetta/backend/phlex.rb

@@ -31,6 +31,40 @@ module JsxRosetta
       VALID_IDENTIFIER = /\A[a-z_][a-z0-9_]*\z/i
       VOID_ELEMENTS = %w[area base br col embed hr img input link meta param source track wbr].freeze
 
+      # Inline budget for object/array literal rendering. When the
+      # single-line rendering of a literal exceeds this width — measured
+      # from the opening bracket — it switches to a multi-line layout
+      # with one entry per line, indented two spaces past the parent's
+      # line indent. Closing bracket re-aligns to the parent indent.
+      # Chosen to keep typical attr lines under ~120 chars after the
+      # kwarg name and surrounding `render Foo.new(...)` wrapper.
+      LITERAL_INLINE_BUDGET = 80
+
+      # Per-library TODO header lines surfaced above the verbatim hook
+      # source. Each library has a different Rails analog, so we don't
+      # collapse them into a single generic block. Keys must mirror the
+      # `:library` values produced by IR::Lowering.
+      HOOK_TODO_HEADERS = {
+        react: [
+          "TODO: React hooks detected. None translate automatically.",
+          "Hotwire/Stimulus handles behavior; controllers/views handle state;",
+          "turbo-frames handle async loading. Original source:"
+        ].freeze,
+        apollo: [
+          "TODO: Apollo data-fetching hooks detected. None translate automatically.",
+          "Move the fetch to the Rails controller (or a model/service); pass the",
+          "result in as a prop. For useMutation, use a form POST + redirect or a",
+          "Turbo Stream response. Original source:"
+        ].freeze,
+        next_js: [
+          "TODO: Next.js navigation hooks detected. None translate automatically.",
+          "Rails analogs: useRouter -> redirect_to / form actions;",
+          "usePathname -> request.path; useSearchParams / useParams -> params;",
+          "useSelectedLayoutSegment(s) -> match against request.path in the view.",
+          "Original source:"
+        ].freeze
+      }.freeze
+
       # Structured intermediate for the data-action attribute — mirrors the
       # ViewComponent backend pattern (lib/jsx_rosetta/backend/view_component.rb).
       EventDescriptor = Data.define(:kind, :body)
@@ -44,17 +78,12 @@ module JsxRosetta
       end
 
       def emit(component)
-        prop_names = component.props.map(&:name)
-        prop_names << component.rest_prop_name if component.rest_prop_name
-        translator = ViewComponent::ExpressionTranslator.new(
-          prop_names: prop_names, local_binding_names: component.local_binding_names
-        )
-
+        translator = build_translator(component)
         @stimulus_identifier = component.stimulus_methods.any? ? stimulus_identifier(component) : nil
         @lambda_methods = []
         @lambda_method_counts = {}
 
-        files = [File.new(path: ruby_path(component), contents: render_ruby_class(component, translator))]
+        files = [File.new(path: ruby_path(component), contents: clean_output(render_ruby_class(component, translator)))]
         if component.stimulus_methods.any?
           files << File.new(
             path: stimulus_path(component),
@@ -64,6 +93,56 @@ module JsxRosetta
         files
       end
 
+      def build_translator(component)
+        prop_names = component.props.map(&:name)
+        prop_names << component.rest_prop_name if component.rest_prop_name
+        prop_aliases = component.props.each_with_object({}) do |prop, hash|
+          hash[prop.alias_name] = prop.name if prop.alias_name
+        end
+        ViewComponent::ExpressionTranslator.new(
+          prop_names: prop_names,
+          local_binding_names: component.local_binding_names,
+          prop_aliases: prop_aliases
+        )
+      end
+
+      # Strip trailing whitespace from each emitted line — easier than
+      # threading rstrip through every formatting helper, and a single
+      # source of truth keeps Layout/TrailingWhitespace at zero. Preserve
+      # the trailing newline of the file as-is. Also suppresses the
+      # intentional-`if false` cops file-wide so the user's rubocop
+      # doesn't drown out actionable findings.
+      def clean_output(source)
+        cleaned = "#{source.split("\n").map(&:rstrip).join("\n")}\n".sub(/\n\n+\z/, "\n")
+        suppress_intentional_if_false_cops(cleaned)
+      end
+
+      # When the file contains any `if false` / `elsif false` branch (the
+      # fallback we emit when a JSX condition can't be translated to Ruby),
+      # disable the cops that flag those at file scope. The corresponding
+      # `# TODO: translate condition:` comment already names the issue, so
+      # the cop's report is redundant noise. Only emits when needed.
+      def suppress_intentional_if_false_cops(source)
+        cops = []
+        cops << "Lint/LiteralAsCondition" if source.match?(/^\s*(?:if|elsif) false$/m)
+        # An elsif-false adjacent to its leading `if false` is the only
+        # configuration that triggers DuplicateElsifCondition — multiple
+        # `if false`s in separate scopes don't qualify. The pattern below
+        # matches an `if false` directly followed (after consequent lines)
+        # by an `elsif false` at the same indent.
+        cops << "Lint/DuplicateElsifCondition" if source.match?(/^(\s*)if false\b[\s\S]*?^\1elsif false\b/m)
+        return source if cops.empty?
+
+        disable = "# rubocop:disable #{cops.join(", ")}\n\n"
+        enable = "# rubocop:enable #{cops.join(", ")}\n"
+        # Magic comment must be followed by a blank line before any other
+        # comment (Layout/EmptyLineAfterMagicComment), and every file-level
+        # disable needs a matching enable (Lint/MissingCopEnableDirective).
+        with_disable = source.sub(/^# frozen_string_literal: true\n\n/,
+                                  "# frozen_string_literal: true\n\n#{disable}")
+        "#{with_disable.chomp}\n#{enable}"
+      end
+
       private
 
       # JSX-returning lowercase helpers (e.g. `textRender`, `getNodeIcon`)
@@ -117,22 +196,78 @@ module JsxRosetta
 
       def render_class_body(component, translator)
         initializer = render_initializer(component, translator)
-        template = render_view_template(component, translator)
-        # Render lambdas only AFTER the template — `@lambda_methods` is
-        # populated as attribute values are rendered.
-        lambda_methods = render_lambda_method_definitions(translator)
-
-        sections = [initializer, template, lambda_methods].compact.join("\n\n")
-        "class #{class_name(component)} < #{PHLEX_BASE_CLASS}\n#{sections}\nend\n"
+        template = if component.mode == :data_factory
+                     render_data_factory_method(component, translator)
+                   else
+                     render_view_template(component, translator)
+                   end
+        # Render private methods (render_methods + lambdas) AFTER the
+        # template — `@lambda_methods` is populated during attribute-value
+        # rendering, and render_methods bodies share the same indent.
+        private_section = render_private_methods(component, translator)
+
+        sections = [initializer, template, private_section].compact.join("\n\n")
+        cls = class_name(component)
+        # One-line docstring above the class — pacifies Style/Documentation
+        # without forcing the host project to disable the cop globally. The
+        # 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"
+      end
+
+      # For data-factory components (`export const createColumns = (args)
+      # => [{...}, {...}]`) emit a public method that returns the
+      # translated data array. The method name is the snake_case of the
+      # original JS identifier (`createColumns` → `create_columns`).
+      # Param names come from the regular `props:` list so callers can
+      # invoke with keyword arguments matching the JS signature.
+      def render_data_factory_method(component, translator)
+        method_name = AST::Inflector.underscore(component.name)
+        param_names = component.props.map(&:name)
+        signature = data_factory_signature(method_name, param_names)
+        # Param refs translate as locals (`token`) inside the body rather
+        # than as ivars (`@token`) — the factory params are method-local,
+        # not constructor-stored. `with_locals` pushes the JS names onto
+        # the translator's local stack for the duration of the body.
+        body = translator.with_locals(param_names) do
+          render_inline_value(component.body, translator, todos: [], attr_name: nil, indent: 4)
+        end
+        "  def #{signature}\n    #{body}\n  end"
       end
 
-      def render_lambda_method_definitions(translator)
-        return nil if @lambda_methods.nil? || @lambda_methods.empty?
+      def data_factory_signature(method_name, param_names)
+        return method_name if param_names.empty?
 
-        defs = @lambda_methods.map do |entry|
+        kwargs = param_names.map { |name| "#{AST::Inflector.underscore(name)}: nil" }
+        "#{method_name}(#{kwargs.join(", ")})"
+      end
+
+      # Coalesce RenderMethod (from local-arrow extraction) and Lambda
+      # (from Gap H object-literal extraction) into one `private` section.
+      # Emitting `private` twice is harmless but ugly; one block reads
+      # cleaner.
+      def render_private_methods(component, translator)
+        render_methods = component.render_methods.map { |rm| render_render_method_definition(rm, translator) }
+        lambda_methods = (@lambda_methods || []).map do |entry|
           render_lambda_method_definition(entry[:method_name], entry[:lambda], translator)
         end
-        "  private\n\n#{defs.join("\n\n")}"
+        all = render_methods + lambda_methods
+        return nil if all.empty?
+
+        "  private\n\n#{all.join("\n\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.
+      def render_render_method_definition(render_method, translator)
+        snake_params = render_method.params.map { |p| AST::Inflector.underscore(p) }
+        signature = snake_params.empty? ? render_method.name : "#{render_method.name}(#{snake_params.join(", ")})"
+        body = translator.with_locals(render_method.params) do
+          render_ir_node(render_method.body, translator, indent: 4)
+        end
+        "  def #{signature}\n#{body}\n  end"
       end
 
       def render_lambda_method_definition(method_name, lambda, translator)
@@ -145,20 +280,30 @@ module JsxRosetta
       end
 
       def render_initializer(component, translator)
+        # Data-factory components consume their params as method args, not
+        # as constructor props — skip the initializer entirely.
+        return nil if component.mode == :data_factory
+
         props = initializable_props(component)
         rest_name = component.rest_prop_name
         return nil if props.empty? && rest_name.nil?
 
+        # Snake-case the rest-name kwarg so it matches the snake_case ivar
+        # the body uses (`**(@description_props || {})`). Emitting the
+        # camelCase JS name straight to the kwarg would create a different
+        # ivar than the body reads, silently dropping the splat's contents.
+        rest_snake = rest_name && AST::Inflector.underscore(rest_name)
         kwargs = props.map { |prop| ruby_kwarg(prop, translator) }
-        kwargs << "**#{rest_name}" if rest_name
+        kwargs << "**#{rest_snake}" if rest_snake
 
-        assignments = props.map do |prop|
+        body = ["    super()"]
+        body.concat(props.map do |prop|
           snake = AST::Inflector.underscore(prop.name)
           "    @#{snake} = #{snake}"
-        end
-        assignments << "    @#{rest_name} = #{rest_name}" if rest_name
+        end)
+        body << "    @#{rest_snake} = #{rest_snake}" if rest_snake
 
-        "  def initialize(#{kwargs.join(", ")})\n#{assignments.join("\n")}\n  end"
+        "  def initialize(#{kwargs.join(", ")})\n#{body.join("\n")}\n  end"
       end
 
       def initializable_props(component)
@@ -179,10 +324,13 @@ module JsxRosetta
           translated = translator.translate(prop.default.expression)
           translated ? translated.ruby : "nil"
         when IR::ObjectLiteral, IR::ArrayLiteral, IR::Lambda
-          # Inline values: route through the recursive renderer. Pass an
-          # empty todos array — TODO markers wouldn't be safe inside a
-          # parameter-list anyway.
-          render_inline_value(prop.default, translator, todos: [], attr_name: prop.name)
+          # Inline values: route through the recursive renderer with
+          # `force_inline: true`. A wrapped multi-line default inside the
+          # `initialize(...)` parameter list would put the `{` at one
+          # column and the children at the indent-aligned column —
+          # legal Ruby but trips Layout/FirstHashElementIndentation. Empty
+          # todos array — TODO markers wouldn't survive a parameter list.
+          render_inline_value(prop.default, translator, todos: [], attr_name: prop.name, force_inline: true)
         else
           "nil"
         end
@@ -207,12 +355,19 @@ module JsxRosetta
       def render_react_hooks_todo(hooks)
         return [] if hooks.empty?
 
-        lines = [
-          "# TODO: React hooks detected. None translate automatically.",
-          "# Hotwire/Stimulus handles behavior; controllers/views handle state;",
-          "# turbo-frames handle async loading. Original source:"
-        ]
-        hooks.each { |hook| lines.concat(comment_lines(hook.source)) }
+        # 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) }
+      end
+
+      def hook_todo_block_lines(library, calls)
+        header_lines = HOOK_TODO_HEADERS.fetch(library, HOOK_TODO_HEADERS[:react])
+        lines = header_lines.map { |line| "# #{line}" }
+        calls.each do |call|
+          lines << "#   operation: #{call.operation}" if call.operation
+          lines.concat(comment_lines(call.source))
+        end
         lines
       end
 
@@ -249,6 +404,7 @@ module JsxRosetta
         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::LocalRenderCall then render_local_render_call(node, translator, indent: indent)
         when IR::Slot then render_slot(node, indent: indent)
         when IR::Text then render_text(node, indent: indent)
         when IR::Interpolation then render_interpolation(node, translator, indent: indent)
@@ -256,6 +412,23 @@ module JsxRosetta
         end
       end
 
+      # Emit a call to a previously-extracted RenderMethod. The method body
+      # uses `tag.*`/`render` helpers (Phlex executes inside the view), so
+      # invoking it inline produces output at the right place in the
+      # template. Arg expressions are translated; any that fail translation
+      # fall back to verbatim source.
+      def render_local_render_call(call, translator, indent:)
+        if call.args.empty?
+          "#{spaces(indent)}#{call.method_name}"
+        else
+          arg_sources = call.args.map do |arg|
+            translated = translator.translate(arg.expression)
+            translated ? translated.ruby : arg.expression
+          end
+          "#{spaces(indent)}#{call.method_name}(#{arg_sources.join(", ")})"
+        end
+      end
+
       # An orphan RenderProp (i.e. one that didn't get consumed as a block
       # by a parent ComponentInvocation). Emit the body inline within the
       # appropriate translator scope; the param names are pushed but no
@@ -268,7 +441,7 @@ module JsxRosetta
 
       def render_element(element, translator, indent:)
         todos = []
-        attrs_source = format_attributes(element.attributes, translator, context: :html, todos: todos)
+        attrs_source = format_attributes(element.attributes, translator, context: :html, todos: todos, indent: indent)
         method_call = "#{element.tag}#{attrs_source}"
 
         body = if VOID_ELEMENTS.include?(element.tag) || element.children.empty?
@@ -283,7 +456,7 @@ module JsxRosetta
 
       def render_component_invocation(invocation, translator, indent:)
         todos = []
-        kwargs = component_invocation_kwargs(invocation.props, translator, todos: todos)
+        kwargs = component_invocation_kwargs(invocation.props, translator, todos: todos, indent: indent)
         class_ref = component_class_reference(invocation.name)
         new_call = kwargs.empty? ? "#{class_ref}.new" : "#{class_ref}.new(#{kwargs})"
 
@@ -335,17 +508,34 @@ module JsxRosetta
       end
 
       def render_conditional(conditional, translator, indent:)
-        test_ruby, todo = safe_test_expression(conditional.test.expression, translator, fallback: "false")
         lines = []
+        emit_conditional_branches(conditional, translator, indent, lines, leading_keyword: "if")
+        lines << "#{spaces(indent)}end"
+        lines.join("\n")
+      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
+      # `if X / else / if Y / end / end` shape that JS `else if` chains
+      # produce into idiomatic Ruby `if X / elsif Y / else / end`. Without
+      # 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
-        lines << "#{spaces(indent)}if #{test_ruby}"
+        lines << "#{spaces(indent)}#{leading_keyword} #{test_ruby}"
         lines << render_ir_node(conditional.consequent, translator, indent: indent + 2)
-        if conditional.alternate
+
+        alt = conditional.alternate
+        return unless alt
+
+        if alt.is_a?(IR::Conditional)
+          emit_conditional_branches(alt, translator, indent, lines, leading_keyword: "elsif")
+        else
           lines << "#{spaces(indent)}else"
-          lines << render_ir_node(conditional.alternate, translator, indent: indent + 2)
+          lines << render_ir_node(alt, translator, indent: indent + 2)
         end
-        lines << "#{spaces(indent)}end"
-        lines.join("\n")
       end
 
       def render_loop(loop_node, translator, indent:)
@@ -389,9 +579,15 @@ module JsxRosetta
       # 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.
+      #
+      # 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.
       def safe_test_expression(expression, translator, fallback:)
         translated = translator.translate(expression)
-        return [translated.ruby, nil] if translated
+        return [translated.ruby, nil] if translated && translated.ruby != "nil"
 
         compact = expression.tr("\n", " ").squeeze(" ")
         [fallback, compact]
@@ -406,7 +602,7 @@ module JsxRosetta
       end
 
       def render_text(text, indent:)
-        "#{spaces(indent)}plain #{text.value.inspect}"
+        "#{spaces(indent)}plain #{AST::Inflector.ruby_string_literal(text.value)}"
       end
 
       def render_interpolation(interpolation, translator, indent:)
@@ -443,8 +639,9 @@ module JsxRosetta
       # renders something visible at runtime.
       def render_untranslated_interpolation(expression, indent)
         compact = expression.tr("\n", " ").squeeze(" ")
+        placeholder = AST::Inflector.ruby_string_literal("[untranslated: #{compact}]")
         "#{spaces(indent)}# TODO: translate #{compact.inspect}\n" \
-          "#{spaces(indent)}plain #{"[untranslated: #{compact}]".inspect}"
+          "#{spaces(indent)}plain #{placeholder}"
       end
 
       def render_comment(comment, indent:)
@@ -459,31 +656,30 @@ 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: [])
+      def format_attributes(attributes, translator, context: :html, 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) }
 
-        sym_parts = []
-        str_parts = []
+        parts = { sym: [], str: [] }
         plain_attrs.each do |a|
-          append_attribute_part(a, translator, sym_parts, str_parts, context: context, todos: todos)
+          append_attribute_part(a, translator, parts, context: context, todos: todos, indent: indent)
         end
-        sym_parts << data_action_entry(events, translator) if events.any?
+        parts[:sym] << data_action_entry(events, translator) if events.any?
 
-        joined = build_attribute_list(sym_parts, str_parts, spreads, translator)
+        joined = build_attribute_list(parts, spreads, translator)
         joined.empty? ? "" : "(#{joined})"
       end
 
-      def append_attribute_part(attribute, translator, sym_parts, str_parts, context:, todos:)
-        part = phlex_attribute_part(attribute, translator, context: context, todos: todos)
+      def append_attribute_part(attribute, translator, parts, context:, todos:, indent: 0)
+        part = phlex_attribute_part(attribute, translator, context: context, todos: todos, indent: indent)
         return unless part
 
-        (part[:string_key] ? str_parts : sym_parts) << part[:source]
+        (part[:string_key] ? parts[:str] : parts[:sym]) << part[:source]
       end
 
-      def build_attribute_list(sym_parts, str_parts, spreads, translator)
-        pieces = sym_parts.dup
-        pieces << "**{ #{str_parts.join(", ")} }" if str_parts.any?
+      def build_attribute_list(parts, spreads, translator)
+        pieces = parts[:sym].dup
+        pieces << "**{ #{parts[:str].join(", ")} }" if parts[:str].any?
         pieces.concat(spreads.map { |s| "**#{render_spread(s.expression, translator)}" })
         pieces.join(", ")
       end
@@ -491,12 +687,13 @@ 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:)
+      def phlex_attribute_part(attribute, translator, context:, todos:, indent: 0)
         case attribute
         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)}" }
-        when IR::Attribute then plain_attribute_part(attribute, translator, context: context, todos: todos)
+        when IR::Style then { string_key: false, source: "style: #{style_to_ruby_string(attribute, translator, todos: todos)}" }
+        when IR::Attribute
+          plain_attribute_part(attribute, translator, context: context, todos: todos, indent: indent)
         end
       end
 
@@ -515,8 +712,8 @@ 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:)
-        value_ruby = attribute_value_to_ruby(attribute.name, attribute.value, translator, todos: todos)
+      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)
         ruby_name = case context
                     when :component then AST::Inflector.underscore(attribute.name)
                     else attribute.name.tr("-", "_")
@@ -524,17 +721,17 @@ module JsxRosetta
         if ruby_name.match?(VALID_IDENTIFIER)
           { string_key: false, source: "#{ruby_name}: #{value_ruby}" }
         else
-          { string_key: true, source: "#{attribute.name.inspect} => #{value_ruby}" }
+          { string_key: true, source: "#{AST::Inflector.ruby_string_literal(attribute.name)} => #{value_ruby}" }
         end
       end
 
-      def attribute_value_to_ruby(name, value, translator, todos:)
+      def attribute_value_to_ruby(name, value, translator, todos:, indent: 0)
         case value
         when true then "true"
-        when String then value.inspect
+        when String then AST::Inflector.ruby_string_literal(value)
         when IR::Interpolation then interpolated_attribute_value(name, value, translator, todos: todos)
-        when IR::ObjectLiteral then render_object_literal_value(value, translator, todos: todos)
-        when IR::ArrayLiteral then render_array_literal_value(value, translator, todos: todos)
+        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)
         end
       end
@@ -542,41 +739,75 @@ module JsxRosetta
       # 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.
-      def render_object_literal_value(object_literal, translator, todos:)
+      # When the single-line rendering exceeds LITERAL_INLINE_BUDGET, or
+      # when any rendered child value spans multiple lines, the layout
+      # switches to one entry per line, indented two spaces past `indent`.
+      def render_object_literal_value(object_literal, translator, todos:, indent: 0, force_inline: false)
+        child_indent = indent + 2
         parts = object_literal.properties.map do |(key, value)|
-          render_object_property(key, value, translator, todos: todos)
+          render_object_property(key, value, translator, todos: todos, indent: child_indent, force_inline: force_inline)
         end
-        "{ #{parts.join(", ")} }"
+        wrap_literal_parts(parts, open: "{", close: "}", indent: indent, inline_sep: ", ", inline_pad: " ",
+                                  force_inline: force_inline)
       end
 
-      def render_object_property(key, value, translator, todos:)
-        value_ruby = render_inline_value(value, translator, todos: todos, attr_name: key)
+      def render_object_property(key, value, translator, todos:, indent: 0, force_inline: false)
+        value_ruby = render_inline_value(value, translator, todos: todos, attr_name: key, indent: indent,
+                                                            force_inline: force_inline)
         snake = AST::Inflector.underscore(key)
         if snake.match?(VALID_IDENTIFIER)
           "#{snake}: #{value_ruby}"
         else
-          "#{key.inspect} => #{value_ruby}"
+          "#{AST::Inflector.ruby_string_literal(key)} => #{value_ruby}"
         end
       end
 
-      def render_array_literal_value(array_literal, translator, todos:)
+      def render_array_literal_value(array_literal, translator, todos:, indent: 0, force_inline: false)
+        child_indent = indent + 2
         parts = array_literal.elements.map do |el|
-          el.nil? ? "nil" : render_inline_value(el, translator, todos: todos, attr_name: nil)
+          if el.nil?
+            "nil"
+          else
+            render_inline_value(el, translator, todos: todos, attr_name: nil, indent: child_indent,
+                                                force_inline: force_inline)
+          end
         end
-        "[#{parts.join(", ")}]"
+        wrap_literal_parts(parts, open: "[", close: "]", indent: indent, inline_sep: ", ", inline_pad: "",
+                                  force_inline: force_inline)
+      end
+
+      # Pick single-line vs multi-line layout for a rendered literal.
+      # Multi-line is forced when any rendered part already contains a
+      # newline (a nested literal that wrapped); otherwise we wrap only
+      # when the single-line form exceeds LITERAL_INLINE_BUDGET.
+      def wrap_literal_parts(parts, **opts)
+        open = opts[:open]
+        close = opts[:close]
+        return "#{open}#{close}" if parts.empty?
+
+        inline = "#{open}#{opts[:inline_pad]}#{parts.join(opts[:inline_sep])}#{opts[:inline_pad]}#{close}"
+        any_multiline = parts.any? { |p| p.include?("\n") }
+        return inline if opts[:force_inline]
+        return inline if !any_multiline && inline.length <= LITERAL_INLINE_BUDGET
+
+        child_pad = " " * (opts[:indent] + 2)
+        close_pad = " " * opts[:indent]
+        "#{open}\n#{child_pad}#{parts.join(",\n#{child_pad}")}\n#{close_pad}#{close}"
       end
 
       # An inline value can appear as a kwarg value, an array element, or a
       # hash property value. Recursive shapes route back through the new IR
       # types; primitives fall through the same paths as attribute_value_to_ruby.
-      def render_inline_value(value, translator, todos:, attr_name:)
+      def render_inline_value(value, translator, todos:, attr_name:, indent: 0, force_inline: false)
         case value
-        when IR::ObjectLiteral then render_object_literal_value(value, translator, todos: todos)
-        when IR::ArrayLiteral then render_array_literal_value(value, translator, todos: todos)
+        when IR::ObjectLiteral
+          render_object_literal_value(value, translator, todos: todos, indent: indent, force_inline: force_inline)
+        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::Interpolation then interpolated_attribute_value(attr_name || "<element>", value, translator,
                                                                  todos: todos)
-        when String then value.inspect
+        when String then AST::Inflector.ruby_string_literal(value)
         when true then "true"
         else
           "nil"
@@ -612,43 +843,51 @@ module JsxRosetta
         @lambda_method_counts[base] == 1 ? base : "#{base}#{@lambda_method_counts[base]}"
       end
 
-      # Attribute-position interpolation. Two failure modes:
-      #   1. Translator returns non-nil but with unresolved identifiers —
-      #      the Ruby reference is fine to emit (it'll surface as a
-      #      NameError at render time if it's wrong). Inline TODO comments
-      #      aren't safe in attribute position (would break hash splat or
-      #      method-call syntax), so the marker is suppressed.
-      #   2. Translator returns nil — the original JS expression couldn't
+      # Attribute-position interpolation. Three failure modes:
+      #   1. Translator returns non-nil, no unresolved identifiers — emit
+      #      the Ruby reference directly. Common case.
+      #   2. Translator returns non-nil but with unresolved identifiers
+      #      starting with uppercase (PascalCase / SCREAMING_SNAKE_CASE —
+      #      almost always imported constants or enums) — emitting bare
+      #      `default_page_size` from `DEFAULT_PAGE_SIZE` produces a
+      #      runtime NameError with no marker. Drop the value to `nil`
+      #      and surface a TODO with the verbatim source. Lowercase
+      #      unresolved identifiers may be Rails helpers (`current_user`)
+      #      and are passed through as before.
+      #   3. Translator returns nil — the original JS expression couldn't
       #      be parsed at all (e.g. `<LeftOutlined .../>`, array literals,
-      #      template literals with method calls). We emit `nil` for the
-      #      kwarg AND record the original expression in `todos` so the
-      #      caller can prepend a `# TODO:` comment line above the element.
+      #      template literals with method calls). Same TODO + nil path.
       def interpolated_attribute_value(name, value, translator, todos:)
         translated = translator.translate(value.expression)
-        return translated.ruby if translated
+        if translated && !uppercase_unresolved?(translated.unresolved_identifiers)
+          return translated.ruby
+        end
 
         compact = value.expression.tr("\n", " ").squeeze(" ")
         todos << "attribute #{name.inspect} dropped — couldn't translate: #{compact}"
         "nil"
       end
 
-      def component_invocation_kwargs(props, translator, todos: [])
+      def uppercase_unresolved?(unresolved_identifiers)
+        unresolved_identifiers.any? { |name| name[0] == name[0].upcase }
+      end
+
+      def component_invocation_kwargs(props, translator, todos: [], indent: 0)
         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) }
 
-        sym_parts = []
-        str_parts = []
+        parts = { sym: [], str: [] }
         plain_attrs.each do |a|
-          append_attribute_part(a, translator, sym_parts, str_parts, context: :component, todos: todos)
+          append_attribute_part(a, translator, parts, context: :component, todos: todos, indent: indent)
         end
-        sym_parts << data_action_entry(events, translator) if events.any?
+        parts[:sym] << data_action_entry(events, translator) if events.any?
 
-        build_attribute_list(sym_parts, str_parts, spreads, translator)
+        build_attribute_list(parts, spreads, translator)
       end
 
       def class_list_to_ruby_string(class_list, translator)
         parts = class_list.segments.map { |seg| class_segment_to_ruby(seg, translator) }
-        %("#{parts.join(" ")}")
+        wrap_concatenated_string(parts.join(" "))
       end
 
       def class_segment_to_ruby(segment, translator)
@@ -660,23 +899,46 @@ module JsxRosetta
         when IR::ConditionalSegment
           cond_translated = translator.translate(segment.condition.expression)
           cond_ruby = cond_translated&.ruby || segment.condition.expression
-          %(\#{#{cond_ruby} ? #{segment.class_name.inspect} : ""})
+          %(\#{#{cond_ruby} ? #{AST::Inflector.ruby_string_literal(segment.class_name)} : ''})
         end
       end
 
-      def style_to_ruby_string(style, translator)
-        parts = style.declarations.map { |decl| style_declaration_to_ruby(decl, translator) }
-        %("#{parts.join(" ")}")
+      def style_to_ruby_string(style, translator, todos: [])
+        parts = style.declarations.filter_map { |decl| style_declaration_to_ruby(decl, translator, todos: todos) }
+        wrap_concatenated_string(parts.join(" "))
       end
 
-      def style_declaration_to_ruby(decl, translator)
-        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};"
+      # Wrap a built-up Ruby string body in single quotes when it contains
+      # no interpolation (`\#{...}`) and no escaping pitfalls; otherwise
+      # use double quotes so the interpolation is honored. Keeps class /
+      # style attribute output passing Style/StringLiterals when no
+      # dynamic segments are present (the common case for hardcoded
+      # `style="margin-bottom: 16px"`).
+      def wrap_concatenated_string(body)
+        return %("#{body}") if body.include?("\#{") || body.include?("'") || body.include?("\\")
+
+        "'#{body}'"
+      end
+
+      def style_declaration_to_ruby(decl, translator, todos: [])
+        case decl.value
+        when String
+          "#{decl.property}: #{decl.value};"
+        when IR::Interpolation
+          translated = translator.translate(decl.value.expression)
+          # Translation failed (e.g., interpolation rooted at an
+          # unresolvable local). Emitting the verbatim JS source inside
+          # `\#{}` would render valid Ruby that NameErrors at runtime.
+          # Drop the declaration and surface a TODO above the element so
+          # the reviewer sees what was lost.
+          if translated.nil?
+            todos << "style declaration #{decl.property.inspect} dropped — " \
+                     "couldn't translate: #{decl.value.expression}"
+            nil
+          else
+            "#{decl.property}: \#{#{translated.ruby}};"
+          end
+        end
       end
 
       # Wrap the spread expression in `(… || {})` so a nil-valued prop
@@ -712,7 +974,7 @@ module JsxRosetta
       end
 
       def render_single_event_descriptor(descriptor)
-        descriptor.kind == :literal ? %("#{descriptor.body}") : descriptor.body
+        descriptor.kind == :literal ? AST::Inflector.ruby_string_literal(descriptor.body) : descriptor.body
       end
 
       def descriptor_in_string(descriptor)