Calendar accessibility fix

[git-nandor]

INSTUI-5009
INSTUI-5010
INSTUI-5014

Improve date picker calendar accessibility

Changes

• Add aria-live="polite" aria-atomic="true" to the month/year header in
  Calendar v1 and v2. Previously the container was a <span> wrapping <div>
  children (invalid HTML), causing screen readers to lose track of the live
  region subtree and skip announcements on month navigation. Changed to <div>.

• Add target month name to navigation button screen reader labels in Calendar
  v1 and v2. Default buttons now announce e.g. "Previous month, November 2023"
  instead of the generic "Previous month".

• Extend renderPrevMonthButton/renderNextMonthButton prop type from Renderable
  to Renderable<{ targetMonthSrLabel: string }> in Calendar v1 and v2. When
  passed as a function, the render prop receives the pre-formatted target month
  label so consumers can build descriptive accessible names for custom buttons.

• Update DateInput v2 to use function render props for navigation buttons,
  appending targetMonthSrLabel to the consumer-provided label string so the
  full announcement reads e.g. "Next month, January 2024".

• Add aria-modal to Dialog when role="dialog" and shouldContainFocus is true,
  scoping the screen reader virtual cursor to the dialog content. Guarded by
  shouldContainFocus so non-modal Dialog usages (Tray without containment,
  DrawerTray during transitions, etc.) are unaffected.

  Test plan

• Open a DateInput date picker with VoiceOver (macOS) or NVDA (Windows): verify the popover is announced as a dialog with its label (e.g. "Date picker, dialog")

• The calendar heading displaying the year and month should use an h2

• The last number in the yearPicker always fully visible

• With the calendar open, press Tab past the last focusable element and Shift+Tab before the first: verify focus stays inside the picker and does not escape

• Open a Modal, Tray, and Popover (non–date picker usage): verify aria-modal appears only when shouldContainFocus is true and does not appear on non-modal usages

• Navigate to the next/previous month using the arrow buttons: verify the screen reader announces the new month and year (e.g. "January 2024") via the aria-live region without requiring the user to move focus

• Check the previous and next month button accessible names: verify they include the target month (e.g. "Previous month, November 2023" / "Next month, January 2024") and not just the generic label

• Pass a function to renderPrevMonthButton / renderNextMonthButton on Calendar v2: verify targetMonthSrLabel is received

  <Calendar
  renderPrevMonthButton={({ targetMonthSrLabel }) => (
    <IconButton
      size="small"
      renderIcon={<ChevronLeftInstUIIcon color="baseColor" />}
      screenReaderLabel={`Go to, ${targetMonthSrLabel}`}
    />
  )}
  renderNextMonthButton={({ targetMonthSrLabel }) => (
    <IconButton
      size="small"
      renderIcon={<ChevronRightInstUIIcon color="baseColor" />}
      screenReaderLabel={`Go to, ${targetMonthSrLabel}`}
    />
  )}
  selectedLabel="Selected"
 />

Co-Authored-By: 🤖 Claude

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://instructure.design/pr-preview/pr-2529/
Built to branch gh-pages at 2026-05-08 13:36 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[ToMESSKa]

Can you please update the prop descriptions here too like in v2?

[git-nandor]

Updated

[ToMESSKa]

Really nice job. See my comment.

[github-actions]

Visual regression report

⚠️ Changes detected.

Status	Count
Unchanged	31
Changed	1
New	0
Removed	0

📊 View full report

Diff images (1)

calendar.png — 367 pixels differ

_{Baselines come from the visual-baselines branch. They refresh on every merge to master.}

[balzss]

Two sibling <h2>s split a single conceptual heading. Screen readers announce them as two separate headings ("December, heading level 2. 2023, heading level 2.") and both show up in heading navigation, instead of one combined "December 2023". aria-atomic doesn't merge them — the heading boundaries still apply.

Suggest collapsing into a single <h2> (which can also host the live-region attributes):

Suggested change

	<div aria-live="polite" aria-atomic="true">
	<h2 css={styles?.navigationLabel}>{visibleMonth.format('MMMM')}</h2>
	{!withYearPicker ? (
	<div>{visibleMonth.format('YYYY')}</div>
	<h2 css={styles?.navigationLabel}>{visibleMonth.format('YYYY')}</h2>
	) : null}
	</span>
	</div>
	<h2
	aria-live="polite"
	aria-atomic="true"
	css={styles?.navigationLabel}
	>
	<span>{visibleMonth.format('MMMM')}</span>
	{!withYearPicker ? (
	<span>{visibleMonth.format('YYYY')}</span>
	) : null}
	</h2>

If the existing two-line visual stacking matters, give the inner <span>s display: block in navigationLabel styles. One heading, one live region, one announcement.

[git-nandor]

Thanks! Modified