Skip to content

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

TypeScript

fix(core): add role="tooltip" to the Tooltip layer (#3243)

Durvesh Pilankare839b09feb0b
diff --git a/.changeset/tooltip-role-a11y.md b/.changeset/tooltip-role-a11y.md
new file mode 100644
index 0000000000..b1bbc8080e
--- /dev/null
+++ b/.changeset/tooltip-role-a11y.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Tooltip and HoverCard: add ARIA roles to the floating layers — `role="tooltip"` on Tooltip (completing the ARIA tooltip pattern; the trigger already links via `aria-describedby`) and `role="dialog"` on HoverCard. Plumbed via a new optional `role` on the layer render props. (#3240; Popover already exposes `role="dialog"`.)
+@durvesh1992
diff --git a/packages/core/src/HoverCard/HoverCard.test.tsx b/packages/core/src/HoverCard/HoverCard.test.tsx
index fdb75f311e..7b22faa540 100644
--- a/packages/core/src/HoverCard/HoverCard.test.tsx
+++ b/packages/core/src/HoverCard/HoverCard.test.tsx
@@ -58,6 +58,17 @@ describe('HoverCard', () => {
expect(screen.getByRole('button', {name: 'Trigger'})).toBeInTheDocument();
});
+ it('gives the floating layer role="dialog"', () => {
+ render(
+ <HoverCard content={<span>Card content</span>}>
+ <button type="button">Trigger</button>
+ </HoverCard>,
+ );
+ expect(screen.getByRole('dialog', {hidden: true})).toHaveTextContent(
+ 'Card content',
+ );
+ });
+
it('wraps element children in an inline-safe span', () => {
const {container} = render(
<p>
diff --git a/packages/core/src/HoverCard/useHoverCard.tsx b/packages/core/src/HoverCard/useHoverCard.tsx
index decd4ddc86..faac7c6096 100644
--- a/packages/core/src/HoverCard/useHoverCard.tsx
+++ b/packages/core/src/HoverCard/useHoverCard.tsx
@@ -455,6 +455,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
const renderProps = {
placement: renderPlacement,
alignment: props?.alignment ?? alignment,
+ role: 'dialog',
xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
// Render the layer as inline-safe phrasing markup so HoverCard stays
// valid (and hydration-stable) inside inline contexts like a `<p>`.
diff --git a/packages/core/src/Layer/useLayer.tsx b/packages/core/src/Layer/useLayer.tsx
index e25d3a1d75..f08e7b0bfb 100644
--- a/packages/core/src/Layer/useLayer.tsx
+++ b/packages/core/src/Layer/useLayer.tsx
@@ -66,6 +66,12 @@ export type LayerAlignment = 'start' | 'center' | 'end';
export interface ContextRenderProps {
placement?: LayerPlacement;
alignment?: LayerAlignment;
+ /**
+ * ARIA role applied to the popover container (e.g. `'tooltip'`). Lets
+ * consumers complete the ARIA pattern and gives test tooling a stable,
+ * non-hashed selector for the layer.
+ */
+ role?: string;
/**
* StyleX styles for the popover container.
*/
@@ -378,6 +384,7 @@ export function useLayer(
const {
placement = 'above',
alignment = 'center',
+ role,
xstyle,
className: extraClassName,
style: extraStyle,
@@ -403,6 +410,7 @@ export function useLayer(
<Container
ref={popoverRefCallback}
id={id}
+ role={role}
popover={lightDismiss ? 'auto' : 'manual'}
className={combinedClassName}
style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}>
diff --git a/packages/core/src/Tooltip/Tooltip.test.tsx b/packages/core/src/Tooltip/Tooltip.test.tsx
index c686e93ea8..bd3067016f 100644
--- a/packages/core/src/Tooltip/Tooltip.test.tsx
+++ b/packages/core/src/Tooltip/Tooltip.test.tsx
@@ -55,6 +55,19 @@ describe('Tooltip', () => {
expect(screen.getByRole('button', {name: 'Trigger'})).toBeInTheDocument();
});
+ it('gives the tooltip layer role="tooltip" linked from the trigger', () => {
+ render(
+ <Tooltip content="Tooltip text">
+ <button type="button">Trigger</button>
+ </Tooltip>,
+ );
+ const layer = screen.getByRole('tooltip', {hidden: true});
+ expect(layer).toHaveTextContent('Tooltip text');
+ // ARIA tooltip pattern: trigger references the layer via aria-describedby.
+ const trigger = screen.getByRole('button', {name: 'Trigger'});
+ expect(trigger.getAttribute('aria-describedby')).toBe(layer.id);
+ });
+
it('calls onOpenChange(true) when shown via hover', async () => {
const onOpenChange = vi.fn();
render(
diff --git a/packages/core/src/Tooltip/useTooltip.tsx b/packages/core/src/Tooltip/useTooltip.tsx
index 783def0ada..e66a30c9d6 100644
--- a/packages/core/src/Tooltip/useTooltip.tsx
+++ b/packages/core/src/Tooltip/useTooltip.tsx
@@ -233,9 +233,7 @@ function isFocusable(element: HTMLElement): boolean {
* {tooltip.renderTooltip('Helpful tooltip text')}
* ```
*/
-export function useTooltip(
- options: TooltipOptions = {},
-): TooltipReturn {
+export function useTooltip(options: TooltipOptions = {}): TooltipReturn {
const {
placement = 'above',
alignment = 'center',
@@ -429,6 +427,7 @@ export function useTooltip(
const renderProps = {
placement: renderPlacement,
alignment: props?.alignment ?? alignment,
+ role: 'tooltip',
xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
className: themeProps('tooltip').className,
};