docs: updated usage & performance guide

Author: DaniAkash

README.md

@@ -43,10 +43,6 @@ Convert hooks into shared states between react components
   - [Dark Mode][expo-app] with React Native on expo. Project in [`example/`](https://github.com/react-native-toolkit/rex-state/tree/master/example) directory
 - ✨ [Why Rex State?](#why-rex-state)
 
-## Motivation
-
-Rex State was initially built as a state management library. But after using it in many projects, its main purpose became creating hooks where the data returned by the hook can be shared across multiple react components.
-
 ## Requirements
 
 Rex State is built purely on React Hooks hence it requires React > 16.8 to work.
@@ -63,35 +59,51 @@ npm i rex-state
 
 ## Usage
 
-```jsx
-import { createRexStore } from 'rex-state';
+Consider the following hook which lets you toggle theme between light & dark modes
 
-// A simple hook to toggle theme modes between 'light' & 'dark'
-const useThemeHook = (initialTheme = 'light') => {
+```jsx
+const useThemeMode = (initialTheme = 'light') => {
   const [theme, setTheme] = useState(initialTheme);
 
   const toggleTheme = () => setTheme(theme === 'light' ? 'dark' : 'light');
 
   return [theme, toggleTheme];
 };
+```
+
+You can use the `createRexStore` module from rex state to create a provider & a store hook to access the result of your `useThemeMode`
+
+```jsx
+import { createRexStore } from 'rex-state';
 
-// using `createRexStore` to create a Provider & a Hook with shared state
 const { useStore: useTheme, RexProvider: ThemeProvider } = createRexStore(
-  useThemeHook
+  useThemeMode
 );
+```
+
+The `useStore` hook & `RexProvider` are renamed to `useTheme` & `ThemeProvider` for use in the application.
+
+Now you can wrap your entire Application inside the `ThemeProvider` to ensure the context is setup properly for the `useTheme` hook.
 
-// Use the `ThemeProvider` at the top level of your React component tree
+```jsx
 const App = () => {
-  // `initialTheme` value can be supplied using the value prop of `ThemeProvider`
   return (
     <ThemeProvider value="dark">
       {/* Rest of your application */}
       <ToggleButton />
+      <ThemeText />
     </ThemeProvider>
   );
 };
+```
+
+> Note: The value of the argument of `useThemeMode` function - `initialTheme` is supplied to the `ThemeProvider` using the `value` prop. The `value` prop only supports a single argument. Hence if your hook requires multiple arguments, you can pass them as a single object
 
-// All components can now access the `useTheme` hook
+Once you add the `ThemeProvider` to the top of your application's tree, the child components can now use the `useTheme` hook to access the result of your `useThemeMode` hook. This time, when you call `toggleTheme` in any of the child components, it will cause your entire application tree to re-render & all the components that use the `useTheme` hook will have the updated value!
+
+The following is a toggle button that toggles the theme when users click on it.
+
+```jsx
 const ToggleButton = () => {
   const [theme, toggleTheme] = useTheme();
 
@@ -102,9 +114,11 @@ const ToggleButton = () => {
     </View>
   );
 };
+```
+
+The next component is a text block that simply displays the theme's mode
 
-// Calling `toggleTheme` in above component will cause updates
-// in all the components in the Application tree using the context API
+```jsx
 const ThemeText = () => {
   const [theme] = useTheme();
 
@@ -117,11 +131,15 @@ const ThemeText = () => {
 };
 ```
 
+Invoking the `toggleTheme` function from the `<ToggleButton/>` component updates the `<ThemeText/>` component. This means your hook is now a shared state between the two components!
+
+Also, check out the [counter example](https://codesandbox.io/s/rex-counter-2m4zy?file=/src/App.js) from codesandbox
+
+Rex State is good for some use cases and not suitable for some use cases since it uses the [React Context](https://reactjs.org/docs/context.html#api) API which is considered inefficient as a change causes the entire React child tree to re-render. Read the [performance](https://rex-state.netlify.app/?path=/story/intro-performance--page) section to see how to use Rex State effectively.
+
 ## Why Rex State?
 
-- It's Tiny!
-- Simple & un-opinionated
-- Makes hooks much more powerful
+Rex State is a handy utility to make your hooks more powerful. It is simple, un-opinionated & is very tiny!
 
 ## Licenses
 

example/src/stories/API.stories.mdx

@@ -5,10 +5,10 @@ import { Meta } from '@storybook/addon-docs/blocks';
 ## `createRexStore`
 
 ```tsx
-createRexStore: <T, V>(useRexState: (value?: V) => T) => {
+createRexStore: <T, V>(useRexState: (value?: V) => T) => ({
   RexProvider: (props: { children: ReactNode; value?: V }) => JSX.Element;
   useStore: () => T;
-};
+});
 ```
 
 `createRexStore` accepts your hook as the argument and returns an object with two properties ﹣

example/src/stories/GettingStarted.stories.mdx

@@ -36,35 +36,53 @@ Convert hooks into shared states between react components
 
 Rex State allows you to convert the result of your hooks into a shared state between multiple react components using the Context API.
 
-```jsx
-import { createRexStore } from 'rex-state';
+## Usage
 
-// A simple hook to toggle theme modes between 'light' & 'dark'
-const useThemeHook = (initialTheme = 'light') => {
+Consider the following hook which lets you toggle theme between light & dark modes
+
+```jsx
+const useThemeMode = (initialTheme = 'light') => {
   const [theme, setTheme] = useState(initialTheme);
 
   const toggleTheme = () => setTheme(theme === 'light' ? 'dark' : 'light');
 
   return [theme, toggleTheme];
 };
+```
+
+You can use the `createRexStore` module from rex state to create a provider & a store hook to access the result of your `useThemeMode`
+
+```jsx
+import { createRexStore } from 'rex-state';
 
-// using `createRexStore` to create a Provider & a Hook with shared state
 const { useStore: useTheme, RexProvider: ThemeProvider } = createRexStore(
-  useThemeHook
+  useThemeMode
 );
+```
+
+The `useStore` hook & `RexProvider` are renamed to `useTheme` & `ThemeProvider` for use in the application.
+
+Now you can wrap your entire Application inside the `ThemeProvider` to ensure the context is setup properly for the `useTheme` hook.
 
-// Use the `ThemeProvider` at the top level of your React component tree
+```jsx
 const App = () => {
-  // `initialTheme` value can be supplied using the value prop of `ThemeProvider`
   return (
     <ThemeProvider value="dark">
       {/* Rest of your application */}
       <ToggleButton />
+      <ThemeText />
     </ThemeProvider>
   );
 };
+```
+
+> Note: The value of the argument of `useThemeMode` function - `initialTheme` is supplied to the `ThemeProvider` using the `value` prop. The `value` prop only supports a single argument. Hence if your hook requires multiple arguments, you can pass them as a single object
 
-// All components can now access the `useTheme` hook
+Once you add the `ThemeProvider` to the top of your application's tree, the child components can now use the `useTheme` hook to access the result of your `useThemeMode` hook. This time, when you call `toggleTheme` in any of the child components, it will cause your entire application tree to re-render & all the components that use the `useTheme` hook will have the updated value!
+
+The following is a toggle button that toggles the theme when users click on it.
+
+```jsx
 const ToggleButton = () => {
   const [theme, toggleTheme] = useTheme();
 
@@ -75,9 +93,11 @@ const ToggleButton = () => {
     </View>
   );
 };
+```
 
-// Calling `toggleTheme` in above component will cause updates
-// in all the components in the Application tree using the context API
+The next component is a text block that simply displays the theme's mode
+
+```jsx
 const ThemeText = () => {
   const [theme] = useTheme();
 
@@ -90,13 +110,25 @@ const ThemeText = () => {
 };
 ```
 
-## Working Example
+## In Action
+
+<br />
 
 <DarkModeProvider value="dark">
   <ToggleButton />
   <ThemeText />
 </DarkModeProvider>
 
+<br />
+<br />
+<br />
+
+As you can see, calling the `toggleTheme` function from the `<ToggleButton/>` component updates the `<ThemeText/>` component. This means your hook is now a shared state between the two components!
+
+Also, check out the [counter example](https://codesandbox.io/s/rex-counter-2m4zy?file=/src/App.js) from codesandbox
+
+Rex State is good for some use cases and not suitable for some use cases since it uses the [React Context](https://reactjs.org/docs/context.html#api) API which is considered inefficient as a change causes the entire React child tree to re-render. Read the performance section to see how to use Rex State effectively.
+
 [coffee-badge]: https://img.shields.io/badge/-%E2%98%95%EF%B8%8F%20buy%20me%20a%20coffee-e85b46
 [coffee-url]: https://www.buymeacoffee.com/daniakash
 [sponsor-badge]: https://img.shields.io/badge/-%F0%9F%8F%85%20sponsor%20this%20project-e85b46

example/src/stories/Performance.stories.mdx

@@ -6,6 +6,16 @@ import { Meta } from '@storybook/addon-docs/blocks';
 
 Rex State makes the values returned by Hooks shareable using the React Context API. But there are knows performance limitations since changing the value of Context causes the entire Application tree to re-render.
 
-Rex State used to have an [`InjectStore`](https://github.com/daniakash/rex-state/tree/9809c7a7a6f71c1644a7d94a058b5606cf49da11#performance) HOC which implemented the solutions suggested by [Dan Abramov](https://github.com/facebook/react/issues/15156#issuecomment-474590693). This HOC is removed in v1.0 as the goal of Rex State is no longer to be a state management tool, but, to be an utility to share hooks across components.
+## When not to use Rex State
 
-You can directly implement the performance optimizations suggested in the above comment if you need. If you are looking for a powerful state management tool that can efficiently avoid unnecessary re-renders, you can try [recoil](https://recoiljs.org/) or [zustand](https://github.com/react-spring/zustand).
+Rex State is not a state management library. It is a utility to quickly share a hook between two components. Hence if you are working with data that changes often and is shared by a large number of components, it is a good idea to avoid rex state.
+
+Rex State used to have an [`InjectStore`](https://github.com/daniakash/rex-state/tree/9809c7a7a6f71c1644a7d94a058b5606cf49da11#performance) HOC which implemented the solutions suggested by [Dan Abramov](https://github.com/facebook/react/issues/15156#issuecomment-474590693). This HOC is removed in v1.0 as the goal of Rex State is no longer to be a state management tool. You can directly implement the performance optimizations suggested in [the comment](https://github.com/facebook/react/issues/15156#issuecomment-474590693) if you need.
+
+If you are looking for a powerful state management tool that can efficiently avoid unnecessary re-renders, you can try [recoil](https://recoiljs.org/) or [zustand](https://github.com/react-spring/zustand).
+
+## When you can use Rex State
+
+Rex State is good for data that doesn't change often. For example, managing color schemes of dark mode & light mode throughout your application is a good use case. As the theme modes do not change often. Also, changing the mode usually requires all the components to re-render.
+
+If you have data that changes often but you want to share the data of your hook with a limited number of components alone, then instead of wrapping your entire application inside the `RexProvider`, you can only wrap the nearest common parent of the required components inside the `RexProvider`. This ensures the re-renders are limited only to that parent and the rest of your application is not disturbed.