@arrai-innovations/reactive-helpers 21.1.2 → 22.1.0

package/use/listRelated.js

@@ -18,44 +18,37 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
 
 // todo: pkKey is misnamed, it should be fkKey... this will be a major breaking change
 /**
- * The rule for defining relationships for objects in a list.
- *
- * @typedef {object} ListRelatedRule
- * @property {string} pkKey - Specifies the foreign key used to link objects across lists. Planned to be renamed to
- *  'fkKey' to better reflect its usage.
+ * @typedef {object} ListRelatedRule - The rule for defining relationships for objects in a list.
+ * @property {string} [pkKey] - Specifies the foreign key used to link objects across lists. Defaults to the rule's
+ *  own key when omitted. Planned to be renamed to 'fkKey' to better reflect its usage.
  * @property {string[]} [order] - Specifies the order in which related objects should be sorted, if applicable.
  * @property {import('./listInstance.js').ObjectsByPk} objects - The objects that can be related based on the foreign key.
  */
 
 /**
- * The rules for defining relationships among objects in a list.
- *
  * @typedef {{
  *     [rule: string]: ListRelatedRule,
- * }} ListRelatedRules
+ * }} ListRelatedRules - The rules for defining relationships among objects in a list.
  */
 
 /**
- * Represents the internal state used by the list related composition function. It manages and computes the relationships
- * between objects based on specified rules, providing real-time updates to related objects as the parent state changes.
- *
- * @typedef {object} ListRelatedRawState
+ * @typedef {object} ListRelatedRawState - Represents the internal state used by the list related composition function. It manages and computes the relationships between objects based on specified rules, providing real-time updates to related objects as the parent state changes.
  * @property {{
  *     [pk: import('../config/commonCrud.js').Pk]: {
- *         [rule: string]: import('vue').ComputedRef<any>,
+ *         [rule: string]: any,
  *     },
- * }} relatedObjects - Stores computed references to related objects, allowing for dynamic access based on object pk and specific rules.
+ * }} relatedObjects - The related objects, by object pk and then rule name. Each entry is backed by a computed, but it is read through a reactive proxy that unwraps it, so reads yield the related object (or array of related objects) and never carry a `.value`.
  * @property {ListRelatedRules} relatedObjectsRules - Defines the rules for establishing relationships, such as foreign key links and sorting orders.
  * @property {{
  *     [pk: import('../config/commonCrud.js').Pk]: {
  *         [rule: string]: import('vue').ComputedRef<[object, string]>,
  *     },
- * }} objAndKeyForPkAndRule - Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation.
+ * }} objAndKeyForPkAndRule - Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation. Reads through the reactive state unwrap the computed to the tuple itself, so `.value` is not used.
  * @property {{
  *     [pk: import('../config/commonCrud.js').Pk]: {
- *         [rule: string]: import('vue').ComputedRef<any>,
+ *         [rule: string]: any,
  *     },
- * }} fkForPkAndRule - Maintains computed references to the foreign keys for each object pk and rule, crucial for navigating complex data relationships.
+ * }} fkForPkAndRule - The foreign key for each object pk and rule, crucial for navigating complex data relationships. Each entry is backed by a computed that the reactive proxy unwraps on read.
  * @property {boolean} relatedObjectsParentStateObjectsWatchRunning - Flags whether the watch on parent state objects is currently active, ensuring updates trigger as needed.
  * @property {boolean} relatedObjectsWatchRunning - Indicates if watches on the related objects themselves are active, managing updates efficiently.
  * @property {boolean} relatedRunning - Signals whether any computations related to object relationships are currently in progress.
@@ -63,41 +56,31 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
  */
 
 /**
- * The raw state properties for a parent of a list related property.
- *
  * @typedef {(
  *     import('./listInstance.js').ListInstanceRawState &
  *     Partial<import('./listSubscription.js').ListSubscriptionRawState>
- * )} ListRelatedParentRawState
+ * )} ListRelatedParentRawState - The raw state properties for a parent of a list related property.
  */
 
 /**
- * The type for a parentState object.
- *
- * @typedef {import('vue').UnwrapNestedRefs<ListRelatedParentRawState>} ListRelatedParentState
+ * @typedef {import('vue').UnwrapNestedRefs<ListRelatedParentRawState>} ListRelatedParentState - The type for a parentState object.
  */
 
 /**
- * The state for a list related property.
- *
  * @typedef {import('vue').UnwrapNestedRefs<
  *     ListRelatedParentRawState &
  *     ListRelatedRawState
- * >} ListRelatedState
+ * >} ListRelatedState - The state for a list related property.
  */
 
 /**
- * The options for the list related composition function.
- *
- * @typedef {object} ListRelatedOptions
+ * @typedef {object} ListRelatedOptions - The options for the list related composition function.
  * @property {ListRelatedParentState} parentState - The parent state object.
  * @property {import('vue').Ref<ListRelatedRules>} relatedObjectsRules - The rules for the related objects.
  */
 
 /**
- * The properties for the list related composition function.
- *
- * @typedef {object} ListRelatedProperties
+ * @typedef {object} ListRelatedProperties - The properties for the list related composition function.
  * @property {ListRelatedState} state - The state for the list related property.
  * @property {ListRelatedParentState} parentState - The parent state object.
  * @property {() => void} stop - Stops all effects of the list related property.
@@ -106,9 +89,7 @@ import { computed, effectScope, nextTick, onScopeDispose, reactive, ref, toRef,
 // if we provided functions, we would add a typedef and mix them into ListRelated
 
 /**
- * An instance of `useListRelated`.
- *
- * @typedef {ListRelatedProperties} ListRelated
+ * @typedef {ListRelatedProperties} ListRelated - An instance of `useListRelated`.
  */
 
 /**
@@ -348,7 +329,7 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
 
     es.run(() => {
         watch(
-            () => Object.keys(parentState.objects),
+            () => parentState.objectsVersion,
             () => {
                 state.relatedObjectsParentStateObjectsWatchRunning = true;
             },
@@ -356,7 +337,7 @@ export function useListRelated({ parentState, relatedObjectsRules }) {
         );
         watch(() => Object.keys(parentState.objects), parentStateObjectsWatch, { immediate: true });
         watch(
-            [() => Object.keys(state.relatedObjects), () => Object.keys(state.relatedObjectsRules || {})],
+            [() => parentState.objectsVersion, () => Object.keys(state.relatedObjectsRules || {})],
             () => {
                 state.relatedObjectsWatchRunning = true;
             },

package/use/listSearch.js

@@ -21,9 +21,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
  */
 
 /**
- * Represents the raw reactive state used by the list search functionality.
- *
- * @typedef {object} ListSearchRawState
+ * @typedef {object} ListSearchRawState - Represents the raw reactive state used by the list search functionality.
  * @property {import('./listInstance.js').ObjectsByPk} objects - Currently filtered objects based on the search.
  * @property {import('./listInstance.js').ObjectsInOrder} objectsInOrder - The list of objects sorted according to the current search criteria.
  * @property {import('./listInstance.js').ListOrder} order - The current sort order of object pks after search have been applied.
@@ -46,7 +44,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
  *     Partial<import('./listRelated.js').ListRelatedRawState> &
  *     Partial<import('./listCalculated.js').ListCalculatedRawState> &
  *     Partial<import('./listFilter.js').ListFilterRawState>
- * )} ListSearchParentRawState
+ * )} ListSearchParentRawState - The raw, pre-unwrapped parent state consumed by the list search mixin, aggregating the upstream list composable states.
  */
 
 /**
@@ -54,7 +52,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
  */
 
 /**
- *  @typedef {import('vue').ToRefs<ListSearchParentState>} ListSearchParentStateToRefs
+ *  @typedef {import('vue').ToRefs<ListSearchParentState>} ListSearchParentStateToRefs - The parent list-search state converted to individual Vue refs.
  */
 
 /**
@@ -86,9 +84,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
  */
 
 /**
- * The properties on a list search instance.
- *
- * @typedef {object} ListSearchProperties
+ * @typedef {object} ListSearchProperties - The properties on a list search instance.
  * @property {ListSearchState} state - The state.
  * @property {import('./search.js').SearchInstance} textSearchIndex - The text search index.
  * @property {() => void} stop - Stops the effect scope and cleans up resources.
@@ -97,9 +93,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
 // if we provided functions, we would add a typedef and mix them into ListSearch
 
 /**
- * The provided list search instance, containing properties and functions.
- *
- * @typedef {ListSearchProperties} ListSearch
+ * @typedef {ListSearchProperties} ListSearch - The provided list search instance, containing properties and functions.
  */
 
 /**
@@ -123,14 +117,11 @@ export function useListSearches(listSearchArgs) {
 }
 
 /**
- * FlexSearch.Document options, specifically for .index. Their documentation isn't very clear on this.
- * Typically, it would be a list of dot-separated keys to index.
- *
- * @typedef {string | string[] | object[]} TextSearchRules
+ * @typedef {string | string[] | object[]} TextSearchRules - FlexSearch.Document options, specifically for .index. Their documentation isn't very clear on this. Typically, it would be a list of dot-separated keys to index.
  */
 
 /**
- * @typedef {object} ListSearchProps
+ * @typedef {object} ListSearchProps - The consumer-supplied props configuring a list's text search (rules, value, and FlexSearch options).
  * @property {TextSearchRules} textSearchRules - Rules for what to search for. Keys are the keys to search for, values are functions that take the object and return The value to search for.
  * @property {string} textSearchValue - The value to search for.
  * @property {object} customDocumentOptions - FlexSearch.Document options.
@@ -139,7 +130,7 @@ export function useListSearches(listSearchArgs) {
  */
 
 /**
- * @typedef {object} ListSearchInstanceOptions
+ * @typedef {object} ListSearchInstanceOptions - The configuration options used to create a list search instance.
  * @property {object} parentState - The list being filtered.
  * @property {ListSearchProps} [props] - Reactive properties.
  * @property {number} [throttle=500] - Throttle wait time.
@@ -271,7 +262,7 @@ export function useListSearch({ parentState, props, throttle = 500, showAllWhenE
             addedKeys: addedObjectPks,
             removedKeys: removedObjectPks,
             sameKeys: sameObjectPks,
-        } = keyDiff(Object.keys(parentState.objects), Object.keys(state.objects));
+        } = keyDiff(Object.keys(parentState.objects), Object.keys(objectEffectScopes));
         const { addedKeys: addedTextSearchRules, removedKeys: removedTextSearchRules } = keyDiff(
             state.textSearchRules,
             previousTextSearchRules

package/use/listSort.js

@@ -1,8 +1,10 @@
 import { keyDiff } from "../utils/keyDiff.js";
+import { loadingCombine } from "../utils/loadingCombine.js";
+import { proxyRunning } from "../utils/proxyRunning.js";
 import get from "lodash-es/get.js";
 import identity from "lodash-es/identity.js";
 import throttle from "lodash-es/throttle.js";
-import { computed, effectScope, reactive, ref, toRef, toRefs, unref, watch } from "vue";
+import { computed, effectScope, onScopeDispose, reactive, ref, toRef, toRefs, unref, watch } from "vue";
 
 /**
  * Provides a Vue 3 composable for sorting lists based on dynamic and customizable rules. This module integrates
@@ -23,7 +25,7 @@ const defaultOptions = {
 
 /**
  * Sets default configuration options for all list sorting operations within the application. This function allows
- * global settings to be specified that affect the behavior of sorting operations unless overridden by specific
+ * global settings to be specified that affect the behaviour of sorting operations unless overridden by specific
  * instance configurations.
  *
  * @param {object} options - Configuration options to set as defaults for list sorting.
@@ -35,25 +37,19 @@ export function setListSortDefaultOptions({ sortThrottleWait }) {
 }
 
 /**
- * Describes a rule for ordering elements in a list. Each rule can directly reference a property of the list items,
- * or define a function to compute the value used for sorting. Rules can be configured to sort in ascending or descending
- * order and can utilize locale-aware string comparison if necessary.
- *
  * @typedef {{
  *     key: string,
  *     keyFn?: (object: any, state: ListSortState) => any,
  *     desc?: boolean,
  *     localeCompare?: boolean
- * }} OrderByRule
+ * }} OrderByRule - Describes a rule for ordering elements in a list. Each rule can directly reference a property of the list items, or define a function to compute the value used for sorting. Rules can be configured to sort in ascending or descending order and can utilize locale-aware string comparison if necessary.
  */
 
 /**
- * Represents the raw state used by the list sorting functionality. Includes all configurations and state necessary
- * to manage sorting operations within a Vue application.
- *
- * @typedef {object} ListSortRawState
+ * @typedef {object} ListSortRawState - Represents the raw state used by the list sorting functionality. Includes all configurations and state necessary to manage sorting operations within a Vue application.
  * @property {OrderByRule[]} orderByRules - Current sorting rules applied to the list.
  * @property {boolean[]} orderByDesc - Flags indicating whether each sort criterion is in descending order.
+ * @property {import('vue').ComputedRef<boolean|undefined>} running - Whether the sort is settling a pending reorder, combined with the upstream running state so it propagates through the composed list state. True from when a new order is computed until the throttled reorder lands.
  */
 
 /**
@@ -66,36 +62,29 @@ export function setListSortDefaultOptions({ sortThrottleWait }) {
  *     Partial<import('./listCalculated.js').ListCalculatedRawState> &
  *     Partial<import('./listFilter.js').ListFilterRawState> &
  *     Partial<import('./listSearch.js').ListSearchRawState>
- * )} ListSortParentRawState
+ * )} ListSortParentRawState - The raw, pre-unwrapped parent state consumed by the list sort mixin, aggregating the upstream list composable states.
  */
 
 /**
- * @typedef {import('vue').UnwrapNestedRefs<ListSortParentRawState>} ListSortParentState
+ * @typedef {import('vue').UnwrapNestedRefs<ListSortParentRawState>} ListSortParentState - The unwrapped reactive parent state consumed by the list sort mixin.
  */
 
 /**
- * The reactive state used by the list sorting functionality. Includes all configurations and state necessary to manage
- * sorting operations within a Vue application.
- *
  * @typedef {import('vue').UnwrapNestedRefs<
  *     ListSortParentRawState &
  *     ListSortRawState
- * >} ListSortState
+ * >} ListSortState - The reactive state used by the list sorting functionality. Includes all configurations and state necessary to manage sorting operations within a Vue application.
  */
 
 /**
- * The configuration options for initializing a list sort instance.
- *
- * @typedef {object} ListSortOptions
+ * @typedef {object} ListSortOptions - The configuration options for initializing a list sort instance.
  * @property {ListSortParentState} parentState - The parent state containing the list data and any associated state needed for sorting.
  * @property {OrderByRule[]|import('vue').Ref<OrderByRule[]>} orderByRules - Rules defining how the list should be sorted, including key and direction.
  * @property {number | symbol} sortThrottleWait - Optional throttle wait time to limit the frequency of sort operations, enhancing performance.
  */
 
 /**
- * The properties available on a list sort instance.
- *
- * @typedef {object} ListSortProperties
+ * @typedef {object} ListSortProperties - The properties available on a list sort instance.
  * @property {ListSortState} state - The reactive state for the list sort.
  * @property {ListSortParentState} parentState - The parent state.
  * @property {() => void} stop - A function to stop the effect scope and clean up resources.
@@ -104,9 +93,7 @@ export function setListSortDefaultOptions({ sortThrottleWait }) {
 // if we provided functions, we would add a typedef and mix them into ListSort
 
 /**
- * The list sort instance, including reactive state and utilities to manage list sorting operations.
- *
- * @typedef {ListSortProperties} ListSort
+ * @typedef {ListSortProperties} ListSort - The list sort instance, including reactive state and utilities to manage list sorting operations.
  */
 
 /**
@@ -177,6 +164,13 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
     })();
     const es = effectScope();
 
+    /** @type {import('vue').Ref<boolean|undefined>} */
+    const parentRunning = ref(undefined);
+    proxyRunning(parentState, "running", parentRunning);
+    // True from the moment a new order is pending until the (possibly throttled) reorder lands.
+    const sortWatchRunning = ref(true);
+    const running = computed(() => loadingCombine(sortWatchRunning.value, parentRunning.value));
+
     const internalState = reactive({
         orderByRules,
         orderByDesc: computed(() =>
@@ -197,52 +191,59 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
                 if (!obj) {
                     return [];
                 }
-                return internalState.orderByRules
-                    ?.filter((r) => r && r.key)
-                    .map((r) => {
-                        if (!r) {
-                            return undefined;
-                        }
-                        if (r.keyFn) {
-                            return r.keyFn(obj, parentState);
-                        }
-                        if (r.key.startsWith("relatedItem.")) {
-                            return get(parentState.relatedObjects?.[pk], r.key.slice(12));
-                        }
-                        if (r.key.startsWith("calculatedItem.")) {
-                            return get(parentState.calculatedObjects?.[pk], r.key.slice(15));
-                        }
-                        return get(obj, r.key);
-                    });
+                return (
+                    internalState.orderByRules
+                        ?.filter((r) => r && r.key)
+                        .map((r) => {
+                            if (!r) {
+                                return undefined;
+                            }
+                            if (r.keyFn) {
+                                return r.keyFn(obj, parentState);
+                            }
+                            if (r.key.startsWith("relatedItem.")) {
+                                return get(parentState.relatedObjects?.[pk], r.key.slice(12));
+                            }
+                            if (r.key.startsWith("calculatedItem.")) {
+                                return get(parentState.calculatedObjects?.[pk], r.key.slice(15));
+                            }
+                            return get(obj, r.key);
+                        }) ?? []
+                );
             })
         );
         criteriaMap[pk] = { scope, crit };
         return crit;
     }
 
+    function syncCriteria(newKeys) {
+        const { addedKeys, removedKeys } = keyDiff(newKeys, Object.keys(criteriaMap));
+        for (const pk of removedKeys) {
+            criteriaMap[pk].scope.stop();
+            delete criteriaMap[pk];
+        }
+        for (const pk of addedKeys) {
+            ensureCriteria(pk);
+        }
+    }
+
     es.run(() => {
         watch(
-            () => Object.keys(parentState.objects),
-            (newKeys) => {
-                const { addedKeys, removedKeys } = keyDiff(newKeys, Object.keys(criteriaMap));
-                for (const pk of removedKeys) {
-                    criteriaMap[pk].scope.stop();
-                    delete criteriaMap[pk];
-                }
-                for (const pk of addedKeys) {
-                    ensureCriteria(pk);
-                }
+            () => parentState.objectsVersion,
+            () => {
+                syncCriteria(Object.keys(parentState.objects));
             },
             { immediate: true, flush: "sync" }
         );
+        watch(() => Object.keys(parentState.objects), syncCriteria);
     });
 
     const rawOrder = computed(() => {
         const arr = [...unref(toRef(parentState, "order"))];
         const rulesArr = internalState.orderByRules?.filter(identity) || [];
         return arr.sort((a, b) => {
-            const aCrit = criteriaMap[a].crit ?? [];
-            const bCrit = criteriaMap[b].crit ?? [];
+            const aCrit = criteriaMap[a]?.crit ?? [];
+            const bCrit = criteriaMap[b]?.crit ?? [];
             for (let i = 0; i < rulesArr.length; i++) {
                 const rule = rulesArr[i];
                 let x = aCrit[i],
@@ -285,16 +286,45 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
     });
 
     const order = ref([]);
-    const assignOrder =
-        sortThrottleWaitNumber > 0
-            ? throttle((v) => {
-                  order.value = v;
-              }, sortThrottleWaitNumber)
-            : (v) => {
-                  order.value = v;
-              };
+    const writeOrder = (v) => {
+        order.value = v;
+        // the pending reorder has landed; let running settle unless the parent is still running
+        sortWatchRunning.value = false;
+    };
+    // Held separately from assignOrder so the throttle's own cancel stays typed.
+    const throttledOrder = sortThrottleWaitNumber > 0 ? throttle(writeOrder, sortThrottleWaitNumber) : null;
+    const assignOrder = throttledOrder ?? writeOrder;
 
-    watch(rawOrder, (v) => assignOrder(v), { immediate: true });
+    es.run(() => {
+        // Raise running synchronously the moment a new order is pending, so a throttled reorder keeps
+        //  running true until it lands. This mirrors the related, calculated, and search layers, and
+        //  lets the composed manager's state.running reflect the final reorder settling. Watch cheap
+        //  signals rather than rawOrder itself: a sync watcher re-evaluates its source on every
+        //  invalidation, and rawOrder performs the full sort, so watching it synchronously re-sorts
+        //  the list once per reactive write while a page is being pushed. The batched objectsVersion
+        //  covers structural changes and the rule reads cover rule changes; reorders triggered another
+        //  way (a row edit, a parent subset change) raise running in the pre-flush watcher below.
+        watch(
+            () => [parentState.objectsVersion, internalState.orderByRules, internalState.orderByDesc],
+            () => {
+                sortWatchRunning.value = true;
+            },
+            { flush: "sync" }
+        );
+        watch(
+            rawOrder,
+            (v) => {
+                sortWatchRunning.value = true;
+                assignOrder(v);
+            },
+            { immediate: true }
+        );
+        // A throttled trailing reorder is a timer, not a reactive effect, so disposal would otherwise
+        //  leave it pending and let it write order after the layer stopped.
+        if (throttledOrder) {
+            onScopeDispose(() => throttledOrder.cancel());
+        }
+    });
 
     // 6) objectsInOrder just follows that
     const objectsInOrder = computed(() => order.value.map((pk) => parentState.objects[pk]));
@@ -307,6 +337,7 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
             objects,
             order,
             objectsInOrder,
+            running,
         }),
         parentState,
         stop: () => {

package/use/listSubscription.js

@@ -33,36 +33,30 @@ export class ListSubscriptionError extends Error {
 }
 
 /**
- * The raw state of a list subscription.
- *
- * @typedef {object} ListSubscriptionMyState
+ * @typedef {object} ListSubscriptionMyState - The raw state of a list subscription.
  * @property {import('vue').Ref<boolean>|boolean} intendToList - If this is true, the list should be fetched, or re-fetched if arguments change.
  * @property {import('vue').Ref<boolean>|boolean} intendToSubscribe - If this is true, the subscription should start or restart if arguments change.
  * @property {import('vue').Ref<boolean>} subscribed - Whether the subscription is active.
  */
 
 /**
- * @typedef {import('vue').ToRefs<import('./listInstance.js').ListInstanceState>} ListInstanceStateRefs
+ * @typedef {import('vue').ToRefs<import('./listInstance.js').ListInstanceState>} ListInstanceStateRefs - The list instance's reactive state converted to individual Vue refs.
  */
 
 /**
- * The raw state of a list subscription, including the state from the list instance.
- *
  * @typedef {ListSubscriptionMyState & (
  *     Pick<import('./loadingError.js').LoadingErrorStatus, "loading" | "error" | "errored">
- * ) & ListInstanceStateRefs} ListSubscriptionRawState
+ * ) & ListInstanceStateRefs} ListSubscriptionRawState - The raw state of a list subscription, including the state from the list instance.
  */
 
 /**
- * A reactive object that manages a list of objects, as returned by `useListInstance`.
- *
- * @typedef {import('vue').Reactive<ListSubscriptionRawState>} ListSubscriptionState
+ * @typedef {import('vue').Reactive<ListSubscriptionRawState>} ListSubscriptionState - A reactive object that manages a list of objects, as returned by `useListInstance`.
  */
 
 /**
- * The methods available on a list subscription.
- *
- * @typedef {Pick<import('./loadingError.js').LoadingErrorStatus, "clearError">} ListSubscriptionFunctions
+ * @typedef {Pick<import('./loadingError.js').LoadingErrorStatus, "clearError"> & {
+ *     stop: () => void
+ * }} ListSubscriptionFunctions - The methods available on a list subscription.
  */
 
 /**
@@ -70,13 +64,11 @@ export class ListSubscriptionError extends Error {
  *     state: ListSubscriptionState,
  *     listInstance: import('./listInstance.js').ListInstance,
  *     loadingError: import('./loadingError.js').LoadingErrorStatus,
- * }} ListSubscriptionContext
+ * }} ListSubscriptionContext - The context (state, list instance, and loading/error status) bound to the shared list subscription functions.
  */
 
 /**
- * The properties of a list subscription.
- *
- * @typedef {object} ListSubscriptionProperties
+ * @typedef {object} ListSubscriptionProperties - The properties of a list subscription.
  * @property {ListSubscriptionState} state - The reactive state of the list subscription.
  * @property {import('./listInstance.js').ListInstance} listInstance - The list instance used by the subscription.
  * @property {import('./cancellableIntent.js').CancellableIntent} listIntent - The `CancellableIntent` instance managing if the list should be (re)fetched.
@@ -84,21 +76,16 @@ export class ListSubscriptionError extends Error {
  */
 
 /**
- * An instance of a list subscription, returned by `useListSubscription`.
- *
- * @typedef {ListSubscriptionFunctions & ListSubscriptionProperties} ListSubscription
+ * @typedef {ListSubscriptionFunctions & ListSubscriptionProperties} ListSubscription - An instance of a list subscription, returned by `useListSubscription`.
  */
 
 /**
- * @typedef {object} ListSubscriptionOwnOptions
+ * @typedef {object} ListSubscriptionOwnOptions - The options specific to a list subscription, namely an optional pre-built list instance to reuse.
  * @property {import("./listInstance.js").ListInstance} [listInstance] - A list instance to use instead of creating one.
  */
 
 /**
- * Defines the settings required to establish a list subscription, detailing how list instances should handle updates
- *  and subscriptions based on the given properties.
- *
- * @typedef {import("./listInstance.js").ListInstanceOptions & ListSubscriptionOwnOptions} ListSubscriptionOptions
+ * @typedef {import("./listInstance.js").ListInstanceOptions & ListSubscriptionOwnOptions} ListSubscriptionOptions - Defines the settings required to establish a list subscription, detailing how list instances should handle updates and subscriptions based on the given properties.
  */
 
 /**
@@ -352,5 +339,12 @@ export function useListSubscription({ listInstance, props, handlers }) {
         listIntent,
         subscribeIntent,
         clearError: proxyLoadingError.clearError,
+        // Stops both intents, mirroring useObjectSubscription, so a caller that owns this
+        // subscription's lifetime does not have to know its intent inventory. The wrapped
+        // instance keeps its state and still takes manual calls.
+        stop: () => {
+            listIntent.stop();
+            subscribeIntent.stop();
+        },
     };
 }

package/use/loading.js

@@ -1,25 +1,23 @@
 import { readonly, ref } from "vue";
 
 /**
- * @typedef {import("vue").Ref<boolean|undefined>} LoadingRef
- * @typedef {Readonly<LoadingRef>} LoadingReadonlyRef
+ * @typedef {import("vue").Ref<boolean|undefined>} LoadingRef - A Vue ref to the loading flag, which is a boolean or undefined.
+ * @typedef {Readonly<LoadingRef>} LoadingReadonlyRef - A readonly Vue ref to the loading flag, which is a boolean or undefined.
  */
 
 /**
- * @typedef {object} LoadingProperties
+ * @typedef {object} LoadingProperties - The reactive loading-state member (loading) contributed by the useLoading composable.
  * @property {LoadingReadonlyRef} loading - Whether the component is loading.
  */
 
 /**
- * @typedef {object} LoadingFunctions
+ * @typedef {object} LoadingFunctions - The loading-state actions (setLoading, clearLoading) contributed by the useLoading composable.
  * @property {() => void} setLoading - Set the loading state to true.
  * @property {() => void} clearLoading - Set the loading state to false.
  */
 
 /**
- * The loading state API.
- *
- * @typedef {LoadingProperties & LoadingFunctions} LoadingStatus
+ * @typedef {LoadingProperties & LoadingFunctions} LoadingStatus - The loading state API.
  */
 
 /**

package/use/loadingError.js

@@ -2,9 +2,9 @@ import { useLoading } from "./loading.js";
 import { useError } from "./error.js";
 
 /**
- * @typedef {import('./loading.js').LoadingProperties & import('./error.js').ErrorProperties} LoadingErrorProperties
- * @typedef {import('./loading.js').LoadingFunctions & import('./error.js').ErrorFunctions} LoadingErrorFunctions
- * @typedef {LoadingErrorProperties & LoadingErrorFunctions} LoadingErrorStatus
+ * @typedef {import('./loading.js').LoadingProperties & import('./error.js').ErrorProperties} LoadingErrorProperties - The combined reactive loading and error state members contributed by the useLoadingError composable.
+ * @typedef {import('./loading.js').LoadingFunctions & import('./error.js').ErrorFunctions} LoadingErrorFunctions - The combined loading and error state actions contributed by the useLoadingError composable.
+ * @typedef {LoadingErrorProperties & LoadingErrorFunctions} LoadingErrorStatus - The combined loading and error state API (properties plus actions) returned by useLoadingError.
  */
 
 /**