docs: Note Vue's mounted useSuspense keeps data after invalidate

docs/core/api/Controller.md

@@ -431,6 +431,44 @@ function ArticleName({ id }: { id: string }) {
 
 :::
 
+::::vue
+
+:::tip[Show the Suspense fallback again]
+
+Remount the component with a new `key` after invalidating; the new instance suspends on the invalid data.
+`timeout="0"` makes `<Suspense>` show its fallback while it waits instead of the old content. Remounting
+resets the component's local state.
+
+```html title="ArticlePage.vue"
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useController } from '@data-client/vue';
+  import { ArticleResource } from './ArticleResource';
+  import ArticleName from './ArticleName.vue';
+
+  const props = defineProps<{ id: string }>();
+  const ctrl = useController();
+  const remountKey = ref(0);
+
+  async function reload() {
+    await ctrl.invalidate(ArticleResource.get, { id: props.id });
+    remountKey.value++;
+  }
+</script>
+
+<template>
+  <button @click="reload">Reload</button>
+  <Suspense timeout="0">
+    <ArticleName :key="remountKey" :id="id" />
+    <template #fallback>Loading...</template>
+  </Suspense>
+</template>
+```
+
+:::
+
+::::
+
 ::::react
 
 :::tip
@@ -949,7 +987,7 @@ export enum ExpiryStatus {
 
 ##### Invalid
 
-- Will always suspend
+- Will always suspend:vue[ during setup; mounted components [keep their current data](../concepts/expiry-policy.md#invalidate) until the refetch resolves]
 - Will always fetch
 
 #### expiresAt

docs/core/api/useSuspense.md

@@ -204,20 +204,26 @@ render(<ProfileDetail />);
 
 Cache policy is [Stale-While-Revalidate](https://tools.ietf.org/html/rfc5861) by default but also [configurable](../concepts/expiry-policy.md).
 
-| Expiry Status | Fetch           | Suspend | Error             | Conditions                                                                                                                                                                   |
-| ------------- | --------------- | ------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Invalid       | yes<sup>1</sup> | yes     | no                | not in store, [deletion](/rest/api/resource#delete), [invalidation](./Controller.md#invalidate), [invalidIfStale](../concepts/expiry-policy.md#endpointinvalidifstale) |
-| Stale         | yes<sup>1</sup> | no      | no                | (first-render, arg change) & [expiry &lt; now](../concepts/expiry-policy.md)                                                                                                 |
-| Valid         | no              | no      | maybe<sup>2</sup> | fetch completion                                                                                                                                                             |
-|               | no              | no      | no                | `null` used as second argument                                                                                                                                               |
+| Expiry Status | Fetch           | Suspend               | Error             | Conditions                                                                                                                                                                   |
+| ------------- | --------------- | --------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Invalid       | yes<sup>1</sup> | yes:vue[<sup>3</sup>] | no                | not in store, [deletion](/rest/api/resource#delete), [invalidation](./Controller.md#invalidate), [invalidIfStale](../concepts/expiry-policy.md#endpointinvalidifstale) |
+| Stale         | yes<sup>1</sup> | no                    | no                | (first-render, arg change) & [expiry &lt; now](../concepts/expiry-policy.md)                                                                                                 |
+| Valid         | no              | no                    | maybe<sup>2</sup> | fetch completion                                                                                                                                                             |
+|               | no              | no                    | no                | `null` used as second argument                                                                                                                                               |
 
-:::note
+::::note
 
 1. Identical fetches are automatically deduplicated
 2. [Hard errors](../concepts/error-policy.md#hard) to be [caught](../getting-started/data-dependency#async-fallbacks) by :react[[Error Boundaries](./AsyncBoundary.md)]:vue[[onErrorCaptured()](https://vuejs.org/api/composition-api-lifecycle.html#onerrorcaptured)]
 
+:::vue
+
+3. Only during setup; mounted components [keep their current data](../concepts/expiry-policy.md#invalidate) until the refetch resolves.
+
 :::
 
+::::
+
 ::::react
 
 :::info[React Native]

packages/core/src/controller/Controller.ts

@@ -187,7 +187,8 @@ export default class Controller<
   };
 
   /**
-   * Forces refetching and suspense on useSuspense with the same Endpoint and parameters.
+   * Forces refetching on useSuspense with the same Endpoint and parameters, suspending until it resolves
+   * (mounted Vue components keep their current data instead).
    * @see https://dataclient.io/docs/api/Controller#invalidate
    */
   invalidate = <E extends EndpointInterface>(
@@ -203,7 +204,8 @@ export default class Controller<
     : Promise.resolve();
 
   /**
-   * Forces refetching and suspense on useSuspense on all matching endpoint result keys.
+   * Forces refetching on useSuspense on all matching endpoint result keys, suspending until it resolves
+   * (mounted Vue components keep their current data instead).
    * @see https://dataclient.io/docs/api/Controller#invalidateAll
    * @returns Promise that resolves when invalidation is commited.
    */