Refactor UI with a modern design system

[zhuiks]

UI can be refactored!
Instead of jQuery-UI it might be one of the following well established frameworks:

• Bootstrap 5
• Material

This will allow to have more responsive layout suitable for mobile devices

I know it's a lot of work but I think it should happen sometime in the future.

[tobias-klein]

These are the things that would have to be re-worked:

• Tabs
• Accordion widget
• Dialogs
• Module Install Assistant
• Verse selection mechanism
• Buttons

Most effort is probably the Tabs and the Module Install Assistant.

Technically this issue could also be handled incrementally, which would require that both libraries (JQuery UI plus the new one) are loaded in parallel until all rework is done.

Before we attempt this work I would like to see a clear list of benefits for the user and/or what this enables in the future.

I would estimate that this is probably at least a full week of work (full-time) or potentially even more.

How would you estimate the effort?

[zhuiks]

Before we attempt this work I would like to see a clear list of benefits for the user and/or what this enables in the future.

• Benefits for the user:

  • Mobile ready!
  • Modern attractive design
  • Familiar interface / design solutions
  • Possibility for right-to-left (RTL) languages

• Benefits for devs and the project

  • simplified css. Most styles would come from the framework/theme. So when we are adding new component we don't need to copy/create styles for it.
  • simplified and semantic html with established html5 and css3 technologies (i.e. flexbox, grid)
  • much more of the common ui task are already implemented within the framework (although it's true for the current jQuery-ui).
  • frontend code can be refactored to be even more component based, i.e. have logic (js) markup (hrml) and few specific styles (css) are in the same file/folder. If we decide sometime in the future to switch to something like react/vue - having such structure would be very beneficial.
  • more design components to work with for future enhancements
  • more familiar code for new contributors

Tabs

Tabs

Accordion widget

Expansion Panels

Dialogs

Dialogs

Module Install Assistant

Steppers

Verse selection mechanism

That one has to be customized. But there is a familiar pattern

Buttons

Buttons

I can try to draw a prototype in Figma. I think it would be beneficial for the future to experiment with UI.
I think we should keep the current color palette

Technically this issue could also be handled incrementally, which would require that both libraries (JQuery UI plus the new one) are loaded in parallel until all rework is done.

Yes definitely it should be done incrementally. Maybe it can be even a separate subproject. Maybe for a candidate for 1.0?

How would you estimate the effort?

It's all depends on how deeply we want to refactor and how familiar dev is with the project code. For me it would be >70 hours (2 full weeks). I assume a lot of small nuances might pop up.

[tobias-klein]

Thanks for the extensive analysis!

From my perspective, the biggest benefits (based on your list) are:

• Mobile ready. This would open the door for having a responsive design that scales from smartphone to tablet to desktop. I would not want to tune the current html/css design towards a smartphone. It works decently on tablet/desktop, but going smaller would not be sustainable with the current framework.
• Simplified and component-based CSS.
• More design components to work with for future enhancements.

In terms of an implementation strategy I could imagine the following:

Start with a new layout / CSS infrastructure from scratch, while trying to re-use existing controllers/components and make them work both with the old and the new layout for a transition period.

0. Decide on the new/modified technology stack.
1. Setup a rough framework with HTML/CSS and basic boot-up code from scratch. Optimize for mobile-first plus add CSS media query adjustments for tablet + desktop sizes. Test in a regular web-browser (with index.html + css + initial JS code).
2. Integrate bible browsing functionality + tag/note rendering based on existing backend + controllers.
3. Integrate menu bar and option handling.
4. Integrate module assistant.
5. Implement tab system based on existing controllers/components.
6. Integrate tag assignment. & tag browsing from existing components.
7. Integrate note editing from existing components.
8. Integrate in-tab search from existing components.
9. Integrate dictionary functionality from existing components.

In terms of technology I think it's a good idea to introduce new responsive design based on modern CSS framework(s). On the other hand I would be a bit relucant regarding JS-frameworks like React, Vue, etc. and rather stick to Vanilla JS (primarily for performance reasons) with a similar approach to components as already used today.

If this can be finished rather quickly (I doubt that) this could happen on a separate development branch.
If it's a longer-term activity then this could happen in a separate repository that includes the current repo as a submodule and re-uses code that way.

Any further thoughts on implementation strategy?

[zhuiks]

I would agree with separate repository (I can use my fork of Ezra Project) and Vanilla JS (future proof)

I see three main goals for this subproject:

1. Redesign UI with mobile first in mind
2. Select and embrace design system with its component library
3. Refactor code along the way (unite html, css, js under each component, possibly implement state management solution for frontend)

In general I will also agree with your roadmap. But I would revised it after first new component implementation and add design prototype step:

0. Decide on the technology
1. Setup the technology
2. Refactor a small component (to understand the concept and try out the technology). Maybe Fullscreen button
3. Draw design prototype and propose it for open discussion.
4. Re-evaluate roadmap

• Refactor Bible browsing
• Tags, notes
• Tabs, menu, etc...
• Module assistant
• ...

0. Requirements for modified technology stack:

• Good established Design system
  As developers we want a "rich" component library so we can just add a few lines of code to use already developed components (tabs, accordion, dialog modals, popups, charts). But design system is much bigger than just a number of components. It has philosophy behind it and a guidance for possible new components.
• Custom elements / web components
  It's already a standard so it will stay till all the browsers will die. It's a nice, framework agnostic way to hide implementation details. It's a learning curve, but it seems like it's future proof.
• Popular
  I think we need to choose something well known by people vs personal preference. That way if somebody new comes into the project he/she might be already familiar with it.

A good list to choose from can be found here

From my research I'd point out Carbon (IBM) and Material (Google). They are very big.
Carbon seems to be more close and enterprise oriented, although it has nice clear documentation and separate section on data visualization. I can't find any examples other than ibm.com

Material is the most popular, familiar for end-users who have android devices, and very thought-trough system.

My personal preference is Material. What do you think? @tobias-klein @alerque

[alerque]

I'm going to bow out of this one, I'm kind of following discussions at a distance but I'm not very closely involved in web front end things these days and don't have a good feel for what the pros and cons of various frameworks are.

From a logistics standpoint stay away from Git submodules as a way of reaching into a code base to reuse bits. I use them every day and they serve a purpose, but this would not be a good use case for them. I would either work in a development branch here, or if you want to split out issues and discussion just start with a fork of this repository and work on top of that with a separate issue tracker. Personally I think just splitting it out here with appropriate issue tags or a project board and it's own branch will be better. If this refactoring does go live it should be at least on par with the current one and therefore replace it across the board so I don't see the point of working on it as a separate project.

[tobias-klein]

Since this issue is so large, I'm also turning this into a discussion for now.
Whenever we come up with "digestible" implementation proposals we can raise new issues for those. We need to take it step by step / incrementally and each increment could be a new issue.

[tobias-klein]

I did a little proof of concept with Bootstrap 5, because I was not satisfied with the jquery ui dialog performance on Android (specifically when there was a large amount of dom nodes in the dialog content - like with the change tags list).

I used the bootstrap modal style as an alternative to jquery ui dialog. This is the result on Android (only applied for change tags dialog).

You can check this out in the wheelnav-bootstrap branch (you need to issue an npm install after switching)

It was rather straightforward to integrate bootstrap on top of the existing codebase. I had to make a few style adjustments. I also noticed that the existing dialogs that have cancel/save buttons would certainly have to be ported. I adjusted the new tag dialog as one example.

What we could do is slowly migrate from jquery ui to bootstrap. We could do that incrementally. The starting point would be the change tags dialog which is introduced by the wheelnav branch.

I think the earliest target release would be 1.5 (Feb 2022) from my perspective. I think it's too late for the current release cycle.

@zhuiks What do you think?

[zhuiks]

@tobias-klein this's great! I can see how easy it can be with switching to Bootstrap. The good thing is that Bootstrap 5 doesn't require jQuery.
My concern is how it can be compatible with web components. I think modal is the most challenging one in this. But I think it's still worth to move to Bootstrap.

In addition to modal progress bar is the prime candidate to switch to Bootstrap.

[tobias-klein]

Thanks for the feedback! Feel free to also implement a small proof of concept before taking a decision on bootstrap.
What exactly makes the model component challenging in a web component context?

These are the things that speak for bootstrap:

• Large set of apps / websites using it today
• Modern , yet well established / less likely to drop quickly in popularity than some of the newer frameworks.
• Works fairly well alongside existing jQuery UI components.

This could be the porting sequence:

1. Dialogs
2. Menus and buttons
3. Tabs
4. Module assistant
   ...

[ghost]

For a long term rework, you may wish to try out the Quasar framework. Deploys for desktop (Electron) web and mobile out of the box. It's made for this type of app. It uses the Vue framework (transitional jQuery UI stuff might be a problem.. if I recall correctly, Vue doesn't play well with jQ)

[tobias-klein]

Looks like an interesting framework, indeed! One design constraint that is needed for Ezra is the ability to use native C++ modules (to integrate SWORD and a SQlite database). That currently works out well when using Electron and Cordova with nodejs-mobile. Maybe there would be alternatives for that as well (using web assembly potentially ...).