tinybase 7.2.0 → 7.3.0-beta.1

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

@@ -981,6 +981,80 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  */
   useTables: (storeOrStoreId?: StoreOrStoreId<Schemas>) => Tables<Schemas[0]>;
 
+  /**
+ * The useTablesState hook returns a Tables object and a function to set it,
+ * following the same pattern as React's useState hook.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useTablesState(
+ *   storeOrStoreId?: StoreOrStoreId,
+ * ): [Tables, (tables: Tables) => void];
+ * ```
+ *
+ * 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
+ */
+  useTablesState: (
+    storeOrStoreId?: StoreOrStoreId<Schemas>,
+  ) => [Tables<Schemas[0]>, (tables: Tables<Schemas[0]>) => 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.
@@ -1294,6 +1368,86 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     storeOrStoreId?: StoreOrStoreId<Schemas>,
   ) => Table<Schemas[0], TableId>;
 
+  /**
+ * The useTableState hook returns a Table and a function to set it, following
+ * the same pattern as React's useState hook.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useTableState(
+ *   tableId: Id,
+ *   storeOrStoreId?: StoreOrStoreId,
+ * ): [Table, (table: Table) => void];
+ * ```
+ *
+ * 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: <TableId extends TableIdFromSchema<Schemas[0]>>(
+    tableId: TableId,
+    storeOrStoreId?: StoreOrStoreId<Schemas>,
+  ) => [
+    Table<Schemas[0], TableId>,
+    (table: Table<Schemas[0], TableId>) => 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
@@ -2167,6 +2321,78 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     storeOrStoreId?: StoreOrStoreId<Schemas>,
   ) => Row<Schemas[0], TableId>;
 
+  /**
+ * The useRowState hook returns a Row and a function to set it, following the
+ * same pattern as React's useState hook.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useRowState(
+ *   tableId: Id,
+ *   rowId: Id,
+ *   storeOrStoreId?: StoreOrStoreId,
+ * ): [Row, (row: Row) => void];
+ * ```
+ *
+ * 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
+ */
+  useRowState: <TableId extends TableIdFromSchema<Schemas[0]>>(
+    tableId: TableId,
+    rowId: Id,
+    storeOrStoreId?: StoreOrStoreId<Schemas>,
+  ) => [Row<Schemas[0], TableId>, (row: Row<Schemas[0], TableId>) => 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
@@ -2521,6 +2747,88 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     storeOrStoreId?: StoreOrStoreId<Schemas>,
   ) => NoInfer<CellOrUndefined<Schemas[0], TableId, CellId>>;
 
+  /**
+ * The useCellState hook returns a Cell from a Store and a callback to set it,
+ * following the common React `useState` convention.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useCellState(
+ *   tableId: Id,
+ *   rowId: Id,
+ *   cellId: Id,
+ *   storeOrStoreId?: StoreOrStoreId,
+ * ): [CellOrUndefined, (cell: Cell) => void];
+ * ```
+ *
+ * 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
+ */
+  useCellState: <
+    TableId extends TableIdFromSchema<Schemas[0]>,
+    CellId extends CellIdFromSchema<Schemas[0], TableId>,
+  >(
+    tableId: TableId,
+    rowId: Id,
+    cellId: CellId,
+    storeOrStoreId?: StoreOrStoreId<Schemas>,
+  ) => [
+    CellOrUndefined<Schemas[0], TableId, CellId>,
+    (cell: Cell<Schemas[0], TableId, CellId>) => 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
@@ -2718,6 +3026,72 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  */
   useValues: (storeOrStoreId?: StoreOrStoreId<Schemas>) => Values<Schemas[1]>;
 
+  /**
+ * The useValuesState hook returns a Values object and a function to set it,
+ * following the same pattern as React's useState hook.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useValuesState(
+ *   storeOrStoreId?: StoreOrStoreId,
+ * ): [Values, (values: Values) => void];
+ * ```
+ *
+ * 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
+ */
+  useValuesState: (
+    storeOrStoreId?: StoreOrStoreId<Schemas>,
+  ) => [Values<Schemas[1]>, (values: Values<Schemas[1]>) => 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.
@@ -3035,6 +3409,75 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     storeOrStoreId?: StoreOrStoreId<Schemas>,
   ) => DefaultedValueFromSchema<Schemas[1], ValueId>;
 
+  /**
+ * The useValueState hook returns a Value from a Store and a callback to set it,
+ * following the common React `useState` convention.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useValueState(
+ *   valueId: Id,
+ *   storeOrStoreId?: StoreOrStoreId,
+ * ): [value: ValueOrUndefined, setValue: (value: Value) => void];
+ * ```
+ *
+ * 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
+ */
+  useValueState: <ValueId extends ValueIdFromSchema<Schemas[1]>>(
+    valueId: ValueId,
+    storeOrStoreId?: StoreOrStoreId<Schemas>,
+  ) => [
+    value: DefaultedValueFromSchema<Schemas[1], ValueId>,
+    setValue: (value: Value<Schemas[1], ValueId>) => void,
+  ];
+
   /**
  * The useSetTablesCallback hook returns a parameterized callback that can be
  * used to set the tabular data of a Store.
@@ -11788,7 +12231,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * useParamValues(
  *   queryId: Id,
  *   queriesOrQueriesId?: QueriesOrQueriesId,
- * ): ParamValues | undefined;
+ * ): ParamValues;
  * ```
  *
  * A Provider component is used to wrap part of an application in a context, and
@@ -11933,7 +12376,93 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
   useParamValues: (
     queryId: Id,
     queriesOrQueriesId?: QueriesOrQueriesId<Schemas>,
-  ) => 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 has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useParamValuesState(
+ *   queryId: Id,
+ *   queriesOrQueriesId?: QueriesOrQueriesId,
+ * ): [ParamValues, (paramValues: ParamValues) => void];
+ * ```
+ *
+ * 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
+ */
+  useParamValuesState: (
+    queryId: Id,
+    queriesOrQueriesId?: QueriesOrQueriesId<Schemas>,
+  ) => [ParamValues, (paramValues: ParamValues) => void];
 
   /**
  * The useParamValue hook returns the current value of a single parameter in a
@@ -12092,6 +12621,95 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     queriesOrQueriesId?: QueriesOrQueriesId<Schemas>,
   ) => 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 has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useParamValueState(
+ *   queryId: Id,
+ *   paramId: Id,
+ *   queriesOrQueriesId?: QueriesOrQueriesId,
+ * ): [ParamValue | undefined, (paramValue: ParamValue) => void];
+ * ```
+ *
+ * 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
+ */
+  useParamValueState: (
+    queryId: Id,
+    paramId: Id,
+    queriesOrQueriesId?: QueriesOrQueriesId<Schemas>,
+  ) => [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.