[store] useTableCellIdsListener

Author: jamesgpearce

src/types/docs/ui-react.js

@@ -2563,6 +2563,68 @@
  * @category Store hooks
  */
 /// useTableListener
+/**
+ * The useTableCellIdsListener hook registers a listener function with a Store
+ * that will be called whenever the Cell Ids that appear anywhere in a Table
+ * change.
+ *
+ * This hook is useful for situations where a component needs to register its
+ * own specific listener to do more than simply tracking the value (which is
+ * more easily done with the useTableCellIds hook).
+ *
+ * You can either listen to a single Table (by specifying its Id as the method's
+ * first parameter) or changes to any Table (by providing `null`).
+ *
+ * Unlike the addTableCellIdsListener method, which returns a listener Id and
+ * requires you to remove it manually, the useTableCellIdsListener hook manages
+ * this lifecycle for you: when the listener changes (per its `listenerDeps`
+ * dependencies) or the component unmounts, the listener on the underlying Store
+ * will be deleted.
+ *
+ * @param tableId The Id of the Table to listen to, or `null` as a wildcard.
+ * @param listener The function that will be called whenever the Cell Ids that
+ * appear anywhere in a 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 useTableCellIdsListener 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
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => {
+ *   useTableCellIdsListener('pets', () => console.log('Cell Ids changed'));
+ *   return <span>App</span>;
+ * };
+ *
+ * const store = createStore().setTables({pets: {fido: {color: 'brown'}}});
+ * const app = document.createElement('div');
+ * const root = ReactDOMClient.createRoot(app);
+ * root.render(<App store={store} />); // !act
+ * console.log(store.getListenerStats().tableCellIds);
+ * // -> 1
+ *
+ * store.setRow('pets', 'felix', {species: 'cat'}); // !act
+ * // -> 'Cell Ids changed'
+ *
+ * root.unmount(); // !act
+ * console.log(store.getListenerStats().rowIds);
+ * // -> 0
+ * ```
+ * @category Store hooks
+ */
+/// useTableCellIdsListener
 /**
  * The useRowIdsListener hook registers a listener function with a Store that
  * will be called whenever the Row Ids in a Table change.

src/types/ui-react.d.ts

@@ -14,6 +14,7 @@ import {
   SortedRowIdsListener,
   Store,
   Table,
+  TableCellIdsListener,
   TableIdsListener,
   TableListener,
   Tables,
@@ -309,6 +310,15 @@ export function useTableListener(
   storeOrStoreId?: StoreOrStoreId,
 ): void;
 
+/// useTableCellIdsListener
+export function useTableCellIdsListener(
+  tableId: IdOrNull,
+  listener: TableCellIdsListener,
+  listenerDeps?: React.DependencyList,
+  mutator?: boolean,
+  storeOrStoreId?: StoreOrStoreId,
+): void;
+
 /// useRowIdsListener
 export function useRowIdsListener(
   tableId: IdOrNull,

src/types/with-schemas/ui-react.d.ts

@@ -56,6 +56,7 @@ import {
   SortedRowIdsListener,
   Store,
   Table,
+  TableCellIdsListener,
   TableIdsListener,
   TableListener,
   Tables,
@@ -426,6 +427,17 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     storeOrStoreId?: StoreOrStoreId<Schemas>,
   ) => void;
 
+  /// useTableCellIdsListener
+  useTableCellIdsListener: <
+    TableIdOrNull extends TableIdFromSchema<Schemas[0]> | null,
+  >(
+    tableId: TableIdOrNull,
+    listener: TableCellIdsListener<Schemas, TableIdOrNull>,
+    listenerDeps?: React.DependencyList,
+    mutator?: boolean,
+    storeOrStoreId?: StoreOrStoreId<Schemas>,
+  ) => void;
+
   /// useRowIdsListener
   useRowIdsListener: <
     TableIdOrNull extends TableIdFromSchema<Schemas[0]> | null,

src/ui-react/hooks.ts

@@ -34,6 +34,7 @@ import {
   SortedRowIdsListener,
   Store,
   Table,
+  TableCellIdsListener,
   TableIdsListener,
   TableListener,
   Tables,
@@ -124,6 +125,7 @@ import {
   useSortedRowIds as useSortedRowIdsDecl,
   useSortedRowIdsListener as useSortedRowIdsListenerDecl,
   useTableCellIds as useTableCellIdsDecl,
+  useTableCellIdsListener as useTableCellIdsListenerDecl,
   useTable as useTableDecl,
   useTableIds as useTableIdsDecl,
   useTableIdsListener as useTableIdsListenerDecl,
@@ -674,6 +676,22 @@ export const useTableListener: typeof useTableListenerDecl = (
     mutator,
   );
 
+export const useTableCellIdsListener: typeof useTableCellIdsListenerDecl = (
+  tableId: IdOrNull,
+  listener: TableCellIdsListener,
+  listenerDeps?: React.DependencyList,
+  mutator?: boolean,
+  storeOrStoreId?: StoreOrStoreId,
+): void =>
+  useListener(
+    TABLE + CELL_IDS,
+    useStoreOrStoreId(storeOrStoreId),
+    listener,
+    listenerDeps,
+    [tableId],
+    mutator,
+  );
+
 export const useRowIdsListener: typeof useRowIdsListenerDecl = (
   tableId: IdOrNull,
   listener: RowIdsListener,