DCB Admin App refresh

The existing Admin app needs evaluating with a view to replacing components to fix issues with non compliance against accessibility guidelines, and to enable better development in the long term.Ā 

Material UI comprises a more complete set of components which are known to be needed now or anticipated in the future.Ā 

This document supports the DCB Jira ticket:

1 ) Goals / criteria for component review and selection

Goal

Description

Priority

Notes

Skinnable UI

The visual presentation needs to be re-skinnable, to support different branding requirements for organisations

Very high

Theme/template styling will be applied once the components are switched over. DCB-312 provides the basis for this functionality.

Internationalisation

The app needs to be translatable into unlimited languages

High

To be continued in https://openlibraryfoundation.atlassian.net/browse/DCB-285Ā 

Accessibility

WAI AA must be supported as a minimum

Very high

Met in DCB-278 and DCB-396. WCAG 2.1.

Open Source

Needs to be free to use

Very high

Met: MUI is an open source library and ā€˜free foreverā€™ under the MIT licence.

Use

Needs a healthy user and developer community

High

Met: MUI is one of the most used UI libraries in the world with an active community and regular maintenance.

Maintenance

Needs to be regularly maintained

Very high

See above.

Responsiveness

Support for tablets and wider screens. Support for mobiles is desirable but not as important

High

Met, with mobile support to be potentially added in future.

2 ) UI elements to be replaced or introduced

Element

Whereā€™s it used currently?

What are we going to replace it with?

JIRA Ticket

Element

Whereā€™s it used currently?

What are we going to replace it with?

JIRA Ticket

Collapsible left-hand menu

SidebarNav.tsx

Sidebar.tsx

Globals.scss

_sidebar.scss

MUI DrawerĀ 

https://openlibraryfoundation.atlassian.net/browse/DCB-255

Breadcrumb

Breadcrumb.tsx

Header.tsx

_header.scss

MUI Breadcrumbs

https://openlibraryfoundation.atlassian.net/browse/DCB-256

Table

Bootstrap Table

Table.tsx

@tanstack/react-table

Table.tsx

useResource.ts

agencies/index.tsx

hostlms/index.tsx

locations/index.tsx

requests/index.tsx

Table component

Details.tsx

components/Table/index.ts

agencies/index.tsx

hostlms/index.tsx

locations/index.tsx

requests/index.tsx

Ā 

MUI X Data Grid (see 3.3.1)

https://openlibraryfoundation.atlassian.net/browse/DCB-231

Typography (Headers, titles etc)

Throughout

MUI TypographyĀ 

https://openlibraryfoundation.atlassian.net/browse/DCB-304

Dropdowns / Selects

HeaderProfileNav.tsx

Replacing dropdown with MUI App Bar

https://openlibraryfoundation.atlassian.net/browse/DCB-278

Button

Details.tsx

Header.tsx

Sidebar.tsx

SideBar.nav

Groups

Hostlms

Locations

Requests

login

MUI Button - one primary button per page (as rule - occasional exceptions may be necessary)

https://openlibraryfoundation.atlassian.net/browse/DCB-304

Icons

Profile.tsx

React Icons - standard switch from FontAwesome icons currently present (and any others)

https://openlibraryfoundation.atlassian.net/browse/DCB-303

Search

Table.tsx

MUI X Data Grid Quick Filter

(Will be implemented as part of the Data Grid)

https://openlibraryfoundation.atlassian.net/browse/DCB-231

Card

Profile.tsx

MUI Card + Paper (to hold cards)

https://openlibraryfoundation.atlassian.net/browse/DCB-304

Modal

Details.tsx

AddAgenciesToGroup.tsx

agencies/index.tsx

groups/index.tsx

NewGroup.tsx

requests/index.tsx

MUI Modal, Dialog (for things like confirmation).

https://openlibraryfoundation.atlassian.net/browse/DCB-304

Pagination (this refers only to the UI pagination controls)

Table.tsx

MUI x DatagridĀ 

Ā 

With customisation so user can go to Page ā€˜Xā€™ by clicking on the number / typing it in

https://openlibraryfoundation.atlassian.net/browse/DCB-231

Possible Future Components (to be implemented in those tickets)

Tabs

Not yet used but will be needed for different data views.

MUI Tabs

Future ticket when needed

Accordion

Not yet used but will be needed for record views.

MUI Accordion

Future ticket when needed

3 ) Review

Components have been selected from Material design libraries and evaluated against the goals (see section 1) for their suitability for use in the Admin app.

3.1. Collapsible left-hand menu

Choices

MUI - React DrawerĀ 

react-pro-sidebar

react-burger-menu

Custom

Notes/Documentation

MUI documentation

Npm react pro sidebar packages page

Npm burger menu package page

N/A

Pros

  • Included in the MUI package

  • Easy to use

  • Highly customisable

  • Visually appealingĀ 

  • Includes transition animationsĀ 

  • Has been around for 8+ yearsĀ 

  • No package installation needed

Cons

  • Big package size - but this includes many other components that will be used.

Ā 

  • Extra package install

  • Relatively large package

  • Inactive maintenanceĀ 

  • Will take time to implement (another task)

Package size

501.3kB (entire material package)

20.4kb - drawer package

64.2kB

108.3kB

Ā 

Ā 

Usage & Maintenance Stats

(package score)

95/100

72/100

69/100

Ā 

Final ChoiceĀ 

x

Ā 

Ā 

Ā 

Justification

Included in the MUI package that is planned to be used, making it convenient.Ā 

Ā 

Ā 

Ā 

3.2. Breadcrumb

Choices

MUI - Breadcrumbs

react-router-dom

Notes/Documentation

React Breadcrumbs component - MaterialĀ UI

https://reactrouter.com/en/main/hooks/use-matches#breadcrumbs

Pros

  • Comes with the MUI package

  • Part of the react-router-dom, so can be used along with other routing features

  • Minimal code

  • Popular and well maintained

Cons

Ā 

  • The code uses nextjs routing, therefore would have to be reworked to include react-router-dom

Package size

501.3kB (material package)

19.4kB - breadcrumb package

70kB

Ā 

Usage & Maintenance Stats

(package score)

95/100

100/100

Final ChoiceĀ 

x

Ā 

Justification

Included in the MUI package and there is no need to rework routing from next js to use it.

Ā 

3.3. Table

Choices

MUI - React Table

Material React Table

Notes/Documentation

MUI documentation

Material React Table documentationĀ 

Pros

  • The project already uses TanStack.

  • Imports TanStack as well as only the necessary components from MUI

  • No need to switch UI components If the project decides to switch from MUI to another UIĀ 

Cons

x

Ā 

Package size

501.3kB (entire material package)

11.3kB - table package

176.9kB

Ā 

Usage & Maintenance Stats

(package score)

95/100

83/100

Final ChoiceĀ 

x

Ā 

Justification

The project already uses TanStack so there is no current need to import a library that imports TanStack again

Ā 

3.3.1 Data Grid Assessment

When considering a replacement for the Table component, a new alternative became apparent in the form of MUI X Data Grids. These grids are faster, more efficient at displaying large data sets, and are also more fully-featured than either of the Table components, coming equipped with native pagination, row selection, sortable columns, filtering, and searching, amongst other useful functionality. My initial assumption was that we would have to switch to Tables first due to the format of our data - however, initial investigative work revealed that this would not be necessary, greatly reducing the complexity and time needed to implement this change. As such, MUI X Data Grids became the clear choice to replace Tables in our admin UI application.

Additional note: MUI X Data Grids replace both our Table UI implementation (previously react-bootstrap) and the headless Table logic implementation (Tanstackā€™s react-table). This makes them significantly more efficient than the other options, as they are effectively ā€˜two for the price of oneā€™ in our situation.

Key affordances

  • Sorting columnsĀ 

  • SearchingĀ 

  • Filtering

  • Clicking on rows to reveal details (as opposed to one column being a ā€˜linkā€™)

  • Checkbox select

  • Menu for future bulk actions

3.4. Typography

Choices

MUI - Typography

Custom Typography componentĀ 

Notes/Documentation

MUI Documentation

guide

Pros

  • Appears to be the most recommended component, as there are a few guides on how to use it here and hereĀ 

  • Full control over code (again)

Cons

Nothing notable

  • Again, will take time

Package size

501.3kB (entire material package)

11.8 kB - Typography

Ā 

Usage & Maintenance Stats

(package score)

95/100

?

Final ChoiceĀ 

x

Ā 

Justification

It will be easier than coding a new Typography component.

Ā 

3.5 Dropdowns/Selects

Choices

MUI - Menu Component

React Select

Custom

Notes/Documentation

Documentation linked to title

Documentation linked to title

Ā 

Pros

  • No extra import required

Ā 

  • More features than MUI for selection features (animation, styles)

  • 5k avg weekly downloads, popular for a smaller package

  • Complete control of code

Cons

  • Not as customisable as react-select

  • Extra import cost

  • Less featuresĀ 

  • Needs maintaining

Package size

501.3kB (entire material package

23.kB - Menu

90.9kB

Ā 

Ā 

Usage & Maintenance Stats

(package score)

95/100

78/100

?

Final ChoiceĀ 

x

Ā 

Ā 

Justification

Unless we need the specified features of react-select, there is no need to use it yet.

Ā 

Ā 

3.6. Button

Choices

MUI - Button Component

Custom

Notes/Documentation

Documentation from MUI

Ā 

Pros

  • Inclusive in MUI (the package we plan to use)

  • Full control

  • Not reliant on a package

Cons

?

  • Will take time to implement own button

  • Is the effort necessary?

Package size

501.3kB (entire material package)

17.2kB - Button

Ā 

Usage & Maintenance Stats

(package score)

95/100

?

Final ChoiceĀ 

x

Ā 

Justification

Searching around, there seem to be no good single package replacements for the MUI button. It is possible to use a button from another package, however the MUI one is already included in the package the project plans to use

Ā 

3.7. Icons

Choices

MUI Icons

React Icons

Font AwesomeĀ 

Notes/Documentation

MUI Icons documentation

React Icons page

Font Awesome Page

Pros

  • Easy to navigate

  • Icons fit a consistent theme

  • When using code examples from MUI, the icons donā€™t need to be changed

  • You only need to import icons you will use

  • Fairly lightweight

  • Includes icons from many different place

Cons

  • Additional import on top of MUI package

  • May not all adhere to a consistent design theme as icons are pulled from different websites

  • Some paid features

  • Pay wall for support featuresĀ 

Package size

4.4MB

Ā 

6.6kB

Ā 

56.6kB

Ā 

Usage & Maintenance Stats

(package score)

95/100

90/100

93/100

Final ChoiceĀ 

Ā 

x

Ā 

Justification

Ā 

Small package size and no pay wall for icons

Ā 

3.9. Card

Choices

MUI Card

react-ui-cards

Notes/Documentation

MUI Documentation

Npm package page

Pros

  • More customisable

  • Neat, pre-made cards without having to write much extra code

Cons

  • Potentially have to write more code to create a nice looking card

  • Not very popular and a small community (low package rating)

  • Unsure of how customisable it is

Package size

501.3kB

11.8kB - Card

446kB

Usage & Maintenance Stats

(package score)

95/100

56/100

Final ChoiceĀ 

x

Ā 

Justification

The package size for react-ui-cards is quite large

Ā 

4.0. Modal

Choices

MUI - Modal Component

react-modal

Notes/Documentation

Documentation

Npm package page

Pros

  • Already themed (visually pleasing)

  • Seems easy to implement

  • Highly customisable

Cons

  • Nothing notable

  • CSS will need customising as the default modal is not visually pleasing

  • Inactive maintenanceĀ 

Package size

501.3kB

17.9kB - Modal

186kB

Usage & Maintenance Stats

(package score)

95/100

80/100

Final ChoiceĀ 

x

Ā 

Justification

No notable issues

Ā 

4.1 Tabs

Choices

MUI Tabs

React-Tabs

Notes/Documentation

DocumentationĀ 

Website

Pros

  • No extra import

Ā 

  • More options for customising (tabs inside tabs, dynamic tabs)

  • Very small package size

Cons

  • Simple compared to react-tabs

Ā 

Package size

501.3kB

16.5kB - Tabs

6.5kB

Ā 

Usage & Maintenance Stats

(package score)

95/100

86/100

Final ChoiceĀ 

x

Ā 

Justification

This is just a suggestion as tabs are already included in the MUI package, but if more features are needed I would recommend switching over to react-tabs.

Ā 

Final Summary

Ā 

The Material UI switchover was completed in DCB-306, with the work captured in DCB-278 and the results can be viewed at https://admin.dev.resharedcb.org/ . The key improvements this work has delivered have been captured below.

  • UI components trusted by the very top companies: companies such as Spotify, Netflix and Amazon either use or build on top of MUI, and theyā€™re not alone. Material UI has the largest UI community in the React ecosystem and is one of its leading libraries.

  • First-class user experience: MUI components are tried, tested and heavily customisable. Weā€™re already customising components such as DataGrids in this release, and as we need more and more functionality our UI will evolve further to meet the needs of our users.

  • First-class design: MUI is simply more visually appealing than its predecessor, giving our admin UI a bit of ā€˜sparkleā€™ and ā€˜wowā€™ factor that makes it easier to sell to customers and more enjoyable to use.

  • World-class documentation: available at MUI, this documentation provides a massive range of examples and use cases for each component, helping not just with implementation but also with teaching and onboarding. Documentation also helps us fix issues quicker.

  • Faster navigation: switching to MUI has delivered speed and reliability improvements over react-bootstrap, its predecessor. It also means we can take advantage of Next.js features like server-side rendering, and eventually server-side pagination, so that we can stay fast even when dealing with huge data sets.

  • Building for the future: Switching to components like MUI Data Grids now means that our UI will stay fast even when dealing with massive data, as these components are designed to work with potentially millions of items.

  • Smaller bundle size, faster builds: by performing this work, weā€™ve been able to nearly halve build time by eliminating unnecessary components, npm packages and CSS, streamlining the application and its dependencies.

  • Easier customisation: our user interface can now be customised either at component-level with just a few lines, or globally with themes, eliminating the need for multiple hard to track changes across lots of CSS files. MUI gives us the power to create beautiful, customisable UIs that can be easily changed for each clientā€™s specific needs.

  • More features: just by switching to Material, we gained: improved pagination, the ability to search data grids, sort and filter columns, and dark mode, to mention a few.

  • More accessible: now fully compliant with WCAG 2.1, the admin UI is hugely accessible after the Material UI upgrade, with more accessibility improvements coming in future releases and the AXE Dev Tools being used to keep it accessible going forward.

  • Supports internationalisation: although weā€™ve not implemented this yet, just switching to Material UI makes supporting different locales a lot easier, with just a few lines of code required.

  • Easier to test: MUI components have well-known and well-documented established behaviours, making them easier to test when we implement automated testing in the UI.

  • Comes with its own design kits: Material UI in your favorite design tool - this improves cross-team collaboration between developers and designers and establishes clear design guidelines.

  • Helps us ship faster: with a huge library of components that can be built upon and combined to fit almost any UI need, thereā€™s no longer a need to ā€˜reinvent the wheelā€™ and spend lots of time building components that already exist, freeing up our developers to tackle the bigger problems.

Operated as a Community Resource by the Open Library Foundation