Merge branch 'main' into combobox_placeholder

packages/terra-core-docs/CHANGELOG.md

@@ -1,10 +1,15 @@
 # Changelog
 
 ## Unreleased
+* Updated
+  * Updated accessibility guidance for `terra-arrange`.
 
 * Updated
   * Updated the Upgrade Guide for `terra-form-combobox`.
 
+* Changed
+  * Changed paginator label on custom page count example.
+
 ## 1.48.0 - (November 2, 2023)
 
 * Updated

packages/terra-core-docs/src/terra-dev-site/doc/arrange/AccessibilityGuide.2.doc.mdx

@@ -10,7 +10,7 @@ import { Badge } from 'terra-arrange/package.json?dev-site-package';
 >
 > Making the DOM order same as visual order will help the assistive technology users to get the correct reading order. 
 >
-> Arrange may also have interactive elements which need to be keyboard focusable and interactable using the `Enter` or `Space` keys.  
+> Arrange may also have interactive elements which need to be keyboard focusable and acted upon using the standard expected keyboard behaviors. 
 >
 >  
 - **Screen reader users** do not necessarily interact with the page in a linear fashion and can use Arrange out of context. Hence, a descriptive label is necessary for each interactive element.
@@ -24,9 +24,12 @@ import { Badge } from 'terra-arrange/package.json?dev-site-package';
 - Ensure the content in the arrange component is reading in logical manner in assistive technology. The DOM structure needs to be in the form the UI order. 
 - Ensure the interactive elements are receiving TAB focus and user able to interact with it. 
 - Ensure the content is available in 200% text only zoom. Except for captions and images of text, text can be resized without assistive technology up to 200 percent without loss of content or functionality. 
-- Ensure the content can be presented without loss of information or functionality, and without requiring scrolling in two dimensions for: Vertical scrolling content at a width equivalent to 320 CSS pixels; Horizontal scrolling content at a height when window is resized to 400%. 
+- Ensure the content can be presented without loss of information or functionality, and without requiring scrolling in two dimensions for: Vertical scrolling content at a width equivalent to 320 CSS pixels; Horizontal scrolling content at a height when window is resized to 400%.
+- Ensure Terra Arrange is not used to create and arrange tabular data that has relationships to columns and rows. Instead, use Terra Table or Terra HTML Table.
 
 ### Content Considerations: What do content creators need to do? 
+- Terra Arrange must not be used to create and arrange tabular data that has relationships to columns and rows. That is to say do not use 
+   Terra arrange to create visible tables. Instead, use Terra Table or Terra HTML Table. 
 - Ensure all interactive elements have descriptive labels that describe their purpose. 
   - For each interactive element within Arrange, provide the engineers with a meaningful label. 
   - Ensure each interactive element label is unique to the page. 
@@ -40,20 +43,21 @@ import { Badge } from 'terra-arrange/package.json?dev-site-package';
   - Any purely decorative icon (does NOT convey any meaning) within a button must be marked as decorative. 
 - Consider how content will adjust to resizing text or reflowing content at different viewpoints. Users may have settings that change the font size, style, or other text attributes. They may also resize a window or zoom into the content. All these things can cause content to resize or reflow, and when it does, content must not overlap, be cut off, or become unusable. 
 - Ensure all content is perceivable by meeting all the color contrast requirements. 
-- After development, ensure the Arrange and its content is keyboard accessible and works as expected. 
-  - Ensure the Arrange has a visible keyboard focus when accessed using the keyboard. 
+- After development, ensure all actionable elements inside of Arrange an is keyboard accessible and work 
+  - Ensure actionable elements inside Arrange has a visible keyboard focus when accessed using the keyboard. 
   - Ensure the Arrange does not cause a keyboard trap. 
 
 ## Usability Expectations:
 
 ### Interaction Details
-- The buttons/icons which are available in the start and end of the component need to be focused via keyboard and proper labelling should be announced in screen reader. 
+- Terra Arrange has no interactions in and of itself. However, it may contain actionable elements. All actionable elements within Terra Arrange must be able to be focused via keyboard and follow the expected keyboard behavior per actionable element, and proper labeling should be announced in the screen reader.  
 
 ### Usability Expectations:
 - The user expects the button would be performing an action indicated in the button label. 
 
 
 ### Keyboard Expectations
+- Terra Arrange has no expected keyboard behaviors itself. However, the content within it will follow the basic keyboard behaviors. 
 
 | Key Sequence | Expectation |
 |---|---|
@@ -146,4 +150,4 @@ import { Badge } from 'terra-arrange/package.json?dev-site-package';
 ## Linked References:
 
 1. [W3C WAI Aria: Use heading to convey meaning and structure  ](https://www.w3.org/WAI/tips/writing/#use-headings-to-convey-meaning-and-structure)
-2. [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG21/#:~:text=%20Web%20Content%20Accessibility%20Guidelines%20%28WCAG%29%202.1%20defines,physical%2C%20speech%2C%20cognitive%2C%20language%2C%20learning%2C%20and%20neurological%20disabilities)
+2. [Web Content Accessibility Guidelines](https://www.w3.org/TR/WCAG21/#:~:text=%20Web%20Content%20Accessibility%20Guidelines%20%28WCAG%29%202.1%20defines,physical%2C%20speech%2C%20cognitive%2C%20language%2C%20learning%2C%20and%20neurological%20disabilities)

packages/terra-core-docs/src/terra-dev-site/doc/paginator/example/ProgressivePaginatorCustomPageCountExample.jsx

@@ -31,7 +31,7 @@ class ProgressivePaginatorCustomPageCountExample extends React.Component {
 
   changePages(index) {
     this.setState({ currentPage: index });
-    this.setState({ pageLabel: `Summary ${index} of total ${Math.abs(totalCount / itemCountPerPage)}` });
+    this.setState({ pageLabel: `Summary ${index} in total ${Math.abs(totalCount / itemCountPerPage)}` });
   }
 
   render() {

packages/terra-paginator/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+* Added
+ * Added VisuallyHiddenText with pageLabel to support screen reader users.
+
 ## 2.87.0 - (October 26, 2023)
 
 * Changed

packages/terra-paginator/src/ControlledProgressivePaginator.jsx

@@ -77,6 +77,8 @@ class ControlledProgressivePaginator extends React.Component {
       intl,
       itemCountPerPage,
       totalCount,
+      pageLabel,
+      hidePageCount,
     } = this.props;
 
     return (event) => {
@@ -88,9 +90,13 @@ class ControlledProgressivePaginator extends React.Component {
 
       let message;
       if (totalCount && itemCountPerPage) {
-        message = intl.formatMessage({ id: 'Terra.paginator.pageSelectedWithCount' }, { pageNumber: index, pageNumberTotal: calculatePages(totalCount, itemCountPerPage) });
+        if (pageLabel && !hidePageCount) {
+          message = intl.formatMessage({ id: 'Terra.paginator.customPageSelectedWithCount' }, { pageLabel, pageNumber: index, pageNumberTotal: calculatePages(totalCount, itemCountPerPage) });
+        } else {
+          message = intl.formatMessage({ id: 'Terra.paginator.pageSelectedWithCount' }, { pageNumber: index, pageNumberTotal: calculatePages(totalCount, itemCountPerPage) });
+        }
       } else {
-        message = intl.formatMessage({ id: 'Terra.paginator.pageSelected' }, { pageNumber: index });
+        message = (pageLabel) ? intl.formatMessage({ id: 'Terra.paginator.customPageSelected' }, { pageLabel }) : intl.formatMessage({ id: 'Terra.paginator.pageSelected' }, { pageNumber: index });
       }
 
       this.setState({ selectedPageMessage: message });
@@ -124,6 +130,7 @@ class ControlledProgressivePaginator extends React.Component {
 
     const { messageId, messageAttributes } = getPageLabel(pageLabel, selectedPage, totalPages);
     const pageDetails = (hidePageCount && pageLabel) ? <div>{pageLabel}</div> : <div>{intl.formatMessage({ id: messageId }, messageAttributes)}</div>;
+    const customPageSelectedMessage = (hidePageCount && pageLabel) ? intl.formatMessage({ id: 'Terra.paginator.customPageSelected' }, { pageLabel }) : undefined;
 
     const fullViewChildren = (
       <>
@@ -192,7 +199,7 @@ class ControlledProgressivePaginator extends React.Component {
     );
 
     const navigationMessage = (
-      <VisuallyHiddenText aria-live="polite" aria-relevant="additions text" text={this.state.selectedPageMessage} />
+      <VisuallyHiddenText aria-live="polite" aria-relevant="additions text" text={customPageSelectedMessage || this.state.selectedPageMessage} />
     );
 
     const fullView = (
@@ -229,6 +236,7 @@ class ControlledProgressivePaginator extends React.Component {
 
     const { messageId, messageAttributes } = getPageLabel(pageLabel, selectedPage, totalPages);
     const pageDetails = (hidePageCount && pageLabel) ? <div>{pageLabel}</div> : <div>{intl.formatMessage({ id: messageId }, messageAttributes)}</div>;
+    const customPageSelectedMessage = (hidePageCount && pageLabel) ? intl.formatMessage({ id: 'Terra.paginator.customPageSelected' }, { pageLabel }) : undefined;
 
     const reducedViewChildren = (
       <>
@@ -297,7 +305,7 @@ class ControlledProgressivePaginator extends React.Component {
     );
 
     const navigationMessage = (
-      <VisuallyHiddenText aria-live="polite" aria-relevant="additions text" text={this.state.selectedPageMessage} />
+      <VisuallyHiddenText aria-live="polite" aria-relevant="additions text" text={customPageSelectedMessage || this.state.selectedPageMessage} />
     );
 
     const reducedView = (

packages/terra-paginator/src/ProgressivePaginator.jsx

@@ -81,6 +81,8 @@ class ProgressivePaginator extends React.Component {
       intl,
       itemCountPerPage,
       totalCount,
+      pageLabel,
+      hidePageCount,
     } = this.props;
 
     return (event) => {
@@ -89,12 +91,15 @@ class ProgressivePaginator extends React.Component {
       }
 
       this.props.onPageChange(index);
-
       let message;
       if (totalCount && itemCountPerPage) {
-        message = intl.formatMessage({ id: 'Terra.paginator.pageSelectedWithCount' }, { pageNumber: index, pageNumberTotal: calculatePages(totalCount, itemCountPerPage) });
+        if (pageLabel && !hidePageCount) {
+          message = intl.formatMessage({ id: 'Terra.paginator.customPageSelectedWithCount' }, { pageLabel, pageNumber: index, pageNumberTotal: calculatePages(totalCount, itemCountPerPage) });
+        } else {
+          message = intl.formatMessage({ id: 'Terra.paginator.pageSelectedWithCount' }, { pageNumber: index, pageNumberTotal: calculatePages(totalCount, itemCountPerPage) });
+        }
       } else {
-        message = intl.formatMessage({ id: 'Terra.paginator.pageSelected' }, { pageNumber: index });
+        message = (pageLabel) ? intl.formatMessage({ id: 'Terra.paginator.customPageSelected' }, { pageLabel }) : intl.formatMessage({ id: 'Terra.paginator.pageSelected' }, { pageNumber: index });
       }
 
       this.setState({
@@ -131,6 +136,7 @@ class ProgressivePaginator extends React.Component {
 
     const { messageId, messageAttributes } = getPageLabel(pageLabel, selectedPage, totalPages);
     const pageDetails = (hidePageCount && pageLabel) ? <div>{pageLabel}</div> : <div>{intl.formatMessage({ id: messageId }, messageAttributes)}</div>;
+    const customPageSelectedMessage = (hidePageCount && pageLabel) ? intl.formatMessage({ id: 'Terra.paginator.customPageSelected' }, { pageLabel }) : undefined;
 
     const fullViewChildren = (
       <>
@@ -199,7 +205,7 @@ class ProgressivePaginator extends React.Component {
     );
 
     const navigationMessage = (
-      <VisuallyHiddenText aria-live="polite" aria-relevant="additions text" text={this.state.selectedPageMessage} />
+      <VisuallyHiddenText aria-live="polite" aria-relevant="additions text" text={customPageSelectedMessage || this.state.selectedPageMessage} />
     );
 
     const fullView = (
@@ -236,6 +242,7 @@ class ProgressivePaginator extends React.Component {
 
     const { messageId, messageAttributes } = getPageLabel(pageLabel, selectedPage, totalPages);
     const pageDetails = (hidePageCount && pageLabel) ? <div>{pageLabel}</div> : <div>{intl.formatMessage({ id: messageId }, messageAttributes)}</div>;
+    const customPageSelectedMessage = (hidePageCount && pageLabel) ? intl.formatMessage({ id: 'Terra.paginator.customPageSelected' }, { pageLabel }) : undefined;
 
     const reducedViewChildren = (
       <>
@@ -304,7 +311,7 @@ class ProgressivePaginator extends React.Component {
     );
 
     const navigationMessage = (
-      <VisuallyHiddenText aria-live="polite" aria-relevant="additions text" text={this.state.selectedPageMessage} />
+      <VisuallyHiddenText aria-live="polite" aria-relevant="additions text" text={customPageSelectedMessage || this.state.selectedPageMessage} />
     );
 
     const reducedView = (

packages/terra-paginator/translations/de.json

@@ -5,7 +5,9 @@
   "Terra.paginator.last": "Letzte",
   "Terra.paginator.pageIndex": "Seite {pageNumber}",
   "Terra.paginator.pageSelected": "Seite {pageNumber} ist ausgewählt.",
+  "Terra.paginator.customPageSelected": "{pageLabel} ist ausgewählt.",
   "Terra.paginator.pageSelectedWithCount": "Seite {pageNumber} von {pageNumberTotal} ist ausgewählt.",
+  "Terra.paginator.customPageSelectedWithCount": "{pageLabel} {pageNumber} von {pageNumberTotal} ist ausgewählt.",
   "Terra.paginator.pageCount": "Seite {pageNumber} von {pageNumberTotal}",
   "Terra.paginator.pageIndexWithLabel": "{pageLabel} {pageNumber}",
   "Terra.paginator.pageCountWithLabel": "{pageLabel} {pageNumber} von {pageNumberTotal}"

packages/terra-paginator/translations/en-AU.json

@@ -4,6 +4,10 @@
   "Terra.paginator.first": "First",
   "Terra.paginator.last": "Last",
   "Terra.paginator.pageIndex": "Page {pageNumber}",
+  "Terra.paginator.pageSelected": "Page {pageNumber} selected",
+  "Terra.paginator.customPageSelected": "{pageLabel} selected",
+  "Terra.paginator.pageSelectedWithCount": "Page {pageNumber} of {pageNumberTotal} is selected",
+  "Terra.paginator.customPageSelectedWithCount": "{pageLabel} {pageNumber} of {pageNumberTotal} is selected",
   "Terra.paginator.pageCount": "Page {pageNumber} of {pageNumberTotal}",
   "Terra.paginator.pageIndexWithLabel": "{pageLabel} {pageNumber}",
   "Terra.paginator.pageCountWithLabel": "{pageLabel} {pageNumber} of {pageNumberTotal}"

packages/terra-paginator/translations/en-CA.json

@@ -4,6 +4,10 @@
   "Terra.paginator.first": "First",
   "Terra.paginator.last": "Last",
   "Terra.paginator.pageIndex": "Page {pageNumber}",
+  "Terra.paginator.pageSelected": "Page {pageNumber} selected",
+  "Terra.paginator.customPageSelected": "{pageLabel} selected",
+  "Terra.paginator.pageSelectedWithCount": "Page {pageNumber} of {pageNumberTotal} is selected",
+  "Terra.paginator.customPageSelectedWithCount": "{pageLabel} {pageNumber} of {pageNumberTotal} is selected",
   "Terra.paginator.pageCount": "Page {pageNumber} of {pageNumberTotal}",
   "Terra.paginator.pageIndexWithLabel": "{pageLabel} {pageNumber}",
   "Terra.paginator.pageCountWithLabel": "{pageLabel} {pageNumber} of {pageNumberTotal}"

packages/terra-paginator/translations/en-GB.json

@@ -5,7 +5,9 @@
   "Terra.paginator.last": "Last",
   "Terra.paginator.pageIndex": "Page {pageNumber}",
   "Terra.paginator.pageSelected": "Page {pageNumber} selected",
+  "Terra.paginator.customPageSelected": "{pageLabel} selected",
   "Terra.paginator.pageSelectedWithCount": "Page {pageNumber} of {pageNumberTotal} is selected",
+  "Terra.paginator.customPageSelectedWithCount": "{pageLabel} {pageNumber} of {pageNumberTotal} is selected",
   "Terra.paginator.pageCount": "Page {pageNumber} of {pageNumberTotal}",
   "Terra.paginator.pageIndexWithLabel": "{pageLabel} {pageNumber}",
   "Terra.paginator.pageCountWithLabel": "{pageLabel} {pageNumber} of {pageNumberTotal}"

packages/terra-paginator/translations/en-US.json

@@ -4,6 +4,10 @@
   "Terra.paginator.first": "First",
   "Terra.paginator.last": "Last",
   "Terra.paginator.pageIndex": "Page {pageNumber}",
+  "Terra.paginator.pageSelected": "Page {pageNumber} selected",
+  "Terra.paginator.customPageSelected": "{pageLabel} selected",
+  "Terra.paginator.pageSelectedWithCount": "Page {pageNumber} of {pageNumberTotal} is selected",
+  "Terra.paginator.customPageSelectedWithCount": "{pageLabel} {pageNumber} of {pageNumberTotal} is selected",
   "Terra.paginator.pageCount": "Page {pageNumber} of {pageNumberTotal}",
   "Terra.paginator.pageIndexWithLabel": "{pageLabel} {pageNumber}",
   "Terra.paginator.pageCountWithLabel": "{pageLabel} {pageNumber} of {pageNumberTotal}"

packages/terra-paginator/translations/en.json

@@ -5,7 +5,9 @@
   "Terra.paginator.last": "Last",
   "Terra.paginator.pageIndex": "Page {pageNumber}",
   "Terra.paginator.pageSelected": "Page {pageNumber} selected",
+  "Terra.paginator.customPageSelected": "{pageLabel} selected",
   "Terra.paginator.pageSelectedWithCount": "Page {pageNumber} of {pageNumberTotal} is selected",
+  "Terra.paginator.customPageSelectedWithCount": "{pageLabel} {pageNumber} of {pageNumberTotal} is selected",
   "Terra.paginator.pageCount": "Page {pageNumber} of {pageNumberTotal}",
   "Terra.paginator.pageIndexWithLabel": "{pageLabel} {pageNumber}",
   "Terra.paginator.pageCountWithLabel": "{pageLabel} {pageNumber} of {pageNumberTotal}"

packages/terra-paginator/translations/es.json

@@ -5,7 +5,9 @@
   "Terra.paginator.last": "Última",
   "Terra.paginator.pageIndex": "Página {pageNumber}",
   "Terra.paginator.pageSelected": "Página {pageNumber} seleccionada",
+  "Terra.paginator.customPageSelected": "{pageLabel} seleccionada",
   "Terra.paginator.pageSelectedWithCount": "La página {pageNumber} de {pageNumberTotal} está seleccionada",
+  "Terra.paginator.customPageSelectedWithCount": "{pageLabel} {pageNumber} de {pageNumberTotal} está seleccionada",
   "Terra.paginator.pageCount": "Página {pageNumber} de {pageNumberTotal}",
   "Terra.paginator.pageIndexWithLabel": "{pageLabel} {pageNumber}",
   "Terra.paginator.pageCountWithLabel": "{pageLabel} {pageNumber} de {pageNumberTotal}"

packages/terra-paginator/translations/fr.json

@@ -5,7 +5,9 @@
   "Terra.paginator.last": "Dernière",
   "Terra.paginator.pageIndex": "Page {pageNumber}",
   "Terra.paginator.pageSelected": "Page {pageNumber} sélectionnée",
+  "Terra.paginator.customPageSelected": "{pageLabel} sélectionnée",
   "Terra.paginator.pageSelectedWithCount": "La page {pageNumber} sur {pageNumberTotal} page(s) est sélectionnée.",
+  "Terra.paginator.customPageSelectedWithCount": "{pageLabel} {pageNumber} sur {pageNumberTotal} page(s) est sélectionnée.",
   "Terra.paginator.pageCount": "Page {pageNumber} sur {pageNumberTotal} page(s)",
   "Terra.paginator.pageIndexWithLabel": "{pageLabel} {pageNumber}",
   "Terra.paginator.pageCountWithLabel": "{pageLabel} {pageNumber} sur {pageNumberTotal} page(s)"

packages/terra-paginator/translations/nl-BE.json

@@ -5,7 +5,9 @@
   "Terra.paginator.last": "Laatste",
   "Terra.paginator.pageIndex": "Pagina {pageNumber}",
   "Terra.paginator.pageSelected": "Pagina {pageNumber} geselecteerd",
+  "Terra.paginator.customPageSelected": "{pageLabel} geselecteerd",
   "Terra.paginator.pageSelectedWithCount": "Pagina {pageNumber} van {pageNumberTotal} is geselecteerd",
+  "Terra.paginator.customPageSelectedWithCount": "{pageLabel} {pageNumber} van {pageNumberTotal} is geselecteerd",
   "Terra.paginator.pageCount": "Pagina {pageNumber} van {pageNumberTotal}",
   "Terra.paginator.pageIndexWithLabel": "{pageLabel} {pageNumber}",
   "Terra.paginator.pageCountWithLabel": "{pageLabel} {pageNumber} van {pageNumberTotal}"

packages/terra-paginator/translations/nl.json

@@ -4,6 +4,10 @@
   "Terra.paginator.first": "Eerste",
   "Terra.paginator.last": "Laatste",
   "Terra.paginator.pageIndex": "Pagina {pageNumber}",
+  "Terra.paginator.pageSelected": "Pagina {pageNumber} geselecteerd",
+  "Terra.paginator.customPageSelected": "{pageLabel} geselecteerd",
+  "Terra.paginator.pageSelectedWithCount": "Pagina {pageNumber} van {pageNumberTotal} is geselecteerd",
+  "Terra.paginator.customPageSelectedWithCount": "{pageLabel} {pageNumber} van {pageNumberTotal} is geselecteerd",
   "Terra.paginator.pageCount": "Pagina {pageNumber} van {pageNumberTotal}",
   "Terra.paginator.pageIndexWithLabel": "{pageLabel} {pageNumber}",
   "Terra.paginator.pageCountWithLabel": "{pageLabel} {pageNumber} van {pageNumberTotal}"