10up/component-library

A library of barebones front-end components built with WordPress and accessibility in mind.

10up Component Library

A library of barebones front-end components built with WordPress and accessibility in mind.

Overview

At 10up, we strive to provide websites that yield a top-notch user experience. In order to improve both our efficiency and consistency, we need to standardize what we use and how we use it. Standardizing our approach to commonly-used front-end components allows us to understand better the inner workings of someone else’s project and produce better solutions for ourselves and our clients.

Each component in this library is built with simplicity and accessibility in mind, tailored to fit the often opinionated nature of WordPress core output. These components are intended to be easily adapted to any number of different projects and use cases.

All components are tested to be WCAG 2.1 Compliant.

Start browsing ☞

How to Use

To use a component, navigate to the component’s detail page to see demos, usage examples, and installation instructions.

Components

• Accordion
• Animate
• Countdown Timer
• Navigation
• Tabs
• Tooltip

Support Level

Active: 10up is actively working on this, and we expect to continue work for the foreseeable future including keeping tested up to the most recent version of WordPress. Bug reports, feature requests, questions, and pull requests are welcome.

Repository Structure and Engineering Guidelines

Visit the CONTRIBUTING page for initial contribution and engineering guidance.

This repository is broken into four parts. Within each part, there is an included README.md file that contains additinal pertinent engineering guidelines and instructions:

• packages: The UI components and scripts that are distributed as an NPM package, and test/demo pages for each component.

• test-utils: This is currently a work in progress.

• e2e: Testing suite for packages. Includes all package components for local testing.

• docs: The public facing documentation site. Includes codebase utilizng Jekyll to construct site. Pulls componets from latest release on npm.

Like what you see?

component-library's Issues

Pass the submenu back to the call

Is your feature request related to a problem? Please describe.
Yes. There is a sort of problem.

When someone clicks a link that opens a submenu, the .submenu element toggles open with aria-hidden="false"
However the anchor item actually clicked (above the submenu element) gets no toggled-on class of any sort. It is not easy to style it for when it is open/closed.

I tried using the callbacks:

onSubmenuOpen: () => { //no way of getting to the current submenu opened },
onSubmenuClose: () => {},

However the callbacks are not being passed any parameters. So it is difficult to get the currently opened submenu and do things with it, or with adjacent siblings, like the clicked anchor.

Describe the solution you'd like
Please pass parameters for the callbacks like so:
Line 241 in navigation.js:
this.settings.onSubmenuOpen.call(this, $submenu);

Then I can use it like so:
onSubmenuOpen: (subMenu ) => { subMenu.previousElementSibling.classList.add('something') },

Ability to change `sub-menu`

Is your feature request related to a problem? Please describe.
I noticed there is hard coded sub-menu class used in the nav component. Could this be part of settings so it could be changed to something else.

This would enable changing sub-menu class to something else that fits better for chosen naming convention.

Describe the solution you'd like
sub-menu can be default but this could be overwritten via settings.

Demo code missing site-menu-toggle class

Describe the bug
The example code for both HTML and Wordpress needs a site-menu-toggle class added to the main toggle element.

To Reproduce
Steps to reproduce the behavior:

1. Create a navigation output based on the markup provided.
2. Load the navigation in a browser window
3. Notice that on desktop, the navigation toggle still appears and its visibility isn't controlled by the script.

Expected behavior
When resizing from mobile to desktop, the navigation toggle should disappear, since it isn't required when the navigation becomes fully displayed.

Desktop (please complete the following information):

• OS: iOS
• Browser: Chrome
• Version: 84.0.4147.105

Additional context
By adding the site-menu-toggle class to the main toggle "a" element, this issue should be resolved.

a11y upgrades - refer to van11y

Verify a11y implementation and guidance is correct on components

Use Van11y as a resource to do the following (if another resource feels appropriate, please include):

1. analyze any enhancements we can / should make to our existing components
2. add any new components

From findings, create new issues / tasks to move this forward.

Van11y: https://van11y.net/

(also, run through a11y testing suites - i.e. siteimprove, axe)

Update Navigation Component

Is your feature request related to a problem? Please describe.

While creating a website using the navigation component, I found I needed to spend a lot of time adding code to get it working. There were also some issues with classes being added to the wrong elements with no way to change this without changing the core code completely.

After inquiring, I found that some developers using the component would normally have to add code on top of the navigation, and I feel a lot of time can be saved if some more options existed for a broader range of scenarios, while still remaining lightweight.

Here were some of the issues I encountered:

Navigation Button Element ONLY opens the navigation.
The menu element when clicked, only opens the ul element inside a nav. In many cases the menu button might need to open the nav itself or a wrapper div that might hold many menus or other elements. It would be nice to choose what the menu button opens.

No need for a menu toggle
In some cases you may have a menu that is in the sidebar and does not require a menu toggle at all. It just needs some javascript to open and close submenus on click. I think there should be a choice as to whether a menu toggle is needed to begin with.

OnSubMenuOpen callback does not pass a parameter of the submenu element opened
The callback functions don't have any params passed that would be helpful, especially the submenu function. We need the submenu that was opened to be passed here.

Desktop Submenus offscreen
Sometimes when using a large submenu, the submenu might go offscreen (see image below). I think checking for offscreen submenus and adding a class to fix it might be helpful.

submenu element
Sometimes .sub-menu might not be the class to target as submenus. I think we need a way to choose the selector for sub-menu elements and not rely on the default ways WordPress spits out the menu. We sometimes use custom walkers to change things.

CSS Issues

• The css that ships with the component only works and expects to work with only one menu with a class of primary-menu.
• The css is also set to display: none / block for most elements and I think that should be left to the developer to decide.
• Currently submenus only disappear once the JS is loaded, because the css is relying on javascript to show/hide. This means submenus show up for a second before disappearing.
• The css also doesn't apply basic styles one would expect like list-style-type: none; on the ul element, but it does include styles one may need to remove, like adding a plus icon to submenu items.

The Fix

Describe the solution you'd like

#49

I have actually created a solution by remaking the navigation, fixing all the items listed above.
In the new navigation I have:

• Added the option to have a menu toggle element only if you want one. The aria-controls on this element will decide what element will get toggled. It can be set to any element ID on page.
• Multiple menus can be made, each with a different media query size. The menu will go horizontal and vertical based on this query with a toggled class.
• All callbacks have parameters
• Option for submenu selector. Defaults to .sub-menu
• Submenus receive a class of offscreen right or left for desktop menus when applicable
• CSS affects all menus that have a class of .js-menu
• Added hover events for top level items on desktop only
• Small fallbacks for when there is no-js

Apply animation button executes only once

When you select your first set of library options, you can only apply the animation once on initial button press.

"Apply this Animation" only executes again when new library options are selected.

New Component: React Accordion

Ensure all other accordion component issues have been addressed.

===

Coordinate with the accordion block in the block library to ensure both work in tandem: https://github.com/10up/block-library/tree/trunk/includes/blocks/block-editor/blocks

Add issue and PR templates

Add parallax library recommendations

Parallax features are notoriously inaccessible, let's do a little research and find something that passes accessibility standards.

Or vet some parallax libraries for recommendation on the site.

Release 2.0.2

Release 2.0.2

Fix typo in doc site sidebar navigation

• The word navigation was misspelled in the href and ID of the navigation item

Navigation Release [2.1.2]

• #89
  • Fix hover state opening subnavigation not working when the default nav is selected.

Navigation Release [2.1.1]

• #85
  • Ensure class site-menu-toggle is on site menu toggle element.
  • Remove role="navigation" from navigation elements.

Slim down readme in favor of baseline docs

Update Component: Navigation - enable mega nav

Either enable a meganav option for the navigation component

Describe the solution you'd like
@saltcod Please add acceptance / expectations

• links to examples
• options to consider
• depth of content
• how complex does it need to be?

Describe alternatives you've considered
If needed, a new meganav component is a possible solution - but not ideal.

Please see #45 and other navigation component issues before starting.

aria-expanded not updated when ESC is pressed

Describe the bug
When the ESC key is used to close the submenus, the aria-expanded attribute stays set to "true" instead of changing to "false". This currently works as expected when using the Enter key to close the submenus.

To Reproduce
Steps to reproduce the behavior:

1. Use the keyboard to navigate through the navigation component
2. Click on parent menu item to display the submenu
3. Press the "ESC" key to close the submenu
4. The aria-expanded attribute of the parent menu item stays set to "true" instead of changing to "false"

Expected behavior
Ensure that the aria-expanded attribute value is changed to "false" when the ESC key closes the submenus.

Add animation examples

actual UI examples

Port `component-audio` repo to monorepo

Is your feature request related to a problem? Please describe.
The Audio Player component is marked as PLANNED on https://baseline.10up.com/components, but we've got https://github.com/10up/component-audio which might as well get ported into this monorepo and if needed marked as BETA if its still evolving.

Describe the solution you'd like

• port https://github.com/10up/component-audio into https://github.com/10up/component-library
• update docs on https://baseline.10up.com/components
• add component-audio label for new issues (or alternate name if component is renamed)
• archive https://github.com/10up/component-audio

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

New Component: React Tabs

Ensure all other tab component issues have been addressed.

===

Coordinate with the tabs block in the block library to ensure both work in tandem: https://github.com/10up/block-library/tree/trunk/includes/blocks/block-editor/blocks

New Feature: Accordion - expanded state control

Is your feature request related to a problem? Please describe.
We've recently had a request from a client (Campbell's) to extend the accordion component with functionality to control its initial expanded state upon page load. By default, this feature is not built-in and would probably have to be added manually (which I'm almost sure has been done several times in the past). This seemed to be a handy feature that could benefit other projects/clients as well.

Describe the solution you'd like
As a solution, we've implemented ToggleControls on two levels:

• A global toggle that controls the expanded state for all accordion items. When the global switch is enabled, all inner child items will inherit the setting
  

• Item-specific toggle that only controls its own expanded state. This option is only available if the global option has been disabled
  

As a result, not only would administrators have more control to customize the initial state of the accordion, but it would also improve the user experience in the editor at the same time.

Release 2.0.1

Release 2.0.1

Enhance animation guidance / capabilities

Issue / Enhancement
Although you can use the callbacks to provide some animation to the accordions, there can be challenges with focus states, adding listeners to transitionend, and accounting for the according content height for consistent smooth transitions.

Solution

• documentation and guidance for adding animation to accordions
• add any necessary callbacks, listeners, or enhancements to allow adding animations to be efficient and easy

Convert Select Component to CSS

Is your feature request related to a problem? Please describe.
We just need to update the code for the section component

Describe the solution you'd like
The displayed code should be CSS instead of SCSS

URL:
https://10up.github.io/wp-component-library/component/custom-select/

Hamburger animations

Add a package of hamburger menu animations. Catch with design/ux about this first and survey at least 10 projects and galleries for inclusion. Animations should have a fast and slow option - discuss speed with design/UX.

Use aria-controls for style rules to force a11y usage.

<button type="button" aria-controls="id-value">default</button> 
<button type="button" aria-controls="id-value" aria-expanded="true">open state</button>

Update component: Navigation - design

This is a ticket to update the default design of the navigation component

Feature: Browser extension for UI testing

Should load the library and allow users to click an element and add any available classes to see the effect.

Update Tab Demo HTML to match new component

Describe the bug
Update Tab Demo HTML to match new component

To Reproduce
Steps to reproduce the behavior:

1. Go to: https://10up.github.io/wp-component-library/component/tabs/index.html
2. Check out the tab demo

Expected behavior
The Tab demo should work

New Component: Posts Filter

We are continually reinventing the wheel creating posts filters on projects.

Create an agnostic post filter component to work with WordPress posts, taxonomies, and CPTs that we can leverage across our projects.

Consider options for construction of component (web component, react, etc).

Before building, define engineering path forward.

New Component: Load More Posts

Guidance, best practices, and snippets for a load more posts component

Is this a possible new category of components in baseline (collection of npm packages to create load more posts functionality).

See legacy issue for previous communication/

The components are prone to leak memory

Describe the bug

The component adds event listeners during setup process, but it doesn't remove it when the component is not needed anymore on the page. It means that if we add and remove accordions programmatically on the same page, it won't be garbage collected and remain in the memory.

Expected behavior

There should be a method to destroy accordion when it's not needed anymore.

Add setting to have Accordion open initially

Is your feature request related to a problem? Please describe.
In several projects I have come across designs that demand individual Accordions to be open by default. (Normally the first of a group.)

Describe the solution you'd like
There are two ways I could thing of:
1: Make the component not handle all the accordions on a page at once, but initiate it for individual items.
Authors would then have to loop over the accordion element themselves but it would allow you to actually return the individual instance of the accordion that exposes the methods to be used in js.

const elements = document.querySelectorAll( '.accordion' );

elements.map( element =>  new Accordion( element, {...} ) );

2: Return the individual instances of the accordion in addition to the $accordions elements.
That way you could call the open method on the first element returned.

Describe alternatives you've considered
A way this can be one currently is by calling the .call() method on the button.

Original Ticket: 10up/component-accordion#38

Component switching mechanism to support a small screen accordion

Update component: accordion (design)

This is a ticket to update the default design of the accordion component

See other existing accordion component issues

===

Coordinate with the accordion block in the block library to ensure both work in tandem: https://github.com/10up/block-library/tree/trunk/includes/blocks/block-editor/blocks

Convert Social Links Component to CSS

https://10up.github.io/wp-component-library/component/social-links/index.html

Focus move on accordion-label on close also

Is your feature request related to a problem? Please describe.
When accordion is toggled, focus moves to accordion-label. But results focus being lost when user closes the accordion since focus moves to accordion-label which is already hidden.

Describe the solution you'd like
Either check is accordion closing and not move focus. Or not move focus at all which is OK by ARIA authoring practices. They do not move focus.

Also related to issue #16.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Original Ticket: 10up/component-accordion#43

Investigate adding a datepicker to the component library

Verify datepicker solution: https://baseline.10up.com/component/datepicker/

Investigate duet as an alternative: https://github.com/duetds/date-picker

Initial feedback (2020):

• Opens on Enter keypress
• Allows selecting of months with keys
• Prevents window scroll when using arrow keys
• Closes on select
• Noting that in the repo there are some issues opened what comes to accessibility
• For use on a client site, see here: https://www.salesforce.com/news/media-library/

Determine next steps

[Security] Workflow e2e.yml is using vulnerable action actions/checkout

The workflow e2e.yml is referencing action actions/checkout using references v1. However this reference is missing the commit a6747255bd19d7a757dbdda8c654a9f84db19839 which may contain fix to the some vulnerability.
The vulnerability fix that is missing by actions version could be related to:
(1) CVE fix
(2) upgrade of vulnerable dependency
(3) fix to secret leak and others.
Please consider to update the reference to the action.

New Component: Data Visualization Library

From @lea10up

It would be nice to have more robust, dynamic data visualization options to replace static image graphs like this:

Having standardized components for this type of content allows for further ways animation can be incorporated on a site and increase interactivity. Depending on the library, a standard data visualization starting point can also potentially improve accessibility (compared to static images).

---

Let's investigate and vet some third party data viz libraries for this one. Whomever picks this up, please work with @lea10up to identify UI features we're looking for in the library, then vet for a11y compliance and/or how our implementations need to be structured to ensure compliance.

Add 50% movement options for sliding in/out

Currently we slide from 0-100 or 100-0. Let's add 0-50 and 50-0 as well. The weight add should be very minor.

The demo and tests should also be updated

Update the modal / dialog component to refer the current release of A11yDialog

Is your feature request related to a problem? Please describe.
A11yDialog made breaking changes in its 7.0 release. Our documentation refers to a legacy version of A11yDialog and we should update our documentation to refer to the latest release.

Describe the solution you'd like
We want to rewrite our docs using the new version (Version 7) and have a notice in there that Version 6 has been deprecated with links (see blow).
In other words, replace all the current documentation to follow version 7's usage / etc and a warning that version 6 will require a migration to work with the recent update.

• Links from Kitty on twitter
• Current docs
• Baseline docs

Describe alternatives you've considered
N/A

Toggle status class on .menu-item-has-children > a

Is your feature request related to a problem? Please describe.
Would be useful to have is-opened (or similar) class toggled when opening/closing sub nav.

<a href="#!ourwork" aria-controls="tenUp-submenu-0" aria-haspopup="true">Our Work</a>

This would enable styling for example for SVG down arrow. Or any other style changes based on state of that link.

Allow different class names

Currently, we need to use accordion-header, accordion-content, accordion-label classes.

It would be nice to allow the user the use other class names and pass those class names to the plugin via options maybe?

Caveat is they would need to use their own CSS.

Option for Top Menu Item with children to be a link as well

This component is great when we have a placeholder title for the top menu item. However, it is frustrating when we need to be able to link to the top menu item as well. I.e. "About" list item with children items of "Our Work", "Press", "FAQ" where "About" is a page. If we want to visit the About page we'd have to make it as a duplicate child item.

Since we already have an svg icon, it would be great for a setting on this component to allow you to have the top menu items be linkable and only the svg icon trigger the menu events or to keep the menu as its currently built where clicking the top menu item triggers the menu events.

Losing :focus when using links inside tabs

Describe the bug
If tabpanel(s) include links, :focus disappears or goes to inactive tab and is not trapped inside of the active tab when browsing with tab key.

To Reproduce
Steps to reproduce the behavior:

1. Add links to tabs of the demo index.html

<div class="tab-content" id="js-tab1" role="tabpanel">
  <h2>Tab 1 Content</h2>
  <p><a href="#1">Link-1</a> ipsum dolor sit amet, consectetur adipiscing elit.</p>
</div><!-- //.tab-content -->

<div class="tab-content" id="js-tab2" role="tabpanel">
  <h2>Tab 2 Content</h2>
  <p><a href="#2">Link-2</a> tincidunt tempor risus gravida tincidunt.</p>
</div><!-- //.tab-content -->

2. Open in browser
3. Browse with tab key
4. After focusing "Link-1" press tab again
5. Focus now goes to "Link-2" but it's not clear to user that tab has changed.

Expected behavior
User could tab-browse all links inside of a tab, and then focus moves to next .tab-item (where you change tab).

Desktop (please complete the following information):

• OS: [Mac OS Catalina]
• Browser [Atleast all webkit browsers]

Mobile (please complete the following information):

• Not an issue on mobile device, atleast when using touchscreen

Nested Tabs Block Won't Switch Tabs

If you have a tabs component inside another tabs component you aren't able to interact with the tabs of the inner component: https://www.screencast.com/t/jqzcKFaZ

Pass information to callback functions

Is your feature request related to a problem? Please describe.
Seen on projects, sometimes content need to be initialized/created on open, or clients want the window to scroll to the open accordion item.

Describe the solution you'd like
It would be nice to have some information about the opened/closed items in the callback functions arguments maybe?

Describe alternatives you've considered
n/a

Feature: JavaScript API

Modeled after bounce.js to product complex JS-based animations. Animations will be chainable and focused on transforms only at first. API should be similar to https://github.com/tictail/bounce.js/ but we'll need to sync on the naming.

importing animations should be available in bulk, but also one by one (e.g. if you only want rotate)

Convert Tooltip to CSS version

https://10up.github.io/wp-component-library/component/tooltips/index.html

Update release workflow documentation

Update release workflow documentation to include guidance

New Component: Slider

Vet slider options

Is tinyslider our go to/ guidance?

What about Splide?

Flickity has a paid / licensing setup - so look into this before using (and also a bit buggy at the moment) - so we are not recommending using this solution

Determine guidance, best practices, and recommendations.

Use other 3rd party component recommendations as a reference.

Add Mobile Responsiveness

Currently on small screens the tabs scroll horizontally, as an example

The design might look like a 'Select' menu, with the drop down being the tabs.

===

Coordinate with the tabs block in the block library to ensure both work in tandem: https://github.com/10up/block-library/tree/trunk/includes/blocks/block-editor/blocks

Port `component-reading-position` repo into this monorepo

Is your feature request related to a problem? Please describe.
Baseline references Reading Position (see https://baseline.10up.com/component/reading-position/), but links out to https://github.com/10up/component-reading-position instead of a sub-package in this repo.

Describe the solution you'd like

• port https://github.com/10up/component-reading-position into https://github.com/10up/component-library
• update https://baseline.10up.com/component/reading-position/ links to monorepo
• add component-reading-position label
• archive https://github.com/10up/component-reading-position

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

readme updates

Is your feature request related to a problem? Please describe.
Update repo to match 10up open source standards.

Describe the solution you'd like

• add support level section and badge

Describe alternatives you've considered
n/a