tinybase 4.1.0-beta.3 → 4.1.0-beta.4

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

@@ -23,7 +23,12 @@ import {
 import {Id, Ids} from './common';
 import {ComponentType} from 'react';
 
-// CustomCell
+/**
+ * The CustomCell object is used to configure custom cell rendering in an HTML
+ * table.
+ * @category Configuration
+ * @since v4.1.0
+ */
 export type CustomCell = {
   /**
    * An optional string that will be used as the label at the top of the table
@@ -42,7 +47,12 @@ export type CustomCell = {
   readonly getComponentProps?: (rowId: Id, cellId: Id) => ExtraProps;
 };
 
-// CustomResultCell
+/**
+ * The CustomResultCell object is used to configure custom cell rendering for
+ * query results in an HTML table.
+ * @category Configuration
+ * @since v4.1.0
+ */
 export type CustomResultCell = {
   /**
    * An optional string that will be used as the label at the top of the table
@@ -61,7 +71,13 @@ export type CustomResultCell = {
   readonly getComponentProps?: (rowId: Id, cellId: Id) => ExtraProps;
 };
 
-// HtmlTableProps
+/**
+ * HtmlTableProps props are used for components that will render in an HTML
+ * table, such as the TableInHtmlTable component or SortedTableInHtmlTable
+ * component.
+ * @category Props
+ * @since v4.1.0
+ */
 export type HtmlTableProps = {
   /**
    * A string className to use on the root of the resulting element.
@@ -79,7 +95,12 @@ export type HtmlTableProps = {
   readonly idColumn?: boolean;
 };
 
-// TableInHtmlTableProps
+/**
+ * TableInHtmlTableProps props are used for components that will render a Table
+ * in an HTML table, such as the TableInHtmlTable component.
+ * @category Props
+ * @since v4.1.0
+ */
 export type TableInHtmlTableProps = {
   /**
    * The Id of the Table in the Store to be rendered.
@@ -106,7 +127,12 @@ export type TableInHtmlTableProps = {
   readonly customCells?: Ids | {[cellId: Id]: string | CustomCell};
 };
 
-// SortedTableInHtmlTableProps
+/**
+ * SortedTableInHtmlTableProps props are used for components that will render a
+ * sorted Table in an HTML table, such as the SortedTableInHtmlTable component.
+ * @category Props
+ * @since v4.1.0
+ */
 export type SortedTableInHtmlTableProps = {
   /**
    * The Id of the Table in the Store to be rendered.
@@ -153,9 +179,31 @@ export type SortedTableInHtmlTableProps = {
    * the sorting and/or direction.
    */
   readonly sortOnClick?: boolean;
+  /**
+   * Either `true` to show the default SortedTablePaginator for the Table, or
+   * provide your own paginator component that takes SortedTablePaginatorProps.
+   */
+  readonly paginator?: boolean | ComponentType<SortedTablePaginatorProps>;
+  /**
+   * A function that is called whenever the sorting or pagination of the Table
+   * is changed by the user, invoked with the sorted Cell Id, whether descending
+   * or not, and the offset of the pagination.
+   */
+  readonly onChange?: (
+    sortAndOffset: [
+      cellId: Id | undefined,
+      descending: boolean,
+      offset: number,
+    ],
+  ) => void;
 };
 
-// ResultTableInHtmlTableProps
+/**
+ * ResultTableInHtmlTableProps props are used for components that will render a
+ * ResultTable in an HTML table, such as the ResultTableInHtmlTable component.
+ * @category Props
+ * @since v4.1.0
+ */
 export type ResultTableInHtmlTableProps = {
   /**
    * The Id of the query in the Queries object for which the ResultTable will be
@@ -178,7 +226,13 @@ export type ResultTableInHtmlTableProps = {
   readonly customCells?: Ids | {[cellId: Id]: string | CustomResultCell};
 };
 
-// ResultSortedTableInHtmlTableProps
+/**
+ * ResultSortedTableInHtmlTableProps props are used for components that will
+ * render a sorted Table in an HTML table, such as the SortedTableInHtmlTable
+ * component.
+ * @category Props
+ * @since v4.1.0
+ */
 export type ResultSortedTableInHtmlTableProps = {
   /**
    * The Id of the query in the Queries object for which the ResultTable will be
@@ -221,9 +275,32 @@ export type ResultSortedTableInHtmlTableProps = {
    * the sorting and/or direction.
    */
   readonly sortOnClick?: boolean;
+  /**
+   * Either `true` to show the default SortedTablePaginator for the ResultTable,
+   * or provide your own paginator component that takes
+   * SortedTablePaginatorProps.
+   */
+  readonly paginator?: boolean | ComponentType<SortedTablePaginatorProps>;
+  /**
+   * A function that is called whenever the sorting or pagination of the
+   * ResultTable is changed by the user, invoked with the sorted Cell Id,
+   * whether descending or not, and the offset of the pagination.
+   */
+  readonly onChange?: (
+    sortAndOffset: [
+      cellId: Id | undefined,
+      descending: boolean,
+      offset: number,
+    ],
+  ) => void;
 };
 
-// ValuesInHtmlTableProps
+/**
+ * ValuesInHtmlTableProps props are used for components that will render Values
+ * in an HTML table, such as the ValuesInHtmlTable component.
+ * @category Props
+ * @since v4.1.0
+ */
 export type ValuesInHtmlTableProps = {
   /**
    * The Store to be accessed: omit for the default context Store, provide an Id
@@ -248,6 +325,60 @@ export type ValuesInHtmlTableProps = {
   readonly getValueComponentProps?: (valueId: Id) => ExtraProps;
 };
 
+/**
+ * SortedTablePaginatorProps props are used for components that will be used as
+ * a table paginator, such as the SortedTablePaginator component.
+ * @category Props
+ * @since v4.1.0
+ */
+export type SortedTablePaginatorProps = {
+  /**
+   * An event that will fire when the offset is updated, called with the new
+   * offset.
+   */
+  readonly onChange: (offset: number) => void;
+  /**
+   * The number of Row Ids to skip for pagination.
+   */
+  readonly offset?: number;
+  /**
+   * The maximum number of Row Ids being returned.
+   */
+  readonly limit?: number;
+  /**
+   * The total number of Row Ids in the paginated table.
+   */
+  readonly total: number;
+  /**
+   * A noun to use in the pagination label for a single row, defaulting to
+   * 'row'.
+   */
+  readonly singular?: string;
+  /**
+   * A noun to use in the pagination label for multiple rows, defaulting to the
+   * value of the singular noun suffixed with the letter 's'.
+   */
+  readonly plural?: string;
+};
+
+/**
+ * StoreInspectorProps props are used to configure the StoreInspector component.
+ * @category Props
+ * @since v4.1.0
+ */
+export type StoreInspectorProps = {
+  /**
+   * An optional string to indicate where you want the inspector to first
+   * appear.
+   */
+  readonly position?: 'left' | 'top' | 'bottom' | 'right' | 'full';
+  /**
+   * An optional boolean to indicate whether the inspector should start in the
+   * opened state.
+   */
+  readonly open?: boolean;
+};
+
 /**
  * The TableInHtmlTable component renders the contents of a single Table in a
  * Store as an HTML <table> element, and registers a listener so that any
@@ -410,6 +541,13 @@ export function TableInHtmlTable(
  * user can click on a column heading to sort by that column. The style classes
  * `sorted` and `ascending` (or `descending`) are added so that you can provide
  * hints to the user how the sorting is being applied.
+ *
+ * Provide a paginator component for the Table with the `paginator` prop. Set to
+ * `true` to use the default SortedTablePaginator, or provide your own component
+ * that accepts SortedTablePaginatorProps.
+ *
+ * Finally, the `onChange` prop lets you listen to a user's changes to the
+ * Table's sorting or pagination.
  * @param props The props for this component.
  * @returns A rendering of the Table in a <table> element.
  * @example
@@ -446,7 +584,7 @@ export function TableInHtmlTable(
  *   <thead>
  *     <tr>
  *       <th>Id</th>
- *       <th class="sorted ascending">species</th>
+ *       <th class="sorted ascending">↑ species</th>
  *     </tr>
  *   </thead>
  *   <tbody>
@@ -658,9 +796,9 @@ export function ValuesInHtmlTable(
  * This component renders a ResultTable by iterating over its Row objects. By
  * default the Cells are in turn rendered with the CellView component, but you
  * can override this behavior by providing a `component` for each Cell in the
- * `customCells` prop. You can pass additional props to that custom
- * component with the `getComponentProps` callback. See the ResultCustomCell
- * type for more details.
+ * `customCells` prop. You can pass additional props to that custom component
+ * with the `getComponentProps` callback. See the ResultCustomCell type for more
+ * details.
  *
  * 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.
@@ -799,9 +937,9 @@ export function ResultTableInHtmlTable(
  * This component renders a ResultTable by iterating over its Row objects, in
  * the order dictated by the sort parameters. By default the Cells are in turn
  * rendered with the CellView component, but you can override this behavior by
- * providing a `component` for each Cell in the `customCells` prop. You
- * can pass additional props to that custom component with the
- * `getComponentProps` callback. See the ResultCustomCell type for more details.
+ * providing a `component` for each Cell in the `customCells` prop. You can pass
+ * additional props to that custom component with the `getComponentProps`
+ * callback. See the ResultCustomCell type for more details.
  *
  * This component uses the useSortedRowIds hook under the covers, which means
  * that any changes to the structure or sorting of the ResultTable will cause a
@@ -814,6 +952,13 @@ export function ResultTableInHtmlTable(
  * user can click on a column heading to sort by that column. The style classes
  * `sorted` and `ascending` (or `descending`) are added so that you can provide
  * hints to the user how the sorting is being applied.
+ *
+ * Provide a paginator component for the ResultTable with the `paginator` prop.
+ * Set to `true` to use the default SortedTablePaginator, or provide your own
+ * component that accepts SortedTablePaginatorProps.
+ *
+ * Finally, the `onChange` prop lets you listen to a user's changes to the
+ * ResultTable's sorting or pagination.
  * @param props The props for this component.
  * @returns A rendering of the ResultTable in a <table> element.
  * @example
@@ -850,7 +995,7 @@ export function ResultTableInHtmlTable(
  *   <thead>
  *     <tr>
  *       <th>Id</th>
- *       <th class="sorted ascending">color</th>
+ *       <th class="sorted ascending">↑ color</th>
  *     </tr>
  *   </thead>
  *   <tbody>
@@ -976,7 +1121,7 @@ export function ResultSortedTableInHtmlTable(
  * // ->
  * `
  * <div class="editableCell">
- *   <button type="button" class="string">string</button>
+ *   <button class="string">string</button>
  *   <input value="brown">
  * </div>
  * `;
@@ -1029,7 +1174,7 @@ export function EditableCellView(
  * // ->
  * `
  * <div class="editableValue">
- *   <button type="button" class="number">number</button>
+ *   <button class="number">number</button>
  *   <input type="number" value="3">
  * </div>
  * `;
@@ -1040,3 +1185,118 @@ export function EditableCellView(
 export function EditableValueView(
   props: ValueProps & {readonly className?: string},
 ): ComponentReturnType;
+
+/**
+ * The SortedTablePaginator component renders a paginator for a sorted table.
+ *
+ * The component displays 'previous' and 'next' buttons for paging through the
+ * Table if there are more Row Ids than fit in each page. The component will
+ * also display a label that shows which Row Ids are being displayed.
+ *
+ * The component's props identify initial pagination settings, and it will fire
+ * an event when the pagination changes.
+ * @param props The props for this component.
+ * @returns The rendering of a paginator control with a label, and next and
+ * previous buttons, where appropriate.
+ * @example
+ * This example creates a Provider context into which a default Store is
+ * provided. The SortedTableInHtmlTable component within it then renders the
+ * Table in a <table> element with a SortedTablePaginator (the default).
+ *
+ * ```jsx
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <SortedTableInHtmlTable
+ *     tableId="pets"
+ *     cellId="species"
+ *     limit={2}
+ *     paginator={true}
+ *   />
+ * );
+ *
+ * const store = createStore().setTables({
+ *   pets: {
+ *     fido: {species: 'dog'},
+ *     felix: {species: 'cat'},
+ *     cujo: {species: 'wolf'},
+ *     lowly: {species: 'worm'},
+ *     polly: {species: 'parrot'},
+ *   },
+ * });
+ * const app = document.createElement('div');
+ * ReactDOMClient.createRoot(app).render(<App store={store} />); // !act
+ * console.log(app.innerHTML);
+ * // ->
+ * `
+ * <table>
+ *   <caption>
+ *     <button class="previous" disabled="">←</button>
+ *     <button class="next">→</button>
+ *     1 to 2 of 5 rows
+ *   </caption>
+ *   <thead>
+ *     <tr>
+ *       <th>Id</th>
+ *       <th class="sorted ascending">↑ species</th>
+ *     </tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr>
+ *       <th>felix</th>
+ *       <td>cat</td>
+ *     </tr>
+ *     <tr>
+ *       <th>fido</th>
+ *       <td>dog</td>
+ *     </tr>
+ *   </tbody>
+ * </table>
+ * `;
+ * ```
+ * @category Store components
+ * @since v4.1.0
+ */
+export function SortedTablePaginator(
+  props: SortedTablePaginatorProps,
+): ComponentReturnType;
+
+/**
+ * The StoreInspector component renders a tool which allows you to view and edit
+ * the content of a Store in a debug web environment.
+ *
+ * The component displays a nub in the corner of the screen which you may then
+ * click to interact with all the Store objects in the Provider component
+ * context.
+ *
+ * The component's props identify the nub's initial location and panel state,
+ * though subsequent user changes to that will be preserved on each reload.
+ * @param props The props for this component.
+ * @returns The rendering of the inspector tool.
+ * @example
+ * This example creates a Provider context into which a default Store is
+ * provided. The StoreInspector component within it then renders the inspector
+ * tool.
+ *
+ * ```jsx
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => <StoreInspector />;
+ *
+ * const store = createStore().setTables({pets: {fido: {species: 'dog'}}});
+ * const app = document.createElement('div');
+ * ReactDOMClient.createRoot(app).render(<App store={store} />); // !act
+ * // ... // !act
+ * console.log(app.innerHTML.substring(0, 35));
+ * // -> '<aside id="tinybaseStoreInspector">'
+ * ```
+ * @category Development components
+ * @since v4.1.0
+ */
+export function StoreInspector(props: StoreInspectorProps): ComponentReturnType;