Skip to content

Migrate navigation graph design, Kotlin DSL, nested graph, and Navigation Editor snippets - #1221

Open
edward-williams-stellarelements wants to merge 1 commit into
android:mainfrom
StellarElements:entcwilliams/navigation-graph-design
Open

Migrate navigation graph design, Kotlin DSL, nested graph, and Navigation Editor snippets#1221
edward-williams-stellarelements wants to merge 1 commit into
android:mainfrom
StellarElements:entcwilliams/navigation-graph-design

Conversation

@edward-williams-stellarelements

@edward-williams-stellarelements edward-williams-stellarelements commented Oct 23, 2026

Copy link
Copy Markdown

Code snippets are for:

This PR moves 15 code blocks from these four guide pages into compiled files. Each page gets its own package, so route names that repeat across pages don't collide.

Page Section Region tag File
Design Pass arguments android_compose_navigation_design_arguments compose/.../navigation/design/DesignGraph.kt
Design Pass arguments (optional argument) android_compose_navigation_design_optional_arguments compose/.../navigation/design/DesignGraph.kt
Design XML android_views_navigation_design_nav_graph views/src/main/res/navigation/nav_graph_design.xml
Kotlin-dsl Create routes for your graph android_views_navigation_kotlin_dsl_routes views/.../navigation/kotlindsl/KotlinDsl.kt
Kotlin-dsl Navigating with your Kotlin DSL graph android_views_navigation_kotlin_dsl_navigate views/.../navigation/kotlindsl/KotlinDsl.kt
Kotlin-dsl Supporting custom destinations android_views_navigation_kotlin_dsl_custom_destination views/.../navigation/kotlindsl/KotlinDsl.kt
Kotlin-dsl Supporting custom destinations (unary plus) android_views_navigation_kotlin_dsl_custom_destination_unary_plus views/.../navigation/kotlindsl/KotlinDsl.kt
Kotlin-dsl Providing custom types android_views_navigation_kotlin_dsl_custom_type_navigate views/.../navigation/kotlindsl/KotlinDsl.kt
Nested-graphs Compose android_compose_navigation_nested_graphs_navigate compose/.../navigation/nestedgraphs/NestedGraphs.kt
Nested-graphs XML android_views_navigation_nested_graphs_nested_graph views/src/main/res/navigation/nav_graph_nested_graphs.xml
Nested-graphs XML (navigate with the action ID) android_views_navigation_nested_graphs_navigate_action views/.../navigation/nestedgraphs/NestedGraphs.kt
Nested-graphs Reference other navigation graphs with include (root graph) android_views_navigation_nested_graphs_include views/src/main/res/navigation/nav_graph_nested_graphs_include.xml
Nested-graphs Reference other navigation graphs with include (included graph) android_views_navigation_nested_graphs_included_graph views/src/main/res/navigation/included_graph.xml
Editor Overview android_views_navigation_editor_empty_graph views/src/main/res/navigation/nav_graph_editor_empty.xml
Editor Anatomy of a destination android_views_navigation_editor_destination views/src/main/res/navigation/nav_graph_editor_destination.xml

compose/... is compose/snippets/src/main/java/com/example/compose/snippets, and views/... is views/src/main/java/com/example/example/snippet/views.

The two route classes on the design page and the navigate() call on the nested-graphs page sit in the Compose sections of those pages, so they go in :compose:snippets. The Fragment, Kotlin DSL, and XML code goes in :views.

Dependencies added to :views

These are the first Fragment navigation snippets in :views, so the module needs:

  • androidx.navigation:navigation-fragment-ktx, as a new androidx-navigation-fragment-ktx catalog entry on the existing androidx-navigation version. Directly or through the Navigation runtime library it brings in, it provides:
    • Fragment.findNavController() in android_views_navigation_kotlin_dsl_navigate.
    • View.findNavController() in android_views_navigation_nested_graphs_navigate_action.
    • NavController.navigatorProvider and the graph builder's addDestination() and unary plus in the two custom destination snippets, and NavController.navigate() in android_views_navigation_kotlin_dsl_custom_type_navigate.
    • The <navigation>, <fragment>, <action>, and <include> elements and their app:startDestination, app:destination, and app:graph attributes in the six graph XML files.
  • The Kotlin serialization plugin and kotlinx-serialization-core, for the @Serializable route classes in android_views_navigation_kotlin_dsl_routes and the routes that the Kotlin-dsl navigate snippets pass to navigate(). Navigation brings in kotlinx-serialization-core only at runtime, so the annotation needs the direct dependency.

:compose:snippets already has Navigation Compose and Kotlin serialization, so it needs nothing new.

Supporting code and resources

Everything in this section sits outside the region tags, so none of it shows on the guide pages.

  • Design page: the page declares Profile twice, with different parameters, so each declaration sits in its own private object (RouteWithArgument and RouteWithOptionalArgument).
  • Kotlin-dsl page:
    • navigateToPlant() calls findNavController() with no receiver, which is the Fragment extension, so it sits in a HomeFragment class (the page's name for the fragment of the Home destination). The class is public because the system recreates fragments by class name.
    • Routes that the snippets use but that the migrated blocks don't declare are private classes at the bottom of the file: PlantDetail(id), plus SearchParameters and SearchRoute, which mirror the page's declarations under "Providing custom types" (without @Parcelize, which compiling doesn't need).
    • The custom destination snippets run inside a createGraph() builder in a NavController extension, so navigatorProvider is the NavController's provider, as the snippets' comment says. CustomNavigator is a minimal Navigator<NavDestination>, and Graph.CustomDestination.route is a private string constant.
    • navigateToSearch() takes the NavController that the snippet calls.
  • Nested-graphs page: the Compose navigate() call gets its NavController from a function parameter, plus a private Match route object. The Fragment version takes the View that it calls findNavController() on.

Resources that the graph XML needs to build. The guide pages don't print them, but the build fails without them:

  • included_graph.xml: the root graph includes @navigation/included_graph, so the page's own code forces this file name. The file holds the page's second graph.
  • label_blank in views/src/main/res/values/strings.xml (value Blank): the editor page's destination uses android:label="@string/label_blank".
  • The tools:layout references (fragment_main, fragment_blank, and others) only affect the Navigation Editor preview, so no layout files are added for them.

List of modifications (visible diffs vs. the page)

  • Design page: no visible changes. All three regions match the page.
  • Kotlin-dsl page:
    • android_views_navigation_kotlin_dsl_custom_destination and android_views_navigation_kotlin_dsl_custom_destination_unary_plus: the comment now ends with a full stop: // The NavigatorProvider is retrieved from the NavController.
    • The other three regions match the page, including the 3-space indent in navigateToPlant().
  • Nested-graphs page:
    • android_views_navigation_nested_graphs_nested_graph, android_views_navigation_nested_graphs_include, and android_views_navigation_nested_graphs_included_graph: the snippets start at the root <navigation> element, without the page's <?xml version="1.0" encoding="utf-8"?> line. An XML declaration has to be the first line of the file, ahead of the license header and the region tag, so it can't sit inside a region. (In the two include examples, the page prints it after a comment, where an XML parser rejects it.)
    • android_views_navigation_nested_graphs_include: the page's ... line is written as the XML comment <!-- ... -->, so the file is valid XML.
    • The two navigate() snippets match the page.
  • Editor page: both snippets start at the root <navigation> element, without the <?xml version="1.0" encoding="utf-8"?> line, for the same reason.

Snippets not migrated

The other code blocks on these pages are left as they are on the guide pages for now:

  • Design page: 7 blocks (the Compose NavHost and createGraph() examples, the route-instance and minimal examples, the two NavHostFragment layouts, and the Kotlin DSL graph).
  • Kotlin-dsl page: 14 blocks (the host layout, the createGraph() graph, the back stack and SavedStateHandle route reads, the fragment, activity, and navigation destination builders, the argument and custom type declarations, the custom NavType, the typed fragment destination, the search route read, the deep link, and the URI format route).
  • Nested-graphs page: the Compose nested graph example. The Java version of the navigate() call isn't migrated. The guide page is being updated separately to show only the Kotlin version.
  • Editor page: the graph under "Connect destinations".

Build: ./gradlew :views:spotlessApply :compose:snippets:spotlessApply runs first. Then ./gradlew :views:build and ./gradlew :compose:snippets:build both pass, with no warnings or lint findings in the added files.

@snippet-bot

snippet-bot Bot commented Oct 23, 2026

Copy link
Copy Markdown

Here is the summary of changes.

You are about to add 15 region tags.

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

  • Refresh this comment

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@riggaroo riggaroo Awaiting requested review from riggaroo riggaroo is a code owner automatically assigned from android/devrel-compose

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@edward-williams-stellarelements