Skip to content

Commit ae26567

Browse files
committed
docs(swingset): Add MosaicProvider docs page
1 parent 2cc1b38 commit ae26567

5 files changed

Lines changed: 97 additions & 2 deletions

File tree

‎packages/mosaic/src/hooks/use-mosaic-experimental.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@ import { createContext, useContext } from 'react';
33
export interface MosaicExperimental {
44
/**
55
* Opens Mosaic's own `UserProfile` and `OrganizationProfile` from `UserButton` and
6-
* `OrganizationSwitcher`, instead of Clerk's profile modals. They skip `appearance` and the link
7-
* entries of `customPages`.
6+
* `OrganizationSwitcher`, instead of Clerk's profile modals.
87
*
98
* @default false
109
*/

‎packages/swingset/src/components/DocsViewer.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
5353
'organization-profile-api-keys-panel': dynamic(() => import('../stories/organization-profile-api-keys-panel.mdx')),
5454
},
5555
misc: {
56+
'mosaic-provider': dynamic(() => import('../stories/mosaic-provider.mdx')),
5657
'organization-switcher': dynamic(() => import('../stories/organization-switcher.mdx')),
5758
'create-organization': dynamic(() => import('../stories/create-organization.mdx')),
5859
'organization-list': dynamic(() => import('../stories/organization-list.mdx')),

‎packages/swingset/src/lib/registry.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,7 @@ import {
162162
} from '../stories/localization.stories';
163163
import { Default as MenuComponentDefault, meta as menuComponentMeta } from '../stories/menu.component.stories';
164164
import { meta as menuMeta } from '../stories/menu.stories';
165+
import { meta as mosaicProviderMeta } from '../stories/mosaic-provider.stories';
165166
import {
166167
Default as OrganizationListDefault,
167168
Empty as OrganizationListEmpty,
@@ -1146,6 +1147,7 @@ export const registry: StoryModule[] = [
11461147
organizationProfileProfileSectionModule,
11471148
organizationProfileDangerSectionModule,
11481149
// Misc
1150+
{ meta: mosaicProviderMeta },
11491151
organizationSwitcherModule,
11501152
createOrganizationModule,
11511153
organizationListModule,
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# MosaicProvider
2+
3+
`MosaicProvider` holds the settings shared by the Mosaic components below it: reading direction, icons,
4+
localization, experimental features and the profile. It also renders the toasts and profile modals those
5+
components open.
6+
7+
## Usage
8+
9+
Wrap the part of your app that uses Mosaic. Every prop is optional.
10+
11+
```tsx
12+
import { MosaicProvider } from '@clerk/mosaic';
13+
14+
<MosaicProvider>
15+
<UserButton />
16+
</MosaicProvider>;
17+
```
18+
19+
## Props
20+
21+
| Prop | Type | Default | Description |
22+
| -------------- | --------------------- | ------- | ----------------------------------------------------------------------------- |
23+
| `children` | `ReactNode` | — | The components that use these settings. |
24+
| `direction` | `'ltr' \| 'rtl'` | `'ltr'` | The direction arrow-key navigation follows. Set it to match the page's `dir`. |
25+
| `icons` | `MosaicIconOverrides` | — | Glyph overrides by name. See [Icon](/components/icon). |
26+
| `localization` | `MosaicLocalization` | — | Locale and strings. See [Localization](/localization/localization). |
27+
| `experimental` | `MosaicExperimental` | — | Features still being tried out. Names and behavior can change in any release. |
28+
| `profile` | `MosaicProfile` | — | The profile shared by the profile components, described below. |
29+
30+
## Experimental
31+
32+
| Option | Type | Default | Description |
33+
| ------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
34+
| `newProfiles` | `boolean` | `false` | `UserButton` and `OrganizationSwitcher` open Mosaic's own `UserProfile` and `OrganizationProfile` instead of Clerk's modals. |
35+
36+
## Profile
37+
38+
`profile` configures the profile that `UserButton`, `OrganizationSwitcher`, `UserProfile` and
39+
`OrganizationProfile` share. `UserProfile` and `OrganizationProfile` use it for any prop they don't set
40+
themselves.
41+
42+
```tsx
43+
<MosaicProvider
44+
profile={{
45+
combined: true,
46+
userProfileUrl: '/account',
47+
userProfileProps: { customPages },
48+
organizationProfileProps: { pageOrder, afterLeaveOrganizationUrl: '/' },
49+
}}
50+
>
51+
<OrganizationSwitcher />
52+
<UserButton combined={false} />
53+
</MosaicProvider>
54+
```
55+
56+
`combined` on `MosaicProvider` decides what the profile shows, and `combined` on `UserButton` decides what
57+
its menu lists. [Profile permutations](/user-button/profile-permutations) shows each pairing.
58+
59+
| Option | Type | Default | Description |
60+
| -------------------------- | -------------------------- | ------- | --------------------------------------------------------------------------------- |
61+
| `combined` | `boolean` | `true` | Whether one profile carries the account's pages and the active organization's. |
62+
| `userProfileUrl` | `string` | — | Your own user profile page. Setting it routes there instead of opening the modal. |
63+
| `userProfileMode` | `'modal' \| 'navigation'` | — | How the user profile opens. Follows from whether `userProfileUrl` is set. |
64+
| `organizationProfileUrl` | `string` | — | Your own organization profile page. Setting it routes there instead of the modal. |
65+
| `organizationProfileMode` | `'modal' \| 'navigation'` | — | How the organization profile opens. Follows from `organizationProfileUrl`. |
66+
| `userProfileProps` | `ProfileUserProps` | — | Options for the user profile. |
67+
| `organizationProfileProps` | `ProfileOrganizationProps` | — | Options for the organization profile, or its pages in a combined profile. |
68+
69+
### `userProfileProps`
70+
71+
| Option | Type | Default | Description |
72+
| ----------------------- | ----------------------- | ------- | ------------------------------------------------------------ |
73+
| `customPages` | `CustomProfilePage[]` | — | Your own pages inside the profile. |
74+
| `pageOrder` | `string[]` | — | Navigation order, by built-in page id or custom page `path`. |
75+
| `additionalOAuthScopes` | `AdditionalOAuthScopes` | — | Extra access to request from each OAuth provider. |
76+
| `apiKeysProps` | `APIKeysPageProps` | — | Options for the API keys page. |
77+
78+
### `organizationProfileProps`
79+
80+
| Option | Type | Default | Description |
81+
| --------------------------- | --------------------- | ------- | ------------------------------------------------------------ |
82+
| `customPages` | `CustomProfilePage[]` | — | Your own pages inside the profile. |
83+
| `pageOrder` | `string[]` | — | Navigation order, by built-in page id or custom page `path`. |
84+
| `afterLeaveOrganizationUrl` | `string` | — | Where the user lands after leaving the organization. |
85+
| `apiKeysProps` | `APIKeysPageProps` | — | Options for the API keys page. |
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
import type { StoryMeta } from '@/lib/types';
2+
3+
export const meta: StoryMeta = {
4+
group: 'Misc',
5+
title: 'MosaicProvider',
6+
status: 'stable',
7+
source: 'packages/mosaic/src/mosaic-provider.tsx',
8+
};

0 commit comments

Comments
 (0)