tinybase 8.5.0-beta.1 → 8.5.0-beta.3

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

@@ -1,18 +1,19 @@
 /**
- * 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
+ * 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.
+ * 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 {ReactNode} from 'react';
 import type {Id} from '../common/index.d.ts';
 import type {
   ComponentReturnType,
@@ -21,8 +22,8 @@ import type {
 } from '../ui-react/index.d.ts';
 
 /**
- * The ChartProps type describes the props that are used to configure the
- * chart element that renders a chart.
+ * The ChartProps type describes the props that are used to configure the chart
+ * element that renders a chart.
  * @category Configuration
  * @since v8.5.0
  */
@@ -38,12 +39,12 @@ export type ChartProps = {
 };
 
 /**
- * The ChartTableSourceProps type describes the props that bind a chart to a
+ * The TableSourceProps type describes the props that bind a chart to a
  * Table in a Store.
  * @category Configuration
  * @since v8.5.0
  */
-export type ChartTableSourceProps = {
+export type TableSourceProps = {
   /**
    * The Id of the Table in the Store to chart.
    * @category Prop
@@ -72,12 +73,12 @@ export type ChartTableSourceProps = {
 };
 
 /**
- * The ChartQuerySourceProps type describes the props that bind a chart to a
+ * The QuerySourceProps type describes the props that bind a chart to a
  * Query in a Queries object.
  * @category Configuration
  * @since v8.5.0
  */
-export type ChartQuerySourceProps = {
+export type QuerySourceProps = {
   /**
    * The Id of the query in the Queries object to chart.
    * @category Prop
@@ -106,20 +107,27 @@ export type ChartQuerySourceProps = {
 };
 
 /**
- * The ChartBindingProps type describes the props that bind a chart to Cell
- * values in TinyBase data.
+ * The BindingProps type describes the props that bind a LineChart
+ * component or BarChart component to Cell values in TinyBase data. An x Cell
+ * value can be a finite number, string, or boolean. A y Cell value must be a
+ * finite number.
  * @category Configuration
  * @since v8.5.0
  */
-export type ChartBindingProps = {
+export type BindingProps = {
   /**
-   * The Id of the Cell that provides each data point's x value.
+   * The Id of the Cell that provides each data point's x value. Finite numbers
+   * can be used as continuous x values in line charts, while strings and
+   * booleans are used as category values. Boolean category labels are rendered
+   * as `true` and `false`.
    * @category Prop
    * @since v8.5.0
    */
   readonly xCellId: Id;
   /**
-   * The Id of the Cell that provides each data point's y value.
+   * The Id of the Cell that provides each data point's y value. Only finite
+   * numbers are charted; rows with missing, non-numeric, or non-finite y values
+   * are ignored.
    * @category Prop
    * @since v8.5.0
    */
@@ -151,7 +159,328 @@ export type ChartBindingProps = {
 };
 
 /**
- * The LineChart component renders a line chart from TinyBase data.
+ * The SeriesProps type describes the props that bind a chart series to Cell
+ * values in TinyBase data. An x Cell value can be a finite number, string, or
+ * boolean. A y Cell value must be a finite number.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type SeriesProps = {
+  /**
+   * An optional string that will be added to the class attribute of the series'
+   * SVG group element.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly className?: string;
+  /**
+   * The Id of the Cell that provides each data point's x value. Finite numbers
+   * can be used as continuous x values in line series, while strings and
+   * booleans are used as category values. Boolean category labels are rendered
+   * as `true` and `false`.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly xCellId: Id;
+  /**
+   * The Id of the Cell that provides each data point's y value. Only finite
+   * numbers are charted; rows with missing, non-numeric, or non-finite y values
+   * are ignored.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly yCellId: Id;
+  /**
+   * An optional label to use for the series in axis titles and tooltips,
+   * defaulting to the y Cell Id.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly label?: string;
+  /**
+   * 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 XAxisProps type describes the props that configure the x axis of a
+ * CartesianChart component.
+ *
+ * The x axis is inferred by default. Use an XAxis component child when you want
+ * to override its title, numeric bounds, tick values, tick count, tick labels,
+ * or SVG class name.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type XAxisProps = {
+  /**
+   * An optional string that will be added to the class attribute of the x-axis
+   * SVG group element.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly className?: string;
+  /**
+   * An optional title to use for the x axis, defaulting to the x Cell Id, or to
+   * a combined title when multiple series use different x Cell Ids.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly title?: string;
+  /**
+   * An optional minimum x-axis bound for continuous numeric x values.
+   *
+   * This prop is ignored when the x axis is categorical.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly min?: number;
+  /**
+   * An optional maximum x-axis bound for continuous numeric x values.
+   *
+   * This prop is ignored when the x axis is categorical.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly max?: number;
+  /**
+   * Optional numeric tick values to use for a continuous x axis.
+   *
+   * This prop is ignored when the x axis is categorical.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly ticks?: readonly number[];
+  /**
+   * An optional preferred number of ticks to render on a continuous x axis.
+   *
+   * The actual number of ticks may vary so that labels remain readable.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly tickCount?: number;
+  /**
+   * An optional function for formatting x-axis tick labels.
+   *
+   * It receives the original tick value, which can be a finite number, string,
+   * or boolean.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly tickFormatter?: (tick: boolean | number | string) => string;
+};
+
+/**
+ * The YAxisProps type describes the props that configure the y axis of a
+ * CartesianChart component.
+ *
+ * The y axis is inferred by default. Use a YAxis component child when you want
+ * to override its title, numeric bounds, tick values, tick count, tick labels,
+ * or SVG class name.
+ * @category Configuration
+ * @since v8.5.0
+ */
+export type YAxisProps = {
+  /**
+   * An optional string that will be added to the class attribute of the y-axis
+   * SVG group element.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly className?: string;
+  /**
+   * An optional title to use for the y axis, defaulting to the y Cell Id, y
+   * series label, or a combined title when multiple series use different y Cell
+   * Ids or labels.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly title?: string;
+  /**
+   * An optional minimum y-axis bound.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly min?: number;
+  /**
+   * An optional maximum y-axis bound.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly max?: number;
+  /**
+   * Optional numeric tick values to use for the y axis.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly ticks?: readonly number[];
+  /**
+   * An optional preferred number of ticks to render on the y axis.
+   *
+   * The actual number of ticks may vary so that labels remain readable.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly tickCount?: number;
+  /**
+   * An optional function for formatting y-axis tick labels.
+   *
+   * It receives the numeric tick value.
+   * @category Prop
+   * @since v8.5.0
+   */
+  readonly tickFormatter?: (tick: number) => string;
+};
+
+/**
+ * The CartesianChart component renders a chart frame and provides TinyBase
+ * source and layout context to LineSeries component and BarSeries component
+ * children.
+ *
+ * See the Composing Charts (React) demo for this component in action:
+ *
+ * ![CartesianChart component example](https://beta.tinybase.org/shots/composing-charts-react-demo.png
+ * "CartesianChart component example")
+ *
+ * The series children declare their own xCellId and yCellId bindings. The
+ * optional XAxis component and YAxis component children can be used to
+ * configure axis titles, bounds, ticks, and tick formatting.
+ * @category Store components
+ * @since v8.5.0
+ * @example
+ * This example creates a Store and renders two LineSeries component children
+ * in a CartesianChart component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createStore} from 'tinybase';
+ * import {CartesianChart, LineSeries} from 'tinybase/ui-react-dom-charts';
+ *
+ * const store = createStore().setTable('pets', {
+ *   hamsters: {order: 1, sold: 12, returned: 1},
+ *   rabbits: {order: 2, sold: 9, returned: 2},
+ * });
+ * const App = () => (
+ *   <CartesianChart store={store} tableId="pets">
+ *     <LineSeries
+ *       className="sold"
+ *       label="Sold pets"
+ *       xCellId="order"
+ *       yCellId="sold"
+ *     />
+ *     <LineSeries
+ *       className="returned"
+ *       label="Returned pets"
+ *       xCellId="order"
+ *       yCellId="returned"
+ *     />
+ *   </CartesianChart>
+ * );
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App />); // !act
+ * console.log(app.firstChild?.nodeName.toLowerCase());
+ * // -> 'svg'
+ * ```
+ */
+export function CartesianChart(
+  props: (TableSourceProps | QuerySourceProps) &
+    ChartProps & {readonly children?: ReactNode},
+): ComponentReturnType;
+
+/**
+ * The XAxis component configures the x axis of a CartesianChart component.
+ *
+ * It is a configuration child rather than a separately rendered SVG element:
+ * include zero or one XAxis component in a CartesianChart component's children.
+ * If omitted, the x axis is inferred from the chart's series.
+ *
+ * See the Axis Overrides (React) demo for this component in action:
+ *
+ * ![XAxis component example](https://beta.tinybase.org/shots/axis-overrides-react-demo.png
+ * "XAxis component example")
+ * @category Store components
+ * @since v8.5.0
+ */
+export function XAxis(props: XAxisProps): ComponentReturnType;
+
+/**
+ * The YAxis component configures the y axis of a CartesianChart component.
+ *
+ * It is a configuration child rather than a separately rendered SVG element:
+ * include zero or one YAxis component in a CartesianChart component's children.
+ * If omitted, the y axis is inferred from the chart's series.
+ *
+ * See the Axis Overrides (React) demo for this component in action:
+ *
+ * ![YAxis component example](https://beta.tinybase.org/shots/axis-overrides-react-demo.png
+ * "YAxis component example")
+ * @category Store components
+ * @since v8.5.0
+ */
+export function YAxis(props: YAxisProps): ComponentReturnType;
+
+/**
+ * The LineSeries component renders a line series in a CartesianChart component.
+ * If every x value in every series is a finite number, the x axis is rendered
+ * as a continuous numeric scale. If any x value is a string or boolean, the x
+ * axis is rendered categorically. When sortCellId is omitted, rows are sorted
+ * by xCellId.
+ *
+ * See the Composing Charts (React) demo for this component in action:
+ *
+ * ![LineSeries component example](https://beta.tinybase.org/shots/composing-charts-react-demo.png
+ * "LineSeries component example")
+ * @category Store components
+ * @since v8.5.0
+ */
+export function LineSeries(props: SeriesProps): ComponentReturnType;
+
+/**
+ * The BarSeries component renders a bar series in a CartesianChart component.
+ * Its x values are always rendered categorically, even when they are finite
+ * numbers. Boolean category labels are rendered as `true` and `false`.
+ *
+ * See the Composing Charts (React) demo for this component in action:
+ *
+ * ![BarSeries component example](https://beta.tinybase.org/shots/composing-charts-react-demo.png
+ * "BarSeries component example")
+ * @category Store components
+ * @since v8.5.0
+ */
+export function BarSeries(props: SeriesProps): ComponentReturnType;
+
+/**
+ * The LineChart component renders a line chart from TinyBase data. If every x
+ * value is a finite number, the x axis is rendered as a continuous numeric
+ * scale. If any x value is a string or boolean, the x axis is rendered
+ * categorically. When sortCellId is omitted, rows are sorted by xCellId.
+ *
+ * See the <LineChart /> (React) demo for this component in action:
+ *
+ * ![LineChart component example](https://beta.tinybase.org/shots/basic-chart-react-demo.png "LineChart
+ * component example")
  * @category Store components
  * @since v8.5.0
  * @example
@@ -190,13 +519,18 @@ export type ChartBindingProps = {
  * ```
  */
 export function LineChart(
-  props: (ChartTableSourceProps | ChartQuerySourceProps) &
-    ChartBindingProps &
-    ChartProps,
+  props: (TableSourceProps | QuerySourceProps) & BindingProps & ChartProps,
 ): ComponentReturnType;
 
 /**
- * The BarChart component renders a bar chart from TinyBase data.
+ * The BarChart component renders a bar chart from TinyBase data. Its x values
+ * are always rendered categorically, even when they are finite numbers. Boolean
+ * category labels are rendered as `true` and `false`.
+ *
+ * See the Sorting And Types (React) demo for this component in action:
+ *
+ * ![BarChart component example](https://beta.tinybase.org/shots/sorting-and-types-react-demo.png
+ * "BarChart component example")
  * @category Store components
  * @since v8.5.0
  * @example
@@ -236,7 +570,5 @@ export function LineChart(
  * ```
  */
 export function BarChart(
-  props: (ChartTableSourceProps | ChartQuerySourceProps) &
-    ChartBindingProps &
-    ChartProps,
+  props: (TableSourceProps | QuerySourceProps) & BindingProps & ChartProps,
 ): ComponentReturnType;