mjml-rb 0.4.2 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0062fce070623c7a358e1af4811bb928a46d7f0cd4e1320a71e16276ccca1d74
-  data.tar.gz: a4e81e450419963570486009b46f44962d93c25b41cdbe4df721346db6e79fc8
+  metadata.gz: a143101aa0a18f9aa1e77160d0810561f9b5e58fe6dbf8c68d9f809b91421d8d
+  data.tar.gz: b3fb93b17518384e6ce03e96162a30ef870ab4534bfc3c0fe62775b5db21c594
 SHA512:
-  metadata.gz: 880bfd1a06dfe3fb9e8fe2169fe660554cb4e9ca96ee5d6eff1d2b41f6df748af14b753895d7b58a3106e33335516f6f4caadd2fd01717c597846b6104330fbf
-  data.tar.gz: 94f84fa6a66210d9177db704c16efa6fce09d983eb138bc5d13fdbf9bf967ac553b867907cfce9190a2bd7e14a6e6108c4ff74eb776d16221cbf77689f59ea85
+  metadata.gz: a811a85d468e8332b29c533efe918038c68fccb9f7383d82bfceff42954cbe7c9faeccbe72dde57380b422881b620a358db2d6032bef62928053a6b25c001d71
+  data.tar.gz: c04f1e1df5835cbf5d0c2f81835ba942aa6f9d3149e592662cffeec22ece7c2841d89f44d4834e5ba29ef8b2891070c402a9da277b04363a7f59541740f2c785

data/README.md

@@ -11,198 +11,98 @@
 > This is a **fully open source project** — feedback, bug reports, test cases,
 > and pull requests are welcome!
 
-This gem provides a Ruby-first implementation of the main MJML tooling:
+A pure-Ruby MJML v4 compiler — no Node.js required.
 
-- library API compatible with `mjml2html`
-- command-line interface (`mjml`)
-- validation commands
-- pure Ruby parser, AST, validator, and renderer
-- no Node.js runtime and no shelling out to the official npm renderer
+- Library API compatible with `mjml2html`
+- Command-line interface (`mjml`)
+- Rails integration (ActionView template handler for `.mjml` views)
+- Validation (soft, strict, skip)
+- Custom component support
+- Pure Ruby parser, AST, validator, and renderer
 
-Remaining parity work is tracked in [npm ↔ Ruby Parity Audit](docs/PARITY_AUDIT.md).
-
-## Compatibility
-
-This project targets **MJML v4 only**.
+**[Full Usage Guide](docs/USAGE.md)** — API reference, all compiler options, component attribute tables, CLI flags, Rails setup, custom components, and more.
 
-- parsing, validation, and rendering are implemented against the MJML v4 document structure
-- component rules and attribute validation follow the MJML v4 model
+## Installation
 
-## Quick start
-
-```bash
-bundle install
-bundle exec ruby -Ilib -e 'require "mjml-rb"; puts MjmlRb.mjml2html("<mjml><mj-body><mj-section><mj-column><mj-text>Hello</mj-text></mj-column></mj-section></mj-body></mjml>")[:html]'
+```ruby
+# Gemfile
+gem "mjml-rb"
 ```
 
-## CLI usage
+## Quick Start
 
-```bash
-bundle exec bin/mjml example.mjml -o output.html
-bundle exec bin/mjml --validate example.mjml
+```ruby
+require "mjml-rb"
+
+result = MjmlRb.mjml2html(<<~MJML)
+  <mjml>
+    <mj-body>
+      <mj-section>
+        <mj-column>
+          <mj-text>Hello World!</mj-text>
+        </mj-column>
+      </mj-section>
+    </mj-body>
+  </mjml>
+MJML
+
+puts result[:html]     # compiled HTML
+puts result[:errors]   # validation errors (if any)
 ```
 
-## Rails integration
-
-In a Rails app, requiring the gem registers an `ActionView` template handler for
-`.mjml` templates through a `Railtie`.
-
-By default, `.mjml` files are treated as raw MJML/XML source.
+## CLI
 
-If you want Slim-backed MJML templates, configure it explicitly:
-
-```ruby
-config.mjml_rb.rails_template_language = :slim
+```bash
+mjml email.mjml -o email.html          # compile to file
+mjml -r "templates/*.mjml" -o output/  # batch compile
+mjml -v email.mjml                     # validate only
+mjml -i -s < email.mjml                # stdin → stdout
 ```
 
-Supported values are `:slim` and `:haml`.
+See the [Usage Guide — CLI section](docs/USAGE.md#cli) for all flags and config options.
 
-With a configured `rails_template_language`, `.mjml` templates are rendered
-through that template engine first, so partials and embedded Ruby can assemble
-MJML before the outer template is compiled to HTML. Without that setting,
-non-XML MJML source is rejected instead of being guessed.
+## Rails
 
-For `:slim` or `:haml`, the matching Rails template handler must already be
-registered in `ActionView` by the corresponding gem or integration layer.
+Add the gem to your Gemfile — that's it. The `.mjml` template handler is registered automatically.
 
-Create a view such as `app/views/user_mailer/welcome.html.mjml`:
-
-```mjml
+```erb
+<!-- app/views/user_mailer/welcome.html.mjml -->
 <mjml>
   <mj-body>
     <mj-section>
       <mj-column>
-        <mj-text>Hello from Rails</mj-text>
+        <mj-text>Welcome, <%= @user.name %>!</mj-text>
       </mj-column>
     </mj-section>
   </mj-body>
 </mjml>
 ```
 
-Then render it like any other Rails template:
-
 ```ruby
 class UserMailer < ApplicationMailer
-  def welcome
-    mail(to: "user@example.com", subject: "Welcome")
+  def welcome(user)
+    @user = user
+    mail(to: user.email, subject: "Welcome")
   end
 end
 ```
 
-Rails rendering uses strict MJML validation by default. You can override the
-compiler options in your application config:
-
-```ruby
-config.mjml_rb.compiler_options = { validation_level: "soft" }
-```
-
-## Custom components
+Supports Slim and Haml via `config.mjml_rb.rails_template_language = :slim`. See the [Usage Guide — Rails section](docs/USAGE.md#rails-integration) for full configuration.
 
-You can register custom MJML components written in Ruby:
-
-```ruby
-class MjRating < MjmlRb::Components::Base
-  TAGS = ["mj-rating"].freeze
-  ALLOWED_ATTRIBUTES = { "stars" => "integer", "color" => "color" }.freeze
-  DEFAULT_ATTRIBUTES = { "stars" => "5", "color" => "#f4b400" }.freeze
-
-  def render(tag_name:, node:, context:, attrs:, parent:)
-    stars = (attrs["stars"] || "5").to_i
-    color = attrs["color"] || "#f4b400"
-    %(<div style="color:#{escape_attr(color)}">#{"\u2605" * stars}</div>)
-  end
-end
-
-MjmlRb.register_component(MjRating,
-  dependencies: { "mj-column" => ["mj-rating"] },
-  ending_tags: ["mj-rating"]
-)
-```
-
-The `dependencies` hash declares which parent tags accept the new component as a child. The `ending_tags` list tells the parser to treat content as raw HTML (like `mj-text`). Both are optional.
-
-Once registered, the component works in MJML markup and is validated like any built-in component.
-
-## `.mjmlrc` config file
-
-Place a `.mjmlrc` file (JSON) in your project root to auto-register custom components and set default compiler options:
+## Architecture
 
-```json
-{
-  "packages": [
-    "./lib/mjml_components/mj_rating.rb"
-  ],
-  "options": {
-    "beautify": true,
-    "validation-level": "soft"
-  }
-}
 ```
-
-- **`packages`** — Ruby files to `require`. Each file should call `MjmlRb.register_component` to register its components.
-- **`options`** — Default compiler options. CLI flags and programmatic options override these.
-
-The CLI loads `.mjmlrc` automatically from the working directory. For the library API, load it explicitly:
-
-```ruby
-MjmlRb::ConfigFile.load("/path/to/project")
-result = MjmlRb.mjml2html(mjml_string)
+MJML string → Parser → AST → Validator → Renderer → HTML
 ```
 
-## Architecture
+1. **Parser** — normalizes source, expands `mj-include`, builds `AstNode` tree
+2. **Validator** — checks structure, hierarchy, and attribute types
+3. **Renderer** — resolves head metadata, applies defaults, emits responsive HTML
 
-The compile pipeline is intentionally simple and fully Ruby-based:
-
-1. `MjmlRb.mjml2html` calls `MjmlRb::Compiler`.
-2. `MjmlRb::Parser` normalizes the source, expands `mj-include`, and builds an `AstNode` tree.
-3. `MjmlRb::Validator` checks structural rules and supported attributes.
-4. `MjmlRb::Renderer` resolves head metadata, applies component defaults, and renders HTML.
-5. `MjmlRb::Compiler` post-processes the output and returns a `Result`.
-
-The key architectural idea is that the project uses a small shared AST plus a component registry:
-
-- the parser produces generic `AstNode` objects instead of component-specific node types
-- structure rules live in `lib/mjml-rb/dependencies.rb`
-- rendering logic lives in `lib/mjml-rb/components/*`
-- head components populate a shared rendering context
-- body components consume that context and emit the final HTML
-
-That split keeps the compiler pipeline predictable:
-
-- parsing is responsible for source normalization and include expansion
-- validation is responsible for MJML structure and attribute checks
-- rendering is responsible for HTML generation and responsive email output
-
-## Project structure
-
-The main files are organized like this:
-
-```text
-lib/mjml-rb.rb                    # public gem entry point
-lib/mjml-rb/compiler.rb           # orchestration: parse -> validate -> render
-lib/mjml-rb/parser.rb             # MJML/XML normalization, includes, AST building
-lib/mjml-rb/ast_node.rb           # shared tree representation
-lib/mjml-rb/validator.rb          # structural and attribute validation
-lib/mjml-rb/dependencies.rb       # allowed parent/child relationships
-lib/mjml-rb/renderer.rb           # HTML document assembly and render context
-lib/mjml-rb/components/*          # per-component rendering and head handling
-lib/mjml-rb/result.rb             # result object returned by the compiler
-lib/mjml-rb/cli.rb                # CLI implementation used by bin/mjml
-docs/ARCHITECTURE.md              # deeper architecture notes
-docs/PARITY_AUDIT.md              # npm vs Ruby parity tracking
-```
+For the full internal walkthrough, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
-If you want the full internal walkthrough, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+Remaining parity work is tracked in [npm ↔ Ruby Parity Audit](docs/PARITY_AUDIT.md).
 
-## Implementation goal
+## License
 
-> **Ruby MJML pipeline without the Node.js renderer.**
->
-> The npm `mjml` package requires Node.js at build time (or runtime via a child
-> process / FFI bridge). This project replaces that entire pipeline with a single
-> Ruby library: XML parsing, AST construction, attribute resolution, validation,
-> and HTML rendering — all in Ruby, with no Node.js runtime and no need to
-> shell out to the official MJML renderer. Drop it into a Rails, Sinatra, or
-> plain Ruby project and render MJML templates the same way you render ERB — no
-> extra runtime, no
-> `package.json`, no `node_modules`.
+MIT

data/lib/mjml-rb/components/section.rb

@@ -603,7 +603,7 @@ module MjmlRb
             "overflow"         => (has_border_radius ? "hidden" : nil),
             "margin"           => "0px auto",
             "margin-top"       => wrapper_gap,
-            "max-width"        => (full_width ? nil : "#{container_px}px")
+            "max-width"        => "#{container_px}px"
           }.merge(full_width ? {} : background_styles)
         )
 

data/lib/mjml-rb/renderer.rb

@@ -545,6 +545,12 @@ module MjmlRb
     end
 
     def normalize_background_fallbacks!(node, declarations)
+      background_image = declaration_value(declarations["background-image"])
+      if background_image && !background_image.empty?
+        declarations.delete("background") if syncable_background?(declaration_value(declarations["background"]))
+        return
+      end
+
       background_color = declaration_value(declarations["background-color"])
       return if background_color.nil? || background_color.empty?
 

data/lib/mjml-rb/version.rb

@@ -1,3 +1,3 @@
 module MjmlRb
-  VERSION = "0.4.2".freeze
+  VERSION = "0.4.3".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mjml-rb
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.3
 platform: ruby
 authors:
 - Andrei Andriichuk