markdowndocs 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 764b5150885d6a306eae6d49fbabd8dedee96dffa9bc55a6f290da57e3b53123
-  data.tar.gz: 2a75805e06c5caa6fcdbf8e4860836bcf886fc5453b4d394761f8f45ae8ba114
+  metadata.gz: 6ca89d7b3d1decf28b07cfaccfd1e2e0e0924f8ef7d56d1374e3cb600cbd4933
+  data.tar.gz: 036b99af3190b230d1ceb327171300758b76d09392a4d28b32a9a0129b9cdaf3
 SHA512:
-  metadata.gz: 8502ba23be6b2ccafa8abc6f0388fddfaf1eae79da276b2ec676087195f04ddc000c576b636c5f81473c10fe30f2786faa9fa7b901419a3f8689226d6440a86e
-  data.tar.gz: 0d71e8284d7a5ed9efcdd8841e0a7e760bb26906e4ac61fb27a1ec32e259357c920e6b86ff66bc16e7d3fdda632c2ed5c12b216ff2b71c1f025f3f1ab73aab99
+  metadata.gz: 80f8fb1ad69d4e83407943a1655a7da909d3704ce950ccb3e01a01a515aa3b7a96804e3ae93ceea7ed2cace9497267d750010a2c6fd05b56db27abc89f597432
+  data.tar.gz: 7b7a5ba65d0e5e549811734b03aed0bcc5d52b0c13b768f5e06599162b367998f7d4f7294fe7af2a37d82924ce1826e7e65fbfa39b616bf97828f6b68f83fe2a

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.5

data/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - 2026-06-24
+
+### Added
+
+- **Persistent audience switcher.** The viewing-mode switcher now renders in a
+  toolbar at the top of both the docs index and every doc page (new
+  `markdowndocs/docs/_docs_toolbar` partial), instead of only the show-page
+  sidebar — the audience choice is always visible and rendered once per page.
+  `DocsController#index` and `#show` both expose `@available_modes` from
+  `config.modes`.
+- **Screen-reader mode announcement.** Switching audience sets `flash[:notice]`
+  (`markdowndocs.mode_announcement`), surfaced in a `role="status"
+  aria-live="polite"` region in the engine layout so the Turbo-replace mode
+  change isn't silent for assistive tech. Hosts may render the flash their own way.
+
+### Changed
+
+- **No-counterpart audience switch goes to the target index.** Switching to a
+  mode where the current doc has no counterpart (and no shared-root fallback)
+  now redirects to that audience's index — with a distinct flash
+  (`markdowndocs.no_counterpart_announcement`) — instead of stranding the reader
+  on a doc outside the audience they chose. Topic-preserving (scoped counterpart)
+  and shared-root docs are unchanged.
+
+### Fixed
+
+- **Mode switcher ARIA: toggle-button group, not a radiogroup.** Each mode is a
+  submit button using `aria-pressed` (was `role="radio"` / `aria-checked`, which
+  implied unimplemented arrow-key navigation). Focus returns to the chosen button
+  after the Turbo replace.
+
 ## [0.9.0] - 2026-06-21
 
 ### Added

data/app/assets/javascripts/markdowndocs/controllers/docs_mode_controller.js

@@ -16,11 +16,45 @@ export default class extends Controller {
   }
 
   static STORAGE_KEY = "markdowndocs_mode"
+  static FOCUS_KEY = "markdowndocs_focus_mode"
 
   connect() {
     if (!this.isAuthenticated()) {
       this.restoreGuestMode()
     }
+    this.restoreFocusAfterToggle()
+  }
+
+  rememberFocus(event) {
+    // Save the mode the user just pressed so we can restore focus to the
+    // matching button after Turbo replaces the page (a11y: keep focus on
+    // the control the user actuated, not on the article wrapper).
+    try {
+      const mode = event.currentTarget.dataset.mode
+      if (mode) {
+        sessionStorage.setItem(this.constructor.FOCUS_KEY, mode)
+      }
+    } catch (e) {
+      // sessionStorage unavailable — accept the focus loss gracefully.
+    }
+  }
+
+  restoreFocusAfterToggle() {
+    let pendingMode
+    try {
+      pendingMode = sessionStorage.getItem(this.constructor.FOCUS_KEY)
+      if (pendingMode) sessionStorage.removeItem(this.constructor.FOCUS_KEY)
+    } catch (e) {
+      return
+    }
+    if (!pendingMode) return
+
+    const button = this.element.querySelector(`button[data-mode="${pendingMode}"]`)
+    if (button) {
+      // Defer past the Turbo render + autofocus on the article wrapper so
+      // we steal focus from it; otherwise autofocus would win the race.
+      window.requestAnimationFrame(() => button.focus())
+    }
   }
 
   isAuthenticated() {

data/app/controllers/markdowndocs/docs_controller.rb

@@ -14,6 +14,7 @@ module Markdowndocs
       # surviving docs are dropped (see Documentation.grouped_by_category).
       @docs_by_category = Documentation.grouped_by_category(mode: @docs_mode)
       @search_enabled = Markdowndocs.config.search_enabled
+      @available_modes = Markdowndocs.config.modes
     end
 
     def search_index
@@ -64,7 +65,7 @@ module Markdowndocs
       )
       @rendered_content = helpers.add_heading_anchors(rendered_html)
       @related_docs = Documentation.by_category(@doc.category).reject { |d| d.path_slug == @doc.path_slug }
-      @available_modes = @doc.available_modes
+      @available_modes = Markdowndocs.config.modes
       @toc_items = helpers.generate_table_of_contents(@rendered_content)
     end
 

data/app/controllers/markdowndocs/preferences_controller.rb

@@ -25,7 +25,25 @@ module Markdowndocs
         httponly: true
       }
 
-      redirect_to(smart_nav_target(mode, params[:current_path]), status: :see_other)
+      current_path = params[:current_path]
+      target = smart_nav_target(mode, current_path)
+      mode_name = I18n.t("markdowndocs.modes.#{mode}", default: mode.titleize)
+
+      flash[:notice] = if redirected_to_index_from_doc?(target, current_path)
+        I18n.t(
+          "markdowndocs.no_counterpart_announcement",
+          mode: mode_name,
+          default: "No %{mode} version of this page — showing the %{mode} documentation."
+        )
+      else
+        I18n.t(
+          "markdowndocs.mode_announcement",
+          mode: mode_name,
+          default: "Now viewing %{mode}."
+        )
+      end
+
+      redirect_to(target, status: :see_other)
     end
 
     private
@@ -50,15 +68,26 @@ module Markdowndocs
       # rejection (and any other reachability rules) match what the show
       # action would actually serve. Bypassing this — e.g. with raw
       # File.exist? — can redirect the user into a 404.
-      if scoped_sibling_reachable?(slug, target_mode) && current_path != scoped_url
+      if scoped_sibling_reachable?(slug, target_mode)
         scoped_url
-      elsif root_sibling_reachable?(slug) && current_path != root_url
+      elsif root_sibling_reachable?(slug)
         root_url
       else
-        current_path
+        # No counterpart in the target mode and no shared root fallback: send the
+        # reader to that audience's index rather than stranding them on a doc
+        # outside the audience they just chose.
+        index_path
       end
     end
 
+    # True when the switch had to fall back to the docs index because the current
+    # doc has no counterpart in the target mode (selects the flash copy below).
+    def redirected_to_index_from_doc?(target, current_path)
+      current_path.present? &&
+        target == markdowndocs.root_path.chomp("/") &&
+        extract_slug_from_path(current_path).present?
+    end
+
     def scoped_sibling_reachable?(slug, target_mode)
       docs_path = Markdowndocs.config.resolved_docs_path
       scoped_file = docs_path.join(target_mode, "#{slug}.md")

data/app/views/layouts/markdowndocs/application.html.erb

@@ -11,6 +11,9 @@
   </head>
 
   <body class="min-h-screen flex flex-col bg-gray-50">
+    <% if flash[:notice].present? %>
+      <div role="status" aria-live="polite" class="sr-only"><%= flash[:notice] %></div>
+    <% end %>
     <%= yield :docs_header %>
 
     <main id="main-content" role="main" class="flex-1">

data/app/views/markdowndocs/docs/_docs_toolbar.html.erb

@@ -0,0 +1,10 @@
+<%# locals: (current_mode:, available_modes:) %>
+<%# Persistent docs toolbar: the audience switcher, shown at the top of both
+    the index and every doc page. Renders nothing when only one mode exists. %>
+<% if available_modes.length > 1 %>
+  <div class="flex justify-end mb-6">
+    <%= render "markdowndocs/docs/mode_switcher",
+      current_mode: current_mode,
+      available_modes: available_modes %>
+  </div>
+<% end %>

data/app/views/markdowndocs/docs/_mode_switcher.html.erb

@@ -1,80 +1,29 @@
 <%# locals: (current_mode:, available_modes:) %>
-<%# No `id=` on the root: show.html.erb renders _navigation twice (mobile +
-    desktop sidebars), which embeds this partial twice — a hardcoded id
-    would produce duplicate ids in the DOM (WCAG 4.1.1 violation, see
-    issue #20). Stimulus already scopes itself via data-controller, which
-    can appear N times without colliding. Tests / selectors should target
-    [data-controller="docs-mode"] rather than #docs-mode-switcher. %>
+<%# Horizontal audience toggle for the docs toolbar (rendered once per page).
+    Toggle-button group, NOT a radiogroup: each option is its own form +
+    submit button, so aria-pressed describes state. No element id — tests
+    target [data-controller="docs-mode"]. %>
 <div
-  class="
-    bg-white
-    dark:bg-slate-800
-    rounded-lg
-    border
-    border-slate-200
-    dark:border-slate-700
-    p-4
-  "
+  class="flex items-center gap-2"
   data-controller="docs-mode"
   data-docs-mode-current-value="<%= current_mode %>"
 >
-  <h3 class="
-    text-sm
-    font-medium
-    text-slate-700
-    dark:text-slate-300
-    mb-3
-  ">
+  <span class="text-sm font-medium text-slate-700 dark:text-slate-300">
     <%= t("markdowndocs.viewing_mode") %>
-  </h3>
-
-  <div
-    class="space-y-2"
-    role="radiogroup"
-    aria-label="<%= t('markdowndocs.select_viewing_mode') %>"
-  >
+  </span>
+  <div class="inline-flex gap-1" role="group" aria-label="<%= t('markdowndocs.select_viewing_mode') %>">
     <% available_modes.each do |mode| %>
-      <%= form_with(
-        url: markdowndocs.preference_path,
-        method: :patch,
-        data: {
-          turbo_action: "replace"
-        }
-      ) do |f| %>
+      <%= form_with(url: markdowndocs.preference_path, method: :patch, data: {turbo_action: "replace"}) do |f| %>
         <%= f.hidden_field :mode, value: mode, id: nil %>
         <%= f.hidden_field :current_path, value: request.fullpath, id: nil %>
         <button
           type="submit"
-          role="radio"
-          aria-checked="<%= current_mode == mode %>"
-          class="
-            w-full
-            text-left
-            p-3
-            rounded-lg
-            border-2
-            transition-all
-            duration-150
-            <%= (current_mode == mode) ? 'border-cyan-500 bg-cyan-50 dark:bg-cyan-900/40 dark:border-cyan-400' : 'border-slate-200 hover:border-slate-300 hover:bg-slate-50 dark:border-slate-700 dark:hover:border-slate-500 dark:hover:bg-slate-700' %>
-          "
+          aria-pressed="<%= current_mode == mode %>"
+          data-mode="<%= mode %>"
+          data-action="click->docs-mode#rememberFocus"
+          class="px-3 py-1.5 text-sm font-medium rounded-md border transition-colors <%= (current_mode == mode) ? 'border-cyan-500 bg-cyan-50 text-cyan-900 dark:bg-cyan-900/40 dark:border-cyan-400 dark:text-cyan-100' : 'border-slate-200 text-slate-700 hover:bg-slate-50 dark:border-slate-700 dark:text-slate-300 dark:hover:bg-slate-700' %>"
         >
-          <span class="
-            block
-            font-medium
-            <%= (current_mode == mode) ? 'text-cyan-900 dark:text-cyan-100' : 'text-slate-900 dark:text-slate-100' %>
-          ">
-            <%= t("markdowndocs.modes.#{mode}", default: mode.titleize) %>
-          </span>
-          <% description = t("markdowndocs.modes.#{mode}_description", default: "") %>
-          <% if description.present? %>
-            <p class="
-              text-xs
-              mt-1
-              <%= (current_mode == mode) ? 'text-cyan-900 dark:text-cyan-100' : 'text-slate-700 dark:text-slate-300' %>
-            ">
-              <%= description %>
-            </p>
-          <% end %>
+          <%= t("markdowndocs.modes.#{mode}", default: mode.titleize) %>
         </button>
       <% end %>
     <% end %>

data/app/views/markdowndocs/docs/_navigation.html.erb

@@ -1,11 +1,5 @@
-<%# locals: (rendered_content:, related_docs:, current_mode:, available_modes:, toc_items:) %>
+<%# locals: (rendered_content:, related_docs:, toc_items:) %>
 <aside class="sidebar space-y-6">
-  <% if available_modes.length > 1 %>
-    <%= render "markdowndocs/docs/mode_switcher",
-      current_mode: current_mode,
-      available_modes: available_modes %>
-  <% end %>
-
   <% if toc_items.length >= 3 %>
     <div class="bg-white dark:bg-slate-800 rounded-lg shadow-sm p-6">
       <nav aria-label="Table of Contents">

data/app/views/markdowndocs/docs/index.html.erb

@@ -6,6 +6,9 @@
        data-controller="docs-search"
        data-docs-search-index-url-value="<%= markdowndocs.search_index_path %>"
     <% end %>>
+    <%= render "markdowndocs/docs/docs_toolbar",
+      current_mode: @docs_mode,
+      available_modes: @available_modes %>
     <!-- Hero Section -->
     <div class="text-center mb-12">
       <h1 class="text-4xl font-bold text-gray-900 dark:text-slate-100 mb-4">Documentation</h1>

data/app/views/markdowndocs/docs/show.html.erb

@@ -18,6 +18,10 @@
     <!-- Breadcrumb -->
     <%= render "markdowndocs/docs/breadcrumb", category: @doc.category, title: @doc.title %>
 
+    <%= render "markdowndocs/docs/docs_toolbar",
+      current_mode: @docs_mode,
+      available_modes: @available_modes %>
+
     <!-- Mobile navigation (hamburger dropdown, hidden on desktop) -->
     <div class="lg:hidden mb-6">
       <button
@@ -57,8 +61,6 @@
         <%= render "markdowndocs/docs/navigation",
           rendered_content: @rendered_content,
           related_docs: @related_docs,
-          current_mode: @docs_mode,
-          available_modes: @available_modes,
           toc_items: @toc_items %>
       </div>
     </div>
@@ -84,8 +86,6 @@
           <%= render "markdowndocs/docs/navigation",
             rendered_content: @rendered_content,
             related_docs: @related_docs,
-            current_mode: @docs_mode,
-            available_modes: @available_modes,
             toc_items: @toc_items %>
         </div>
       </div>

data/config/locales/en.yml

@@ -4,6 +4,8 @@ en:
     navigation_sidebar: "Navigation & Related Docs"
     viewing_mode: "Viewing Mode"
     select_viewing_mode: "Select documentation viewing mode"
+    mode_announcement: "Now viewing %{mode}."
+    no_counterpart_announcement: "No %{mode} version of this page — showing the %{mode} documentation."
     modes:
       guide: "User Guide"
       guide_description: "User-friendly explanations and step-by-step instructions"

data/lib/markdowndocs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Markdowndocs
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.4.6"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdowndocs
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Dave Chmura
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-23 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -75,6 +75,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".tool-versions"
 - CHANGELOG.md
 - README.md
 - Rakefile
@@ -91,6 +92,7 @@ files:
 - app/views/layouts/markdowndocs/application.html.erb
 - app/views/markdowndocs/docs/_breadcrumb.html.erb
 - app/views/markdowndocs/docs/_card.html.erb
+- app/views/markdowndocs/docs/_docs_toolbar.html.erb
 - app/views/markdowndocs/docs/_mode_switcher.html.erb
 - app/views/markdowndocs/docs/_navigation.html.erb
 - app/views/markdowndocs/docs/index.html.erb
@@ -104,6 +106,7 @@ files:
 - lib/markdowndocs/configuration.rb
 - lib/markdowndocs/engine.rb
 - lib/markdowndocs/version.rb
+- mise.toml
 - sig/markdowndocs.rbs
 homepage: https://github.com/dschmura/markdowndocs
 licenses: