feat(mosaic): support badges in profile navigation

.changeset/mosaic-badge-context-defaults.md

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

.changeset/mosaic-profile-nav-badge.md

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

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

@@ -0,0 +1,7 @@
+'use client';
+
+import React from 'react';
+
+import type { BadgeProps } from './badge';
+
+export const BadgeContext = React.createContext<Pick<BadgeProps, 'color'>>({});

packages/mosaic/src/components/badge/badge.test.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 import { describe, expect, it } from 'vitest';
 
 import { Badge } from './badge';
+import { BadgeContext } from './badge.context';
 
 const atoms = stylex.create({
   spaced: { marginTop: '8px' },
@@ -27,6 +28,24 @@ describe('Mosaic Badge', () => {
     expect(screen.getByText('Active')).toHaveAttribute('data-color', color);
   });
 
+  it('takes its color from BadgeContext when none is passed', () => {
+    render(
+      <BadgeContext.Provider value={{ color: 'neutral' }}>
+        <Badge>Active</Badge>
+      </BadgeContext.Provider>,
+    );
+    expect(screen.getByText('Active')).toHaveAttribute('data-color', 'neutral');
+  });
+
+  it('lets an explicit color override the BadgeContext default', () => {
+    render(
+      <BadgeContext.Provider value={{ color: 'neutral' }}>
+        <Badge color='positive'>Active</Badge>
+      </BadgeContext.Provider>,
+    );
+    expect(screen.getByText('Active')).toHaveAttribute('data-color', 'positive');
+  });
+
   it('merges xstyle atoms after the slot atoms', () => {
     render(<Badge xstyle={atoms.spaced}>Active</Badge>);
     const badge = screen.getByText('Active');

packages/mosaic/src/components/badge/badge.tsx

@@ -5,6 +5,7 @@ import { useRender } from '../../primitives/utils';
 import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { reset } from '../../utils/reset.styles';
+import { BadgeContext } from './badge.context';
 import { colors, styles } from './badge.styles';
 
 export type BadgeProps = MosaicComponentProps<'span'> & {
@@ -30,9 +31,11 @@ export type BadgeProps = MosaicComponentProps<'span'> & {
  * <Badge render={<a href='/billing' />}>Upgrade</Badge>
  */
 export const Badge = React.forwardRef<HTMLSpanElement, BadgeProps>(function MosaicBadge(
-  { color = 'primary', render, xstyle, ...rest },
+  { color: colorProp, render, xstyle, ...rest },
   ref,
 ) {
+  const defaults = React.useContext(BadgeContext);
+  const color = colorProp ?? defaults.color ?? 'primary';
   return useRender({
     defaultTagName: 'span',
     render,

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

@@ -263,6 +263,13 @@ export const styles = stylex.create({
     flexShrink: 0,
   },
 
+  navItemBadge: {
+    alignItems: 'center',
+    display: 'inline-flex',
+    flexShrink: 0,
+    marginInlineStart: 'auto',
+  },
+
   branding: {
     display: 'block',
     marginBlockStart: 'auto',

packages/mosaic/src/components/profile/profile.test.tsx

@@ -5,6 +5,7 @@ import React from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { MosaicProvider } from '../../MosaicProvider';
+import { Badge } from '../badge';
 import { Card } from '../card';
 import { Dialog } from '../dialog';
 import { Icon } from '../icon';
@@ -54,6 +55,56 @@ function atomsOf(style: stylex.StyleXStyles): string[] {
 }
 
 describe('Profile', () => {
+  it('renders trailing badge content in a navigation item', () => {
+    render(
+      <Profile.Root value='account'>
+        <Profile.Title>Settings</Profile.Title>
+        <Profile.Nav>
+          <Profile.NavItem
+            value='account'
+            badge={<Badge>3</Badge>}
+          >
+            Account
+          </Profile.NavItem>
+        </Profile.Nav>
+        <Profile.Content>
+          <Profile.ContentPanel value='account'>Account content</Profile.ContentPanel>
+        </Profile.Content>
+      </Profile.Root>,
+    );
+
+    expect(screen.getByText('3').closest('.cl-profile-nav-item-badge')).toBeInTheDocument();
+  });
+
+  it('defaults a navigation item badge to the neutral color', () => {
+    render(
+      <Profile.Root value='account'>
+        <Profile.Title>Settings</Profile.Title>
+        <Profile.Nav>
+          <Profile.NavItem
+            value='account'
+            badge={<Badge>3</Badge>}
+          >
+            Account
+          </Profile.NavItem>
+          <Profile.NavItem
+            value='security'
+            badge={<Badge color='warning'>1</Badge>}
+          >
+            Security
+          </Profile.NavItem>
+        </Profile.Nav>
+        <Profile.Content>
+          <Profile.ContentPanel value='account'>Account content</Profile.ContentPanel>
+          <Profile.ContentPanel value='security'>Security content</Profile.ContentPanel>
+        </Profile.Content>
+      </Profile.Root>,
+    );
+
+    expect(screen.getByText('3')).toHaveAttribute('data-color', 'neutral');
+    expect(screen.getByText('1')).toHaveAttribute('data-color', 'warning');
+  });
+
   it('is a labelled navigation of tabs beside the selected page', () => {
     renderSurface();
 

packages/mosaic/src/components/profile/profile.tsx

@@ -9,6 +9,7 @@ import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { focusOutline } from '../../utils/focus-outline.styles';
 import { reset } from '../../utils/reset.styles';
+import { BadgeContext } from '../badge/badge.context';
 import { Branding } from '../branding';
 import { Dialog, DialogContext, isInDialog } from '../dialog';
 import { Drawer } from '../drawer';
@@ -318,12 +319,15 @@ export interface ProfileNavItemProps extends MosaicComponentProps<'button'> {
   value: string;
   /** Leads the label. Any node, so a page of the consumer's own can bring its own mark. */
   icon?: React.ReactNode;
+  badge?: React.ReactNode;
   disabled?: boolean;
 }
 
+const navItemBadgeDefaults = { color: 'neutral' } as const;
+
 /** A destination. Selecting it shows the `Profile.ContentPanel` sharing its `value`. */
 const NavItem = React.forwardRef<HTMLButtonElement, ProfileNavItemProps>(function ProfileNavItem(
-  { value, icon, disabled, children, render, xstyle, onClick, ...rest },
+  { value, icon, badge, disabled, children, render, xstyle, onClick, ...rest },
   ref,
 ) {
   const { compact, closeNav } = useProfileContext('Profile.NavItem');
@@ -355,6 +359,11 @@ const NavItem = React.forwardRef<HTMLButtonElement, ProfileNavItemProps>(functio
         </span>
       ) : null}
       <span {...themeProps('profile-nav-item-label')}>{children}</span>
+      {badge != null ? (
+        <span {...mergeStyleProps(themeProps('profile-nav-item-badge'), stylex.props(reset.base, styles.navItemBadge))}>
+          <BadgeContext.Provider value={navItemBadgeDefaults}>{badge}</BadgeContext.Provider>
+        </span>
+      ) : null}
     </Tabs.Tab>
   );
 });

packages/swingset/src/stories/profile.component.mdx

@@ -21,6 +21,7 @@ its dismiss, and fills the popup; standalone it paints the same frame and takes
 ## Usage
 
 ```tsx
+import { Badge } from '@clerk/mosaic/components/badge';
 import { Icon } from '@clerk/mosaic/components/icon';
 import { Profile } from '@clerk/mosaic/components/profile';
 
@@ -39,6 +40,7 @@ import { Profile } from '@clerk/mosaic/components/profile';
     <Profile.NavItem
       value='security'
       icon={<Icon name='shield-check' size='sm' />}
+      badge={<Badge>2</Badge>}
     >
       Security
     </Profile.NavItem>
@@ -54,8 +56,8 @@ import { Profile } from '@clerk/mosaic/components/profile';
 `elevation` picks how it sits, the way `Card`'s does: `card` (default) is framed, with a fixed
 height and the pages scrolling inside; `flush` is the page's own content — no frame, the page
 scrolls, the columns a gap apart, held to a reading width and centred. A
-`NavItem` and a `Page` pair by `value`. `icon` takes any node, so a page of the consumer's own can
-bring its own mark. `Title` is a visually hidden heading: it names the navigation, the compact
+`NavItem` and a `Page` pair by `value`. `icon` and `badge` take nodes, so a page can supply its own
+leading mark and trailing status. A `Badge` passed to `badge` is `neutral` unless it sets its own `color`. `Title` is a visually hidden heading: it names the navigation, the compact
 sheet, and — inside a dialog — the dialog itself, the way `Card.Title` does.
 
 ## Parts

packages/swingset/src/stories/profile.component.stories.tsx

@@ -1,3 +1,4 @@
+import { Badge } from '@clerk/mosaic/components/badge';
 import { Button } from '@clerk/mosaic/components/button';
 import { Icon } from '@clerk/mosaic/components/icon';
 import type { ProfileRootProps } from '@clerk/mosaic/components/profile';
@@ -169,6 +170,7 @@ function Surface({
                 size='sm'
               />
             }
+            badge={item.id === 'security' ? <Badge>2</Badge> : undefined}
           >
             {item.label}
           </Profile.NavItem>