USWDS-Next - Alpha: Create `usa-details` web component #29

amyleadem · 2024-06-26T23:50:30Z

Summary

Created an alpha version of a usa-details web component

Related issue

Closes #19

Preview link

Sample implementation

<usa-details name="example-group-name">
  <details open="true">
    <summary>First Amendment</summary>
    <div slot="details-body">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.</div>
  </details>
  <details>
    <summary>Second Amendment</summary>
    <div slot="details-body">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.</div>
  </details>      
  <details>
    <summary>Third Amendment</summary>
    <div slot="details-body">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.</div>
  </details>
</usa-details>

Reference

Details element (MDN)

Requirements notes (WIP)

Common component names

Details, Accordion, Collapse

Variants

Type	Name	Description
Border	Borderless (default)	No border
	Bordered	Border around panel and button
Group	Multi select (default)	Allow multiple panels in a group to be open at one time
	Single select	Open only one panel in a group at a time

Settings and CSS Variables

Description	Related USWDS setting	New CSS variable
Border width	`$theme-accordion-border-width`	`--theme-details-border-width`
Border color	`$theme-accordion-border-color`	`--theme-details-border-color`
Button background color	`$theme-accordion-button-background-color`	`--theme-details-summary-background-color`
Panel background color	`$theme-accordion-background-color`	`--theme-details-background-color`
Component font family	`$theme-accordion-font-family`	`--theme-details-font-family`

Possibilities for additional customization:

Summary/content font weight
Summary/content padding
Summary/content text color
Summary/content font size
Open/close icons
Icon placement (left/right)

Accessibility

See related accessibility tests

Attributes & Props

Attribute	Element	Description
`open="true"`	`<details>`	If the `open` attribute is present on the `<details>` element, the content inside its `details-content` slot should be visible on load.
`name="[group name]"`	`<details>`	If a defined `name` attribute is present on the `<details>` element, the `<details>` elements with the same `name` value will be treated as a single-select group and toggle each other.

Slots

Slot name	Expected Element	Example code	Count
`details-body`	`<div>`	`<div slot="details-body">[Accordion panel content]</div>`	1

Expected interactions:

All:
- You can show and hide content panels with enter, spacebar, mouse click, or voice command
- You can insert rich text and other components inside the content region
Single select: When you open a panel in the group, the other panels in the group close
Multi select: When you open a panel in the group, the other panels stay in their current open/closed state

Test cases

Be able to change background colors, text colors, border colors, change icons, update icon placement
Add new style property and customize it

amyleadem

Update: I had originally imagined that the implementation would look something like this for single select "accordion" behavior:

<usa-details-group>
  <usa-details name="example-details-group">
    <details>
      <summary>First Amendment</summary>
      <div slot="details-body">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.</div>
    </details>
  </usa-details>
  <usa-details name="example-details-group">
    <details>
      <summary>Second Amendment</summary>
      <div slot="details-body">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.</div>
    </details>
  </usa-details>
</usa-details-group>

However, this structure isolated the two <details> elements from each other in the shadow DOM and prevented the native name attribute from working as expected. I updated the structure to this instead so that we could rely on the the native functionality of the <details> element to toggle the component instead of writing custom JS:

<usa-details>
  <details open="true" name="example-details-group">
    <summary>First Amendment</summary>
    <div slot="details-body">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.</div>
  </details>
  <details name="example-details-group">
    <summary>Second Amendment</summary>
    <div slot="details-body">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.</div>
  </details>
</usa-details>

Curious to hear if anyone has concerns about this update.

…/add-details-component

mejiaj

Nice job! It looks just like the existing accordion. My testing focused a lot on the functionality of the component.

I tested the following:

Changing controls
Updating detail attributes & content
Comparing custom element properties to native details element

Can we add a basic example of how to use in the PR description? Additionally a preview link would help too.

PR comments use conventional comment style.

mejiaj · 2024-07-05T18:26:13Z

src/components/usa-details/index.js

Question: Are there any events we can trigger via JS on this component?

For example, <usa-banner> can be toggled via toggle() in console.

details-toggle-2024-07-05.at.13.17.58.webm

mejiaj · 2024-07-05T18:54:38Z

src/components/usa-details/details.stories.js

+    item1Summary: {name: "Item 1 - Summary text"},
+    item1Content: { name: "Item 1 - Panel content"},
+    item1Open: { name: "Item 1 - Open panel on load"},
+    item2Show: { name: "Include item 2 in preview"},
+    item2Summary: {name: "Item 2 - Summary text", if: { arg: 'item2Show' } },
+    item2Content: { name: "Item 2 - Panel content", if: { arg: 'item2Show' } },
+    item2Open: { name: "Item 2 - Open panel on load", if: { arg: 'item2Show' } },
+    item3Show: { name: "Include item 3 in preview"},
+    item3Summary: {name: "Item 3 - Summary text", if: { arg: 'item3Show' } },
+    item3Content: { name: "Item 3 - Panel content", if: { arg: 'item3Show' } },
+    item3Open: { name: "Item 3 - Open panel on load", if: { arg: 'item3Show' } },


Suggestion (if-minor): These are marked as defaults, but they're only used in two variants.

It'd be nice to cleanly separate this. Some suggestions:

Separate default strings from default controls. For example, default args would be reserved for args that are seen on most/every variant.

Adding ability to automatically add any number of accordions (depending on LOE).

mejiaj · 2024-07-05T19:00:14Z

src/components/usa-details/index.js

+  static properties = {
+    bordered: { type: Boolean }
+  }


Question (non-blocking): Should open be listed here?

I was only listing the props that should be added to <usa-details> here. In the current iteration, the open attribute should be added to the the child <details> element, so I left it off the properties list for now. Let me know if that should change!

mejiaj · 2024-07-05T19:07:37Z

src/components/usa-details/index.js

+
+  template() {
+    const classes = {
+      "usa-details": true,


Issue: This should be on the element if it's not dynamic.

mejiaj · 2024-07-05T19:17:19Z

src/components/usa-details/index.js

+          this.content.classList.add('usa-details__content');
+
+          return html`
+            <details class="${classMap(classes)}" open="${this.open || nothing}" name="${this.name || nothing}">


Issue: In native disclosure, the open attribute doesn't have a value. For example something like open="false" will still keep the element open.

We should follow this pattern to keep things consistent.

The Details disclosure element - HTML: HyperText Markup Language | MDN

src/components/usa-details/index.js

mejiaj · 2024-07-05T19:28:55Z

src/components/usa-details/index.js

+ * @cssprop --theme-details-font-family - Sets the font family for the details element
+ * @cssprop --theme-details-border-color - Sets the border width for the details element
+ * @cssprop --theme-details-border-width - Sets the border color for the details element
+ * @cssprop --theme-details-background-color - Sets the background color of the content panels
+ * @cssprop --theme-details-summary-background-color - Sets the background color of the summary element


Thought: I wonder if there's a way to show these component settings in storybook args.

mejiaj · 2024-07-05T19:30:44Z

src/components/usa-details/usa-details.css.js

Question: Curious why didn't we use usa-accordion SCSS here?

mejiaj · 2024-07-05T19:47:28Z

src/components/usa-details/details.stories.js

+    item1Summary: {name: "Item 1 - Summary text"},
+    item1Content: { name: "Item 1 - Panel content"},
+    item1Open: { name: "Item 1 - Open panel on load"},
+    item2Show: { name: "Include item 2 in preview"},
+    item2Summary: {name: "Item 2 - Summary text", if: { arg: 'item2Show' } },
+    item2Content: { name: "Item 2 - Panel content", if: { arg: 'item2Show' } },
+    item2Open: { name: "Item 2 - Open panel on load", if: { arg: 'item2Show' } },
+    item3Show: { name: "Include item 3 in preview"},
+    item3Summary: {name: "Item 3 - Summary text", if: { arg: 'item3Show' } },
+    item3Content: { name: "Item 3 - Panel content", if: { arg: 'item3Show' } },
+    item3Open: { name: "Item 3 - Open panel on load", if: { arg: 'item3Show' } },


Thought: It'd be nice if we could do this in a more intuitive way that wasn't focused on a fixed number of elements.

Possible control ideas

A button in controls that toggles fields for header/content.

An array of objects for header/body content.

A textarea to input any number of <details>.

mejiaj · 2024-07-05T19:49:18Z

src/components/usa-details/usa-details.css.js

+      .usa-details__summary {
+        /* TODO: use local files */
+        /* TODO: determine if background image is still the best way to add icons here */
+        background-image: url(https://designsystem.digital.gov/assets/img/usa-icons/add.svg);


Question (non-blocking): Is it possible to override this? How would I set my own icon?

amyleadem · 2024-07-09T16:33:52Z

src/components/usa-details/index.js

+          this.content.classList.add('usa-details__content');
+
+          return html`
+            <details class="${classMap(classes)}" open="${this.open || nothing}" name="${this.name || nothing}">


Suggested change

<details class="${classMap(classes)}" open="${this.open || nothing}" name="${this.name || nothing}">

<details class="usa-details ${classMap(classes)}" open="${this.open || nothing}" name="${this.name || nothing}">

amyleadem · 2024-07-10T23:47:30Z

Converting to draft while experiment with theming and adding usa-accordion component.

- Moved to separate PR to prevent scope creep

Set up initial details component

8cec43f

amyleadem changed the title ~~USWDS-Next: Set up initial details component~~ USWDS-Next: Create usa-details web component Jun 27, 2024

amyleadem changed the title ~~USWDS-Next: Create usa-details web component~~ USWDS-Next - Alpha: Create usa-details web component Jun 27, 2024

amyleadem added 6 commits June 28, 2024 09:48

Add open and name attributes

c7c9700

Add accordion styles in JS; Add multiple details items

671abca

Remove old code; format code

7ee3737

Move styles to separate js file

57140c8

Rename style classes; remove unnecessary styles

7509fc1

Add bordered variant; add css vars for settings

a50916c

amyleadem commented Jul 3, 2024

View reviewed changes

amyleadem added 2 commits July 3, 2024 10:29

Remove console.log

27ef4e6

Add TODO comments; format code

f628083

amyleadem marked this pull request as ready for review July 3, 2024 19:28

amyleadem requested review from mejiaj and mahoneycm July 3, 2024 19:55

amyleadem added 2 commits July 3, 2024 14:27

Merge branch 'develop' of https://github.com/uswds/uswds-next into al…

55f89c8

…/add-details-component

Merge develop; move details component into src

83f51f1

mejiaj requested changes Jul 5, 2024

View reviewed changes

amyleadem added 4 commits July 5, 2024 14:13

Enable remark-gfm for doc formatting

db372e3

Add custom docs for details component

b4ebc5d

Update --theme- -> --usa-theme-

21c2a02

Move template content directly to render

cd7b972

amyleadem commented Jul 9, 2024

View reviewed changes

amyleadem added 7 commits July 9, 2024 16:19

Rename usa-details.mdx -> readme.mdx

26e846c

Rename custom docs file; add css var controls

d833c45

Rename readme and stories.js

4f8bad3

Move name attribute to usa-details

cef69c9

Replace name attribute with multiselect

0c38bf6

Add accordion component; add additional core vars

b7f5356

Update details to diff from accordion

c0f002e

amyleadem marked this pull request as draft July 10, 2024 23:47

amyleadem added 3 commits July 15, 2024 08:25

Remove accordion component

4c8c0b4

- Moved to separate PR to prevent scope creep

Fix typo in top margin var

ab86a58

Remove test class

184fad1

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

USWDS-Next - Alpha: Create `usa-details` web component #29

USWDS-Next - Alpha: Create `usa-details` web component #29

amyleadem commented Jun 26, 2024 •

edited

Loading

amyleadem left a comment •

edited

Loading

mejiaj left a comment •

edited

Loading

mejiaj Jul 5, 2024

mejiaj Jul 5, 2024

mejiaj Jul 5, 2024

amyleadem Jul 8, 2024

mejiaj Jul 5, 2024

mejiaj Jul 5, 2024

mejiaj Jul 5, 2024

mejiaj Jul 5, 2024

mejiaj Jul 5, 2024

mejiaj Jul 5, 2024

amyleadem Jul 9, 2024

amyleadem commented Jul 10, 2024

	<details class="${classMap(classes)}" open="${this.open \|\| nothing}" name="${this.name \|\| nothing}">
	<details class="usa-details ${classMap(classes)}" open="${this.open \|\| nothing}" name="${this.name \|\| nothing}">

USWDS-Next - Alpha: Create usa-details web component #29

Are you sure you want to change the base?

USWDS-Next - Alpha: Create usa-details web component #29

Conversation

amyleadem commented Jun 26, 2024 • edited Loading

Summary

Related issue

Preview link

Sample implementation

Reference

Requirements notes (WIP)

Common component names

Variants

Settings and CSS Variables

Accessibility

Attributes & Props

Slots

Expected interactions:

Test cases

amyleadem left a comment • edited Loading

Choose a reason for hiding this comment

mejiaj left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amyleadem commented Jul 10, 2024

USWDS-Next - Alpha: Create `usa-details` web component #29

USWDS-Next - Alpha: Create `usa-details` web component #29

amyleadem commented Jun 26, 2024 •

edited

Loading

amyleadem left a comment •

edited

Loading

mejiaj left a comment •

edited

Loading