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-04-28 14:32 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.