support global typescript theme definition

[k-yle]

This PR fixes a number of things that make react-jss's createUseStyles less convenient for TypeScript users.

The problems:

1. Defining createUseStyles is tedious because you need to pass the theme as a type argument every time, which has to be imported from somewhere (createUseStyles<MyTheme>(theme => { ... }))
2. If you supply a type argument, then you lose one of the most important type safety features - the typecheck of the class names:
   
   This is because, if you supply a type argument, the union type ("myHeader" | "myFooter" in the screenshot) just becomes string.
   ­
   To fix this, you have to duplicate every class name, and now the code looks horrendous:

   createUseStyles<MyTheme, "myHeader" | "myFooter">(theme => ({ 
     myHeader: { margin: 0 },
     myFooter: { padding: 0 },
   }))

3. For JavaScript users, or mixed TS/JS users, there is no way to get auto-complete (intellisense) for the theme. Because the createUseStyles<MyTheme>() syntax is not possible in JS files.

This PR fixes these 3 issues.

Anyone (TypeScript and JavaScript users) can create a file called global.d.ts anywhere in their project. It is not imported by anything; TypeScript and/or VSCode's TSServer finds it automatically. It could like this:

declare global {
  namespace Jss {
    export interface Theme {
      themeColour: string;
    }
  }
}

export {};

Now, when call createUseStyles() you don't need to provide any type arguments to get type definitions for the theme, and the class names (see screenshot above) are automatically inferred by typescript without defining them separately.

I have added tests to confirm that this works and that TypeScript produces errors if you make a typo in the classes object or the theme object.

Todo

• Add test that verifies the modified behaviour
• Add documentation if it changes public API

[moshest]

Most users will be lazy and will not create the Theme interface. How the library going to behave in this case?

[moshest]

lgtm

[k-yle]

hi @moshest, if users don't extend the JSS.Theme interface, it will just be an empty interface {}

this matches the old behaviour, so it won't be a breaking a change.

[kof]

merged, thanks!

[kof]

will be released with the next release, we aggregate a bit

[kof]

Released in v10.6.0