Sean/support custom user profile rows (#382)

* Add external navigation path support to UserProfileView

Allow embedding UserProfileView in a parent NavigationStack by passing
an optional navigationPath binding. When provided, destinations push
onto the parent's path instead of an internal stack.

- Add externalPath and externalPathBaseCount to UserProfileNavigation
- Add navigate(to:) and popToRoot() methods for unified navigation
- Extract profileContent to conditionally wrap in NavigationStack
- Track isEmbedded in telemetry payload

# Conflicts:
#	Sources/ClerkKitUI/Components/UserProfile/UserProfileView.swift

* Refactor UserProfileView to configure external navigation path lazily

Move external navigation path configuration from init to taskOnce
to ensure the binding is properly captured when the view appears.
This fixes an issue where the external path could be stale when
passed through initializer state wrappers.

* Add includingSelf parameter to popToRoot for account deletion

When deleting the last session in embedded mode, we need to also
pop the UserProfileView entry itself from the parent's navigation
stack, not just the views pushed by the profile flow.

* Fix bounds checking in popToRoot to prevent negative values

* Refactor UserProfileView navigation to use router pattern

Replace imperative navigation.navigate() calls with a new
UserProfileRouter struct that manages push/pop operations via
closures. This provides a cleaner API for embedded and standalone
navigation scenarios.

- Extract routing logic from UserProfileNavigation into UserProfileRouter
- Track embedded push count via @State to properly pop to root
- Inject router through environment for consistent access

* Refactor UserProfileView to use @entry macro for router

Move navigation path from UserProfileNavigation to local state
within UserProfileView, simplifying the navigation class to only
manage presentation state. Replace custom EnvironmentKey with
@entry macro for cleaner environment value declaration.

* Rename UserProfileNavigation to UserProfileSheetNavigation

* Simplify popToRoot by moving includingSelf logic inside

* Simplify popToRoot by combining removeLast operations

* Replace push count tracking with initial path count

Use initialPathCount captured at init to calculate entries to
remove during popToRoot, eliminating the need for onChange tracking
and embeddedPushCount state management.

* Add includingSelf parameter to UserProfileRouter.popToRoot

Clarifies the caller's intent when popping to root after account
deletion. The decision about whether to include the current view
in the pop is now made explicitly at the call site based on
whether the user still exists and if the account switcher will
be presented.

* Add preview for UserProfileView embedded in parent NavigationStack

* Add custom rows support to UserProfileView

Allow developers to inject custom rows into the root profile screen
with flexible placement options. Custom rows can be positioned at
section start/end or before/after specific built-in rows.

* Type user profile custom navigation routes

Replace AnyHashable-based custom row and destination routing with typed
Route generics, add UserProfileNavigator for environment-driven
navigation, and keep a built-in router for Clerk-owned child views.

* Add custom user profile rows to UserButton

Support custom profile rows and destination routing from
`UserButton` into `UserProfileView`.

Update profile row icon rendering so asset and system icons
share consistent sizing and theming.

* Remove built-in row navigation from UserProfileNavigator

The public navigator should only allow pushing custom routes.
Built-in row navigation is now handled internally through
the private navigate(to:) helper method.

* Simplify UserProfileView navigation by inlining navigator

The UserProfileNavigator instance was being created on every body
evaluation via the computed property. Inline the calls to navigate()
directly and construct the navigator only when needed for child views.

* Rename popToRoot to dismiss with explicit action enum

* Rename UserProfileCustomRow to UserProfileCustomItem

Use view modifier API for custom items and destinations

* Move initialPathCount initialization to onFirstAppear

This ensures the initial path count is captured when the view actually
appears rather than during init, providing more reliable navigation
state tracking.

* Move UserButtonPresentationContext below public struct

* Inline UserProfileView sheet content in UserButton

* Improve row ID to support duplicate routes

* Add missing environment objects to SwiftUI previews

* Refactor UserProfileView navigation and extract header

Separate built-in and custom route navigation paths to allow custom
routes to use a distinct navigation destination. Extract header view
and custom row helpers into separate files for better organization.

* Remove unused bundle parameter from UserProfileCustomRow

SwiftUI's LocalizedStringKey automatically uses the calling module's
bundle via an internal init. Explicit bundle passing was redundant
and added unnecessary API surface.

* Change internal properties from public to internal

* Add configurable width and height to asset icon type

Author: seanperez29

Sources/ClerkKitUI/Components/UserButton/UserButton.swift

@@ -51,17 +51,14 @@ import SwiftUI
 ///   }
 /// }
 /// ```
-public struct UserButton<SignedOutContent: View>: View {
+public struct UserButton<Route: Hashable, SignedOutContent: View, Destination: View>: View {
   @Environment(Clerk.self) private var clerk
   @Environment(\.clerkTheme) private var theme
 
-  enum PresentationContext {
-    case standard
-    case sessionTaskToolbar
-  }
-
   @State private var presentedSheet: PresentedSheet?
-  private let presentationContext: PresentationContext
+  private let presentationContext: UserButtonPresentationContext
+  private let customRows: [UserProfileCustomRow<Route>]
+  private let customDestination: (@MainActor (Route) -> Destination)?
   private let signedOutContent: () -> SignedOutContent
 
   private enum PresentedSheet: String, Identifiable {
@@ -80,29 +77,39 @@ public struct UserButton<SignedOutContent: View>: View {
   /// and handle presenting the user profile sheet when tapped.
   public init(
     @ViewBuilder signedOutContent: @escaping () -> SignedOutContent
-  ) {
+  ) where Route == Never, Destination == EmptyView {
     self.init(
       presentationContext: .standard,
+      customRows: [],
+      customDestination: nil,
       signedOutContent: signedOutContent
     )
   }
 
   init(
-    presentationContext: PresentationContext,
+    presentationContext: UserButtonPresentationContext,
+    customRows: [UserProfileCustomRow<Route>],
+    customDestination: (@MainActor (Route) -> Destination)?,
     @ViewBuilder signedOutContent: @escaping () -> SignedOutContent
   ) {
     self.presentationContext = presentationContext
+    self.customRows = customRows
+    self.customDestination = customDestination
     self.signedOutContent = signedOutContent
   }
 
   /// Creates a new user button with no signed-out content.
-  public init() where SignedOutContent == EmptyView {
+  public init() where Route == Never, SignedOutContent == EmptyView, Destination == EmptyView {
     self.init(presentationContext: .standard)
   }
 
-  init(presentationContext: PresentationContext) where SignedOutContent == EmptyView {
+  init(
+    presentationContext: UserButtonPresentationContext
+  ) where Route == Never, SignedOutContent == EmptyView, Destination == EmptyView {
     self.init(
       presentationContext: presentationContext,
+      customRows: [],
+      customDestination: nil,
       signedOutContent: { EmptyView() }
     )
   }
@@ -142,8 +149,13 @@ public struct UserButton<SignedOutContent: View>: View {
     .sheet(item: $presentedSheet) { sheet in
       switch sheet {
       case .userProfile:
-        UserProfileView()
-          .presentationDragIndicator(.visible)
+        UserProfileView(
+          isDismissable: true,
+          navigationPath: nil,
+          customRows: customRows,
+          customDestination: customDestination
+        )
+        .presentationDragIndicator(.visible)
       case .sessionTaskAuth:
         AuthView()
           .presentationDragIndicator(.visible)
@@ -163,7 +175,24 @@ public struct UserButton<SignedOutContent: View>: View {
   }
 }
 
+enum UserButtonPresentationContext {
+  case standard
+  case sessionTaskToolbar
+}
+
 extension UserButton {
+  /// Replaces the custom rows shown in the presented user profile.
+  public func userProfileRows(
+    _ rows: [UserProfileCustomRow<Route>]
+  ) -> UserButton<Route, SignedOutContent, Destination> {
+    UserButton<Route, SignedOutContent, Destination>(
+      presentationContext: presentationContext,
+      customRows: rows,
+      customDestination: customDestination,
+      signedOutContent: signedOutContent
+    )
+  }
+
   private func handleTap() {
     switch presentationContext {
     case .sessionTaskToolbar:
@@ -178,6 +207,47 @@ extension UserButton {
   }
 }
 
+extension UserButton where Destination == EmptyView {
+  /// Sets the custom destination builder used by custom rows in the presented user profile.
+  public func userProfileDestination<NewDestination: View>(
+    @ViewBuilder _ destination: @escaping @MainActor (Route) -> NewDestination
+  ) -> UserButton<Route, SignedOutContent, NewDestination> {
+    UserButton<Route, SignedOutContent, NewDestination>(
+      presentationContext: presentationContext,
+      customRows: customRows,
+      customDestination: destination,
+      signedOutContent: signedOutContent
+    )
+  }
+}
+
+extension UserButton where Route == Never, Destination == EmptyView {
+  /// Sets the custom rows shown in the presented user profile.
+  public func userProfileRows<NewRoute: Hashable>(
+    _ rows: [UserProfileCustomRow<NewRoute>]
+  ) -> UserButton<NewRoute, SignedOutContent, EmptyView> {
+    UserButton<NewRoute, SignedOutContent, EmptyView>(
+      presentationContext: presentationContext,
+      customRows: rows,
+      customDestination: nil,
+      signedOutContent: signedOutContent
+    )
+  }
+
+  /// Sets the custom destination builder used by custom rows in the presented user profile.
+  public func userProfileDestination<NewRoute: Hashable, NewDestination: View>(
+    for _: NewRoute.Type = NewRoute.self,
+    @ViewBuilder _ destination: @escaping @MainActor (NewRoute) -> NewDestination
+  ) -> UserButton<NewRoute, SignedOutContent, NewDestination> {
+    UserButton<NewRoute, SignedOutContent, NewDestination>(
+      presentationContext: presentationContext,
+      customRows: [],
+      customDestination: destination,
+      signedOutContent: signedOutContent
+    )
+  }
+}
+
 #Preview {
   UserButton()
     .clerkPreview()

Sources/ClerkKitUI/Components/UserButton/UserButtonAccountSwitcher.swift

@@ -11,7 +11,7 @@ import SwiftUI
 struct UserButtonAccountSwitcher: View {
   @Environment(Clerk.self) private var clerk
   @Environment(\.clerkTheme) private var theme
-  @Environment(UserProfileNavigation.self) private var navigation
+  @Environment(UserProfileSheetNavigation.self) private var navigation
   @Environment(\.dismiss) private var dismiss
 
   @Binding private var contentHeight: CGFloat
@@ -171,6 +171,7 @@ struct UserButtonAccountSwitcher: View {
 #Preview {
   UserButtonAccountSwitcher()
     .clerkPreview()
+    .environment(UserProfileSheetNavigation())
     .environment(\.clerkTheme, .clerk)
 }
 

Sources/ClerkKitUI/Components/UserButton/UserProfileRowView.swift

@@ -10,17 +10,24 @@ import SwiftUI
 struct UserProfileRowView: View {
   @Environment(\.clerkTheme) private var theme
 
-  let icon: String
+  let icon: UserProfileRowIcon
   let text: LocalizedStringKey
+  let bundle: Bundle?
+
+  init(icon: UserProfileRowIcon, text: LocalizedStringKey, bundle: Bundle? = .module) {
+    self.icon = icon
+    self.text = text
+    self.bundle = bundle
+  }
+
+  init(icon: String, text: LocalizedStringKey, bundle: Bundle? = .module) {
+    self.init(icon: .asset(name: icon), text: text, bundle: bundle)
+  }
 
   var body: some View {
     HStack(spacing: 16) {
-      Image(icon, bundle: .module)
-        .resizable()
-        .scaledToFit()
-        .frame(width: 48, height: 24)
-        .foregroundStyle(theme.colors.mutedForeground)
-      Text(text, bundle: .module)
+      iconView
+      Text(text, bundle: bundle)
         .font(theme.fonts.body)
         .fontWeight(.semibold)
         .foregroundStyle(theme.colors.foreground)
@@ -31,6 +38,27 @@ struct UserProfileRowView: View {
     .padding(.horizontal, 24)
     .contentShape(.rect)
   }
+
+  @ViewBuilder
+  private var iconView: some View {
+    switch icon {
+    case .asset(let name, let width, let height):
+      Image(name, bundle: bundle)
+        .renderingMode(.template)
+        .resizable()
+        .scaledToFit()
+        .frame(width: width, height: height)
+        .frame(width: 48, height: 24)
+        .foregroundStyle(theme.colors.mutedForeground)
+    case .system(let name):
+      Image(systemName: name)
+        .resizable()
+        .scaledToFit()
+        .frame(maxWidth: 21, maxHeight: 21)
+        .frame(width: 48, height: 24)
+        .foregroundStyle(theme.colors.mutedForeground)
+    }
+  }
 }
 
 #Preview {

Sources/ClerkKitUI/Components/UserProfile/BackupCodesView.swift

@@ -10,7 +10,7 @@ import SwiftUI
 
 struct BackupCodesView: View {
   @Environment(\.clerkTheme) private var theme
-  @Environment(UserProfileNavigation.self) private var navigation
+  @Environment(UserProfileSheetNavigation.self) private var navigation
   @Environment(\.dismiss) private var dismiss
 
   enum MfaType {
@@ -132,6 +132,7 @@ struct BackupCodesGrid: View {
     backupCodes: ["abc", "def", "ghi", "jkl", "lmn", "opq", "rst", "uvw", "xyz"],
     mfaType: .authenticatorApp
   )
+  .environment(UserProfileSheetNavigation())
 }
 
 #endif

Sources/ClerkKitUI/Components/UserProfile/UserProfileAddMfaView.swift

@@ -11,7 +11,7 @@ import SwiftUI
 struct UserProfileAddMfaView: View {
   @Environment(Clerk.self) private var clerk
   @Environment(\.clerkTheme) private var theme
-  @Environment(UserProfileNavigation.self) private var navigation
+  @Environment(UserProfileSheetNavigation.self) private var navigation
   @Environment(\.dismiss) private var dismiss
 
   @State private var error: Error?