feat(mosaic): add a fullscreen dialog variant for profiles

.changeset/mosaic-fullscreen-profile-refactor.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/mosaic-fullscreen-profile.md

@@ -0,0 +1,5 @@
+---
+'@clerk/mosaic': minor
+---
+
+Add a `fullscreen` Dialog variant that presents a profile across the whole viewport at every width, with a localizable "Back to app" button above the navigation in place of the corner close button. Profile navigation items are now 32px tall, matching the default button height, and use a neutral 6% hover and 8% selected background in every profile presentation.

packages/mosaic/src/components/dialog/__tests__/dialog.test.tsx

@@ -96,6 +96,17 @@ describe('Mosaic Dialog', () => {
     expect(document.querySelector('.cl-dialog-viewport')).toHaveAttribute('data-variant', 'profile');
   });
 
+  it('reflects the fullscreen variant as data-variant on the popup and the viewport', () => {
+    render(
+      <Dialog.Root defaultOpen>
+        <Dialog.Popup variant='fullscreen'>Body</Dialog.Popup>
+      </Dialog.Root>,
+    );
+
+    expect(document.querySelector('.cl-dialog-popup')).toHaveAttribute('data-variant', 'fullscreen');
+    expect(document.querySelector('.cl-dialog-viewport')).toHaveAttribute('data-variant', 'fullscreen');
+  });
+
   it('composes consumer xstyle onto the popup', () => {
     const caller = stylex.create({ popup: { marginTop: '8px' } });
     render(
@@ -251,6 +262,17 @@ describe('nested Mosaic Dialogs', () => {
     warn.mockRestore();
   });
 
+  it('warns when a fullscreen profile opens inside another dialog', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const user = userEvent.setup();
+    render(<Nested innerVariant='fullscreen' />);
+
+    await user.click(screen.getByRole('button', { name: 'Add email' }));
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('variant="fullscreen"'));
+    warn.mockRestore();
+  });
+
   // A card over a profile is the delete-account confirmation: a `Card` inside a `card` dialog.
   it('does not warn for a card over a profile, or for the profile itself', async () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
@@ -595,6 +617,14 @@ describe('compactPlacement', () => {
     warn.mockRestore();
   });
 
+  it('warns when a fullscreen profile is given a placement', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    renderPlacement('sheet', 'fullscreen');
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('variant="fullscreen"'));
+    warn.mockRestore();
+  });
+
   it('keeps a profile centered by default without warning', () => {
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
     renderPlacement(undefined, 'profile');

packages/mosaic/src/components/dialog/dialog.styles.ts

@@ -269,6 +269,8 @@ export const styles = stylex.create({
   },
 });
 
+const profileCloseInset = { insetBlockStart: space['3'], insetInlineEnd: space['3'] };
+
 /**
  * Positions the ICON the surface's inset from the corner, not the button box: the `sm` circle
  * carries `(space[7] - space[4]) / 2` = `space[1.5]` of its own padding around the glyph, so each
@@ -277,9 +279,27 @@ export const styles = stylex.create({
  */
 export const closeInsets = stylex.create({
   card: { insetBlockStart: space['2.5'], insetInlineEnd: space['2.5'] },
-  profile: { insetBlockStart: space['3'], insetInlineEnd: space['3'] },
+  profile: profileCloseInset,
+  fullscreen: profileCloseInset,
 });
 
+const profileViewport = {
+  // A definite container height is NOT enough on its own: an `auto` grid row still sizes to its
+  // content and happily exceeds the container, which is how a profile of rows measured 2208px
+  // inside a 1251px overlay. `minmax(0, 1fr)` pins the single row to the content box, so the row
+  // is what an item stretches to and what its overflow is measured against.
+  //
+  // Deliberately NOT applied to the scrolling variants: it would clamp the row there too, which is
+  // exactly what has to stop happening for the popup to grow past the fold.
+  gridTemplateRows: 'minmax(0, 1fr)',
+  // A DEFINITE height, taken from the overlay (`position: fixed; inset: 0`), which makes the
+  // single grid row definite too. That is what lets `variants.profile` fill the content box with
+  // `align-self: stretch` alone — no `dvh` arithmetic, so nothing can disagree with the box a
+  // bottom-anchored sheet aligns to. They genuinely do diverge: on an emulated iPhone the
+  // overlay measures 1251px while `100dvh` reports 844.
+  height: '100%',
+};
+
 /**
  * Named for what the surface IS rather than for a t-shirt step, because these are different
  * surfaces rather than one surface at two scales — the names stay honest if they later diverge
@@ -314,22 +334,8 @@ export const closeInsets = stylex.create({
  */
 export const viewportVariants = stylex.create({
   card: { minHeight: '100%' },
-  profile: {
-    // A definite container height is NOT enough on its own: an `auto` grid row still sizes to its
-    // content and happily exceeds the container, which is how a profile of rows measured 2208px
-    // inside a 1251px overlay. `minmax(0, 1fr)` pins the single row to the content box, so the row
-    // is what an item stretches to and what its overflow is measured against.
-    //
-    // Deliberately NOT applied to the scrolling variants: it would clamp the row there too, which is
-    // exactly what has to stop happening for the popup to grow past the fold.
-    gridTemplateRows: 'minmax(0, 1fr)',
-    // A DEFINITE height, taken from the overlay (`position: fixed; inset: 0`), which makes the
-    // single grid row definite too. That is what lets `variants.profile` fill the content box with
-    // `align-self: stretch` alone — no `dvh` arithmetic, so nothing can disagree with the box a
-    // bottom-anchored sheet aligns to. They genuinely do diverge: on an emulated iPhone the
-    // overlay measures 1251px while `100dvh` reports 844.
-    height: '100%',
-  },
+  profile: profileViewport,
+  fullscreen: profileViewport,
 });
 
 /** Pins the box for a sheet, so `compactPlacements.sheet` can cap the popup at the overlay's own height. */
@@ -359,8 +365,35 @@ export const trackVariants = stylex.create({
     // Same definite row as the viewport's, one level down, so the popup's `stretch` lands on it.
     gridTemplateRows: 'minmax(0, 1fr)',
   },
+  fullscreen: {
+    '--_cl-dialog-inset': '0px',
+    paddingInline: 0,
+    gridTemplateRows: 'minmax(0, 1fr)',
+  },
 });
 
+const profileSurface = {
+  borderColor: null,
+  borderRadius: null,
+  borderStyle: null,
+  borderWidth: null,
+  // The profile does NOT scroll itself, and that is the whole design. A fixed-height surface
+  // needs somewhere for overflow to go, but putting the scroll on the POPUP takes everything
+  // anchored to it along for the ride — the close button most obviously. So the popup clips,
+  // and the scroll region is the surface's own: `Profile` scrolls its content column.
+  // Deliberately a flex column with no `align-items` override, so the surface inside grows to
+  // the popup's height.
+  //
+  // `clip` rather than `hidden` for the same reason as the viewport: `hidden` would make the
+  // profile a scroll container, and focusing anything inside it that sits outside its box would
+  // scroll the profile itself.
+  overflow: 'clip',
+  // Fills the viewport's content box rather than computing a height from `dvh`. The grid row
+  // is definite (see `styles.viewport`), so `stretch` lands the profile's edges on exactly the
+  // lines a bottom-anchored sheet reaches with `align-self: end`, and clamps to them.
+  alignSelf: 'stretch',
+};
+
 export const variants = stylex.create({
   // The surface is a `Card` — so it comes from `Card`'s own `elevations.overlay`, and the popup
   // contributes geometry and motion. Compose it by rendering the card INSIDE the popup:
@@ -397,27 +430,8 @@ export const variants = stylex.create({
    *
    * Consequence worth knowing: `variant="profile"` with no surface inside renders an unpainted box.
    */
-  profile: {
-    borderColor: null,
-    borderRadius: null,
-    borderStyle: null,
-    borderWidth: null,
-    // The profile does NOT scroll itself, and that is the whole design. A fixed-height surface
-    // needs somewhere for overflow to go, but putting the scroll on the POPUP takes everything
-    // anchored to it along for the ride — the close button most obviously. So the popup clips,
-    // and the scroll region is the surface's own: `Profile` scrolls its content column.
-    // Deliberately a flex column with no `align-items` override, so the surface inside grows to
-    // the popup's height.
-    //
-    // `clip` rather than `hidden` for the same reason as the viewport: `hidden` would make the
-    // profile a scroll container, and focusing anything inside it that sits outside its box would
-    // scroll the profile itself.
-    overflow: 'clip',
-    // Fills the viewport's content box rather than computing a height from `dvh`. The grid row
-    // is definite (see `styles.viewport`), so `stretch` lands the profile's edges on exactly the
-    // lines a bottom-anchored sheet reaches with `align-self: end`, and clamps to them.
-    alignSelf: 'stretch',
-  },
+  profile: profileSurface,
+  fullscreen: profileSurface,
 });
 
 /**
@@ -500,6 +514,20 @@ export const trackCompactPlacements = stylex.create({
   },
 });
 
+const profileBackdropMotion = {
+  opacity: {
+    default: 1,
+    ':where([data-ending-style])': 0,
+    ':where([data-starting-style])': SCRIM_ENTER_OPACITY,
+  },
+  transitionDuration: {
+    default: durationVars['--cl-duration-fast'],
+    ':where([data-ending-style])': durationVars['--cl-duration-fast'],
+  },
+  transitionProperty: 'opacity',
+  transitionTimingFunction: 'linear',
+};
+
 /**
  * Enter/exit motion, keyed by size, because the two surfaces want opposite things.
  *
@@ -544,19 +572,8 @@ export const backdropMotion = stylex.create({
   },
 
   /** Identical to `card` — the popup it accompanies fades on the same clock, it just does not scale. */
-  profile: {
-    opacity: {
-      default: 1,
-      ':where([data-ending-style])': 0,
-      ':where([data-starting-style])': SCRIM_ENTER_OPACITY,
-    },
-    transitionDuration: {
-      default: durationVars['--cl-duration-fast'],
-      ':where([data-ending-style])': durationVars['--cl-duration-fast'],
-    },
-    transitionProperty: 'opacity',
-    transitionTimingFunction: 'linear',
-  },
+  profile: profileBackdropMotion,
+  fullscreen: profileBackdropMotion,
 });
 
 // The plain CSS `ease-out` — `cubic-bezier(0, 0, 0.58, 1)` — used ONLY for the sheet's slide out.
@@ -597,6 +614,22 @@ const ENTER_SCALE = 0.94;
 const STACK_SCALE = 0.96;
 const STACK_LIFT = '-0.5rem';
 
+const profilePopupMotion = {
+  opacity: {
+    default: 1,
+    ':where([data-starting-style], [data-ending-style])': 0,
+  },
+  transitionDuration: {
+    default: durationVars['--cl-duration-fast'],
+    ':where([data-ending-style])': durationVars['--cl-duration-fast'],
+  },
+  transitionProperty: 'opacity',
+  transitionTimingFunction: {
+    default: easingVars['--cl-ease-enter'],
+    ':where([data-ending-style])': easingVars['--cl-ease-exit'],
+  },
+};
+
 export const popupMotion = stylex.create({
   /**
    * `compactPlacement='sheet'`: a card that scales from its center above the compact band, and slides up
@@ -770,19 +803,6 @@ export const popupMotion = stylex.create({
    * No reduced-motion branch, matching `card` — under `reduce` the two shed their transform and
    * are left with exactly this, so there is nothing here to drop.
    */
-  profile: {
-    opacity: {
-      default: 1,
-      ':where([data-starting-style], [data-ending-style])': 0,
-    },
-    transitionDuration: {
-      default: durationVars['--cl-duration-fast'],
-      ':where([data-ending-style])': durationVars['--cl-duration-fast'],
-    },
-    transitionProperty: 'opacity',
-    transitionTimingFunction: {
-      default: easingVars['--cl-ease-enter'],
-      ':where([data-ending-style])': easingVars['--cl-ease-exit'],
-    },
-  },
+  profile: profilePopupMotion,
+  fullscreen: profilePopupMotion,
 });

packages/mosaic/src/components/dialog/dialog.tsx

@@ -33,12 +33,16 @@ import { guardKeyboardTouch } from './keyboard-touch';
 
 /**
  * Which surface the dialog holds, and so the geometry it is given: `card` is a `Card` at the
- * card's width, `profile` a `Profile` filling the height. Not a `size`, because these are
- * different surfaces rather than one surface at two widths — a second card width would be a size
- * of the `card` variant.
+ * card's width, `profile` a `Profile` filling the height, `fullscreen` a `Profile` filling the
+ * viewport. Not a `size`, because these are different surfaces rather than one surface at two
+ * widths — a second card width would be a size of the `card` variant.
  */
 export type DialogVariant = keyof typeof variants;
 
+function holdsProfile(variant: DialogVariant): boolean {
+  return variant !== 'card';
+}
+
 /**
  * Where the surface sits in the compact band — a window under `40rem`. `center`
  * everywhere above it: there is no edge close enough for anchoring to mean anything at those
@@ -317,11 +321,11 @@ function Viewport({
  */
 function useNestedVariantWarning(isNestedInDialog: boolean, variant: DialogVariant) {
   React.useEffect(() => {
-    if (process.env.NODE_ENV === 'production' || !isNestedInDialog || variant !== 'profile') {
+    if (process.env.NODE_ENV === 'production' || !isNestedInDialog || !holdsProfile(variant)) {
       return;
     }
     console.warn(
-      '[Clerk] a variant="profile" Dialog opened inside another Dialog. A profile is a root-level surface that hosts what opens over it; open a card instead.',
+      `[Clerk] a variant="${variant}" Dialog opened inside another Dialog. A profile is a root-level surface that hosts what opens over it; open a card instead.`,
     );
   }, [isNestedInDialog, variant]);
 }
@@ -336,14 +340,14 @@ function useCompactPlacementWarning(variant: DialogVariant, placement: DialogCom
   React.useEffect(() => {
     if (
       process.env.NODE_ENV === 'production' ||
-      variant !== 'profile' ||
+      !holdsProfile(variant) ||
       placement === undefined ||
       placement === 'center'
     ) {
       return;
     }
     console.warn(
-      `[Clerk] <Dialog.Popup variant="profile" compactPlacement="${placement}"> — a profile fills the compact band and takes no placement. It was ignored.`,
+      `[Clerk] <Dialog.Popup variant="${variant}" compactPlacement="${placement}"> — a profile fills the compact band and takes no placement. It was ignored.`,
     );
   }, [variant, placement]);
 }
@@ -364,7 +368,7 @@ const Popup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function Dialog
   const { role, isStacked: isNestedInDialog, labelId, descriptionId } = useHeadlessDialogContext();
   const isAlert = role === 'alertdialog';
   // A profile has its own compact-band treatment and takes no placement; the warning says so.
-  const compactPlacement: DialogCompactPlacement = variant === 'profile' ? 'center' : (compactPlacementProp ?? 'sheet');
+  const compactPlacement: DialogCompactPlacement = holdsProfile(variant) ? 'center' : (compactPlacementProp ?? 'sheet');
   useCompactPlacementWarning(variant, compactPlacementProp);
   useNestedVariantWarning(isNestedInDialog, variant);
 
@@ -375,7 +379,7 @@ const Popup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function Dialog
   // Observed through state rather than a plain ref, because the warnings have to re-run when the
   // node arrives and a ref mutation does not re-render.
   const [node, setNode] = React.useState<HTMLDivElement | null>(null);
-  useAccessibleNameWarning(node, 'Dialog', variant === 'profile' ? 'Profile.Title' : 'Card.Title');
+  useAccessibleNameWarning(node, 'Dialog', holdsProfile(variant) ? 'Profile.Title' : 'Card.Title');
   // A name alone is enough for an ordinary dialog; an alert is announced as an interruption and
   // its description is what says which decision is being asked for.
   useAccessibleDescriptionWarning(isAlert ? node : null, 'Dialog', 'Card.Description');
@@ -437,7 +441,7 @@ const Popup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function Dialog
   );
 
   return (
-    <Primitive.Portal>{variant === 'profile' ? <ToastProvider>{viewport}</ToastProvider> : viewport}</Primitive.Portal>
+    <Primitive.Portal>{holdsProfile(variant) ? <ToastProvider>{viewport}</ToastProvider> : viewport}</Primitive.Portal>
   );
 });
 

packages/mosaic/src/components/profile/profile.context.ts

@@ -2,6 +2,8 @@ import React from 'react';
 
 export type ProfileNavLayout = 'column' | 'select' | 'sheet';
 
+export type ProfileDismiss = 'back' | 'corner' | 'none';
+
 export interface ProfileContextValue {
   titleId: string;
   renderBranding: boolean;
@@ -18,6 +20,7 @@ export interface ProfileContextValue {
   pageTitleRef: React.MutableRefObject<HTMLHeadingElement | null>;
   navTriggerRef: React.MutableRefObject<HTMLButtonElement | null>;
   inline: boolean;
+  dismiss: ProfileDismiss;
 }
 
 export const ProfileContext = React.createContext<ProfileContextValue | null>(null);

packages/mosaic/src/components/profile/profile.messages.ts

@@ -0,0 +1,3 @@
+export const profileMessages = {
+  backToApp: 'Back to app',
+} as const;