react-email-rails 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05b64507c82feabb25781eaec8487c5e7282f65060abbac88719bfb2bc79d499
-  data.tar.gz: fc1f7fe4d40195537b5218818aa0fb8b72be78834238223dc377c52f7843af15
+  metadata.gz: 4bbfbb40c2044856c9061ba2a3c134d07dbd5aa9b58b6cfe3d576d25fe45b4d2
+  data.tar.gz: 7c272a65e71044f813c813b248a48bc69e3a043494ad9f6133ae8c69ab006b24
 SHA512:
-  metadata.gz: 61afe5bf3fc51e550ca9608bd91deeeb9794cd4a90bac53a7bf0fb48f2f12f5984f50dadbbd245c05e34d8dc4ab7c478f2ff8420aa94e9f57c98e39fb04bab01
-  data.tar.gz: 992fd9253d2a2cf31f9ecd37f7bd960c52efddaf74541aefa5ed124ebef4941d9404c00d7f417a6cc2d36f998d3391d8f1bf3ec3d865ec232c43c5a2df2ed4c1
+  metadata.gz: c5b434f0983a8c1280d622203869f535a0c98fb293bcfff3d51d39a8676d730d000b901cb9bcc6b3b478fe633904974798131482e44982140f40e12951ac1423
+  data.tar.gz: 21652f85cc0ee448ec90ffd7b24c4eaf05b892dbe0e83d487777ae57bbcda7a34c46e1b9becad9174838edd0d33919b11aa9efb56cbd520433803c8a3fd82385

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.5.0
+
+- Add `react_email_share` for sharing props across every `react:` email a mailer renders, mirroring inertia-rails' `inertia_share`. Supports static values, lazy lambdas and blocks (evaluated in the mailer instance), `only`/`except`/`if`/`unless` filters, and subclass inheritance. Per-mail props win over shared props.
+- Shared props merge shallowly by default. Pass `deep_merge: true` to `mail` to merge nested hashes, or set `config.deep_merge_shared_props = true` to make it the default.
+
 ## 0.4.1
 
 - `ReactEmailRails.parse` now neutralizes unsafe link/button URI schemes: hrefs whose scheme is not `http`, `https`, `mailto`, or `tel` (e.g. `javascript:`/`data:`) are blanked before they reach the document `Hash`. Scheme detection ignores the whitespace and control characters browsers strip when resolving a scheme, so case- and whitespace-obfuscated payloads are caught too.

data/README.md

@@ -33,7 +33,7 @@ react-email-rails automatically renders both HTML and plain-text versions from t
 
 ## Status
 
-**react-email-rails is pre-1.0.** It's tested in CI across the supported Ruby, Rails, Node, and Vite versions, but it hasn't been battle-tested in high-volume production environments yet, and the API may still change before 1.0. Please [share feedback and report issues](https://github.com/heysupertape/react-email-rails/issues).
+**react-email-rails is pre-1.0.** It was extracted from [XOXO](https://xoxo.email) which is pre-launch, so it hasn't been battle-tested in high-volume production environments yet. It's tested in CI across the supported Ruby, Rails, Node, and Vite versions, but the API may still change before 1.0. Please [share feedback and report issues](https://github.com/heysupertape/react-email-rails/issues).
 
 ## Requirements
 
@@ -160,7 +160,7 @@ That's it. It now renders and delivers like any other Action Mailer email.
 
 ## Usage
 
-Pass data from your mailer. Each top-level key becomes a prop on the component's default export.
+Pass data from your mailer and each top-level key becomes a prop on the component's default export. Our API mirrors [inertia-rails](https://inertia-rails.dev), making the two libraries feel consistent when used together.
 
 ```ruby
 mail react: { foo: "bar" }, ...
@@ -172,9 +172,11 @@ export default function Email({ foo }: { foo: string }) {
 }
 ```
 
-Choose the level of inference you want:
+### Props
 
-### Implicit Component, Instance Props
+Choose the level of inference you want for your props:
+
+#### Implicit Component, Instance Props
 
 ```ruby
 class AccountMailer < ApplicationMailer
@@ -191,7 +193,7 @@ Action Mailer's framework assigns (including `params` and `rendered_format`) are
 
 Without `use_react_instance_props`, `react: true` still infers the component and renders it with no props, which is handy for emails that take no props at all.
 
-### Implicit Component, Explicit Props
+#### Implicit Component, Explicit Props
 
 ```ruby
 mail(
@@ -204,7 +206,7 @@ mail(
 )
 ```
 
-### Explicit Component, Explicit Props
+#### Explicit Component, Explicit Props
 
 ```ruby
 mail(
@@ -218,7 +220,81 @@ mail(
 )
 ```
 
-These forms mirror [inertia-rails](https://inertia-rails.dev), making the two libraries feel consistent when used together.
+### Shared Props
+
+Use `react_email_share` to share data with all of a mailer's emails and subclasses, and it'll be automatically merged with any inline props.
+
+```ruby
+class MarketingMailer < ApplicationMailer
+  # Static value
+  react_email_share app_name: "Acme"
+
+  # Lambda value, evaluated lazily in the mailer instance
+  react_email_share unread_count: -> { current_user&.unread_count }
+
+  # Block, evaluated lazily in the mailer instance
+  react_email_share do
+    { brand: { name: "Acme", url: marketing_url } }
+  end
+end
+```
+
+Per-mail props win over shared props of the same name, so a mailer can always override what it inherits:
+
+```ruby
+mail react: { app_name: "Acme Pro" }, ... # overrides the shared app_name
+```
+
+Shared props apply to all three forms above (`react:` hash, `react: "component", props:`, and `react: true`).
+
+#### Conditional Sharing
+
+Pass any `before_action` filter (`only`, `except`, `if`, `unless`) to scope a share to certain actions:
+
+```ruby
+react_email_share only: [:welcome, :reactivation] do
+  { promotion: current_promotion }
+end
+
+react_email_share if: :user_signed_in? do
+  { user: { name: current_user.name } }
+end
+```
+
+You can also share from inside an action, before calling `mail`:
+
+```ruby
+def welcome
+  react_email_share notice: "Thanks for joining!"
+  mail react: { account: }, to: account.email, subject: "Welcome"
+end
+```
+
+#### Deep Merging
+
+By default shared props are merged shallowly, so a per-mail prop replaces a shared one of the same name outright. Pass `deep_merge: true` to merge nested hashes instead:
+
+```ruby
+react_email_share do
+  { settings: { theme: "light", locale: "en" } }
+end
+
+# Shallow (default): settings => { theme: "dark" }
+mail react: { settings: { theme: "dark" } }, ...
+
+# Deep: settings => { theme: "dark", locale: "en" }
+mail react: { settings: { theme: "dark" } }, deep_merge: true, ...
+```
+
+Set `config.deep_merge_shared_props = true` to make deep merging the default for every email. (See [Configuration](#configuration))
+
+### Prop Serialization
+
+Like `render json:`, `mail react:` accepts any object that responds to `as_json`, including hashes, Active Model objects, and serializers such as [Alba](https://github.com/okuramasafumi/alba) or [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers).
+
+### Prop Transformation
+
+Prop keys are camelized by default, so `account.plan_name` arrives as `account.planName`. Override `transform_props` in your [configuration](#configuration).
 
 ### Component Names
 
@@ -241,14 +317,6 @@ mail react: "users/welcome", props: { user: }, to:, subject:
 
 Or override `component_path_resolver` globally in your [configuration](#configuration).
 
-### Prop Serialization
-
-Like `render json:`, `mail react:` accepts any object that responds to `as_json`, including hashes, Active Model objects, and serializers such as [Alba](https://github.com/okuramasafumi/alba) or [ActiveModel::Serializer](https://github.com/rails-api/active_model_serializers).
-
-### Prop Transformation
-
-Prop keys are camelized by default, so `account.plan_name` arrives as `account.planName`. Override `transform_props` in your [configuration](#configuration).
-
 ### Layouts
 
 Action Mailer layouts aren't applied to `react:` emails. React Email treats layouts like any other component, so share structure with normal React composition instead:
@@ -314,6 +382,7 @@ If the defaults don't fit, override them in `config/initializers/react_email_rai
 | `render_timeout` | `10` seconds |
 | `render_process_max_requests` | `1_000` |
 | `on_render_error` | `nil` |
+| `deep_merge_shared_props` | `false` |
 
 #### Prop Transformation
 

data/lib/react_email_rails/action_mailer.rb

@@ -1,6 +1,9 @@
 module ReactEmailRails::ActionMailer
   extend(ActiveSupport::Concern)
 
+  # `react_email_share` kwargs reserved for `before_action` filtering, not prop data.
+  SHARED_FILTER_OPTIONS = [:if, :unless, :only, :except].freeze
+
   prepended do
     class_attribute(:react_email_use_instance_props, default: false)
   end
@@ -9,6 +12,22 @@ module ReactEmailRails::ActionMailer
     def use_react_instance_props
       self.react_email_use_instance_props = true
     end
+
+    # Share props with every `react:` email this mailer and its subclasses render.
+    # Mirrors inertia-rails `inertia_share`; `only`/`except`/`if`/`unless` go to `before_action`.
+    def react_email_share(hash = nil, **props, &block)
+      options = props.slice(*SHARED_FILTER_OPTIONS)
+      data = hash || props.except(*SHARED_FILTER_OPTIONS)
+
+      before_action(**options) do
+        react_email_append_shared(data, block)
+      end
+    end
+  end
+
+  # Share props from within an action, e.g. conditionally before calling `mail`.
+  def react_email_share(hash = nil, **props, &block)
+    react_email_append_shared(hash || props, block)
   end
 
   def mail(headers = {}, &block)
@@ -17,8 +36,13 @@ module ReactEmailRails::ActionMailer
     headers = headers.dup
     react = headers.delete(:react)
     props = headers.delete(:props) if headers.key?(:props)
+    deep_merge = headers.delete(:deep_merge) if headers.key?(:deep_merge)
 
     component, resolved_props = ReactEmailRails::PropsResolver.new(self).resolve(react, props)
+    resolved_props = ReactEmailRails::SharedProps.new(self).merge_into(
+      resolved_props,
+      deep_merge: react_email_deep_merge?(deep_merge),
+    )
     render_options = ReactEmailRails.configuration.resolve_render_options(self)
     rendered = ReactEmailRails.render(component:, props: resolved_props, render_options:)
 
@@ -28,4 +52,18 @@ module ReactEmailRails::ActionMailer
       yield(format) if block
     end
   end
+
+  private
+
+  def react_email_append_shared(data, block)
+    store = (@_react_email_shared ||= [])
+    store << data.dup.freeze if data.present?
+    store << block if block
+  end
+
+  def react_email_deep_merge?(override)
+    return ReactEmailRails.configuration.deep_merge_shared_props if override.nil?
+
+    override
+  end
 end

data/lib/react_email_rails/configuration.rb

@@ -34,6 +34,7 @@ class ReactEmailRails::Configuration
     :render_options,
     :transform_props,
     :on_render_error,
+    :deep_merge_shared_props,
   )
 
   attr_reader(
@@ -52,6 +53,7 @@ class ReactEmailRails::Configuration
         config.render_process_max_requests = DEFAULT_RENDER_PROCESS_MAX_REQUESTS
         config.transform_props = :lower_camel
         config.on_render_error = nil
+        config.deep_merge_shared_props = false
       end
     end
   end

data/lib/react_email_rails/shared_props.rb

@@ -0,0 +1,44 @@
+# Collects props registered with `react_email_share` and merges them beneath the
+# per-mail props, which win on conflict. Mirrors inertia-rails shared data.
+class ReactEmailRails::SharedProps
+  IVAR = :@_react_email_shared
+
+  def initialize(mailer)
+    @mailer = mailer
+  end
+
+  # Returns `props` untouched when nothing is shared, so non-Hash inputs (e.g.
+  # serializers) still flow straight through to serialization.
+  def merge_into(props, deep_merge:)
+    shared = to_h
+    return props if shared.empty?
+
+    base = shared.as_json
+    incoming = props.as_json
+    deep_merge ? base.deep_merge(incoming) : base.merge(incoming)
+  end
+
+  def to_h
+    entries.each_with_object({}) do |entry, props|
+      props.merge!(resolve(entry))
+    end
+  end
+
+  private
+
+  attr_reader(:mailer)
+
+  def entries
+    mailer.instance_variable_get(IVAR) || []
+  end
+
+  # An entry is either a static Hash or a block evaluated at render time. Callable
+  # values inside a Hash are evaluated too, so `unread_count: -> { ... }` works.
+  def resolve(entry)
+    hash = entry.respond_to?(:call) ? mailer.instance_exec(&entry) : entry
+
+    (hash || {}).transform_values do |value|
+      value.respond_to?(:call) ? mailer.instance_exec(&value) : value
+    end
+  end
+end

data/lib/react_email_rails/version.rb

@@ -1,3 +1,3 @@
 module ReactEmailRails
-  VERSION = "0.4.1"
+  VERSION = "0.5.0"
 end

data/lib/react_email_rails.rb

@@ -5,6 +5,7 @@ require("active_support/concern")
 require("active_support/notifications")
 require("active_support/core_ext/object/blank")
 require("active_support/core_ext/object/json")
+require("active_support/core_ext/hash/deep_merge")
 require("active_support/inflector")
 require("rails/railtie")
 
@@ -24,6 +25,7 @@ require_relative("react_email_rails/render_modes/persistent/command_runner")
 require_relative("react_email_rails/configuration")
 require_relative("react_email_rails/tasks")
 require_relative("react_email_rails/props_resolver")
+require_relative("react_email_rails/shared_props")
 require_relative("react_email_rails/railtie")
 
 module ReactEmailRails

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react-email-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Supertape
@@ -164,6 +164,7 @@ files:
 - lib/react_email_rails/render_modes/subprocess/command_runner.rb
 - lib/react_email_rails/render_protocol.rb
 - lib/react_email_rails/rendered_email.rb
+- lib/react_email_rails/shared_props.rb
 - lib/react_email_rails/tasks.rb
 - lib/react_email_rails/version.rb
 - lib/tasks/react_email_rails/build.rake