feat: introduce snippets common library module and documentation tools

ApiDemos/project/common-ui/build.gradle.kts

@@ -1,7 +1,7 @@
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 /*
- * Copyright 2025 Google LLC
+ * Copyright 2026 Google LLC
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -18,6 +18,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 plugins {
     alias(libs.plugins.android.library)
+    alias(libs.plugins.kotlin.compose)
 }
 
 android {
@@ -45,6 +46,7 @@ android {
     }
     buildFeatures {
         viewBinding = true
+        compose = true
     }
     compileOptions {
         sourceCompatibility = JavaVersion.VERSION_17
@@ -64,12 +66,25 @@ android {
 }
 
 dependencies {
-
     implementation(libs.core.ktx)
     implementation(libs.appcompat)
     implementation(libs.material)
     implementation(libs.play.services.maps)
+
+    // Jetpack Compose
+    implementation(platform(libs.compose.bom))
+    implementation(libs.ui)
+    implementation(libs.ui.graphics)
+    implementation(libs.ui.tooling.preview)
+    implementation(libs.material3)
+    implementation(libs.material.icons.extended)
+    implementation(libs.activity.compose)
+    debugImplementation(libs.ui.tooling)
+
+    // Lifecycle & Coroutines
+    implementation(libs.lifecycle.runtime.ktx)
+
     testImplementation(libs.junit)
     androidTestImplementation(libs.junit)
     androidTestImplementation(libs.espresso.core)
-}
+}

ApiDemos/project/common-ui/src/main/java/com/example/common_ui/catalog/SampleEvaluation.kt

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.common_ui.catalog
+
+import java.io.Serializable
+
+/**
+ * Domain data model representing a sample manual review evaluation.
+ */
+data class SampleEvaluation(
+    val sampleId: String,
+    val sampleTitle: String = "",
+    val activityName: String = "",
+    val category: String = "",
+    val framework: String = "",
+    val status: String = ReviewStatus.UNCHECKED.name,
+    val notes: String = "",
+    val screenshotPath: String? = null,
+    val lastUpdated: Long = System.currentTimeMillis()
+) : Serializable

ApiDemos/project/common-ui/src/main/java/com/example/common_ui/catalog/SampleMetadata.kt

@@ -0,0 +1,179 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.common_ui.catalog
+
+import java.io.Serializable
+
+/**
+ * Annotation for Google Maps Platform sample activities and snippet entry points.
+ *
+ * Provides metadata consumed by the dynamic catalog builder and the on-device reviewer mode.
+ */
+@Target(AnnotationTarget.CLASS)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class Sample(
+    val id: String,
+    val title: String,
+    val description: String,
+    val category: String,
+    val complexity: Complexity = Complexity.SIMPLE,
+    val tags: Array<String> = [],
+    val apiCalls: Array<String> = [],
+    val purpose: String = "",
+    val successCriteria: String = "",
+    val failureIndicators: String = "",
+    val helpHtml: String = "",
+    val framework: Framework = Framework.KOTLIN_VIEWS
+)
+
+/**
+ * Complexity classification for samples.
+ */
+enum class Complexity(val displayName: String, val badge: String, val order: Int) : Serializable {
+    SNIPPET("Snippet", "🔹", 1),
+    SIMPLE("Simple", "🟢", 2),
+    ADVANCED("Advanced", "🔴", 3);
+
+    companion object {
+        fun fromString(value: String?): Complexity {
+            return entries.find { it.name.equals(value, ignoreCase = true) } ?: SIMPLE
+        }
+    }
+}
+
+/**
+ * Supported development frameworks in this repository.
+ */
+enum class Framework(
+    val id: String,
+    val displayName: String,
+    val badge: String,
+    val iconEmoji: String,
+    val accentColorHex: Long
+) : Serializable {
+    KOTLIN_VIEWS(
+        id = "kotlin",
+        displayName = "Kotlin Views",
+        badge = "Kotlin",
+        iconEmoji = "💜",
+        accentColorHex = 0xFF7F52FF
+    ),
+    JAVA_VIEWS(
+        id = "java",
+        displayName = "Java Views",
+        badge = "Java",
+        iconEmoji = "☕",
+        accentColorHex = 0xFFE76F51
+    );
+
+    companion object {
+        fun fromId(id: String?): Framework {
+            return entries.find { it.id.equals(id, ignoreCase = true) } ?: KOTLIN_VIEWS
+        }
+    }
+}
+
+/**
+ * Manual review evaluation status for a sample.
+ */
+enum class ReviewStatus(
+    val displayName: String,
+    val badge: String,
+    val iconEmoji: String,
+    val colorHex: Long
+) : Serializable {
+    UNCHECKED("Unchecked", "UNCHECKED", "⚪", 0xFF9E9E9E),
+    NEEDS_WORK("Needs Work", "NEEDS_WORK", "🔴", 0xFFF44336),
+    PASSING("Passing", "PASSING", "🟢", 0xFF4CAF50);
+
+    companion object {
+        fun fromString(value: String?): ReviewStatus {
+            return entries.find { it.name.equals(value, ignoreCase = true) } ?: UNCHECKED
+        }
+    }
+}
+
+/**
+ * Immutable domain model representing a sample entry across Kotlin and Java frameworks.
+ */
+data class SampleItem(
+    val id: String,
+    val title: String,
+    val description: String,
+    val category: String,
+    val complexity: Complexity = Complexity.SIMPLE,
+    val tags: List<String> = emptyList(),
+    val apiCalls: List<String> = emptyList(),
+    val purpose: String = "",
+    val successCriteria: String = "",
+    val failureIndicators: String = "",
+    val helpHtml: String = "",
+    val kotlinActivity: String? = null,
+    val javaActivity: String? = null
+) : Serializable {
+
+    /**
+     * Builds an HTML formatted help box for reviewer and developer guidance.
+     * When [isReviewerMode] is false (Developer/Learner mode), evaluation criteria
+     * (Success Criteria and Failure Indicators) are omitted to keep the UI clean.
+     */
+    fun getFormattedHelpHtml(isReviewerMode: Boolean = true): String {
+        if (helpHtml.isNotBlank()) {
+            return helpHtml
+        }
+        val builder = StringBuilder()
+        builder.append("<h3><b>${title}</b></h3>")
+        builder.append("<p><i>${description}</i></p>")
+        builder.append("<hr/>")
+
+        if (purpose.isNotBlank()) {
+            builder.append("<p><b>🎯 Purpose:</b><br/>${purpose}</p>")
+        }
+        if (isReviewerMode) {
+            if (successCriteria.isNotBlank()) {
+                builder.append("<p><b>✅ Success Criteria:</b><br/>${successCriteria}</p>")
+            }
+            if (failureIndicators.isNotBlank()) {
+                builder.append("<p><b>⚠️ Failure / Broken Indicators:</b><br/>${failureIndicators}</p>")
+            }
+        }
+
+        if (tags.isNotEmpty()) {
+            builder.append("<p><b>🏷️ Tags:</b> ")
+            builder.append(tags.joinToString(" "))
+            builder.append("</p>")
+        }
+        return builder.toString()
+    }
+
+    /**
+     * Resolves the activity class name for a given target framework.
+     */
+    fun getActivityForFramework(framework: Framework): String? {
+        return when (framework) {
+            Framework.KOTLIN_VIEWS -> kotlinActivity ?: javaActivity
+            Framework.JAVA_VIEWS -> javaActivity ?: kotlinActivity
+        }
+    }
+
+    /**
+     * Returns the Fully Qualified Class Name (FQCN) identifier for the given framework.
+     */
+    fun getTargetFqcn(framework: Framework): String {
+        return getActivityForFramework(framework) ?: id
+    }
+}

ApiDemos/project/common-ui/src/main/java/com/example/common_ui/catalog/compose/CatalogActivity.kt

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.example.common_ui.catalog.compose
+
+import android.content.Intent
+import android.os.Bundle
+import android.widget.Toast
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import com.example.common_ui.catalog.Framework
+import com.example.common_ui.catalog.SampleItem
+
+/**
+ * Clean, modern Jetpack Compose Catalog application for end-user developers.
+ *
+ * Provides multi-framework browsing, instant search, complexity filters, and sample expectation guides.
+ */
+open class CatalogActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        enableEdgeToEdge()
+
+        setContent {
+            CatalogTheme {
+                CatalogScreen(
+                    isReviewerMode = false,
+                    onLaunchSample = { sample, framework ->
+                        launchSample(sample, framework)
+                    },
+                    onSwitchMode = {
+                        val intent = Intent().setClassName(packageName, "com.example.common_ui.catalog.compose.ReviewerActivity")
+                        startActivity(intent)
+                    }
+                )
+            }
+        }
+    }
+
+    protected fun launchSample(sample: SampleItem, framework: Framework) {
+        val className = sample.getActivityForFramework(framework)
+        if (className.isNullOrBlank()) {
+            Toast.makeText(this, "No ${framework.displayName} implementation available for ${sample.title}", Toast.LENGTH_SHORT).show()
+            return
+        }
+
+        try {
+            val intent = Intent().setClassName(packageName, className).apply {
+                putExtra("extra_sample_id", sample.id)
+                putExtra("extra_is_reviewer_mode", false)
+            }
+            startActivity(intent)
+        } catch (e: Exception) {
+            Toast.makeText(this, "Could not launch ${sample.title}: ${e.message}", Toast.LENGTH_LONG).show()
+        }
+    }
+}