docs: updated docs

Author: imp-dance

docs/docs/Advanced/index.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 6
+---
+
+# Advanced
+
+Read more about how `rtk-query-loader` actually works.

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

@@ -0,0 +1,78 @@
+# Under the hood
+
+How does `rtk-query-loader` work _under the hood_?
+
+## Virtual DOM
+
+Imagine you have this component, rendered through `withLoader`:
+
+```tsx
+const loader = createLoader({...});
+
+const Component = withLoader((props, queries) => {...}, loader);
+
+const App = () => {
+    return (
+        <div>
+            <Component />
+        </div>
+    )
+}
+```
+
+What actually ends up rendering in the virtual DOM is something like this:
+
+```txt title="onLoading"
+div
+└── RTKLoader
+    └── loader.onLoading(props)
+```
+
+```txt title="onError"
+div
+└── RTKLoader
+    └── loader.onError(props, error)
+```
+
+```txt title="onFetching"
+div
+└── RTKLoader
+    └── loader.onFetching(props, Component)
+```
+
+```txt title="onSuccess"
+div
+└── RTKLoader
+    └── null
+    └── Component (with data)
+    └── null
+```
+
+```txt title="whileFetching"
+div
+└── RTKLoader
+    └── loader.whileFetching.prepend()
+    └── Component (with data)
+    └── loader.whileFetching.append()
+```
+
+## RTKLoader
+
+`RTKLoader` simply receives the loader and component, and handles returning the correct state depending on the query. You can take a look at how this component behaves [in the codebase](https://github.com/ryfylke-react-as/rtk-query-loader/blob/main/src/RTKLoader.tsx).
+
+## Custom `loaderComponent`
+
+You could pass a custom `loaderComponent` to your loaders, if you'd like:
+
+```typescript
+const CustomLoader = (props: CustomLoaderProps) => {
+  // Handle rendering
+};
+
+const loader = createLoader({
+  loaderComponent: CustomLoader,
+  // ...
+});
+```
+
+This allows you to have really fine control over how the rendering of components using `withLoader` should work.

docs/docs/Exports/create-loader.md

@@ -6,7 +6,38 @@ sidebar_position: 1
 
 Creates a `Loader`.
 
-Takes the following argument:
+```typescript title="example.ts"
+type ConsumerProps = Record<string, any> & {
+  userId: string;
+};
+
+const loader = createLoader({
+  queriesArg: (props: ConsumerProps) => props.userId,
+  queries: (userId) => {
+    return [useGetUser(userId)] as const;
+  },
+  deferredQueries: (userId) => {
+    return [useGetUserRelations(userId)] as const;
+  },
+  transform: (queries, deferredQueries) => ({
+    queries: [...queries, ...deferredQueries],
+    foo: "bar",
+  }),
+  onLoading: (props) => <div>Loading...</div>,
+  onError: (props, error) => <div>Error!</div>,
+  whileFetching: {
+    prepend: (props) => <LoadingSpinner />,
+  },
+});
+```
+
+A `Loader` takes ownership over...
+
+- Data-loading
+- Data-transformation
+- Fetch-state rendering
+
+Here is the `createLoader` argument:
 
 ````typescript
 type CreateLoaderArgs<

docs/docs/Exports/index.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Exports

docs/docs/Exports/use-create-query.md

@@ -26,3 +26,8 @@ const loader = createLoader({
   },
 });
 ```
+
+> You lose some great features from RTK query when using `useCreateQuery`.
+> If possible, try to stick to using actual queries, created from a `@reduxjs/toolkit` API.
+> You can look at this feature like an escape-hatch that allows you to pass other
+> data through the loader as well.

docs/docs/Features/extending.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 1
+---
+
+# Extend
+
+You can **extend** existing `Loader`s. This lets you inherit and overwrite properties from an existing `Loader`.
+
+```tsx
+const parentLoader = createLoader({
+    onLoading: () => <div>Loading...</div>
+});
+
+const childLoader = parentLoader.extend({
+    queries: () => [...] as const,
+})
+```
+
+It's worth mentioning that queries and transform are linked in this context, meaning that if you supply a new queries argument in the extended loader, but no transform, then you will not inherit the transform from the original loader.
+
+- Supplying just a new `queries` argument will result in transform being undefined in practise.
+- Supplying just a new `transform` argument will result in the new transform being ignored.
+- Supplying a new `transform` and a new `queries` argument will properly overwrite the existing base properties.
+
+All other properties in the loader will overwrite as expected. You can, for example, just supply a new `onLoading`, or `onError`.
+
+> You may extend _extended_ loaders, to create an inheritance model.

docs/docs/Features/index.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 4
+---
+
+# Features
+
+Read more about various `rtk-query-loader` features.

docs/docs/Features/transforming.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 2
+---
+
+# Transform
+
+You can transform the queries to any format you'd like.
+
+```ts
+const notTransformed = createLoader({
+  queries: () => [useGetPokemonsQuery()],
+});
+
+type NotTransformedData = InferLoaderData<typeof notTransformed>;
+// readonly [UseQueryResults<Pokemon[]>]
+
+const transformed = createLoader({
+  queries: () => [useGetPokemonsQuery()],
+  transform: (queries) => ({
+    results: queries[0].data,
+    query: queries[0],
+  }),
+});
+
+type TransformedData = InferLoaderData<typeof transformed>;
+// { results: Pokemon[]; query: UseQueryResult<Pokemon[]>; }
+```

docs/docs/Quick Guide/consume-loader.md

@@ -37,7 +37,7 @@ export const UserRoute = withLoader((props: Props, queries) => {
 
 Every `Loader` contains an actual hook that you can call to run all the queries and aggregate their statuses as if they were just one joined query.
 
-```tsx
+```tsx {3,9}
 import { userRouteLoader } from "./baseLoader";
 
 const useLoaderData = userRouteLoader.useLoader;

docs/docs/Quick Guide/extend-loader.md

@@ -12,7 +12,7 @@ import { baseLoader } from "./baseLoader";
 export const userRouteLoader = baseLoader.extend({});
 ```
 
-You can pass any argument from [`createLoader`](/Exports/create-loader) into `Loader.extend`.
+You can pass any argument from [`createLoader`](/Exports/create-loader) into [`Loader.extend`](/Features/extending).
 
 Its up to you how much you want to separate logic here. Some examples would be...