Add docs
This commit is contained in:
Mark Sinclair
@@ -0,0 +1,12 @@
|
|||||||
|
# Shared assets
|
||||||
|
|
||||||
|
This directory contains asset files shared by many projects in this repo.
|
||||||
|
|
||||||
|
You will find:
|
||||||
|
|
||||||
|
- favicons
|
||||||
|
- logos
|
||||||
|
- shared fonts
|
||||||
|
- shared icon SVGs
|
||||||
|
|
||||||
|
See [ts-packages/react-webpack-with-theme-example](../ts-packages/react-webpack-with-theme-example) for examples of usage.
|
||||||
@@ -0,0 +1,70 @@
|
|||||||
|
# Nym MUI Theme
|
||||||
|
|
||||||
|
This package provides an extension to the MUI theme system to use Nym branding.
|
||||||
|
|
||||||
|
If you are unfamiliar with Material UI theming, please read the following first:
|
||||||
|
- https://mui.com/customization/theming/
|
||||||
|
- https://mui.com/customization/palette/
|
||||||
|
- https://mui.com/customization/dark-mode/#dark-mode-with-custom-palette
|
||||||
|
|
||||||
|
## Add theme typings to your project
|
||||||
|
|
||||||
|
This package also provides a [template file](./template/mui-theme.d.ts) to add typings to the theme using Typescript's module augmentation.
|
||||||
|
|
||||||
|
Read the following if you are unfamiliar with module augmentation and declaration merging. Then
|
||||||
|
look at the recommendations from Material UI docs for implementation:
|
||||||
|
- https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation
|
||||||
|
- https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-interfaces
|
||||||
|
- https://mui.com/customization/palette/#adding-new-colors
|
||||||
|
|
||||||
|
## Example usage
|
||||||
|
|
||||||
|
You can see an example of how to use this theme in [react-webpack-with-theme-example](../react-webpack-with-theme-example/src/App.tsx):
|
||||||
|
|
||||||
|
```typescript jsx
|
||||||
|
export const App: React.FC = () => (
|
||||||
|
<AppContextProvider>
|
||||||
|
<AppTheme>
|
||||||
|
<Content />
|
||||||
|
</AppTheme>
|
||||||
|
</AppContextProvider>
|
||||||
|
);
|
||||||
|
|
||||||
|
export const AppTheme: React.FC = ({ children }) => {
|
||||||
|
const { mode } = useAppContext();
|
||||||
|
|
||||||
|
return <NymThemeProvider mode={mode}>{children}</NymThemeProvider>;
|
||||||
|
};
|
||||||
|
|
||||||
|
export const Content: React.FC = () => {
|
||||||
|
...
|
||||||
|
<Typography sx={{ color: (theme) => theme.palette.nym.networkExplorer.mixnodes.status.active }}>
|
||||||
|
The quick brown fox jumps over the white fence
|
||||||
|
</Typography>
|
||||||
|
...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
The best way to make changes to the theme is to:
|
||||||
|
|
||||||
|
1. Run this package in watch mode with `yarn watch`
|
||||||
|
2. Run Storybook from [react-components](../react-components/README.md) with `yarn storybook`
|
||||||
|
3. Make sure the component you are changing is included in the [playground](../react-components/src/playground/index.tsx)
|
||||||
|
4. Watch for changes in the [Playground story](../react-components/src/stories/Playground.stories.tsx)
|
||||||
|
|
||||||
|
Also remember to check light mode and dark mode!
|
||||||
|
|
||||||
|
## Building
|
||||||
|
|
||||||
|
This package should be built from the root of the repository as follows:
|
||||||
|
|
||||||
|
```
|
||||||
|
yarn
|
||||||
|
yarn build
|
||||||
|
```
|
||||||
|
|
||||||
|
## Publishing
|
||||||
|
|
||||||
|
This package is not published to NPM ... yet.
|
||||||
@@ -0,0 +1,52 @@
|
|||||||
|
# Nym Shared React Components
|
||||||
|
|
||||||
|
This package contains shared React components that are used in other Nym projects.
|
||||||
|
|
||||||
|
It uses the following packages:
|
||||||
|
|
||||||
|
- [shared MUI theme](../mui-theme/README.md)
|
||||||
|
- [webpack config](../webpack/README.md)
|
||||||
|
- [MUI](https://https://mui.com/)
|
||||||
|
- Typescript
|
||||||
|
- React
|
||||||
|
|
||||||
|
## Building
|
||||||
|
|
||||||
|
```
|
||||||
|
yarn
|
||||||
|
yarn build
|
||||||
|
```
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
Run watch mode with:
|
||||||
|
|
||||||
|
```
|
||||||
|
yarn watch
|
||||||
|
```
|
||||||
|
|
||||||
|
Or you can run Storybook with:
|
||||||
|
|
||||||
|
```
|
||||||
|
yarn storybook
|
||||||
|
```
|
||||||
|
|
||||||
|
Or you can run the [example project](../react-webpack-with-theme-example/README.md) in dev mode and this package in watch mode, and test results in the example project's dev server output.
|
||||||
|
|
||||||
|
## Playground
|
||||||
|
|
||||||
|
There are [playground components](./src/playground/index.tsx) that are intended to be used during development to see the effects are changes to the MUI theme or shared components at a glance.
|
||||||
|
|
||||||
|
They are available in Storybook from [src/stories/Playground.stories.tsx](./src/stories/Playground.stories.tsx).
|
||||||
|
|
||||||
|
> ℹ️ **Tip**: use the playground to make sure components stay consistent and you don't break other components while making changes
|
||||||
|
|
||||||
|
## Shared assets
|
||||||
|
|
||||||
|
This project uses [shared asset files](../../assets/README.md) such as favicons and logos.
|
||||||
|
|
||||||
|
> ℹ️ **Tip**: use to keep your project consistent with Nym's branding and so that it automatically receives changes when the shared assets change. Please try to avoid duplicating the files in the shared assets directory.
|
||||||
|
|
||||||
|
## Publishing
|
||||||
|
|
||||||
|
This package is not published to NPM ... yet.
|
||||||
@@ -0,0 +1,98 @@
|
|||||||
|
# Example with React + Typescript + Webpack 5 + MUI
|
||||||
|
|
||||||
|
An example of using default Webpack and Typescript settings with React and MUI, including theming.
|
||||||
|
|
||||||
|
You can use this example as a seed for a new project.
|
||||||
|
|
||||||
|
Remember to build the dependency packages from the root of this repo by running:
|
||||||
|
|
||||||
|
```
|
||||||
|
yarn
|
||||||
|
yarn build
|
||||||
|
```
|
||||||
|
|
||||||
|
If you need to make changes to the dependency packages, you can run `yarn watch` in that package to watch for chagnes and build them. This project will pick up the changes in the built package and hot-reload / recompile.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
### Yarn workspaces
|
||||||
|
|
||||||
|
Packages from `ts-packages` are shared using Yarn workspaces. Make sure you add you new project to [package.json](../../package.json) to use the shared packages.
|
||||||
|
|
||||||
|
> ⚠️ **Warning**: Yarn workspaces will share all dependencies between projects and works by falling back to parent directories until a `node_modules` directory is found. So be careful when messing around with `node_modules` and resolution, because unexpected things could happen - for example, if you do not run `yarn` from the root and you have a `node_modules` in a directory that is a parent of the directory where you checkout out this repository, that `node_modules` will be used for resolving packages 🙀.
|
||||||
|
|
||||||
|
### Typescript
|
||||||
|
|
||||||
|
Shared Typescript config is in [tsconfig.json](./tsconfig.json), with specific production settings in [tsconfig.prod.json](./tsconfig.prod.json) that:
|
||||||
|
|
||||||
|
- exclude Storybook stories and Jest tests
|
||||||
|
- do not output typing `*.d.ts` files
|
||||||
|
|
||||||
|
### Webpack
|
||||||
|
|
||||||
|
Inherit config for Webpack 5 with additional tweaks including:
|
||||||
|
|
||||||
|
- favicon generation from [SVG favicon asset files](../../assets/favicon/favicon.svg)
|
||||||
|
- asset handling (svg, png, fonts, css, etc)
|
||||||
|
- minification
|
||||||
|
|
||||||
|
The development settings include:
|
||||||
|
|
||||||
|
- `ts-loader` for quick transpilation
|
||||||
|
- threaded type checking using `tsc`
|
||||||
|
- hot reloading using `react-refresh`
|
||||||
|
|
||||||
|
### Storybook
|
||||||
|
|
||||||
|
Storybook is available in [@nymproject/react](../react-components/src/stories/Introduction.stories.mdx) and can be run using `yarn storybook`.
|
||||||
|
|
||||||
|
### MUI and theming
|
||||||
|
|
||||||
|
The [Nym theme](../mui-theme/src/theme/theme.ts) provides a theme provider that you can add as follows:
|
||||||
|
|
||||||
|
```typescript jsx
|
||||||
|
export const App: React.FC = () => (
|
||||||
|
<AppContextProvider>
|
||||||
|
<AppTheme>
|
||||||
|
<Content />
|
||||||
|
</AppTheme>
|
||||||
|
</AppContextProvider>
|
||||||
|
);
|
||||||
|
|
||||||
|
export const AppTheme: React.FC = ({ children }) => {
|
||||||
|
const { mode } = useAppContext();
|
||||||
|
|
||||||
|
return <NymThemeProvider mode={mode}>{children}</NymThemeProvider>;
|
||||||
|
};
|
||||||
|
|
||||||
|
export const Content: React.FC = () => {
|
||||||
|
...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
And augment typings for the Theme by adding [mui-theme.d.ts](./src/theme/mui-theme.d.ts):
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import { Theme, ThemeOptions, Palette, PaletteOptions } from '@mui/material/styles';
|
||||||
|
import { NymTheme, NymPaletteWithExtensions, NymPaletteWithExtensionsOptions } from '@nymproject/mui-theme';
|
||||||
|
|
||||||
|
declare module '@mui/material/styles' {
|
||||||
|
interface Theme extends NymTheme {}
|
||||||
|
interface ThemeOptions extends Partial<NymTheme> {}
|
||||||
|
interface Palette extends NymPaletteWithExtensions {}
|
||||||
|
interface PaletteOptions extends NymPaletteWithExtensionsOptions {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Adding the above, means that any component now has the correct typings, for example, below the Nym palette interface is available for all MUI `Theme` instances with code completion for VSCode and IntelliJ:
|
||||||
|
|
||||||
|
```typescript jsx
|
||||||
|
import { Typography } from '@mui/material';
|
||||||
|
|
||||||
|
...
|
||||||
|
|
||||||
|
<Typography sx={{ color: (theme) => theme.palette.nym.networkExplorer.mixnodes.status.active }}>
|
||||||
|
The quick brown fox jumps over the white fence
|
||||||
|
</Typography>
|
||||||
|
|
||||||
|
```
|
||||||
@@ -0,0 +1,11 @@
|
|||||||
|
# Common Webpack 5 Config
|
||||||
|
|
||||||
|
This package contains shared configuration for webpack:
|
||||||
|
|
||||||
|
- [webpack.common.js](./webpack.common.js): common settings for a Typescript + React project
|
||||||
|
- [webpack.dev.js](./webpack.dev.js): additional settings for dev mode
|
||||||
|
- [webpack.prod.js](./webpack.prod.js): production settings
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
See [the example](../react-webpack-with-theme-example/README.md)
|
||||||
Reference in New Issue
Block a user