jsx_rosetta 0.4.0 → 0.6.0

data/lib/jsx_rosetta/ir/module_shape_classifier.rb

@@ -78,9 +78,28 @@ module JsxRosetta
         name.start_with?("use") && name.length > 3 && name[3] == name[3].upcase
       end
 
+      # Only flag class-component shape when the class has no usable render
+      # method. Classes WITH `render()` lower via the
+      # ClassDeclaration → ViewComponent path added in v0.5.0, so the
+      # classifier should leave them alone and let the regular component
+      # finder pick them up.
       def class_component?(stmt)
         decl = stmt.of_type?(*EXPORT_TYPES) ? stmt[:declaration] : stmt
-        AST::Node.matches?(decl, "ClassDeclaration")
+        return false unless AST::Node.matches?(decl, "ClassDeclaration")
+
+        !class_has_render_method?(decl)
+      end
+
+      def class_has_render_method?(class_decl)
+        body = class_decl.child(:body)
+        return false unless body
+
+        body[:body].any? do |member|
+          next false unless AST::Node.matches?(member, "ClassMethod", "MethodDefinition")
+
+          key = member.child(:key)
+          AST::Node.matches?(key, "Identifier") && key[:name] == "render" && member[:kind] != "constructor"
+        end
       end
 
       # Recognize `export const X = React.memo(...)` (export wrapper) or a

data/lib/jsx_rosetta/ir/radix_registry.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module JsxRosetta
+  module IR
+    # When a shadcn TSX wraps a Radix primitive like
+    # `<SeparatorPrimitive.Root orientation="horizontal" />`, the translator
+    # has historically lowered it to a `ComponentInvocation` whose name is
+    # the member chain (`"SeparatorPrimitive.Root"`) — which emits as
+    # `render SeparatorPrimitive::Root.new(...)`, an undefined-constant
+    # NameError at render time.
+    #
+    # The shapes underneath are stable enough across Radix that we can map
+    # the common (LocalImportName, MemberName) pairs to plain HTML elements
+    # plus any always-applied attributes. The mapping is keyed on the LOCAL
+    # binding name shadcn uses by convention (e.g. `SeparatorPrimitive`),
+    # which matches the import-aliasing pattern in every shadcn fork I've
+    # surveyed. Unknown pairs fall through to the existing ComponentInvocation
+    # / TODO behavior so consumers can hand-shim primitives we don't cover.
+    #
+    # Source specifiers that count as "Radix" — both the `radix-ui` umbrella
+    # package and the older `@radix-ui/react-*` per-primitive packages.
+    RADIX_SOURCE_PATTERN = %r{\A(?:radix-ui|@radix-ui/react-[\w-]+)\z}
+
+    # Local binding names that resolve to Radix's `Slot` primitive.
+    # Matches `Slot` (shadcn-v4 umbrella) and `SlotPrimitive` (older
+    # convention). Anything looser would silently drop user-defined
+    # components whose names happen to start with "Slot".
+    SLOT_LOCAL_NAME_PATTERN = /\ASlot(?:Primitive)?\z/
+
+    module RadixRegistry
+      # Each entry maps [PrimitiveBaseName, MemberName] →
+      #   { tag: <html-tag>, attrs: { <fixed kwarg name> => <value> } }
+      # The `attrs` are merged into the element's lowered attributes (the
+      # consumer's own kwargs win on conflict — see `merge_radix_attrs`).
+      #
+      # `PrimitiveBaseName` is the *canonical* Radix primitive name
+      # (e.g. `Separator`); the lookup strips an optional `Primitive` suffix
+      # from the consumer's local binding before keying in, so both shadcn-v3
+      # (`import { Separator as SeparatorPrimitive } from "radix-ui"`) and
+      # shadcn-v4 (`import { Separator } from "radix-ui"`) umbrella idioms
+      # resolve. Namespace imports (`import * as SeparatorPrimitive from
+      # "@radix-ui/react-separator"`) also strip the suffix.
+      MAP = {
+        # Separator / Label / Avatar / Switch primitives — the shapes we hit
+        # most often in the bulk shadcn translation pass.
+        %w[Separator Root] => { tag: "div", attrs: { role: "separator" } },
+        %w[Label Root] => { tag: "label", attrs: {} },
+        %w[Avatar Root] => { tag: "span", attrs: {} },
+        %w[Avatar Image] => { tag: "img", attrs: {} },
+        %w[Avatar Fallback] => { tag: "span", attrs: {} },
+        %w[Switch Root] => { tag: "button", attrs: { type: "button", role: "switch" } },
+        %w[Switch Thumb] => { tag: "span", attrs: {} },
+        %w[Progress Root] => { tag: "div", attrs: { role: "progressbar" } },
+        %w[Progress Indicator] => { tag: "div", attrs: {} },
+        # Aspect-ratio + scroll-area roots are presentational containers.
+        %w[AspectRatio Root] => { tag: "div", attrs: {} },
+        %w[ScrollArea Root] => { tag: "div", attrs: {} },
+        %w[ScrollArea Viewport] => { tag: "div", attrs: {} },
+        # Tabs primitives — `data-orientation` comes from the JSX attrs;
+        # role=tablist on List + role=tab on Trigger + role=tabpanel on Content.
+        %w[Tabs Root] => { tag: "div", attrs: {} },
+        %w[Tabs List] => { tag: "div", attrs: { role: "tablist" } },
+        %w[Tabs Trigger] => { tag: "button", attrs: { type: "button", role: "tab" } },
+        %w[Tabs Content] => { tag: "div", attrs: { role: "tabpanel" } },
+        # Toggle / ToggleGroup — pressable buttons.
+        %w[Toggle Root] => { tag: "button", attrs: { type: "button" } },
+        %w[ToggleGroup Root] => { tag: "div", attrs: { role: "group" } },
+        %w[ToggleGroup Item] => { tag: "button", attrs: { type: "button" } },
+        # Collapsible — presentational containers; the open/closed state is
+        # data-state driven by the consumer (Stimulus or otherwise).
+        %w[Collapsible Root] => { tag: "div", attrs: {} },
+        %w[Collapsible Trigger] => { tag: "button", attrs: { type: "button" } },
+        %w[Collapsible Content] => { tag: "div", attrs: {} }
+      }.freeze
+
+      # Strip an optional `Primitive` suffix from the local binding so the
+      # registry's canonical names match both umbrella imports (`Separator`)
+      # and the older convention (`SeparatorPrimitive`).
+      def self.lookup(local_name, member)
+        MAP[[local_name, member]] || MAP[[local_name.sub(/Primitive\z/, ""), member]]
+      end
+    end
+  end
+end

data/lib/jsx_rosetta/ir/types.rb

@@ -33,12 +33,19 @@ module JsxRosetta
     #                  inline arrows / const-bound arrows used in onX={...}.
     #                  When non-empty, backends should emit a sibling
     #                  Stimulus controller file alongside the .rb/.erb pair.
-    # react_hooks    : [ReactHookCall] — calls to React hooks (useState,
-    #                  useEffect, useRef, useContext, useMemo, useCallback,
-    #                  useReducer, useImperativeHandle, useLayoutEffect).
-    #                  Surfaced as a distinct TODO block so the human
-    #                  reviewer knows to translate behavior to Stimulus
-    #                  and state to server-side rendering.
+    # react_hooks    : [ReactHookCall] — every recognized hook invocation
+    #                  in the component body, regardless of library.
+    #                  Includes React's built-in hooks (useState, useEffect,
+    #                  useRef, useContext, useMemo, useCallback, useReducer,
+    #                  useImperativeHandle, useLayoutEffect), Apollo hooks
+    #                  (useQuery, useMutation, useLazyQuery, useSubscription,
+    #                  useApolloClient), and Next.js navigation hooks
+    #                  (useRouter, usePathname, useSearchParams, useParams,
+    #                  useSelectedLayoutSegment(s)). Each call carries a
+    #                  `library` tag so backends can group them and emit a
+    #                  library-specific TODO pointing at the right Rails
+    #                  analog (Stimulus/server-render for React; controller
+    #                  fetch for Apollo; request.path/params for Next.js).
     # module_bindings : [LocalBinding] — top-level `const`/`let` declarations
     #                  outside the component function that aren't themselves
     #                  components. Captured so backends can either translate
@@ -47,10 +54,90 @@ module JsxRosetta
     #                  Without this capture, references to module-level
     #                  constants from inside the JSX silently drop and
     #                  produce unbacked snake_case references at render time.
+    # module_imports : [ModuleImport] — top-level `import` declarations.
+    #                  Backends thread the imported names into the
+    #                  ExpressionTranslator so any expression-context
+    #                  reference to an import (e.g. `styles.listContainer`
+    #                  from `import styles from "./X.module.css"`, or
+    #                  `AlertStatusEnum.Pending` from a TS enum import)
+    #                  bails out to a TODO instead of snake-casing to a
+    #                  bare identifier that NameErrors at render time.
+    # render_methods : [RenderMethod] — local arrow bindings that return JSX
+    #                  and are invoked from the JSX body (`const renderHeader
+    #                  = () => <div/>; ... {renderHeader()}`). Backends emit
+    #                  each as a private method on the generated class and
+    #                  reference it from a LocalRenderCall at the use site.
+    # mode  : Symbol — `:view` for a normal Phlex/ViewComponent component
+    #         whose body is rendered as JSX (the default); `:data_factory`
+    #         for column-descriptor / option-list modules whose top-level
+    #         export is a function returning an array of object literals.
+    #         When `:data_factory`, the backend emits a snake_case method
+    #         that returns the translated data, instead of `view_template`.
+    #         JSX inside object properties still extracts to private
+    #         methods on the class via the IR::Lambda path.
+    # server_data_source : ServerDataSource | nil — capture of a
+    #                  Next.js `getServerSideProps` / `getStaticProps`
+    #                  export from the same source file as this component.
+    #                  Body preserved verbatim so the Phlex backend can
+    #                  emit it as a TODO comment block above the class
+    #                  (the matching Rails controller action is where the
+    #                  user ports the data-loading logic). Attached only
+    #                  to the first component when a file contains
+    #                  multiple — Next.js page files have exactly one
+    #                  default-export component, so collisions are rare.
+    # hoc_wrappers   : [String] — Higher-Order Component wrapper names
+    #                  that the lowering peeled off when finding this
+    #                  component (e.g. `memo`, `forwardRef`, `observer`,
+    #                  `connect`, `withRouter`). Recorded in
+    #                  outside-in order so a `memo(forwardRef(...))`
+    #                  emits as ["memo", "forwardRef"]. Backends surface
+    #                  these as a TODO comment block above the class
+    #                  explaining each wrapper's Rails analog (or
+    #                  lack of one). Empty for components without
+    #                  wrappers — the common case.
     Component = Data.define(:name, :props, :body, :rest_prop_name,
                             :local_bindings, :local_binding_names,
-                            :module_bindings,
-                            :stimulus_methods, :react_hooks) do
+                            :module_bindings, :module_imports,
+                            :stimulus_methods, :react_hooks,
+                            :render_methods, :mode, :server_data_source,
+                            :hoc_wrappers) do
+      include Node
+    end
+
+    # A Next.js server data-loading export (`getServerSideProps` /
+    # `getStaticProps`). Captured at lowering time so the Phlex backend can
+    # surface the body as a TODO comment block pointed at the matching
+    # Rails controller action. Body is preserved verbatim — no JS-to-Ruby
+    # translation is attempted per project rules.
+    #
+    # hook_name : String — "getServerSideProps" or "getStaticProps".
+    # source    : String — verbatim JS of the entire export statement.
+    ServerDataSource = Data.define(:hook_name, :source) do
+      include Node
+    end
+
+    # A top-level `import` declaration. Captured at lowering time so the
+    # ExpressionTranslator can recognize use-site references and bail out
+    # to a TODO instead of emitting a bare snake_case identifier that
+    # NameErrors at render time.
+    #
+    # name   : String — the local binding name (the side the source uses
+    #          to reference the imported value). For `import { foo as bar }`
+    #          this is "bar"; for `import * as styles` this is "styles";
+    #          for `import Default` this is "Default".
+    # source        : String — the module specifier verbatim
+    #                 (e.g. "./styles.module.css", "@apollo/client", "react").
+    #                 Lets backends apply per-source policy later (e.g. always
+    #                 strip `*.module.css` references).
+    # kind          : Symbol — :default | :named | :namespace.
+    # imported_name : String? — original exported name from the source module.
+    #                 For `import { ChevronRight as CR } from "lucide-react"`,
+    #                 `name` is `"CR"` and `imported_name` is `"ChevronRight"`.
+    #                 nil for default / namespace imports where there's no
+    #                 distinct exported name. Backends that look up vendored
+    #                 data by canonical name (icons) need the imported name;
+    #                 most callers want the local binding.
+    ModuleImport = Data.define(:name, :source, :kind, :imported_name) do
       include Node
     end
 
@@ -64,22 +151,116 @@ module JsxRosetta
       include Node
     end
 
-    # A React hook invocation detected in the component body (`useState`,
-    # `useEffect`, …). Surfaced separately from local_bindings so backends
-    # can emit a more specific TODO that points at the Stimulus / Hotwire
-    # / server-render alternative, instead of a generic "translate this JS".
+    # A module-level call to `cva()` from class-variance-authority. shadcn
+    # components ubiquitously use this builder to attach a base class string
+    # plus per-axis variant maps to a JSX component. The translator
+    # recognizes the pattern at lowering time so backends can emit real
+    # Ruby constants (`FOO_BASE_CLASS`, `FOO_VARIANT_CLASSES`) instead of
+    # leaving the call as a TODO comment, and so the use-site
+    # `cn(fooVariants({ variant }), className)` translates to a proper
+    # Ruby string interpolation.
+    #
+    # name             : String — the const binding name (e.g. "buttonVariants").
+    # base_class       : String — the first string argument to cva().
+    # variants         : Hash[String => Hash[String => String]]
+    #                    — { "variant" => { "default" => "...", "outline" => "..." } }
+    # default_variants : Hash[String => String] — per-axis default value name
+    #                    (matched against the variant axis keys).
+    # compound_source  : String | nil — INTENTIONALLY UNPARSED verbatim JS
+    #                    source of any `compoundVariants` entry. Field name
+    #                    reads structural; it isn't — backends only print
+    #                    it as a TODO comment alongside the constants since
+    #                    compoundVariants semantics aren't supported in the
+    #                    first cut.
+    CvaBinding = Data.define(:name, :base_class, :variants, :default_variants, :compound_source) do
+      include Node
+    end
+
+    # A literal-shaped module-level `const` declaration that lowers to a real
+    # Ruby constant. Distinct from `LocalBinding` (verbatim TODO block) and
+    # `CvaBinding` (structured cva variants). The detector accepts initializers
+    # whose value reduces to a Ruby-literal-friendly object — strings, numbers,
+    # booleans, null, arrays/hashes of the same. Non-literal initializers
+    # (call expressions, identifier references, JSX) still fall through to
+    # the `LocalBinding` path so their verbatim source surfaces in the
+    # module-bindings TODO block.
+    #
+    # name          : String — original JS identifier (e.g. "TAGS", "COLUMNS").
+    # constant_name : String — Ruby constant identifier emitted above the class
+    #                 (`AST::Inflector.underscore(name).upcase`). Stored on the
+    #                 IR so future collision-detection has somewhere to bind.
+    # value         : Object — Ruby-literal-friendly value (String, Integer,
+    #                 Float, true, false, nil, Array of the same, Hash with
+    #                 String keys mapping to the same). Backends call `.inspect`
+    #                 to emit the literal text.
+    ModuleConstant = Data.define(:name, :constant_name, :value) do
+      include Node
+    end
+
+    # A className attribute value that resolves to a known cva binding's
+    # call shape — `className={cn(buttonVariants({ variant, size }),
+    # className)}` or the no-cn direct form `className={buttonVariants({
+    # variant })}`. The translator recognizes the AST shape at lowering
+    # so the backend never has to regex over verbatim JS source; this
+    # naturally handles literal-pinned axes, reversed arg order, and
+    # the cn-vs-no-cn forms.
+    #
+    # binding_name : String — referenced cva binding's const name.
+    # axes         : [CvaAxisPair] — preserved in JSX source order.
+    # class_arg    : Interpolation | nil — the optional trailing className
+    #                arg from `cn(<cvaCall>, <classArg>)`. Nil for the
+    #                single-arg `cn(<cvaCall>)` and the no-cn direct
+    #                forms.
+    CvaCallSite = Data.define(:binding_name, :axes, :class_arg) do
+      include Node
+    end
+
+    # One axis-value pair inside a cva call's options object. The
+    # discriminator `kind` tells the backend how to render the value:
     #
-    # hook   : String — hook function name (`"useState"`, `"useEffect"`, …)
-    # source : String — verbatim JS of the entire statement.
-    ReactHookCall = Data.define(:hook, :source) do
+    #   :prop_ref — JS identifier referencing a prop (`{ variant }` or
+    #               `{ variant: someProp }`). Backends render as
+    #               `@snake_case` against the receiving Phlex component.
+    #   :literal_string  — `{ variant: "default" }` — the literal value
+    #                      is the variant-table key.
+    #   :literal_other   — `{ size: 42 }` / `{ active: true }` — Ruby
+    #                      literal passed through to the bracket key.
+    #   :literal_nil     — `{ variant: null }` or `undefined`.
+    CvaAxisPair = Data.define(:axis, :kind, :source) do
+      include Node
+    end
+
+    # A hook invocation detected in the component body. Covers React's
+    # built-in hooks plus framework hooks we recognize (Apollo's `useQuery`/
+    # `useMutation`/etc., Next.js's `useRouter`/`usePathname`/etc.).
+    # Surfaced separately from local_bindings so backends can emit a more
+    # specific TODO pointing at the Rails equivalent for each library,
+    # instead of a generic "translate this JS".
+    #
+    # hook      : String — hook function name (`"useState"`, `"useQuery"`, …)
+    # source    : String — verbatim JS of the entire statement.
+    # library   : Symbol — `:react`, `:apollo`, or `:next_js`. Backends
+    #             group hooks by library and emit one TODO block per group,
+    #             since each library maps to a different Rails analog.
+    # operation : String | nil — for Apollo hooks called with a bare-Identifier
+    #             first argument (`useQuery(GET_USERS_QUERY, …)`), the
+    #             captured operation name. nil when the first argument is
+    #             not a simple Identifier, or when the hook isn't Apollo.
+    #             Backends echo it in the TODO so the reviewer can match
+    #             the operation back to its GraphQL document and to the
+    #             Rails controller / model fetch it should become.
+    ReactHookCall = Data.define(:hook, :source, :library, :operation) do
       include Node
     end
 
     # A component prop, possibly with a default value.
     #
-    # name    : String
-    # default : Interpolation | nil
-    Prop = Data.define(:name, :default) do
+    # name       : String — the prop name on the parent (e.g. "data-testid").
+    # default    : Interpolation | nil
+    # alias_name : String | nil — the local binding name inside the body when
+    #              the destructure renames it (`"data-testid": dataTestId`).
+    #              Use sites of the alias resolve to the prop's ivar.
+    Prop = Data.define(:name, :default, :alias_name) do
       include Node
     end
 
@@ -279,7 +460,17 @@ module JsxRosetta
     #                 `name != original_name`, backends emit a collision
     #                 marker comment in the generated controller JS so the
     #                 reviewer can see the silent rename.
-    StimulusMethod = Data.define(:name, :body_source, :original_name) do
+    # params        : [String | nil] — original arrow/function parameter
+    #                 names (e.g. `["e"]`, `["event"]`, or `[]` for
+    #                 `() => …`). A `nil` entry signals a non-identifier
+    #                 param (destructured `({target}) =>`, rest `(...args) =>`)
+    #                 that the pasted body can't safely reference — backends
+    #                 bail to the TODO form when any entry is nil.
+    # body_is_block : Boolean — true when the arrow body was a BlockStatement
+    #                 (`(e) => { … }`), false for an expression-form body
+    #                 (`(e) => doX(e)`). Backends use this to decide whether
+    #                 to strip outer braces when pasting verbatim.
+    StimulusMethod = Data.define(:name, :body_source, :original_name, :params, :body_is_block) do
       include Node
     end
 
@@ -333,6 +524,25 @@ module JsxRosetta
       include Node
     end
 
+    # An arrow/function expression whose body isn't JSX — typically a
+    # JSX event handler on a PascalCase component (`onClick={() => doX()}`)
+    # or a non-JSX-returning callback prop. We can't translate arbitrary
+    # JS bodies to Ruby procedurally, so backends emit a stub method on
+    # the class with the verbatim JS body preserved as a TODO comment;
+    # the kwarg at the use site becomes `method(:method_name)` so the
+    # receiving component has a callable reference and the structural
+    # attachment is preserved end-to-end.
+    #
+    # params      : [String]
+    # body_source : String — verbatim JS of the arrow/function body
+    #               (the part after `=>` for arrows, or the full block
+    #               body for FunctionExpressions). Preserved as a
+    #               comment in the emitted method so the reviewer can
+    #               translate the behavior to Ruby.
+    EventHandler = Data.define(:params, :body_source) do
+      include Node
+    end
+
     # A render-prop child: `<Form.List>{(fields) => <div>{fields}</div>}</Form.List>`.
     # Backends emit this as a Ruby block on the render call, with the params
     # bound as block arguments. Distinct from Loop (which iterates an
@@ -343,5 +553,40 @@ module JsxRosetta
     RenderProp = Data.define(:params, :body) do
       include Node
     end
+
+    # The Next.js `_app.tsx` content slot — what JSX writes as
+    # `<Component {...pageProps} />`. Lowered to a distinguished node so
+    # the Phlex backend can emit `yield` (the Rails layout convention) in
+    # its place when the host file is a layout. Outside the layout
+    # rendering path the node still emits a yield, since the only way to
+    # produce one in our IR is to hit this exact source shape.
+    LayoutYield = Data.define do
+      include Node
+    end
+
+    # A locally-declared JSX-returning arrow that's invoked inside the
+    # render body: `const renderHeader = (count) => <h1>{count}</h1>;
+    # ... {renderHeader(headerCount)}`. Backends emit one private method
+    # per RenderMethod on the generated class and reference it via a
+    # LocalRenderCall at each use site.
+    #
+    # name   : String — snake_case method name on the class.
+    # params : [String] — arrow param names (camelCase preserved; backends
+    #          snake_case to form Ruby parameter names).
+    # body   : Node — the lowered IR node produced by the arrow's body.
+    RenderMethod = Data.define(:name, :params, :body) do
+      include Node
+    end
+
+    # A call to a locally-declared JSX-returning arrow at its use site.
+    # Pairs with a sibling RenderMethod on Component#render_methods.
+    #
+    # method_name : String — snake_case method name (matches RenderMethod#name).
+    # args        : [Interpolation] — argument expressions captured verbatim
+    #               (each Interpolation's expression is translated by the
+    #               backend's ExpressionTranslator at emission time).
+    LocalRenderCall = Data.define(:method_name, :args) do
+      include Node
+    end
   end
 end

data/lib/jsx_rosetta/ir.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
 require_relative "ir/types"
+require_relative "ir/radix_registry"
 require_relative "ir/lowering"
 
 module JsxRosetta
   module IR
-    def self.lower(ast_file, source:)
-      Lowering.lower(ast_file, source: source)
+    def self.lower(ast_file, source:, keep_slot: false)
+      Lowering.lower(ast_file, source: source, keep_slot: keep_slot)
     end
 
-    def self.lower_all(ast_file, source:)
-      Lowering.lower_all(ast_file, source: source)
+    def self.lower_all(ast_file, source:, keep_slot: false)
+      Lowering.lower_all(ast_file, source: source, keep_slot: keep_slot)
     end
   end
 end