dojo/cli-create-theme

This package provides tooling support for theme generation in Dojo.

@dojo/cli-create-theme

This package provides tooling support for theme generation in Dojo 2.

Imagine a scenario in which you are using third-party widgets in your Dojo 2 application (or the widgets provided by @dojo/widgets) and you want to theme them to match your existing application styles. This is where the dojo create theme command helps you.

This package will quickly generate theme scaffolding for third party widgets.

Features

Adds a dojo create theme command which displays an interactive instruction to ask two questions:

• What Package to do you want to theme?
• Which of the theme files would you like to scaffold?

Upon successful execution of this command, dojo create theme creates a number of files for you in your app:

• src/themes/theme.ts
• src/themes/widget/path/widget.m.css

The latter CSS module comes ready with themable CSS selectors which you can fill in the styles for.

How do I use this package?

Install dojo/cli-create-theme in a Dojo 2 app:

npm install --save-dev @dojo/cli-create-theme

Run the command: dojo create theme.

For example, if you have widgets which live in the folder: node_modules/@dojo/widgets, you can enter: @dojo/widgets as the answer to What Package to do you want to theme?.

Compatible packages

Any package that has a theme directory containing .m.css and coresponding, compiled definition files (.m.css.js) is compatible.

node_modules
└── package
    └── theme
        │   theme-file.m.css
        │   theme-file.m.css.js

How do I contribute?

We appreciate your interest! Please see the Dojo 2 Meta Repository for the Contributing Guidelines.

Code Style

This repository uses prettier for code styling rules and formatting. A pre-commit hook is installed automatically and configured to run prettier against all staged files as per the configuration in the projects package.json.

An additional npm script to run prettier (with write set to true) against all src and test project files is available by running:

npm run prettier

Testing

Test cases MUST be written using Intern using the Object test interface and Assert assertion interface.

90% branch coverage MUST be provided for all code submitted to this repository, as reported by istanbul’s combined coverage results for all supported platforms.

To test locally in node run:

grunt test

To test against browsers with a local selenium server run:

grunt test:local

To test against BrowserStack or Sauce Labs run:

grunt test:browserstack

or

grunt test:saucelabs

Licensing information

© 2018 JS Foundation & contributors. New BSD and Apache 2.0 licenses.

cli-create-theme's Issues

Improve tests

It would be good to split the two large tests for this repo into multiple smaller tests to assert against units of code rather than entire journeys. This will make the tests less brittle.
Also when using sinon, calling stub.firstCall.matches is preferable to stub.getCall().args[0][0] and similar.

Theme command should ask user for theme name

Enhancement

create theme command should request a theme name to allow for more than one theme to be created.

Change import hint to relative rather than absolute

Enhancement

Seeing as the dojo create theme command is ran from the project root I believe that the hint message at the end should be relative.

ie. please import 'themes/myTheme/theme.ts' into your project

**Bug** dojo create theme hanging in Windows 10

Bug

I tried running dojo create theme --name dojo. It started up, asked for the Package. and then Any More? I replied no and then it just hangs. At least 13 hours so far.

Code

dojo create theme --name dojo
? What Package to do you want to theme? @dojo/widgets
? Any more? No

Expected behavior:

I expect a list of widgets to select from.

Actual behavior:

Nothing Happened. It just froze. Ctrl-C does not work and I had to shut down the command window.

I shut down the Terminal Window and tried it again to fully document it.

I opened CMD with Administrator priveledges (just in case)

Here are the steps I took.

F:\hcaccess\biz-e-corp>dir

Volume in drive F is My Passport
Volume Serial Number is 229A-9512

Directory of F:\hcaccess\biz-e-corp

2018-11-23 08:09 PM

.
2018-11-23 08:09 PM ..
2018-11-23 08:04 PM node_modules
2018-11-23 03:53 PM output
2018-11-23 08:04 PM 543,344 package-lock.json
2018-11-23 08:04 PM 539 package.json
2018-11-22 11:37 AM src
2018-11-23 08:09 PM test
2018-11-23 08:09 PM test.n
2018-11-21 05:15 PM tests
2018-11-21 05:15 PM 599 tsconfig.json
2018-11-21 05:15 PM 1,910 tslint.json
4 File(s) 546,392 bytes
8 Dir(s) 1,974,680,293,376 bytes free

F:\hcaccess\biz-e-corp>
F:\hcaccess\biz-e-corp>dojo create theme --name dojo
? What Package to do you want to theme? @dojo/widgets
? Any more? No
This package path does not exist: node_modules@dojo\widgets\theme

At this point I checked and node_modules\@dojo\widgets was gone as well as node_modules\@dojo\themes I copied them from another site I tried when first using Dojo 2. The Hello World app.

F:\hcaccess\biz-e-corp>dir node_modules@dojo
Volume in drive F is My Passport
Volume Serial Number is 229A-9512

Directory of F:\hcaccess\biz-e-corp\node_modules@dojo

2018-11-24 09:17 AM

.
2018-11-24 09:17 AM ..
2018-11-21 05:17 PM cli-build-app
2018-11-23 07:40 PM cli-create-theme
2018-11-23 08:04 PM cli-create-widget
2018-11-21 05:17 PM cli-test-intern
2018-11-21 05:17 PM framework
2018-11-24 09:17 AM themes
2018-11-21 05:17 PM webpack-contrib
2018-11-24 09:17 AM widgets
0 File(s) 0 bytes
10 Dir(s) 1,974,665,129,984 bytes free

F:\hcaccess\biz-e-corp>dojo create theme --name dojo
? What Package to do you want to theme? @dojo/widgets
? Any more? No

Same result. Except the Widgets and themes folders did not disappear.

Address code review feedback

@tomdye has left some extra comments here: #1 so this issue is a reminder that those comments need addressing.

README feedback

1. We've still got a TODO in the README for adding mentions of third party libraries
2. What is there is fine, and explains clearly how to use the command, but after reading the README I'm not really sure what this is doing for me. I know it's creating a couple of files and I can fill in some selectors, but I don't know what that's really buying me in terms of creating a theme.

Improve the formatting for the generated theme file

Here is what it looks like:

Should fix the extra new lines, trailing spaces and trailing comma on the last exported key-value pair.

When there are multiple widgets, the formatting can also be improved:

Improve the output of CSS modules

The CSS module file which is output for some widgets can look like this:

That's the calendar. It's a little overwhelming and hard to visually locate selectors in such a long list, we could improve this output by alphabetizing the selectors.

Generated theme does not work in Windows

Bug

The generated theme file does not work in Windows. The theme.ts file that gets generated looks like,

import * as accordionPane from './@dojo\widgets\accordion-pane/accordion-pane.m.css';

export default {
	'@dojo\widgets\accordion-pane': accordionPane
};

Notice specifically the path of the import, ./@dojo\widgets\accordion-pane/accordion-pane.m.css. Those \ characters are causing the import to fail and should be /.

To reproduce, simply use dojo create theme --name test in Windows...

Handle the case of existing CSS module files

When we detect an existing theme file is present, we do not overwrite it, however this same behavior doesn't kick in for existing CSS module files meaning they can get overwritten. Ideally we would inform the user of:

• The path of the existing CSS module file
• The fact that we will not overwrite it
• The list of CSS selectors which they can manually merge into their CSS file if they wish to

Missing CSS module definition files leads to a confusing workflow

The generated theme files links to a CSS module that does yet have a TS definition, so you see this error in the editor:

This is a bit confusing and would be nicer if the CSS modules used to automatically generate definition files.

Grunt release does not work

Bug

Grunt release command is not working due to Command / Helper types not being used and eject object being invalid.

Improve the formatting of the theme template

Enhancement

Code
The template formatting of https://github.com/dojo/cli-create-theme/blob/master/src/templates/src/theme.ts.ejs is not maintainable and doesn't adhere to our practices of code style, so we should look at how we can improve considering we need to preserve the output theme file which is created from this template.

Create a cli-util repo which common CLI utilities

This comment explains all! #1 (comment)

Package needs to be updated for 3.0

This package should be updated to use the new @dojo/scripts and the latest @dojo/cli.

Fix failing unit tests

Bug

Unit tests are failing on windows on travis.

Add Appveyor for testing on windows

We should add appveyor to run the unit tests on windows. See one of the other CLI commands for an example.

Instruct the user what to do with their new theme file

Enhancement

Tom had a good idea:

the output should include a message along the lines of please import 'src/themes/myTheme/theme' into your project to use your new theme

Handle the case when a theme file already exists

When a theme file already exists, you see this message:

A theme file already exists in ....src/themes/theme.ts. Will not overwrite.

But we do still generate the CSS modules. We should address this somehow, for example, print out the code in the terminal, and instruct the user to merge it with their existing theme file.

Improve terminal output to explain to the user exactly what was created

Here is a happy path:

dojo create theme
? What Package to do you want to theme? @dojo/widgets
? Any more? No
? Which of the @dojo/widgets theme files would you like to scaffold? accordionPane
 create ...src/themes/theme.ts

Notice, we are told a theme file was created, but not which CSS modules were created. The user should be told this information.

Support for third party widgets

Right now, this will only work for the official Dojo widgets, this won't work for third party widgets out of the box. What level of support should be provided for third party widgets?