studio-engine 0.77.4 → 0.78.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9497ed872cea58d146d2859f8220ad71e3979b2b1603fb263622081c29e3144e
-  data.tar.gz: 7de61f4d57e71e09bf6d5fa32acd0309625e547d52b0d4bbfc45c94f7bd60328
+  metadata.gz: 12e1056052d4d49cd70e0ca81e8a39fc4f1c370166d73ea319315337fc648f5f
+  data.tar.gz: 0d94f90bff68c27a6c86d07ad53904b330a3717121f5f944244d0153a2e53a63
 SHA512:
-  metadata.gz: d443cc7d3b914255adef0e681d926c4bb88c92dd1cbe4814195a5a6c55132e95e58550ddb14d6277b717bf6a7778823620c87ab7aa3bba0499373b0db33063b3
-  data.tar.gz: e4e6df7c16f17a790b9058030d2f3b1b519ca882ac13069ea69f641b76974ca9fabd47a0de8ec89d9e8333dfbd428a2fdbdf46334c5d4e046ba4ba737ee2c2fe
+  metadata.gz: cb929bb288de471829b57f90cfbf01fff7d4e51d68607da51b32df832ad4946662a0617a85002ec6244c23fb3d3d17db069528b090690378ba68a7f53669141a
+  data.tar.gz: bb9eb9c389d8d89887ba72b0bff91b080944b501c3564aed06b26b317f013445f6fd9636d327ba20e70cfd7e4d3065928b6d091eed8c22160e6b819de69825ba

data/CHANGELOG.md

@@ -4,6 +4,16 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.78.0 — 2026-09-29
+
+### Added
+
+- **`Studio.navbar_links` puts app links in the engine navbar.** An Array, or a
+  callable receiving the view, of `{ label:, href:, active:, badge: }` renders in
+  the desktop bar and the phone row, with `aria-current` on the active link and
+  an optional badge such as `"#12"`. An app that registers nothing renders the
+  same navbar bytes as before. See the README, *Navigation*.
+
 ## 0.77.4 — 2026-09-28
 
 ### Fixed

data/README.md

@@ -583,6 +583,34 @@ undefined, so mount `studio/modals/host` before writing a trigger.
 Full contract, including what the partial may assume: the doc comment at the top
 of `app/views/style/_host.html.erb`.
 
+### Navigation — `Studio.sidebar_sections` and `Studio.navbar_links`
+
+Two seams, both empty by default, so the navbar is unchanged until an app opts in.
+
+- `sidebar_sections` fills the slide-out link sidebar (the cog trigger in the icon
+  rail). Rules: `lib/studio/sidebar_sections.rb`.
+- `navbar_links` fills the navbar's own link slots: the desktop bar beside the
+  logo and the phone row under it. Rules: `lib/studio/navbar_links.rb`.
+
+```ruby
+Studio.configure do |config|
+  # An Array, or a callable receiving the view (so a badge can read current_user).
+  config.navbar_links = ->(view) {
+    [ { label: "Contests", href: view.contests_path, active: %r{\A/contests} },
+      { label: "Rank", href: "/rank",
+        badge: (view.logged_in? ? "##{view.current_user.rank}" : nil) } ]
+  }
+end
+```
+
+- `label:` and `href:` are required; both are escaped.
+- `active:` is `true`/`false`, a Regexp, or a callable taking `request.path`.
+  Omitted, a link is active when the path equals its href's path. The active
+  link gets `aria-current="page"` and the primary tone.
+- `badge:` is optional short text, such as `"#12"`, shown as a pill in the link.
+- A bad entry raises `Studio::NavbarLinks::InvalidLink` naming its index: at
+  assignment for a static Array, at render for a callable.
+
 ### User nav slots
 
 `components/_user_nav.html.erb` renders the right-side navbar user section.

data/app/helpers/studio_navbar_helper.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# The navbar-links view seam. Links resolve once per render pass, since the
+# host lambda may read current_user or the database.
+module StudioNavbarHelper
+  NAVBAR_LINK_CLASS = "inline-flex items-center gap-1.5 whitespace-nowrap font-medium transition"
+  NAVBAR_BADGE_CLASS = "rounded-full border border-subtle px-1.5 py-0.5 text-[10px] leading-none " \
+                       "font-semibold text-muted tabular-nums"
+
+  def studio_navbar_links
+    @studio_navbar_links ||= Studio.navbar_links_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:)
+    tone = link[:active] ? "text-primary" : "text-secondary hover:text-primary"
+    link_to link[:href], class: "#{NAVBAR_LINK_CLASS} #{size} #{tone}",
+                         aria: { current: ("page" if link[:active]) } do
+      badge = content_tag(:span, link[:badge], class: NAVBAR_BADGE_CLASS) if link[:badge]
+      safe_join([link[:label], badge].compact)
+    end
+  end
+end

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

@@ -26,6 +26,9 @@
     Preview renders skip it too: the /admin/navbar page renders this partial
     repeatedly and the panels carry page-unique ids. %>
 <% sidebar_active = !is_preview && respond_to?(:studio_sidebar?) && studio_sidebar? %>
+<%# 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 : [] %>
 <% 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) %>
@@ -141,8 +144,11 @@
               spans drawing outside it, which is the bug rather than the fix. %>
           <h1 class="nav-title font-extrabold text-heading tracking-tight min-w-0"><span class="truncate"><%= prefix %></span><span class="text-primary truncate"><%= last_word %></span></h1>
         <% end %>
-        <%# Desktop nav — apps should override this partial to add links here %>
-        <nav class="hidden md:flex items-center gap-4">
+        <%# Desktop nav — Studio.navbar_links %>
+        <nav class="hidden md:flex items-center gap-4"<%= ' aria-label="Main"'.html_safe if navbar_links.any? %>>
+          <% navbar_links.each do |link| %>
+          <%= studio_navbar_link_tag(link, size: "text-sm") %>
+          <% end %>
         </nav>
       </div>
     </div>
@@ -161,8 +167,15 @@
       <% end %>
     </div>
   </div>
-  <%# Mobile sub-navbar: compact row hidden on desktop — apps should override to add links %>
+  <%# Mobile sub-navbar: compact row hidden on desktop — Studio.navbar_links on the left %>
   <div class="flex md:hidden items-center gap-3 px-4 py-1.5 border-t border-subtle bg-surface-alt">
+    <% if navbar_links.any? %>
+    <nav aria-label="Main" class="flex items-center gap-3 overflow-x-auto">
+      <% navbar_links.each do |link| %>
+      <%= studio_navbar_link_tag(link, size: "text-xs") %>
+      <% end %>
+    </nav>
+    <% end %>
     <span class="ml-auto flex items-center gap-3">
       <%= render "components/link_sidebar_trigger" if sidebar_active %>
       <%= render "components/admin_dropdown" unless sidebar_active && studio_sidebar_replaces_admin_menu? %>

data/lib/studio/navbar_links.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Resolves Studio.navbar_links, the links the engine navbar renders in its
+# desktop bar and phone row. Pure Ruby, so the unit suite covers it without
+# the dummy app.
+#
+# Declared as an Array or a callable (receives the view context, so a badge can
+# read current_user). Each entry resolves to:
+#
+#   { label: "Contests", href: "/contests", active: true, badge: "#12" }
+#
+# `active` may be true/false, a Regexp or a callable matched against
+# request.path; omitted, it is true when the path equals the href's path.
+# `badge` is optional short text. A bad entry raises InvalidLink by index.
+module Studio
+  module NavbarLinks
+    class InvalidLink < ArgumentError; end
+
+    KEYS = %i[label href active badge].freeze
+
+    module_function
+
+    def resolve(declared, view)
+      links = declared.respond_to?(:call) ? declared.call(view) : declared
+      path = request_path(view)
+      entries(links).each_with_index.map do |link, index|
+        link = check!(link, index)
+        { label: link[:label].to_s, href: link[:href].to_s,
+          active: active?(link, path), badge: badge(link[:badge]) }
+      end
+    end
+
+    # Shape check without a request: a static list fails at boot, not on the
+    # first page render. A callable is checked when it resolves.
+    def validate!(declared)
+      return nil if declared.respond_to?(:call)
+
+      entries(declared).each_with_index { |link, index| check!(link, index) }
+      nil
+    end
+
+    def entries(links)
+      return [] if links.nil?
+      return links if links.is_a?(Array)
+
+      raise InvalidLink, "Studio.navbar_links must be an Array or a callable returning an Array " \
+                         "(got #{links.class})"
+    end
+
+    def check!(link, index)
+      where = "Studio.navbar_links[#{index}]"
+      raise InvalidLink, "#{where} must be a Hash (got #{link.class})" unless link.is_a?(Hash)
+
+      link = link.to_h { |key, value| [key.to_sym, value] }
+      unknown = link.keys - KEYS
+      raise InvalidLink, "#{where} has unknown key :#{unknown.first}" if unknown.any?
+
+      %i[label href].each do |key|
+        raise InvalidLink, "#{where} needs a :#{key}" if link[key].to_s.strip.empty?
+      end
+      unless [nil, true, false].include?(link[:active]) || link[:active].is_a?(Regexp) ||
+             link[:active].respond_to?(:call)
+        raise InvalidLink, "#{where} :active must be true, false, a Regexp or a callable"
+      end
+      unless link[:badge].nil? || [String, Symbol, Numeric].any? { |type| link[:badge].is_a?(type) }
+        raise InvalidLink, "#{where} :badge must be short text"
+      end
+
+      link
+    end
+
+    def active?(link, path)
+      case (rule = link[:active])
+      when true, false then rule
+      when nil then !path.nil? && path == link[:href].to_s.split(/[?#]/).first
+      when Regexp then !path.nil? && rule.match?(path)
+      else !path.nil? && rule.call(path) ? true : false
+      end
+    end
+
+    def badge(value)
+      text = value.to_s.strip
+      text.empty? ? nil : text
+    end
+
+    def request_path(view)
+      return nil unless view.respond_to?(:request)
+
+      view.request&.path
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.77.4"
+  VERSION = "0.78.0"
 end

data/lib/studio.rb

@@ -12,6 +12,7 @@ require "studio/js_literal"
 require "studio/js_identifier"
 require "studio/partial_block"
 require "studio/sidebar_sections"
+require "studio/navbar_links"
 require "studio/profile_sections"
 require "studio/profile_image"
 require "studio/oauth_identity"
@@ -174,6 +175,23 @@ module Studio
   #   end
   mattr_accessor :sidebar_sections, default: []
 
+  # ---- Navbar links ----
+  # Links for the engine navbar's desktop bar and phone row. The default []
+  # renders nothing, so the navbar stays byte-identical until an app opts in.
+  # An Array, or a callable receiving the view, of
+  # { label:, href:, active: (bool, Regexp or ->(path)), badge: (optional) }.
+  # Rules: lib/studio/navbar_links.rb.
+  #
+  #   config.navbar_links = ->(view) {
+  #     [ { label: "Contests", href: view.contests_path, active: %r{\A/contests} },
+  #       { label: "Rank", href: "/rank", badge: ("#12" if view.logged_in?) } ] }
+  mattr_reader :navbar_links, default: []
+
+  def self.navbar_links=(links)
+    NavbarLinks.validate!(links)
+    @@navbar_links = links
+  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
@@ -877,6 +895,11 @@ module Studio
     SidebarSections.resolve(sidebar_sections, view)
   end
 
+  # Navbar links resolved for a view context (lib/studio/navbar_links.rb).
+  def self.navbar_links_for(view)
+    NavbarLinks.resolve(navbar_links, view)
+  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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.77.4
+  version: 0.78.0
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-28 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -345,6 +345,7 @@ files:
 - app/helpers/studio/fizz_helper.rb
 - app/helpers/studio/geo_helper.rb
 - app/helpers/studio_email_delivery_helper.rb
+- app/helpers/studio_navbar_helper.rb
 - app/helpers/studio_sidebar_helper.rb
 - app/helpers/studio_theme_helper.rb
 - app/jobs/error_log_cleanup_job.rb
@@ -572,6 +573,7 @@ files:
 - lib/studio/log_rotation.rb
 - lib/studio/mail_transport.rb
 - lib/studio/name_parts.rb
+- lib/studio/navbar_links.rb
 - lib/studio/newsletter.rb
 - lib/studio/oauth_identity.rb
 - lib/studio/partial_block.rb