GitBook: [#27] No subject

README (1).md

@@ -0,0 +1,168 @@
+---
+description: Start using TSS, with or without MUI
+---
+
+# 🔧 Setup
+
+```
+yarn add tss-react @emotion/react
+```
+
+{% tabs %}
+{% tab title="With MUI" %}
+{% hint style="info" %}
+If you are migrating from `@material-ui/core` (v4) to `@mui/material` (v5) checkout the migration guide from MUI's documentation website [here](https://mui.com/guides/migration-v4/#2-use-tss-react).
+{% endhint %}
+
+{% hint style="info" %}
+If you are still using material-ui v4 [here is a reference setup](https://github.com/garronej/tss-react/tree/main/src/test/apps/muiV4ssr).
+{% endhint %}
+
+```tsx
+import { render } from "react-dom";
+import { CacheProvider } from "@emotion/react";
+import createCache from "@emotion/cache";
+import { ThemeProvider } from "@mui/material/styles";
+
+export const muiCache = createCache({
+    "key": "mui",
+    "prepend": true
+});
+
+//NOTE: Don't use <StyledEngineProvider injectFirst/>
+render(
+    <CacheProvider value={muiCache}>
+        <ThemeProvider theme={myTheme}>
+            <Root />
+        </ThemeProvider>
+    </CacheProvider>,
+    document.getElementById("root")
+);
+```
+
+As a MUI user (if you are using TypeScript >= v4.4), you can simply:
+
+```typescript
+import { makeStyles, withStyles } from "tss-react/mui";
+```
+
+The theme object that will be passed to your callbacks functions will be the one you get with `import { useTheme } from "@mui/material/styles"`.
+
+If you want to take controls over what the `theme` object should be, you can re-export `makeStyles` and `withStyles` from a file called, for example, `makesStyles.ts`:
+
+```typescript
+import { useTheme } from "@mui/material/styles";
+//WARNING: tss-react require TypeScript v4.4 or newer. If you can't update use:
+//import { createMakeAndWithStyles } from "tss-react/compat";
+import { createMakeAndWithStyles } from "tss-react";
+
+export const { makeStyles, withStyles } = createMakeAndWithStyles({
+    useTheme
+    // OR, if you have extended the default mui theme adding your own custom properties: 
+    // Let's assume the myTheme object that you provide to the <ThemeProvider /> is of 
+    // type MyTheme then you'll write:
+    //"useTheme": useTheme as (()=> MyTheme)
+});
+```
+
+`./MyComponent.tsx`
+
+```tsx
+import { makeStyles } from "tss-react/mui";
+//OR:
+//import { makeStyles } from "./makeStyles";
+
+export function MyComponent(props: Props) {
+    const { className } = props;
+
+    const [color, setColor] = useState<"red" | "blue">("red");
+
+    const { classes, cx } = useStyles({ color });
+
+    //Thanks to cx, className will take priority over classes.root 🤩
+    //With TSS you must stop using clsx and use cx instead.
+    return <span className={cx(classes.root, className)}>hello world</span>;
+}
+
+const useStyles = makeStyles<{ color: "red" | "blue" }>()(
+    (theme, { color }) => ({
+        "root": {
+            color,
+            "&:hover": {
+                "backgroundColor": theme.primaryColor
+            }
+        }
+    })
+);
+```
+
+{% hint style="warning" %}
+**Keep `@emotion/styled` as a dependency of your project**.
+
+Even if you never use it explicitly, it's a peer dependency of `@mui/material`.
+{% endhint %}
+
+{% hint style="warning" %}
+[Storybook](https://storybook.js.org): As of writing this lines storybook still uses by default emotion 10.\
+Material-ui and TSS runs emotion 11 so there is [some changes](https://github.com/garronej/onyxia-ui/blob/324de62248074582b227e584c53fb2e123f5325f/.storybook/main.js#L31-L32) to be made to your `.storybook/main.js` to make it uses emotion 11.
+{% endhint %}
+{% endtab %}
+
+{% tab title="Standalone" %}
+```
+yarn add tss-react @emotion/react
+```
+
+`./makeStyles.ts`
+
+```typescript
+import { createMakeStyles } from "tss-react";
+
+function useTheme() {
+    return {
+        "primaryColor": "#32CD32",
+    };
+}
+
+export const { makeStyles } = createMakeStyles({ useTheme });
+```
+
+`./MyComponent.tsx`
+
+```tsx
+import { makeStyles } from "./makeStyles";
+
+export function MyComponent(props: Props) {
+    const { className } = props;
+
+    const [color, setColor] = useState<"red" | "blue">("red");
+
+    const { classes, cx } = useStyles({ color });
+
+    //Thanks to cx, className will take priority over classes.root 🤩
+    return <span className={cx(classes.root, className)}>hello world</span>;
+}
+
+const useStyles = makeStyles<{ color: "red" | "blue" }>()(
+    (theme, { color }) => ({
+        "root": {
+            color,
+            "&:hover": {
+                "backgroundColor": theme.primaryColor
+            }
+        }
+    })
+);
+```
+{% endtab %}
+{% endtabs %}
+
+{% hint style="success" %}
+If you don't want to end up writing things like:
+
+```typescript
+import { makeStyles } from "../../../../../../makeStyles";
+```
+
+You can put [`"baseUrl": "src"`](https://github.com/InseeFrLab/onyxia-web/blob/ae02b05cd7b17d74fb6a8cbc4c7b1c6f569dfa41/tsconfig.json#L3) in your `tsconfig.json` and import things [relative to your `src/` directory](https://github.com/garronej/tss-react/blob/314aaab87198e7fd3523e34300288495f3242800/src/test/spa/src/index.tsx#L2-L3).
+{% endhint %}

README.md

@@ -6,12 +6,13 @@ description: ✨ makeStyles is dead, long live makeStyles! ✨
 
 [![](https://github.com/garronej/tss-react/workflows/ci/badge.svg?branch=main) ](https://github.com/garronej/tss-react/actions)[![](https://img.shields.io/npm/dw/tss-react) ](https://www.npmjs.com/package/tss-react)[![](https://img.shields.io/npm/l/tss-react)](https://github.com/garronej/tss-react/blob/main/LICENSE)
 
-`'tss-react'` is intended to be the replacement for [@material-ui v4 `makeStyles`](https://material-ui.com/styles/basics/#hook-api) and [`'react-jss'`](https://cssinjs.org/react-jss/?v=v10.9.0).
+'tss-react' is intended to advantageously replace the now deprecated [@material-ui v4 makeStyles](https://material-ui.com/styles/basics/#hook-api) and [react-jss](https://cssinjs.org/react-jss/?v=v10.9.0) by providing much better TypeScript support.
 
 * ✅ Seamless integration with [MUI](https://mui.com) and [material-ui v4](https://v4.mui.com).
 * ✅ [`withStyles`](https://v4.mui.com/styles/api/#withstyles-styles-options-higher-order-component) API support.
+* ✅ [JavaScript support](https://github.com/garronej/tss-react/issues/28).
 * ✅ Server side rendering support (e.g: Next.js).
-* ✅ Offers a type-safe equivalent of the JSS `$` syntax.
+* ✅ Offers [a type-safe equivalent of the JSS `$` syntax](nested-selectors-ex-usd-syntax.md).
 * ✅ Custom `@emotion` cache support.
 * ✅ Build on top of [`@emotion/react`](https://emotion.sh/docs/@emotion/react), it has very little impact on the bundle size alongside MUI (\~5kB minziped).
 * ✅ [Maintained for the foreseeable future](https://github.com/mui-org/material-ui/issues/28463#issuecomment-923085976), issues are dealt with within good delays.

SUMMARY.md

@@ -1,7 +1,7 @@
 # Table of contents
 
 * [🚀 Why TSS](README.md)
-* [🔧 Setup](README.md)
+* [🔧 Setup](<README (1).md>)
 * [🔍 API References](page-1.md)
   * [makeStyles -> useStyles](api-references/makestyles-greater-than-usestyles.md)
   * [withStyles](api-references/withstyles.md)