studio-engine 0.79.0 → 0.80.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a41688fc9d2fd9a08b96ea00d90e971d3be7618577acf83887d7c64b71076d3
-  data.tar.gz: 6930fd3598433185b2c578ebc2f287a54c972828ab73f068800521f76793a82a
+  metadata.gz: 7b9678d8f3c7e2fbb15531909b721ff80ccd9e933d15c283e0c7fa1861137b11
+  data.tar.gz: c495551acf3d80d22f1c7760d65cabb0f949021680f94f152514e409c117400a
 SHA512:
-  metadata.gz: c089670e6c2ba85bac8a7851f13f4fa033801e738583974d7207d1960ebccf181530feec5ef3c4cd8f4ae5300d793b5d54eaeb91f46cd9732287f2d44d31ab13
-  data.tar.gz: c6e24cd7de1298e73e58309da359ffcdae06d150e0b13afba52f90f8864782d6c197b22cf7b61279d88a1d98e52b562eafb7f4e76cd968f6088bb77c3fb3b011
+  metadata.gz: 9c28aa14a0b3a28ca0dd876fc0835431f66588159ec3d11e79f6319f9350be50e4a49d4e6891253334a07f3a0c49db0974e74819b2d2d6f40a17460f5b8e68f9
+  data.tar.gz: 1221cfc40625adeda5fda0293de168969e95d50e43ecb01f2dde1c21c2d0b0f41807b10118f63f291ca74c094f7b1eec1ae23dc4b107be6e6543de8c5b2274ca

data/CHANGELOG.md

@@ -4,6 +4,19 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.80.0 — 2026-09-30
+
+### Added
+
+- **`Studio.navbar_user_name` and `Studio.sign_in_label` set the navbar's two
+  identity words.** `navbar_user_name` takes a method name (`:player_name`) or a
+  callable `->(user, view)` and replaces `display_name` in the signed-in user
+  nav; a blank answer or a raise falls back to `display_name`, and a raise is
+  reported once rather than 500ing the layout. `sign_in_label` (default
+  `"Log in"`) labels the signed-out button in `layouts/_navbar` and
+  `components/_user_nav`. An app that sets neither renders the same navbar bytes
+  as before. See the README, *Navbar identity*.
+
 ## 0.79.0 — 2026-09-30
 
 ### Changed

data/README.md

@@ -611,6 +611,36 @@ end
 - A bad entry raises `Studio::NavbarLinks::InvalidLink` naming its index: at
   assignment for a static Array, at render for a callable.
 
+### Navbar identity — `Studio.navbar_user_name` and `Studio.sign_in_label`
+
+Two words the navbar says about the viewer. Both defaults render the navbar
+byte-identical to before, so an app that sets neither sees no change. Rules:
+`lib/studio/navbar_identity.rb`.
+
+```ruby
+Studio.configure do |config|
+  # The signed-in name in components/_user_nav. nil (the default) is display_name.
+  config.navbar_user_name = :player_name                        # a method on the user
+  # config.navbar_user_name = ->(user, view) { user.player_name } # or a callable
+
+  # The signed-out button in layouts/_navbar and components/_user_nav.
+  config.sign_in_label = "Sign in"                              # default "Log in"
+end
+```
+
+- `navbar_user_name` is `nil`, a method name (Symbol or String), or a callable.
+  A two-argument callable gets `(user, view)`; a one-argument callable gets the
+  user alone.
+- The name is always escaped, even when the method or callable returns an
+  `html_safe` string.
+- A method or callable that answers blank falls back to `display_name`. One
+  that raises also falls back, and the error is reported once per process per
+  error class (to `ErrorLog` when the app has it, else the Rails log), so a
+  broken setting never 500s the layout.
+- The engine has no I18n catalogue, so the label is plain config, not a locale
+  key. A blank or non-String label, or a `navbar_user_name` of any other type,
+  raises `Studio::NavbarIdentity::InvalidConfig` at assignment.
+
 ### User nav slots
 
 `components/_user_nav.html.erb` renders the right-side navbar user section.

data/app/views/components/_user_nav.html.erb

@@ -11,6 +11,10 @@
                          address + level progress bar) entirely
                          (e.g. a seeds bar)
 
+    Config, not locals: the signed-in name is Studio.navbar_user_name
+    (default display_name) and the signed-out button reads
+    Studio.sign_in_label (default "Log in"); lib/studio/navbar_identity.rb.
+
     Other locals:
       show_logout_link — boolean, show explicit "Log out" link in the
                          second row (Studio uses this)
@@ -204,7 +208,7 @@
         the link's accessible name. %>
     <% account_classes = "group flex items-center gap-2 flex-shrink-0" %>
     <% account_inner = capture do %>
-      <span class="sr-only md:not-sr-only md:max-w-40"><span class="block truncate text-right text-heading font-semibold text-base leading-none transition<%= " group-hover:text-primary" if studio_nav_destination %>" data-nav-name><%= current_user.display_name %></span></span>
+      <span class="sr-only md:not-sr-only md:max-w-40"><span class="block truncate text-right text-heading font-semibold text-base leading-none transition<%= " group-hover:text-primary" if studio_nav_destination %>" data-nav-name><%= Studio.navbar_user_name_for(current_user, self) %></span></span>
       <span class="flex-shrink-0 flex items-center" aria-hidden="true">
         <%= render "components/avatar", user: current_user, size: "nav" %>
       </span>
@@ -219,7 +223,7 @@
     <%# Desktop only, as above: the phone row carries the toggle below md. %>
     <span class="hidden md:flex" data-nav-theme-toggle="desktop"><%= render "components/theme_toggle_morph" %></span>
     <div class="flex items-center gap-3 ml-auto">
-      <%= link_to "Log in", login_path, class: "text-heading hover:text-primary text-sm font-semibold transition" %>
+      <%= link_to Studio.sign_in_label, login_path, class: "text-heading hover:text-primary text-sm font-semibold transition" %>
       <%= link_to "Sign up", signup_path, class: "btn btn-primary btn-sm" %>
     </div>
   <% end %>

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

@@ -162,7 +162,7 @@
         <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>
-          <%= link_to "Log in", login_path, class: "btn btn-primary" %>
+          <%= link_to Studio.sign_in_label, login_path, class: "btn btn-primary" %>
         </div>
       <% end %>
     </div>

data/lib/studio/navbar_identity.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Resolves the two words the engine navbar says about who is (or is not) signed
+# in: the signed-in user's name (Studio.navbar_user_name) and the signed-out
+# button's label (Studio.sign_in_label). Pure Ruby, so the unit suite covers it
+# without the dummy app.
+#
+# Studio.navbar_user_name is one of:
+#
+#   nil                     the default: user.display_name, as before
+#   :player_name            a method called on the user ("player_name" works too)
+#   ->(user, view) { ... }  a callable; a one-argument callable gets the user only
+#
+# A layout must not 500 over a name. When the configured method or callable
+# RAISES, the navbar prints display_name and the failure is reported once per
+# process per error class (ErrorLog when the host has it, else Rails.logger),
+# not once per page view. A BLANK answer falls back to display_name quietly:
+# a user with no player name yet is data, not a fault.
+#
+# The name comes back as a plain String, never an html_safe buffer, so ERB
+# escapes whatever a host's method or callable returned.
+module Studio
+  module NavbarIdentity
+    class InvalidConfig < ArgumentError; end
+
+    DEFAULT_SIGN_IN_LABEL = "Log in"
+
+    @reported = {}
+    @reported_lock = Mutex.new
+
+    module_function
+
+    def user_name(user, view = nil, config: Studio.navbar_user_name)
+      fallback = user.display_name # outside the rescue: the default path is not ours to swallow
+      return fallback if config.nil?
+
+      begin
+        text = plain_text(configured_name(config, user, view))
+      rescue StandardError => e
+        report_once(e)
+        return fallback
+      end
+      text.empty? ? fallback : text
+    end
+
+    def validate_name!(config)
+      return nil if config.nil? || config.respond_to?(:call)
+      return nil if (config.is_a?(Symbol) || config.is_a?(String)) && !config.to_s.strip.empty?
+
+      raise InvalidConfig, "Studio.navbar_user_name must be nil, a method name (Symbol) or a callable " \
+                           "->(user, view) (got #{config.inspect})"
+    end
+
+    def validate_label!(label)
+      return nil if label.is_a?(String) && !label.strip.empty?
+
+      raise InvalidConfig, "Studio.sign_in_label must be non-blank text (got #{label.inspect})"
+    end
+
+    # Forget what was reported, so a reconfigured name reports its own failure.
+    def reset_reported!
+      @reported_lock.synchronize { @reported.clear }
+    end
+
+    def configured_name(config, user, view)
+      return user.public_send(config.to_sym) unless config.respond_to?(:call)
+
+      config.respond_to?(:arity) && config.arity == 1 ? config.call(user) : config.call(user, view)
+    end
+
+    # String.new drops an html_safe flag: SafeBuffer#to_s returns the buffer
+    # itself, which ERB would print raw.
+    def plain_text(value)
+      String.new(value.to_s).strip
+    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_user_name failed, showing display_name: " \
+                            "#{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.79.0"
+  VERSION = "0.80.0"
 end

data/lib/studio.rb

@@ -13,6 +13,7 @@ require "studio/js_identifier"
 require "studio/partial_block"
 require "studio/sidebar_sections"
 require "studio/navbar_links"
+require "studio/navbar_identity"
 require "studio/profile_sections"
 require "studio/profile_image"
 require "studio/oauth_identity"
@@ -192,6 +193,33 @@ module Studio
     @@navbar_links = links
   end
 
+  # ---- Navbar identity ----
+  # The name the signed-in user nav prints, and the signed-out button's label.
+  # Both defaults render the navbar byte-identical to before. The engine has no
+  # I18n catalogue, so the label is plain config rather than a locale key.
+  # Rules: lib/studio/navbar_identity.rb.
+  #
+  #   config.navbar_user_name = :player_name                          # a method on the user
+  #   config.navbar_user_name = ->(user, view) { user.player_name }   # or a callable
+  #   config.sign_in_label    = "Sign in"
+  #
+  # nil means user.display_name. A method or callable that raises, or answers
+  # blank, falls back to display_name; a raise is reported once, never a 500.
+  mattr_reader :navbar_user_name, default: nil
+
+  def self.navbar_user_name=(config)
+    NavbarIdentity.validate_name!(config)
+    NavbarIdentity.reset_reported!
+    @@navbar_user_name = config
+  end
+
+  mattr_reader :sign_in_label, default: NavbarIdentity::DEFAULT_SIGN_IN_LABEL
+
+  def self.sign_in_label=(label)
+    NavbarIdentity.validate_label!(label)
+    @@sign_in_label = label
+  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
@@ -902,6 +930,11 @@ module Studio
     NavbarLinks.resolve(navbar_links, 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)
+  end
+
   # The engine's standard /profile rows. Hosts compose against this rather than
   # restating a literal list, so a later release that adds a standard row
   # delivers it to every app that used the seam as intended.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.79.0
+  version: 0.80.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -573,6 +573,7 @@ files:
 - lib/studio/log_rotation.rb
 - lib/studio/mail_transport.rb
 - lib/studio/name_parts.rb
+- lib/studio/navbar_identity.rb
 - lib/studio/navbar_links.rb
 - lib/studio/newsletter.rb
 - lib/studio/oauth_identity.rb