feat(mosaic): follow DirectionProvider for arrow-key navigation (#10420)

Author: alexcarpenter

.changeset/mosaic-direction-provider.md

@@ -0,0 +1,5 @@
+---
+'@clerk/mosaic': patch
+---
+
+Add a `direction` prop to `MosaicProvider` (`'ltr' | 'rtl'`, default `'ltr'`). Arrow-key navigation in tabs, segmented controls, one-time code inputs, tag inputs, and nested menus now follows this prop instead of the nearest `dir` attribute. Pages that render right-to-left should pass `direction="rtl"`.

packages/mosaic/ARCHITECTURE.md

@@ -74,7 +74,7 @@ State styling uses real class + attribute-selector specificity — no `&&` boost
 
 ## MosaicProvider
 
-Mosaic components need no provider to render or to be styled — the stylesheet and the `--cl-*` tokens do that work. `MosaicProvider` exists for three things: per-name icon glyph overrides, localization, and the toast region (it mounts `ToastProvider`).
+Mosaic components need no provider to render or to be styled — the stylesheet and the `--cl-*` tokens do that work. `MosaicProvider` exists for four things: per-name icon glyph overrides, localization, the reading direction keyboard navigation follows (it mounts `DirectionProvider`), and the toast region (it mounts `ToastProvider`).
 
 ```tsx
 import { MosaicProvider } from './mosaic-provider';

packages/mosaic/docs/headless.md

@@ -133,6 +133,14 @@ Any new part with an exit transition needs one of the two;
 animated element). Add `cssVars()` to floating-ui middleware **after** `arrow()`,
 or the transform origin won't follow the arrow.
 
+## Reading direction
+
+Read the direction with `useDirection()` from `primitives/direction-provider`, never from the DOM
+`dir` attribute or computed style. It returns `ltr` outside a `DirectionProvider`. Use
+`readingDirectionKeys(direction)` for the previous and next arrow keys, or pass
+`rtl: direction === 'rtl'` to floating-ui's `Composite` or `useListNavigation`
+(`tabs/tabs-list.tsx`). `MosaicProvider` renders the `DirectionProvider` from its `direction` prop.
+
 ## Testing
 
 Primitive tests run on **happy-dom** (the `primitives` project in Mosaic's

packages/mosaic/src/__tests__/mosaic-provider.test.tsx

@@ -6,6 +6,7 @@ import type { MosaicIconOverrides } from '../icons/overrides';
 import { useMosaicIcons } from '../icons/overrides';
 import { useLocale, useMessages } from '../localization';
 import { MosaicProvider } from '../mosaic-provider';
+import { useDirection } from '../primitives/direction-provider';
 
 describe('MosaicProvider icons', () => {
   it('exposes the icon overrides via useMosaicIcons', () => {
@@ -49,3 +50,19 @@ describe('MosaicProvider localization', () => {
     expect(result.current).toBe('de');
   });
 });
+
+describe('MosaicProvider direction', () => {
+  it('passes the direction prop to useDirection', () => {
+    const { result } = renderHook(() => useDirection(), {
+      wrapper: ({ children }) => React.createElement(MosaicProvider, { direction: 'rtl' }, children),
+    });
+    expect(result.current).toBe('rtl');
+  });
+
+  it('defaults to ltr', () => {
+    const { result } = renderHook(() => useDirection(), {
+      wrapper: ({ children }) => React.createElement(MosaicProvider, {}, children),
+    });
+    expect(result.current).toBe('ltr');
+  });
+});

packages/mosaic/src/components/segmented-control/segmented-control.test.tsx

@@ -3,6 +3,7 @@ import userEvent from '@testing-library/user-event';
 import React from 'react';
 import { describe, expect, it, vi } from 'vitest';
 
+import { DirectionProvider } from '../../primitives/direction-provider';
 import { SegmentedControl } from './segmented-control';
 
 function BillingPeriod(props: Partial<React.ComponentProps<typeof SegmentedControl.Root>>) {
@@ -58,9 +59,9 @@ describe('Mosaic SegmentedControl', () => {
 
   it('flips the arrow keys in a right-to-left layout', async () => {
     render(
-      <div dir='rtl'>
+      <DirectionProvider direction='rtl'>
         <BillingPeriod defaultValue='monthly' />
-      </div>,
+      </DirectionProvider>,
     );
 
     await userEvent.tab();

packages/mosaic/src/mosaic-provider.tsx

@@ -8,9 +8,13 @@ import type { MosaicLocalization } from './localization';
 import { MosaicLocalizationProvider, resolveLocalization } from './localization';
 import type { ModalSurfaces } from './modals/modal.types';
 import { ModalHost } from './modals/modal-host';
+import type { TextDirection } from './primitives/direction-provider';
+import { DirectionProvider } from './primitives/direction-provider';
 
 export interface MosaicProviderProps {
   children: React.ReactNode;
+  /** Reading direction that arrow-key navigation follows. Set it to match the page's `dir`. Defaults to `ltr`. */
+  direction?: TextDirection;
   /** Per-name icon glyph overrides, applied to every `<Icon>` below this provider. */
   icons?: MosaicIconOverrides;
   /** Locale and strings for everything Mosaic renders; see `MosaicLocalization`. */
@@ -20,21 +24,23 @@ export interface MosaicProviderProps {
 // Exported Mosaic components annotate a React return type on purpose. The package sets
 // `jsxImportSource: '@emotion/react'`, so an inferred return leaks Emotion's `JSX.Element` into the
 // published `.d.ts`, which React 19 consumers reject as a JSX element type.
-export function MosaicProvider({ children, icons, localization }: MosaicProviderProps): React.ReactElement {
+export function MosaicProvider({ children, direction, icons, localization }: MosaicProviderProps): React.ReactElement {
   const iconsValue = React.useMemo(() => icons ?? {}, [icons]);
   const localizationValue = React.useMemo(() => resolveLocalization(localization), [localization]);
   const [now] = React.useState(() => new Date());
 
   return (
-    <MosaicIconsProvider value={iconsValue}>
-      <MosaicLocalizationProvider value={localizationValue}>
-        <MosaicNowProvider value={now}>
-          <ToastProvider>
-            <ModalHost surfaces={modalSurfaces}>{children}</ModalHost>
-          </ToastProvider>
-        </MosaicNowProvider>
-      </MosaicLocalizationProvider>
-    </MosaicIconsProvider>
+    <DirectionProvider direction={direction}>
+      <MosaicIconsProvider value={iconsValue}>
+        <MosaicLocalizationProvider value={localizationValue}>
+          <MosaicNowProvider value={now}>
+            <ToastProvider>
+              <ModalHost surfaces={modalSurfaces}>{children}</ModalHost>
+            </ToastProvider>
+          </MosaicNowProvider>
+        </MosaicLocalizationProvider>
+      </MosaicIconsProvider>
+    </DirectionProvider>
   );
 }
 

packages/mosaic/src/primitives/direction-provider/direction-provider.test.tsx

@@ -0,0 +1,37 @@
+import { renderHook } from '@testing-library/react';
+import React from 'react';
+import { describe, expect, it } from 'vitest';
+
+import { DirectionProvider, useDirection } from './index';
+
+describe('DirectionProvider', () => {
+  it('defaults to ltr without a provider', () => {
+    const { result } = renderHook(() => useDirection());
+    expect(result.current).toBe('ltr');
+  });
+
+  it('defaults to ltr when no direction is given', () => {
+    const { result } = renderHook(() => useDirection(), {
+      wrapper: ({ children }) => <DirectionProvider>{children}</DirectionProvider>,
+    });
+    expect(result.current).toBe('ltr');
+  });
+
+  it('provides the direction to descendants', () => {
+    const { result } = renderHook(() => useDirection(), {
+      wrapper: ({ children }) => <DirectionProvider direction='rtl'>{children}</DirectionProvider>,
+    });
+    expect(result.current).toBe('rtl');
+  });
+
+  it('lets a nested provider override an outer one', () => {
+    const { result } = renderHook(() => useDirection(), {
+      wrapper: ({ children }) => (
+        <DirectionProvider direction='rtl'>
+          <DirectionProvider direction='ltr'>{children}</DirectionProvider>
+        </DirectionProvider>
+      ),
+    });
+    expect(result.current).toBe('ltr');
+  });
+});

packages/mosaic/src/primitives/direction-provider/direction-provider.tsx

@@ -0,0 +1,29 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import React from 'react';
+
+export type TextDirection = 'ltr' | 'rtl';
+
+export interface DirectionProviderProps {
+  /** The reading direction that keyboard navigation follows below this provider. Defaults to `ltr`. */
+  direction?: TextDirection;
+  children: ReactNode;
+}
+
+const DirectionContext = React.createContext<TextDirection | undefined>(undefined);
+
+export function DirectionProvider({ direction = 'ltr', children }: DirectionProviderProps): React.ReactElement {
+  return <DirectionContext.Provider value={direction}>{children}</DirectionContext.Provider>;
+}
+
+export function useDirection(): TextDirection {
+  return React.useContext(DirectionContext) ?? 'ltr';
+}
+
+export function readingDirectionKeys(direction: TextDirection) {
+  return {
+    previousKey: direction === 'rtl' ? 'ArrowRight' : 'ArrowLeft',
+    nextKey: direction === 'rtl' ? 'ArrowLeft' : 'ArrowRight',
+  };
+}

packages/mosaic/src/primitives/direction-provider/index.ts

@@ -0,0 +1,2 @@
+export { DirectionProvider, readingDirectionKeys, useDirection } from './direction-provider';
+export type { DirectionProviderProps, TextDirection } from './direction-provider';

packages/mosaic/src/primitives/menu/menu-root.tsx

@@ -25,6 +25,7 @@ import {
 } from '@floating-ui/react';
 import { type ReactNode, useContext, useEffect, useMemo, useRef, useState } from 'react';
 
+import { useDirection } from '../direction-provider';
 import { useControllableState } from '../hooks/use-controllable-state';
 import { useReturnFocus } from '../hooks/use-return-focus';
 import { useTransition } from '../hooks/use-transition';
@@ -71,6 +72,7 @@ function MenuInner(props: MenuProps) {
   // has a parent node id too, and treating that as nesting makes it hover-open, side-placed, and
   // unclickable by mouse.
   const isNested = parentId != null && parentContext != null;
+  const direction = useDirection();
 
   const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -179,6 +181,7 @@ function MenuInner(props: MenuProps) {
     listRef: elementsRef,
     activeIndex,
     nested: isNested,
+    rtl: direction === 'rtl',
     onNavigate: setActiveIndex,
   });
   const typeahead = useTypeahead(floatingContext, {