[state] useTableState

Author: jamesgpearce

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

@@ -1016,6 +1016,68 @@
  * @since v1.0.0
  */
 /// useTable
+/**
+ * The useTableState hook returns a Table and a function to set it, following
+ * the same pattern as React's useState hook.
+ *
+ * This is a convenience hook that combines the useTable and useSetTableCallback
+ * hooks. It's useful when you need both read and write access to a Table in a
+ * single component.
+ *
+ * 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 useTableState hook lets you indicate which Store to use: omit the final
+ * parameter for the default context Store, provide an Id for a named context
+ * Store, or provide a Store explicitly by reference.
+ * @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 containing the Table and a function to set it.
+ * @example
+ * This example creates a Store outside the application, which is used in the
+ * useTableState hook by reference. A button updates the Table when clicked.
+ *
+ * ```jsx
+ * import {createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {useTableState} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setTable('pets', {fido: {species: 'dog'}});
+ * const App = () => {
+ *   const [table, setTable] = useTableState('pets', store);
+ *   return (
+ *     <div>
+ *       {JSON.stringify(table)}
+ *       <button onClick={() => setTable({...table, felix: {species: 'cat'}})}>
+ *         Add
+ *       </button>
+ *     </div>
+ *   );
+ * };
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div>{"fido":{"species":"dog"}}<button>Add</button></div>'
+ *
+ * const button = app.querySelector('button');
+ * // -> button MouseEvent('click', {bubbles: true})
+ * console.log(app.innerHTML);
+ * // ->
+ * `
+ * <div>
+ *   {"fido":{"species":"dog"},"felix":{"species":"cat"}}
+ *   <button>Add</button>
+ * </div>
+ * `;
+ * ```
+ * @category State hooks
+ * @since v7.3.0
+ */
+/// useTableState
 /**
  * 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

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

@@ -163,6 +163,12 @@ export function useHasTable(
 /// useTable
 export function useTable(tableId: Id, storeOrStoreId?: StoreOrStoreId): Table;
 
+/// useTableState
+export function useTableState(
+  tableId: Id,
+  storeOrStoreId?: StoreOrStoreId,
+): [Table, (table: Table) => void];
+
 /// useTableCellIds
 export function useTableCellIds(
   tableId: Id,

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

@@ -216,6 +216,15 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     storeOrStoreId?: StoreOrStoreId<Schemas>,
   ) => Table<Schemas[0], TableId>;
 
+  /// useTableState
+  useTableState: <TableId extends TableIdFromSchema<Schemas[0]>>(
+    tableId: TableId,
+    storeOrStoreId?: StoreOrStoreId<Schemas>,
+  ) => [
+    Table<Schemas[0], TableId>,
+    (table: Table<Schemas[0], TableId>) => void,
+  ];
+
   /// useTableCellIds
   useTableCellIds: <TableId extends TableIdFromSchema<Schemas[0]>>(
     tableId: TableId,

src/ui-react/hooks.ts

@@ -239,6 +239,7 @@ import type {
   useTableIds as useTableIdsDecl,
   useTableIdsListener as useTableIdsListenerDecl,
   useTableListener as useTableListenerDecl,
+  useTableState as useTableStateDecl,
   useTables as useTablesDecl,
   useTablesListener as useTablesListenerDecl,
   useUndoInformation as useUndoInformationDecl,
@@ -670,6 +671,14 @@ export const useTable: typeof useTableDecl = (
     tableId,
   ]);
 
+export const useTableState: typeof useTableStateDecl = (
+  tableId: Id,
+  storeOrStoreId?: StoreOrStoreId,
+): [Table, (table: Table) => void] => [
+  useTable(tableId, storeOrStoreId),
+  useSetTableCallback(tableId, (table) => table, [], storeOrStoreId),
+];
+
 export const useTableCellIds: typeof useTableCellIdsDecl = (
   tableId: Id,
   storeOrStoreId?: StoreOrStoreId,

test/unit/core/ui-react/hooks.test.tsx

@@ -152,6 +152,7 @@ import {
   useTableIds,
   useTableIdsListener,
   useTableListener,
+  useTableState,
   useTables,
   useTablesListener,
   useUndoInformation,
@@ -1174,6 +1175,37 @@ describe('Read Hooks', () => {
     unmount();
   });
 
+  test('useTableState', () => {
+    const Test = () => {
+      const [table, setTable] = useTableState('t1', store);
+      return (
+        <span>
+          {JSON.stringify(table)}
+          <button onClick={() => setTable({...table, r2: {c1: 2}})} />
+        </span>
+      );
+    };
+
+    store.setTable('t1', {r1: {c1: 1}});
+    const {container, unmount} = render(<Test />);
+
+    expect(container.innerHTML).toEqual(
+      '<span>{"r1":{"c1":1}}<button></button></span>',
+    );
+
+    act(() => fireEvent.click(container.querySelector('button') as Element));
+    expect(container.innerHTML).toEqual(
+      '<span>{"r1":{"c1":1},"r2":{"c1":2}}<button></button></span>',
+    );
+
+    act(() => fireEvent.click(container.querySelector('button') as Element));
+    expect(container.innerHTML).toEqual(
+      '<span>{"r1":{"c1":1},"r2":{"c1":2}}<button></button></span>',
+    );
+
+    unmount();
+  });
+
   test('useTableCellIds', () => {
     const Test = ({tableId}: {tableId: Id}) =>
       didRender(JSON.stringify(useTableCellIds(tableId, store)));