chore: Added migration docs and new test for payload

Author: imp-dance

docs/docs/Migrations/v0.x.md

@@ -0,0 +1,113 @@
+# Migrating to `1.0.0`
+
+If you are using `@ryfylke-react/rtk-query-loader@0.3.51` or earlier, these docs will help you migrate your existing codebase over to `1.0.0`.
+
+## Input format for data
+
+Previously, queries have been passed using two arguments:
+
+- **`queries`**
+- **`deferredQueries`**
+
+These two functions used to return a `readonly UseQueryResult<T>[]`.
+
+In version `1.0.0`, these arguments have now been joined into one, called `useQueries`.
+
+```typescript {3-10,15-23}
+// Previously
+const loader = createLoader({
+  queries: (arg: string) => {
+    const pokemonQuery = useGetPokemon(arg);
+    return [pokemonQuery] as const;
+  },
+  deferredQueries: () => {
+    const otherQuery = useOtherQuery();
+    return [otherQuery] as const;
+  },
+});
+
+// In version 1:
+const loader = createLoader({
+  useQueries: (arg: string) => {
+    const pokemonQuery = useGetPokemon(arg);
+    const otherQuery = useOtherQuery();
+
+    return {
+      queries: { pokemonQuery },
+      deferredQueries: { otherQuery },
+    };
+  },
+});
+```
+
+:::info
+Previously, you _had_ to use `transform` as well to expose the deferred queries to your consumer. This is no longer required.
+:::
+
+## Output format for data
+
+This also means that the output format of the loader has changed. Typescript will help you out here, but for the most part **what you send in is what you get out**.
+
+```typescript
+const loader = createLoader({
+  useQueries: () => ({
+    queries: {
+      pokemons: useGetPokemons(),
+    },
+  }),
+});
+
+type LoaderData = InferLoaderData<typeof loader>;
+// {
+//    queries: {
+//        pokemons: UseQueryResult<Pokemon[]>
+//    }
+// }
+```
+
+This output format change will affect your consumer components, as well as the (now single) argument passed to `transform`.
+
+You can still of course optionally [transform](../Features/transforming.md) the output.
+
+:::tip You should know
+This I/O interface change is the **only breaking change** from the previous versions.
+:::
+
+:::note
+Through rewriting the tests and lots of local testing, I can assure you that this refactor should be relatively straight forward and easy to do. If you fix the loaders first by changing and `queries` and `deferredQueries` to now use `useQueries`, you can let Typescript help you out in the consumers afterwards.
+:::
+
+## New feature: `payload`
+
+You can now send _any_ data you want through the loader. This is useful for when your loader contains a lot of logic, or if you want to pass some handlers down to the consumer to change the arguments of your queries.
+
+```typescript
+const loader = createLoader({
+  useQueries: () => {
+    const [pokemonName, setPokemonName] = useState("charizard");
+    const pokemon = useGetPokemon(pokemonName);
+
+    return {
+      queries: {
+        pokemon,
+      },
+      payload: {
+        changePokemon: setPokemonName,
+      },
+    };
+  },
+});
+
+const Consumer = withLoader((props, data) => {
+  const { payload, queries } = 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.
+
+## Reporting bugs
+
+If you find any bugs or issues with this new update, I strongly encourage you to [file a bug report](https://github.com/ryfylke-react-as/rtk-query-loader/issues/new?assignees=&labels=&template=bug_report.md&title=) on the Github repo.
+
+I hope you are happy with the changes coming in version `1`. They have been thoroughly thought out and brewed on for a couple of months. Although it's never fun to push a breaking change, I hope you agree that these changes add a lot more flexibility to the loaders, and less confusion around I/O format. I'm personally very glad that I'm no longer required to rembember to use `as const` to ensure I get the correct types in my loader.

docs/docs/intro.md

@@ -29,3 +29,7 @@ npm i @ryfylke-react/rtk-query-loader
 :::tip Getting Started
 Get started with our recommended best practises by following the [**Quick guide**](/Quick%20guide).
 :::
+
+:::danger These docs are for version 1.0.0 and up
+If you are using version `0.3.51` or earlier, please refer to the [**migration guide**](./Migrations/v0.x).
+:::

testing-app/src/tests.test.tsx

@@ -298,6 +298,23 @@ describe("withLoader", () => {
     expect(screen.getByText("Success")).toBeVisible();
   });
 
+  test("Can send static payload to loader", async () => {
+    const Component = withLoader(
+      (_, loader) => {
+        return <div>{loader.payload.foo}</div>;
+      },
+      createLoader({
+        useQueries: () => ({
+          payload: {
+            foo: "bar" as const,
+          },
+        }),
+      })
+    );
+    render(<Component />);
+    expect(screen.getByText("bar")).toBeVisible();
+  });
+
   describe(".extend()", () => {
     test("Can extend onLoading", async () => {
       render(<ExtendedLoaderComponent />);