docs: updated documentation

Author: imp-dance

docs/docs/Advanced/index.md renamed to docs/docs/Advanced/index.mdx

@@ -2,6 +2,10 @@
 sidebar_position: 7
 ---
 
+import DocCardList from "@theme/DocCardList";
+
 # Advanced
 
 Read more about how `rtk-query-loader` actually works.
+
+<DocCardList />

docs/docs/Exports/aggregate-to-query.md

@@ -0,0 +1,29 @@
+---
+sidebar_position: 6
+---
+
+# aggregateToQuery
+
+Aggregated a set of `UseQueryResult` into a single query.
+
+:::caution
+`aggregateToQuery` does not add any `data` to the resulting query. You will have to do that manually afterwards.
+:::
+
+```typescript
+import {
+  aggregateToQuery,
+  UseQueryResult,
+} from "@ryfylke-react/rtk-query-loader";
+
+const queries = [
+  useQueryOne(),
+  useQueryTwo(),
+  useQueryThree(),
+] as const;
+
+const query: UseQueryResult<unknown> = {
+  ...aggregateToQuery(queries),
+  data: queries.map((query) => query.data),
+};
+```

docs/docs/Exports/consumer-props.md

@@ -0,0 +1,36 @@
+---
+sidebar_position: 5
+---
+
+# ConsumerProps
+
+Helper for typing your expected consumer props for the loader.
+
+```typescript
+type PokemonLoaderProps = ConsumerProps<{
+  name: string;
+}>;
+
+const pokemonLoader = createLoader({
+  queriesArg: (props: PokemonLoaderProps) => props.name,
+  useQueries: (name) => ({
+    queries: { pokemon: useGetPokemon(name) },
+  }),
+});
+
+// pokemonLoader can now we used by any component
+// that accepts a prop `name` of type `string`.
+
+type PokemonComponentProps = {
+  name: string;
+  size: number;
+}; // ✅
+
+type OtherPokemonComponentProps = {
+  name: string;
+}; // ✅
+
+type IncompatibleProps = {
+  pokemonName: string;
+}; // ❌
+```

docs/docs/Exports/create-loader.md

@@ -39,12 +39,6 @@ const loader = createLoader({
 });
 ```
 
-A `Loader` takes ownership over...
-
-- Data-loading
-- Data-transformation
-- Fetch-state rendering
-
 :::caution Using version `0.3.51` or earlier?
 Please refer to the [**migration guide**](../Migrations/v0.x).
 :::

docs/docs/Exports/index.md renamed to docs/docs/Exports/index.mdx

@@ -2,8 +2,12 @@
 sidebar_position: 6
 ---
 
+import DocCardList from "@theme/DocCardList";
+
 # Exports
 
 Describes the different exports and their related types.
 
 All the types can be found [here](https://github.com/ryfylke-react-as/rtk-query-loader/blob/main/src/types.ts).
+
+<DocCardList />

docs/docs/Features/custom-loader.md

@@ -4,6 +4,85 @@ sidebar_position: 5
 
 # Custom `loaderComponent`
 
+A `loaderComponent` is the component that determines what to render given the aggregated query status, when using `withLoader`.
+
+```typescript title="loaderComponent Props"
+export type CustomLoaderProps<T = unknown> = {
+  /** The joined query for the loader */
+  query: UseQueryResult<T>;
+  /** What the loader requests be rendered when data is available */
+  onSuccess: (data: T) => React.ReactElement;
+  /** What the loader requests be rendered when the query fails */
+  onError?: (
+    error: SerializedError | FetchBaseQueryError
+  ) => JSX.Element;
+  /** What the loader requests be rendered while loading data */
+  onLoading?: React.ReactElement;
+  /** What the loader requests be rendered while fetching data */
+  onFetching?: React.ReactElement;
+  /** What the loader requests be rendered while fetching data */
+  whileFetching?: {
+    /** Should be appended to the success result while fetching */
+    append?: React.ReactElement;
+    /** Should be prepended to the success result while fetching */
+    prepend?: React.ReactElement;
+  };
+};
+```
+
+This is what the default `loaderComponent` looks like:
+
+```typescript title=RTKLoader.tsx
+import { SerializedError } from "@reduxjs/toolkit";
+import * as React from "react";
+import { CustomLoaderProps } from "./types";
+
+export function RTKLoader<T>(
+  props: CustomLoaderProps<T>
+): React.ReactElement {
+  const shouldLoad =
+    props.query.isLoading || props.query.isUninitialized;
+  const hasError = props.query.isError && props.query.error;
+  const isFetching = props.query.isFetching;
+
+  if (shouldLoad) {
+    return props.onLoading ?? <React.Fragment />;
+  }
+
+  if (hasError) {
+    return (
+      props.onError?.(props.query.error as SerializedError) ?? (
+        <React.Fragment />
+      )
+    );
+  }
+
+  if (isFetching && props.onFetching) {
+    return props.onFetching;
+  }
+
+  if (props.query.data !== undefined) {
+    const prepend = isFetching
+      ? props.whileFetching?.prepend ?? null
+      : null;
+    const append = isFetching
+      ? props.whileFetching?.append ?? null
+      : null;
+    const componentWithData = props.onSuccess(props.query.data);
+
+    return (
+      <>
+        {prepend}
+        {componentWithData}
+        {append}
+      </>
+    );
+  }
+
+  return <React.Fragment />;
+}
+```
+
 You could pass a custom `loaderComponent` to your loaders, if you'd like:
 
 ```typescript

docs/docs/Features/index.md renamed to docs/docs/Features/index.mdx

@@ -2,17 +2,26 @@
 sidebar_position: 5
 ---
 
+import DocCardList from "@theme/DocCardList";
+
 # Features
 
 RTK Query Loader tries to give you all the flexibility you need to create reusable and extendable loaders.
 
-- Supply multiple queries.
+- Supply as many queries as you'd like.
 - Supply queries that [don't affect loading state](defer-queries.md).
-- [Transform](./transforming.md) the queries to your desired output-format.
+- Send down payloads that contain any static data.
+- [Transform](./transforming.md) the data to your desired output-format.
+- Set up [default](../Quick%20Guide/base-loader.md) loading and error states.
 - [Extend](./extending.md) existing loaders.
 - Re-use existing loaders
+- Create [stateful loaders](./stateful-loader)
 
 And even if you don't use `RTK Query`...
 
 - Supply queries that are [just promises](../Exports/use-create-query.md).
 - [Use with other data loading libraries](./other-libs.md)
+
+---
+
+<DocCardList />

docs/docs/Features/stateful-loader.md

@@ -0,0 +1,44 @@
+---
+sidebar-position: 6
+---
+
+# Stateful loaders
+
+Since a `Loader` contains a hook, that hook can contain state.
+
+```typescript
+const loader = createLoader({
+  useQueries: () => {
+    const [name, setName] = useState("charizard");
+    const pokemon = useGetPokemon(name);
+    return {
+      queries: {
+        pokemon,
+      },
+    };
+  },
+});
+```
+
+You can then control this state, by sending the handlers through `payload`:
+
+```typescript {10}
+const componentLoader = createLoader({
+  useQueries: () => {
+    const [name, setName] = useState("charizard");
+    const debouncedName = useDebounce(name, 200);
+    const pokemon = useGetPokemon(debouncedName);
+    return {
+      queries: {
+        pokemon,
+      },
+      payload: { name, setName },
+    };
+  },
+});
+
+const Component = withLoader((props, loader) => {
+  const onChange = (e) => loader.payload.setName(e.target.value);
+  // ...
+}, componentLoader);
+```

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

@@ -0,0 +1,53 @@
+---
+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,
+      },
+    };
+  },
+});
+```
+
+:::tip
+`ConsumerProps<T>` simply means that the consumer component's props should have _atleast_ the properties of `T`.
+
+```typescript
+type ConsumerProps<T extends Record<string, unknown>> = Record<
+  string,
+  unknown
+> &
+  T;
+```
+
+:::
+
+```typescript
+<UserRoute userId="1234" />
+// → queriesArg({ userId: "1234" })
+// → "1234"
+// → loader.useQueries("1234")
+```

docs/docs/Quick Guide/add-queries.md

@@ -2,7 +2,7 @@
 sidebar_position: 3
 ---
 
-# Adding queries
+# 3. Add queries
 
 You can now start to add queries to your extended loaders.
 
@@ -29,69 +29,3 @@ export const userRouteLoader = baseLoader.extend({
 ```
 
 You can add as many queries as you'd like to `Response.queries`, and they will all aggregate to a common loading state.
-
-## Accepting arguments
-
-If you want the loader to take an argument, you can do that.
-
-```tsx {2}
-export const userRouteLoader = baseLoader.extend({
-  useQueries: (userId: string) => {
-    const user = useGetUserQuery(userId);
-    const posts = useGetPostsByUser(userId);
-
-    return {
-      queries: {
-        user,
-        posts,
-      },
-    };
-  },
-});
-```
-
-:::caution Beware
-If you want to consume this loader through `withLoader`, you need to add the `queriesArg` argument. This supplies the loader with an argument piped from `props`.
-:::
-
-### `queriesArg`
-
-This argument transforms the consumer's props to the queries argument.
-
-```tsx {1-5,8-10}
-// This means that any component that has props that extend this
-// type can consume the loader using `withLoader`
-type UserRouteLoaderProps = Record<string, any> & {
-  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,
-      },
-    };
-  },
-});
-```
-
-A component consuming this loader would pass the argument automatically through this pipeline:
-
-```typescript
-// props → queriesArg → useQueries
-loaderArgs.useQueries(queriesArg(consumerProps));
-```
-
-```typescript
-<UserRoute userId="1234" />
-// → queriesArg({ userId: "1234" })
-// → "1234"
-// → loader.useQueries("1234")
-```