An open source design system that's fully customizable and agent ready
TypeScript
fix(a11y): unique names for repeated nav landmarks (#4692)
AKde6d448cadb3
diff --git a/.changeset/a11y-table-pagination-both-labels.md b/.changeset/a11y-table-pagination-both-labels.mdnew file mode 100644index 0000000000..e7b167503a--- /dev/null+++ b/.changeset/a11y-table-pagination-both-labels.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[fix] useTablePagination: with `position='both'` the two pagination `<nav>` landmarks now get distinct accessible names — "{label} (top)" above the table and "{label} (bottom)" below it (axe landmark-unique). Consumer-supplied `label` values are interpolated into both names; single-position labels are unchanged.+@AKnassadiff --git a/.github/a11y-baseline.json b/.github/a11y-baseline.jsonindex bb75e38b8f..0cf359b00b 100644--- a/.github/a11y-baseline.json+++ b/.github/a11y-baseline.json@@ -598,11 +598,6 @@"impact": "serious","helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"},- {- "key": "Layout::Content Width — Responsive Panels::landmark-unique",- "impact": "moderate",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"- },{"key": "Layout::Content Width — Start Panel::color-contrast","impact": "serious",@@ -668,11 +663,6 @@"impact": "serious","helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"},- {- "key": "Pagination::All Variants::landmark-unique",- "impact": "moderate",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"- },{"key": "PopArt::Debug Projection::color-contrast","impact": "serious",@@ -858,16 +848,6 @@"impact": "serious","helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"},- {- "key": "TabList::Divider Gap (sm / md / lg)::landmark-unique",- "impact": "moderate",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"- },- {- "key": "TabList::Size Variants::landmark-unique",- "impact": "moderate",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"- },{"key": "Table::In Card Densities::color-contrast","impact": "serious",@@ -913,16 +893,6 @@"impact": "serious","helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"},- {- "key": "TablePagination::Options Matrix::landmark-unique",- "impact": "moderate",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"- },- {- "key": "TablePagination::Position Both::landmark-unique",- "impact": "moderate",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"- },{"key": "TableTree::Default::aria-conditional-attr","impact": "serious",@@ -1008,16 +978,6 @@"impact": "serious","helpUrl": "https://dequeuniversity.com/rules/axe/4.12/color-contrast?application=playwright"},- {- "key": "Toolbar::Composition: Tab Navigation::landmark-unique",- "impact": "moderate",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"- },- {- "key": "ToolbarEdgeCompensation::Tabs in toolbar (all sizes)::landmark-unique",- "impact": "moderate",- "helpUrl": "https://dequeuniversity.com/rules/axe/4.12/landmark-unique?application=playwright"- },{"key": "useContainerReveal::Inverted Conceal::color-contrast","impact": "serious",diff --git a/apps/storybook/stories/Layout.stories.tsx b/apps/storybook/stories/Layout.stories.tsxindex 1bb496ec39..15c5ba9121 100644--- a/apps/storybook/stories/Layout.stories.tsx+++ b/apps/storybook/stories/Layout.stories.tsx@@ -743,9 +743,7 @@ export const ThemedLayout: Story = {render: () => (<HStack gap={6} xstyle={styles.storySection}><VStack gap={3}>- <p {...stylex.props(styles.sectionLabel)}>- Stone Theme- </p>+ <p {...stylex.props(styles.sectionLabel)}>Stone Theme</p><Theme theme={stoneTheme}><Card width={400}><Layout@@ -779,9 +777,7 @@ export const ThemedLayout: Story = {</VStack><VStack gap={3}>- <p {...stylex.props(styles.sectionLabel)}>- Neutral Theme- </p>+ <p {...stylex.props(styles.sectionLabel)}>Neutral Theme</p><Theme theme={neutralTheme}><Card width={400}><Layout@@ -1229,7 +1225,11 @@ export const ContentWidthResponsive: Story = {</LayoutHeader>}start={- <LayoutPanel width={160} hasDivider role="navigation">+ <LayoutPanel+ width={160}+ hasDivider+ role="navigation"+ label="Wide navigation"><NavItem active>Dashboard</NavItem><NavItem>Settings</NavItem></LayoutPanel>@@ -1262,7 +1262,11 @@ export const ContentWidthResponsive: Story = {</LayoutHeader>}start={- <LayoutPanel width={160} hasDivider role="navigation">+ <LayoutPanel+ width={160}+ hasDivider+ role="navigation"+ label="Medium navigation"><NavItem active>Dashboard</NavItem><NavItem>Settings</NavItem></LayoutPanel>@@ -1295,7 +1299,11 @@ export const ContentWidthResponsive: Story = {</LayoutHeader>}start={- <LayoutPanel width={160} hasDivider role="navigation">+ <LayoutPanel+ width={160}+ hasDivider+ role="navigation"+ label="Narrow navigation"><NavItem active>Dashboard</NavItem><NavItem>Settings</NavItem></LayoutPanel>diff --git a/apps/storybook/stories/TabList.stories.tsx b/apps/storybook/stories/TabList.stories.tsxindex cfaf8e9351..3948142618 100644--- a/apps/storybook/stories/TabList.stories.tsx+++ b/apps/storybook/stories/TabList.stories.tsx@@ -101,7 +101,11 @@ export const SizeVariants: Story = {size=\"{size}\"</div><div style={{border: '1px dashed #ccc', display: 'inline-flex'}}>- <TabList value={value} onChange={setValue} size={size}>+ <TabList+ value={value}+ onChange={setValue}+ size={size}+ aria-label={`Tabs (${size})`}><Tab value="home" label="Home" /><Tab value="projects" label="Projects" /><Tab value="settings" label="Settings" />@@ -242,7 +246,12 @@ export const DividerGap: Story = {<span style={{font: '600 12px system-ui', color: '#4E606F'}}>size="{size}" · hasDivider · matched Button size</span>- <TabList value={value} onChange={setValue} size={size} hasDivider>+ <TabList+ value={value}+ onChange={setValue}+ size={size}+ hasDivider+ aria-label={`Tabs (${size})`}><Tab value="overview" label="Overview" /><Tab value="activity" label="Activity" /><Tab value="settings" label="Settings" />diff --git a/apps/storybook/stories/TablePagination.stories.tsx b/apps/storybook/stories/TablePagination.stories.tsxindex 21f90aed37..280bcf1341 100644--- a/apps/storybook/stories/TablePagination.stories.tsx+++ b/apps/storybook/stories/TablePagination.stories.tsx@@ -51,10 +51,12 @@ function PaginatedDemo({variant = 'pages',position = 'below',align = 'start',+ label,}: {variant?: Variant;position?: Position;align?: Align;+ label?: string;}) {const [page, setPage] = useState(1);const pageSize = 10;@@ -67,6 +69,7 @@ function PaginatedDemo({variant,position,align,+ label,});return (@@ -394,6 +397,7 @@ export const OptionsMatrix: Story = {variant={variant}position={position}align={align}+ label={`Table pagination (${variant}, ${position}, ${align})`}/></div>)),diff --git a/apps/storybook/stories/Toolbar.stories.tsx b/apps/storybook/stories/Toolbar.stories.tsxindex 6e219e0298..8c9119ed76 100644--- a/apps/storybook/stories/Toolbar.stories.tsx+++ b/apps/storybook/stories/Toolbar.stories.tsx@@ -414,7 +414,10 @@ export const WithTabNavigation: Story = {size={size}dividers={['bottom']}startContent={- <TabList value={tab} onChange={setTab}>+ <TabList+ value={tab}+ onChange={setTab}+ aria-label={`Tab navigation (${size})`}><Tab value="overview" label="Overview" /><Tab value="analytics" label="Analytics" /><Tab value="settings" label="Settings" />diff --git a/apps/storybook/stories/ToolbarEdgeCompensation.stories.tsx b/apps/storybook/stories/ToolbarEdgeCompensation.stories.tsxindex e0bf2b524b..f360615505 100644--- a/apps/storybook/stories/ToolbarEdgeCompensation.stories.tsx+++ b/apps/storybook/stories/ToolbarEdgeCompensation.stories.tsx@@ -1053,9 +1053,7 @@ export const CardLayoutContentWidthToolbar: Story = {<LayoutHeader hasDivider padding={0}><Toolbarlabel="Card layout header"- startContent={- <Heading level={4}>Notifications</Heading>- }+ startContent={<Heading level={4}>Notifications</Heading>}/></LayoutHeader>}@@ -1144,7 +1142,10 @@ export const WithTabs: Story = {size={size}dividers={['bottom']}startContent={- <TabList value={tab} onChange={setTab}>+ <TabList+ value={tab}+ onChange={setTab}+ aria-label={`Tab toolbar tabs (${size})`}><Tab value="overview" label="Overview" /><Tab value="analytics" label="Analytics" /><Tab value="settings" label="Settings" />diff --git a/packages/core/locales/en.json b/packages/core/locales/en.jsonindex dea955a8c9..ca7bb42e69 100644--- a/packages/core/locales/en.json+++ b/packages/core/locales/en.json@@ -813,7 +813,15 @@},"@astryx.table.pagination.label": {"defaultMessage": "Table pagination",- "description": "Screen-reader-only accessible name for the pagination `<nav>` appended below a data table. Kept separate from `@astryx.pagination.label` so translations may diverge."+ "description": "Screen-reader-only accessible name for a table's pagination `<nav>` (rendered below and/or above the table per the plugin's position config). Kept separate from `@astryx.pagination.label` so translations may diverge. When position='both', this string is interpolated as the {label} value into `@astryx.table.pagination.labelAbove`/`labelBelow` — keep it compatible with those suffix templates."+ },+ "@astryx.table.pagination.labelAbove": {+ "defaultMessage": "{label} (top)",+ "description": "Accessible name for the pagination `<nav>` rendered above the table when position='both' renders two navs. `label` is the resolved base label (default \"Table pagination\" or consumer-supplied); the suffix keeps the two same-type landmarks distinguishable."+ },+ "@astryx.table.pagination.labelBelow": {+ "defaultMessage": "{label} (bottom)",+ "description": "Accessible name for the pagination `<nav>` rendered below the table when position='both' renders two navs. `label` is the resolved base label (default \"Table pagination\" or consumer-supplied); the suffix keeps the two same-type landmarks distinguishable."},"@astryx.timeInput.placeholder": {"defaultMessage": "Select a time",diff --git a/packages/core/src/Table/plugins/pagination/useTablePagination.test.tsx b/packages/core/src/Table/plugins/pagination/useTablePagination.test.tsxindex ce9b1d499d..22b68091c0 100644--- a/packages/core/src/Table/plugins/pagination/useTablePagination.test.tsx+++ b/packages/core/src/Table/plugins/pagination/useTablePagination.test.tsx@@ -229,7 +229,7 @@ describe('useTablePagination', () => {).toBeTruthy();});- it('transformTableContext renders Pagination above and below', () => {+ it('transformTableContext renders distinctly named Pagination above and below', () => {render(<PaginatedTabledata={generateItems(30)}@@ -237,10 +237,40 @@ describe('useTablePagination', () => {position="both"/>,);- const navs = screen.getAllByRole('navigation', {- name: 'Table pagination',+ const table = screen.getByRole('table');+ // Each nav landmark gets a unique accessible name (axe landmark-unique)+ const topNav = screen.getByRole('navigation', {+ name: 'Table pagination (top)',+ });+ const bottomNav = screen.getByRole('navigation', {+ name: 'Table pagination (bottom)',});- expect(navs).toHaveLength(2);+ // Top nav comes before the table, bottom nav after it in DOM order+ expect(+ table.compareDocumentPosition(topNav) &+ Node.DOCUMENT_POSITION_PRECEDING,+ ).toBeTruthy();+ expect(+ table.compareDocumentPosition(bottomNav) &+ Node.DOCUMENT_POSITION_FOLLOWING,+ ).toBeTruthy();+ });++ it('position="both" interpolates a consumer label into distinct nav names', () => {+ render(+ <PaginatedTable+ data={generateItems(30)}+ pageSize={10}+ position="both"+ label="Users table"+ />,+ );+ expect(+ screen.getByRole('navigation', {name: 'Users table (top)'}),+ ).toBeInTheDocument();+ expect(+ screen.getByRole('navigation', {name: 'Users table (bottom)'}),+ ).toBeInTheDocument();});it('transformTableContext does not render Pagination when position is none', () => {diff --git a/packages/core/src/Table/plugins/pagination/useTablePagination.tsx b/packages/core/src/Table/plugins/pagination/useTablePagination.tsxindex fbb562cc1e..fcc2994043 100644--- a/packages/core/src/Table/plugins/pagination/useTablePagination.tsx+++ b/packages/core/src/Table/plugins/pagination/useTablePagination.tsx@@ -164,6 +164,9 @@ export interface UseTablePaginationConfig {/*** Accessible label for the pagination nav landmark.+ * When `position` is 'both', the two navs get distinct names by suffixing+ * this label — "{label} (top)" above and "{label} (bottom)" below — so+ * same-type landmarks stay distinguishable to assistive technology.* @default 'Table pagination'*/label?: string;@@ -211,6 +214,10 @@ export function useTablePagination<T extends Record<string, unknown>>(label: labelFromProps,} = config;const label = labelFromProps ?? t('@astryx.table.pagination.label');+ // position='both' renders two nav landmarks; suffix the base label so each+ // gets a unique accessible name (axe landmark-unique).+ const labelAbove = t('@astryx.table.pagination.labelAbove', {label});+ const labelBelow = t('@astryx.table.pagination.labelBelow', {label});// Same guard as Pagination itself: 0/NaN/negative pageSize would produce an// Infinity/NaN totalPages here, which bypasses Pagination's own coercion@@ -240,8 +247,20 @@ export function useTablePagination<T extends Record<string, unknown>>(// Keep current config in a ref so the plugin can read the latest values// without needing to recreate the plugin object on every change.- const configRef = useRef({paginationProps, position, align});- configRef.current = {paginationProps, position, align};+ const configRef = useRef({+ paginationProps,+ position,+ align,+ labelAbove,+ labelBelow,+ });+ configRef.current = {+ paginationProps,+ position,+ align,+ labelAbove,+ labelBelow,+ };// Stable plugin object \u2014 created once, reads config via ref.return useMemo(@@ -251,6 +270,8 @@ export function useTablePagination<T extends Record<string, unknown>>(position: pos,paginationProps: props,align: a,+ labelAbove: above,+ labelBelow: below,} = configRef.current;if (pos === 'none') {return children;@@ -277,7 +298,18 @@ export function useTablePagination<T extends Record<string, unknown>>(a === 'end' && styles.alignEnd,a === 'start' && styles.alignStart,)}>- <Pagination {...props} />+ <Pagination+ {...props}+ // Two navs with the same name are indistinguishable landmarks;+ // give each side a unique name when both render.+ label={+ pos === 'both'+ ? side === 'above'+ ? above+ : below+ : props.label+ }+ /></div>);diff --git a/packages/core/src/Table/useTablePagination.doc.mjs b/packages/core/src/Table/useTablePagination.doc.mjsindex 77b6e220bf..c7a1c53730 100644--- a/packages/core/src/Table/useTablePagination.doc.mjs+++ b/packages/core/src/Table/useTablePagination.doc.mjs@@ -72,6 +72,12 @@ export const docs = {description: 'Horizontal alignment of the pagination controls.',default: "'center'",},+ {+ name: 'label',+ type: 'string',+ description: "Accessible name for the pagination nav landmark. With position='both' the two navs get distinct names — the label suffixed as '(top)' and '(bottom)' — so same-type landmarks stay unique (axe landmark-unique).",+ default: "'Table pagination'",+ },],};@@ -129,5 +135,6 @@ export const docsDense = {pageSize: 'Items per page. Default 10.',variant: "Pagination variant: 'pages'|'count'|'compact'|'dots'|'none'.",position: "Render position: 'below'|'above'|'both'|'none'.",+ label: "Accessible name for the nav landmark; position='both' emits '<label> (top)' / '<label> (bottom)'.",},};