jsx_rosetta 0.5.1 → 0.6.0

data/lib/jsx_rosetta/ir/lowering.rb

@@ -55,12 +55,12 @@ module JsxRosetta
         end
       end
 
-      def self.lower(file, source:)
-        new(source).lower_file(file)
+      def self.lower(file, source:, keep_slot: false)
+        new(source, keep_slot: keep_slot).lower_file(file)
       end
 
-      def self.lower_all(file, source:)
-        new(source).lower_all_components(file)
+      def self.lower_all(file, source:, keep_slot: false)
+        new(source, keep_slot: keep_slot).lower_all_components(file)
       end
 
       REACT_HOOKS = %w[
@@ -126,6 +126,14 @@ module JsxRosetta
         "LogicalExpression" => ->(n) { [n[:left], n[:right]] }
       }.freeze
 
+      # Known wrapper-call names that lowering peers through to find the
+      # inner component definition. Both bare (`memo(...)`) and React-
+      # namespaced (`React.memo(...)`) forms count. Wrappers we don't
+      # unwrap (e.g. `React.lazy` — different shape, no inline function
+      # body) stay off this list on purpose; declarations using them
+      # won't be recognized as components, same as pre-unwrap behavior.
+      HOC_WRAPPER_NAMES = %w[memo forwardRef observer connect withRouter withTranslation].to_set.freeze
+
       SHAPE_MESSAGES = {
         hoc_wrapped: "looks like a HOC-wrapped component (React.memo / forwardRef / lazy / observer) — " \
                      "this version doesn't peel HOC wrappers; remove the wrapper or upgrade when supported",
@@ -146,8 +154,14 @@ module JsxRosetta
         unknown: nil
       }.freeze
 
-      def initialize(source)
+      def initialize(source, keep_slot: false)
         @source = source
+        # When false (default), the shadcn `<Comp asChild>` pattern that
+        # routes through Radix's Slot.Root gets its Slot branch dropped at
+        # lowering time, leaving only the non-Slot HTML/component branch.
+        # When true, preserve the full polymorphic conditional (legacy
+        # behavior; useful if the consumer shims Components::Slot::Root).
+        @keep_slot = keep_slot
         @prop_names = []
         @local_jsx = {}
         @local_bindings = []
@@ -160,6 +174,11 @@ module JsxRosetta
         @react_hooks = []
         @render_methods = []
         @render_method_seen = {}
+        # File-level imports; populated once at lower_file / lower_all_components
+        # entry and consulted by JSX lowering to decide whether a member-chain
+        # tag like `SeparatorPrimitive.Root` should resolve through the Radix
+        # registry into an HTML Element.
+        @module_imports = []
         # Class-component non-render members (constructor, lifecycle hooks,
         # custom handlers). Keyed by class name; populated by
         # extract_class_component, drained by lower_component to surface
@@ -172,17 +191,63 @@ module JsxRosetta
         raise no_component_error(file.program) if candidates.empty?
 
         name, function = candidates.first
-        module_bindings = capture_module_bindings(file.program, candidates)
-        attach_module_bindings(lower_component(name, function), module_bindings)
+        @module_bindings = capture_module_bindings(file.program, candidates)
+        @module_imports = capture_module_imports(file.program)
+        @server_data_source = capture_server_data_source(file.program)
+        attach_module_metadata(lower_component(name, function),
+                               @module_bindings, @module_imports, @server_data_source)
       end
 
       def lower_all_components(file)
         candidates = find_component_functions(file.program)
         raise no_component_error(file.program) if candidates.empty?
 
-        module_bindings = capture_module_bindings(file.program, candidates)
-        candidates.map do |name, function|
-          attach_module_bindings(lower_component(name, function), module_bindings)
+        @module_bindings = capture_module_bindings(file.program, candidates)
+        @module_imports = capture_module_imports(file.program)
+        @server_data_source = capture_server_data_source(file.program)
+        candidates.each_with_index.map do |(name, function), idx|
+          # Only the first sibling carries the server_data_source — a page
+          # file has at most one such export, and attaching it to every
+          # sibling would duplicate the TODO block across N files.
+          sds = idx.zero? ? @server_data_source : nil
+          attach_module_metadata(lower_component(name, function),
+                                 @module_bindings, @module_imports, sds)
+        end
+      end
+
+      SERVER_DATA_HOOK_NAMES = %w[getServerSideProps getStaticProps].freeze
+
+      # Capture a top-level `export function getServerSideProps()` or
+      # `export const getServerSideProps = ...` (or getStaticProps) so the
+      # Phlex backend can surface the body as a TODO comment block. Returns
+      # nil when no such export is present (the common case for ordinary
+      # components — only Next.js pages have these).
+      def capture_server_data_source(program)
+        program.body.each do |stmt|
+          next unless stmt.of_type?("ExportNamedDeclaration")
+
+          decl = stmt[:declaration]
+          next unless decl.is_a?(AST::Node)
+
+          name = server_data_hook_name(decl)
+          return ServerDataSource.new(hook_name: name, source: source_of(stmt)) if name
+        end
+        nil
+      end
+
+      def server_data_hook_name(decl)
+        case decl.type
+        when "FunctionDeclaration"
+          id = decl[:id]
+          id&.[](:name) if id.is_a?(AST::Node) && SERVER_DATA_HOOK_NAMES.include?(id[:name])
+        when "VariableDeclaration"
+          first = decl[:declarations].first
+          return nil unless first.is_a?(AST::Node)
+
+          id = first[:id]
+          return nil unless id.is_a?(AST::Node) && id.of_type?("Identifier")
+
+          id[:name] if SERVER_DATA_HOOK_NAMES.include?(id[:name])
         end
       end
 
@@ -206,32 +271,300 @@ module JsxRosetta
         case stmt.type
         when "VariableDeclaration"
           stmt[:declarations].each { |d| record_module_binding(stmt, d, component_names, bindings) }
-        when "ExportNamedDeclaration"
+        when "FunctionDeclaration"
+          record_module_function_binding(stmt, component_names, bindings)
+        when "ExportNamedDeclaration", "ExportDefaultDeclaration"
           decl = stmt[:declaration]
           walk_module_binding(decl, component_names, bindings) if decl.is_a?(AST::Node)
         end
       end
 
+      # Top-level `function onError(){}` helpers — non-component, non-hook
+      # functions declared in the same file as the component. Without
+      # capture, a `<Button onClick={onError}>` use site translates to
+      # `on_click: on_error` which NameErrors at render time because
+      # nothing binds `on_error`. Recording the name here threads it into
+      # the translator's bailout set so the reference becomes `on_click: nil`
+      # plus a visible TODO.
+      def record_module_function_binding(stmt, component_names, bindings)
+        name = stmt[:id]&.[](:name)
+        return unless name
+        return if component_names.include?(name)
+
+        bindings << LocalBinding.new(name: name, source: source_of(stmt).strip)
+      end
+
       def record_module_binding(stmt, declarator, component_names, bindings)
         init = declarator[:init]
         return unless init.is_a?(AST::Node)
 
-        # 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))
-
         name = declarator[:id]&.[](:name)
         return unless name
 
+        # Component declarators (`const Foo = () => ...` and the
+        # HOC-wrapped `const Foo = memo(() => ...)` form) are handled by
+        # the component pipeline; skip them here so the source doesn't
+        # surface twice (once as a TODO, once as the class).
+        return if component_names.include?(name)
+
+        # shadcn-style `const fooVariants = cva(base, { variants, ... })` gets
+        # recognized at lowering and stored as a CvaBinding — the backend
+        # turns it into real Ruby constants and the use-site call collapses
+        # to a string interpolation. Falls through to the generic LocalBinding
+        # path when the cva shape doesn't match exactly.
+        if (cva = parse_cva_binding(init, name))
+          bindings << cva
+          return
+        end
+
+        # Literal-shaped `const FOO = "x"` / `const COLUMNS = [...]` /
+        # `const TAGS = {...}` lowers to a real Ruby constant emitted above
+        # the class. Anything richer (call expressions, identifier refs,
+        # JSX) bails to the LocalBinding TODO-block fallback below.
+        if (constant = parse_module_constant(init, name))
+          bindings << constant
+          return
+        end
+
         bindings << LocalBinding.new(name: name, source: source_of(stmt).strip)
       end
 
-      def attach_module_bindings(component, module_bindings)
-        return component if module_bindings.empty?
+      # Returns an IR::ModuleConstant when `init` reduces to a Ruby-literal-
+      # friendly value, or nil otherwise. Anything that depends on runtime
+      # state (call expressions, identifier references, function expressions,
+      # JSX) bails out so the existing LocalBinding TODO path still surfaces
+      # the original JS source.
+      def parse_module_constant(init, name)
+        value = literal_value(init)
+        return nil if value == :__not_literal__
+
+        ModuleConstant.new(
+          name: name,
+          constant_name: AST::Inflector.underscore(name).upcase,
+          value: value
+        )
+      end
+
+      # Returns the Ruby-literal-friendly value for `node`, or the sentinel
+      # `:__not_literal__` when the node isn't translatable. Sentinel rather
+      # than `nil` so a JS `null` (which legitimately maps to Ruby `nil`)
+      # is distinguishable from "couldn't parse this."
+      def literal_value(node)
+        return :__not_literal__ unless node.is_a?(AST::Node)
+
+        case node.type
+        when "StringLiteral", "NumericLiteral", "BooleanLiteral" then node[:value]
+        when "NullLiteral" then nil
+        when "TemplateLiteral" then literal_value_from_template(node)
+        when "ArrayExpression" then literal_value_from_array(node)
+        when "ObjectExpression" then literal_value_from_object(node)
+        when "UnaryExpression" then literal_value_from_unary(node)
+        when "TSAsExpression", "TSSatisfiesExpression", "TSTypeAssertion"
+          literal_value(node[:expression])
+        else :__not_literal__
+        end
+      end
+
+      def literal_value_from_template(node)
+        return :__not_literal__ unless (node[:expressions] || []).empty?
+
+        # `quasi[:value]` is a plain Hash with String keys ("cooked" / "raw"),
+        # not an AST::Node — Babel's AST wraps Hashes only when they carry a
+        # "type" field. Use the String key directly.
+        (node[:quasis] || []).map { |q| q[:value]["cooked"] }.join
+      end
+
+      def literal_value_from_array(node)
+        elements = node[:elements] || []
+        result = []
+        elements.each do |elem|
+          # Holes in array literals (`[1, , 3]`) come through as nil; map to
+          # Ruby `nil` to preserve length. Spread elements bail — we can't
+          # statically expand the spread target.
+          if elem.nil?
+            result << nil
+            next
+          end
+          return :__not_literal__ if elem.is_a?(AST::Node) && elem.type == "SpreadElement"
+
+          value = literal_value(elem)
+          return :__not_literal__ if value == :__not_literal__
+
+          result << value
+        end
+        result
+      end
+
+      def literal_value_from_object(node)
+        properties = node[:properties] || []
+        result = {}
+        properties.each do |prop|
+          return :__not_literal__ unless prop.is_a?(AST::Node) && prop.type == "ObjectProperty"
+          return :__not_literal__ if prop[:computed]
+          return :__not_literal__ if prop[:shorthand] && prop[:value].is_a?(AST::Node) &&
+                                     prop[:value].type == "Identifier"
 
-        component.with(module_bindings: module_bindings)
+          key = property_key(prop)
+          return :__not_literal__ unless key.is_a?(String)
+
+          value = literal_value(prop[:value])
+          return :__not_literal__ if value == :__not_literal__
+
+          result[key] = value
+        end
+        result
+      end
+
+      def literal_value_from_unary(node)
+        return :__not_literal__ unless %w[- +].include?(node[:operator])
+
+        inner = literal_value(node[:argument])
+        return :__not_literal__ unless inner.is_a?(Numeric)
+
+        node[:operator] == "-" ? -inner : inner
+      end
+
+      # Returns a CvaBinding when `init` is a `cva(base, options)` call we
+      # know how to parse, or nil to fall through to LocalBinding.
+      def parse_cva_binding(init, name)
+        return nil unless cva_call?(init)
+
+        args = init[:arguments] || []
+        base_class = extract_cva_string(args[0])
+        return nil unless base_class
+
+        options = args[1]
+        return nil unless options.is_a?(AST::Node) && options.type == "ObjectExpression"
+
+        CvaBinding.new(
+          name: name,
+          base_class: base_class,
+          variants: extract_cva_variants(options),
+          default_variants: extract_cva_default_variants(options),
+          compound_source: extract_cva_compound_source(options)
+        )
+      end
+
+      def cva_call?(node)
+        return false unless node.is_a?(AST::Node) && node.type == "CallExpression"
+
+        callee = node[:callee]
+        callee.is_a?(AST::Node) && callee.type == "Identifier" && callee[:name] == "cva"
+      end
+
+      def extract_cva_string(node)
+        return nil unless node.is_a?(AST::Node)
+
+        case node.type
+        when "StringLiteral"
+          node[:value]
+        when "TemplateLiteral"
+          # Only handle templates with no interpolations — they're effectively
+          # a string literal (shadcn's cva bases sometimes use a template for
+          # multi-line readability).
+          return nil unless (node[:expressions] || []).empty?
+
+          (node[:quasis] || []).map { |q| q[:value][:cooked] }.join
+        end
+      end
+
+      def extract_cva_variants(options_node)
+        prop = find_object_property(options_node, "variants")
+        return {} unless object_expression?(prop&.[](:value))
+
+        prop[:value][:properties].each_with_object({}) do |axis, hash|
+          axis_name = property_key(axis)
+          options = extract_cva_axis_options(axis[:value])
+          hash[axis_name] = options if axis_name && !options.empty?
+        end
+      end
+
+      def extract_cva_axis_options(axis_value_node)
+        return {} unless object_expression?(axis_value_node)
+
+        axis_value_node[:properties].each_with_object({}) do |opt, hash|
+          opt_name = property_key(opt)
+          opt_value = extract_cva_string(opt[:value])
+          hash[opt_name] = opt_value if opt_name && opt_value
+        end
+      end
+
+      def object_expression?(node)
+        node.is_a?(AST::Node) && node.type == "ObjectExpression"
+      end
+
+      def extract_cva_default_variants(options_node)
+        prop = find_object_property(options_node, "defaultVariants")
+        return {} unless prop && prop[:value].is_a?(AST::Node) && prop[:value].type == "ObjectExpression"
+
+        prop[:value][:properties].each_with_object({}) do |p, hash|
+          key = property_key(p)
+          val = extract_cva_string(p[:value])
+          hash[key] = val if key && val
+        end
+      end
+
+      def extract_cva_compound_source(options_node)
+        prop = find_object_property(options_node, "compoundVariants")
+        return nil unless prop
+
+        source_of(prop[:value]).strip
+      end
+
+      def find_object_property(obj_node, name)
+        (obj_node[:properties] || []).find { |p| property_key(p) == name }
+      end
+
+      def property_key(prop)
+        return nil unless prop.is_a?(AST::Node) && prop[:key].is_a?(AST::Node)
+
+        key = prop[:key]
+        case key.type
+        when "Identifier" then key[:name]
+        when "StringLiteral" then key[:value]
+        end
+      end
+
+      def attach_module_metadata(component, module_bindings, module_imports, server_data_source = nil)
+        component.with(
+          module_bindings: module_bindings,
+          module_imports: module_imports,
+          server_data_source: server_data_source
+        )
+      end
+
+      # Capture every top-level `import` declaration so the translator can
+      # recognize use-site references at expression-context. Without this,
+      # an import like `import styles from "./X.module.css"` lets every
+      # `styles.listContainer` use snake-case to a bare `styles` reference
+      # that NameErrors at render time.
+      def capture_module_imports(program)
+        imports = []
+        program.body.each do |stmt|
+          next unless stmt.is_a?(AST::Node) && stmt.type == "ImportDeclaration"
+
+          source = stmt[:source]&.[](:value).to_s
+          (stmt[:specifiers] || []).each do |spec|
+            name = spec[:local]&.[](:name)
+            next unless name
+
+            imports << ModuleImport.new(
+              name: name,
+              source: source,
+              kind: import_specifier_kind(spec),
+              imported_name: spec[:imported]&.[](:name)
+            )
+          end
+        end
+        imports
+      end
+
+      def import_specifier_kind(spec)
+        case spec.type
+        when "ImportDefaultSpecifier" then :default
+        when "ImportNamespaceSpecifier" then :namespace
+        else :named
+        end
       end
 
       private
@@ -317,10 +650,29 @@ module JsxRosetta
         when "FunctionDeclaration" then [[declaration[:id]&.[](:name), declaration]]
         when "VariableDeclaration" then extract_arrow_components(declaration)
         when "ClassDeclaration" then extract_class_component(declaration)
+        when "CallExpression" then extract_hoc_default_export(declaration)
         else []
         end
       end
 
+      # `export default memo(function X() {...})` — the declaration is a
+      # CallExpression whose argument is a named FunctionExpression. Peer
+      # through to the inner function and record the wrapper. Anonymous
+      # forms (`export default memo(function () {...})`) get skipped —
+      # `lower_component` rejects anonymous functions and the pre-unwrap
+      # behavior was the same.
+      def extract_hoc_default_export(call_expression)
+        unwrapped = unwrap_hoc(call_expression)
+        return [] unless unwrapped
+
+        inner = unwrapped[:function]
+        name = inner[:id]&.[](:name) if inner.respond_to?(:[])
+        return [] unless name
+
+        record_hoc_wrappers(name, unwrapped[:wrappers])
+        [[name, inner]]
+      end
+
       # Recognize a class component by the presence of a `render()` method.
       # We don't require `extends React.Component` because TypeScript codebases
       # often declare the parent via an `extends` of a typed alias. The render
@@ -447,20 +799,86 @@ module JsxRosetta
         variable_declaration[:declarations].filter_map do |declarator|
           init = declarator[:init]
           next nil unless init.is_a?(AST::Node)
-          next nil unless %w[ArrowFunctionExpression FunctionExpression].include?(init.type)
 
           name = declarator[:id]&.[](:name)
-          name ? [name, init] : nil
+          next nil unless name
+
+          if %w[ArrowFunctionExpression FunctionExpression].include?(init.type)
+            [name, init]
+          elsif (unwrapped = unwrap_hoc(init))
+            record_hoc_wrappers(name, unwrapped[:wrappers])
+            [name, unwrapped[:function]]
+          end
         end
       end
 
+      # Peer through a CallExpression initializer to find an inline
+      # function/arrow argument that's the real component definition.
+      # Recurses through nested wrappers so `memo(forwardRef(fn))` flattens
+      # to `["memo", "forwardRef"]` + the innermost `fn`. Returns
+      # `{ function: AST, wrappers: [String] }` or nil when no unwrap
+      # applies (the initializer is a CallExpression but doesn't match
+      # a known wrapper shape).
+      def unwrap_hoc(node)
+        wrappers = []
+        current = node
+        while current.is_a?(AST::Node) && current.type == "CallExpression"
+          callee_name = hoc_callee_name(current[:callee])
+          break unless callee_name
+
+          inner = current[:arguments].first
+          break unless inner.is_a?(AST::Node)
+
+          wrappers << callee_name
+          if %w[ArrowFunctionExpression FunctionExpression].include?(inner.type)
+            return { function: inner, wrappers: wrappers }
+          end
+
+          current = inner
+        end
+        nil
+      end
+
+      # Extract the wrapper name from a CallExpression callee. Accepts the
+      # bare form (`memo(...)`) and the React-namespace form (`React.memo(...)`).
+      # Returns the local name ("memo") in both cases so the wrapper TODO
+      # text doesn't have to handle both spellings.
+      def hoc_callee_name(callee)
+        return nil unless callee.is_a?(AST::Node)
+
+        name =
+          case callee.type
+          when "Identifier"
+            callee[:name]
+          when "MemberExpression"
+            object = callee[:object]
+            property = callee[:property]
+            return nil unless object.is_a?(AST::Node) && object.of_type?("Identifier")
+            return nil unless object[:name] == "React"
+            return nil unless property.is_a?(AST::Node) && property.of_type?("Identifier")
+
+            property[:name]
+          end
+        name if name && HOC_WRAPPER_NAMES.include?(name)
+      end
+
+      def record_hoc_wrappers(name, wrappers)
+        @component_hoc_wrappers ||= {}
+        @component_hoc_wrappers[name] = wrappers
+      end
+
       def lower_component(name, function)
         if name.nil? || name.empty?
           raise lowering_error("anonymous component functions are not supported", node: function)
         end
 
         reset_per_component_state!
-        props, rest_prop_name = lower_params(function[:params])
+        hoc_wrappers = (@component_hoc_wrappers || {})[name] || []
+        # forwardRef's inner function is `(props, ref) => …` — the second
+        # param has no Rails analog, so drop it before lower_params sees
+        # it (otherwise it'd land as a `ref:` ivar with no use site).
+        params_for_lowering = drop_forward_ref_param(function[:params], hoc_wrappers)
+        props, rest_prop_name = lower_params(params_for_lowering)
         @prop_names = props.map(&:name)
         absorb_class_metadata(name, function, props) if function.of_type?("ClassMethod", "MethodDefinition")
 
@@ -479,13 +897,22 @@ module JsxRosetta
           local_bindings: @local_bindings,
           local_binding_names: (@local_binding_names + unconsumed_arrow_names).uniq,
           module_bindings: [],
+          module_imports: [],
           stimulus_methods: @stimulus_methods,
           react_hooks: @react_hooks,
           render_methods: @render_methods,
-          mode: mode
+          mode: mode,
+          server_data_source: nil,
+          hoc_wrappers: hoc_wrappers
         )
       end
 
+      def drop_forward_ref_param(params, wrappers)
+        return params unless wrappers.include?("forwardRef") && params.size > 1
+
+        params[0..-2]
+      end
+
       # A "data factory" function — common for AG-Grid / antd column
       # descriptor modules — is a function whose body just returns an array
       # of object literals (`export const createColumns = (...) => [{...},
@@ -1116,14 +1543,82 @@ module JsxRosetta
           # 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 next_js_layout_yield?(tag, attributes)
+          # `<Component {...pageProps} />` — the canonical Next.js _app
+          # content slot. Lowering to LayoutYield lets the Phlex backend
+          # emit `yield` (Rails layout convention) instead of trying to
+          # render the prop verbatim.
+          LayoutYield.new
         elsif html_element?(tag)
           Element.new(tag: tag, attributes: attributes, children: children)
+        elsif (radix = radix_primitive_for(tag))
+          # `<SeparatorPrimitive.Root .../>` (imported from radix-ui) lowers
+          # to a plain `<div role="separator">` so the consumer doesn't have
+          # to define a Components::SeparatorPrimitive::Root shim.
+          Element.new(
+            tag: radix[:tag],
+            attributes: merge_radix_attrs(radix[:attrs], attributes),
+            children: children
+          )
         else
           ComponentInvocation.new(name: tag, props: attributes, children: children)
         end
       end
 
+      # Returns the Radix registry entry for `<LocalName.Member />` when:
+      #   - the tag is a two-segment member chain
+      #   - the root segment was imported from a Radix-shaped package
+      #   - the (LocalName, Member) pair is in the registry
+      # Otherwise nil — the caller falls through to a ComponentInvocation.
+      def radix_primitive_for(tag)
+        segments = tag.split(".")
+        return nil if segments.length != 2
+
+        local, member = segments
+        return nil unless imported_from_radix?(local)
+
+        RadixRegistry.lookup(local, member)
+      end
+
+      def imported_from_radix?(local_name)
+        @module_imports.any? do |imp|
+          imp.name == local_name && RADIX_SOURCE_PATTERN.match?(imp.source)
+        end
+      end
+
+      # Combine the registry's fixed attrs (role, type, etc.) with the
+      # consumer's own JSX attributes. Consumer attrs win on collision — the
+      # JSX is the source of truth; the registry just supplies safe defaults.
+      # Collision keys normalize away case + hyphens/underscores so future
+      # registry entries like `data-state` don't slip past a consumer's
+      # `dataState`.
+      def merge_radix_attrs(fixed_attrs, jsx_attrs)
+        user_keys = jsx_attrs.filter_map do |a|
+          a.respond_to?(:name) ? normalize_attr_key(a.name) : nil
+        end.to_set
+        injected = fixed_attrs.filter_map do |name, value|
+          attr_name = name.to_s
+          next if user_keys.include?(normalize_attr_key(attr_name))
+
+          Attribute.new(name: attr_name, value: value.to_s)
+        end
+        injected + jsx_attrs
+      end
+
+      def normalize_attr_key(name)
+        name.to_s.downcase.tr("-_", "")
+      end
+
       def lower_polymorphic_tag_use(poly, attributes, children)
+        if (chosen = drop_slot_branch(poly))
+          # The shadcn `<Comp asChild>` pattern routes through Radix's
+          # Slot.Root, which has no Ruby class on the Phlex side. Drop the
+          # Slot branch and render the underlying HTML/component branch
+          # directly. Pass `--keep-slot` to preserve the conditional if
+          # the consumer is shimming Slot::Root themselves.
+          return build_polymorphic_branch(chosen, attributes, children)
+        end
+
         Conditional.new(
           test: Interpolation.new(expression: source_of(poly[:test])),
           consequent: build_polymorphic_branch(poly[:true_branch], attributes, children),
@@ -1140,6 +1635,41 @@ module JsxRosetta
         end
       end
 
+      # Returns the non-Slot branch when exactly one of the polymorphic
+      # branches resolves to a Radix Slot reference (`Slot` or `Slot.Root`
+      # rooted at a `radix-ui` import). Returns nil otherwise — including
+      # when `--keep-slot` is in effect — so the caller emits the full
+      # conditional unchanged.
+      def drop_slot_branch(poly)
+        return nil if @keep_slot
+
+        t = poly[:true_branch]
+        f = poly[:false_branch]
+        t_is_slot = radix_slot_branch?(t)
+        f_is_slot = radix_slot_branch?(f)
+        return f if t_is_slot && !f_is_slot
+        return t if f_is_slot && !t_is_slot
+
+        nil
+      end
+
+      # True iff `branch` references a Slot import from a Radix-shaped
+      # package. The local binding is one of {`Slot`, `SlotPrimitive`} —
+      # both correspond to the canonical "import from radix-ui / @radix-ui/
+      # react-slot" pattern. Anything else (e.g. a user-defined
+      # `SlotMachine` from a random package whose path happens to contain
+      # "radix") falls through and renders the conditional unchanged.
+      def radix_slot_branch?(branch)
+        return false unless branch[:kind] == :component
+
+        root = branch[:tag].split(".").first
+        return false unless root && SLOT_LOCAL_NAME_PATTERN.match?(root)
+
+        @module_imports.any? do |imp|
+          imp.name == root && RADIX_SOURCE_PATTERN.match?(imp.source)
+        end
+      end
+
       def lower_jsx_fragment(fragment)
         Fragment.new(children: lower_children(fragment.jsx_children))
       end
@@ -1489,10 +2019,116 @@ module JsxRosetta
         if value.is_a?(AST::JSXExpressionContainer)
           decomposed = try_lower_class_helper(value.expression)
           return decomposed if decomposed
+
+          cva_call = try_lower_cva_call_site(value.expression)
+          return cva_call if cva_call
         end
         StyleBinding.new(expression: style_binding_expression(value))
       end
 
+      # Recognize the cva call shape — `cn(<cvaName>({ axes }), <classArg>)`
+      # or the bare `<cvaName>({ axes })` direct form — against a CvaBinding
+      # captured during module-level lowering. Returns an IR::CvaCallSite,
+      # or nil so the caller falls through to the generic StyleBinding.
+      # AST-driven instead of regexing over verbatim source, which lets us
+      # handle reversed-arg `cn(<classArg>, <cvaName>(...))`, the no-cn
+      # direct form, and literal-pinned axes naturally.
+      def try_lower_cva_call_site(expression)
+        return nil unless expression.respond_to?(:type)
+        return nil unless expression.type == "CallExpression"
+
+        callee = expression.child(:callee)
+        return nil unless callee
+
+        if callee.of_type?("Identifier") && %w[cn clsx classnames].include?(callee[:name])
+          build_cva_call_site_from_class_helper(expression[:arguments] || [])
+        else
+          build_cva_call_site_from_direct(expression)
+        end
+      end
+
+      # `cn(<cvaCall>, <classArg>)` or `cn(<classArg>, <cvaCall>)` — accept
+      # the first argument that resolves to a known cva call; the remaining
+      # argument (if any) becomes the optional `class_arg`. Anything more
+      # complex (3+ args, nested cn, multiple cva calls) bails to nil.
+      def build_cva_call_site_from_class_helper(args)
+        return nil unless args.length.between?(1, 2)
+
+        cva_arg_index = args.find_index { |a| cva_call_against_known_binding?(a) }
+        return nil unless cva_arg_index
+
+        cva_arg = args[cva_arg_index]
+        class_arg = args.length == 2 ? args[1 - cva_arg_index] : nil
+        build_cva_call_site_node(cva_arg, class_arg)
+      end
+
+      # Bare `<cvaName>({ axes })` — same shape with no class_arg.
+      def build_cva_call_site_from_direct(expression)
+        return nil unless cva_call_against_known_binding?(expression)
+
+        build_cva_call_site_node(expression, nil)
+      end
+
+      def build_cva_call_site_node(cva_call, class_arg_node)
+        callee_name = cva_call[:callee][:name]
+        options = cva_call[:arguments]&.first
+        return nil unless options && options.type == "ObjectExpression"
+
+        axes = options[:properties].filter_map { |prop| build_cva_axis_pair(prop) }
+        class_arg = class_arg_node && Interpolation.new(expression: source_of(class_arg_node))
+        CvaCallSite.new(binding_name: callee_name, axes: axes, class_arg: class_arg)
+      end
+
+      # Pull one axis-value pair off the cva options object. Shorthand
+      # (`{ variant }`) and explicit (`{ variant: someExpr }`) both work;
+      # spread (`{ ...rest }`) and computed keys bail to nil so the call
+      # site falls through to the generic translator with a TODO.
+      def build_cva_axis_pair(prop)
+        return nil unless prop.type == "ObjectProperty"
+
+        axis = property_key_name(prop)
+        return nil unless axis
+
+        value_node = prop[:value]
+        kind, source = classify_cva_axis_value(value_node)
+        CvaAxisPair.new(axis: axis, kind: kind, source: source)
+      end
+
+      def property_key_name(prop)
+        case prop[:key].type
+        when "Identifier" then prop[:key][:name]
+        when "StringLiteral" then prop[:key][:value]
+        end
+      end
+
+      def classify_cva_axis_value(node)
+        case node.type
+        when "StringLiteral" then [:literal_string, node[:value]]
+        when "NumericLiteral", "BooleanLiteral" then [:literal_other, source_of(node)]
+        when "NullLiteral" then [:literal_nil, nil]
+        when "Identifier"
+          # Shorthand `{ variant }` and explicit `{ variant: ident }` both
+          # land here; the source is the identifier name itself.
+          node[:name] == "undefined" ? [:literal_nil, nil] : [:prop_ref, node[:name]]
+        else
+          # Member chains, calls, etc. — pass the source through as a
+          # raw expression. The backend re-translates it through
+          # ExpressionTranslator like any other prop reference.
+          [:prop_ref, source_of(node)]
+        end
+      end
+
+      def cva_call_against_known_binding?(node)
+        return false unless node.respond_to?(:type)
+        return false unless node.type == "CallExpression"
+
+        callee = node.child(:callee)
+        return false unless callee&.of_type?("Identifier")
+
+        binding_name = callee[:name]
+        @module_bindings.any? { |b| b.is_a?(CvaBinding) && b.name == binding_name }
+      end
+
       def try_lower_class_helper(expression)
         return nil unless AST::Node.matches?(expression, "CallExpression")
 
@@ -1573,9 +2209,18 @@ module JsxRosetta
       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])
+        body_node = arrow_node[:body]
+        body_source = source_of(body_node)
+        # Preserve nil entries for non-Identifier params (ObjectPattern,
+        # ArrayPattern, RestElement) so emit-time bails to TODO rather
+        # than pasting a body that references undefined locals.
+        params = Array(arrow_node[:params]).map { |p| p.type == "Identifier" ? p[:name] : nil }
         @stimulus_methods << StimulusMethod.new(
-          name: method_name, body_source: body_source, original_name: base
+          name: method_name,
+          body_source: body_source,
+          original_name: base,
+          params: params,
+          body_is_block: body_node.type == "BlockStatement"
         )
         @local_arrows.delete(name_hint) if name_hint
         StimulusBinding.new(event: event, method_name: method_name)
@@ -1589,7 +2234,11 @@ module JsxRosetta
         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
+          name: method_name,
+          body_source: body_source,
+          original_name: identifier_name,
+          params: [],
+          body_is_block: false
         )
         StimulusBinding.new(event: event, method_name: method_name)
       end
@@ -1620,18 +2269,39 @@ module JsxRosetta
       # 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.
+      # Lambda, JSXElement / JSXFragment → the same Element / Fragment /
+      # ComponentInvocation that JSX children lower to. 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)
+        when "JSXElement", "JSXFragment" then lower_jsx_value(expression)
         else
           Interpolation.new(expression: source_of(expression))
         end
       end
 
+      # JSX appearing in a non-child position — typically as an attribute
+      # value (`icon={<Foo/>}`, `fallback={<Loading/>}`). Lowered through
+      # the same `lower_jsx` pipeline as children, so the resulting IR
+      # node (Element / ComponentInvocation / Fragment) carries all the
+      # structure the backend can use to emit a real Phlex render call
+      # in place of the old "[untranslated: …]" drop. Single-child
+      # Fragments (`<><Foo/></>`, often emitted by React idioms or as a
+      # workaround for "one node required") collapse to the inner child
+      # so the kwarg value isn't an awkwardly-wrapped Fragment.
+      def lower_jsx_value(expression)
+        lowered = lower_jsx(expression)
+        if lowered.is_a?(Fragment) && lowered.children.length == 1
+          lowered.children.first
+        else
+          lowered
+        end
+      end
+
       def lower_object_literal(object_expression)
         properties = []
         object_expression[:properties].each do |prop|
@@ -1673,10 +2343,16 @@ module JsxRosetta
           return Interpolation.new(expression: source_of(arrow))
         end
 
+        param_names = params.map { |p| p[:name] }
         body = lower_lambda_body(arrow[:body])
-        return Interpolation.new(expression: source_of(arrow)) unless body
+        # JSX-bearing body → render lambda (translated to a Phlex render
+        # method). Non-JSX body → opaque event handler (the body becomes
+        # a verbatim TODO inside a stub method on the class). Without
+        # this fork, every `onClick={() => doX()}` on a PascalCase tag
+        # used to bail to Interpolation and drop with a TODO.
+        return Lambda.new(params: param_names, body: body) if body
 
-        Lambda.new(params: params.map { |p| p[:name] }, body: body)
+        EventHandler.new(params: param_names, body_source: source_of(arrow[:body]))
       end
 
       def lower_lambda_body(body)
@@ -1707,6 +2383,19 @@ module JsxRosetta
         first == first.downcase
       end
 
+      # `<Component {...pageProps} />` — Next.js _app content slot. Tag must
+      # be exactly "Component" and the props must include a spread of
+      # "pageProps". Strict shape match keeps this from false-firing on
+      # ordinary code that happens to render a prop-named `<Component>` —
+      # the `{...pageProps}` spread is the unambiguous Next.js signal.
+      def next_js_layout_yield?(tag, attributes)
+        return false unless tag == "Component"
+
+        attributes.any? do |attr|
+          attr.is_a?(SpreadAttribute) && attr.expression.strip == "pageProps"
+        end
+      end
+
       def source_of(node)
         @source[node.start_pos...node.end_pos]
       end