cerner · adoroshk · Aug 14, 2023 · Jun 30, 2023 · Jul 7, 2023 · Jul 7, 2023
@@ -15,6 +15,7 @@
 * Updated
   * Updated an example for `terra-dropdown-button`.
   * Updated email field validation for `terra-form-field`.
+  * Updated `terra-show-hide` examples for new focusRef prop, description for the new prop usage.
 
 * Added
   * Added documentation updates for `terra-form-input`.

@@ -1,19 +1,28 @@
 import { Badge } from 'terra-show-hide/package.json?dev-site-package';
+import { Notice } from "@cerner/terra-docs";
 
 import DefaultShowHide from './example/DefaultShowHide?dev-site-example';
 import CustomButtonTextShowHide from './example/CustomButtonTextShowHide?dev-site-example';
+import LinkShowHide from './example/LinkShowHide?dev-site-example';
 import InitiallyOpenShowHide from './example/InitiallyOpenShowHide?dev-site-example';
 import ButtonAlignCenterShowHide from './example/ButtonAlignCenterShowHide?dev-site-example';
 import ButtonAlignRightShowHide from './example/ButtonAlignRightShowHide?dev-site-example';
 import NoPreviewShowHide from './example/NoPreviewShowHide?dev-site-example';
+import NoFocusRefShowHide from './example/NoFocusRefShowHide?dev-site-example';
 
 import ShowHidePropsTable from 'terra-show-hide/src/ShowHide?dev-site-props-table';
+import ShowHideFocuserPropsTable from 'terra-show-hide/src/ShowHideFocuser?dev-site-props-table';
 
 <Badge />
 
 # Terra Show Hide
 
-Show Hide Component that will show a preview of content and then expand it with a Show More button.
+Show Hide Component - is a disclosure widget that enables content to be either collapsed (hidden) or expanded (visible). It has two elements: a disclosure [button][1] and a section of content whose visibility is controlled by the button. When the controlled content is hidden, the button is often styled as a typical push button with a down-pointing caret to hint that activating the button will display additional content. When the content is visible, the content displays above the button and the caret points up.
+
+Another Terra component, [Toggle Button][2], is available and preferred to Show/Hide because it better adheres to accessibility best practices for disclosure components. It differs from Show Hide by displaying the content below the button when it is activated. 
+
+[1]: https://www.w3.org/WAI/ARIA/apg/patterns/button/
+[2]: https://engineering.cerner.com/terra-core/components/cerner-terra-core-docs/toggle-button/about
 
 ## Getting Started
 
@@ -42,9 +51,127 @@ The Show-Hide component must be composed inside the [Base][1] component with a l
 ## Usage
 
 ```jsx
-import ShowHide from 'terra-show-hide';
+import ShowHide, { ShowHideFocuser } from 'terra-show-hide';
 ```
 
+## Accessibility
+
+<Notice variant="important" ariaLevel="3">
+
+  To make the Show/Hide component accessible, you must use the `focusRef` prop. This prop allows assistive technologies such as screen readers to move user focus backward to hidden text and announce it when it is disclosed. For backward compatibility, the `focusRef` prop is optional, but is required to meet accessibility requirements.
+
+</Notice>
+
+<Notice variant="caution" ariaLevel="3">
+
+  This component is not recommended for use in Safari due to VoiceOver focus limitations with Show Hide. Consider using Terra Toggle Button instead.
+
+</Notice>
+
+###  Keyboard Interactions 
+  When the disclosure control has focus:
+  - Enter key activates the disclosure control and toggles the visibility of the disclosure content.
+  - Space key activates the disclosure control and toggles the visibility of the disclosure content. 
+
+### Truncate a paragraph of text
+
+  - At the top level of your component declare a `ref`, pass it as `focusRef` prop to `ShowHide` component.
+  - Pass a node with the preview portion of the text as a prop to `ShowHide` component.
+  - Use the `ShowHideFocuser` component inside `<p>` tag. A `ShowHideFocuser` component allows `ShowHide` component to set focus on the beginning of the focusable text upon opening.
+  - The text split in the prefix and focusable text portions must be passed as string props. The prefix prop should contain the portion of the text that was a part of the preview prop, passed to `ShowHide`.
+  - Forward `focusRef` to `ShowHideFocuser` component.
+
+  ```jsx
+  import React, { useRef, useState } from 'react';
+  import ShowHide, { ShowHideFocuser } from 'terra-show-hide';
+
+  const MyComponent = () => {
+    const focusRef = useRef(null);
+    const [isOpen, setIsOpen] = useState(false);
+    const toggleShowHide = () => setIsOpen(!isOpen);
+
+    const prefix = 'Patients are requesting greater affordability and efficiency in healthcare. With procedures performed in an ambulatory surgery center costing up to 60% less compared to a hospital outpatient department (1), the demand for these facilities is increasing.';
+    const focusableText = 'In fact, the U.S. ambulatory surgery center market is expected to see a 6.9 % compound annual growth rate, reaching $33 billion by 2028. (2) Cerner understands the urgency to grow in the ambulatory surgery center market while continuing to deliver excellent care. Healthcare IT products can help improve clinician efficiency and patient outcomes, as well as enhance communication and data exchange between ambulatory surgery center providers and patients. Read';
+
+    return (
+      <ShowHide focusRef={focusRef} preview={ <p>{prefix}</p> } isOpen={isOpen} onChange={toggleShowHide} >
+        <p>
+          <ShowHideFocuser ref={this.focusRef} prefix={prefix} focusableText={focusableText} />
+        </p>
+      </ShowHide>
+    );
+  }
+  ```
+
+### Multiple children
+  Even though the main purpose of the `ShowHide` component is to truncate long paragraps of texts, the content of the `ShowHide` does not have to be one paragraph. It can include links, lists, and any kind of HTML tags as long as the first line of the hidden text is passed as a string prop to `ShowHideFocuser` component rather than an HTML element.
+
+Please note:
+  - Links can be placed inside the `p` tag that wraps `ShowHideFocuser` component both preceding and following it. The prop `prefix` can be omitted if content has been passed as an HTML element preceding `ShowHideFocuser`.
+  - Everything that precedes `ShowHideFocuser` component must be also included into the `ShowHide` preview prop.
+  - Do not break lists placing `ShowHideFocuser` inside `li`, as it might cause assistive technologies to read the content incorrectly.
+
+  ```jsx
+    import React, { useState, useRef } from 'react';
+    import ShowHide, { ShowHideFocuser } from 'terra-show-hide';
+
+    const MyComponent = () => {
+      const focusRef = useRef(null);
+      const [isOpen, setIsOpen] = useState(false);
+      const toggleShowHide = () => setIsOpen(!isOpen);
+
+      const header = 'Bringing clarity to life sciences and healthcare decision-making ';
+      const prefix = 'When we accelerate the discovery, development and deployment of life-enhancing insights and therapies, clinicians and patients benefit.';
+      const preview = [
+        <h3>{header}</h3>,
+        <p>{prefix}</p>,
+      ];
+
+      return (
+        <ShowHide focusRef={focusRef} preview={preview} isOpen={isOpen} onChange={toggleShowHide} >
+          <h3>{header}</h3>
+          <p>
+            <ShowHideFocuser ref={this.focusRef} prefix={prefix} focusableText="Several factors help bring clarity to life sciences, researchers and clinicians and " />
+            <a href="#">guide better care</a>
+          </p>
+          <ul>
+            <li>Data-driven research solutions for commercial and real-world evidence collaborators and health providers</li>
+            <li>Support to move from simply accumulating and analyzing data to linking and generating deeper insights </li>
+            <li>Combined life sciences knowledge, healthcare innovation and collaborative research expertise</li>
+          </ul>
+        </ShowHide>
+      );
+    }
+  ```
+
+### First hidden child is an interactive element (link, button, etc)
+  - At the top level of your component declare a `ref`.
+  - In this case there is no need to use `ShowHideFocuser`. Forward `focusRef` to the interactive element directly.
+
+  ```jsx
+    import React, { useState, useRef } from 'react';
+    import ShowHide from 'terra-show-hide';
+
+    const MyComponent = () => {
+      const focusRef = useRef(null);
+      const [isOpen, setIsOpen] = useState(false);
+      const toggleShowHide = () => setIsOpen(!isOpen);
+
+      const previewText = 'Although the process is complex and will vary greatly based on regional and economic factors, it’s clear that healthcare entities must start planning their transitions now.';
+      const text = 'it expects all Medicare Parts A and B beneficiaries and most Medicaid beneficiaries to be in a value-based care relationship with accountability for quality and total cost of care by 2030.';
+
+      return (
+        <ShowHide focusRef={focusRef} preview={<p>{previewText}</p>} isOpen={isOpen} onChange={toggleShowHide} >
+          <p>
+            {previewText}
+            <a ref={this.focusRef} href="#">CMS recently announced</a>
+            {text}
+          </p>
+        </ShowHide>
+      );
+    }
+  ```
+
 ## Component Features
 
 * [Cross-Browser Support](https://engineering.cerner.com/terra-ui/about/terra-ui/component-standards#cross-browser-support)
@@ -57,10 +184,17 @@ import ShowHide from 'terra-show-hide';
 ## Examples
 <DefaultShowHide title="Default ShowHide" />
 <CustomButtonTextShowHide title="Custom Button Text ShowHide" />
+<LinkShowHide title="ShowHide with a Link" />
+<MultipleChildrenShowHide title="ShowHide with Multiple Children" />
+<ListShowHide title="ShowHide with a List Content" />
 <InitiallyOpenShowHide title="Initially Open ShowHide" />
 <ButtonAlignCenterShowHide title="Button Align Center ShowHide" />
 <ButtonAlignRightShowHide title="Button Align Right ShowHide" />
 <NoPreviewShowHide title="No Preview ShowHide" />
+<NoFocusRefShowHide title="No focusRef ShowHide (see Accessibility note for information about the focusRef prop)" />
 
 ## Show Hide Props
 <ShowHidePropsTable />
+
+## Show Hide Focuser Props
+<ShowHideFocuserPropsTable />
@@ -1,15 +1,16 @@
 import React from 'react';
-import ShowHide from 'terra-show-hide';
+import ShowHide, { ShowHideFocuser } from 'terra-show-hide';
 
-const fullText = 'According to the Journal of Healthcare Management/American College of Healthcare Executives, a 500-bed hospital loses over $4 million annually due to clinical communication inefficiencies. A unified clinical communication strategy can help health systems begin to close the gap and improve efficiency at every level. Enable your clinical care team with real-time health communication tools and workflows that help them to collaborate more effectively on the go and provide a quality patient care experience. A unified strategy and improved communication tools can help address many challenges including identification of patient care team members, mobile clinical workflows, secure and timely critical alerts, and more.';
-const previewText = fullText.substring(0, 280);
+const prefix = 'According to the Journal of Healthcare Management/American College of Healthcare Executives, a 500-bed hospital loses over $4 million annually due to clinical communication inefficiencies. A unified clinical communication strategy can help health systems begin to close the gap';
+const focusableText = 'and improve efficiency at every level. Enable your clinical care team with real-time health communication tools and workflows that help them to collaborate more effectively on the go and provide a quality patient care experience. A unified strategy and improved communication tools can help address many challenges including identification of patient care team members, mobile clinical workflows, secure and timely critical alerts, and more.';
 
 class ButtonAlignCenterShowHide extends React.Component {
   constructor(props) {
     super(props);
 
     this.state = { isOpen: false };
     this.toggleShowHide = this.toggleShowHide.bind(this);
+    this.focusRef = React.createRef();
   }
 
   toggleShowHide() {
@@ -21,8 +22,8 @@ class ButtonAlignCenterShowHide extends React.Component {
   render() {
     return (
       <div>
-        <ShowHide buttonAlign="center" preview={<p>{previewText}</p>} isOpen={this.state.isOpen} onChange={this.toggleShowHide}>
-          <p>{fullText}</p>
+        <ShowHide focusRef={this.focusRef} buttonAlign="center" preview={<p>{prefix}</p>} isOpen={this.state.isOpen} onChange={this.toggleShowHide}>
+          <p><ShowHideFocuser ref={this.focusRef} prefix={prefix} focusableText={focusableText} /></p>
         </ShowHide>
       </div>
     );

@@ -1,15 +1,16 @@
 import React from 'react';
-import ShowHide from 'terra-show-hide';
+import ShowHide, { ShowHideFocuser } from 'terra-show-hide';
 
-const fullText = 'A connected care team starts with an integrated communication strategy. CareAware ConnectTM is a healthcare communication tool that leverages the use of intuitive technology to help associate the right care team members with the right patients and provides a way to effectively communicate and collaborate while on the go through a smart, mobile device. Integration with Cerner Millennium® enables care teams to streamline bedside workflows including medication administration, device association, and specimen collection.';
-const previewText = fullText.substring(0, 280);
+const prefix = 'A connected care team starts with an integrated communication strategy. CareAware ConnectTM is a healthcare communication tool that leverages the use of intuitive technology to help associate the right care team members with the right patients and provides a way to effectively';
+const focusableText = 'communicate and collaborate while on the go through a smart, mobile device. Integration with Cerner Millennium® enables care teams to streamline bedside workflows including medication administration, device association, and specimen collection.';
 
 class ButtonAlignRightShowHideTest extends React.Component {
   constructor(props) {
     super(props);
 
     this.state = { isOpen: false };
     this.toggleShowHide = this.toggleShowHide.bind(this);
+    this.focusRef = React.createRef();
   }
 
   toggleShowHide() {
@@ -21,8 +22,8 @@ class ButtonAlignRightShowHideTest extends React.Component {
   render() {
     return (
       <div>
-        <ShowHide buttonAlign="end" preview={<p>{previewText}</p>} isOpen={this.state.isOpen} onChange={this.toggleShowHide}>
-          <p>{fullText}</p>
+        <ShowHide focusRef={this.focusRef} buttonAlign="end" preview={<p>{prefix}</p>} isOpen={this.state.isOpen} onChange={this.toggleShowHide}>
+          <p><ShowHideFocuser ref={this.focusRef} prefix={prefix} focusableText={focusableText} /></p>
         </ShowHide>
       </div>
     );

@@ -1,16 +1,25 @@
+/* eslint-disable jsx-a11y/anchor-is-valid */
 import React from 'react';
-import ShowHide from 'terra-show-hide';
-
-const sentences = [
-  <h3 key="sentence1">Key Benefits of Cerner Cardiovascular Solutions</h3>,
-  <p key="sentence2">Eliminates silos of information and the resulting inefficiencies with a unified EHR and cardiovascular system</p>,
-  <p key="sentence3">Creates efficient diagnostic workflows, image management and analysis</p>,
-  <p key="sentence4">Enhances clinical, financial and performance outcomes with comprehensive procedural documentation</p>,
-  <p key="sentence5">Promotes cardiac disease management through health maintenance protocols</p>,
-  // <p key="sentence6">Lorem ipsum dolor sit amet consectetur adipiscing elit.</p>,
-  // <p key="sentence7">Lorem ipsum dolor sit amet consectetur adipiscing elit.</p>,
-  // <p key="sentence8">Lorem ipsum dolor sit amet consectetur adipiscing elit.</p>,
-  // <p key="sentence9">Lorem ipsum dolor sit amet consectetur adipiscing elit.</p>
+import ShowHide, { ShowHideFocuser } from 'terra-show-hide';
+
+const header = 'Bringing clarity to life sciences and healthcare decision-making ';
+const text = [
+  'When we accelerate the discovery, development and deployment of life-enhancing insights and therapies, clinicians and patients benefit. Connecting data and breaking down silos',
+  'across the healthcare innovation ecosystem must be our collective focus to help improve everyday health for all people. Several factors help bring clarity to life sciences, researchers and clinicians and',
+  'guide better care,',
+  'including:',
+];
+const listItems = [
+  <li key="item1">Data-driven research solutions for commercial and real-world evidence collaborators and health providers</li>,
+  <li key="item2">Support to move from simply accumulating and analyzing data to linking and generating deeper insights </li>,
+  <li key="item3">Combined life sciences knowledge, healthcare innovation and collaborative research expertise</li>,
+  <li key="item4">Access to an expansive network of diverse research-ready health systems; as well as de-identified, real-world data from the EHR that also includes patient-reported outcomes</li>,
+];
+const conclusion = 'Through data and technology, we have the power to help life sciences, clinicians and researchers expand therapeutic areas of research and generate better evidence to solve healthcare challenges around the world. Together, we can accelerate groundbreaking research and trial opportunities that have the potential to transform everyday healthcare and improve people’s lives.';
+
+const preview = [
+  <h3 key="header">{header}</h3>,
+  <p key="prefix">{text[0]}</p>,
 ];
 
 class CustomButtonTextShowHide extends React.Component {
@@ -19,6 +28,7 @@ class CustomButtonTextShowHide extends React.Component {
 
     this.state = { isOpen: false };
     this.toggleShowHide = this.toggleShowHide.bind(this);
+    this.focusRef = React.createRef();
   }
 
   toggleShowHide() {
@@ -31,19 +41,29 @@ class CustomButtonTextShowHide extends React.Component {
     let customText = '';
 
     if (this.state.isOpen) {
-      customText = `Hide ${sentences.length - 3} Sentences`;
+      customText = 'Hide Composit Content';
     } else {
-      customText = `Show ${sentences.length - 3} More Sentences`;
+      customText = 'Show Composit Content';
     }
 
     return (
       <ShowHide
-        preview={[sentences[0], sentences[1], sentences[2]]}
+        preview={preview}
         onChange={this.toggleShowHide}
         isOpen={this.state.isOpen}
         buttonText={customText}
+        focusRef={this.focusRef}
       >
-        {sentences}
+        <h3>{header}</h3>
+        <p>
+          <ShowHideFocuser ref={this.focusRef} prefix={text[0]} focusableText={text[1]} />
+          {' '}
+          <a href="#">{text[2]}</a>
+          {' '}
+          {text[3]}
+        </p>
+        <ul>{listItems}</ul>
+        <p>{conclusion}</p>
       </ShowHide>
     );
   }