From 7e0938f84174e654b24c3b9e8e9925be4a37acec Mon Sep 17 00:00:00 2001
From: TheFlow <theflow@sydigital.com>
Date: Mon, 23 Feb 2026 07:44:25 +1300
Subject: [PATCH] feat(docs): mobile UX improvements for docs page

On mobile (<1024px), skip auto-loading first document so users see the
sidebar category browser. Add sticky blue navigation bar showing current
document title. Expand all categories by default on mobile initial view.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 public/js/docs-app.js | 53 +++++++++++++++++++++++++++----------------
 1 file changed, 33 insertions(+), 20 deletions(-)

diff --git a/public/js/docs-app.js b/public/js/docs-app.js
index 8da5f9bb..04bc3e9e 100644
--- a/public/js/docs-app.js
+++ b/public/js/docs-app.js
@@ -272,10 +272,10 @@ function updatePageUI(lang = currentLanguage) {
     }
   });
 
-  // Update Back to Documents button
-  const backBtn = document.querySelector('#back-to-docs-btn span');
-  if (backBtn) {
-    backBtn.textContent = t.backToDocuments;
+  // Update Back to Documents bar label
+  const backLabel = document.querySelector('#back-to-docs-btn [data-back-label]');
+  if (backLabel) {
+    backLabel.textContent = t.documentsHeading;
   }
 
   // Update Select Document placeholder (if visible)
@@ -706,11 +706,15 @@ async function loadDocuments() {
 
     const t = getUITranslations(currentLanguage);
 
+    // On mobile with no ?doc= param, expand all categories for browsing
+    const isMobileView = window.innerWidth < 1024;
+    const noDocParam = !new URLSearchParams(window.location.search).get('doc');
+
     sortedCategories.forEach(([categoryId, category]) => {
       const docs = grouped[categoryId] || [];
       if (docs.length === 0) return;
 
-      const isCollapsed = category.collapsed || false;
+      const isCollapsed = (isMobileView && noDocParam) ? false : (category.collapsed || false);
       const categoryLabel = t.categories[categoryId] || categoryId;
 
       // Category header
@@ -838,23 +842,26 @@ async function loadDocuments() {
     }
     // Priority 3: Default behavior
     else {
-      // Default: Auto-load first document in "Getting Started" category (order: 1)
-      const gettingStartedDocs = grouped['getting-started'] || [];
-      if (gettingStartedDocs.length > 0) {
-        // Load the first document (order: 1) if available
-        const firstDoc = gettingStartedDocs.find(d => d.order === 1);
-        if (firstDoc) {
-          loadDocument(firstDoc.slug);
-        } else {
-          loadDocument(gettingStartedDocs[0].slug);
-        }
-      } else if (documents.length > 0) {
-        // Fallback to first available document in any category
-        const firstCategory = sortedCategories.find(([catId]) => grouped[catId] && grouped[catId].length > 0);
-        if (firstCategory) {
-          loadDocument(grouped[firstCategory[0]][0].slug);
+      // On mobile, show sidebar (don't auto-load) so user can browse categories
+      const isMobile = window.innerWidth < 1024;
+      if (!isMobile) {
+        // Desktop: auto-load first Getting Started doc as before
+        const gettingStartedDocs = grouped['getting-started'] || [];
+        if (gettingStartedDocs.length > 0) {
+          const firstDoc = gettingStartedDocs.find(d => d.order === 1);
+          if (firstDoc) {
+            loadDocument(firstDoc.slug);
+          } else {
+            loadDocument(gettingStartedDocs[0].slug);
+          }
+        } else if (documents.length > 0) {
+          const firstCategory = sortedCategories.find(([catId]) => grouped[catId] && grouped[catId].length > 0);
+          if (firstCategory) {
+            loadDocument(grouped[firstCategory[0]][0].slug);
+          }
         }
       }
+      // Mobile: sidebar remains visible, user taps to choose a document
     }
   } catch (error) {
     console.error('Error loading documents:', error);
@@ -1012,6 +1019,12 @@ async function loadDocument(slug, lang = null) {
     // Mobile navigation: Add document-active class to show document view
     document.body.classList.add('document-active');
 
+    // Update mobile sticky bar with current document title
+    const mobileDocTitle = document.getElementById('mobile-doc-title');
+    if (mobileDocTitle && currentDocument) {
+      mobileDocTitle.textContent = currentDocument.title;
+    }
+
     // Scroll to top
     window.scrollTo({ top: 0, behavior: 'smooth' });