studio-engine 0.113.0 → 0.114.0

data/app/views/studio/modals/blocks/_change_username.html.erb

@@ -21,11 +21,34 @@
 
   Everything else (finalize_url, finalize_hook, saved_event, quest_label,
   leveling, modal_store, demo, celebration copy) passes straight through.
+
+  locked (Hash, optional) — the rename is not open to this person yet, and the
+           card says why instead of offering the input. The APP decides (a
+           frozen account, a first contest not yet entered); the engine only
+           draws the answer:
+             title:     required, e.g. "Username locked".
+             subtitle:  the reason.
+             cta_label: with cta_href, a primary link to where the rename
+             cta_href:  unlocks (it closes the modal on the way), and a Dismiss
+                        link under it. Without them, one Dismiss button.
+             dismiss:   the dismiss label. Default "Dismiss".
+           Any other key raises. Absent (the default), the card renders exactly
+           as it did before the local existed.
 %>
 <%
   current_username = local_assigns.fetch(:current_username)
 
-  username_locals = local_assigns.except(:current_username).reverse_merge(
+  # A Hash or nothing; a misspelt key would otherwise drop the CTA silently.
+  locked = local_assigns[:locked]
+  unless locked.nil?
+    unless locked.is_a?(Hash) && locked[:title].present? && (locked.keys - %i[title subtitle cta_label cta_href dismiss]).empty?
+      raise ArgumentError, "blocks/_change_username locked: takes { title:, subtitle:, cta_label:, cta_href:, dismiss: } with a title, got #{locked.inspect}"
+    end
+    # IDENTIFIER position ($store.<name>.close()) — VALIDATED, never escaped.
+    locked_store = Studio::JsIdentifier.validate!(local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
+  end
+
+  username_locals = local_assigns.except(:current_username, :locked).reverse_merge(
     title:              "Change Username",
     description:        "Pick a name that's right for you.",
     input:              true,
@@ -43,4 +66,19 @@
     celebrate_subtitle: "Nice — you earned 25 seeds by completing a quest. Complete more quests to earn a Free Entry Token."
   )
 %>
+<% if locked %>
+<div data-username-locked>
+  <%= render "studio/modals/blocks/card_header",
+        size: :lg, icon: :error, title: locked[:title], subtitle: locked[:subtitle] %>
+  <% if locked[:cta_label] && locked[:cta_href] %>
+  <%= link_to locked[:cta_label], locked[:cta_href],
+              class: "btn btn-primary btn-lg w-full", "@click": "$store.#{locked_store}.close()" %>
+  <button type="button" @click="$store.<%= locked_store %>.close()"
+          class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition"><%= locked.fetch(:dismiss, "Dismiss") %></button>
+  <% else %>
+  <button type="button" @click="$store.<%= locked_store %>.close()" class="btn btn-outline btn-lg w-full"><%= locked.fetch(:dismiss, "Dismiss") %></button>
+  <% end %>
+</div>
+<% else %>
 <%= render "studio/modals/blocks/leveling_activity", username_locals %>
+<% end %>

data/app/views/studio/modals/blocks/_error_card.html.erb

@@ -20,6 +20,26 @@
 
     secondary_label: optional secondary action ("Close", "Cancel", etc).
     secondary_event: dispatch event for the secondary action.
+
+  Closing the modal, and counting down to it (each optional; unset, the card
+  renders exactly as it did before they existed):
+    cta_close:       boolean. The primary button closes the modal store instead
+                     of reloading or dispatching. Raises with cta_reload or
+                     cta_event.
+    secondary_close: boolean. The secondary action closes the modal store.
+                     Raises with secondary_event.
+    countdown_key:   Alpine expression for the seconds to wait, read once at
+                     mount (e.g. "$store.modals.current().props.secondsLeft", from a 429's
+                     Retry-After). Adds a "Try again in 12s." line that counts
+                     down (minutes above 90s) and is hidden at zero.
+    countdown_text:  the words before the wait. Default "Try again in".
+    auto_close:      with countdown_key, close the store at zero. Default true.
+    modal_store:     the Alpine store the close actions and the auto-close
+                     close. Default "modals"; validated as a JS identifier
+                     (Studio::JsIdentifier), since the buttons splice it as a name.
+
+  The countdown is studio/modal_countdown's studioModalCountdown(), published by
+  studio/alpine_scopes; this card carries no script.
 %>
 <%
   icon_emoji = local_assigns[:icon_emoji] || "⏳"   # ⏳
@@ -33,12 +53,37 @@
   # interpolated form is load-bearing.
   cta_event_js       = Studio::JsLiteral.in_attribute(local_assigns[:cta_event])
   secondary_event_js = Studio::JsLiteral.in_attribute(local_assigns[:secondary_event])
+
+  # THE CLOSE ACTIONS. A third way to wire a button that already has two, so
+  # naming two at once is refused rather than settled by branch order: a Retry
+  # that silently closes instead of dispatching is a card that looks right.
+  cta_close       = !!local_assigns[:cta_close]
+  secondary_close = !!local_assigns[:secondary_close]
+  if cta_close && (local_assigns[:cta_reload] || local_assigns[:cta_event])
+    raise ArgumentError, "blocks/_error_card: cta_close closes the store; it takes no cta_reload or cta_event"
+  end
+  if secondary_close && local_assigns[:secondary_event]
+    raise ArgumentError, "blocks/_error_card: secondary_close closes the store; it takes no secondary_event"
+  end
+  # IDENTIFIER position ($store.<name>.close()) — VALIDATED, never escaped.
+  modal_store = Studio::JsIdentifier.validate!(local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
+
+  # The countdown's x-data. countdown_key is an Alpine EXPRESSION by contract,
+  # like message_key, and lands as code; the store is a validated identifier,
+  # so it cannot leave the string it sits in. tag.attributes encodes the double
+  # quote, so the expression cannot close the attribute either.
+  countdown_key  = local_assigns[:countdown_key]
+  countdown_text = local_assigns.fetch(:countdown_text, "Try again in")
+  countdown_data = if countdown_key
+    "studioModalCountdown({ seconds: (#{countdown_key}), store: '#{modal_store}', " \
+      "autoClose: #{local_assigns.fetch(:auto_close, true) ? 'true' : 'false'} })".html_safe
+  end
 %>
 <%# role="alert" on the CARD, not on its message: the message is server-rendered
     static text, so it never "changes" for a live region to notice. The modal host
     renders content through <template x-if>, so this whole card ENTERS the DOM when
     the failure happens — which is the event a screen reader can announce. %>
-<div role="alert" class="text-center py-6">
+<div role="alert"<% if countdown_data %> <%= tag.attributes("x-data": countdown_data) %><% end %> class="text-center py-6">
   <div class="text-5xl mb-4 leading-none"><%= icon_emoji %></div>
   <p class="text-sm text-heading font-semibold mb-2"><%= title %></p>
 
@@ -48,10 +93,16 @@
     <p class="text-xs text-secondary mb-4"><%= message %></p>
   <% end %>
 
+  <% if countdown_data %>
+    <%# aria-live="off": the card is role="alert", and a label ticking inside it would be announced every second. %>
+    <p class="text-xs text-secondary mb-4" x-show="counting" aria-live="off"><%= countdown_text %> <span class="text-heading font-semibold" x-text="waitLabel"></span>.</p>
+  <% end %>
   <% if local_assigns[:cta_reload] %>
     <button @click="window.location.reload()" class="btn btn-outline btn-sm"><%= cta_label %></button>
   <% elsif local_assigns[:cta_event] %>
     <button @click="$dispatch('<%= cta_event_js %>')" class="btn btn-outline btn-sm"><%= cta_label %></button>
+  <% elsif cta_close %>
+    <button type="button" @click="$store.<%= modal_store %>.close()" class="btn btn-outline btn-sm"><%= cta_label %></button>
   <% end %>
 
   <% if local_assigns[:secondary_label] && local_assigns[:secondary_event] %>
@@ -59,5 +110,10 @@
             class="block mx-auto mt-3 text-xs text-secondary hover:text-heading underline underline-offset-2">
       <%= secondary_label %>
     </button>
+  <% elsif local_assigns[:secondary_label] && secondary_close %>
+    <button type="button" @click="$store.<%= modal_store %>.close()"
+            class="block mx-auto mt-3 text-xs text-secondary hover:text-heading underline underline-offset-2">
+      <%= secondary_label %>
+    </button>
   <% end %>
 </div>

data/app/views/studio/modals/blocks/_success_card.html.erb

@@ -35,13 +35,21 @@
                            on the left and a launch arrow on the
                            right. The "canonical" tx link.
 
-    slot_position:         :below_cta (default) or :above_cta — where the block
-                           renders. See the note on the slot itself.
+    slot_position:         :below_cta (default), :above_cta, or :message — where
+                           the block renders. :message puts it in the message's
+                           place, for copy richer than one string (two bound
+                           addresses with bold spans); it then replaces
+                           message / message_key. See the note on the slot itself.
     cta_label:             primary CTA button text.
     cta_href_key:          Alpine expression for the button's href.
                            Mutually exclusive with cta_event.
     cta_event:             window event name dispatched on click.
                            Mutually exclusive with cta_href_key.
+    cta_close:             boolean. The CTA closes the modal store
+                           ($store.<modal_store>.close()) instead of following
+                           a href or dispatching an event: the "Got it" of an
+                           informational card. Raises with cta_href_key or
+                           cta_event.
     cta_drain:             boolean. When set together with
                            auto_redirect_url_key, the countdown
                            drains as a translucent overlay on the CTA
@@ -51,6 +59,11 @@
 
     secondary_label:       optional secondary action label.
     secondary_event:       optional secondary action dispatch event.
+    secondary_close:       boolean. The secondary action closes the modal store
+                           instead of dispatching. Raises with secondary_event.
+    modal_store:           the Alpine store the two close actions close. Default
+                           "modals"; validated as a JS identifier
+                           (Studio::JsIdentifier), since it is spliced as a name.
 
     auto_redirect_url_key: Alpine expression for the redirect URL.
                            When set, an internal countdown ticks down
@@ -78,6 +91,22 @@
   # returns the layout's content, so a card rendered from a layout with no
   # block re-emitted the whole page body under its CTA. See Studio::PartialBlock.
   caller_block  = Studio::PartialBlock.content(self, yield)
+  block_in_message = caller_block && slot_position == :message
+
+  # THE CLOSE ACTIONS, and the store they close. Each is a third way to wire a
+  # button that already has two, so naming two at once is refused rather than
+  # resolved by an order nobody reads: a CTA that silently ignores the event the
+  # host passed is a card that renders right and does the wrong thing.
+  cta_close       = !!local_assigns[:cta_close]
+  secondary_close = !!local_assigns[:secondary_close]
+  if cta_close && (local_assigns[:cta_href_key] || local_assigns[:cta_event])
+    raise ArgumentError, "blocks/_success_card: cta_close closes the store; it takes no cta_href_key or cta_event"
+  end
+  if secondary_close && local_assigns[:secondary_event]
+    raise ArgumentError, "blocks/_success_card: secondary_close closes the store; it takes no secondary_event"
+  end
+  # IDENTIFIER position ($store.<name>.close()) — VALIDATED, never escaped.
+  modal_store = Studio::JsIdentifier.validate!(local_assigns.fetch(:modal_store, "modals"), local: :modal_store)
 
   data_attr = "{
     _remaining: #{redirect_secs},
@@ -169,7 +198,12 @@
     <p class="<%= title_class %>"><%= title %></p>
   <% end %>
 
-  <% if local_assigns[:message_key] %>
+  <%# The block IN the message's place (slot_position: :message): a div, not a
+      p, because the caller's markup may hold block elements, which a p would
+      have the parser split around. Same type and spacing as the message. %>
+  <% if block_in_message %>
+    <div class="text-sm text-secondary mb-4"><%= caller_block %></div>
+  <% elsif local_assigns[:message_key] %>
     <p class="text-sm text-secondary mb-4" x-text="<%= message_key %>"></p>
   <% elsif local_assigns[:message] %>
     <p class="text-sm text-secondary mb-4"><%= message %></p>
@@ -282,6 +316,8 @@
       <a :href="<%= cta_href_key %>" class="btn btn-primary btn-lg w-full"><%= cta_label %></a>
     <% elsif local_assigns[:cta_event] %>
       <button @click="$dispatch('<%= cta_event_js %>')" class="btn btn-primary btn-lg w-full"><%= cta_label %></button>
+    <% elsif cta_close %>
+      <button type="button" @click="$store.<%= modal_store %>.close()" class="btn btn-primary btn-lg w-full"><%= cta_label %></button>
     <% end %>
   <% end %>
 
@@ -290,12 +326,17 @@
             class="block mx-auto mt-3 text-xs text-secondary hover:text-heading underline underline-offset-2">
       <%= secondary_label %>
     </button>
+  <% elsif local_assigns[:secondary_label] && secondary_close %>
+    <button type="button" @click="$store.<%= modal_store %>.close()"
+            class="block mx-auto mt-3 text-xs text-secondary hover:text-heading underline underline-offset-2">
+      <%= secondary_label %>
+    </button>
   <% end %>
 
   <%# ...or below it, which stays the DEFAULT: every existing caller renders here
       and none of them asked to move. The block is captured once at the top, and
       exactly one of these two branches renders it. %>
-  <% if caller_block && slot_position != :above_cta %>
+  <% if caller_block && slot_position != :above_cta && !block_in_message %>
     <div class="mt-3"><%= caller_block %></div>
   <% end %>
 </div>

data/app/views/studio/profiles/_newsletter_modals.html.erb

@@ -1,4 +1,4 @@
-<%# The newsletter row's two modals, registered into the page's scoped host.
+<%# The newsletter row's modals, registered into the page's scoped host.
 
     Locals: user (required).
 
@@ -14,48 +14,310 @@
     has no address, and a newsletter needs somewhere to send. It is written as the
     account email but NOT marked verified — see the controller for why that
     distinction is load-bearing.
+
+    FOR A HOST THAT MOUNTS THESE ITSELF (turf-monster, on its own $store.modals
+    and its own JSON routes). Every local below is optional, and with all of them
+    unset the two cards above render byte for byte as they did before the locals
+    existed (test/views/newsletter_modals_test.rb holds that).
+
+      modal_store       the Alpine store the cards answer to. Default
+                        "profileModals"; validated as a JS identifier, since
+                        it is spliced as a name ($store.<name>.close()).
+      submit_mode       :form (default) — each card posts the engine form to
+                        profile_newsletter_path with Turbo off, a full reload.
+                        :json — each card posts JSON to the host's route
+                        (studio/newsletter_modal), stays on the page, shows a
+                        spinner and an inline error line, dispatches
+                        changed_event and steps to the next card. A card whose
+                        opener passed props.onSubmit hands it the address and
+                        posts nothing: the opener's own request takes over.
+      subscribe_url     :json only, and required there by every card that
+                        subscribes (email, subscribe). The host's endpoint.
+      unsubscribe_url   :json only, and required there by the unsubscribe card.
+      unsubscribe_method :json only. The verb the unsubscribe card sends.
+                        Default "DELETE", the engine route's.
+      changed_event     :json only. The window event a success dispatches,
+                        with { subscribed, email, response }. Default
+                        "studio:newsletter-changed".
+      fetcher           :json only. The host's own request wrapper, by its
+                        export name in the importmap module
+                        "studio/host_fetchers", which the host pins to a file
+                        of its own (Turf Monster: authedFetch, so a 401 opens
+                        sign-in and a 429 the rate-limit card). Validated as a
+                        JS identifier; refused under :form, where nothing
+                        would call it. Unset, the cards send plain fetch.
+                        The contract is in studio/newsletter_modal.js.
+
+    THE CARDS. Each is a Hash of its copy, or off. The two above are on by
+    default (false turns one off); the other three are off by default (a Hash,
+    or true for the engine's copy, turns one on). Every card takes id:, title:,
+    subtitle: and header: (more blocks/_card_header locals: size, icon,
+    icon_emoji, icon_color), plus the keys listed. An unknown key raises.
+
+      unsubscribe_card  'newsletter-unsubscribe'. button:, cancel:, saving:.
+                        :json steps to goodbye_card when it is on.
+      email_card        'newsletter-email'. button:, cancel:, saving:.
+                        :json steps to success_card when it is on.
+      subscribe_card    'newsletter-subscribe'. The join, with a consent box
+                        (ticked to start; Subscribe waits for it) and, for an
+                        account with no address, the address field. consent:,
+                        button:, cancel:, saving:. :json steps to success_card.
+      success_card      'newsletter-success'. The "Subscribed!" beat. partial:
+                        and locals: render the host's slot under the header (a
+                        seeds bar, a next-step button); the card's props, the
+                        host's JSON answer, are in scope there as `props`. With
+                        no slot the card ends in a Close button; with one, a
+                        Close link (cancel:).
+      goodbye_card      'newsletter-goodbye'. The beat after an unsubscribe.
+                        button:.
+%>
+<%
+  newsletter_modal_store = Studio::JsIdentifier.validate!(
+    local_assigns.fetch(:modal_store, "profileModals"), local: :modal_store)
+  newsletter_mode = local_assigns.fetch(:submit_mode, :form).to_sym
+  unless %i[form json].include?(newsletter_mode)
+    raise ArgumentError, "studio/profiles/_newsletter_modals submit_mode: :form or :json, got #{newsletter_mode.inspect}"
+  end
+  newsletter_json = newsletter_mode == :json
+
+  # The host's fetcher, by name (studio/host_fetchers). A name, so it is
+  # refused rather than escaped; under :form nothing would ever call it.
+  newsletter_fetcher = local_assigns[:fetcher].presence&.to_s
+  if newsletter_fetcher
+    unless newsletter_json
+      raise ArgumentError, "studio/profiles/_newsletter_modals fetcher: needs submit_mode: :json; the form cards send no request of their own"
+    end
+    unless newsletter_fetcher.match?(Studio::JsIdentifier::PATTERN)
+      raise ArgumentError, "studio/profiles/_newsletter_modals fetcher: must be a JS identifier (an export name in studio/host_fetchers); got #{local_assigns[:fetcher].inspect}"
+    end
+  end
+
+  # Each card's defaults; a host's Hash is merged over them. The two cards that
+  # shipped first keep their copy and their header exactly.
+  newsletter_card_defaults = {
+    unsubscribe_card: { on: true, id: "newsletter-unsubscribe",
+                        title: "Unsubscribe?",
+                        subtitle: "You'll stop receiving updates. You can join again from this page any time.",
+                        header: { size: :lg, icon: :error },
+                        button: "Unsubscribe", cancel: "Cancel", saving: "Unsubscribing…" },
+    email_card:       { on: true, id: "newsletter-email",
+                        title: "Where should we send it?",
+                        subtitle: "There's no email on this account yet. We'll use this for the newsletter.",
+                        header: { size: :lg, icon_color: :primary },
+                        button: "Subscribe", cancel: "Cancel", saving: "Subscribing…" },
+    subscribe_card:   { on: false, id: "newsletter-subscribe",
+                        title: "Join the newsletter",
+                        subtitle: "News and updates, now and then. Leave any time.",
+                        header: { size: :md, icon_emoji: "📬" },
+                        consent: "Send me the newsletter",
+                        button: "Subscribe", cancel: "Close", saving: "Subscribing…" },
+    success_card:     { on: false, id: "newsletter-success",
+                        title: "Subscribed!",
+                        subtitle: "You're on the list.",
+                        header: { size: :lg, icon_emoji: "🎉" },
+                        partial: nil, locals: {},
+                        button: "Close", cancel: "Close" },
+    goodbye_card:     { on: false, id: "newsletter-goodbye",
+                        title: "See you later",
+                        subtitle: "You're off the list. You can join again any time.",
+                        header: { size: :lg, icon_emoji: "👋" },
+                        button: "Close" }
+  }
+
+  newsletter_cards = newsletter_card_defaults.to_h do |name, defaults|
+    given = local_assigns.fetch(name) { defaults[:on] }
+    card = case given
+           when false, nil then nil
+           when true then defaults
+           when Hash
+             unknown = given.keys - (defaults.keys - [:on])
+             if unknown.any?
+               raise ArgumentError, "studio/profiles/_newsletter_modals #{name}: unknown key #{unknown.map(&:inspect).join(', ')}"
+             end
+             defaults.merge(given).merge(header: defaults[:header].merge(given[:header] || {}))
+           else
+             raise ArgumentError, "studio/profiles/_newsletter_modals #{name}: a Hash, true or false, got #{given.inspect}"
+           end
+    [name, card]
+  end
+
+  # The URL each JSON card posts to, refused at render when missing: a card with
+  # no endpoint renders perfectly and fails on the one press that matters.
+  newsletter_url = lambda do |key|
+    url = local_assigns[key].presence
+    raise ArgumentError, "studio/profiles/_newsletter_modals: submit_mode: :json needs #{key}" unless url
+    url
+  end
+
+  # The x-data for one JSON card (studio/newsletter_modal). Every value lands in
+  # a JS string, escaped; tag.attributes encodes the double quote.
+  newsletter_scope = lambda do |**opts|
+    named = { store: newsletter_modal_store }
+    named[:fetcher] = newsletter_fetcher if newsletter_fetcher && opts.any?
+    pairs = named.merge(opts).map do |key, value|
+      literal = (value == true || value == false) ? value.to_s : "'#{Studio::JsLiteral.in_attribute(value.to_s)}'"
+      "#{key}: #{literal}"
+    end
+    "studioNewsletterModal({ #{pairs.join(', ')} })".html_safe
+  end
+
+  newsletter_needs_email = Studio::Newsletter.needs_email?(user)
+  newsletter_success_id  = newsletter_cards[:success_card]&.dig(:id).to_s
+  newsletter_goodbye_id  = newsletter_cards[:goodbye_card]&.dig(:id).to_s
+  newsletter_changed     = local_assigns.fetch(:changed_event, "studio:newsletter-changed")
 %>
 
 <%# --- leaving asks --------------------------------------------------------- %>
-<template x-if="$store.profileModals.current()?.id === 'newsletter-unsubscribe'">
-  <div>
+<% if (card = newsletter_cards[:unsubscribe_card]) %>
+<template x-if="$store.<%= newsletter_modal_store %>.current()?.id === '<%= Studio::JsLiteral.in_attribute(card[:id]) %>'">
+  <div<% if newsletter_json %> <%= tag.attributes("x-data": newsletter_scope.call(action: "unsubscribe", url: newsletter_url.call(:unsubscribe_url), method: local_assigns.fetch(:unsubscribe_method, "DELETE"), nextId: newsletter_goodbye_id, event: newsletter_changed)) %><% end %>>
     <%= render "studio/modals/blocks/card_header",
-          size: :lg,
-          icon: :error,
-          title: "Unsubscribe?",
-          subtitle: "You'll stop receiving updates. You can join again from this page any time." %>
+          **card[:header], title: card[:title], subtitle: card[:subtitle] %>
 
+<% if newsletter_json %>
+    <p x-show="error" x-cloak role="alert" aria-live="assertive" aria-atomic="true"
+       x-text="error" class="text-xs mb-3 text-center text-danger-ink"></p>
+    <button type="button" @click="submit()" :disabled="!ready"
+            class="btn btn-danger btn-lg w-full disabled:opacity-50 disabled:cursor-not-allowed">
+      <span x-show="!saving"><%= card[:button] %></span>
+      <span x-show="saving" x-cloak class="inline-flex items-center justify-center gap-2">
+        <span class="spinner" aria-hidden="true" style="--spinner-track: currentColor; --spinner-color: transparent; opacity: 0.85"></span><%= card[:saving] %>
+      </span>
+    </button>
+<% else %>
     <%= form_with url: profile_newsletter_path, method: :delete, data: { turbo: false } do %>
-      <button type="submit" class="btn btn-danger btn-lg w-full">Unsubscribe</button>
+      <button type="submit" class="btn btn-danger btn-lg w-full"><%= card[:button] %></button>
     <% end %>
+<% end %>
 
-    <button type="button" @click="$store.profileModals.close()"
+    <button type="button" @click="$store.<%= newsletter_modal_store %>.close()"
             class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition">
-      Cancel
+      <%= card[:cancel] %>
     </button>
   </div>
 </template>
+<% end %>
 
 <%# --- joining without an address on file ----------------------------------- %>
-<template x-if="$store.profileModals.current()?.id === 'newsletter-email'">
-  <div>
+<% if (card = newsletter_cards[:email_card]) %>
+<template x-if="$store.<%= newsletter_modal_store %>.current()?.id === '<%= Studio::JsLiteral.in_attribute(card[:id]) %>'">
+  <div<% if newsletter_json %> <%= tag.attributes("x-data": newsletter_scope.call(action: "subscribe", url: newsletter_url.call(:subscribe_url), needsEmail: true, nextId: newsletter_success_id, event: newsletter_changed)) %><% end %>>
+    <%= render "studio/modals/blocks/card_header",
+          **card[:header], title: card[:title], subtitle: card[:subtitle] %>
+
+<% if newsletter_json %>
+    <input type="email" x-model="email" @keydown.enter.prevent="submit()" required autocomplete="email"
+           placeholder="you@example.com" class="input-field w-full mb-3">
+    <p x-show="error" x-cloak role="alert" aria-live="assertive" aria-atomic="true"
+       x-text="error" class="text-xs mb-3 text-danger-ink"></p>
+    <button type="button" @click="submit()" :disabled="!ready"
+            class="btn btn-primary btn-lg w-full disabled:opacity-50 disabled:cursor-not-allowed">
+      <span x-show="!saving"><%= card[:button] %></span>
+      <span x-show="saving" x-cloak class="inline-flex items-center justify-center gap-2">
+        <span class="spinner" aria-hidden="true" style="--spinner-track: currentColor; --spinner-color: transparent; opacity: 0.85"></span><%= card[:saving] %>
+      </span>
+    </button>
+<% else %>
+    <%= form_with url: profile_newsletter_path, method: :post, scope: :profile,
+                  data: { turbo: false } do |f| %>
+      <%= f.email_field :email, required: true, autocomplete: "email",
+                        placeholder: "you@example.com",
+                        class: "input-field w-full mb-3" %>
+      <button type="submit" class="btn btn-primary btn-lg w-full"><%= card[:button] %></button>
+    <% end %>
+<% end %>
+
+    <button type="button" @click="$store.<%= newsletter_modal_store %>.close()"
+            class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition">
+      <%= card[:cancel] %>
+    </button>
+  </div>
+</template>
+<% end %>
+<%# --- joining, with consent (optional) ------------------------------------ %>
+<% if (card = newsletter_cards[:subscribe_card]) %>
+
+<template x-if="$store.<%= newsletter_modal_store %>.current()?.id === '<%= Studio::JsLiteral.in_attribute(card[:id]) %>'">
+  <div <%= tag.attributes("x-data": newsletter_scope.call(**(newsletter_json ? { action: "subscribe", url: newsletter_url.call(:subscribe_url), needsEmail: newsletter_needs_email, requiresConsent: true, nextId: newsletter_success_id, event: newsletter_changed } : {}))) %>>
     <%= render "studio/modals/blocks/card_header",
-          size: :lg,
-          icon_color: :primary,
-          title: "Where should we send it?",
-          subtitle: "There's no email on this account yet. We'll use this for the newsletter." %>
+          **card[:header], title: card[:title], subtitle: card[:subtitle] %>
 
+<% if newsletter_json %>
+    <% if newsletter_needs_email %>
+    <input type="email" x-model="email" @keydown.enter.prevent="submit()" required autocomplete="email"
+           placeholder="you@example.com" class="input-field w-full mb-3">
+    <% end %>
+    <label class="flex items-center gap-2 text-xs text-secondary mb-3 select-none cursor-pointer">
+      <input type="checkbox" x-model="consent" class="rounded border-subtle text-primary cursor-pointer">
+      <%= card[:consent] %>
+    </label>
+    <p x-show="error" x-cloak role="alert" aria-live="assertive" aria-atomic="true"
+       x-text="error" class="text-xs mb-3 text-danger-ink"></p>
+    <button type="button" @click="submit()" :disabled="!ready"
+            class="btn btn-primary btn-lg w-full disabled:opacity-50 disabled:cursor-not-allowed">
+      <span x-show="!saving"><%= card[:button] %></span>
+      <span x-show="saving" x-cloak class="inline-flex items-center justify-center gap-2">
+        <span class="spinner" aria-hidden="true" style="--spinner-track: currentColor; --spinner-color: transparent; opacity: 0.85"></span><%= card[:saving] %>
+      </span>
+    </button>
+<% else %>
+    <%# The plain path: the browser holds the submit until the box is ticked. %>
     <%= form_with url: profile_newsletter_path, method: :post, scope: :profile,
                   data: { turbo: false } do |f| %>
+      <% if newsletter_needs_email %>
       <%= f.email_field :email, required: true, autocomplete: "email",
                         placeholder: "you@example.com",
                         class: "input-field w-full mb-3" %>
-      <button type="submit" class="btn btn-primary btn-lg w-full">Subscribe</button>
+      <% end %>
+      <label class="flex items-center gap-2 text-xs text-secondary mb-3 select-none cursor-pointer">
+        <input type="checkbox" required checked class="rounded border-subtle text-primary cursor-pointer">
+        <%= card[:consent] %>
+      </label>
+      <button type="submit" class="btn btn-primary btn-lg w-full"><%= card[:button] %></button>
     <% end %>
+<% end %>
+
+    <button type="button" @click="$store.<%= newsletter_modal_store %>.close()"
+            class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition">
+      <%= card[:cancel] %>
+    </button>
+  </div>
+</template>
+<% end %>
+<%# --- the "Subscribed!" beat (optional) ------------------------------------ %>
+<% if (card = newsletter_cards[:success_card]) %>
+
+<template x-if="$store.<%= newsletter_modal_store %>.current()?.id === '<%= Studio::JsLiteral.in_attribute(card[:id]) %>'">
+  <div <%= tag.attributes("x-data": newsletter_scope.call) %>>
+    <%= render "studio/modals/blocks/card_header",
+          **card[:header], title: card[:title], subtitle: card[:subtitle] %>
 
-    <button type="button" @click="$store.profileModals.close()"
+<% if card[:partial] %>
+    <%= render card[:partial], **(card[:locals] || {}) %>
+
+    <button type="button" @click="$store.<%= newsletter_modal_store %>.close()"
             class="block mx-auto mt-3 text-sm text-secondary hover:text-heading transition">
-      Cancel
+      <%= card[:cancel] %>
+    </button>
+<% else %>
+    <button type="button" @click="$store.<%= newsletter_modal_store %>.close()" class="btn btn-primary btn-lg w-full">
+      <%= card[:button] %>
+    </button>
+<% end %>
+  </div>
+</template>
+<% end %>
+<%# --- the goodbye beat (optional) ----------------------------------------- %>
+<% if (card = newsletter_cards[:goodbye_card]) %>
+
+<template x-if="$store.<%= newsletter_modal_store %>.current()?.id === '<%= Studio::JsLiteral.in_attribute(card[:id]) %>'">
+  <div <%= tag.attributes("x-data": newsletter_scope.call) %>>
+    <%= render "studio/modals/blocks/card_header",
+          **card[:header], title: card[:title], subtitle: card[:subtitle] %>
+
+    <button type="button" @click="$store.<%= newsletter_modal_store %>.close()" class="btn btn-primary btn-lg w-full">
+      <%= card[:button] %>
     </button>
   </div>
 </template>
+<% end %>