An open source design system that's fully customizable and agent ready
TypeScript
fix(TopNav): the featured card's link arrow mirrors in RTL (#9317)
Cindy Zhang01015794a825
diff --git a/.changeset/topnav-featured-card-rtl-arrow.md b/.changeset/topnav-featured-card-rtl-arrow.mdnew file mode 100644index 0000000000..0a0e8029ad--- /dev/null+++ b/.changeset/topnav-featured-card-rtl-arrow.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] TopNavMegaMenuFeaturedCard: in right-to-left layouts the link arrow now points toward the inline end (left) instead of backwards. The link's text and accessible name are unchanged.++@cixzhangdiff --git a/docs/specs/components/TopNav/TopNavMegaMenuFeaturedCard.spec.md b/docs/specs/components/TopNav/TopNavMegaMenuFeaturedCard.spec.mdindex 6ae5dee92f..ab1fdc8c5b 100644--- a/docs/specs/components/TopNav/TopNavMegaMenuFeaturedCard.spec.md+++ b/docs/specs/components/TopNav/TopNavMegaMenuFeaturedCard.spec.md@@ -30,7 +30,7 @@ system_specs: []| Behavior | A promotional card for a mega menu's featured slot: optional image, title, description, an optional call-to-action link, then caller content. || End-user impact | Users see a highlighted destination; screen-reader users skip a decorative image unless `imageAlt` names it. || Builder impact | None. |-| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps (see Current-state impact). |+| Compatibility/readiness | Records shipped behavior; no public change. One implementation gap (see Current-state impact). || Review checks | Reject an image without `imageAlt` that is exposed to assistive technology, or a link rendered when only one of `linkLabel` and `linkHref` is set. || Governing rules | `design:bidirectionality` DR4; `architecture:interaction-modality`; `architecture:component-theming-surface`. |@@ -53,9 +53,6 @@ Consumer migration instructions belong in consumer docs and release notes.## Current-state impact-- **The link arrow does not mirror.** The call-to-action link ends with a- literal `→`, which points right in right-to-left layouts too.- `design:bidirectionality` DR4 requires a progression glyph to mirror once.- **Browser default focus ring.** The call-to-action link does not use the sharedfocus outline; keyboard focus paints the browser's default ring.`architecture:interaction-modality` provides the shared indicator it bypasses.@@ -79,12 +76,12 @@ No component-local concept beyond the consumer props.## Behavioral and layout contract-| ID | Invariant | Basis |-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1 | The root `div` carries `top-nav-mega-menu-featured-card`, the forwarded `ref`, and other DOM props, and shows: the image (full width, 140 px tall) when `image` is set, then the title, description, link, and `children`. | Current source and tests |-| FR2 | Without `imageAlt` the image is decorative: `alt=""`, `role="presentation"`, and `aria-hidden="true"`. With `imageAlt` it is a normal image with that alternative text. | Current source and tests |-| FR3 | The link renders only when both `linkLabel` and `linkHref` are set, through the `LinkProvider` link component, as `linkLabel` followed by ` →`. | Current source and tests |-| FR4 | `className`, `style`, and `xstyle` merge after component styles. | Current source |+| ID | Invariant | Basis |+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |+| FR1 | The root `div` carries `top-nav-mega-menu-featured-card`, the forwarded `ref`, and other DOM props, and shows: the image (full width, 140 px tall) when `image` is set, then the title, description, link, and `children`. | Current source and tests |+| FR2 | Without `imageAlt` the image is decorative: `alt=""`, `role="presentation"`, and `aria-hidden="true"`. With `imageAlt` it is a normal image with that alternative text. | Current source and tests |+| FR3 | The link renders only when both `linkLabel` and `linkHref` are set, through the `LinkProvider` link component, as `linkLabel` followed by ` →`; the arrow mirrors once in right-to-left layouts (`design:bidirectionality` DR4). | Current source and tests |+| FR4 | `className`, `style`, and `xstyle` merge after component styles. | Current source |### Allowed variation@@ -125,16 +122,17 @@ anatomy-theming map is recorded.- `family:navigation-destinations` owns the accept/block decision for eachdestination this component renders.- `component:TopNavMegaMenu` renders the card in its featured area.-- `design:bidirectionality` DR4 governs the link glyph gap.+- `design:bidirectionality` DR4 governs the link glyph.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| -------- | ---------------------------------------------------- | --------------------------- | -------------------------------------------- | ------------------------------------------------ |-| FR1 | `TopNav.test.tsx` featured-card rest-forwarding test | Root props | Dropped props fail. | `audit:TopNavMegaMenuFeaturedCard/behavior` |-| FR2, FR3 | `TopNav.test.tsx` featured-card image tests | With and without `imageAlt` | Exposed decorative image or lost link fails. | `audit:TopNavMegaMenuFeaturedCard/accessibility` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| --------------- | ----------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |+| FR1 | `TopNav.test.tsx` featured-card rest-forwarding test | Root props | Dropped props fail. | `audit:TopNavMegaMenuFeaturedCard/behavior` |+| FR2, FR3 | `TopNav.test.tsx` featured-card image tests | With and without `imageAlt` | Exposed decorative image or lost link fails. | `audit:TopNavMegaMenuFeaturedCard/accessibility` |+| FR3 (RTL arrow) | `TopNav.test.tsx` featured-card arrow-mirror test, plus real-browser evidence | Link with a label, LTR and RTL | An arrow that points right in RTL, or a link name that changes, fails. Gap: the unit test sees the mirror class but not the inline-block box the transform needs; no committed browser check fails on an unmirrored arrow. | `audit:TopNavMegaMenuFeaturedCard/i18n-rtl` |-Read from source, with no focused test yet: the content order (FR1); the forwarded `ref` and the `top-nav-mega-menu-featured-card` target (FR1); that the link renders only when both `linkLabel` and `linkHref` are set (FR3); the image size (FR1), the `LinkProvider` link and trailing arrow (FR3), and FR4.+Read from source, with no focused test yet: the content order (FR1); the forwarded `ref` and the `top-nav-mega-menu-featured-card` target (FR1); that the link renders only when both `linkLabel` and `linkHref` are set (FR3); the image size (FR1), the `LinkProvider` link (FR3), and FR4.## Decision logdiff --git a/packages/core/src/TopNav/TopNav.test.tsx b/packages/core/src/TopNav/TopNav.test.tsxindex 80595a9687..a3a5aed53f 100644--- a/packages/core/src/TopNav/TopNav.test.tsx+++ b/packages/core/src/TopNav/TopNav.test.tsx@@ -9,6 +9,7 @@* SYNC: When TopNav components change, update tests to match new behavior*/+import * as stylex from '@stylexjs/stylex';import {describe, it, expect, vi} from 'vitest';import {fireEvent, render, screen, act} from '@testing-library/react';import {__resetMenuPressForTest} from '../hooks/useMenuPress';@@ -24,6 +25,7 @@ import {TopNavMegaMenuFeaturedCard} from './TopNavMegaMenuFeaturedCard';import {LinkProvider} from '../Link/LinkProvider';import {InternationalizationProvider} from '../i18n/InternationalizationProvider';import koreanCatalog from '../../locales/ko-KR.json';+import {rtlStyles} from '../utils';function CustomLink({children,@@ -821,6 +823,35 @@ describe('TopNavItem', () => {const link = screen.getByRole('link', {name: /Read the announcement/});expect(link).toHaveAttribute('href', '/blog/v4');});++ // design:bidirectionality DR4: the arrow points toward the inline end, so+ // it mirrors in RTL. jsdom does not apply compiled StyleX CSS, so this pins+ // the structure the mirror relies on: the arrow sits in its own element+ // carrying the shared rtlStyles.mirror, and the link name is unchanged.+ it('wraps the link arrow in the shared RTL mirror', () => {+ const {className: mirrorClassName} = stylex.props(rtlStyles.mirror);+ const mirrorClasses = mirrorClassName?.split(' ') ?? [];+ expect(mirrorClasses.length).toBeGreaterThan(0);+ render(+ <div dir="rtl">+ <TopNavMegaMenuFeaturedCard+ title="What's new"+ linkLabel="Read the announcement"+ linkHref="/blog/v4"+ />+ </div>,+ );+ const link = screen.getByRole('link', {+ name: 'Read the announcement →',+ });+ const arrow = Array.from(link.querySelectorAll('span')).find(+ span => span.textContent === '→',+ );+ expect(arrow).toBeDefined();+ for (const className of mirrorClasses) {+ expect(arrow).toHaveClass(className);+ }+ });});});diff --git a/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.tsx b/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.tsxindex a70749085d..51eaef9521 100644--- a/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.tsx+++ b/packages/core/src/TopNav/TopNavMegaMenuFeaturedCard.tsx@@ -26,7 +26,7 @@ import {typeScaleVars,fontWeightVars,} from '../theme/tokens.stylex';-import {mergeProps} from '../utils';+import {mergeProps, rtlStyles} from '../utils';import type {BaseProps} from '../BaseProps';import {useLinkComponent} from '../Link/useLinkComponent';import {themeProps} from '../utils/themeProps';@@ -70,6 +70,10 @@ const styles = stylex.create({color: colorVars['--color-text-accent'],textDecoration: 'none',},+ // A transform needs a box: an inline span would not mirror.+ linkArrow: {+ display: 'inline-block',+ },});// =============================================================================@@ -175,7 +179,10 @@ export function TopNavMegaMenuFeaturedCard({)}{linkLabel && linkHref && (<LinkComponent href={linkHref} {...stylex.props(styles.link)}>- {linkLabel} →+ {linkLabel}{' '}+ {/* The arrow points toward the inline end, so it mirrors in RTL+ (design:bidirectionality DR4); U+2192 is not bidi-mirrored. */}+ <span {...stylex.props(styles.linkArrow, rtlStyles.mirror)}>→</span></LinkComponent>)}{children}