feat: add config.nav_links for custom header navigation links

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `config.nav_links` — accepts an array of `{ label:, url: }` hashes; each entry is appended to the main navigation bar so host apps can link back to their own admin pages or related tools without modifying the engine layout
 - i18n support — all UI labels, flash messages, table headers, empty states, confirmations, and sparkline tooltips are now backed by locale YAML files; ships with English (`en`) and Spanish (`es`) out of the box
 - Locale switcher — a `<select>` dropdown in the header lets users switch languages at runtime; locale is stored in the session and applied via `I18n.with_locale`; automatically hidden when only one locale is configured
 - `config.available_locales` — controls which locales appear in the switcher (default: `[:en, :es]`)

README.md

@@ -123,6 +123,13 @@ SolidStackWeb.configure do |config|
   # Multi-database — pass a connects_to hash when Solid Queue / Cache / Cable
   # live on a separate database from your primary (default: nil, uses primary).
   config.connects_to = { database: { writing: :queue, reading: :queue } }
+
+  # Custom nav links — appended to the main navigation bar (default: []).
+  # Use this to link back to your host application's admin pages or related tools.
+  config.nav_links = [
+    { label: "Back to App", url: "/" },
+    { label: "Admin",       url: "/admin" }
+  ]
 end
 ```
 

ROADMAP.md

@@ -10,7 +10,6 @@
 > _Breaking changes or large architectural additions._
 
 - **Custom dashboard cards** — registration hook so host apps can inject their own stat cards alongside the built-in queue, cache, and cable cards
-- **Custom nav links** — `config.nav_links = [{ label: "Admin", url: "/admin" }]` to integrate the dashboard into the host app's navigation
 
 ---
 

app/views/layouts/solid_stack_web/application.html.erb

@@ -22,6 +22,9 @@
               class: "sqw-nav__link#{" sqw-nav__link--active" if current_section == :cache}" %>
         <%= link_to t("solid_stack_web.layout.nav.cable"), cable_path,
               class: "sqw-nav__link#{" sqw-nav__link--active" if current_section == :cable}" %>
+        <% SolidStackWeb.nav_links.each do |link| %>
+          <%= link_to link[:label], link[:url], class: "sqw-nav__link" %>
+        <% end %>
       </nav>
       <%= render "solid_stack_web/shared/locale_switcher" %>
       <button class="sqw-theme-toggle" aria-label="<%= t("solid_stack_web.layout.theme_toggle") %>"

lib/solid_stack_web.rb

@@ -9,7 +9,7 @@ class << self
                 :alert_slow_job_count_threshold, :alert_stale_process_threshold,
                 :dashboard_refresh_interval, :default_refresh_interval,
                 :search_results_limit, :allow_value_preview,
-                :available_locales
+                :available_locales, :nav_links
 
     def page_size
       @page_size || 25
@@ -67,6 +67,10 @@ def available_locales
       @available_locales || %i[en es]
     end
 
+    def nav_links
+      @nav_links || []
+    end
+
     # Returns the path at which the engine is mounted in the host application,
     # derived automatically from the host's routes. Host apps can use this to
     # build links to the dashboard without hardcoding the mount path.

spec/requests/solid_stack_web/nav_links_spec.rb

@@ -0,0 +1,37 @@
+require "rails_helper"
+
+RSpec.describe "Nav links", type: :request do
+  let(:engine_root) { "/solid_stack" }
+
+  after { SolidStackWeb.nav_links = nil }
+
+  it "renders no custom links by default" do
+    get engine_root
+    expect(response.body).not_to include("sqw-nav__link--custom")
+  end
+
+  it "renders a configured custom nav link" do
+    SolidStackWeb.nav_links = [{ label: "Admin", url: "/admin" }]
+    get engine_root
+    expect(response.body).to include("Admin")
+    expect(response.body).to include("/admin")
+  end
+
+  it "renders multiple custom nav links" do
+    SolidStackWeb.nav_links = [
+      { label: "Admin", url: "/admin" },
+      { label: "Docs",  url: "/docs"  }
+    ]
+    get engine_root
+    expect(response.body).to include("Admin")
+    expect(response.body).to include("/admin")
+    expect(response.body).to include("Docs")
+    expect(response.body).to include("/docs")
+  end
+
+  it "renders custom links with the nav link class" do
+    SolidStackWeb.nav_links = [{ label: "Admin", url: "/admin" }]
+    get engine_root
+    expect(response.body).to match(/class="sqw-nav__link"[^>]*>Admin/)
+  end
+end