@3fn/core 14.1.0 → 15.0.0

package/dist/consumer-canonical/skills/navigation-3/references/android/guide/navigation/navigation-3/recipes/scenes-twopane.md

@@ -0,0 +1,244 @@
+# Two-Pane Scene Recipe
+
+This example shows how to create a two pane layout using the Scenes API.
+
+A `TwoPaneSceneStrategy` will return a `TwoPaneScene` if:
+
+- the window width is over 600dp
+- the last two nav entries on the back stack have indicated that they support being displayed in a `TwoPaneScene` in their metadata.
+
+See `TwoPaneScene.kt` for more implementation details.
+[![](https://developer.android.com/static/images/picto-icons/code.svg) Explore View the full recipe on GitHub.](https://github.com/android/nav3-recipes/tree/main/app/src/main/java/com/example/nav3recipes/scenes/twopane)
+
+```
+package com.example.nav3recipes.scenes.twopane
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.adaptive.currentWindowAdaptiveInfoV2
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import androidx.navigation3.runtime.NavEntry
+import androidx.navigation3.runtime.NavMetadataKey
+import androidx.navigation3.runtime.contains
+import androidx.navigation3.runtime.metadata
+import androidx.navigation3.scene.Scene
+import androidx.navigation3.scene.SceneStrategy
+import androidx.navigation3.scene.SceneStrategyScope
+import androidx.window.core.layout.WindowSizeClass
+import androidx.window.core.layout.WindowSizeClass.Companion.WIDTH_DP_MEDIUM_LOWER_BOUND
+
+// --- TwoPaneScene ---
+/**
+ * A custom [Scene] that displays two [NavEntry]s side-by-side in a 50/50 split.
+ */
+data class TwoPaneScene<T : Any>(
+    override val key: Any,
+    override val previousEntries: List<NavEntry<T>>,
+    val firstEntry: NavEntry<T>,
+    val secondEntry: NavEntry<T>
+) : Scene<T> {
+    override val entries: List<NavEntry<T>> = listOf(firstEntry, secondEntry)
+    override val content: @Composable (() -> Unit) = {
+        Row(modifier = Modifier.fillMaxSize()) {
+            Column(modifier = Modifier.weight(0.5f)) {
+                firstEntry.Content()
+            }
+            Column(modifier = Modifier.weight(0.5f)) {
+                secondEntry.Content()
+            }
+        }
+    }
+
+    companion object {
+        /**
+         * Helper function to add metadata to a [NavEntry] indicating it can be displayed
+         * in a two-pane layout.
+         */
+        fun twoPane() = metadata {
+            put(TwoPaneKey, true)
+        }
+    }
+
+    object TwoPaneKey : NavMetadataKey<Boolean>
+}
+
+@Composable
+fun <T : Any> rememberTwoPaneSceneStrategy(): TwoPaneSceneStrategy<T> {
+    val windowSizeClass = currentWindowAdaptiveInfoV2().windowSizeClass
+
+    return remember(windowSizeClass) {
+        TwoPaneSceneStrategy(windowSizeClass)
+    }
+}
+
+
+// --- TwoPaneSceneStrategy ---
+/**
+ * A [SceneStrategy] that activates a [TwoPaneScene] if the window is wide enough
+ * and the top two back stack entries declare support for two-pane display.
+ */
+class TwoPaneSceneStrategy<T : Any>(val windowSizeClass: WindowSizeClass) : SceneStrategy<T> {
+
+    override fun SceneStrategyScope<T>.calculateScene(entries: List<NavEntry<T>>): Scene<T>? {
+
+        // Condition 1: Only return a Scene if the window is sufficiently wide to render two panes.
+        // We use isWidthAtLeastBreakpoint with WIDTH_DP_MEDIUM_LOWER_BOUND (600dp).
+        if (!windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND)) {
+            return null
+        }
+
+        val lastTwoEntries = entries.takeLast(2)
+
+        // Condition 2: Only return a Scene if there are two entries, and both have declared
+        // they can be displayed in a two pane scene.
+        return if (lastTwoEntries.size == 2
+            && lastTwoEntries.all { it.metadata.contains(TwoPaneScene.TwoPaneKey) }
+        ) {
+            val firstEntry = lastTwoEntries.first()
+            val secondEntry = lastTwoEntries.last()
+
+            // The scene key must uniquely represent the state of the scene.
+            // A Pair of the first and second entry keys ensures uniqueness.
+            val sceneKey = Pair(firstEntry.contentKey, secondEntry.contentKey)
+
+            TwoPaneScene(
+                key = sceneKey,
+                // Where we go back to is a UX decision. In this case, we only remove the top
+                // entry from the back stack, despite displaying two entries in this scene.
+                // This is because in this app we only ever add one entry to the
+                // back stack at a time. It would therefore be confusing to the user to add one
+                // when navigating forward, but remove two when navigating back.
+                previousEntries = entries.dropLast(1),
+                firstEntry = firstEntry,
+                secondEntry = secondEntry
+            )
+
+        } else {
+            null
+        }
+    }
+
+
+}
+```
+
+```
+/*
+ * Copyright 2025 The Android Open Source Project
+ *
+ * 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.nav3recipes.scenes.twopane
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.animation.SharedTransitionLayout
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Column
+import androidx.compose.material3.Button
+import androidx.compose.material3.Text
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.lifecycle.compose.dropUnlessResumed
+import androidx.navigation3.runtime.NavBackStack
+import androidx.navigation3.runtime.NavKey
+import androidx.navigation3.runtime.entryProvider
+import androidx.navigation3.runtime.rememberNavBackStack
+import androidx.navigation3.ui.NavDisplay
+import com.example.nav3recipes.content.ContentBase
+import com.example.nav3recipes.content.ContentGreen
+import com.example.nav3recipes.content.ContentRed
+import com.example.nav3recipes.ui.setEdgeToEdgeConfig
+import com.example.nav3recipes.ui.theme.colors
+import kotlinx.serialization.Serializable
+
+@Serializable
+private object Home : NavKey
+
+@Serializable
+private data class Product(val id: Int) : NavKey
+
+@Serializable
+private data object Profile : NavKey
+
+class TwoPaneActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        setEdgeToEdgeConfig()
+        super.onCreate(savedInstanceState)
+
+        setContent {
+            val backStack = rememberNavBackStack(Home)
+            val twoPaneStrategy = rememberTwoPaneSceneStrategy<NavKey>()
+
+            SharedTransitionLayout {
+                NavDisplay(
+                    backStack = backStack,
+                    onBack = { backStack.removeLastOrNull() },
+                    sceneStrategies = listOf(twoPaneStrategy),
+                    sharedTransitionScope = this,
+                    entryProvider = entryProvider {
+                        entry<Home>(
+                            metadata = TwoPaneScene.twoPane()
+                        ) {
+                            ContentRed("Welcome to Nav3") {
+                                Button(onClick = { backStack.addProductRoute(1) }) {
+                                    Text("View the first product")
+                                }
+                            }
+                        }
+                        entry<Product>(
+                            metadata = TwoPaneScene.twoPane()
+                        ) { product ->
+                            ContentBase(
+                                "Product ${product.id} ",
+                                Modifier.background(colors[product.id % colors.size])
+                            ) {
+                                Column(horizontalAlignment = Alignment.CenterHorizontally) {
+                                    Button(onClick = dropUnlessResumed {
+                                        backStack.addProductRoute(product.id + 1)
+                                    }) {
+                                        Text("View the next product")
+                                    }
+                                    Button(onClick = dropUnlessResumed {
+                                        backStack.add(Profile)
+                                    }) {
+                                        Text("View profile")
+                                    }
+                                }
+                            }
+                        }
+                        entry<Profile> {
+                            ContentGreen("Profile (single pane only)")
+                        }
+                    }
+                )
+            }
+        }
+    }
+}
+
+private fun NavBackStack<NavKey>.addProductRoute(productId: Int) {
+    val productRoute =
+        Product(productId)
+    // Avoid adding the same product route to the back stack twice.
+    if (!contains(productRoute)) {
+        add(productRoute)
+    }
+}
+```

package/dist/consumer-canonical/skills/navigation-3/references/android/guide/navigation/type-safe-destinations.md

@@ -0,0 +1,129 @@
+This guide outlines the process of replacing string-based routes with
+serializable Kotlin types to achieve compile-time safety and eliminate runtime
+crashes caused by typos or incorrect argument types.
+
+## Prerequisites
+
+Before starting the migration, verify that your project meets the following
+requirements:
+
+1. **Navigation version**: Update to Jetpack Navigation 2.8.0 or higher
+2. **Kotlin serialization plugin**:
+3. Add the plugin to `libs.versions.toml`:
+
+    [libraries]
+    kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerializationJson" }
+
+    [plugins]
+    kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+
+- Add the dependencies to your top-level `build.gradle.kts` and module-level `build.gradle.kts`.
+
+## Step 1: Define Your Destinations
+
+Replace your constant route strings with `@Serializable` objects and classes.
+
+- **For screens without arguments** : Use a `data object`
+- **For screens with arguments** : Use a `data class`
+
+**Before (string based):**
+
+    const val ROUTE_HOME = "home"
+    const val ROUTE_PROFILE = "profile/{userId}"
+
+**After (type safe):**
+
+    import kotlinx.serialization.Serializable
+
+    @Serializable
+    object Home
+
+    @Serializable
+    data class Profile(val userId: String)
+
+## Step 2: Update the NavHost Configuration
+
+Update your `NavHost` to use the new generic types in the `composable` and
+`dialog` function.
+
+**Before:**
+
+    NavHost(navController, startDestination = "home") {
+        composable("home") { HomeScreen(...) }
+        composable("profile/{userId}") { backStackEntry ->
+            val userId = backStackEntry.arguments?.getString("userId")
+            ProfileScreen(userId)
+        }
+    }
+
+**After:**
+
+    NavHost(navController, startDestination = Home) {
+        composable<Home> {
+            HomeScreen(...)
+        }
+        composable<Profile> { backStackEntry ->
+            // The library automatically handles argument extraction
+            val profile: Profile = backStackEntry.toRoute()
+            ProfileScreen(profile.userId)
+        }
+    }
+
+## Step 3: Implement Type-Safe Navigation Calls
+
+Replace string-interpolated navigation calls with class instances.
+
+**Before:**
+
+    navController.navigate("profile/user123")
+
+**After:**
+
+    navController.navigate(Profile(userId = "user123"))
+
+## Step 4: Accessing Arguments in ViewModels
+
+If you use a `ViewModel`, you can now extract the route object directly from the
+`SavedStateHandle`.
+
+**Implementation:**
+
+    class ProfileViewModel(
+        savedStateHandle: SavedStateHandle
+    ) : ViewModel() {
+        // Automatically parses arguments into the Profile class
+        private val profile = savedStateHandle.toRoute<Profile>()
+        val userId = profile.userId
+    }
+
+## Step 5: (Advanced) Handling Custom Types
+
+If you need to pass complex data classes (not just primitives), you must define
+a custom `NavType`.
+
+1. **Create the Custom Type** : \`\`\`kotlin val SearchFilterType = object : NavType(isNullableAllowed = false) { override fun get(bundle: Bundle, key: String): SearchFilter? = Json.decodeFromString(bundle.getString(key) ?: return null)
+
+    override fun parseValue(value: String): SearchFilter =
+        Json.decodeFromString(Uri.decode(value))
+
+    override fun put(bundle: Bundle, key: String, value: SearchFilter) {
+        bundle.putString(key, Json.encodeToString(value))
+    }
+
+}
+
+
+
+    2. **Register it in the Graph**:
+    ```kotlin
+    composable<Search>(
+        typeMap = mapOf(typeOf<SearchFilter>() to SearchFilterType)
+    ) { ... }
+
+## Best practices and tips
+
+- **Sealed Hierarchies**: For large apps, group your routes using a sealed interface or class to keep the navigation structure organized
+- **Object Instances** : For routes without parameters, always use `object` instead of `class` to avoid unnecessary allocations
+- **Nullable Types** : The new API supports nullable types (for example, `data
+  class Search(val query: String?)`) and provides default values automatically
+- **Testing** : Use `navController.currentBackStackEntry?.hasRoute<T>()` to check the current destination in a type-safe manner during UI tests

package/dist/consumer-canonical/skills/theming-styles/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: theming-styles
+description: Use this skill to integrate the Jetpack Compose Styles API into an Android
+  project. This skill guides you through upgrading dependencies, setting up component
+  themes, making custom components styleable, and migrating existing layout properties
+  to use unified styles. Migrate custom design system components, replace hard coded
+  parameters with Style attributes, and use Modifier.styleable for interaction states.
+license: Complete terms in LICENSE.txt
+metadata:
+  author: Google LLC
+  last-updated: '2026-05-19'
+  keywords:
+  - Jetpack Compose
+  - Styles
+  - Theming with Styles
+  - Migrate to Styles
+  - Modifier.styleable
+---
+
+## Limitations
+
+- Warn the user that this skill is EXPERIMENTAL and requires updating to alpha version of Compose and opting in to the Experimental APIs.
+- This skill only supports custom UI components and custom themes.
+- This skill does not support Material Design component Styles.
+
+## Prerequisites
+
+### 1. Upgrade dependencies
+
+- The project must use `compileSdk` version 37 or higher.
+- The project must use `androidx.compose.foundation:foundation` version `1.12.0-alpha01` or higher.
+- Alternatively, the project must use Compose BOM version `2026.04.01` or higher.
+- The API requires this exact package: `import
+  androidx.compose.foundation.style.Style`
+
+### 2. Configure compiler options to enable experimental API
+
+You must opt-in to the experimental API at the project level. Add the following
+block to your module's `build.gradle.kts`:
+
+    kotlin {
+        compilerOptions {
+            jvmTarget = JvmTarget.fromTarget("17")
+            freeCompilerArgs.add("-opt-in=androidx.compose.foundation.style.ExperimentalFoundationStyleApi")
+        }
+    }
+
+## Core workflows and guides
+
+Refer to the official documentation to complete specific development tasks:
+
+- Basic Style Usage: To set backgrounds, sizes, and alignments on a component, follow the [Compose Styles Fundamentals
+  Guide](references/android/develop/ui/compose/styles/fundamentals.md).
+- State and Transitions: To configure property changes for state shifts (like pressed or hovered), follow the [Animations and State-Based Styling
+  Guide](references/android/develop/ui/compose/styles/state-animations.md).
+- Architecture Trade offs: To decide when to use a Style versus a standard Modifier, follow the [Styles versus Modifiers
+  Comparison](references/android/develop/ui/compose/styles/styles-vs-modifiers.md).
+- Theme Level Integration: To connect style definitions with custom themes, follow [Theming with Styles](references/android/develop/ui/compose/styles/theming.md) and [Custom Themes in Compose](references/android/develop/ui/compose/designsystems/custom.md).
+
+## Step-by-Step Migration Workflow
+
+### Step 1: Analyze theme structure
+
+1. Locate your central theme file (such as `Theme.kt`).
+2. Identify design tokens. Note references for colors, typography, and shapes (for example, `LocalColorScheme`, `LocalTypography`, or `LocalShapes`).
+3. If the project lacks Jetpack Compose dependencies, stop. Instruct the user to migrate to Jetpack Compose first.
+4. If the project imports `androidx.compose.material.MaterialTheme`, recommend migrating to Material 3 before proceeding.
+
+### Step 2: Establish `ComponentStyles`
+
+1. Create a new file named `ComponentStyles.kt` in your theme directory.
+2. Define a top-level data class to hold your component styles, for example, the Jetsnack one is called `JetsnackStyles`:
+
+
+   ```kotlin
+   object ExampleComponentStyles {
+       val customButtonStyle: Style = {
+
+       }
+       val customTextFieldStyle: Style = {
+
+       }
+   }
+   ```
+
+   <br />
+
+3. Expose this class through your custom theme with a static reference, don't
+   use `CompositionLocals` here as it's not required.
+
+
+   ```kotlin
+   @Immutable
+   class JetsnackTheme(
+       // other Design system properties
+   ) {
+       companion object {
+           val colors: CustomThemingWithStyles.JetsnackColors
+               @Composable @ReadOnlyComposable
+               get() = LocalJetsnackTheme.current.colors
+           // ...
+
+           // add helper static reference
+           val styles: ComponentStyles = ComponentStyles
+       }
+   }
+   ```
+
+   <br />
+
+4. Provide extensions on `StyleScope` to reference theme tokens directly if
+   they are exposed using `CompositionLocals`. For example:
+
+
+   ```kotlin
+   val StyleScope.colors: JetsnackColors
+       get() = LocalJetsnackTheme.currentValue.colors
+
+   val StyleScope.typography: androidx.compose.material3.Typography
+       get() = LocalJetsnackTheme.currentValue.typography
+
+   val StyleScope.shapes: Shapes
+       get() = LocalJetsnackTheme.currentValue.shapes
+   ```
+
+   <br />
+
+### Step 3: Migrate a component to Styles API
+
+For each custom component (for example, `CustomButton`), complete the following
+sequence:
+
+1. If you are able to run an Android emulator, locate an existing screenshot test for the component. If none exists, create one using the existing project testing framework. If no framework exists, use UI Automator or Espresso to create a screenshot test with minimum required setup. Run the test and take a baseline screenshot of the Component. ELSE proceed to the next step without a screenshot test.
+2. **Remove individual styling parameters** : Remove styling parameters such as `backgroundColor`, `shape`, `textStyle`, and `contentPadding` from the signature - anything that `StyleScope` supports.
+3. **Add the style parameter** : Add `style: Style = Style` to the function signature.
+4. **Declare state tracking** : If the component is interactable, create a `MutableStyleState` using the interaction source. Update state fields (such as `isEnabled`) inside the Composable to track the state correctly.
+5. **Apply styleable modifier** : Replace specific layout modifiers on the root element with `Modifier.styleable()`.
+6. **Move defaults to ComponentStyles** : Move hardcoded values from the component definition to a dedicated `Style` instance in `ComponentStyles.kt`.
+7. **Validate component:** Compare the baseline screenshot image taken at the start with the rendered Compose Preview of the new composable. Ignore string content; focus on layout and styling. Iterate on the Compose code until visual parity is achieved. Once verified, write a Compose UI test for the new composable.
+
+#### Migration example
+
+Before Migration:
+
+
+```kotlin
+@Composable
+fun CustomButton(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    backgroundColor: Color = JetsnackTheme.colors.brandLight,
+    disabledBackgroundColor: Color = JetsnackTheme.colors.brandSecondary,
+    shape: Shape = JetsnackTheme.shapes.extraLarge,
+    textStyle: TextStyle = JetsnackTheme.typography.labelLarge,
+    enabled: Boolean = true,
+    content: @Composable RowScope.() -> Unit,
+) {
+    val interactionSource = remember { MutableInteractionSource() }
+    Row(
+        modifier
+            .clickable(onClick = onClick, indication = null, interactionSource = interactionSource)
+            .background(if (enabled) backgroundColor else disabledBackgroundColor, shape)
+            .defaultMinSize(58.dp, 40.dp),
+        horizontalArrangement = Arrangement.Center,
+        verticalAlignment = Alignment.CenterVertically,
+        content = content,
+    )
+}
+```
+
+<br />
+
+After Migration:
+
+
+```kotlin
+// Exposed via ComponentStyles.kt
+object ComponentStyles {
+    val buttonStyle = Style {
+        background(colors.brandLight)
+        shape(shapes.extraLarge)
+        minWidth(58.dp)
+        minHeight(40.dp)
+        textStyle(typography.labelLarge)
+        disabled {
+            background(colors.brandSecondary)
+        }
+    }
+}
+
+@Composable
+fun CustomButton(
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    style: Style = Style,
+    enabled: Boolean = true,
+    content: @Composable RowScope.() -> Unit,
+) {
+    val interactionSource = remember { MutableInteractionSource() }
+    val styleState = rememberUpdatedStyleState(interactionSource) {
+        it.isEnabled = enabled
+    }
+    Row(
+        modifier
+            .clickable(onClick = onClick, indication = null, interactionSource = interactionSource)
+            .styleable(styleState, JetsnackTheme.styles.buttonStyle, style),
+        horizontalArrangement = Arrangement.Center,
+        verticalAlignment = Alignment.CenterVertically,
+        content = content,
+    )
+}
+```
+
+<br />
+
+### Step 4: Validate Changes
+
+1. Build the project. Verify that there are no compilation errors.
+2. Run your module's screenshot tests.
+3. Compare visual outputs of the whole app between the previous and updated components. Verify that no visual layout regressions occur.