Material Theme and Widget improvements

[tomdye]

Overview

This EPIC encapsulates all issues and work to write both a material theme for @dojo/widgets and to adapt and improve our widgets to work with a material implementation and to serve us better in future projects.

MDC docs: https://material.io/develop/web/components/

History

We wish to implement a material theme for @dojo/widgets. This will provide us with a themed widget library and iron out any pain points in our widgets for theming / project use.

Two POCs have been worked upon to decide the best way to proceed, the two approaches are

1. Use mdc adapters and foundations to create a new library.
2. Write a @dojo/theme to implement material and make appropriate changes to @dojo/widgets to support it.

The text-input changes using a material theme can be found here along with the theme itself which is part of the POC for adapters / foundations which can be found here.

We have chosen to proceed with option 2 as this gives us the greatest re-use of existing assets and will provide more themeable / usable widgets.

Working on a material widget issue

Each widget issues will consist of multiple parts and must be written in the Queens English:

1. Read the documentation for the appropriate mdc component. For example the readme for textfield can be found here.

2. Design and document the features of material for the given component that we will implement on the appropriate issue. (This may include properties such as dense / outlined etc)

3. Design and document any extra properties / improvements that should be implemented for the widget. ie. primary / icon etc properties for button etc. These may be part of material but may also be enhancements to our widget offerings such that theyre more useful in projects etc.

4. Adapt the dom structure to be compatible with the material css, details of what is required can be found in the readme for each mdc component. eg. textfield details can be found

5. Create a theme css file for the widget in @dojo/theme/material using composes where possible to pull in classes and styles from the mdc css. An example of this can be seen int he dojo material POC linked above.

6. Make any necessary changes to the dojo theme to support the new structure (if any).

Normalising event callbacks

Not every widget needs to have every callback, we should apply common sense to the ones we attach and normalise the callback names as much as possible.

New callbacks

• onValue(value: any): void This will be the equivalent of onInput and should be called on every change allowing the controlling app / widget to set the value on the widget.
• onKey(key: number, preventDefaultL () => void) This will replace keydown / keypress / keyup and should be used where appropriate.
• onValidate(valid: boolean, message: string): void This will be called from a self-validated widget when the valid state has changed and validate is not set to false.
• onOver(): void This will be triggered when a pointer moves over the widget
• onOut(): void This will be triggered when a pointer moves out of the widget.

Changed callbacks

• onFocus / onBlur / onClick Will no longer receive a value.

Removed callbacks

• onInput / onChange Will no longer be used.
• onTouch* / onMouse* Will no longer be used.

Widgets to be worked on

• [ ] text-input: issue
• [ ] label: issue
• [ ] button: issue
• [ ] icon: issue
• [ ] text-area: (requires text-input to be completed)
• [ ] select: issue
• [ ] combo-box: (requires select to be completed)
• [ ] radio:
• [ ] checkbox: issue
• [ ] switch: issue
• [ ] slider: issue
• [ ] date-input: issue

[aciccarello]

My initial work on creating a material theme in dojo/themes was blocked by dojo/cli-build-theme#11

[sebilasse]

@tomdye @nicknisi @dylans After lots of hard work /me created a working material theme (for my CMS based on ActivityPub). But the widgets are slightly different from the original dojo2 widgets to make the aspects below work. Please tell me if I should build and upload a showcase so that you can give feedback because I'd be willing to contribute if you like it. It is a Work in Progress [not too much documentation ;) and no tests yet] but around 30 widgets seem to work.

One goal is to move things that can be accomplished by CSS to, well CSS … All widgets should be able to be statically generated if you just want to use e.g. the Toggle in an HTML form.

The theme covers most of the material aspects. Exactly the first part of this issue

Working on a material widget issue

Change your variables in

• Colors.css based on the Material Schemes for your colors additionally specify classes .light and .dark add the .primary and .secondary sugar for all these schemes
• Depth.css based on the Material "depth". It specifies the "shadows" but also the animation durations and easings which are based on the depth.
• Typo.css covers the Material best practice and apart from material has a solid typographic baseline based on your font metrics
• Animations things like the material click / touch effects, ripples, progress animations etc.

As said I could upload a showcase.

[tomdye]

Thanks for bringing this to our attention @sebilasse , have you got any of your work on this raised to GH etc? We've been fairly successful using css-modules to compose the material classes directly from the mdc material CSS to create a dojo theme. We've implemented it for an internal project and plan to use the same pattern to create a material theme leveraging mdc for v6/7 of Dojo.

[sebilasse]

@tomdye

have you got any of your work on this raised to GH etc?

Yes, about 1 minute ago. Here https://github.com/sebilasse/dojo-material-sneakpreview

[sebilasse]

@tomdye What is not working in the preview anymore are the colored schemes (you can currently only click light/dark in the toolbar [and baseline and different sizes] ). This happened after an Update from dojo 3 to 5 because of changes in css modules (I think I used @apply before but it is easy to change).

If you wonder about some CSS rules keep in mind that they might exist because the widgets are statically usable even without JS …

What is not implemented yet: List Listbox = List + ui box and Select = TextInput readonly + Listbox and ComboBox = TextInput readonly + Listbox

[tomdye]

The initial work on material has been completed so we can close down this issue