Skip to content

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

TypeScript

fix(DateTimeInput, TimeInput): silence the busy Spinner and announce the busy start once (#7942)

Cindy Zhangec8c3c9f7d11
diff --git a/.changeset/datetime-time-inputs-busy-announces-once.md b/.changeset/datetime-time-inputs-busy-announces-once.md
new file mode 100644
index 0000000000..b97040a37e
--- /dev/null
+++ b/.changeset/datetime-time-inputs-busy-announces-once.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `DateTimeInput` and `TimeInput` (popover, native and bottom-sheet presentations) announce their busy start ("Loading") once, politely, through the shared announcement channel, and the Spinner they show while busy is hidden from assistive technology (`spec:AST-086` FR6, FR8). Before, that Spinner mounted as its own `role="status"` region already named "Loading", which screen readers often skip, and it was a second owner beside the field's `aria-busy`. A change made inside the open bottom sheet under a pending `changeAction` is announced from inside the sheet. Tests that found the busy Spinner with `getByRole('status', {name: 'Loading'})` should check the field's `aria-busy` instead.
+
+@cixzhang
diff --git a/packages/core/src/DateTimeInput/DateTimeInput.tsx b/packages/core/src/DateTimeInput/DateTimeInput.tsx
index c2c069b974..a5b5bc294b 100644
--- a/packages/core/src/DateTimeInput/DateTimeInput.tsx
+++ b/packages/core/src/DateTimeInput/DateTimeInput.tsx
@@ -65,6 +65,7 @@ import {useCalendarConstraints} from '../Calendar/hooks';
import {usePopover} from '../Popover';
import {useTooltip} from '../Tooltip';
import {useInputContainer} from '../hooks/useInputContainer';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
import {
type ISOTimeString,
@@ -709,6 +710,9 @@ function PointerDateTimeField({
const [optimisticValue, setOptimisticValue] = useOptimistic(value);
const isPendingChange = optimisticValue !== value;
const isBusy = isLoading || isPendingChange;
+ // The busy Spinner is decorative; this control announces its busy start
+ // (spec:AST-086 FR8).
+ useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), dateInputRef);
// A native wheel emits several edits while it remains open. Disabling the
// control after the first optimistic edit detaches the iOS picker, so pending
// changeAction work stays interactive just like TouchDateTimeField. Explicit
@@ -1801,7 +1805,7 @@ function PointerDateTimeField({
onClick={handleClear}
/>
)}
- {isBusy && <Spinner size="sm" />}
+ {isBusy && <Spinner size="sm" aria-hidden="true" />}
{statusIcon}
</div>
diff --git a/packages/core/src/DateTimeInput/TouchDateTimeField.tsx b/packages/core/src/DateTimeInput/TouchDateTimeField.tsx
index aae238a05b..654dcecdd2 100644
--- a/packages/core/src/DateTimeInput/TouchDateTimeField.tsx
+++ b/packages/core/src/DateTimeInput/TouchDateTimeField.tsx
@@ -47,6 +47,7 @@ import {
} from '../Field';
import {useInputStatusIcon, useMergedRefs} from '../hooks';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {Icon} from '../Icon';
import {IconButton} from '../IconButton';
import {useTranslator, InternationalizationContext} from '../i18n';
@@ -576,6 +577,15 @@ export function TouchDateTimeField({
});
const [isSheetOpen, setIsSheetOpen] = useState(false);
+ const sheetBodyRef = useRef<HTMLDivElement | null>(null);
+ // The busy Spinner is decorative; this control announces its busy start
+ // (spec:AST-086 FR8). A change made in the open modal sheet starts it while
+ // the sheet is open, so it is announced from inside the sheet.
+ useBusyAnnouncement(
+ isBusy,
+ t('@astryx.spinner.loading'),
+ isSheetOpen ? sheetBodyRef : dateInputRef,
+ );
const [activePanel, setActivePanel] = useState<TouchDateTimePanel>('date');
const [isWheelOpen, setIsWheelOpen] = useState(false);
const [draftTime, setDraftTime] = useState<ISOTimeString | undefined>(() =>
@@ -1412,7 +1422,7 @@ export function TouchDateTimeField({
onClick={handleClear}
/>
)}
- {isBusy && <Spinner size="sm" />}
+ {isBusy && <Spinner size="sm" aria-hidden="true" />}
{isRenderable(statusIcon) && statusIcon}
</div>
@@ -1497,7 +1507,9 @@ export function TouchDateTimeField({
// touchSheetBody owns the inset, including the band under the grab
// handle.
padding={0}>
- <div {...stylex.props(styles.touchSheetBody)}>{surface}</div>
+ <div ref={sheetBodyRef} {...stylex.props(styles.touchSheetBody)}>
+ {surface}
+ </div>
</BottomSheet>
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
diff --git a/packages/core/src/TimeInput/TimeInput.tsx b/packages/core/src/TimeInput/TimeInput.tsx
index d0e3531ea8..afa1fee1df 100644
--- a/packages/core/src/TimeInput/TimeInput.tsx
+++ b/packages/core/src/TimeInput/TimeInput.tsx
@@ -70,6 +70,7 @@ import {
import type {SizeValue} from '../utils/types';
import {useSize} from '../SizeContext/SizeContext';
import {useAnnounce} from '../hooks/useAnnounce';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {useInputContainer} from '../hooks/useInputContainer';
import {useMediaQuery} from '../hooks/useMediaQuery';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
@@ -475,6 +476,9 @@ function TimeField({
const [, startTransition] = useTransition();
const [optimisticValue, setOptimisticValue] = useOptimistic(value);
const isBusy = isLoading || optimisticValue !== value;
+ // The busy Spinner is decorative; this control announces its busy start
+ // (spec:AST-086 FR8).
+ useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), containerRef);
// In grouped mode the status message renders as a visually-hidden node that
// exists only for aria-describedby. Announce it through the persistent
@@ -865,7 +869,7 @@ function TimeField({
</VisuallyHidden>
</>
)}
- {isBusy && <Spinner size="sm" />}
+ {isBusy && <Spinner size="sm" aria-hidden="true" />}
{hasClear && optimisticValue && !isDisabled && (
<InputClearButton
label={t('@astryx.timeInput.clearLabel', {label})}
diff --git a/packages/core/src/TimeInput/TouchTimeField.tsx b/packages/core/src/TimeInput/TouchTimeField.tsx
index 69461ba520..e0c98e7b2f 100644
--- a/packages/core/src/TimeInput/TouchTimeField.tsx
+++ b/packages/core/src/TimeInput/TouchTimeField.tsx
@@ -42,6 +42,7 @@ import {useFieldInputStyling} from '../Field/fieldParts';
import {joinAriaIDs} from '../utils/inputAria';
import {groupStyles} from '../InputGroup/groupStyles';
import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {Icon} from '../Icon';
@@ -254,6 +255,15 @@ export function TouchTimeField({
const [, startTransition] = useTransition();
const [optimisticValue, setOptimisticValue] = useOptimistic(value);
const isBusy = isLoading || optimisticValue !== value;
+ const sheetBodyRef = useRef<HTMLDivElement | null>(null);
+ // The busy Spinner is decorative; this control announces its busy start
+ // (spec:AST-086 FR8). A change made in the open modal sheet starts it while
+ // the sheet is open, so it is announced from inside the sheet.
+ useBusyAnnouncement(
+ isBusy,
+ t('@astryx.spinner.loading'),
+ isSheetOpen ? sheetBodyRef : inputRef,
+ );
const isEffectivelyDisabled = isDisabled || isLoading;
const showsDisabledMessage = isDisabled && !!disabledMessage;
@@ -516,7 +526,7 @@ export function TouchTimeField({
}
{...stylex.props(styles.input)}
/>
- {isBusy && <Spinner size="sm" />}
+ {isBusy && <Spinner size="sm" aria-hidden="true" />}
{hasClear && optimisticValue && !isEffectivelyDisabled && (
<InputClearButton
label={t('@astryx.timeInput.clearLabel', {label})}
@@ -531,7 +541,7 @@ export function TouchTimeField({
height="hug"
// sheetBody owns the inset, including the band under the grab handle.
padding={0}>
- <div {...stylex.props(styles.sheetBody)}>
+ <div ref={sheetBodyRef} {...stylex.props(styles.sheetBody)}>
<div {...stylex.props(styles.wheels)}>
<Wheel
label={t('@astryx.dateTimeInput.hourWheel')}
diff --git a/packages/core/src/__tests__/BusyOwnerAnnouncement.test.tsx b/packages/core/src/__tests__/BusyOwnerAnnouncement.test.tsx
index 0b185e53ba..d1a4a4468a 100644
--- a/packages/core/src/__tests__/BusyOwnerAnnouncement.test.tsx
+++ b/packages/core/src/__tests__/BusyOwnerAnnouncement.test.tsx
@@ -19,7 +19,7 @@ import {
it,
vi,
} from 'vitest';
-import {act, fireEvent, render, screen} from '@testing-library/react';
+import {act, fireEvent, render, screen, within} from '@testing-library/react';
import {TextInput} from '../TextInput';
import {TextArea} from '../TextArea';
import {Selector} from '../Selector';
@@ -27,8 +27,11 @@ import {MultiSelector} from '../MultiSelector';
import {ComplexSelector} from '../ComplexSelector';
import {DateInput} from '../DateInput';
import {DateRangeInput} from '../DateRangeInput';
+import {DateTimeInput} from '../DateTimeInput';
+import {TimeInput} from '../TimeInput';
import {BaseTypeahead, Typeahead} from '../Typeahead';
import type {SearchableItem, SearchSource} from '../Typeahead';
+import type {ISOTimeString} from '../utils';
import {Tokenizer} from '../Tokenizer';
const announce = vi.fn();
@@ -104,6 +107,30 @@ const OWNERS: ReadonlyArray<
),
] as const,
),
+ ...(['popover', 'native', 'bottom-sheet'] as const).flatMap(presentation => [
+ [
+ `DateTimeInput (${presentation})`,
+ (isLoading: boolean) => (
+ <DateTimeInput
+ label="When"
+ presentation={presentation}
+ onChange={() => {}}
+ isLoading={isLoading}
+ />
+ ),
+ ] as const,
+ [
+ `TimeInput (${presentation})`,
+ (isLoading: boolean) => (
+ <TimeInput
+ label="Time"
+ presentation={presentation}
+ onChange={() => {}}
+ isLoading={isLoading}
+ />
+ ),
+ ] as const,
+ ]),
[
'DateRangeInput',
isLoading => (
@@ -367,3 +394,77 @@ describe.each(SEARCH_OWNERS)(
});
},
);
+
+/**
+ * Bottom-sheet fields whose sheet stays open while a changeAction is pending:
+ * the sheet is a modal dialog, so the busy start must be announced inside it.
+ */
+const SHEET_OWNERS: ReadonlyArray<
+ readonly [
+ string,
+ (changeAction: () => Promise<void>) => ReactElement,
+ () => void,
+ ]
+> = [
+ [
+ 'TimeInput',
+ changeAction => (
+ <TimeInput
+ label="Time"
+ presentation="bottom-sheet"
+ value={'09:00' as ISOTimeString}
+ onChange={() => {}}
+ changeAction={changeAction}
+ />
+ ),
+ () => {
+ fireEvent.click(screen.getByRole('button', {name: /Time/}));
+ },
+ ],
+];
+
+describe.each(SHEET_OWNERS)(
+ '%s busy start from inside its open sheet (spec:AST-086 Platform support)',
+ (_name, renderOwner, openSheet) => {
+ beforeEach(() => {
+ HTMLDialogElement.prototype.showModal = vi.fn(function (
+ this: HTMLDialogElement,
+ ) {
+ this.setAttribute('open', '');
+ });
+ HTMLDialogElement.prototype.close = vi.fn(function (
+ this: HTMLDialogElement,
+ ) {
+ this.removeAttribute('open');
+ });
+ const matches = Element.prototype.matches;
+ vi.spyOn(Element.prototype, 'matches').mockImplementation(function (
+ this: Element,
+ selector: string,
+ ) {
+ return selector === ':modal'
+ ? this instanceof HTMLDialogElement && this.open
+ : matches.call(this, selector);
+ });
+ });
+ afterEach(() => {
+ vi.restoreAllMocks();
+ });
+
+ it('announces the busy start in a region inside the open sheet, not behind it', async () => {
+ render(renderOwner(async () => new Promise<void>(() => {})));
+ openSheet();
+ const sheet = document.querySelector('dialog[open]');
+ expect(sheet).not.toBeNull();
+ act(() => {
+ fireEvent.click(within(sheet as HTMLElement).getAllByRole('option')[1]);
+ });
+ await nextFrame();
+ await nextFrame();
+ expect(
+ sheet!.querySelector('[data-astryx-modal-busy-region]'),
+ ).toHaveTextContent('Loading');
+ expect(busyAnnouncements()).toEqual([]);
+ });
+ },
+);