tinybase 7.2.0 → 7.3.0-beta.1

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

@@ -848,6 +848,72 @@ export function useHasTables(storeOrStoreId?: StoreOrStoreId): boolean;
  */
 export function useTables(storeOrStoreId?: StoreOrStoreId): Tables;
 
+/**
+ * The useTablesState hook returns a Tables object and a function to set it,
+ * following the same pattern as React's useState hook.
+ *
+ * This is a convenience hook that combines the useTables and
+ * useSetTablesCallback hooks. It's useful when you need both read and write
+ * access to all Tables 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 useTablesState hook lets you indicate which Store to use: omit the
+ * parameter for the default context Store, provide an Id for a named context
+ * Store, or provide a Store explicitly by reference.
+ * @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 Tables object and a function to set it.
+ * @example
+ * This example creates a Store outside the application, which is used in the
+ * useTablesState hook by reference. A button updates the Tables when clicked.
+ *
+ * ```jsx
+ * import {createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {useTablesState} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const App = () => {
+ *   const [tables, setTables] = useTablesState(store);
+ *   return (
+ *     <div>
+ *       {JSON.stringify(tables)}
+ *       <button
+ *         onClick={() => setTables({...tables, species: {dog: {price: 5}}})}
+ *       >
+ *         Add
+ *       </button>
+ *     </div>
+ *   );
+ * };
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div>{"pets":{"fido":{"species":"dog"}}}<button>Add</button></div>'
+ *
+ * const _button = app.querySelector('button');
+ * // -> _button MouseEvent('click', {bubbles: true})
+ * console.log(app.innerHTML);
+ * // ->
+ * `
+ * <div>
+ *   {"pets":{"fido":{"species":"dog"}},"species":{"dog":{"price":5}}}
+ *   <button>Add</button>
+ * </div>
+ * `;
+ * ```
+ * @category State hooks
+ * @since v7.3.0
+ */
+export function useTablesState(
+  storeOrStoreId?: StoreOrStoreId,
+): [Tables, (tables: Tables) => void];
+
 /**
  * The useTableIds hook returns the Ids of every Table in a Store, and registers
  * a listener so that any changes to that result will cause a re-render.
@@ -1135,6 +1201,74 @@ export function useHasTable(
  */
 export function useTable(tableId: Id, storeOrStoreId?: StoreOrStoreId): Table;
 
+/**
+ * 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
+ */
+export function useTableState(
+  tableId: Id,
+  storeOrStoreId?: StoreOrStoreId,
+): [Table, (table: Table) => void];
+
 /**
  * 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
@@ -1924,6 +2058,68 @@ export function useRow(
   storeOrStoreId?: StoreOrStoreId,
 ): Row;
 
+/**
+ * The useRowState hook returns a Row and a function to set it, following the
+ * same pattern as React's useState hook.
+ *
+ * This is a convenience hook that combines the useRow and useSetRowCallback
+ * hooks. It's useful when you need both read and write access to a Row 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 useRowState 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 rowId The Id of the Row in the Table.
+ * @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 Row and a function to set it.
+ * @example
+ * This example creates a Store outside the application, which is used in the
+ * useRowState hook by reference. A button updates the Row when clicked.
+ *
+ * ```jsx
+ * import {createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {useRowState} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setTable('t1', {r1: {c1: 'Alice', c2: 30}});
+ * const App = () => {
+ *   const [row, setRow] = useRowState('t1', 'r1', store);
+ *   return (
+ *     <div>
+ *       {JSON.stringify(row)}
+ *       <button onClick={() => setRow({...row, c2: (row.c2 || 0) + 1})}>
+ *         Birthday
+ *       </button>
+ *     </div>
+ *   );
+ * };
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div>{\"c1\":\"Alice\",\"c2\":30}<button>Birthday</button></div>'
+ *
+ * const _button = app.querySelector('button');
+ * // -> _button MouseEvent('click', {bubbles: true})
+ * console.log(app.innerHTML);
+ * // -> '<div>{\"c1\":\"Alice\",\"c2\":31}<button>Birthday</button></div>'
+ * ```
+ * @category State hooks
+ * @since v7.3.0
+ */
+export function useRowState(
+  tableId: Id,
+  rowId: Id,
+  storeOrStoreId?: StoreOrStoreId,
+): [Row, (row: Row) => void];
+
 /**
  * The useCellIds hook returns the Ids of every Cell in a given Row, in a given
  * Table, and registers a listener so that any changes to that result will cause
@@ -2240,6 +2436,71 @@ export function useCell(
   storeOrStoreId?: StoreOrStoreId,
 ): CellOrUndefined;
 
+/**
+ * The useCellState hook returns a Cell from a Store and a callback to set it,
+ * following the common React `useState` convention.
+ *
+ * This hook is useful for creating components that read and write a Cell in a
+ * single line, similar to how you would use React's `useState` hook.
+ *
+ * The component this is used in will re-render when the Cell changes.
+ * @param tableId The Id of the Table in the Store.
+ * @param rowId The Id of the Row in the Table.
+ * @param cellId The Id of the Cell in the Row.
+ * @param storeOrStoreId The Store to get data from: omit for the default
+ * context Store, provide an Id for a named context Store, or provide an
+ * explicit reference.
+ * @returns A tuple containing the current Cell and a setter callback that can
+ * be called with a new Cell value.
+ * @example
+ * This example creates a Store outside the application, which is used in the
+ * useCellState hook by reference.
+ *
+ * ```jsx
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import React from 'react';
+ * import {useCellState} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setCell('pets', 'fido', 'visits', 0);
+ * const App = () => {
+ *   const [visits, setVisits] = useCellState(
+ *     'pets',
+ *     'fido',
+ *     'visits',
+ *     store,
+ *   );
+ *   return (
+ *     <span>
+ *       Visits: {visits}
+ *       <button onClick={() => setVisits(visits + 1)}>Visit</button>
+ *     </span>
+ *   );
+ * };
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>Visits: 0<button>Visit</button></span>'
+ *
+ * const _button = app.querySelector('button');
+ * // -> _button MouseEvent('click', {bubbles: true})
+ * console.log(app.innerHTML);
+ * // -> '<span>Visits: 1<button>Visit</button></span>'
+ *
+ * root.unmount(); // !act
+ * ```
+ * @category State hooks
+ * @since v7.3.0
+ */
+export function useCellState(
+  tableId: Id,
+  rowId: Id,
+  cellId: Id,
+  storeOrStoreId?: StoreOrStoreId,
+): [CellOrUndefined, (cell: Cell) => void];
+
 /**
  * The useHasValues hook returns a boolean indicating whether any Values exist
  * in the Store, and registers a listener so that any changes to that result
@@ -2425,6 +2686,64 @@ export function useHasValues(storeOrStoreId?: StoreOrStoreId): boolean;
  */
 export function useValues(storeOrStoreId?: StoreOrStoreId): Values;
 
+/**
+ * The useValuesState hook returns a Values object and a function to set it,
+ * following the same pattern as React's useState hook.
+ *
+ * This is a convenience hook that combines the useValues and
+ * useSetValuesCallback hooks. It's useful when you need both read and write
+ * access to all Values 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 useValuesState hook lets you indicate which Store to use: omit the
+ * parameter for the default context Store, provide an Id for a named context
+ * Store, or provide a Store explicitly by reference.
+ * @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 Values object and a function to set it.
+ * @example
+ * This example creates a Store outside the application, which is used in the
+ * useValuesState hook by reference. A button updates the Values when clicked.
+ *
+ * ```jsx
+ * import {createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {useValuesState} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setValues({open: true});
+ * const App = () => {
+ *   const [values, setValues] = useValuesState(store);
+ *   return (
+ *     <div>
+ *       {JSON.stringify(values)}
+ *       <button onClick={() => setValues({...values, employees: 3})}>
+ *         Add
+ *       </button>
+ *     </div>
+ *   );
+ * };
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div>{"open":true}<button>Add</button></div>'
+ *
+ * const _button = app.querySelector('button');
+ * // -> _button MouseEvent('click', {bubbles: true})
+ * console.log(app.innerHTML);
+ * // -> '<div>{"open":true,"employees":3}<button>Add</button></div>'
+ * ```
+ * @category State hooks
+ * @since v7.3.0
+ */
+export function useValuesState(
+  storeOrStoreId?: StoreOrStoreId,
+): [Values, (values: Values) => void];
+
 /**
  * The useValueIds hook returns the Ids of every Value in a Store, and registers
  * a listener so that any changes to that result will cause a re-render.
@@ -2716,6 +3035,63 @@ export function useValue(
   storeOrStoreId?: StoreOrStoreId,
 ): ValueOrUndefined;
 
+/**
+ * The useValueState hook returns a Value from a Store and a callback to set it,
+ * following the common React `useState` convention.
+ *
+ * This hook is useful for creating components that read and write a Value in a
+ * single line, similar to how you would use React's `useState` hook.
+ *
+ * The component this is used in will re-render when the Value changes.
+ * @param valueId The Id of the Value.
+ * @param storeOrStoreId The Store to get data from: omit for the default
+ * context Store, provide an Id for a named context Store, or provide an
+ * explicit reference.
+ * @returns A tuple containing the current Value and a setter callback that can
+ * be called with a new Value.
+ * @example
+ * This example creates a Store outside the application, which is used in the
+ * useValueState hook by reference.
+ *
+ * ```jsx
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import React from 'react';
+ * import {useValueState} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setValues({employees: 3});
+ * const App = () => {
+ *   const [employees, setEmployees] = useValueState('employees', store);
+ *   return (
+ *     <span>
+ *       Employees: {employees}
+ *       <button onClick={() => setEmployees(employees + 1)}>Hire</button>
+ *     </span>
+ *   );
+ * };
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>Employees: 3<button>Hire</button></span>'
+ *
+ * const _button = app.querySelector('button');
+ * // -> _button MouseEvent('click', {bubbles: true})
+ *
+ * console.log(app.innerHTML);
+ * // -> '<span>Employees: 4<button>Hire</button></span>'
+ *
+ * root.unmount(); // !act
+ * ```
+ * @category State hooks
+ * @since v7.3.0
+ */
+export function useValueState(
+  valueId: Id,
+  storeOrStoreId?: StoreOrStoreId,
+): [value: ValueOrUndefined, setValue: (value: Value) => void];
+
 /**
  * The useSetTablesCallback hook returns a parameterized callback that can be
  * used to set the tabular data of a Store.
@@ -10878,7 +11254,84 @@ export function useResultCellListener(
 export function useParamValues(
   queryId: Id,
   queriesOrQueriesId?: QueriesOrQueriesId,
-): ParamValues | undefined;
+): ParamValues;
+
+/**
+ * The useParamValuesState hook returns an array containing all the parameter
+ * values for a query, and a callback for changing them, providing an easy way
+ * to bind a query's parameters to a user-controlled component.
+ *
+ * This is a convenience hook that combines the useParamValues and
+ * useSetParamValuesCallback hooks. It's useful when you need both read and
+ * write access to query parameters in a single component.
+ *
+ * A Provider component is used to wrap part of an application in a context,
+ * and it can contain a default Queries object or a set of Queries objects
+ * named by Id. The useParamValuesState hook lets you indicate which Queries
+ * object to use: omit the final parameter for the default context Queries
+ * object, provide an Id for a named context Queries object, or provide an
+ * explicit reference.
+ * @param queryId The Id of the query.
+ * @param queriesOrQueriesId The Queries object to be accessed: omit for the
+ * default context Queries object, provide an Id for a named context Queries
+ * object, or provide an explicit reference.
+ * @returns An array containing the parameter values and a function to set them.
+ * @example
+ * This example creates a Queries object outside the application, which is used
+ * in the useParamValuesState hook by reference. A button updates the parameters
+ * when clicked.
+ *
+ * ```jsx
+ * import {createQueries, createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {useParamValuesState} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ *   cujo: {species: 'dog'},
+ * });
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'petsBySpecies',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('species');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ *
+ * const App = () => {
+ *   const [paramValues, setParamValues] = useParamValuesState(
+ *     'petsBySpecies',
+ *     queries,
+ *   );
+ *   return (
+ *     <button onClick={() => setParamValues({species: 'cat'})}>
+ *       {JSON.stringify(paramValues)}
+ *     </button>
+ *   );
+ * };
+ *
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<button>{"species":"dog"}</button>'
+ *
+ * const _button = app.querySelector('button');
+ * // -> _button MouseEvent('click', {bubbles: true})
+ * console.log(app.innerHTML);
+ * // -> '<button>{"species":"cat"}</button>'
+ * ```
+ * @category State hooks
+ * @since v7.3.0
+ */
+export function useParamValuesState(
+  queryId: Id,
+  queriesOrQueriesId?: QueriesOrQueriesId,
+): [ParamValues, (paramValues: ParamValues) => void];
 
 /**
  * The useParamValue hook returns the current value of a single parameter in a
@@ -11027,6 +11480,85 @@ export function useParamValue(
   queriesOrQueriesId?: QueriesOrQueriesId,
 ): ParamValue | undefined;
 
+/**
+ * The useParamValueState hook returns a parameter value and a function to set
+ * it, following the same pattern as React's useState hook.
+ *
+ * This is a convenience hook that combines the useParamValue and
+ * useSetParamValueCallback hooks. It's useful when you need both read and write
+ * access to a query parameter in a single component.
+ *
+ * A Provider component is used to wrap part of an application in a context,
+ * and it can contain a default Queries object or a set of Queries objects
+ * named by Id. The useParamValueState hook lets you indicate which Queries
+ * object to use: omit the final parameter for the default context Queries
+ * object, provide an Id for a named context Queries object, or provide an
+ * explicit reference.
+ * @param queryId The Id of the query.
+ * @param paramId The Id of the parameter.
+ * @param queriesOrQueriesId The Queries object to be accessed: omit for the
+ * default context Queries object, provide an Id for a named context Queries
+ * object, or provide an explicit reference.
+ * @returns An array containing the parameter value and a function to set it.
+ * @example
+ * This example creates a Queries object outside the application, which is used
+ * in the useParamValueState hook by reference. A button updates the parameter
+ * when clicked.
+ *
+ * ```jsx
+ * import {createQueries, createStore} from 'tinybase';
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {useParamValueState} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ * });
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'petsBySpecies',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('species');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ * const App = () => {
+ *   const [species, setSpecies] = useParamValueState(
+ *     'petsBySpecies',
+ *     'species',
+ *     queries,
+ *   );
+ *   return (
+ *     <div>
+ *       Species: {species}
+ *       <button onClick={() => setSpecies('cat')}>Change</button>
+ *     </div>
+ *   );
+ * };
+ *
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div>Species: dog<button>Change</button></div>'
+ *
+ * const _button = app.querySelector('button');
+ * // -> _button MouseEvent('click', {bubbles: true})
+ * console.log(app.innerHTML);
+ * // -> '<div>Species: cat<button>Change</button></div>'
+ * ```
+ * @category State hooks
+ * @since v7.3.0
+ */
+export function useParamValueState(
+  queryId: Id,
+  paramId: Id,
+  queriesOrQueriesId?: QueriesOrQueriesId,
+): [ParamValue | undefined, (paramValue: ParamValue) => void];
+
 /**
  * The useParamValuesListener hook registers a listener function with a Queries
  * object that will be called whenever the parameter values for a query change.