tinybase 2.0.0-beta.1 → 2.0.0-beta.4

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

@@ -17,7 +17,7 @@
  * @see Building UIs With Checkpoints guide
  * @see Countries demo
  * @see Todo App demos
- * @see TinyDraw demo
+ * @see Drawing demo
  * @packageDocumentation
  * @module ui-react
  */
@@ -31,6 +31,7 @@ import {
   Row,
   RowIdsListener,
   RowListener,
+  SortedRowIdsListener,
   Store,
   Table,
   TableIdsListener,
@@ -153,6 +154,7 @@ export type RelationshipsOrRelationshipsId = Relationships | Id;
  * parameter or a prop, allowing you to pass in either the Store or its Id.
  *
  * @category Identity
+ * @since v2.0.0
  */
 export type QueriesOrQueriesId = Queries | Id;
 
@@ -426,9 +428,6 @@ export function useTables(storeOrStoreId?: StoreOrStoreId): Tables;
  * @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.
- * @param trackReorder Since v2.0.0, an optional boolean that indicates that the
- * listener should be called if the set of Ids remains the same but their order
- * changes. See the addTableIdsListener method for more details.
  * @returns An array of the Ids of every Table in the Store.
  * @example
  * This example creates a Store outside the application, which is used in the
@@ -486,10 +485,7 @@ export function useTables(storeOrStoreId?: StoreOrStoreId): Tables;
  * ```
  * @category Store hooks
  */
-export function useTableIds(
-  storeOrStoreId?: StoreOrStoreId,
-  trackReorder?: boolean,
-): Ids;
+export function useTableIds(storeOrStoreId?: StoreOrStoreId): Ids;
 
 /**
  * The useTable hook returns an object containing the entire data of a single
@@ -590,9 +586,6 @@ export function useTable(tableId: Id, storeOrStoreId?: StoreOrStoreId): 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.
- * @param trackReorder Since v2.0.0, an optional boolean that indicates that the
- * listener should be called if the set of Ids remains the same but their order
- * changes. See the addRowIdsListener method for more details.
  * @returns An array of the Ids of every Row in the Table.
  * @example
  * This example creates a Store outside the application, which is used in the
@@ -652,10 +645,124 @@ export function useTable(tableId: Id, storeOrStoreId?: StoreOrStoreId): Table;
  * ```
  * @category Store hooks
  */
-export function useRowIds(
+export function useRowIds(tableId: Id, storeOrStoreId?: StoreOrStoreId): Ids;
+
+/**
+ * The useSortedRowIds hook returns the sorted (and optionally, paginated) Ids
+ * of every Row in a given 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
+ * useSortedRowIds 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
+ * sorted Row 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 cellId The Id of the Cell whose values are used for the sorting, or
+ * `undefined` to by sort the Row Id itself.
+ * @param descending Whether the sorting should be in descending order.
+ * @param offset The number of Row Ids to skip for pagination purposes, if any.
+ * @param limit The maximum number of Row Ids to return, or `undefined` for all.
+ * @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 sorted Ids of every Row in the Table.
+ * @example
+ * This example creates a Store outside the application, which is used in the
+ * useSortedRowIds hook by reference. A change to the data in the Store
+ * re-renders the component.
+ *
+ * ```jsx
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const App = () => (
+ *   <span>
+ *     {JSON.stringify(
+ *       useSortedRowIds('pets', 'species', false, 0, undefined, store),
+ *     )}
+ *   </span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["felix","fido"]</span>'
+ *
+ * store.setRow('pets', 'cujo', {species: 'wolf'}); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["felix","fido","cujo"]</span>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a default Store is
+ * provided. A component within it then uses the useSortedRowIds hook.
+ *
+ * ```jsx
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => <span>{JSON.stringify(useSortedRowIds('pets'))}</span>;
+ *
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App store={store} />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["felix","fido"]</span>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a Store is provided, named
+ * by Id. A component within it then uses the useSortedRowIds hook.
+ *
+ * ```jsx
+ * const App = ({store}) => (
+ *   <Provider storesById={{petStore: store}}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <span>
+ *     {JSON.stringify(
+ *       useSortedRowIds('pets', 'species', false, 0, undefined, 'petStore'),
+ *     )}
+ *   </span>
+ * );
+ *
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App store={store} />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["felix","fido"]</span>'
+ * ```
+ * @category Store hooks
+ * @since v2.0.0
+ */
+export function useSortedRowIds(
   tableId: Id,
+  cellId?: Id,
+  descending?: boolean,
+  offset?: number,
+  limit?: number,
   storeOrStoreId?: StoreOrStoreId,
-  trackReorder?: boolean,
 ): Ids;
 
 /**
@@ -765,9 +872,6 @@ export function useRow(
  * @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.
- * @param trackReorder Since v2.0.0, an optional boolean that indicates that the
- * listener should be called if the set of Ids remains the same but their order
- * changes. See the addCellIdsListener method for more details.
  * @returns An array of the Ids of every Cell in the Row.
  * @example
  * This example creates a Store outside the application, which is used in the
@@ -835,7 +939,6 @@ export function useCellIds(
   tableId: Id,
   rowId: Id,
   storeOrStoreId?: StoreOrStoreId,
-  trackReorder?: boolean,
 ): Ids;
 
 /**
@@ -1842,9 +1945,6 @@ export function useTablesListener(
  * @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 trackReorder Since v2.0.0, an optional boolean that indicates that the
- * listener should be called if the set of Ids remains the same but their order
- * changes. See the addTableIdsListener method for more details.
  * @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
@@ -1884,7 +1984,6 @@ export function useTablesListener(
 export function useTableIdsListener(
   listener: TableIdsListener,
   listenerDeps?: React.DependencyList,
-  trackReorder?: boolean,
   mutator?: boolean,
   storeOrStoreId?: StoreOrStoreId,
 ): void;
@@ -1977,9 +2076,6 @@ export function useTableListener(
  * @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 trackReorder Since v2.0.0, an optional boolean that indicates that the
- * listener should be called if the set of Ids remains the same but their order
- * changes. See the addRowIdsListener method for more details.
  * @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
@@ -2020,7 +2116,88 @@ export function useRowIdsListener(
   tableId: IdOrNull,
   listener: RowIdsListener,
   listenerDeps?: React.DependencyList,
-  trackReorder?: boolean,
+  mutator?: boolean,
+  storeOrStoreId?: StoreOrStoreId,
+): void;
+
+/**
+ * The useSortedRowIdsListener hook registers a listener function with a Store
+ * that will be called whenever sorted (and optionally, paginated) Row Ids 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 useSortedRowIds hook).
+ *
+ * Unlike the addSortedRowIdsListener method, which returns a listener Id and
+ * requires you to remove it manually, the useSortedRowIdsListener 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 in the Store.
+ * @param cellId The Id of the Cell whose values are used for the sorting, or
+ * `undefined` to by sort the Row Id itself.
+ * @param descending Whether the sorting should be in descending order.
+ * @param offset The number of Row Ids to skip for pagination purposes, if any.
+ * @param limit The maximum number of Row Ids to return, or `undefined` for all.
+ * @param listener The function that will be called whenever the sorted Row Ids
+ * in the 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 useSortedRowIdsListener 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 = () => {
+ *   useSortedRowIdsListener('pets', 'species', false, 0, undefined, () =>
+ *     console.log('Sorted Row Ids changed'),
+ *   );
+ *   return <span>App</span>;
+ * };
+ *
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App store={store} />, app); // !act
+ * console.log(store.getListenerStats().sortedRowIds);
+ * // -> 1
+ *
+ * store.setRow('pets', 'cujo', {species: 'wolf'}); // !act
+ * // -> 'Sorted Row Ids changed'
+ *
+ * ReactDOM.unmountComponentAtNode(app); // !act
+ * console.log(store.getListenerStats().sortedRowIds);
+ * // -> 0
+ * ```
+ * @category Store hooks
+ * @since v2.0.0
+ */
+export function useSortedRowIdsListener(
+  tableId: Id,
+  cellId: Id | undefined,
+  descending: boolean,
+  offset: number,
+  limit: number | undefined,
+  listener: SortedRowIdsListener,
+  listenerDeps?: React.DependencyList,
   mutator?: boolean,
   storeOrStoreId?: StoreOrStoreId,
 ): void;
@@ -2129,9 +2306,6 @@ export function useRowListener(
  * @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 trackReorder Since v2.0.0, an optional boolean that indicates that the
- * listener should be called if the set of Ids remains the same but their order
- * changes. See the addCellIdsListener method for more details.
  * @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
@@ -2175,7 +2349,6 @@ export function useCellIdsListener(
   rowId: IdOrNull,
   listener: CellIdsListener,
   listenerDeps?: React.DependencyList,
-  trackReorder?: boolean,
   mutator?: boolean,
   storeOrStoreId?: StoreOrStoreId,
 ): void;
@@ -4065,7 +4238,7 @@ export function useLinkedRowIdsListener(
  * // -> '<span>brown</span>'
  * ```
  * @category Queries hooks
- * @since v2.0.0-beta
+ * @since v2.0.0
  */
 export function useCreateQueries(
   store: Store,
@@ -4133,6 +4306,7 @@ export function useCreateQueries(
  * // -> '<span>0</span>'
  * ```
  * @category Queries hooks
+ * @since v2.0.0
  */
 export function useQueries(id?: Id): Queries | undefined;
 
@@ -4249,6 +4423,7 @@ export function useQueries(id?: Id): Queries | undefined;
  * // -> '<span>{"fido":{"color":"brown"},"cujo":{"color":"black"}}</span>'
  * ```
  * @category Queries hooks
+ * @since v2.0.0
  */
 export function useResultTable(
   queryId: Id,
@@ -4275,8 +4450,6 @@ export function useResultTable(
  * @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.
- * @param trackReorder An optional boolean that indicates that the listener
- * should be called if the set of Ids remains the same but their order changes.
  * See the addResultRowIdsListener method for more details.
  * @returns An array of the Ids of every Row in the result of the query.
  * @example
@@ -4371,11 +4544,164 @@ export function useResultTable(
  * // -> '<span>["fido","cujo"]</span>'
  * ```
  * @category Queries hooks
+ * @since v2.0.0
  */
 export function useResultRowIds(
   queryId: Id,
   queriesOrQueriesId?: QueriesOrQueriesId,
-  trackReorder?: boolean,
+): Ids;
+
+/**
+ * The useResultSortedRowIds hook returns the sorted (and optionally, paginated)
+ * Ids of every Row in the result Table of the given query, and registers a
+ * listener so that any changes to those Ids 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 Queries object or a set of Queries objects named by
+ * Id. The useResultSortedRowIds hook lets you indicate which Queries object to
+ * get data for: omit the final optional final parameter for the default context
+ * Queries object, provide an Id for a named context Queries object, or provide
+ * a Queries object explicitly by reference.
+ *
+ * When first rendered, this hook will create a listener so that changes to the
+ * sorted result Row Ids will cause a re-render. When the component containing
+ * this hook is unmounted, the listener will be automatically removed.
+ *
+ * @param queryId The Id of the query.
+ * @param cellId The Id of the result Cell whose values are used for the
+ * sorting, or `undefined` to by sort the result Row Id itself.
+ * @param descending Whether the sorting should be in descending order.
+ * @param offset The number of Row Ids to skip for pagination purposes, if any.
+ * @param limit The maximum number of Row Ids to return, or `undefined` for all.
+ * @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 of the Ids of every Row in the result of the query.
+ * @example
+ * This example creates a Queries object outside the application, which is used
+ * in the useResultSortedRowIds hook by reference. A change to the data in the
+ * query re-renders the component.
+ *
+ * ```jsx
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog', color: 'brown'},
+ *   felix: {species: 'cat', color: 'black'},
+ *   cujo: {species: 'dog', color: 'black'},
+ * });
+ * const queries = createQueries(store).setQueryDefinition(
+ *   'dogColors',
+ *   'pets',
+ *   ({select, where}) => {
+ *     select('color');
+ *     where('species', 'dog');
+ *   },
+ * );
+ * const App = () => (
+ *   <span>
+ *     {JSON.stringify(
+ *       useResultSortedRowIds(
+ *         'dogColors',
+ *         'color',
+ *         false,
+ *         0,
+ *         undefined,
+ *         queries,
+ *       ),
+ *     )}
+ *   </span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["cujo","fido"]</span>'
+ *
+ * store.setCell('pets', 'cujo', 'species', 'wolf'); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["fido"]</span>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a default Queries object
+ * is provided. A component within it then uses the useResultSortedRowIds hook.
+ *
+ * ```jsx
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <span>
+ *     {JSON.stringify(useResultSortedRowIds('dogColors', 'color'))}
+ *   </span>
+ * );
+ *
+ * const queries = createQueries(
+ *   createStore().setTable('pets', {
+ *     fido: {species: 'dog', color: 'brown'},
+ *     felix: {species: 'cat', color: 'black'},
+ *     cujo: {species: 'dog', color: 'black'},
+ *   }),
+ * ).setQueryDefinition('dogColors', 'pets', ({select, where}) => {
+ *   select('color');
+ *   where('species', 'dog');
+ * });
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App queries={queries} />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["cujo","fido"]</span>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a Queries object is
+ * provided, named by Id. A component within it then uses the
+ * useResultSortedRowIds hook.
+ *
+ * ```jsx
+ * const App = ({queries}) => (
+ *   <Provider queriesById={{petQueries: queries}}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <span>
+ *     {JSON.stringify(
+ *       useResultSortedRowIds(
+ *         'dogColors',
+ *         'color',
+ *         false,
+ *         0,
+ *         undefined,
+ *         'petQueries',
+ *       ),
+ *     )}
+ *   </span>
+ * );
+ *
+ * const queries = createQueries(
+ *   createStore().setTable('pets', {
+ *     fido: {species: 'dog', color: 'brown'},
+ *     felix: {species: 'cat', color: 'black'},
+ *     cujo: {species: 'dog', color: 'black'},
+ *   }),
+ * ).setQueryDefinition('dogColors', 'pets', ({select, where}) => {
+ *   select('color');
+ *   where('species', 'dog');
+ * });
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App queries={queries} />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["cujo","fido"]</span>'
+ * ```
+ * @category Queries hooks
+ * @since v2.0.0
+ */
+export function useResultSortedRowIds(
+  queryId: Id,
+  cellId?: Id,
+  descending?: boolean,
+  offset?: number,
+  limit?: number,
+  queriesOrQueriesId?: QueriesOrQueriesId,
 ): Ids;
 
 /**
@@ -4495,6 +4821,7 @@ export function useResultRowIds(
  * // -> '<span>{"color":"brown"}</span>'
  * ```
  * @category Queries hooks
+ * @since v2.0.0
  */
 export function useResultRow(
   queryId: Id,
@@ -4625,6 +4952,7 @@ export function useResultRow(
  * // -> '<span>["species","color"]</span>'
  * ```
  * @category Queries hooks
+ * @since v2.0.0
  */
 export function useResultCellIds(
   queryId: Id,
@@ -4751,6 +5079,7 @@ export function useResultCellIds(
  * // -> '<span>brown</span>'
  * ```
  * @category Queries hooks
+ * @since v2.0.0
  */
 export function useResultCell(
   queryId: Id,
@@ -4827,6 +5156,7 @@ export function useResultCell(
  * // -> 0
  * ```
  * @category Queries hooks
+ * @since v2.0.0
  */
 export function useResultTableListener(
   queryId: IdOrNull,
@@ -4859,9 +5189,6 @@ export function useResultTableListener(
  * @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 trackReorder An optional boolean that indicates that the listener
- * should be called if the set of Ids remains the same but their order changes.
- * See the addResultRowIdsListener method for more details.
  * @param queriesOrQueriesId The Queries object to register the listener with:
  * omit for the default context Queries object, provide an Id for a named
  * context Queries object, or provide an explicit reference.
@@ -4878,7 +5205,7 @@ export function useResultTableListener(
  * );
  * const Pane = () => {
  *   useResultRowIdsListener('petColors', () =>
- *     console.log('Result row Ids changed'),
+ *     console.log('Result Row Ids changed'),
  *   );
  *   return <span>App</span>;
  * };
@@ -4899,25 +5226,113 @@ export function useResultTableListener(
  * // -> 1
  *
  * store.setRow('pets', 'rex', {species: 'dog', color: 'tan'}); // !act
- * // -> 'Result row Ids changed'
+ * // -> 'Result Row Ids changed'
  *
  * ReactDOM.unmountComponentAtNode(app); // !act
  * console.log(queries.getListenerStats().rowIds);
  * // -> 0
  * ```
  * @category Queries hooks
+ * @since v2.0.0
  */
 export function useResultRowIdsListener(
   queryId: IdOrNull,
   listener: ResultRowIdsListener,
   listenerDeps?: React.DependencyList,
-  trackReorder?: boolean,
   queriesOrQueriesId?: QueriesOrQueriesId,
 ): void;
 
 /**
- * The useResultRowListener hook registers a listener function with a Queries
- * object that will be called whenever data in a result Row changes.
+ * The useResultSortedRowIdsListener hook registers a listener function with a
+ * Queries object that will be called whenever the sorted (and optionally,
+ * paginated) Row Ids in a result 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 useResultSortedRowIds hook).
+ *
+ * Unlike the addResultSortedRowIdsListener method, which returns a listener Id
+ * and requires you to remove it manually, the useResultSortedRowIdsListener
+ * hook manages this lifecycle for you: when the listener changes (per its
+ * `listenerDeps` dependencies) or the component unmounts, the listener on the
+ * underlying Queries object will be deleted.
+ *
+ * @param queryId The Id of the query to listen to.
+ * @param cellId The Id of the Cell whose values are used for the sorting, or
+ * `undefined` to by sort the Row Id itself.
+ * @param descending Whether the sorting should be in descending order.
+ * @param offset The number of Row Ids to skip for pagination purposes, if any.
+ * @param limit The maximum number of Row Ids to return, or `undefined` for all.
+ * @param listener The function that will be called whenever the Row Ids in the
+ * matching result 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 queriesOrQueriesId The Queries object to register the listener with:
+ * omit for the default context Queries object, provide an Id for a named
+ * context Queries object, or provide an explicit reference.
+ * @example
+ * This example uses the useResultSortedRowIdsListener hook to create a listener
+ * that is scoped to a single component. When the component is unmounted, the
+ * listener is removed from the Queries object.
+ *
+ * ```jsx
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => {
+ *   useResultSortedRowIdsListener(
+ *     'petColors',
+ *     'color',
+ *     false,
+ *     0,
+ *     undefined,
+ *     () => console.log('Sorted result Row Ids changed'),
+ *   );
+ *   return <span>App</span>;
+ * };
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog', color: 'brown'},
+ *   felix: {species: 'cat', color: 'black'},
+ *   cujo: {species: 'dog', color: 'black'},
+ * });
+ * const queries = createQueries(store).setQueryDefinition(
+ *   'petColors',
+ *   'pets',
+ *   ({select}) => select('color'),
+ * );
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App queries={queries} />, app); // !act
+ * console.log(queries.getListenerStats().sortedRowIds);
+ * // -> 1
+ *
+ * store.setRow('pets', 'cujo', {color: 'tan'}); // !act
+ * // -> 'Sorted result Row Ids changed'
+ *
+ * ReactDOM.unmountComponentAtNode(app); // !act
+ * console.log(queries.getListenerStats().sortedRowIds);
+ * // -> 0
+ * ```
+ * @category Queries hooks
+ * @since v2.0.0
+ */
+export function useResultSortedRowIdsListener(
+  queryId: Id,
+  cellId: Id | undefined,
+  descending: boolean,
+  offset: number,
+  limit: number | undefined,
+  listener: ResultRowIdsListener,
+  listenerDeps?: React.DependencyList,
+  queriesOrQueriesId?: QueriesOrQueriesId,
+): void;
+
+/**
+ * The useResultRowListener hook registers a listener function with a Queries
+ * object that will be called whenever data in a result Row changes.
  *
  * 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
@@ -4989,6 +5404,7 @@ export function useResultRowIdsListener(
  * // -> 0
  * ```
  * @category Queries hooks
+ * @since v2.0.0
  */
 export function useResultRowListener(
   queryId: IdOrNull,
@@ -5072,6 +5488,7 @@ export function useResultRowListener(
  * // -> 0
  * ```
  * @category Queries hooks
+ * @since v2.0.0
  */
 export function useResultCellIdsListener(
   queryId: IdOrNull,
@@ -5157,6 +5574,7 @@ export function useResultCellIdsListener(
  * // -> 0
  * ```
  * @category Queries hooks
+ * @since v2.0.0
  */
 export function useResultCellListener(
   queryId: IdOrNull,
@@ -6168,12 +6586,6 @@ export type TablesProps = {
    * for a named context Store, or provide an explicit reference.
    */
   readonly store?: StoreOrStoreId;
-  /**
-   * An optional boolean that indicates that the component should re-render if
-   * the set of Table Ids in the Store remains the same but their order changes.
-   * See the addTableIdsListener method for more details.
-   */
-  readonly trackReorder?: boolean;
   /**
    * A component for rendering each Table in the Store (to override the default
    * TableView component).
@@ -6212,11 +6624,60 @@ export type TableProps = {
    */
   readonly store?: StoreOrStoreId;
   /**
-   * An optional boolean that indicates that the component should re-render if
-   * the set of Row Ids in the Table remains the same but their order changes.
-   * See the addRowIdsListener method for more details.
+   * A custom component for rendering each Row in the Table (to override the
+   * default RowView component).
+   */
+  readonly rowComponent?: ComponentType<RowProps>;
+  /**
+   * A function for generating extra props for each custom Row component based
+   * on its Id.
+   */
+  readonly getRowComponentProps?: (rowId: Id) => ExtraProps;
+  /**
+   * A component or string to separate each Row component.
+   */
+  readonly separator?: ReactElement | string;
+  /**
+   * Whether the component should also render the Id of the Table, and its
+   * descendent objects, to assist with debugging.
+   */
+  readonly debugIds?: boolean;
+};
+
+/**
+ * SortedTableProps props are used for components that refer to a single sorted
+ * Table in a Store, such as the SortedTableView component.
+ *
+ * @category Props
+ * @since v2.0.0
+ */
+export type SortedTableProps = {
+  /**
+   * The Id of the Table in the Store to be rendered.
+   */
+  readonly tableId: Id;
+  /**
+   * The Id of the Cell whose values are used for the sorting. If omitted, the
+   * view will sort the Row Id itself.
    */
-  readonly trackReorder?: boolean;
+  readonly cellId?: Id;
+  /**
+   * Whether the sorting should be in descending order.
+   */
+  readonly descending?: boolean;
+  /**
+   * The number of Row Ids to skip for pagination purposes.
+   */
+  readonly offset?: number;
+  /**
+   * The maximum number of Row Ids to return.
+   */
+  readonly limit?: number;
+  /**
+   * The Store to be accessed: omit for the default context Store, provide an Id
+   * for a named context Store, or provide an explicit reference.
+   */
+  readonly store?: StoreOrStoreId;
   /**
    * A custom component for rendering each Row in the Table (to override the
    * default RowView component).
@@ -6258,12 +6719,6 @@ export type RowProps = {
    * for a named context Store, or provide an explicit reference.
    */
   readonly store?: StoreOrStoreId;
-  /**
-   * An optional boolean that indicates that the component should re-render if
-   * the set of Cell Ids remains the same but their order changes. See the
-   * addCellIdsListener method for more details.
-   */
-  readonly trackReorder?: boolean;
   /**
    * A custom component for rendering each Cell in the Row (to override the
    * default CellView component).
@@ -6549,6 +7004,7 @@ export type LinkedRowsProps = {
  * result Table, such as the ResultTableView component.
  *
  * @category Props
+ * @since v2.0.0
  */
 export type ResultTableProps = {
   /**
@@ -6563,11 +7019,62 @@ export type ResultTableProps = {
    */
   readonly queries?: QueriesOrQueriesId;
   /**
-   * An optional boolean that indicates that the component should re-render if
-   * the set of Row Ids in the result Table remains the same but their order
-   * changes. See the addResultRowIdsListener method for more details.
+   * A custom component for rendering each Row in the Table (to override the
+   * default ResultRowView component).
+   */
+  readonly resultRowComponent?: ComponentType<ResultRowProps>;
+  /**
+   * A function for generating extra props for each custom Row component based
+   * on its Id.
+   */
+  readonly getResultRowComponentProps?: (rowId: Id) => ExtraProps;
+  /**
+   * A component or string to separate each Row component.
+   */
+  readonly separator?: ReactElement | string;
+  /**
+   * Whether the component should also render the Id of the query, and its
+   * descendent objects, to assist with debugging.
+   */
+  readonly debugIds?: boolean;
+};
+
+/**
+ * ResultSortedTableProps props are used for components that refer to a single
+ * sorted query result Table, such as the ResultSortedTableView component.
+ *
+ * @category Props
+ * @since v2.0.0
+ */
+export type ResultSortedTableProps = {
+  /**
+   * The Id of the query in the Queries object for which the sorted result Table
+   * will be rendered.
+   */
+  readonly queryId: Id;
+  /**
+   * The Id of the Cell whose values are used for the sorting. If omitted, the
+   * view will sort the Row Id itself.
+   */
+  readonly cellId?: Id;
+  /**
+   * Whether the sorting should be in descending order.
    */
-  readonly trackReorder?: boolean;
+  readonly descending?: boolean;
+  /**
+   * The number of Row Ids to skip for pagination purposes.
+   */
+  readonly offset?: number;
+  /**
+   * The maximum number of Row Ids to return.
+   */
+  readonly limit?: number;
+  /**
+   * 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.
+   */
+  readonly queries?: QueriesOrQueriesId;
   /**
    * A custom component for rendering each Row in the Table (to override the
    * default ResultRowView component).
@@ -6594,6 +7101,7 @@ export type ResultTableProps = {
  * query result Table, such as the ResultRowView component.
  *
  * @category Props
+ * @since v2.0.0
  */
 export type ResultRowProps = {
   /**
@@ -6637,6 +7145,7 @@ export type ResultRowProps = {
  * Row of a result Table, such as the ResultCellView component.
  *
  * @category Props
+ * @since v2.0.0
  */
 export type ResultCellProps = {
   /**
@@ -6789,8 +7298,8 @@ export type ForwardCheckpointsProps = {
 
 /**
  * ProviderProps props are used with the Provider component, so that Store
- * Metrics, Indexes, Relationships, and Checkpoints objects can be passed into
- * the context of an application and used throughout.
+ * Metrics, Indexes, Relationships, Queries, and Checkpoints objects can be
+ * passed into the context of an application and used throughout.
  *
  * One of each type of object can be provided as a default within the context.
  * Additionally, multiple of each type of object can be provided in an Id-keyed
@@ -6841,12 +7350,12 @@ export type ProviderProps = {
   readonly relationshipsById?: {[relationshipsId: Id]: Relationships};
   /**
    * A default single Queries object that will be available within the Provider
-   * context.
+   * context, since v2.0.0.
    */
   readonly queries?: Queries;
   /**
    * An object containing multiple Queries objects that will be available within
-   * the Provider context by their Id.
+   * the Provider context by their Id, since v2.0.0.
    */
   readonly queriesById?: {[queriesId: Id]: Queries};
   /**
@@ -6873,9 +7382,9 @@ export type ComponentReturnType = ReactElement<any, any> | null;
  * The Provider component is used to wrap part of an application in a context
  * that provides default objects to be used by hooks and components within.
  *
- * Store, Metrics, Indexes, Relationships, and Checkpoints objects can be passed
- * into the context of an application and used throughout. One of each type of
- * object can be provided as a default within the context. Additionally,
+ * Store, Metrics, Indexes, Relationships, Queries, and Checkpoints objects can
+ * be passed into the context of an application and used throughout. One of each
+ * type of object can be provided as a default within the context. Additionally,
  * multiple of each type of object can be provided in an Id-keyed map to the
  * `___ById` props.
  *
@@ -7172,6 +7681,136 @@ export function CellView(props: CellProps): ComponentReturnType;
  */
 export function RowView(props: RowProps): ComponentReturnType;
 
+/**
+ * The SortedTableView component renders the contents of a single sorted Table
+ * in a Store, and registers a listener so that any changes to that result will
+ * cause a re-render.
+ *
+ * The component's props identify which Table to render based on Table Id, and
+ * Store (which is either the default context Store, a named context Store, or
+ * by explicit reference). It also takes a Cell Id to sort by and a boolean to
+ * indicate that the sorting should be in descending order. The `offset` and
+ * `limit` props are used to paginate results, but default to `0` and
+ * `undefined` to return all available Row Ids if not specified.
+ *
+ * This component renders a Table by iterating over its Row objects, in the
+ * order dictated by the sort parameters. By default these are in turn rendered
+ * with the RowView component, but you can override this behavior by providing a
+ * `rowComponent` prop, a custom component of your own that will render a Row
+ * based on RowProps. You can also pass additional props to your custom
+ * component with the `getRowComponentProps` callback prop.
+ *
+ * This component uses the useSortedRowIds hook under the covers, which means
+ * that any changes to the structure or sorting of the Table will cause a
+ * re-render.
+ *
+ * @param props The props for this component.
+ * @returns A rendering of the Table, or nothing, if not present.
+ * @example
+ * This example creates a Store outside the application, which is used in the
+ * SortedTableView component by reference. A change to the data in the Store
+ * re-renders the component.
+ *
+ * ```jsx
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const App = () => (
+ *   <div>
+ *     <SortedTableView
+ *       tableId="pets"
+ *       cellId="species"
+ *       store={store}
+ *       separator="/"
+ *     />
+ *   </div>
+ * );
+ *
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div>cat/dog</div>'
+ *
+ * store.setRow('pets', 'cujo', {species: 'wolf'}); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div>cat/dog/wolf</div>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a default Store is
+ * provided. The SortedTableView component within it then renders the Table
+ * (with Ids for readability).
+ *
+ * ```jsx
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <div>
+ *     <SortedTableView tableId="pets" cellId="species" debugIds={true} />
+ *   </div>
+ * );
+ *
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App store={store} />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div>pets:{felix:{species:{cat}}fido:{species:{dog}}}</div>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a default Store is
+ * provided. The SortedTableView component within it then renders the Table with
+ * a custom Row component and a custom props callback.
+ *
+ * ```jsx
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <div>
+ *     <SortedTableView
+ *       tableId="pets"
+ *       cellId="species"
+ *       rowComponent={FormattedRowView}
+ *       getRowComponentProps={(rowId) => ({bold: rowId == 'fido'})}
+ *     />
+ *   </div>
+ * );
+ * const FormattedRowView = ({tableId, rowId, bold}) => (
+ *   <span>
+ *     {bold ? <b>{rowId}</b> : rowId}
+ *     {': '}
+ *     <RowView tableId={tableId} rowId={rowId} />
+ *   </span>
+ * );
+ *
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *   },
+ * });
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App store={store} />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div><span>felix: cat</span><span><b>fido</b>: dog</span></div>'
+ * ```
+ * @category Store components
+ * @since v2.0.0
+ */
+export function SortedTableView(props: SortedTableProps): ComponentReturnType;
+
 /**
  * The TableView component renders the contents of a single Table in a Store,
  * and registers a listener so that any changes to that result will cause a
@@ -8265,6 +8904,7 @@ export function LinkedRowsView(props: LinkedRowsProps): ComponentReturnType;
  * // -> '<span></span>'
  * ```
  * @category Queries components
+ * @since v2.0.0
  */
 export function ResultCellView(props: ResultCellProps): ComponentReturnType;
 
@@ -8411,9 +9051,150 @@ export function ResultCellView(props: ResultCellProps): ComponentReturnType;
  * // -> '<div><span><b>species</b>: dog</span><span>color: brown</span></div>'
  * ```
  * @category Queries components
+ * @since v2.0.0
  */
 export function ResultRowView(props: ResultRowProps): ComponentReturnType;
 
+/**
+ * The ResultSortedTableView component renders the contents of a single query's
+ * sorted result Table in a Queries object, and registers a listener so that any
+ * changes to that result will cause a re-render.
+ *
+ * The component's props identify which Table to render based on query Id, and
+ * Queries object (which is either the default context Queries object, a named
+ * context Queries object, or by explicit reference). It also takes a Cell Id to
+ * sort by and a boolean to indicate that the sorting should be in descending
+ * order. The `offset` and `limit` props are used to paginate results, but
+ * default to `0` and `undefined` to return all available Row Ids if not
+ * specified.
+ *
+ * This component renders a result Table by iterating over its Row objects, in
+ * the order dictated by the sort parameters. By default these are in turn
+ * rendered with the ResultRowView component, but you can override this behavior
+ * by providing a `resultRowComponent` prop, a custom component of your own that
+ * will render a Row based on ResultRowProps. You can also pass additional props
+ * to your custom component with the `getResultRowComponentProps` callback prop.
+ *
+ * This component uses the useResultSortedRowIds hook under the covers, which
+ * means that any changes to the structure or sorting of the result Table will
+ * cause a re-render.
+ *
+ * @param props The props for this component.
+ * @returns A rendering of the result Table, or nothing, if not present.
+ * @example
+ * This example creates a Queries object outside the application, which is used
+ * in the ResultSortedTableView component by reference. A change to the data in
+ * the Store re-renders the component.
+ *
+ * ```jsx
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog', color: 'brown'},
+ *   felix: {species: 'cat', color: 'black'},
+ * });
+ * const queries = createQueries(store).setQueryDefinition(
+ *   'petColors',
+ *   'pets',
+ *   ({select}) => select('color'),
+ * );
+ * const App = () => (
+ *   <div>
+ *     <ResultSortedTableView
+ *       queryId="petColors"
+ *       cellId="color"
+ *       queries={queries}
+ *       separator="/"
+ *     />
+ *   </div>
+ * );
+ *
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div>black/brown</div>'
+ *
+ * store.setCell('pets', 'felix', 'color', 'white'); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div>brown/white</div>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a default Queries object
+ * is provided. The ResultSortedTableView component within it then renders the
+ * Table (with Ids for readability).
+ *
+ * ```jsx
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <div>
+ *     <ResultSortedTableView
+ *       queryId="petColors"
+ *       cellId="color"
+ *       debugIds={true}
+ *     />
+ *   </div>
+ * );
+ *
+ * const queries = createQueries(
+ *   createStore().setTable('pets', {
+ *     fido: {species: 'dog', color: 'brown'},
+ *     felix: {species: 'cat', color: 'black'},
+ *   }),
+ * ).setQueryDefinition('petColors', 'pets', ({select}) => select('color'));
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App queries={queries} />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div>petColors:{felix:{color:{black}}fido:{color:{brown}}}</div>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a default Queries object
+ * is provided. The ResultSortedTableView component within it then renders the
+ * Table with a custom Row component and a custom props callback.
+ *
+ * ```jsx
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <div>
+ *     <ResultSortedTableView
+ *       queryId="petColors"
+ *       cellId="color"
+ *       resultRowComponent={FormattedRowView}
+ *       getResultRowComponentProps={(rowId) => ({bold: rowId == 'fido'})}
+ *     />
+ *   </div>
+ * );
+ * const FormattedRowView = ({queryId, rowId, bold}) => (
+ *   <span>
+ *     {bold ? <b>{rowId}</b> : rowId}
+ *     {': '}
+ *     <ResultRowView queryId={queryId} rowId={rowId} />
+ *   </span>
+ * );
+ *
+ * const queries = createQueries(
+ *   createStore().setTable('pets', {
+ *     fido: {species: 'dog', color: 'brown'},
+ *     felix: {species: 'cat', color: 'black'},
+ *   }),
+ * ).setQueryDefinition('petColors', 'pets', ({select}) => select('color'));
+ * const app = document.createElement('div');
+ * ReactDOM.render(<App queries={queries} />, app); // !act
+ * console.log(app.innerHTML);
+ * // -> '<div><span>felix: black</span><span><b>fido</b>: brown</span></div>'
+ * ```
+ * @category Queries components
+ * @since v2.0.0
+ */
+export function ResultSortedTableView(
+  props: ResultSortedTableProps,
+): ComponentReturnType;
+
 /**
  * The ResultTableView component renders the contents of a single query's result
  * Table in a Queries object, and registers a listener so that any changes to
@@ -8533,6 +9314,7 @@ export function ResultRowView(props: ResultRowProps): ComponentReturnType;
  * // -> '<div><span><b>fido</b>: brown</span><span>felix: black</span></div>'
  * ```
  * @category Queries components
+ * @since v2.0.0
  */
 export function ResultTableView(props: ResultTableProps): ComponentReturnType;