Skip to content

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

TypeScript

fix(core): constrain range Slider thumb bounds and fix group labeling (#4356)

Baraa Hamodieea026a90e34
diff --git a/.changeset/a11y-slider-range-aria.md b/.changeset/a11y-slider-range-aria.md
new file mode 100644
index 0000000000..12b7110a40
--- /dev/null
+++ b/.changeset/a11y-slider-range-aria.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Slider: constrain range thumb aria-valuemin/aria-valuemax by the sibling thumb (including minStepsBetweenThumbs) and render the label as a group label wired via aria-labelledby instead of an inert <label htmlFor>
+@bhamodi
diff --git a/packages/core/src/Slider/Slider.test.tsx b/packages/core/src/Slider/Slider.test.tsx
index 3c42856fa6..4532adfedb 100644
--- a/packages/core/src/Slider/Slider.test.tsx
+++ b/packages/core/src/Slider/Slider.test.tsx
@@ -9,6 +9,7 @@
* SYNC: When Slider.tsx changes, update tests to match new behavior
*/
+import {useState} from 'react';
import {describe, it, expect, vi, beforeEach} from 'vitest';
import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
@@ -50,23 +51,17 @@ beforeEach(() => {
describe('Slider', () => {
// --- Aria labels ---
- it('single thumb uses label as aria-label', () => {
+ it('single thumb takes its accessible name from the label', () => {
render(<Slider label="Volume" value={50} />);
const slider = screen.getByRole('slider');
- expect(slider).toHaveAttribute('aria-label', 'Volume');
+ expect(slider).toHaveAccessibleName('Volume');
});
- it('range thumbs have correct aria-labels', () => {
+ it('range thumbs have individual names composing with the group label', () => {
render(<Slider label="Price range" value={[20, 80] as [number, number]} />);
const sliders = screen.getAllByRole('slider');
- expect(sliders[0]).toHaveAttribute(
- 'aria-label',
- 'Price range, minimum value',
- );
- expect(sliders[1]).toHaveAttribute(
- 'aria-label',
- 'Price range, maximum value',
- );
+ expect(sliders[0]).toHaveAccessibleName('Minimum value');
+ expect(sliders[1]).toHaveAccessibleName('Maximum value');
});
it('sets aria-valuetext with formatValue', () => {
@@ -110,6 +105,102 @@ describe('Slider', () => {
const sliders = screen.getAllByRole('slider');
expect(sliders[0]).toHaveAttribute('aria-valuenow', '25');
expect(sliders[1]).toHaveAttribute('aria-valuenow', '75');
+ // Per the APG multi-thumb pattern, each thumb's bounds are constrained by
+ // its sibling: the lower thumb can't exceed the upper thumb's value and
+ // the upper thumb can't go below the lower thumb's value.
+ expect(sliders[0]).toHaveAttribute('aria-valuemin', '0');
+ expect(sliders[0]).toHaveAttribute('aria-valuemax', '75');
+ expect(sliders[1]).toHaveAttribute('aria-valuemin', '25');
+ expect(sliders[1]).toHaveAttribute('aria-valuemax', '100');
+ });
+
+ it('range thumb bounds update after moving a thumb', async () => {
+ const user = userEvent.setup();
+ function ControlledRange() {
+ const [value, setValue] = useState<[number, number]>([25, 75]);
+ return (
+ <Slider
+ label="Range"
+ value={value}
+ onChange={setValue}
+ min={0}
+ max={100}
+ />
+ );
+ }
+ render(<ControlledRange />);
+ const sliders = screen.getAllByRole('slider');
+ act(() => {
+ sliders[0].focus();
+ });
+ await user.keyboard('{ArrowRight}');
+ expect(sliders[0]).toHaveAttribute('aria-valuenow', '26');
+ // The upper thumb's floor tracks the lower thumb's new value.
+ expect(sliders[1]).toHaveAttribute('aria-valuemin', '26');
+ expect(sliders[0]).toHaveAttribute('aria-valuemax', '75');
+ });
+
+ it('range thumb bounds include the minStepsBetweenThumbs gap', () => {
+ render(
+ <Slider
+ label="Range"
+ value={[20, 80] as [number, number]}
+ min={0}
+ max={100}
+ step={5}
+ minStepsBetweenThumbs={2}
+ />,
+ );
+ const sliders = screen.getAllByRole('slider');
+ // minGap = 2 steps * 5 = 10
+ expect(sliders[0]).toHaveAttribute('aria-valuemax', '70');
+ expect(sliders[1]).toHaveAttribute('aria-valuemin', '30');
+ });
+
+ // --- Label association ---
+
+ // A <label htmlFor> must point at an existing form-associated element;
+ // div[role="slider"] is not labelable, so the Slider label must render as a
+ // group label instead (WCAG 1.3.1).
+ const LABELABLE_TAGS = new Set([
+ 'BUTTON',
+ 'INPUT',
+ 'METER',
+ 'OUTPUT',
+ 'PROGRESS',
+ 'SELECT',
+ 'TEXTAREA',
+ ]);
+
+ function expectNoOrphanedLabels(container: HTMLElement) {
+ for (const labelEl of container.querySelectorAll('label[for]')) {
+ const target = document.getElementById(labelEl.getAttribute('for')!);
+ expect(target).not.toBeNull();
+ expect(LABELABLE_TAGS.has(target!.tagName)).toBe(true);
+ }
+ }
+
+ it('single mode renders the label as a group label naming the thumb', () => {
+ const {container} = render(<Slider label="Volume" value={50} />);
+ expectNoOrphanedLabels(container);
+ const slider = screen.getByRole('slider');
+ const labelledBy = slider.getAttribute('aria-labelledby');
+ expect(labelledBy).toBeTruthy();
+ expect(document.getElementById(labelledBy!)).toHaveTextContent('Volume');
+ expect(slider).toHaveAccessibleName('Volume');
+ });
+
+ it('range mode labels the slider group via aria-labelledby', () => {
+ const {container} = render(
+ <Slider label="Price range" value={[20, 80] as [number, number]} />,
+ );
+ expectNoOrphanedLabels(container);
+ const group = screen.getByRole('group', {name: 'Price range'});
+ const labelledBy = group.getAttribute('aria-labelledby');
+ expect(labelledBy).toBeTruthy();
+ expect(document.getElementById(labelledBy!)).toHaveTextContent(
+ 'Price range',
+ );
});
it('sets aria-orientation for vertical', () => {
diff --git a/packages/core/src/Slider/Slider.tsx b/packages/core/src/Slider/Slider.tsx
index 4c6a30cb3b..6245268939 100644
--- a/packages/core/src/Slider/Slider.tsx
+++ b/packages/core/src/Slider/Slider.tsx
@@ -392,6 +392,7 @@ export function Slider({ref, ...props}: SliderProps) {
const isHorizontal = orientation === 'horizontal';
const id = useId();
+ const labelID = useId();
const descriptionID = useId();
const statusMessageID = useId();
const requiredID = useId();
@@ -695,11 +696,25 @@ export function Slider({ref, ...props}: SliderProps) {
? {left: `${percent}%`}
: {bottom: `${percent}%`, left: '50%'};
+ // In range mode each thumb keeps a short individual name that composes
+ // with the group label (announced via the group's aria-labelledby), per
+ // the APG multi-thumb slider pattern. In single mode the thumb takes its
+ // name from the visible label element via aria-labelledby.
const thumbLabel = isRange
? thumbIndex === 0
- ? `${label}, minimum value`
- : `${label}, maximum value`
- : label;
+ ? 'Minimum value'
+ : 'Maximum value'
+ : undefined;
+
+ // ARIA bounds must agree with the movement clamping in updateValue: in
+ // range mode a thumb can't cross its sibling (minus the
+ // minStepsBetweenThumbs gap), and the result is always clamped to
+ // [min, max].
+ const minGap = minStepsBetweenThumbs * step;
+ const ariaValueMin =
+ isRange && thumbIndex === 1 ? clamp(values[0] + minGap, min, max) : min;
+ const ariaValueMax =
+ isRange && thumbIndex === 0 ? clamp(values[1] - minGap, min, max) : max;
// Suppress the per-thumb value bubble while the disabled-message tooltip is
// showing, so a disabled slider surfaces the *reason* on hover/focus rather
@@ -716,14 +731,15 @@ export function Slider({ref, ...props}: SliderProps) {
// focus-discoverable; value changes stay blocked by the isDisabled
// guards in the pointer/keyboard handlers.
tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
- aria-valuemin={min}
- aria-valuemax={max}
+ aria-valuemin={ariaValueMin}
+ aria-valuemax={ariaValueMax}
aria-valuenow={val}
aria-valuetext={formatValue ? formatValue(val) : undefined}
aria-orientation={orientation}
aria-disabled={isDisabled || undefined}
aria-invalid={status?.type === 'error' ? true : undefined}
aria-label={thumbLabel}
+ aria-labelledby={!isRange ? labelID : undefined}
aria-describedby={ariaDescribedBy}
onKeyDown={e => handleKeyDown(thumbIndex, e)}
{...mergeProps(
@@ -796,6 +812,14 @@ export function Slider({ref, ...props}: SliderProps) {
isLabelHidden={isLabelHidden}
description={description}
inputID={id}
+ labelID={labelID}
+ // The thumb is a div[role="slider"], which a <label htmlFor> can't
+ // name (only form-associated elements are labelable). Render the label
+ // as a group label and associate it via aria-labelledby instead: the
+ // single thumb references it directly, and in range mode the
+ // role="group" container references it while each thumb keeps its own
+ // "Minimum value"/"Maximum value" name.
+ isGroupLabel
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}
@@ -838,7 +862,9 @@ export function Slider({ref, ...props}: SliderProps) {
))}
<div
ref={mergeRefs(ref, trackRef, disabledMessageTooltip.ref)}
- {...(isRange ? {role: 'group', 'aria-label': label} : undefined)}
+ {...(isRange
+ ? {role: 'group', 'aria-labelledby': labelID}
+ : undefined)}
onPointerDown={handlePointerDown}
onPointerMove={handlePointerMove}
onPointerUp={handlePointerUp}