jsx_rosetta 0.4.0 → 0.5.1

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,24 @@ 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.
+    # 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.
     Component = Data.define(:name, :props, :body, :rest_prop_name,
                             :local_bindings, :local_binding_names,
                             :module_bindings,
-                            :stimulus_methods, :react_hooks) do
+                            :stimulus_methods, :react_hooks,
+                            :render_methods, :mode) do
       include Node
     end
 
@@ -64,22 +85,37 @@ 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 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"`, `"useEffect"`, …)
-    # source : String — verbatim JS of the entire statement.
-    ReactHookCall = Data.define(:hook, :source) do
+    # 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
 
@@ -343,5 +379,30 @@ module JsxRosetta
     RenderProp = Data.define(:params, :body) 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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JsxRosetta
-  VERSION = "0.4.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jsx_rosetta
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Sean McCleary
@@ -28,6 +28,7 @@ files:
 - LICENSE.txt
 - PLAN.md
 - README.md
+- ROADMAP.md
 - Rakefile
 - exe/jsx_rosetta
 - lib/jsx_rosetta.rb