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.mdnew file mode 100644index 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.+@nynexman4464diff --git a/packages/cli/assets/docs/internationalization.doc.mjs b/packages/cli/assets/docs/internationalization.doc.mjsindex 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.tsxindex 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}isIconOnlydiff --git a/packages/core/src/i18n/InternationalizationProvider.doc.mjs b/packages/core/src/i18n/InternationalizationProvider.doc.mjsindex 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.tsxindex 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.tsindex 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