docs: Updated docs

imp-dance · imp-dance · commit 9285a0c1fed7 · 2023-02-21T18:29:14.000+01:00
diff --git a/docs/docs/Advanced/index.md b/docs/docs/Advanced/index.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # Advanced
diff --git a/docs/docs/Exports/index.md b/docs/docs/Exports/index.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # Exports
diff --git a/docs/docs/Exports/use-create-query.md b/docs/docs/Exports/use-create-query.md
@@ -27,7 +27,10 @@ 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.
+:::caution
+You lose some great features from RTK query when using `useCreateQuery`.
+
+When 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.
+:::
diff --git a/docs/docs/Features/extending.md b/docs/docs/Features/extending.md
@@ -24,4 +24,6 @@ It's worth mentioning that queries and transform are linked in this context, mea
 
 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.
+:::info
+You may extend _extended_ loaders, to create an inheritance model.
+:::
diff --git a/docs/docs/Features/index.md b/docs/docs/Features/index.md
@@ -1,7 +1,14 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Features
 
-Read more about various `rtk-query-loader` features.
+RTK Query Loader tries to give you all the flexibility you need to create reusable and extendable loaders.
+
+- Supply multiple queries.
+- Supply queries that are [not from RTK](../Exports/use-create-query.md).
+- Supply queries that [don't affect loading state](defer-queries.md).
+- [Transform](./transforming.md) the queries to your desired output-format.
+- [Extend](./extending.md) existing loaders.
+- Re-use existing loaders
diff --git a/docs/docs/Quick Guide/add-queries.md b/docs/docs/Quick Guide/add-queries.md
@@ -40,7 +40,11 @@ export const userRouteLoader = baseLoader.extend({
 });
 ```
 
-**If you want to consume this loader through `withLoader`, you need to add the `queriesArg` argument**.
+:::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.
 
diff --git a/docs/docs/Quick Guide/base-loader.md b/docs/docs/Quick Guide/base-loader.md
@@ -6,7 +6,9 @@ sidebar_position: 1
 
 A `Loader` can control the loading, fetch and error state views for consumer components.
 
-> Use a base loader to create sensible "fallback"/"default"-states for consumer components.
+:::tip
+Use a base loader to create sensible "fallback"/"default"-states for consumer components.
+:::
 
 ```tsx title="/src/loaders/baseLoader.tsx" {7-20}
 import {
diff --git a/docs/docs/Quick Guide/consume-loader.mdx b/docs/docs/Quick Guide/consume-loader.mdx
@@ -2,13 +2,19 @@
 sidebar_position: 4
 ---
 
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
 # Consume the loader
 
-## Using `withLoader`
+<Tabs groupId="method" queryString>
+  <Tab label="Using withLoader" value="withLoader">
+
+A convenient wrapper that ensures that the component is only rendered when it has data.
 
-A convenient wrapper that ensures that the component is only rendered when it has data. This is definitely the preferred and optimal way to consume the loaders.
+This is definitely the preferred and optimal way to consume the loaders.
 
-```tsx title="/src/routes/UserRoute.tsx" {8-22}
+```tsx {8-22}
 import { withLoader } from "@ryfylke-react/rtk-query-loader";
 import { userRouteLoader } from "../loaders/baseLoader";
 
@@ -33,7 +39,8 @@ export const UserRoute = withLoader((props: Props, queries) => {
 }, userRouteLoader);
 ```
 
-## Using `useLoader`
+  </Tab>
+  <Tab label="Using useLoader" value="useLoader" default>
 
 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.
 
@@ -58,3 +65,6 @@ const UserRoute = (props: Props) => {
   // ...
 };
 ```
+
+  </Tab>
+</Tabs>
diff --git a/docs/docs/Quick Guide/extend-loader.md b/docs/docs/Quick Guide/extend-loader.md
@@ -14,10 +14,12 @@ export const userRouteLoader = baseLoader.extend({});
 
 You can pass any argument from [`createLoader`](/Exports/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...
 
 - Co-locating loaders in a shared folder
 - Co-locating loaders in same file as component
 - Co-locating loaders in same directory but in a separate file from the component
 
 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.
+:::
diff --git a/docs/docs/Quick Guide/index.md b/docs/docs/Quick Guide/index.md
@@ -1,7 +1,12 @@
 ---
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 # Quick guide
 
-Get started quickly by following these steps.
+`rtk-query-loader` is a tool that you can use to clean up your codebase and prevent duplicate code. The following guide will walk you through some of our recommended best practises for making the most out of this package.
+
+1. [Create a base loader](./base-loader.md)
+2. [Extend the base loader](./extend-loader.md)
+3. [Add queries](./add-queries.md)
+4. [Consume the loader](./consume-loader.md)
diff --git a/docs/docs/examples.md b/docs/docs/examples.md
@@ -0,0 +1,39 @@
+---
+sidebar_position: 3
+---
+
+# Simple example
+
+```tsx {10-19,22-31}
+import {
+  withLoader,
+  createLoader,
+} from "@ryfylke-react/rtk-query-loader";
+import { useParams } from "react-router-dom";
+import { useGetUserQuery } from "../api/user";
+import { ErrorView } from "../components/ErrorView";
+
+// Create a loader
+const userRouteLoader = createLoader({
+  queries: () => {
+    const { userId } = useParams();
+    const userQuery = useGetUserQuery(userId);
+
+    return [userQuery] as const; // important
+  },
+  onLoading: (props) => <div>Loading...</div>,
+  onError: (props, error) => <ErrorView error={error} />,
+});
+
+// Consume the loader
+const UserRoute = withLoader((props: {}, queries) => {
+  // Queries have successfully loaded
+  const user = queries[0].data;
+
+  return (
+    <div>
+      <h2>{user.name}</h2>
+    </div>
+  );
+}, userRouteLoader);
+```
diff --git a/docs/docs/intro.md b/docs/docs/intro.md
@@ -11,6 +11,13 @@ slug: /
 ![npm downloads](https://img.shields.io/npm/dm/@ryfylke-react/rtk-query-loader)
 [![github stars](https://img.shields.io/github/stars/ryfylke-react-as/rtk-query-loader?style=social)](https://github.com/ryfylke-react-as/rtk-query-loader)
 
+Lets you create loaders for use with [RTK Query](https://redux-toolkit.js.org/rtk-query/overview).
+
+- [x] **Reusable**
+- [x] **Extendable**
+- [x] **Transformable**
+- [x] **Type-safe**
+
 ```shell
 npm i @ryfylke-react/rtk-query-loader
 ```
@@ -19,9 +26,6 @@ npm i @ryfylke-react/rtk-query-loader
 - [NPM](https://www.npmjs.com/package/@ryfylke-react/rtk-query-loader)
 - [CodeSandbox](https://codesandbox.io/s/rtk-query-loader-demo-42tubp) (demo/playground)
 
-Lets you create loaders for RTK query.
-
-- [x] **Reusable**
-- [x] **Extendable**
-- [x] **Transformable**
-- [x] **Type-safe**
+:::tip Getting Started
+Get started with our recommended best practises by following the [**Quick guide**](/Quick%20guide).
+:::
diff --git a/docs/docs/problem-solve.md b/docs/docs/problem-solve.md
@@ -44,41 +44,3 @@ What if we could instead "join" these queries into one, and then just return ear
 - [x] Reusability across multiple components
 - [x] Extendability
 - [x] Transform the output to any format you'd like.
-
-## Simple example
-
-```tsx {10-19,22-31}
-import {
-  withLoader,
-  createLoader,
-} from "@ryfylke-react/rtk-query-loader";
-import { useParams } from "react-router-dom";
-import { useGetUserQuery } from "../api/user";
-import { ErrorView } from "../components/ErrorView";
-
-// Create a loader
-const userRouteLoader = createLoader({
-  queries: () => {
-    const { userId } = useParams();
-    const userQuery = useGetUserQuery(userId);
-
-    return [userQuery] as const; // important
-  },
-  onLoading: (props) => <div>Loading...</div>,
-  onError: (props, error) => <ErrorView error={error} />,
-});
-
-// Consume the loader
-const UserRoute = withLoader((props: {}, queries) => {
-  // Queries have successfully loaded
-  const user = queries[0].data;
-
-  return (
-    <div>
-      <h2>{user.name}</h2>
-    </div>
-  );
-}, userRouteLoader);
-```
-
-> Get started with our recommended best practises by following the [**Quick guide**](/Quick%20guide) on the next page.
diff --git a/tsconfig.json b/tsconfig.json
@@ -1,6 +1,6 @@
 {
   "include": ["src"],
-  "exclude": ["dist", "node_modules"],
+  "exclude": ["dist", "node_modules", "docs"],
   "compilerOptions": {
     "module": "esnext",
     "lib": ["dom", "esnext"],
