[hooks] useSortedRowIdsListener object arg

Author: jamesgpearce

docs/api/ui-react/functions/store-hooks/usesortedrowidslistener/article.html

@@ -1523,7 +1523,6 @@
  * @since v2.0.0
  */
 /// useSortedRowIds
-
 /**
  * When called with an object as the first argument, the useSortedRowIds method
  * destructures it to make it easier to skip optional parameters.
@@ -1571,7 +1570,6 @@
  * @since v6.1.0
  */
 /// useSortedRowIds.2
-
 /**
  * The useHasRow hook returns a boolean indicating whether a given Row exists in
  * the Store, and registers a listener so that any changes to that result will
@@ -4428,6 +4426,67 @@
  * @since v2.0.0
  */
 /// useSortedRowIdsListener
+/**
+ * When called with an object as the first argument, the useSortedRowIds method
+ * destructures it to make it easier to skip optional parameters.
+ * @param args A SortedRowIdsArgs object containing the Id of the Table in the
+ * Store, and optional `cellId`, `descending`, `offset`, and `limit` parameters.
+ * @param listener The function that will be called whenever the sorted Row Ids
+ * in the Table change.
+ * @param listenerDeps An optional array of dependencies for the `listener`
+ * function, which, if any change, result in the re-registration of the
+ * listener. This parameter defaults to an empty array.
+ * @param mutator An optional boolean that indicates that the listener mutates
+ * Store data.
+ * @param storeOrStoreId The Store to register the listener with: omit for the
+ * default context Store, provide an Id for a named context Store, or provide an
+ * explicit reference.
+ * @example
+ * This example uses the useSortedRowIdsListener hook to create a listener that
+ * is scoped to a single component. When the component is unmounted, the
+ * listener is removed from the Store.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import {Provider, useSortedRowIdsListener} from 'tinybase/ui-react';
+ *
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => {
+ *   useSortedRowIdsListener({tableId: 'pets', cellId: 'species'}, () =>
+ *     console.log('Sorted Row Ids changed'),
+ *   );
+ *   return <span>App</span>;
+ * };
+ *
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App store={store} />); // !act
+ * console.log(store.getListenerStats().sortedRowIds);
+ * // -> 1
+ *
+ * store.setRow('pets', 'cujo', {species: 'wolf'}); // !act
+ * // -> 'Sorted Row Ids changed'
+ *
+ * root.unmount(); // !act
+ * console.log(store.getListenerStats().sortedRowIds);
+ * // -> 0
+ * ```
+ * @category Store hooks
+ * @since v6.1.0
+ */
+/// useSortedRowIdsListener.2
 /**
  * The useHasRowListener hook registers a listener function with the Store that
  * will be called when a Row is added to or removed from the Store.

docs/api/ui-react/functions/store-hooks/usesortedrowidslistener/index.html

@@ -489,6 +489,15 @@ export function useSortedRowIdsListener(
   storeOrStoreId?: StoreOrStoreId,
 ): void;
 
+/// useSortedRowIdsListener.2
+export function useSortedRowIdsListener(
+  args: SortedRowIdsArgs,
+  listener: SortedRowIdsListener,
+  listenerDeps?: React.DependencyList,
+  mutator?: boolean,
+  storeOrStoreId?: StoreOrStoreId,
+): void;
+
 /// useHasRowListener
 export function useHasRowListener(
   tableId: IdOrNull,

src/@types/ui-react/docs.js

@@ -623,24 +623,39 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     storeOrStoreId?: StoreOrStoreId<Schemas>,
   ) => void;
 
-  /// useSortedRowIdsListener
-  useSortedRowIdsListener: <
-    TableId extends TableIdFromSchema<Schemas[0]>,
-    CellIdOrUndefined extends CellIdFromSchema<Schemas[0], TableId> | undefined,
-    Descending extends boolean,
-    Offset extends number,
-    Limit extends number | undefined,
-  >(
-    tableId: TableId,
-    cellId: CellIdOrUndefined,
-    descending: Descending,
-    offset: Offset,
-    limit: Limit,
-    listener: SortedRowIdsListener<Schemas, TableId, CellIdOrUndefined>,
-    listenerDeps?: React.DependencyList,
-    mutator?: boolean,
-    storeOrStoreId?: StoreOrStoreId<Schemas>,
-  ) => void;
+  useSortedRowIdsListener: {
+    /// useSortedRowIdsListener
+    <
+      TableId extends TableIdFromSchema<Schemas[0]>,
+      CellIdOrUndefined extends
+        | CellIdFromSchema<Schemas[0], TableId>
+        | undefined,
+    >(
+      tableId: TableId,
+      cellId: CellIdOrUndefined,
+      descending: boolean,
+      offset: number,
+      limit: number | undefined,
+      listener: SortedRowIdsListener<Schemas, TableId, CellIdOrUndefined>,
+      listenerDeps?: React.DependencyList,
+      mutator?: boolean,
+      storeOrStoreId?: StoreOrStoreId<Schemas>,
+    ): void;
+
+    /// useSortedRowIdsListener.2
+    <
+      TableId extends TableIdFromSchema<Schemas[0]>,
+      CellIdOrUndefined extends
+        | CellIdFromSchema<Schemas[0], TableId>
+        | undefined,
+    >(
+      args: SortedRowIdsArgs<Schemas[0], TableId>,
+      listener: SortedRowIdsListener<Schemas, TableId, CellIdOrUndefined>,
+      listenerDeps?: React.DependencyList,
+      mutator?: boolean,
+      storeOrStoreId?: StoreOrStoreId<Schemas>,
+    ): void;
+  };
 
   /// useHasRowListener
   useHasRowListener: <

src/@types/ui-react/index.d.ts

@@ -496,6 +496,26 @@ const useSortedRowIdsImpl = (
     [tableId, cellId, descending, offset, limit],
   );
 
+export const useSortedRowIdsListenerImpl = (
+  tableId: Id,
+  cellId: Id | undefined,
+  descending: boolean,
+  offset: number,
+  limit: number | undefined,
+  listener: SortedRowIdsListener,
+  listenerDeps?: DependencyList,
+  mutator?: boolean,
+  storeOrStoreId?: StoreOrStoreId,
+): void =>
+  useListener(
+    SORTED_ROW_IDS,
+    useStoreOrStoreById(storeOrStoreId),
+    listener,
+    listenerDeps,
+    [tableId, cellId, descending, offset, limit],
+    mutator,
+  );
+
 // ---
 
 export const useCreateStore: typeof useCreateStoreDecl = (
@@ -1130,23 +1150,40 @@ export const useRowIdsListener: typeof useRowIdsListenerDecl = (
   );
 
 export const useSortedRowIdsListener: typeof useSortedRowIdsListenerDecl = (
-  tableId: Id,
-  cellId: Id | undefined,
-  descending: boolean,
-  offset: number,
-  limit: number | undefined,
-  listener: SortedRowIdsListener,
+  tableIdOrArgs: Id | SortedRowIdsArgs,
+  cellIdOrListener: Id | undefined | SortedRowIdsListener,
+  descendingOrListenerDeps: boolean | DependencyList | undefined,
+  offsetOrMutator: number | boolean | undefined,
+  limitOrStoreOrStoreId: number | undefined | StoreOrStoreId,
+  listener?: SortedRowIdsListener,
   listenerDeps?: DependencyList,
   mutator?: boolean,
   storeOrStoreId?: StoreOrStoreId,
 ): void =>
-  useListener(
-    SORTED_ROW_IDS,
-    useStoreOrStoreById(storeOrStoreId),
-    listener,
-    listenerDeps,
-    [tableId, cellId, descending, offset, limit],
-    mutator,
+  (useSortedRowIdsListenerImpl as any)(
+    ...(isObject(tableIdOrArgs)
+      ? [
+          tableIdOrArgs.tableId,
+          tableIdOrArgs.cellId,
+          tableIdOrArgs.descending ?? false,
+          tableIdOrArgs.offset ?? 0,
+          tableIdOrArgs.limit,
+          cellIdOrListener,
+          descendingOrListenerDeps,
+          offsetOrMutator,
+          limitOrStoreOrStoreId,
+        ]
+      : [
+          tableIdOrArgs,
+          cellIdOrListener,
+          descendingOrListenerDeps,
+          offsetOrMutator,
+          limitOrStoreOrStoreId,
+          listener,
+          listenerDeps,
+          mutator,
+          storeOrStoreId,
+        ]),
   );
 
 export const useHasRowListener: typeof useHasRowListenerDecl = (