docs: Updated docs

imp-dance · imp-dance · commit 14ec7685d393 · 2023-03-18T13:46:39.000+01:00
diff --git a/docs/docs/Exports/create-loader.md b/docs/docs/Exports/create-loader.md
diff --git a/docs/docs/Exports/with-loader.md b/docs/docs/Exports/with-loader.md
diff --git a/docs/docs/Features/index.mdx b/docs/docs/Features/index.mdx
@@ -13,13 +13,12 @@ RTK Query Loader tries to give you all the flexibility you need to create reusab
 - 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
+- [Extend](./extending.md) and 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).
+- Supply queries that are [just promises](../Reference/use-create-query.md).
 - [Use with other data loading libraries](./other-libs.md)
 
 ---
diff --git a/docs/docs/Migrations/v0.x.md b/docs/docs/Migrations/v0.x.md
@@ -104,7 +104,7 @@ const Consumer = withLoader((props, data) => {
 }, loader);
 ```
 
-Previously, if you wanted to do something like this, you had to use [useCreateQuery](../Exports/use-create-query.md), or a wrapper component. If you did, you can now refactor your code to use `payload` instead, which should be a lot more clean and flexible.
+Previously, if you wanted to do something like this, you had to use [useCreateQuery](../Reference/use-create-query.md), or a wrapper component. If you did, you can now refactor your code to use `payload` instead, which should be a lot more clean and flexible.
 
 ## Change: Extend transform
 
diff --git a/docs/docs/Quick Guide/add-queries.md b/docs/docs/Quick Guide/add-queries.md
@@ -6,7 +6,7 @@ sidebar_position: 3
 
 You can now start to add queries to your extended loaders.
 
-The `useQueries` argument of [createLoader](/Exports/create-loader) is a _hook_, which means that [the rules of hooks](https://reactjs.org/docs/hooks-rules.html) apply. This gives you the super-power of utilizing other hooks inside of your loader.
+The `useQueries` argument of [createLoader](/Reference/create-loader) is a _hook_, which means that [the rules of hooks](https://reactjs.org/docs/hooks-rules.html) apply. This gives you the super-power of utilizing other hooks inside of your loader.
 
 ```tsx title="/src/loaders/userRouteLoader.tsx" {6-15}
 import { baseLoader } from "./baseLoader";
diff --git a/docs/docs/Quick Guide/extend-loader.md b/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`](/Features/extending).
+You can pass any argument from [`createLoader`](/Reference/create-loader) into [`Loader.extend`](/Features/extending).
 
 :::info Separation of concerns
 Its up to you how much you want to separate logic here. Some examples would be...
diff --git a/docs/docs/Reference/aggregate-to-query.md b/docs/docs/Reference/aggregate-to-query.md
@@ -4,11 +4,7 @@ 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.
-:::
+Aggregates a set of `UseQueryResult` into a single query.
 
 ```typescript
 import {
@@ -27,3 +23,7 @@ const query: UseQueryResult<unknown> = {
   data: queries.map((query) => query.data),
 };
 ```
+
+:::caution
+`aggregateToQuery` does not add any `data` to the resulting query. You will have to do that manually afterwards.
+:::
diff --git a/docs/docs/Reference/consumer-props.md b/docs/docs/Reference/consumer-props.md
diff --git a/docs/docs/Reference/create-loader.md b/docs/docs/Reference/create-loader.md
@@ -0,0 +1,95 @@
+---
+sidebar_position: 1
+---
+
+# createLoader
+
+Creates a `Loader`.
+
+## Arguments
+
+All arguments are optional.
+
+- **`useQueries`** - A hook that runs the queries and returns them. It can take an argument, which can be transformed from the consumer props through `queriesArg`
+  ```typescript
+  useQueries: (arg?: Arg) => {
+      queries?: Record<string, UseQueryResult>;
+      deferredQueries?: Record<string, UseQueryResult>;
+      payload?: any;
+  }
+  ```
+- **`queriesArg`** - A function that transforms the consumer props into the argument for `useQueries` - required if your loader should be able to take arguments from props.
+  ```typescript
+  queriesArg: (props: Props) => Arg;
+  ```
+- **`transform`** - A function that lets you transform the shape of the output data.
+  ```typescript
+  transform: (data: Data) => TransformedData;
+  ```
+- **`onLoading`** - A function that determines what to render while the component is going through it's initial load phase.
+  ```typescript
+  onLoading: (props: Props) => ReactElement;
+  ```
+- **`onError`** - A function that determines what to render while the component is going through it's initial load phase.
+  ```typescript
+  onError: (props: Props, error: unknown) => ReactElement;
+  ```
+- **`whileFetching`** - An object that lets you append &/ prepend elements to your component while it is fetching.
+  ```typescript
+  whileFetching: {
+      prepend?: (props: Props, data?: Data) => ReactElement;
+      append?: (props: Props, data?: Data) => ReactElement;
+  };
+  ```
+- **`config`** - An object that lets you configure the behavior of the loader.
+  ```typescript
+  config: {
+      defer? {
+          shouldThrowError?: boolean;
+      };
+      loaderComponent?: Component<LoaderComponentProps>;
+  }
+  ```
+
+## Return
+
+`createLoader` returns a `Loader`. You can use this loader with [withLoader](with-loader.md), or you can call the `.extend` method to produce a new loader using the original loader as a base. `.extend` takes the same set of arguments as `createLoader`.
+
+## Example usage
+
+```typescript title="example.ts"
+type ConsumerProps = Record<string, any> & {
+  userId: string;
+};
+
+const loader = createLoader({
+  queriesArg: (props: ConsumerProps) => props.userId,
+  useQueries: (userId) => {
+    return {
+      queries: {
+        user: useGetUser(userId),
+      },
+      deferredQueries: {
+        relations: useGetUserRelations(userId),
+      },
+      payload: {
+        // Lets you send any static data to your consumer
+        static: "data",
+      },
+    };
+  },
+  transform: (loaderData) => ({
+    ...loaderData,
+    foo: "bar",
+  }),
+  onLoading: (props) => <LoadingView />,
+  onError: (props, error) => <ErrorView />,
+  whileFetching: {
+    prepend: (props) => <LoadingOverlay />,
+  },
+});
+```
+
+:::caution Using version `0.3.51` or earlier?
+Please refer to the [**migration guide**](../Migrations/v0.x).
+:::
diff --git a/docs/docs/Reference/index.mdx b/docs/docs/Reference/index.mdx
@@ -4,7 +4,7 @@ sidebar_position: 6
 
 import DocCardList from "@theme/DocCardList";
 
-# Exports
+# Reference
 
 Describes the different exports and their related types.
 
diff --git a/docs/docs/Reference/infer-loader-data.md b/docs/docs/Reference/infer-loader-data.md
diff --git a/docs/docs/Reference/use-create-query.md b/docs/docs/Reference/use-create-query.md
@@ -4,9 +4,16 @@ sidebar_position: 4
 
 # useCreateQuery
 
-#### **Warning**: This API is experimental and might change.
+Lets you use any function that returns a promise to load your component.
 
-Lets you use any function that returns a promise in your loader as if it was an RTK useQuery.
+## Arguments
+
+`useCreateQuery` takes two arguments:
+
+- The first argument is a function that returns a promise.
+- The second argument is a dependency array. Whenever a value in this array changes, the query is re-run.
+
+## Example usage
 
 ```typescript
 import {
diff --git a/docs/docs/Reference/with-loader.md b/docs/docs/Reference/with-loader.md
@@ -0,0 +1,51 @@
+---
+sidebar_position: 1
+---
+
+# withLoader
+
+Consumes a `Loader`.
+
+## Arguments
+
+`withLoader` takes two arguments.
+
+```typescript
+type Argument1 = (props: P, loaderData: R) => ReactElement;
+type Argument2 = Loader;
+```
+
+- The first argument is a component, but with an extra parameter for the loaded data.
+- The second argument is a `Loader` (returned from `createLoader`)
+
+## Example usage
+
+```tsx
+const pokemonLoader = createLoader({
+  useQueries: () => ({
+    queries: { pokemon: useGetPokemon() },
+  }),
+});
+
+const Pokemon = withLoader((props, { queries }) => {
+  return <div>{queries.pokemon.data.name}</div>;
+}, pokemonLoader);
+```
+
+Here is another example, where the arguments are all unwrapped:
+
+```tsx
+const pokemonLoader = createLoader({
+  useQueries: () => ({
+    queries: { pokemon: useGetPokemon() },
+  }),
+});
+
+type PokemonData = InferLoaderData<typeof pokemonLoader>;
+
+const LoadedComponent = (props, loaderData: PokemonData) => {
+  return <div>{loaderData.queries.pokemon.data.name}</div>;
+};
+
+const Pokemon = withLoader(LoadedComponent, pokemonLoader);
+```
diff --git a/docs/docs/examples.mdx b/docs/docs/examples.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 import TOCInline from "@theme/TOCInline";
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
@@ -1,6 +1,7 @@
 ---
 sidebar_position: 1
 slug: /
+title: Introduction
 ---
 
 # RTK Query Loader
diff --git a/docs/docs/problem-solve.md b/docs/docs/problem-solve.md
@@ -4,17 +4,62 @@ sidebar_position: 2
 
 # What problem does this solve?
 
-Handling the loading and error state of components that depend on external data can be very tedious,
-especially when you are managing multiple queries. RTK Query Loader aims to help you solve these issues by letting you create composable loaders that you can move out of the presentational components.
+**Handling the loading and error state of components that depend on external data can be tedious,
+especially when you are managing multiple queries.**
+
+### Example
+
+This component requires some data. There are 26 lines of code that are **just** concerned with ensuring that the data is present before rendering the _actual_ component.
+
+```typescript {2-28}
+const Component = () => {
+  const pokemonQuery = useGetPokemon("charizard");
+  const userQuery = useGetCurrentUser();
+  const userStatsQuery = useGetUserStats();
+
+  if (
+    pokemonQuery.isLoading ||
+    userQuery.isLoading ||
+    userStatsQuery.isLoading
+  ) {
+    return <LoadingView />;
+  }
+
+  if (
+    pokemonQuery.isError ||
+    userQuery.isError ||
+    userStatsQuery.isError
+  ) {
+    return (
+      <ErrorView
+        error={
+          pokemonQuery.error ??
+          userQuery.error ??
+          userStatsQuery.error
+        }
+      />
+    );
+  }
+  // Finally, you can write the actual component...
+};
+```
+
+RTK Query Loader lets you **move all of this logic out of the component**, and also make it _reusable_ and _composable_, so that other components can reuse that loader and have access to the same data.
 
 - [x] Isolate the data-loading code away from the presentational components
-- [x] Increased type certainty
+- [x] Increase type certainty
   - 🔥 Way less optional chaining in your components
   - 🔥 You write the components as if the data is already present
 - [x] Composability
   - ♻️ Extend existing loaders
   - ♻️ Overwrite only select properties
-- [x] Full control
+- [x] You're still fully in control
   - 🛠️ Loading/error states
   - 🛠️ Custom loader-component
-  - 🛠️ Control defer behaviour
+  - 🛠️ Configure the behavior of your loaders
+
+## Alternatives
+
+If you are using a Suspense-enabled framework, or any form of server-side rendering that can feed your components with data, then that would be a more optimal approach. [Remix](https://remix.run/docs/en/1.14.3/route/loader) has the concept of loaders built in, and NextJS is suspense enabled.
+
+If you are, however, building an SPA, or not using Next or Remix, then this package can be a great way for you gain the concept of loaders without moving to server-side rendering.
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
