ruby_ui_converter 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffc607673bf4249a934ea009f793f034a3d1c75bb72a100ff1df2f39e60e3ff7
-  data.tar.gz: 670b2734525033da876314c0a30b18da3910c9a7cac284d1d1759e43bc7cf2af
+  metadata.gz: 3ee2aaa230c92e0464d439a5767bfdc7913a013015fdd9f56a46f05bfb7c7400
+  data.tar.gz: ca39a6d4d10ab0b05d9a58115580faf0b71e3ecd5bee909d6ae7b267c682c98a
 SHA512:
-  metadata.gz: ceff723f0ea70a12973656154e947c5367170e8c2eab787f242f317ddbf106528ebeddb6882a74fe53f90917e5139d9d44c3b32c0792b58eab3342fb9f8419bb
-  data.tar.gz: ee214fe74ea2f9065d72aa5da91441cad67ffee934e756467c5d99702e234086c65891774e825fece326aa98a2b3b24d46267eedda906de846fa059475b75b10
+  metadata.gz: 515e92dc6c9d48b04c288cbb7a2448db2c4d51abdeaa6179746b4c02710eb2624417b295bced7186ed822db787017f23e6fa2c56888c09f3f79d6cee25b7acbe
+  data.tar.gz: b1d86c82e5405034576ed838fa998af8298f48187eaa987d2612ca76c4f731df585482a94bbaf18e837b8b1b193c481b703477e660f2031e85bf5845b7f0d0a5

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## [0.2.0] - 2026-11-13
+
+### Added
+
+- **HAML support**: `.haml` views and partials are converted alongside `.erb`
+  (`convert app/views` picks up both; `convert_string(..., format: :haml)`).
+  A new front-end (`HamlParser`) uses the haml gem's own parser — an
+  *optional* dependency, required lazily, supporting haml 5.2/6.x/7.x — and
+  builds the same AST as the ERB front-end, so RubyUI mapping, `link_to`/
+  `render`, form-builder mapping, locals/ivars detection and `--literal`
+  apply unchanged. Covers tags/shorthand, `=`/`!=`/`&=`, control flow and
+  blocks, interpolated text (parsed as HTML, so inline markup and
+  `#{link_to ...}` convert too), attribute merging (`class`/`id`, literal
+  `data:`/`aria:` hashes, booleans, `[@obj]` → `dom_id`/`dom_class`, splats),
+  comments (`/` with nested content → `comment do … end`), doctype and the
+  `:javascript`/`:css`/`:plain`/`:escaped`/`:erb`/`:ruby` filters. Without
+  the haml gem, the CLI explains once how to add it.
+- Compatibility matrix in the README and in CI: unit tests on Ruby 3.0–4.0
+  (plus `ruby-head`), and an end-to-end check (`script/rails_e2e/run.sh`) that
+  scaffolds, converts and renders a fresh Rails 7.1/7.2/8.0/8.1 app on
+  Ruby 3.2–4.0 — including a resource scaffolded with haml-rails, whose
+  converted HAML views are rendered too.
+
+### Changed
+
+- Two templates generating the same `.rb` (`show.html.erb` + `show.html.haml`,
+  or a `+variant`) are now reported as an error instead of being skipped or
+  overwritten.
+- Attribute expressions that are already self-delimited (`[a, b]`, `{...}`,
+  `dom_id(user, :row)`) are no longer wrapped in parentheses.
+
+### Fixed
+
+- HTML character references in text and literal attribute values
+  (`©`, ` `, `—`, `&`, `—`, `—`) are now
+  decoded before emitting, instead of being double-escaped by Phlex
+  (`©` used to render as the visible text "©"). Applies to ERB and
+  HAML text; `<script>`/`<style>` content and HAML's `:escaped` filter stay
+  verbatim. Invisible characters such as a decoded `&nbsp;` are written as
+  ` ` escapes in the generated source.
+- `form_with model: @x do |form|` (unparenthesized) now activates the
+  form-builder mapping (the model capture swallowed `do |form|`).
+- A same-line space between inline siblings (`<em>a</em> <%= b %>`) is kept
+  as Phlex `whitespace` instead of being dropped.
+
 ## [0.1.0] - 2026-06-14
 
 - Top-level views now get an initializer (or `prop`s with `--literal`) built

data/README.md

@@ -1,18 +1,20 @@
 # ruby_ui_converter
 
-Convert Rails `.erb` views and partials into [Phlex](https://www.phlex.fun) /
-[RubyUI](https://rubyui.com) Ruby components.
+Convert Rails `.erb` and `.haml` views and partials into
+[Phlex](https://www.phlex.fun) / [RubyUI](https://rubyui.com) Ruby components.
 
 Point it at a views directory and it walks recursively, converting each `.erb`
-template into an equivalent `.rb` file **next to it**:
+or `.haml` template into an equivalent `.rb` file **next to it**:
 
 ```
 app/views/users/index.html.erb   ->  app/views/users/index.rb   (Views::Users::Index)
 app/views/users/_user.html.erb   ->  app/views/users/user.rb    (Views::Users::User)
+app/views/posts/show.html.haml   ->  app/views/posts/show.rb    (Views::Posts::Show)
 ```
 
-Traditional Rails partials (`_user.html.erb`) become their own Phlex component
-classes, with detected locals exposed as keyword arguments. Top-level views get
+Traditional Rails partials (`_user.html.erb` / `_user.html.haml`) become their
+own Phlex component classes, with detected locals exposed as keyword
+arguments. Top-level views get
 an initializer for the controller instance variables they reference, so you can
 render them with `render Views::Users::Index.new(users: ...)`.
 
@@ -41,6 +43,13 @@ gem install ruby_ui_converter
 > RubyUI, convert with `--no-ruby-ui` to emit plain Phlex elements — then only
 > [phlex-rails](https://github.com/phlex-ruby/phlex-rails) is required.
 >
+> Converting **`.haml`** templates additionally needs the
+> [haml](https://rubygems.org/gems/haml) gem (5.2+) to be loadable by the
+> converter — it uses haml's own parser. It is an *optional* dependency, not
+> installed with this gem: apps with `.haml` views already have it in their
+> bundle, so run the converter with `bundle exec` inside the app. See
+> [HAML templates](#haml-templates).
+>
 > Likewise, converting with `--literal` makes the generated code depend on the
 > [literal](https://rubygems.org/gems/literal) gem (`bundle add literal` +
 > `extend Literal::Properties` on your base component class — see
@@ -58,10 +67,63 @@ gem install ruby_ui_converter
 > `rails new` and a scaffold with every common column type all the way to
 > rendering the converted Phlex/RubyUI components, step by step.
 
+## Compatibility
+
+There are two layers to check: the **converter** (the CLI/library that reads
+`.erb`/`.haml` and writes `.rb`) and the **generated code** (which runs inside your
+Rails app on top of [phlex-rails](https://github.com/phlex-ruby/phlex-rails) and
+[ruby_ui](https://rubygems.org/gems/ruby_ui)).
+
+**Converter** — depends only on `thor`, no Rails needed:
+
+| Ruby | 3.0 | 3.1 | 3.2 | 3.3 | 3.4 | 4.0 |
+| ---- | :-: | :-: | :-: | :-: | :-: | :-: |
+|      | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  |
+
+`.haml` conversion uses the haml gem found at runtime: **haml 5.2, 6.x and
+7.x** are supported (they share the parser API). haml 7 needs Ruby ≥ 3.2, so
+CI exercises haml 6 on Ruby 3.0/3.1 and haml 7 on Ruby 3.2+.
+
+**Generated code in a Rails app** — phlex-rails 2.x / ruby_ui 1.x require
+Ruby ≥ 3.2 and Rails ≥ 7.1, < 9:
+
+| Rails \ Ruby | 3.2 | 3.3 | 3.4 | 4.0 |
+| ------------ | :-: | :-: | :-: | :-: |
+| **8.1**      | ✅  | ✅  | ✅  | ✅  |
+| **8.0**      | ✅  | ✅  | ✅  | ✅  |
+| **7.2**      | ✅  | ✅  | ✅  | ✅  |
+| **7.1**      | ✅  | ✅  | ✅  | ✅  |
+
+Both matrices run in [CI](.github/workflows/ci.yml): the unit suite on every
+Ruby above (plus `ruby-head`, allowed to fail), and an end-to-end check
+([`script/rails_e2e/run.sh`](script/rails_e2e/run.sh)) for every Rails × Ruby
+cell — it runs `rails new`, scaffolds a resource with every common column type
+(ERB views) plus a second one with [haml-rails](https://github.com/haml/haml-rails)
+(HAML views), converts both, and renders them through the generated
+Phlex/RubyUI classes in an integration test (index, show, new, edit,
+validation errors, create).
+Last verified with Ruby 4.0.9, Rails 8.1.4.1, phlex-rails 2.4.0 and
+ruby_ui 1.6.0.
+
+> [!NOTE]
+> Rails 7.1/7.2/8.0 apps created today resolve `json` 3.x and `minitest` 6.x,
+> which those Rails versions themselves don't support (`unknown keyword:
+> quirks_mode` when saving a JSON column; a minitest `ArgumentError` on 7.1).
+> This is unrelated to the converter — pin `gem "json", "< 3"` and
+> `gem "minitest", "< 6"` in such apps (the CI check does the same).
+
+> [!WARNING]
+> On any Rails version: `refract` 1.1.0 (a dependency of phlex 2.4) references
+> `Prism::MissingNode`, which `prism` 2.x removed. Apps that resolve prism 2.x
+> crash with `uninitialized constant Prism::MissingNode` as soon as they eager
+> load (production, or tests with `CI` set) — even in development everything
+> looks fine. Until refract is fixed, add `gem "prism", "< 2"` to your Gemfile.
+> The CI check pins it too and runs with eager loading on.
+
 ## CLI usage
 
 ```bash
-# Convert a whole folder (recursively), writing .rb next to each .erb
+# Convert a whole folder (recursively), writing .rb next to each .erb/.haml
 bundle exec ruby_ui_converter convert app/views/users
 
 # Preview without writing anything
@@ -109,6 +171,9 @@ RubyUIConverter.convert_string('<h1><%= @title %></h1>', class_name: "Page")
 #     h1 { @title }
 #   end
 # end
+
+# Same for HAML
+RubyUIConverter.convert_string("%h1= @title", class_name: "Page", format: :haml)
 ```
 
 ## What gets converted
@@ -130,6 +195,7 @@ RubyUIConverter.convert_string('<h1><%= @title %></h1>', class_name: "Page")
 | `<%= render "form", user: @user %>`       | `render Views::Users::Form.new(user: @user)`        |
 | `data-id="<%= id %>"`                     | `"data-id": id`                                     |
 | `<%# comment %>`                          | `# comment`                                         |
+| `&copy; 2026&nbsp;&mdash; a &lt;b&gt;`    | `"© 2026\u00A0— a <b>"` (Phlex re-escapes)          |
 
 Top-level views get an initializer built from the controller instance variables
 they reference (`@products` → `def initialize(products: nil); @products = products; end`),
@@ -188,6 +254,63 @@ class Components::Base < Phlex::HTML
 end
 ```
 
+## HAML templates
+
+`.haml` files are converted alongside `.erb` ones (same CLI, same options,
+same naming: `_user.html.haml` → `Views::Users::User`). Parsing is done by
+the [haml](https://rubygems.org/gems/haml) gem's own parser (5.2, 6.x or 7.x),
+which must be loadable by the converter — run it with `bundle exec` inside an
+app that uses HAML. Without it, `.erb` files still convert and the CLI
+explains once how to add the gem.
+
+The HAML front-end builds the **same intermediate tree** the ERB one does, so
+everything else — RubyUI element mapping, `link_to`/`render` translation,
+form-builder mapping, locals/ivars detection, `--literal` — applies unchanged.
+
+| HAML                                          | Generated Ruby                                              |
+| --------------------------------------------- | ----------------------------------------------------------- |
+| `%p.lead#intro Hello`                         | `p(class: "lead", id: "intro") { "Hello" }`                 |
+| `%p= user.email` / `!= markup`                | `p { user.email }` / `raw(safe(markup))`                    |
+| `%p Hi #{name}`                               | `plain "Hi "` + `plain(name)` (like `Hi <%= name %>`)       |
+| `Go to #{link_to "Docs", docs_path}`          | `plain "Go to "` + `Link(href: docs_path) { "Docs" }`       |
+| `- if a` / `- elsif b` / `- else`             | real `if / elsif / else / end`                              |
+| `- items.each do \|i\|`                       | `items.each do \|i\| … end`                                 |
+| `.card{class: "shadow"}`                      | `Card(class: "card shadow")`                                |
+| `%p.btn{class: "x #{y}"}`                     | `p(class: "btn x #{y}")`                                    |
+| `%p.row{class: [a, b]}`                       | `p(class: ["row", [a, b]])` (Phlex flattens the array)      |
+| `%a{data: {turbo_method: :delete}}`           | `"data-turbo-method": "delete"`                             |
+| `%input{type: "checkbox", checked: false}`    | `Checkbox()` (`false`/`nil` attributes are dropped)         |
+| `%li[@user]`                                  | `li(id: dom_id(@user), class: dom_class(@user))`            |
+| `%div{html_attrs}`                            | `div(**(html_attrs))`                                       |
+| `-# note` / `/ note`                          | `# note` / `comment { "note" }`                             |
+| `/` with nested content                       | `comment do … end`                                          |
+| `:javascript` / `:css`                        | `script` / `style` with raw content (interpolation kept)    |
+| `:plain` / `:escaped` / `:erb` / `:ruby`      | text (as HTML) / escaped text / ERB conversion / statements |
+
+Plain text keeps HAML's semantics: it may contain inline HTML (parsed into
+elements) and its `#{}` interpolations are escaped. HAML puts a line break
+between lines, so a text line next to other content gets a separating space
+(`Signed in as` + `%strong= name` → `plain "Signed in as "` + `strong { name }`),
+except around tags that remove whitespace (`%img>`).
+
+HAML-specific limitations:
+
+- Whitespace is approximated: only text lines get the separating space; two
+  adjacent outputs/tags on separate lines render without one, and `~`/preserve
+  handling is not reproduced.
+- `[@obj]` uses Rails' `dom_id`/`dom_class`: for a new record that gives
+  `new_user`, where HAML gives `user_new`. Include the `DOMID` helper (see
+  [step 3](#3-include-the-rails-helpers-your-views-use)).
+- `{id: [a, b]}`: HAML joins with `_`, Phlex with a space.
+- A class array merged with shorthand classes relies on Phlex flattening
+  nested arrays (verified on Phlex 2).
+- Class-based RubyUI rules (`.card` → `Card`, `.badge` → `Badge`) only match a
+  static class: `.card{class: "x #{y}"}` or `.card[@user]` stays a `div`
+  (same as `<div class="card <%= y %>">` in ERB).
+- IE conditional comments (`/[if IE]`) and filters other than the ones above
+  (`:markdown`, `:scss`, …) are left as `# TODO` comments.
+- Inline HTML that opens on one line and closes on another isn't nested.
+
 ## Migrating a Rails ERB app
 
 `ruby_ui_converter` only **generates** the component source — running it
@@ -450,11 +573,14 @@ Caveats worth reviewing (heuristic, model binding is reconstructed by hand):
 
 ## Design & limitations
 
-The converter is a pure-Ruby pipeline with **no native dependencies**:
+The converter is a pure-Ruby pipeline with **no native dependencies** (only
+`thor` at runtime; the haml gem is used, when present, for `.haml` files). Two
+front-ends build the same AST, which a single Transformer turns into Ruby:
 
 ```
-ERB ─▶ Lexer ─▶ HtmlTokenizer ─▶ Parser ─▶ Transformer ─▶ Ruby/Phlex
-       (tokens)   (html tokens)  (AST)      (CodeBuilder)
+.erb  ─▶ Lexer ─▶ HtmlTokenizer ─▶ Parser ──────┐
+                                                ├─▶ AST ─▶ Transformer ─▶ Ruby/Phlex
+.haml ─▶ Haml::Parser (haml gem) ─▶ HamlParser ─┘           (CodeBuilder)
 ```
 
 It covers the common cases well, but it is a heuristic source-to-source tool —
@@ -467,10 +593,18 @@ It covers the common cases well, but it is a heuristic source-to-source tool —
   as blocks but may need manual adjustment for phlex-rails idioms.
 - `render @collection` / object forms are emitted as a bare `render ...` call;
   phlex-rails' `#render` handles model objects and relations.
+- HTML character references in text and literal attribute values are
+  decoded (`&copy;` → `©`, `&#8212;` → `—`) so Phlex doesn't escape them
+  twice; named references cover the HTML 4 set (`&nbsp;`, `&mdash;`,
+  accented letters, arrows, Greek, …) — other names are left as written.
 - Inline `<script>` / `<style>` content is wrapped in a raw call
   (`raw(safe(...))` on Phlex 2, `unsafe_raw(...)` on Phlex 1) with a TODO.
 - Custom elements (e.g. `<my-widget>`) are emitted as method calls and may need
   a Phlex-compatible registration.
+- Two templates for the same action (`show.html.erb` + `show.html.haml`, or a
+  variant like `show.html+phone.erb`) would generate the same `.rb`: the first
+  is converted and the other is reported as an error.
+- See also the [HAML-specific limitations](#haml-templates).
 
 Generated files are checked for valid Ruby syntax by the test suite, but
 semantic equivalence is your responsibility to verify.
@@ -480,6 +614,9 @@ semantic equivalence is your responsibility to verify.
 ```bash
 bin/setup        # bundle install
 bundle exec rake test
+
+# end-to-end check against a fresh Rails app (latest patch of the series)
+script/rails_e2e/run.sh 8.1
 ```
 
 ## License

data/lib/ruby_ui_converter/cli.rb

@@ -8,11 +8,12 @@ module RubyUIConverter
       true
     end
 
-    desc "convert PATH", "Convert .erb views/partials under PATH into RubyUI/Phlex .rb files"
+    desc "convert PATH", "Convert .erb/.haml views/partials under PATH into RubyUI/Phlex .rb files"
     long_desc <<~DESC
-      Recursively walks PATH looking for *.erb files and writes an equivalent
-      .rb component next to each one (e.g. index.html.erb -> index.rb). Rails
-      partials (_form.html.erb) become their own component classes (form.rb).
+      Recursively walks PATH looking for *.erb and *.haml files and writes an
+      equivalent .rb component next to each one (e.g. index.html.erb ->
+      index.rb). Rails partials (_form.html.haml) become their own component
+      classes (form.rb). Converting .haml requires the haml gem to be loadable.
 
       By default, basic HTML elements are mapped onto RubyUI kit components
       (a -> Link, button -> Button, input -> Input, table -> Table, ...).
@@ -71,7 +72,7 @@ module RubyUIConverter
 
     def report(results, config)
       if results.empty?
-        say "No .erb files found.", :yellow
+        say "No .erb or .haml files found.", :yellow
         return
       end
 
@@ -86,13 +87,28 @@ module RubyUIConverter
         when :skipped
           say "  skipped  #{relative(result.output)} (exists, use --force)", :yellow
         when :error
-          say "  error    #{relative(result.source)}: #{result.error.message}", :red
+          if missing_haml?(result)
+            say "  error    #{relative(result.source)}: haml gem not available", :red
+          else
+            say "  error    #{relative(result.source)}: #{result.error.message}", :red
+          end
         end
       end
 
       counts = results.group_by(&:status).transform_values(&:size)
       say ""
       say "Done. #{counts.map { |status, n| "#{n} #{status}" }.join(", ")}."
+
+      # Every .haml file fails the same way without the gem: explain it once.
+      return unless results.any? { |result| missing_haml?(result) }
+
+      say ""
+      say "Note: #{HamlParser::MISSING_HAML}, then run the converter again " \
+          "(inside your app, `bundle exec ruby_ui_converter ...`).", :yellow
+    end
+
+    def missing_haml?(result)
+      result.status == :error && result.error&.message == HamlParser::MISSING_HAML
     end
 
     def preview(result)

data/lib/ruby_ui_converter/converter.rb

@@ -32,7 +32,12 @@ module RubyUIConverter
     end
 
     def run
-      FileWalker.new(@path).erb_files.map { |file| convert_file(file) }
+      # output path -> source that claimed it in this run. Two templates of the
+      # same action (show.html.erb + show.html.haml, or a variant like
+      # show.html+phone.erb) map to the same .rb; the later one is reported as
+      # an error instead of silently skipping or overwriting the first.
+      @claimed = {}
+      FileWalker.new(@path).template_files.map { |file| convert_file(file) }
     end
 
     private
@@ -55,9 +60,17 @@ module RubyUIConverter
     def convert_file(file)
       file = File.expand_path(file)
       template = Template.new(path: file, root: root, config: @config)
-      code = template.render
       output = template.output_path
 
+      if (other = @claimed[output])
+        error = Error.new("#{File.basename(output)} is also generated from #{File.basename(other)}; " \
+                          "convert one of them (or remove the other) to avoid a clash")
+        return Result.new(source: file, output: output, status: :error, error: error)
+      end
+
+      @claimed[output] = file
+      code = template.render
+
       if @config.dry_run
         return Result.new(source: file, output: output, status: :previewed, code: code)
       end

data/lib/ruby_ui_converter/file_walker.rb

@@ -1,22 +1,29 @@
 # frozen_string_literal: true
 
 module RubyUIConverter
-  # Finds .erb files under a path (recursively for directories).
+  # Finds template files (.erb, .haml) under a path (recursively for
+  # directories).
   class FileWalker
-    ERB_GLOB = "**/*.erb"
+    # Keep in sync with RubyUIConverter::FORMATS.
+    GLOB = "**/*.{erb,haml}"
 
     def initialize(path)
       @path = path
     end
 
-    def erb_files
+    def template_files
       if File.directory?(@path)
-        Dir.glob(File.join(@path, ERB_GLOB)).select { |f| File.file?(f) }.sort
-      elsif File.file?(@path) && @path.end_with?(".erb")
+        Dir.glob(File.join(@path, GLOB)).select { |f| File.file?(f) }.sort
+      elsif File.file?(@path) && RubyUIConverter.format_for(@path)
         [@path]
       else
         []
       end
     end
+
+    # Kept for backwards compatibility: only the .erb templates.
+    def erb_files
+      template_files.select { |f| RubyUIConverter.format_for(f) == :erb }
+    end
   end
 end

data/lib/ruby_ui_converter/form_builder.rb

@@ -60,6 +60,10 @@ module RubyUIConverter
     end
 
     def model_expression(header)
+      # Drop the block opener first so an unparenthesized call
+      # (`form_with model: @product do |form|`) doesn't capture `do |form|`.
+      header = header.sub(/\s*\bdo\s*(\|[^|]*\|)?\s*\z/, "")
+
       if (model = header[/\bmodel:\s*([^,)]+)/, 1])
         return model.strip
       end

data/lib/ruby_ui_converter/haml_attributes.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module RubyUIConverter
+  # Turns the attributes of a HAML tag (as Haml::Parser reports them) into the
+  # converter's attribute list — `[[name, parts], ...]`, the same shape the ERB
+  # Parser builds (see Nodes) — merging them the way HAML does:
+  #
+  #   * sources, in order: static (`.a#b`, `(x="y")`, `(disabled)`), html-style
+  #     dynamic `(x=expr)`, the `{...}` hash, then the object reference `[@obj]`;
+  #   * `class` values are merged (space-joined), `id` values joined with `_`;
+  #     any other repeated attribute is overridden by the later source;
+  #   * `false`/`nil` literals drop the attribute, `true` makes it boolean;
+  #   * literal `data:`/`aria:` hashes expand to hyphenated attributes
+  #     (`data: {turbo_method: :delete}` -> `"data-turbo-method": "delete"`);
+  #   * string literals become text/erb parts (so ComponentMap matchers like
+  #     `static_classes` keep working); symbol literals become text;
+  #   * a hash Haml can't split (`{html_attrs}`, `{**opts}`) becomes a
+  #     `**(...)` splat.
+  class HamlAttributes
+    NESTED = %w[data aria].freeze
+    MERGED = { "class" => " ", "id" => "_" }.freeze
+
+    Entry = Struct.new(:name, :values)
+
+    def self.build(tag_value)
+      new(tag_value).build
+    end
+
+    def initialize(tag_value)
+      @tag = tag_value
+      @entries = []
+    end
+
+    def build
+      static_attributes
+      dynamic = @tag[:dynamic_attributes]
+      dynamic_hash(dynamic&.new)
+      dynamic_hash(dynamic&.old)
+      object_reference
+      @entries.map { |entry| finalize(entry) }
+    end
+
+    private
+
+    # --- sources -----------------------------------------------------------
+
+    def static_attributes
+      @tag[:attributes].to_h.each do |name, value|
+        case value
+        when true then add(name.to_s, [:bool])
+        when nil, false then add(name.to_s, nil)
+        else add(name.to_s, [:parts, [[:text, value.to_s]]])
+        end
+      end
+    end
+
+    def dynamic_hash(hash_code)
+      return if hash_code.nil? || hash_code.strip.empty?
+
+      pairs = ::Haml::AttributeParser.parse(hash_code)
+      if pairs
+        pairs.each { |name, code| add_code(name.to_s, code) }
+      else
+        @entries << Entry.new(:__splat__, [[:parts, [erb(splat_code(hash_code))]]])
+      end
+    end
+
+    # `%div[@user]` / `%div[@user, :edit]` -> Rails' dom_id / dom_class.
+    def object_reference
+      ref = @tag[:object_ref]
+      return if ref.nil? || ref == :nil
+
+      args = RailsHelpers.split_args(ref.to_s.strip.sub(/\A\[/, "").sub(/\]\z/, ""))
+      return if args.empty?
+
+      call_args = args.first(2).join(", ")
+      add("id", [:code, "dom_id(#{call_args})"])
+      add("class", [:code, "dom_class(#{call_args})"])
+    end
+
+    # --- values ------------------------------------------------------------
+
+    def add_code(name, code)
+      if NESTED.include?(name) && (nested = nested_hash(code))
+        nested.each { |key, value| add_code("#{name}-#{key.to_s.tr("_", "-")}", value) }
+      else
+        add(name, value_for(code))
+      end
+    end
+
+    def nested_hash(code)
+      code = code.to_s.strip
+      return nil unless code.start_with?("{")
+
+      ::Haml::AttributeParser.parse(code)
+    end
+
+    # nil means "drop the attribute".
+    def value_for(code)
+      code = code.to_s.strip
+      return [:bool] if code == "true"
+      return nil if %w[false nil].include?(code)
+      return [:parts, [[:text, code[1..]]]] if code.match?(/\A:\w+[?!]?\z/)
+
+      parts = RubyLiteral.string_parts(code)
+      return [:parts, parts.map { |kind, value| kind == :text ? [:text, value] : erb(value) }] if parts
+
+      [:code, code]
+    end
+
+    def add(name, value)
+      entry = @entries.find { |e| e.name == name }
+
+      if MERGED.key?(name)
+        return unless value
+
+        entry ? entry.values << value : @entries << Entry.new(name, [value])
+      elsif value.nil?
+        @entries.delete(entry)
+      elsif entry
+        entry.values = [value]
+      else
+        @entries << Entry.new(name, [value])
+      end
+    end
+
+    # --- output ------------------------------------------------------------
+
+    def finalize(entry)
+      values = entry.values
+      return [entry.name, nil] if values == [[:bool]]
+      return [entry.name, to_parts(values.first)] if values.length == 1
+
+      separator = MERGED.fetch(entry.name, " ")
+      if entry.name == "class" && values.any? { |kind, _| kind == :code }
+        # Arbitrary expressions may be arrays/nil: let Phlex flatten them.
+        [entry.name, [erb("[#{values.map { |value| to_code(value) }.join(", ")}]")]]
+      else
+        parts = values.flat_map.with_index do |value, index|
+          (index.zero? ? [] : [[:text, separator]]) + to_parts(value)
+        end
+        [entry.name, parts]
+      end
+    end
+
+    def to_parts(value)
+      kind, payload = value
+      case kind
+      when :parts then payload
+      when :code then [erb(payload)]
+      when :bool then [erb("true")]
+      end
+    end
+
+    def to_code(value)
+      kind, payload = value
+      return payload if kind == :code
+      return "true" if kind == :bool
+      return payload[0][1].value if payload.length == 1 && payload[0][0] == :erb
+
+      body = payload.map do |part_kind, part|
+        part_kind == :text ? escape(part) : "\#{#{part.value}}"
+      end.join
+      "\"#{body}\""
+    end
+
+    def escape(text)
+      text.gsub(/[\\"\n\t]|\#\{/) do |match|
+        { "\\" => "\\\\", "\"" => "\\\"", "\n" => "\\n", "\t" => "\\t", "\#{" => "\\\#{" }[match]
+      end
+    end
+
+    # "{a: 1}" -> "{a: 1}"; "{html_attrs}" -> "html_attrs" (haml treats the
+    # braces' content as an argument list, so a bare expression is the hash).
+    def splat_code(hash_code)
+      inner = hash_code.to_s.strip.sub(/\A\{/, "").sub(/\}\z/, "").strip
+      args = RailsHelpers.split_args(inner)
+      pairs = args.any? { |arg| arg =~ /\A(\*\*|[\w?!]+:(?!:)|"[^"]*":|'[^']*':)/ || arg.include?("=>") }
+      pairs ? "{#{inner}}" : inner
+    end
+
+    def erb(code)
+      [:erb, Lexer::Token.new(type: :output, value: code, raw: false)]
+    end
+  end
+end