Merge pull request #151 from appdevforall/feat/ADFA-4593-tiers-1-2-tooltips

ADFA-4593: three-tier help — tiers 1 & 2 in-APK tooltip mechanism (scaffold)

Author: luisguzman-adfa

controller/app/build.gradle

@@ -393,3 +393,47 @@ task syncNativeArtifacts {
 }
 
 preBuild.dependsOn syncNativeArtifacts
+
+// ---- ADFA-4593: tooltip three-tier help database ------------------------------
+// Source of truth is tools/help/i18n (.pot + <lang>.po compiled to assets/help.db).
+// Requires Python + polib for validation/compilation; if Python is absent the
+// committed help.db is used and checks are skipped (so local builds never break).
+def helpI18nDir = file("tools/help/i18n")
+def helpDb = file("src/main/assets/help.db")
+def helpRequiredLangs = "es,fr,hi,pt,ru"
+def helpPython = (System.getProperty("os.name").toLowerCase().contains("win")
+        ? ["py", "python", "python3"] : ["python3", "python"]).find { name ->
+    try { def p = "${name} --version".execute(); p.waitFor(); p.exitValue() == 0 }
+    catch (ignored) { false }
+}
+
+if (helpPython == null) {
+    logger.warn("ADFA-4593: Python not found; using committed help.db and skipping tooltip "
+            + "translation checks. Install Python + polib for full enforcement (required in CI).")
+} else {
+    tasks.register("validateHelpTranslations", Exec) {
+        group = "help"
+        description = "Fail the build if required tooltip translations are missing."
+        inputs.dir helpI18nDir
+        workingDir projectDir
+        def allowMissing = project.hasProperty("helpAllowMissing") ? project.property("helpAllowMissing") : "false"
+        commandLine helpPython, "tools/help/validate_help.py", "tools/help/i18n",
+                "--required", helpRequiredLangs, "--allow-missing", allowMissing
+    }
+    tasks.register("buildHelpDb", Exec) {
+        group = "help"
+        description = "Compile the tooltip help.db from .po sources."
+        inputs.dir helpI18nDir
+        outputs.file helpDb
+        dependsOn "validateHelpTranslations"
+        workingDir projectDir
+        commandLine helpPython, "tools/help/build_help_db.py", "tools/help/i18n", helpDb.absolutePath
+    }
+    tasks.register("extractHelpPot", Exec) {
+        group = "help"
+        description = "Regenerate strings.pot from the English source (run on demand)."
+        workingDir projectDir
+        commandLine helpPython, "tools/help/extract_help_pot.py", "tools/help/i18n"
+    }
+    tasks.matching { it.name == "preBuild" }.configureEach { dependsOn "buildHelpDb" }
+}

controller/app/src/main/assets/help.db

@@ -10,6 +10,9 @@
 package org.iiab.controller;
 
 import org.iiab.controller.util.AppExecutors;
+import org.iiab.controller.help.TooltipCategory;
+import org.iiab.controller.help.TooltipTag;
+import org.iiab.controller.help.ViewTooltips;
 
 import android.Manifest;
 import android.os.Bundle;
@@ -380,6 +383,12 @@ public boolean onTouch(View v, MotionEvent event) {
         headerIcon = findViewById(R.id.header_icon);
         ImageButton btnShareQr = findViewById(R.id.btn_share_qr);
 
+        // ADFA-4593: three-tier help — attach tier-1/2 tooltips (long-press) to native controls.
+        ViewTooltips.attachLongPress(themeToggle, TooltipCategory.K2GO, TooltipTag.MAIN_THEME_TOGGLE);
+        ViewTooltips.attachLongPress(btnSettings, TooltipCategory.K2GO, TooltipTag.MAIN_SETTINGS);
+        ViewTooltips.attachLongPress(btnShareQr, TooltipCategory.K2GO, TooltipTag.MAIN_SHARE_QR);
+        ViewTooltips.attachLongPress(versionFooter, TooltipCategory.K2GO, TooltipTag.MAIN_VERSION);
+
         // Listeners
         themeToggle.setOnClickListener(v -> toggleTheme());
         btnSettings.setOnClickListener(v -> startActivity(new Intent(MainActivity.this, SetupActivity.class)));

controller/app/src/main/java/org/iiab/controller/MainActivity.java

@@ -0,0 +1,25 @@
+/*
+ * ============================================================================
+ * Name        : HelpLink.java
+ * Author      : AppDevForAll
+ * Copyright   : Copyright (c) 2026 AppDevForAll
+ * Description : A tier-3 help link (label + relative URI) shown in a tooltip.
+ * ============================================================================
+ */
+package org.iiab.controller.help;
+
+/**
+ * A tier-3 link. {@link #uri} is a relative path resolved against the tier-3
+ * help server base URL (see ADFA-4594). Kept relative so the serving host/port
+ * can change without touching the content database.
+ */
+public final class HelpLink {
+
+    public final String label;
+    public final String uri;
+
+    public HelpLink(String label, String uri) {
+        this.label = label;
+        this.uri = uri;
+    }
+}

controller/app/src/main/java/org/iiab/controller/help/HelpLink.java

@@ -0,0 +1,22 @@
+/*
+ * ============================================================================
+ * Name        : TooltipCategory.java
+ * Author      : AppDevForAll
+ * Copyright   : Copyright (c) 2026 AppDevForAll
+ * Description : Tooltip category constants for the K2Go three-tier help system.
+ * ============================================================================
+ */
+package org.iiab.controller.help;
+
+/**
+ * Categories partition the tooltip namespace (mirrors Code On the Go's model,
+ * where categories are ide/java/kotlin/xml). K2Go starts with a single native
+ * category; more can be added later without schema changes.
+ */
+public final class TooltipCategory {
+
+    private TooltipCategory() {}
+
+    /** Native K2Go UI (tiers 1 & 2 live in the APK). */
+    public static final String K2GO = "k2go";
+}

controller/app/src/main/java/org/iiab/controller/help/TooltipCategory.java

@@ -0,0 +1,42 @@
+/*
+ * ============================================================================
+ * Name        : TooltipItem.java
+ * Author      : AppDevForAll
+ * Copyright   : Copyright (c) 2026 AppDevForAll
+ * Description : Immutable value object for one tooltip: tier-1 summary,
+ *               tier-2 detail, and tier-3 links.
+ * ============================================================================
+ */
+package org.iiab.controller.help;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public final class TooltipItem {
+
+    public final String category;
+    public final String tag;
+    /** Tier 1: short summary (HTML). */
+    public final String summary;
+    /** Tier 2: longer detail (HTML); may be empty. */
+    public final String detail;
+    /** Tier 3: links to full help pages; may be empty. */
+    public final List<HelpLink> links;
+
+    public TooltipItem(String category, String tag, String summary, String detail,
+                       List<HelpLink> links) {
+        this.category = category;
+        this.tag = tag;
+        this.summary = summary;
+        this.detail = detail;
+        this.links = (links != null) ? links : new ArrayList<HelpLink>();
+    }
+
+    public boolean hasDetail() {
+        return detail != null && !detail.trim().isEmpty();
+    }
+
+    public boolean hasLinks() {
+        return links != null && !links.isEmpty();
+    }
+}