umaar
commented
6 years ago Still learning, so some ideas might not make sense!
Exploring ideas to improve the theming story
Introduction
This GitHub comment outlines my investigation into the mechanisms and potential improvements for theming.
The points below are numbered so you can quickly refer to it in your response.
1. Clarification on one problem we wish to solve
When theming some widgets, for example built-in Dojo 2 Button widget, you may wish to override the existing styling:
Note: A widget must specify class names as themable so they be overridden.
When you, an end-user, would like to consume a widget and override its themable classes, you might create a new CSS file styles/themes/dark/button.m.css:
.selector1 {
color: red;
}
.selector2 {
color: blue;
}The main problem is this: How does an end user know: a) which selectors they can style. b) What part of the widget is affected by such a selector.
2. Potential solution: Autosuggest
As a user, if I were writing a theme CSS file for a widget, it'd be great to get autosuggest values for the available selectors. Some editors do this based on the HTML which is detected.
How: I can only think of users having to install a custom code editor plugin which isn't ideal. So this is probably not feasible.
3. Potential solution: Scaffolding
Just like how there are tools and plugins to convert HTML to CSS, what if we could generate a styles/themes/dark/button.m.css file automatically, with the selectors already present, and rules ready to be filled in?
How:
- A new command part of the Dojo CLI which inspects + evaluates the widget source to determine their themable classes
- Extract information/hints from readme/code comments which a widget author must add to their widget source code, this can be picked up via the CLI and used to generate a CSS file
To think about:
- This could be a large engineering effort with lots of delicate pieces
- Would the scaffold command work on an existing CSS file? E.g. if the user had already started writing one?
- What happens when a widget is updated, will the scaffold tool handle the new classes correctly?
4. Potential solution: Terminal logging
What if the Dojo CLI logged a message to the terminal to alert the user when they have used a class which is not themeable.
To think about:
- We haven't solved the problem of telling the user which classes were available from the start
- Extra noise to already noisy CLI output
5. Potential solution: DevTools console logging
What if the browser console logged the available themable classes.
To think about:
- Could be easier to compute this client side, rather than having to do source code inspection like with solution 4
- Messages can be disabled in production
- Messages can be grouped using the Console API to decrease the noise
- When dealing with styling related concerns, the user is likely to have browser DevTools already open
- Not all users will be running the Dojo CLI/have DevTools open when developing their app, in an ideal world, the user has the information they need as they're writing the CSS file
- Inspecting a class in the DOM Tree doesn't tell you whether it is themable
6. Potential solution: Education
Educate and encourage widget authors to add all themable classes to their readme documentation.
To think about:
- This has a maintenance cost: widget authors must always remember to keep documentation up to date
- Smaller engineering effort than some other options
7. Potential solution: DevTools extension
Inspect and see original class names through a DevTools extension.
To think about:
- Is not ideal to ask the user to install additional tools
- Extra engineering effort to develop + maintain browser extensions
- What browsers to support?
- Whenever I think about needing an extension to do accomplish something relatively small in a similar context, I wonder if there is a deeper problem with the approach which was taken
8. Potential solution: Removing the unique classname transformation
In a traditional app, if I were using a third party component, I might inspect it with DevTools, see what classes are used, write out the class in my custom.css file and override things. Dojo 2 users can't do that because the classes have been "scoped" and can change. What if Dojo 2 was rearchitected so original class names were preserved? This would help with the problem being discussed in this comment, but also have improved developer ergonomics in view-source, inspect-element & testing workflows. To achieve the goal of scoping CSS, that could be explored separately (for example something like the scoped attribute - however this was removed from the spec).
To clarify: if we achieve this, the user would then have to 'inspect element' and use the class in their theme, however this doesn't necessarily identify which classes are available for theming and which are not.
To think about:
- Large engineering effort
- Can improve the experience of debugging Dojo 2 apps
A side issue
When exploring themes, I tried to understand how I could extend an existing theme from node_modules.
The problem is this: If you try to use composes with compiled/built CSS code:
composes: root from '../../../../node_modules/@dojo/widgets/themes/dojo/button.m.css';The classes in that file have been 'scoped' and cannot be imported as the user would expect.
9. Potential solution: Publish raw CSS
Publish the raw CSS files (e.g. to the NPM repository) so they can be 'composed' from directly,
To think about:
- For the the user, it's an additional/potentially unintutive step, e.g. it might be unclear what file they need to compose from
- External widget authors need to be aware of this step, but also must set up the infrastructure to do it
10. Potential solution: Extend the composes method
Noticed that the raw CSS module turns into a few files, one of which is: node_modules/@dojo/widgets/themes/dojo/button.m.css.js which has a piece of JSON inside it like this:
{"root":"_1lZxc2Ul","addon":"TAlDrfED","pressed":"_37ji2mWW","popup":"_29G5UqBS","disabled":"GlYj4g4z"," _key":"dojo-button"}So I wonder if the composes function (not sure who or what implements it) can somehow be enhanced so if it detects a .js extension:
.selector {
composes: root from '../../../../node_modules/@dojo/widgets/themes/dojo/button.m.js' /* <-- Notice the .js extension */
}It automatically reads the JSON from that file and figures out which style rule you meant.
11. Potential solution: Extend the composes method with source maps
When you write composes: root from '../../../../node_modules/@dojo/widgets/themes/dojo/button.m.css';
The composes function could check if there is a sourcemap, if there is, it extracts the relevant (e.g. root) selector from the original file since the source map should have this information.
Another side issue:
Would be nice to enhance the composes function so it provides logging if it can not find the class the user is trying to import.
Update - Generating theme files
It's probably worth improving the experience of creating theme files. For example:
import * as Header from './Header.m.css';
export default {
'Header': Header
}If you change 'Header' -> into 'header' there are no errors and it can take a while to realize what the problem is.
tomdye
agubler
Enhancement
We should create a tool that helps with theme generation. Specifically, the tool should help improve the following processes:
Package Version: rc