feat(mosaic): Configure the profile on MosaicProvider

Author: alexcarpenter

.changeset/mosaic-profile-provider.md

@@ -0,0 +1,20 @@
+---
+'@clerk/mosaic': minor
+---
+
+Configure the profile on `MosaicProvider` with the new `profile` prop, so `UserButton`, `OrganizationSwitcher` and `UserProfile` share one setup. This makes pairings like a user-only `UserButton` beside an `OrganizationSwitcher` with one combined profile possible.
+
+```tsx
+<MosaicProvider profile={{ combined: true, userProfileProps, organizationProfileProps }}>
+  <OrganizationSwitcher />
+  <UserButton combined={false} />
+</MosaicProvider>
+```
+
+Breaking changes:
+
+- `UserButton`: `mode` is replaced by `combined`, which only decides what the menu lists. `mode='user'` becomes `combined={false}`, and to keep the account-only profile too, also set `profile={{ combined: false }}` on `MosaicProvider`.
+- `UserButton` and `OrganizationSwitcher`: `userProfileProps` and `organizationProfileProps` move to `MosaicProvider`'s `profile`.
+- `UserProfile`: `mode` is replaced by `combined`. When unset it follows `profile.combined`, and it also picks up the provider's profile props, with its own props winning.
+- With `experimental.newProfiles`, `OrganizationSwitcher` now opens the combined profile by default. Set `profile={{ combined: false }}` for the standalone organization profile.
+- The `UserProfileMode` type is removed.

.changeset/profile-permutations-swingset.md

@@ -4,13 +4,15 @@ import { MosaicProvider, UserButton } from '@clerk/mosaic';
 
 export default function Page() {
   return (
-    <MosaicProvider experimental={{ newProfiles: true }}>
-      <UserButton
-        customMenuItems={[{ id: 'custom-link', label: 'Custom link', href: '/custom/link-target' }]}
-        userProfileProps={{
+    <MosaicProvider
+      experimental={{ newProfiles: true }}
+      profile={{
+        userProfileProps: {
           customPages: [{ label: 'Custom page', path: 'custom-page', content: <p>custom-page-content</p> }],
-        }}
-      />
+        },
+      }}
+    >
+      <UserButton customMenuItems={[{ id: 'custom-link', label: 'Custom link', href: '/custom/link-target' }]} />
     </MosaicProvider>
   );
 }

integration/templates/next-app-router-mosaic/src/app/custom/page.tsx

@@ -4,12 +4,16 @@ import { MosaicProvider, OrganizationSwitcher } from '@clerk/mosaic';
 
 export default function Page() {
   return (
-    <MosaicProvider experimental={{ newProfiles: true }}>
+    <MosaicProvider
+      experimental={{ newProfiles: true }}
+      profile={{
+        organizationProfileProps: {
+          customPages: [{ label: 'Custom page', path: 'custom-page', content: <p>custom-page-content</p> }],
+        },
+      }}
+    >
       <OrganizationSwitcher
         customMenuItems={[{ id: 'custom-link', label: 'Custom link', href: '/custom/link-target' }]}
-        organizationProfileProps={{
-          customPages: [{ label: 'Custom page', path: 'custom-page', content: <p>custom-page-content</p> }],
-        }}
       />
     </MosaicProvider>
   );

integration/templates/next-app-router-mosaic/src/app/organization-switcher/page.tsx

@@ -4,6 +4,7 @@ import { act, render } from '@testing-library/react';
 import type { ReactElement } from 'react';
 import { vi } from 'vitest';
 
+import type { MosaicProfile } from '../../features/profile-pages/use-mosaic-profile';
 import type { MosaicExperimental } from '../../hooks/use-mosaic-experimental';
 import type { MosaicLocalization } from '../../localization';
 import { MosaicProvider } from '../../mosaic-provider';
@@ -14,6 +15,7 @@ export async function renderWithClerk(
   options?: Parameters<Clerk['load']>[0],
   localization?: MosaicLocalization,
   experimental?: MosaicExperimental,
+  profile?: MosaicProfile,
 ) {
   const clerk = new Clerk(publishableKey());
   const navigate = vi.fn((_to: string) => Promise.resolve());
@@ -26,6 +28,7 @@ export async function renderWithClerk(
       <MosaicProvider
         localization={localization}
         experimental={experimental}
+        profile={profile}
       >
         {element}
       </MosaicProvider>

packages/mosaic/src/__tests__/feature/render.tsx

@@ -381,7 +381,7 @@ describe('OrganizationSwitcher with experimental.newProfiles', () => {
     await page.viewport(1280, 800);
     onTestFinished(() => page.viewport(414, 896));
     serveFapi(noOffers());
-    return renderWithClerk(tree(props), undefined, undefined, { newProfiles: true });
+    return renderWithClerk(tree(props), undefined, undefined, { newProfiles: true }, { combined: false });
   }
 
   it('opens the OrganizationProfile, without the account pages, from Settings', async () => {

packages/mosaic/src/features/organization-switcher/__tests__/organization-switcher.feature.test.tsx

@@ -8,11 +8,11 @@ import type { OrganizationSwitcherModelOptions } from '../switcher/switcher.mode
 import type { SwitcherMenuProps } from '../switcher/switcher.types';
 import type { SwitcherTriggerProps } from '../switcher/switcher.view';
 
-/** Everything `<OrganizationSwitcher />` takes: profile routing, trigger content, the app's own menu rows, and the profile it opens. */
+/** Everything `<OrganizationSwitcher />` takes: profile routing, trigger content, and the app's own menu rows. */
 export type OrganizationSwitcherProps = OrganizationSwitcherModelOptions &
   SwitcherTriggerProps &
   SwitcherMenuProps &
-  Pick<SwitcherProps, 'organizationProfileProps' | 'fallback'>;
+  Pick<SwitcherProps, 'fallback'>;
 
 /**
  * The active organization's avatar, and the menu behind it: switch organization or back to the
@@ -47,14 +47,10 @@ export type OrganizationSwitcherProps = OrganizationSwitcherModelOptions &
  * ```
  *
  * @example
- * `customPages` adds your own pages to the organization profile; `customMenuItems` adds your own rows
- * beside Settings, each one either an `onClick` action or an `href` link.
+ * `customMenuItems` adds your own rows beside Settings, each one either an `onClick` action or an
+ * `href` link. The profile's own pages are set on `MosaicProvider`'s `profile`.
  * ```tsx
  * <OrganizationSwitcher
- *   organizationProfileProps={{
- *     customPages: [{ path: 'audit', label: 'Audit log', icon: <ListIcon />, content: <AuditPage /> }],
- *     pageOrder: ['general', 'members', 'audit'],
- *   }}
  *   customMenuItems={[{ id: 'docs', label: 'Documentation', icon: <BookIcon />, href: 'https://example.com/docs' }]}
  * />
  * ```

packages/mosaic/src/features/organization-switcher/organization-switcher.tsx

@@ -0,0 +1,58 @@
+import type { OrganizationProfileProps, UserProfileProps } from '@clerk/shared/types';
+import { createContext, useContext } from 'react';
+
+import type { OrganizationProfilePageId } from '../switcher/switcher.pages';
+import type { CustomProfileItem, UserProfilePageId } from '../user-profile/user-profile.types';
+
+export interface MosaicProfile {
+  /**
+   * Whether one profile carries the account's pages and the active organization's. `false` keeps them
+   * in separate profiles. It decides the profile's shape, not what `UserButton`'s menu lists.
+   *
+   * @default true
+   */
+  combined?: boolean;
+  /**
+   * Options for the user profile, whichever component opens or mounts it.
+   */
+  userProfileProps?: ProfileUserProps;
+  /**
+   * Options for the organization profile, or the organization's pages in a combined profile,
+   * whichever component opens or mounts it.
+   */
+  organizationProfileProps?: ProfileOrganizationProps;
+}
+
+/** What a profile takes beyond the profile component's own props. */
+export interface ProfilePages<PageId extends string> {
+  /**
+   * Provide custom pages and links to be rendered inside the profile.
+   */
+  customPages?: CustomProfileItem[];
+  /**
+   * Controls the order of the profile's navigation. Accepts the ids of built-in pages and the
+   * `path` of custom pages. Pages not listed are placed after the listed ones. The first entry is
+   * the page the profile opens on, so it cannot be a link.
+   *
+   * @default undefined
+   */
+  pageOrder?: (PageId | (string & {}))[];
+}
+
+/** Options for the underlying `<UserProfile />` component. */
+export interface ProfileUserProps
+  extends
+    ProfilePages<UserProfilePageId>,
+    Pick<UserProfileProps, 'additionalOAuthScopes' | 'apiKeysProps' | 'appearance'> {}
+
+/** Options for the underlying `<OrganizationProfile />` component. */
+export interface ProfileOrganizationProps
+  extends ProfilePages<OrganizationProfilePageId>, Pick<OrganizationProfileProps, 'appearance'> {}
+
+const MosaicProfileContext = createContext<MosaicProfile>({});
+
+export const MosaicProfileProvider = MosaicProfileContext.Provider;
+
+export function useMosaicProfile(): MosaicProfile {
+  return useContext(MosaicProfileContext);
+}