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.1 1 ) Goals / criteria for component review and selection
- 1.2 2 ) UI elements to be replaced or introduced
- 1.3 3 ) Review
- 1.3.1 3.1. Collapsible left-hand menu
- 1.3.2 3.2. Breadcrumb
- 1.3.3 3.3. Table
- 1.3.4 3.3.1 Data Grid Assessment
- 1.3.5 3.4. Typography
- 1.3.6 3.5 Dropdowns/Selects
- 1.3.7 3.6. Button
- 1.3.8 3.7. Icons
- 1.3.9 3.9. Card
- 1.3.10 4.0. Modal
- 1.3.11 4.1 Tabs
- 2 Final Summary
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 |
|---|---|---|---|
Collapsible left-hand menu | SidebarNav.tsx Sidebar.tsx Globals.scss _sidebar.scss | MUI Drawer | |
Breadcrumb | Breadcrumb.tsx Header.tsx _header.scss | MUI Breadcrumbs | |
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) | |
Typography (Headers, titles etc) | Throughout | MUI Typography | |
Dropdowns / Selects | HeaderProfileNav.tsx | Replacing dropdown with MUI App Bar | |
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) | |
Icons | Profile.tsx | React Icons - standard switch from FontAwesome icons currently present (and any others) | |
Search | Table.tsx | MUI X Data Grid Quick Filter (Will be implemented as part of the Data Grid) | |
Card | Profile.tsx | MUI Card + Paper (to hold cards) | |
Modal | Details.tsx AddAgenciesToGroup.tsx agencies/index.tsx groups/index.tsx NewGroup.tsx requests/index.tsx | MUI Modal, Dialog (for things like confirmation). | |
Pagination (this refers only to the UI pagination controls) | Table.tsx |
With customisation so user can go to Page ‘X’ by clicking on the number / typing it in |
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. | 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 | N/A | |||
Pros |
|
|
|
|
Cons |
|
|
|
|
Package size | 501.3kB (entire material package) 20.4kb - drawer package |
|
| |
Usage & Maintenance Stats (package score) |
| |||
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 | https://reactrouter.com/en/main/hooks/use-matches#breadcrumbs | |
Pros |
|
|
Cons |
|
|
Package size | 501.3kB (material package) 19.4kB - breadcrumb package |
|
Usage & Maintenance Stats (package score) | ||
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 | ||
Pros |
|
|
Cons | x |
|
Package size | 501.3kB (entire material package) 11.3kB - table package |
|
Usage & Maintenance Stats (package score) | ||
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 | ||
Pros |
| |
Cons | Nothing notable |
|
Package size | 501.3kB (entire material package) 11.8 kB - Typography |
|
Usage & Maintenance Stats (package score) | ? | |
Final Choice | x |
|
Justification | It will be easier than coding a new Typography component. |
|
3.5 Dropdowns/Selects
Choices | Custom | ||
Notes/Documentation | Documentation linked to title | Documentation linked to title |
|
Pros |
|
|
|
Cons |
|
|
|
Package size | 501.3kB (entire material package 23.kB - Menu |
|
|
Usage & Maintenance Stats (package score) | ? | ||
Final Choice | x |
|
|
Justification | Unless we need the specified features of react-select, there is no need to use it yet. |
|
|