An open source design system that's fully customizable and agent ready
TypeScript
fix(Outline): restore visible keyboard focus (#6920)
Cindy Zhang73a6506d6053
diff --git a/.changeset/outline-visible-focus.md b/.changeset/outline-visible-focus.mdnew file mode 100644index 0000000000..6f23fe45a9--- /dev/null+++ b/.changeset/outline-visible-focus.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Restore Outline's visible keyboard focus indicator.++@cixzhangdiff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 11eb8d7a9e..378d0655e8 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -1157,6 +1157,34 @@ jobs:--project chromium \--output empty-state-announcement-output+ # Outline owns real DOM focus through roving tabindex. Computed paint,+ # pointer modality, clipping, forced colors, and exact pixels require the+ # same real Chromium artifact this blocking accessibility lane already owns.+ - name: Run Outline focus indicator contract+ if: github.event_name == 'pull_request'+ env:+ ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha }}+ run: |+ COMPONENTS=$(node .github/scripts/a11y-pr-scope.mjs analysis.json)+ case ",${COMPONENTS}," in+ *,core/Outline,*)+ pnpm exec playwright test \+ packages/core/src/Outline/OutlineFocus.a11y.chromium.spec.ts \+ --project chromium \+ --output outline-focus-output+ ;;+ *) echo "Outline not in PR scope; skipping focus evidence." ;;+ esac++ - name: Upload Outline focus evidence+ if: always() && github.event_name == 'pull_request'+ uses: actions/upload-artifact@v7+ with:+ name: outline-focus-evidence-${{ needs.build-storybook.outputs.short_hash }}+ path: test-results/outline-focus-evidence/+ retention-days: 30+ if-no-files-found: ignore+# ChatMessageBubble is nested under the shared Chat source directory, so# the generic stable-visual owner cannot select its dedicated fixture.# Run the component's bounded evidence matrix only when the PR scope namesdiff --git a/packages/core/src/Outline/Outline.test.tsx b/packages/core/src/Outline/Outline.test.tsxindex 2ef3a9af2f..fd304d9684 100644--- a/packages/core/src/Outline/Outline.test.tsx+++ b/packages/core/src/Outline/Outline.test.tsx@@ -357,6 +357,21 @@ describe('Outline keyboard navigation', () => {]);});+ it('uses actual DOM focus rather than aria-activedescendant', () => {+ render(<Outline items={items} activeId="intro" />);+ const nav = screen.getByRole('navigation', {name: 'Table of contents'});+ const links = screen.getAllByRole('link');++ act(() => {+ links[2].focus();+ });++ expect(links[2]).toHaveFocus();+ expect(nav).not.toHaveAttribute('aria-activedescendant');+ expect(links[0]).toHaveAttribute('aria-current', 'location');+ expect(links[2]).not.toHaveAttribute('aria-current');+ });+it('seats the tab stop on the active heading, not always the first', () => {// WAI-ARIA roving tabindex: the single tab stop belongs on the *current*// item. Tabbing into a TOC while reading section 3 must land on section 3,diff --git a/packages/core/src/Outline/Outline.tsx b/packages/core/src/Outline/Outline.tsxindex 280d236d71..e2aa14ad25 100644--- a/packages/core/src/Outline/Outline.tsx+++ b/packages/core/src/Outline/Outline.tsx@@ -198,7 +198,6 @@ const styles = stylex.create({},display: 'flex',fontWeight: fontWeightVars['--font-weight-normal'],- outline: 'none',position: 'relative',textAlign: 'start',textDecoration: 'none',diff --git a/packages/core/src/Outline/OutlineFocus.a11y.chromium.spec.ts b/packages/core/src/Outline/OutlineFocus.a11y.chromium.spec.tsnew file mode 100644index 0000000000..bf22e71d03--- /dev/null+++ b/packages/core/src/Outline/OutlineFocus.a11y.chromium.spec.ts@@ -0,0 +1,551 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file OutlineFocus.a11y.chromium.spec.ts+ * @input Uses the built Outline keyboard-navigation Storybook story and real Chromium+ * @output Pixel, computed-style, input-modality, focus-model, and clipping evidence+ * for Outline's keyboard focus indicator+ * @position Browser regression for the focus behavior that DOM emulation cannot paint+ */++import {execFileSync} from 'node:child_process';+import * as fs from 'node:fs';+import * as path from 'node:path';+import {expect, test, type Browser, type Page} from '@playwright/test';+import pixelmatch from 'pixelmatch';+// @ts-expect-error -- pngjs ships no declarations; runtime support is pinned.+import {PNG} from 'pngjs';+import {+ DEFAULT_STORYBOOK_DIR,+ serveStorybook,+ type StaticServer,+} from '@astryxdesign/a11y-spec/storybook';++const OUTPUT = path.resolve('test-results/outline-focus-evidence');+const STORY_ID = 'core-outline--keyboard-navigation';+const BASE_VIEWPORT = {width: 1280, height: 900};++interface FocusPaint {+ readonly text: string;+ readonly tag: string;+ readonly focusVisible: boolean;+ readonly tabIndex: string | null;+ readonly ariaCurrent: string | null;+ readonly ariaActiveDescendant: string | null;+ readonly level: string | null;+ readonly outline: {+ readonly width: string;+ readonly style: string;+ readonly color: string;+ readonly offset: string;+ };+ readonly tokens: {+ readonly width: string;+ readonly style: string;+ readonly color: string;+ readonly offset: string;+ };+ readonly adjacentBackground: string;+ readonly contrast: number;+ readonly clippedBy: ReadonlyArray<string>;+}++interface Receipt {+ readonly target: string;+ readonly state: string;+ readonly theme: 'neutral';+ readonly mode: 'light' | 'dark';+ readonly direction: 'ltr' | 'rtl';+ readonly viewport: {readonly width: number; readonly height: number};+ readonly forcedColors: boolean;+ readonly pageScaleFactor: number;+ readonly browser: string;+ readonly build: string;+ readonly focused: FocusPaint;+ readonly arrowed: FocusPaint;+ readonly pointerFocusVisible: boolean;+ readonly touchFocusVisible: boolean | null;+ readonly restToFocusChangedPixels: number;+ readonly restToArrowChangedPixels: number;+ readonly screenshots: ReadonlyArray<string>;+ readonly video: string;+}++let storybook: StaticServer;+const receipts: Receipt[] = [];+let checkoutSha = '';+let storybookSha = '';++test.beforeAll(async () => {+ checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {+ encoding: 'utf8',+ }).trim();+ if (+ process.env.ASTRYX_HEAD_SHA &&+ process.env.ASTRYX_HEAD_SHA !== checkoutSha+ ) {+ throw new Error('The audited checkout does not match the PR head');+ }+ fs.mkdirSync(OUTPUT, {recursive: true});+ storybook = await serveStorybook(+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,+ );+ const stamp = await fetch(`${storybook.origin}/astryx-build-sha.txt`);+ if (!stamp.ok) {+ throw new Error(+ `The Storybook build has no source stamp (${stamp.status})`,+ );+ }+ storybookSha = (await stamp.text()).trim();+ if (storybookSha !== checkoutSha) {+ throw new Error(+ 'The served Storybook build does not match the audited checkout',+ );+ }+});++test.afterAll(async () => {+ fs.writeFileSync(+ path.join(OUTPUT, 'manifest.json'),+ `${JSON.stringify(+ {+ version: 1,+ component: 'core/Outline',+ checkoutSha,+ storybookSha,+ storyId: STORY_ID,+ statesNotApplicable: {+ selected: 'Outline exposes current location, not selection',+ disabled: 'OutlineItem has no disabled state',+ ariaActiveDescendant:+ 'Outline uses actual DOM focus with roving tabindex instead',+ },+ receipts,+ },+ null,+ 2,+ )}\n`,+ );+ await storybook?.close();+});++function storyUrl(+ origin: string,+ mode: 'light' | 'dark',+ direction: 'ltr' | 'rtl',+): string {+ return `${origin}/iframe.html?id=${STORY_ID}&viewMode=story&globals=astryxTheme:neutral;colorMode:${mode};direction:${direction}`;+}++function parseColor(color: string): [number, number, number, number] {+ const channels = color.match(/[\d.]+/g)?.map(Number) ?? [];+ if (channels.length < 3) {+ throw new Error(`Cannot parse rendered color: ${color}`);+ }+ return [channels[0], channels[1], channels[2], channels[3] ?? 1];+}++function luminance([red, green, blue]: ReadonlyArray<number>): number {+ const linear = [red, green, blue].map(channel => {+ const value = channel / 255;+ return value <= 0.04045+ ? value / 12.92+ : Math.pow((value + 0.055) / 1.055, 2.4);+ });+ return 0.2126 * linear[0] + 0.7152 * linear[1] + 0.0722 * linear[2];+}++function contrast(foreground: string, background: string): number {+ const foregroundLuminance = luminance(parseColor(foreground));+ const backgroundLuminance = luminance(parseColor(background));+ const lighter = Math.max(foregroundLuminance, backgroundLuminance);+ const darker = Math.min(foregroundLuminance, backgroundLuminance);+ return (lighter + 0.05) / (darker + 0.05);+}++async function focusPaint(page: Page): Promise<FocusPaint> {+ const rendered = await page.evaluate(() => {+ const element = document.activeElement;+ if (!(element instanceof HTMLElement)) {+ throw new Error('There is no focused HTMLElement');+ }+ const style = getComputedStyle(element);+ const width = Number.parseFloat(style.outlineWidth);+ const offset = Number.parseFloat(style.outlineOffset);+ const rect = element.getBoundingClientRect();+ const ring = {+ left: rect.left - width - offset,+ right: rect.right + width + offset,+ top: rect.top - width - offset,+ bottom: rect.bottom + width + offset,+ };+ const clippedBy: string[] = [];+ let ancestor = element.parentElement;+ while (ancestor != null) {+ const ancestorStyle = getComputedStyle(ancestor);+ const ancestorRect = ancestor.getBoundingClientRect();+ const clipsX = ['hidden', 'clip', 'scroll', 'auto'].includes(+ ancestorStyle.overflowX,+ );+ const clipsY = ['hidden', 'clip', 'scroll', 'auto'].includes(+ ancestorStyle.overflowY,+ );+ if (+ (clipsX &&+ (ring.left < ancestorRect.left || ring.right > ancestorRect.right)) ||+ (clipsY &&+ (ring.top < ancestorRect.top || ring.bottom > ancestorRect.bottom))+ ) {+ clippedBy.push(+ `${ancestor.tagName}.${ancestor.className || '(no-class)'}`,+ );+ }+ ancestor = ancestor.parentElement;+ }+ let backdrop = element.parentElement;+ let adjacentBackground = 'rgba(0, 0, 0, 0)';+ while (backdrop != null) {+ const candidate = getComputedStyle(backdrop).backgroundColor;+ if (!candidate.endsWith(', 0)') && candidate !== 'transparent') {+ adjacentBackground = candidate;+ break;+ }+ backdrop = backdrop.parentElement;+ }+ return {+ text: element.textContent?.trim() ?? '',+ tag: element.tagName,+ focusVisible: element.matches(':focus-visible'),+ tabIndex: element.getAttribute('tabindex'),+ ariaCurrent: element.getAttribute('aria-current'),+ ariaActiveDescendant:+ element+ .closest('nav')+ ?.querySelector('[aria-activedescendant]')+ ?.getAttribute('aria-activedescendant') ?? null,+ level: element.getAttribute('data-level'),+ outline: {+ width: style.outlineWidth,+ style: style.outlineStyle,+ color: style.outlineColor,+ offset: style.outlineOffset,+ },+ tokens: {+ width: style.getPropertyValue('--focus-outline-width').trim(),+ style: style.getPropertyValue('--focus-outline-style').trim(),+ color: style.getPropertyValue('--focus-outline-color').trim(),+ offset: style.getPropertyValue('--focus-outline-offset').trim(),+ },+ adjacentBackground,+ clippedBy,+ };+ });+ return {+ ...rendered,+ contrast: contrast(rendered.outline.color, rendered.adjacentBackground),+ };+}++function changedPixels(before: Buffer, after: Buffer): number {+ const left = PNG.sync.read(before);+ const right = PNG.sync.read(after);+ expect({width: left.width, height: left.height}).toEqual({+ width: right.width,+ height: right.height,+ });+ return pixelmatch(left.data, right.data, undefined, left.width, left.height, {+ threshold: 0,+ });+}++async function screenshotRegion(page: Page): Promise<Buffer> {+ const box = await page+ .getByRole('navigation', {name: 'Table of contents'})+ .boundingBox();+ if (box == null) {+ throw new Error('Outline has no rendered box');+ }+ const pad = 8;+ return page.screenshot({+ animations: 'disabled',+ clip: {+ x: Math.max(0, Math.floor(box.x - pad)),+ y: Math.max(0, Math.floor(box.y - pad)),+ width: Math.ceil(box.width + 2 * pad),+ height: Math.ceil(box.height + 2 * pad),+ },+ });+}++function expectVisibleTokenRing(paint: FocusPaint): void {+ expect(paint.tag).toBe('A');+ expect(paint.focusVisible).toBe(true);+ expect(paint.outline.width).toBe(paint.tokens.width);+ expect(paint.outline.style).toBe(paint.tokens.style);+ expect(paint.outline.offset).toBe(paint.tokens.offset);+ expect(paint.outline.width).toBe('2px');+ expect(paint.outline.style).toBe('solid');+ expect(paint.outline.offset).toBe('3px');+ expect(paint.outline.color).not.toBe('rgba(0, 0, 0, 0)');+ expect(paint.contrast).toBeGreaterThanOrEqual(3);+ expect(paint.clippedBy).toEqual([]);+ expect(paint.ariaActiveDescendant).toBeNull();+}++interface Scenario {+ readonly state: string;+ readonly mode: 'light' | 'dark';+ readonly direction: 'ltr' | 'rtl';+ readonly viewport: {readonly width: number; readonly height: number};+ readonly forcedColors?: boolean;+ readonly hasTouch?: boolean;+ readonly pageScaleFactor?: number;+}++const SCENARIOS: ReadonlyArray<Scenario> = [+ {+ state: 'default-light',+ mode: 'light',+ direction: 'ltr',+ viewport: BASE_VIEWPORT,+ },+ {+ state: 'default-dark',+ mode: 'dark',+ direction: 'ltr',+ viewport: BASE_VIEWPORT,+ },+ {+ state: 'narrow-rtl-light',+ mode: 'light',+ direction: 'rtl',+ viewport: {width: 320, height: 640},+ },+ {+ state: 'narrow-rtl-dark',+ mode: 'dark',+ direction: 'rtl',+ viewport: {width: 320, height: 640},+ },+ {+ state: 'forced-colors',+ mode: 'light',+ direction: 'ltr',+ viewport: BASE_VIEWPORT,+ forcedColors: true,+ },+ {+ state: 'narrow-touch',+ mode: 'light',+ direction: 'ltr',+ viewport: {width: 320, height: 640},+ hasTouch: true,+ },+ {+ state: 'high-zoom-focus-return',+ mode: 'light',+ direction: 'ltr',+ // 320 CSS px is the WCAG 400% reflow equivalent of the 1280px baseline.+ viewport: {width: 320, height: 640},+ pageScaleFactor: 4,+ },+];++async function runScenario(+ browser: Browser,+ target: {readonly name: string; readonly origin: string},+ scenario: Scenario,+): Promise<string[]> {+ const failures: string[] = [];+ const context = await browser.newContext({+ viewport: scenario.viewport,+ colorScheme: scenario.mode,+ deviceScaleFactor: 1,+ forcedColors: scenario.forcedColors ? 'active' : 'none',+ hasTouch: scenario.hasTouch ?? false,+ isMobile: scenario.hasTouch ?? false,+ recordVideo: {dir: OUTPUT, size: scenario.viewport},+ });+ const page = await context.newPage();+ const video = page.video();+ const prefix = `${target.name}__${scenario.state}`;+ const screenshots = {+ rest: path.join(OUTPUT, `${prefix}__rest.png`),+ focus: path.join(OUTPUT, `${prefix}__focus.png`),+ arrow: path.join(OUTPUT, `${prefix}__arrow.png`),+ pointer: path.join(OUTPUT, `${prefix}__pointer.png`),+ };+ const videoPath = path.join(OUTPUT, `${prefix}.webm`);+ let receipt: Receipt | null = null;+ try {+ await page.goto(+ storyUrl(target.origin, scenario.mode, scenario.direction),+ {+ waitUntil: 'load',+ },+ );+ const nav = page.getByRole('navigation', {name: 'Table of contents'});+ await nav.waitFor({state: 'visible'});+ const links = nav.getByRole('link');+ await expect(links).toHaveCount(6);+ await expect(nav.locator('[aria-current="location"]')).toHaveCount(1);+ await expect(nav.locator('[aria-selected]')).toHaveCount(0);+ await expect(nav.locator('[aria-disabled]')).toHaveCount(0);+ expect(+ await links.evaluateAll(elements =>+ elements.map(element => element.getAttribute('data-level')),+ ),+ ).toEqual(['2', '2', '2', '3', '3', '2']);+ const currentIndex = await links.evaluateAll(elements =>+ elements.findIndex(+ element => element.getAttribute('aria-current') === 'location',+ ),+ );+ expect(currentIndex).toBeGreaterThanOrEqual(0);+ const nextIndex = (currentIndex + 1) % 6;++ if (scenario.pageScaleFactor != null) {+ const cdp = await page.context().newCDPSession(page);+ await cdp.send('Emulation.setPageScaleFactor', {+ pageScaleFactor: scenario.pageScaleFactor,+ });+ expect(await page.evaluate(() => window.visualViewport?.scale ?? 1)).toBe(+ scenario.pageScaleFactor,+ );+ }++ const rest = await screenshotRegion(page);+ fs.writeFileSync(screenshots.rest, rest);++ await page.getByRole('button', {name: 'Focus me, then press Tab'}).focus();+ await page.keyboard.press('Tab');+ const focused = await focusPaint(page);+ const focusedPng = await screenshotRegion(page);+ fs.writeFileSync(screenshots.focus, focusedPng);++ await page.keyboard.press('ArrowDown');+ const arrowed = await focusPaint(page);+ const arrowPng = await screenshotRegion(page);+ fs.writeFileSync(screenshots.arrow, arrowPng);++ const prior = await links.nth(currentIndex).getAttribute('tabindex');+ const current = await links.nth(nextIndex).getAttribute('tabindex');+ expect(prior).toBe('-1');+ expect(current).toBe('0');++ // Focus return uses the roving stop the reader last chose, not the old current item.+ await page.keyboard.press('Shift+Tab');+ await expect(+ page.getByRole('button', {name: 'Focus me, then press Tab'}),+ ).toBeFocused();+ await page.keyboard.press('Tab');+ await expect(links.nth(nextIndex)).toBeFocused();++ // Programmatic focus uses the same actual-DOM-focus model;+ // aria-activedescendant is intentionally absent.+ await links.nth(4).focus();+ await expect(links.nth(4)).toBeFocused();+ await expect(nav.locator('[aria-activedescendant]')).toHaveCount(0);+ await expect(links.nth(currentIndex)).toHaveAttribute(+ 'aria-current',+ 'location',+ );+ await expect(links.nth(4)).not.toHaveAttribute('aria-current');++ const thirdBox = await links.nth(2).boundingBox();+ if (thirdBox == null) {+ throw new Error('The pointer target has no rendered box');+ }+ await page.mouse.click(+ thirdBox.x + thirdBox.width / 2,+ thirdBox.y + thirdBox.height / 2,+ );+ const pointerFocusVisible = await links+ .nth(2)+ .evaluate(element => element.matches(':focus-visible'));+ fs.writeFileSync(screenshots.pointer, await screenshotRegion(page));++ let touchFocusVisible: boolean | null = null;+ if (scenario.hasTouch) {+ const fourthBox = await links.nth(3).boundingBox();+ if (fourthBox == null) {+ throw new Error('The touch target has no rendered box');+ }+ await page.touchscreen.tap(+ fourthBox.x + fourthBox.width / 2,+ fourthBox.y + fourthBox.height / 2,+ );+ touchFocusVisible = await links+ .nth(3)+ .evaluate(element => element.matches(':focus-visible'));+ }++ receipt = {+ target: target.name,+ state: scenario.state,+ theme: 'neutral',+ mode: scenario.mode,+ direction: scenario.direction,+ viewport: scenario.viewport,+ forcedColors: scenario.forcedColors ?? false,+ pageScaleFactor: scenario.pageScaleFactor ?? 1,+ browser: browser.version(),+ build: target.name === 'current-head' ? storybookSha : 'external-preview',+ focused,+ arrowed,+ pointerFocusVisible,+ touchFocusVisible,+ restToFocusChangedPixels: changedPixels(rest, focusedPng),+ restToArrowChangedPixels: changedPixels(rest, arrowPng),+ screenshots: Object.values(screenshots).map(file => path.basename(file)),+ video: path.basename(videoPath),+ };++ const checks = () => {+ expectVisibleTokenRing(focused);+ expect(focused.ariaCurrent).toBe('location');+ expect(focused.tabIndex).toBe('0');+ expect(focused.level).toMatch(/^[1-6]$/);++ expectVisibleTokenRing(arrowed);+ expect(arrowed.ariaCurrent).toBeNull();+ expect(arrowed.tabIndex).toBe('0');+ expect(arrowed.level).toMatch(/^[1-6]$/);++ expect(receipt?.pointerFocusVisible).toBe(false);+ expect(receipt?.touchFocusVisible).not.toBe(true);+ expect(receipt?.restToFocusChangedPixels).toBeGreaterThan(0);+ expect(receipt?.restToArrowChangedPixels).toBeGreaterThan(0);+ };+ try {+ checks();+ } catch (error) {+ failures.push(`${target.name}/${scenario.state}: ${String(error)}`);+ }+ } catch (error) {+ failures.push(`${target.name}/${scenario.state}: ${String(error)}`);+ } finally {+ if (receipt != null) {+ receipts.push(receipt);+ }+ await context.close();+ if (video != null) {+ await video.saveAs(videoPath);+ }+ }+ return failures;+}++test('keeps the actual focused Outline link visibly outlined in every supported context', async ({+ browser,+}) => {+ test.setTimeout(4 * 60 * 1000);+ const failures: string[] = [];+ const targets = [{name: 'current-head', origin: storybook.origin}] as const;+ for (const target of targets) {+ for (const scenario of SCENARIOS) {+ failures.push(...(await runScenario(browser, target, scenario)));+ }+ }+ expect(failures).toEqual([]);+});