Skip to content

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

TypeScript

fix(ChatLayout): release hidden scroll affordance focus (#7738)

Cindy Zhang95e1674ce1df
diff --git a/.changeset/chat-scroll-affordance-focus.md b/.changeset/chat-scroll-affordance-focus.md
new file mode 100644
index 0000000000..a2d155bd50
--- /dev/null
+++ b/.changeset/chat-scroll-affordance-focus.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `ChatLayoutScrollButton`: the scroll-to-bottom pill now gives up keyboard focus, and refuses new focus, as soon as it starts to hide. Previously focus stayed on the fading pill for about half a second, until `visibility: hidden` applied, so it could sit on a control that was fading out or already transparent (WCAG 2.2 SC 2.4.7 Focus Visible). (#7738)
+
+@cixzhang
diff --git a/packages/core/src/Chat/ChatLayoutScrollButton.test.tsx b/packages/core/src/Chat/ChatLayoutScrollButton.test.tsx
index edb9d77b57..d365e84bbb 100644
--- a/packages/core/src/Chat/ChatLayoutScrollButton.test.tsx
+++ b/packages/core/src/Chat/ChatLayoutScrollButton.test.tsx
@@ -70,6 +70,19 @@ describe('ChatLayoutScrollButton', () => {
).toHaveFocus();
});
+ it('makes the pill inert whenever the visible state turns off', () => {
+ const {container, rerender} = render(
+ <ChatLayoutScrollButton isVisible onClick={() => {}} />,
+ );
+ const pill = container.querySelector('.astryx-chat-layout-scroll-button');
+
+ expect(pill).not.toHaveAttribute('inert');
+
+ rerender(<ChatLayoutScrollButton isVisible={false} onClick={() => {}} />);
+
+ expect(pill).toHaveAttribute('inert');
+ });
+
it('is not keyboard reachable while hidden', async () => {
const user = userEvent.setup();
render(
diff --git a/packages/core/src/Chat/ChatLayoutScrollButton.tsx b/packages/core/src/Chat/ChatLayoutScrollButton.tsx
index f79025b815..70d7b9afd1 100644
--- a/packages/core/src/Chat/ChatLayoutScrollButton.tsx
+++ b/packages/core/src/Chat/ChatLayoutScrollButton.tsx
@@ -86,8 +86,9 @@ const styles = stylex.create({
opacity: 0,
pointerEvents: 'none',
// The hidden pill paints nothing, so focus landing on it would have no
- // visible indicator (WCAG 2.2 SC 2.4.7). `opacity` and `pointer-events`
- // leave the button in sequential focus navigation; `visibility` removes it.
+ // visible indicator (WCAG 2.2 SC 2.4.7). `visibility` removes it from
+ // sequential navigation after the fade; `inert` immediately prevents new
+ // focus and makes an already-focused descendant relinquish focus.
visibility: 'hidden',
maxWidth: sizeVars['--size-element-md'],
},
@@ -151,6 +152,7 @@ export function ChatLayoutScrollButton({
{...mergeProps(stylex.props(styles.wrapper, xstyle), className, style)}
{...rest}>
<div
+ inert={!isVisible}
{...mergeProps(
themeProps('chat-layout-scroll-button'),
stylex.props(
diff --git a/packages/core/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts b/packages/core/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts
index 7ff56b2772..893cda96ce 100644
--- a/packages/core/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts
+++ b/packages/core/src/Chat/__tests__/ChatLayoutScrollButton.a11y.chromium.spec.ts
@@ -44,6 +44,7 @@ const STORY_ID = 'core-chatlayout--scroll-affordance-states';
* a stable handle for it.
*/
const PILL = '.astryx-chat-layout-scroll-button';
+const AFFORDANCE = `${PILL} button`;
/** One observed tab stop, identified structurally rather than by its text. */
type FocusStop = {
@@ -126,7 +127,11 @@ test.afterAll(async () => {
async function openStory(
page: Page,
- {theme = 'neutral', colorMode = 'light'} = {},
+ {
+ theme = 'neutral',
+ colorMode = 'light',
+ holdMotion = true,
+ }: {theme?: string; colorMode?: string; holdMotion?: boolean} = {},
): Promise<Locator> {
page.on('pageerror', error => pageErrors.push(String(error)));
browserVersion = page.context().browser()?.version() ?? 'unknown';
@@ -136,7 +141,9 @@ async function openStory(
);
const root = page.locator('.astryx-chat-layout');
await root.waitFor({state: 'visible'});
- await holdMotionStill(page);
+ if (holdMotion) {
+ await holdMotionStill(page);
+ }
await page.evaluate(async () => document.fonts.ready);
return root;
}
@@ -169,21 +176,25 @@ async function pillVisibility(page: Page): Promise<string> {
}
/**
- * Can the affordance take focus at all? This is the mechanism under test:
- * `visibility: hidden` removes an element from sequential focus navigation AND
- * refuses programmatic focus, which `opacity: 0` does neither of. A CSS locator
- * is used rather than a role query because a hidden button is not in the
- * accessibility tree and a role query would not resolve it.
+ * Can the affordance take new focus at all? This is one half of the mechanism
+ * under test: `inert` refuses programmatic focus immediately, while delayed
+ * `visibility: hidden` removes the control from sequential navigation after the
+ * fade. A CSS locator is used rather than a role query because a hidden button
+ * is not in the accessibility tree and a role query would not resolve it.
*/
-async function affordanceAcceptsFocus(page: Page): Promise<boolean> {
- return page
- .locator('.astryx-chat-layout-scroll-button button')
- .evaluate(element => {
- // preventScroll: focusing must not move the scroll position, or the
- // probe would change the very state the next assertion reads.
- (element as HTMLElement).focus({preventScroll: true});
- return document.activeElement === element;
- });
+async function affordanceAcceptsFocus(
+ page: Page,
+ resetFocus: Locator,
+): Promise<boolean> {
+ // Start outside the affordance so this probe proves a NEW focus transfer;
+ // equality alone would also be true when a button stayed active as it hid.
+ await resetFocus.focus();
+ return page.locator(AFFORDANCE).evaluate(element => {
+ // preventScroll: focusing must not move the scroll position, or the
+ // probe would change the very state the next assertion reads.
+ (element as HTMLElement).focus({preventScroll: true});
+ return document.activeElement === element;
+ });
}
/**
@@ -340,6 +351,36 @@ async function capture(
return receipt;
}
+test('the hiding affordance releases focus before its fade finishes', async ({
+ page,
+}) => {
+ const root = await openStory(page, {holdMotion: false});
+ const pill = page.locator(PILL);
+ const affordance = page.locator(AFFORDANCE);
+
+ await scrollToTop(root);
+ await expect(pill).toHaveCSS('visibility', 'visible');
+ await affordance.focus();
+ await expect(affordance).toBeFocused();
+
+ await page.keyboard.press('Enter');
+ await expect
+ .poll(
+ async () =>
+ affordance.evaluate(element => document.activeElement === element),
+ {timeout: 5000},
+ )
+ .toBe(false);
+
+ // `visibility` flips only after the fade. Focus leaving while it is still
+ // visible proves the immediate `inert` state rather than the delayed CSS.
+ await expect(pill).toHaveCSS('visibility', 'visible');
+ await expect
+ .poll(async () => distanceFromBottom(root), {timeout: 5000})
+ .toBeLessThan(2);
+ await expect(pill).toHaveCSS('visibility', 'hidden');
+});
+
test('the scroll affordance is keyboard reachable exactly while it is visible', async ({
page,
}) => {
@@ -367,7 +408,7 @@ test('the scroll affordance is keyboard reachable exactly while it is visible',
expect(await distanceFromBottom(root)).toBeLessThan(2);
await expect(pill).toHaveCSS('visibility', 'hidden');
expect(
- await affordanceAcceptsFocus(page),
+ await affordanceAcceptsFocus(page, before),
'a control that paints nothing must refuse focus (WCAG 2.2 SC 2.4.7)',
).toBe(false);
const restFrame = await capture(page, 'rest-hidden', {
@@ -384,7 +425,7 @@ test('the scroll affordance is keyboard reachable exactly while it is visible',
await expect(pill).toHaveCSS('visibility', 'visible');
expect(await distanceFromBottom(root)).toBeGreaterThan(100);
expect(
- await affordanceAcceptsFocus(page),
+ await affordanceAcceptsFocus(page, before),
'the visible affordance must keep its keyboard access',
).toBe(true);
await expect(
@@ -415,8 +456,12 @@ test('the scroll affordance is keyboard reachable exactly while it is visible',
.poll(async () => distanceFromBottom(root), {timeout: 5000})
.toBeLessThan(2);
await expect(pill).toHaveCSS('visibility', 'hidden');
+ await expect(
+ page.locator(AFFORDANCE),
+ 'the affordance must relinquish focus when it hides',
+ ).not.toBeFocused();
expect(
- await affordanceAcceptsFocus(page),
+ await affordanceAcceptsFocus(page, before),
'after returning to the bottom the affordance must refuse focus again',
).toBe(false);
const returnedFrame = await capture(page, 'returned-hidden', {