jsx_rosetta 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57170a56efc4593faf87b9ee0e3ac055f862cb058b9185ed57bb9a12d47f9af4
-  data.tar.gz: bd52ab90f51bc6be003f33b7cc10cda266002fa55386bc079f199fbcc9f3130b
+  metadata.gz: d7b64119bbfe86413da7a779ada7e47cab06088411cb4667be2e79f8cfba3464
+  data.tar.gz: c1c1ac742642015a6ae7037538a34bf58b42b6e2fc232bedf48f8660b13a640d
 SHA512:
-  metadata.gz: 145db314ab8d61384fbebbf8969310664c358c6b561bf1dbf742e97feb71497e58703d300c9d6b1e75159dfee27ee7a0173662a631ab143597b0b6633fff67ff
-  data.tar.gz: 423f772ec2e33618ad6e6567d20caa9a4c375c8c05a5cb8425b681010ee89ecddda2fd9a6ddde0c2ab0777962c1d9e51cd3ec69f28236cc0e1390cdf25ccd90e
+  metadata.gz: 44a3dc2fc89b0dbb59ca5026f2cb27cc7f22e498cf125483725e1db07a39db1e45616baff9766be82bc52e443b33bf64180b90175660536c91f4bfc89e5b1926
+  data.tar.gz: a9c999e35af23ff2aba38a02ff57fc6229bf051dc339db859c341c9c1d607f88278542abd07a742ac84840616a305dcfe48b8bad32767ffbf5fc8d08c45ef7a9

data/CHANGELOG.md

@@ -1,5 +1,210 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.4.0] - 2026-05-11
+
+Closes nine translation gaps identified during a sample review of 12
+random Phlex outputs from the v0.3.0 stress run. Each gap was a silent
+drop, a render-time NameError, or a semantic mistranslation — the
+generated Ruby parsed but didn't behave like the source JSX.
+
+### Added
+
+- **Render-prop / function-as-children support.**
+  `<Form.List>{(fields) => <p>{fields}</p>}</Form.List>` now lowers to a
+  new `IR::RenderProp` and emits as a Ruby block on the parent `render`
+  call: `render Form::List.new do |fields| ... end`. Both Phlex and
+  ViewComponent backends emit the block; param names snake_case to match
+  Ruby convention. Previously dropped as `plain "[untranslated: ...]"`.
+- **Recursive object/array/lambda translation in attribute values.**
+  New IR types `ObjectLiteral`, `ArrayLiteral`, and `Lambda` mean that
+  `<Select options={[{ value: 10, label: "10 / page" }]} />` now emits
+  `options: [{ value: 10, label: "10 / page" }]` (Ruby array of hashes)
+  instead of `options: nil` with a TODO. Identifier keys snake_case
+  (`dataLabel` → `data_label`); nested literals recurse. Function-valued
+  properties — e.g. AG-Grid `render: (v) => <Tag>{v}</Tag>` — extract to
+  private methods on the class (`def render_render(v); span do; ...; end`)
+  and the property emits as `render: method(:render_render)` so the
+  body has access to the Phlex tag.* helpers.
+- **Module-level constants captured into `Component#module_bindings`.**
+  `const FOO = 400; function X() { return <p>{FOO}</p>; }` no longer
+  silently drops the FOO declaration — the backend emits a TODO comment
+  block above the class with the original source so the reviewer either
+  translates it to a Ruby constant or moves it to a Rails initializer.
+- **Destructure-pattern names recognized by the translator.**
+  `const [count, setCount] = useState(0); <p>{count}</p>` previously
+  emitted a bare `plain count` that NameErrored at render time. The
+  destructured names are now captured in `Component#local_binding_names`
+  and the `ExpressionTranslator` emits a `nil` placeholder for them so
+  the file at least loads. Covers `ArrayPattern`, `ObjectPattern`
+  (including aliased properties, `AssignmentPattern` defaults, and
+  `RestElement`), and hook-tuple destructures.
+- **Member-expression destructure resolution.** `const { Content } = Layout`
+  followed by `<Content/>` now resolves to `Layout::Content`, not a
+  free-floating `ContentComponent`. Multiple destructured names from the
+  same parent identifier all resolve correctly.
+
+### Fixed
+
+- **Component-prop callbacks no longer over-promote to Stimulus.**
+  `<Select onChange={onChange} />` (PascalCase tag) previously emitted
+  `data-action="change->foo#onChange"` — a Stimulus action descriptor
+  that never fires because the receiving component is a Ruby class, not
+  a DOM element. The lowering now checks `html_element?(tag)` before
+  promoting `on*` attrs and treats component-prop callbacks as regular
+  `IR::Attribute` kwargs. Stimulus promotion still applies to lowercase
+  HTML tags as before. Closes a regression introduced by the v0.3.0
+  prop-handler Stimulus promotion.
+- **Spread-of-nil no longer raises at render time.** `<div {...maybeNil}>`
+  used to emit `**@maybe_nil`, which raises when the prop is `nil`. Both
+  Phlex and ViewComponent backends now wrap as `**(@maybe_nil || {})`.
+  Cheap to emit unconditionally and idempotent.
+- **Duplicate handler names are no longer silently renamed.** Two
+  `onClick={handleReset}` handlers in one component previously produced
+  `handleReset` / `handleReset2` with no marker. `StimulusMethod` now
+  carries an `original_name` field, and the generated controller JS
+  emits a `// NOTE: method renamed from "handleReset"` comment above the
+  renamed method.
+- **ReactNode-typed props get a `raw` hint comment.** When an
+  interpolation translates to a bare `@ivar` reference (likely a prop),
+  the Phlex backend emits a comment hint —
+  `plain @extra # NOTE: use \`raw\` instead of \`plain\` if this is a
+  ReactNode-typed prop`. `plain` HTML-escapes its argument, which is
+  wrong for prebuilt-markup props but right for strings; we can't tell
+  at translation time, so we default to safe (`plain`) and surface the
+  choice.
+
+### Investigation
+
+- **Sibling named exports — not a gap.** Probed four shapes of
+  `export default Foo; export function Loading() {}` against the gem;
+  all four shapes correctly emit both `foo.rb` and `loading.rb`. Closed
+  the suspected gap as a false positive from the random sample.
+
+### Refactored
+
+- `Lowering` class shrunk by ~150 lines (v0.3.0 prep, now shipping):
+  pure-heuristic `ModuleShapeClassifier` lives in its own file; helper
+  methods `AST::Node#child`, `#of_type?`, `Node.matches?` replaced ~25
+  defensive `is_a?(AST::Node) && type ==` checks; class/style rendering
+  in the ViewComponent backend deduplicated across HTML-vs-Ruby output
+  formats; `tag_builder_data_action` replaced its "parse what I just
+  emitted" heuristic with a structured `EventDescriptor` intermediate.
+
+### Stress test outcome
+
+- 929-file Phlex stress run on `reserv-web`: 887/929 clean translations
+  (unchanged — rejection logic untouched), **0/1224 syntax failures**
+  (down from 25 on v0.3.0). All emitted `.rb` files now pass `ruby -c`.
+- Five residual bugs were caught during the v0.4.0 stress rerun and
+  fixed inline:
+  - Prop default expressions that translated to `nil # TODO: ...` inside
+    `initialize(...)` swallowed the closing `)`. Prop defaults now route
+    through the same recursive lowering as attribute values.
+  - Multi-line JSX comments only prefixed the first line with `#`. Every
+    line of a comment now gets a `#` prefix.
+  - Template literals with inner `"` or `\\` characters could break the
+    surrounding Ruby string. Literal segments now escape both.
+  - `token.blue` (where `token` was a captured local binding) translated
+    to `nil.blue` — `NoMethodError` at render time. Member-chain roots
+    that resolve to a known-local binding now fall through to the
+    snake_case bare reference with an unresolved marker rather than the
+    `nil` placeholder.
+  - `["a", "b"].map((x) => <li/>)` lost the array literal and emitted
+    `[].each` because the translator can't parse `[...]`. The lowering
+    now recognizes ArrayExpression iterables and routes them through
+    the recursive ArrayLiteral path.
+
+### Spec count
+
+- Up to 343 examples (from 304), all green. `bundle exec rubocop` clean.
+
+## [0.3.0] - 2026-05-10
+
+Driven by a 929-file stress run against the entire `reserv-web` codebase
+(`reserv-web/src/` + `reserv-web/pages/` + `packages/`). Baseline outcome
+on v0.2.0: 838/929 (90.2%) clean exit, 91 hard failures across 5 distinct
+error categories. This release ships fixes for all five plus a follow-up
+that opens up lowercase JSX-returning helpers as components, lifting the
+corpus to **887/929 (95.5%) clean exit**. The 42 remaining failures are
+non-component modules (utility/hook libraries, AG-Grid column
+descriptors, class-based ErrorBoundary components, side-effect
+initializers); each now reports a classifier-tagged error that explains
+*why* it didn't translate.
+
+### Fixed
+
+- **StringLiteral destructure keys no longer crash.**
+  `function X({ "data-testid": dataTestId })` previously surfaced as a
+  `bundler: failed to load command` after `Inflector.underscore(nil)` —
+  the v0.2.0 ObjectPattern fix only handled `Identifier` keys. The
+  lowering now reads `:value` from `StringLiteral` keys. Closes 11 files.
+- **Hyphenated prop names emit valid Ruby.** `Inflector.underscore` now
+  converts hyphens to underscores, so `data-testid` becomes `data_testid`
+  in Ruby identifiers (kwarg, ivar). HTML attribute names continue to
+  preserve hyphens — they're rendered from `Attribute.name` directly.
+
+### Added — return-shape lowering
+
+- **`return null;`, `return identifier;`, `return call();`** in return
+  position. Previously each raised "unexpected JSX node in lowering: …"
+  and crashed translation. The return-position dispatcher now accepts:
+  - `NullLiteral` → empty `IR::Text` (renders nothing in ERB; valid as a
+    Conditional alternate)
+  - `Identifier` → `IR::Interpolation`, with inlining when the identifier
+    is bound to a JSX local (`const card = <p/>; return card;`)
+  - `CallExpression` → `IR::Interpolation` of the verbatim source
+  Closes 20 files.
+- **Trailing `switch` and `try` body shapes.** Component bodies whose
+  only return path lives inside a trailing `switch (subject) { case A:
+  return X; default: return Y; }` or `try { return X; } catch …` now
+  lower cleanly. Switch fall-through groups (`case A: case B: return X;`)
+  emit a single Conditional with an OR-joined test
+  (`subject === A || subject === B`). Cases with multi-statement bodies
+  (other than a single block-wrapped return) bail and the gem still
+  raises "no return statement". Catch/finally handlers are dropped —
+  they typically encode JS-only error semantics. Closes ~5 files.
+- **Leading `if (X) return Y;` guards** wrap around any trailing return
+  structure (return / if-chain / switch / try). Previously a guard
+  before a trailing if-chain or switch was silently dropped (or caused
+  the surrounding structure to bail).
+
+### Added — what counts as a component
+
+- **Lowercase-named JSX-returning helpers** (`textRender`,
+  `booleanRender`, `cellFor`) now lower as components. The PascalCase
+  rule was tightened to "PascalCase OR (lowercase + body returns JSX,
+  excluding `use*` hook names)." A pre-lowering AST scan walks the
+  function body's return paths (recursing into BlockStatement,
+  IfStatement, SwitchStatement, TryStatement, ConditionalExpression,
+  LogicalExpression) to detect any reachable JSX value. Closes ~10
+  utility-renderer files.
+- **Permissive return-position dispatcher.** Function bodies that
+  return arbitrary non-JSX expressions (`return money.formattedValue;`,
+  `return computeValue();`, `` return `${name}` ``) now lower cleanly.
+  Member access, template literals, binary expressions, and other
+  bare-expression returns become `IR::Interpolation`; string and
+  numeric literals become `IR::Text`. This is what makes lowercase
+  JSX-helpers tractable — their guard returns are usually non-JSX.
+- **Implicit-return arrow bodies of any shape.** Previously
+  `const X = () => <div/>` worked but `const X = () => cond ? <a/> : <b/>`
+  raised "unsupported component body". The body dispatcher now routes
+  any non-block body through the return-position dispatcher.
+
+### Improved
+
+- **Module-shape classifier with eight labels and per-shape messages.**
+  Every `no component function found in module` error now appends a
+  specific label and a concrete suggestion: `:hoc_wrapped` (peel
+  `React.memo` / `forwardRef` / `lazy` / `observer`), `:class_component`
+  (rewrite as a function), `:hooks_only` (move behavior to Stimulus,
+  state to ivars), `:columns_data` (data lives in models or presenters),
+  `:types_only` (TypeScript types erase), `:utils_only` (only
+  JSX-returning helpers translate), `:mixed_exports` (split the file),
+  `:side_effects_only` (use a Rails initializer). Stress-test
+  validation: 42 remaining failures, 0 unlabeled.
+
 ## [0.2.0] - 2026-05-10
 
 Driven by an empirical probe of v0.1.0 against a 39-file Next.js production

data/README.md

@@ -13,7 +13,7 @@ gem itself emits.
 
 ```
 JSX text ──► Babel AST ──► Ruby AST ──► IR ──► backend ──► .rb / .html.erb / _controller.js
-            (Node sidecar) (typed tree) (sema)        (ViewComponent / RailsView / RoutesScript)
+            (Node sidecar) (typed tree) (sema)        (ViewComponent / RailsView / Phlex / RoutesScript)
 ```
 
 ## Installation
@@ -40,6 +40,17 @@ jsx_rosetta translate path/to/Button.tsx -o app/components
 #     app/components/button_component/button_component.html.erb
 #     app/components/button_component/button_controller.js   (when inline arrow handlers)
 
+# Translate as a single-file Phlex 2.x view class (no separate ERB)
+jsx_rosetta translate path/to/Button.tsx --as=phlex -o app/components
+# →   app/components/button.rb
+#     app/components/button_controller.js     (when inline arrow handlers)
+# With suffix:
+jsx_rosetta translate path/to/Button.tsx --as=phlex --phlex-suffix=Component -o app/components
+# →   app/components/button_component.rb       (class ButtonComponent)
+# With namespace:
+jsx_rosetta translate path/to/Button.tsx --as=phlex --phlex-namespace=Components -o app/components
+# →   app/components/button.rb                 (class Components::Button)
+
 # Translate a route-tied page as a Rails view template (no Ruby class)
 jsx_rosetta translate path/to/Home.tsx --as=view -o app/views/home
 # →   app/views/home/home.html.erb       (rename to index.html.erb)
@@ -96,12 +107,17 @@ JsxRosetta::Backend::RoutesScript.new(source_path: "router.tsx").emit(route_tree
 ```
 
 Optional kwargs to `JsxRosetta.translate`:
-- `backend: :view_component | :rails_view` (default `:view_component`)
-- `helpers: nil | Hash | false` — JSX-name → Rails-helper mapping (see below)
-- `layout: :sidecar | :flat` (default `:sidecar`, ignored for `:rails_view`)
+- `backend: :view_component | :rails_view | :phlex` (default `:view_component`)
+- `backend_options: Hash` — per-backend options (see below)
+- `helpers: nil | Hash | false` — JSX-name → Rails-helper mapping (see below; ViewComponent/RailsView only)
+- `layout: :sidecar | :flat` (default `:sidecar`; ViewComponent only)
 - `typescript: true` — force the TypeScript Babel plugin
 - `source_filename:` — surfaces in parse errors
 
+Phlex backend options (pass via `backend_options:`):
+- `suffix: "Component"` — append a suffix to the class name and file name. Mutually exclusive with `namespace:`.
+- `namespace: "Components"` — wrap the class in a `module Namespace` block. Mutually exclusive with `suffix:`.
+
 ## What translates
 
 | JSX construct                        | Translation                                                |
@@ -159,13 +175,13 @@ auto-perform. Common cases:
   recreate React's runtime in Ruby.
 - React Router's data-router form (`createBrowserRouter([...])`). Only the
   declarative `<Routes><Route>` shape is parsed today.
-- Backends other than ViewComponent and RailsView (Phlex, Slim, LiveView).
+- Backends other than ViewComponent, RailsView, and Phlex (Slim, LiveView).
 - Suspense → Turbo Frame mapping (depends on a data-fetching translation
   story we don't have yet).
 
-## ViewComponent emission targets
+## Emission targets
 
-Two backends, picked via `--as` on the CLI or `backend:` in the API:
+Three backends, picked via `--as` on the CLI or `backend:` in the API:
 
 **`:view_component` (default)** — emits a sidecar layout matching
 ViewComponent's `--sidecar` generator convention:
@@ -185,6 +201,52 @@ Pass `layout: :flat` to revert to the older flat layout
 no Ruby class and no sidecar. Place at `app/views/<controller>/<action>.html.erb`;
 the controller's instance variables become the template's `@x` references.
 
+**`:phlex`** — emits a single-file [Phlex 2.x](https://www.phlex.fun/) view
+class. The JSX template lives inside `view_template` as Ruby method calls,
+not in a separate ERB file:
+
+```ruby
+# app/components/card.rb (default mode)
+# app/components/card_component.rb (suffix: "Component")
+class Card < Phlex::HTML
+  def initialize(title: nil)
+    @title = title
+  end
+
+  def view_template
+    div(class: "card") do
+      h2 { plain @title }
+      yield
+    end
+  end
+end
+```
+
+Three mutually exclusive naming strategies (configurable):
+- **default** — `class FlashyHeader < Phlex::HTML` (collision-prone in large
+  apps where names like `Card` / `User` / `Image` overlap with models).
+- **`suffix: "Component"`** — `class FlashyHeaderComponent < Phlex::HTML`,
+  matches the ViewComponent layout, safest for migrations.
+- **`namespace: "Components"`** — wraps the class in a `module Components`
+  block. Cross-references inside the namespace stay bare (`render Card.new`)
+  and resolve via Ruby's constant lookup.
+
+Stimulus handlers still emit a sibling `_controller.js` skeleton alongside
+the `.rb` — the `data-controller`/`data-action` attrs go inline on the
+element (emitted as `data_controller:`/`data_action:` kwargs; Phlex
+auto-hyphenates underscores at render time), the handler body goes into
+the JS skeleton as a TODO comment.
+
+Attribute emission specifics:
+- Hyphenated JSX attrs (`data-testid`, `aria-label`) emit as snake_case
+  kwargs (`data_testid:`, `aria_label:`). Phlex 2.x converts the
+  underscores back to hyphens on render.
+- camelCase JSX attrs (`viewBox`, `preserveAspectRatio`) preserve
+  verbatim — Phlex only converts underscores, so SVG attributes stay
+  intact.
+- Attributes with characters that aren't valid Ruby identifiers (e.g.
+  `xml:lang`) fall back to a quoted string key inside `**{ "xml:lang" => x }`.
+
 ## Helper mappings
 
 Capitalized JSX tags that have a direct Rails helper analog skip the

data/lib/jsx_rosetta/ast/inflector.rb

@@ -11,6 +11,7 @@ module JsxRosetta
         string
           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr("-", "_")
           .downcase
       end
 

data/lib/jsx_rosetta/ast/node.rb

@@ -66,7 +66,10 @@ module JsxRosetta
       end
 
       # Field access. Accepts snake_case symbols/strings (translated to
-      # camelCase) and camelCase strings (used verbatim).
+      # camelCase) and camelCase strings (used verbatim). Returns whatever
+      # the raw hash contains at that key (Node, Array of Nodes, String,
+      # Hash, nil) — caller is responsible for type-checking. For typed
+      # access, prefer `#child` (returns Node | nil).
       def [](key)
         raw_key = key.to_s
         return Node.wrap(@raw[raw_key]) if @raw.key?(raw_key)
@@ -75,6 +78,30 @@ module JsxRosetta
         Node.wrap(@raw[camel_key])
       end
 
+      # Typed child access — returns the wrapped Node at `key`, or nil if
+      # absent or non-Node-shaped. Use this in lowering passes to avoid
+      # repetitive `is_a?(AST::Node)` defenses.
+      def child(key)
+        value = self[key]
+        value.is_a?(Node) ? value : nil
+      end
+
+      # Type predicate on a known Node. Use only when the receiver is
+      # guaranteed to be a Node — otherwise prefer `Node.matches?` (class
+      # method) which tolerates nil / non-Node values from hash lookups.
+      # Accepts multiple types: `node.of_type?("StringLiteral", "NumericLiteral")`.
+      def of_type?(*types)
+        types.include?(type)
+      end
+
+      # Defensive type predicate. True iff `value` is an AST::Node whose
+      # type is one of `types`. False for nil, arrays, strings, hashes, or
+      # any non-Node — making it safe for raw hash field accesses where
+      # the contents may be anything.
+      def self.matches?(value, *types)
+        value.is_a?(Node) && types.include?(value.type)
+      end
+
       def dig(*keys)
         keys.reduce(self) do |current, key|
           break nil if current.nil?