react-email-rails 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8de13aced1b8b88a622cdc40577ec17c80ad457cee75ea57266dc248e5355416
-  data.tar.gz: d42cacd94f77a32ccf75d72b5e8c19506549902c64617a723c6617e0bc613a58
+  metadata.gz: 52da00b9618d5b217b66af2598edf2a25fa9d0850447bfc95d8637c778837583
+  data.tar.gz: 84bcdbd09672b293b85d65bbde9779c0d0d2c2c282dd83e72cc2412d38150c6b
 SHA512:
-  metadata.gz: 1fbbbb75215e8b4b77de4d4c15e533348e2b7195196d5b9401541596e24507b3c046ca8f74998f20b76f9fbf6d9b67d8c0ec29a86af3aaa64e0b1b70bece4c85
-  data.tar.gz: 5e7025b1552256c5d1b2fd01a911c7d941b2fd41aa6cd94ddd646fbeb79713888dd6dc13785ff71c66cadb9362877e2abe4715855630813314e7073f509ccccc
+  metadata.gz: b9ce2a8643e90776bee1f37c9758fd9d853465d37b73184e0ebdeb20a87e33d9d686354b1a8256cb3bb4887221d25b7c14c9b6733d905c04e86f3fa2d1e06cc7
+  data.tar.gz: 1257c29d6639ed5a1559d23d64316bea2c6ccf075b365e816dc0bfd41cb996003e466dbabe97bc50aa9b736e2a45e81e083cd908791f91d8d94f13b239e65f67

data/CHANGELOG.md

@@ -1,13 +1,19 @@
 # Changelog
 
+## 0.3.0
+
+- Add `ReactEmailRails.parse` to convert semantic HTML into a canonical `@react-email/editor` document using a renderer's extensions.
+- Add `@tiptap/html` and `happy-dom` as optional peer dependencies, required only when calling `parse`; compose-only document rendering does not require them.
+- Bump the render protocol to 3 (the renderer now accepts parse requests). The Ruby gem and npm package must be upgraded together, as before.
+
 ## 0.2.0
 
-- Add `ReactEmailRails.compose` for server-side rendering of `@react-email/editor` documents (Tiptap/ProseMirror JSON) to HTML and text, the server analog of the editor's client-side `composeReactEmail` export.
-- Add the `documents` Vite plugin option for discovering document renderers, parallel to `emails`. It is off by default; the editor packages stay out of the email render path and build graph unless it is enabled.
-- Report document nodes that render to nothing (a node whose extension is not an email renderer) as non-fatal warnings — on the result (`rendered.warnings`) and the `render.react-email-rails` instrumentation payload (`payload[:warnings]`) — so silently dropped content is detectable.
+- Add `ReactEmailRails.compose` for server-side rendering of `@react-email/editor` documents to HTML and text.
+- Add the `documents` Vite plugin option for discovering document renderers, parallel to `emails`.
+- Report document nodes that render to nothing as non-fatal warnings on the result and instrumentation payload.
 - Add `@react-email/editor` and `@tiptap/core` as optional peer dependencies (only required when rendering documents).
 - Bump the render protocol to 2 (the renderer now accepts document requests). The Ruby gem and npm package must be upgraded together, as before.
-- **Breaking:** `on_render_error` callbacks now receive a uniform `(error, **context)` shape, where `context` carries `kind:` (`"email"`/`"document"`) and either `component:` (emails) or `type:` (documents). Update `->(error, component:) { ... }` callbacks to `->(error, **context) { ... }`.
+- **Breaking:** `on_render_error` callbacks now receive `(error, **context)` with `kind:` plus `component:` for emails or `type:` for documents.
 
 ## 0.1.3
 

data/README.md

@@ -311,6 +311,12 @@ Install the editor packages:
 npm i @react-email/editor @tiptap/core
 ```
 
+To also parse HTML into documents with [`parse`](#parsing-html-into-a-document), add `@tiptap/html` and its server DOM, `happy-dom`:
+
+```sh
+npm i @tiptap/html happy-dom
+```
+
 Enable the `documents` option in your Vite config:
 
 ```ts
@@ -397,7 +403,7 @@ broadcast = Broadcast.find(params[:id])
 
 rendered = ReactEmailRails.compose(
   type: "broadcast",
-  document: broadcast.body,          # Tiptap JSON, e.g. a jsonb column
+  document: broadcast.body,          # a Hash in Tiptap's shape, e.g. from a jsonb column
   context: { brand_name: "Acme", preview_text: broadcast.subject },
   preview: broadcast.subject,        # optional; falls back to getPreview(context)
 )
@@ -408,10 +414,40 @@ rendered.text # => "ACME\n\n..."
 
 It returns the same `RenderedEmail` (`html`/`text`) as `render`, runs through the same [render modes](#render-modes), and raises `ReactEmailRails::RenderError` on failure. Documents don't go through Action Mailer — broadcasts and the like usually have their own delivery path — so deliver `rendered.html`/`rendered.text` however your app sends mail.
 
-**Keys:** `context` is key-transformed exactly like component props (so `brand_name` arrives as `brandName`, per [`transform_props`](#prop-transformation)). The **`document` is passed through verbatim** — its keys (`type`, `attrs`, `content`, `marks`, node names, `globalContent`) are structural and are never transformed.
+**The document is a `Hash`.** You pass and store it as a plain Ruby `Hash` with string keys — what a jsonb column hands back, and what [`parse`](#parsing-html-into-a-document) returns. "Tiptap JSON" names the document's *shape* (and the format it's serialized to over the wire to the renderer), not the Ruby type; `compose` accepts any object that responds to `as_json`, but a `Hash` is the norm.
+
+**Keys:** the document's keys (`type`, `attrs`, `content`, `marks`, node names, `globalContent`) are structural and **passed through verbatim** — never transformed. Only `context` is key-transformed, camelized exactly like component props (so `brand_name` arrives as `brandName`, per [`transform_props`](#prop-transformation)).
 
 `render_options` does not apply to documents; `composeReactEmail` controls its own rendering.
 
+### Parsing HTML into a Document
+
+`ReactEmailRails.parse` converts semantic HTML into the same document `Hash` shape the editor stores, using the selected renderer's extensions. This needs the `@tiptap/html` and `happy-dom` packages (see [Setup](#setup)).
+
+```ruby
+document = ReactEmailRails.parse(
+  type: "broadcast",                 # the same renderer type compose uses
+  html: params[:body_html],          # the HTML the caller sent
+  context: { brand_name: "Acme" },   # optional; reaches buildExtensions, like compose
+)
+
+broadcast.update!(body: document)    # persist the Hash (e.g. to a jsonb column)
+```
+
+Later, render the stored document like any other:
+
+```ruby
+rendered = ReactEmailRails.compose(type: "broadcast", document: broadcast.body)
+```
+
+`parse` returns a plain Ruby `Hash` with string keys, normalized through the renderer's schema. It uses the same [render modes](#render-modes) as `compose` and raises `ReactEmailRails::RenderError` on failure. `context` is key-transformed like component props; the HTML is sent verbatim.
+
+What this means in practice:
+
+- HTML maps to a node only when an extension defines how to parse it. Unknown elements, inline styles, and classes may be dropped or flattened.
+- Editor-only constructs such as custom email nodes and the persisted `globalContent` theme node do not round-trip from plain HTML.
+- If you already have the document `Hash`, pass it to `compose` directly.
+
 ### Debugging Dropped Content
 
 The most common integration bug is an extension/document mismatch. A node whose type is **missing from `buildExtensions` entirely** raises `ReactEmailRails::RenderError` (it can't be parsed) — loud and safe. The quiet case is a node that *is* in the schema but whose extension does not render to email (a plain Tiptap node rather than an email one): `composeReactEmail` renders it as nothing, with no error.
@@ -510,7 +546,7 @@ end
 
 #### Error Reporting
 
-Use `on_render_error` to report failures before the exception is re-raised. The callback receives the error and a `context` of `kind:` (`"email"` or `"document"`) plus the identifier — `component:` for emails, `type:` for documents. Accept `**context` so one handler covers both render kinds:
+Use `on_render_error` to report failures before the exception is re-raised. The callback receives the error and a `context` of `kind:` (`"email"`, `"document"`, or `"parse"`) plus the identifier — `component:` for emails, `type:` for documents and parse requests. Accept `**context` so one handler covers every render kind:
 
 ```ruby
 ReactEmailRails.configure do |config|
@@ -522,7 +558,7 @@ end
 
 #### Instrumentation
 
-Every render emits an [ActiveSupport::Notifications](https://guides.rubyonrails.org/active_support_instrumentation.html) event named `render.react-email-rails`, so you can log render timing or forward it to your APM. The payload carries a `kind` (`"email"` or `"document"`), the `component` name (email) or `type` (document), and, on success, the rendered HTML size in `html_bytes`. Document renders that drop content also include `warnings` (see [Debugging Dropped Content](#debugging-dropped-content)):
+Every render emits an [ActiveSupport::Notifications](https://guides.rubyonrails.org/active_support_instrumentation.html) event named `render.react-email-rails`, so you can log render timing or forward it to your APM. The payload carries a `kind` (`"email"`, `"document"`, or `"parse"`), the `component` name (email) or `type` (document and parse), and, on a successful render, the rendered HTML size in `html_bytes` (omitted for `parse`, which returns a document rather than HTML). Document renders that drop content also include `warnings` (see [Debugging Dropped Content](#debugging-dropped-content)):
 
 ```ruby
 ActiveSupport::Notifications.subscribe("render.react-email-rails") do |event|

data/lib/react_email_rails/render_modes/persistent/server.rb

@@ -81,6 +81,7 @@ class ReactEmailRails::RenderModes::Persistent::Server
         body[:html] = response["html"] if response.key?("html")
         body[:text] = response["text"] if response.key?("text")
         body[:warnings] = response["warnings"] if response.key?("warnings")
+        body[:document] = response["document"] if response.key?("document")
       end,
     ))
   rescue JSON::ParserError => e

data/lib/react_email_rails/render_modes/subprocess.rb

@@ -10,9 +10,12 @@ class ReactEmailRails::RenderModes::Subprocess
 
   # Payload-agnostic transport: the caller builds and serializes the payload.
   # `label` identifies the render in error messages (component name or document type).
-  def initialize(payload:, label:)
+  # `response` selects how the renderer's reply is interpreted: `:email` builds a
+  # RenderedEmail (render/compose), `:document` returns the parsed document (parse).
+  def initialize(payload:, label:, response: :email)
     @payload = payload
     @label = label
+    @response = response
   end
 
   def render
@@ -21,15 +24,15 @@ class ReactEmailRails::RenderModes::Subprocess
 
   private
 
-  attr_reader(:payload, :label)
+  attr_reader(:payload, :label, :response)
 
   def run
     result = capture(payload_json)
     raise(render_error(error_message(result.stderr, result.status))) unless result.status.success?
 
     body = JSON.parse(result.stdout)
-    validate_response!(body)
-    ReactEmailRails::RenderedEmail.new(html: body.fetch("html"), text: body["text"].to_s, warnings: warnings_from(body))
+    validate_metadata!(body)
+    build_result(body)
   rescue JSON::ParserError => e
     raise(render_error("render process returned invalid JSON: #{e.message}"))
   rescue KeyError => e
@@ -75,12 +78,31 @@ class ReactEmailRails::RenderModes::Subprocess
     raise(render_error("email bundle not found at #{bundle_path.inspect}; run react-email-rails-build before rendering React emails"))
   end
 
-  def validate_response!(body)
-    raise(render_error(ReactEmailRails::RenderProtocol.mismatch_message(body))) unless ReactEmailRails::RenderProtocol.compatible_metadata?(body)
+  def validate_metadata!(body)
+    return if ReactEmailRails::RenderProtocol.compatible_metadata?(body)
+
+    raise(render_error(ReactEmailRails::RenderProtocol.mismatch_message(body)))
+  end
+
+  def build_result(body)
+    response == :document ? build_document(body) : build_rendered_email(body)
+  end
 
+  def build_rendered_email(body)
     raise(KeyError.new(key: "html")) unless body.key?("html")
     raise(render_error("render process returned an invalid response: html must be a string")) unless body["html"].is_a?(String)
     raise(render_error("render process returned an invalid response: text must be a string")) if body.key?("text") && !body["text"].is_a?(String)
+
+    ReactEmailRails::RenderedEmail.new(html: body.fetch("html"), text: body["text"].to_s, warnings: warnings_from(body))
+  end
+
+  def build_document(body)
+    raise(KeyError.new(key: "document")) unless body.key?("document")
+
+    document = body.fetch("document")
+    raise(render_error("parse process returned an invalid response: document must be an object")) unless document.is_a?(Hash)
+
+    document
   end
 
   def warnings_from(body)

data/lib/react_email_rails/render_protocol.rb

@@ -1,5 +1,5 @@
 module ReactEmailRails
-  RENDER_PROTOCOL_VERSION = 2
+  RENDER_PROTOCOL_VERSION = 3
 
   module RenderProtocol
     extend(self)

data/lib/react_email_rails/version.rb

@@ -1,3 +1,3 @@
 module ReactEmailRails
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/react_email_rails.rb

@@ -67,6 +67,23 @@ module ReactEmailRails
       raise
     end
 
+    # Parse HTML into an editor document Hash using the renderer's extensions.
+    def parse(type:, html:, context: {})
+      payload = {
+        kind: "parse",
+        type:,
+        html: html.to_s,
+        context: serialized_props(context),
+      }
+
+      instrument(kind: "parse", type:) do
+        configuration.resolved_render_mode.new(payload:, label: type, response: :document).render
+      end
+    rescue ReactEmailRails::RenderError => e
+      configuration.on_render_error&.call(e, kind: "parse", type:)
+      raise
+    end
+
     def healthy?
       configuration.resolved_render_mode.healthy?(
         command: configuration.send(:resolved_render_command),
@@ -84,9 +101,11 @@ module ReactEmailRails
 
     def instrument(**metadata)
       ActiveSupport::Notifications.instrument("render.react-email-rails", **metadata) do |payload|
-        yield.tap do |rendered|
-          payload[:html_bytes] = rendered.html.bytesize
-          payload[:warnings] = rendered.warnings if rendered.warnings.present?
+        yield.tap do |result|
+          next unless result.respond_to?(:html)
+
+          payload[:html_bytes] = result.html.bytesize
+          payload[:warnings] = result.warnings if result.warnings.present?
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react-email-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Supertape