@glancekit/android-core 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,32 @@
+# @glancekit/android-core
+
+Pure Android core module for GlanceKit alpha.
+
+This module owns the pure Android implementation:
+
+- `ProgressCardData`
+- `WidgetStateRepository`
+- `WidgetUpdateManager`
+- `ProgressCardWidget`
+- `ProgressCardWidgetReceiver`
+
+It intentionally does not depend on React Native.
+
+## Intended Use
+
+Most React Native and Expo consumers should install:
+
+- `@glancekit/react-native`
+- `@glancekit/expo-plugin` for Expo managed builds
+
+This package exists so the Android implementation has a clean boundary and can be consumed directly by:
+
+- the native Android demo in `examples/native-android-demo`
+- `@glancekit/react-native` as a bridge dependency
+
+## Alpha Notes
+
+- Android only
+- internal/power-user package for alpha
+- `ProgressCardWidget` is the only widget template
+- no React Native JS API is exposed from this package

package/build.gradle.kts

@@ -0,0 +1,51 @@
+import org.jetbrains.kotlin.config.KotlinCompilerVersion
+
+plugins {
+    id("com.android.library")
+    id("org.jetbrains.kotlin.android")
+}
+
+val composeExpectedKotlinVersion = "1.9.24"
+val detectedKotlinVersion = KotlinCompilerVersion.VERSION
+
+android {
+    namespace = "dev.glancekit.androidcore"
+    compileSdk = 34
+
+    defaultConfig {
+        minSdk = 26
+        consumerProguardFiles("consumer-rules.pro")
+    }
+
+    buildFeatures {
+        compose = true
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    composeOptions {
+        kotlinCompilerExtensionVersion = "1.5.14"
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+        if (detectedKotlinVersion != composeExpectedKotlinVersion) {
+            freeCompilerArgs += listOf(
+                "-P",
+                "plugin:androidx.compose.compiler.plugins.kotlin:suppressKotlinVersionCompatibilityCheck=$detectedKotlinVersion",
+            )
+        }
+    }
+}
+
+dependencies {
+    implementation("androidx.core:core-ktx:1.13.1")
+    implementation("androidx.datastore:datastore-preferences:1.1.1")
+    api("androidx.glance:glance-appwidget:1.1.1")
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")
+
+    testImplementation("junit:junit:4.13.2")
+}

package/consumer-rules.pro

@@ -0,0 +1 @@
+

package/index.js

@@ -0,0 +1 @@
+module.exports = {};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@glancekit/android-core",
+  "version": "0.1.0-alpha.0",
+  "private": false,
+  "description": "Pure Android Glance/DataStore core module for GlanceKit alpha.",
+  "main": "index.js",
+  "files": [
+    "README.md",
+    "package.json",
+    "index.js",
+    "build.gradle.kts",
+    "consumer-rules.pro",
+    "src/main"
+  ],
+  "keywords": [
+    "glancekit",
+    "android",
+    "jetpack-glance",
+    "android-widget",
+    "datastore"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "echo android-core build is driven by Gradle consumers",
+    "lint": "echo android-core lint pending",
+    "typecheck": "echo android-core typecheck pending"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/main/java/dev/glancekit/androidcore/ProgressCardData.kt

@@ -0,0 +1,29 @@
+package dev.glancekit.androidcore
+
+data class ProgressCardData(
+    val title: String,
+    val subtitle: String,
+    val progress: Int,
+    val deepLink: String? = null,
+) {
+    fun normalized(): ProgressCardData = copy(
+        title = title.trim(),
+        subtitle = subtitle.trim(),
+        deepLink = deepLink?.trim()?.takeIf { it.isNotEmpty() },
+    )
+
+    fun validate() {
+        require(title.isNotBlank()) { "Widget title cannot be empty." }
+        require(subtitle.isNotBlank()) { "Widget subtitle cannot be empty." }
+        require(progress in 0..100) { "Widget progress must be between 0 and 100." }
+    }
+
+    companion object {
+        val DEFAULT = ProgressCardData(
+            title = "Daily Progress",
+            subtitle = "Tap the app to update this widget.",
+            progress = 0,
+            deepLink = null,
+        )
+    }
+}

package/src/main/java/dev/glancekit/androidcore/WidgetStateRepository.kt

@@ -0,0 +1,76 @@
+package dev.glancekit.androidcore
+
+import android.content.Context
+import android.util.Log
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.intPreferencesKey
+import androidx.datastore.preferences.core.stringPreferencesKey
+import androidx.datastore.preferences.preferencesDataStore
+import kotlinx.coroutines.flow.first
+
+private val Context.widgetDataStore by preferencesDataStore(name = "glancekit_widgets")
+
+internal object WidgetStateRepository {
+    suspend fun loadWidget(context: Context, widgetId: Int): ProgressCardData {
+        if (widgetId <= 0) {
+            Log.w(TAG, "loadWidget called with invalid widgetId=$widgetId, returning default state")
+            return ProgressCardData.DEFAULT
+        }
+
+        val preferences = context.widgetDataStore.data.first()
+        val data = ProgressCardData(
+            title = preferences[stringPreferencesKey(titleKey(widgetId))]
+                ?: ProgressCardData.DEFAULT.title,
+            subtitle = preferences[stringPreferencesKey(subtitleKey(widgetId))]
+                ?: ProgressCardData.DEFAULT.subtitle,
+            progress = preferences[intPreferencesKey(progressKey(widgetId))]
+                ?: ProgressCardData.DEFAULT.progress,
+            deepLink = preferences[stringPreferencesKey(deepLinkKey(widgetId))],
+        )
+        Log.d(
+            TAG,
+            "loadWidget widgetId=$widgetId title=${data.title} progress=${data.progress} deepLink=${data.deepLink}",
+        )
+        return data
+    }
+
+    suspend fun saveWidget(context: Context, widgetId: Int, data: ProgressCardData) {
+        Log.d(
+            TAG,
+            "saveWidget widgetId=$widgetId title=${data.title} progress=${data.progress} deepLink=${data.deepLink}",
+        )
+        context.widgetDataStore.edit { preferences ->
+            preferences[stringPreferencesKey(titleKey(widgetId))] = data.title
+            preferences[stringPreferencesKey(subtitleKey(widgetId))] = data.subtitle
+            preferences[intPreferencesKey(progressKey(widgetId))] = data.progress
+            val deepLinkKey = stringPreferencesKey(deepLinkKey(widgetId))
+            if (data.deepLink == null) {
+                preferences.remove(deepLinkKey)
+            } else {
+                preferences[deepLinkKey] = data.deepLink
+            }
+        }
+    }
+
+    suspend fun deleteWidget(context: Context, widgetId: Int) {
+        if (widgetId <= 0) {
+            Log.w(TAG, "deleteWidget skipped for invalid widgetId=$widgetId")
+            return
+        }
+
+        Log.d(TAG, "deleteWidget widgetId=$widgetId")
+        context.widgetDataStore.edit { preferences ->
+            preferences.remove(stringPreferencesKey(titleKey(widgetId)))
+            preferences.remove(stringPreferencesKey(subtitleKey(widgetId)))
+            preferences.remove(intPreferencesKey(progressKey(widgetId)))
+            preferences.remove(stringPreferencesKey(deepLinkKey(widgetId)))
+        }
+    }
+
+    private fun titleKey(widgetId: Int) = "widget_${widgetId}_title"
+    private fun subtitleKey(widgetId: Int) = "widget_${widgetId}_subtitle"
+    private fun progressKey(widgetId: Int) = "widget_${widgetId}_progress"
+    private fun deepLinkKey(widgetId: Int) = "widget_${widgetId}_deep_link"
+
+    private const val TAG = "GlanceKitState"
+}

package/src/main/java/dev/glancekit/androidcore/WidgetUpdateManager.kt

@@ -0,0 +1,102 @@
+package dev.glancekit.androidcore
+
+import android.content.Context
+import android.util.Log
+import androidx.glance.appwidget.GlanceAppWidgetManager
+import androidx.glance.appwidget.updateAll
+import dev.glancekit.androidcore.widget.ProgressCardWidget
+
+object WidgetUpdateManager {
+    suspend fun updateProgressCardWidget(
+        context: Context,
+        widgetId: Int,
+        data: ProgressCardData,
+        widgetClass: Class<out ProgressCardWidget> = ProgressCardWidget::class.java,
+    ): ProgressCardData {
+        require(widgetId > 0) { "Widget ID must be a positive integer." }
+
+        Log.d(TAG, "updateProgressCardWidget start widgetId=$widgetId widgetClass=${widgetClass.name} rawData=$data")
+        val normalized = data.normalized()
+        normalized.validate()
+        WidgetStateRepository.saveWidget(context, widgetId, normalized)
+        refreshProgressCardWidget(context, widgetId, widgetClass)
+        Log.d(TAG, "updateProgressCardWidget success widgetId=$widgetId normalized=$normalized")
+        return normalized
+    }
+
+    suspend fun loadProgressCardWidget(
+        context: Context,
+        widgetId: Int,
+    ): ProgressCardData {
+        Log.d(TAG, "loadProgressCardWidget widgetId=$widgetId")
+        return WidgetStateRepository.loadWidget(context, widgetId)
+    }
+
+    suspend fun refreshProgressCardWidget(
+        context: Context,
+        widgetId: Int,
+        widgetClass: Class<out ProgressCardWidget> = ProgressCardWidget::class.java,
+    ) {
+        Log.d(TAG, "refreshProgressCardWidget widgetId=$widgetId widgetClass=${widgetClass.name}")
+        val manager = GlanceAppWidgetManager(context)
+        val glanceIds = manager.getGlanceIds(widgetClass)
+        Log.d(TAG, "refreshProgressCardWidget glanceIds count=${glanceIds.size} values=$glanceIds")
+        val widget = widgetClass.getDeclaredConstructor().newInstance()
+        glanceIds.forEach { glanceId ->
+            val appWidgetId = manager.getAppWidgetId(glanceId)
+            if (appWidgetId == widgetId) {
+                Log.d(TAG, "refreshProgressCardWidget matched glanceId=$glanceId appWidgetId=$appWidgetId")
+                widget.update(context, glanceId)
+            }
+        }
+    }
+
+    suspend fun refreshAllProgressCardWidgets(
+        context: Context,
+        widgetClass: Class<out ProgressCardWidget> = ProgressCardWidget::class.java,
+    ) {
+        Log.d(TAG, "refreshAllProgressCardWidgets widgetClass=${widgetClass.name}")
+        widgetClass.getDeclaredConstructor().newInstance().updateAll(context)
+    }
+
+    suspend fun updateAllProgressCardWidgets(
+        context: Context,
+        data: ProgressCardData,
+        widgetClass: Class<out ProgressCardWidget> = ProgressCardWidget::class.java,
+    ): Int {
+        val normalized = data.normalized()
+        normalized.validate()
+
+        val manager = GlanceAppWidgetManager(context)
+        val glanceIds = manager.getGlanceIds(widgetClass)
+        Log.d(
+            TAG,
+            "updateAllProgressCardWidgets widgetClass=${widgetClass.name} glanceIds count=${glanceIds.size} values=$glanceIds",
+        )
+        check(glanceIds.isNotEmpty()) {
+            "No ProgressCardWidget instances are currently added to the home screen. " +
+                "Searched for widgetClass=${widgetClass.name}."
+        }
+
+        Log.d(
+            TAG,
+            "updateAllProgressCardWidgets count=${glanceIds.size} normalized=$normalized",
+        )
+        val widget = widgetClass.getDeclaredConstructor().newInstance()
+        glanceIds.forEach { glanceId ->
+            val appWidgetId = manager.getAppWidgetId(glanceId)
+            WidgetStateRepository.saveWidget(context, appWidgetId, normalized)
+            Log.d(TAG, "updateAllProgressCardWidgets updating glanceId=$glanceId appWidgetId=$appWidgetId")
+            widget.update(context, glanceId)
+        }
+
+        return glanceIds.size
+    }
+
+    suspend fun deleteProgressCardWidget(context: Context, widgetId: Int) {
+        Log.d(TAG, "deleteProgressCardWidget widgetId=$widgetId")
+        WidgetStateRepository.deleteWidget(context, widgetId)
+    }
+
+    private const val TAG = "GlanceKitUpdate"
+}

package/src/main/java/dev/glancekit/androidcore/widget/ProgressCardWidget.kt

@@ -0,0 +1,185 @@
+package dev.glancekit.androidcore.widget
+
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.util.Log
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.unit.dp
+import androidx.glance.GlanceId
+import androidx.glance.GlanceModifier
+import androidx.glance.action.Action
+import androidx.glance.action.clickable
+import androidx.glance.appwidget.GlanceAppWidget
+import androidx.glance.appwidget.GlanceAppWidgetManager
+import androidx.glance.appwidget.action.actionStartActivity
+import androidx.glance.appwidget.provideContent
+import androidx.glance.layout.Column
+import androidx.glance.layout.Spacer
+import androidx.glance.layout.height
+import androidx.glance.layout.padding
+import androidx.glance.text.Text
+import dev.glancekit.androidcore.ProgressCardData
+import dev.glancekit.androidcore.WidgetUpdateManager
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+
+open class ProgressCardWidget : GlanceAppWidget() {
+    override suspend fun provideGlance(context: Context, id: GlanceId) {
+        Log.d(TAG, "provideGlance start glanceId=$id")
+        try {
+            val renderState = loadRenderState(context, id)
+            Log.d(TAG, "provideGlance before provideContent glanceId=$id")
+            provideContent {
+                Log.d(
+                    TAG,
+                    "provideContent entered glanceId=$id mode=${renderState.mode} widgetId=${renderState.widgetId}",
+                )
+
+                when (renderState.mode) {
+                    RenderMode.Fallback -> {
+                        Log.d(TAG, "render static content fallback glanceId=$id")
+                        MinimalFallbackContent()
+                    }
+
+                    RenderMode.Data -> {
+                        Log.d(
+                            TAG,
+                            "render data content widgetId=${renderState.widgetId} title=${renderState.data.title}",
+                        )
+                        ProgressCardTextContent(
+                            data = renderState.data,
+                            onClick = renderState.onClick,
+                        )
+                    }
+                }
+            }
+        } catch (error: Throwable) {
+            Log.e(TAG, "provideGlance failure catch glanceId=$id", error)
+            throw error
+        }
+    }
+
+    private suspend fun loadRenderState(context: Context, id: GlanceId): RenderState {
+        return runCatching {
+            val manager = GlanceAppWidgetManager(context)
+            val widgetId = manager.getAppWidgetId(id)
+            Log.d(TAG, "state read start widgetId=$widgetId glanceId=$id")
+
+            val data = withContext(Dispatchers.IO) {
+                WidgetUpdateManager.loadProgressCardWidget(context, widgetId)
+            }.also { loadedData ->
+                Log.d(
+                    TAG,
+                    "state read success widgetId=$widgetId title=${loadedData.title} progress=${loadedData.progress}",
+                )
+            }
+
+            RenderState(
+                widgetId = widgetId,
+                data = data,
+                onClick = createClickAction(context, widgetId, data),
+                mode = RenderMode.Data,
+            )
+        }.getOrElse { error ->
+            Log.e(TAG, "state read failure glanceId=$id", error)
+            RenderState(
+                widgetId = -1,
+                data = ProgressCardData.DEFAULT,
+                onClick = null,
+                mode = RenderMode.Fallback,
+            )
+        }
+    }
+
+    private fun createClickAction(
+        context: Context,
+        widgetId: Int,
+        data: ProgressCardData,
+    ): Action? {
+        Log.d(TAG, "click action creation start widgetId=$widgetId")
+        return runCatching {
+            val intent = createDeepLinkIntent(context, widgetId, data)
+            actionStartActivity(intent).also {
+                Log.d(TAG, "click action creation success widgetId=$widgetId uri=${intent.data}")
+            }
+        }.getOrElse { error ->
+            Log.e(TAG, "click action creation failure widgetId=$widgetId", error)
+            null
+        }
+    }
+
+    private fun createDeepLinkIntent(
+        context: Context,
+        widgetId: Int,
+        data: ProgressCardData,
+    ): Intent {
+        val deepLinkUri = data.deepLink?.let(Uri::parse) ?: Uri.Builder()
+            .scheme("glancekit")
+            .authority("progress")
+            .appendPath(widgetId.toString())
+            .build()
+
+        return Intent(Intent.ACTION_VIEW, deepLinkUri).apply {
+            `package` = context.packageName
+            addFlags(
+                Intent.FLAG_ACTIVITY_NEW_TASK or
+                    Intent.FLAG_ACTIVITY_CLEAR_TOP or
+                    Intent.FLAG_ACTIVITY_SINGLE_TOP
+            )
+        }
+    }
+
+    companion object {
+        private const val TAG = "GlanceKitWidget"
+    }
+}
+
+private data class RenderState(
+    val widgetId: Int,
+    val data: ProgressCardData,
+    val onClick: Action?,
+    val mode: RenderMode,
+)
+
+private enum class RenderMode {
+    Fallback,
+    Data,
+}
+
+@Composable
+private fun MinimalFallbackContent() {
+    Column(modifier = GlanceModifier.padding(CONTENT_PADDING)) {
+        Text(text = "GlanceKit")
+        Spacer(modifier = GlanceModifier.height(TEXT_SPACING_SMALL))
+        Text(text = "Waiting for data")
+    }
+}
+
+@Composable
+private fun ProgressCardTextContent(
+    data: ProgressCardData,
+    onClick: Action?,
+) {
+    val contentModifier = GlanceModifier
+        .padding(CONTENT_PADDING)
+        .let { modifier ->
+            if (onClick == null) {
+                modifier
+            } else {
+                modifier.clickable(onClick)
+            }
+        }
+
+    Column(modifier = contentModifier) {
+        Text(text = data.title.ifBlank { ProgressCardData.DEFAULT.title })
+        Spacer(modifier = GlanceModifier.height(TEXT_SPACING_SMALL))
+        Text(text = data.subtitle.ifBlank { ProgressCardData.DEFAULT.subtitle })
+        Spacer(modifier = GlanceModifier.height(TEXT_SPACING_LARGE))
+        Text(text = "${data.progress.coerceIn(0, 100)}% complete")
+    }
+}
+
+private val CONTENT_PADDING = 16.dp
+private val TEXT_SPACING_SMALL = 4.dp
+private val TEXT_SPACING_LARGE = 10.dp

package/src/main/java/dev/glancekit/androidcore/widget/ProgressCardWidgetReceiver.kt

@@ -0,0 +1,52 @@
+package dev.glancekit.androidcore.widget
+
+import android.appwidget.AppWidgetManager
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+import androidx.glance.appwidget.GlanceAppWidget
+import androidx.glance.appwidget.GlanceAppWidgetReceiver
+import dev.glancekit.androidcore.WidgetUpdateManager
+import kotlinx.coroutines.runBlocking
+
+open class ProgressCardWidgetReceiver : GlanceAppWidgetReceiver() {
+    override val glanceAppWidget: GlanceAppWidget = ProgressCardWidget()
+
+    override fun onReceive(context: Context, intent: Intent) {
+        Log.d(TAG, "onReceive action=${intent.action}")
+        super.onReceive(context, intent)
+    }
+
+    override fun onUpdate(
+        context: Context,
+        appWidgetManager: AppWidgetManager,
+        appWidgetIds: IntArray,
+    ) {
+        Log.d(TAG, "onUpdate widgetIds=${appWidgetIds.joinToString()}")
+        super.onUpdate(context, appWidgetManager, appWidgetIds)
+    }
+
+    override fun onEnabled(context: Context) {
+        Log.d(TAG, "onEnabled")
+        super.onEnabled(context)
+    }
+
+    override fun onDisabled(context: Context) {
+        Log.d(TAG, "onDisabled")
+        super.onDisabled(context)
+    }
+
+    override fun onDeleted(context: Context, appWidgetIds: IntArray) {
+        Log.d(TAG, "onDeleted widgetIds=${appWidgetIds.joinToString()}")
+        super.onDeleted(context, appWidgetIds)
+        runBlocking {
+            appWidgetIds.forEach { widgetId ->
+                WidgetUpdateManager.deleteProgressCardWidget(context, widgetId)
+            }
+        }
+    }
+
+    companion object {
+        private const val TAG = "GlanceKitReceiver"
+    }
+}