Skip to content

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

TypeScript

test(a11y): repair Tabs contract proof gaps (#6254)

Cindy Zhangcf47bab31aca
diff --git a/internal/a11y-spec/src/harness/chromium.chromium.spec.ts b/internal/a11y-spec/src/harness/chromium.chromium.spec.ts
index 3e96d3b4c6..0fe9eee38c 100644
--- a/internal/a11y-spec/src/harness/chromium.chromium.spec.ts
+++ b/internal/a11y-spec/src/harness/chromium.chromium.spec.ts
@@ -3,7 +3,7 @@
/**
* @file chromium.chromium.spec.ts
* @input Uses @playwright/test and the public Chromium harness seam
- * @output Focused accessibility-tree mapping tests for computed node state
+ * @output Focused accessibility-tree mapping and clipping-aware rendered-visibility tests
* @position Harness regression coverage; proves browser AX properties are exposed without DOM substitution.
*/
@@ -149,6 +149,9 @@ test('subjects report rendered visibility', async ({page}) => {
<div id="visible">Visible</div>
<div id="hidden" style="display:none">Hidden</div>
<div id="transparent" style="opacity:0">Transparent</div>
+ <div id="clipped" style="clip-path:inset(100%)">Clipped</div>
+ <div id="partially-clipped" style="clip-path:inset(25%)">Partially clipped</div>
+ <div id="offscreen" style="position:absolute;left:-10000px">Offscreen</div>
`);
const cdp = await page.context().newCDPSession(page);
const harness = createChromiumHarness({
@@ -158,10 +161,18 @@ test('subjects report rendered visibility', async ({page}) => {
related: {
hidden: page.locator('#hidden'),
transparent: page.locator('#transparent'),
+ clipped: page.locator('#clipped'),
+ partiallyClipped: page.locator('#partially-clipped'),
+ offscreen: page.locator('#offscreen'),
},
});
expect(await (await harness.subject()).isVisible()).toBe(true);
expect(await (await harness.related('hidden')).isVisible()).toBe(false);
expect(await (await harness.related('transparent')).isVisible()).toBe(false);
+ expect(await (await harness.related('clipped')).isVisible()).toBe(false);
+ expect(await (await harness.related('partiallyClipped')).isVisible()).toBe(
+ true,
+ );
+ expect(await (await harness.related('offscreen')).isVisible()).toBe(true);
});
diff --git a/internal/a11y-spec/src/harness/chromium.ts b/internal/a11y-spec/src/harness/chromium.ts
index 69d4cb12f2..993234373d 100644
--- a/internal/a11y-spec/src/harness/chromium.ts
+++ b/internal/a11y-spec/src/harness/chromium.ts
@@ -5,7 +5,7 @@
* @input Uses a Playwright `Page`, the semantic subject `Locator`, optional
* binding-owned pointer-target and visible-label `Locator`s, and the Chrome
* DevTools Protocol accessibility domain behind them
- * @output `createChromiumHarness` — a harness that observes the DOM,
+ * @output `createChromiumHarness` — a clipping-aware harness that observes the DOM,
* accessibility-tree, and real-browser layers of a page rendered by a real
* shipping engine — plus `holdMotionStill`, the page setup its specs share.
* @position The high-fidelity lane. Imported only from the Playwright specs, so
@@ -364,7 +364,27 @@ async function renderedVisible(locator: Locator): Promise<boolean> {
return false;
}
const box = element.getBoundingClientRect();
- return box.width > 0 && box.height > 0;
+ if (box.width <= 0 || box.height <= 0) {
+ return false;
+ }
+ const rootMargin = [
+ Math.max(0, -box.top),
+ Math.max(0, box.right - window.innerWidth),
+ Math.max(0, box.bottom - window.innerHeight),
+ Math.max(0, -box.left),
+ ]
+ .map(value => `${value}px`)
+ .join(' ');
+ return new Promise<boolean>(resolve => {
+ const observer = new IntersectionObserver(
+ entries => {
+ observer.disconnect();
+ resolve((entries[0]?.intersectionRatio ?? 0) > 0);
+ },
+ {rootMargin},
+ );
+ observer.observe(element);
+ });
});
}
diff --git a/internal/a11y-spec/src/patterns/tabs.fixtures.ts b/internal/a11y-spec/src/patterns/tabs.fixtures.ts
index dba28f8197..2aca155993 100644
--- a/internal/a11y-spec/src/patterns/tabs.fixtures.ts
+++ b/internal/a11y-spec/src/patterns/tabs.fixtures.ts
@@ -3,7 +3,7 @@
/**
* @file tabs.fixtures.ts
* @input Uses TabsStateFacts
- * @output Plain-HTML conforming and deliberately violating Tabs fixtures
+ * @output Plain-HTML conforming and deliberately violating Tabs fixtures, including two-tab boundary and clipped-paint mutations
* @position Mutation proof for the reusable contract; no Astryx component code.
*/
@@ -103,12 +103,14 @@ interface GroupOptions {
readonly firstPanelHidden?: boolean;
readonly firstPanelCssHidden?: boolean;
readonly firstPanelTransparent?: boolean;
+ readonly firstPanelClipped?: boolean;
readonly secondPanelHidden?: boolean;
readonly secondPanelCssVisible?: boolean;
readonly duplicatePanelId?: boolean;
readonly duplicateTabId?: boolean;
readonly wrongEntry?: boolean;
readonly trapTab?: boolean;
+ readonly thirdTab?: boolean;
readonly arrow?:
| 'works'
| 'inert'
@@ -142,12 +144,14 @@ function groupHtml(options: GroupOptions = {}): string {
firstPanelHidden = !firstSelected,
firstPanelCssHidden = false,
firstPanelTransparent = false,
+ firstPanelClipped = false,
secondPanelHidden = !secondSelected,
secondPanelCssVisible = false,
duplicatePanelId = false,
duplicateTabId = false,
wrongEntry = false,
trapTab = false,
+ thirdTab = true,
arrow = 'works',
keyboard = 'works',
pointer = 'works',
@@ -183,17 +187,17 @@ function groupHtml(options: GroupOptions = {}): string {
<div${subjectAttribute('tablist')} data-a11y-tabs role="${tablistRole}"${named ? ' aria-label="Project views"' : ''} dir="${direction}">
<button${subjectAttribute('first-tab')} data-a11y-related="first" data-key="first" id="tab-first" role="${tabRole}" aria-selected="${firstSelected}"${controlsAttribute}${firstAria} tabindex="${wrongEntry ? -1 : firstSelected ? 0 : -1}">${firstLabel}</button>
<button${subjectAttribute('second-tab')} data-a11y-related="second" data-key="second" id="tab-second" role="tab" aria-selected="${secondSelected}" aria-controls="panel-second" tabindex="${wrongEntry ? 0 : secondSelected ? 0 : -1}"${secondDisabled ? ' disabled' : ''}${secondAriaDisabled ? ' aria-disabled="true"' : ''}>Activity</button>
- <button data-a11y-related="third" data-key="third" id="tab-third" role="tab" aria-selected="false" aria-controls="panel-third" tabindex="-1"${thirdDisabled ? ' disabled' : ''}>Members</button>
+ ${thirdTab ? '<button data-a11y-related="third" data-key="third" id="tab-third" role="tab" aria-selected="false" aria-controls="panel-third" tabindex="-1"' + (thirdDisabled ? ' disabled' : '') + '>Members</button>' : ''}
</div>
- <div${subjectAttribute('first-panel')} data-a11y-related="panel-first" id="panel-first" role="${panelRole}"${panelLabelAttribute}${firstPanelHidden ? ' hidden' : ''}${firstPanelCssHidden ? ' style="display:none"' : firstPanelTransparent ? ' style="opacity:0"' : ''}>Overview panel</div>
+ <div${subjectAttribute('first-panel')} data-a11y-related="panel-first" id="panel-first" role="${panelRole}"${panelLabelAttribute}${firstPanelHidden ? ' hidden' : ''}${firstPanelCssHidden ? ' style="display:none"' : firstPanelTransparent ? ' style="opacity:0"' : firstPanelClipped ? ' style="clip-path:inset(100%)"' : ''}>Overview panel</div>
<div${subjectAttribute('second-panel')} data-a11y-related="panel-second" id="panel-second" role="tabpanel" aria-labelledby="tab-second"${secondPanelHidden ? ' hidden' : ''}${secondPanelCssVisible ? ' style="display:block !important"' : ''}>Activity panel</div>
- <div data-a11y-related="panel-third" id="panel-third" role="tabpanel" aria-labelledby="tab-third" hidden>Members panel</div>
+ ${thirdTab ? '<div data-a11y-related="panel-third" id="panel-third" role="tabpanel" aria-labelledby="tab-third" hidden>Members panel</div>' : ''}
<button type="button">After</button>
<script>
(() => {
const list = document.querySelector('[data-a11y-tabs]');
const tabs = Array.from(list.querySelectorAll('[role="tab"], [data-key]'));
- const panels = ['first', 'second', 'third'].map(key => document.getElementById('panel-' + key));
+ const panels = [${thirdTab ? "'first', 'second', 'third'" : "'first', 'second'"}].map(key => document.getElementById('panel-' + key));
const select = key => {
tabs.forEach(tab => {
const active = tab.dataset.key === key;
@@ -261,6 +265,15 @@ export const TABS_FIXTURES: readonly TabsFixture[] = [
facts: baseFacts(),
html: groupHtml(),
},
+ {
+ id: 'conforming-tablist-two-tabs',
+ summary: 'a two-tab set that wraps both arrows at both boundaries',
+ facts: baseFacts({
+ tabRelations: ['first', 'second'],
+ panelRelations: ['panel-first', 'panel-second'],
+ }),
+ html: groupHtml({thirdTab: false}),
+ },
{
id: 'conforming-tablist-rtl',
summary: 'a horizontal RTL manual-activation tablist',
@@ -498,6 +511,12 @@ export const TABS_FIXTURES: readonly TabsFixture[] = [
facts: panelFacts(),
html: groupHtml({subject: 'first-panel', firstPanelCssHidden: true}),
},
+ {
+ id: 'violating-panel-active-clipped',
+ summary: 'an active positive-size tabpanel fully clipped from paint',
+ facts: panelFacts(),
+ html: groupHtml({subject: 'first-panel', firstPanelClipped: true}),
+ },
{
id: 'violating-panel-active-transparent',
summary: 'an active tabpanel rendered fully transparent',
@@ -516,6 +535,12 @@ export const TABS_FIXTURES: readonly TabsFixture[] = [
facts: baseFacts(),
html: groupHtml({firstPanelCssHidden: true}),
},
+ {
+ id: 'violating-selection-active-clipped',
+ summary: 'the selected positive-size panel is fully clipped from paint',
+ facts: baseFacts(),
+ html: groupHtml({firstPanelClipped: true}),
+ },
{
id: 'violating-selection-active-transparent',
summary: 'the selected panel is fully transparent during selection',
@@ -558,6 +583,16 @@ export const TABS_FIXTURES: readonly TabsFixture[] = [
facts: baseFacts(),
html: groupHtml({arrow: 'one-way'}),
},
+ {
+ id: 'violating-two-tab-arrow-no-wrap',
+ summary:
+ 'a two-tab set whose arrows move only inward and stop at both outward boundaries',
+ facts: baseFacts({
+ tabRelations: ['first', 'second'],
+ panelRelations: ['panel-first', 'panel-second'],
+ }),
+ html: groupHtml({arrow: 'no-wrap', thirdTab: false}),
+ },
{
id: 'violating-arrow-no-wrap',
summary: 'a tablist whose arrows stop at the ends instead of wrapping',
@@ -655,12 +690,14 @@ export const TABS_MUTATIONS: Readonly<Record<string, readonly string[]>> = {
'tabs.tabpanel.name-exposed': ['violating-panel-name'],
'tabs.tabpanel.active-state-matches': [
'violating-panel-active-hidden',
+ 'violating-panel-active-clipped',
'violating-panel-active-transparent',
'violating-panel-inactive-visible',
],
'tabs.selection.exposed': [
'violating-selection-two',
'violating-selection-active-css-hidden',
+ 'violating-selection-active-clipped',
'violating-selection-active-transparent',
'violating-selection-inactive-css-visible',
],
@@ -670,6 +707,7 @@ export const TABS_MUTATIONS: Readonly<Record<string, readonly string[]>> = {
'violating-arrow-one-way',
],
'tabs.focus.wraps-ends': [
+ 'violating-two-tab-arrow-no-wrap',
'violating-arrow-no-wrap',
'violating-rtl-arrow-no-wrap',
],
@@ -740,6 +778,8 @@ const EXPECTED_MUTATION_FAILURES: Readonly<Record<string, string>> = {
'the browser computes no accessible name for this tabpanel',
'tabs.tabpanel.active-state-matches:violating-panel-active-hidden':
'the binding declares this tabpanel active, but the browser reports it hidden',
+ 'tabs.tabpanel.active-state-matches:violating-panel-active-clipped':
+ 'the binding declares this tabpanel active, but the browser reports it hidden',
'tabs.tabpanel.active-state-matches:violating-panel-active-transparent':
'the binding declares this tabpanel active, but the browser reports it hidden',
'tabs.tabpanel.active-state-matches:violating-panel-inactive-visible':
@@ -748,6 +788,8 @@ const EXPECTED_MUTATION_FAILURES: Readonly<Record<string, string>> = {
'expected exactly "first" selected, but the browser exposes "first", "second"',
'tabs.selection.exposed:violating-selection-active-css-hidden':
'the "panel-first" panel is hidden while "first" is selected',
+ 'tabs.selection.exposed:violating-selection-active-clipped':
+ 'the "panel-first" panel is hidden while "first" is selected',
'tabs.selection.exposed:violating-selection-active-transparent':
'the "panel-first" panel is hidden while "first" is selected',
'tabs.selection.exposed:violating-selection-inactive-css-visible':
@@ -760,6 +802,8 @@ const EXPECTED_MUTATION_FAILURES: Readonly<Record<string, string>> = {
'pressing ArrowRight from "first" did not focus the next available tab "second"',
'tabs.focus.arrow-round-trip:violating-arrow-one-way':
'pressing ArrowRight moved to "second", but pressing ArrowLeft did not restore focus to "first"',
+ 'tabs.focus.wraps-ends:violating-two-tab-arrow-no-wrap':
+ 'pressing ArrowLeft outward from "first" did not wrap focus to "second"',
'tabs.focus.wraps-ends:violating-arrow-no-wrap':
'neither ArrowLeft nor ArrowRight wrapped focus from the first tab "first" to the last tab "third"',
'tabs.focus.wraps-ends:violating-rtl-arrow-no-wrap':
diff --git a/internal/a11y-spec/src/patterns/tabs.ts b/internal/a11y-spec/src/patterns/tabs.ts
index b3580c0ad8..a972feeb35 100644
--- a/internal/a11y-spec/src/patterns/tabs.ts
+++ b/internal/a11y-spec/src/patterns/tabs.ts
@@ -3,7 +3,7 @@
/**
* @file tabs.ts
* @input Uses the accessibility contract vocabulary
- * @output TABS_PATTERN and TabsStateFacts
+ * @output TABS_PATTERN and TabsStateFacts, including direction-neutral outward-boundary wrap proof
* @position Reusable accessibility contract for explicit horizontal ARIA Tabs compositions.
*
* This contract covers only a caller-selected `role="tablist"` composition.
@@ -256,6 +256,24 @@ async function assertEndWrap(
}
const first = await harness.related(firstName);
const last = await harness.related(lastName);
+ if (facts.tabRelations.length === 2) {
+ for (const key of ['ArrowLeft', 'ArrowRight'] as const) {
+ await first.focus();
+ await harness.press(key);
+ if (!(await last.isFocused())) {
+ throw new Error(
+ `pressing ${key} outward from "${firstName}" did not wrap focus to "${lastName}"`,
+ );
+ }
+ await harness.press(key);
+ if (!(await first.isFocused())) {
+ throw new Error(
+ `pressing ${key} outward from "${lastName}" did not wrap focus to "${firstName}"`,
+ );
+ }
+ }
+ return;
+ }
const attempts: ReadonlyArray<readonly [Key, Key]> = [
['ArrowLeft', 'ArrowRight'],
['ArrowRight', 'ArrowLeft'],