Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

refactor(core): mirror Pagination chevrons under RTL via CSS, not JS direction read (#4687)

nynexman4464e0de50fe1650
diff --git a/.changeset/pagination-css-mirror-chevrons.md b/.changeset/pagination-css-mirror-chevrons.md
new file mode 100644
index 0000000000..06124f4f91
--- /dev/null
+++ b/.changeset/pagination-css-mirror-chevrons.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Pagination: mirror the prev/next chevrons under RTL with CSS (the shared `scaleX(-1)` mirror) instead of reading the ambient direction in JS. The controls now flip purely from an ancestor's `dir`, matching Calendar and the rest of the library — so they render correctly on the server with no hydration flash. No API change; `aria-label`s are unchanged.
+@nynexman4464
diff --git a/packages/cli/assets/docs/internationalization.doc.mjs b/packages/cli/assets/docs/internationalization.doc.mjs
index 3c7f2bb041..304812d283 100644
--- a/packages/cli/assets/docs/internationalization.doc.mjs
+++ b/packages/cli/assets/docs/internationalization.doc.mjs
@@ -93,6 +93,10 @@ import fr from '@astryxdesign/core/locales/fr.json';
type: 'prose',
text: "Astryx tracks text direction (`'ltr'` or `'rtl'`) alongside the locale. By default the direction is derived from the `locale` you pass to `<InternationalizationProvider>` via [`Intl.Locale.getTextInfo()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getTextInfo), so RTL locales such as Arabic (`ar`), Hebrew (`he`), Farsi (`fa`), and Urdu (`ur`) resolve to `'rtl'` automatically.",
},
+ {
+ type: 'prose',
+ text: "You don't wire anything per component. Once the direction is set, astryx components mirror on their own: layout and spacing flip via CSS logical properties, directional icons (chevrons, carets) flip in place, keyboard arrow keys swap left/right, and overlays position on the correct side. Set the direction once and the whole component tree follows.",
+ },
{
type: 'code',
lang: 'tsx',
@@ -146,7 +150,7 @@ export default function RootLayout({children, params}) {
},
{
type: 'prose',
- text: 'To make just one part of a left-to-right page right-to-left; say an Arabic quote or a comment thread; wrap that part in its own `<InternationalizationProvider dir="rtl">` and add `dir="rtl"` to the element around it. (One current limitation: pop-up overlays like menus and dialogs opened from inside that region aren\'t mirrored yet; that\'s coming in later RTL work.)',
+ text: 'To make just one part of a left-to-right page right-to-left; say an Arabic quote or a comment thread; wrap that part in its own `<InternationalizationProvider dir="rtl">` and add `dir="rtl"` to the element around it. Pop-up overlays; menus, dialogs, popovers, tooltips; opened from inside that region mirror too: they position with logical CSS anchor placement, so they land on the correct side and inherit the region\'s direction automatically.',
},
],
},
@@ -341,20 +345,60 @@ function SaveButton() {
},
{
type: 'prose',
- text: "Component authors read the ambient text direction with `useDirection()`. Reach for it only when CSS logical properties can't express the mirroring; swapping a directional icon, mirroring behavioral logic (slider math, keyboard nav), or direction-specific geometry. It returns `'ltr'` when called outside a provider, matching the silent-fallback behavior of `useTranslator`.",
+ text: "When you author a component that needs to respond to direction, resolve it from the DOM, not from a render-time JavaScript read, and reach for the lightest tool that works. In priority order:",
+ },
+ {
+ type: 'heading',
+ level: 4,
+ text: '1. CSS logical properties first',
+ },
+ {
+ type: 'prose',
+ text: "Use `insetInlineStart`, `paddingInlineEnd`, `marginInline`, and friends instead of physical `left`/`right`. Most mirroring needs nothing more; the browser flips it from the ambient `dir`. The `@astryx/no-physical-properties` ESLint rule enforces this.",
+ },
+ {
+ type: 'heading',
+ level: 4,
+ text: '2. Directional icons — mirror with CSS, not a name-swap',
+ },
+ {
+ type: 'prose',
+ text: "Render one fixed glyph and wrap it in the shared `rtlStyles.mirror` (a `scaleX(-1)` that only applies under `[dir=\"rtl\"]`). It flips from the ancestor `dir` through the cascade, so it works on the server with no hydration flash. Do not pick `chevronLeft` vs `chevronRight` in JS. This is how Pagination, Calendar, and Carousel handle their chevrons.",
},
{
type: 'code',
lang: 'tsx',
- label: 'useDirection() in a component',
- code: `import {useDirection} from '@astryxdesign/core/i18n';
+ label: 'Mirror a directional icon with CSS',
+ code: `import * as stylex from '@stylexjs/stylex';
+import {rtlStyles} from '@astryxdesign/core';
function NextButton() {
- const direction = useDirection();
- const icon = direction === 'rtl' ? 'chevronLeft' : 'chevronRight';
- return <Icon icon={icon} />;
+ // One glyph; CSS flips it under RTL. No direction read.
+ return (
+ <span {...stylex.props(rtlStyles.mirror)}>
+ <Icon icon="chevronRight" />
+ </span>
+ );
}`,
},
+ {
+ type: 'heading',
+ level: 4,
+ text: '3. Behavioral logic — read the DOM lazily, on the event',
+ },
+ {
+ type: 'prose',
+ text: "For things CSS can't express; keyboard arrow-key mapping, drag/scroll math; read direction at interaction time with `isRtlElement(el)` (a `getComputedStyle().direction` check), never during render. The focus primitives (`useListFocus`, `useGridFocus`, `useTreeFocus`) already auto-detect direction from their container, so arrow keys flip for free; don't pass a direction flag to them. (`isRtl` on `useListFocus`/`useGridFocus` is deprecated in favor of auto-detection, and new hooks don't accept it.)",
+ },
+ {
+ type: 'heading',
+ level: 4,
+ text: '4. useDirection() context — the last resort',
+ },
+ {
+ type: 'prose',
+ text: "Reach for it only when you genuinely need the direction value during render and none of the above fit. It's SSR-safe and returns `'ltr'` outside a provider (matching `useTranslator`'s silent fallback), but it's the one path that can mismatch on hydration if the provider's `direction` disagrees with `<html dir>`; so prefer the options above, which resolve purely from the DOM. As of the CSS-mirror migration, no astryx component reads direction from context at render time.",
+ },
{
type: 'heading',
level: 3,
diff --git a/packages/core/src/Pagination/Pagination.tsx b/packages/core/src/Pagination/Pagination.tsx
index 7d14e28a0c..c9db597dd4 100644
--- a/packages/core/src/Pagination/Pagination.tsx
+++ b/packages/core/src/Pagination/Pagination.tsx
@@ -5,7 +5,7 @@
/**
* @file Pagination.tsx
* @input Uses React, StyleX, Button, Icon, Selector, Text; page number buttons delegate to Button.
- * Reads i18n direction via useDirection() to flip the prev/next chevrons under RTL.
+ * Prev/next chevrons mirror under RTL via the shared rtlStyles.mirror (CSS scaleX), not a JS direction read.
* @output Exports Pagination component, PaginationProps, PaginationVariant, PaginationSize types
* @position Core implementation; consumed by index.ts, tested by Pagination.test.tsx
*
@@ -37,11 +37,10 @@ import {Selector} from '../Selector';
import {Text} from '../Text';
import {useAnnounce} from '../hooks/useAnnounce';
import {useListFocus} from '../hooks/useListFocus';
-import {mergeProps} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
import {useTranslator} from '../i18n/useTranslator';
-import {useDirection} from '../i18n/useDirection';
import type {PaginationVariantMap} from './index';
// =============================================================================
@@ -343,11 +342,6 @@ export function Pagination({
const previousLabel = t('@astryx.pagination.previous');
const nextLabel = t('@astryx.pagination.next');
- // Directional icons: under RTL, the "previous" control points right and the
- // "next" control points left. aria-labels stay semantic (unchanged).
- const direction = useDirection();
- const previousIcon = direction === 'rtl' ? 'chevronRight' : 'chevronLeft';
- const nextIcon = direction === 'rtl' ? 'chevronLeft' : 'chevronRight';
const pageIndicatorsLabel = t('@astryx.pagination.pageIndicators');
const itemsPerPageLabel = t('@astryx.pagination.itemsPerPage');
@@ -651,7 +645,11 @@ export function Pagination({
label={previousLabel}
variant="ghost"
size={buttonSize}
- icon={<Icon icon={previousIcon} size={isSm ? 'sm' : 'md'} />}
+ icon={
+ <span {...stylex.props(rtlStyles.mirror)}>
+ <Icon icon="chevronLeft" size={isSm ? 'sm' : 'md'} />
+ </span>
+ }
onClick={handlePrevious}
isDisabled={isDisabled || !hasPrevious}
isIconOnly
@@ -663,7 +661,11 @@ export function Pagination({
label={nextLabel}
variant="ghost"
size={buttonSize}
- icon={<Icon icon={nextIcon} size={isSm ? 'sm' : 'md'} />}
+ icon={
+ <span {...stylex.props(rtlStyles.mirror)}>
+ <Icon icon="chevronRight" size={isSm ? 'sm' : 'md'} />
+ </span>
+ }
onClick={handleNext}
isDisabled={isDisabled || !hasNext}
isIconOnly
diff --git a/packages/core/src/i18n/InternationalizationProvider.doc.mjs b/packages/core/src/i18n/InternationalizationProvider.doc.mjs
index 57d0c65a69..abbbba8fec 100644
--- a/packages/core/src/i18n/InternationalizationProvider.doc.mjs
+++ b/packages/core/src/i18n/InternationalizationProvider.doc.mjs
@@ -37,6 +37,11 @@ export const docs = {
description:
'Use real BCP 47 tags such as `fr`, `pt-BR`, or `ar`; regional locales fall back to their base language before English.',
},
+ {
+ guidance: true,
+ description:
+ 'Set the `dir` attribute on `<html>` (or a wrapping element) yourself — the provider does not set it. Astryx components mirror layout and directional icons from the DOM `dir`, so an RTL locale won\'t visually mirror without it. Use `getLocaleDirection(locale)` to derive the value for both the provider and the DOM.',
+ },
{
guidance: false,
description:
@@ -66,6 +71,13 @@ export const docs = {
description:
'Sparse per-locale key overrides applied on top of shipped defaults. Overrides are locale-keyed so a runtime locale swap picks up the correct set.',
},
+ {
+ name: 'dir',
+ type: "'ltr' | 'rtl'",
+ required: false,
+ description:
+ 'Explicit text-direction override for the context. When omitted, direction is derived from `locale` via `Intl.Locale.getTextInfo()`. This sets the direction Astryx reads, but it does NOT set the DOM `dir` attribute — you must set `dir` on `<html>` (or a wrapping element) yourself, since Astryx components mirror layout and directional icons from the DOM `dir`, not from this prop. Set both to the same value and keep them in sync.',
+ },
{
name: 'children',
type: 'ReactNode',
diff --git a/packages/core/src/i18n/InternationalizationProvider.tsx b/packages/core/src/i18n/InternationalizationProvider.tsx
index 66c8f8f569..9650fd86b6 100644
--- a/packages/core/src/i18n/InternationalizationProvider.tsx
+++ b/packages/core/src/i18n/InternationalizationProvider.tsx
@@ -61,6 +61,12 @@ export interface InternationalizationProviderProps {
* from `locale` via `Intl.Locale.getTextInfo()`. Provide this to force a
* direction (e.g. RTL layout testing under an English catalog) or to skip the
* derivation when you already know the direction.
+ *
+ * This sets the direction astryx reads via context; it does NOT set the DOM
+ * `dir` attribute. You must set `dir` on `<html>` (or a wrapping element)
+ * yourself — astryx components mirror layout and directional icons from the
+ * DOM `dir`, so an RTL locale won't visually mirror without it. Keep the two
+ * in sync (e.g. `dir={getLocaleDirection(locale)}` on both).
*/
dir?: 'ltr' | 'rtl';
children: ReactNode;
diff --git a/packages/core/src/i18n/useDirection.ts b/packages/core/src/i18n/useDirection.ts
index f3c696d252..a8184b98ed 100644
--- a/packages/core/src/i18n/useDirection.ts
+++ b/packages/core/src/i18n/useDirection.ts
@@ -10,9 +10,12 @@
* when called outside a provider (matches the silent-en-fallback pattern of
* useTranslator).
*
- * Use this in components that need to swap directional icons, mirror
- * behavioral logic (slider math, keyboard nav), or apply direction-specific
- * styling that CSS logical properties can't express.
+ * Render-time last resort. Prefer, in order: CSS logical properties; the shared
+ * `rtlStyles.mirror` for directional icons (CSS scaleX, not a JS icon-name
+ * swap); and lazy DOM reads (`isRtlElement`) for behavioral logic like keyboard
+ * nav or drag math. Reach for this hook only when you need the direction value
+ * during render and none of those fit — note it can mismatch on hydration if
+ * the provider's direction disagrees with the actual `<html dir>`.
*
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/i18n/InternationalizationContext.ts