From 4fb21c55cc63760a167a8fc6bca2894414c2f09e Mon Sep 17 00:00:00 2001
From: Chuck Smith <eclectic-coding@users.noreply.github.com>
Date: Sun, 7 Jun 2026 06:55:27 -0400
Subject: [PATCH] feat: add config.nav_links for custom header navigation links

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md                                  |  1 +
 README.md                                     |  7 ++++
 ROADMAP.md                                    |  1 -
 .../solid_stack_web/application.html.erb      |  3 ++
 lib/solid_stack_web.rb                        |  6 ++-
 .../solid_stack_web/nav_links_spec.rb         | 37 +++++++++++++++++++
 6 files changed, 53 insertions(+), 2 deletions(-)
 create mode 100644 spec/requests/solid_stack_web/nav_links_spec.rb

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9adee7d..dab1b26 100644
--- a/CHANGELOG.md
+++ b/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]`)
diff --git a/README.md b/README.md
index 0c1748b..d7a9de7 100644
--- a/README.md
+++ b/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
 ```
 
diff --git a/ROADMAP.md b/ROADMAP.md
index 1992d97..85c02d5 100644
--- a/ROADMAP.md
+++ b/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
 
 ---
 
diff --git a/app/views/layouts/solid_stack_web/application.html.erb b/app/views/layouts/solid_stack_web/application.html.erb
index 6390206..bb910fb 100644
--- a/app/views/layouts/solid_stack_web/application.html.erb
+++ b/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") %>"
diff --git a/lib/solid_stack_web.rb b/lib/solid_stack_web.rb
index 5c0da4d..5752ea8 100644
--- a/lib/solid_stack_web.rb
+++ b/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.
diff --git a/spec/requests/solid_stack_web/nav_links_spec.rb b/spec/requests/solid_stack_web/nav_links_spec.rb
new file mode 100644
index 0000000..4a97b5f
--- /dev/null
+++ b/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