rails_email 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d450b660f8baa8e70bc9d9782b1ac175b433f56980805bd27c6249364afa5ee1
+  data.tar.gz: 80d17908c3b8956837271e69c1f8254ec3772b5f8f58211311a643da598703a6
+SHA512:
+  metadata.gz: 847d2b04921e10073d2ec4ec29423109454886d86b67222f0a41c31df5e8ae87e94fcf3a1a91a340866c73908cedc8c6fd4abd020be5a91c59763265f8381485
+  data.tar.gz: c852dcfce91392fd8e55483077764e0da719323fe7daee0a5f38312babe14e4580655c128619cb981363234cb8250e09056d708ca86556d7db9ad59011cacbdc

data/README.md

@@ -0,0 +1,159 @@
+# RailsEmail
+
+A polished mailer preview UI for Rails — inspired by [React Email](https://react.email). Drop it in and your `/rails/mailers` preview route gets a modern dark/light interface with viewport controls, source inspection, CSS compatibility checks, and spam scoring.
+
+Zero configuration. No build step. Works with your existing `ActionMailer::Preview` classes.
+
+---
+
+## Features
+
+- **Dark & light theme** — toggle anytime, preference saved in localStorage
+- **Dark mode email rendering** — LCH-based color inversion (same algorithm as React Email)
+- **Viewport presets** — Mobile (375px), Tablet (768px), Desktop (1280px), Email (600px), or custom
+- **Source viewer** — toggle between rendered preview and raw HTML / plain-text source
+- **Headers panel** — view From, To, Subject, Date, Reply-To, CC, BCC at a glance
+- **CSS compatibility checker** — detects unsupported properties (Flexbox, Grid, CSS variables, animations…) with the affected clients listed
+- **Spam score** — runs your email through Postmark's SpamAssassin API and shows a score out of 10
+- **Download as .eml** — grab the full RFC 822 message for local testing
+- **Locale selector** — switch preview locale without leaving the page
+- **Collapsible sidebar** — more room for your email when you need it
+
+---
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails >= 7.0
+- ActionMailer previews enabled (`config.action_mailer.show_previews = true` in development)
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "rails_email"
+```
+
+Then run:
+
+```
+bundle install
+```
+
+That's it. No generators, no initializers, no configuration files needed.
+
+> **Note:** Make sure `config.action_mailer.show_previews = true` is set in `config/environments/development.rb`. Rails enables this by default in development, so you probably don't need to touch anything.
+
+---
+
+## Usage
+
+Start your Rails server and visit:
+
+```
+http://localhost:3000/rails/mailers
+```
+
+Your existing `ActionMailer::Preview` classes appear in the left sidebar. Click any email action to open the preview.
+
+### Preview classes
+
+RailsEmail works with standard ActionMailer previews. Place them in `test/mailers/previews/` (or wherever `config.action_mailer.preview_paths` points):
+
+```ruby
+# test/mailers/previews/user_mailer_preview.rb
+class UserMailerPreview < ActionMailer::Preview
+  def welcome_email
+    UserMailer.with(user: User.first).welcome_email
+  end
+
+  def password_reset
+    UserMailer.with(user: User.first).password_reset
+  end
+end
+```
+
+### Spam check
+
+The Spam tab sends the full RFC 822 message (headers + body) to [Postmark's SpamAssassin API](https://spamcheck.postmarkapp.com). No API key required. An internet connection is needed when running the check.
+
+The score is displayed as **X / 10** (higher is better). The individual SpamAssassin rules that fired are shown below the score, sorted by impact.
+
+---
+
+## Tabs reference
+
+| Tab | What it shows |
+|---|---|
+| **Headers** | From, To, Subject, Date, Reply-To, CC, BCC; locale switcher |
+| **Compatibility** | CSS properties in the email that are unsupported by major clients |
+| **Spam** | SpamAssassin score and the rules that contributed to it |
+| **Attachments** | Files attached to the email with download links |
+
+---
+
+## Keyboard / UI controls
+
+| Control | Action |
+|---|---|
+| Sidebar toggle (☰) | Collapse / expand the mailer list |
+| Preview / Source buttons | Switch between rendered and raw views |
+| Desktop / Mobile buttons | Switch between full-width and 375 px mobile viewport |
+| Viewport dropdown | Fine-grained presets: Mobile, Tablet, Desktop, Email (600 px), Custom |
+| Theme toggle (☀/☾) | Switch dark ↔ light; saved across sessions |
+| ↓ Download | Download the email as an `.eml` file |
+| ∨ (panel header) | Collapse / expand the bottom info panel |
+
+---
+
+## How it works
+
+RailsEmail is a Rails Engine that:
+
+1. Prepends its own views to `Rails::MailersController`, replacing the default preview templates without touching the controller itself.
+2. Adds a single new route — `GET /rails/mailers/spam_check/*path` — prepended before ActionMailer's wildcard so it is matched first.
+3. Includes a controller extension that handles the spam check request: it calls your preview, serialises the result to a full RFC 822 string via `email.to_s`, and forwards it to Postmark's SpamAssassin API over TLS.
+
+No monkey-patching, no middleware, no asset pipeline involvement. Everything is rendered as inline ERB (CSS and JS embedded in partials).
+
+---
+
+## Development
+
+Clone the repo and install dependencies:
+
+```bash
+git clone https://github.com/your-org/rails_email.git
+cd rails_email
+bundle install
+```
+
+The `test/dummy` directory contains a minimal Rails app with sample mailers. Run it with:
+
+```bash
+cd test/dummy
+bundle exec rails server
+```
+
+Then open `http://localhost:3000/rails/mailers`.
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b my-feature`)
+3. Commit your changes (`git commit -m 'Add my feature'`)
+4. Push to the branch (`git push origin my-feature`)
+5. Open a pull request
+
+Please keep changes focused. Bug fixes and improvements to existing features are welcome. For larger changes, open an issue first to discuss the approach.
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE) for details.

data/app/views/rails/mailers/_scripts.html.erb

@@ -0,0 +1,344 @@
+<%# colorjs for dark-mode color inversion — same approach as React Email %>
+<script src="https://cdn.jsdelivr.net/npm/colorjs.io/dist/color.legacy.min.js"></script>
+
+<script>
+(function () {
+
+  // ── Theme ────────────────────────────────────────────────
+  var savedTheme = localStorage.getItem("rm_theme") || "dark";
+  document.documentElement.dataset.theme = savedTheme;
+
+  window.rmToggleTheme = function () {
+    var html   = document.documentElement;
+    var isDark = html.dataset.theme === "dark";
+    html.dataset.theme = isDark ? "light" : "dark";
+    localStorage.setItem("rm_theme", isDark ? "light" : "dark");
+    var moon = document.getElementById("rm-icon-moon");
+    var sun  = document.getElementById("rm-icon-sun");
+    if (moon) moon.classList.toggle("hidden", isDark);
+    if (sun)  sun.classList.toggle("hidden",  !isDark);
+    rmApplyDarkMode(!isDark);
+  };
+
+  document.addEventListener("DOMContentLoaded", function () {
+    if (savedTheme === "light") {
+      var moon = document.getElementById("rm-icon-moon");
+      var sun  = document.getElementById("rm-icon-sun");
+      if (moon) moon.classList.add("hidden");
+      if (sun)  sun.classList.remove("hidden");
+    }
+    // Apply dark mode inversion on initial load if dark theme active
+    var iframe = document.getElementById("rm-email-frame");
+    if (iframe) {
+      iframe.addEventListener("load", function () {
+        if (document.documentElement.dataset.theme === "dark") {
+          rmApplyDarkMode(true);
+        }
+      });
+    }
+  });
+
+  // ── Dark mode: colorjs LCH inversion (React Email algorithm) ─
+  function* walkDom(node) {
+    if (node.nodeType === 1) yield node;
+    for (var c of Array.from(node.childNodes)) yield* walkDom(c);
+  }
+
+  function invertLch(colorStr, isBg) {
+    if (!colorStr || colorStr === "transparent" || colorStr === "rgba(0, 0, 0, 0)") return null;
+    try {
+      var c   = new Color(colorStr).to("lch");
+      var l   = c.l;
+      var newL = isBg
+        ? (l >= 50 ? 50 - (l - 50) * 0.75 : 50 + (50 - l) * 0.75)
+        : (l <  50 ? 50 + (50 - l) * 0.75 : 50 - (l - 50) * 0.75);
+      c.l = Math.max(0, Math.min(100, newL));
+      c.c = Math.max(0, c.c * 0.8);
+      return c.to("srgb").toString({ format: "hex" });
+    } catch (e) { return null; }
+  }
+
+  window.rmApplyDarkMode = function (isDark) {
+    var iframe = document.getElementById("rm-email-frame");
+    if (!iframe || !iframe.contentDocument || !iframe.contentDocument.body) return;
+    var doc = iframe.contentDocument;
+
+    if (!isDark) {
+      // Restore originals
+      for (var el of walkDom(doc.body)) {
+        if (el.dataset.rmBg !== undefined) { el.style.backgroundColor = el.dataset.rmBg; delete el.dataset.rmBg; }
+        if (el.dataset.rmFg !== undefined) { el.style.color            = el.dataset.rmFg; delete el.dataset.rmFg; }
+      }
+      doc.documentElement.style.colorScheme = "";
+      return;
+    }
+
+    doc.documentElement.style.colorScheme = "dark";
+
+    if (typeof Color === "undefined") return; // CDN not loaded
+
+    var view = doc.defaultView || iframe.contentWindow;
+    for (var el of walkDom(doc.body)) {
+      var s = view.getComputedStyle(el);
+
+      var bg = s.backgroundColor;
+      if (bg && bg !== "rgba(0, 0, 0, 0)") {
+        el.dataset.rmBg = el.style.backgroundColor || "";
+        var invBg = invertLch(bg, true);
+        if (invBg) el.style.backgroundColor = invBg;
+      }
+
+      var fg = s.color;
+      if (fg && fg !== "rgba(0, 0, 0, 0)") {
+        el.dataset.rmFg = el.style.color || "";
+        var invFg = invertLch(fg, false);
+        if (invFg) el.style.color = invFg;
+      }
+    }
+  };
+
+  // ── Sidebar ──────────────────────────────────────────────
+  window.rmToggleSidebar = function () {
+    var s = document.getElementById("rm-sidebar");
+    if (s) s.classList.toggle("collapsed");
+  };
+
+  // ── View (preview ↔ source) ──────────────────────────────
+  window.rmSetView = function (view) {
+    var vP = document.getElementById("rm-view-preview");
+    var vS = document.getElementById("rm-view-source");
+    var bP = document.getElementById("rm-btn-preview");
+    var bS = document.getElementById("rm-btn-source");
+    if (vP) vP.classList.toggle("hidden", view !== "preview");
+    if (vS) vS.classList.toggle("hidden", view !== "source");
+    if (bP) bP.classList.toggle("active", view === "preview");
+    if (bS) bS.classList.toggle("active", view === "source");
+  };
+
+  // ── Viewport size ────────────────────────────────────────
+  var _vpOpen = false;
+
+  window.rmToggleViewportDropdown = function (e) {
+    e.stopPropagation();
+    _vpOpen = !_vpOpen;
+    var p = document.getElementById("rm-viewport-panel");
+    if (p) p.classList.toggle("hidden", !_vpOpen);
+  };
+
+  document.addEventListener("click", function (e) {
+    if (!e.target.closest("#rm-size-group")) {
+      var p = document.getElementById("rm-viewport-panel");
+      if (p) p.classList.add("hidden");
+      _vpOpen = false;
+    }
+  });
+
+  window.rmApplyPreset = function (name, w, h) {
+    var iframe = document.getElementById("rm-email-frame");
+    var stage  = document.getElementById("rm-stage");
+    if (!iframe) return;
+
+    // Width
+    if (w) {
+      iframe.style.width    = w + "px";
+      iframe.style.maxWidth = w + "px";
+      if (stage) stage.style.alignItems = "flex-start";
+    } else {
+      iframe.style.width    = "100%";
+      iframe.style.maxWidth = "";
+      if (stage) stage.style.alignItems = "";
+    }
+
+    // Height
+    if (h) {
+      iframe.style.height = h + "px";
+    } else {
+      iframe.style.height = "100%";
+    }
+
+    // Update preset active states
+    document.querySelectorAll(".rm-vp-preset").forEach(function (btn) {
+      btn.classList.toggle("rm-vp-active", btn.dataset.preset === name);
+    });
+
+    // Sync desktop / mobile quick buttons
+    var bD = document.getElementById("rm-btn-desktop");
+    var bM = document.getElementById("rm-btn-mobile");
+    if (bD) bD.classList.toggle("active", !w);
+    if (bM) bM.classList.toggle("active", w === 375);
+
+    localStorage.setItem("rm_vp", JSON.stringify({ name: name, w: w, h: h }));
+
+    // Close dropdown
+    var panel = document.getElementById("rm-viewport-panel");
+    if (panel) panel.classList.add("hidden");
+    _vpOpen = false;
+  };
+
+  window.rmApplyCustomViewport = function () {
+    var wv = parseInt(document.getElementById("rm-vp-w").value, 10) || null;
+    var hv = parseInt(document.getElementById("rm-vp-h").value, 10) || null;
+    rmApplyPreset("Custom", wv, hv);
+  };
+
+  window.rmSetSize = function (size) {
+    if (size === "mobile") rmApplyPreset("Mobile", 375, null);
+    else                   rmApplyPreset("Full",   null, null);
+  };
+
+  // Restore saved viewport
+  document.addEventListener("DOMContentLoaded", function () {
+    var saved = localStorage.getItem("rm_vp");
+    if (saved) { try { var vp = JSON.parse(saved); rmApplyPreset(vp.name, vp.w, vp.h); } catch (e) {} }
+  });
+
+  // ── Source sub-tabs ──────────────────────────────────────
+  window.rmSetSourceTab = function (id, btn) {
+    document.querySelectorAll(".rm-source-body").forEach(function (el) { el.classList.add("hidden"); });
+    document.querySelectorAll(".rm-source-tab").forEach(function (el) { el.classList.remove("active"); });
+    var el = document.getElementById(id);
+    if (el) el.classList.remove("hidden");
+    btn.classList.add("active");
+  };
+
+  // ── Bottom panel tabs ────────────────────────────────────
+  window.rmSetBottomTab = function (id, btn) {
+    document.querySelectorAll(".rm-tab-content").forEach(function (el) { el.classList.remove("active"); });
+    document.querySelectorAll(".rm-bottom-tab").forEach(function (el) { el.classList.remove("active"); });
+    var el = document.getElementById(id);
+    if (el) el.classList.add("active");
+    btn.classList.add("active");
+  };
+
+  // ── Bottom panel collapse ────────────────────────────────
+  var _panelOpen = true;
+  window.rmTogglePanel = function () {
+    _panelOpen = !_panelOpen;
+    var body = document.getElementById("rm-panel-body");
+    var icon = document.getElementById("rm-collapse-icon");
+    if (body) body.classList.toggle("hidden", !_panelOpen);
+    if (icon) icon.style.transform = _panelOpen ? "" : "rotate(180deg)";
+  };
+
+  // ── Compatibility check ──────────────────────────────────
+  var RM_COMPAT = [
+    { prop: "border-radius",    rx: /border-radius/i,                     clients: "Outlook 2007–21, Outlook.com" },
+    { prop: "box-sizing",       rx: /box-sizing/i,                         clients: "Gmail, Outlook 2007–21, Yahoo Mail" },
+    { prop: "overflow",         rx: /\boverflow\s*:/i,                     clients: "Outlook 2007–21" },
+    { prop: "word-break",       rx: /word-break/i,                         clients: "Outlook 2007–21, Yahoo Mail" },
+    { prop: "display: flex",    rx: /display\s*:\s*flex/i,                  clients: "Outlook 2007–21, Gmail (webmail)" },
+    { prop: "display: grid",    rx: /display\s*:\s*grid/i,                  clients: "Outlook 2007–21, Gmail, Yahoo Mail" },
+    { prop: "CSS variables",    rx: /var\s*\(/i,                            clients: "Outlook 2007–21, Gmail, Yahoo Mail" },
+    { prop: "position (fixed)", rx: /position\s*:\s*(fixed|sticky)/i,      clients: "Gmail, Outlook.com, Yahoo Mail" },
+    { prop: "opacity",          rx: /\bopacity\s*:/i,                       clients: "Outlook 2007–16" },
+    { prop: "text-shadow",      rx: /text-shadow/i,                         clients: "Outlook 2007–21" },
+    { prop: "animation",        rx: /\banimation\b/i,                       clients: "Outlook 2007–21, Gmail, Yahoo Mail" },
+    { prop: "transform",        rx: /\btransform\s*:/i,                     clients: "Outlook 2007–21, Gmail" },
+    { prop: "filter",           rx: /\bfilter\s*:/i,                        clients: "Outlook 2007–21, Gmail" },
+    { prop: "background-size",  rx: /background-size/i,                     clients: "Outlook 2007–21" },
+    { prop: "min-height",       rx: /min-height/i,                          clients: "Outlook 2007–21" },
+    { prop: "object-fit",       rx: /object-fit/i,                          clients: "Outlook 2007–21, Gmail" },
+    { prop: "letter-spacing",   rx: /letter-spacing/i,                      clients: "Outlook 2007–21" },
+    { prop: "@font-face",       rx: /@font-face/i,                          clients: "Gmail, Yahoo Mail, Outlook 2007–21" },
+    { prop: "@media queries",   rx: /@media/i,                              clients: "Gmail (webmail), Outlook 2007–03" },
+  ];
+
+  window.rmRunCompatibilityCheck = function () {
+    var box = document.getElementById("rm-compat-content");
+    if (!box) return;
+
+    var iframe = document.getElementById("rm-email-frame");
+    if (!iframe || !iframe.contentDocument || !iframe.contentDocument.body) {
+      box.innerHTML = '<p class="rm-check-error">No email loaded.</p>';
+      return;
+    }
+
+    var doc  = iframe.contentDocument;
+    var css  = Array.from(doc.querySelectorAll("style")).map(function (s) { return s.textContent || ""; }).join("\n");
+    var inl  = Array.from(doc.querySelectorAll("[style]")).map(function (el) { return el.getAttribute("style") || ""; }).join("\n");
+    var text = css + "\n" + inl;
+
+    var issues = RM_COMPAT.filter(function (r) { return r.rx.test(text); });
+
+    if (issues.length === 0) {
+      box.innerHTML = '<div class="rm-check-ok"><div class="rm-check-ok-icon">✓</div><strong>Great compatibility</strong><p>No known issues detected.</p></div>';
+      return;
+    }
+
+    var rows = issues.map(function (r) {
+      return "<tr><td class='rm-compat-prop'>⚠ " + r.prop + "</td><td class='rm-compat-clients'>Not supported in " + r.clients + "</td></tr>";
+    }).join("");
+    box.innerHTML = "<table class='rm-compat-table'>" + rows + "</table>";
+  };
+
+  // ── Spam check (Postmark / SpamAssassin) ─────────────────
+  window.rmRunSpamCheck = function (path) {
+    var box = document.getElementById("rm-spam-content");
+    if (!box) return;
+    box.innerHTML = '<div class="rm-check-loading"><span>Checking…</span></div>';
+
+    fetch("/rails/mailers/spam_check/" + path)
+      .then(function (r) { return r.json(); })
+      .then(function (data) {
+        if (data.error) {
+          box.innerHTML = '<p class="rm-check-error">⚠ ' + data.error + '</p>';
+          return;
+        }
+
+        var score        = parseFloat(data.score) || 0;
+        var displayScore = Math.round(Math.max(0, 10 - score) * 10) / 10;
+        var iconClass    = score < 1.5 ? "" : score < 3 ? "rm-check-ok-icon--warn" : "rm-check-ok-icon--danger";
+        var label        = score < 1.5 ? "Clean email" : score < 3 ? "Low spam risk" : "Spam issues detected";
+
+        var header = '<div class="rm-check-ok">' +
+          '<div class="rm-check-ok-icon ' + iconClass + '">' + displayScore + '/10</div>' +
+          '<strong>' + label + '</strong>' +
+          '<p>SpamAssassin score: ' + score + '</p>' +
+          '</div>';
+
+        var rows = "";
+        if (data.rules && data.rules.length) {
+          var sorted = data.rules.slice().sort(function (a, b) { return parseFloat(b.score) - parseFloat(a.score); });
+          var actionable = sorted.filter(function (r) {
+            var desc = (r.description || r.name || "");
+            return !desc.startsWith("ADMINISTRATOR NOTICE") &&
+                   !desc.startsWith("Informational:");
+          });
+          rows = "<table class='rm-spam-table'>" +
+            actionable.map(function (r) {
+              return "<tr><td class='rm-spam-points'>" + r.score + "</td><td class='rm-spam-desc'>" + (r.description || r.name || "") + "</td></tr>";
+            }).join("") +
+            "</table>";
+        }
+
+        box.innerHTML = header + rows;
+      })
+      .catch(function () {
+        box.innerHTML = '<p class="rm-check-error">Spam check unavailable — no internet connection.</p>';
+      });
+  };
+
+  // ── Rails-compatible iframe refresh ─────────────────────
+  window.refreshBody = function (reload) {
+    var partSel   = document.querySelector("select#part");
+    var localeSel = document.querySelector("select#locale");
+    var iframe    = document.getElementById("rm-email-frame");
+    if (!iframe) return;
+
+    var partParam = partSel
+      ? partSel.options[partSel.selectedIndex].value
+      : (document.querySelector("#mime_type") ? document.querySelector("#mime_type").dataset.mimeType : "");
+    var localeParam = localeSel ? localeSel.options[localeSel.selectedIndex].value : null;
+    var fresh = localeParam ? ("?" + partParam + "&" + localeParam) : ("?" + partParam);
+
+    iframe.contentWindow.location = fresh;
+
+    var url   = location.pathname.replace(/\.(txt|html)$/, "");
+    var fmt   = /html/.test(partParam) ? ".html" : ".txt";
+    var state = localeParam ? (url + fmt + "?" + localeParam) : (url + fmt);
+    if (reload) location.href = state;
+    else if (history.replaceState) history.replaceState({}, "", state);
+  };
+
+}());
+</script>

data/app/views/rails/mailers/_sidebar.html.erb

@@ -0,0 +1,26 @@
+<%
+  _all_previews    = ActionMailer::Preview.all
+  _active_preview  = local_assigns.fetch(:active_preview, nil)
+  _active_action   = local_assigns.fetch(:active_action, nil)
+%>
+<aside class="rm-sidebar" id="rm-sidebar">
+  <% _all_previews.each do |preview| %>
+    <div class="rm-mailer-group">
+      <div class="rm-mailer-label"><%= preview.preview_name.gsub("_", " ").titleize %></div>
+      <% preview.emails.each do |email| %>
+        <%
+          path   = "#{preview.preview_name}/#{email}"
+          href   = url_for(controller: "rails/mailers", action: "preview", path: path)
+          active = _active_preview == preview && _active_action.to_s == email.to_s
+        %>
+        <a href="<%= href %>" class="rm-email-link <%= 'active' if active %>">
+          <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/>
+            <polyline points="14 2 14 8 20 8"/>
+          </svg>
+          <%= email %>
+        </a>
+      <% end %>
+    </div>
+  <% end %>
+</aside>