tinybase 4.1.0-beta.0 → 4.1.0-beta.2

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

@@ -69,6 +69,7 @@ import {
   ResultCellListener,
   ResultRowIdsListener,
   ResultRowListener,
+  ResultTableCellIdsListener,
   ResultTableListener,
 } from './queries.d';
 import {Persister} from './persisters.d';
@@ -5273,7 +5274,7 @@ export function useQueries(id?: Id): Queries | undefined;
 
 /**
  * The useResultTable hook returns an object containing the entire data of the
- * result Table of the given query, and registers a listener so that any changes
+ * ResultTable of the given query, 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
@@ -5290,7 +5291,7 @@ export function useQueries(id?: Id): Queries | undefined;
  * @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 object containing the entire data of the result Table.
+ * @returns An object containing the entire data of the ResultTable.
  * @example
  * This example creates a Queries object outside the application, which is used
  * in the useTable hook by reference. A change to the data in the query
@@ -5391,7 +5392,136 @@ export function useResultTable(
 ): Table;
 
 /**
- * The useResultRowIds hook returns the Ids of every Row in the result Table of
+ * The useResultTableCellIds hook returns the Ids of every Cell used across the
+ * whole ResultTable 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 useResultTableCellIds 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
+ * result Cell 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 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. See the
+ * addResultTableCellIdsListener method for more details.
+ * @returns An array of the Ids of every Cell in the result of the query.
+ * @example
+ * This example creates a Queries object outside the application, which is used
+ * in the useResultTableCellIds 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(
+ *   'dogColorsAndLegs',
+ *   'pets',
+ *   ({select, where}) => {
+ *     select('color');
+ *     select('legs');
+ *     where('species', 'dog');
+ *   },
+ * );
+ * const App = () => (
+ *   <span>
+ *     {JSON.stringify(useResultTableCellIds('dogColorsAndLegs', queries))}
+ *   </span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * ReactDOMClient.createRoot(app).render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["color"]</span>'
+ *
+ * store.setCell('pets', 'cujo', 'legs', 4); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["color","legs"]</span>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a default Queries object
+ * is provided. A component within it then uses the useResultTableCellIds hook.
+ *
+ * ```jsx
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <span>{JSON.stringify(useResultTableCellIds('dogColorsAndLegs'))}</span>
+ * );
+ *
+ * const queries = createQueries(
+ *   createStore().setTable('pets', {
+ *     fido: {species: 'dog', color: 'brown'},
+ *     felix: {species: 'cat', color: 'black'},
+ *     cujo: {species: 'dog', color: 'black', legs: 4},
+ *   }),
+ * ).setQueryDefinition('dogColorsAndLegs', 'pets', ({select, where}) => {
+ *   select('color');
+ *   select('legs');
+ *   where('species', 'dog');
+ * });
+ * const app = document.createElement('div');
+ * ReactDOMClient.createRoot(app).render(<App queries={queries} />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["color","legs"]</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
+ * useResultTableCellIds hook.
+ *
+ * ```jsx
+ * const App = ({queries}) => (
+ *   <Provider queriesById={{petQueries: queries}}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <span>
+ *     {JSON.stringify(
+ *       useResultTableCellIds('dogColorsAndLegs', 'petQueries'),
+ *     )}
+ *   </span>
+ * );
+ *
+ * const queries = createQueries(
+ *   createStore().setTable('pets', {
+ *     fido: {species: 'dog', color: 'brown'},
+ *     felix: {species: 'cat', color: 'black'},
+ *     cujo: {species: 'dog', color: 'black', legs: 4},
+ *   }),
+ * ).setQueryDefinition('dogColorsAndLegs', 'pets', ({select, where}) => {
+ *   select('color');
+ *   select('legs');
+ *   where('species', 'dog');
+ * });
+ * const app = document.createElement('div');
+ * ReactDOMClient.createRoot(app).render(<App queries={queries} />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>["color","legs"]</span>'
+ * ```
+ * @category Queries hooks
+ * @since v4.1.0
+ */
+export function useResultTableCellIds(
+  queryId: Id,
+  queriesOrQueriesId?: QueriesOrQueriesId,
+): Ids;
+
+/**
+ * The useResultRowIds hook returns the Ids of every Row in the ResultTable of
  * the given query, and registers a listener so that any changes to those Ids
  * will cause a re-render.
  *
@@ -5512,7 +5642,7 @@ export function useResultRowIds(
 
 /**
  * The useResultSortedRowIds hook returns the sorted (and optionally, paginated)
- * Ids of every Row in the result Table of the given query, and registers a
+ * Ids of every Row in the ResultTable 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
@@ -5663,9 +5793,9 @@ export function useResultSortedRowIds(
 ): Ids;
 
 /**
- * The useResultRow hook returns an object containing the data of a
- * single Row in the result Table of the given query, and registers a listener
- * so that any changes to that Row will cause a re-render.
+ * The useResultRow hook returns an object containing the data of a single Row
+ * in the ResultTable of the given query, and registers a listener so that any
+ * changes to that Row 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
@@ -5678,11 +5808,11 @@ export function useResultSortedRowIds(
  * result Row 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 rowId The Id of the Row in the result Table.
+ * @param rowId The Id of the Row in the ResultTable.
  * @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 object containing the entire data of the Row in the result Table
+ * @returns An object containing the entire data of the Row in the ResultTable
  * of the query.
  * @example
  * This example creates a Queries object outside the application, which is used
@@ -5788,7 +5918,7 @@ export function useResultRow(
 
 /**
  * The useResultCellIds hook returns the Ids of every Cell in a given Row in the
- * result Table of the given query, and registers a listener so that any changes
+ * ResultTable 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
@@ -5802,7 +5932,7 @@ export function useResultRow(
  * result Cell 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 rowId The Id of the Row in the result Table.
+ * @param rowId The Id of the Row in the ResultTable.
  * @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.
@@ -5918,7 +6048,7 @@ export function useResultCellIds(
 
 /**
  * The useResultCell hook returns the value of a single Cell in a given Row in
- * the result Table of the given query, and registers a listener so that any
+ * the ResultTable of the given query, and registers a listener so that any
  * changes to that value will cause a re-render.
  *
  * A Provider component is used to wrap part of an application in a context, and
@@ -5932,7 +6062,7 @@ export function useResultCellIds(
  * result Cell 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 rowId The Id of the Row in the result Table.
+ * @param rowId The Id of the Row in the ResultTable.
  * @param cellId The Id of the Cell in the Row.
  * @param queriesOrQueriesId The Queries object to be accessed: omit for the
  * default context Queries object, provide an Id for a named context Queries
@@ -6045,14 +6175,14 @@ export function useResultCell(
 
 /**
  * The useResultTableListener hook registers a listener function with a Queries
- * object that will be called whenever data in a result Table changes.
+ * object that will be called whenever data in a ResultTable 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
  * more easily done with the useResultTable hook).
  *
- * You can either listen to a single result Table (by specifying a query Id as
- * the method's first parameter) or changes to any result Table (by providing a
+ * You can either listen to a single ResultTable (by specifying a query Id as
+ * the method's first parameter) or changes to any ResultTable (by providing a
  * `null` wildcard).
  *
  * Unlike the addResultTableListener method, which returns a listener Id and
@@ -6062,7 +6192,7 @@ export function useResultCell(
  * Queries object will be deleted.
  * @param queryId The Id of the query to listen to, or `null` as a wildcard.
  * @param listener The function that will be called whenever data in the
- * matching result Table changes.
+ * matching ResultTable changes.
  * @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.
@@ -6120,16 +6250,97 @@ export function useResultTableListener(
   queriesOrQueriesId?: QueriesOrQueriesId,
 ): void;
 
+/**
+ * The useResultTableCellIdsListener hook registers a listener function with a
+ * Queries object that will be called whenever the Cell Ids that appear anywhere
+ * in a ResultTable 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 useResultTableCellIds hook).
+ *
+ * You can either listen to a single ResultTable (by specifying a query Id as
+ * the method's first parameter) or changes to any ResultTable (by providing a
+ * `null` wildcard).
+ *
+ * Unlike the addResultTableCellIdsListener method, which returns a listener Id
+ * and requires you to remove it manually, the useResultTableCellIdsListener
+ * 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, or `null` as a wildcard.
+ * @param listener The function that will be called whenever the Cell Ids that
+ * appear anywhere in the ResultTable 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 useResultTableCellIdsListener 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 = () => {
+ *   useResultTableCellIdsListener('petColorsAndLegs', () =>
+ *     console.log('Result Cell 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(
+ *   'petColorsAndLegs',
+ *   'pets',
+ *   ({select}) => {
+ *     select('color');
+ *     select('legs');
+ *   },
+ * );
+ * const app = document.createElement('div');
+ * const root = ReactDOMClient.createRoot(app);
+ * root.render(<App queries={queries} />); // !act
+ * console.log(queries.getListenerStats().tableCellIds);
+ * // -> 1
+ *
+ * store.setCell('pets', 'cujo', 'legs', 4); // !act
+ * // -> 'Result Cell Ids changed'
+ *
+ * root.unmount(); // !act
+ * console.log(queries.getListenerStats().tableCellIds);
+ * // -> 0
+ * ```
+ * @category Queries hooks
+ * @since v4.1.0
+ */
+export function useResultTableCellIdsListener(
+  queryId: IdOrNull,
+  listener: ResultTableCellIdsListener,
+  listenerDeps?: React.DependencyList,
+  queriesOrQueriesId?: QueriesOrQueriesId,
+): void;
+
 /**
  * The useResultRowIdsListener hook registers a listener function with a Queries
- * object that will be called whenever the Row Ids in a result Table change.
+ * object that will be called whenever the Row Ids in a ResultTable 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 useResultRowIds hook).
  *
- * You can either listen to a single result Table (by specifying a query Id as
- * the method's first parameter) or changes to any result Table (by providing a
+ * You can either listen to a single ResultTable (by specifying a query Id as
+ * the method's first parameter) or changes to any ResultTable (by providing a
  * `null` wildcard).
  *
  * Unlike the addResultRowIdsListener method, which returns a listener Id and
@@ -6139,7 +6350,7 @@ export function useResultTableListener(
  * Queries object will be deleted.
  * @param queryId The Id of the query to listen to, or `null` as a wildcard.
  * @param listener The function that will be called whenever the Row Ids in the
- * matching result Table change.
+ * matching ResultTable 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.
@@ -6200,7 +6411,7 @@ export function useResultRowIdsListener(
 /**
  * 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.
+ * paginated) Row Ids in a ResultTable 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
@@ -6218,7 +6429,7 @@ export function useResultRowIdsListener(
  * @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.
+ * matching ResultTable 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.
@@ -6391,7 +6602,7 @@ export function useResultRowListener(
  * @param queryId The Id of the query to listen to, or `null` as a wildcard.
  * @param rowId The Id of the result Row to listen to, or `null` as a wildcard.
  * @param listener The function that will be called whenever the Row Ids in the
- * matching result Table change.
+ * matching ResultTable 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.
@@ -7593,6 +7804,11 @@ export type TableProps = {
    * on its Id.
    */
   readonly getRowComponentProps?: (rowId: Id) => ExtraProps;
+  /**
+   * An optional list of Cell Ids to use for rendering a prescribed set of the
+   * Table's Cells in a given order.
+   */
+  readonly customCellIds?: Ids;
   /**
    * A component or string to separate each Row component.
    */
@@ -7647,6 +7863,11 @@ export type SortedTableProps = {
    * on its Id.
    */
   readonly getRowComponentProps?: (rowId: Id) => ExtraProps;
+  /**
+   * An optional list of Cell Ids to use for rendering a prescribed set of the
+   * sorted Table's Cells in a given order.
+   */
+  readonly customCellIds?: Ids;
   /**
    * A component or string to separate each Row component.
    */
@@ -7687,6 +7908,11 @@ export type RowProps = {
    * on its Id.
    */
   readonly getCellComponentProps?: (cellId: Id) => ExtraProps;
+  /**
+   * An optional list of Cell Ids to use for rendering a prescribed set of the
+   * Row's Cells in a given order.
+   */
+  readonly customCellIds?: Ids;
   /**
    * A component or string to separate each Cell component.
    */
@@ -8007,14 +8233,14 @@ export type LinkedRowsProps = {
 
 /**
  * ResultTableProps props are used for components that refer to a single query
- * result Table, such as the ResultTableView component.
+ * ResultTable, such as the ResultTableView component.
  * @category Props
  * @since v2.0.0
  */
 export type ResultTableProps = {
   /**
-   * The Id of the query in the Queries object for which the result Table will
-   * be rendered.
+   * The Id of the query in the Queries object for which the ResultTable will be
+   * rendered.
    */
   readonly queryId: Id;
   /**
@@ -8046,13 +8272,13 @@ export type ResultTableProps = {
 
 /**
  * ResultSortedTableProps props are used for components that refer to a single
- * sorted query result Table, such as the ResultSortedTableView component.
+ * sorted query ResultTable, 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
+   * The Id of the query in the Queries object for which the sorted ResultTable
    * will be rendered.
    */
   readonly queryId: Id;
@@ -8102,18 +8328,18 @@ export type ResultSortedTableProps = {
 
 /**
  * ResultRowProps props are used for components that refer to a single Row in a
- * query result Table, such as the ResultRowView component.
+ * query ResultTable, such as the ResultRowView component.
  * @category Props
  * @since v2.0.0
  */
 export type ResultRowProps = {
   /**
-   * The Id of the query in the Queries object for which the result Table will
-   * be rendered.
+   * The Id of the query in the Queries object for which the ResultTable will be
+   * rendered.
    */
   readonly queryId: Id;
   /**
-   * The Id of the Row in the result Table to be rendered.
+   * The Id of the Row in the ResultTable to be rendered.
    */
   readonly rowId: Id;
   /**
@@ -8145,14 +8371,14 @@ export type ResultRowProps = {
 
 /**
  * ResultRowProps props are used for components that refer to a single Cell in a
- * Row of a result Table, such as the ResultCellView component.
+ * Row of a ResultTable, such as the ResultCellView component.
  * @category Props
  * @since v2.0.0
  */
 export type ResultCellProps = {
   /**
-   * The Id of the query in the Queries object for which the result Table will
-   * be rendered.
+   * The Id of the query in the Queries object for which the ResultTable will be
+   * rendered.
    */
   readonly queryId: Id;
   /**
@@ -8582,8 +8808,10 @@ export function CellView(props: CellProps): ComponentReturnType;
  * You can create your own RowView-like component to customize the way that a
  * Row is rendered: see the TableView component for more details.
  *
- * This component uses the useCellIds hook under the covers, which means that
- * any changes to the structure of the Row will cause a re-render.
+ * Since v4.1.0, you can use the `customCellIds` prop if you want to render a
+ * prescribed set of the Row's Cells in a given order. Otherwise, this component
+ * uses the useCellIds hook under the covers, which means that any changes to
+ * the structure of the Row will cause a re-render.
  * @param props The props for this component.
  * @returns A rendering of the Row, or nothing, if not present.
  * @example
@@ -8610,8 +8838,8 @@ export function CellView(props: CellProps): ComponentReturnType;
  * ```
  * @example
  * This example creates a Provider context into which a default Store is
- * provided. The RowView component within it then renders the Row (with Ids for
- * readability).
+ * provided. The RowView component within it then renders the Row for a custom
+ * set of Cell Ids (and rendered with Ids for readability).
  *
  * ```jsx
  * const App = ({store}) => (
@@ -8619,20 +8847,27 @@ export function CellView(props: CellProps): ComponentReturnType;
  *     <Pane />
  *   </Provider>
  * );
+ * const customCellIds = ['color', 'species'];
  * const Pane = () => (
  *   <div>
- *     <RowView tableId="pets" rowId="fido" debugIds={true} />
+ *     <RowView
+ *       tableId="pets"
+ *       rowId="fido"
+ *       customCellIds={customCellIds}
+ *       debugIds={true}
+ *     />
  *   </div>
  * );
  *
  * const store = createStore().setRow('pets', 'fido', {
  *   species: 'dog',
  *   color: 'walnut',
+ *   legs: 4,
  * });
  * const app = document.createElement('div');
  * ReactDOMClient.createRoot(app).render(<App store={store} />); // !act
  * console.log(app.innerHTML);
- * // -> '<div>fido:{species:{dog}color:{walnut}}</div>'
+ * // -> '<div>fido:{color:{walnut}species:{dog}}</div>'
  * ```
  * @example
  * This example creates a Provider context into which a default Store is
@@ -8698,6 +8933,9 @@ export function RowView(props: RowProps): ComponentReturnType;
  * 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.
+ *
+ * Since v4.1.0, you can use the `customCellIds` prop if you want to render a
+ * prescribed set of the Table's Cells in a given order for each Row.
  * @param props The props for this component.
  * @returns A rendering of the Table, or nothing, if not present.
  * @example
@@ -8734,8 +8972,8 @@ export function RowView(props: RowProps): ComponentReturnType;
  * ```
  * @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).
+ * provided. The SortedTableView component within it then renders the Table for
+ * a custom set of Cell Ids (and rendered with Ids for readability).
  *
  * ```jsx
  * const App = ({store}) => (
@@ -8743,16 +8981,22 @@ export function RowView(props: RowProps): ComponentReturnType;
  *     <Pane />
  *   </Provider>
  * );
+ * const customCellIds = ['species'];
  * const Pane = () => (
  *   <div>
- *     <SortedTableView tableId="pets" cellId="species" debugIds={true} />
+ *     <SortedTableView
+ *       tableId="pets"
+ *       cellId="species"
+ *       customCellIds={customCellIds}
+ *       debugIds={true}
+ *     />
  *   </div>
  * );
  *
  * const store = createStore().setTables({
  *   pets: {
- *     fido: {species: 'dog'},
- *     felix: {species: 'cat'},
+ *     fido: {color: 'black', species: 'dog'},
+ *     felix: {color: 'brown', species: 'cat'},
  *   },
  * });
  * const app = document.createElement('div');
@@ -8825,6 +9069,9 @@ export function SortedTableView(props: SortedTableProps): ComponentReturnType;
  *
  * This component uses the useRowIds hook under the covers, which means that any
  * changes to the structure of the Table will cause a re-render.
+ *
+ * Since v4.1.0, you can use the `customCellIds` prop if you want to render a
+ * prescribed set of the Table's Cells in a given order for each Row.
  * @param props The props for this component.
  * @returns A rendering of the Table, or nothing, if not present.
  * @example
@@ -8851,8 +9098,8 @@ export function SortedTableView(props: SortedTableProps): ComponentReturnType;
  * ```
  * @example
  * This example creates a Provider context into which a default Store is
- * provided. The TableView component within it then renders the Table (with Ids
- * for readability).
+ * provided. The TableView component within it then renders the Table for a
+ * custom set of Cell Ids (and rendered with Ids for readability).
  *
  * ```jsx
  * const App = ({store}) => (
@@ -8860,15 +9107,20 @@ export function SortedTableView(props: SortedTableProps): ComponentReturnType;
  *     <Pane />
  *   </Provider>
  * );
+ * const customCellIds = ['species'];
  * const Pane = () => (
  *   <div>
- *     <TableView tableId="pets" debugIds={true} />
+ *     <TableView
+ *       tableId="pets"
+ *       customCellIds={customCellIds}
+ *       debugIds={true}
+ *     />
  *   </div>
  * );
  *
  * const store = createStore().setTable('pets', {
- *   fido: {species: 'dog'},
- *   felix: {species: 'cat'},
+ *   fido: {color: 'black', species: 'dog'},
+ *   felix: {color: 'brown', species: 'cat'},
  * });
  * const app = document.createElement('div');
  * ReactDOMClient.createRoot(app).render(<App store={store} />); // !act
@@ -9128,8 +9380,8 @@ export function ValueView(props: ValueProps): ComponentReturnType;
  * also pass additional props to your custom component with the
  * `getValueComponentProps` callback prop.
  *
- * This component uses the useTableIds hook under the covers, which means that
- * any changes to the structure of the Store will cause a re-render.
+ * This component uses the useValueIds hook under the covers, which means that
+ * any changes to the Values in the Store will cause a re-render.
  *
  * This component uses the useValueIds hook under the covers, which means that
  * any changes to the Store's Values will cause a re-render.
@@ -9975,7 +10227,7 @@ export function LinkedRowsView(props: LinkedRowsProps): ComponentReturnType;
 
 /**
  * The ResultCellView component renders the value of a single Cell in a given
- * Row, in a given query's result Table, and registers a listener so that any
+ * Row, in a given query's ResultTable, and registers a listener so that any
  * changes to that result will cause a re-render.
  *
  * The component's props identify which Cell to render based on query Id, Row
@@ -10097,7 +10349,7 @@ export function ResultCellView(props: ResultCellProps): ComponentReturnType;
 
 /**
  * The ResultRowView component renders the contents of a single Row in a given
- * query's result Table, and registers a listener so that any changes to that
+ * query's ResultTable, and registers a listener so that any changes to that
  * result will cause a re-render.
  *
  * The component's props identify which Row to render based on query Id, Row Id,
@@ -10243,18 +10495,18 @@ 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
+ * sorted ResultTable 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.
+ * The component's props identify which ResultTable 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
+ * This component renders a ResultTable 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
@@ -10262,10 +10514,10 @@ export function ResultRowView(props: ResultRowProps): ComponentReturnType;
  * 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
+ * means that any changes to the structure or sorting of the ResultTable will
  * cause a re-render.
  * @param props The props for this component.
- * @returns A rendering of the result Table, or nothing, if not present.
+ * @returns A rendering of the ResultTable, 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
@@ -10381,15 +10633,15 @@ export function ResultSortedTableView(
 ): 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
- * that result will cause a re-render.
+ * The ResultTableView component renders the contents of a single query's
+ * ResultTable 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).
+ * The component's props identify which ResultTable 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).
  *
- * This component renders a result Table by iterating over its Row objects. By
+ * This component renders a ResultTable by iterating over its Row objects. 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
@@ -10397,9 +10649,9 @@ export function ResultSortedTableView(
  * `getResultRowComponentProps` callback prop.
  *
  * This component uses the useResultRowIds hook under the covers, which means
- * that any changes to the structure of the result Table will cause a re-render.
+ * that any changes to the structure of the ResultTable will cause a re-render.
  * @param props The props for this component.
- * @returns A rendering of the result Table, or nothing, if not present.
+ * @returns A rendering of the ResultTable, or nothing, if not present.
  * @example
  * This example creates a Queries object outside the application, which is used
  * in the ResultTableView component by reference. A change to the data in the