android-sdd 1.0.0

package/skills/Android Ecosystem/Glance/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: glance
+description: >
+  Jetpack Glance for building App Widgets with Compose-like API.
+  Load this skill when creating home screen or lock screen widgets,
+  updating widget content, or handling widget interactions.
+---
+
+# Glance
+
+## Overview
+Jetpack Glance provides a Compose-like API for building Android App Widgets. Instead of XML RemoteViews, Glance lets you write widget UI in a declarative style. Glance is built on top of RemoteViews internally — it translates Composable-like functions to RemoteViews at runtime.
+
+---
+
+## Core Principles
+
+- Glance is **not Compose** — it only supports a subset of Compose-like APIs
+- Widget UI runs in a **different process** — no direct state sharing with the app
+- Use **GlanceStateDefinition** for widget state — not ViewModel or StateFlow
+- Widget updates must be triggered explicitly — they don't auto-update on app state change
+- Glance components are a **limited subset** — not all Compose components are available
+
+---
+
+## Setup
+
+```toml
+[versions]
+glance = "1.1.0"
+
+[libraries]
+glance-appwidget = { module = "androidx.glance:glance-appwidget", version.ref = "glance" }
+glance-material3 = { module = "androidx.glance:glance-material3", version.ref = "glance" }
+```
+
+```kotlin
+dependencies {
+    implementation(libs.glance.appwidget)
+    implementation(libs.glance.material3)
+}
+```
+
+---
+
+## Widget Definition
+
+```kotlin
+// ✅ Define the widget
+class MyAppWidget : GlanceAppWidget() {
+
+    override val stateDefinition = MyWidgetStateDefinition
+
+    @Composable
+    override fun Content() {
+        val state = currentState<MyWidgetState>()
+        val context = LocalContext.current
+
+        GlanceTheme {
+            MyWidgetContent(
+                state = state,
+                onRefreshClick = actionRunCallback<RefreshAction>()
+            )
+        }
+    }
+}
+
+// ✅ Composable widget UI
+@Composable
+fun MyWidgetContent(
+    state: MyWidgetState,
+    onRefreshClick: Action
+) {
+    Column(
+        modifier = GlanceModifier
+            .fillMaxSize()
+            .background(GlanceTheme.colors.surface)
+            .padding(16.dp)
+            .cornerRadius(16.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        Text(
+            text = state.title,
+            style = TextStyle(
+                color = GlanceTheme.colors.onSurface,
+                fontSize = 16.sp,
+                fontWeight = FontWeight.Bold
+            )
+        )
+
+        Spacer(modifier = GlanceModifier.height(8.dp))
+
+        Text(
+            text = state.subtitle,
+            style = TextStyle(
+                color = GlanceTheme.colors.onSurface,
+                fontSize = 12.sp
+            )
+        )
+
+        Spacer(modifier = GlanceModifier.defaultWeight())
+
+        Button(
+            text = "Refresh",
+            onClick = onRefreshClick
+        )
+    }
+}
+```
+
+---
+
+## Widget State
+
+```kotlin
+// ✅ Define state model
+data class MyWidgetState(
+    val title: String = "",
+    val subtitle: String = "",
+    val isLoading: Boolean = false
+)
+
+// ✅ State definition using DataStore
+val MyWidgetStateDefinition = object : GlanceStateDefinition<MyWidgetState> {
+
+    override suspend fun getDataStore(
+        context: Context,
+        fileKey: String
+    ): DataStore<MyWidgetState> = DataStoreFactory.create(
+        serializer = MyWidgetStateSerializer,
+        produceFile = { context.dataStoreFile(fileKey) }
+    )
+
+    override fun getLocation(context: Context, fileKey: String): File =
+        context.dataStoreFile(fileKey)
+}
+
+// ✅ Serializer for widget state
+object MyWidgetStateSerializer : Serializer<MyWidgetState> {
+    override val defaultValue = MyWidgetState()
+
+    override suspend fun readFrom(input: InputStream): MyWidgetState = try {
+        Json.decodeFromString(input.readBytes().decodeToString())
+    } catch (e: Exception) {
+        defaultValue
+    }
+
+    override suspend fun writeTo(t: MyWidgetState, output: OutputStream) {
+        output.write(Json.encodeToString(t).toByteArray())
+    }
+}
+```
+
+---
+
+## Widget Receiver
+
+```kotlin
+// ✅ GlanceAppWidgetReceiver — entry point for the widget
+class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
+    override val glanceAppWidget = MyAppWidget()
+}
+```
+
+```xml
+<!-- AndroidManifest.xml -->
+<receiver
+    android:name=".widget.MyAppWidgetReceiver"
+    android:exported="true">
+    <intent-filter>
+        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
+    </intent-filter>
+    <meta-data
+        android:name="android.appwidget.provider"
+        android:resource="@xml/my_widget_info" />
+</receiver>
+```
+
+```xml
+<!-- res/xml/my_widget_info.xml -->
+<appwidget-provider
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:minWidth="250dp"
+    android:minHeight="110dp"
+    android:targetCellWidth="4"
+    android:targetCellHeight="2"
+    android:resizeMode="horizontal|vertical"
+    android:updatePeriodMillis="1800000"
+    android:widgetCategory="home_screen"
+    android:initialLayout="@layout/glance_default_loading_layout" />
+```
+
+---
+
+## Updating Widget State
+
+```kotlin
+// ✅ Update widget from app — e.g., from ViewModel or Worker
+suspend fun updateWidget(context: Context, newState: MyWidgetState) {
+    // Update state in all widget instances
+    GlanceAppWidgetManager(context)
+        .getGlanceIds(MyAppWidget::class.java)
+        .forEach { glanceId ->
+            updateAppWidgetState(context, MyWidgetStateDefinition, glanceId) {
+                newState
+            }
+            MyAppWidget().update(context, glanceId)
+        }
+}
+
+// ✅ Update from WorkManager for periodic refresh
+class WidgetUpdateWorker(
+    context: Context,
+    params: WorkerParameters
+) : CoroutineWorker(context, params) {
+
+    override suspend fun doWork(): Result {
+        val data = repository.fetchLatestData()
+        updateWidget(
+            applicationContext,
+            MyWidgetState(title = data.title, subtitle = data.subtitle)
+        )
+        return Result.success()
+    }
+}
+```
+
+---
+
+## Widget Actions
+
+```kotlin
+// ✅ Handle button clicks via ActionCallback
+class RefreshAction : ActionCallback {
+    override suspend fun onAction(
+        context: Context,
+        glanceId: GlanceId,
+        parameters: ActionParameters
+    ) {
+        // Update widget state on click
+        updateAppWidgetState(context, MyWidgetStateDefinition, glanceId) { state ->
+            state.copy(isLoading = true)
+        }
+        MyAppWidget().update(context, glanceId)
+
+        // Fetch new data
+        val newData = repository.fetchData()
+        updateAppWidgetState(context, MyWidgetStateDefinition, glanceId) {
+            MyWidgetState(title = newData.title, subtitle = newData.subtitle)
+        }
+        MyAppWidget().update(context, glanceId)
+    }
+}
+
+// ✅ Open app on widget click
+val openAppAction = actionStartActivity<MainActivity>()
+
+// ✅ Open specific screen via deep link
+val openDetailAction = actionStartActivity(
+    Intent(context, MainActivity::class.java).apply {
+        putExtra("destination", "detail")
+    }
+)
+```
+
+---
+
+## Glance Components Reference
+
+```kotlin
+// ✅ Available layout components
+Row { }
+Column { }
+Box { }
+LazyColumn { }  // for lists
+
+// ✅ Available UI components
+Text(text = "Hello")
+Button(text = "Click", onClick = action)
+Image(provider = ImageProvider(R.drawable.icon), contentDescription = null)
+CircularProgressIndicator()
+LinearProgressIndicator(progress = 0.5f)
+Spacer(modifier = GlanceModifier.height(8.dp))
+Switch(checked = true, onCheckedChange = action)
+CheckBox(checked = false, onCheckedChange = action)
+
+// ✅ GlanceModifier (not Compose Modifier)
+GlanceModifier
+    .fillMaxSize()
+    .fillMaxWidth()
+    .wrapContentSize()
+    .padding(16.dp)
+    .background(Color.White)
+    .clickable(onClick = action)
+    .cornerRadius(12.dp)
+```
+
+---
+
+## Anti-Patterns
+
+- Using Compose components not available in Glance — runtime crash
+- Sharing ViewModel state directly with widget — different processes
+- Not calling `widget.update()` after state change — UI stays stale
+- Complex animations in widgets — not supported, RemoteViews limitation
+- Making widgets too complex — widgets should show summary, not replace the app
+- Not handling widget resize — use `SizeMode.Responsive` for multiple sizes
+
+---
+
+## Related Skills
+- `compose` — Glance has similar but different API
+- `datastore` — widget state persistence
+- `workmanager` — periodic widget updates
+- `app-widget` — traditional RemoteViews-based widgets

package/skills/Android Platform/Configuration/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: configuration
+description: >
+  Android Configuration changes handling — screen rotation, locale change,
+  dark mode, font scale, and other runtime configuration events.
+  Load this skill when handling configuration changes, deciding what to retain
+  across rotation, or supporting dynamic locale/theme switching.
+---
+
+# Configuration
+
+## Overview
+
+Android Configuration represents the current state of the device — screen orientation, locale, font scale, night mode, and more. When configuration changes, Android destroys and recreates the Activity by default. Proper handling ensures seamless UX without data loss or memory leaks.
+
+---
+
+## Core Principles
+
+- Never store UI state in Activity — use ViewModel to survive configuration changes
+- Never use `android:configChanges` to avoid recreating Activity unless absolutely necessary
+- Handle configuration-dependent resources via the resource qualifier system — not in code
+- Use `SavedStateHandle` for state that must survive both configuration change and process death
+- Test rotation and locale change explicitly — they expose the most lifecycle bugs
+
+---
+
+## What Happens on Configuration Change
+
+```
+User rotates screen
+    → Activity.onPause()
+    → Activity.onStop()
+    → Activity.onDestroy()       ← Activity is destroyed
+    → ViewModel stays alive      ← ViewModel is NOT destroyed
+    → new Activity.onCreate()
+    → new Activity.onStart()
+    → new Activity.onResume()
+```
+
+---
+
+## ViewModel — Surviving Configuration Change
+
+```kotlin
+// ✅ ViewModel survives rotation — store all UI state here
+class UserViewModel : ViewModel() {
+    private val _state = MutableStateFlow(UserUiState())
+    val state: StateFlow<UserUiState> = _state.asStateFlow()
+}
+
+// ✅ Activity/Fragment — just observe, never store state locally
+class UserFragment : Fragment() {
+    private val viewModel: UserViewModel by viewModels()
+
+    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
+        viewLifecycleOwner.lifecycleScope.launch {
+            repeatOnLifecycle(Lifecycle.State.STARTED) {
+                viewModel.state.collect { render(it) }
+            }
+        }
+    }
+}
+```
+
+---
+
+## Detecting Configuration in Code
+
+```kotlin
+// ✅ Read current configuration
+val config = resources.configuration
+
+// Night mode
+val isNightMode = config.uiMode and Configuration.UI_MODE_NIGHT_MASK ==
+        Configuration.UI_MODE_NIGHT_YES
+
+// Orientation
+val isLandscape = config.orientation == Configuration.ORIENTATION_LANDSCAPE
+
+// Locale
+val locale = config.locales[0]
+
+// Screen size class
+val isTablet = config.smallestScreenWidthDp >= 600
+
+// ✅ In Compose
+val isSystemInDarkTheme = isSystemInDarkTheme()
+val windowSizeClass = calculateWindowSizeClass(activity)
+```
+
+---
+
+## Dynamic Locale Change (API 33+)
+
+```kotlin
+// ✅ API 33+ — use LocaleManager
+if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+    getSystemService(LocaleManager::class.java)
+        .applicationLocales = LocaleList(Locale.forLanguageTag("fa"))
+}
+
+// ✅ API < 33 — use AppCompatDelegate
+AppCompatDelegate.setApplicationLocales(
+    LocaleListCompat.forLanguageTags("fa")
+)
+```
+
+---
+
+## Dynamic Dark Mode
+
+```kotlin
+// ✅ Change theme at runtime
+AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
+AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
+AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM)
+
+// ✅ Persist preference and apply on app start
+class ThemeManager(private val prefs: DataStore<Preferences>) {
+    suspend fun applyTheme() {
+        val isDark = prefs.data.first()[DARK_MODE_KEY] ?: false
+        AppCompatDelegate.setDefaultNightMode(
+            if (isDark) AppCompatDelegate.MODE_NIGHT_YES
+            else AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM
+        )
+    }
+}
+```
+
+---
+
+## configChanges — When to Use
+
+```xml
+<!-- ✅ Only for cases where recreation is genuinely harmful -->
+<!-- Example: video player, camera, map — recreation causes flicker/reset -->
+<activity
+    android:name=".PlayerActivity"
+    android:configChanges="orientation|screenSize|keyboardHidden" />
+```
+
+```kotlin
+// ✅ Handle manually when configChanges is declared
+override fun onConfigurationChanged(newConfig: Configuration) {
+    super.onConfigurationChanged(newConfig)
+    if (newConfig.orientation == Configuration.ORIENTATION_LANDSCAPE) {
+        adjustLayoutForLandscape()
+    }
+}
+
+// ❌ Don't use configChanges just to avoid writing proper ViewModel code
+```
+
+---
+
+## Window Size Classes (Adaptive UI)
+
+```kotlin
+// ✅ Use WindowSizeClass for adaptive layouts
+@Composable
+fun AdaptiveScreen(windowSizeClass: WindowSizeClass) {
+    when (windowSizeClass.widthSizeClass) {
+        WindowWidthSizeClass.Compact -> PhoneLayout()
+        WindowWidthSizeClass.Medium  -> TabletLayout()
+        WindowWidthSizeClass.Expanded -> DesktopLayout()
+    }
+}
+
+// Setup in Activity
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        val windowSizeClass = calculateWindowSizeClass(this)
+        setContent {
+            AdaptiveScreen(windowSizeClass)
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Storing UI state in Activity fields — lost on rotation
+- Using `android:configChanges` to avoid ViewModel — just delays the problem
+- Reading configuration in ViewModel — ViewModel should be config-independent
+- Hardcoding layout logic for orientation in code instead of resource qualifiers
+- Not testing rotation — the most common source of state loss bugs
+- Using `onRetainNonConfigurationInstance()` — replaced by ViewModel
+
+---
+
+## Related Skills
+
+- `savedstatehandle` — persisting state across process death
+- `lifecycle` — Activity/Fragment lifecycle during config change
+- `viewmodel` — surviving configuration changes
+- `resources` — configuration qualifiers in res/
+- `adaptive-ui` — WindowSizeClass and responsive layouts