tinybase 3.2.0-beta.0 → 3.3.0

package/lib/types/ui-react.d.ts

@@ -37,6 +37,7 @@ import {
   SortedRowIdsListener,
   Store,
   Table,
+  TableCellIdsListener,
   TableIdsListener,
   TableListener,
   Tables,
@@ -580,6 +581,92 @@ export function useTableIds(storeOrStoreId?: StoreOrStoreId): Ids;
  */
 export function useTable(tableId: Id, storeOrStoreId?: StoreOrStoreId): Table;
 
+/**
+ * The useTableCellIds hook returns the Ids of every Cell used across the whole
+ * Table, and registers a listener so that any changes to that result will cause
+ * a re-render.
+ *
+ * A Provider component is used to wrap part of an application in a context, and
+ * it can contain a default Store or a set of Store objects named by Id. The
+ * useTableCellIds hook lets you indicate which Store to get data for: omit the
+ * optional final parameter for the default context Store, provide an Id for a
+ * named context Store, or provide a Store explicitly by reference.
+ *
+ * When first rendered, this hook will create a listener so that changes to the
+ * Table Cell Ids will cause a re-render. When the component containing this
+ * hook is unmounted, the listener will be automatically removed.
+ *
+ * @param tableId The Id of the Table in the Store.
+ * @param storeOrStoreId The Store to be accessed: omit for the default context
+ * Store, provide an Id for a named context Store, or provide an explicit
+ * reference.
+ * @returns An array of the Ids of every Cell used across the whole Table.
+ * @example
+ * This example creates a Store outside the application, which is used in the
+ * useTableCellIds hook by reference. A change to the data in the Store
+ * re-renders the component.
+ *
+ * ```jsx
+ * const store = createStore().setCell('pets', 'fido', 'color', 'brown');
+ * const App = () => (
+ *   <span>{JSON.stringify(useTableCellIds('pets', store))}</span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * ReactDOMClient.createRoot(app).render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["color"]</span>'
+ *
+ * store.setCell('pets', 'felix', 'species', 'cat'); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["color","species"]</span>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a default Store is
+ * provided. A component within it then uses the useTableCellIds hook.
+ *
+ * ```jsx
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => <span>{JSON.stringify(useTableCellIds('pets'))}</span>;
+ *
+ * const store = createStore().setCell('pets', 'fido', 'color', 'brown');
+ * const app = document.createElement('div');
+ * ReactDOMClient.createRoot(app).render(<App store={store} />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["color"]</span>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a Store is provided, named
+ * by Id. A component within it then uses the useTableCellIds hook.
+ *
+ * ```jsx
+ * const App = ({store}) => (
+ *   <Provider storesById={{petStore: store}}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <span>{JSON.stringify(useTableCellIds('pets', 'petStore'))}</span>
+ * );
+ *
+ * const store = createStore().setCell('pets', 'fido', 'color', 'brown');
+ * const app = document.createElement('div');
+ * ReactDOMClient.createRoot(app).render(<App store={store} />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["color"]</span>'
+ * ```
+ * @category Store hooks
+ * @since v3.3
+ */
+export function useTableCellIds(
+  tableId: Id,
+  storeOrStoreId?: StoreOrStoreId,
+): Ids;
+
 /**
  * The useRowIds hook returns the Ids of every Row in a given Table, and
  * registers a listener so that any changes to that result will cause a
@@ -1563,6 +1650,13 @@ export function useSetRowCallback<Parameter>(
  * hook's `storeOrStoreId` parameter) is always automatically used as a hook
  * dependency for the callback.
  *
+ * The `reuseRowIds` parameter defaults to `true`, which means that if you
+ * delete a Row and then add another, the Id will be re-used - unless you delete
+ * the entire Table, in which case all Row Ids will reset. Otherwise, if you
+ * specify `reuseRowIds` to be `false`, then the Id will be a monotonically
+ * increasing string representation of an increasing integer, regardless of any
+ * you may have previously deleted.
+ *
  * @param tableId The Id of the Table in the Store.
  * @param getRow A function which returns the Row object that will be used to
  * update the Store, based on the parameter the callback will receive (and which
@@ -1578,6 +1672,9 @@ export function useSetRowCallback<Parameter>(
  * @param thenDeps An optional array of dependencies for the `then` function,
  * which, if any change, result in the regeneration of the callback. This
  * parameter defaults to an empty array.
+ * @param reuseRowIds Whether Ids should be recycled from previously deleted Row
+ * objects, defaulting to `true`.
+ *
  * @returns A parameterized callback for subsequent use.
  * @example
  * This example uses the useAddRowCallback hook to create an event handler which
@@ -1622,6 +1719,7 @@ export function useAddRowCallback<Parameter>(
   storeOrStoreId?: StoreOrStoreId,
   then?: (rowId: Id | undefined, store: Store, row: Row) => void,
   thenDeps?: React.DependencyList,
+  reuseRowIds?: boolean,
 ): ParameterizedCallback<Parameter>;
 
 /**
@@ -2696,6 +2794,75 @@ export function useTableListener(
   storeOrStoreId?: StoreOrStoreId,
 ): void;
 
+/**
+ * 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
+ */
+export function useTableCellIdsListener(
+  tableId: IdOrNull,
+  listener: TableCellIdsListener,
+  listenerDeps?: React.DependencyList,
+  mutator?: boolean,
+  storeOrStoreId?: StoreOrStoreId,
+): void;
+
 /**
  * The useRowIdsListener hook registers a listener function with a Store that
  * will be called whenever the Row Ids in a Table change.