Merge pull request #573 from appdevforall/feat/K2GO-410-help-topic-routing

K2GO-410 feat(help): route the help viewer by topic (wizard to install, Settings to home)

Author: luisguzman-adfa

controller/app/src/main/java/org/appdevforall/k2go/help/domain/HelpEntry.java

@@ -0,0 +1,38 @@
+/*
+ * ============================================================================
+ * Name        : HelpEntry.java
+ * Author      : AppDevForAll
+ * Copyright   : Copyright (c) 2026 AppDevForAll
+ * Description : K2GO-410. Resolve the bundled manual page for a (topic, language) pair.
+ * ============================================================================
+ */
+package org.appdevforall.k2go.help.domain;
+
+/**
+ * Resolves the bundled manual page for a (topic, language) pair: the two axes of the in-app help
+ * content. Returns a path relative to {@code assets/help/} (e.g. {@code "app-install.html"}); the
+ * viewer prefixes the WebViewAssetLoader base.
+ *
+ * <p>The manual ships English-only today, so {@code languageTag} is accepted but not yet used. When
+ * localized manuals are added under {@code assets/help/<lang>/}, map the tag to that subdirectory
+ * HERE, in one place: the {@link HelpTopic} callers and the viewer do not change. This is the
+ * app-local (assets) path; the box-served tier-3 route lives in {@link Tier3DocsUrl}.
+ */
+public final class HelpEntry {
+
+    private HelpEntry() {}
+
+    /**
+     * The {@code assets/help/}-relative page for a topic.
+     *
+     * @param topic       the content axis; null resolves to {@link HelpTopic#HOME}
+     * @param languageTag the language axis (e.g. from the app locale); reserved for future
+     *                    localized manuals, ignored today
+     */
+    public static String assetPath(HelpTopic topic, String languageTag) {
+        HelpTopic t = (topic != null) ? topic : HelpTopic.HOME;
+        // TODO(K2GO-410 follow-up): when a localized manual exists under assets/help/<lang>/ for
+        // languageTag, return that subdir + t.fileName(). Single point of change for the language axis.
+        return t.fileName();
+    }
+}

controller/app/src/main/java/org/appdevforall/k2go/help/domain/HelpTopic.java

@@ -0,0 +1,47 @@
+/*
+ * ============================================================================
+ * Name        : HelpTopic.java
+ * Author      : AppDevForAll
+ * Copyright   : Copyright (c) 2026 AppDevForAll
+ * Description : K2GO-410. The content axis of the in-app manual: which bundled page to open.
+ * ============================================================================
+ */
+package org.appdevforall.k2go.help.domain;
+
+/**
+ * The content axis of the bundled help manual (K2GO-410): which topic page the in-app viewer opens.
+ * Each constant names a page file under {@code assets/help/}. Pair it with {@link HelpEntry} to get
+ * the resolved path. This is the app-local (assets) manual, separate from the box-served tier-3
+ * route in {@link Tier3DocsUrl}.
+ */
+public enum HelpTopic {
+
+    /** The manual landing page ("Welcome and contents"); the default entry. */
+    HOME("index.html"),
+
+    /** The "Install the app" page: the wizard help target while the user is installing. */
+    INSTALL("app-install.html");
+
+    private final String fileName;
+
+    HelpTopic(String fileName) {
+        this.fileName = fileName;
+    }
+
+    /** The page file name within {@code assets/help/}. */
+    public String fileName() {
+        return fileName;
+    }
+
+    /** Resolve a topic by its {@link #name()}; returns {@code fallback} for null or an unknown name. */
+    public static HelpTopic fromName(String name, HelpTopic fallback) {
+        if (name != null) {
+            for (HelpTopic t : values()) {
+                if (t.name().equals(name)) {
+                    return t;
+                }
+            }
+        }
+        return fallback;
+    }
+}

controller/app/src/main/java/org/appdevforall/k2go/redesign/HelpViewerActivity.java

@@ -31,6 +31,9 @@
 import com.google.android.material.appbar.MaterialToolbar;
 
 import org.appdevforall.k2go.R;
+import org.appdevforall.k2go.applang.data.AppLocaleController;
+import org.appdevforall.k2go.help.domain.HelpEntry;
+import org.appdevforall.k2go.help.domain.HelpTopic;
 import org.appdevforall.k2go.config.BoxEndpoints;
 import org.appdevforall.k2go.portal.data.PdfViewerCatalog;
 import org.appdevforall.k2go.portal.domain.NavigationPolicy;
@@ -61,8 +64,10 @@ public class HelpViewerActivity extends AppCompatActivity {
 
     private static final String TAG = "K2Go-Help";
     private static final String APPASSETS_HOST = "appassets.androidplatform.net";
-    private static final String HELP_ENTRY =
-            "https://" + APPASSETS_HOST + "/assets/help/index.html";
+    private static final String APPASSETS_BASE = "https://" + APPASSETS_HOST + "/assets/help/";
+
+    /** Intent extra: the {@link HelpTopic} name to open. Absent -> HOME (the manual landing). */
+    public static final String EXTRA_TOPIC = "k2go_help_topic";
 
     private WebView webView;
     // pdf.js builds advertised by the box's /pdfjs/manifest.json (loaded off the main thread);
@@ -158,7 +163,12 @@ public void onReceivedError(WebView view, WebResourceRequest request,
             downloadFile(Uri.parse(url), contentDisposition, mimetype);
         });
 
-        webView.loadUrl(HELP_ENTRY);
+        // K2GO-410: two axes pick the entry page -- the topic (content) from the caller's extra and
+        // the app language (resolved centrally). HelpEntry maps them to a bundled page; the language
+        // axis is a no-op until localized manuals ship. Settings passes no topic -> HOME.
+        HelpTopic topic = HelpTopic.fromName(getIntent().getStringExtra(EXTRA_TOPIC), HelpTopic.HOME);
+        String entryUrl = APPASSETS_BASE + HelpEntry.assetPath(topic, AppLocaleController.currentTag());
+        webView.loadUrl(entryUrl);
     }
 
     private void downloadFile(Uri uri, String contentDisposition, String mimetype) {

controller/app/src/main/java/org/appdevforall/k2go/redesign/WizardHelpButton.java

@@ -61,7 +61,10 @@ public static void installOn(Activity activity) {
         lp.setMargins(m, Math.round(16 * d), m, m);   // top margin clears the status bar
         root.addView(b, lp);
 
+        // K2GO-410: the wizard help opens the install topic; Settings (no extra) opens HOME.
         b.setOnClickListener(v ->
-                activity.startActivity(new Intent(activity, HelpViewerActivity.class)));
+                activity.startActivity(new Intent(activity, HelpViewerActivity.class)
+                        .putExtra(HelpViewerActivity.EXTRA_TOPIC,
+                                org.appdevforall.k2go.help.domain.HelpTopic.INSTALL.name())));
     }
 }

controller/app/src/test/java/org/appdevforall/k2go/help/domain/HelpEntryTest.java

@@ -0,0 +1,26 @@
+package org.appdevforall.k2go.help.domain;
+
+import static org.junit.Assert.assertEquals;
+
+import org.junit.Test;
+
+/** Pure-JVM tests for the (topic, language) -> bundled page resolver (K2GO-410). */
+public class HelpEntryTest {
+
+    @Test public void resolvesTopicToItsPage() {
+        assertEquals("index.html", HelpEntry.assetPath(HelpTopic.HOME, "en"));
+        assertEquals("app-install.html", HelpEntry.assetPath(HelpTopic.INSTALL, "en"));
+    }
+
+    @Test public void languageIsNotUsedYet() {
+        // Single-language manual today: any tag (including null/empty) resolves to the same page.
+        String en = HelpEntry.assetPath(HelpTopic.INSTALL, "en");
+        assertEquals(en, HelpEntry.assetPath(HelpTopic.INSTALL, "es"));
+        assertEquals(en, HelpEntry.assetPath(HelpTopic.INSTALL, ""));
+        assertEquals(en, HelpEntry.assetPath(HelpTopic.INSTALL, null));
+    }
+
+    @Test public void nullTopicResolvesToHome() {
+        assertEquals("index.html", HelpEntry.assetPath(null, "en"));
+    }
+}

controller/app/src/test/java/org/appdevforall/k2go/help/domain/HelpTopicTest.java

@@ -0,0 +1,25 @@
+package org.appdevforall.k2go.help.domain;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertSame;
+
+import org.junit.Test;
+
+/** Pure-JVM tests for the help content axis (K2GO-410). */
+public class HelpTopicTest {
+
+    @Test public void fileNamesMapToBundledPages() {
+        assertEquals("index.html", HelpTopic.HOME.fileName());
+        assertEquals("app-install.html", HelpTopic.INSTALL.fileName());
+    }
+
+    @Test public void fromNameParsesKnownConstant() {
+        assertSame(HelpTopic.INSTALL, HelpTopic.fromName("INSTALL", HelpTopic.HOME));
+    }
+
+    @Test public void fromNameFallsBackForNullOrUnknown() {
+        assertSame(HelpTopic.HOME, HelpTopic.fromName(null, HelpTopic.HOME));
+        assertSame(HelpTopic.HOME, HelpTopic.fromName("does-not-exist", HelpTopic.HOME));
+        assertSame(HelpTopic.INSTALL, HelpTopic.fromName("nope", HelpTopic.INSTALL));
+    }
+}