tinybase 8.4.2 → 8.5.0-beta.1

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

@@ -692,7 +692,7 @@ export type SortedTablePaginatorProps = {
  *
  * See the <TableInHtmlTable /> (React) demo for this component in action:
  *
- * ![TableInHtmlTable example](https://tinybase.org/shots/tableinhtmltable-react-demo.png
+ * ![TableInHtmlTable example](https://beta.tinybase.org/shots/tableinhtmltable-react-demo.png
  * "TableInHtmlTable example")
  *
  * The component's props identify which Table to render based on Table Id, and
@@ -838,7 +838,7 @@ export function TableInHtmlTable(
  * See the <SortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![SortedTableInHtmlTable example](https://tinybase.org/shots/sortedtableinhtmltable-react-demo.png
+ * ![SortedTableInHtmlTable example](https://beta.tinybase.org/shots/sortedtableinhtmltable-react-demo.png
  * "SortedTableInHtmlTable example")
  *
  * The component's props identify which Table to render based on Table Id, and
@@ -1011,7 +1011,7 @@ export function SortedTableInHtmlTable(
  *
  * See the <ValuesInHtmlTable /> (React) demo for this component in action:
  *
- * ![ValuesInHtmlTable example](https://tinybase.org/shots/valuesinhtmltable-react-demo.png
+ * ![ValuesInHtmlTable example](https://beta.tinybase.org/shots/valuesinhtmltable-react-demo.png
  * "ValuesInHtmlTable example")
  *
  * The component's props identify which Row to render based on Table Id, Row Id,
@@ -1142,7 +1142,7 @@ export function ValuesInHtmlTable(
  *
  * See the <SliceInHtmlTable /> (React) demo for this component in action:
  *
- * ![SliceInHtmlTable example](https://tinybase.org/shots/sliceinhtmltable-react-demo.png
+ * ![SliceInHtmlTable example](https://beta.tinybase.org/shots/sliceinhtmltable-react-demo.png
  * "SliceInHtmlTable example")
  *
  * The component's props identify which Slice to render based on Index Id, Slice
@@ -1300,7 +1300,7 @@ export function SliceInHtmlTable(
  * See the <RelationshipInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![RelationshipInHtmlTable example](https://tinybase.org/shots/relationshipinhtmltable-react-demo.png
+ * ![RelationshipInHtmlTable example](https://beta.tinybase.org/shots/relationshipinhtmltable-react-demo.png
  * "RelationshipInHtmlTable example")
  *
  * The component's props identify which Relationship to render based on
@@ -1478,7 +1478,7 @@ export function RelationshipInHtmlTable(
  * See the <ResultTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![ResultTableInHtmlTable example](https://tinybase.org/shots/resulttableinhtmltable-react-demo.png
+ * ![ResultTableInHtmlTable example](https://beta.tinybase.org/shots/resulttableinhtmltable-react-demo.png
  * "ResultTableInHtmlTable example")
  *
  * The component's props identify which ResultTable to render based on query Id,
@@ -1631,7 +1631,7 @@ export function ResultTableInHtmlTable(
  * See the <ResultSortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![ResultSortedTableInHtmlTable example](https://tinybase.org/shots/resultsortedtableinhtmltable-react-demo.png
+ * ![ResultSortedTableInHtmlTable example](https://beta.tinybase.org/shots/resultsortedtableinhtmltable-react-demo.png
  * "ResultSortedTableInHtmlTable example")
  *
  * The component's props identify which ResultTable to render based on query Id,
@@ -1805,7 +1805,7 @@ export function ResultSortedTableInHtmlTable(
  *
  * See the <EditableCellView /> (React) demo for this component in action:
  *
- * ![EditableCellView example](https://tinybase.org/shots/editablecellview-react-demo.png
+ * ![EditableCellView example](https://beta.tinybase.org/shots/editablecellview-react-demo.png
  * "EditableCellView example")
  *
  * The component's props identify which Cell to render based on Table Id, Row
@@ -1876,7 +1876,7 @@ export function EditableCellView(
  *
  * See the <EditableValueView /> (React) demo for this component in action:
  *
- * ![EditableValueView example](https://tinybase.org/shots/editablevalueview-react-demo.png
+ * ![EditableValueView example](https://beta.tinybase.org/shots/editablevalueview-react-demo.png
  * "EditableValueView example")
  *
  * The component's props identify which Value to render based on Table Id, Row
@@ -1947,7 +1947,7 @@ export function EditableValueView(
  * See the <SortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![SortedTablePaginator example](https://tinybase.org/shots/sortedtablepaginator-react-demo.png
+ * ![SortedTablePaginator example](https://beta.tinybase.org/shots/sortedtablepaginator-react-demo.png
  * "SortedTablePaginator example")
  *
  * The component displays 'previous' and 'next' buttons for paging through the

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

@@ -674,7 +674,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * See the <TableInHtmlTable /> (React) demo for this component in action:
  *
- * ![TableInHtmlTable example](https://tinybase.org/shots/tableinhtmltable-react-demo.png
+ * ![TableInHtmlTable example](https://beta.tinybase.org/shots/tableinhtmltable-react-demo.png
  * "TableInHtmlTable example")
  *
  * The component's props identify which Table to render based on Table Id, and
@@ -828,7 +828,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * See the <SortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![SortedTableInHtmlTable example](https://tinybase.org/shots/sortedtableinhtmltable-react-demo.png
+ * ![SortedTableInHtmlTable example](https://beta.tinybase.org/shots/sortedtableinhtmltable-react-demo.png
  * "SortedTableInHtmlTable example")
  *
  * The component's props identify which Table to render based on Table Id, and
@@ -1009,7 +1009,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * See the <ValuesInHtmlTable /> (React) demo for this component in action:
  *
- * ![ValuesInHtmlTable example](https://tinybase.org/shots/valuesinhtmltable-react-demo.png
+ * ![ValuesInHtmlTable example](https://beta.tinybase.org/shots/valuesinhtmltable-react-demo.png
  * "ValuesInHtmlTable example")
  *
  * The component's props identify which Row to render based on Table Id, Row Id,
@@ -1148,7 +1148,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * See the <SliceInHtmlTable /> (React) demo for this component in action:
  *
- * ![SliceInHtmlTable example](https://tinybase.org/shots/sliceinhtmltable-react-demo.png
+ * ![SliceInHtmlTable example](https://beta.tinybase.org/shots/sliceinhtmltable-react-demo.png
  * "SliceInHtmlTable example")
  *
  * The component's props identify which Slice to render based on Index Id, Slice
@@ -1314,7 +1314,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * See the <RelationshipInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![RelationshipInHtmlTable example](https://tinybase.org/shots/relationshipinhtmltable-react-demo.png
+ * ![RelationshipInHtmlTable example](https://beta.tinybase.org/shots/relationshipinhtmltable-react-demo.png
  * "RelationshipInHtmlTable example")
  *
  * The component's props identify which Relationship to render based on
@@ -1500,7 +1500,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * See the <ResultTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![ResultTableInHtmlTable example](https://tinybase.org/shots/resulttableinhtmltable-react-demo.png
+ * ![ResultTableInHtmlTable example](https://beta.tinybase.org/shots/resulttableinhtmltable-react-demo.png
  * "ResultTableInHtmlTable example")
  *
  * The component's props identify which ResultTable to render based on query Id,
@@ -1661,7 +1661,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * See the <ResultSortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![ResultSortedTableInHtmlTable example](https://tinybase.org/shots/resultsortedtableinhtmltable-react-demo.png
+ * ![ResultSortedTableInHtmlTable example](https://beta.tinybase.org/shots/resultsortedtableinhtmltable-react-demo.png
  * "ResultSortedTableInHtmlTable example")
  *
  * The component's props identify which ResultTable to render based on query Id,
@@ -1843,7 +1843,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * See the <EditableCellView /> (React) demo for this component in action:
  *
- * ![EditableCellView example](https://tinybase.org/shots/editablecellview-react-demo.png
+ * ![EditableCellView example](https://beta.tinybase.org/shots/editablecellview-react-demo.png
  * "EditableCellView example")
  *
  * The component's props identify which Cell to render based on Table Id, Row
@@ -1928,7 +1928,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  *
  * See the <EditableValueView /> (React) demo for this component in action:
  *
- * ![EditableValueView example](https://tinybase.org/shots/editablevalueview-react-demo.png
+ * ![EditableValueView example](https://beta.tinybase.org/shots/editablevalueview-react-demo.png
  * "EditableValueView example")
  *
  * The component's props identify which Value to render based on Table Id, Row
@@ -1999,7 +1999,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * See the <SortedTableInHtmlTable /> (React) demo for this component in
  * action:
  *
- * ![SortedTablePaginator example](https://tinybase.org/shots/sortedtablepaginator-react-demo.png
+ * ![SortedTablePaginator example](https://beta.tinybase.org/shots/sortedtablepaginator-react-demo.png
  * "SortedTablePaginator example")
  *
  * The component displays 'previous' and 'next' buttons for paging through the

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

@@ -0,0 +1,242 @@
+/**
+ * The ui-react-dom-charts module of the TinyBase project provides components
+ * to make it easy to create web-based reactive charts with Store and Queries
+ * objects.
+ *
+ * The components in this module use the react-dom module and so are not
+ * appropriate for environments like React Native (although those in the
+ * lower-level ui-react module are).
+ *
+ * For a full list of SVG class names that can be styled with CSS, see the
+ * Using Charts guide.
+ * @packageDocumentation
+ * @module ui-react-dom-charts
+ * @since v8.5.0
+ */
+import type {Id} from '../common/index.d.ts';
+import type {
+  ComponentReturnType,
+  QueriesOrQueriesId,
+  StoreOrStoreId,
+} from '../ui-react/index.d.ts';
+
+/**
+ * The ChartProps type describes the props that are used to configure the
+ * chart element that renders a chart.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartProps = {
+  /**
+   * An optional string that will be used as the class attribute of the chart's
+   * SVG element. This can be used as the root selector for styling chart
+   * internals, as shown in the Using Charts guide.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly className?: string;
+};
+
+/**
+ * The ChartTableSourceProps type describes the props that bind a chart to a
+ * Table in a Store.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartTableSourceProps = {
+  /**
+   * The Id of the Table in the Store to chart.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly tableId: Id;
+  /**
+   * The Store to chart, or the Id of a Store that is registered with the
+   * Provider component.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly store?: StoreOrStoreId;
+  /**
+   * This prop is not used when binding a chart to a Table.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly queryId?: never;
+  /**
+   * This prop is not used when binding a chart to a Table.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly queries?: never;
+};
+
+/**
+ * The ChartQuerySourceProps type describes the props that bind a chart to a
+ * Query in a Queries object.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartQuerySourceProps = {
+  /**
+   * The Id of the query in the Queries object to chart.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly queryId: Id;
+  /**
+   * The Queries object to chart, or the Id of a Queries object that is
+   * registered with the Provider component.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly queries?: QueriesOrQueriesId;
+  /**
+   * This prop is not used when binding a chart to a Query.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly tableId?: never;
+  /**
+   * This prop is not used when binding a chart to a Query.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly store?: never;
+};
+
+/**
+ * The ChartBindingProps type describes the props that bind a chart to Cell
+ * values in TinyBase data.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type ChartBindingProps = {
+  /**
+   * The Id of the Cell that provides each data point's x value.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly xCellId: Id;
+  /**
+   * The Id of the Cell that provides each data point's y value.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly yCellId: Id;
+  /**
+   * The Id of the Cell used to sort the charted rows.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly sortCellId?: Id;
+  /**
+   * Whether the charted rows should be sorted in descending order.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly descending?: boolean;
+  /**
+   * The number of sorted rows to skip before charting.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly offset?: number;
+  /**
+   * The maximum number of sorted rows to chart.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly limit?: number;
+};
+
+/**
+ * The LineChart component renders a line chart from TinyBase data.
+ * @category Store components
+ * @since v8.5.0
+ * @example
+ * This example creates a Provider context into which a default Store is
+ * provided. The LineChart component then renders an SVG chart from Cells in the
+ * `pets` Table.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import {Provider} from 'tinybase/ui-react';
+ * import {LineChart} from 'tinybase/ui-react-dom-charts';
+ *
+ * const App = ({store}) => (
+ *   <Provider store={store}>
+ *     <LineChart
+ *       tableId="pets"
+ *       xCellId="order"
+ *       yCellId="sold"
+ *       className="sales"
+ *     />
+ *   </Provider>
+ * );
+ *
+ * const store = createStore().setTable('pets', {
+ *   hamsters: {order: 1, sold: 12},
+ *   rabbits: {order: 2, sold: 9},
+ * });
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App store={store} />); // !act
+ * console.log(app.firstChild?.nodeName.toLowerCase());
+ * // -> 'svg'
+ * console.log(app.firstChild?.getAttribute('class'));
+ * // -> 'sales'
+ * ```
+ */
+export function LineChart(
+  props: (ChartTableSourceProps | ChartQuerySourceProps) &
+    ChartBindingProps &
+    ChartProps,
+): ComponentReturnType;
+
+/**
+ * The BarChart component renders a bar chart from TinyBase data.
+ * @category Store components
+ * @since v8.5.0
+ * @example
+ * This example creates a Queries object and provides it through Provider
+ * context. The BarChart component then renders an SVG chart from Cells in the
+ * `bySpecies` query.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {Provider} from 'tinybase/ui-react';
+ * import {BarChart} from 'tinybase/ui-react-dom-charts';
+ *
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <BarChart queryId="bySpecies" xCellId="species" yCellId="sold" />
+ *   </Provider>
+ * );
+ *
+ * const store = createStore().setTable('pets', {
+ *   hamsters: {species: 'hamster', sold: 12},
+ *   rabbits: {species: 'rabbit', sold: 9},
+ * });
+ * const queries = createQueries(store).setQueryDefinition(
+ *   'bySpecies',
+ *   'pets',
+ *   ({select}) => {
+ *     select('species');
+ *     select('sold');
+ *   },
+ * );
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App queries={queries} />); // !act
+ * console.log(app.firstChild?.nodeName.toLowerCase());
+ * // -> 'svg'
+ * ```
+ */
+export function BarChart(
+  props: (ChartTableSourceProps | ChartQuerySourceProps) &
+    ChartBindingProps &
+    ChartProps,
+): ComponentReturnType;