@arrai-innovations/reactive-helpers 21.1.2 → 22.1.0

package/types/use/listInstance.d.ts

@@ -1,15 +1,11 @@
 /**
- * The reactive arguments for the list instance.
- *
- * @typedef {object} ListInstanceProps
+ * @typedef {object} ListInstanceProps - The reactive arguments for the list instance.
  * @property {string} pkKey - The primary key field for the list objects.
  * @property {object} params - The arguments passed to the server.
  * @property {object} target - Implementation specific arguments.
  */
 /**
- * The configuration options used to create a list instance.
- *
- * @typedef {object} ListInstanceOptions
+ * @typedef {object} ListInstanceOptions - The configuration options used to create a list instance.
  * @property {import('vue').UnwrapNestedRefs<ListInstanceProps>} props - The props for the list instance.
  * @property {object} [handlers] - Default implementation are used as set by `setListCrud`.
  * @property {import('../config/listCrud.js').CrudListFn} [handlers.list] - Provide the implementation for the list
@@ -22,22 +18,16 @@
  *  subscribe function.
  */
 /**
- * The objects by pk.
- *
- * @typedef {{[pk: import('../config/commonCrud.js').Pk]: import('../use/objectInstance.js').ExistingCrudObject}} ObjectsByPk
+ * @typedef {{[pk: import('../config/commonCrud.js').Pk]: import('../use/objectInstance.js').ExistingCrudObject}} ObjectsByPk - The objects by pk.
  */
 /**
- * The objects in order, based on .order & .objects.
- *
- * @typedef {import('vue').ComputedRef<import('../use/objectInstance.js').ExistingCrudObject[]>} ObjectsInOrder
+ * @typedef {import('vue').ComputedRef<import('../use/objectInstance.js').ExistingCrudObject[]>} ObjectsInOrder - The objects in order, based on .order & .objects.
  */
 /**
- * The order of the objects in the list.
- *
- * @typedef {import('vue').ComputedRef<import('../config/commonCrud.js').Pk[]>} ListOrder
+ * @typedef {import('vue').ComputedRef<import('../config/commonCrud.js').Pk[]>} ListOrder - The order of the objects in the list.
  */
 /**
- * @typedef {object} ListInstanceRawStateCrud
+ * @typedef {object} ListInstanceRawStateCrud - The raw CRUD handlers and target args stored in a list instance's reactive state.
  * @property {import('vue').Reactive<import('../config/objectCrud.js').TargetArgs|{}>} args - The arguments to be passed to the crud handlers.
  * @property {import('../config/listCrud.js').CrudListFn} list - The list function.
  * @property {import('../config/listCrud.js').CrudListSubscribeFn} subscribe - The subscribe function.
@@ -45,64 +35,57 @@
  * @property {import('../config/listCrud.js').CrudExecuteActionFn} executeAction - The execute action function.
  */
 /**
- * @typedef {Map<import('../config/commonCrud.js').Pk, import('vue').Reactive<import('../use/objectInstance.js').ExistingCrudObject>>} ObjectsMap
+ * @typedef {Map<import('../config/commonCrud.js').Pk, import('vue').Reactive<import('../use/objectInstance.js').ExistingCrudObject>>} ObjectsMap - A Map of primary keys to the list's reactive existing objects.
  */
 /**
- * @typedef {object} PaginateInfo
+ * @typedef {object} PaginateInfo - Pagination details for a list, including total records, total pages, per-page count, and current page.
  * @property {number} [totalRecords] - The total records.
  * @property {number} [totalPages] - The total pages.
  * @property {number} [perPage] - The per page.
  * @property {number} [page] - The page you are giving us results for.
  */
 /**
- * @typedef {{ [key: string]: number | string }} ColumnTotals
+ * @typedef {{ [key: string]: number | string }} ColumnTotals - A map of column names to their aggregate total values for a list.
  */
 /**
- * The raw state object for the list instance, defining the reactive properties and their types.
- *
- * @typedef {object} ListInstanceRawMyState
+ * @typedef {object} ListInstanceRawMyState - The raw state object for the list instance, defining the reactive properties and their types.
  * @property {import('vue').Reactive<ListInstanceRawStateCrud>} crud - CRUD handlers and their configurations for the list.
  * @property {string} pkKey - The primary key field for the list objects.
  * @property {object} params - Arguments passed to the server for listing operations.
  * @property {ObjectsMap} objectsMap - The map of objects stored by their pks.
  * @property {ObjectsByPk} objects - The list objects stored by their pks.
+ * @property {number} objectsVersion - Increments when the set of object keys changes.
  * @property {ListOrder} order - The order of objects in the list.
  * @property {ObjectsInOrder} objectsInOrder - The objects in the order specified by the list.
  * @property {import('vue').ShallowReactive<PaginateInfo>} paginateInfo - Pagination information for the list.
  * @property {import('vue').ShallowReactive<ColumnTotals>} columnTotals - Column totals for the list.
  */
 /**
- * @typedef {ListInstanceRawMyState & Pick<import('./loadingError.js').LoadingErrorStatus, "loading" | "error" | "errored">} ListInstanceRawState
+ * @typedef {ListInstanceRawMyState & Pick<import('./loadingError.js').LoadingErrorStatus, "loading" | "error" | "errored">} ListInstanceRawState - The raw, pre-unwrapped state of a list instance, combining its own state with loading and error status.
  */
 /**
- * Defines the reactive state used by the list instance.
- *
- * @typedef {import('vue').UnwrapNestedRefs<ListInstanceRawState>} ListInstanceState
+ * @typedef {import('vue').UnwrapNestedRefs<ListInstanceRawState>} ListInstanceState - Defines the reactive state used by the list instance.
  */
 /**
- * @typedef {(newObjects: import('../use/objectInstance.js').ExistingCrudObject[]) => void} PushObjectsFn
+ * @typedef {(newObjects: import('../use/objectInstance.js').ExistingCrudObject[]) => void} PushObjectsFn - Signature for the function that pushes a page of newly received objects into the list.
  */
 /**
- * Options to control which reactive state is reset when clearing the list.
- *
- * @typedef {object} ClearListOptions
+ * @typedef {object} ClearListOptions - Options to control which reactive state is reset when clearing the list.
  * @property {boolean} [keepPagination] - When true, keep the current pagination information.
  * @property {boolean} [keepColumnTotals] - When true, keep the current column totals.
  * @property {boolean} [keepError] - When true, keep the current error state.
  */
 /**
- * @typedef {(options?: ClearListOptions) => void} ClearListFn
+ * @typedef {(options?: ClearListOptions) => void} ClearListFn - Signature for the handler that clears the objects held by the list.
  */
 /**
- * @typedef {(info: PaginateInfo) => void} SetPaginateInfoFn
+ * @typedef {(info: PaginateInfo) => void} SetPaginateInfoFn - Signature for the handler that updates the list's pagination information.
  */
 /**
- * @typedef {(total: ColumnTotals) => void} SetColumnTotalsFn
+ * @typedef {(total: ColumnTotals) => void} SetColumnTotalsFn - Signature for the handler that updates the list's column totals.
  */
 /**
- * Defines the methods provided by the list instance for managing objects in the list.
- *
- * @typedef {object} ListInstanceMyFunctions
+ * @typedef {object} ListInstanceMyFunctions - Defines the methods provided by the list instance for managing objects in the list.
  * @property {PushObjectsFn} pushObjects - Customizable callback for handling new objects per page.
  * @property {(object: import('../use/objectInstance.js').ExistingCrudObject) => void} addListObject - Adds an object to the list.
  * @property {(object: import('../use/objectInstance.js').ExistingCrudObject) => void} updateListObject - Updates an object in the list.
@@ -117,17 +100,13 @@
  * @property {(total: ColumnTotals) => void} setColumnTotals - The method to update column totals.
  */
 /**
- * @typedef {ListInstanceMyFunctions & Pick<import('./loadingError.js').LoadingErrorStatus, "clearError">} ListInstanceFunctions
+ * @typedef {ListInstanceMyFunctions & Pick<import('./loadingError.js').LoadingErrorStatus, "clearError">} ListInstanceFunctions - The methods contributed by the list instance, including its CRUD operations plus clearError.
  */
 /**
- * Helper type to facilitate the combination of state and functions into a single type.
- *
- * @typedef {{state: ListInstanceState}} ListInstanceStateMixIn
+ * @typedef {{state: ListInstanceState}} ListInstanceStateMixIn - Helper type to facilitate the combination of state and functions into a single type.
  */
 /**
- * The list instance, combining state management and functional operations for managing a list of objects.
- *
- * @typedef {ListInstanceStateMixIn & ListInstanceFunctions} ListInstance
+ * @typedef {ListInstanceStateMixIn & ListInstanceFunctions} ListInstance - The list instance, combining state management and functional operations for managing a list of objects.
  */
 /**
  * Creates and manages multiple list instances.
@@ -188,7 +167,7 @@ export function useListInstances(listInstanceArgs: {
  * ```
  *
  * @param {ListInstanceOptions} options - Specifies the configuration options for creating a list instance, including
- *  properties for CRUD operations and UI behaviors like page persistence.
+ *  properties for CRUD operations and UI behaviours like page persistence.
  * @returns {ListInstance} The list instance.
  * @throws {ListInstanceError} If the props are missing.
  */
@@ -217,15 +196,15 @@ export class ListInstanceError extends Error {
  */
 export type ListInstanceProps = {
     /**
-     * - The primary key field for the list objects.
+     * The primary key field for the list objects.
      */
     pkKey: string;
     /**
-     * - The arguments passed to the server.
+     * The arguments passed to the server.
      */
     params: object;
     /**
-     * - Implementation specific arguments.
+     * Implementation specific arguments.
      */
     target: object;
 };
@@ -234,11 +213,11 @@ export type ListInstanceProps = {
  */
 export type ListInstanceOptions = {
     /**
-     * - The props for the list instance.
+     * The props for the list instance.
      */
     props: import("vue").UnwrapNestedRefs<ListInstanceProps>;
     /**
-     * - Default implementation are used as set by `setListCrud`.
+     * Default implementation are used as set by `setListCrud`.
      */
     handlers?: {
         list?: import("../config/listCrud.js").CrudListFn;
@@ -261,47 +240,59 @@ export type ObjectsInOrder = import("vue").ComputedRef<import("../use/objectInst
  * The order of the objects in the list.
  */
 export type ListOrder = import("vue").ComputedRef<import("../config/commonCrud.js").Pk[]>;
+/**
+ * The raw CRUD handlers and target args stored in a list instance's reactive state.
+ */
 export type ListInstanceRawStateCrud = {
     /**
-     * - The arguments to be passed to the crud handlers.
+     * The arguments to be passed to the crud handlers.
      */
     args: import("vue").Reactive<import("../config/objectCrud.js").TargetArgs | {}>;
     /**
-     * - The list function.
+     * The list function.
      */
     list: import("../config/listCrud.js").CrudListFn;
     /**
-     * - The subscribe function.
+     * The subscribe function.
      */
     subscribe: import("../config/listCrud.js").CrudListSubscribeFn;
     /**
-     * - The bulk delete function.
+     * The bulk delete function.
      */
     bulkDelete: import("../config/listCrud.js").CrudBulkDeleteFn;
     /**
-     * - The execute action function.
+     * The execute action function.
      */
     executeAction: import("../config/listCrud.js").CrudExecuteActionFn;
 };
+/**
+ * A Map of primary keys to the list's reactive existing objects.
+ */
 export type ObjectsMap = Map<import("../config/commonCrud.js").Pk, import("vue").Reactive<import("../use/objectInstance.js").ExistingCrudObject>>;
+/**
+ * Pagination details for a list, including total records, total pages, per-page count, and current page.
+ */
 export type PaginateInfo = {
     /**
-     * - The total records.
+     * The total records.
      */
     totalRecords?: number;
     /**
-     * - The total pages.
+     * The total pages.
      */
     totalPages?: number;
     /**
-     * - The per page.
+     * The per page.
      */
     perPage?: number;
     /**
-     * - The page you are giving us results for.
+     * The page you are giving us results for.
      */
     page?: number;
 };
+/**
+ * A map of column names to their aggregate total values for a list.
+ */
 export type ColumnTotals = {
     [key: string]: number | string;
 };
@@ -310,123 +301,145 @@ export type ColumnTotals = {
  */
 export type ListInstanceRawMyState = {
     /**
-     * - CRUD handlers and their configurations for the list.
+     * CRUD handlers and their configurations for the list.
      */
     crud: import("vue").Reactive<ListInstanceRawStateCrud>;
     /**
-     * - The primary key field for the list objects.
+     * The primary key field for the list objects.
      */
     pkKey: string;
     /**
-     * - Arguments passed to the server for listing operations.
+     * Arguments passed to the server for listing operations.
      */
     params: object;
     /**
-     * - The map of objects stored by their pks.
+     * The map of objects stored by their pks.
      */
     objectsMap: ObjectsMap;
     /**
-     * - The list objects stored by their pks.
+     * The list objects stored by their pks.
      */
     objects: ObjectsByPk;
     /**
-     * - The order of objects in the list.
+     * Increments when the set of object keys changes.
+     */
+    objectsVersion: number;
+    /**
+     * The order of objects in the list.
      */
     order: ListOrder;
     /**
-     * - The objects in the order specified by the list.
+     * The objects in the order specified by the list.
      */
     objectsInOrder: ObjectsInOrder;
     /**
-     * - Pagination information for the list.
+     * Pagination information for the list.
      */
     paginateInfo: import("vue").ShallowReactive<PaginateInfo>;
     /**
-     * - Column totals for the list.
+     * Column totals for the list.
      */
     columnTotals: import("vue").ShallowReactive<ColumnTotals>;
 };
+/**
+ * The raw, pre-unwrapped state of a list instance, combining its own state with loading and error status.
+ */
 export type ListInstanceRawState = ListInstanceRawMyState & Pick<import("./loadingError.js").LoadingErrorStatus, "loading" | "error" | "errored">;
 /**
  * Defines the reactive state used by the list instance.
  */
 export type ListInstanceState = import("vue").UnwrapNestedRefs<ListInstanceRawState>;
+/**
+ * Signature for the function that pushes a page of newly received objects into the list.
+ */
 export type PushObjectsFn = (newObjects: import("../use/objectInstance.js").ExistingCrudObject[]) => void;
 /**
  * Options to control which reactive state is reset when clearing the list.
  */
 export type ClearListOptions = {
     /**
-     * - When true, keep the current pagination information.
+     * When true, keep the current pagination information.
      */
     keepPagination?: boolean;
     /**
-     * - When true, keep the current column totals.
+     * When true, keep the current column totals.
      */
     keepColumnTotals?: boolean;
     /**
-     * - When true, keep the current error state.
+     * When true, keep the current error state.
      */
     keepError?: boolean;
 };
+/**
+ * Signature for the handler that clears the objects held by the list.
+ */
 export type ClearListFn = (options?: ClearListOptions) => void;
+/**
+ * Signature for the handler that updates the list's pagination information.
+ */
 export type SetPaginateInfoFn = (info: PaginateInfo) => void;
+/**
+ * Signature for the handler that updates the list's column totals.
+ */
 export type SetColumnTotalsFn = (total: ColumnTotals) => void;
 /**
  * Defines the methods provided by the list instance for managing objects in the list.
  */
 export type ListInstanceMyFunctions = {
     /**
-     * - Customizable callback for handling new objects per page.
+     * Customizable callback for handling new objects per page.
      */
     pushObjects: PushObjectsFn;
     /**
-     * - Adds an object to the list.
+     * Adds an object to the list.
      */
     addListObject: (object: import("../use/objectInstance.js").ExistingCrudObject) => void;
     /**
-     * - Updates an object in the list.
+     * Updates an object in the list.
      */
     updateListObject: (object: import("../use/objectInstance.js").ExistingCrudObject) => void;
     /**
-     * - Deletes an object from the list by pk.
+     * Deletes an object from the list by pk.
      */
     deleteListObject: (objectId: import("../config/commonCrud.js").PkInput) => void;
     /**
-     * - Clears the list objects and optionally keeps pagination, totals,
+     * Clears the list objects and optionally keeps pagination, totals,
      * or error state.
      */
     clearList: (options?: ClearListOptions) => void;
     /**
-     * - Generates a unique fake pk for use within the list.
+     * Generates a unique fake pk for use within the list.
      */
     getFakePk: () => import("../config/commonCrud.js").Pk;
     /**
-     * - Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.
+     * Initiates a fetch to retrieve objects according to the CRUD configuration, returning a promise to a boolean indicating success.
      */
     list: (args?: import("../config/listCrud.js").AdditionalListArgs) => import("../utils/cancellablePromise.js").MaybeCancellablePromise<boolean | never>;
     /**
-     * - Deletes objects from the list by pk, returning a promise to a boolean indicating success.
+     * Deletes objects from the list by pk, returning a promise to a boolean indicating success.
      */
     bulkDelete: (args?: {
         pks?: import("../config/commonCrud.js").Pk[];
     } & import("../config/listCrud.js").AdditionalListArgs) => Promise<boolean>;
     /**
-     * - Initiates an action on all objects in the list, returning the response, or null if the action failed.
+     * Initiates an action on all objects in the list, returning the response, or null if the action failed.
      */
     executeAction: (args: {
         action: string;
         pks?: import("../config/commonCrud.js").Pk[];
     } & import("../config/listCrud.js").AdditionalListArgs) => Promise<object | string | boolean | null>;
     /**
-     * - The method to update pagination information.
+     * The method to update pagination information.
      */
     setPaginateInfo: (info: PaginateInfo) => void;
     /**
-     * - The method to update column totals.
+     * The method to update column totals.
      */
     setColumnTotals: (total: ColumnTotals) => void;
 };
+/**
+ * The methods contributed by the list instance, including its CRUD operations plus clearError.
+ */
 export type ListInstanceFunctions = ListInstanceMyFunctions & Pick<import("./loadingError.js").LoadingErrorStatus, "clearError">;
 /**
  * Helper type to facilitate the combination of state and functions into a single type.

package/types/use/listRelated.d.ts

@@ -5,87 +5,68 @@
  * @module use/listRelated.js
  */
 /**
- * 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.
  * @property {import('vue').Ref<boolean>} running - General flag that indicates if the list-related logic is processing, used to manage UI feedback or prevent concurrent operations.
  */
 /**
- * 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.
  */
 /**
- * An instance of `useListRelated`.
- *
- * @typedef {ListRelatedProperties} ListRelated
+ * @typedef {ListRelatedProperties} ListRelated - An instance of `useListRelated`.
  */
 /**
  * Creates and manages multiple instances of list-related properties, linking each to corresponding parent instances
@@ -182,16 +163,16 @@ export function useListRelated({ parentState, relatedObjectsRules }: ListRelated
  */
 export type ListRelatedRule = {
     /**
-     * - Specifies the foreign key used to link objects across lists. Planned to be renamed to
-     * 'fkKey' to better reflect its usage.
+     * 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.
      */
-    pkKey: string;
+    pkKey?: string;
     /**
-     * - Specifies the order in which related objects should be sorted, if applicable.
+     * Specifies the order in which related objects should be sorted, if applicable.
      */
     order?: string[];
     /**
-     * - The objects that can be related based on the foreign key.
+     * The objects that can be related based on the foreign key.
      */
     objects: import("./listInstance.js").ObjectsByPk;
 };
@@ -202,24 +183,23 @@ export type ListRelatedRules = {
     [rule: string]: ListRelatedRule;
 };
 /**
- * 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.
+ * 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.
  */
 export type ListRelatedRawState = {
     /**
-     * - Stores computed references to related objects, allowing for dynamic access based on object pk and specific rules.
+     * 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`.
      */
     relatedObjects: {
         [pk: import("../config/commonCrud.js").Pk]: {
-            [rule: string]: import("vue").ComputedRef<any>;
+            [rule: string]: any;
         };
     };
     /**
-     * - Defines the rules for establishing relationships, such as foreign key links and sorting orders.
+     * Defines the rules for establishing relationships, such as foreign key links and sorting orders.
      */
     relatedObjectsRules: ListRelatedRules;
     /**
-     * - Maps each object pk and rule to a tuple consisting of the related object and its respective key, facilitating direct data manipulation.
+     * 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.
      */
     objAndKeyForPkAndRule: {
         [pk: import("../config/commonCrud.js").Pk]: {
@@ -227,27 +207,27 @@ export type ListRelatedRawState = {
         };
     };
     /**
-     * - Maintains computed references to the foreign keys for each object pk and rule, crucial for navigating complex data relationships.
+     * 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.
      */
     fkForPkAndRule: {
         [pk: import("../config/commonCrud.js").Pk]: {
-            [rule: string]: import("vue").ComputedRef<any>;
+            [rule: string]: any;
         };
     };
     /**
-     * - Flags whether the watch on parent state objects is currently active, ensuring updates trigger as needed.
+     * Flags whether the watch on parent state objects is currently active, ensuring updates trigger as needed.
      */
     relatedObjectsParentStateObjectsWatchRunning: boolean;
     /**
-     * - Indicates if watches on the related objects themselves are active, managing updates efficiently.
+     * Indicates if watches on the related objects themselves are active, managing updates efficiently.
      */
     relatedObjectsWatchRunning: boolean;
     /**
-     * - Signals whether any computations related to object relationships are currently in progress.
+     * Signals whether any computations related to object relationships are currently in progress.
      */
     relatedRunning: boolean;
     /**
-     * - General flag that indicates if the list-related logic is processing, used to manage UI feedback or prevent concurrent operations.
+     * General flag that indicates if the list-related logic is processing, used to manage UI feedback or prevent concurrent operations.
      */
     running: import("vue").Ref<boolean>;
 };
@@ -268,11 +248,11 @@ export type ListRelatedState = import("vue").UnwrapNestedRefs<ListRelatedParentR
  */
 export type ListRelatedOptions = {
     /**
-     * - The parent state object.
+     * The parent state object.
      */
     parentState: ListRelatedParentState;
     /**
-     * - The rules for the related objects.
+     * The rules for the related objects.
      */
     relatedObjectsRules: import("vue").Ref<ListRelatedRules>;
 };
@@ -281,15 +261,15 @@ export type ListRelatedOptions = {
  */
 export type ListRelatedProperties = {
     /**
-     * - The state for the list related property.
+     * The state for the list related property.
      */
     state: ListRelatedState;
     /**
-     * - The parent state object.
+     * The parent state object.
      */
     parentState: ListRelatedParentState;
     /**
-     * - Stops all effects of the list related property.
+     * Stops all effects of the list related property.
      */
     stop: () => void;
 };