adobe
feat(contextual-help): add contextual help pattern
Description
Adds @spectrum-web-components/contextual-help, as per https://spectrum.adobe.com/page/contextual-help/
Related issue(s)
- https://github.com/adobe/spectrum-web-components/discussions/4281
Motivation and context
Contextual help is a pattern used widely across Adobe apps. Even if at its core it is a simple component, the lack of a reusable component around this pattern results in different teams implementing different versions of it. Differences in implementation differ not only on the visual level, but also on the accessibility and mobile responsiveness level. Current implementations are some of them lacking keyboard navigation support, screen reader support, and not taking into consideration user experience on mobile devices.
How has this been tested?
- [ ] Test case 1
- Go here
- Do this
- [ ] Test case 2
- Go here
- Do this
Screenshots (if appropriate)
Types of changes
- [ ] Bug fix (non-breaking change which fixes an issue)
- [x] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [ ] Chore (minor updates related to the tooling or maintenance of the repository, does not impact compiled assets)
Checklist
- [x] I have signed the Adobe Open Source CLA.
- [x] My code follows the code style of this project.
- [x] If my change required a change to the documentation, I have updated the documentation in this pull request.
- [x] I have read the CONTRIBUTING document.
- [x] I have added tests to cover my changes.
- [ ] All new and existing tests passed.
- [x] I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
Best practices
This repository uses conventional commit syntax for each commit message; note that the GitHub UI does not use this by default so be cautious when accepting suggested changes. Avoid the "Update branch" button on the pull request and opt instead for rebasing your branch against main.
Branch preview
Visual regression test results
When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:
- High Contrast Mode | Medium | LTR
- Spectrum | Lightest | Medium | LTR
- Spectrum | Lightest | Medium | RTL
- Spectrum | Lightest | Large | LTR
- Spectrum | Lightest | Large | RTL
- Spectrum | Light | Medium | LTR
- Spectrum | Light | Medium | RTL
- Spectrum | Light | Large | LTR
- Spectrum | Light | Large | RTL
- Spectrum | Dark | Medium | LTR
- Spectrum | Dark | Medium | RTL
- Spectrum | Dark | Large | LTR
- Spectrum | Dark | Large | RTL
- Spectrum | Darkest | Medium | LTR
- Spectrum | Darkest | Medium | RTL
- Spectrum | Darkest | Large | LTR
- Spectrum | Darkest | Large | RTL
- Express | Lightest | Medium | LTR
- Express | Lightest | Medium | RTL
- Express | Lightest | Large | LTR
- Express | Lightest | Large | RTL
- Express | Light | Medium | LTR
- Express | Light | Medium | RTL
- Express | Light | Large | LTR
- Express | Light | Large | RTL
- Express | Dark | Medium | LTR
- Express | Dark | Medium | RTL
- Express | Dark | Large | LTR
- Express | Dark | Large | RTL
- Express | Darkest | Medium | LTR
- Express | Darkest | Medium | RTL
- Express | Darkest | Large | LTR
- Express | Darkest | Large | RTL
- Spectrum-two | Light | Medium | LTR
- Spectrum-two | Light | Medium | RTL
- Spectrum-two | Light | Large | LTR
- Spectrum-two | Light | Large | RTL
- Spectrum-two | Dark | Medium | LTR
- Spectrum-two | Dark | Medium | RTL
- Spectrum-two | Dark | Large | LTR
- Spectrum-two | Dark | Large | RTL
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
Lighthouse scores
| Category | Latest (report) | Main (report) | Branch (report) |
|---|---|---|---|
| Performance | 0.99 | 0.99 | 0.99 |
| Accessibility | 1 | 1 | 1 |
| Best Practices | 1 | 1 | 1 |
| SEO | 1 | 0.92 | 0.92 |
| PWA | 1 | 1 | 1 |
What is this?
Lighthouse scores comparing the documentation site built from the PR ("Branch") to that of the production documentation site ("Latest") and the build currently on main ("Main"). Higher scores are better, but note that the SEO scores on Netlify URLs are artifically constrained to 0.92.
Transfer Size
| Category | Latest | Main | Branch |
|---|---|---|---|
| Total | 224.097 kB | 210.69 kB 🏆 | 210.695 kB |
| Scripts | 53.43 kB | 48.317 kB 🏆 | 48.395 kB |
| Stylesheet | 34.839 kB | 30.472 kB | 30.373 kB 🏆 |
| Document | 5.996 kB | 5.268 kB 🏆 | 5.312 kB |
| Font | 126.953 kB | 126.633 kB | 126.615 kB 🏆 |
Request Count
| Category | Latest | Main | Branch |
|---|---|---|---|
| Total | 48 | 45 | 45 |
| Scripts | 37 | 37 | 37 |
| Stylesheet | 5 | 5 | 5 |
| Document | 1 | 1 | 1 |
| Font | 2 | 2 | 2 |
Tachometer results
Chrome
color-field permalink
basic-test
| Version | Bytes | Avg Time | vs remote | vs branch |
|---|---|---|---|---|
| npm latest | 487 kB | 41.05ms - 43.29ms | - | unsure 🔍 -6% - +1% -2.59ms - +0.46ms |
| branch | 475 kB | 42.21ms - 44.27ms | unsure 🔍 -1% - +6% -0.46ms - +2.59ms |
- |
combobox permalink
basic-test
| Version | Bytes | Avg Time | vs remote | vs branch |
|---|---|---|---|---|
| npm latest | 709 kB | 35.45ms - 36.41ms | - | faster ✔ 3% - 6% 1.17ms - 2.31ms |
| branch | 696 kB | 37.37ms - 37.97ms | slower ❌ 3% - 6% 1.17ms - 2.31ms |
- |
light-dom-test permalink
| Version | Bytes | Avg Time | vs remote | vs branch |
|---|---|---|---|---|
| npm latest | 710 kB | 386.18ms - 392.60ms | - | faster ✔ 3% - 5% 10.36ms - 20.16ms |
| branch | 697 kB | 400.95ms - 408.35ms | slower ❌ 3% - 5% 10.36ms - 20.16ms |
- |
Firefox
color-field permalink
basic-test
| Version | Bytes | Avg Time | vs remote | vs branch |
|---|---|---|---|---|
| npm latest | 495 kB | 75.74ms - 78.62ms | - | unsure 🔍 -6% - +0% -4.78ms - +0.26ms |
| branch | 483 kB | 77.37ms - 81.51ms | unsure 🔍 -0% - +6% -0.26ms - +4.78ms |
- |
combobox permalink
basic-test
| Version | Bytes | Avg Time | vs remote | vs branch |
|---|---|---|---|---|
| npm latest | 709 kB | 61.74ms - 68.78ms | - | slower ❌ 1% - 13% 0.51ms - 7.93ms |
| branch | 696 kB | 59.88ms - 62.20ms | faster ✔ 1% - 12% 0.51ms - 7.93ms |
- |
light-dom-test permalink
| Version | Bytes | Avg Time | vs remote | vs branch |
|---|---|---|---|---|
| npm latest | 710 kB | 717.68ms - 740.00ms | - | slower ❌ 2% - 6% 15.05ms - 40.03ms |
| branch | 697 kB | 695.69ms - 706.91ms | faster ✔ 2% - 5% 15.05ms - 40.03ms |
- |
I'm marking it as ready for review even if unit tests are incomplete, because I am looking for a high level review of this current implementation, and any changes would make the tests obsolete.
I found this component to be a good use case for the slottable-request pattern. However, if this seems overkill given the small contents of the popover I can get rid of it.
I'm looking for comments on the width / max-width dilema: https://github.com/adobe/spectrum-web-components/discussions/4281#discussioncomment-9186262, as well as on the mobile behaviour.
@Rajdeepc as per office hours discussion, I removed the trigger directive usage and went back to sp-overlay, as it was better suited for my component.
Can you look into why these examples don't work for this component?
@TarunAdobe seems to be due to the type of the controls: radio, number, and text which do not map well on Picker. I can convert the radio one into select, but the number and text I don't think that those can be converted. Do we have a way to exclude them from the docs, but not the storybook?
@Rocss Hmm seems like you're right! Thanks for pointing it out. We will take this up in a separate PR as this needs some work around how we create these demos.
@Rocss Would it be okay to surface up a contextual-help-memory.test.ts with this PR so that we can triage any memory leaks in the code similar to this
@Rocss Hmm seems like you're right! Thanks for pointing it out. We will take this up in a separate PR as this needs some work around how we create these demos.
Should be fixed by #4512
@blunteshwar I observe this, however, the failing tests are not related to this PR, and the error seems to be for Action Button Error: There was no baseline image to compare against.. Is this happening on any other PR?