Skip to content

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

TypeScript

Banner: name the dismiss control after the banner it closes (#5113)

Cindy Zhangd7c163c1d4b8
diff --git a/.changeset/banner-dismiss-accessible-name.md b/.changeset/banner-dismiss-accessible-name.md
new file mode 100644
index 0000000000..928084ddc5
--- /dev/null
+++ b/.changeset/banner-dismiss-accessible-name.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Banner names each dismiss control after its string title, so stacked banners no longer expose identical "Dismiss" buttons to screen readers. Rich titles retain the generic translated name unless the consumer supplies an already-translated `dismissLabel`; that override also labels the tooltip.
+
+@cixzhang
diff --git a/internal/scripts/upload-crowdin-screenshots.mjs b/internal/scripts/upload-crowdin-screenshots.mjs
index 44abdf5c18..06c53ba683 100644
--- a/internal/scripts/upload-crowdin-screenshots.mjs
+++ b/internal/scripts/upload-crowdin-screenshots.mjs
@@ -643,13 +643,20 @@ const TARGETS = [
// ==========================================================================
{
name: 'banner-dismissable',
- // Banner with an × dismiss button (aria-label="Dismiss").
+ // The × button's aria-label now names its banner ("Dismiss <title>"), so
+ // this target tags dismissTitled with the string the story actually
+ // renders; the bare `banner.dismiss` survives as the button's tooltip.
storyId: 'core-banner--dismissable',
viewport: {width: 900, height: 200},
interact: async () => {},
selector: null,
manualTags: [
- t('astryx.banner.dismiss', 'srOnlyReveal', undefined, 'below'),
+ t(
+ 'astryx.banner.dismissTitled',
+ 'srOnlyReveal',
+ 'Dismiss Your session will expire soon.',
+ 'below',
+ ),
],
},
{
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index 8f7625c8f4..370f635837 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -285,7 +285,11 @@
},
"@astryx.banner.dismiss": {
"defaultMessage": "Dismiss",
- "description": "\"Dismiss\" = close/hide this notification (not \"reject a person\"). Aria label AND tooltip on the small X button on a Banner."
+ "description": "\"Dismiss\" = close/hide this notification (not \"reject a person\"). Tooltip on the small X button on a Banner, and its aria label when the banner's title is not plain text."
+ },
+ "@astryx.banner.dismissTitled": {
+ "defaultMessage": "{dismiss} {title}",
+ "description": "Aria label on the small X button on a Banner, naming which banner it closes so stacked banners are distinguishable. `{dismiss}` is the already-translated tooltip text from `banner.dismiss`; keep it verbatim in the message so visible and accessible labels match. `{title}` is the banner's own title text — example: `Dismiss Upload failed`. Reorder the placeholders freely."
},
"@astryx.calendar.previousMonth": {
"defaultMessage": "Previous month",
diff --git a/packages/core/src/Banner/Banner.doc.mjs b/packages/core/src/Banner/Banner.doc.mjs
index bddd09d16f..69448259d2 100644
--- a/packages/core/src/Banner/Banner.doc.mjs
+++ b/packages/core/src/Banner/Banner.doc.mjs
@@ -67,6 +67,12 @@ export const docs = {
description:
'Called when the dismiss button is clicked; banner hides itself regardless of whether this is provided.',
},
+ {
+ name: 'dismissLabel',
+ type: 'string',
+ description:
+ 'Accessible name and visible tooltip for the dismiss button (pass it already translated). Defaults to "Dismiss <title>" for a string title, so stacked banners are distinguishable; set it when the title is a ReactNode.',
+ },
{
name: 'endContent',
type: 'ReactNode',
@@ -165,6 +171,7 @@ export const docsZh = {
{name: 'icon', type: 'ReactNode', description: '覆盖默认的状态图标。'},
{name: 'isDismissable', type: 'boolean', description: '横幅是否可被用户关闭。', default: 'false'},
{name: 'onDismiss', type: '() => void', description: '点击关闭按钮时调用;无论是否提供此回调,横幅都会自动隐藏。'},
+ {name: 'dismissLabel', type: 'string', description: '关闭按钮的无障碍名称和可见工具提示(请传入已翻译的字符串)。字符串标题默认生成“关闭 <标题>”;富文本标题请设置此属性。'},
{name: 'endContent', type: 'ReactNode', description: '渲染在头部区域末端对齐的操作内容,通常是按钮或链接。头部过窄时会整体换行到文本下方,自成一行。'},
{name: 'container', type: "'card' | 'section'", description: '视觉变体:card 带圆角;section 无圆角全宽,适用于页面级场景。', default: "'card'"},
{name: 'elevation', type: "'none' | 'low' | 'med' | 'high'", description: '静止阴影深度。用于悬浮于内容之上的浮动横幅;none 为默认内联横幅。', default: "'none'"},
@@ -241,6 +248,8 @@ export const docsDense = {
icon: 'override default status icon',
isDismissable: 'user can dismiss banner',
onDismiss: 'dismiss callback; banner self-hides regardless',
+ dismissLabel:
+ 'a11y name + visible tooltip for dismiss; defaults to "Dismiss <title>"',
endContent: 'end-aligned action in header, typically button/link; wraps to its own row when the header is too narrow',
container: 'card=border-radius; section=full-width no radius for page-level',
elevation: 'resting shadow depth: none|low|med|high; raise for a floating banner',
diff --git a/packages/core/src/Banner/Banner.test.tsx b/packages/core/src/Banner/Banner.test.tsx
index c092c3e5b2..0ba4d2d4f9 100644
--- a/packages/core/src/Banner/Banner.test.tsx
+++ b/packages/core/src/Banner/Banner.test.tsx
@@ -15,6 +15,7 @@ import {render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {Banner} from './Banner';
import {registerIcons, resetIcons} from '../Icon';
+import {InternationalizationProvider} from '../i18n';
describe('Banner', () => {
afterEach(() => {
@@ -97,7 +98,9 @@ describe('Banner', () => {
it('renders dismiss button when isDismissable', () => {
render(<Banner status="info" title="Dismissable" isDismissable />);
- expect(screen.getByRole('button', {name: 'Dismiss'})).toBeInTheDocument();
+ expect(
+ screen.getByRole('button', {name: 'Dismiss Dismissable'}),
+ ).toBeInTheDocument();
});
it('calls onDismiss when dismiss button is clicked', async () => {
@@ -111,7 +114,7 @@ describe('Banner', () => {
onDismiss={onDismiss}
/>,
);
- await user.click(screen.getByRole('button', {name: 'Dismiss'}));
+ await user.click(screen.getByRole('button', {name: 'Dismiss Dismissable'}));
expect(onDismiss).toHaveBeenCalledTimes(1);
});
@@ -126,7 +129,9 @@ describe('Banner', () => {
/>,
);
expect(screen.getByTestId('banner')).toBeInTheDocument();
- await user.click(screen.getByRole('button', {name: 'Dismiss'}));
+ await user.click(
+ screen.getByRole('button', {name: 'Dismiss Self Dismissing'}),
+ );
expect(screen.queryByTestId('banner')).not.toBeInTheDocument();
});
@@ -142,16 +147,14 @@ describe('Banner', () => {
data-testid="banner"
/>,
);
- await user.click(screen.getByRole('button', {name: 'Dismiss'}));
+ await user.click(screen.getByRole('button', {name: 'Dismiss Dismissable'}));
expect(screen.queryByTestId('banner')).not.toBeInTheDocument();
expect(onDismiss).toHaveBeenCalledTimes(1);
});
it('does not render dismiss button when isDismissable is false', () => {
render(<Banner status="info" title="Not Dismissable" />);
- expect(
- screen.queryByRole('button', {name: 'Dismiss'}),
- ).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', {name: /^Dismiss/})).toBeNull();
});
it('renders endContent', () => {
@@ -235,7 +238,9 @@ describe('Banner', () => {
);
// No toggle exists, so nothing should carry disclosure state, and the
// region needs no id for a button to point at.
- const dismiss = screen.getByRole('button', {name: 'Dismiss'});
+ const dismiss = screen.getByRole('button', {
+ name: 'Dismiss Plain content',
+ });
expect(dismiss).not.toHaveAttribute('aria-expanded');
expect(dismiss).not.toHaveAttribute('aria-controls');
expect(
@@ -343,7 +348,7 @@ describe('Banner', () => {
b => b.getAttribute('aria-label') || b.textContent,
);
const expandIndex = buttonNames.indexOf('Expand');
- const dismissIndex = buttonNames.indexOf('Dismiss');
+ const dismissIndex = buttonNames.indexOf('Dismiss Order Test');
expect(expandIndex).toBeLessThan(dismissIndex);
});
@@ -548,7 +553,9 @@ describe('Banner', () => {
before.focus();
await user.tab();
- expect(screen.getByRole('button', {name: 'Dismiss'})).toHaveFocus();
+ expect(
+ screen.getByRole('button', {name: 'Dismiss Heads up'}),
+ ).toHaveFocus();
await user.keyboard('{Enter}');
@@ -565,7 +572,7 @@ describe('Banner', () => {
<Banner status="info" title="Heads up" isDismissable />
</>,
);
- await user.click(screen.getByRole('button', {name: 'Dismiss'}));
+ await user.click(screen.getByRole('button', {name: 'Dismiss Heads up'}));
expect(screen.queryByRole('status')).not.toBeInTheDocument();
});
});
@@ -650,4 +657,62 @@ describe('Banner', () => {
expect(getComputedStyle(textColumn).flexBasis).not.toBe('8rem');
});
});
+
+ describe('dismiss control naming', () => {
+ it('names stacked string-title banners distinctly', () => {
+ render(
+ <>
+ <Banner status="error" title="Upload invoice failed" isDismissable />
+ <Banner status="error" title="Delete report failed" isDismissable />
+ </>,
+ );
+ const buttons = screen.getAllByRole('button');
+ expect(buttons.map(button => button.getAttribute('aria-label'))).toEqual([
+ 'Dismiss Upload invoice failed',
+ 'Dismiss Delete report failed',
+ ]);
+ for (const button of buttons) {
+ expect(button).toHaveAccessibleDescription('Dismiss');
+ }
+ });
+
+ it('keeps the bare name and tooltip for a rich title', () => {
+ render(
+ <Banner status="info" title={<span>Rich title</span>} isDismissable />,
+ );
+ const button = screen.getByRole('button', {name: 'Dismiss'});
+ expect(button).toHaveAccessibleDescription('Dismiss');
+ });
+
+ it('uses a translated dismissLabel for a rich title and its tooltip', () => {
+ render(
+ <Banner
+ status="info"
+ title={<span>Wartungshinweis</span>}
+ isDismissable
+ dismissLabel="Wartungshinweis schließen"
+ />,
+ );
+ const button = screen.getByRole('button', {
+ name: 'Wartungshinweis schließen',
+ });
+ expect(button).toHaveAccessibleDescription('Wartungshinweis schließen');
+ });
+
+ it('keeps a translated verb when the titled message falls back to English', () => {
+ render(
+ <InternationalizationProvider
+ locale="de-DE"
+ overrides={{
+ 'de-DE': {'@astryx.banner.dismiss': 'Schließen'},
+ }}>
+ <Banner status="info" title="Wartungshinweis" isDismissable />
+ </InternationalizationProvider>,
+ );
+ const button = screen.getByRole('button', {
+ name: 'Schließen Wartungshinweis',
+ });
+ expect(button).toHaveAccessibleDescription('Schließen');
+ });
+ });
});
diff --git a/packages/core/src/Banner/Banner.tsx b/packages/core/src/Banner/Banner.tsx
index 95a6ea5ca8..caad611962 100644
--- a/packages/core/src/Banner/Banner.tsx
+++ b/packages/core/src/Banner/Banner.tsx
@@ -118,6 +118,15 @@ export interface BannerProps extends BaseProps<HTMLDivElement> {
* The banner will hide itself regardless of whether this callback is provided.
*/
onDismiss?: () => void;
+ /**
+ * Accessible name and visible tooltip for the dismiss button, replacing the default.
+ * Pass an already-translated string.
+ *
+ * The default is "Dismiss {title}" when `title` is a string, so stacked
+ * banners are told apart by a screen reader; a non-string `title` falls back
+ * to "Dismiss" and should set this.
+ */
+ dismissLabel?: string;
/**
* Action button rendered in the header area (end-aligned).
* Typically an Button with a secondary or ghost variant.
@@ -440,6 +449,7 @@ export function Banner({
icon,
isDismissable = false,
onDismiss,
+ dismissLabel,
endContent,
container = 'card',
elevation = 'none',
@@ -490,6 +500,15 @@ export function Banner({
const role = statusRole[status] ?? FALLBACK_ROLE;
const iconColor = statusIconColor[status];
const hasChildren = isRenderable(children);
+ // Keep the default tooltip concise while the accessible name identifies
+ // the banner; an explicit translated override names both surfaces.
+ const dismiss = t('@astryx.banner.dismiss');
+ const dismissTooltip = dismissLabel ?? dismiss;
+ const dismissName =
+ dismissLabel ??
+ (typeof title === 'string'
+ ? t('@astryx.banner.dismissTitled', {dismiss, title})
+ : dismiss);
if (isDismissed) {
return null;
@@ -657,8 +676,8 @@ export function Banner({
<Button
variant="ghost"
size="sm"
- label={t('@astryx.banner.dismiss')}
- tooltip={t('@astryx.banner.dismiss')}
+ label={dismissName}
+ tooltip={dismissTooltip}
icon={<Icon icon="close" size="sm" color="inherit" />}
onClick={handleDismiss}
isIconOnly
diff --git a/packages/core/src/Layout/__tests__/edgeCompensation.test.tsx b/packages/core/src/Layout/__tests__/edgeCompensation.test.tsx
index a3d815c1f1..3243080a21 100644
--- a/packages/core/src/Layout/__tests__/edgeCompensation.test.tsx
+++ b/packages/core/src/Layout/__tests__/edgeCompensation.test.tsx
@@ -112,7 +112,7 @@ describe('Edge Compensation', () => {
describe('Banner container compensation', () => {
it('renders dismissable banner with ghost dismiss button', () => {
render(<Banner status="info" title="Test" isDismissable />);
- const dismissButton = screen.getByRole('button', {name: 'Dismiss'});
+ const dismissButton = screen.getByRole('button', {name: 'Dismiss Test'});
expect(dismissButton).toHaveAttribute(EDGE_COMP_ATTR);
});
});