studio-engine 0.41.0 → 0.43.0

data/app/models/studio/email_setting.rb

@@ -0,0 +1,206 @@
+module Studio
+  # An operator's per-email overrides, editable from /admin/emails.
+  #
+  # The registry (code) supplies defaults; a row here overrides them for THIS
+  # app. That split matters: the scrim is the dial between a readable header and
+  # a visible picture, and the right value depends on artwork that changes
+  # without a deploy — so it has to be tunable by the person looking at it.
+  #
+  # Nil-safe throughout, because the table is installed by a migration the host
+  # runs. An app that has not run it yet must still send email.
+  class EmailSetting < ApplicationRecord
+    self.table_name = "studio_email_settings"
+
+    SCRIM_RANGE = (0..100).freeze
+
+    validates :email_key, presence: true, uniqueness: true
+    validates :scrim_percent, numericality: { only_integer: true,
+                                              greater_than_or_equal_to: SCRIM_RANGE.min,
+                                              less_than_or_equal_to: SCRIM_RANGE.max },
+                              allow_nil: true
+
+    # The banner's words and logo. Each is nil until the operator sets it, and
+    # nil means INHERIT — never "empty".
+    COPY_FIELDS = %i[header header_fallback subtext logo_url subject body cta_text cta_color].freeze
+
+    # The footer is shared by every email this app sends, so it is stored once
+    # under a reserved key rather than copied onto each row. Underscored so it
+    # cannot collide with a registry key, which is always a plain identifier.
+    FOOTER_KEY = "_footer".freeze
+    FOOTER_FIELDS = %i[discord_url logo_url].freeze
+
+    class << self
+      # The saved scrim for this email as a 0.0-1.0 fraction, or nil when the
+      # operator has not set one (the registry default then applies).
+      def scrim_for(key)
+        return nil unless table_ready?
+
+        percent = for_key(key)&.scrim_percent
+        percent.nil? ? nil : percent / 100.0
+      end
+
+      # One saved copy field, or nil to inherit. Blank is stored as nil by
+      # #set_copy, so a blank return here always means "not set".
+      def copy_for(key, field)
+        return nil unless table_ready?
+        return nil unless COPY_FIELDS.include?(field.to_sym)
+
+        for_key(key)&.public_send(field).presence
+      end
+
+      # The row for this email, memoised PER REQUEST.
+      #
+      # Building one banner asks for the header, the fallback, the sub-text, the
+      # logo, the subject, the scrim and hide_logo — seven find_by calls for one
+      # row, on the mail DELIVERY path, and multiplied by every row on
+      # /admin/emails. The cache is request-scoped rather than a class variable
+      # so a write in one request cannot be served to the next.
+      # IsolatedExecutionState, not Thread.current: Puma reuses threads, so a
+      # thread-local outlives the request that filled it and the next request
+      # served by that thread would get the previous one's row. Rails resets
+      # IsolatedExecutionState around every request and job.
+      def for_key(key)
+        cache = ActiveSupport::IsolatedExecutionState[:studio_email_settings] ||= {}
+        return cache[key.to_s] if cache.key?(key.to_s)
+
+        cache[key.to_s] = find_by(email_key: key.to_s)
+      end
+
+      # Called after any write, because a memoised row that outlives its update
+      # serves the operator their old copy back and looks like the save failed.
+      def forget!(key = nil)
+        cache = ActiveSupport::IsolatedExecutionState[:studio_email_settings]
+        return if cache.nil?
+
+        key.nil? ? cache.clear : cache.delete(key.to_s)
+      end
+
+      # The shared footer, as a plain hash. Reads through the same per-request
+      # memo as everything else, so rendering it on every email in a list costs
+      # one query rather than one per email.
+      # The saved footer, or NIL when the operator has never touched it.
+      #
+      # nil and {} are different answers and the distinction is load-bearing: no
+      # row means "apply the defaults", while a row whose fields are blank means
+      # "I cleared these on purpose". Returning {} for both made clearing the
+      # logo hand the default straight back, so the field could not be emptied.
+      def footer
+        return nil unless table_ready?
+
+        row = for_key(FOOTER_KEY)
+        return nil if row.nil?
+
+        FOOTER_FIELDS.index_with { |field| row.public_send(field).presence }
+      end
+
+      # Write the footer ONLY when it actually changes.
+      #
+      # There is one Save for the whole page, so every save posts the footer
+      # inputs — blank ones included, from a page where the operator only touched
+      # the subject. Writing those blanks created a row of nils, which reads the
+      # same as "cleared", so the shared footer vanished from every email the app
+      # sends and could not be recovered without retyping it.
+      #
+      # Comparing against what is stored keeps both meanings: blanks matching an
+      # untouched footer write nothing, blanks replacing a stored value clear it.
+      def update_footer(discord_url: nil, logo_url: nil)
+        posted = { discord_url: discord_url.presence, logo_url: logo_url.presence }
+        stored = footer
+
+        return nil if stored.nil? && posted.values.all?(&:nil?)
+        return nil if stored.present? && stored.slice(:discord_url, :logo_url) == posted
+
+        set_footer(posted)
+      end
+
+      def set_footer(attrs)
+        return nil unless table_ready?
+
+        record = find_or_initialize_by(email_key: FOOTER_KEY)
+        FOOTER_FIELDS.each do |field|
+          next unless attrs.key?(field) || attrs.key?(field.to_s)
+
+          record.public_send(:"#{field}=", (attrs[field] || attrs[field.to_s]).presence)
+        end
+        record.save!
+        forget!(FOOTER_KEY)
+        record
+      end
+
+      # nil when the operator has not decided — the registry then answers.
+      def cta_enabled_for(key)
+        return nil unless table_ready?
+
+        for_key(key)&.cta_enabled
+      end
+
+      def set_cta_enabled(key, value)
+        return nil unless table_ready?
+
+        record = find_or_initialize_by(email_key: key.to_s)
+        record.cta_enabled = value.nil? ? nil : ActiveModel::Type::Boolean.new.cast(value)
+        record.save!
+        forget!(key)
+        record
+      end
+
+      # True when the operator has explicitly hidden the logo — which is a
+      # different answer from "no logo url saved" (that one inherits).
+      def hide_logo?(key)
+        return false unless table_ready?
+
+        for_key(key)&.hide_logo || false
+      rescue ActiveRecord::ActiveRecordError
+        false
+      end
+
+      # Save the words. A blank field is stored as NULL rather than "", so
+      # clearing a box means "go back to the registry default" — the same
+      # gesture that resets the tint.
+      def set_copy(key, attrs)
+        return nil unless table_ready?
+
+        record = find_or_initialize_by(email_key: key.to_s)
+        COPY_FIELDS.each do |field|
+          next unless attrs.key?(field) || attrs.key?(field.to_s)
+
+          record.public_send(:"#{field}=", (attrs[field] || attrs[field.to_s]).presence)
+        end
+        # ONLY when the form carried it. Two separate cards post to this method,
+        # and an absent checkbox means "this form does not manage the logo", not
+        # "show the logo" — writing false either way let saving the subject
+        # silently un-hide a logo the operator had hidden.
+        if attrs.key?(:hide_logo) || attrs.key?("hide_logo")
+          record.hide_logo = ActiveModel::Type::Boolean.new.cast(attrs[:hide_logo] || attrs["hide_logo"]) || false
+        end
+        record.save!
+        # Drop the memo, or the operator is shown the value they just replaced —
+        # the same "saved successfully, changed nothing" shape the permit bug had.
+        forget!(key)
+        record
+      end
+
+      # Store a percent, or clear the override with nil/blank so the email falls
+      # back to the registry default rather than being pinned to whatever the
+      # default happened to be on the day.
+      def set_scrim(key, percent)
+        return nil unless table_ready?
+
+        record = find_or_initialize_by(email_key: key.to_s)
+        record.scrim_percent = percent.presence&.to_i
+        record.save!
+        forget!(key)
+        record
+      end
+
+      # Reference the constant directly so Zeitwerk autoloads it — defined?()
+      # does NOT trigger autoload, so it reads "undefined" for a not-yet-loaded
+      # const and would silently disable every setting.
+      def table_ready?
+        table_exists?
+      rescue ActiveRecord::ActiveRecordError, NameError
+        false
+      end
+    end
+  end
+end

data/app/services/studio/banner.rb

@@ -0,0 +1,191 @@
+module Studio
+  # A LAYERED email banner: a background image with the header, sub-text and
+  # logo sitting on top as live HTML, rather than composed into the picture.
+  #
+  # ## Why layered rather than composited
+  #
+  # The alternative is drawing the text into the image server-side. That gives
+  # pixel-exact brand typography in every client, but it cannot do the one thing
+  # this design needs: an ANIMATED background WITH per-recipient text. Composing
+  # "Welcome Mason!" into sixty frames means a multi-megabyte GIF generated per
+  # recipient, per send.
+  #
+  # Layering separates them. The background animates, the greeting is live, and
+  # nothing is generated at send time.
+  #
+  # ## What it costs, stated plainly
+  #
+  # Gmail and Outlook strip webfonts, so the heading falls back to a system face
+  # rather than the brand font. In exchange the text survives blocked images
+  # (which Outlook desktop does by default), stays selectable and translatable,
+  # and no asset is produced per send.
+  #
+  # ## Why the markup looks like 1999
+  #
+  # Outlook on Windows renders through Word, which ignores `background-image` on
+  # nearly everything. The `<td background>` attribute plus a VML `v:rect` /
+  # `v:fill` block — the long-established "bulletproof background" pattern — is
+  # what makes a background image work there at all. The conditional comment is
+  # invisible to every other client.
+  # A plain class, not a Struct-with-block: constants declared inside a
+  # `Struct.new do ... end` attach to the ENCLOSING module, so DEFAULT_SCRIM
+  # would have been Studio::DEFAULT_SCRIM and Banner::DEFAULT_SCRIM would not
+  # exist. Named constants are part of this object's API, so they live on it.
+  class Banner
+    ATTRIBUTES = %i[background_url header subtext logo_url logo_alt scrim width height].freeze
+    attr_reader(*ATTRIBUTES)
+
+    def initialize(**attrs)
+      unknown = attrs.keys - ATTRIBUTES
+      raise ArgumentError, "unknown banner attribute: #{unknown.join(", ")}" if unknown.any?
+
+      ATTRIBUTES.each { |name| instance_variable_set(:"@#{name}", attrs[name]) }
+    end
+
+    # The email card is 600px wide; the banner fills it.
+    #
+    # 300, not 200. It was cut to 200 to take out vertical dead space, which the
+    # proportional type below then closed on its own — so the shorter box was
+    # buying nothing and costing the artwork half its sky. Everything in the
+    # partial scales from this number, which is what makes the change one line.
+    DEFAULT_WIDTH  = 600
+    DEFAULT_HEIGHT = 300
+
+    # A wash between the artwork and the text. Not decoration: background art is
+    # chosen for looks, not contrast, and white text over a pale sky is
+    # unreadable. 0 disables it for artwork already dark enough to carry type.
+    #
+    # Raised from 0.34 after seeing it in a real inbox — bright artwork left the
+    # sub-text working harder than it should. Rendered at 0.34 / 0.45 / 0.55 and
+    # chosen by eye, because "legible" is a judgement about a picture, not a
+    # number a test can settle.
+    DEFAULT_SCRIM = 0.40
+
+    def width  = (@width  || DEFAULT_WIDTH).to_i
+    def height = (@height || DEFAULT_HEIGHT).to_i
+
+    # The scrim as a SOLID hex, for Outlook.
+    #
+    # Word's rendering engine ignores rgba(), so the wash simply does not exist
+    # there — white text over bare artwork, which is the exact contrast case the
+    # scrim was added to solve, in the one client nobody can spot-check. VML
+    # cannot layer a translucent fill over an image fill either, so the honest
+    # approximation is a solid colour: the scrim tint blended toward the artwork's
+    # own darkness by the same fraction. It is not the same picture as everywhere
+    # else, and it is legible, which is the point.
+    SCRIM_RGB = [24, 16, 64].freeze
+
+    def scrim_solid_hex
+      fraction = scrim_opacity
+      # Blend the tint toward mid-grey rather than to black: at low opacities a
+      # blend toward black reads far darker in Outlook than the rgba() wash does
+      # elsewhere, which trades one wrong picture for another.
+      blended = SCRIM_RGB.map { |channel| ((channel * fraction) + (128 * (1 - fraction))).round.clamp(0, 255) }
+      format("#%02X%02X%02X", *blended)
+    end
+
+    def scrim_opacity
+      value = @scrim
+      return DEFAULT_SCRIM if value.nil?
+
+      value.to_f.clamp(0.0, 1.0)
+    end
+
+    # A banner with nothing to show is not a banner. The layout falls back to
+    # the plain <img> path (or to no banner at all).
+    def renderable? = background_url.present? || header.present?
+
+    # Everything the layout needs for one email, or nil.
+    #
+    # Reads the catalogue for the artwork so an app inherits the shared
+    # background and logo without repeating them, and lets a caller override any
+    # piece per send — which is the whole point of the header being dynamic.
+    # `name` is the DYNAMIC part and the only thing a mailer should normally
+    # pass. A mailer that hands over a finished header instead takes the wording
+    # away from the operator: the /admin/emails field would still accept an edit
+    # and the email would still ignore it — a control that lies about what it
+    # does. So the mailer supplies who the person is, and the operator supplies
+    # what the banner says about them.
+    def self.for(key, name: nil, header: nil, subtext: nil, background_url: nil,
+                 logo_url: nil, scrim: nil, logo_alt: nil)
+      banner = new(
+        background_url: background_url || Studio::EmailCatalog.background_url(key),
+        logo_url:       logo_url       || safe_image_url(Studio::EmailCatalog.resolved_logo_url(key)),
+        logo_alt:       logo_alt       || Studio.app_name,
+        header:         header         || header_for(key, name),
+        subtext:        subtext        || Studio::EmailCatalog.subtext(key),
+        # Resolution order: an explicit argument (a caller who knows better),
+        # then what the OPERATOR saved on /admin/emails, then the registry, then
+        # the default. The operator sits above the registry on purpose — they
+        # are the one looking at the artwork.
+        scrim:          scrim || Studio::EmailCatalog.scrim(key)
+      )
+      # A LAYERED banner needs its picture, and renderable? deliberately accepts
+      # a header alone — right for a caller building a Banner directly, wrong
+      # here. A nil background means the catalogue said this app sends the email
+      # flat, and a text-only card is not what that inbox gets.
+      banner.background_url.present? ? banner : nil
+    end
+
+    # The placeholder an operator types into the header field. Braces rather
+    # than Ruby's %{name}: an operator-editable string is passed to no formatter
+    # here, and a stray "%" in "50% off" would raise inside format() where a
+    # stray brace is simply left alone.
+    # An operator types the logo URL into an admin form, and it is rendered into
+    # an <img src>. Admin-only and low risk, but "javascript:" and "data:" in a
+    # src are cheap to refuse and there is no reason to carry them: a logo is
+    # fetched over http(s) or served from this app's own asset path.
+    def self.safe_image_url(url)
+      value = url.to_s.strip
+      return nil if value.empty?
+      return value if value.start_with?("/")
+
+      value.match?(%r{\Ahttps?://}i) ? value : nil
+    end
+
+    NAME_PLACEHOLDER = "{name}".freeze
+
+    # The app's own name. Present because the DEFAULTS need it: "Your sign-in
+    # link" reads as though it could be from anyone, and a registry constant
+    # cannot interpolate Studio.app_name at load time. An operator gets it for
+    # free in any field.
+    APP_PLACEHOLDER = "{app}".freeze
+
+    # FIRST name only. The banner is one line of large type in a 600px box, and
+    # "Welcome Bartholomew Fitzgerald-Montgomery!" wraps out of it.
+    # Shared with the SUBJECT, which takes the same placeholder. One
+    # implementation, so "{name}" cannot mean two things on one email.
+    def self.interpolate(template, name)
+      text = template.to_s.gsub(APP_PLACEHOLDER, Studio.app_name.to_s)
+      first = name.to_s.strip.split.first
+      return text.gsub(NAME_PLACEHOLDER, first) if first.present?
+
+      # NO NAME, AND NO RAW PLACEHOLDER EITHER. The header carries a whole second
+      # field for this case; a subject line does not, and "Sign in to Studio,
+      # {name}" reaching an inbox is the most visible way this feature fails. The
+      # token goes, and the punctuation it hung off goes with it — the result is
+      # "Sign in to Studio", not "Sign in to Studio, ".
+      # Two passes, because the punctuation can sit on either side: "Sign in,
+      # {name}" and "{name}, your link is here" both have to come out clean, and
+      # "Hi {name} welcome" must not become "Hiwelcome".
+      text.gsub(/[,;:\u2014-]?\s*#{Regexp.escape(NAME_PLACEHOLDER)}/, "")
+          .sub(/\A\s*[,;:\u2014-]\s*/, "")
+          .squeeze(" ").strip
+    end
+
+    def self.header_for(key, name)
+      template = Studio::EmailCatalog.header_template(key).to_s
+      first = name.to_s.strip.split.first
+
+      return interpolate(template, name) if first.present?
+      # No name: a template that asks for one cannot be rendered honestly, so
+      # the fallback answers instead. A template with no name placeholder is
+      # already name-free and stands as written — still interpolated, because
+      # {app} does not depend on the recipient.
+      fallback = Studio::EmailCatalog.header_fallback(key) if template.include?(NAME_PLACEHOLDER)
+
+      interpolate(fallback || template, nil)
+    end
+  end
+
+end