docs: Large update to documentation, added illustrations, refactoring content

Author: imp-dance

docs/docs/Advanced/index.mdx

@@ -0,0 +1 @@
+{}

docs/docs/Advanced/under-the-hood.md

@@ -7,7 +7,7 @@ sidebar_position: 4
 You can use RTK Query Loader with most other similar query-fetching libraries. This is possible through the use of _resolvers_.
 
 :::note
-Although `rtk-query-loader` was build with `@reduxjs/toolkit` in mind, the underlying principles can be applied to any similar data loading solution. [Read more about how RTK Query Loader works under the hood](../Advanced/under-the-hood.md).
+Although `rtk-query-loader` was build with `@reduxjs/toolkit` in mind, the underlying principles can be applied to any similar data loading solution.
 :::
 
 ## Tanstack Query

docs/docs/Features/_category_.json

@@ -0,0 +1,3 @@
+{
+  "collapsed": false
+}

docs/docs/Features/other-libs.md

@@ -0,0 +1,92 @@
+---
+sidebar_position: 4
+---
+
+# 4. Arguments for your loader
+
+If you want the loader to take an argument, all you have to do is to add a `queriesArg`:
+
+```tsx {5-7,10-12}
+import { ConsumerProps } from "@ryfylke-react/rtk-query-loader";
+
+// This means that any component that has props that extend this
+// type can consume the loader using `withLoader`
+type UserRouteLoaderProps = ConsumerProps<{
+  userId: string;
+}>;
+
+export const userRouteLoader = baseLoader.extend({
+  queriesArg: (props: UserRouteLoaderProps) => props.userId,
+  // type is now inferred from queriesArg return
+  useQueries: (userId) => {
+    const user = useGetUserQuery(userId);
+    const posts = useGetPostsByUser(userId);
+
+    return {
+      queries: {
+        user,
+        posts,
+      },
+    };
+  },
+});
+```
+
+## Data flow
+
+The transformation layer between the useQueries hook and the loader is the `queriesArg` function. It takes the component's props and returns the argument that should be passed to the useQueries hook. This is nessecary to be able to consume the loader in a type-safe way.
+
+<img
+  src={require("./queriesArg.png").default}
+  alt="queriesArg"
+  style={{ maxWidth: "100%" }}
+/>
+
+## When using `<AwaitLoader />`
+
+You should pass the expected _props_ to the `arg` prop when using `<AwaitLoader />`.
+
+```tsx
+<AwaitLoader
+    loader={loader}
+    render={(data) => (...)}
+    args={{
+        userId: "1234",
+    }}
+/>
+```
+
+## Properly typing the `queriesArg` function
+
+You can use the `ConsumerProps<T>` utility type to type the `queriesArg` function.
+
+```tsx
+import {
+  ConsumerProps,
+  createLoader,
+} from "@ryfylke-react/rtk-query-loader";
+
+type UserRouteLoaderProps = ConsumerProps<{
+  userId: string;
+}>;
+
+const loader = createLoader({
+  queriesArg: (props: UserRouteLoaderProps) => props.userId,
+  // ...
+});
+```
+
+The type utility will ensure that the type can be extended by the consumer components. This means that the following types are both valid for the definition above:
+
+```ts
+// This is valid ✅
+type Props_1 = {
+  userId: string;
+};
+
+// This is also valid ✅
+type Props_2 = {
+  userId: string;
+  someOtherProp: string;
+};
+```

docs/docs/Quick Guide/_category_.json

@@ -7,7 +7,24 @@ import TabItem from "@theme/TabItem";
 
 # 5. Consume the loader
 
-You can consume a loader using one of the following methods:
+## Picking the right method
+
+We recommend consuming the loader with either `withLoader` or `AwaitLoader`.
+
+- Use `withLoader` if you want to use the loader to affect the whole component.
+- Use `AwaitLoader` if you want to use the loader in a more conditional way, or if you only want a small section of your component to start loading data, after the rest of the component has rendered.
+
+You could also use `useLoader`, which is the hook that `withLoader` and `AwaitLoader` use under the hood. This will simply return the aggregated queries of the loader, and is useful if you want to use the data, but **not the loading and error states of the loader**.
+
+<img
+  src={require("./rtk-query-loader-chart.png").default}
+  alt="Chart showing differences between AwaitLoader and withLoader"
+  style={{ maxWidth: 500 }}
+/>
+
+## Examples
+
+Select a tab below to see an example of how you would consume the loader using that specific method.
 
 <Tabs groupId="method" queryString>
   <Tab label="withLoader" value="withLoader" default>
@@ -62,6 +79,8 @@ export const UserRoute = withLoader((props: Props, loader) => {
 
   <Tab label="<AwaitLoader>" value="load">
 
+> **New in version 1.0.4**
+
 If you prefer not using higher order components, or want to use the loader in a more conditional way, you can use the &lt;`AwaitLoader` /&gt; component.
 
 ```tsx {6-18}

docs/docs/Quick Guide/accept-arguments.md

@@ -23,3 +23,12 @@ Its up to you how much you want to separate logic here. Some examples would be..
 
 I personally prefer to keep the loaders close to the component, either in a file besides it or directly in the file itself, and then keep a base loader somewhere else to extend from.
 :::
+
+## Loader hierarchy
+
+You can extend from any loader, including loaders that have already been extended. This allows you to create a hierarchy of loaders that can be used to share logic between components.
+
+<img
+  src={require("./extend-loader.png").default}
+  alt="Loader hierarchy illustration"
+/>