studio-engine 0.130.0 → 0.131.0

data/app/controllers/concerns/studio/magic_link_issuing.rb

@@ -19,6 +19,10 @@ module Studio
   module MagicLinkIssuing
     extend ActiveSupport::Concern
 
+    # Shown when a link could not be minted or mailed. The same words for every
+    # address, known or new, so a failure reveals no more than a success does.
+    DELIVERY_FAILED = "We could not send your sign-in email just now. Please try again in a few minutes.".freeze
+
     private
 
     # Mint a token. `return_to` is sanitized to a same-origin path by the store.

data/app/controllers/magic_links_controller.rb

@@ -20,11 +20,24 @@ class MagicLinksController < ApplicationController
   # Respond uniformly for any well-formed email. Under create-or-login every
   # address is "valid" (it logs in or signs up), so there is nothing to
   # enumerate. A malformed email gets the same response with no mail sent.
+  #
+  # A mint or mail failure is logged once (rescue_and_log) and answered the same
+  # way for every address, as the passwordless signup does: the login page with
+  # one alert, or a 503 with a fixed JSON body. 503, not 4xx: the visitor's
+  # input was fine and a retry may work; a 4xx would tell a client to change the
+  # request. The body never carries the internal message, and this action never
+  # looks an account up, so the reply cannot say whether the email is known.
   def create
     email = params[:email].to_s.strip.downcase
     if email.match?(URI::MailTo::EMAIL_REGEXP)
-      token = issue_magic_link(email, Studio::LinkToken.sanitize_path(params[:return_to]))
-      Studio::Email.deliver(UserMailer, :magic_link, email, token, to: email)
+      begin
+        rescue_and_log do
+          token = issue_magic_link(email, Studio::LinkToken.sanitize_path(params[:return_to]))
+          Studio::Email.deliver(UserMailer, :magic_link, email, token, to: email)
+        end
+      rescue StandardError
+        return delivery_failed
+      end
     end
     respond_to do |format|
       format.json { render json: { success: true } }
@@ -32,6 +45,16 @@ class MagicLinksController < ApplicationController
     end
   end
 
+  private
+
+  def delivery_failed
+    message = Studio::MagicLinkIssuing::DELIVERY_FAILED
+    respond_to do |format|
+      format.json { render json: { success: false, error: "delivery_failed", message: message }, status: :service_unavailable }
+      format.html { redirect_to login_path, alert: message }
+    end
+  end
+
   # issue_magic_link (mint a Studio::Link row) comes from
   # Studio::MagicLinkIssuing, shared with UserMailer — which builds the URL that
   # consumes it — so the mint and its landing URL cannot drift apart.

data/app/controllers/registrations_controller.rb

@@ -3,40 +3,76 @@ class RegistrationsController < ApplicationController
 
   skip_before_action :require_authentication
 
+  # Shown when the sign-in link could not be minted or mailed. The same words for
+  # every address, known or new, so a failure reveals no more than a success does.
+  # POST /magic_link shows the same words (Studio::MagicLinkIssuing).
+  DELIVERY_FAILED = Studio::MagicLinkIssuing::DELIVERY_FAILED
+
   def new
     @user = User.new
   end
 
+  # Gated on the same predicate registrations/new renders the password form on,
+  # so the form a visitor sees is always the form this action reads.
+  #
+  # No method-level rescue. One used to catch every StandardError here, log
+  # nothing, and render registrations/new; on the passwordless branch @user was
+  # never set, so that render raised NoMethodError on nil and the failure that
+  # started it was lost. Each branch now owns its failure, and anything it does
+  # not expect is logged by rescue_and_log and left to surface.
   def create
-    # Passwordless apps: there is no create-account-by-form. Logging a user in
-    # straight from a signup POST would skip proof of email ownership, so we
-    # treat "sign up" as a magic-link request — the create-or-login link (which
-    # only fires after the recipient clicks it) does the account creation.
-    # Gated on the same predicate registrations/new renders the password form on,
-    # so the form a visitor sees is always the form this action reads.
-    unless Studio.password_login_available?
-      email = (params.dig(:user, :email) || params[:email]).to_s.strip.downcase
-      if email.match?(URI::MailTo::EMAIL_REGEXP)
-        token = issue_magic_link(email, nil)
-        Studio::Email.deliver(UserMailer, :magic_link, email, token, to: email)
+    Studio.password_login_available? ? create_with_password : create_passwordless
+  end
+
+  private
+
+  # Passwordless apps: there is no create-account-by-form. Logging a user in
+  # straight from a signup POST would skip proof of email ownership, so we
+  # treat "sign up" as a magic-link request — the create-or-login link (which
+  # only fires after the recipient clicks it) does the account creation.
+  #
+  # A mint or mail failure is logged (rescue_and_log) and answered with the same
+  # friendly page for every address. No account exists either way, and this
+  # branch never looks one up, so the answer cannot say whether the email is known.
+  def create_passwordless
+    email = (params.dig(:user, :email) || params[:email]).to_s.strip.downcase
+    if email.match?(URI::MailTo::EMAIL_REGEXP)
+      begin
+        rescue_and_log do
+          token = issue_magic_link(email, nil)
+          Studio::Email.deliver(UserMailer, :magic_link, email, token, to: email)
+        end
+      rescue StandardError
+        return redirect_to signup_path, alert: DELIVERY_FAILED
       end
-      return redirect_to login_path, notice: "Check your inbox — we just emailed you a #{Studio::AuthLabels.link_noun(Studio.sign_in_label)}."
     end
+    redirect_to login_path, notice: "Check your inbox — we just emailed you a #{Studio::AuthLabels.link_noun(Studio.sign_in_label)}."
+  end
 
+  # A validation failure is the visitor's input: re-render the form with its
+  # errors and write no ErrorLog row. Anything else is logged and re-raised to
+  # the engine's catch-all, never swallowed.
+  #
+  # No `target:` here. The user is unsaved when the raise lands, and ErrorLog's
+  # belongs_to would autosave it while writing the row: the same failing write a
+  # second time, inside the logger. That raise escapes before @_error_logged is
+  # set, so the catch-all logs the same failure again: two rows for one error.
+  def create_with_password
     @user = User.new(user_params)
-    Studio.configure_new_user.call(@user)
-    rescue_and_log(target: @user) do
-      @user.save!
-      set_app_session(@user)
-      redirect_to root_path, notice: Studio.welcome_message.call(@user)
+    rescue_and_log do
+      Studio.configure_new_user.call(@user)
+      if @user.save
+        set_app_session(@user)
+        redirect_to root_path, notice: Studio.welcome_message.call(@user)
+      else
+        render :new, status: :unprocessable_entity
+      end
     end
-  rescue StandardError => e
-    render :new, status: :unprocessable_entity
   end
 
-  private
-
+  # A POST with no `user` key builds a blank user, whose validations then
+  # re-render the form, rather than a ParameterMissing the form cannot show.
   def user_params
-    params.require(:user).permit(*Studio.registration_params)
+    params.fetch(:user, {}).permit(*Studio.registration_params)
   end
 end

data/app/controllers/style_controller.rb

@@ -19,4 +19,10 @@ class StyleController < ApplicationController
   rescue StandardError => e
     Rails.logger.warn("[style] theme preload skipped: #{e.message}")
   end
+
+  # One page of the Loaders section's demo feed, at /admin/style/loaders_feed?page=N
+  # (style/_loaders_feed_page; Studio::Loader::DEMO_FEED_PAGES pages).
+  def loaders_feed
+    @page = params[:page].to_i.clamp(1, Studio::Loader::DEMO_FEED_PAGES)
+  end
 end

data/app/helpers/studio/agent_chat_helper.rb

@@ -1,8 +1,21 @@
 # frozen_string_literal: true
 
 module Studio
-  # The agent chat's voice option (docs/AGENT_CHAT.md, "Talking by voice").
+  # The agent chat's voice option (docs/AGENT_CHAT.md, "Talking by voice"), and
+  # the link that opens the talk-to-agent modal ("Talk to an agent in a modal").
   module AgentChatHelper
+    # A link that opens studio/agent_chat/_talk_modal with `soul`, `topic` and
+    # an optional `opener` (the visitor's first message; default "I'd like to
+    # talk about <topic>."). `href` is where the link goes when the modal is not
+    # on the page, did not load, or the click is a modified one (a new tab): a
+    # real chat page, so no click is ever lost. A block replaces `label`.
+    def studio_talk_to_agent_link(label = nil, href:, soul:, topic: nil, opener: nil, **options, &block)
+      data = (options.delete(:data) || {}).merge(studio_talk_to_agent: true, talk_soul: soul.to_s,
+                                                  talk_topic: topic.to_s.presence, talk_opener: opener.to_s.presence).compact
+      options[:aria] = { haspopup: "dialog" }.merge(options[:aria] || {})
+      block ? link_to(href, **options, data: data, &block) : link_to(label, href, **options, data: data)
+    end
+
     # The signed-in user on this page, or nil. A page whose controller has no
     # current_user is a signed-out page.
     def studio_agent_chat_viewer

data/app/helpers/studio/crumbs_helper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Studio
+  # The crumb trail for studio/_page_header, from the app's parent map (Studio::Crumbs,
+  # docs/PAGE_HEADER.md). Prefixed for the reason Studio::GeoHelper gives: every helper
+  # module is included into every view.
+  #
+  #   studio_crumbs(:deployments)                 the map's own page: its ancestors
+  #   studio_crumbs(parent: :deployments)         a page not in the map: its parent and up
+  #   studio_crumbs(:release, release: @release)  keywords for the map's lambdas
+  #   studio_crumbs_here                          an engine page: the map's page at this address
+  #
+  # A key the map lacks raises in development and test, and in production logs and
+  # draws no trail (Studio::Crumbs.strict?), so a typo is not a 500.
+  module CrumbsHelper
+    def studio_crumbs(key = nil, parent: nil, **locals)
+      Studio.crumbs.trail(self, key, parent: parent, **locals)
+    rescue Studio::Crumbs::UnknownPage, Studio::Crumbs::Cycle => error
+      raise if Studio::Crumbs.strict?
+
+      Studio::Crumbs.report(error)
+      []
+    end
+
+    # The trail for the page at this request's address, from the host's map, or none. An
+    # engine page cannot know the host's key for itself, so it asks by address.
+    def studio_crumbs_here
+      return [] unless respond_to?(:request) && request
+
+      key = Studio.crumbs.key_for_path(self, request.path)
+      key ? studio_crumbs(key) : []
+    end
+  end
+end

data/app/helpers/studio/loader_helper.rb

@@ -13,6 +13,12 @@ module Studio
   #   <%= studio_loader_pending %>                  inside a submit button
   #   <%= studio_loader_overlay %>                  the page-load overlay (layout, once)
   #
+  # The plain styles draw no icon, only theme colours (docs/LOADER.md, "The family"):
+  #
+  #   <%= studio_loader style: :spinner %>          a ring, 20px
+  #   <%= studio_loader style: :dots %>             three pulsing dots
+  #   <%= studio_loader style: :bar, percent: 40 %> a bar; without percent it sweeps
+  #
   # Prefixed names for the reason Studio::GeoHelper gives: every helper module is
   # included into every view.
   module LoaderHelper
@@ -22,7 +28,7 @@ module Studio
     LOADER_BEAD_LAYERS = [[46, 9, 0.5], [30, 9, 0.75], [16, 9, 0.95], [7, 9.5, 1], [2.6, 10, 1], [0.3, 17, 1]].freeze
     LOADER_BEAD_UNIT = 264.3
 
-    def studio_loader(size: 96, style: nil, icon: nil, art: nil, label: "Loading", percent: nil,
+    def studio_loader(size: nil, style: nil, icon: nil, art: nil, label: "Loading", percent: nil,
                       tone: nil, pending: false, **html)
       config = Studio.loader
       style = style ? Studio::Loader.style!(style) : config[:style]
@@ -34,7 +40,7 @@ module Studio
 
       render "studio/loader/loader",
              style: style,
-             size: studio_loader_size(size),
+             size: studio_loader_size(size.nil? ? Studio::Loader.default_size(style) : size),
              icon: icon || Studio.loader_icon,
              art: art_data,
              label: label,
@@ -64,6 +70,77 @@ module Studio
       render "studio/loader/overlay", label: label, delay: delay.to_i, min_show: min_show.to_i, max_wait: max_wait.to_i, size: size, options: options
     end
 
+    # ---- The rest of the family: the page's shape while it waits ----------
+
+    SKELETON_KINDS = %i[lines avatar card media].freeze
+    SKELETON_LINES = { lines: 3, avatar: 2, card: 2, media: 0 }.freeze
+    # Line widths, in turn, so a block of lines reads as text; the last is short.
+    SKELETON_WIDTHS = [100, 94, 86, 97, 90].freeze
+
+    # Grey shapes of the content to come (docs/LOADER.md, "Skeleton"). The
+    # wrapper is aria-busy; every shape is hidden from assistive tech, and one
+    # line of screen-reader text names the wait. Any html option lands on the
+    # wrapper, which is a grid: give it a class for the layout of `count` items.
+    #
+    #   <%= studio_skeleton %>                                  three lines
+    #   <%= studio_skeleton :avatar, count: 4 %>                four list rows
+    #   <%= studio_skeleton :card, count: 3, class: "sm:grid-cols-3" %>
+    #   <%= studio_skeleton :media %>                           one 16:9 block
+    def studio_skeleton(kind = :lines, count: 1, lines: nil, label: "Loading", **html)
+      kind = kind.to_s.to_sym
+      unless SKELETON_KINDS.include?(kind)
+        raise ArgumentError, "studio_skeleton kind must be one of #{SKELETON_KINDS.map(&:inspect).join(', ')} (got #{kind.inspect})"
+      end
+
+      render "studio/loader/skeleton",
+             kind: kind,
+             count: count.to_i.clamp(1, 50),
+             lines: (lines.nil? ? SKELETON_LINES[kind] : lines.to_i.clamp(0, 12)),
+             label: label,
+             html: html
+    end
+
+    # The width of line `index` of `total`, as a CSS length.
+    def studio_skeleton_width(index, total)
+      return "60%" if total > 1 && index == total - 1
+
+      "#{SKELETON_WIDTHS[index % SKELETON_WIDTHS.size]}%"
+    end
+
+    # A list that loads its next page as its end comes near (docs/LOADER.md,
+    # "Infinite scroll"). The block is one page of items; the view renders the
+    # same call for every page, with `page` and the next page's URL (nil on the
+    # last). Each later page arrives inside a <turbo-frame> nested in the one
+    # before, so the list grows in place; a visible "Load more" link loads it
+    # by itself, with the keyboard or with no script.
+    #
+    #   <%= studio_infinite_scroll id: "posts", page: @page,
+    #         next_url: (posts_path(page: @page + 1) if @more) do %>
+    #     <% @posts.each do |post| %><%= render post %><% end %>
+    #   <% end %>
+    def studio_infinite_scroll(id:, page: 1, next_url: nil, more_label: "Load more",
+                               end_label: "That is everything", announce: "%{count} more loaded", **html, &block)
+      page = [page.to_i, 1].max
+      render "studio/loader/infinite_scroll",
+             id: id.to_s,
+             page: page,
+             next_url: next_url.presence,
+             more_label: more_label,
+             end_label: end_label,
+             announce: announce,
+             items: capture(&block),
+             html: html
+    end
+
+    def studio_infinite_scroll_frame_id(id, page) = "#{id}-page-#{page}"
+
+    # Pull the page down from its top to reload it: phones with touch only
+    # (docs/LOADER.md, "Pull to refresh"). Wraps the block. With `frame:` it
+    # reloads that <turbo-frame>; without, the page, as a replace visit.
+    def studio_pull_to_refresh(frame: nil, label: "Refreshing", **html, &block)
+      render "studio/loader/pull_to_refresh", frame: frame, label: label, body: capture(&block), html: html
+    end
+
     def studio_loader_size(size)
       size.is_a?(Numeric) ? "#{size}px" : size.to_s
     end