Summary

Update @uswds/uswds to 3.14 and make changes to maintain parity. Each table row from USWDS release notes is covered below.

Features

• usa-accordion, uswds-core (USWDS - Accordion: Extending accordion to allow for start/end icon alignment uswds/uswds#6789):
  • Added optional iconPosition prop to Accordion which applies usa-accordion--icon-start or usa-accordion--icon-end when set.
  • Update Accordion storybook entries to default the first accordion item to expanded, matching USWDS storybook.
  • Add "Icon Start" and "Icon End" storybook entries to demonstrate effect of iconPosition prop.
  • Add/update tests.
• usa-breadcrumb (USWDS - Breadcrumb: Wrap by default instead of truncating uswds/uswds#6722):
  • Add truncate option to variant prop. Wrap is now the default.
  • No longer apply inert class usa-breadcrumb--wrap; only apply usa-breadcrumb--truncate when variant is truncate.
  • Update BreadcrumbBar storybook entries to use longer current breadcrumb, matching USWDS storybook.
  • Replace "Wrapping Breadcrumb" storybook entry with "Truncated Breadcrumb".
  • Add/update tests.
• usa-range (fix: add visual hint instruction to range slider - 6614 uswds/uswds#6673, [Task] Range Slider: Moved hint above the slider to match other component hints uswds/uswds#6811):
  • Add optional hint prop to RangeInput. By default, hint "Move the slider to change the value" appears above the input.
  • Change label in storybook entries to "Range slider", matching USWDS.
  • Add "No Hint" storybook entry.
  • Add "Disabled" and "Aria Disabled" storybook entries for parity with USWDS.
  • Add/update tests.
• usa-range (USWDS - Range slider: Improve border visibility uswds/uswds#6659):
  • No changes required, CSS only.
• usa-date-picker (USWDS - Date Picker: Add aria-current to today's date button uswds/uswds#6593):
  • Set aria-current to "date" for today's date.
  • Add/update tests.
• usa-file-input (USWDS - File input: Use error token for error border uswds/uswds#6669):
  • No changes required, CSS only.

Bug fixes

• usa-modal, uswds-core (USWDS - Modal: Fix for content reading twice in screen readers uswds/uswds#6703, USWDS - Modal: Restore page content when the opener has left the document uswds/uswds#6786):
  • When modal opens and initial focus is determined...
    1. continue respecting the element with [data-focus] if it exists, then fall back to...
    2. the first non-disabled button in the footer if it exists, then fall back to...
    3. any non-disabled button in the modal if it exists, and finally fall back to...
    4. the modal itself.
  • Update type annotations, fixing incorrect type assertion on the queried elements.
  • Apply aria-hidden/aria-modal attributes to modal.
  • Update tests.
• usa-memorable-date (USWDS - Memorable Date: Adjusting date hint text and format uswds/uswds#6725):
  • Support adding screen-reader hints to date inputs with prop srHint on DateInput
  • Update "Date Of Birth Example" storybook to more closely mimic USWDS.
  • Add tests.
• usa-file-input (USWDS - File input: Remove drag instruction on mobile uswds/uswds#6660):
  • Remove IE11 and legacy Edge user agent tests as a basis for drag text hints. These browsers are not supported by USWDS 3.
  • Switch from "hide drag text" to "show drag text" state based on whether window.matchMedia() matches (hover: hover) and (pointer: fine). React to media match changes.
  • Support setting "choose text" for either the fine or not-fine cases.
  • Use "Custom Text" storybook entry to demonstrate use of chooseTextWithoutDrag.
  • Replace IE11/Edge choose text tests with new "pointer capability" tests.
• usa-character-count (USWDS - Character Count: Defer aria-live to prevent iOS VoiceOver announcement on page load uswds/uswds#6595):
  • This change had related changes that are missing from the v3.14 release notes: USWDS - Character count: Improve over-limit screen reader announcements uswds/uswds#6767 and USWDS - Multiple Enhanced Components: Fixed initialization issues uswds/uswds#6664 .
  • Skip announcement on initial render.
  • When character limit is exceeded, prefix announcement with "Character limit exceeded." The new mixed punctuation in strings like Character limit exceeded. 1 character over limit matches USWDS.
  • Delay announcements by 1200ms when validity is unchanged or when the count becomes invalid, avoiding unnecessary announcements if subsequent changes are made quick enough to cancel earlier ones. Quickly update announcement status when character count becomes valid.
  • Use 'assertive' announcements when invalid and 'polite' when valid.
  • Update tests.
• usa-character-count (USWDS - Character Count: Fix label selector uswds/uswds#6385):
  • Does not affect this project.
• usa-footer (USWDS - Footer: Prevent unsafe element creation from data-tag attribute uswds/uswds#6674):
  • Does not affect this project.
• usa-banner, uswds-core (Fix toggle lookup to respect component root uswds/uswds#6714)
  • While this technically does not affect this project, its premise does. Several components are broken in shadow DOMs and light DOMs. A separate issue should be created to improve compatibility.
• usa-core (Fix Escape handling in language selector uswds/uswds#6713):
  • Does not affect this project. Focus trap configured with Escape support.
• usa-core (fix: prevent console error when using datalist with text inputs uswds/uswds#6594):
  • Does not affect this project.
• usa-table (USWDS - Table: Restore row header border in borderless tables uswds/uswds#6661):
  • No changes required, CSS only.
• usa-table (USWDS - Table: Fixes .usa-sr-only table caption heading row collapse uswds/uswds#6633):
  • No changes required, CSS only.
• usa-time-picker (USWDS - Time picker: Add combobox style dependency uswds/uswds#6634):
  • No changes required, CSS only.
• usa-input, usa-textarea, usa-range, usa-combo-box, usa-input-prefix-suffix, usa-select (Fix select overflow by setting border-box sizing uswds/uswds#6736):
  • No changes required, CSS only.
• usa-in-page-navigation (USWDS - update data prop for consistency uswds/uswds#6688):
  • Does not affect this project.
• uswds-core ([uswds-core]: ink assignments theme color was referencing wrong variable uswds/uswds#6651):
  • No changes required, CSS only.

Guidance changes

• Alert
  • Direct users to review USWDS 3.14 release notes.

Markup changes

• Memorable date (DateInput in this project)
  • This mostly only affects the "Date Of Birth" storybook example. No real breaking changes need to be described, but new support for screen reader only hints could be mentioned.
• File input
  • Differences in drag text based on whether hover and fine pointer are available are discussed in breaking changes.
• Accordion icon alignment
  • Breaking changes mention the changed default icon position new theme setting $theme-accordion-icon-position.

Breaking changes

• USWDS 3.14.0 required. Peer dependency is now @uswds/uswds ^3.14.0. USWDS 3.14 also changes the appearance of the accordion, breadcrumb, range slider, borderless table row headers, and file input error border. See the USWDS 3.14.0 release notes.
• Accordion: USWDS now places the expand/collapse icon at the start (left) by default. Use the new iconPosition="end" prop, or set $theme-accordion-icon-position: "end" in your USWDS theme, to keep the previous placement.
• BreadcrumbBar: Breadcrumbs wrap by default instead of truncating. variant="wrap" no longer has an effect and usa-breadcrumb--wrap is no longer applied. Use variant="truncate" to restore single-line truncation.
• RangeSlider: Component RangeInput has been renamed to RangeSlider, matching USWDS naming. A new hint prop is available to render a usage hint above the slider; it is referenced by aria-describedby. Recommended text from USWDS: "Move the slider to change the value".
• FileInput: On devices without hover and a fine pointer, the drag instruction is omitted and the text reads "Choose from folder". Customize it with the new chooseTextWithoutDrag prop. IE11 and legacy Edge user agent detection was removed. Tests asserting the exact instruction text may need updating.
• CharacterCount: The screen reader status is empty on initial render and updates after 1200ms (was 1000ms). Over-limit announcements are prefixed with "Character limit exceeded." and use aria-live="assertive".
• Modal: Initial focus goes to the [data-focus] element, then the first enabled button in ModalFooter, then the first enabled button in the modal, then the modal itself. The dialog has aria-hidden="true" while closed and aria-modal="true" while open. Tests that query the dialog role while it is closed need hidden: true.

Related Issues or PRs

• build(deps-dev): Bump @uswds/uswds from 3.13.0 to 3.14.0 #3613

How To Test

Confirm components behave the same as described in USWDS release notes for version 3.14.0.

Happo differences

• Components/Accordion
  • This changeset sets the first accordion item to expanded, matching USWDS storybook.
  • The new default expansion icon is on the left now (configurable by theme setting: $theme-accordion-icon-position).
  • "Icon Start" and "Icon End" entries are new.
• Components/Date input
  • Hint for "Date Of Birth" updated to match USWDS storybook entry "Memorable Date".
• Components/Modal
  • Changes are a result of new auto-focus behavior for modals.
• Components/File input
  • Changes are a result of new "choose file" messaging based on whether fine pointer exists.
• Components/Breadcrumb
  • Current breadcrumb title matches new string from USWDS.
  • Default behavior is to wrap; entry "Wrapping Breadcrumb" became "Truncated Breadcrumb" with opposite behavior.
• Components/Range slider
  • "Disabled" and "Aria Disabled" entries added for parity with USWDS storybook.
  • Default hint was added in this changeset. New entry "No Hint" shows slider without hint.

Author & Maintainer checklist

• Is this is a breaking change?
  • Yes, and I accounted for the breaking changes according to the linked documentation
  • No
• Once merged, add the PR and Issue author(s) as a contributor(s) via the all-contributors bot