jsx_rosetta 0.5.1 → 0.6.0

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

@@ -54,6 +54,14 @@ 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
@@ -67,11 +75,69 @@ module JsxRosetta
     #         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,
+                            :module_bindings, :module_imports,
                             :stimulus_methods, :react_hooks,
-                            :render_methods, :mode) do
+                            :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
 
@@ -85,6 +151,85 @@ module JsxRosetta
       include Node
     end
 
+    # 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:
+    #
+    #   :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.).
@@ -315,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
 
@@ -369,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
@@ -380,6 +554,16 @@ module JsxRosetta
       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

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