jsx_rosetta 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28709ed22159e135331acff12df2c1fadbc2b692c62cd90d40a977192b28a46d
-  data.tar.gz: 4c8543a43d7ca8e96ba3c93d92f89fddbb548d4329332487df67683cabffa4e9
+  metadata.gz: d7b64119bbfe86413da7a779ada7e47cab06088411cb4667be2e79f8cfba3464
+  data.tar.gz: c1c1ac742642015a6ae7037538a34bf58b42b6e2fc232bedf48f8660b13a640d
 SHA512:
-  metadata.gz: c053e3111f0dc98f5ce3549d0c50a06f04f69bdbb13f5206296e807c62174b1e3824c9ac30d327884c20d1dd39d4fa821bec931292ff9802343b7d8c6a1da1ce
-  data.tar.gz: d06787398b3c56482c881184f0cdcbe6ce20071c9c6a1d1cc411fad1514a5a4910d9d7ddfd78455107e14f4285fdf4dcf2299f42a48622790bccb9c7d02bfc17
+  metadata.gz: 44a3dc2fc89b0dbb59ca5026f2cb27cc7f22e498cf125483725e1db07a39db1e45616baff9766be82bc52e443b33bf64180b90175660536c91f4bfc89e5b1926
+  data.tar.gz: a9c999e35af23ff2aba38a02ff57fc6229bf051dc339db859c341c9c1d607f88278542abd07a742ac84840616a305dcfe48b8bad32767ffbf5fc8d08c45ef7a9

data/CHANGELOG.md

@@ -1,5 +1,125 @@
 # 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

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/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?