@kwantis-id3/frontend-library 0.14.1 → 0.14.2

package/README.md

@@ -26,6 +26,7 @@ pnpm add @kwantis-id3/frontend-library
 
 Note that the library uses @emotion/styled and @emotion/react as dev dependencies. Installing them in your project may cause conflicts.
 The library however offers its own styled utility, that can be used to create styled components.
+<br><br>
 
 ## Usage
 The library has various components, each one with its own documentation. Please refer to the storybook documentation for more information.
@@ -51,7 +52,7 @@ The following are under development or on our roadmap:
 
 
 You can find various examples of usage in the projects stories.
-
+<br><br>
 ## Theming
 The library internally uses the [emotion](https://emotion.sh/docs/introduction) library for styling. By default, the library uses a default theme, that looks like this:
 
@@ -103,6 +104,115 @@ declare module "@kwantis-id3/frontend-library" {
 }
 ```
 
+### Fetching the theme from an API
+In case you fetch the theme from an API, there are a couple of things you need to do to avoid complications.
+
+#### 1. Handling non-native theme keys
+The library uses the `ThemeColorsObject` interface to define the theme colors. This interface is used to define the default theme, and to extend it with custom properties, as discussed in the previous section.
+
+If you fetch the theme from an API, it is **strongly** advised to use a default theme containing the additional keys, and then override it with the fetched one.
+
+Otherwise, the additional keys in the theme may be `undefined`, and accessing them before the theme has finished fetching will cause an error.
+
+Here's an example on how to do it, using react query, assuming that the theme has been extended with a `newColor` property:
+
+```ts
+import { ThemeContextProvider, ThemeContextProps } from "@kwantis-id3/frontend-library";
+import { useQuery } from "react-query";
+
+const App = () => {
+  const defaultTheme: ThemeContextProps = {
+    colors: {
+      primary: { main: "#cccccc", contrastText: "#cccccc" },
+      secondary: { main: "#cccccc", contrastText: "#cccccc" },
+      tertiary: { main: "#cccccc", contrastText: "#cccccc" },
+      statusOk: { main: "#cccccc", contrastText: "#cccccc" },
+      statusWarning: { main: "#cccccc", contrastText: "#cccccc" },
+      statusCritical: { main: "#cccccc", contrastText: "#cccccc" },
+      statusNeutral: { main: "#cccccc", contrastText: "#cccccc" },
+      newColor: { main: "#cccccc", contrastText: "#cccccc" },
+    }
+  }
+
+  const fetchedTheme = useQuery({
+    queryKey: ["theme"],
+    queryFn: getColors,
+    initialData: defaultTheme,
+  });
+
+  return (
+    <ThemeContextProvider theme={fetchedTheme.data}>
+      {...}
+    </ThemeContextProvider>
+  )
+}
+```
+
+#### 2. Avoiding FOUC
+If you fetch the theme from an API, you may experience a FOUC (Flash Of Unstyled Content) when the theme is being fetched.
+
+This is because the default theme (either being the one native to the library, or a custom one like in the previous section) is applied before the fetched one is ready, and the two may have some differences (especially if your application needs to be deployed on various instances with different themes).
+
+To avoid this, you have 3 possible solutions:
+1. Do not render the application until the theme is ready
+2. Store the theme in the local storage, and use it as the default theme. Please note that this approach will still show the FOUC in the following cases:
+    - The user has never visited the application before
+    - The user has cleared the local storage / is using a different browser or device
+    - The user has visited the application before, but the theme has changed since then
+3. Use the `initialData` property of the `useQuery` hook to pass a default theme, since useQuery automatically caches the queries data. This approach will still show the FOUC in the following cases:
+    - The user has never visited the application before
+    - The user has cleared the local storage / is using a different browser or device
+    - The user has visited the application before, but the theme has changed since then
+
+For case 3, the code remains unchanged from the previous section, so here's an example without react query for case 2:
+
+```ts
+import { ThemeContextProvider, ThemeContextProps } from "@kwantis-id3/frontend-library";
+import React, { useEffect, useState } from "react";
+import axios from "axios";
+
+const App = () => {
+  const defaultTheme: ThemeContextProps = {
+    colors: {
+      primary: { main: "#cccccc", contrastText: "#cccccc" },
+      secondary: { main: "#cccccc", contrastText: "#cccccc" },
+      tertiary: { main: "#cccccc", contrastText: "#cccccc" },
+      statusOk: { main: "#cccccc", contrastText: "#cccccc" },
+      statusWarning: { main: "#cccccc", contrastText: "#cccccc" },
+      statusCritical: { main: "#cccccc", contrastText: "#cccccc" },
+      statusNeutral: { main: "#cccccc", contrastText: "#cccccc" },
+      newColor: { main: "#cccccc", contrastText: "#cccccc" },
+    }
+  }
+
+  const [theme, setTheme] = React.useState(() => { //initialize state with default or localstorage value
+    const localTheme = localStorage.getItem("myStoredTheme");
+    if (localTheme) {
+      return JSON.parse(localTheme) as ThemeContextProps;
+    }
+    return defaultTheme;
+  });
+
+  useEffect(() => {
+    axios.get<ThemeContextProps>("theme")
+    .then((response) => {
+      setTheme(response.data);
+      localStorage.setItem("myStoredTheme", JSON.stringify(response.data));
+    })
+    .catch ((error) => {
+      console.log(error);
+    })
+  }, []);
+
+  return (
+    <ThemeContextProvider theme={theme}>
+      {...}
+    </ThemeContextProvider>
+  )
+}
+
+```
+
 ## The useThemeContext hook
 The library exports a `useThemeContext` hook, that can be used to access the theme object from any component,
 exposing a `ThemeProperties` object.