Story: Create JS for usa-accordion

[andyvanavery31]

As a user of the NCIDS, I want to be able to condense sections of content into an accordion on a site page, so that my visitors can easily locate a section and then explore it further without needing to scroll through large amounts of content to get to it.

Requirements

• The js will be built to work with the css from the usa-accordion component from USWDS
• The js will allow the creator to indicate what the sections will be that will be reduced into the accordion headings
• The js will allow the creator to indicate what content will be hidden within the sections of the accordion
• The js will ensure that when the section is collapsed and the user clicks anywhere in the heading container, the section will expand
• The js will ensure that when the section is expanded and the user clicks anywhere in the heading container, the section will collapse
• The js will have an option that will allow the user to expand multiple sections at the same time. Opening multiple sections will be disabled as default
• The js will allow the option to have the first section will appear expanded, while all other sections will appear collapsed as the standard for its use, and this option will be active as default
• The js will allow nested accordions to function where, if the section containing another accordion is expanded, the internal accordion will follow the same rules as a stand alone accordion (first section will be expanded. Other section will be collapsed)
• If a user is viewing a url with an anchor fragment (i.e. #) we need to find that heading, or section those contents are in, and expand that section on init.
• The ncids-twig-template for this component will be created

Notes

• Section is defined as heading + content

DoR DS Tasks

• Refine user story statement
• Create scenarios
• Internal Review of Scenarios
  • Design Approval
  • Development Approval
  • IA Approval
• Internal review of DS AC's (Development, Design, IA, QA)

DoD DS Tasks

• Develop DS class from design Figma comp
  • Update Documentation Site
    • Draft the guidance and all sections necessary for addition to the NCIDS for All Documentation Site. TIMING OF DOCUMENTATION COMPLETION TO BE DISCUSSED ON 10JAN2024.
    • Create page for the Accordion within the Components section
    • Update the list of components on the main Components landing page
  • Update Storybook Site
  • Update Example Site (if needed)
• Internal review of the DS solution
• Demo DS solution to client

Resources

• USWDS Documentation on usa-accordion https://designsystem.digital.gov/components/accordion/

Scenarios

• Storybook: Under USWDS, Components, on the Accordion page, the JS will be updated to the solution from this ticket
  • We actually have 3 forms of HTML to support. (Noted in the technical section) The "Basic HTML" is what we should use for our default and variants. The other html tests should be under test cases.
  • 📁 Accordion
    • 📁 Default
      • Default
      • Default - multiselectable
    • 📁 Variants
      • 📁 Bordered
        • Bordered
        • Bordered - multiselectable
    • 📁 Test Cases
      • 📁 Basic HTML
        • Nested Example
        • No JS
      • 📁 Cancer.gov HTML
        • Sample article
        • Nested
        • No JS
      • 📁 USWDS†

† USWDS may live in a different folder based on convos with @olitharp-nci

Acceptance Criteria

Default Single Accordion

Scenario: A user views a page with a usa-accordion component
  Given the js for the usa-accordion component has been created
    And the usa-accordion with the new js has been added to a page
  When the user views the usa-accordion component
  Then they will see the each section header displayed for the accordion
    And the first section will be expanded to display all of the hidden content
    And all other sections will be collapsed to hide the content within those sections
  When a user clicks on the heading container displayed for a collapsed section
  Then the section clicked will expand
  When a user clicks on the heading container displayed for an expanded section
  Then the section clicked will collapse
  When the user clicks on multiple collapsed section headers sequentially
  Then the clicked on section will expand
    And the previously expanded section will collapse

Single Accordion with First Section Collapsed

Scenario: A user views a page with a usa-accordion component
  Given the js for the usa-accordion component has been created
    And the usa-accordion with the new js has been added to a page
  When the user views the usa-accordion component
  Then they will see the each section header displayed for the accordion
    And all sections will be collapsed to hide the content within those sections
  When a user clicks on the heading container displayed for a collapsed section
  Then the section clicked will expand
  When a user clicks on the heading container displayed for an expanded section
  Then the section clicked will collapse
  When the user clicks on multiple collapsed section headers sequentially
  Then the clicked on section will expand
    And the previously expanded section will collapse

Single Accordion with Multiple Expansions Allowed

Scenario: A user views a page with a usa-accordion component with multiple expansions of sections allowed
  Given the js for the usa-accordion component has been created
    And the usa-accordion with the new js has been added to a page
  When the user views the usa-accordion component
  Then they will see the each section header displayed for the accordion
    And the first section will be expanded to display all of the hidden content
    And all other sections will be collapsed to hide the content within those sections
  When a user clicks on the heading container displayed for a collapsed section
  Then the section clicked will expand
  When a user clicks on the heading container displayed for an expanded section
  Then the section clicked will collapse
  When the user clicks on multiple collapsed section headers sequentially
  Then all clicked sections will expand sequentially

Nested Default Accordions

Scenario: A user views a page with a usa-accordion component nested within another usa-accordion
  Given the js for the usa-accordion component has been created
    And the usa-accordion with the new js has been added to a page nested in another usa-accordion
  When the user views the usa-accordion component
  Then they will see the each section header displayed for the accordion
    And the first section will be expanded to display all of the hidden content
    And all other sections will be collapsed to hide the content within those sections
  When a user clicks on the heading container displayed for a collapsed section
  Then the section clicked will expand
  When a user clicks on the heading container displayed for an expanded section
  Then the section clicked will collapse
  When the user clicks on multiple collapsed section headers sequentially
  Then the clicked on section will expand
    And the previously expanded section will collapse
  When the user clicks on the heading of a section that contains a nested accordion
  Then the nested accordion will appear
    And the information surrounding the nested accordion will be visible (it is within the level of the first accordion)
    And the first section of the nested accordion will be expanded
    And all other sections of the nested accordion will be collapsed
  When a user clicks on the section heading for a collapsed section of the nested accordion
  Then that section will expand within the expanded first level accordion
  When a user clicks on the section heading for any expanded section of the nested accordion
  Then that section will collapse within the expanded first level accordion
  When a user clicks on multiple collapsed sections within the nested accordion sequentially
  Then the clicked on nested section will expand
    And the previously expanded nested section will collapse
  When a user clicks on the section heading for the expanded first level accordion that contains the nested accordion
  Then the section will collapse
  When the user reclicks on the same section heading of the now collapsed first level accordion that contains the nested accordion
  Then the section will expand with the nested accordion visible
    And the first section of the nested accordion will be expanded
    And the other sections of the nested accordion will be collapsed

[bryanpizzillo]

Technical Solution

This will go into ncids-js/usa-accordion. You will need to add ncids-js/usa-accordion to both ncids-js/typedoc.json and package.json in the exports section.

Supported HTML

Basic HTML

(Before JS initializes)

<div class="usa-accordion usa-prose">
  <hX>Heading</hX>
  <p></p>
  <ul>...</ul>
  <div class=" usa-accordion usa-prose">
     <hY>Sub heading</hY>
     <p></p>
     <hZ id="_section8">Sub Sub Heading</hZ>
  </div>
  <hY>Some sub heading</hY>
  
  <hX>Heading 2</hX>
  ...
</div>

Cancer.gov Article HTML

(Before JS initializes)

<article class="usa-accordion">
   <section class="usa-prose" aria-labeled-by="s1">
      <hX id="s1"></hX>
        <p></p>
        <ul>...</ul>
   </section>
</article>

USWDS HTML

(Before JS initializes. Yes they require you to add in all the stuff we would normally do.)

<div class="usa-accordion">
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="true"
      aria-controls="a1"
    >
      First Amendment
    </button>
  </h4>
  <div id="a1" class="usa-accordion__content usa-prose">
    <p>
      Congress shall make no law respecting an establishment of religion, or
      prohibiting the free exercise thereof; or abridging the freedom of speech,
      or of the press; or the right of the people peaceably to assemble, and to
      petition the Government for a redress of grievances.
    </p>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="a2"
    >
      Second Amendment
    </button>
  </h4>
  <div id="a2" class="usa-accordion__content usa-prose">
    <p>
      A well regulated Militia, being necessary to the security of a free State,
      the right of the people to keep and bear Arms, shall not be infringed.
    </p>
    <ul>
      <li>This is a list item</li>
      <li>Another list item</li>
    </ul>
  </div>
  <h4 class="usa-accordion__heading">
    <button
      type="button"
      class="usa-accordion__button"
      aria-expanded="false"
      aria-controls="a3"
    >
      Third Amendment
    </button>
  </h4>
  <div id="a3" class="usa-accordion__content usa-prose">
    <p>
      No Soldier shall, in time of peace be quartered in any house, without the
      consent of the Owner, nor in time of war, but in a manner to be prescribed
      by law.
    </p>
  </div>
</div>

Initialization Notes:

• Any classes attached to headings need to be removed. (e.g. nci-header-h2...)
• After HTML is USWDS

Initialization Flow:

• For each child element of <div class="usa-accordion">
  • I think everything prior to the first header is left alone??
  • Is this a heading yes?
    • Is the heading the first one?
      • take note of the heading level. We will call this Heading Level
    • is this heading the same level as Heading Level?
      • then start a new block of contents; generate an id for the element -- THIS NEEDS TO BE UNIQUE ACCROSS THE PAGE!!!
      • turn the HX text into a a button like USWDS. set aria-controls to generated id above
      • strip classes from header (but remember them)
    • This is not at the Heading Levle
      • then yoink the element to the current block of contents
  • Is this a header no? then yoink the element to the current block of contents

NOTE: Uninitialization needs to turn it back into the EXACT html as before.

** The USWDS classes for the button should be used, and proper aria attributes. This should cover the open/close svg. **

NOTE: If a user is viewing a url with an anchor fragment (i.e. #) we need to find that heading, or section those contents are in, and expand that section on init.

Component Options

• allowMultiple - boolean - Allow multiple items to be open at the same time. Default: false
• openSections - array - Maybe. Defaults to [1].

Data Attributes

• On Div
  • [For autoinit] data-allow-multiple - sets allowMultiple as true
  • [Fot autoinit] data-open-sections - this maps to openSections.

Public Component Methods

• getSections() - returns AccordionSection this is order based on the dom ordering on the page
  getSections was found not to be as important for end user as toggleSectionId
  • AccordionSection:
    • Heading: HTMLElement
    • Contents: HTMLElement
    • Status: Open | Closed
    • ToggleStatus() - Expands or Collapses the section based on its current state.
      • Fires off usa-accordion:section:expand(AccordionSection) when Closed -> Open
      • Fires off usa-accordion:section:collapsed(AccordionSection) when Open -> Close
      • Do not fire when initializing or when Expand or Collapse All
• CloseAll() - Closes all sections.
  • Fires off usa-accordion:collapseAll(Accordion)
• OpenAll() - Opens all sections.
  • Fires off usa-accordion:expandAll(Accordion)
• toggleSectionWithId(sectionId: string) - toggles section with given id open/closed
• unregister() - reverse any html transformations made to instantiate an accordion

Events (See above)

• Maybe usa-accordion:initialized ??