Skip to content

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.md
new file mode 100644
index 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.
+@AKnassa
diff --git a/.github/a11y-baseline.json b/.github/a11y-baseline.json
index 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.tsx
index 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.tsx
index 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=&quot;{size}&quot; · 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.tsx
index 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.tsx
index 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.tsx
index 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}>
<Toolbar
label="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.json
index 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.tsx
index 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(
<PaginatedTable
data={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.tsx
index 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.mjs
index 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)'.",
},
};