@opengeoweb/theme 2.0.1 → 2.1.0

package/README.md

@@ -1,115 +1,508 @@
-[![pipeline status](https://gitlab.com/opengeoweb/geoweb-theme/badges/master/pipeline.svg)](https://gitlab.com/opengeoweb/geoweb-theme/-/commits/master)
-[![current version](https://img.shields.io/badge/dynamic/json?color=blue&label=version&query=version&url=https://gitlab.com/opengeoweb/geoweb-theme/raw/master/package.json)](https://gitlab.com/opengeoweb/geoweb-theme/-/tags)
+# Theme
+
+The aim of this library is to make sure all MUI components look as specified in the designs found on Zeplin. There are multiple themes (dark and light) with color and stying which can be added and all values are accessible throughout the whole application.
+
+## Content
+
+- [Quick start](#quick-start)
+  - [Running storybook](#running-storybook)
+  - [Adding styles/colors](#adding-styles-colors)
+  - [Using styles/colors to (React/MUI) components](#using-styles-colors-to--react-mui--components)
+  - [Using styles/colors in canvas components](#using-styles-colors-in-non--canvas--mui-components)
+  - [Using themes in stories](#using-themes-in-stories)
+- [Rules of theme lib](#rules-of-theme-lib)
+- [Folder structure](#folder-structure)
+  - [types `(lib/components/Theme/types.ts)`](#types---lib-components-theme-typests--)
+  - [themes `(lib/components/Theme/darkTheme.ts, .../lightTheme.ts, .../gwTheme.ts)`](#themes---lib-components-theme-darkthemets---lightthemets---gwthemets--)
+  - [ThemeContext `(lib/components/Theme/ThemeContext)`](#themecontext---lib-components-theme-themecontext--)
+  - [utils `(lib/components/Theme/utils.ts)`](#utils---lib-components-theme-utilsts--)
+  - [stories `(lib/stories)`](#stories---lib-stories--)
+- [Naming convention](#naming-convention)
+- [Theme Stories `(lib/stories)`](#theme-stories---lib-stories--)
+  - [Overwrite default MUI component styling](#overwrite-default-mui-component-styling)
+- [important note about Material UI v5](#important-note-about-material-ui-v5)
+- [Guidelines and tips for translating design to code](#guidelines-and-tips-for-translating-design-to-code)
+  - [Layer manager example](#layer-manager-example)
+    - [Wrapper](#wrapper)
+    - [Top bar](#top-bar)
+    - [Table](#table)
+    - [Footer](#footer)
+- [Do's and dont's](#do-s-and-dont-s)
+  - [Do's](#do-s)
+  - [Don'ts](#don-ts)
+- [Known issues](#known-issues)
+- [Roadmap](#roadmap)
+- [Unit testing](#unit-testing)
+- [Image snapshot testing](#image-snapshot-testing)
+  - [Add a new snapshot test](#add-a-new-snapshot-test)
+  - [Running snapshot tests and updating snapshots locally](#running-snapshot-tests-and-updating-snapshots-locally)
+- [Questions and feedback](#questions-and-feedback)
+- [Documentation](#documentation)
+
+<small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>
+
+## Quick start
+
+### Running storybook
 
-# KNMI GeoWeb Theme
+```
+nx storybook theme
+```
+
+### Adding styles/colors
+
+1. Add the name and type on the GeowebColorPalette type
+
+```javascript
+// libs/theme/src/lib/components/Theme/types.ts
+export type GeowebColorPalette = {
+  buttons: {
+    primaryMouseOver: CSSProperties,
+  },
+  // ... rest of type
+};
+```
+
+2. Add the style/color values in lightTheme and darkTheme
+
+```javascript
+/// libs/theme/src/lib/components/Theme/lightTheme.ts
+export const colors: GeowebColorPalette = {
+  buttons: {
+    primaryMouseOver: {
+      fill: '#186DFF',
+      border: '#71A6FF',
+    },
+  },
+```
+
+3. Verify it works by navigating to the Color story demo and see the new colors work in all themes. Every property you fill in is accessible throughout every app or library.
+
+### Using styles/colors to (React/MUI) components
+
+1. Make sure the theme ThemeProvider is used
+
+```javascript
+import { ThemeProvider } from '@opengeoweb/theme';
+
+export const Wrapper: React.FC = () => (
+  <ThemeProvider>
+    <MyComponent />
+  </ThemeProvider>
+);
+```
+
+> **note** make sure to use the ThemeProvider in unit tests too, as they will fail otherwise
+
+2.  Use the style/color in your component. The theme palette can be found as `geowebColor` property inside the `theme.palette` of the MUI Theme
+
+```javascript
+const useStyles = makeStyles((theme) => ({
+  button: {
+    border: theme.palette.geowebColors.buttons.flatMouseOver.border,
+    '&:hover': {
+      backgroundColor: theme.palette.geowebColors.buttons.flatMouseOver.fill,
+    },
+  },
+}));
+
+const MyButton: React.FC = () => {
+  const classes = useStyles();
+  return <Button className={classes.button}>content</Button>;
+};
+```
+
+### Using styles/colors in canvas components
+
+Since the color values are depending on the current selected theme, we can't use a static object for color values. A simple solution for this is to access the theme via `useTheme` hook selector, and pass it as a param to the canvas drawing function.
+
+1. Use `useTheme` selector and pass theme as argument to the draw method:
+
+```javascript
+// libs/core/src/lib/components/TimeSlider/TimeSliderLegend/TimeSliderLegend.tsx
+const TimeSliderLegend: React.FC<TimeSliderLegendProps> = (
+  props: TimeSliderLegendProps,
+) => {
+  const theme = useTheme();
+  return (
+    <div>
+      <CanvasComponent
+        onRenderCanvas={(ctx: CanvasRenderingContext2D): void => {
+          renderTimeSliderLegend(
+            ctx,
+            theme,
+            // ...props and other methods
+          );
+        }}
+      />
+    </div>
+  );
+};
+```
+
+2. Extend the render method with theme as argument, and pass if necessary the theme further to the other render methods. Most easy way is to just pass the whole theme as object, so you can use the `Theme` type from MUI.
+
+```javascript
+// libs/core/src/lib/components/TimeSlider/TimeSliderLegend/TimeSliderLegendRenderFunctions.tsx
+import { Theme } from  '@material-ui/core';
+
+export const renderTimeSliderLegend = (
+  context: CanvasRenderingContext2D,
+  theme: Theme,
+  canvasWidth: number,
+  height: number,
+  centerTime: number,
+  secondsPerPx: number,
+  dataScaleToSecondsPerPx: number,
+  selectedTimeUnix: number,
+  scale: Scale,
+  currentTimeUnix: number,
+): void => {
+  const ctx = context;
+
+  drawBackground(
+    ctx,
+    theme,
+    visibleTimeStart,
+    visibleTimeEnd,
+    canvasWidth,
+    height,
+    scale,
+  );
+```
+
+3. Use the color (or any other given property) by deconstructing the passed theme if needed, and if needed use the `rgba` property.
+
+```javascript
+// libs/core/src/lib/components/TimeSlider/TimeSliderLegend/TimeSliderLegendRenderFunctions.tsx
+const drawBackground = (
+  context: CanvasRenderingContext2D,
+  theme: Theme,
+  visibleTimeStart: number,
+  visibleTimeEnd: number,
+  canvasWidth: number,
+  height: number,
+  scale: Scale,
+): void => {
+  const ctx = context;
+  const { timelineTimelineSurface, timelineNightTime} = theme.palette.geowebColors.timeSlider
+
+    ctx.fillStyle = isColorIntervalEven(scale, timestep)
+      ? timelineTimelineSurface.rgba
+      : timelineNightTime.rgba;
+  });
+};
+```
+
+### Using themes in stories
+
+When using a component which relies on theme styling, wrap the main component of your story with the `ThemeWrapper` component instead of `ThemeProvider`. `ThemeWrapper` will later get an extra `StyleEngineProvider` parent component (see https://mui.com/guides/migration-v4/#style-library). For components with old GWTheme styline, you can use `ThemeWrapperOldTheme`.
+
+If you need to show multiple stories and don't want to see the default background, use the `disableCssBaseline` property to prevent that.
+
+```javascript
+import { darkTheme, ThemeWrapper } from '../../components/Theme';
+
+export const TableDark = (): React.ReactElement => (
+  <ThemeWrapper theme={darkTheme}>
+    <TableDemo />
+  </ThemeWrapper>
+);
+```
+
+## Rules of theme lib
+
+- The theme should not export any other component then the themes, ThemeProvider and corresponding hooks. This lib is only showing the MUI components with the correct default style. If you need a component which needs custom props and should be used across different applications, consider making a new component in the `shared` lib.
+- It should not import other any library other then MUI.
+
+## Folder structure
+
+```
+// lib/components
+// lib/components/Theme/darkTheme.ts
+// lib/components/Theme/lighTheme.ts
+// lib/components/Theme/gwTheme.ts
+// lib/components/Theme/utils.ts
+// lib/components/Theme/types.ts
+// lib/components/Theme/ThemeContext.tsx
+
+// lib/stories
+// lib/stories/StoryWrapper.tsx
+// lib/stories/story.stories.tsx
+```
+
+#### types `(lib/components/Theme/types.ts)`
+
+Defines the color palette of the theme.
+
+#### themes `(lib/components/Theme/darkTheme.ts, .../lightTheme.ts, .../gwTheme.ts)`
+
+Exports files containing all the values per theme. Every color added to light or dark will automatically be inserted into gwTheme to maintain backwards compatibility while finishing the theme colors.
+
+#### ThemeContext `(lib/components/Theme/ThemeContext)`
+
+- exports `ThemeProvider` wrapper for all MUI components including a `CssBaseline` component of MUI.
+- exports an `useThemeContext` to switch themes.
+- exports `ThemeWrapper` wrapper for stories and `ThemeWrapperOldTheme` wrapper for stories with old GWTheme (to be deprecated)
+
+#### utils `(lib/components/Theme/utils.ts)`
 
-### Installation
+- **hex2rgba** handles hex values to rgba
+- **parseColors** parses the theme values and when opacity and fill are given, adds a rgba value. This is handy for canvas components, as they expect one value to render a fill.
 
-To run the KNMI Theme storybook you need npm. The easiest way to install npm is via nvm. Please visit https://nvm.sh/ and follow the instructions. When nvm is installed, please run the following command:
+  If in future another parser is needed (for example a font parser: when fontSize and fontFamily is given, return font which combines those values), it can be added here,
 
+- **createShadows** creates a list of shadows (elevations) as specified by design . These can be accessed through the theming by `theme.shadows`.
+- **createTheme** function that creates the theme with given colors and shadows. This also override default MUI components. It sets the values of the theme as `geowebColors` inside the palette of the MUI Theme.
+
+#### stories `(lib/stories)`
+
+Contains demos of MUI components within the theme. [More information](#theme-stories---lib-stories--)
+
+## Naming convention
+
+When adding a new color, it needs to follow the names provided by design. It follows the pattern segmentName.elementName.value or segmentName.elementName.elementProp1.value.
+
+![naming convention](src/lib/docs/namingConvention.png?raw=true)
+
+If you look at the example above, you can see two segments: Background and Buttons. Backgrounds don't need much properties other then fill, so we don't need deep value. Buttons on the other hand have next to a fill a border, so it makes sense to specify it a bit more:
+
+```javascript
+// lib/components/Theme/lightTheme.ts
+  background: {
+    surface: '#FFFFFF',
+    surfaceApp: '#F5F5F5',
+    surfaceBrowser: '#CFCFCF',
+  },
+  buttons: {
+    primary: {
+      fill: '#F186DFF',
+      border: 'none',
+    },
+    tertiary: {
+      fill: 'none',
+      border: '#0075A9',
+    }
+  }
 ```
-nvm install 12
+
+Some Components have more colors sections. Take a look at some of the colors of the Timeslider.
+![enter image description here](src/lib/docs/timesliderColors.png?raw=true)
+
+> **Note:** Some color names have (D) after their name (currently only in Dark theme). This means the color already defined in the main Color Palette and you don't have to define it again.
+
+The segment is TimeSlider, and a sub segment is Player and Time scale. We don't want to create another level of depth so we solve this by adding this 'sub segment' as a prefix to the name of the element.
+
+```javascript
+// lib/components/Theme/darkTheme.ts
+ timeSlider: {
+    playerNeedlePlayerTop: {
+      fill: '#E3004F',
+      opacity: 100,
+    },
+	timeScaleText: {
+      fontSize: 12,
+    },
+    timeScaleTimeIndicatiors: {
+      fill: '#A2A2A2',
+    },
+  },
 ```
 
-### To run the storybook
+> **Note:** fill is often used for elements but color for example is also possible for font elements
+
+If there are mistakes in naming, colors are missing in the Design, contact [Didier](https://gitlab.com/didier.dezanet). Other way around as well, if any names have been changed [Didier](https://gitlab.com/didier.dezanet) should create a ticket to fix it here as well to keep consistency.
 
+## Theme Stories `(lib/stories)`
+
+Contains demo stories with MUI components. Every story is build with the `StoryWrapper` component which needs links to the designs (`lib/stories/StoryWrapper.tsx`) and can be toggled from light to dark theme. It does not export anything, it only shows the MUI components in light or dark theme.
+
+- The **Color** story shows all the colors, styles and other properties of the defined theme. Could be handy for reviewing styling values. On the right the `geowebColor` object is shown, and these values are accessible throughout all components with the ThemeProvider wrapper. Not that more values are shown than given, this is because of the parsers that adds in some cases extra properties as for example `rgba`
+- The **Elevation** shows all elevations we currently have. These can be used for defining `box-shadow` for elements. If you want to use the elevation in code:
+
+```javascript
+const useStyles = makeStyles((theme) => ({
+  header: {
+    boxShadow: theme.shadows[1], // elevation_01
+  },
+}));
 ```
-npm ci
-npm run storybook
+
+- The rest of the stories are for showing the MUI elements without any styling, other then the given theme styling.
+
+### Overwrite default MUI component styling
+
+When developing and using a new component of the MUI library which has no theme story, it could be a good idea to create a story, add the component there, and add some theme styling. That way there is a clear example how the component will look in the MUI environment.
+
+In the function below `createTheme` takes the value of theme and shadows (elevation) and creates the theme. Some default components are overwritten as MuiCssBaseline and MuiRadio with given theme styling.
+
+```javascript
+// libs/theme/src/lib/components/Theme/utils.ts
+export const createTheme = (
+  paletteType: PaletteType,
+  geowebColors: GeowebColorPalette,
+  shadows: Shadows,
+): Theme =>
+  createMuiTheme({
+    palette: {
+      background: {
+        paper: geowebColors.background.surfaceApp,
+        default: geowebColors.background.surfaceBrowser,
+      },
+      text: {
+        primary: geowebColors.typographyAndIcons.text,
+      },
+      // geoweb color palette
+      geowebColors,
+    },
+    shape: { borderRadius: BORDER_RADIUS },
+    typography: {
+      fontFamily: ['Roboto', 'Helvetica', 'Arial', 'sans-serif'].join(','),
+    },
+    shadows,
+    overrides: {
+      MuiCssBaseline: {
+        '@global': {
+          body: {
+            fontSmoothing: 'auto',
+          },
+        },
+      },
+      MuiRadio: {
+        root: {
+          color: geowebColors.typographyAndIcons.iconLinkActive,
+        },
+      },
+    }
 ```
 
-### Storybook
+> **Note:** when you add or change a style of a MUI component, every component will look default that way. If you need for example need some more custom styling or props, consider creating a reusable component in the `shared` library. Remember this library does not export components.
+
+## important note about Material UI v5
+
+Material UI v5 is just around the corner. This will making theming much easier with for example the possibility of [adding custom variants](https://next.material-ui.com/customization/theme-components/#adding-new-component-variants).
+
+For example, take a look in the designs of the [Buttons]. (https://app.zeplin.io/project/5ecf84a3c6ae1047a368f393/screen/5ecf85c60f301e47ca4eee55) There are multiple variants of the Button specified, but the MUI Button only accepts the default variant names supplied by MUI (contained, outlined, text). In future we could add custom new variants as primary, secondary and tertiary.
+
+If you want to have a reusable Button in this case there are two options:
+
+- Create a Button story in `theme` lib, add some buttons with variants of props that are matching with design. For example `<Button variant='filled' color="primary" />`. You probably need some overriding of styles so that can be added in `createTheme` at the override section. This is not ideal, as the it's still a bit of matching and combining with props, and not all names of design we can add.
+- Create a Button story in `shared` lib, import the Button of MUI, and add there all the (custom) variants you need. Colors and style can be retrieved by `useTheme` hook selector, this is a better solution as it won't break anything, and you name all props like provided in design to keep it consistent.
 
-#### Inspecting the components with storybook
+## Guidelines and tips for translating design to code
 
-Storybook can be used to view the components. If you run `npm run storybook` a storybook server will start in which you can see all the components for which stories are written.
+The designs found in Zeplin can roughly be split in two:
 
-#### Writing a new story
+1. Components
+   - Base components following MUI names as Container, Buttons, Elevation, Cards, Elevation, Table
+   - Grouped components combining Base components as Header, Top Bar
+2. Modules
+   - TimeSlider, Sigmet, LayerManager etc
 
-Stories live in the stories folder. Here is the documentation on the syntax for adding new stories:
-https://storybook.js.org/docs/basics/writing-stories/
+### Layer manager example
 
-#### Deploying a static version of your storybook
+In this example, we're going to have a look at the Layer manager.
+![enter image description here](src/lib/docs/layerManager.png?raw=true)
 
-The storybook can be compiled to a static version via npm run build-storybook. The static contents are then placed in the folder storybook-geoweb-core.
+Looking at the design, we can see it's consisting mainly out these elements:
 
-### Managing packages
+- Wrapper
+- Top bar
+- Table
+- Footer
 
-Follow the instructions below for dependency management. Please refer to [the documentation](https://docs.npmjs.com/cli-documentation/) for more information on any of the specific commands.
+#### Wrapper
 
-#### Removing extraneous packages
+This is the first component which holds all sub components which compose the Layermanager. Looking it from a MUI perspective, the first element should be a Paper because it's a surface, and has the background name `Background Surface app`. The box-shadow is a side effect of elevation, the higher the elevation, the more shadow. Elevation is a default property of Paper, and since the elevations are also defined in the theme we can use those.
 
-During development, we may end up with packages that have been installed but are not actually being used. In order to remove them, run `npm prune`.
+#### Top bar
 
-#### Adding a new dependency
+If you look at the header and forget the left group, you can see it's a header that is used on multiple places like Sigmet dialog header, LayerManager and MultiDimensionSelect but in different sizes. It makes sense to create a reusable component in the `shared` library with a property size to ensure all sizes work correctly.
 
-Adding a new dependency can be done following these steps:
+> link to design: https://app.zeplin.io/project/5ecf84a3c6ae1047a368f393/screen/60f9319044360a123ca42552
 
-1. `npm install <package-name>` or `npm install <package-name> --save-dev`
-2. commit the updated files package.json and package-lock.json
+#### Table
 
-Make sure to add the package as a dev depencency when it's only used for development purposes (like storybook or linting).
+The elements of the layermanager are build on top of the table design. In this case, it would make sense to create a new Table\* story in the `theme` library. There we make a story where we are using the MUI Table components, and make sure it has all the correct colors and styling. When that is working correctly, we can use the Table component everywhere and it will look the same everywhere.
 
-#### Updating an existing dependency
+Every row renders columns with different inputs; for example for the layers list we can use the MUI `MenuItem` component. It would make sense to create a separate story for `MenuItem`, and make sure all base colors are correct.
 
-To see a list of which packages could need updating, run `npm outdated -l`.
-A red package name means there’s a newer version matching the semver requirements in the package.json, so it can be updated. Yellow indicates that there’s a newer version higher than the semver requirements in the package.json (usually a new major version), so proceed with caution.
+By wrapping them all together, there's probably some additional styling needed specific for the LayerManager but that's perfectly fine (it can be done in for example the `Wrapper` described above). The goal is that the `MenuItem` and `Table` will have a good default look to use in other places as well.
 
-To update a single package to its latest version that matches the version required in package.json (red in the list), run `npm update <package-name>`, and commit the updated package-lock.json file.
+> link to design: https://app.zeplin.io/project/5ecf84a3c6ae1047a368f393/screen/6093e69005029c358090bd4e
 
-To update all packages at once (that are red in the list), run `npm update`, and commit the updated package-lock.json file.
+> **\*note** it's a assumption the Table component will work for the LayerManager. Currently there's a small story demo that shows's the styling so far, but not with for example max-height functionality. This is possible with adding `position:sticky` to the `th` elements, but needs further investigation if this component can fully suit our needs.
 
-To update a single package to a version higher than the required version in package.json (yellow in the list):
+#### Footer
 
-1. check if there are any breaking changes to be aware of in the new version
-2. `npm install <package-name>@<version>` or `npm install <package-name>@<version> --save-dev`
-3. commit the updated files package.json and package-lock.json
-4. update the code related to breaking changes
+This footer is only used for when the wrapper is resizable. Therefore it would make sense to make it part of a Resizable component. It can use the default values from the theme by using `useTheme` hook.
 
-After any version change, make sure to test if everything still works.
+## Do's and dont's
 
-#### Checking for vulnerabilities
+### Do's
 
-To scan the project for any known vulnerabilities in existing dependencies, you can run `npm audit`. To fix them:
+- do follow design names, if you feel the name has too much repeat in it or can be changed, ask [Didier](https://gitlab.com/didier.dezanet)! Same for missing colors .
+- do add links to design in code
+- do create shared components that are used in knmi-geoweb and reference application in the `shared` lib
+- do add a ThemeProvider for components with a new theme styling. Otherwise unit tests will break
+- do discuss the library and the usage of it. If you think it can be approved please let us know!
 
-1. `npm audit fix`
-2. commit the updated package-lock.json
-3. test if everything still works
+### Don'ts
 
-### Tests
+- don't add double colors (see TimeSlider example). In dark theme designs, color names suffixed with a (D) are color names defined in the main Color page.
+- don't override the theme for MUI components when they are specific for a design. For example the buttons in the Timeslider don't follow the exact rules of the main Buttons, so it's a good idea to make a custom TimeSliderButton component which uses the colors defined in the theme palette.
 
-Tests can be run by the following command: `npm test`. This will run all the tests specified in the stories without starting a browser.
-In order to see a coverage report, run: `npm run test:coverage`
+## Known issues
 
-#### Testing the package in another project
+- **React.Strictmode** does not work well with dynamic changing of themes. For now we have disabled it, but it should be activated again after the update to MUI 5. https://gitlab.com/opengeoweb/opengeoweb/-/issues/965
+- **Expect unit tests to fail** when using components with the theme. This is easily fixed by wrapping your test with the `ThemeProvider` from the `theme` lib. Don't import the ThemeProvider wrapper in the failed test, but use the `CoreThemeProvider` or `CoreThemeStoreProvider` found in [`libs/core/src/lib/components/Providers/Providers.tsx`](https://gitlab.com/opengeoweb/opengeoweb/-/blob/master/libs/core/src/lib/components/Providers/Providers.tsx#L36)
+- There are some **storybook bugs** with stories with Themes. When switching stories with new and old theme, it could be possible that some colors are rendered wrong. This is probably happening because one of the stories with old theme has `React.Strictmode` activated. This is only happening in storybook, and when refreshing page the colors should be correct. This will fix itself when we have `gwTheme` removed.
+- **MUI 5** makes it easy to add custom variants to components, so we should wait for that release before investing more heavy in theme stories: https://next.material-ui.com/customization/theme-components/#adding-new-component-variants . Check the progress of the release of [v5 here](https://github.com/mui-org/material-ui/milestone/44)
+- The `ThemeProvider` imports the **CssBaseline** components which allows us to set a body background and also resets some initial browser styling values. One thing it's resetting is the css **box-sizing** property. If you experience misaligning in (canvas) components, this might be the property you want to check out.
 
-To test the package in another project without publishing it, you can follow these steps:
-In geoweb-theme:
+## Roadmap
 
-1. `npm run package`
+Theming will be never be finished as it is an ongoing progress. The goal is to have the `gwTheme` removed, and only use `lightTheme` and `darkTheme` throughout all libs and apps. The following points need to be done to reach that:
+
+Other libs where `ThemeProvider` from `theme` should be used and `gwTheme` should be replaced:
+
+- [ ] airmet/sigmet (**TICKET TO BE CREATED**)
+- [ ] spaceweather (**TICKET TO BE CREATED**)
+- [ ] taf (**TICKET TO BE CREATED**)
+- [ ] form-fields (**TICKET TO BE CREATED**)
+- [ ] shared (**TICKET TO BE CREATED**)
+
+Another point of the roadmap is upgrade to MUI5. This is complete when all `@material-ui` references have been removed from the code
+
+- [ ] Investigate impact of upgrade to MUI5 https://gitlab.com/opengeoweb/opengeoweb/-/issues/1355
+
+## Unit testing
+
+```
+nx test theme
+```
 
-In yourproject:
+## Image snapshot testing
 
-1. `cd <path/to/yourproject>`
-2. `npm install <absolute path/to/tar/created/by/npm pack>`
+The current regex filters on storykind `snapshots/`. So that means all stories inside the snapshots folder in storybook will be included. To add a new snapshot test, add a story inside the folder `libs/theme/src/lib/stories/snapshots`, and make sure in storybook itself it's also shown under snapshots.
 
-#### Bundling, packaging and publishing to NPM
+[Read more about snapshot testing](https://gitlab.com/opengeoweb/opengeoweb/#image-snapshot-testing)
 
-We use Semantic Versioning, see the [documentation](https://semver.org) for details.
+### Running snapshot tests and updating snapshots locally
 
-1. Decide how to bump the version, is it a major, minor or patch version?
-2. Create a new branch based off master and ensure there is an upstream branch BEFORE going to the next step
-3. Update the version by running `npm version major|minor|patch` on the new branch
-4. Merge the branch into master
-5. Go to the gitlab pipeline of master and run the publish stage
-6. Check for the new version on [npm](https://www.npmjs.com/package/@opengeoweb/theme) and [gitlab](https://gitlab.com/opengeoweb/geoweb-theme/-/tags)
+1. You need to have [docker](https://docs.docker.com/get-docker/) installed and running.
+2. Start Chromium by running: `npm run start-chromium`. (This will start a docker container with chromium, to run snapshot tests in. We need this to make sure everyone gets the same snapshot results.)
+3. Run the snapshot tests: `npm run test:image-snap-theme`. This will first create a new static storybook build and then run the tests.
+4. If a snapshot test fails, you can find and inspect the differences in `libs/theme/src/lib/storyshots/__image_snapshots__/__diff_output__/`.
+5. To update the snapshots, run `npm run test:image-snap-theme-update`. Snapshots are saved under `libs/theme/src/lib/storyshots/__image_snapshots__/`. Make sure to commit the new snapshots.
+6. Stop Chromium by running: `npm run stop-chromium`.
 
-### License
+## Questions and feedback
 
-This project is licensed under the terms of the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) license.
+Everything written here and coded is open for feedback. If you have any code related questions, please contact the GeoWeb team, if you have any questions about the design, naming and or guidelines please contact the designer [Didier](https://gitlab.com/didier.dezanet)
 
-Every file in this project has an header that specifies the licence and copyright. It is possible to add/remove the licence header using the following commands:
+## Documentation
 
-- `npm run licence:add` => it adds to all possible files the licence header if the file has not an header with the same content of the LICENCE file. This action can require a manual check in the case in which the file contains a wrong header (i.g. a simple word is missed), because it just adds another header without removing the wrong one.
+https://opengeoweb.gitlab.io/opengeoweb/docs/theme/
 
-- `npm run licence:remove` => it removes the specific header from all files that contain an header with the same content of the LICENCE file. This action can require a manual check in the case in which the file contains a wrong header (i.g. a simple word is missed), because it just removes the correct header and not the wrong one.
+> Written with [StackEdit](https://stackedit.io/).

package/index.d.ts

@@ -1 +1 @@
-export { GWTheme } from './theme';
+export * from './lib/components/Theme';

package/lib/components/Theme/ThemeContext.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+import { Theme as MUITheme } from '@material-ui/core';
+interface ThemeContextProps {
+    toggleTheme?: () => void;
+    isDark?: boolean;
+}
+export declare const ThemeContext: React.Context<Partial<ThemeContextProps>>;
+interface ThemeProviderProps {
+    children: React.ReactNode;
+    theme?: MUITheme;
+    disableCssBaseline?: boolean;
+}
+export declare const ThemeProvider: React.FC<ThemeProviderProps>;
+export declare const useThemeContext: () => Partial<ThemeContextProps>;
+export declare const ThemeWrapper: React.FC<ThemeProviderProps>;
+export declare const ThemeWrapperOldTheme: React.FC<ThemeProviderProps>;
+export {};

package/{theme.test.d.ts → lib/components/Theme/ThemeContext.spec.d.ts}

@@ -1 +1 @@
-export {};
+export {};

package/lib/components/Theme/darkTheme.d.ts

@@ -0,0 +1,3 @@
+import { GeowebColorPalette } from './types';
+export declare const colors: GeowebColorPalette;
+export declare const darkTheme: import("@material-ui/core").Theme;

package/{theme.d.ts → lib/components/Theme/gwTheme.d.ts}

@@ -1,7 +1,7 @@
-import { AlertClassKey } from '@material-ui/lab/Alert';
-declare module '@material-ui/core/styles/overrides' {
-    interface ComponentNameToClassKey {
-        MuiAlert: AlertClassKey;
-    }
-}
-export declare const GWTheme: import("@material-ui/core").Theme;
+import { AlertClassKey } from '@material-ui/lab/Alert';
+declare module '@material-ui/core/styles/overrides' {
+    interface ComponentNameToClassKey {
+        MuiAlert: AlertClassKey;
+    }
+}
+export declare const GWTheme: import("@material-ui/core").Theme;

package/lib/components/Theme/index.d.ts

@@ -0,0 +1,5 @@
+export { GWTheme } from './gwTheme';
+export * from './ThemeContext';
+export { lightTheme } from './lightTheme';
+export { darkTheme } from './darkTheme';
+export * from './types';

package/lib/components/Theme/lightTheme.d.ts

@@ -0,0 +1,3 @@
+import { GeowebColorPalette } from './types';
+export declare const colors: GeowebColorPalette;
+export declare const lightTheme: import("@material-ui/core").Theme;