studio-engine 0.111.3 → 0.112.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ab9a9a4e4e6a34bf0a48ef2c2f06b9d1f6b3c2f9f0bbc17730e0cfb22180b0d
-  data.tar.gz: d8a4142dbe8272eab927353dbd6885b143f6130b32b38bb20cdb2f720bb603b6
+  metadata.gz: '09a16af7f2551278541c2fed1ac5a1c360b37f5de50cfdbd0316f531ba691406'
+  data.tar.gz: e8b69c9399401bea6e9efd2e231dc2100d89bfd2c9d9032a9f64f431df8ef0c8
 SHA512:
-  metadata.gz: bff9c7c9e6e8f4f10822fece60dcf57d18f2f5de4beabeedb2f0e55afafbc2faeda6421e455b9eca9e96faf400bac471a99789ba9b4cc2274b345cd453802ec1
-  data.tar.gz: b6978c646770e0606fab504ba0f8700aeb86355bf0bcb7465a7c22a5d401d508f588feb4ccbefc3f917122fb9f992336e5efe35b687d23d5e0fb324e78aaaa21
+  metadata.gz: f25be26a1ef2ffc0a4684787878e221ddaf03b9ac5839a988780e9c1ad38d1199a755e36e6acfa9cff516fac27a1ceb7184724ce34f70ec158d8e7fa4f407049
+  data.tar.gz: 64ac19247ffaddbe3f2d9095c41ab19aeddad3f011f27b03894f659dd573aba832bedc781c27df9047e806021ef3a789e1d223f214a695e01da186b5e1c1970c

data/CHANGELOG.md

@@ -4,6 +4,24 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.112.0 — 2026-10-19
+
+### Added
+
+- **`Studio.navbar_signed_out_cta`: a call to action on the signed-out navbar.**
+  Set it to `{ label: "Build App", path: "/build" }` (or a callable receiving
+  the view) and the signed-out primary button carries that label and path,
+  while sign-in stays one tap away as a quiet `Studio.sign_in_label` link to
+  `login_path`: beside the button from `md`, and in the mobile sub-navbar below
+  `md`, where the top row has no room for both. It is separate from
+  `Studio.sign_in_label`, which also words the engine's auth pages. Unset (the
+  default) the navbar renders byte-identical to before; signed in it changes
+  nothing. A bad Hash raises `Studio::NavbarSignedOutCta::InvalidConfig` at
+  assignment; a raising callable falls back to the sign-in button and is
+  reported once. `components/_user_nav`'s own signed-out branch (a sign-in
+  link and Sign up, reached through `show_logged_in: true`) is unchanged.
+  README, *Signed-out call to action*.
+
 ## 0.111.3 — 2026-10-18
 
 ### Fixed

data/README.md

@@ -736,6 +736,36 @@ end
   *log-on link*. The "Sign in with Google" and "Sign up" buttons are not
   sign-in labels and do not change.
 
+### Signed-out call to action — `Studio.navbar_signed_out_cta`
+
+What the signed-out navbar's primary button does. Unset (`nil`, the default),
+it is the sign-in button, `Studio.sign_in_label` to `login_path`, and the navbar
+renders the same bytes as before the setting. Rules:
+`lib/studio/navbar_signed_out_cta.rb`.
+
+```ruby
+Studio.configure do |config|
+  config.navbar_signed_out_cta = { label: "Build App", path: "/build" }
+  # or a callable receiving the view; nil keeps the sign-in button for that render
+  # config.navbar_signed_out_cta = ->(view) { { label: "Play", path: view.contests_path } }
+end
+```
+
+- Set, the primary button carries `label:` to `path:`, and sign-in stays one tap
+  away as a quiet text link (`Studio.sign_in_label` to `login_path`): beside the
+  button from `md`, and in the phone row under the header below `md`, where the
+  top row has no room for two controls beside the brand. Both sign-in links
+  carry `data-nav-sign-in`; the button carries `data-nav-signed-out-cta`.
+- It is a separate setting from `sign_in_label` on purpose: that label also
+  words the engine's auth pages, so it cannot double as a marketing CTA.
+- Signed in, the setting changes nothing.
+- `label:` and `path:` are required non-blank text, both escaped. A bad Hash
+  raises `Studio::NavbarSignedOutCta::InvalidConfig` at assignment, a callable's
+  bad answer at render. A callable that raises falls back to the sign-in button
+  and is reported once per process per error class, never a 500.
+- A host on an older engine can set it safely with
+  `Studio.navbar_signed_out_cta = … if Studio.respond_to?(:navbar_signed_out_cta=)`.
+
 ### User nav slots
 
 `components/_user_nav.html.erb` renders the right-side navbar user section.

data/app/helpers/studio_navbar_helper.rb

@@ -11,6 +11,15 @@ module StudioNavbarHelper
     @studio_navbar_links ||= Studio.navbar_links_for(self)
   end
 
+  # The signed-out CTA ({ label:, path: }) or nil for the sign-in button.
+  # Resolved once per render pass: the desktop button and the phone row's
+  # sign-in link both ask, and a host callable may read the request.
+  def studio_navbar_signed_out_cta
+    return @studio_navbar_signed_out_cta if defined?(@studio_navbar_signed_out_cta)
+
+    @studio_navbar_signed_out_cta = Studio.navbar_signed_out_cta_for(self)
+  end
+
   # One resolved link. size is the text utility: text-sm on desktop, text-xs
   # in the phone row, matching the links apps hand-wrote in forked navbars.
   def studio_navbar_link_tag(link, size:)

data/app/views/layouts/_navbar.html.erb

@@ -31,6 +31,12 @@
 <%# Studio.navbar_links: links for the desktop bar and phone row.
     Empty by default, which renders the same bytes as before. %>
 <% navbar_links = respond_to?(:studio_navbar_links) ? studio_navbar_links : [] %>
+<%# Studio.navbar_signed_out_cta: signed out, the primary button can carry a
+    call to action instead of sign-in. nil (the default) renders the same bytes
+    as before. Set, sign-in stays one tap away as a quiet text link: beside the
+    button from md, and in the phone row below md, where the top row has no
+    room for two controls beside the brand. %>
+<% signed_out_cta = !show_user && respond_to?(:studio_navbar_signed_out_cta) ? studio_navbar_signed_out_cta : nil %>
 <% if sidebar_active %>
   <% sidebar_trigger_desktop = capture { render "components/link_sidebar_trigger", class_name: "hidden md:inline-flex" } %>
   <% extra_icons_html = safe_join([extra_icons_html, sidebar_trigger_desktop].compact) %>
@@ -196,7 +202,12 @@
         <div class="flex items-center justify-end gap-3">
           <%= sidebar_trigger_desktop if sidebar_active %>
           <span class="hidden md:flex"><%= render "components/theme_toggle_morph" %></span>
+          <% if signed_out_cta %>
+          <%= link_to Studio.sign_in_label, login_path, class: "hidden md:inline text-sm font-semibold text-secondary hover:text-primary whitespace-nowrap transition", data: { nav_sign_in: "" } %>
+          <%= link_to signed_out_cta[:label], signed_out_cta[:path], class: "btn btn-primary whitespace-nowrap", data: { nav_signed_out_cta: "" } %>
+          <% else %>
           <%= link_to Studio.sign_in_label, login_path, class: "btn btn-primary" %>
+          <% end %>
         </div>
       <% end %>
     </div>
@@ -211,6 +222,9 @@
     </nav>
     <% end %>
     <span class="ml-auto flex items-center gap-3">
+      <% if signed_out_cta %>
+      <%= link_to Studio.sign_in_label, login_path, class: "text-xs font-semibold text-secondary hover:text-primary whitespace-nowrap transition", data: { nav_sign_in: "" } %>
+      <% end %>
       <%= render "components/link_sidebar_trigger" if sidebar_active %>
       <%= render "components/admin_dropdown" unless sidebar_active && studio_sidebar_replaces_admin_menu? %>
       <%= render "components/theme_toggle_morph" %>

data/lib/studio/navbar_signed_out_cta.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Resolves Studio.navbar_signed_out_cta, the call to action the engine navbar's
+# signed-out primary button carries in place of sign-in. Pure Ruby, so the unit
+# suite covers it without the dummy app.
+#
+# Studio.navbar_signed_out_cta is one of:
+#
+#   nil                              the default: the button is the sign-in
+#                                    button (Studio.sign_in_label -> login_path),
+#                                    byte-identical to before the setting
+#   { label: "Build App", path: "/build" }
+#                                    the button carries this label and path, and
+#                                    a quiet sign-in text link sits beside it
+#   ->(view) { { label:, path: } }   a callable receiving the view; answering nil
+#                                    keeps the default for that render
+#
+# It is separate from Studio.sign_in_label on purpose: that label also words the
+# engine's own auth pages (lib/studio/auth_labels.rb), so it cannot be bent into
+# a marketing CTA. The sign-in link always keeps it.
+#
+# A bad static Hash raises InvalidConfig at assignment; a callable's answer is
+# checked when it resolves and raises the same error. A callable that RAISES
+# is a runtime fault, not a shape fault: the navbar falls back to the sign-in
+# button and the failure is reported once per process per error class, so a
+# layout never 500s over a CTA.
+module Studio
+  module NavbarSignedOutCta
+    class InvalidConfig < ArgumentError; end
+
+    KEYS = %i[label path].freeze
+
+    @reported = {}
+    @reported_lock = Mutex.new
+
+    module_function
+
+    # The CTA for one render, as { label:, path: } with plain String values, or
+    # nil for the default sign-in button.
+    def resolve(config, view)
+      return nil if config.nil?
+      return normalize(config) unless config.respond_to?(:call)
+
+      begin
+        answer = config.call(view)
+      rescue StandardError => e
+        report_once(e)
+        return nil
+      end
+      answer.nil? ? nil : normalize(answer)
+    end
+
+    # Shape check without a view: a static Hash fails at boot, not on the first
+    # signed-out page. A callable is checked when it resolves.
+    def validate!(config)
+      return nil if config.nil? || config.respond_to?(:call)
+
+      normalize(config)
+      nil
+    end
+
+    def normalize(config)
+      unless config.is_a?(Hash)
+        raise InvalidConfig, "Studio.navbar_signed_out_cta must be nil, a Hash { label:, path: } " \
+                             "or a callable returning one (got #{config.class})"
+      end
+
+      config = config.to_h { |key, value| [key.to_sym, value] }
+      unknown = config.keys - KEYS
+      raise InvalidConfig, "Studio.navbar_signed_out_cta has unknown key :#{unknown.first}" if unknown.any?
+
+      KEYS.to_h do |key|
+        value = config[key]
+        unless (value.is_a?(String) || value.is_a?(Symbol)) && !value.to_s.strip.empty?
+          raise InvalidConfig, "Studio.navbar_signed_out_cta needs a non-blank :#{key} (got #{value.inspect})"
+        end
+
+        # String.new drops an html_safe flag, so ERB escapes whatever came back.
+        [key, String.new(value.to_s).strip]
+      end
+    end
+
+    # Forget what was reported, so a reconfigured callable reports its own failure.
+    def reset_reported!
+      @reported_lock.synchronize { @reported.clear }
+    end
+
+    def report_once(error)
+      first = @reported_lock.synchronize { @reported[error.class.name] ? false : (@reported[error.class.name] = true) }
+      return unless first
+
+      if defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+        ::ErrorLog.capture!(error)
+      elsif defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+        ::Rails.logger.warn("[studio-navbar] Studio.navbar_signed_out_cta failed, showing the sign-in button: " \
+                            "#{error.class}: #{error.message}")
+      end
+    rescue StandardError
+      nil # reporting is best-effort: the navbar still renders
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.111.3"
+  VERSION = "0.112.0.rc1"
 end

data/lib/studio.rb

@@ -33,6 +33,7 @@ require "studio/sidebar_sections"
 require "studio/site_footer"
 require "studio/booking"
 require "studio/navbar_links"
+require "studio/navbar_signed_out_cta"
 require "studio/navbar_identity"
 require "studio/navbar_wordmark"
 require "studio/auth_labels"
@@ -279,6 +280,25 @@ module Studio
     @@sign_in_label = label
   end
 
+  # ---- Navbar signed-out CTA ----
+  # What the signed-out navbar's primary button does. nil, the default, keeps
+  # the sign-in button (sign_in_label -> login_path) byte-identical to before.
+  # Set, the button carries this label and path and a quiet sign-in text link
+  # (sign_in_label -> login_path) sits beside it on desktop and in the phone row
+  # under it. A Hash, or a callable receiving the view (nil keeps the default).
+  # Separate from sign_in_label, which also words the engine's auth pages.
+  # Rules: lib/studio/navbar_signed_out_cta.rb.
+  #
+  #   config.navbar_signed_out_cta = { label: "Build App", path: "/build" }
+  #   config.navbar_signed_out_cta = ->(view) { { label: "Play", path: view.contests_path } }
+  mattr_reader :navbar_signed_out_cta, default: nil
+
+  def self.navbar_signed_out_cta=(config)
+    NavbarSignedOutCta.validate!(config)
+    NavbarSignedOutCta.reset_reported!
+    @@navbar_signed_out_cta = config
+  end
+
   # ---- The shared profile page (/profile) ----
   # The rows that make up /profile. `nil` — the default — means "the engine's
   # standard page", NOT "no rows": a brand-new app with an empty initializer gets
@@ -1414,6 +1434,12 @@ module Studio
     NavbarLinks.resolve(navbar_links, view)
   end
 
+  # The signed-out CTA for a view, or nil for the sign-in button
+  # (lib/studio/navbar_signed_out_cta.rb).
+  def self.navbar_signed_out_cta_for(view)
+    NavbarSignedOutCta.resolve(navbar_signed_out_cta, view)
+  end
+
   # The signed-in user's navbar name for a view (lib/studio/navbar_identity.rb).
   def self.navbar_user_name_for(user, view = nil)
     NavbarIdentity.user_name(user, view, config: navbar_user_name)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.111.3
+  version: 0.112.0.rc1
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-19 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -763,6 +763,7 @@ files:
 - lib/studio/name_parts.rb
 - lib/studio/navbar_identity.rb
 - lib/studio/navbar_links.rb
+- lib/studio/navbar_signed_out_cta.rb
 - lib/studio/navbar_wordmark.rb
 - lib/studio/newsletter.rb
 - lib/studio/oauth_identity.rb